shopstack 0.1.0 → 0.2.1

package/src/client.d.ts

@@ -0,0 +1,220 @@
+export interface ShopstackClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+
+export interface PaymentCard {
+  number: string;
+  exp_month: number;
+  exp_year: number;
+  cvc: string;
+}
+
+export interface PaymentApproval {
+  id: string;
+  subtotal: string | null;
+  shipping: string | null;
+  tax: string | null;
+  total: string;
+  currency: string;
+  expires_at: string;
+}
+
+export interface Checkout {
+  id: string;
+  status:
+    | "queued"
+    | "started"
+    | "help_required"
+    | "approval_required"
+    | "submitting"
+    | "complete"
+    | "failed"
+    | "cancelled";
+  revision: number;
+  activity: string;
+  intent?: {
+    name: string;
+    phase: "selected" | "completed" | "uncertain" | "failed";
+    updated_at: string;
+  };
+  item_url: string;
+  required_input?: { type: "payment_card" };
+  approval?: PaymentApproval;
+  result?: Record<string, unknown>;
+  failure?: Record<string, unknown>;
+  created_at: string;
+  updated_at: string;
+  expires_at: string;
+}
+
+export interface RunCheckoutOptions {
+  idempotencyKey?: string;
+  pollIntervalMs?: number;
+  timeoutMs?: number;
+  onProgress?(checkout: Checkout): void | Promise<void>;
+  paymentDetails?(
+    checkout: Checkout,
+  ): PaymentCard | Promise<PaymentCard | undefined> | undefined;
+  approve?(
+    approval: PaymentApproval,
+    checkout: Checkout,
+  ): boolean | Promise<boolean | undefined> | undefined;
+  message?(
+    checkout: Checkout,
+  ): string | Promise<string | undefined> | undefined;
+}
+
+export interface AccountSignupStarted {
+  id: string;
+  account_type: "personal" | "developer";
+  email: string;
+  status: "verification_required";
+  created_at: string;
+  expires_at: string;
+  poll_token: string;
+}
+
+export interface VerifiedAccountSignup {
+  id: string;
+  status: "verified";
+  verified_at: string;
+  account: Record<string, unknown>;
+  api_key: string;
+  key_type: "user" | "developer";
+  user?: Record<string, unknown>;
+}
+
+export interface SignupOptions {
+  accountType: "personal" | "developer";
+  email: string;
+  pollIntervalMs?: number;
+  timeoutMs?: number;
+  persistence?: SignupPersistence;
+  onProgress?(progress: SignupProgress): void | Promise<void>;
+  onVerificationRequired?(signup: Omit<AccountSignupStarted, "poll_token">):
+    | void
+    | Promise<void>;
+}
+
+export interface PendingSignupState {
+  accountType: "personal" | "developer";
+  attemptId: string;
+  email: string;
+  expiresAt?: string;
+  idempotencyKey: string;
+  pollToken?: string;
+  recoveryKey: string;
+  signupId?: string;
+}
+
+export interface SignupPersistence {
+  loadPending(input: {
+    accountType: "personal" | "developer";
+    email: string;
+  }): Promise<PendingSignupState | undefined>;
+  savePending(state: PendingSignupState): Promise<void>;
+  completePending(
+    state: PendingSignupState,
+    result: VerifiedAccountSignup,
+  ): Promise<void>;
+  deletePending(state: PendingSignupState): Promise<void>;
+}
+
+export interface SignupProgress {
+  state:
+    | "pending"
+    | "email_sent"
+    | "waiting"
+    | "verified"
+    | "expired"
+    | "rate_limited"
+    | "conflict"
+    | "retryable_failure"
+    | "complete";
+  account_type?: "personal" | "developer";
+  email?: string;
+  expires_at?: string;
+  key_type?: "user" | "developer";
+}
+
+export type CompletedAccountSignup = Omit<VerifiedAccountSignup, "api_key">;
+
+export class ShopstackApiError extends Error {
+  code: string;
+  requestId?: string;
+  status?: number;
+}
+
+export class ShopstackClient {
+  constructor(options?: ShopstackClientOptions);
+  startAccountSignup(input: {
+    accountType: "personal" | "developer";
+    email: string;
+  }): Promise<AccountSignupStarted>;
+  pollAccountSignup(
+    signupId: string,
+    pollToken: string,
+  ): Promise<
+    Omit<AccountSignupStarted, "poll_token"> | VerifiedAccountSignup
+  >;
+  waitForAccountSignup(
+    signupId: string,
+    pollToken: string,
+    options?: { pollIntervalMs?: number; timeoutMs?: number },
+  ): Promise<VerifiedAccountSignup>;
+  signup(input: SignupOptions): Promise<CompletedAccountSignup>;
+  createUser(input: {
+    externalId: string;
+    idempotencyKey?: string;
+  }): Promise<Record<string, unknown>>;
+  listUsers(): Promise<Record<string, unknown>>;
+  getUser(userId: string): Promise<Record<string, unknown>>;
+  rotateUserApiKey(
+    userId: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<Record<string, unknown>>;
+  updateUser(
+    userId: string,
+    status: "active" | "suspended",
+    options?: { idempotencyKey?: string },
+  ): Promise<Record<string, unknown>>;
+  listConnections(): Promise<Record<string, unknown>>;
+  connect(
+    paymentProvider?: "link",
+    options?: { idempotencyKey?: string },
+  ): Promise<Record<string, unknown>>;
+  createCheckout(
+    checkout: Record<string, unknown>,
+    options?: { idempotencyKey?: string },
+  ): Promise<Checkout>;
+  getCheckout(checkoutId: string): Promise<Checkout>;
+  cancelCheckout(
+    checkoutId: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<Checkout>;
+  sendMessage(
+    checkoutId: string,
+    content: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<Record<string, unknown>>;
+  listMessages(checkoutId: string): Promise<Record<string, unknown>>;
+  listEvents(checkoutId: string): Promise<Record<string, unknown>>;
+  listArtifacts(checkoutId: string): Promise<Record<string, unknown>>;
+  providePaymentDetails(
+    checkoutId: string,
+    card: PaymentCard,
+    options?: { idempotencyKey?: string },
+  ): Promise<Checkout>;
+  decidePaymentApproval(
+    checkoutId: string,
+    approvalId: string,
+    approved: boolean,
+    options?: { idempotencyKey?: string },
+  ): Promise<Checkout>;
+  runCheckout(
+    checkout: Record<string, unknown>,
+    options?: RunCheckoutOptions,
+  ): Promise<Checkout>;
+}

package/src/client.js

@@ -0,0 +1,486 @@
+import { randomBytes, randomUUID } from "node:crypto";
+
+const TERMINAL_STATUSES = new Set(["complete", "failed", "cancelled"]);
+
+export class ShopstackApiError extends Error {
+  constructor(message, { code = "api_error", requestId, status } = {}) {
+    super(message);
+    this.name = "ShopstackApiError";
+    this.code = code;
+    this.requestId = requestId;
+    this.status = status;
+  }
+}
+
+function idempotencyKey(prefix) {
+  return `${prefix}-${randomUUID()}`;
+}
+
+function signupRecoveryKey() {
+  return `signup_recovery_${randomBytes(32).toString("base64url")}`;
+}
+
+function signupAttemptKey(accountType, email) {
+  return `${accountType}\u0000${email.trim().toLowerCase()}`;
+}
+
+function delay(milliseconds) {
+  return milliseconds <= 0
+    ? Promise.resolve()
+    : new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+export class ShopstackClient {
+  constructor({
+    apiKey,
+    baseUrl = "https://shopstack-staging.shopstack.workers.dev/v1",
+    fetch: fetchImplementation = globalThis.fetch,
+  } = {}) {
+    if (typeof baseUrl !== "string" || !/^https?:\/\//u.test(baseUrl)) {
+      throw new TypeError("baseUrl must be an HTTP(S) URL");
+    }
+    if (typeof fetchImplementation !== "function") {
+      throw new TypeError("a fetch implementation is required");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/u, "");
+    this.fetch = fetchImplementation;
+  }
+
+  async request(
+    path,
+    {
+      bearerToken,
+      body,
+      idempotencyKey: mutationKey,
+      method = "GET",
+      signupRecoveryKey: recoveryKey,
+    } = {},
+  ) {
+    const headers = new Headers({ Accept: "application/json" });
+    const authorization = bearerToken ?? this.apiKey;
+    if (authorization) {
+      headers.set("Authorization", `Bearer ${authorization}`);
+    }
+    if (body !== undefined) headers.set("Content-Type", "application/json");
+    if (mutationKey) headers.set("Idempotency-Key", mutationKey);
+    if (recoveryKey) headers.set("Signup-Recovery-Key", recoveryKey);
+    const response = await this.fetch(`${this.baseUrl}${path}`, {
+      body: body === undefined ? undefined : JSON.stringify(body),
+      headers,
+      method,
+    });
+    const raw = await response.text();
+    let payload;
+    try {
+      payload = raw ? JSON.parse(raw) : undefined;
+    } catch {
+      throw new ShopstackApiError("Shopstack returned invalid JSON.", {
+        status: response.status,
+      });
+    }
+    if (!response.ok) {
+      const error = payload?.error;
+      throw new ShopstackApiError(
+        typeof error?.message === "string"
+          ? error.message
+          : `Shopstack request failed with status ${response.status}.`,
+        {
+          code: typeof error?.code === "string" ? error.code : "api_error",
+          requestId:
+            typeof error?.request_id === "string"
+              ? error.request_id
+              : undefined,
+          status: response.status,
+        },
+      );
+    }
+    return payload;
+  }
+
+  _startAccountSignup({ accountType, email, idempotencyKey: key, recoveryKey }) {
+    return this.request("/accounts", {
+      body: { account_type: accountType, email },
+      idempotencyKey: key,
+      method: "POST",
+      signupRecoveryKey: recoveryKey,
+    });
+  }
+
+  startAccountSignup({ accountType, email } = {}) {
+    return this._startAccountSignup({
+      accountType,
+      email,
+      idempotencyKey: idempotencyKey("account"),
+      recoveryKey: signupRecoveryKey(),
+    });
+  }
+
+  pollAccountSignup(signupId, pollToken) {
+    return this.request(`/accounts/${encodeURIComponent(signupId)}`, {
+      bearerToken: pollToken,
+    });
+  }
+
+  async waitForAccountSignup(
+    signupId,
+    pollToken,
+    { pollIntervalMs = 2_000, timeoutMs = 15 * 60 * 1_000 } = {},
+  ) {
+    const startedAt = Date.now();
+    while (true) {
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new ShopstackApiError("Email verification timed out.", {
+          code: "signup_timeout",
+        });
+      }
+      const current = await this.pollAccountSignup(signupId, pollToken);
+      if (current.status === "verified") return current;
+      await delay(pollIntervalMs);
+    }
+  }
+
+  async signup({
+    accountType,
+    email,
+    onProgress,
+    onVerificationRequired,
+    persistence,
+    pollIntervalMs = 2_000,
+    timeoutMs = 15 * 60 * 1_000,
+  } = {}) {
+    const normalizedEmail = email.trim().toLowerCase();
+    const memoryKey = signupAttemptKey(accountType, normalizedEmail);
+    this._pendingSignups ??= new Map();
+    const storage = persistence ?? {
+      completePending: async (state, result) => {
+        this.apiKey = result.api_key;
+        this._pendingSignups.delete(memoryKey);
+      },
+      deletePending: async () => this._pendingSignups.delete(memoryKey),
+      loadPending: async () => this._pendingSignups.get(memoryKey),
+      savePending: async (state) => {
+        this._pendingSignups.set(memoryKey, structuredClone(state));
+      },
+    };
+    const publish = async (state, details = {}) => {
+      if (typeof onProgress === "function") await onProgress({ state, ...details });
+    };
+    let pending = await storage.loadPending({
+      accountType,
+      email: normalizedEmail,
+    });
+    if (
+      pending?.expiresAt &&
+      Date.parse(pending.expiresAt) <= Date.now()
+    ) {
+      await storage.deletePending(pending);
+      await publish("expired", {
+        account_type: accountType,
+        email: normalizedEmail,
+      });
+      pending = undefined;
+    }
+    pending ??= {
+      accountType,
+      attemptId: `attempt-${randomUUID()}`,
+      email: normalizedEmail,
+      idempotencyKey: idempotencyKey("account"),
+      recoveryKey: signupRecoveryKey(),
+    };
+    await storage.savePending(pending);
+    await publish("pending", {
+      account_type: accountType,
+      email: normalizedEmail,
+    });
+    try {
+      if (!pending.signupId || !pending.pollToken) {
+        const started = await this._startAccountSignup({
+          accountType,
+          email: normalizedEmail,
+          idempotencyKey: pending.idempotencyKey,
+          recoveryKey: pending.recoveryKey,
+        });
+        pending = {
+          ...pending,
+          expiresAt: started.expires_at,
+          pollToken: started.poll_token,
+          signupId: started.id,
+        };
+        await storage.savePending(pending);
+        if (typeof onVerificationRequired === "function") {
+          await onVerificationRequired({
+            account_type: started.account_type,
+            email: started.email,
+            expires_at: started.expires_at,
+            id: started.id,
+            status: started.status,
+          });
+        }
+        await publish("email_sent", {
+          account_type: accountType,
+          email: normalizedEmail,
+          expires_at: started.expires_at,
+        });
+      }
+      await publish("waiting", {
+        account_type: accountType,
+        email: normalizedEmail,
+        expires_at: pending.expiresAt,
+      });
+      const result = await this.waitForAccountSignup(
+        pending.signupId,
+        pending.pollToken,
+        { pollIntervalMs, timeoutMs },
+      );
+      await storage.completePending(pending, result);
+      await publish("verified", {
+        account_type: accountType,
+        email: normalizedEmail,
+      });
+      await publish("complete", {
+        account_type: accountType,
+        email: normalizedEmail,
+        key_type: result.key_type,
+      });
+      const { api_key: _credential, ...completed } = result;
+      return completed;
+    } catch (error) {
+      if (error?.code === "signup_expired") {
+        await storage.deletePending(pending);
+        await publish("expired", {
+          account_type: accountType,
+          email: normalizedEmail,
+        });
+      } else if (error?.code === "rate_limited") {
+        await publish("rate_limited", {
+          account_type: accountType,
+          email: normalizedEmail,
+        });
+      } else if (
+        error?.code === "idempotency_conflict" ||
+        error?.code === "invalid_signup_recovery"
+      ) {
+        await storage.deletePending(pending);
+        await publish("conflict", {
+          account_type: accountType,
+          email: normalizedEmail,
+        });
+      } else {
+        await publish("retryable_failure", {
+          account_type: accountType,
+          email: normalizedEmail,
+        });
+      }
+      throw error;
+    }
+  }
+
+  createUser({ externalId, idempotencyKey: key } = {}) {
+    return this.request("/users", {
+      body: { external_id: externalId },
+      idempotencyKey: key ?? idempotencyKey("user"),
+      method: "POST",
+    });
+  }
+
+  listUsers() {
+    return this.request("/users");
+  }
+
+  getUser(userId) {
+    return this.request(`/users/${encodeURIComponent(userId)}`);
+  }
+
+  rotateUserApiKey(userId, { idempotencyKey: key } = {}) {
+    return this.request(`/users/${encodeURIComponent(userId)}/api-key/rotate`, {
+      idempotencyKey: key ?? idempotencyKey("rotate"),
+      method: "POST",
+    });
+  }
+
+  updateUser(userId, status, { idempotencyKey: key } = {}) {
+    return this.request(`/users/${encodeURIComponent(userId)}`, {
+      body: { status },
+      idempotencyKey: key ?? idempotencyKey("user-update"),
+      method: "PATCH",
+    });
+  }
+
+  listConnections() {
+    return this.request("/connect");
+  }
+
+  connect(paymentProvider = "link", { idempotencyKey: key } = {}) {
+    return this.request("/connect", {
+      body: { payment_provider: paymentProvider },
+      idempotencyKey: key ?? idempotencyKey("connect"),
+      method: "POST",
+    });
+  }
+
+  createCheckout(checkout, { idempotencyKey: key } = {}) {
+    return this.request("/checkout", {
+      body: checkout,
+      idempotencyKey: key ?? idempotencyKey("checkout"),
+      method: "POST",
+    });
+  }
+
+  getCheckout(checkoutId) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}`);
+  }
+
+  cancelCheckout(checkoutId, { idempotencyKey: key } = {}) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}/cancel`, {
+      idempotencyKey: key ?? idempotencyKey("cancel"),
+      method: "POST",
+    });
+  }
+
+  sendMessage(checkoutId, content, { idempotencyKey: key } = {}) {
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/messages`,
+      {
+        body: { content },
+        idempotencyKey: key ?? idempotencyKey("message"),
+        method: "POST",
+      },
+    );
+  }
+
+  listMessages(checkoutId) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}/messages`);
+  }
+
+  listEvents(checkoutId) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}/events`);
+  }
+
+  listArtifacts(checkoutId) {
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/artifacts`,
+    );
+  }
+
+  providePaymentDetails(checkoutId, card, { idempotencyKey: key } = {}) {
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/payment-details`,
+      {
+        body: { card },
+        idempotencyKey: key ?? idempotencyKey("payment-details"),
+        method: "POST",
+      },
+    );
+  }
+
+  decidePaymentApproval(
+    checkoutId,
+    approvalId,
+    approved,
+    { idempotencyKey: key } = {},
+  ) {
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/payment-approval`,
+      {
+        body: { approval_id: approvalId, approved },
+        idempotencyKey: key ?? idempotencyKey("approval"),
+        method: "POST",
+      },
+    );
+  }
+
+  async runCheckout(checkoutRequest, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30 * 60 * 1_000;
+    const startedAt = Date.now();
+    let checkout = await this.createCheckout(checkoutRequest, {
+      idempotencyKey: options.idempotencyKey,
+    });
+    let progressFingerprint;
+    const publishProgress = async (current) => {
+      if (typeof options.onProgress !== "function") return;
+      const fingerprint = JSON.stringify([
+        current.status,
+        current.revision,
+        current.activity,
+        current.intent?.name,
+        current.intent?.phase,
+        current.intent?.updated_at,
+        current.required_input?.type,
+        current.approval?.id,
+      ]);
+      if (fingerprint === progressFingerprint) return;
+      progressFingerprint = fingerprint;
+      await options.onProgress(current);
+    };
+    await publishProgress(checkout);
+    let handledPaymentRevision;
+    let handledApprovalId;
+    let handledMessageRevision;
+    while (!TERMINAL_STATUSES.has(checkout.status)) {
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new ShopstackApiError("Checkout monitoring timed out.", {
+          code: "checkout_timeout",
+        });
+      }
+      checkout = await this.getCheckout(checkout.id);
+      await publishProgress(checkout);
+      if (
+        checkout.required_input?.type === "payment_card" &&
+        handledPaymentRevision !== checkout.revision
+      ) {
+        if (typeof options.paymentDetails !== "function") return checkout;
+        handledPaymentRevision = checkout.revision;
+        const card = await options.paymentDetails(checkout);
+        if (card === undefined) return checkout;
+        await this.providePaymentDetails(checkout.id, card, {
+          idempotencyKey: `payment-details-${checkout.id}-${checkout.revision}`,
+        });
+        continue;
+      }
+      if (
+        checkout.status === "approval_required" &&
+        checkout.approval &&
+        handledApprovalId !== checkout.approval.id
+      ) {
+        if (typeof options.approve !== "function") return checkout;
+        handledApprovalId = checkout.approval.id;
+        const approved = await options.approve(checkout.approval, checkout);
+        if (typeof approved !== "boolean") return checkout;
+        await this.decidePaymentApproval(
+          checkout.id,
+          checkout.approval.id,
+          approved,
+          { idempotencyKey: `approval-${checkout.approval.id}` },
+        );
+        if (!approved) return this.getCheckout(checkout.id);
+        continue;
+      }
+      if (
+        checkout.status === "help_required" &&
+        checkout.required_input === undefined &&
+        handledMessageRevision !== checkout.revision
+      ) {
+        if (typeof options.message !== "function") return checkout;
+        handledMessageRevision = checkout.revision;
+        const content = await options.message(checkout);
+        if (typeof content !== "string" || content.length === 0)
+          return checkout;
+        await this.sendMessage(checkout.id, content, {
+          idempotencyKey: `message-${checkout.id}-${checkout.revision}`,
+        });
+        continue;
+      }
+      if (!TERMINAL_STATUSES.has(checkout.status)) {
+        const pollIntervalMs =
+          options.pollIntervalMs ??
+          (checkout.status === "help_required" ||
+          checkout.status === "approval_required"
+            ? 5_000
+            : 2_000);
+        await delay(pollIntervalMs);
+      }
+    }
+    return checkout;
+  }
+}