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

import * as organizations from "@distilled.cloud/cloudflare/organizations";
import { Unowned } from "alchemy/AdoptPolicy";
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.Organization.Organization" as const;
type TypeId = typeof TypeId;

/**
 * Business profile attached to an organization. All fields are required
 * when a profile is present — the API stores the profile as a unit.
 */
export interface Profile {
  /**
   * Street address of the business that owns the organization.
   */
  businessAddress: string;
  /**
   * Contact email of the business.
   */
  businessEmail: string;
  /**
   * Legal name of the business.
   */
  businessName: string;
  /**
   * Contact phone number of the business.
   */
  businessPhone: string;
  /**
   * Free-form external metadata (e.g. a CRM or billing reference).
   */
  externalMetadata: string;
}

/**
 * Feature flags Cloudflare sets on an organization. Read-only —
 * controlled by the organization's entitlements.
 */
export interface Flags {
  /**
   * Whether accounts may be created under this organization.
   */
  accountCreation: string;
  /**
   * Whether accounts may be deleted under this organization.
   */
  accountDeletion: string;
  /**
   * Whether accounts may be migrated into this organization.
   */
  accountMigration: string;
  /**
   * Whether accounts may be moved between organizations.
   */
  accountMobility: string;
  /**
   * Whether sub-organizations may be created under this organization.
   */
  subOrgCreation: string;
}

export interface Props {
  /**
   * Display name of the organization. Mutable in place. If omitted, a
   * unique name is generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * ID of the parent organization, for building an organization
   * hierarchy. Changing the parent triggers a replacement — re-parenting
   * is gated by the organization's `accountMobility`/flags and is not
   * supported in place.
   */
  parent?: string;
  /**
   * Business profile of the organization. Mutable in place.
   */
  profile?: Profile;
}

export interface Attributes {
  /**
   * Cloudflare-assigned identifier of the organization.
   */
  organizationId: string;
  /**
   * Display name of the organization.
   */
  name: string;
  /**
   * ISO8601 timestamp of when the organization was created.
   */
  createTime: string;
  /**
   * Who manages this organization, if it is managed by a parent entity.
   */
  managedBy: string | undefined;
  /**
   * Feature flags controlled by the organization's entitlements.
   */
  flags: Flags | undefined;
  /**
   * Parent organization, if this organization is part of a hierarchy.
   */
  parent: { id: string; name: string } | undefined;
  /**
   * Business profile of the organization, if one is set.
   */
  profile: Profile | undefined;
}

export type Organization = Resource<TypeId, Props, Attributes, never, Providers>;

/**
 * A Cloudflare Organization — the hierarchical container above accounts.
 *
 * Organizations group accounts (and sub-organizations) under a single
 * management umbrella; an account's `managedBy.parentOrgId` points at its
 * owning organization. The feature is entitlement-gated: only tenant /
 * organizations-enabled customers can create organizations — on a standard
 * account every `/organizations` call fails with the typed `Forbidden`
 * error.
 *
 * `name` and `profile` are mutable in place; changing `parent` triggers a
 * replacement.
 *
 * Safety: organizations carry no ownership markers. When there is no prior
 * state, `read` scans for an existing organization with the same name
 * (and parent) and reports it as `Unowned`, so the engine refuses to take
 * it over unless `--adopt` (or `adopt(true)`) is set.
 * ### Creating an Organization
 * **Example:** Basic organization
 * ```typescript
 * const org = yield* Cloudflare.Organization.Organization("Platform", {
 *   name: "acme-platform",
 * });
 * ```
 *
 * **Example:** Organization with a business profile
 * ```typescript
 * const org = yield* Cloudflare.Organization.Organization("Platform", {
 *   name: "acme-platform",
 *   profile: {
 *     businessName: "Acme Corp",
 *     businessEmail: "ops@acme.com",
 *     businessPhone: "+1-555-0100",
 *     businessAddress: "1 Acme Way, Springfield",
 *     externalMetadata: "crm:acct-42",
 *   },
 * });
 * ```
 *
 * ### Hierarchies
 * **Example:** Sub-organization under a parent
 * ```typescript
 * const parent = yield* Cloudflare.Organization.Organization("Root", {
 *   name: "acme-root",
 * });
 * // Changing `parent` later replaces the sub-organization.
 * const sub = yield* Cloudflare.Organization.Organization("Emea", {
 *   name: "acme-emea",
 *   parent: parent.organizationId,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/fundamentals/setup/manage-organizations/
 *
 * @resource
 * @product Organizations
 * @category Account & Identity
 */
export const Organization = Resource<Organization>(TypeId, {
  aliases: ["Cloudflare.Organization"],
});

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

export const OrganizationProvider = () =>
  Provider.succeed(Organization, {
    stables: ["organizationId", "createTime"],

    // Enumerate every organization reachable by the credentials. Cloudflare's
    // `/organizations` collection is account-wide (no per-account scoping
    // beyond the token), so there is no env scope to resolve — just paginate
    // exhaustively and map each row to the same `Attributes` shape `read`
    // returns. The op is entitlement-gated: on an unentitled account it
    // rejects with the typed `Forbidden` error, which `list()` tolerates
    // (returns `[]`) so account-wide enumeration / `nuke` never blows up.
    list: () =>
      organizations.listOrganizations.pages({}).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) => (page.result ?? []).map(toAttributes)),
        ),
        // Organizations are a Tenant/reseller feature — a regular account
        // token gets `Forbidden` ("Authentication error"). Nothing to list.
        Effect.catchTag("Forbidden", () => Effect.succeed([])),
      ),

    diff: Effect.fn(function* ({ olds, news, output }) {
      // `news` may still carry unresolved plan-time expressions — defer
      // to the engine's default update logic until everything is concrete.
      if (!isResolved(news)) return undefined;
      // Re-parenting is not supported in place — hierarchy moves are
      // gated by `accountMobility`/flags, so a parent change replaces.
      const oldParent = output?.parent?.id ?? (olds?.parent as string | undefined);
      const newParent = news.parent;
      // `parent` is Input<string>; only compare once both are concrete.
      if (
        (oldParent === undefined) !== (newParent === undefined) ||
        (typeof oldParent === "string" && typeof newParent === "string" && oldParent !== newParent)
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, output, olds }) {
      // Owned path: refresh by our persisted organization id.
      if (output?.organizationId) {
        const observed = yield* getOrganization(output.organizationId);
        return observed ? toAttributes(observed) : undefined;
      }

      // Cold read — recover from lost state by matching the deterministic
      // physical name (+ parent). Organization names are not guaranteed
      // unique and carry no ownership markers, so report the match as
      // `Unowned`: the engine refuses to take it over unless `adopt` is
      // set.
      const name = yield* createOrganizationName(id, olds?.name);
      const parent = olds?.parent as string | undefined;
      const match = yield* findByName(name, parent);
      return match ? Unowned(toAttributes(match)) : undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const name = yield* createOrganizationName(id, news.name);
      // Inputs have been resolved to concrete strings by Plan.
      const parent = news.parent as string | undefined;

      // Observe — the organization id cached on `output` is a hint, not
      // a guarantee: a missing organization falls through to create.
      const observed = output?.organizationId
        ? yield* getOrganization(output.organizationId)
        : undefined;

      if (!observed) {
        // Ensure — greenfield (or out-of-band delete): create with the
        // full desired body. Names are not unique on Cloudflare's side,
        // so there is no AlreadyExists race to tolerate.
        const created = yield* organizations.createOrganization({
          name,
          parent: parent !== undefined ? { id: parent } : undefined,
          profile: news.profile,
        });
        return toAttributes(created);
      }

      // Sync — diff observed cloud state against desired; the update API
      // is a PUT requiring `name`, so send the full desired shape, but
      // skip the call entirely on a no-op. The desired profile keeps the
      // observed one when the props omit it (the PUT would otherwise
      // clear it).
      const desiredProfile = news.profile ?? observed.profile ?? undefined;
      const dirty = observed.name !== name || !sameProfile(observed.profile, news.profile);

      if (!dirty) {
        return toAttributes(observed);
      }

      const updated = yield* organizations.updateOrganization({
        organizationId: observed.id,
        name,
        parent: observed.parent != null ? { id: observed.parent.id } : undefined,
        profile: desiredProfile,
      });
      return toAttributes(updated);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Deletion is refused while the organization still manages
      // accounts or sub-organizations — that's a genuine dependency
      // violation, so it propagates. Already-gone is success.
      yield* organizations
        .deleteOrganization({ organizationId: output.organizationId })
        .pipe(Effect.catchTag("OrganizationNotFound", () => Effect.void));
    }),
  });

type ObservedOrganization = organizations.GetOrganizationResponse;

/**
 * Read an organization by id, mapping "gone" (`OrganizationNotFound`,
 * HTTP 404) to `undefined`.
 */
const getOrganization = (organizationId: string) =>
  organizations.getOrganization({ organizationId }).pipe(
    Effect.map((org): ObservedOrganization | undefined => org),
    Effect.catchTag("OrganizationNotFound", () => Effect.undefined),
  );

/**
 * Find an organization by exact name (and parent, when one is expected).
 * Cloudflare's name filter narrows server-side; re-check exactly
 * client-side. If several organizations carry the same name, pick the
 * oldest for determinism.
 */
const findByName = (name: string, parent: string | undefined) =>
  organizations.listOrganizations.items({ name: { contains: name } }).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .filter((org) => org.name === name && (parent === undefined || org.parent?.id === parent))
        .sort((a, b) => a.createTime.localeCompare(b.createTime))
        .at(0),
    ),
  );

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

/**
 * Compare the observed profile against the desired one. An omitted
 * desired profile is "keep whatever is there" — never a diff.
 */
const sameProfile = (observed: Profile | null | undefined, desired: Profile | undefined) =>
  desired === undefined ||
  (observed != null &&
    observed.businessAddress === desired.businessAddress &&
    observed.businessEmail === desired.businessEmail &&
    observed.businessName === desired.businessName &&
    observed.businessPhone === desired.businessPhone &&
    observed.externalMetadata === desired.externalMetadata);

const toAttributes = (
  org:
    | organizations.GetOrganizationResponse
    | organizations.CreateOrganizationResponse
    | organizations.UpdateOrganizationResponse
    | organizations.ListOrganizationsResponse["result"][number],
): Attributes => ({
  organizationId: org.id,
  name: org.name,
  createTime: org.createTime,
  managedBy: org.meta.managedBy ?? undefined,
  flags: org.meta.tenantFlags ?? undefined,
  parent: org.parent ?? undefined,
  profile: org.profile ?? undefined,
});