@epostak/sdk 1.0.0 → 1.1.0

package/dist/resources/webhooks.js

@@ -1,49 +1,270 @@
 import { BaseResource, buildQuery } from "../utils/request.js";
+/**
+ * Sub-resource for the webhook pull queue — an alternative to push webhooks.
+ * Use the pull queue when your server cannot receive inbound HTTPS requests.
+ * Events accumulate in the queue and must be acknowledged after processing.
+ *
+ * @example
+ * ```typescript
+ * // Poll-based event consumption loop
+ * const { items, has_more } = await client.webhooks.queue.pull({ limit: 50 });
+ * for (const item of items) {
+ *   await processEvent(item);
+ *   await client.webhooks.queue.ack(item.id);
+ * }
+ * ```
+ */
 export class WebhookQueueResource extends BaseResource {
+    /**
+     * Pull unacknowledged events from the webhook queue.
+     * Events remain in the queue until explicitly acknowledged via `ack()` or `batchAck()`.
+     *
+     * @param params - Optional limit and event type filter
+     * @returns Array of queue items and whether more items are available
+     *
+     * @example
+     * ```typescript
+     * const { items, has_more } = await client.webhooks.queue.pull({
+     *   limit: 20,
+     *   event_type: 'document.received',
+     * });
+     * ```
+     */
     pull(params) {
         return this.request("GET", `/webhook-queue${buildQuery({
             limit: params?.limit,
             event_type: params?.event_type,
         })}`);
     }
+    /**
+     * Acknowledge (remove) a single event from the queue after processing.
+     *
+     * @param eventId - The event ID to acknowledge
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * await client.webhooks.queue.ack('event-uuid');
+     * ```
+     */
     ack(eventId) {
         return this.request("DELETE", `/webhook-queue/${encodeURIComponent(eventId)}`);
     }
+    /**
+     * Acknowledge (remove) multiple events from the queue in a single request.
+     *
+     * @param eventIds - Array of event IDs to acknowledge
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * const { items } = await client.webhooks.queue.pull({ limit: 50 });
+     * // Process all items...
+     * await client.webhooks.queue.batchAck(items.map(i => i.id));
+     * ```
+     */
     batchAck(eventIds) {
-        return this.request("POST", "/webhook-queue/batch-ack", { event_ids: eventIds });
+        return this.request("POST", "/webhook-queue/batch-ack", {
+            event_ids: eventIds,
+        });
     }
+    /**
+     * Pull events across all managed firms (integrator endpoint).
+     * Only available with integrator API keys (`sk_int_*`).
+     * Use the `since` parameter for cursor-based polling.
+     *
+     * @param params - Optional limit and since timestamp for cursor-based polling
+     * @returns Array of events across all firms with count
+     *
+     * @example
+     * ```typescript
+     * const { events, count } = await client.webhooks.queue.pullAll({
+     *   since: '2026-04-11T00:00:00Z',
+     *   limit: 200,
+     * });
+     * ```
+     */
     pullAll(params) {
         return this.request("GET", `/webhook-queue/all${buildQuery({
             limit: params?.limit,
             since: params?.since,
         })}`);
     }
+    /**
+     * Acknowledge (remove) multiple events from the cross-firm queue (integrator endpoint).
+     * Only available with integrator API keys (`sk_int_*`).
+     *
+     * @param eventIds - Array of event IDs to acknowledge
+     * @returns Object with the count of acknowledged events
+     *
+     * @example
+     * ```typescript
+     * const { events } = await client.webhooks.queue.pullAll({ limit: 100 });
+     * // Process all events...
+     * const { acknowledged } = await client.webhooks.queue.batchAckAll(
+     *   events.map(e => e.event_id),
+     * );
+     * ```
+     */
     batchAckAll(eventIds) {
-        return this.request("POST", "/webhook-queue/all/batch-ack", { event_ids: eventIds });
+        return this.request("POST", "/webhook-queue/all/batch-ack", {
+            event_ids: eventIds,
+        });
     }
 }
+/**
+ * Resource for managing webhook subscriptions and the pull queue.
+ * Webhooks notify your server about document events (sent, received, validated).
+ * Choose between push webhooks (server receives HTTPS POST) or the pull queue
+ * (your code polls for events).
+ *
+ * @example
+ * ```typescript
+ * // Create a push webhook
+ * const webhook = await client.webhooks.create({
+ *   url: 'https://example.com/webhooks/epostak',
+ *   events: ['document.received', 'document.sent'],
+ * });
+ * // Store webhook.secret for HMAC verification
+ * ```
+ */
 export class WebhooksResource extends BaseResource {
-    /** Access the webhook pull queue for polling-based consumption */
+    /** Sub-resource for the pull queue (polling-based event consumption) */
     queue;
     constructor(config) {
         super(config);
         this.queue = new WebhookQueueResource(config);
     }
+    /**
+     * Create a new webhook subscription. Returns the HMAC-SHA256 signing secret
+     * which is only available at creation time — store it securely.
+     *
+     * @param body - Webhook URL and optional event filter
+     * @returns Webhook details including the one-time signing secret
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.create({
+     *   url: 'https://example.com/webhooks',
+     *   events: ['document.received'],
+     * });
+     * console.log(webhook.secret); // Store this securely!
+     * ```
+     */
     create(body) {
         return this.request("POST", "/webhooks", body);
     }
+    /**
+     * List all webhook subscriptions for the current account.
+     *
+     * @returns Array of webhook subscriptions
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await client.webhooks.list();
+     * webhooks.forEach(w => console.log(w.url, w.isActive));
+     * ```
+     */
     async list() {
         const res = await this.request("GET", "/webhooks");
         return res.data;
     }
+    /**
+     * Get a webhook subscription by ID, including recent delivery history.
+     * Use the delivery history to debug failed webhook deliveries.
+     *
+     * @param id - Webhook UUID
+     * @returns Webhook details with delivery history
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.get('webhook-uuid');
+     * const failedDeliveries = webhook.deliveries.filter(d => d.status === 'failed');
+     * ```
+     */
     get(id) {
         return this.request("GET", `/webhooks/${encodeURIComponent(id)}`);
     }
+    /**
+     * Update a webhook subscription. Use this to change the URL, event filter,
+     * or pause/resume the webhook.
+     *
+     * @param id - Webhook UUID
+     * @param body - Fields to update (omit to leave unchanged)
+     * @returns The updated webhook
+     *
+     * @example
+     * ```typescript
+     * // Pause a webhook
+     * await client.webhooks.update('webhook-uuid', { isActive: false });
+     *
+     * // Change URL and events
+     * await client.webhooks.update('webhook-uuid', {
+     *   url: 'https://new-url.com/webhooks',
+     *   events: ['document.received', 'document.validated'],
+     * });
+     * ```
+     */
     update(id, body) {
         return this.request("PATCH", `/webhooks/${encodeURIComponent(id)}`, body);
     }
+    /**
+     * Delete a webhook subscription. Stops all future deliveries for this webhook.
+     *
+     * @param id - Webhook UUID to delete
+     * @returns Confirmation with `deleted: true`
+     *
+     * @example
+     * ```typescript
+     * await client.webhooks.delete('webhook-uuid');
+     * ```
+     */
     delete(id) {
         return this.request("DELETE", `/webhooks/${encodeURIComponent(id)}`);
     }
+    /**
+     * Send a test event to a webhook endpoint. Useful for verifying your
+     * webhook URL is reachable and responding correctly.
+     *
+     * @param id - Webhook UUID to test
+     * @param event - Event type to simulate (defaults to server-chosen event)
+     * @returns Test result with success status, HTTP status code, and response time
+     *
+     * @example
+     * ```typescript
+     * const result = await client.webhooks.test('webhook-uuid');
+     * console.log(result.success, result.responseTime + 'ms');
+     * ```
+     */
+    test(id, event) {
+        const body = {};
+        if (event)
+            body.event = event;
+        return this.request("POST", `/webhooks/${encodeURIComponent(id)}/test`, body);
+    }
+    /**
+     * Get paginated delivery history for a webhook. Use this to inspect
+     * individual delivery attempts, filter by status, and debug failures.
+     *
+     * @param id - Webhook UUID
+     * @param params - Optional pagination and filter parameters
+     * @returns Paginated list of delivery records with total count
+     *
+     * @example
+     * ```typescript
+     * const { deliveries, total } = await client.webhooks.deliveries('webhook-uuid', {
+     *   status: 'FAILED',
+     *   limit: 50,
+     * });
+     * ```
+     */
+    deliveries(id, params) {
+        return this.request("GET", `/webhooks/${encodeURIComponent(id)}/deliveries${buildQuery({
+            limit: params?.limit,
+            offset: params?.offset,
+            status: params?.status,
+            event: params?.event,
+        })}`);
+    }
 }
 //# sourceMappingURL=webhooks.js.map

package/dist/resources/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/resources/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAe/D,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,IAAI,CAAC,MAA2B;QAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,iBAAiB,UAAU,CAAC;YACrD,KAAK,EAAE,MAAM,EAAE,KAAK;YACpB,UAAU,EAAE,MAAM,EAAE,UAAU;SAC/B,CAAC,EAAE,CAAC,CAAC;IACR,CAAC;IAED,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,kBAAkB,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,QAAQ,CAAC,QAAkB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,0BAA0B,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,OAAO,CAAC,MAA8B;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,qBAAqB,UAAU,CAAC;YACzD,KAAK,EAAE,MAAM,EAAE,KAAK;YACpB,KAAK,EAAE,MAAM,EAAE,KAAK;SACrB,CAAC,EAAE,CAAC,CAAC;IACR,CAAC;IAED,WAAW,CAAC,QAAkB;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,8BAA8B,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IACvF,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAChD,kEAAkE;IAClE,KAAK,CAAuB;IAE5B,YAAY,MAAoB;QAC9B,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,KAAK,GAAG,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,IAA0B;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAsB,KAAK,EAAE,WAAW,CAAC,CAAC;QACxE,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,aAAa,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,CAAC,EAAU,EAAE,IAA0B;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,aAAa,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,CAAC,EAAU;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,aAAa,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;CACF"}
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/resources/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAmB/D;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,MAA2B;QAC9B,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,iBAAiB,UAAU,CAAC;YAC1B,KAAK,EAAE,MAAM,EAAE,KAAK;YACpB,UAAU,EAAE,MAAM,EAAE,UAAU;SAC/B,CAAC,EAAE,CACL,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,OAAO,CACjB,QAAQ,EACR,kBAAkB,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAChD,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAkB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,0BAA0B,EAAE;YACtD,SAAS,EAAE,QAAQ;SACpB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAA8B;QACpC,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,qBAAqB,UAAU,CAAC;YAC9B,KAAK,EAAE,MAAM,EAAE,KAAK;YACpB,KAAK,EAAE,MAAM,EAAE,KAAK;SACrB,CAAC,EAAE,CACL,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,QAAkB;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,8BAA8B,EAAE;YAC1D,SAAS,EAAE,QAAQ;SACpB,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAChD,wEAAwE;IACxE,KAAK,CAAuB;IAE5B,YAAY,MAAoB;QAC9B,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,KAAK,GAAG,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,IAA0B;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAsB,KAAK,EAAE,WAAW,CAAC,CAAC;QACxE,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,aAAa,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,EAAU,EAAE,IAA0B;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,aAAa,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAU;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,aAAa,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAU,EAAE,KAAoB;QACnC,MAAM,IAAI,GAA2B,EAAE,CAAC;QACxC,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAC9B,OAAO,IAAI,CAAC,OAAO,CACjB,MAAM,EACN,aAAa,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAC1C,IAAI,CACL,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CACR,EAAU,EACV,MAAgC;QAEhC,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,aAAa,kBAAkB,CAAC,EAAE,CAAC,cAAc,UAAU,CAAC;YAC1D,KAAK,EAAE,MAAM,EAAE,KAAK;YACpB,MAAM,EAAE,MAAM,EAAE,MAAM;YACtB,MAAM,EAAE,MAAM,EAAE,MAAM;YACtB,KAAK,EAAE,MAAM,EAAE,KAAK;SACrB,CAAC,EAAE,CACL,CAAC;IACJ,CAAC;CACF"}