@clocknext/sdk 0.11.0 → 0.12.1

package/dist/index.cjs

@@ -1,17 +1,145 @@
 'use strict';
 
+// src/errors.ts
+var ClockNextError = class extends Error {
+  /** HTTP status, when the failure came from a server response. */
+  status;
+  /** Whether the SDK considers this failure worth retrying. */
+  retryable;
+  /**
+   * The server's machine-readable code, when it sent one. Branch on this in
+   * preference to `.message`, which is human copy and may be reworded.
+   */
+  code;
+  /**
+   * The idempotency key of the request that failed, for metering calls.
+   *
+   * This is what makes a dead-letter retry safe: re-send the failed signal with
+   * this SAME key and the server deduplicates it instead of billing twice. A
+   * fresh key would double-bill, so never generate one when replaying.
+   */
+  idempotencyKey;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.status = opts.status;
+    this.retryable = opts.retryable ?? false;
+    this.code = opts.code;
+    this.idempotencyKey = opts.idempotencyKey;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthError = class extends ClockNextError {
+};
+var ForbiddenError = class extends ClockNextError {
+};
+var ValidationError = class extends ClockNextError {
+};
+var NotFoundError = class extends ClockNextError {
+};
+var PlanError = class extends ClockNextError {
+};
+var AllowanceError = class extends ClockNextError {
+};
+var ConflictError = class extends ClockNextError {
+};
+var RateLimitError = class extends ClockNextError {
+  retryAfterMs;
+  constructor(message, opts = {}) {
+    super(message, {
+      status: 429,
+      retryable: true,
+      idempotencyKey: opts.idempotencyKey
+    });
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+};
+var ServerError = class extends ClockNextError {
+};
+var NetworkError = class extends ClockNextError {
+  constructor(message, opts = {}) {
+    super(message, { retryable: true, idempotencyKey: opts.idempotencyKey });
+  }
+};
+var FIELD_PATHS = [
+  [/\busage\.inputTokens\b/g, "tokens.input"],
+  [/\busage\.outputTokens\b/g, "tokens.output"],
+  [/\busage\.cacheTokens\b/g, "tokens.cache"],
+  [/\busage\.model\b/g, "model"],
+  // A missing/invalid `usage` block as a whole: the caller's equivalent is
+  // `tokens` (plus `model`, which the SDK hoists to the top level).
+  [/^usage:/, "tokens:"]
+];
+function translateFieldPaths(message) {
+  let out = message;
+  for (const [pattern, replacement] of FIELD_PATHS) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+var ALLOWANCE_MESSAGE = /\binsufficient\b|\bno allowance left\b|\bno slots left\b|\boutcomes remaining\b|\btop up the (?:allowance|balance)\b/i;
+function isAllowanceFailure(message, code) {
+  if (code) return code === "ALLOWANCE_EXHAUSTED";
+  return ALLOWANCE_MESSAGE.test(message);
+}
+var TRANSIENT_CONFLICT = /could not resolve the idempotent request/i;
+function errorFromResponse(status, message, retryAfterMs, meta = {}) {
+  const raw = message || `Request failed with status ${status}.`;
+  const { code, idempotencyKey } = meta;
+  const opts = { status, code, idempotencyKey };
+  if (status === 400) {
+    return new ValidationError(translateFieldPaths(raw), opts);
+  }
+  if (status === 401) return new AuthError(raw, opts);
+  if (status === 403) return new ForbiddenError(raw, opts);
+  if (status === 404) return new NotFoundError(raw, opts);
+  if (status === 408) return new ClockNextError(raw, { ...opts, retryable: true });
+  if (status === 409) {
+    return new ConflictError(raw, {
+      ...opts,
+      retryable: code === "IDEMPOTENCY_UNRESOLVED" || TRANSIENT_CONFLICT.test(raw)
+    });
+  }
+  if (status === 422) {
+    return isAllowanceFailure(raw, code) ? new AllowanceError(raw, opts) : new PlanError(raw, opts);
+  }
+  if (status === 429) return new RateLimitError(raw, { retryAfterMs, idempotencyKey });
+  if (status >= 500) return new ServerError(raw, { ...opts, retryable: true });
+  return new ClockNextError(raw, opts);
+}
+
 // src/config.ts
 var DEFAULT_BASE_URL = "https://payments.clocknext.com";
+function defaultOnError(error, signal) {
+  const what = signal ? `${signal.type} signal` : "request";
+  const who = signal ? ` customer=${signal.customerId}` : "";
+  const key = signal?.idempotencyKey != null ? ` idempotencyKey=${signal.idempotencyKey}` : "";
+  console.error(
+    `[clocknext] ${what} permanently failed and was NOT recorded.${who}${key}`,
+    error
+  );
+  console.error(
+    "[clocknext] Pass `onError` to handle this yourself, or `onError: () => {}` to silence it."
+  );
+}
+function defaultOnDrop(signal, reason) {
+  if (reason === "send_failed") return;
+  const why = reason === "queue_full" ? "the local queue is full \u2014 raise `batch.maxQueueSize` or flush more often" : "the client is closed \u2014 this signal was tracked after `close()`";
+  console.error(
+    `[clocknext] dropped a ${signal.type} signal without sending it: ${why}.`,
+    `customer=${signal.customerId}`
+  );
+}
 function num(value, fallback, min) {
   return typeof value === "number" && Number.isFinite(value) && value >= min ? value : fallback;
 }
 function resolveConfig(config) {
   if (!config.apiKey || typeof config.apiKey !== "string") {
-    throw new Error("ClockNext: `apiKey` is required.");
+    throw new ValidationError("ClockNext: `apiKey` is required.");
   }
   const fetchImpl = config.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
   if (!fetchImpl) {
-    throw new Error(
+    throw new ValidationError(
       "ClockNext: no global `fetch` found. Use Node 18+, or pass a `fetch` implementation."
     );
   }
@@ -33,10 +161,11 @@ function resolveConfig(config) {
     },
     fetch: fetchImpl,
     logger: config.logger ?? {},
-    onError: config.onError,
+    // Both default to loud. See the note above `defaultOnError`.
+    onError: config.onError ?? defaultOnError,
     onFlush: config.onFlush,
     onRetry: config.onRetry,
-    onDrop: config.onDrop
+    onDrop: config.onDrop ?? defaultOnDrop
   };
 }
 
@@ -66,20 +195,25 @@ var Flusher = class {
   timer = null;
   draining = null;
   closed = false;
-  /** Buffer one signal. Drops (with onDrop) when closed or the queue is full. */
+  /**
+   * Buffer one signal. Drops (with onDrop) when closed or the queue is full.
+   * Returns whether it was actually buffered, so `track()` can report a drop
+   * honestly instead of answering "buffered" for a signal it threw away.
+   */
   enqueue(item) {
     if (this.closed) {
-      this.cfg.onDrop?.(item.signal, "send_failed");
-      return;
+      this.cfg.onDrop?.(item.signal, "closed");
+      return false;
     }
     if (this.queue.size() >= this.cfg.batch.maxQueueSize) {
       this.cfg.logger.warn?.("[clocknext] queue full \u2014 dropping signal");
       this.cfg.onDrop?.(item.signal, "queue_full");
-      return;
+      return false;
     }
     this.queue.push(item);
     if (this.queue.size() >= this.cfg.batch.maxSize) void this.flush();
     else this.arm();
+    return true;
   }
   /** Arm the interval timer if it isn't already running. */
   arm() {
@@ -90,21 +224,37 @@ var Flusher = class {
     }, this.cfg.batch.maxIntervalMs);
     this.timer.unref?.();
   }
-  /**
-   * Send everything currently buffered. Overlapping calls share the single
-   * in-progress drain, so total in-flight sends never exceed `maxConcurrency`.
-   */
-  flush() {
+  /** Cancel the interval timer if one is armed. */
+  clearTimer() {
     if (this.timer) {
       clearTimeout(this.timer);
       this.timer = null;
     }
-    if (!this.draining) {
-      this.draining = this.drain().finally(() => {
-        this.draining = null;
-      });
-    }
-    return this.draining;
+  }
+  /**
+   * Send everything buffered at the moment this resolves.
+   *
+   * Overlapping calls CHAIN onto the in-flight drain rather than sharing it.
+   * Sharing looks equivalent and is not: a drain that has already passed its
+   * final `size() > 0` check cannot see a signal enqueued a moment later, so
+   * handing that same promise back would resolve `flush()` — and therefore
+   * `close()` — with the buffer non-empty. Since `close()` has already set
+   * `closed`, `arm()` will not re-arm, and the timer it did arm is `unref`'d,
+   * so the process is free to exit and that signal is simply lost. Chaining
+   * guarantees at least one full drain begins after this call.
+   *
+   * Concurrency is unaffected: drains run one after another, and each one
+   * sends at most `maxConcurrency` signals at a time.
+   */
+  flush() {
+    this.clearTimer();
+    const prior = this.draining ?? Promise.resolve();
+    const tracked = prior.catch(() => {
+    }).then(() => this.drain()).finally(() => {
+      if (this.draining === tracked) this.draining = null;
+    });
+    this.draining = tracked;
+    return tracked;
   }
   /** Drain the buffer in concurrency-bounded waves until it's empty. */
   async drain() {
@@ -125,7 +275,10 @@ var Flusher = class {
         path: item.path,
         body: item.body,
         // Best-effort metering opts into retries on transient failures.
-        retry: true
+        retry: true,
+        // Rides onto any thrown error so `onError` can replay this exact
+        // signal without minting a new key (which would bill it twice).
+        idempotencyKey: typeof item.body.idempotencyKey === "string" ? item.body.idempotencyKey : void 0
       });
       return true;
     } catch (error) {
@@ -141,65 +294,10 @@ var Flusher = class {
   async close() {
     this.closed = true;
     await this.flush();
+    this.clearTimer();
   }
 };
 
-// src/errors.ts
-var ClockNextError = class extends Error {
-  /** HTTP status, when the failure came from a server response. */
-  status;
-  /** Whether the SDK considers this failure worth retrying. */
-  retryable;
-  constructor(message, opts = {}) {
-    super(message);
-    this.name = new.target.name;
-    this.status = opts.status;
-    this.retryable = opts.retryable ?? false;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-var AuthError = class extends ClockNextError {
-};
-var ValidationError = class extends ClockNextError {
-};
-var NotFoundError = class extends ClockNextError {
-};
-var PlanError = class extends ClockNextError {
-};
-var AllowanceError = class extends ClockNextError {
-};
-var ConflictError = class extends ClockNextError {
-};
-var RateLimitError = class extends ClockNextError {
-  retryAfterMs;
-  constructor(message, opts = {}) {
-    super(message, { status: 429, retryable: true });
-    this.retryAfterMs = opts.retryAfterMs;
-  }
-};
-var ServerError = class extends ClockNextError {
-};
-var NetworkError = class extends ClockNextError {
-  constructor(message) {
-    super(message, { retryable: true });
-  }
-};
-function errorFromResponse(status, message, retryAfterMs) {
-  const msg = message || `Request failed with status ${status}.`;
-  const opts = { status };
-  if (status === 400) return new ValidationError(msg, opts);
-  if (status === 401) return new AuthError(msg, opts);
-  if (status === 404) return new NotFoundError(msg, opts);
-  if (status === 408) return new ClockNextError(msg, { ...opts, retryable: true });
-  if (status === 409) return new ConflictError(msg, { ...opts, retryable: true });
-  if (status === 422) {
-    return /insufficient/i.test(msg) ? new AllowanceError(msg, opts) : new PlanError(msg, opts);
-  }
-  if (status === 429) return new RateLimitError(msg, { retryAfterMs });
-  if (status >= 500) return new ServerError(msg, { ...opts, retryable: true });
-  return new ClockNextError(msg, opts);
-}
-
 // src/retry.ts
 function isRetryable(error) {
   return error instanceof ClockNextError && error.retryable;
@@ -230,7 +328,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.11.0" ;
+var SDK_VERSION = "0.12.1" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -274,7 +372,7 @@ var Transport = class {
       });
     } catch (err) {
       const message2 = controller.signal.aborted ? `Request to ${opts.path} timed out after ${this.cfg.timeoutMs}ms.` : `Network error calling ${opts.path}: ${err instanceof Error ? err.message : String(err)}`;
-      throw new NetworkError(message2);
+      throw new NetworkError(message2, { idempotencyKey: opts.idempotencyKey });
     } finally {
       clearTimeout(timer);
     }
@@ -287,21 +385,30 @@ var Transport = class {
       }
     }
     const obj = json ?? {};
-    const isNew = typeof obj === "object" && obj !== null && "statusDetail" in obj;
-    if (isNew) {
+    const meta = { idempotencyKey: opts.idempotencyKey };
+    const isEnveloped = typeof obj === "object" && obj !== null && "statusDetail" in obj;
+    if (isEnveloped) {
       const detail = obj.statusDetail;
       if (res.ok && detail?.status === "SUCCESS") {
         return obj.result ?? {};
       }
       const message2 = detail?.message ?? `Request failed with status ${res.status}.`;
-      throw errorFromResponse(res.status, message2, parseRetryAfter(res.headers));
+      throw errorFromResponse(res.status, message2, parseRetryAfter(res.headers), {
+        ...meta,
+        code: detail?.code
+      });
     }
     const envelope = obj;
     if (res.ok && envelope.ok !== false) {
       return envelope;
     }
     const message = envelope.error ?? text ?? `Request failed with status ${res.status}.`;
-    throw errorFromResponse(res.status, message, parseRetryAfter(res.headers));
+    throw errorFromResponse(
+      res.status,
+      message,
+      parseRetryAfter(res.headers),
+      meta
+    );
   }
   headers(opts) {
     const h = {
@@ -325,6 +432,14 @@ var Transport = class {
   }
 };
 
+// src/filters.ts
+function activeQuery(active) {
+  return active === true ? "true" : void 0;
+}
+function filterByActive(rows, active) {
+  return active === false ? rows.filter((row) => !row.isActive) : rows;
+}
+
 // src/resources/composites.ts
 var Composites = class {
   constructor(transport) {
@@ -333,16 +448,16 @@ var Composites = class {
   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. */
+   *  keep every row they already own.
+   *  `{ active: false }` returns only archived ones; omitting it returns
+   *  both. See `activeQuery` — the API itself only supports `true`. */
   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)
-      }
+      query: { active: activeQuery(params.active) }
     });
-    return res.composites;
+    return filterByActive(res.composites, params.active);
   }
   /** Create a composite. `POST /api/v1/composites`. */
   async create(input) {
@@ -361,14 +476,16 @@ var Credits = class {
     this.transport = transport;
   }
   transport;
-  /** List credit types. Pass `{ active: true }` to only return active ones. */
+  /** List credit 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 = {}) {
     const res = await this.transport.request({
       method: "GET",
       path: "/api/v1/credits",
-      query: { active: params.active === void 0 ? void 0 : String(params.active) }
+      query: { active: activeQuery(params.active) }
     });
-    return res.credits;
+    return filterByActive(res.credits, params.active);
   }
   /** Create a credit type; returns the created credit. `POST /api/v1/credits`. */
   async create(input) {
@@ -659,14 +776,16 @@ var Outcomes = class {
     this.transport = transport;
   }
   transport;
-  /** List outcome types. Pass `{ active: true }` to only return active ones. */
+  /** List outcome 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 = {}) {
     const res = await this.transport.request({
       method: "GET",
       path: "/api/v1/outcomes",
-      query: { active: params.active === void 0 ? void 0 : String(params.active) }
+      query: { active: activeQuery(params.active) }
     });
-    return res.outcomes;
+    return filterByActive(res.outcomes, params.active);
   }
   /** Create an outcome type with its steps. `POST /api/v1/outcomes`. */
   async create(input) {
@@ -742,14 +861,16 @@ var Plans = class {
     this.transport = transport;
   }
   transport;
-  /** List plans, oldest-first. Pass `{ active: true }` to only return active plans. */
+  /** List plans, oldest-first. Pass `{ active: true }` to only return active plans.
+   *  `{ active: false }` returns only archived ones; omitting it returns
+   *  both. See `activeQuery` — the API itself only supports `true`. */
   async list(params = {}) {
     const res = await this.transport.request({
       method: "GET",
       path: "/api/v1/plans",
-      query: { active: params.active === void 0 ? void 0 : String(params.active) }
+      query: { active: activeQuery(params.active) }
     });
-    return res.plans;
+    return filterByActive(res.plans, params.active);
   }
   /** Create a plan. `POST /api/v1/plans`. */
   async create(input) {
@@ -947,22 +1068,27 @@ var Signals = class {
    */
   async track(signal, opts = {}) {
     const body = signalToWire(signal);
-    if (body.idempotencyKey == null) body.idempotencyKey = newKey();
+    const idempotencyKey = typeof body.idempotencyKey === "string" ? body.idempotencyKey : newKey();
+    body.idempotencyKey = idempotencyKey;
+    const tracked = { ...signal, idempotencyKey };
     const path = SIGNAL_PATHS[signal.type];
     const sendNow = opts.wait || this.cfg.mode === "sync";
     if (!sendNow) {
-      this.flusher.enqueue({ path, body, signal });
-      return { queued: true };
+      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({
       method: "POST",
       path,
       body,
       // Best-effort metering opts into retries on transient failures.
-      retry: true
+      retry: true,
+      idempotencyKey
     });
+    const queued = res.queued === true;
     return {
-      queued: res.queued === true,
+      status: queued ? "accepted" : "recorded",
+      queued,
       usageLog: res.usageLog ?? null,
       ...handles(res)
     };
@@ -1009,9 +1135,11 @@ var Signals = class {
    * Branch on `queued`.
    */
   async unit(input) {
+    const idempotencyKey = input.idempotencyKey ?? newKey();
     const res = await this.transport.request({
       method: "POST",
       path: UNIT_PATH,
+      idempotencyKey,
       body: {
         customerId: input.customerId,
         agentKey: input.agentKey,
@@ -1025,13 +1153,15 @@ var Signals = class {
         // 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()
+        idempotencyKey
       },
       // Best-effort metering opts into retries on transient failures.
       retry: true
     });
+    const queued = res.queued === true;
     return {
-      queued: res.queued === true,
+      status: queued ? "accepted" : "recorded",
+      queued,
       unitUsage: res.unitUsage ?? null,
       ...handles(res)
     };
@@ -1047,9 +1177,13 @@ var Signals = class {
    * 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.
+   * 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
@@ -1058,9 +1192,11 @@ var Signals = class {
    * rather than failing it.
    */
   async completeComposite(input) {
+    const idempotencyKey = input.idempotencyKey ?? newKey();
     const res = await this.transport.request({
       method: "POST",
       path: COMPOSITE_COMPLETE_PATH,
+      idempotencyKey,
       body: {
         customerId: input.customerId,
         composite: { [input.composite.ref]: input.composite.value },
@@ -1069,12 +1205,14 @@ var Signals = class {
         // 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()
+        idempotencyKey
       },
       retry: true
     });
+    const queued = res.queued === true;
     return {
-      queued: res.queued === true,
+      delivery: queued ? "accepted" : "recorded",
+      queued,
       ...res.status != null ? { status: res.status } : {},
       ...res.composite !== void 0 ? { composite: res.composite } : {},
       ...res.value !== void 0 ? { value: res.value } : {},
@@ -1102,14 +1240,16 @@ var Units = class {
     this.transport = transport;
   }
   transport;
-  /** List unit types. Pass `{ active: true }` to only return active ones. */
+  /** 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 = {}) {
     const res = await this.transport.request({
       method: "GET",
       path: "/api/v1/units-catalog",
-      query: { active: params.active === void 0 ? void 0 : String(params.active) }
+      query: { active: activeQuery(params.active) }
     });
-    return res.units;
+    return filterByActive(res.units, params.active);
   }
   /** Create a unit type. `POST /api/v1/units-catalog`. */
   async create(input) {
@@ -1201,16 +1341,16 @@ var Workspace = class {
     });
   }
   /** The org's enabled models with live prices. `{ active: true }` returns only
-   *  the models that can be metered right now. */
+   *  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 = {}) {
     const res = await this.transport.request({
       method: "GET",
       path: "/api/v1/models",
-      query: {
-        active: params.active === void 0 ? void 0 : String(params.active)
-      }
+      query: { active: activeQuery(params.active) }
     });
-    return res.models;
+    return filterByActive(res.models, params.active);
   }
 };
 
@@ -1286,6 +1426,7 @@ exports.AuthError = AuthError;
 exports.ClockNext = ClockNext;
 exports.ClockNextError = ClockNextError;
 exports.ConflictError = ConflictError;
+exports.ForbiddenError = ForbiddenError;
 exports.NetworkError = NetworkError;
 exports.NotFoundError = NotFoundError;
 exports.PlanError = PlanError;