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

import * as accounts from "@distilled.cloud/cloudflare/accounts";
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 type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.Account.Account" as const;
type TypeId = typeof TypeId;

/**
 * The kind of Cloudflare account. Cannot be changed after creation.
 */
export type AccountType = "standard" | "enterprise";

export interface AccountProps {
  /**
   * Account name (display name). Mutable in place. If omitted, a unique
   * name is generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The kind of account to create. Cannot be changed after creation —
   * Cloudflare rejects type changes (`UpdateAccountTypeNotSupported`), so
   * updating this property triggers a replacement.
   * @default "standard"
   */
  type?: AccountType;
  /**
   * Tenant unit to create the account under. Only meaningful for tenant /
   * partner credentials; defaults to the tenant's root unit. Create-only —
   * updating this property triggers a replacement.
   *
   * @see https://developers.cloudflare.com/tenant/how-to/manage-accounts/
   */
  unit?: {
    /**
     * The id of the tenant unit to create the account on.
     */
    id?: string;
  };
  /**
   * Abuse contact email address for the account
   * (`settings.abuse_contact_email`). Mutable in place. When omitted, the
   * setting is left unmanaged (an existing value is not cleared).
   */
  abuseContactEmail?: string;
  /**
   * Whether membership in this account requires that two-factor
   * authentication is enabled (`settings.enforce_twofactor`). Mutable in
   * place. When omitted, the setting is left unmanaged.
   * @default false
   */
  enforceTwofactor?: boolean;
}

export interface AccountAttributes {
  /**
   * Account identifier tag assigned by Cloudflare.
   */
  accountId: string;
  /**
   * Account name (display name).
   */
  name: string;
  /**
   * The kind of account.
   */
  type: AccountType;
  /**
   * Timestamp for the creation of the account.
   */
  createdOn: string | undefined;
  /**
   * Id of the tenant organization the account is managed by, if any.
   */
  parentOrgId: string | undefined;
  /**
   * Name of the tenant organization the account is managed by, if any.
   */
  parentOrgName: string | undefined;
  /**
   * Abuse contact email address configured on the account, if any.
   */
  abuseContactEmail: string | undefined;
  /**
   * Whether membership in the account requires two-factor authentication.
   */
  enforceTwofactor: boolean;
}

export type Account = Resource<TypeId, AccountProps, AccountAttributes, never, Providers>;

/**
 * A Cloudflare account (subaccount), for tenant / partner platforms that
 * provision an account per customer.
 *
 * Creating accounts (`POST /accounts`) is restricted to credentials with the
 * tenant entitlement — a standard user receives the typed
 * `AccountCreationForbidden` error (Cloudflare error code 1002). The `name`
 * and account settings are mutable in place; `type` and the tenant `unit`
 * are create-only and trigger a replacement. Deleting the resource queues
 * the account for deletion (also tenant-gated).
 *
 * The account's physical identity is the Cloudflare-assigned `accountId`.
 * Account names are not unique, so there is no find-by-name fallback: if
 * state is lost, the account is treated as missing rather than guessed at.
 * ### Creating an account
 * **Example:** Standard subaccount with a generated name
 * ```typescript
 * const account = yield* Cloudflare.Account.Account("CustomerAccount", {});
 * ```
 *
 * **Example:** Subaccount on a specific tenant unit
 * ```typescript
 * const account = yield* Cloudflare.Account.Account("CustomerAccount", {
 *   name: "Customer: ACME Inc",
 *   unit: { id: tenantUnitId },
 * });
 * ```
 *
 * ### Account settings
 * **Example:** Enforce two-factor authentication for all members
 * ```typescript
 * const account = yield* Cloudflare.Account.Account("CustomerAccount", {
 *   name: "Customer: ACME Inc",
 *   enforceTwofactor: true,
 *   abuseContactEmail: "abuse@acme.example",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/tenant/how-to/manage-accounts/
 *
 * @resource
 * @product Accounts
 * @category Account & Identity
 */
export const Account = Resource<Account>(TypeId, {
  aliases: ["Cloudflare.Account"],
});

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

export const AccountProvider = () =>
  Provider.succeed(Account, {
    stables: ["accountId", "type", "createdOn", "parentOrgId", "parentOrgName"],

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      // The account type cannot be changed after creation — Cloudflare
      // rejects it with `UpdateAccountTypeNotSupported`.
      const oldType = output?.type ?? olds?.type ?? "standard";
      if ((news.type ?? "standard") !== oldType) {
        return { action: "replace" } as const;
      }
      // The tenant unit is a create-only placement decision.
      if ((olds?.unit?.id ?? undefined) !== (news.unit?.id ?? undefined)) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    list: () =>
      // `listAccounts` (GET /accounts) enumerates every account the API
      // token can access — no scope input required. The list items carry
      // the full account shape (settings + managedBy), so each maps
      // directly to the same `Attributes` `read` produces with no
      // per-item hydration. Paginate exhaustively.
      accounts.listAccounts.pages({}).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((account) => toAttributes(account)),
          ),
        ),
      ),

    read: Effect.fn(function* ({ output }) {
      // The physical identity is the Cloudflare-assigned account id —
      // names are not unique, so there is no cold find-by-name fallback.
      if (!output?.accountId) return undefined;
      const observed = yield* getAccount(output.accountId);
      return observed ? toAttributes(observed) : undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const name = news.name ?? (yield* createPhysicalName({ id, lowercase: true }));

      // 1. Observe — the account id cached on `output` is a hint, not a
      //    guarantee: a deleted account falls through to create.
      let observed = output?.accountId ? yield* getAccount(output.accountId) : undefined;

      // 2. Ensure — create when missing. Names are not unique on
      //    Cloudflare's side, so there is no AlreadyExists race to
      //    tolerate. Requires the tenant entitlement: a standard user
      //    surfaces the typed `AccountCreationForbidden` (code 1002).
      if (!observed) {
        observed = yield* accounts.createAccount({
          name,
          type: news.type,
          unit: news.unit,
        });
      }

      // 3. Sync — diff observed cloud state against desired; skip the PUT
      //    entirely on a no-op. Settings props left undefined are
      //    unmanaged: the observed value is kept as-is.
      const settings = observed.settings ?? undefined;
      const nameDirty = observed.name !== name;
      const abuseDirty =
        news.abuseContactEmail !== undefined &&
        (settings?.abuseContactEmail ?? undefined) !== news.abuseContactEmail;
      const twofactorDirty =
        news.enforceTwofactor !== undefined &&
        (settings?.enforceTwofactor ?? false) !== news.enforceTwofactor;

      if (nameDirty || abuseDirty || twofactorDirty) {
        observed = yield* accounts.updateAccount({
          accountId: observed.id,
          id: observed.id,
          name,
          settings:
            abuseDirty || twofactorDirty
              ? {
                  abuseContactEmail: news.abuseContactEmail,
                  enforceTwofactor: news.enforceTwofactor,
                }
              : undefined,
        });
      }

      return toAttributes(observed);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Account deletion is queued / asynchronous on Cloudflare's side —
      // a successful DELETE means "pending deletion", which is success for
      // us. An already-gone (or already-pending) account surfaces as
      // `InvalidRoute` (code 7003): that's success too.
      yield* accounts
        .deleteAccount({ accountId: output.accountId })
        .pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
    }),
  });

type ObservedAccount =
  | accounts.GetAccountResponse
  | accounts.CreateAccountResponse
  | accounts.UpdateAccountResponse
  | accounts.ListAccountsResponse["result"][number];

/**
 * Read an account by id, mapping "gone" to `undefined`. A missing (or
 * deletion-pending) account surfaces as `InvalidRoute` (Cloudflare error
 * code 7003).
 */
const getAccount = (accountId: string) =>
  accounts.getAccount({ accountId }).pipe(
    Effect.map((account): ObservedAccount | undefined => account),
    Effect.catchTag("InvalidRoute", () => Effect.undefined),
  );

const toAttributes = (account: ObservedAccount): AccountAttributes => ({
  accountId: account.id,
  name: account.name,
  // Distilled widens generated string enums to open unions (`string & {}`).
  type: account.type as AccountType,
  createdOn: account.createdOn ?? undefined,
  parentOrgId: account.managedBy?.parentOrgId ?? undefined,
  parentOrgName: account.managedBy?.parentOrgName ?? undefined,
  abuseContactEmail: account.settings?.abuseContactEmail ?? undefined,
  enforceTwofactor: account.settings?.enforceTwofactor ?? false,
});