@delopay/sdk 0.9.0 → 0.11.0

package/README.md

@@ -167,24 +167,26 @@ const gateways = await delopay.shops.gateways.list(merchantId, shop.shop_id);
 
 ### Webhook verification
 
+Delopay signs each outgoing webhook with HMAC-SHA512 over the raw request body and delivers the hex-encoded digest in the `X-Webhook-Signature-512` header. Use `express.raw()` (not `express.json()`) so the bytes reach the verifier unchanged.
+
 ```typescript
+import express from 'express';
 import { Delopay } from '@delopay/sdk';
 
-// In your Express handler:
-app.post('/webhooks/delopay', express.raw({ type: 'application/json' }), (req, res) => {
-  const signature = req.headers['delopay-signature'] as string;
+app.post('/webhooks/delopay', express.raw({ type: 'application/json' }), async (req, res) => {
+  const signature = req.header('x-webhook-signature-512') ?? '';
   const secret = process.env.DELOPAY_WEBHOOK_SECRET!;
 
   let event;
   try {
-    event = Delopay.webhooks.verify(req.body.toString(), signature, secret);
-  } catch (err) {
+    event = await Delopay.webhooks.verify(req.body, signature, secret);
+  } catch {
     return res.status(400).send('Invalid signature');
   }
 
   switch (event.type) {
     case 'payment_succeeded':
-      // fulfill order
+      // fulfil order
       break;
     case 'payment_failed':
       // notify customer

package/dist/{chunk-WTVISXEY.js → chunk-VQPHGGNQ.js}

@@ -345,14 +345,20 @@ var Connectors = class {
   async verify(params) {
     return this.request("POST", "/account/connectors/verify", { body: params });
   }
-  /** Register a webhook for a connector. `POST /account/{merchantId}/connectors/webhooks/{connectorId}` */
-  async registerWebhook(merchantId, connectorId) {
-    return this.request(
-      "POST",
-      `/account/${encodeURIComponent(merchantId)}/connectors/webhooks/${encodeURIComponent(connectorId)}`
-    );
+  /**
+   * Register a webhook for a connector.
+   * `POST /account/{merchantId}/connectors/webhooks/{connectorId}`
+   *
+   * @param params - Optional event scope. Defaults to `{ event_type: 'all_events' }`
+   *   on the backend when omitted; pass `{ event_type: { specific_event: '…' } }`
+   *   to scope to a single event.
+   */
+  async registerWebhook(merchantId, connectorId, params) {
+    const path = `/account/${encodeURIComponent(merchantId)}/connectors/webhooks/${encodeURIComponent(connectorId)}`;
+    if (params === void 0) return this.request("POST", path);
+    return this.request("POST", path, { body: params });
   }
-  /** Get a webhook for a connector. `GET /account/{merchantId}/connectors/webhooks/{connectorId}` */
+  /** Get registered webhooks for a connector. `GET /account/{merchantId}/connectors/webhooks/{connectorId}` */
   async getWebhook(merchantId, connectorId) {
     return this.request(
       "GET",
@@ -941,15 +947,34 @@ var Payments = class {
    * Retrieve a payment by its ID.
    *
    * @param paymentId - The unique payment intent ID.
+   * @param options - Optional query flags. `force_sync` asks the backend to
+   *   reconcile state with the connector before returning (used to recover a
+   *   stuck intent when a webhook was lost). `all_keys_required` lifts the
+   *   backend's `should_call_connector` gate so a `requires_payment_method`
+   *   intent can still trigger a sync — without it the backend short-circuits
+   *   and returns the local snapshot. Both flags are JWT-authenticated dashboard
+   *   helpers; API-key callers can use them too where the backend allows.
    * @returns The payment intent.
    *
    * @example
    * ```typescript
    * const payment = await delopay.payments.retrieve('pay_abc123');
+   * const synced = await delopay.payments.retrieve('pay_abc123', {
+   *   force_sync: true,
+   *   all_keys_required: true,
+   * });
    * ```
    */
-  async retrieve(paymentId) {
-    return this.request("GET", `/payments/${encodeURIComponent(paymentId)}`);
+  async retrieve(paymentId, options) {
+    const path = `/payments/${encodeURIComponent(paymentId)}`;
+    if (options === void 0) return this.request("GET", path);
+    const query = {};
+    if (options.force_sync !== void 0) query["force_sync"] = options.force_sync;
+    if (options.all_keys_required !== void 0) {
+      query["all_keys_required"] = options.all_keys_required;
+    }
+    if (Object.keys(query).length === 0) return this.request("GET", path);
+    return this.request("GET", path, { query });
   }
   /**
    * Update an existing payment intent before it is confirmed.
@@ -1350,29 +1375,41 @@ var Projects = class {
    * Retrieve a project by its ID.
    *
    * @param projectId - The unique project ID.
+   * @param merchantId - Optional merchant scope. When provided, sent as
+   *   `?merchant_id=…` — required by dashboards that authenticate with a JWT
+   *   spanning multiple merchants and need to disambiguate which one this
+   *   call applies to. API-key callers can omit it.
    * @returns The project.
    */
-  async retrieve(projectId) {
-    return this.request("GET", `/projects/${encodeURIComponent(projectId)}`);
+  async retrieve(projectId, merchantId) {
+    const path = `/projects/${encodeURIComponent(projectId)}`;
+    if (merchantId === void 0) return this.request("GET", path);
+    return this.request("GET", path, { query: { merchant_id: merchantId } });
   }
   /**
    * Update a project's details.
    *
    * @param projectId - The project ID to update.
    * @param params - Fields to update.
+   * @param merchantId - Optional merchant scope. See {@link Projects.retrieve}.
    * @returns The updated project.
    */
-  async update(projectId, params) {
-    return this.request("PUT", `/projects/${encodeURIComponent(projectId)}`, { body: params });
+  async update(projectId, params, merchantId) {
+    const path = `/projects/${encodeURIComponent(projectId)}`;
+    if (merchantId === void 0) return this.request("PUT", path, { body: params });
+    return this.request("PUT", path, { body: params, query: { merchant_id: merchantId } });
   }
   /**
    * Delete a project.
    *
    * @param projectId - The project ID to delete.
+   * @param merchantId - Optional merchant scope. See {@link Projects.retrieve}.
    * @returns The deleted project object.
    */
-  async delete(projectId) {
-    return this.request("DELETE", `/projects/${encodeURIComponent(projectId)}`);
+  async delete(projectId, merchantId) {
+    const path = `/projects/${encodeURIComponent(projectId)}`;
+    if (merchantId === void 0) return this.request("DELETE", path);
+    return this.request("DELETE", path, { query: { merchant_id: merchantId } });
   }
   /**
    * List all projects for a merchant.
@@ -2051,9 +2088,20 @@ var Users = class {
   async listRolesV2() {
     return this.request("GET", "/user/role/v2/list");
   }
-  /** List invitable roles. `GET /user/role/list/invite` */
-  async listInvitableRoles() {
-    return this.request("GET", "/user/role/list/invite");
+  /**
+   * List invitable roles. `GET /user/role/list/invite`
+   *
+   * @param params - Optional query. `entity_type` scopes the role list to a
+   *   particular entity (e.g. `'merchant'` to list only merchant-scoped roles
+   *   when inviting employees from the merchant dashboard).
+   */
+  async listInvitableRoles(params) {
+    if (params === void 0 || params.entity_type === void 0) {
+      return this.request("GET", "/user/role/list/invite");
+    }
+    return this.request("GET", "/user/role/list/invite", {
+      query: { entity_type: params.entity_type }
+    });
   }
   /** List updatable roles. `GET /user/role/list/update` */
   async listUpdatableRoles() {
@@ -2117,72 +2165,75 @@ var Webhooks = {
   /**
    * Verify the signature of an incoming Delopay webhook and return the parsed event.
    *
+   * Delopay signs each outgoing webhook with HMAC-SHA512 over the raw request body,
+   * using your shop's webhook secret (the *payment response hash key* configured on
+   * the shop). The hex-encoded digest is delivered in the `X-Webhook-Signature-512`
+   * HTTP header.
+   *
    * Uses the Web Crypto API (`globalThis.crypto.subtle`), so it runs unchanged in
    * Node 18+, modern browsers, Deno, Bun, and edge runtimes (Cloudflare Workers, Vercel Edge).
    *
-   * This method is available as a static property on the `Delopay` class
+   * Available as a static property on the `Delopay` class
    * (`Delopay.webhooks.verify`) and does not require a client instance.
    *
-   * @param rawBody - The raw request body string (do **not** parse it before passing).
-   * @param signatureHeader - The value of the `delopay-signature` HTTP header.
-   * @param secret - Your webhook signing secret from the Delopay dashboard.
-   * @param options - Optional verification settings (replay tolerance).
+   * @param rawBody - The raw request body. Pass the original bytes (`Uint8Array` /
+   *   `Buffer`) when possible; if you pass a string, it must be the unmodified UTF-8
+   *   text of the request body. Do **not** parse it before passing.
+   * @param signatureHeader - The value of the `X-Webhook-Signature-512` HTTP header.
+   * @param secret - Your shop's webhook signing secret.
    * @returns Promise that resolves to the parsed webhook event.
-   * @throws {Error} When the signature is invalid, the timestamp is missing, or the event is too old.
+   * @throws {Error} When the signature header is malformed or does not match the body.
    *
    * @example
    * ```typescript
    * // Express example
    * app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
-   *   const event = await Delopay.webhooks.verify(
-   *     req.body.toString(),
-   *     req.headers['delopay-signature'] as string,
-   *     process.env.DELOPAY_WEBHOOK_SECRET!,
-   *   );
-   *   console.log(event.type, event.data);
-   *   res.sendStatus(200);
+   *   try {
+   *     const event = await Delopay.webhooks.verify(
+   *       req.body, // Buffer from express.raw()
+   *       req.header('x-webhook-signature-512') ?? '',
+   *       process.env.DELOPAY_WEBHOOK_SECRET!,
+   *     );
+   *     console.log(event.type, event.data);
+   *     res.sendStatus(200);
+   *   } catch {
+   *     res.status(400).send('Invalid signature');
+   *   }
    * });
    * ```
    */
-  async verify(rawBody, signatureHeader, secret, options) {
-    const tolerance = options?.tolerance ?? 300;
-    const parts = signatureHeader.split(",");
-    const timestampPart = parts.find((p) => p.startsWith("t="));
-    const signaturePart = parts.find((p) => p.startsWith("v1="));
-    if (!timestampPart || !signaturePart) {
-      throw new Error("Invalid webhook signature format");
-    }
-    const timestamp = Number.parseInt(timestampPart.slice(2), 10);
-    if (!Number.isFinite(timestamp)) {
-      throw new Error("Invalid webhook timestamp");
-    }
-    const signatureHex = signaturePart.slice(3);
-    const signatureBytes = hexToBytes(signatureHex);
+  async verify(rawBody, signatureHeader, secret) {
     const subtle = globalThis.crypto?.subtle;
     if (!subtle) {
       throw new Error(
         "Web Crypto unavailable: Delopay.webhooks.verify requires globalThis.crypto.subtle (Node 18+, modern browsers, Workers, Deno)"
       );
     }
+    const signatureBytes = hexToBytes(signatureHeader.trim());
+    if (!signatureBytes) {
+      throw new Error("Invalid webhook signature format");
+    }
     const encoder = new TextEncoder();
+    const bodyBytes = typeof rawBody === "string" ? encoder.encode(rawBody) : rawBody;
     const asBufferSource = (bytes) => bytes;
     const key = await subtle.importKey(
       "raw",
       asBufferSource(encoder.encode(secret)),
-      { name: "HMAC", hash: "SHA-256" },
+      { name: "HMAC", hash: "SHA-512" },
       false,
       ["verify"]
     );
-    const signedPayload = asBufferSource(encoder.encode(`${timestamp}.${rawBody}`));
-    const signaturesMatch = signatureBytes !== null && await subtle.verify("HMAC", key, asBufferSource(signatureBytes), signedPayload);
-    if (!signaturesMatch) {
+    const valid = await subtle.verify(
+      "HMAC",
+      key,
+      asBufferSource(signatureBytes),
+      asBufferSource(bodyBytes)
+    );
+    if (!valid) {
       throw new Error("Invalid webhook signature");
     }
-    const age = Math.floor(Date.now() / 1e3) - timestamp;
-    if (Math.abs(age) > tolerance) {
-      throw new Error("Webhook timestamp too old");
-    }
-    return JSON.parse(rawBody);
+    const bodyText = typeof rawBody === "string" ? rawBody : new TextDecoder("utf-8").decode(rawBody);
+    return JSON.parse(bodyText);
   }
 };
 
@@ -2826,4 +2877,4 @@ export {
   Subscriptions,
   Delopay
 };
-//# sourceMappingURL=chunk-WTVISXEY.js.map
+//# sourceMappingURL=chunk-VQPHGGNQ.js.map