@centrali-io/centrali-sdk 5.2.0 → 5.3.0

package/index.ts

@@ -2367,6 +2367,139 @@ export interface BulkOperationResult {
     message: string;
 }
 
+// =====================================================
+// 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],
+ * });
+ * ```
+ */
+export const RecordEvents = {
+    CREATED: 'record_created',
+    UPDATED: 'record_updated',
+    DELETED: 'record_deleted',
+    BULK_CREATED: 'records_bulk_created',
+} as const;
+
+export type WebhookDeliveryStatus = 'success' | 'failed' | 'retrying';
+
+export interface WebhookSubscription {
+    id: string;
+    name: string;
+    url: string;
+    events: RecordEventType[];
+    /**
+     * Optional list of record slugs to scope the subscription to. When null or
+     * empty, the subscription receives events for all collections.
+     */
+    recordSlugs?: string[] | null;
+    active: boolean;
+    /**
+     * Signing secret (`whsec_` prefix). Returned by `create` and `rotateSecret`;
+     * undefined on subsequent reads so it is safe to pass subscriptions around.
+     */
+    secret?: string;
+    workspaceSlug: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+/**
+ * Full webhook delivery record including request payload and response body.
+ * Returned by `deliveries.get()`.
+ */
+export interface WebhookDelivery {
+    id: string;
+    webhookSubscriptionId: string;
+    workspaceSlug: string;
+    event: string;
+    attemptCount: number;
+    status: WebhookDeliveryStatus;
+    lastError?: string | null;
+    httpStatus?: number | null;
+    lastAttemptAt: string;
+    nextAttemptAt?: string | null;
+    requestPayload?: any;
+    responseBody?: string | null;
+    /** Delivery ID the row was replayed from, or null for original deliveries. */
+    replayedFrom?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * Trimmed delivery row returned by `deliveries.list()` — omits `requestPayload`
+ * and `responseBody`. Fetch individual deliveries with `deliveries.get()` to get
+ * the full payload and response body.
+ */
+export type WebhookDeliverySummary = Omit<WebhookDelivery, 'requestPayload' | 'responseBody'>;
+
+export interface CreateWebhookSubscriptionInput {
+    name: string;
+    url: string;
+    events: RecordEventType[];
+    /** Optional — restrict to a subset of collections. Omit for all collections. */
+    recordSlugs?: string[];
+    active?: boolean;
+}
+
+export interface UpdateWebhookSubscriptionInput {
+    name?: string;
+    url?: string;
+    events?: RecordEventType[];
+    /**
+     * Update the collection scope. Pass an empty array (`[]`) to clear the
+     * restriction so the subscription receives events for all collections.
+     * Omit the field to leave the scope unchanged.
+     */
+    recordSlugs?: string[];
+    active?: boolean;
+}
+
+export interface ListWebhookDeliveriesOptions {
+    status?: WebhookDeliveryStatus;
+    /** ISO 8601 datetime or Date — include deliveries created at or after this time. */
+    since?: string | Date;
+    /** ISO 8601 datetime or Date — include deliveries created at or before this time. */
+    until?: string | Date;
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * Pagination metadata returned alongside `deliveries.list()` rows. The backend
+ * surfaces `{ data, meta }` which the SDK normalizer passes through as the
+ * `ApiResponse` itself — so `result.data` is the array and `result.meta` is
+ * this object.
+ */
+export interface WebhookDeliveriesListMeta {
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+export interface WebhookReplayResponse {
+    deliveryId: string;
+    replayedFrom: string | null;
+    status: WebhookDeliveryStatus;
+}
+
+export interface WebhookCancelResponse {
+    deliveryId: string;
+    status: WebhookDeliveryStatus;
+    lastError: string | null;
+}
+
 /**
  * Generate the API URL from the base URL by adding the 'api.' subdomain.
  * E.g., https://centrali.io -> https://api.centrali.io
@@ -3066,6 +3199,49 @@ export function getAllowedDomainsApiPath(workspaceId: string, domainId?: string)
     return domainId ? `${basePath}/${domainId}` : basePath;
 }
 
+// =====================================================
+// Webhook Subscription API Paths
+// =====================================================
+
+/**
+ * Generate Webhook Subscriptions API URL PATH.
+ */
+export function getWebhookSubscriptionsApiPath(workspaceId: string, subscriptionId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/webhook-subscriptions`;
+    return subscriptionId ? `${basePath}/${subscriptionId}` : basePath;
+}
+
+/**
+ * Generate rotate-secret API URL PATH for a webhook subscription.
+ */
+export function getWebhookSubscriptionRotateSecretApiPath(workspaceId: string, subscriptionId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/${subscriptionId}/rotate-secret`;
+}
+
+/**
+ * Generate deliveries API URL PATH scoped to a webhook subscription.
+ */
+export function getWebhookSubscriptionDeliveriesApiPath(workspaceId: string, subscriptionId: string, deliveryId?: string): string {
+    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.
+ */
+export function getWebhookDeliveryRetryApiPath(workspaceId: string, deliveryId: string): string {
+    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.
+ */
+export function getWebhookDeliveryCancelApiPath(workspaceId: string, deliveryId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/webhook-subscriptions/deliveries/${deliveryId}/cancel`;
+}
+
 // =====================================================
 // Orchestrations Manager
 // =====================================================
@@ -5146,6 +5322,188 @@ export class 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);
+ * ```
+ */
+export class WebhookSubscriptionsManager {
+    private requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>;
+    private workspaceId: string;
+
+    /**
+     * Delivery history and replay controls. Deliveries are per-subscription for
+     * list/get, but retry/cancel are workspace-scoped — the backend routes
+     * those under `/webhook-subscriptions/deliveries/{id}/retry|cancel`, so the
+     * subscription ID is not needed to replay or cancel.
+     */
+    public readonly deliveries: {
+        /**
+         * List deliveries for a subscription. Rows omit `requestPayload` and
+         * `responseBody` — use `deliveries.get()` to fetch the full record.
+         * `result.data` is the array of trimmed rows; `result.meta` carries
+         * the pagination counters (`total`, `limit`, `offset`).
+         */
+        list: (subscriptionId: string, options?: ListWebhookDeliveriesOptions) => Promise<ApiResponse<WebhookDeliverySummary[]> & { meta?: WebhookDeliveriesListMeta }>;
+        /** Get a single delivery including the full payload and response body. */
+        get: (subscriptionId: string, deliveryId: string) => Promise<ApiResponse<WebhookDelivery>>;
+        /**
+         * Replay a previously recorded delivery. Queues a new delivery row
+         * pointing at `replayedFrom` the original. Returns the new delivery ID.
+         */
+        retry: (deliveryId: string) => Promise<ApiResponse<WebhookReplayResponse>>;
+        /**
+         * Cancel a delivery that is currently in `retrying` status. Flips the
+         * row to `failed` with `lastError = 'Cancelled by user'`.
+         */
+        cancel: (deliveryId: string) => Promise<ApiResponse<WebhookCancelResponse>>;
+    };
+
+    constructor(
+        workspaceId: string,
+        requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>
+    ) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+
+        const toIso = (v: string | Date | undefined): string | undefined => {
+            if (!v) return undefined;
+            return v instanceof Date ? v.toISOString() : v;
+        };
+
+        this.deliveries = {
+            list: (subscriptionId: string, options?: ListWebhookDeliveriesOptions) => {
+                const path = getWebhookSubscriptionDeliveriesApiPath(this.workspaceId, subscriptionId);
+                const queryParams: Record<string, any> = {};
+                if (options?.status) queryParams.status = options.status;
+                if (options?.since) queryParams.since = toIso(options.since);
+                if (options?.until) queryParams.until = toIso(options.until);
+                if (options?.limit !== undefined) queryParams.limit = options.limit;
+                if (options?.offset !== undefined) queryParams.offset = options.offset;
+                return this.requestFn<WebhookDeliverySummary[]>(
+                    'GET',
+                    path,
+                    null,
+                    Object.keys(queryParams).length > 0 ? queryParams : undefined
+                ) as Promise<ApiResponse<WebhookDeliverySummary[]> & { meta?: WebhookDeliveriesListMeta }>;
+            },
+            get: (subscriptionId: string, deliveryId: string) => {
+                const path = getWebhookSubscriptionDeliveriesApiPath(this.workspaceId, subscriptionId, deliveryId);
+                return this.requestFn<WebhookDelivery>('GET', path);
+            },
+            retry: (deliveryId: string) => {
+                const path = getWebhookDeliveryRetryApiPath(this.workspaceId, deliveryId);
+                return this.requestFn<WebhookReplayResponse>('POST', path);
+            },
+            cancel: (deliveryId: string) => {
+                const path = getWebhookDeliveryCancelApiPath(this.workspaceId, deliveryId);
+                return this.requestFn<WebhookCancelResponse>('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);
+     * ```
+     */
+    public list(): Promise<ApiResponse<WebhookSubscription[]>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId);
+        return this.requestFn<WebhookSubscription[]>('GET', path);
+    }
+
+    /**
+     * Get a webhook subscription by ID.
+     * @param subscriptionId - The subscription UUID
+     */
+    public get(subscriptionId: string): Promise<ApiResponse<WebhookSubscription>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn<WebhookSubscription>('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
+     * ```
+     */
+    public create(input: CreateWebhookSubscriptionInput): Promise<ApiResponse<WebhookSubscription>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId);
+        return this.requestFn<WebhookSubscription>('POST', path, input);
+    }
+
+    /**
+     * Update fields on a webhook subscription. The signing secret is managed
+     * by the server — use `rotateSecret()` to regenerate it.
+     */
+    public update(subscriptionId: string, patch: UpdateWebhookSubscriptionInput): Promise<ApiResponse<WebhookSubscription>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn<WebhookSubscription>('PATCH', path, patch);
+    }
+
+    /** Delete a webhook subscription. Existing delivery history is retained. */
+    public delete(subscriptionId: string): Promise<ApiResponse<void>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn<void>('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.
+     */
+    public rotateSecret(subscriptionId: string): Promise<ApiResponse<WebhookSubscription>> {
+        const path = getWebhookSubscriptionRotateSecretApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn<WebhookSubscription>('POST', path);
+    }
+}
+
 /**
  * Main Centrali SDK client.
  */
@@ -5164,6 +5522,7 @@ export class CentraliSDK {
     private _collections: CollectionsManager | null = null;
     private _functions: ComputeFunctionsManager | null = null;
     private _runs: FunctionRunsManager | null = null;
+    private _webhookSubscriptions: WebhookSubscriptionsManager | null = null;
     private isRefreshingToken: boolean = false;
     private tokenRefreshPromise: Promise<string> | null = null;
 
@@ -5661,6 +6020,43 @@ export 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);
+     * ```
+     */
+    public get webhookSubscriptions(): WebhookSubscriptionsManager {
+        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.
      */

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "type": "commonjs",
   "repository": {
     "type": "git",
@@ -10,8 +11,7 @@
   },
   "scripts": {
     "build": "tsc --project tsconfig.json",
-    "prepublishOnly": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "prepublishOnly": "npm run build"
   },
   "keywords": [],
   "author": "Blueinit",
@@ -25,7 +25,7 @@
     "@types/eventsource": "^1.1.15",
     "@types/q": "^1.5.8",
     "@types/qs": "^6.14.0",
-    "typescript": "^5.8.3"
+    "typescript": "5.9.3"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/tsconfig.json

@@ -52,7 +52,7 @@
     // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
 
     /* Emit */
-    // "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+    "declaration": true,                                 /* Emit .d.ts alongside .js so consumers don't re-parse index.ts (~6.6k lines) on every build. */
     // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
     // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
     // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */