@clocknext/sdk 0.11.0 → 0.12.1

package/src/resources/customers.ts

@@ -0,0 +1,298 @@
+import type { Transport } from "../http.js";
+import type {
+  AddMemberInput,
+  ApiCustomer,
+  CreateCustomerInput,
+  CreditAdjustInput,
+  CreditBalance,
+  CustomerBalances,
+  CustomerList,
+  CustomerPlan,
+  CustomerProfileInput,
+  Member,
+  MemberProfile,
+  OutcomeAdjustInput,
+  OutcomeBalance,
+  RemovedMember,
+  UnitAdjustInput,
+  UnitBalance,
+  UpdateMemberInput,
+  UsageList,
+  WalletEntryInput,
+  WalletList,
+  WalletTransaction,
+} from "../types.js";
+
+/**
+ * The `customers` resource — full CRUD over the org's customers plus the
+ * read-only insight endpoints (usage / balances / plan). Every call is scoped
+ * to the API key's organisation server-side; a customer in another org
+ * resolves as a NotFoundError.
+ */
+export class Customers {
+  constructor(private readonly transport: Transport) {}
+
+  /** Create a customer. `POST /api/v1/customers`. */
+  async create(input: CreateCustomerInput): Promise<ApiCustomer> {
+    const res = await this.transport.request<{ customer: ApiCustomer }>({
+      method: "POST",
+      path: "/api/v1/customers",
+      body: input,
+    });
+    return res.customer;
+  }
+
+  /** List customers, most-recent first (cursor-paginated). `GET /api/v1/customers`. */
+  async list(params: {
+    limit?: number;
+    q?: string;
+    cursor?: string;
+  } = {}): Promise<CustomerList> {
+    const res = await this.transport.request<CustomerList>({
+      method: "GET",
+      path: "/api/v1/customers",
+      query: { limit: params.limit, q: params.q, cursor: params.cursor },
+    });
+    return { customers: res.customers, nextCursor: res.nextCursor };
+  }
+
+  /**
+   * Async iterator over ALL customers, transparently following the cursor.
+   * `for await (const c of cnk.customers.iterate()) { … }`
+   */
+  async *iterate(params: { limit?: number; q?: string } = {}): AsyncGenerator<
+    ApiCustomer
+  > {
+    let cursor: string | undefined;
+    do {
+      const page = await this.list({ ...params, cursor });
+      for (const c of page.customers) yield c;
+      cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+  }
+
+  /** Fetch one customer. `GET /api/v1/customers/:id`. */
+  async get(id: string): Promise<ApiCustomer> {
+    const res = await this.transport.request<{ customer: ApiCustomer }>({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}`,
+    });
+    return res.customer;
+  }
+
+  /** Update a customer (partial). `PATCH /api/v1/customers/:id`. */
+  async update(
+    id: string,
+    input: CustomerProfileInput,
+  ): Promise<ApiCustomer> {
+    const res = await this.transport.request<{ customer: ApiCustomer }>({
+      method: "PATCH",
+      path: `/api/v1/customers/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.customer;
+  }
+
+  /** Delete a customer (members, invitations, usage logs cascade). */
+  async delete(id: string): Promise<void> {
+    await this.transport.request({
+      method: "DELETE",
+      path: `/api/v1/customers/${encodeURIComponent(id)}`,
+    });
+  }
+
+  /** A customer's usage history. `GET /api/v1/usage?customerId=`. */
+  async usage(id: string, params: { limit?: number } = {}): Promise<UsageList> {
+    const res = await this.transport.request<UsageList>({
+      method: "GET",
+      path: `/api/v1/usage`,
+      query: { customerId: id, limit: params.limit },
+    });
+    return { customer: res.customer, totals: res.totals, logs: res.logs };
+  }
+
+  /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
+  balances(id: string): Promise<CustomerBalances> {
+    return this.transport.request<CustomerBalances>({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/balances`,
+    });
+  }
+
+  /**
+   * One credit balance for a customer, matched by `creditId` or `creditName`;
+   * `null` when the customer has no plan or no matching credit. Convenience
+   * over `balances()` + `Array.find` — it fetches the FULL balances under the
+   * hood (there is no server-side scoped read), so prefer `balances()` when you
+   * need several rows from the same customer.
+   */
+  async creditBalance(
+    customerId: string,
+    match: { creditId?: string; creditName?: string },
+  ): Promise<CreditBalance | null> {
+    const { credits } = await this.balances(customerId);
+    return (
+      credits.find(
+        (c) =>
+          (match.creditId != null && c.creditId === match.creditId) ||
+          (match.creditName != null && c.creditName === match.creditName),
+      ) ?? null
+    );
+  }
+
+  /** One outcome balance for a customer, matched by `outcomeId` or
+   *  `outcomeName`; `null` when absent. See {@link creditBalance} for the
+   *  fetch-then-filter caveat. */
+  async outcomeBalance(
+    customerId: string,
+    match: { outcomeId?: string; outcomeName?: string },
+  ): Promise<OutcomeBalance | null> {
+    const { outcomes } = await this.balances(customerId);
+    return (
+      outcomes.find(
+        (o) =>
+          (match.outcomeId != null && o.outcomeId === match.outcomeId) ||
+          (match.outcomeName != null && o.outcomeName === match.outcomeName),
+      ) ?? null
+    );
+  }
+
+  /** One unit balance for a customer, matched by `unitId` or `unitName`;
+   *  `null` when absent. See {@link creditBalance} for the fetch-then-filter
+   *  caveat. */
+  async unitBalance(
+    customerId: string,
+    match: { unitId?: string; unitName?: string },
+  ): Promise<UnitBalance | null> {
+    const { units } = await this.balances(customerId);
+    return (
+      units.find(
+        (u) =>
+          (match.unitId != null && u.unitId === match.unitId) ||
+          (match.unitName != null && u.unitName === match.unitName),
+      ) ?? null
+    );
+  }
+
+  /** The customer's current plan. `GET …/:id/plan`. */
+  plan(id: string): Promise<CustomerPlan> {
+    return this.transport.request<CustomerPlan>({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/plan`,
+    });
+  }
+
+  // --- Members -------------------------------------------------------------
+
+  /** List a customer's members. `GET …/:id/members`. */
+  async listMembers(id: string): Promise<Member[]> {
+    const res = await this.transport.request<{ members: Member[] }>({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/members`,
+    });
+    return res.members;
+  }
+
+  /** Add a member to a customer. Duplicate `email` → ConflictError. */
+  async addMember(id: string, input: AddMemberInput): Promise<MemberProfile> {
+    const res = await this.transport.request<{ member: MemberProfile }>({
+      method: "POST",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/members`,
+      body: input,
+    });
+    return res.member;
+  }
+
+  /** Update a member's profile. Duplicate `email` → ConflictError. `PATCH …/:id/members/:memberId`. */
+  async updateMember(
+    id: string,
+    memberId: string,
+    input: UpdateMemberInput,
+  ): Promise<MemberProfile> {
+    const res = await this.transport.request<{ member: MemberProfile }>({
+      method: "PATCH",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/members/${encodeURIComponent(memberId)}`,
+      body: input,
+    });
+    return res.member;
+  }
+
+  /** Remove a member from a customer, returning who was removed. `DELETE …/:id/members/:memberId`. */
+  async removeMember(id: string, memberId: string): Promise<RemovedMember> {
+    const res = await this.transport.request<{ removed: true; member: RemovedMember }>({
+      method: "DELETE",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/members/${encodeURIComponent(memberId)}`,
+    });
+    return res.member;
+  }
+
+  // --- Wallet & billing config --------------------------------------------
+
+  /** The customer's wallet balance + transactions. `GET …/:id/wallet`. */
+  wallet(id: string, params: { limit?: number } = {}): Promise<WalletList> {
+    return this.transport.request<WalletList>({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/wallet`,
+      query: { limit: params.limit },
+    });
+  }
+
+  /**
+   * Record a manual wallet entry (top-up or deduction). `amount` is always
+   * positive; the sign comes from `type`. `POST …/:id/wallet`.
+   */
+  async addWalletEntry(
+    id: string,
+    input: WalletEntryInput,
+  ): Promise<{ transaction: WalletTransaction; balanceUsd: number }> {
+    return this.transport.request<{
+      transaction: WalletTransaction;
+      balanceUsd: number;
+    }>({
+      method: "POST",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/wallet`,
+      body: input,
+    });
+  }
+
+  // Note: a customer's currency is set through `update(id, { currencyCode })`
+  // (PATCH …/:id) — there is no separate currency endpoint. Credit-type
+  // assignment has no public API.
+
+  // --- Balance adjustments -------------------------------------------------
+
+  /** Grant or claw back a credit balance. `POST …/:id/credits/adjust`. */
+  async adjustCredit(id: string, input: CreditAdjustInput): Promise<void> {
+    await this.transport.request({
+      method: "POST",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/credits/adjust`,
+      body: input,
+    });
+  }
+
+  /** Grant or claw back an outcome balance. Returns the remaining balance. */
+  async adjustOutcome(
+    id: string,
+    input: OutcomeAdjustInput,
+  ): Promise<{ remaining: number }> {
+    const res = await this.transport.request<{ remaining: number }>({
+      method: "POST",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/outcomes/adjust`,
+      body: input,
+    });
+    return { remaining: res.remaining };
+  }
+
+  /** Grant or claw back a unit balance. Returns the remaining balance. */
+  async adjustUnit(
+    id: string,
+    input: UnitAdjustInput,
+  ): Promise<{ remaining: number }> {
+    const res = await this.transport.request<{ remaining: number }>({
+      method: "POST",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/units/adjust`,
+      body: input,
+    });
+    return { remaining: res.remaining };
+  }
+}

package/src/resources/invoices.ts

@@ -0,0 +1,51 @@
+import type { Transport } from "../http.js";
+import type {
+  InvoiceDetail,
+  InvoiceListRow,
+  InvoiceStatus,
+  PayLink,
+} from "../types.js";
+
+/**
+ * The `invoices` resource — read-only. Invoices are generated by the billing
+ * engine from purchases; you list them, read one, or mint a hosted pay link for
+ * an OPEN invoice. `/api/v1/invoices`.
+ */
+export class Invoices {
+  constructor(private readonly transport: Transport) {}
+
+  /** List invoices, most-recent first. Filter by customer and/or status. */
+  async list(
+    params: { customerId?: string; status?: InvoiceStatus; limit?: number } = {},
+  ): Promise<InvoiceListRow[]> {
+    const res = await this.transport.request<{ invoices: InvoiceListRow[] }>({
+      method: "GET",
+      path: "/api/v1/invoices",
+      query: {
+        customerId: params.customerId,
+        status: params.status,
+        limit: params.limit,
+      },
+    });
+    return res.invoices;
+  }
+
+  /** Fetch one full invoice + its plan snapshot. `GET /api/v1/invoices/:id`. */
+  get(id: string): Promise<InvoiceDetail> {
+    return this.transport.request<InvoiceDetail>({
+      method: "GET",
+      path: `/api/v1/invoices/${encodeURIComponent(id)}`,
+    });
+  }
+
+  /**
+   * Mint a hosted pay link for an OPEN invoice. PAID/VOID invoices are rejected
+   * with a `ConflictError`. `GET /api/v1/invoices/:id/pay-link`.
+   */
+  payLink(id: string): Promise<PayLink> {
+    return this.transport.request<PayLink>({
+      method: "GET",
+      path: `/api/v1/invoices/${encodeURIComponent(id)}/pay-link`,
+    });
+  }
+}

package/src/resources/outcomes.ts

@@ -0,0 +1,82 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type {
+  CreateOutcomeInput,
+  Outcome,
+  OutcomeDetail,
+  UpdateOutcomeInput,
+} from "../types.js";
+
+/**
+ * The `outcomes` resource — manage the org's outcome *types* (the catalog). An
+ * outcome is a multi-step workflow. `/api/v1/outcomes`.
+ *
+ * Two distinct kinds of agent key, in separate namespaces, each unique per
+ * organisation — do not conflate them:
+ * - the OUTCOME's own `agentKey`, REQUIRED on `create()` and `update()`, which
+ *   names the outcome itself in the catalogue;
+ * - each STEP's `agentKey`, which is what you pass to `signals.outcome()` to
+ *   report usage and to the outcome-adjust API.
+ */
+export class Outcomes {
+  constructor(private readonly transport: Transport) {}
+
+  /** List outcome types. Pass `{ active: true }` to only return active ones.
+   *  `{ active: false }` returns only archived ones; omitting it returns
+   *  both. See `activeQuery` — the API itself only supports `true`. */
+  async list(params: { active?: boolean } = {}): Promise<Outcome[]> {
+    const res = await this.transport.request<{ outcomes: Outcome[] }>({
+      method: "GET",
+      path: "/api/v1/outcomes",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.outcomes, params.active);
+  }
+
+  /** Create an outcome type with its steps. `POST /api/v1/outcomes`. */
+  async create(input: CreateOutcomeInput): Promise<Outcome> {
+    const res = await this.transport.request<{ outcome: Outcome }>({
+      method: "POST",
+      path: "/api/v1/outcomes",
+      body: input,
+    });
+    return res.outcome;
+  }
+
+  /** Fetch one outcome type with steps + stats. `GET /api/v1/outcomes/:id`. */
+  async get(id: string): Promise<OutcomeDetail> {
+    const res = await this.transport.request<{ outcome: OutcomeDetail }>({
+      method: "GET",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
+    });
+    return res.outcome;
+  }
+
+  /** Update an outcome type's definition. `PATCH /api/v1/outcomes/:id`. */
+  async update(id: string, input: UpdateOutcomeInput): Promise<Outcome> {
+    const res = await this.transport.request<{ outcome: Outcome }>({
+      method: "PATCH",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.outcome;
+  }
+
+  /** Activate or deactivate an outcome type; returns the updated outcome. */
+  async setActive(id: string, isActive: boolean): Promise<Outcome> {
+    const res = await this.transport.request<{ outcome: Outcome }>({
+      method: "PATCH",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
+      body: { isActive },
+    });
+    return res.outcome;
+  }
+
+  /** Delete an outcome type. */
+  async delete(id: string): Promise<void> {
+    await this.transport.request({
+      method: "DELETE",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
+    });
+  }
+}

package/src/resources/payments.ts

@@ -0,0 +1,30 @@
+import type { Transport } from "../http.js";
+import type { PaymentDetail, PaymentRow } from "../types.js";
+
+/**
+ * The `payments` resource — read-only. A payment is a PAID invoice; the `id`
+ * used here is that underlying invoice id. `/api/v1/payments`.
+ */
+export class Payments {
+  constructor(private readonly transport: Transport) {}
+
+  /** List payments (paid invoices), most-recent first. Filter by customer. */
+  async list(
+    params: { customerId?: string; limit?: number } = {},
+  ): Promise<PaymentRow[]> {
+    const res = await this.transport.request<{ payments: PaymentRow[] }>({
+      method: "GET",
+      path: "/api/v1/payments",
+      query: { customerId: params.customerId, limit: params.limit },
+    });
+    return res.payments;
+  }
+
+  /** Fetch one payment + its plan snapshot. `GET /api/v1/payments/:id`. */
+  get(id: string): Promise<PaymentDetail> {
+    return this.transport.request<PaymentDetail>({
+      method: "GET",
+      path: `/api/v1/payments/${encodeURIComponent(id)}`,
+    });
+  }
+}

package/src/resources/plans.ts

@@ -0,0 +1,76 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type {
+  CreatePlanInput,
+  Plan,
+  PlanDetail,
+  UpdatePlanInput,
+} from "../types.js";
+
+/**
+ * The `plans` resource — define and manage the billing plans customers
+ * subscribe to. Each plan is a set of entitlement components (wallet / credit /
+ * outcome / unit / flat) billed on a cycle. `/api/v1/plans`.
+ */
+export class Plans {
+  constructor(private readonly transport: Transport) {}
+
+  /** List plans, oldest-first. Pass `{ active: true }` to only return active plans.
+   *  `{ active: false }` returns only archived ones; omitting it returns
+   *  both. See `activeQuery` — the API itself only supports `true`. */
+  async list(params: { active?: boolean } = {}): Promise<Plan[]> {
+    const res = await this.transport.request<{ plans: Plan[] }>({
+      method: "GET",
+      path: "/api/v1/plans",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.plans, params.active);
+  }
+
+  /** Create a plan. `POST /api/v1/plans`. */
+  async create(input: CreatePlanInput): Promise<Plan> {
+    const res = await this.transport.request<{ plan: Plan }>({
+      method: "POST",
+      path: "/api/v1/plans",
+      body: input,
+    });
+    return res.plan;
+  }
+
+  /** Fetch one plan with aggregate subscriber/invoice stats. `GET /api/v1/plans/:id`. */
+  async get(id: string): Promise<PlanDetail> {
+    const res = await this.transport.request<{ plan: PlanDetail }>({
+      method: "GET",
+      path: `/api/v1/plans/${encodeURIComponent(id)}`,
+    });
+    return res.plan;
+  }
+
+  /** Replace a plan's definition (components + settings). `PATCH /api/v1/plans/:id`. */
+  async update(id: string, input: UpdatePlanInput): Promise<Plan> {
+    const res = await this.transport.request<{ plan: Plan }>({
+      method: "PATCH",
+      path: `/api/v1/plans/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.plan;
+  }
+
+  /** Activate or deactivate a plan without rewriting it. */
+  async setActive(id: string, isActive: boolean): Promise<Plan> {
+    const res = await this.transport.request<{ plan: Plan }>({
+      method: "PATCH",
+      path: `/api/v1/plans/${encodeURIComponent(id)}`,
+      body: { isActive },
+    });
+    return res.plan;
+  }
+
+  /** Delete a plan. Refused once any customer has purchased it. */
+  async delete(id: string): Promise<void> {
+    await this.transport.request({
+      method: "DELETE",
+      path: `/api/v1/plans/${encodeURIComponent(id)}`,
+    });
+  }
+}

package/src/resources/portal.ts

@@ -0,0 +1,31 @@
+import type { Transport } from "../http.js";
+import type { PortalToken, PortalTokenInput } from "../types.js";
+
+/**
+ * The `portal` resource — mint a short-lived embed token for one of your
+ * customers, then render `<iframe src=".../portal/embed?token=<token>">`. The
+ * HS256 signing secret never leaves ClockNext; your backend only needs its API
+ * key. `POST /api/v1/portal/token`.
+ */
+export class Portal {
+  constructor(private readonly transport: Transport) {}
+
+  async createToken(input: PortalTokenInput): Promise<PortalToken> {
+    const res = await this.transport.request<
+      { token: string; expiresAt: number; expiresIn: number }
+    >({
+      method: "POST",
+      path: "/api/v1/portal/token",
+      body: {
+        customerId: input.customerId,
+        ttlSeconds: input.ttlSeconds,
+        memberEmail: input.memberEmail,
+      },
+    });
+    return {
+      token: res.token,
+      expiresAt: res.expiresAt,
+      expiresIn: res.expiresIn,
+    };
+  }
+}

package/src/resources/purchases.ts

@@ -0,0 +1,75 @@
+import type { Transport } from "../http.js";
+import type {
+  CreatePurchaseInput,
+  Purchase,
+  PurchaseDetail,
+  PurchaseStatus,
+} from "../types.js";
+
+/**
+ * The `purchases` resource — a purchase is a customer's subscription to a plan.
+ * Creating one auto-cancels the customer's existing scheduled/active purchase
+ * (this is also how you "change plan"). `/api/v1/purchases`.
+ */
+export class Purchases {
+  constructor(private readonly transport: Transport) {}
+
+  /** List purchases, most-recent first. Filter by customer and/or status. */
+  async list(
+    params: { customerId?: string; status?: PurchaseStatus; limit?: number } = {},
+  ): Promise<Purchase[]> {
+    const res = await this.transport.request<{ purchases: Purchase[] }>({
+      method: "GET",
+      path: "/api/v1/purchases",
+      query: {
+        customerId: params.customerId,
+        status: params.status,
+        limit: params.limit,
+      },
+    });
+    return res.purchases;
+  }
+
+  /** Subscribe a customer to a plan. `POST /api/v1/purchases`. */
+  async create(input: CreatePurchaseInput): Promise<Purchase> {
+    const res = await this.transport.request<{ purchase: Purchase }>({
+      method: "POST",
+      path: "/api/v1/purchases",
+      body: input,
+    });
+    return res.purchase;
+  }
+
+  /** Fetch one purchase. `GET /api/v1/purchases/:id`. */
+  async get(id: string): Promise<PurchaseDetail> {
+    const res = await this.transport.request<{ purchase: PurchaseDetail }>({
+      method: "GET",
+      path: `/api/v1/purchases/${encodeURIComponent(id)}`,
+    });
+    return res.purchase;
+  }
+
+  /**
+   * Turn automatic billing on or off for a purchase. When pausing, an optional
+   * `pauseReason` is recorded. `PATCH /api/v1/purchases/:id`.
+   */
+  async setAutoPayment(
+    id: string,
+    autoPayment: boolean,
+    opts: { pauseReason?: string } = {},
+  ): Promise<{ autoPayment: boolean }> {
+    return this.transport.request<{ autoPayment: boolean }>({
+      method: "PATCH",
+      path: `/api/v1/purchases/${encodeURIComponent(id)}`,
+      body: { autoPayment, pauseReason: opts.pauseReason },
+    });
+  }
+
+  /** Cancel a purchase (voids any open invoice). `POST /api/v1/purchases/:id/cancel`. */
+  async cancel(id: string): Promise<void> {
+    await this.transport.request({
+      method: "POST",
+      path: `/api/v1/purchases/${encodeURIComponent(id)}/cancel`,
+    });
+  }
+}