@clocknext/sdk 0.19.2 → 0.20.1

package/examples/webhook-receiver.ts

@@ -0,0 +1,70 @@
+/**
+ * Receive ClockNext webhooks (wallet.balance.update / wallet.balance.drop).
+ * Create the endpoint in the dashboard (Settings → Webhooks), pick the events,
+ * and copy the signing secret — it is shown once.
+ *
+ *   CLOCKNEXT_WEBHOOK_SECRET=… npx tsx examples/webhook-receiver.ts
+ *
+ * Plain `node:http` so the example has no framework to install. The one rule
+ * that decides whether any framework works: verify the RAW body. A body parser
+ * that parses and re-serialises the JSON changes the bytes, and every signature
+ * then fails. In Express, mount `express.raw({ type: "application/json" })` on
+ * this route instead of `express.json()` and pass `req.body` (a Buffer).
+ */
+import { createServer } from "node:http";
+import { constructWebhookEvent, WebhookSignatureError } from "@clocknext/sdk";
+
+const secret = process.env.CLOCKNEXT_WEBHOOK_SECRET!;
+
+// Delivery is at-least-once and a retry carries the SAME event id. In
+// production keep these in a database or Redis, not memory.
+const seen = new Set<string>();
+
+createServer(async (req, res) => {
+  if (req.method !== "POST" || req.url !== "/webhooks/clocknext") {
+    res.statusCode = 404;
+    return res.end();
+  }
+
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  const rawBody = Buffer.concat(chunks);
+
+  let event;
+  try {
+    event = constructWebhookEvent(
+      rawBody,
+      req.headers["x-clocknext-signature"] as string | undefined,
+      secret,
+    );
+  } catch (err) {
+    if (err instanceof WebhookSignatureError) {
+      console.warn("rejected webhook:", err.message);
+      res.statusCode = 400;
+      return res.end();
+    }
+    throw err;
+  }
+
+  // Answer fast: ClockNext times out after 5s and retries any non-2xx.
+  if (!seen.has(event.id)) {
+    seen.add(event.id);
+    switch (event.event_type) {
+      case "wallet.balance.update":
+        console.log(
+          `${event.data.customer.name}: $${event.data.previous_balance} → $${event.data.current_balance} (${event.data.source})`,
+        );
+        break;
+      case "wallet.balance.drop":
+        console.log(
+          `${event.data.customer.name} fell to $${event.data.current_balance}, at or below $${event.data.threshold} — warn them or top up`,
+        );
+        break;
+      default:
+        // An event type added after this SDK version: ignore it, still 200.
+        break;
+    }
+  }
+  res.statusCode = 200;
+  res.end();
+}).listen(3000, () => console.log("listening on :3000"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.19.2",
+  "version": "0.20.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/client.ts

@@ -14,6 +14,7 @@ import { Signals } from "./resources/signals.js";
 import { Units } from "./resources/units.js";
 import { Taxes } from "./resources/taxes.js";
 import type { ClockNextConfig, ResolvedConfig } from "./types.js";
+import { Webhooks } from "./webhooks.js";
 
 /**
  * The ClockNext client.
@@ -58,6 +59,9 @@ export class ClockNext {
   /** Mint customer-portal embed tokens. */
   readonly portal: Portal;
 
+  /** Verify incoming ClockNext webhooks (`wallet.balance.update` / `.drop`). */
+  readonly webhooks: Webhooks;
+
   private readonly cfg: ResolvedConfig;
   private readonly flusher: Flusher;
 
@@ -84,6 +88,7 @@ export class ClockNext {
     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). */

package/src/errors.ts

@@ -11,6 +11,7 @@ export type ClockNextErrorCode =
   | "ALLOWANCE_EXHAUSTED"
   | "PLAN_REJECTED"
   | "IDEMPOTENCY_UNRESOLVED"
+  | "WEBHOOK_SIGNATURE_INVALID"
   | (string & {});
 
 export class ClockNextError extends Error {
@@ -95,6 +96,15 @@ export class RateLimitError extends ClockNextError {
 /** 5xx — server-side error. */
 export class ServerError extends ClockNextError {}
 
+/** A webhook request failed verification (`webhooks.constructEvent`): missing or
+ *  malformed signature header, wrong secret or altered body, a timestamp outside
+ *  the tolerance, or a body that is not a ClockNext event. Answer 400. */
+export class WebhookSignatureError extends ClockNextError {
+  constructor(message: string) {
+    super(message, { status: 400, retryable: false, code: "WEBHOOK_SIGNATURE_INVALID" });
+  }
+}
+
 /** fetch threw / request timed out — request never completed. */
 export class NetworkError extends ClockNextError {
   constructor(message: string, opts: { idempotencyKey?: string } = {}) {

package/src/index.ts

@@ -19,8 +19,27 @@ export {
   RateLimitError,
   ServerError,
   NetworkError,
+  WebhookSignatureError,
 } from "./errors.js";
 
+export {
+  constructWebhookEvent,
+  signWebhookPayload,
+  WEBHOOK_SIGNATURE_HEADER,
+} from "./webhooks.js";
+
+export type {
+  WebhookEvent,
+  WebhookEventType,
+  WebhookWalletSource,
+  WebhookCustomer,
+  WalletBalanceUpdateEvent,
+  WalletBalanceUpdateData,
+  WalletBalanceDropEvent,
+  WalletBalanceDropData,
+  ConstructEventOptions,
+} from "./webhooks.js";
+
 export type { ClockNextErrorCode } from "./errors.js";
 
 export { signalToWire } from "./resources/signals.js";
@@ -71,6 +90,7 @@ export type {
   CreateCustomerInput,
   CustomerList,
   CustomerBalances,
+  WalletAlert,
   WalletLedgerPage,
   WalletLedgerParams,
   WalletTransaction,

package/src/resources/customers.ts

@@ -23,6 +23,7 @@ import type {
   UnitBalance,
   UpdateMemberInput,
   WalletAdjustInput,
+  WalletAlert,
   WalletLedgerPage,
   WalletLedgerParams,
   WalletTransaction,
@@ -401,6 +402,34 @@ export class Customers {
     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: string, threshold: number | null): Promise<WalletAlert> {
+    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: string, threshold: number | null): Promise<WalletAlert> {
+    return this.walletAlert(
+      `/api/v1/customers/ext/${encodeURIComponent(id)}/wallet/alert`,
+      threshold,
+    );
+  }
+
+  private walletAlert(path: string, threshold: number | null): Promise<WalletAlert> {
+    return this.transport.request<WalletAlert>({
+      method: "PUT",
+      path,
+      body: { threshold },
+    });
+  }
+
   /**
    * The one body behind all ten adjust calls.
    *

package/src/types.ts

@@ -768,11 +768,21 @@ export interface WalletLedgerPage {
   /** Reserved Wallet balance, USD; `null` when the workspace hasn't enabled
    *  it. */
   reservedBalanceUsd: number | null;
+  /** The customer's own low-balance alert level, USD; `null` when none is set.
+   *  At or below it the `wallet.balance.drop` webhook fires for this customer.
+   *  Set with `customers.setWalletAlert()`. */
+  lowBalanceAlertUsd: number | null;
   transactions: WalletTransaction[];
   /** Pass back as `cursor` for the next page; `null` on the last page. */
   nextCursor: string | null;
 }
 
+/** Result of `customers.setWalletAlert()`. */
+export interface WalletAlert {
+  /** The saved low-balance alert level, USD; `null` once cleared. */
+  lowBalanceAlertUsd: number | null;
+}
+
 export interface WalletLedgerParams {
   /** Default 50, max 200. */
   limit?: number;

package/src/webhooks.ts

@@ -0,0 +1,244 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { WebhookSignatureError } from "./errors.js";
+
+/**
+ * Receiving ClockNext webhooks.
+ *
+ * ClockNext POSTs a signed JSON event to each endpoint you register in the
+ * dashboard (Settings → Webhooks). Two events exist today:
+ *
+ *   wallet.balance.update  a customer's MAIN wallet balance moved (credit or
+ *                          debit). Invoice settlements and the Reserved
+ *                          Wallet do not fire it.
+ *   wallet.balance.drop    a debit took the balance from above a level to at
+ *                          or below it. The level is the customer's own alert
+ *                          level (`customers.setWalletAlert`) when they have
+ *                          one, otherwise the endpoint's threshold. Fires once
+ *                          per drop through the level, not on every debit while
+ *                          the balance stays under it.
+ *
+ * Verify every request before trusting it — {@link constructWebhookEvent} does
+ * that and returns the typed event. It needs the RAW request body: parsing the
+ * JSON and re-serialising it changes the bytes and the signature will not match.
+ *
+ * Delivery is at-least-once: a non-2xx answer (or a timeout past 5s) is retried
+ * with the SAME event `id`, so de-duplicate on `id`.
+ */
+
+/** Events ClockNext sends today. New event types may be added later — ignore
+ *  any `event_type` you do not recognise (and still answer 2xx). */
+export type WebhookEventType = "wallet.balance.update" | "wallet.balance.drop";
+
+/**
+ * The `source` a `wallet.balance.update` event carries: the STORED ledger
+ * source, which is coarser than `WalletTransactionSource` on the ledger API.
+ * Do not compare the two — the ledger API reports `SUBSCRIPTION`, `RENEWAL`,
+ * `API`, … where the webhook says `TOPUP` or `ADJUSTMENT`.
+ *
+ * The ledger also has a `SETTLE` source (an invoice being paid off), but
+ * `wallet.balance.update` is never sent for it, so it is not in this type.
+ */
+export type WebhookWalletSource = "TOPUP" | "USAGE" | "ADJUSTMENT";
+
+/** The customer a wallet event is about. */
+export interface WebhookCustomer {
+  id: string;
+  name: string;
+}
+
+/** Fields on every event. Field names are snake_case, exactly as sent. */
+interface WebhookEventBase<T extends WebhookEventType, D> {
+  /** `evt_…`. Identical across retries of one delivery — de-duplicate on it. */
+  id: string;
+  event_type: T;
+  /** ISO-8601 time the event was created. */
+  triggered_at: string;
+  data: D;
+}
+
+/** `data` of `wallet.balance.update`. Balances are USD. */
+export interface WalletBalanceUpdateData {
+  customer: WebhookCustomer;
+  source: WebhookWalletSource;
+  previous_balance: number;
+  current_balance: number;
+  currency_code: "usd";
+}
+
+/** `data` of `wallet.balance.drop`. Balances and `threshold` are USD. */
+export interface WalletBalanceDropData {
+  customer: WebhookCustomer;
+  /** The level that was crossed: the customer's own alert level, else the
+   *  endpoint's threshold. */
+  threshold: number;
+  previous_balance: number;
+  current_balance: number;
+  currency_code: "usd";
+}
+
+export type WalletBalanceUpdateEvent = WebhookEventBase<
+  "wallet.balance.update",
+  WalletBalanceUpdateData
+>;
+export type WalletBalanceDropEvent = WebhookEventBase<
+  "wallet.balance.drop",
+  WalletBalanceDropData
+>;
+
+/** Any event ClockNext sends. Narrow on `event_type`. */
+export type WebhookEvent = WalletBalanceUpdateEvent | WalletBalanceDropEvent;
+
+export interface ConstructEventOptions {
+  /** Reject an event whose signed timestamp is further than this from now, in
+   *  either direction (replay protection). Default 300 (5 minutes). Pass 0 to
+   *  skip the check — only do that in tests. */
+  toleranceSeconds?: number;
+  /** Override "now" (unix seconds). For tests. */
+  now?: number;
+}
+
+/** Header ClockNext puts the signature in. Node lower-cases header names. */
+export const WEBHOOK_SIGNATURE_HEADER = "x-clocknext-signature";
+
+const DEFAULT_TOLERANCE_SECONDS = 300;
+
+/**
+ * Signs a body the way ClockNext does: `t=<unix_seconds>,v1=<hex hmac>`, the
+ * HMAC-SHA256 of `${timestamp}.${rawBody}` under the endpoint secret. Exported
+ * so you can sign a fixture in your own receiver's tests.
+ */
+export function signWebhookPayload(
+  secret: string,
+  rawBody: string | Buffer,
+  timestamp: number,
+): string {
+  const hmac = createHmac("sha256", secret)
+    .update(`${timestamp}.`)
+    .update(rawBody)
+    .digest("hex");
+  return `t=${timestamp},v1=${hmac}`;
+}
+
+function parseHeader(header: string): { t: number; v1: string[] } {
+  let t: number | undefined;
+  const v1: string[] = [];
+  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 === undefined || v1.length === 0) {
+    throw new WebhookSignatureError(
+      "Malformed x-clocknext-signature header: expected `t=<unix_seconds>,v1=<hex>`.",
+    );
+  }
+  return { t, v1 };
+}
+
+function safeEqualHex(expectedHex: string, givenHex: string): boolean {
+  const expected = Buffer.from(expectedHex, "hex");
+  const given = Buffer.from(givenHex, "hex");
+  // timingSafeEqual throws on a length mismatch, so compare lengths first.
+  // A non-hex or wrong-length value can never be a valid HMAC-SHA256.
+  return given.length === expected.length && timingSafeEqual(expected, given);
+}
+
+/**
+ * Verifies a ClockNext webhook request and returns the typed event.
+ *
+ * ```ts
+ * app.post("/clocknext", express.raw({ type: "application/json" }), (req, res) => {
+ *   let event;
+ *   try {
+ *     event = constructWebhookEvent(
+ *       req.body,                                  // the raw Buffer, NOT parsed JSON
+ *       req.header("x-clocknext-signature"),
+ *       process.env.CLOCKNEXT_WEBHOOK_SECRET!,
+ *     );
+ *   } catch {
+ *     return res.sendStatus(400);
+ *   }
+ *   if (event.event_type === "wallet.balance.drop") { … }
+ *   res.sendStatus(200);
+ * });
+ * ```
+ *
+ * @throws {WebhookSignatureError} header missing or malformed, signature does
+ *   not match, timestamp outside the tolerance, or the body is not a JSON event.
+ */
+export function constructWebhookEvent(
+  rawBody: string | Buffer,
+  signatureHeader: string | null | undefined,
+  secret: string,
+  options: ConstructEventOptions = {},
+): WebhookEvent {
+  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);
+
+  // Recompute from the same `${t}.${body}` and accept any listed `v1`, so a
+  // future signing-key rotation that sends two signatures keeps working.
+  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() / 1000);
+    if (Math.abs(now - t) > tolerance) {
+      throw new WebhookSignatureError(
+        `Webhook timestamp is outside the ${tolerance}s tolerance — possible replay.`,
+      );
+    }
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody.toString());
+  } catch {
+    throw new WebhookSignatureError("Webhook body is not valid JSON.");
+  }
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    typeof (parsed as { id?: unknown }).id !== "string" ||
+    typeof (parsed as { event_type?: unknown }).event_type !== "string"
+  ) {
+    throw new WebhookSignatureError("Webhook body is not a ClockNext event.");
+  }
+  return parsed as WebhookEvent;
+}
+
+/** `cnk.webhooks` — the same verifier as {@link constructWebhookEvent}, for
+ *  callers who already hold a client. Needs no network and no API key use. */
+export class Webhooks {
+  /** See {@link constructWebhookEvent}. */
+  constructEvent(
+    rawBody: string | Buffer,
+    signatureHeader: string | null | undefined,
+    secret: string,
+    options?: ConstructEventOptions,
+  ): WebhookEvent {
+    return constructWebhookEvent(rawBody, signatureHeader, secret, options);
+  }
+}