sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Calls/ App.ts

import * as calls from "@distilled.cloud/cloudflare/calls";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.Calls.App" as const;
type TypeId = typeof TypeId;

export type AppProps = {
  /**
   * A short description of the app, not shown to end users and not unique.
   * Mutable in place. If omitted, a unique name is generated from the app,
   * stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
};

export type AppAttributes = {
  /**
   * Cloudflare-generated unique identifier for the app. Used in client SDK
   * session URLs (`https://rtc.live.cloudflare.com/v1/apps/{appId}/...`).
   */
  appId: string;
  /**
   * The Cloudflare account the app belongs to.
   */
  accountId: string;
  /**
   * App secret (bearer token) used to authenticate against the Realtime SFU
   * HTTPS API. Returned only at creation time and never re-readable — Alchemy
   * persists it in state and carries it forward across updates.
   */
  secret: Redacted.Redacted<string>;
  /**
   * A short description of the app.
   */
  name: string;
  /**
   * When the app was created.
   */
  created: string;
  /**
   * When the app was last modified.
   */
  modified: string;
};

export type App = Resource<TypeId, AppProps, AppAttributes, never, Providers>;

/**
 * A Cloudflare Realtime (formerly "Calls") SFU application.
 *
 * An app is the unit of isolation for Cloudflare's WebRTC SFU: clients
 * connect to sessions scoped to the app's auto-assigned `appId`, and your
 * backend authenticates management calls with the create-only `secret`
 * (a bearer token). The only configurable property is the human-readable
 * `name`, which is mutable in place.
 * ### Creating an App
 * **Example:** App with a generated name
 * ```typescript
 * const app = yield* Cloudflare.Calls.App("realtime", {});
 * ```
 *
 * **Example:** App with an explicit name
 * ```typescript
 * const app = yield* Cloudflare.Calls.App("realtime", {
 *   name: "my-realtime-app",
 * });
 * ```
 *
 * ### Using the credentials
 * **Example:** Passing the appId and secret to a backend
 * ```typescript
 * // appId is public — it appears in client session URLs:
 * const appId = app.appId;
 *
 * // The secret is redacted — use it server-side as a bearer token
 * // against https://rtc.live.cloudflare.com/v1/apps/{appId}/...
 * const secret = app.secret; // Redacted<string>
 * ```
 *
 * @see https://developers.cloudflare.com/realtime/
 *
 * @resource
 * @product Calls
 * @category Media
 */
export const App = Resource<App>(TypeId);

/**
 * Returns true if the given value is a App resource.
 */
export const isApp = (value: unknown): value is App =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const AppProvider = () =>
  Provider.succeed(App, {
    stables: ["appId", "accountId", "secret", "created"],
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Account-scoped collection: enumerate every Calls app under the
      // account, exhaustively paginating `result`. The create-only secret
      // is never returned by the list endpoint, so — matching `read` for a
      // resource without prior state — hydrate it as an empty Redacted.
      return yield* calls.listSfus.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((app) => toAttributes(app, accountId, Redacted.make(""))),
          ),
        ),
      );
    }),
    diff: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output !== undefined && output.accountId !== accountId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ output }) {
      // The app secret is returned only at creation time, so an app cannot
      // be re-hydrated without prior state — no cold read / adoption path.
      if (!output?.appId) return undefined;
      const observed = yield* getApp(output.accountId, output.appId);
      return observed ? toAttributes(observed, output.accountId, output.secret) : undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createAppName(id, news.name);

      // Observe — the appId cached on `output` is a hint, not a guarantee:
      // a missing app (code 20007) falls through and we recreate.
      const observed = output?.appId
        ? yield* getApp(output.accountId ?? accountId, output.appId)
        : undefined;

      if (!observed || !output) {
        // Ensure — greenfield (or out-of-band delete): create and capture
        // the create-only secret. Names are not unique on Cloudflare's
        // side, so there is no AlreadyExists race to tolerate.
        const created = yield* calls.createSfu({ accountId, name });
        return toAttributes(created, accountId, Redacted.make(created.secret ?? ""));
      }

      // Sync — the only mutable aspect is `name`; diff observed cloud
      // state against desired and skip the PUT entirely on a no-op.
      if (observed.name === name) {
        return toAttributes(observed, output.accountId, output.secret);
      }
      const updated = yield* calls.updateSfu({
        accountId: output.accountId,
        appId: output.appId,
        name,
      });
      return toAttributes(updated, output.accountId, output.secret);
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* calls
        .deleteSfu({ accountId: output.accountId, appId: output.appId })
        .pipe(Effect.catchTag("CallsAppNotFound", () => Effect.void));
    }),
  });

/**
 * Read an app by id, mapping "gone" (`CallsAppNotFound`, Cloudflare error
 * code 20007) to `undefined`.
 */
const getApp = (accountId: string, appId: string) =>
  calls
    .getSfu({ accountId, appId })
    .pipe(Effect.catchTag("CallsAppNotFound", () => Effect.undefined));

const createAppName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true }));
  });

const toAttributes = (
  app: calls.GetSfuResponse | calls.CreateSfuResponse | calls.UpdateSfuResponse,
  accountId: string,
  secret: Redacted.Redacted<string>,
): AppAttributes => ({
  appId: app.uid ?? "",
  accountId,
  secret,
  name: app.name ?? "",
  created: app.created ?? "",
  modified: app.modified ?? "",
});