sailfork / t3code-github / .repos/ alchemy-effect/ packages/ stripe/ src/ EntitlementsFeature.ts

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  GetEntitlementsFeatures,
  GetEntitlementsFeature,
  CreateEntitlementsFeature,
  UpdateEntitlementsFeature,
  type EntitlementsFeature as StripeEntitlementsFeature,
} from "@distilled.cloud/stripe/stripe";
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 { tagRecord } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import {
  alchemyMetadataKeys,
  createInternalMetadata,
  diffMetadata,
  hasAlchemyMetadata,
  stripInternalMetadata,
  toMetadata,
} from "./Metadata.ts";
import { isMissingStripeResource } from "./missing.ts";
import type { Providers } from "./Providers.ts";

const NAME_MAX_LENGTH = 80;
const LOOKUP_KEY_MAX_LENGTH = 80;
const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;

export interface EntitlementsFeatureProps {
  /**
   * Unique system identifier for this feature (max 80 characters). If
   * omitted, a unique key is generated from the stack, stage, and logical
   * id. Create-only — changing it replaces the feature.
   */
  lookupKey?: string;
  /**
   * Feature name for your own purpose, not shown to customers (max 80
   * characters). If omitted, a unique name is generated from the stack,
   * stage, and logical id. Mutable.
   */
  name?: string;
  /**
   * Whether the feature can be attached to new products. Inactive
   * (archived) features are omitted from the default list endpoint.
   * @default true
   */
  active?: boolean;
  /**
   * User-defined metadata. Alchemy ownership keys (`alchemy_stack` /
   * `alchemy_stage` / `alchemy_id`) are merged in automatically. Keys may
   * not contain `:`. Mutable.
   */
  metadata?: Record<string, string>;
}

export type EntitlementsFeature = Resource<
  "Stripe.EntitlementsFeature",
  EntitlementsFeatureProps,
  {
    /** Stripe feature id (`feat_…`). */
    id: string;
    /** Unique system identifier for this feature. */
    lookupKey: string;
    /** Feature name for your own purpose, not shown to customers. */
    name: string;
    /** Whether the feature can be attached to new products. */
    active: boolean;
    /** User-defined metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
    /** Whether the feature exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Entitlements Feature — a monetizable ability you attach to
 * Products. When a customer purchases a product with this feature, Stripe
 * creates an entitlement for them. `lookup_key` is unique among active
 * features and immutable (changing it replaces the feature). Name and
 * metadata update in place.
 *
 * Stripe does not hard-delete features; destroying this resource
 * deactivates it (`active: false`). Archived features cannot be edited
 * or unarchived. An archived lookup key can be reused — a later create
 * with the same key provisions a new feature.
 *
 * @see https://docs.stripe.com/api/entitlements/feature
 *
 * ### Creating a Feature
 * **Example:** Generated lookup key
 * ```typescript
 * const seats = yield* Stripe.EntitlementsFeature("seats");
 * ```
 *
 * **Example:** Named feature with lookup key
 * ```typescript
 * const seats = yield* Stripe.EntitlementsFeature("seats", {
 *   lookupKey: "seats",
 *   name: "Seat licenses",
 * });
 * ```
 *
 * ### Updating a Feature
 * **Example:** Rename and retag
 * ```typescript
 * const seats = yield* Stripe.EntitlementsFeature("seats", {
 *   lookupKey: "seats",
 *   name: "Seat licenses (updated)",
 *   metadata: { plan: "pro" },
 * });
 * ```
 *
 * ### Deactivating a Feature
 * **Example:** Destroy deactivates rather than deleting
 * ```typescript
 * // stack.destroy() / resource removal sets active: false
 * const seats = yield* Stripe.EntitlementsFeature("seats", {
 *   lookupKey: "seats",
 *   name: "Seat licenses",
 * });
 * ```
 *
 * @resource
 * @product Entitlements
 */
export const EntitlementsFeature = Resource<EntitlementsFeature>("Stripe.EntitlementsFeature");

type EntitlementsFeatureAttributes = EntitlementsFeature["Attributes"];

const userMetadata = (
  metadata: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalMetadata(tagRecord(metadata));

const toName = (id: string, name: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return name ?? existing ?? (yield* createPhysicalName({ id, maxLength: NAME_MAX_LENGTH }));
  });

const toLookupKey = (id: string, lookupKey: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return (
      lookupKey ??
      existing ??
      (yield* createPhysicalName({
        id,
        maxLength: LOOKUP_KEY_MAX_LENGTH,
        lowercase: true,
      }))
    );
  });

const toAttrs = (feature: StripeEntitlementsFeature): EntitlementsFeatureAttributes => ({
  id: feature.id,
  lookupKey: feature.lookup_key,
  name: feature.name,
  active: feature.active,
  metadata: userMetadata(feature.metadata),
  livemode: feature.livemode,
});

const isMissingFeature = isMissingStripeResource;

const getById = (id: string) =>
  GetEntitlementsFeature({ id }).pipe(Effect.catchIf(isMissingFeature, () => Effect.undefined));

const listByArchived = Effect.fn(function* (archived: boolean) {
  const features: StripeEntitlementsFeature[] = [];
  let startingAfter: string | undefined;
  for (let page = 0; page < LIST_MAX_PAGES; page++) {
    const response = yield* GetEntitlementsFeatures({
      archived,
      limit: LIST_PAGE_SIZE,
      ...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
    });
    features.push(...response.data);
    if (!response.has_more || response.data.length === 0) {
      break;
    }
    startingAfter = response.data[response.data.length - 1]?.id;
    if (startingAfter === undefined) {
      break;
    }
  }
  return features;
});

const findByLookupKey = Effect.fn(function* (lookupKey: string) {
  // Archived features cannot be updated or unarchived. Their lookup keys
  // are reusable, so observation must ignore them and let ensure create.
  const active = yield* GetEntitlementsFeatures({
    lookup_key: lookupKey,
    archived: false,
    limit: LIST_PAGE_SIZE,
  });
  return active.data[0];
});

const findByAlchemyId = Effect.fn(function* (id: string) {
  const features = yield* listByArchived(false);
  const matches: StripeEntitlementsFeature[] = [];
  for (const feature of features) {
    if (yield* hasAlchemyMetadata(id, tagRecord(feature.metadata))) {
      matches.push(feature);
    }
  }
  matches.sort((a, b) => (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
  return matches[0];
});

const observe = Effect.fn(function* (input: {
  id?: string;
  logicalId: string;
  lookupKey?: string;
}) {
  if (input.id !== undefined) {
    const byId = yield* getById(input.id);
    if (byId !== undefined) return byId;
  }
  if (input.lookupKey !== undefined) {
    const byKey = yield* findByLookupKey(input.lookupKey);
    if (
      byKey !== undefined &&
      (yield* hasAlchemyMetadata(input.logicalId, tagRecord(byKey.metadata)))
    ) {
      return byKey;
    }
  }
  return yield* findByAlchemyId(input.logicalId);
});

const desiredMetadata = Effect.fn(function* (
  id: string,
  metadata: Record<string, string> | undefined,
) {
  return {
    ...toMetadata(metadata),
    ...(yield* createInternalMetadata(id)),
  };
});

const shouldReplace = (
  news: EntitlementsFeatureProps,
  output: EntitlementsFeatureAttributes | undefined,
): boolean => {
  if (output === undefined) return false;
  if (news.lookupKey !== undefined && news.lookupKey !== output.lookupKey) {
    return true;
  }
  return false;
};

export const EntitlementsFeatureProvider = () =>
  Provider.succeed(EntitlementsFeature, {
    stables: ["id", "lookupKey", "livemode"],

    diff: Effect.fn(function* ({ news, output }) {
      if (!isResolved(news)) return undefined;
      if (shouldReplace(news, output)) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, output }) {
      const existing = yield* observe({
        id: output?.id,
        logicalId: id,
        lookupKey: output?.lookupKey,
      });
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing);
      return (yield* hasAlchemyMetadata(id, tagRecord(existing.metadata))) ? attrs : Unowned(attrs);
    }),

    list: Effect.fn(function* () {
      // Default list API is active features; archived (deactivated) rows
      // stay in Stripe but must not re-enter nuke. Filter to alchemy_stack
      // so account-wide teardown only touches our rows.
      const features = yield* listByArchived(false);
      return features
        .filter((feature) => {
          const metadata = tagRecord(feature.metadata);
          return metadata[alchemyMetadataKeys.stack] !== undefined;
        })
        .map(toAttrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const lookupKey = yield* toLookupKey(id, news.lookupKey, output?.lookupKey);
      const name = yield* toName(id, news.name, output?.name);
      const metadata = yield* desiredMetadata(id, news.metadata);
      const desiredActive = news.active ?? true;

      let current: StripeEntitlementsFeature | undefined = yield* observe({
        id: output?.id,
        logicalId: id,
        lookupKey,
      });
      if (current !== undefined && shouldReplace(news, toAttrs(current))) {
        current = undefined;
      }
      // Stripe rejects updates to archived features and cannot unarchive
      // them. Treat inactive rows as missing so ensure creates a new one
      // (lookup keys become reusable once archived).
      if (current !== undefined && current.active === false) {
        if (desiredActive === false) {
          return toAttrs(current);
        }
        current = undefined;
      }

      if (current === undefined) {
        current = yield* CreateEntitlementsFeature({
          lookup_key: lookupKey,
          name,
          metadata,
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-entitlements-feature-${instanceId}`,
          }),
        );
      }

      const observedMetadata = tagRecord(current.metadata);
      const { upsert, removed } = diffMetadata(observedMetadata, metadata);
      const metadataChanged = upsert.length > 0 || removed.length > 0;
      const nameChanged = current.name !== name;
      const activeChanged = current.active !== desiredActive;

      if (!nameChanged && !activeChanged && !metadataChanged) {
        return toAttrs(current);
      }

      const updated = yield* UpdateEntitlementsFeature({
        id: current.id,
        ...(nameChanged ? { name } : {}),
        ...(activeChanged ? { active: desiredActive } : {}),
        ...(metadataChanged
          ? {
              metadata: {
                ...Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value])),
                ...Object.fromEntries(removed.map((key) => [key, ""])),
              },
            }
          : {}),
      });
      return toAttrs(updated);
    }),

    delete: Effect.fn(function* ({ output }) {
      const existing = yield* getById(output.id);
      if (existing === undefined || !existing.active) return;
      yield* UpdateEntitlementsFeature({
        id: existing.id,
        active: false,
      }).pipe(Effect.catchIf(isMissingFeature, () => Effect.void));
    }),
  });