@clocknext/sdk 0.18.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Official ClockNext SDK — record usage signals and manage plans, purchases, invoices, customers, and billing from your backend.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -61,6 +61,9 @@ export type {
   UsageLogOutcomeAttribution,
   UsageLogEntry,
   UsageLogPage,
+  UsageLogLookupEntitlementType,
+  UsageLogLookupEntry,
+  UsageLogLookupResult,
   // customers
   CustomerRef,
   ApiCustomer,
@@ -68,6 +71,10 @@ export type {
   CreateCustomerInput,
   CustomerList,
   CustomerBalances,
+  WalletLedgerPage,
+  WalletLedgerParams,
+  WalletTransaction,
+  WalletTransactionSource,
   CreditBalance,
   OutcomeBalance,
   UnitBalance,

package/src/resources/customers.ts

@@ -23,6 +23,9 @@ import type {
   UnitBalance,
   UpdateMemberInput,
   WalletAdjustInput,
+  WalletLedgerPage,
+  WalletLedgerParams,
+  WalletTransaction,
 } from "../types.js";
 
 /**
@@ -147,6 +150,57 @@ export class Customers {
     });
   }
 
+  /**
+   * One page of the customer's wallet ledger — every movement of wallet
+   * money, newest first — plus both wallet balances. Cursor-paginated: pass
+   * back `nextCursor` as `cursor`. `GET /api/v1/customers/:id/wallet`.
+   */
+  wallet(id: string, params: WalletLedgerParams = {}): Promise<WalletLedgerPage> {
+    return this.walletPage(`/api/v1/customers/${encodeURIComponent(id)}/wallet`, params);
+  }
+
+  /** {@link wallet}, addressing the customer by its `externalId`.
+   *  `GET /api/v1/customers/ext/:externalId/wallet`. */
+  walletByExternalId(
+    externalId: string,
+    params: WalletLedgerParams = {},
+  ): Promise<WalletLedgerPage> {
+    return this.walletPage(
+      `/api/v1/customers/ext/${encodeURIComponent(externalId)}/wallet`,
+      params,
+    );
+  }
+
+  /**
+   * Async iterator over the customer's WHOLE wallet ledger, newest first,
+   * following the cursor. `params.cursor` is ignored.
+   * `for await (const t of cnk.customers.iterateWallet(id)) { … }`
+   */
+  async *iterateWallet(
+    id: string,
+    params: Omit<WalletLedgerParams, "cursor"> = {},
+  ): AsyncGenerator<WalletTransaction> {
+    let cursor: string | undefined;
+    do {
+      const page = await this.wallet(id, { ...params, cursor });
+      for (const t of page.transactions) yield t;
+      cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+  }
+
+  private walletPage(path: string, params: WalletLedgerParams): Promise<WalletLedgerPage> {
+    return this.transport.request<WalletLedgerPage>({
+      method: "GET",
+      path,
+      query: {
+        limit: params.limit,
+        cursor: params.cursor,
+        from: params.from,
+        to: params.to,
+      },
+    });
+  }
+
   /** {@link balances}, addressing the customer by its `externalId`.
    *  `GET /api/v1/customers/ext/:externalId/balances`. */
   balancesByExternalId(externalId: string): Promise<CustomerBalances> {

package/src/resources/signals.ts

@@ -18,6 +18,7 @@ import type {
   UnitTrackResult,
   UsageLogListParams,
   UsageLogPage,
+  UsageLogLookupResult,
   WalletInput,
 } from "../types.js";
 
@@ -46,6 +47,7 @@ const UNIT_PATH = "/api/v1/signal/unit";
 const COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
 const OUTCOME_COMPLETE_PATH = "/api/v1/signal/outcome/complete";
 const USAGE_LOG_PATH = "/api/v1/signal/usage-log";
+const USAGE_LOG_LOOKUP_PATH = "/api/v1/signal/usage-log/lookup";
 
 /**
  * Builds the request body for a typed Signal.
@@ -286,6 +288,7 @@ export class Signals {
         ...customerRefToWire(input),
         runId: input.runId,
         ...(input.member ? { member: input.member } : {}),
+        ...(input.custom ? { custom: input.custom } : {}),
         idempotencyKey,
       },
       retry: true,
@@ -328,6 +331,7 @@ export class Signals {
         ...(input.composite
           ? { composite: { [input.composite.ref]: input.composite.value } }
           : {}),
+        ...(input.custom ? { custom: input.custom } : {}),
         // Assigned HERE, before the send, so the SAME key rides every
         // transport-level retry below. Without it a single 500 followed by a
         // success is TWO un-keyed reports, and the server dedups on the key —
@@ -391,6 +395,7 @@ export class Signals {
       body: {
         ...customerRefToWire(input),
         composite: { [input.composite.ref]: input.composite.value },
+        ...(input.custom ? { custom: input.custom } : {}),
         // Auto-assigned like the others. A retry here could not double-BILL
         // even without it — closing a closed occurrence is a server-side
         // no-op — but that safety comes from occurrence-level dedup, not from
@@ -441,4 +446,25 @@ export class Signals {
       },
     });
   }
+
+  /**
+   * Fetches up to 100 usage-log rows by id, in one call.
+   * `GET /api/v1/signal/usage-log/lookup`.
+   *
+   * Built for linking a wallet debit to its usage: pass the `usageLogId`s
+   * from `customers.wallet()` instead of paging through
+   * {@link usageLog}. Scoped to your org, not to one customer — every row
+   * carries its own `customerId`.
+   *
+   * Rows come back in the order of `ids`; duplicates are removed. Ids that
+   * match nothing in your org are listed in `notFound`. More than 100
+   * distinct ids is a 400.
+   */
+  lookupUsageLogs(ids: string[]): Promise<UsageLogLookupResult> {
+    return this.transport.request<UsageLogLookupResult>({
+      method: "GET",
+      path: USAGE_LOG_LOOKUP_PATH,
+      query: { ids: ids.join(",") },
+    });
+  }
 }

package/src/types.ts

@@ -189,6 +189,8 @@ export type OutcomeCompletionInput = CustomerRef & {
   runId: string;
   /** Optional member (email) this completion is attributed to. */
   member?: string;
+  /** Free-form metadata, stored as-is with this completion. Never priced. */
+  custom?: Record<string, unknown>;
   /** Idempotency key, auto-generated if omitted. Sending this completion twice
    *  for the same run is already a safe no-op server-side, so this only
    *  collapses a retry into one attempt rather than protecting against a
@@ -429,8 +431,9 @@ export interface UsageLogOutcomeAttribution {
 export interface UsageLogEntry {
   id: string;
   createdAt: string;
-  /** Which meter this row is. */
-  type: "credit" | "outcome" | "unit" | "wallet" | "composite";
+  /** Which meter this row is. `"outcome"` is one step of a run;
+   *  `"outcome_completion"` is the finished run itself (one per run). */
+  type: "credit" | "outcome" | "outcome_completion" | "unit" | "wallet" | "composite";
   status: SignalStatus;
   typeName: string | null;
   member: string | null;
@@ -455,8 +458,22 @@ export interface UsageLogEntry {
   /** Populated only when `type === "composite"`. `amount` is a formatted USD
    *  price — the composite's flat price, read live, not stored per row. */
   composite: { amount: string } | null;
-  /** The `custom` object sent on the signal, as sent. `null` when none was
-   *  sent, and always `null` for unit and composite rows. */
+  /** Populated only when `type === "outcome_completion"`. `amount` is the
+   *  price frozen when the run completed (your plan price, else the catalogue
+   *  price). */
+  outcomeCompletion: {
+    runId: string | null;
+    amount: string;
+    runSignals: number;
+  } | null;
+  /** The composite that covers this row's billing, by name — the row's price
+   *  is then included in that composite's own charge, not billed on top. Set
+   *  on credit / outcome / unit / outcome_completion rows tagged into a
+   *  composite on the customer's plan; `null` otherwise. */
+  coveredByComposite: string | null;
+  /** The `custom` object sent, as sent — on the signal itself, or on the
+   *  `completeComposite()` / `completeOutcome()` call that closed a composite /
+   *  outcome_completion row. `null` when none was sent. */
   custom: Record<string, unknown> | null;
 }
 
@@ -467,6 +484,83 @@ export interface UsageLogPage {
   nextCursor: string | null;
 }
 
+// ---------------------------------------------------------------------------
+// Usage log lookup (mirrors GET /api/v1/signal/usage-log/lookup)
+// ---------------------------------------------------------------------------
+
+/** What a {@link UsageLogLookupEntry} row is. `"outcome"` is one step of a
+ *  run; `"outcome_completion"` and `"composite_completion"` are the finished
+ *  runs themselves. */
+export type UsageLogLookupEntitlementType =
+  | "credit"
+  | "outcome"
+  | "outcome_completion"
+  | "unit"
+  | "composite_completion"
+  | "wallet";
+
+/**
+ * One row of `signals.lookupUsageLogs()`. Only the group that matches
+ * `entitlement.type` holds data; the others are `null`.
+ */
+export interface UsageLogLookupEntry {
+  id: string;
+  /** The customer this row belongs to — a lookup can span customers. */
+  customerId: string;
+  /** For a finished run (`outcome_completion`, `composite_completion`), when
+   *  it completed. */
+  createdAt: string;
+  status: SignalStatus;
+  /** The credit / outcome / unit / composite this row is for. A wallet row has
+   *  `id: null` and `name: "Wallet"`. */
+  entitlement: { type: UsageLogLookupEntitlementType; id: string | null; name: string | null };
+  member: string | null;
+  model: { name: string | null; provider: string | null } | null;
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    /** Cache-read tokens. */
+    cacheTokens: number;
+    /** Cache-write tokens, priced separately from cache reads. */
+    cacheWriteTokens: number;
+  };
+  /** Formatted USD strings. `customerCost` is what this row charged:
+   *  `"$0.00"` on an outcome step (the run is billed at completion) and on any
+   *  row a composite pays for. On a unit row it is what the wallet paid for
+   *  that report (debits minus refunds), `"$0.00"` when the wallet paid
+   *  nothing. */
+  cost: { providedCost: string; customerCost: string };
+  /** `entitlement.type === "credit"`. */
+  credit: { amount: string; appliedRules: UsageLogAppliedRule[] } | null;
+  /** `entitlement.type === "outcome"`. `runCompleted` is true once the run is
+   *  finished — on every step row of that run. */
+  outcome: { step: string | null; stepName: string | null; runId: string | null; runCompleted: boolean } | null;
+  /** `entitlement.type === "outcome_completion"`. `amount` is the price frozen
+   *  when the run completed. */
+  outcomeCompletion: { runId: string | null; amount: string } | null;
+  /** `entitlement.type === "unit"`. `quantity` is formatted. */
+  unit: { quantity: string } | null;
+  /** `entitlement.type === "composite_completion"`. `refId` is the
+   *  composite's tag key, `runId` the tag value you sent. */
+  compositeCompletion: { refId: string | null; runId: string | null; amount: string; startedAt: string } | null;
+  /** `entitlement.type === "wallet"`. What the wallet paid, formatted USD —
+   *  the same value as `cost.customerCost`. */
+  wallet: { amount: string } | null;
+  /** The composite that pays for this row — its id, its tag key (`refId`) and
+   *  the tag value you sent (`runId`). `null` when the row is billed by
+   *  itself. */
+  composite: { id: string | null; refId: string | null; runId: string | null } | null;
+  /** The `custom` object sent, as sent. `null` when none was sent. */
+  custom: Record<string, unknown> | null;
+}
+
+export interface UsageLogLookupResult {
+  /** The rows found, in the order of the ids you asked for. */
+  usageLogs: UsageLogLookupEntry[];
+  /** The ids that matched nothing in your org, in the order you asked. */
+  notFound: string[];
+}
+
 // ---------------------------------------------------------------------------
 // Customers (mirrors src/lib/customers/api.ts)
 // ---------------------------------------------------------------------------
@@ -491,8 +585,6 @@ export interface ApiCustomer {
   taxId: string | null;
   currencyCode: string;
   creditAllowance: number;
-  recurringTransactionEmail: boolean;
-  autoRecurring: boolean;
   createdAt: string;
   updatedAt: string;
 }
@@ -523,10 +615,6 @@ export interface CustomerProfileInput {
   taxId?: string | null;
   /** ISO 4217 (3 letters); must be enabled for the org. */
   currencyCode?: string;
-  /** Send the invoice, payment receipt and card-payment-failed emails for recurring invoices. Defaults to `true` on create. */
-  recurringTransactionEmail?: boolean;
-  /** Issue every recurring invoice as `AUTO_CLOSED` (applied as if paid, never payable). Defaults to `false` on create. */
-  autoRecurring?: boolean;
 }
 
 /** `name` and `email` are required on create; every other field is optional. */
@@ -619,6 +707,83 @@ export interface CustomerBalances {
   composites: CompositeBalance[];
 }
 
+/** What caused a wallet ledger row (`WalletTransaction.source`). */
+export type WalletTransactionSource =
+  /** Wallet money from a new plan purchase. */
+  | "SUBSCRIPTION"
+  /** Wallet money from a plan renewal, or unused money removed at renewal. */
+  | "RENEWAL"
+  /** Changed in the ClockNext dashboard. */
+  | "MANUAL"
+  /** Changed with `customers.adjustWallet()`. */
+  | "API"
+  /** Top-up paid by the customer in the customer portal. */
+  | "CUSTOMER_PORTAL"
+  /** Charged by a signal; `usageLogId` links the signal. */
+  | "USAGE_LOG"
+  /** Usage cleared by a paid pay-as-you-go invoice. */
+  | "INVOICE_SETTLEMENT"
+  /** Settlement undone by a voided invoice. */
+  | "INVOICE_VOID";
+
+/** One row of a customer's wallet ledger (`customers.wallet()`). */
+export interface WalletTransaction {
+  id: string;
+  /** ISO 8601. */
+  createdAt: string;
+  /** `CREDIT` adds money, `DEBIT` takes it out. */
+  type: "CREDIT" | "DEBIT";
+  /** Which balance moved: the ordinary wallet or the Reserved Wallet. */
+  pool: "main" | "reserved";
+  source: WalletTransactionSource;
+  /** Always positive — `type` gives the direction. In `currencyCode`. */
+  amount: number;
+  /** The same amount in USD. */
+  amountUsd: number;
+  currencyCode: string;
+  /** 1 USD = this many units of `currencyCode`, at write time. */
+  currencyRateUsd: number;
+  /** Only text a person wrote: your own note on an `API` row, the admin's
+   *  note on a `MANUAL` row. `null` on every row the system writes itself —
+   *  `source` says what those are. */
+  notes: string | null;
+  /** On a usage charge for an entitlement: which kind. `null` otherwise. */
+  entitlementType: "CREDIT" | "OUTCOME" | "UNIT" | "COMPOSITE" | null;
+  /** Id of that credit / outcome / unit / composite. */
+  entitlementId: string | null;
+  /** Its name when the row was written. */
+  entitlementName: string | null;
+  /** On a `USAGE_LOG` row: the id of the matching row in
+   *  `signals.usageLog()`. */
+  usageLogId: string | null;
+  /** On a `SUBSCRIPTION` / `RENEWAL` grant: the purchase it came from. */
+  purchaseId: string | null;
+  purchaseNumber: string | null;
+}
+
+/** One page of a customer's wallet ledger, newest first. */
+export interface WalletLedgerPage {
+  /** Ordinary wallet balance, USD. May be negative. */
+  balanceUsd: number;
+  /** Reserved Wallet balance, USD; `null` when the workspace hasn't enabled
+   *  it. */
+  reservedBalanceUsd: number | null;
+  transactions: WalletTransaction[];
+  /** Pass back as `cursor` for the next page; `null` on the last page. */
+  nextCursor: string | null;
+}
+
+export interface WalletLedgerParams {
+  /** Default 50, max 200. */
+  limit?: number;
+  /** A previous page's `nextCursor`. Omit for the first page. */
+  cursor?: string;
+  /** First day to include, `YYYY-MM-DD` (UTC). The whole day is included. */
+  from?: string;
+  /** Last day to include, `YYYY-MM-DD` (UTC). The whole day is included. */
+  to?: string;
+}
+
 /** The customer's active plan (the `plan` field of `customers.plan()`);
  *  `null` when the customer is unsubscribed. */
 export interface CustomerPlanDetails {
@@ -1120,7 +1285,8 @@ export interface PurchaseDetail {
 // Invoices & Payments
 // ---------------------------------------------------------------------------
 
-/** `AUTO_CLOSED` — a recurring invoice for a customer with `autoRecurring` on:
+/** `AUTO_CLOSED` — a recurring invoice of an organisation with "Auto close
+ *  invoices on recurring" on (dashboard: Settings → Organisation → Billing):
  *  applied as if paid, but never payable. */
 export type InvoiceStatus = "OPEN" | "PAID" | "VOID" | "AUTO_CLOSED";
 
@@ -1529,6 +1695,8 @@ export type UnitInput = CustomerRef & {
   quantity?: number;
   /** Optional composite this unit report belongs to. See {@link CompositeTag}. */
   composite?: CompositeTag;
+  /** Free-form metadata, stored as-is with this unit report. Never priced. */
+  custom?: Record<string, unknown>;
   /**
    * Idempotency key for safe retries — a repeat carrying the same key returns
    * the original result instead of drawing the balance down twice.
@@ -1580,6 +1748,9 @@ export type CompositeCompletionInput = CustomerRef & {
   /** Which occurrence to close: the composite's `refId` and the correlation
    *  value the signals were tagged with. */
   composite: CompositeTag;
+  /** Free-form metadata, stored as-is on the occurrence this call closes.
+   *  Never priced. */
+  custom?: Record<string, unknown>;
   /** Idempotency key, auto-generated if omitted. Closing twice is already a
    *  safe no-op, so this only collapses retries into one recorded attempt
    *  rather than protecting against a double charge. */