sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Stream/ Watermark.ts

import * as stream from "@distilled.cloud/cloudflare/stream";
import { isResolved } from "alchemy/Diff";
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 Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.Stream.Watermark" as const;
type TypeId = typeof TypeId;

/**
 * Location of the watermark image on the video.
 */
export type WatermarkPosition = "upperRight" | "upperLeft" | "lowerLeft" | "lowerRight" | "center";

export type WatermarkProps = {
  /**
   * A short description of the watermark profile. If omitted, a unique
   * name is generated from the app, stage, and logical ID. Watermark
   * profiles have no update endpoint — changing the name triggers a
   * replacement.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * URL of the watermark image (a PNG up to 2 MiB) for Cloudflare to
   * download. Changing the URL triggers a replacement.
   */
  url: string;
  /**
   * The translucency of the image. `0.0` is completely transparent and
   * `1.0` is completely opaque. Changing the opacity triggers a
   * replacement.
   * @default 1.0
   */
  opacity?: number;
  /**
   * The whitespace between the adjacent edges (determined by position)
   * of the video and the image. `0.0` is no padding, `1.0` is a fully
   * padded video width or length. Changing the padding triggers a
   * replacement.
   * @default 0.05
   */
  padding?: number;
  /**
   * The location of the image. Note that `center` ignores the `padding`
   * parameter. Changing the position triggers a replacement.
   * @default "upperRight"
   */
  position?: WatermarkPosition;
  /**
   * The size of the image relative to the overall size of the video.
   * `0.0` means no scaling, `1.0` fills the entire video. Changing the
   * scale triggers a replacement.
   * @default 0.15
   */
  scale?: number;
};

export type WatermarkAttributes = {
  /**
   * The unique identifier for the watermark profile (Cloudflare `uid`).
   */
  watermarkId: string;
  /**
   * The Cloudflare account the watermark profile belongs to.
   */
  accountId: string;
  /**
   * A short description of the watermark profile.
   */
  name: string;
  /**
   * The date and time the watermark profile was created.
   */
  created: string | undefined;
  /**
   * The source URL the watermark image was downloaded from.
   */
  downloadedFrom: string | undefined;
  /**
   * The translucency of the image.
   */
  opacity: number;
  /**
   * The whitespace between the video edges and the image.
   */
  padding: number;
  /**
   * The location of the image.
   */
  position: WatermarkPosition;
  /**
   * The size of the image relative to the overall size of the video.
   */
  scale: number;
  /**
   * The size of the image in bytes.
   */
  size: number | undefined;
  /**
   * The height of the image in pixels.
   */
  height: number | undefined;
  /**
   * The width of the image in pixels.
   */
  width: number | undefined;
};

export type Watermark = Resource<TypeId, WatermarkProps, WatermarkAttributes, never, Providers>;

/**
 * A Cloudflare Stream watermark profile — a PNG image stamped onto
 * videos at upload time.
 *
 * Watermark profiles are create-only: Cloudflare exposes no update
 * endpoint, so **every** prop change triggers a replacement (a new
 * profile is created and the old one deleted). The image is downloaded
 * by Cloudflare from the given URL at creation time.
 *
 * Requires the Stream subscription to be enabled on the account.
 * ### Creating a watermark
 * **Example:** Default watermark from an image URL
 * ```typescript
 * const watermark = yield* Cloudflare.Stream.Watermark("Logo", {
 *   url: "https://example.com/logo.png",
 * });
 * ```
 *
 * **Example:** Centered semi-transparent watermark
 * ```typescript
 * const watermark = yield* Cloudflare.Stream.Watermark("Logo", {
 *   url: "https://example.com/logo.png",
 *   position: "center",
 *   opacity: 0.5,
 *   scale: 0.3,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/stream/edit-videos/applying-watermarks/
 *
 * @resource
 * @product Stream
 * @category Media
 */
export const Watermark = Resource<Watermark>(TypeId);

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

export const WatermarkProvider = () =>
  Provider.succeed(Watermark, {
    stables: ["watermarkId", "accountId", "created", "downloadedFrom", "size", "height", "width"],

    diff: Effect.fn(function* ({ id, olds, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output !== undefined && output.accountId !== accountId) {
        return { action: "replace" } as const;
      }
      if (olds === undefined) return undefined;
      // `news` may still contain unresolved Outputs at plan time — let
      // the engine apply the default update logic in that case.
      if (!isResolved(news)) return undefined;
      // No update endpoint — any prop change is a replacement. Compare
      // against the observed output where the API echoes the value, and
      // against olds for the create-only `url`.
      const oldName = output?.name ?? olds.name ?? (yield* watermarkName(id, olds.name));
      const newName = yield* watermarkName(id, news.name);
      if (
        newName !== oldName ||
        news.url !== olds.url ||
        (news.opacity ?? 1.0) !== (output?.opacity ?? olds.opacity ?? 1.0) ||
        (news.padding ?? 0.05) !== (output?.padding ?? olds.padding ?? 0.05) ||
        (news.position ?? "upperRight") !== (output?.position ?? olds.position ?? "upperRight") ||
        (news.scale ?? 0.15) !== (output?.scale ?? olds.scale ?? 0.15)
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, output, olds, previous }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      if (output?.watermarkId) {
        const observed = yield* getWatermark(acct, output.watermarkId);
        return observed ? toAttributes(observed, acct) : undefined;
      }
      // Cold read — recover from lost state by matching the
      // deterministic physical name. Names are not unique on
      // Cloudflare's side; an exact match on our generated/explicit
      // name is the best identity we have.
      const name = yield* watermarkName(id, olds?.name);
      const match = yield* findByName(acct, name);
      // A replacement reuses the name: the watermark it is replacing is not
      // the replacement.
      if (!match || match.uid === previous?.watermarkId) return undefined;
      return toAttributes(match, acct);
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* watermarkName(id, news.name);

      // Observe — the uid cached on `output` is a hint, not a
      // guarantee: a not-found falls through to "missing" and we
      // recreate.
      const observed = output?.watermarkId
        ? yield* getWatermark(output.accountId ?? accountId, output.watermarkId)
        : undefined;

      if (observed) {
        // Create-only resource — prop drift is handled as a replacement
        // by `diff`; nothing to sync here.
        return toAttributes(observed, output?.accountId ?? accountId);
      }

      // Ensure — create with the full desired body. uids are
      // auto-assigned so there is no AlreadyExists race to tolerate.
      const created = yield* stream.createWatermark({
        accountId,
        name,
        url: news.url,
        opacity: news.opacity,
        padding: news.padding,
        position: news.position,
        scale: news.scale,
      });
      return toAttributes(created, accountId);
    }),

    list: Effect.fn(function* () {
      // Account-scoped collection — watermark profiles are enumerated
      // per account. `listWatermarks` is paginated (items: "result");
      // collect every page and hydrate into the `read` Attributes shape.
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* stream.listWatermarks.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((w) => toAttributes(w, accountId)),
          ),
        ),
      );
    }),

    delete: Effect.fn(function* ({ output }) {
      // Idempotent — a watermark already deleted out-of-band surfaces
      // as `WatermarkNotFound` (Cloudflare error code 10003).
      yield* stream
        .deleteWatermark({
          accountId: output.accountId,
          identifier: output.watermarkId,
        })
        .pipe(Effect.catchTag("WatermarkNotFound", () => Effect.void));
    }),
  });

/**
 * Read a watermark by uid, mapping "gone" (`WatermarkNotFound`,
 * Cloudflare error code 10003) to `undefined`.
 */
const getWatermark = (accountId: string, watermarkId: string) =>
  stream
    .getWatermark({ accountId, identifier: watermarkId })
    .pipe(Effect.catchTag("WatermarkNotFound", () => Effect.undefined));

/**
 * Find a watermark by exact name. Names are not unique — if several
 * watermarks carry the same name, pick the oldest for determinism.
 */
const findByName = (accountId: string, name: string) =>
  stream.listWatermarks({ accountId }).pipe(
    Effect.map((list) =>
      [...list.result]
        .filter((w) => w.name === name)
        .sort((a, b) => (a.created ?? "").localeCompare(b.created ?? ""))
        .at(0),
    ),
  );

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

const toAttributes = (
  watermark:
    | stream.GetWatermarkResponse
    | stream.CreateWatermarkResponse
    | stream.ListWatermarksResponse["result"][number],
  accountId: string,
): WatermarkAttributes => ({
  watermarkId: watermark.uid ?? "",
  accountId,
  name: watermark.name ?? "",
  created: watermark.created ?? undefined,
  downloadedFrom: watermark.downloadedFrom ?? undefined,
  opacity: watermark.opacity ?? 1.0,
  padding: watermark.padding ?? 0.05,
  position: (watermark.position ?? "upperRight") as WatermarkPosition,
  scale: watermark.scale ?? 0.15,
  size: watermark.size ?? undefined,
  height: watermark.height ?? undefined,
  width: watermark.width ?? undefined,
});