@nurama/sdk 0.0.0-stage → 1.4.0

package/dist/routes/user.d.ts

@@ -0,0 +1,112 @@
+import NuramaClient from '../NuramaClient.js';
+import { type User, type PublicUser } from '@nurama/types';
+export interface FileData {
+    name: string;
+    checksum: string;
+    sizeInMB: number;
+}
+export interface UpdateUserData {
+    email?: string;
+    userName?: string;
+    password?: string;
+    firstName?: string;
+    middleName?: string;
+    lastName?: string;
+    company?: string;
+    displayName?: string;
+    color?: string;
+    allowOauthAutolink?: boolean;
+}
+export interface PreferencesData {
+    hide?: string[];
+    dismissed?: {
+        todos?: string[];
+    };
+    dailyTips?: {
+        disabled?: boolean;
+        lastShownDate?: string;
+    };
+    featureIntros?: Record<string, string[]>;
+    dateFormat?: 'european' | 'american' | 'iso';
+}
+export interface UserTodo {
+    id: string;
+    dismissible: boolean;
+}
+/**
+ * Defines user-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the user-related methods.
+ */
+export default function createUserMethods(client: NuramaClient): {
+    /**
+     * Retrieves the public profile of a specific user.
+     * Requires authentication.
+     * @param {string} userId - The ID of the user to retrieve.
+     * @returns {Promise<object>} Public user object.
+     */
+    getUser(userId: string): Promise<PublicUser>;
+    /**
+     * Retrieves the current user's profile.
+     * Requires authentication.
+     * @returns {Promise<PublicUser>} The current user's profile.
+     * @throws {Error} If no user ID is found in the token.
+     */
+    getSelf(): Promise<PublicUser>;
+    /**
+     * Deletes the current user.
+     * Requires authentication.
+     * @returns {Promise<void>}
+     */
+    deleteCurrentUser(): Promise<void>;
+    /**
+     * Updates the user's avatar.
+     * @param {object} fileData - File metadata (e.g., { name, checksum, sizeInMB }).
+     * @returns {Promise<object>} Object containing signed URL data and updated user info.
+     */
+    updateAvatar(fileData: FileData): Promise<any>;
+    /**
+     * Creates a new avatar for the user.
+     * @param {object} fileData - File metadata (e.g., { name, checksum, sizeInMB }).
+     * @returns {Promise<object>} Object containing signed URL data and updated user info.
+     */
+    createAvatar(fileData: FileData): Promise<any>;
+    /**
+     * Updates the user's preferences.
+     * @param {object} preferenceData - Preference data to update (e.g., { hide: ['feedHint'] }).
+     * @returns {Promise<object>} Updated user object.
+     */
+    updatePreferences(preferenceData: PreferencesData): Promise<User>;
+    /**
+     * Record that the current user has seen a one-time UI element (welcome
+     * video, tutorial coachmark). Idempotent. Returns the updated user.
+     * @param {string} element - one-time element key (see backend oneTimeElements).
+     */
+    markSeen(element: string): Promise<User>;
+    /**
+     * Remove one-time UI elements from the current user's `hasSeen` so they
+     * display again. Pass specific element keys, or omit to clear ALL.
+     * Returns the updated user.
+     * @param {string[]} [elements] - elements to remove; omit to clear all.
+     */
+    unmarkSeen(elements?: string[]): Promise<User>;
+    /**
+     * Updates the logged-in user's profile.
+     * Requires authentication.
+     * At least one field must be provided.
+     * @param {UpdateUserData} updateData - The user data fields to update.
+     * @returns {Promise<User>} The updated user object.
+     */
+    updateSelf(updateData: UpdateUserData): Promise<User>;
+    /**
+     * Get the current user's active site-level Todos for the onboarding
+     * drawer. Returns only todos whose completion condition isn't met and
+     * (for dismissibles) that the user hasn't opted out of. Server
+     * computes from live state — no caching on the server side, so a
+     * fresh call always reflects ground truth.
+     */
+    getTodos(): Promise<{
+        todos: UserTodo[];
+    }>;
+};
+//# sourceMappingURL=user.d.ts.map

package/dist/routes/user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/routes/user.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3D,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAGD,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAMhB,SAAS,CAAC,EAAE;QACV,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IAIF,SAAS,CAAC,EAAE;QACV,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IAGF,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAIzC,UAAU,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,KAAK,CAAC;CAEhD;AAKD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,MAAM,EAAE,YAAY;IAG1D;;;;;OAKG;oBACmB,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAWlD;;;;;OAKG;eACc,OAAO,CAAC,UAAU,CAAC;IAQpC;;;;OAIG;yBACwB,OAAO,CAAC,IAAI,CAAC;IAOxC;;;;OAIG;2BAC0B,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAQpD;;;;OAIG;2BAC0B,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAQpD;;;;OAIG;sCACqC,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IASvE;;;;OAIG;sBACqB,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C;;;;;OAKG;0BACyB,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD;;;;;;OAMG;2BAC0B,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3D;;;;;;OAMG;gBACe,OAAO,CAAC;QAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;EAQnD"}

package/dist/routes/user.js

@@ -0,0 +1,151 @@
+/**
+ * Defines user-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the user-related methods.
+ */
+export default function createUserMethods(client) {
+    // Specify return type more accurately if possible, using UserMethods interface
+    return {
+        /**
+         * Retrieves the public profile of a specific user.
+         * Requires authentication.
+         * @param {string} userId - The ID of the user to retrieve.
+         * @returns {Promise<object>} Public user object.
+         */
+        async getUser(userId) {
+            if (!userId) {
+                throw new Error('userId is required.');
+            }
+            return client._request({
+                method: 'GET',
+                endpoint: `/v1/users/${userId}`,
+                sendJWT: true,
+            });
+        },
+        /**
+         * Retrieves the current user's profile.
+         * Requires authentication.
+         * @returns {Promise<PublicUser>} The current user's profile.
+         * @throws {Error} If no user ID is found in the token.
+         */
+        async getSelf() {
+            return client._request({
+                method: 'GET',
+                endpoint: '/v1/users',
+                sendJWT: true,
+            });
+        },
+        /**
+         * Deletes the current user.
+         * Requires authentication.
+         * @returns {Promise<void>}
+         */
+        async deleteCurrentUser() {
+            return client._request({
+                method: 'DELETE',
+                endpoint: '/v1/users',
+                sendJWT: true,
+            });
+        },
+        /**
+         * Updates the user's avatar.
+         * @param {object} fileData - File metadata (e.g., { name, checksum, sizeInMB }).
+         * @returns {Promise<object>} Object containing signed URL data and updated user info.
+         */
+        async updateAvatar(fileData) {
+            return client._request({
+                method: 'PUT',
+                endpoint: '/v1/users/avatar',
+                body: fileData,
+                sendJWT: true,
+            });
+        },
+        /**
+         * Creates a new avatar for the user.
+         * @param {object} fileData - File metadata (e.g., { name, checksum, sizeInMB }).
+         * @returns {Promise<object>} Object containing signed URL data and updated user info.
+         */
+        async createAvatar(fileData) {
+            return client._request({
+                method: 'POST',
+                endpoint: '/v1/users/avatar',
+                body: fileData,
+                sendJWT: true,
+            });
+        },
+        /**
+         * Updates the user's preferences.
+         * @param {object} preferenceData - Preference data to update (e.g., { hide: ['feedHint'] }).
+         * @returns {Promise<object>} Updated user object.
+         */
+        async updatePreferences(preferenceData) {
+            return client._request({
+                method: 'PATCH',
+                endpoint: '/v1/users/preferences',
+                body: preferenceData,
+                sendJWT: true,
+            });
+        },
+        /**
+         * Record that the current user has seen a one-time UI element (welcome
+         * video, tutorial coachmark). Idempotent. Returns the updated user.
+         * @param {string} element - one-time element key (see backend oneTimeElements).
+         */
+        async markSeen(element) {
+            return client._request({
+                method: 'POST',
+                endpoint: '/v1/users/has-seen',
+                body: { element },
+                sendJWT: true,
+            });
+        },
+        /**
+         * Remove one-time UI elements from the current user's `hasSeen` so they
+         * display again. Pass specific element keys, or omit to clear ALL.
+         * Returns the updated user.
+         * @param {string[]} [elements] - elements to remove; omit to clear all.
+         */
+        async unmarkSeen(elements) {
+            return client._request({
+                method: 'DELETE',
+                endpoint: '/v1/users/has-seen',
+                body: elements ? { elements } : {},
+                sendJWT: true,
+            });
+        },
+        /**
+         * Updates the logged-in user's profile.
+         * Requires authentication.
+         * At least one field must be provided.
+         * @param {UpdateUserData} updateData - The user data fields to update.
+         * @returns {Promise<User>} The updated user object.
+         */
+        async updateSelf(updateData) {
+            // Ensure at least one key is present, matching backend validation .min(1)
+            if (Object.keys(updateData).length === 0) {
+                throw new Error('At least one field must be provided to update the user.');
+            }
+            return client._request({
+                method: 'PATCH',
+                endpoint: '/v1/users', // Endpoint for updating the logged-in user
+                body: updateData,
+                sendJWT: true,
+            });
+        },
+        /**
+         * Get the current user's active site-level Todos for the onboarding
+         * drawer. Returns only todos whose completion condition isn't met and
+         * (for dismissibles) that the user hasn't opted out of. Server
+         * computes from live state — no caching on the server side, so a
+         * fresh call always reflects ground truth.
+         */
+        async getTodos() {
+            return client._request({
+                method: 'GET',
+                endpoint: '/v1/users/todos',
+                sendJWT: true,
+            });
+        },
+    };
+}
+//# sourceMappingURL=user.js.map

package/dist/routes/user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.js","sourceRoot":"","sources":["../../src/routes/user.ts"],"names":[],"mappings":"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"}

package/dist/routes/version.d.ts

@@ -0,0 +1,42 @@
+import NuramaClient from '../NuramaClient.js';
+export interface CommitResponse {
+    buildCommit: string;
+}
+export interface HealthStatus {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Epoch milliseconds when the check ran. */
+    timestamp: number;
+    /** Process uptime in seconds. */
+    uptime: number;
+    /** Present when status is `degraded` or `unhealthy`. */
+    reason?: string;
+    postgres: {
+        status: 'connected' | 'disconnected';
+        [key: string]: unknown;
+    };
+    memory: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Defines version-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the version-related methods.
+ */
+export default function createVersionMethods(client: NuramaClient): {
+    /**
+     * Retrieves the latest git commit hash of the deployed application.
+     * This is a public endpoint and does not require authentication.
+     * @returns {Promise<CommitResponse>} An object containing the buildCommit hash.
+     */
+    getCommitHash(): Promise<CommitResponse>;
+    /**
+     * Retrieves the API health report (database connectivity, memory, uptime).
+     * Public endpoint. Resolves normally for `healthy` and `degraded`; the API
+     * responds 503 for `unhealthy`, which surfaces as a thrown error with `status: 503`
+     * and the report on `data`.
+     * @returns {Promise<HealthStatus>} The health report.
+     */
+    getHealth(): Promise<HealthStatus>;
+};
+export type VersionMethods = ReturnType<typeof createVersionMethods>;
+//# sourceMappingURL=version.d.ts.map

package/dist/routes/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/routes/version.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAG9C,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC7C,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QAAE,MAAM,EAAE,WAAW,GAAG,cAAc,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC3E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,oBAAoB,CAAC,MAAM,EAAE,YAAY;IAE7D;;;;OAIG;qBACoB,OAAO,CAAC,cAAc,CAAC;IAQ9C;;;;;;OAMG;iBACgB,OAAO,CAAC,YAAY,CAAC;EAS3C;AAGD,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/routes/version.js

@@ -0,0 +1,38 @@
+// --- Method Definitions ---
+/**
+ * Defines version-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the version-related methods.
+ */
+export default function createVersionMethods(client) {
+    return {
+        /**
+         * Retrieves the latest git commit hash of the deployed application.
+         * This is a public endpoint and does not require authentication.
+         * @returns {Promise<CommitResponse>} An object containing the buildCommit hash.
+         */
+        async getCommitHash() {
+            return client._request({
+                method: 'GET',
+                endpoint: '/v1/version/commit',
+                sendJWT: false,
+            });
+        },
+        /**
+         * Retrieves the API health report (database connectivity, memory, uptime).
+         * Public endpoint. Resolves normally for `healthy` and `degraded`; the API
+         * responds 503 for `unhealthy`, which surfaces as a thrown error with `status: 503`
+         * and the report on `data`.
+         * @returns {Promise<HealthStatus>} The health report.
+         */
+        async getHealth() {
+            return client._request({
+                method: 'GET',
+                endpoint: '/v1/version/health',
+                sendJWT: false,
+                bypassCache: true,
+            });
+        },
+    };
+}
+//# sourceMappingURL=version.js.map

package/dist/routes/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/routes/version.ts"],"names":[],"mappings":"AAoBA,6BAA6B;AAE7B;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,oBAAoB,CAAC,MAAoB;IAC/D,OAAO;QACL;;;;WAIG;QACH,KAAK,CAAC,aAAa;YACjB,OAAO,MAAM,CAAC,QAAQ,CAAiB;gBACrC,MAAM,EAAE,KAAK;gBACb,QAAQ,EAAE,oBAAoB;gBAC9B,OAAO,EAAE,KAAK;aACf,CAAC,CAAC;QACL,CAAC;QAED;;;;;;WAMG;QACH,KAAK,CAAC,SAAS;YACb,OAAO,MAAM,CAAC,QAAQ,CAAe;gBACnC,MAAM,EAAE,KAAK;gBACb,QAAQ,EAAE,oBAAoB;gBAC9B,OAAO,EAAE,KAAK;gBACd,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/routes/webhook.d.ts

@@ -0,0 +1,170 @@
+import NuramaClient from '../NuramaClient.js';
+/**
+ * Wire-format webhook event names. Mirrors the backend's
+ * `@config/webhookEvents` registry. New events land here and on the
+ * backend together; the additive-only payload contract means receivers
+ * pinned to a specific event name keep working as fields are added.
+ */
+export type WebhookEvent = 'task.created' | 'task.updated' | 'task.deleted' | 'chat.message.created' | 'asset.published' | 'webhook.test';
+export type WebhookSubscriptionStatus = 'active' | 'paused' | 'failedOut';
+/**
+ * Public shape of a webhook subscription. Never includes the signing
+ * secret or the encrypted ciphertext — those are server-only fields.
+ */
+export interface WebhookSubscription {
+    id: string;
+    workspaceId: string;
+    appId?: string | null;
+    name: string;
+    url: string;
+    events: WebhookEvent[];
+    status: WebhookSubscriptionStatus;
+    failedOutAt?: string | null;
+    failedOutReason?: string | null;
+    /**
+     * Optional expiration. When set and in the past, the worker stops
+     * fanning new attempts to this subscription, and any in-flight
+     * attempts DLQ with a clear reason rather than retrying. Null = no
+     * expiry; the subscription delivers indefinitely until manually
+     * paused or deleted.
+     */
+    expiresAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    createdById: string;
+    lastDeliveryAt?: string | null;
+    lastSuccessAt?: string | null;
+    lastFailureAt?: string | null;
+}
+export interface CreateWebhookData {
+    name: string;
+    url: string;
+    events: WebhookEvent[];
+    /** Optional ISO timestamp. Must be in the future when set. */
+    expiresAt?: string | null;
+}
+export interface UpdateWebhookData {
+    name?: string;
+    url?: string;
+    events?: WebhookEvent[];
+    status?: 'active' | 'paused';
+    /** Pass null to clear an existing expiry; pass a future ISO date to set / extend. */
+    expiresAt?: string | null;
+}
+export interface CreateWebhookResponse {
+    subscription: WebhookSubscription;
+    /**
+     * The HMAC signing secret. Returned ONLY here (and from
+     * `rotateWebhookSecret`). The server keeps the ciphertext on the row
+     * and cannot recover the plaintext later — the customer must capture
+     * it now or rotate.
+     */
+    signingSecret: string;
+}
+export interface RotateWebhookSecretResponse extends CreateWebhookResponse {
+}
+export type WebhookAttemptStatus = 'pending' | 'inflight' | 'succeeded' | 'failed' | 'dlq';
+export interface WebhookAttempt {
+    id: string;
+    notificationId: string;
+    subscriptionId: string;
+    attempt: number;
+    maxAttempts: number;
+    status: WebhookAttemptStatus;
+    signatureV1: string;
+    scheduledAt: string;
+    startedAt?: string | null;
+    deliveredAt?: string | null;
+    nextRetryAt?: string | null;
+    responseCode?: number | null;
+    responseBody?: string | null;
+    responseHeaders?: Record<string, any> | null;
+    errorMessage?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ListDeliveriesParams {
+    limit?: number;
+    cursor?: string;
+    status?: WebhookAttemptStatus;
+}
+export interface ListDeliveriesResponse {
+    items: WebhookAttempt[];
+    nextCursor: string | null;
+}
+export interface TestWebhookResponse {
+    queued: true;
+    message: string;
+}
+/**
+ * Outbound webhook subscription management. Admin-gated server-side
+ * by `canManageWebhooks`. All operations are workspace-scoped — there
+ * is no app-owned surface here yet (Phase 3 / OAuth).
+ */
+export default function createWebhookMethods(client: NuramaClient): {
+    /**
+     * Create a webhook subscription. The signing secret is in the
+     * response's `secret` field — store it immediately, it cannot be
+     * retrieved again.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    createWebhook(workspaceId: string, data: CreateWebhookData): Promise<CreateWebhookResponse>;
+    /**
+     * List webhook subscriptions in a workspace. Secrets are never returned.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    listWebhooks(workspaceId: string): Promise<WebhookSubscription[]>;
+    /**
+     * Fetch a single webhook subscription by id.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    getWebhook(workspaceId: string, webhookId: string): Promise<WebhookSubscription>;
+    /**
+     * Update a webhook subscription's url, event filter, or active state.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    updateWebhook(workspaceId: string, webhookId: string, data: UpdateWebhookData): Promise<WebhookSubscription>;
+    /**
+     * Delete a webhook subscription. In-flight deliveries continue to
+     * the receiver until they exhaust retries; no new deliveries fire.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    deleteWebhook(workspaceId: string, webhookId: string): Promise<void>;
+    /**
+     * Generate a new HMAC signing secret for a subscription and return
+     * it once. The old secret is invalidated immediately.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    rotateWebhookSecret(workspaceId: string, webhookId: string): Promise<RotateWebhookSecretResponse>;
+    /**
+     * Fire a synthetic `webhook.test` delivery to the subscription's
+     * URL. The receiver gets a small payload they can use to verify
+     * their HMAC + parsing setup. Returns immediately; check the
+     * delivery log for the outcome.
+     */
+    testWebhook(workspaceId: string, webhookId: string): Promise<TestWebhookResponse>;
+    /**
+     * Paginated list of delivery attempts for a webhook subscription.
+     * Useful for diagnosing failures (HTTP status, response body snippet,
+     * retry timing).
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    listWebhookDeliveries(workspaceId: string, webhookId: string, params?: ListDeliveriesParams): Promise<ListDeliveriesResponse>;
+    /**
+     * Re-fire a specific past delivery attempt. Useful for confirming a
+     * receiver fix without waiting for the next real event.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    replayWebhookDelivery(workspaceId: string, webhookId: string, attemptId: string): Promise<{
+        attempt: WebhookAttempt;
+    }>;
+};
+//# sourceMappingURL=webhook.d.ts.map

package/dist/routes/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/routes/webhook.ts"],"names":[],"mappings":"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"}