@nile-squad/nylonpay-ts 1.0.6 → 1.0.8

package/dist/index.d.ts

@@ -149,6 +149,14 @@ type VerifyWebhookInput = {
     payload: string | Uint8Array;
     signature: string;
     secret: string;
+    /**
+     * Replay-protection window in seconds. After the signature is verified, the
+     * timestamp carried inside the signed body must be within this many seconds of
+     * now, or verification fails. Defaults to 300 (5 minutes). Set to `0` to
+     * disable the freshness check (not recommended — a captured webhook then
+     * verifies forever).
+     */
+    toleranceSeconds?: number;
 };
 /**
  * Full transaction record returned by lookups, event handlers, and the
@@ -245,16 +253,39 @@ type AfterPayoutHook = (result: Result<{
     reference: string;
     status: string;
 }, string>, input: MakePayoutInput) => void | Promise<void>;
+/**
+ * Wrapper applied to every lifecycle hook. The SDK runs `fn` inside `safeTry`,
+ * so a throw or rejection in merchant code never bubbles into the payment flow —
+ * it is routed to `onError` instead.
+ *
+ * WHY `onError` is required: an unhandled hook failure in a payments SDK is the
+ * worst kind of silent bug (the payment "succeeds" while a wallet credit or
+ * fulfillment side-effect was lost). Forcing the merchant to declare what
+ * happens on failure replaces both the old "throw and maybe crash" behaviour and
+ * a silent `catch {}` with an explicit, type-enforced decision.
+ */
+type SdkHook<TFn> = {
+    /** Set `false` to disable this hook without removing its config. Default: true. */
+    enabled?: boolean;
+    /** The hook implementation. */
+    fn: TFn;
+    /**
+     * Required. Receives the thrown/rejected value if `fn` fails. Runs inside
+     * `safeTry` too, so an error here is contained as well.
+     */
+    onError: (error: unknown) => void | Promise<void>;
+};
 /**
  * Lifecycle hooks registered once at SDK creation. Each hook fires on every
  * matching operation — use them for cross-cutting concerns like logging,
- * audit trails, and payload enrichment.
+ * audit trails, and payload enrichment. Every hook is wrapped in {@link SdkHook}
+ * so merchant code can never crash the payment flow.
  */
 type SdkHooks = {
-    beforeCollect?: BeforeCollectHook;
-    afterCollect?: AfterCollectHook;
-    beforePayout?: BeforePayoutHook;
-    afterPayout?: AfterPayoutHook;
+    beforeCollect?: SdkHook<BeforeCollectHook>;
+    afterCollect?: SdkHook<AfterCollectHook>;
+    beforePayout?: SdkHook<BeforePayoutHook>;
+    afterPayout?: SdkHook<AfterPayoutHook>;
 };
 /**
  * SDK configuration supplied by the merchant at initialization.
@@ -273,12 +304,6 @@ type NylonPayConfig = {
     maxPollIntervalMs?: number;
     maxPollDurationMs?: number;
     maxPollAttempts?: number;
-    /**
-     * Receive status updates over an SSE stream (default `true`), falling back to
-     * polling automatically when the stream is unavailable. Set `false` to poll
-     * only.
-     */
-    streaming?: boolean;
     fetch?: typeof globalThis.fetch;
     /** Force a new instance even if one already exists for this key+url pair. */
     force?: boolean;
@@ -595,9 +620,9 @@ interface PaymentInstance {
  * Factory function to create a Nylon Pay SDK instance.
  * This is the main entry point for merchants.
  *
- * Calling createNylonPay with the same apiKey and baseUrl returns the same
- * instance (singleton per key+url pair). Pass { force: true } to create a
- * fresh instance and replace the cached one.
+ * Calling createNylonPay with the same apiKey, apiSecret and baseUrl returns the
+ * same instance (singleton per key+secret+url). Rotating the secret yields a
+ * fresh instance. Pass { force: true } to force a new instance regardless.
  *
  * @example
  * ```ts
@@ -613,9 +638,9 @@ interface PaymentInstance {
 /**
  * Create a Nylon Pay SDK instance.
  *
- * Returns the same instance for the same apiKey + baseUrl combination unless
- * { force: true } is passed. Use your test keys for sandbox, production keys
- * for live.
+ * Returns the same instance for the same apiKey + apiSecret + baseUrl
+ * combination unless { force: true } is passed. Use your test keys for sandbox,
+ * production keys for live.
  *
  * @param config - SDK configuration with apiKey and apiSecret
  * @returns SDK instance with all payment operations
@@ -663,13 +688,19 @@ declare function parseError(error: string): SdkError;
  */
 
 /**
- * Verify that a webhook payload was signed by Nylon Pay.
- * Operates on raw payload bytes, NOT parsed JSON (spec invariant #8).
+ * Verify that a webhook payload was genuinely sent by Nylon Pay.
+ *
+ * Two checks, both must pass:
+ * 1. **Authenticity** — HMAC-SHA256 over the raw payload bytes (NOT parsed
+ *    JSON, spec invariant #8) matches the provided signature.
+ * 2. **Freshness** — the `timestamp` carried inside the signed body is within
+ *    `toleranceSeconds` of now (default 300s). This is what stops a replay: a
+ *    captured `(body, signature)` pair stays cryptographically valid forever,
+ *    but its embedded timestamp goes stale. Every genuine delivery, including
+ *    retries hours later, is re-stamped and re-signed, so this never rejects
+ *    legitimate traffic. Pass `toleranceSeconds: 0` to skip this check.
  *
- * @param input.payload - Raw request body as string or Uint8Array
- * @param input.signature - Signature from the webhook header
- * @param input.secret - Merchant's webhook secret
- * @returns True when the signature is valid
+ * @returns True when the signature is valid and (when enforced) the webhook is fresh
  */
 declare function verifyWebhookSignature(input: VerifyWebhookInput): boolean;