@clocknext/sdk 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -185,12 +185,38 @@ interface SerializedUsageLog {
     balance: UsageBalance | null;
     createdAt: string;
 }
-/** Result of a single signal send (sync mode, or `{ wait: true }`). */
+/**
+ * Result of a single signal send (sync mode, or `{ wait: true }`).
+ *
+ * `queued: true` has TWO causes, and they are not the same thing:
+ * 1. **Client-side buffering** (async mode, no `wait`) — the signal is in this
+ *    process's buffer and has not been sent. No `messageId`.
+ * 2. **Server-side durable hand-off** — the request WAS sent and the server
+ *    answered `202 Accepted`, having enqueued it for a worker to price. Carries
+ *    a `messageId`. `usageLog` is null: the log does not exist yet.
+ *
+ * In case 2 the signal is accepted but **not yet billed**, and it has only been
+ * shallowly validated. A bad `agentKey`, a customer with no matching plan, or an
+ * exhausted allowance is detected by the worker LATER and never surfaces here —
+ * the signal is simply dropped. A `202` therefore means "accepted", never
+ * "recorded". To confirm a signal actually landed, read it back with
+ * `signals.list({ customerId })`.
+ *
+ * When the server has no queue configured it prices inline instead and returns
+ * `queued: false` with a populated `usageLog`, validating synchronously.
+ */
 interface TrackResult {
-    /** True when the signal was buffered (async mode) and not yet sent. */
+    /** True when the signal has not been priced yet — either buffered locally
+     *  (async mode) or accepted for asynchronous processing by the server. */
     queued: boolean;
-    /** The computed usage log — present only once the signal has been sent. */
+    /** The computed usage log. Non-null ONLY when the server priced the signal
+     *  inline (`queued: false`); null on a `202` hand-off and absent while the
+     *  signal sits in the client-side buffer. */
     usageLog?: SerializedUsageLog | null;
+    /** The server's durable-queue message id, present only on a `202` hand-off
+     *  (server-side queueing). Absent for client-side buffering and for inline
+     *  pricing. */
+    messageId?: string;
 }
 interface UsageList {
     customer: {
@@ -279,7 +305,9 @@ interface OutcomeBalance {
     granted: number;
     remaining: number;
     /** Each step's `agentKey` is what `signals.outcome()` and the outcome adjust
-     *  API use to address this outcome (outcomes have no key of their own). */
+     *  API use to address this outcome at runtime. The outcome also has its own
+     *  separate key ({@link Outcome.agentKey}), but neither of those APIs accepts
+     *  it — it identifies the outcome in the catalogue, not in a signal. */
     steps: {
         id: string;
         name: string;
@@ -734,10 +762,12 @@ interface CreditAdjustInput {
     notes?: string;
 }
 /** Grant/claw an outcome balance. `delta` is a non-zero whole number; floored at
- *  0. The outcome is addressed by a STEP's `agentKey` (outcomes have no key of
- *  their own). */
+ *  0. The outcome is addressed here by a STEP's `agentKey`, which resolves to its
+ *  parent outcome — NOT by the outcome's own `agentKey` ({@link Outcome.agentKey}),
+ *  which this endpoint does not accept. */
 interface OutcomeAdjustInput {
-    /** An outcome step's stable agent key — identifies the parent outcome. */
+    /** An outcome STEP's stable agent key — identifies the parent outcome. Passing
+     *  the outcome's own `agentKey` here fails with `422`. */
     agentKey: string;
     delta: number;
     notes?: string;
@@ -846,6 +876,17 @@ interface OutcomeStepInput {
 interface Outcome {
     id: string;
     name: string;
+    /**
+     * The OUTCOME's own stable agent key — its durable identity, mirroring
+     * {@link Credit.agentKey}. Lowercased `[a-z0-9._-]`, max 80 chars, unique per
+     * organisation. A rename never changes it.
+     *
+     * Distinct from each step's `agentKey` in `steps`, and in a SEPARATE
+     * namespace: usage is always reported against a STEP's key
+     * (`signals.outcome({ agentKey })`), never this one. This key identifies the
+     * outcome itself when creating or updating it.
+     */
+    agentKey: string;
     description: string | null;
     isActive: boolean;
     marginPercent: number;
@@ -874,6 +915,15 @@ interface OutcomeDetail extends Outcome {
 }
 interface CreateOutcomeInput {
     name: string;
+    /**
+     * The OUTCOME's own stable agent key — REQUIRED. Lowercased `[a-z0-9._-]`,
+     * max 80 chars, unique per organisation (the server lowercases and trims it).
+     *
+     * Separate namespace from `steps[].agentKey`: this names the outcome, a step
+     * key names a step and is what `signals.outcome()` reports against. Omitting
+     * it is rejected with a `ValidationError` (400).
+     */
+    agentKey: string;
     basePrice: number;
     marginPercent: number;
     pricePerOutcome: number;
@@ -1280,8 +1330,14 @@ declare class Invoices {
 
 /**
  * The `outcomes` resource — manage the org's outcome *types* (the catalog). An
- * outcome is a multi-step workflow; each step has a stable `agentKey` you pass
- * to `signals.outcome()`. `/api/v1/outcomes`.
+ * 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.
  */
 declare class Outcomes {
     private readonly transport;
@@ -1431,15 +1487,31 @@ declare function signalToWire(signal: Signal): Record<string, unknown>;
 /**
  * The `signals` resource: record usage signals and read them back.
  *
- * In async mode (default), `track()` buffers the signal and returns immediately
- * with `{ queued: true }`. Pass `{ wait: true }` (or construct the client in
- * `sync` mode) to await the send and receive the computed `usageLog`.
+ * In async mode (default), `track()` buffers the signal locally and returns
+ * immediately with `{ queued: true }`. Pass `{ wait: true }` (or construct the
+ * client in `sync` mode) to await the request.
+ *
+ * Awaiting the request does NOT guarantee a priced result. Where the server has
+ * a durable queue configured it answers `202` and prices the signal in a worker,
+ * so `track()` resolves `{ queued: true, messageId, usageLog: null }` — accepted,
+ * not yet billed, and validated only later (a bad `agentKey` is dropped there,
+ * silently). Only when the server prices inline do you get
+ * `{ queued: false, usageLog }`. Branch on `queued`; never assume `usageLog`.
+ * `verify()` is the way to validate and price a signal synchronously, and
+ * `list()` is how you confirm one actually landed.
  */
 declare class Signals {
     private readonly transport;
     private readonly flusher;
     private readonly cfg;
     constructor(transport: Transport, flusher: Flusher, cfg: ResolvedConfig);
+    /**
+     * Record one usage signal. `POST /api/v1/usage`.
+     *
+     * 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".
+     */
     track(signal: Signal, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;

package/dist/index.d.ts

@@ -185,12 +185,38 @@ interface SerializedUsageLog {
     balance: UsageBalance | null;
     createdAt: string;
 }
-/** Result of a single signal send (sync mode, or `{ wait: true }`). */
+/**
+ * Result of a single signal send (sync mode, or `{ wait: true }`).
+ *
+ * `queued: true` has TWO causes, and they are not the same thing:
+ * 1. **Client-side buffering** (async mode, no `wait`) — the signal is in this
+ *    process's buffer and has not been sent. No `messageId`.
+ * 2. **Server-side durable hand-off** — the request WAS sent and the server
+ *    answered `202 Accepted`, having enqueued it for a worker to price. Carries
+ *    a `messageId`. `usageLog` is null: the log does not exist yet.
+ *
+ * In case 2 the signal is accepted but **not yet billed**, and it has only been
+ * shallowly validated. A bad `agentKey`, a customer with no matching plan, or an
+ * exhausted allowance is detected by the worker LATER and never surfaces here —
+ * the signal is simply dropped. A `202` therefore means "accepted", never
+ * "recorded". To confirm a signal actually landed, read it back with
+ * `signals.list({ customerId })`.
+ *
+ * When the server has no queue configured it prices inline instead and returns
+ * `queued: false` with a populated `usageLog`, validating synchronously.
+ */
 interface TrackResult {
-    /** True when the signal was buffered (async mode) and not yet sent. */
+    /** True when the signal has not been priced yet — either buffered locally
+     *  (async mode) or accepted for asynchronous processing by the server. */
     queued: boolean;
-    /** The computed usage log — present only once the signal has been sent. */
+    /** The computed usage log. Non-null ONLY when the server priced the signal
+     *  inline (`queued: false`); null on a `202` hand-off and absent while the
+     *  signal sits in the client-side buffer. */
     usageLog?: SerializedUsageLog | null;
+    /** The server's durable-queue message id, present only on a `202` hand-off
+     *  (server-side queueing). Absent for client-side buffering and for inline
+     *  pricing. */
+    messageId?: string;
 }
 interface UsageList {
     customer: {
@@ -279,7 +305,9 @@ interface OutcomeBalance {
     granted: number;
     remaining: number;
     /** Each step's `agentKey` is what `signals.outcome()` and the outcome adjust
-     *  API use to address this outcome (outcomes have no key of their own). */
+     *  API use to address this outcome at runtime. The outcome also has its own
+     *  separate key ({@link Outcome.agentKey}), but neither of those APIs accepts
+     *  it — it identifies the outcome in the catalogue, not in a signal. */
     steps: {
         id: string;
         name: string;
@@ -734,10 +762,12 @@ interface CreditAdjustInput {
     notes?: string;
 }
 /** Grant/claw an outcome balance. `delta` is a non-zero whole number; floored at
- *  0. The outcome is addressed by a STEP's `agentKey` (outcomes have no key of
- *  their own). */
+ *  0. The outcome is addressed here by a STEP's `agentKey`, which resolves to its
+ *  parent outcome — NOT by the outcome's own `agentKey` ({@link Outcome.agentKey}),
+ *  which this endpoint does not accept. */
 interface OutcomeAdjustInput {
-    /** An outcome step's stable agent key — identifies the parent outcome. */
+    /** An outcome STEP's stable agent key — identifies the parent outcome. Passing
+     *  the outcome's own `agentKey` here fails with `422`. */
     agentKey: string;
     delta: number;
     notes?: string;
@@ -846,6 +876,17 @@ interface OutcomeStepInput {
 interface Outcome {
     id: string;
     name: string;
+    /**
+     * The OUTCOME's own stable agent key — its durable identity, mirroring
+     * {@link Credit.agentKey}. Lowercased `[a-z0-9._-]`, max 80 chars, unique per
+     * organisation. A rename never changes it.
+     *
+     * Distinct from each step's `agentKey` in `steps`, and in a SEPARATE
+     * namespace: usage is always reported against a STEP's key
+     * (`signals.outcome({ agentKey })`), never this one. This key identifies the
+     * outcome itself when creating or updating it.
+     */
+    agentKey: string;
     description: string | null;
     isActive: boolean;
     marginPercent: number;
@@ -874,6 +915,15 @@ interface OutcomeDetail extends Outcome {
 }
 interface CreateOutcomeInput {
     name: string;
+    /**
+     * The OUTCOME's own stable agent key — REQUIRED. Lowercased `[a-z0-9._-]`,
+     * max 80 chars, unique per organisation (the server lowercases and trims it).
+     *
+     * Separate namespace from `steps[].agentKey`: this names the outcome, a step
+     * key names a step and is what `signals.outcome()` reports against. Omitting
+     * it is rejected with a `ValidationError` (400).
+     */
+    agentKey: string;
     basePrice: number;
     marginPercent: number;
     pricePerOutcome: number;
@@ -1280,8 +1330,14 @@ declare class Invoices {
 
 /**
  * The `outcomes` resource — manage the org's outcome *types* (the catalog). An
- * outcome is a multi-step workflow; each step has a stable `agentKey` you pass
- * to `signals.outcome()`. `/api/v1/outcomes`.
+ * 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.
  */
 declare class Outcomes {
     private readonly transport;
@@ -1431,15 +1487,31 @@ declare function signalToWire(signal: Signal): Record<string, unknown>;
 /**
  * The `signals` resource: record usage signals and read them back.
  *
- * In async mode (default), `track()` buffers the signal and returns immediately
- * with `{ queued: true }`. Pass `{ wait: true }` (or construct the client in
- * `sync` mode) to await the send and receive the computed `usageLog`.
+ * In async mode (default), `track()` buffers the signal locally and returns
+ * immediately with `{ queued: true }`. Pass `{ wait: true }` (or construct the
+ * client in `sync` mode) to await the request.
+ *
+ * Awaiting the request does NOT guarantee a priced result. Where the server has
+ * a durable queue configured it answers `202` and prices the signal in a worker,
+ * so `track()` resolves `{ queued: true, messageId, usageLog: null }` — accepted,
+ * not yet billed, and validated only later (a bad `agentKey` is dropped there,
+ * silently). Only when the server prices inline do you get
+ * `{ queued: false, usageLog }`. Branch on `queued`; never assume `usageLog`.
+ * `verify()` is the way to validate and price a signal synchronously, and
+ * `list()` is how you confirm one actually landed.
  */
 declare class Signals {
     private readonly transport;
     private readonly flusher;
     private readonly cfg;
     constructor(transport: Transport, flusher: Flusher, cfg: ResolvedConfig);
+    /**
+     * Record one usage signal. `POST /api/v1/usage`.
+     *
+     * 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".
+     */
     track(signal: Signal, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;

package/dist/index.js

@@ -227,7 +227,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.7.0" ;
+var SDK_VERSION = "0.8.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -887,6 +887,13 @@ var Signals = class {
   transport;
   flusher;
   cfg;
+  /**
+   * Record one usage signal. `POST /api/v1/usage`.
+   *
+   * 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, opts = {}) {
     const body = signalToWire(signal);
     if (body.idempotencyKey == null) body.idempotencyKey = newKey();
@@ -903,8 +910,9 @@ var Signals = class {
       retry: true
     });
     return {
-      queued: false,
-      usageLog: res.usageLog ?? null
+      queued: res.queued === true,
+      usageLog: res.usageLog ?? null,
+      ...res.messageId != null ? { messageId: res.messageId } : {}
     };
   }
   /**