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),
);
}),
});