@clocknext/sdk 0.11.0 → 0.12.1

package/src/resources/signals.ts

@@ -0,0 +1,393 @@
+import type { Transport } from "../http.js";
+import type { Flusher } from "../flusher.js";
+import { newKey } from "../idempotency.js";
+import type {
+  CompositeCompletionInput,
+  CompositeCompletionResult,
+  CreditInput,
+  OutcomeInput,
+  ResolvedConfig,
+  SerializedUnitUsage,
+  Signal,
+  SignalType,
+  TrackResult,
+  UnitInput,
+  UnitTrackResult,
+  UnitUsageList,
+  UsageList,
+  WalletInput,
+} from "../types.js";
+
+/**
+ * Which route each signal type posts to.
+ *
+ * This map IS the migration off `POST /api/v1/usage`. The signal's `type` no
+ * longer travels in the body — it picks the URL, and the server reads the
+ * meter off the path. That is the server's design, not a convenience: a body
+ * can neither omit the meter nor contradict it, so the whole class of "the
+ * `type` field said credit but the fields describe a unit" bug is gone.
+ *
+ * `type` stays on the SDK's own `Signal` objects because it is still the
+ * discriminator callers write and TypeScript narrows on. It just stops being
+ * something we send.
+ */
+const SIGNAL_PATHS: Record<SignalType, string> = {
+  credit: "/api/v1/signal/credit",
+  outcome: "/api/v1/signal/outcome",
+  wallet: "/api/v1/signal/wallet",
+};
+
+/** Unit reports and composite completions are not part of the `Signal` union
+ *  (no model, no tokens), so they carry their paths separately. */
+const UNIT_PATH = "/api/v1/signal/unit";
+const COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
+
+/**
+ * Builds the request body for a typed Signal.
+ *
+ * Two grouping changes from the pre-0.10 `POST /api/v1/usage` body, both of
+ * which the server now requires:
+ *
+ *   usage:     { model, inputTokens, outputTokens, cacheTokens }
+ *   composite: { "<refId>": "<value>" }
+ *
+ * `usage` collects the four fields describing one LLM call. `composite` is the
+ * more consequential one: the tag used to sit at the TOP LEVEL under its own
+ * caller-defined property name, which meant a composite called `model` or
+ * `status` shadowed a real ingest field. Nested, the two namespaces are
+ * separate and that collision is impossible.
+ *
+ * The route is NOT part of this body — see {@link SIGNAL_PATHS}.
+ */
+export function signalToWire(signal: Signal): Record<string, unknown> {
+  const t = signal.tokens;
+  const body: Record<string, unknown> = {
+    customerId: signal.customerId,
+    // `usage` is required on all three model-priced kinds. input/output are
+    // always sent; `cacheTokens` only when provided (the server defaults 0).
+    usage: {
+      model: signal.model,
+      inputTokens: t.input,
+      outputTokens: t.output,
+      ...(t.cache != null ? { cacheTokens: t.cache } : {}),
+    },
+  };
+  if (signal.member) body.member = signal.member;
+  if (signal.custom) body.custom = signal.custom;
+
+  // credit + outcome both resolve their target via the stable `agentKey`.
+  // A wallet signal has none: it meters money at the model's cost rather than
+  // a named entitlement.
+  if (signal.type === "credit" || signal.type === "outcome") {
+    body.agentKey = signal.agentKey;
+  }
+
+  // Outcome runs are grouped by `runId`; `complete` ends the run.
+  if (signal.type === "outcome") {
+    body.runId = signal.runId;
+    if (signal.complete != null) body.complete = signal.complete;
+  }
+
+  // Composite tag, nested under its `refId`. Never set for wallet — the server
+  // accepts and ignores one there, but sending it would only imply a rollup
+  // that will not exist.
+  if (signal.type !== "wallet" && signal.composite) {
+    body.composite = { [signal.composite.ref]: signal.composite.value };
+  }
+
+  // A caller-supplied idempotency key is forwarded verbatim; `track()` fills in
+  // an auto-generated one when none was given.
+  if (signal.idempotencyKey) body.idempotencyKey = signal.idempotencyKey;
+  return body;
+}
+
+/** The fields every `/api/v1/signal/*` response may carry. */
+interface SignalResponse {
+  queued?: boolean;
+  messageId?: string;
+  rawId?: string;
+}
+
+/** Copy the two durability handles onto a result, each only when present. */
+function handles(res: SignalResponse) {
+  return {
+    ...(res.messageId != null ? { messageId: res.messageId } : {}),
+    ...(res.rawId != null ? { rawId: res.rawId } : {}),
+  };
+}
+
+/**
+ * The `signals` resource: record usage signals and read them back.
+ *
+ * In async mode (default), `track()` buffers the signal locally and returns
+ * immediately with `{ status: "buffered" }`. Pass `{ wait: true }` (or
+ * construct the client in `sync` mode) to await the request instead.
+ *
+ * Awaiting the request does NOT mean waiting for a price, and deliberately so.
+ * The server writes every signal to a durable inbox and hands it to a worker,
+ * answering `202` — so `track()` resolves `{ status: "accepted", messageId,
+ * rawId, usageLog: null }`: impossible to lose, not yet billed. Only when the
+ * server prices inline do you get `{ status: "recorded", usageLog }`. Branch on
+ * `status`; never assume `usageLog`.
+ *
+ * Nothing here ever blocks a request thread on billing. That is the point: a
+ * meter that makes the caller wait for pricing has moved your billing system
+ * onto your product's critical path.
+ *
+ * Because of that, a signal the server later REJECTS (unknown `agentKey`, a
+ * model the org has not enabled, no active plan) cannot come back through this
+ * promise — and does not reach `onError` either, since from here that request
+ * succeeded. Such a rejection has no programmatic channel at all: it is
+ * recorded on the workspace's signal log in the ClockNext dashboard, which is
+ * owner-only by design.
+ *
+ * `list()` is the partial check available from code. It returns priced usage
+ * logs with a `status`, so it confirms a signal landed and whether pricing
+ * succeeded — but a signal refused BEFORE pricing never becomes a usage log
+ * and does not appear there.
+ */
+export class Signals {
+  constructor(
+    private readonly transport: Transport,
+    private readonly flusher: Flusher,
+    private readonly cfg: ResolvedConfig,
+  ) {}
+
+  /**
+   * Record one usage signal, to the route its `type` selects:
+   * `POST /api/v1/signal/credit` | `/signal/outcome` | `/signal/wallet`.
+   *
+   * Returns as soon as the signal is buffered (async mode) or the request has
+   * been answered (`{ wait: true }` / sync mode). See {@link TrackResult}: a
+   * resolved promise means "accepted", which is not the same as "billed".
+   */
+  async track(
+    signal: Signal,
+    opts: { wait?: boolean } = {},
+  ): Promise<TrackResult> {
+    const body = signalToWire(signal);
+    // Assign the idempotency key ONCE, here — before the signal is buffered or
+    // sent — so the SAME key rides every retry (Transport-level replay AND a
+    // re-flush of the buffered body). That is what makes a retried signal
+    // dedup server-side instead of double-recording (see idempotency.ts, AD-4).
+    const idempotencyKey =
+      typeof body.idempotencyKey === "string" ? body.idempotencyKey : newKey();
+    body.idempotencyKey = idempotencyKey;
+
+    // The key is stamped back onto the SIGNAL, not just the body, because the
+    // signal is what `onError`/`onDrop` receive. Without this, a caller writing
+    // the documented dead-letter path — catch the drop, persist it, resend
+    // later — would resend with a freshly generated key, and the server would
+    // treat it as a second event and bill it twice. The one mechanism that
+    // prevents duplicates has to be reachable from the one hook that handles
+    // failures.
+    const tracked: Signal = { ...signal, idempotencyKey };
+
+    const path = SIGNAL_PATHS[signal.type];
+
+    const sendNow = opts.wait || this.cfg.mode === "sync";
+    if (!sendNow) {
+      // The path is buffered WITH the body. The flusher used to hardcode one
+      // endpoint for everything; now that each meter has its own, a buffered
+      // signal has to remember where it was going or async mode would quietly
+      // keep posting to a route sync mode has already left behind.
+      // A closed client or a full queue discards the signal. Saying
+      // "buffered" there would hand back a success-shaped result for a
+      // billable event that no longer exists.
+      const buffered = this.flusher.enqueue({ path, body, signal: tracked });
+      return buffered
+        ? { status: "buffered", queued: true }
+        : { status: "dropped", queued: false };
+    }
+
+    const res = await this.transport.request<
+      SignalResponse & { usageLog?: TrackResult["usageLog"] }
+    >({
+      method: "POST",
+      path,
+      body,
+      // Best-effort metering opts into retries on transient failures.
+      retry: true,
+      idempotencyKey,
+    });
+    // The server answers one of two ways for a real record, and we must not
+    // flatten them: `202 { queued: true, messageId, rawId }` when it hands the
+    // signal to its durable queue (priced later by a worker — no log yet), or
+    // `200 { usageLog, rawId }` when it prices inline. Either way `rawId` is
+    // the handle on a written, unlosable row.
+    const queued = res.queued === true;
+    return {
+      status: queued ? "accepted" : "recorded",
+      queued,
+      usageLog: res.usageLog ?? null,
+      ...handles(res),
+    };
+  }
+
+  /** Meter a named credit. `POST /api/v1/signal/credit`. */
+  credit(input: CreditInput, opts?: { wait?: boolean }): Promise<TrackResult> {
+    return this.track({ ...input, type: "credit" }, opts);
+  }
+
+  /** Debit the customer's wallet at model cost. `POST /api/v1/signal/wallet`. */
+  wallet(input: WalletInput, opts?: { wait?: boolean }): Promise<TrackResult> {
+    return this.track({ ...input, type: "wallet" }, opts);
+  }
+
+  /** Advance one step of an outcome workflow. `POST /api/v1/signal/outcome`. */
+  outcome(
+    input: OutcomeInput,
+    opts?: { wait?: boolean },
+  ): Promise<TrackResult> {
+    return this.track({ ...input, type: "outcome" }, opts);
+  }
+
+  /**
+   * Recent usage logs + totals for a customer. `GET /api/v1/usage`.
+   *
+   * Still the legacy path, deliberately. The `/api/v1/signal/*` family is
+   * POST-only — it replaced how usage is INGESTED, not how it is read — so
+   * `GET /api/v1/usage` has no successor and is not deprecated. It is also the
+   * only way to prove a signal landed, which matters more now that ingestion
+   * answers `202` for everything.
+   */
+  async list(params: {
+    customerId: string;
+    limit?: number;
+  }): Promise<UsageList> {
+    const res = await this.transport.request<UsageList>({
+      method: "GET",
+      path: "/api/v1/usage",
+      query: { customerId: params.customerId, limit: params.limit },
+    });
+    return { customer: res.customer, totals: res.totals, logs: res.logs };
+  }
+
+  /**
+   * Record one unit-metered event (a fixed-price meter with no tokens),
+   * addressed to a catalog unit by its `agentKey`. Sent immediately — unit
+   * events are not buffered. `POST /api/v1/signal/unit`.
+   *
+   * Two things changed with the move off `POST /api/v1/units`, and both show up
+   * in the return type. The route is now durable (the report lands in an inbox
+   * before it is priced, so a failure parks as Pending and can be retried
+   * instead of losing a billable event) and it answers `202` when it queues —
+   * so this resolves {@link UnitTrackResult}, not a bare `{ unitUsage }`.
+   * Branch on `queued`.
+   */
+  async unit(input: UnitInput): Promise<UnitTrackResult> {
+    const idempotencyKey = input.idempotencyKey ?? newKey();
+    const res = await this.transport.request<
+      SignalResponse & { unitUsage?: SerializedUnitUsage }
+    >({
+      method: "POST",
+      path: UNIT_PATH,
+      idempotencyKey,
+      body: {
+        customerId: input.customerId,
+        agentKey: input.agentKey,
+        ...(input.quantity != null ? { quantity: input.quantity } : {}),
+        ...(input.member ? { member: input.member } : {}),
+        ...(input.composite
+          ? { composite: { [input.composite.ref]: input.composite.value } }
+          : {}),
+        // 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 —
+        // so it bills the allowance down twice, up to `retry.maxAttempts`
+        // times. The route gained idempotency precisely to stop that; not
+        // using it by default would leave the double-charge reachable from the
+        // client instead of the server.
+        idempotencyKey,
+      },
+      // Best-effort metering opts into retries on transient failures.
+      retry: true,
+    });
+    const queued = res.queued === true;
+    return {
+      status: queued ? "accepted" : "recorded",
+      queued,
+      unitUsage: res.unitUsage ?? null,
+      ...handles(res),
+    };
+  }
+
+  /**
+   * Close ONE occurrence of a composite — a distinct tag value.
+   * `POST /api/v1/signal/composite/complete`.
+   *
+   * A composite bundles several credits / outcomes / units and is billed as one
+   * thing. The occurrence opens on the first tagged signal and costs nothing;
+   * this call is the moment it is billed. Only your code knows when the
+   * workflow ended, so this is a DECLARATION, not a hint: tagged signals may
+   * arrive in any order and the occurrence stays open and unbilled until you
+   * say otherwise. Put it on the line before your own `return`.
+   *
+   * EVERY composite needs this, outcome-backed ones included. An outcome's own
+   * `complete: true` closes its RUN and nothing else — it does not close the
+   * composite occurrence the run was tagged into, whatever mix of credits,
+   * outcomes and units that composite wraps. (Earlier versions of this SDK
+   * documented the opposite. Believing it means the occurrence stays ONGOING
+   * forever and is never billed, so if you tag outcome signals with a
+   * `composite`, you must still call this.)
+   *
+   * Closing twice is safe: the second call answers `ALREADY_COMPLETED` and
+   * cannot bill again. Calling it EARLY is also safe — before every entitlement
+   * the composite is restricted to has reported, or while an ADVANCE pool is
+   * full — the server parks the ping and applies it when the blocker clears,
+   * rather than failing it.
+   */
+  async completeComposite(
+    input: CompositeCompletionInput,
+  ): Promise<CompositeCompletionResult> {
+    const idempotencyKey = input.idempotencyKey ?? newKey();
+    const res = await this.transport.request<
+      SignalResponse & {
+        status?: "COMPLETED" | "ALREADY_COMPLETED";
+        composite?: CompositeCompletionResult["composite"];
+        value?: string | null;
+      }
+    >({
+      method: "POST",
+      path: COMPOSITE_COMPLETE_PATH,
+      idempotencyKey,
+      body: {
+        customerId: input.customerId,
+        composite: { [input.composite.ref]: input.composite.value },
+        // 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
+        // idempotency, and an un-keyed replay still writes a redundant inbox
+        // row. Keying it collapses the retry into the one attempt it is.
+        idempotencyKey,
+      },
+      retry: true,
+    });
+    const queued = res.queued === true;
+    return {
+      delivery: queued ? "accepted" : "recorded",
+      queued,
+      ...(res.status != null ? { status: res.status } : {}),
+      ...(res.composite !== undefined ? { composite: res.composite } : {}),
+      ...(res.value !== undefined ? { value: res.value } : {}),
+      ...handles(res),
+    };
+  }
+
+  /**
+   * A customer's unit balances + recent unit events. `GET /api/v1/units`.
+   *
+   * Legacy path for the same reason as {@link list}: the signal family is
+   * POST-only, so the read side has no successor and is not deprecated.
+   */
+  unitUsage(params: {
+    customerId: string;
+    limit?: number;
+  }): Promise<UnitUsageList> {
+    return this.transport.request<UnitUsageList>({
+      method: "GET",
+      path: "/api/v1/units",
+      query: { customerId: params.customerId, limit: params.limit },
+    });
+  }
+}

package/src/resources/units.ts

@@ -0,0 +1,76 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type {
+  CreateUnitInput,
+  Unit,
+  UnitDetail,
+  UpdateUnitInput,
+} from "../types.js";
+
+/**
+ * The `units` resource — manage the org's unit *types* (the catalog): named,
+ * quantity-priced meters (FLAT / SLAB / VOLUME). Record consumption against a
+ * unit with `signals.unit()`. `/api/v1/units-catalog`.
+ */
+export class Units {
+  constructor(private readonly transport: Transport) {}
+
+  /** List unit 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<Unit[]> {
+    const res = await this.transport.request<{ units: Unit[] }>({
+      method: "GET",
+      path: "/api/v1/units-catalog",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.units, params.active);
+  }
+
+  /** Create a unit type. `POST /api/v1/units-catalog`. */
+  async create(input: CreateUnitInput): Promise<Unit> {
+    const res = await this.transport.request<{ unit: Unit }>({
+      method: "POST",
+      path: "/api/v1/units-catalog",
+      body: input,
+    });
+    return res.unit;
+  }
+
+  /** Fetch one unit type with stats. `GET /api/v1/units-catalog/:id`. */
+  async get(id: string): Promise<UnitDetail> {
+    const res = await this.transport.request<{ unit: UnitDetail }>({
+      method: "GET",
+      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`,
+    });
+    return res.unit;
+  }
+
+  /** Update a unit type's definition. `PATCH /api/v1/units-catalog/:id`. */
+  async update(id: string, input: UpdateUnitInput): Promise<Unit> {
+    const res = await this.transport.request<{ unit: Unit }>({
+      method: "PATCH",
+      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.unit;
+  }
+
+  /** Activate or deactivate a unit type. */
+  async setActive(id: string, isActive: boolean): Promise<Unit> {
+    const res = await this.transport.request<{ unit: Unit }>({
+      method: "PATCH",
+      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`,
+      body: { isActive },
+    });
+    return res.unit;
+  }
+
+  /** Delete a unit type. */
+  async delete(id: string): Promise<void> {
+    await this.transport.request({
+      method: "DELETE",
+      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`,
+    });
+  }
+}

package/src/resources/webhooks.ts

@@ -0,0 +1,37 @@
+import type { Transport } from "../http.js";
+import type { ThresholdKind, UpsertWebhookInput, Webhook } from "../types.js";
+
+/**
+ * The `webhooks` resource — threshold alerts. At most one webhook per kind
+ * (CREDIT / OUTCOME / WALLET); posting a kind again upserts it. `/api/v1/webhooks`.
+ */
+export class Webhooks {
+  constructor(private readonly transport: Transport) {}
+
+  /** List configured webhooks. `GET /api/v1/webhooks`. */
+  async list(): Promise<Webhook[]> {
+    const res = await this.transport.request<{ webhooks: Webhook[] }>({
+      method: "GET",
+      path: "/api/v1/webhooks",
+    });
+    return res.webhooks;
+  }
+
+  /** Create or replace the webhook for a kind. `POST /api/v1/webhooks`. */
+  async upsert(input: UpsertWebhookInput): Promise<Webhook> {
+    const res = await this.transport.request<{ webhook: Webhook }>({
+      method: "POST",
+      path: "/api/v1/webhooks",
+      body: input,
+    });
+    return res.webhook;
+  }
+
+  /** Delete the webhook for a kind (idempotent). `DELETE /api/v1/webhooks/:kind`. */
+  async delete(kind: ThresholdKind): Promise<void> {
+    await this.transport.request({
+      method: "DELETE",
+      path: `/api/v1/webhooks/${encodeURIComponent(kind)}`,
+    });
+  }
+}

package/src/resources/workspace.ts

@@ -0,0 +1,33 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type { Model, WorkspaceIdentity } from "../types.js";
+
+/**
+ * The `workspace` resource — read-only introspection of the org behind the API
+ * key. Grounds an integration (which workspace, and is it `sandbox` or `live`?)
+ * and lists the models it may meter against. `/api/v1/me`, `/api/v1/models`.
+ */
+export class Workspace {
+  constructor(private readonly transport: Transport) {}
+
+  /** Identify the org + key behind the request, incl. `sandbox` | `live`. */
+  me(): Promise<WorkspaceIdentity> {
+    return this.transport.request<WorkspaceIdentity>({
+      method: "GET",
+      path: "/api/v1/me",
+    });
+  }
+
+  /** The org's enabled models with live prices. `{ active: true }` returns only
+   *  the models that can be metered right now.
+   *  `{ active: false }` returns only archived ones; omitting it returns
+   *  both. See `activeQuery` — the API itself only supports `true`. */
+  async models(params: { active?: boolean } = {}): Promise<Model[]> {
+    const res = await this.transport.request<{ models: Model[] }>({
+      method: "GET",
+      path: "/api/v1/models",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.models, params.active);
+  }
+}

package/src/retry.ts

@@ -0,0 +1,56 @@
+import { ClockNextError } from "./errors.js";
+
+/**
+ * Retry classification + backoff. Mirrors the convergent industry policy
+ * (Stripe / Stainless clients): retry transient transport failures
+ * (network, timeout, 408/409/429/5xx); never retry deterministic 4xx
+ * (400/401/404 and 422 validation/plan/allowance). Exponential backoff with
+ * equal jitter, honoring a server `Retry-After`. The Transport additionally
+ * gates retries by request safety (GET/DELETE, or a write that explicitly
+ * opts in).
+ */
+
+/** Whether an error should be retried. NetworkError/Server/RateLimit/Conflict
+ *  carry `retryable: true`; everything else is permanent. */
+export function isRetryable(error: unknown): boolean {
+  return error instanceof ClockNextError && error.retryable;
+}
+
+/** Parses `Retry-After` (seconds or HTTP-date) and `retry-after-ms` headers. */
+export function parseRetryAfter(headers: Headers): number | undefined {
+  const ms = headers.get("retry-after-ms");
+  if (ms) {
+    const n = Number(ms);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  const ra = headers.get("retry-after");
+  if (ra) {
+    const secs = Number(ra);
+    if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
+    const date = Date.parse(ra);
+    if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  }
+  return undefined;
+}
+
+/**
+ * Backoff for a given attempt (1-based). Exponential `base * 2^(attempt-1)`,
+ * capped at `maxDelayMs`, with equal jitter (×[0.5, 1.0]). A server-provided
+ * `retryAfterMs` overrides the computed value.
+ */
+export function computeBackoff(
+  attempt: number,
+  opts: { baseDelayMs: number; maxDelayMs: number },
+  retryAfterMs?: number,
+  rand: () => number = Math.random,
+): number {
+  if (retryAfterMs != null) return Math.min(retryAfterMs, opts.maxDelayMs);
+  const raw = opts.baseDelayMs * Math.pow(2, Math.max(0, attempt - 1));
+  const capped = Math.min(raw, opts.maxDelayMs);
+  // Equal jitter: a random point in [0.5, 1.0] of the capped delay.
+  return Math.round(capped * (0.5 + rand() * 0.5));
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}