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

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  DeleteTerminalLocation,
  GetTerminalLocations,
  GetTerminalLocation,
  CreateTerminalLocation,
  UpdateTerminalLocation,
  type Address,
  type DeletedTerminalLocation,
  type LegalEntityJapanAddress,
  type CreateAccountRequestCompanyAddressKana,
  type CreateTerminalLocationRequestAddress,
  type TerminalLocation as StripeTerminalLocation,
} from "@distilled.cloud/stripe/stripe";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, 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 = 1000;
const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;

export interface TerminalLocationAddress {
  /**
   * City, district, suburb, town, or village. Required in most countries.
   */
  city?: string;
  /**
   * Two-letter ISO 3166-1 alpha-2 country code. Create-only — changing
   * it replaces the location.
   */
  country: string;
  /**
   * Address line 1 (street, PO Box, or company name).
   */
  line1?: string;
  /**
   * Address line 2 (apartment, suite, unit, or building).
   */
  line2?: string;
  /**
   * ZIP or postal code. Required in most countries.
   */
  postalCode?: string;
  /**
   * State, county, province, or region (ISO 3166-2). Required in the US
   * and Canada.
   */
  state?: string;
}

export interface TerminalLocationJapanAddress {
  /**
   * City or ward.
   */
  city?: string;
  /**
   * Two-letter ISO 3166-1 alpha-2 country code.
   */
  country?: string;
  /**
   * Block or building number.
   */
  line1?: string;
  /**
   * Building details.
   */
  line2?: string;
  /**
   * Postal code.
   */
  postalCode?: string;
  /**
   * Prefecture.
   */
  state?: string;
  /**
   * Town or cho-me.
   */
  town?: string;
}

export interface TerminalLocationProps {
  /**
   * Display name of the location. If omitted, a unique name is generated
   * from the stack, stage, and logical id. Maximum length is 1000
   * characters. Mutable.
   */
  displayName?: string;
  /**
   * Full address of the location. `country` is required and create-only —
   * changing it replaces the location. Other fields update in place;
   * required fields vary by country.
   */
  address: TerminalLocationAddress;
  /**
   * Kana variation of the full address (Japan only). Mutable.
   */
  addressKana?: TerminalLocationJapanAddress;
  /**
   * Kanji variation of the full address (Japan only). Mutable.
   */
  addressKanji?: TerminalLocationJapanAddress;
  /**
   * Id of a Terminal Configuration applied to every reader at this
   * location. Empty string unsets. Mutable.
   */
  configurationOverrides?: string;
  /**
   * Kana variation of the display name (Japan only). Mutable.
   */
  displayNameKana?: string;
  /**
   * Kanji variation of the display name (Japan only). Mutable.
   */
  displayNameKanji?: string;
  /**
   * Phone number for the location. Empty string unsets. Mutable.
   */
  phone?: string;
  /**
   * 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 TerminalLocation = Resource<
  "Stripe.TerminalLocation",
  TerminalLocationProps,
  {
    /** Stripe Terminal Location id (`tml_…`). */
    id: string;
    /** Display name of the location. */
    displayName: string;
    /** Full address of the location. */
    address: TerminalLocationAddress;
    /** Kana variation of the full address, if set. */
    addressKana: TerminalLocationJapanAddress | undefined;
    /** Kanji variation of the full address, if set. */
    addressKanji: TerminalLocationJapanAddress | undefined;
    /** Terminal Configuration id applied to readers at this location. */
    configurationOverrides: string | undefined;
    /** Kana variation of the display name, if set. */
    displayNameKana: string | undefined;
    /** Kanji variation of the display name, if set. */
    displayNameKanji: string | undefined;
    /** Phone number for the location, if set. */
    phone: string | undefined;
    /** User-defined metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
    /** Whether the location exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Terminal Location — a grouping of Terminal readers at a
 * physical site. Display name, phone, metadata, configuration overrides,
 * and address fields other than `country` update in place. Changing
 * `address.country` replaces the location; re-register readers on the
 * new one.
 *
 * Destroy hard-deletes the location.
 *
 * @see https://docs.stripe.com/api/terminal/locations
 *
 * ### Creating a Location
 * **Example:** US storefront
 * ```typescript
 * const store = yield* Stripe.TerminalLocation("storefront", {
 *   displayName: "Market Street",
 *   address: {
 *     line1: "123 Market Street",
 *     city: "San Francisco",
 *     state: "CA",
 *     postalCode: "94105",
 *     country: "US",
 *   },
 * });
 * ```
 *
 * **Example:** Generated name with phone and metadata
 * ```typescript
 * const kiosk = yield* Stripe.TerminalLocation("kiosk", {
 *   address: {
 *     line1: "1 Infinite Loop",
 *     city: "Cupertino",
 *     state: "CA",
 *     postalCode: "95014",
 *     country: "US",
 *   },
 *   phone: "+14085551234",
 *   metadata: { region: "west" },
 * });
 * ```
 *
 * ### Updating a Location
 * **Example:** Rename and retag
 * ```typescript
 * const store = yield* Stripe.TerminalLocation("storefront", {
 *   displayName: "Market Street Annex",
 *   address: {
 *     line1: "125 Market Street",
 *     city: "San Francisco",
 *     state: "CA",
 *     postalCode: "94105",
 *     country: "US",
 *   },
 *   metadata: { region: "west" },
 * });
 * ```
 *
 * ### Deleting a Location
 * **Example:** Destroy deletes the location
 * ```typescript
 * // stack.destroy() / resource removal calls DELETE
 * const store = yield* Stripe.TerminalLocation("storefront", {
 *   address: {
 *     line1: "123 Market Street",
 *     city: "San Francisco",
 *     state: "CA",
 *     postalCode: "94105",
 *     country: "US",
 *   },
 * });
 * ```
 *
 * @resource
 * @product Terminal
 */
export const TerminalLocation = Resource<TerminalLocation>("Stripe.TerminalLocation");

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

type TerminalLocationAttributes = TerminalLocation["Attributes"];

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

const optionalString = (value: string | null | undefined): string | undefined =>
  value == null || value === "" ? undefined : value;

const fromObservedAddress = (address: Address): TerminalLocationAddress => ({
  country: address.country ?? "",
  ...(optionalString(address.city) !== undefined ? { city: optionalString(address.city) } : {}),
  ...(optionalString(address.line1) !== undefined ? { line1: optionalString(address.line1) } : {}),
  ...(optionalString(address.line2) !== undefined ? { line2: optionalString(address.line2) } : {}),
  ...(optionalString(address.postal_code) !== undefined
    ? { postalCode: optionalString(address.postal_code) }
    : {}),
  ...(optionalString(address.state) !== undefined ? { state: optionalString(address.state) } : {}),
});

const fromObservedJapanAddress = (
  address: LegalEntityJapanAddress | undefined,
): TerminalLocationJapanAddress | undefined => {
  if (address === undefined) return undefined;
  const mapped: TerminalLocationJapanAddress = {
    ...(optionalString(address.city) !== undefined ? { city: optionalString(address.city) } : {}),
    ...(optionalString(address.country) !== undefined
      ? { country: optionalString(address.country) }
      : {}),
    ...(optionalString(address.line1) !== undefined
      ? { line1: optionalString(address.line1) }
      : {}),
    ...(optionalString(address.line2) !== undefined
      ? { line2: optionalString(address.line2) }
      : {}),
    ...(optionalString(address.postal_code) !== undefined
      ? { postalCode: optionalString(address.postal_code) }
      : {}),
    ...(optionalString(address.state) !== undefined
      ? { state: optionalString(address.state) }
      : {}),
    ...(optionalString(address.town) !== undefined ? { town: optionalString(address.town) } : {}),
  };
  return Object.keys(mapped).length > 0 ? mapped : undefined;
};

const toWireAddress = (address: TerminalLocationAddress): CreateTerminalLocationRequestAddress => ({
  country: address.country,
  ...(address.city !== undefined ? { city: address.city } : {}),
  ...(address.line1 !== undefined ? { line1: address.line1 } : {}),
  ...(address.line2 !== undefined ? { line2: address.line2 } : {}),
  ...(address.postalCode !== undefined ? { postal_code: address.postalCode } : {}),
  ...(address.state !== undefined ? { state: address.state } : {}),
});

const toWireJapanAddress = (
  address: TerminalLocationJapanAddress,
): CreateAccountRequestCompanyAddressKana => ({
  ...(address.city !== undefined ? { city: address.city } : {}),
  ...(address.country !== undefined ? { country: address.country } : {}),
  ...(address.line1 !== undefined ? { line1: address.line1 } : {}),
  ...(address.line2 !== undefined ? { line2: address.line2 } : {}),
  ...(address.postalCode !== undefined ? { postal_code: address.postalCode } : {}),
  ...(address.state !== undefined ? { state: address.state } : {}),
  ...(address.town !== undefined ? { town: address.town } : {}),
});

const isDeletedLocation = (
  value: StripeTerminalLocation | DeletedTerminalLocation,
): value is DeletedTerminalLocation => "deleted" in value && value.deleted === true;

const asLocation = (
  value: StripeTerminalLocation | DeletedTerminalLocation | undefined,
): StripeTerminalLocation | undefined => {
  if (value === undefined || isDeletedLocation(value)) return undefined;
  return value;
};

const toAttrs = (location: StripeTerminalLocation): TerminalLocationAttributes => ({
  id: location.id,
  displayName: location.display_name,
  address: fromObservedAddress(location.address),
  addressKana: fromObservedJapanAddress(location.address_kana),
  addressKanji: fromObservedJapanAddress(location.address_kanji),
  configurationOverrides: optionalString(location.configuration_overrides),
  displayNameKana: optionalString(location.display_name_kana),
  displayNameKanji: optionalString(location.display_name_kanji),
  phone: optionalString(location.phone),
  metadata: userMetadata(location.metadata),
  livemode: location.livemode,
});

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

const isMissingLocation = isMissingStripeResource;

const getById = (location: string) =>
  GetTerminalLocation({ location }).pipe(
    Effect.map(asLocation),
    Effect.catchIf(isMissingLocation, () => Effect.undefined),
  );

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

const findByAlchemyId = Effect.fn(function* (id: string) {
  const locations = yield* listAllLocations();
  const matches: StripeTerminalLocation[] = [];
  for (const location of locations) {
    if (yield* hasAlchemyMetadata(id, tagRecord(location.metadata))) {
      matches.push(location);
    }
  }
  return matches[0];
});

const observe = Effect.fn(function* (input: { id?: string; logicalId: string }) {
  if (input.id !== undefined) {
    const byId = yield* getById(input.id);
    if (byId !== undefined) return byId;
  }
  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: TerminalLocationProps,
  output: TerminalLocationAttributes | undefined,
): boolean => {
  if (output === undefined) return false;
  return news.address.country !== output.address.country;
};

export const TerminalLocationProvider = () =>
  Provider.succeed(TerminalLocation, {
    stables: ["id", "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,
      });
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing);
      return (yield* hasAlchemyMetadata(id, tagRecord(existing.metadata))) ? attrs : Unowned(attrs);
    }),

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

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const displayName = yield* toDisplayName(id, news.displayName, output?.displayName);
      const metadata = yield* desiredMetadata(id, news.metadata);
      const desiredPhone = news.phone ?? "";
      const desiredConfig = news.configurationOverrides ?? "";
      const desiredDisplayNameKana = news.displayNameKana ?? "";
      const desiredDisplayNameKanji = news.displayNameKanji ?? "";
      const address = toWireAddress(news.address);

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

      if (current === undefined) {
        current = yield* CreateTerminalLocation({
          display_name: displayName,
          address,
          metadata,
          ...(news.addressKana !== undefined
            ? { address_kana: toWireJapanAddress(news.addressKana) }
            : {}),
          ...(news.addressKanji !== undefined
            ? { address_kanji: toWireJapanAddress(news.addressKanji) }
            : {}),
          ...(desiredConfig.length > 0 ? { configuration_overrides: desiredConfig } : {}),
          ...(desiredDisplayNameKana.length > 0
            ? { display_name_kana: desiredDisplayNameKana }
            : {}),
          ...(desiredDisplayNameKanji.length > 0
            ? { display_name_kanji: desiredDisplayNameKanji }
            : {}),
          ...(desiredPhone.length > 0 ? { phone: desiredPhone } : {}),
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-terminal-location-${instanceId}`,
          }),
        );
      }

      if (current === undefined) {
        return yield* new TerminalLocationNotResolved({ displayName });
      }

      const observedMetadata = tagRecord(current.metadata);
      const { upsert, removed } = diffMetadata(observedMetadata, metadata);
      const metadataChanged = upsert.length > 0 || removed.length > 0;
      const displayNameChanged = current.display_name !== displayName;
      const addressChanged = !deepEqual(fromObservedAddress(current.address), news.address, {
        stripNullish: true,
      });
      const addressKanaChanged =
        news.addressKana !== undefined &&
        !deepEqual(fromObservedJapanAddress(current.address_kana), news.addressKana, {
          stripNullish: true,
        });
      const addressKanjiChanged =
        news.addressKanji !== undefined &&
        !deepEqual(fromObservedJapanAddress(current.address_kanji), news.addressKanji, {
          stripNullish: true,
        });
      const phoneChanged = (current.phone ?? "") !== desiredPhone;
      const configChanged = (current.configuration_overrides ?? "") !== desiredConfig;
      const displayNameKanaChanged = (current.display_name_kana ?? "") !== desiredDisplayNameKana;
      const displayNameKanjiChanged =
        (current.display_name_kanji ?? "") !== desiredDisplayNameKanji;

      if (
        !displayNameChanged &&
        !addressChanged &&
        !addressKanaChanged &&
        !addressKanjiChanged &&
        !phoneChanged &&
        !configChanged &&
        !displayNameKanaChanged &&
        !displayNameKanjiChanged &&
        !metadataChanged
      ) {
        return toAttrs(current);
      }

      const updated = yield* UpdateTerminalLocation({
        location: current.id,
        ...(displayNameChanged ? { display_name: displayName } : {}),
        ...(addressChanged ? { address } : {}),
        ...(addressKanaChanged && news.addressKana !== undefined
          ? { address_kana: toWireJapanAddress(news.addressKana) }
          : {}),
        ...(addressKanjiChanged && news.addressKanji !== undefined
          ? { address_kanji: toWireJapanAddress(news.addressKanji) }
          : {}),
        ...(configChanged ? { configuration_overrides: desiredConfig } : {}),
        ...(displayNameKanaChanged ? { display_name_kana: desiredDisplayNameKana } : {}),
        ...(displayNameKanjiChanged ? { display_name_kanji: desiredDisplayNameKanji } : {}),
        ...(phoneChanged ? { phone: desiredPhone } : {}),
        ...(metadataChanged
          ? {
              metadata: {
                ...Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value])),
                ...Object.fromEntries(removed.map((key) => [key, ""])),
              },
            }
          : {}),
      });
      const location = asLocation(updated);
      if (location === undefined) {
        return yield* new TerminalLocationNotResolved({ displayName });
      }
      return toAttrs(location);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* DeleteTerminalLocation({ location: output.id }).pipe(
        Effect.catchIf(isMissingLocation, () => Effect.void),
      );
    }),
  });