@clocknext/sdk 0.7.0 → 0.10.0

package/dist/index.js

@@ -119,7 +119,8 @@ var Flusher = class {
     try {
       await this.transport.request({
         method: "POST",
-        path: "/api/v1/usage",
+        // Per-item, not per-Flusher: one route per meter. See `QueuedSignal`.
+        path: item.path,
         body: item.body,
         // Best-effort metering opts into retries on transient failures.
         retry: true
@@ -227,7 +228,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.7.0" ;
+var SDK_VERSION = "0.10.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -322,6 +323,36 @@ var Transport = class {
   }
 };
 
+// src/resources/composites.ts
+var Composites = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** List composites. Pass `{ active: true }` for only the ones a signal can
+   *  still be tagged with — the default list INCLUDES archived ones, which
+   *  keep every row they already own. */
+  async list(params = {}) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: "/api/v1/composites",
+      query: {
+        active: params.active === void 0 ? void 0 : String(params.active)
+      }
+    });
+    return res.composites;
+  }
+  /** Create a composite. `POST /api/v1/composites`. */
+  async create(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/composites",
+      body: input
+    });
+    return res.composite;
+  }
+};
+
 // src/resources/credits.ts
 var Credits = class {
   constructor(transport) {
@@ -504,7 +535,7 @@ var Customers = class {
     });
     return res.members;
   }
-  /** Add a member to a customer. Duplicate `employeeId` → ConflictError. */
+  /** Add a member to a customer. Duplicate `email` → ConflictError. */
   async addMember(id, input) {
     const res = await this.transport.request({
       method: "POST",
@@ -513,7 +544,7 @@ var Customers = class {
     });
     return res.member;
   }
-  /** Update a member's profile (role is fixed). `PATCH …/:id/members/:memberId`. */
+  /** Update a member's profile. Duplicate `email` → ConflictError. `PATCH …/:id/members/:memberId`. */
   async updateMember(id, memberId, input) {
     const res = await this.transport.request({
       method: "PATCH",
@@ -522,12 +553,13 @@ var Customers = class {
     });
     return res.member;
   }
-  /** Remove a member from a customer. `DELETE …/:id/members/:memberId`. */
+  /** Remove a member from a customer, returning who was removed. `DELETE …/:id/members/:memberId`. */
   async removeMember(id, memberId) {
-    await this.transport.request({
+    const res = await this.transport.request({
       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`. */
@@ -853,18 +885,28 @@ function newKey() {
 }
 
 // src/resources/signals.ts
+var SIGNAL_PATHS = {
+  credit: "/api/v1/signal/credit",
+  outcome: "/api/v1/signal/outcome",
+  wallet: "/api/v1/signal/wallet"
+};
+var UNIT_PATH = "/api/v1/signal/unit";
+var COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
 function signalToWire(signal) {
+  const t = signal.tokens;
   const body = {
     customerId: signal.customerId,
-    type: signal.type,
-    model: signal.model
+    // `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;
-  const t = signal.tokens;
-  body.inputTokens = t.input;
-  body.outputTokens = t.output;
-  if (t.cache != null) body.cacheTokens = t.cache;
   if (signal.type === "credit" || signal.type === "outcome") {
     body.agentKey = signal.agentKey;
   }
@@ -872,12 +914,18 @@ function signalToWire(signal) {
     body.runId = signal.runId;
     if (signal.complete != null) body.complete = signal.complete;
   }
-  if (signal.type !== "wallet" && signal.metric) {
-    body[signal.metric.ref] = signal.metric.value;
+  if (signal.type !== "wallet" && signal.composite) {
+    body.composite = { [signal.composite.ref]: signal.composite.value };
   }
   if (signal.idempotencyKey) body.idempotencyKey = signal.idempotencyKey;
   return body;
 }
+function handles(res) {
+  return {
+    ...res.messageId != null ? { messageId: res.messageId } : {},
+    ...res.rawId != null ? { rawId: res.rawId } : {}
+  };
+}
 var Signals = class {
   constructor(transport, flusher, cfg) {
     this.transport = transport;
@@ -887,56 +935,79 @@ var Signals = class {
   transport;
   flusher;
   cfg;
+  /**
+   * 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, opts = {}) {
     const body = signalToWire(signal);
     if (body.idempotencyKey == null) body.idempotencyKey = newKey();
+    const path = SIGNAL_PATHS[signal.type];
     const sendNow = opts.wait || this.cfg.mode === "sync";
     if (!sendNow) {
-      this.flusher.enqueue({ body, signal });
+      this.flusher.enqueue({ path, body, signal });
       return { queued: true };
     }
     const res = await this.transport.request({
       method: "POST",
-      path: "/api/v1/usage",
+      path,
       body,
       // Best-effort metering opts into retries on transient failures.
       retry: true
     });
     return {
-      queued: false,
-      usageLog: res.usageLog ?? null
+      queued: res.queued === true,
+      usageLog: res.usageLog ?? null,
+      ...handles(res)
     };
   }
   /**
    * Validate + price a signal WITHOUT recording it (server `dryRun`). Returns
    * the projected usage log so an integration can preflight before sending real
    * traffic — no inbox row, wallet / outcome writes, or webhooks fire.
+   *
+   * Only the model-priced kinds support this. A dry run is not offered for unit
+   * reports or composite completions, and the server REJECTS the flag on those
+   * routes rather than accepting and ignoring it — which is why there is no
+   * dry-run path through `unit()` or `completeComposite()`.
    */
   async verify(signal) {
     const body = signalToWire(signal);
     body.dryRun = true;
     const res = await this.transport.request({
       method: "POST",
-      path: "/api/v1/usage",
+      path: SIGNAL_PATHS[signal.type],
       body,
       // A dry run writes nothing, so it is always safe to retry.
       retry: true
     });
     return res.usageLog ?? null;
   }
-  /** Meter a named credit. */
+  /** Meter a named credit. `POST /api/v1/signal/credit`. */
   credit(input, opts) {
     return this.track({ ...input, type: "credit" }, opts);
   }
-  /** Debit the customer's wallet at model cost. */
+  /** Debit the customer's wallet at model cost. `POST /api/v1/signal/wallet`. */
   wallet(input, opts) {
     return this.track({ ...input, type: "wallet" }, opts);
   }
-  /** Advance one step of an outcome workflow. */
+  /** Advance one step of an outcome workflow. `POST /api/v1/signal/outcome`. */
   outcome(input, opts) {
     return this.track({ ...input, type: "outcome" }, opts);
   }
-  /** Recent usage logs + totals for a customer. `GET /api/v1/usage`. */
+  /**
+   * 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) {
     const res = await this.transport.request({
       method: "GET",
@@ -948,22 +1019,94 @@ var Signals = class {
   /**
    * 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/units`.
+   * 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) {
-    return this.transport.request({
+    const res = await this.transport.request({
       method: "POST",
-      path: "/api/v1/units",
+      path: UNIT_PATH,
       body: {
         customerId: input.customerId,
         agentKey: input.agentKey,
-        ...input.member ? { member: input.member } : {}
+        ...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: input.idempotencyKey ?? newKey()
       },
       // Best-effort metering opts into retries on transient failures.
       retry: true
     });
+    return {
+      queued: res.queued === true,
+      unitUsage: res.unitUsage ?? null,
+      ...handles(res)
+    };
   }
-  /** A customer's unit balances + recent unit events. `GET /api/v1/units`. */
+  /**
+   * 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`.
+   *
+   * An OUTCOME never needs this — its own `complete: true` closes its run and
+   * the matching occurrence together. Credits and units have no "done" signal
+   * of their own, so this is theirs.
+   *
+   * 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) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: COMPOSITE_COMPLETE_PATH,
+      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: input.idempotencyKey ?? newKey()
+      },
+      retry: true
+    });
+    return {
+      queued: res.queued === true,
+      ...res.status != null ? { status: res.status } : {},
+      ...res.composite !== void 0 ? { composite: res.composite } : {},
+      ...res.value !== void 0 ? { 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) {
     return this.transport.request({
       method: "GET",
@@ -1107,6 +1250,8 @@ var ClockNext = class {
   payments;
   /** Manage the credit-type catalog. */
   credits;
+  /** Manage the composite catalog — bundles billed as one thing. */
+  composites;
   /** Manage the outcome-type catalog. */
   outcomes;
   /** Manage the unit-type catalog. */
@@ -1135,6 +1280,7 @@ var ClockNext = class {
     this.invoices = new Invoices(transport);
     this.payments = new Payments(transport);
     this.credits = new Credits(transport);
+    this.composites = new Composites(transport);
     this.outcomes = new Outcomes(transport);
     this.units = new Units(transport);
     this.webhooks = new Webhooks(transport);