@clocknext/sdk 0.12.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Official ClockNext SDK — record usage signals and manage plans, purchases, invoices, customers, and billing from your backend.",
   "license": "MIT",
   "type": "module",

package/src/config.ts

@@ -14,9 +14,13 @@ const DEFAULT_BASE_URL = "https://payments.clocknext.com";
  *
  * In the default `async` mode a signal is sent by the background flusher, long
  * after `signals.credit()` resolved `{ status: "buffered" }`. There is no
- * promise left to reject into, so a rejected signal — an unknown `agentKey`, a
- * model the org has not enabled, a customer with no active plan — has nowhere
- * to surface except these hooks.
+ * promise left to reject into, so a failed REQUEST — a bad API key, an
+ * unreachable host, a timeout — has nowhere to surface except these hooks.
+ *
+ * They do not cover a signal the server accepted (`202`) and then refused while
+ * pricing it: that request succeeded as far as this SDK can tell. Those
+ * rejections are recorded on the workspace's signal log in the ClockNext
+ * dashboard, which is owner-only by design.
  *
  * They used to default to nothing at all, which meant a misconfigured
  * integration compiled, ran, returned success-shaped results, and metered

package/src/resources/signals.ts

@@ -136,8 +136,15 @@ function handles(res: SignalResponse) {
  *
  * 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. It surfaces on the `onError` hook, and `list()` is how you confirm
- * one actually landed — ingestion being asynchronous, the only way to.
+ * 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(

package/src/types.ts

@@ -278,8 +278,10 @@ export interface TrackResult {
    *   `"accepted"` — the server has written it to its durable inbox (`202`)
    *                  and will price it shortly. It can no longer be lost, but
    *                  it is not billed yet and `usageLog` is null. A rejection
-   *                  discovered during pricing will NOT come back to you here —
-   *                  read it back with `signals.list()`.
+   *                  discovered during pricing will NOT come back to you here,
+   *                  nor on `onError`. `signals.list()` shows what got priced;
+   *                  the dashboard's signal log — owner-only, by design — is
+   *                  where an individual rejection says why.
    *   `"recorded"` — the server priced it inline and `usageLog` is populated.
    *   `"dropped"`  — the SDK threw it away without sending: the client is
    *                  closed, or the local queue is full. `onDrop` fired with