@clocknext/sdk 0.19.1 → 0.20.0

package/README.md

@@ -9,7 +9,9 @@ Official TypeScript/JavaScript SDK for ClockNext. Use it from a backend to:
 
 The SDK targets the ClockNext `/api/v1` API and requires Node.js 18 or newer.
 It has zero runtime dependencies and works with native `fetch` in Node, Bun,
-Deno, and edge runtimes.
+Deno, and edge runtimes. The one exception is webhook signature verification
+([Webhooks](#webhooks)), which uses `node:crypto` and so needs Node (or a
+runtime that provides it); it is not supported on edge runtimes.
 
 ---
 
@@ -657,7 +659,7 @@ for await (const t of cnk.customers.iterateWallet(customerId)) {
 
 ### Look up usage rows by id
 
-`signals.lookupUsageLogs(ids)` returns up to 100 usage-log rows in one call —
+`signals.lookupUsageLogs(ids)` returns up to 10 usage-log rows in one call —
 for example the row behind each wallet debit's `usageLogId`. It is scoped to
 your org, not one customer: every row has its own `customerId`. Rows come back
 in the order of `ids`; ids with no row in your org are listed in `notFound`.
@@ -877,6 +879,76 @@ const one = await cnk.taxes.get(gst.id);
 await cnk.taxes.update(gst.id, { percentage: 12 }); // only the percentage changes
 ```
 
+## Webhooks
+
+ClockNext can POST a signed event to your server when a customer's wallet
+changes. Create the endpoint in the dashboard (**Settings → Webhooks**), choose
+its events, and copy the signing secret — it is shown once. (The SDK verifies
+and types these events; it does not create or list endpoints.)
+
+| Event | Fires when |
+| --- | --- |
+| `wallet.balance.update` | A customer's **main** wallet balance moves, credit or debit. Not for invoice settlements, and not for the Reserved Wallet. |
+| `wallet.balance.drop` | A debit takes the balance from above a level to at or below it. Fires **once per drop** through the level, not on every debit while the balance stays under it. |
+
+The level for `wallet.balance.drop` is the customer's own alert level if they
+have one, otherwise the endpoint's threshold. Set or clear a customer's own
+level with the SDK:
+
+```ts
+await cnk.customers.setWalletAlert(customerId, 50);   // alert at or below $50
+await cnk.customers.setWalletAlert(customerId, null); // clear it: fall back to each endpoint's threshold
+await cnk.customers.setWalletAlertByExternalId("acme-42", 50);
+
+(await cnk.customers.wallet(customerId)).lowBalanceAlertUsd; // 50, or null
+```
+
+### Verify, then handle
+
+```ts
+import { constructWebhookEvent, WebhookSignatureError } from "@clocknext/sdk";
+
+// `rawBody` is the UNPARSED request body (string or Buffer).
+const event = constructWebhookEvent(
+  rawBody,
+  req.headers["x-clocknext-signature"],
+  process.env.CLOCKNEXT_WEBHOOK_SECRET!,
+);
+// the same check is available as cnk.webhooks.constructEvent(…)
+
+if (event.event_type === "wallet.balance.drop") {
+  event.data.customer.id;
+  event.data.threshold;        // the level that was crossed, USD
+  event.data.previous_balance; // USD
+  event.data.current_balance;  // USD
+}
+```
+
+`constructWebhookEvent` throws `WebhookSignatureError` (a 400, never retryable)
+when the header is missing or malformed, the signature does not match, the
+timestamp is more than 5 minutes from now (`{ toleranceSeconds }` changes
+that), or the body is not a ClockNext event. Answer **400** to those.
+
+- **Use the raw body.** The signature is an HMAC-SHA256 of `${t}.${rawBody}`;
+  parsing the JSON and re-serialising it changes the bytes and every signature
+  fails. In Express mount `express.raw({ type: "application/json" })` on the
+  webhook route, not `express.json()`.
+- **Answer 2xx quickly.** ClockNext waits 5 seconds and retries any other
+  answer. Do slow work after you respond.
+- **De-duplicate on `event.id`.** Delivery is at-least-once, and a retry
+  carries the same `id`.
+- **Ignore event types you do not know.** More may be added; answer 2xx.
+- **Field names are snake_case**, exactly as sent (`event_type`,
+  `previous_balance`, …), unlike the camelCase the rest of the SDK returns.
+- **`source` is not the ledger's `source`.** `wallet.balance.update` carries the
+  stored source — `TOPUP`, `USAGE`, `SETTLE` or `ADJUSTMENT` — not the finer
+  `SUBSCRIPTION` / `RENEWAL` / `API` / … that `customers.wallet()` reports.
+  Do not compare the two.
+- To test your receiver, sign a fixture with `signWebhookPayload(secret, body,
+  Math.floor(Date.now() / 1000))` and send it as the header.
+
+See [`examples/webhook-receiver.ts`](examples/webhook-receiver.ts).
+
 ## Customer portal
 
 ```ts

package/dist/index.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var crypto = require('crypto');
+
 // src/errors.ts
 var ClockNextError = class extends Error {
   /** HTTP status, when the failure came from a server response. */
@@ -56,6 +58,11 @@ var RateLimitError = class extends ClockNextError {
 };
 var ServerError = class extends ClockNextError {
 };
+var WebhookSignatureError = class extends ClockNextError {
+  constructor(message) {
+    super(message, { status: 400, retryable: false, code: "WEBHOOK_SIGNATURE_INVALID" });
+  }
+};
 var NetworkError = class extends ClockNextError {
   constructor(message, opts = {}) {
     super(message, { retryable: true, idempotencyKey: opts.idempotencyKey });
@@ -333,7 +340,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.19.1" ;
+var SDK_VERSION = "0.20.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -874,6 +881,31 @@ var Customers = class {
   adjustWalletByExternalId(id, input) {
     return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/wallet/adjust`, input);
   }
+  /**
+   * Set (a number of 0 or more, USD) or clear (`null`) a customer's low-balance
+   * alert level. At or below it the `wallet.balance.drop` webhook fires for this
+   * customer, whatever the endpoint's own threshold is; a customer without a
+   * level falls back to each endpoint's threshold. Returns the saved level.
+   * Idempotent (a PUT), so it retries safely. `PUT …/:id/wallet/alert`.
+   */
+  setWalletAlert(id, threshold) {
+    return this.walletAlert(`/api/v1/customers/${encodeURIComponent(id)}/wallet/alert`, threshold);
+  }
+  /** {@link setWalletAlert}, addressing the customer by its `externalId` (`id`
+   *  here). `PUT /api/v1/customers/ext/:externalId/wallet/alert`. */
+  setWalletAlertByExternalId(id, threshold) {
+    return this.walletAlert(
+      `/api/v1/customers/ext/${encodeURIComponent(id)}/wallet/alert`,
+      threshold
+    );
+  }
+  walletAlert(path, threshold) {
+    return this.transport.request({
+      method: "PUT",
+      path,
+      body: { threshold }
+    });
+  }
   /**
    * The one body behind all ten adjust calls.
    *
@@ -1492,7 +1524,7 @@ var Signals = class {
     });
   }
   /**
-   * Fetches up to 100 usage-log rows by id, in one call.
+   * Fetches up to 10 usage-log rows by id, in one call.
    * `GET /api/v1/signal/usage-log/lookup`.
    *
    * Built for linking a wallet debit to its usage: pass the `usageLogId`s
@@ -1501,7 +1533,7 @@ var Signals = class {
    * carries its own `customerId`.
    *
    * Rows come back in the order of `ids`; duplicates are removed. Ids that
-   * match nothing in your org are listed in `notFound`. More than 100
+   * match nothing in your org are listed in `notFound`. More than 10
    * distinct ids is a 400.
    */
   lookupUsageLogs(ids) {
@@ -1624,6 +1656,83 @@ var Taxes = class {
     return res.tax;
   }
 };
+var WEBHOOK_SIGNATURE_HEADER = "x-clocknext-signature";
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function signWebhookPayload(secret, rawBody, timestamp) {
+  const hmac = crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");
+  return `t=${timestamp},v1=${hmac}`;
+}
+function parseHeader(header) {
+  let t;
+  const v1 = [];
+  for (const part of header.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const k = part.slice(0, eq).trim();
+    const v = part.slice(eq + 1).trim();
+    if (k === "t") {
+      if (/^\d+$/.test(v)) t = Number(v);
+    } else if (k === "v1") {
+      v1.push(v);
+    }
+  }
+  if (t === void 0 || v1.length === 0) {
+    throw new WebhookSignatureError(
+      "Malformed x-clocknext-signature header: expected `t=<unix_seconds>,v1=<hex>`."
+    );
+  }
+  return { t, v1 };
+}
+function safeEqualHex(expectedHex, givenHex) {
+  const expected = Buffer.from(expectedHex, "hex");
+  const given = Buffer.from(givenHex, "hex");
+  return given.length === expected.length && crypto.timingSafeEqual(expected, given);
+}
+function constructWebhookEvent(rawBody, signatureHeader, secret, options = {}) {
+  if (typeof rawBody !== "string" && !Buffer.isBuffer(rawBody)) {
+    throw new WebhookSignatureError(
+      "Webhook body must be the raw request body (string or Buffer), not parsed JSON. With Express use express.raw({ type: 'application/json' })."
+    );
+  }
+  if (!secret) {
+    throw new WebhookSignatureError("A webhook secret is required.");
+  }
+  if (!signatureHeader) {
+    throw new WebhookSignatureError("Missing x-clocknext-signature header.");
+  }
+  const { t, v1 } = parseHeader(signatureHeader);
+  const expected = signWebhookPayload(secret, rawBody, t).split("v1=")[1];
+  if (!v1.some((candidate) => safeEqualHex(expected, candidate))) {
+    throw new WebhookSignatureError(
+      "Webhook signature does not match. Check the secret and that the body is the unmodified raw body."
+    );
+  }
+  const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (tolerance > 0) {
+    const now = options.now ?? Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - t) > tolerance) {
+      throw new WebhookSignatureError(
+        `Webhook timestamp is outside the ${tolerance}s tolerance \u2014 possible replay.`
+      );
+    }
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(rawBody.toString());
+  } catch {
+    throw new WebhookSignatureError("Webhook body is not valid JSON.");
+  }
+  if (typeof parsed !== "object" || parsed === null || typeof parsed.id !== "string" || typeof parsed.event_type !== "string") {
+    throw new WebhookSignatureError("Webhook body is not a ClockNext event.");
+  }
+  return parsed;
+}
+var Webhooks = class {
+  /** See {@link constructWebhookEvent}. */
+  constructEvent(rawBody, signatureHeader, secret, options) {
+    return constructWebhookEvent(rawBody, signatureHeader, secret, options);
+  }
+};
 
 // src/client.ts
 var ClockNext = class {
@@ -1651,6 +1760,8 @@ var ClockNext = class {
   payments;
   /** Mint customer-portal embed tokens. */
   portal;
+  /** Verify incoming ClockNext webhooks (`wallet.balance.update` / `.drop`). */
+  webhooks;
   cfg;
   flusher;
   constructor(config) {
@@ -1674,6 +1785,7 @@ var ClockNext = class {
     this.invoices = new Invoices(transport);
     this.payments = new Payments(transport);
     this.portal = new Portal(transport);
+    this.webhooks = new Webhooks();
   }
   /** Number of signals currently buffered (async mode). */
   get pending() {
@@ -1701,6 +1813,10 @@ exports.PlanError = PlanError;
 exports.RateLimitError = RateLimitError;
 exports.ServerError = ServerError;
 exports.ValidationError = ValidationError;
+exports.WEBHOOK_SIGNATURE_HEADER = WEBHOOK_SIGNATURE_HEADER;
+exports.WebhookSignatureError = WebhookSignatureError;
+exports.constructWebhookEvent = constructWebhookEvent;
+exports.signWebhookPayload = signWebhookPayload;
 exports.signalToWire = signalToWire;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map