@clocknext/sdk 0.12.0 → 0.12.1

package/README.md

@@ -46,17 +46,37 @@ A signal is silently discarded if any of these is true:
 | a required field is missing | see the tables below |
 | the allowance is exhausted | top up with `customers.adjustCredit()` etc. |
 
-Two things follow:
-
-- **Always pass `onError`.** It is the only channel a rejected signal has. The
-  SDK logs to `console.error` by default rather than staying silent, but a real
-  integration should handle it.
-- **Prove it landed with `signals.list()`**, not with the return value. That is
-  the only authoritative read.
+Three things follow.
+
+**The per-signal verdict lives in the ClockNext dashboard, and only there.**
+Every signal is logged with its outcome — accepted, processed, or failed with a
+reason — on the workspace's signal log. That view is owner-only in the product
+UI by design and is not exposed through this SDK or any API. When usage is not
+being billed and the causes below do not explain it, that log is where you look.
+
+**`onError` does not see worker-side rejections.** It fires when the HTTP
+request itself fails — network, timeout, auth, a `4xx` returned *before* the
+`202`. A signal that was accepted and then rejected during pricing never
+reaches it, because from the SDK's point of view that request succeeded. Pass it
+anyway: it is how you catch a bad API key, an unreachable host, and a dropped
+buffer.
+
+**`signals.list()` is the programmatic check, and it is partial.** It returns
+priced usage logs, each with a `status`, so it can tell you a signal landed and
+whether pricing succeeded. It cannot tell you about a signal that was rejected
+*before* it was ever priced — an unknown `agentKey`, a customer with no plan —
+because no usage log is written for one. Those appear only in the dashboard.
 
 ```ts
 const usage = await cnk.signals.list({ customerId });
-console.log(usage.totals.count); // 0 means nothing was recorded
+
+// Nothing here at all → rejected before pricing. Check the dashboard's log.
+console.log(usage.totals.count);
+
+// Present but not billed → priced and refused; `status` says which.
+for (const log of usage.logs) {
+  if (log.status !== "SUCCESS") console.warn(log.id, log.status);
+}
 ```
 
 ### 2. Nothing can be metered until five things exist
@@ -103,7 +123,8 @@ if (!apiKey) throw new Error("CLOCKNEXT_API_KEY is required");
 
 const cnk = new ClockNext({
   apiKey,
-  // The only channel a rejected signal has. Do not skip it.
+  // Catches request-level failures (bad key, network, dropped buffer).
+  // Rejections found later, during pricing, are visible only in the dashboard.
   onError: (error, signal) =>
     console.error("[clocknext] signal rejected", signal?.type, error),
 });
@@ -430,7 +451,13 @@ and `.idempotencyKey` on metering calls. Constructor failures — a missing
 
 Because ingest answers `202` before validating, **a try/catch around
 `signals.credit()` will not catch a rejected signal**, with or without
-`{ wait: true }`. Those surface on the hooks:
+`{ wait: true }` — and neither will `onError`. A rejection discovered during
+pricing 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.
+
+What the hooks below DO cover is everything that fails before the `202`: an
+invalid API key, an unreachable host, a timeout, and signals the SDK dropped
+without sending.
 
 ```ts
 import { ClockNext, ClockNextError } from "@clocknext/sdk";
@@ -452,6 +479,10 @@ const cnk = new ClockNext({
 
 `onFlush` counts signals the server **accepted**, not signals it billed.
 
+So the division of labour is: these hooks tell you your integration cannot
+reach ClockNext; `signals.list()` tells you what got priced; the dashboard's
+signal log tells you why an individual signal did not.
+
 ## Balances and usage
 
 ```ts

package/dist/index.cjs

@@ -328,7 +328,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.12.0" ;
+var SDK_VERSION = "0.12.1" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;