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

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  DeleteRadarValueList,
  GetRadarValueLists,
  GetRadarValueList,
  CreateRadarValueList,
  UpdateRadarValueList,
  type RadarValueList as StripeRadarValueList,
} 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 Data from "effect/Data";
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 = 250;
const ALIAS_MAX_LENGTH = 100;
const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;

/**
 * Type of items stored in a Radar value list. Create-only — changing it
 * replaces the list.
 */
export type RadarValueListItemType =
  | "account"
  | "card_bin"
  | "card_fingerprint"
  | "case_sensitive_string"
  | "country"
  | "crypto_fingerprint"
  | "customer_id"
  | "email"
  | "ip_address"
  | "sepa_debit_fingerprint"
  | "string"
  | "us_bank_account_fingerprint";

export interface RadarValueListProps {
  /**
   * Alias used to reference this list in Radar rules. Unique per account;
   * alphanumeric characters and underscores only, max 100 characters. If
   * omitted, a unique alias is generated from the stack, stage, and
   * logical id. Create-only — changing it replaces the list.
   */
  alias?: string;
  /**
   * Human-readable name shown in the Stripe Dashboard. If omitted, a unique
   * name is generated from the stack, stage, and logical id. Mutable.
   */
  name?: string;
  /**
   * Type of items stored in this list. Immutable after create.
   * @default "string"
   */
  itemType?: RadarValueListItemType;
  /**
   * 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 RadarValueList = Resource<
  "Stripe.RadarValueList",
  RadarValueListProps,
  {
    /** Stripe Radar value list id (`rsl_…`). */
    id: string;
    /** Alias used to reference this list in Radar rules. */
    alias: string;
    /** Human-readable name shown in the Stripe Dashboard. */
    name: string;
    /** Type of items stored in this list. */
    itemType: RadarValueListItemType;
    /** Name or email of the user who created this list. */
    createdBy: string;
    /** User-defined metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
    /** Unix timestamp when the list was created. */
    created: number;
    /** Whether the list exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Radar Value List — a named collection of values (emails, IPs,
 * card fingerprints, …) referenced from Radar rules. `alias` and
 * `itemType` are immutable and changing them replaces the list. Name and
 * metadata update in place. Destroy deletes the list and its items; a
 * list referenced by a Radar rule cannot be deleted.
 *
 * Radar custom lists may require Radar for Fraud Teams.
 *
 * @see https://docs.stripe.com/api/radar/value_lists
 *
 * ### Creating a Value List
 * **Example:** Generated alias
 * ```typescript
 * const blocked = yield* Stripe.RadarValueList("blocked-emails", {
 *   itemType: "email",
 * });
 * ```
 *
 * **Example:** Named list with alias
 * ```typescript
 * const blocked = yield* Stripe.RadarValueList("blocked-emails", {
 *   alias: "custom_email_blocklist",
 *   name: "Blocked emails",
 *   itemType: "email",
 * });
 * ```
 *
 * ### Updating a Value List
 * **Example:** Rename and retag
 * ```typescript
 * const blocked = yield* Stripe.RadarValueList("blocked-emails", {
 *   alias: "custom_email_blocklist",
 *   name: "Blocked emails (updated)",
 *   itemType: "email",
 *   metadata: { team: "fraud" },
 * });
 * ```
 *
 * ### Replacing a Value List
 * **Example:** Changing item type replaces the list
 * ```typescript
 * const blocked = yield* Stripe.RadarValueList("blocked", {
 *   alias: "custom_blocklist",
 *   itemType: "ip_address",
 * });
 * ```
 *
 * @resource
 * @product Radar
 */
export const RadarValueList = Resource<RadarValueList>("Stripe.RadarValueList");

export class RadarValueListNotResolved extends Data.TaggedError(
  "Stripe.RadarValueListNotResolved",
)<{
  alias: string;
}> {}

type RadarValueListAttributes = RadarValueList["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 toAlias = (id: string, alias: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (alias !== undefined) return alias;
    if (existing !== undefined) return existing;
    const generated = yield* createPhysicalName({
      id,
      maxLength: ALIAS_MAX_LENGTH,
      lowercase: true,
      delimiter: "_",
    });
    // Stripe aliases allow only [A-Za-z0-9_]; physical names may still
    // contain hyphens from the stack/stage prefix.
    return generated.replaceAll("-", "_");
  });

const toAttrs = (list: StripeRadarValueList): RadarValueListAttributes => ({
  id: list.id,
  alias: list.alias,
  name: list.name,
  itemType: list.item_type,
  createdBy: list.created_by,
  metadata: userMetadata(list.metadata),
  created: list.created,
  livemode: list.livemode,
});

const isMissingValueList = isMissingStripeResource;

const getById = (valueList: string) =>
  GetRadarValueList({ value_list: valueList }).pipe(
    Effect.catchIf(isMissingValueList, () => Effect.undefined),
  );

const findByAlias = (alias: string) =>
  Effect.gen(function* () {
    const response = yield* GetRadarValueLists({
      alias,
      limit: 1,
    });
    return response.data[0];
  });

const listAllValueLists = Effect.fn(function* () {
  const lists: StripeRadarValueList[] = [];
  let startingAfter: string | undefined;
  for (let page = 0; page < LIST_MAX_PAGES; page++) {
    const response = yield* GetRadarValueLists({
      limit: LIST_PAGE_SIZE,
      ...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
    });
    lists.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 lists;
});

const findByAlchemyId = Effect.fn(function* (id: string) {
  const lists = yield* listAllValueLists();
  const matches: StripeRadarValueList[] = [];
  for (const list of lists) {
    if (yield* hasAlchemyMetadata(id, tagRecord(list.metadata))) {
      matches.push(list);
    }
  }
  matches.sort((a, b) => b.created - a.created);
  return matches[0];
});

const observe = Effect.fn(function* (input: { id?: string; logicalId: string; alias?: string }) {
  if (input.id !== undefined) {
    const byId = yield* getById(input.id);
    if (byId !== undefined) return byId;
  }
  if (input.alias !== undefined) {
    const byAlias = yield* findByAlias(input.alias);
    if (
      byAlias !== undefined &&
      (yield* hasAlchemyMetadata(input.logicalId, tagRecord(byAlias.metadata)))
    ) {
      return byAlias;
    }
  }
  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: RadarValueListProps,
  output: RadarValueListAttributes | undefined,
): boolean => {
  if (output === undefined) return false;
  if (news.alias !== undefined && news.alias !== output.alias) {
    return true;
  }
  if (news.itemType !== undefined && news.itemType !== output.itemType) {
    return true;
  }
  return false;
};

export const RadarValueListProvider = () =>
  Provider.succeed(RadarValueList, {
    stables: ["id", "alias", "itemType", "created", "createdBy", "livemode"],

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      if (shouldReplace(news, output)) {
        const previousAlias = output?.alias ?? olds?.alias;
        return {
          action: "replace" as const,
          deleteFirst: news.alias !== undefined && news.alias === previousAlias,
        };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, output, previous }) {
      const existing = yield* observe({
        id: output?.id,
        logicalId: id,
        alias: output?.alias,
      });
      if (existing === undefined) return undefined;
      // A create-first replacement finds the list it is replacing under the
      // same logical id: that is not the replacement.
      if (output === undefined && existing.id === previous?.id) return undefined;
      const attrs = toAttrs(existing);
      return (yield* hasAlchemyMetadata(id, tagRecord(existing.metadata))) ? attrs : Unowned(attrs);
    }),

    list: Effect.fn(function* () {
      const lists = yield* listAllValueLists();
      return lists
        .filter((list) => {
          const metadata = tagRecord(list.metadata);
          return metadata[alchemyMetadataKeys.stack] !== undefined;
        })
        .map(toAttrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const alias = yield* toAlias(id, news.alias, output?.alias);
      const name = yield* toName(id, news.name, output?.name);
      const metadata = yield* desiredMetadata(id, news.metadata);
      const itemType = news.itemType ?? output?.itemType ?? "string";

      let current: StripeRadarValueList | undefined = yield* observe({
        id: output?.id,
        logicalId: id,
        alias,
      });
      if (current !== undefined && shouldReplace(news, toAttrs(current))) {
        current = undefined;
      }

      if (current === undefined) {
        current = yield* CreateRadarValueList({
          alias,
          name,
          item_type: itemType,
          metadata,
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-radar-value-list-${instanceId}`,
          }),
        );
      }

      if (current === undefined) {
        return yield* new RadarValueListNotResolved({ alias });
      }

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

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

      const updated = yield* UpdateRadarValueList({
        value_list: current.id,
        ...(nameChanged ? { name } : {}),
        ...(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 }) {
      yield* DeleteRadarValueList({ value_list: output.id }).pipe(
        Effect.catchIf(isMissingValueList, () => Effect.void),
      );
    }),
  });