sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Access/ Bookmark.ts

import * as crypto from "node:crypto";
import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

export class BookmarkUnexpectedResponse extends Data.TaggedError("BookmarkUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type BookmarkProps = {
  /**
   * The name of the bookmark application shown in the App Launcher. Used as
   * a stable identifier so the provider can locate the bookmark during
   * adoption / state recovery. If omitted, a unique name is generated from
   * the stack/stage/logical id.
   *
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The domain the bookmark links to, e.g. `example.com` or
   * `wiki.example.com/path`.
   */
  domain: string;
  /**
   * The image URL for the logo shown in the App Launcher dashboard.
   */
  logoUrl?: string;
  /**
   * Whether to display the bookmark in the App Launcher.
   *
   * @default true
   */
  appLauncherVisible?: boolean;
};

export type Bookmark = Resource<
  "Cloudflare.Access.Bookmark",
  BookmarkProps,
  {
    /** UUID of the bookmark application. */
    bookmarkId: string;
    /** Cloudflare account that owns the bookmark. */
    accountId: string;
    /** Display name reported by Cloudflare. */
    name: string;
    /** The domain the bookmark links to. */
    domain: string;
    /** The logo URL shown in the App Launcher. */
    logoUrl: string | undefined;
    /** Whether the bookmark is displayed in the App Launcher. */
    appLauncherVisible: boolean;
  },
  never,
  Providers
>;

/**
 * A Cloudflare Zero Trust Access bookmark application — an unprotected link
 * shown in the App Launcher.
 * @deprecated **Legacy resource.** Cloudflare has deprecated the dedicated
 * bookmarks API in favor of Access applications with `type: "bookmark"` —
 * prefer {@link Application} for new configurations. This resource is
 * provided for managing pre-existing bookmark records.
 *
 * ### Creating a Bookmark
 * **Example:** Basic bookmark
 * ```typescript
 * const bookmark = yield* Cloudflare.Access.Bookmark("Wiki", {
 *   domain: "wiki.example.com",
 * });
 * ```
 *
 * **Example:** Bookmark with a logo, hidden from the App Launcher
 * ```typescript
 * const bookmark = yield* Cloudflare.Access.Bookmark("Wiki", {
 *   name: "internal-wiki",
 *   domain: "wiki.example.com",
 *   logoUrl: "https://example.com/logo.png",
 *   appLauncherVisible: false,
 * });
 * ```
 *
 * ### Preferred Alternative
 * **Example:** Bookmark-type Access application (non-legacy)
 * ```typescript
 * const app = yield* Cloudflare.Access.Application("Wiki", {
 *   type: "bookmark",
 *   domain: "wiki.example.com",
 * });
 * ```
 *
 * @resource
 * @product Access
 * @category Cloudflare One (Zero Trust)
 */
export const Bookmark = Resource<Bookmark>("Cloudflare.Access.Bookmark");

export const isBookmark = (value: unknown): value is Bookmark =>
  Predicate.hasProperty(value, "Type") && value.Type === "Cloudflare.Access.Bookmark";

export const BookmarkProvider = () =>
  Provider.succeed(Bookmark, {
    stables: ["bookmarkId", "accountId"],
    diff: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // name/domain/logoUrl/appLauncherVisible converge via PUT.
    }),
    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      if (output?.bookmarkId) {
        const direct = yield* getBookmark(acct, output.bookmarkId);
        if (direct && direct.id) return toAttrs(direct, acct);
      }
      const name = yield* createBookmarkName(id, output?.name ?? olds?.name);
      const existing = yield* findBookmarkByName(acct, name);
      if (!existing || !existing.id) return undefined;
      return toAttrs(existing, acct);
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const name = yield* createBookmarkName(id, news.name);
      const desiredVisible = news.appLauncherVisible ?? true;

      // Observe — prefer the cached id, fall back to a name lookup so we
      // recover from out-of-band deletes and state-persistence failures.
      let observed: ObservedBookmark | undefined;
      if (output?.bookmarkId) {
        observed = yield* getBookmark(acct, output.bookmarkId);
      }
      if (!observed || !observed.id) {
        observed = yield* findBookmarkByName(acct, name);
      }

      // Ensure — create when missing. The legacy API requires the new
      // bookmark's UUID in the path, so derive a deterministic one from the
      // name: a retry after a partial failure converges on the same record.
      if (!observed || !observed.id) {
        const bookmarkId = yield* deterministicUuid(`${acct}:${name}`);
        const created = yield* zeroTrust
          .createAccessBookmark({
            accountId: acct,
            bookmarkId,
            name,
            domain: news.domain,
            logoUrl: news.logoUrl,
            appLauncherVisible: desiredVisible,
          })
          .pipe(
            Effect.catch((err) =>
              Effect.gen(function* () {
                const existing = yield* getBookmark(acct, bookmarkId);
                if (existing && existing.id) return existing;
                return yield* err;
              }),
            ),
          );
        if (!created.id) {
          return yield* new BookmarkUnexpectedResponse({
            message: "Bookmark: created bookmark missing id",
          });
        }
        return toAttrs(created, acct);
      }

      // Sync — PUT the full desired shape only on a real delta.
      if (
        observed.name !== name ||
        observed.domain !== news.domain ||
        (observed.logoUrl ?? undefined) !== news.logoUrl ||
        (observed.appLauncherVisible ?? true) !== desiredVisible
      ) {
        const updated = yield* zeroTrust.updateAccessBookmark({
          accountId: acct,
          bookmarkId: observed.id,
          name,
          domain: news.domain,
          logoUrl: news.logoUrl,
          appLauncherVisible: desiredVisible,
        });
        observed = {
          id: updated.id ?? observed.id,
          name: updated.name ?? name,
          domain: updated.domain ?? news.domain,
          logoUrl: updated.logoUrl ?? news.logoUrl,
          appLauncherVisible: updated.appLauncherVisible ?? desiredVisible,
        };
      }

      return toAttrs(observed, acct);
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* zeroTrust
        .deleteAccessBookmark({
          accountId: output.accountId,
          bookmarkId: output.bookmarkId,
        })
        .pipe(Effect.catchTag("AccessBookmarkNotFound", () => Effect.void));
    }),
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* zeroTrust.listAccessBookmarks.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .filter((b): b is ObservedBookmark & { id: string } => Predicate.isNotNullish(b.id))
              .map((b) => toAttrs(b, accountId)),
          ),
        ),
      );
    }),
  });

const createBookmarkName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    if (name) return name;
    return yield* createPhysicalName({ id });
  });

const getBookmark = (acct: string, bookmarkId: string) =>
  zeroTrust
    .getAccessBookmark({ accountId: acct, bookmarkId })
    .pipe(Effect.catchTag("AccessBookmarkNotFound", () => Effect.undefined));

const findBookmarkByName = (acct: string, name: string) =>
  zeroTrust.listAccessBookmarks.items({ accountId: acct }).pipe(
    Stream.filter((b): b is ObservedBookmark => b.name === name),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
    Effect.orElseSucceed(() => undefined),
  );

/** RFC-4122-shaped v4 UUID derived deterministically from a seed string. */
const deterministicUuid = (seed: string) =>
  Effect.sync(() => {
    const hex = crypto.createHash("sha256").update(seed).digest("hex");
    const bytes = hex.slice(0, 32).split("");
    bytes[12] = "4";
    bytes[16] = ((parseInt(bytes[16]!, 16) & 0x3) | 0x8).toString(16);
    const s = bytes.join("");
    return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`;
  });

const toAttrs = (observed: ObservedBookmark, accountId: string) => ({
  bookmarkId: observed.id!,
  accountId,
  name: observed.name ?? "",
  domain: observed.domain ?? "",
  logoUrl: observed.logoUrl ?? undefined,
  appLauncherVisible: observed.appLauncherVisible ?? true,
});

type ObservedBookmark = {
  id?: string;
  name?: string | null;
  domain?: string | null;
  logoUrl?: string | null;
  appLauncherVisible?: boolean | null;
};