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

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  DeleteTerminalReader,
  GetTerminalReaders,
  GetTerminalReader,
  CreateTerminalReader,
  UpdateTerminalReader,
  type DeletedTerminalReader,
  type TerminalReader as StripeTerminalReader,
  type TerminalReaderDeviceType,
  type TerminalReaderLocation,
  type TerminalReaderStatus,
} from "@distilled.cloud/stripe/stripe";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
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";

export type { TerminalReaderDeviceType, TerminalReaderStatus };

const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;

export interface TerminalReaderProps {
  /**
   * Pairing code generated by the reader (or a simulated-reader code in
   * test mode such as `"simulated-wpe"`, `"simulated-s700"`, or
   * `"simulated-s710"`). Create-only — used when the reader is missing;
   * changing it on an existing reader is ignored.
   */
  registrationCode: string;
  /**
   * Custom label for easier identification. If omitted on create, Stripe
   * uses the registration code. Mutable.
   */
  label?: string;
  /**
   * Id of the Terminal Location to assign the reader to (`tml_…`).
   * Create-only — changing it replaces the reader. Simulated readers
   * typically require a location.
   */
  location?: 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 TerminalReader = Resource<
  "Stripe.TerminalReader",
  TerminalReaderProps,
  {
    /** Stripe Terminal reader id (`tmr_…`). */
    id: string;
    /** Custom label for easier identification. */
    label: string;
    /** Assigned Terminal Location id (`tml_…`), if any. */
    location: string | undefined;
    /** Device type of the reader (e.g. `simulated_wisepos_e`). */
    deviceType: TerminalReaderDeviceType;
    /** Serial number of the reader. */
    serialNumber: string;
    /** Networking status, if reported. */
    status: TerminalReaderStatus | undefined;
    /** Local IP address of the reader, if known. */
    ipAddress: string | undefined;
    /** Current software version of the reader, if known. */
    deviceSwVersion: string | undefined;
    /**
     * Last time this reader reported to Stripe, in milliseconds since the
     * Unix epoch.
     */
    lastSeenAt: number | undefined;
    /** User-defined metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
    /** Whether the reader exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Terminal Reader — a physical or simulated card reader that
 * accepts in-person payments. `registrationCode` and `location` are
 * create-only; changing `location` replaces the reader. `label` and
 * `metadata` update in place. Destroy deletes the reader.
 *
 * In test mode, register a simulated WisePOS E with
 * `registrationCode: "simulated-wpe"` (or `"simulated-s700"` /
 * `"simulated-s710"`). Simulated readers typically need a Terminal
 * Location.
 *
 * @see https://docs.stripe.com/api/terminal/readers
 *
 * ### Creating a Reader
 * **Example:** Simulated WisePOS E
 * ```typescript
 * const reader = yield* Stripe.TerminalReader("front-counter", {
 *   registrationCode: "simulated-wpe",
 *   label: "Front counter",
 *   location: locationId,
 * });
 * ```
 *
 * **Example:** Physical reader with metadata
 * ```typescript
 * const reader = yield* Stripe.TerminalReader("pos-1", {
 *   registrationCode: pairingCode,
 *   label: "POS 1",
 *   location: location.id,
 *   metadata: { station: "1" },
 * });
 * ```
 *
 * ### Updating a Reader
 * **Example:** Relabel and retag
 * ```typescript
 * const reader = yield* Stripe.TerminalReader("front-counter", {
 *   registrationCode: "simulated-wpe",
 *   label: "Front counter (updated)",
 *   location: locationId,
 *   metadata: { station: "1", floor: "lobby" },
 * });
 * ```
 *
 * ### Deleting a Reader
 * **Example:** Destroy deletes the reader
 * ```typescript
 * const reader = yield* Stripe.TerminalReader("front-counter", {
 *   registrationCode: "simulated-wpe",
 *   location: locationId,
 * });
 * // stack.destroy() deletes the reader
 * ```
 *
 * @resource
 * @product Terminal
 */
export const TerminalReader = Resource<TerminalReader>("Stripe.TerminalReader");

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

type TerminalReaderAttributes = TerminalReader["Attributes"];

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

const isDeletedReader = (
  value: StripeTerminalReader | DeletedTerminalReader,
): value is DeletedTerminalReader => "deleted" in value && value.deleted === true;

const asReader = (
  value: StripeTerminalReader | DeletedTerminalReader | undefined,
): StripeTerminalReader | undefined => {
  if (value === undefined || isDeletedReader(value)) return undefined;
  return value;
};

const locationIdOf = (location: TerminalReaderLocation | null | undefined): string | undefined => {
  if (location == null) return undefined;
  if (typeof location === "string") return location;
  return location.id;
};

const toAttrs = (reader: StripeTerminalReader): TerminalReaderAttributes => ({
  id: reader.id,
  label: reader.label,
  location: locationIdOf(reader.location),
  deviceType: reader.device_type,
  serialNumber: reader.serial_number,
  status: reader.status ?? undefined,
  ipAddress: reader.ip_address ?? undefined,
  deviceSwVersion: reader.device_sw_version ?? undefined,
  lastSeenAt: reader.last_seen_at ?? undefined,
  metadata: userMetadata(reader.metadata),
  livemode: reader.livemode,
});

const isMissingReader = isMissingStripeResource;

const getById = (reader: string) =>
  GetTerminalReader({ reader }).pipe(
    Effect.map(asReader),
    Effect.catchIf(isMissingReader, () => Effect.undefined),
  );

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

const findByAlchemyId = Effect.fn(function* (id: string) {
  const readers = yield* listAllReaders();
  const matches: StripeTerminalReader[] = [];
  for (const reader of readers) {
    if (yield* hasAlchemyMetadata(id, tagRecord(reader.metadata))) {
      matches.push(reader);
    }
  }
  matches.sort((a, b) => (b.last_seen_at ?? 0) - (a.last_seen_at ?? 0));
  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: TerminalReaderProps,
  output: TerminalReaderAttributes | undefined,
): boolean => {
  if (output === undefined) return false;
  if (news.location !== undefined && news.location !== (output.location ?? undefined)) {
    return true;
  }
  return false;
};

export const TerminalReaderProvider = () =>
  Provider.succeed(TerminalReader, {
    stables: ["id", "deviceType", "serialNumber", "location", "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 readers = yield* listAllReaders();
      return readers
        .filter((reader) => {
          const metadata = tagRecord(reader.metadata);
          return metadata[alchemyMetadataKeys.stack] !== undefined;
        })
        .map(toAttrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const metadata = yield* desiredMetadata(id, news.metadata);

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

      if (current === undefined) {
        current = yield* CreateTerminalReader({
          registration_code: news.registrationCode,
          metadata,
          ...(news.label !== undefined ? { label: news.label } : {}),
          ...(news.location !== undefined ? { location: news.location } : {}),
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-terminal-reader-${instanceId}`,
          }),
        );
      }

      if (current === undefined) {
        return yield* new TerminalReaderNotResolved({
          reader: output?.id ?? news.registrationCode,
        });
      }

      const observedMetadata = tagRecord(current.metadata);
      const { upsert, removed } = diffMetadata(observedMetadata, metadata);
      const metadataChanged = upsert.length > 0 || removed.length > 0;
      const labelChanged = news.label !== undefined && current.label !== news.label;

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

      const updated = yield* UpdateTerminalReader({
        reader: current.id,
        ...(labelChanged ? { label: news.label } : {}),
        ...(metadataChanged
          ? {
              metadata: {
                ...Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value])),
                ...Object.fromEntries(removed.map((key) => [key, ""])),
              },
            }
          : {}),
      });
      const reader = asReader(updated);
      if (reader === undefined) {
        return yield* new TerminalReaderNotResolved({ reader: current.id });
      }
      return toAttrs(reader);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* DeleteTerminalReader({ reader: output.id }).pipe(
        Effect.catchIf(isMissingReader, () => Effect.void),
      );
    }),
  });