@centrali-io/centrali-sdk 5.2.0 → 5.3.0

package/dist/index.js

@@ -51,7 +51,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CentraliSDK = exports.FunctionRunsManager = exports.ComputeFunctionsManager = exports.CollectionsManager = exports.StructuresManager = exports.AllowedDomainsManager = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.OrchestrationsManager = exports.RealtimeManager = exports.CentraliError = void 0;
+exports.CentraliSDK = exports.WebhookSubscriptionsManager = exports.FunctionRunsManager = exports.ComputeFunctionsManager = exports.CollectionsManager = exports.StructuresManager = exports.AllowedDomainsManager = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.OrchestrationsManager = exports.RealtimeManager = exports.RecordEvents = exports.CentraliError = void 0;
 exports.isCentraliError = isCentraliError;
 exports.getApiUrl = getApiUrl;
 exports.getAuthUrl = getAuthUrl;
@@ -103,6 +103,11 @@ exports.getOrchestrationsApiPath = getOrchestrationsApiPath;
 exports.getOrchestrationRunsApiPath = getOrchestrationRunsApiPath;
 exports.getOrchestrationRunStepsApiPath = getOrchestrationRunStepsApiPath;
 exports.getAllowedDomainsApiPath = getAllowedDomainsApiPath;
+exports.getWebhookSubscriptionsApiPath = getWebhookSubscriptionsApiPath;
+exports.getWebhookSubscriptionRotateSecretApiPath = getWebhookSubscriptionRotateSecretApiPath;
+exports.getWebhookSubscriptionDeliveriesApiPath = getWebhookSubscriptionDeliveriesApiPath;
+exports.getWebhookDeliveryRetryApiPath = getWebhookDeliveryRetryApiPath;
+exports.getWebhookDeliveryCancelApiPath = getWebhookDeliveryCancelApiPath;
 const axios_1 = __importStar(require("axios"));
 const qs_1 = __importDefault(require("qs"));
 const eventsource_1 = require("eventsource");
@@ -193,6 +198,28 @@ function toCentraliError(err) {
 function encodeFormData(data) {
     return new URLSearchParams(data).toString();
 }
+// =====================================================
+// Webhook Subscription Types
+// =====================================================
+/**
+ * Record event name constants — use these when constructing `events` on a
+ * webhook subscription instead of hand-typing strings.
+ *
+ * @example
+ * ```ts
+ * await centrali.webhookSubscriptions.create({
+ *   name: 'Order created',
+ *   url: 'https://my-app.example.com/webhooks/centrali',
+ *   events: [RecordEvents.CREATED, RecordEvents.UPDATED],
+ * });
+ * ```
+ */
+exports.RecordEvents = {
+    CREATED: 'record_created',
+    UPDATED: 'record_updated',
+    DELETED: 'record_deleted',
+    BULK_CREATED: 'records_bulk_created',
+};
 /**
  * Generate the API URL from the base URL by adding the 'api.' subdomain.
  * E.g., https://centrali.io -> https://api.centrali.io
@@ -798,6 +825,43 @@ function getAllowedDomainsApiPath(workspaceId, domainId) {
     return domainId ? `${basePath}/${domainId}` : basePath;
 }
 // =====================================================
+// Webhook Subscription API Paths
+// =====================================================
+/**
+ * Generate Webhook Subscriptions API URL PATH.
+ */
+function getWebhookSubscriptionsApiPath(workspaceId, subscriptionId) {
+    const basePath = `data/workspace/${workspaceId}/api/v1/webhook-subscriptions`;
+    return subscriptionId ? `${basePath}/${subscriptionId}` : basePath;
+}
+/**
+ * Generate rotate-secret API URL PATH for a webhook subscription.
+ */
+function getWebhookSubscriptionRotateSecretApiPath(workspaceId, subscriptionId) {
+    return `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/${subscriptionId}/rotate-secret`;
+}
+/**
+ * Generate deliveries API URL PATH scoped to a webhook subscription.
+ */
+function getWebhookSubscriptionDeliveriesApiPath(workspaceId, subscriptionId, deliveryId) {
+    const basePath = `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/${subscriptionId}/deliveries`;
+    return deliveryId ? `${basePath}/${deliveryId}` : basePath;
+}
+/**
+ * Generate retry API URL PATH for a webhook delivery.
+ * Retry is workspace-scoped (not nested under a subscription) — only the delivery ID is needed.
+ */
+function getWebhookDeliveryRetryApiPath(workspaceId, deliveryId) {
+    return `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/deliveries/${deliveryId}/retry`;
+}
+/**
+ * Generate cancel API URL PATH for a webhook delivery retry.
+ * Cancel is workspace-scoped — only the delivery ID is needed.
+ */
+function getWebhookDeliveryCancelApiPath(workspaceId, deliveryId) {
+    return `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/deliveries/${deliveryId}/cancel`;
+}
+// =====================================================
 // Orchestrations Manager
 // =====================================================
 /**
@@ -2709,6 +2773,146 @@ class FunctionRunsManager {
     }
 }
 exports.FunctionRunsManager = FunctionRunsManager;
+// =====================================================
+// Webhook Subscriptions Manager
+// =====================================================
+/**
+ * WebhookSubscriptionsManager provides methods for managing outbound webhook
+ * subscriptions and inspecting delivery history. Access via
+ * `centrali.webhookSubscriptions`.
+ *
+ * Subscriptions listen for record events (`record_created`, `record_updated`,
+ * `record_deleted`, `records_bulk_created`) and POST a signed JSON payload to
+ * your URL. Payloads are signed with HMAC-SHA256 using the subscription's
+ * `whsec_` secret and delivered in the `X-Signature` header.
+ *
+ * Usage:
+ * ```ts
+ * // Create a subscription
+ * const sub = await centrali.webhookSubscriptions.create({
+ *   name: 'Orders webhook',
+ *   url: 'https://my-app.example.com/webhooks/centrali',
+ *   events: [RecordEvents.CREATED, RecordEvents.UPDATED],
+ *   recordSlugs: ['orders'],
+ * });
+ * // The signing secret is returned on create — copy it now, it's not shown again.
+ * // `secret` is typed `string | undefined` (reads omit it), so assert here.
+ * console.log('Signing secret:', sub.data.secret!);
+ *
+ * // Rotate the secret (immediate cutover)
+ * const rotated = await centrali.webhookSubscriptions.rotateSecret(sub.data.id);
+ *
+ * // Inspect delivery history
+ * const deliveries = await centrali.webhookSubscriptions.deliveries.list(sub.data.id);
+ *
+ * // Replay a delivery
+ * await centrali.webhookSubscriptions.deliveries.retry(deliveryId);
+ * ```
+ */
+class WebhookSubscriptionsManager {
+    constructor(workspaceId, requestFn) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+        const toIso = (v) => {
+            if (!v)
+                return undefined;
+            return v instanceof Date ? v.toISOString() : v;
+        };
+        this.deliveries = {
+            list: (subscriptionId, options) => {
+                const path = getWebhookSubscriptionDeliveriesApiPath(this.workspaceId, subscriptionId);
+                const queryParams = {};
+                if (options === null || options === void 0 ? void 0 : options.status)
+                    queryParams.status = options.status;
+                if (options === null || options === void 0 ? void 0 : options.since)
+                    queryParams.since = toIso(options.since);
+                if (options === null || options === void 0 ? void 0 : options.until)
+                    queryParams.until = toIso(options.until);
+                if ((options === null || options === void 0 ? void 0 : options.limit) !== undefined)
+                    queryParams.limit = options.limit;
+                if ((options === null || options === void 0 ? void 0 : options.offset) !== undefined)
+                    queryParams.offset = options.offset;
+                return this.requestFn('GET', path, null, Object.keys(queryParams).length > 0 ? queryParams : undefined);
+            },
+            get: (subscriptionId, deliveryId) => {
+                const path = getWebhookSubscriptionDeliveriesApiPath(this.workspaceId, subscriptionId, deliveryId);
+                return this.requestFn('GET', path);
+            },
+            retry: (deliveryId) => {
+                const path = getWebhookDeliveryRetryApiPath(this.workspaceId, deliveryId);
+                return this.requestFn('POST', path);
+            },
+            cancel: (deliveryId) => {
+                const path = getWebhookDeliveryCancelApiPath(this.workspaceId, deliveryId);
+                return this.requestFn('POST', path);
+            },
+        };
+    }
+    /**
+     * List all webhook subscriptions in the workspace.
+     *
+     * @example
+     * ```ts
+     * const subs = await centrali.webhookSubscriptions.list();
+     * for (const sub of subs.data) console.log(sub.name, sub.url);
+     * ```
+     */
+    list() {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId);
+        return this.requestFn('GET', path);
+    }
+    /**
+     * Get a webhook subscription by ID.
+     * @param subscriptionId - The subscription UUID
+     */
+    get(subscriptionId) {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn('GET', path);
+    }
+    /**
+     * Create a webhook subscription. The response `secret` field is only
+     * populated on this call (and on `rotateSecret`) — copy it immediately;
+     * subsequent `get`/`list` responses do not return the secret.
+     *
+     * @example
+     * ```ts
+     * const sub = await centrali.webhookSubscriptions.create({
+     *   name: 'Order notifications',
+     *   url: 'https://api.example.com/hooks/centrali',
+     *   events: [RecordEvents.CREATED, RecordEvents.UPDATED],
+     *   recordSlugs: ['orders'],
+     * });
+     * const signingSecret = sub.data.secret; // copy once — not returned on reads
+     * ```
+     */
+    create(input) {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId);
+        return this.requestFn('POST', path, input);
+    }
+    /**
+     * Update fields on a webhook subscription. The signing secret is managed
+     * by the server — use `rotateSecret()` to regenerate it.
+     */
+    update(subscriptionId, patch) {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn('PATCH', path, patch);
+    }
+    /** Delete a webhook subscription. Existing delivery history is retained. */
+    delete(subscriptionId) {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn('DELETE', path);
+    }
+    /**
+     * Rotate the signing secret. Immediate cutover — the previous secret stops
+     * signing on the next dispatch. The response includes the new secret;
+     * capture it before closing the response.
+     */
+    rotateSecret(subscriptionId) {
+        const path = getWebhookSubscriptionRotateSecretApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn('POST', path);
+    }
+}
+exports.WebhookSubscriptionsManager = WebhookSubscriptionsManager;
 /**
  * Main Centrali SDK client.
  */
@@ -2726,6 +2930,7 @@ class CentraliSDK {
         this._collections = null;
         this._functions = null;
         this._runs = null;
+        this._webhookSubscriptions = null;
         this.isRefreshingToken = false;
         this.tokenRefreshPromise = null;
         this.options = options;
@@ -3141,6 +3346,39 @@ class CentraliSDK {
         }
         return this._runs;
     }
+    /**
+     * Webhook subscriptions namespace for outbound webhooks — create, update,
+     * rotate signing secrets, inspect delivery history, and replay/cancel
+     * individual deliveries.
+     *
+     * Usage:
+     * ```ts
+     * // Create a subscription (capture secret immediately — not returned on reads)
+     * const sub = await centrali.webhookSubscriptions.create({
+     *   name: 'Order notifications',
+     *   url: 'https://api.example.com/hooks/centrali',
+     *   events: [RecordEvents.CREATED, RecordEvents.UPDATED],
+     *   recordSlugs: ['orders'],
+     * });
+     *
+     * // Rotate the signing secret (immediate cutover)
+     * const rotated = await centrali.webhookSubscriptions.rotateSecret(sub.data.id);
+     *
+     * // Inspect deliveries
+     * const deliveries = await centrali.webhookSubscriptions.deliveries.list(sub.data.id, {
+     *   status: 'failed'
+     * });
+     *
+     * // Replay a failed delivery
+     * await centrali.webhookSubscriptions.deliveries.retry(deliveries.data[0].id);
+     * ```
+     */
+    get webhookSubscriptions() {
+        if (!this._webhookSubscriptions) {
+            this._webhookSubscriptions = new WebhookSubscriptionsManager(this.options.workspaceId, this.request.bind(this));
+        }
+        return this._webhookSubscriptions;
+    }
     /**
      * Manually set or update the bearer token for subsequent requests.
      */