@clocknext/sdk 0.17.0 → 0.19.0

package/package.json

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

package/src/client.ts

@@ -12,6 +12,7 @@ import { Portal } from "./resources/portal.js";
 import { Purchases } from "./resources/purchases.js";
 import { Signals } from "./resources/signals.js";
 import { Units } from "./resources/units.js";
+import { Taxes } from "./resources/taxes.js";
 import type { ClockNextConfig, ResolvedConfig } from "./types.js";
 
 /**
@@ -46,6 +47,8 @@ export class ClockNext {
   readonly units: Units;
   /** Composites: list, get, create, update, archive, unarchive (no delete). */
   readonly composites: Composites;
+  /** Tax rates by country: list, get, create, update (archive in the dashboard). */
+  readonly taxes: Taxes;
   /** Subscribe customers to plans (purchases). */
   readonly purchases: Purchases;
   /** Read invoices and mint hosted pay links. */
@@ -76,6 +79,7 @@ export class ClockNext {
     this.outcomes = new Outcomes(transport);
     this.units = new Units(transport);
     this.composites = new Composites(transport);
+    this.taxes = new Taxes(transport);
     this.purchases = new Purchases(transport);
     this.invoices = new Invoices(transport);
     this.payments = new Payments(transport);

package/src/index.ts

@@ -56,7 +56,6 @@ export type {
   CompositeCompletionInput,
   CompositeCompletionResult,
   SerializedUnitUsage,
-  UsageLogPeriod,
   UsageLogListParams,
   UsageLogAppliedRule,
   UsageLogOutcomeAttribution,
@@ -69,6 +68,10 @@ export type {
   CreateCustomerInput,
   CustomerList,
   CustomerBalances,
+  WalletLedgerPage,
+  WalletLedgerParams,
+  WalletTransaction,
+  WalletTransactionSource,
   CreditBalance,
   OutcomeBalance,
   UnitBalance,
@@ -114,6 +117,11 @@ export type {
   Unit,
   CreateUnitInput,
   UpdateUnitInput,
+  // taxes
+  TaxBehavior,
+  Tax,
+  CreateTaxInput,
+  UpdateTaxInput,
   CompositeItem,
   Composite,
   CreateCompositeInput,

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

@@ -286,6 +286,7 @@ export class Signals {
         ...customerRefToWire(input),
         runId: input.runId,
         ...(input.member ? { member: input.member } : {}),
+        ...(input.custom ? { custom: input.custom } : {}),
         idempotencyKey,
       },
       retry: true,
@@ -328,6 +329,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 +393,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
@@ -436,7 +439,6 @@ export class Signals {
         customerId: params.customerId,
         limit: params.limit,
         cursor: params.cursor,
-        period: params.period,
         from: params.from,
         to: params.to,
       },

package/src/resources/taxes.ts

@@ -0,0 +1,59 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type { CreateTaxInput, Tax, UpdateTaxInput } from "../types.js";
+
+/**
+ * The `taxes` resource — the tax rates charged to customers by billing
+ * country (the same rates as Settings → Taxes). `/api/v1/taxes`.
+ *
+ * Every active tax for a customer's country is applied to their invoices and
+ * portal purchases automatically. There is no `delete()`, `archive()` or
+ * `unarchive()` — archiving and restoring a tax is done in the dashboard.
+ */
+export class Taxes {
+  constructor(private readonly transport: Transport) {}
+
+  /** List them, oldest first. `{ active: true }` returns only active ones,
+   *  `{ active: false }` only archived ones; omit it for both. */
+  async list(params: { active?: boolean } = {}): Promise<Tax[]> {
+    const res = await this.transport.request<{ taxes: Tax[] }>({
+      method: "GET",
+      path: "/api/v1/taxes",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.taxes, params.active);
+  }
+
+  /** One tax. */
+  async get(id: string): Promise<Tax> {
+    const res = await this.transport.request<{ tax: Tax }>({
+      method: "GET",
+      path: `/api/v1/taxes/${encodeURIComponent(id)}`,
+    });
+    return res.tax;
+  }
+
+  /** Create one. It starts active. Two active taxes can't share a name
+   *  (ignoring case) in the same country — that's a `ConflictError`. Not
+   *  retried on failure — a retry could create a second row. */
+  async create(input: CreateTaxInput): Promise<Tax> {
+    const res = await this.transport.request<{ created: true; tax: Tax }>({
+      method: "POST",
+      path: "/api/v1/taxes",
+      body: input,
+    });
+    return res.tax;
+  }
+
+  /** PARTIAL update: only the fields you send change. Archived taxes can be
+   *  edited and stay archived. Only invoices issued afterwards use the new
+   *  values. */
+  async update(id: string, input: UpdateTaxInput): Promise<Tax> {
+    const res = await this.transport.request<{ updated: true; tax: Tax }>({
+      method: "PATCH",
+      path: `/api/v1/taxes/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.tax;
+  }
+}

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
@@ -383,9 +385,6 @@ export interface TrackResult {
 // Usage log (mirrors GET /api/v1/signal/usage-log)
 // ---------------------------------------------------------------------------
 
-/** A preset time window, or `"custom"` for an explicit `from`/`to` range. */
-export type UsageLogPeriod = "all" | "today" | "7d" | "30d" | "90d" | "custom";
-
 export interface UsageLogListParams {
   customerId: string;
   /** Default 50, max 200. */
@@ -393,11 +392,11 @@ export interface UsageLogListParams {
   /** Pass back a previous page's `nextCursor` to fetch the next page. Omit for
    *  the first page. */
   cursor?: string;
-  /** Default `"all"`. Pair `"custom"` with `from`/`to`. */
-  period?: UsageLogPeriod;
-  /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+  /** First day to include, `YYYY-MM-DD` (UTC). The whole day is included.
+   *  Keep sending the same value while paging with `cursor`. */
   from?: string;
-  /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+  /** Last day to include, `YYYY-MM-DD` (UTC). The whole day is included.
+   *  Must not be before `from`. */
   to?: string;
 }
 
@@ -426,13 +425,15 @@ export interface UsageLogOutcomeAttribution {
  * One row of a customer's usage history, merged from every meter kind
  * (`UsageLog`, `UnitUsageLog`, completed composite occurrences) into one
  * feed and sorted by time — the same rows the customer portal's own "Usage
- * logs" table shows. `model`, `credit`, `outcome`, `unit` and `composite` are
- * each `null` unless `kind` matches that group.
+ * logs" table shows. `credit`, `outcome`, `unit` and `composite` are each
+ * `null` unless `type` matches that group.
  */
 export interface UsageLogEntry {
   id: string;
   createdAt: string;
-  kind: "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;
@@ -447,16 +448,33 @@ export interface UsageLogEntry {
   };
   /** Formatted USD strings (e.g. `"$0.0064"`). */
   cost: { providedCost: string; customerCost: string };
-  /** Populated only when `kind === "credit"`. `amount` is a formatted credit
+  /** Populated only when `type === "credit"`. `amount` is a formatted credit
    *  value, honouring the org's credit-decimals display setting. */
   credit: { amount: string; appliedRules: UsageLogAppliedRule[] } | null;
-  /** Populated only when `kind === "outcome"`. */
+  /** Populated only when `type === "outcome"`. */
   outcome: UsageLogOutcomeAttribution | null;
-  /** Populated only when `kind === "unit"`. `quantity` is formatted. */
+  /** Populated only when `type === "unit"`. `quantity` is formatted. */
   unit: { quantity: string } | null;
-  /** Populated only when `kind === "composite"`. `amount` is a formatted USD
+  /** 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;
+  /** 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;
 }
 
 export interface UsageLogPage {
@@ -490,8 +508,6 @@ export interface ApiCustomer {
   taxId: string | null;
   currencyCode: string;
   creditAllowance: number;
-  recurringTransactionEmail: boolean;
-  autoRecurring: boolean;
   createdAt: string;
   updatedAt: string;
 }
@@ -522,10 +538,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. */
@@ -618,6 +630,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 {
@@ -963,6 +1052,46 @@ export interface CreateUnitInput {
 /** `units.update()` body — PARTIAL. `tiers`, when sent, is the complete list. */
 export type UpdateUnitInput = Partial<CreateUnitInput>;
 
+/** How a tax applies: `"inclusive"` — already inside the price;
+ *  `"exclusive"` — added on top. Lower case only. */
+export type TaxBehavior = "inclusive" | "exclusive";
+
+/** A tax rate, charged to customers whose billing country matches. */
+export interface Tax {
+  id: string;
+  /** Shown on invoices. Unique among active taxes in the same country,
+   *  ignoring case. */
+  name: string;
+  /** A note for your team; not shown to customers. */
+  description: string | null;
+  /** 0–100. */
+  percentage: number;
+  /** ISO 3166-1 alpha-2, upper case (e.g. `"IN"`). */
+  countryCode: string;
+  behavior: TaxBehavior;
+  /** `false` once archived in the dashboard (Settings → Taxes): it no longer
+   *  applies to new invoices. */
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** `taxes.create()` body. */
+export interface CreateTaxInput {
+  /** 1–100 characters. */
+  name: string;
+  /** 0–100. */
+  percentage: number;
+  /** ISO 3166-1 alpha-2 (lower case is accepted). A country name is refused. */
+  countryCode: string;
+  behavior: TaxBehavior;
+  /** Up to 500 characters. */
+  description?: string | null;
+}
+
+/** `taxes.update()` body — PARTIAL: only the fields you send change. */
+export type UpdateTaxInput = Partial<CreateTaxInput>;
+
 /** A catalogue item a composite wraps. */
 export interface CompositeItem {
   id: string;
@@ -1079,7 +1208,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";
 
@@ -1488,6 +1618,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.
@@ -1539,6 +1671,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. */