@clocknext/sdk 0.19.1 → 0.20.0

package/dist/index.d.cts

@@ -748,10 +748,19 @@ 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()`. */
+interface WalletAlert {
+    /** The saved low-balance alert level, USD; `null` once cleared. */
+    lowBalanceAlertUsd: number | null;
+}
 interface WalletLedgerParams {
     /** Default 50, max 200. */
     limit?: number;
@@ -2029,6 +2038,18 @@ declare class Customers {
     /** {@link adjustWallet}, addressing the customer by its `externalId` (`id`
      *  here). `POST /api/v1/customers/ext/:externalId/wallet/adjust`. */
     adjustWalletByExternalId(id: string, input: WalletAdjustInput): Promise<AdjustResult>;
+    /**
+     * 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>;
+    /** {@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>;
+    private walletAlert;
     /**
      * The one body behind all ten adjust calls.
      *
@@ -2423,7 +2444,7 @@ declare class Signals {
      */
     usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
     /**
-     * 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
@@ -2432,7 +2453,7 @@ declare class Signals {
      * 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: string[]): Promise<UsageLogLookupResult>;
@@ -2495,6 +2516,124 @@ declare class Taxes {
     update(id: string, input: UpdateTaxInput): Promise<Tax>;
 }
 
+/**
+ * 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). */
+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`.
+ *
+ * `SETTLE` is part of the type but `wallet.balance.update` does not fire for it.
+ */
+type WebhookWalletSource = "TOPUP" | "USAGE" | "SETTLE" | "ADJUSTMENT";
+/** The customer a wallet event is about. */
+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. */
+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. */
+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";
+}
+type WalletBalanceUpdateEvent = WebhookEventBase<"wallet.balance.update", WalletBalanceUpdateData>;
+type WalletBalanceDropEvent = WebhookEventBase<"wallet.balance.drop", WalletBalanceDropData>;
+/** Any event ClockNext sends. Narrow on `event_type`. */
+type WebhookEvent = WalletBalanceUpdateEvent | WalletBalanceDropEvent;
+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. */
+declare const WEBHOOK_SIGNATURE_HEADER = "x-clocknext-signature";
+/**
+ * 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.
+ */
+declare function signWebhookPayload(secret: string, rawBody: string | Buffer, timestamp: number): string;
+/**
+ * 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.
+ */
+declare function constructWebhookEvent(rawBody: string | Buffer, signatureHeader: string | null | undefined, secret: string, options?: ConstructEventOptions): WebhookEvent;
+/** `cnk.webhooks` — the same verifier as {@link constructWebhookEvent}, for
+ *  callers who already hold a client. Needs no network and no API key use. */
+declare class Webhooks {
+    /** See {@link constructWebhookEvent}. */
+    constructEvent(rawBody: string | Buffer, signatureHeader: string | null | undefined, secret: string, options?: ConstructEventOptions): WebhookEvent;
+}
+
 /**
  * The ClockNext client.
  *
@@ -2537,6 +2676,8 @@ declare class ClockNext {
     readonly payments: Payments;
     /** Mint customer-portal embed tokens. */
     readonly portal: Portal;
+    /** Verify incoming ClockNext webhooks (`wallet.balance.update` / `.drop`). */
+    readonly webhooks: Webhooks;
     private readonly cfg;
     private readonly flusher;
     constructor(config: ClockNextConfig);
@@ -2556,7 +2697,7 @@ declare class ClockNext {
  */
 /** Machine-readable failure code, when the server sends one
  *  (`statusDetail.code`). Preferred over any message heuristic. */
-type ClockNextErrorCode = "ALLOWANCE_EXHAUSTED" | "PLAN_REJECTED" | "IDEMPOTENCY_UNRESOLVED" | (string & {});
+type ClockNextErrorCode = "ALLOWANCE_EXHAUSTED" | "PLAN_REJECTED" | "IDEMPOTENCY_UNRESOLVED" | "WEBHOOK_SIGNATURE_INVALID" | (string & {});
 declare class ClockNextError extends Error {
     /** HTTP status, when the failure came from a server response. */
     readonly status?: number;
@@ -2617,6 +2758,12 @@ declare class RateLimitError extends ClockNextError {
 /** 5xx — server-side error. */
 declare 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. */
+declare class WebhookSignatureError extends ClockNextError {
+    constructor(message: string);
+}
 /** fetch threw / request timed out — request never completed. */
 declare class NetworkError extends ClockNextError {
     constructor(message: string, opts?: {
@@ -2624,4 +2771,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateTaxInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tax, type TaxBehavior, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateTaxInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogLookupEntitlementType, type UsageLogLookupEntry, type UsageLogLookupResult, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, type WalletAdjustInput, type WalletInput, type WalletLedgerPage, type WalletLedgerParams, type WalletPool, type WalletSignal, type WalletTransaction, type WalletTransactionSource, signalToWire };
+export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type ConstructEventOptions, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateTaxInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tax, type TaxBehavior, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateTaxInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogLookupEntitlementType, type UsageLogLookupEntry, type UsageLogLookupResult, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, WEBHOOK_SIGNATURE_HEADER, type WalletAdjustInput, type WalletAlert, type WalletBalanceDropData, type WalletBalanceDropEvent, type WalletBalanceUpdateData, type WalletBalanceUpdateEvent, type WalletInput, type WalletLedgerPage, type WalletLedgerParams, type WalletPool, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WebhookCustomer, type WebhookEvent, type WebhookEventType, WebhookSignatureError, type WebhookWalletSource, constructWebhookEvent, signWebhookPayload, signalToWire };

package/dist/index.d.ts

@@ -748,10 +748,19 @@ 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()`. */
+interface WalletAlert {
+    /** The saved low-balance alert level, USD; `null` once cleared. */
+    lowBalanceAlertUsd: number | null;
+}
 interface WalletLedgerParams {
     /** Default 50, max 200. */
     limit?: number;
@@ -2029,6 +2038,18 @@ declare class Customers {
     /** {@link adjustWallet}, addressing the customer by its `externalId` (`id`
      *  here). `POST /api/v1/customers/ext/:externalId/wallet/adjust`. */
     adjustWalletByExternalId(id: string, input: WalletAdjustInput): Promise<AdjustResult>;
+    /**
+     * 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>;
+    /** {@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>;
+    private walletAlert;
     /**
      * The one body behind all ten adjust calls.
      *
@@ -2423,7 +2444,7 @@ declare class Signals {
      */
     usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
     /**
-     * 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
@@ -2432,7 +2453,7 @@ declare class Signals {
      * 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: string[]): Promise<UsageLogLookupResult>;
@@ -2495,6 +2516,124 @@ declare class Taxes {
     update(id: string, input: UpdateTaxInput): Promise<Tax>;
 }
 
+/**
+ * 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). */
+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`.
+ *
+ * `SETTLE` is part of the type but `wallet.balance.update` does not fire for it.
+ */
+type WebhookWalletSource = "TOPUP" | "USAGE" | "SETTLE" | "ADJUSTMENT";
+/** The customer a wallet event is about. */
+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. */
+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. */
+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";
+}
+type WalletBalanceUpdateEvent = WebhookEventBase<"wallet.balance.update", WalletBalanceUpdateData>;
+type WalletBalanceDropEvent = WebhookEventBase<"wallet.balance.drop", WalletBalanceDropData>;
+/** Any event ClockNext sends. Narrow on `event_type`. */
+type WebhookEvent = WalletBalanceUpdateEvent | WalletBalanceDropEvent;
+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. */
+declare const WEBHOOK_SIGNATURE_HEADER = "x-clocknext-signature";
+/**
+ * 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.
+ */
+declare function signWebhookPayload(secret: string, rawBody: string | Buffer, timestamp: number): string;
+/**
+ * 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.
+ */
+declare function constructWebhookEvent(rawBody: string | Buffer, signatureHeader: string | null | undefined, secret: string, options?: ConstructEventOptions): WebhookEvent;
+/** `cnk.webhooks` — the same verifier as {@link constructWebhookEvent}, for
+ *  callers who already hold a client. Needs no network and no API key use. */
+declare class Webhooks {
+    /** See {@link constructWebhookEvent}. */
+    constructEvent(rawBody: string | Buffer, signatureHeader: string | null | undefined, secret: string, options?: ConstructEventOptions): WebhookEvent;
+}
+
 /**
  * The ClockNext client.
  *
@@ -2537,6 +2676,8 @@ declare class ClockNext {
     readonly payments: Payments;
     /** Mint customer-portal embed tokens. */
     readonly portal: Portal;
+    /** Verify incoming ClockNext webhooks (`wallet.balance.update` / `.drop`). */
+    readonly webhooks: Webhooks;
     private readonly cfg;
     private readonly flusher;
     constructor(config: ClockNextConfig);
@@ -2556,7 +2697,7 @@ declare class ClockNext {
  */
 /** Machine-readable failure code, when the server sends one
  *  (`statusDetail.code`). Preferred over any message heuristic. */
-type ClockNextErrorCode = "ALLOWANCE_EXHAUSTED" | "PLAN_REJECTED" | "IDEMPOTENCY_UNRESOLVED" | (string & {});
+type ClockNextErrorCode = "ALLOWANCE_EXHAUSTED" | "PLAN_REJECTED" | "IDEMPOTENCY_UNRESOLVED" | "WEBHOOK_SIGNATURE_INVALID" | (string & {});
 declare class ClockNextError extends Error {
     /** HTTP status, when the failure came from a server response. */
     readonly status?: number;
@@ -2617,6 +2758,12 @@ declare class RateLimitError extends ClockNextError {
 /** 5xx — server-side error. */
 declare 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. */
+declare class WebhookSignatureError extends ClockNextError {
+    constructor(message: string);
+}
 /** fetch threw / request timed out — request never completed. */
 declare class NetworkError extends ClockNextError {
     constructor(message: string, opts?: {
@@ -2624,4 +2771,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateTaxInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tax, type TaxBehavior, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateTaxInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogLookupEntitlementType, type UsageLogLookupEntry, type UsageLogLookupResult, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, type WalletAdjustInput, type WalletInput, type WalletLedgerPage, type WalletLedgerParams, type WalletPool, type WalletSignal, type WalletTransaction, type WalletTransactionSource, signalToWire };
+export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type ConstructEventOptions, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateTaxInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tax, type TaxBehavior, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateTaxInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogLookupEntitlementType, type UsageLogLookupEntry, type UsageLogLookupResult, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, WEBHOOK_SIGNATURE_HEADER, type WalletAdjustInput, type WalletAlert, type WalletBalanceDropData, type WalletBalanceDropEvent, type WalletBalanceUpdateData, type WalletBalanceUpdateEvent, type WalletInput, type WalletLedgerPage, type WalletLedgerParams, type WalletPool, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WebhookCustomer, type WebhookEvent, type WebhookEventType, WebhookSignatureError, type WebhookWalletSource, constructWebhookEvent, signWebhookPayload, signalToWire };

package/dist/index.js

@@ -1,3 +1,5 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+
 // src/errors.ts
 var ClockNextError = class extends Error {
   /** HTTP status, when the failure came from a server response. */
@@ -54,6 +56,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 });
@@ -331,7 +338,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;
@@ -872,6 +879,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.
    *
@@ -1490,7 +1522,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
@@ -1499,7 +1531,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) {
@@ -1622,6 +1654,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 = 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 && 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 {
@@ -1649,6 +1758,8 @@ var ClockNext = class {
   payments;
   /** Mint customer-portal embed tokens. */
   portal;
+  /** Verify incoming ClockNext webhooks (`wallet.balance.update` / `.drop`). */
+  webhooks;
   cfg;
   flusher;
   constructor(config) {
@@ -1672,6 +1783,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() {
@@ -1687,6 +1799,6 @@ var ClockNext = class {
   }
 };
 
-export { AllowanceError, AuthError, ClockNext, ClockNextError, ConflictError, ForbiddenError, NetworkError, NotFoundError, PlanError, RateLimitError, ServerError, ValidationError, signalToWire };
+export { AllowanceError, AuthError, ClockNext, ClockNextError, ConflictError, ForbiddenError, NetworkError, NotFoundError, PlanError, RateLimitError, ServerError, ValidationError, WEBHOOK_SIGNATURE_HEADER, WebhookSignatureError, constructWebhookEvent, signWebhookPayload, signalToWire };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map