featurebase-node 0.0.2

package/src/resources/webhooks.ts

@@ -0,0 +1,850 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Webhooks allow you to receive real-time HTTP callbacks when events occur in your Featurebase organization. Configure webhook endpoints to subscribe to specific event types.
+ */
+export class Webhooks extends APIResource {
+  /**
+   * Creates a new webhook to receive event notifications.
+   *
+   * ### Request Body
+   *
+   * | Field                   | Type     | Required | Description                          |
+   * | ----------------------- | -------- | -------- | ------------------------------------ |
+   * | `name`                  | string   | Yes      | Human-readable name (max 100 chars)  |
+   * | `url`                   | string   | Yes      | Webhook endpoint URL (must be HTTPS) |
+   * | `description`           | string   | No       | Optional description (max 500 chars) |
+   * | `topics`                | string[] | Yes      | Event topics to subscribe to         |
+   * | `requestConfig`         | object   | No       | Request configuration                |
+   * | `requestConfig.headers` | object   | No       | Custom headers to send (max 10)      |
+   *
+   * ### Available Topics
+   *
+   * - `post.created` - When a new feedback post is created
+   * - `post.updated` - When a feedback post is updated
+   * - `post.deleted` - When a feedback post is deleted
+   * - `post.voted` - When a feedback post receives a vote
+   * - `ticket.created` - When a new ticket is created
+   * - `ticket.updated` - When a ticket is updated
+   * - `ticket.deleted` - When a ticket is deleted
+   * - `changelog.published` - When a changelog is published
+   * - `comment.created` - When a comment is created
+   * - `comment.updated` - When a comment is updated
+   * - `comment.deleted` - When a comment is deleted
+   *
+   * ### Response
+   *
+   * Returns the created webhook object including the signing secret.
+   *
+   * ### Example Request
+   *
+   * ```json
+   * {
+   *   "name": "Production Webhook",
+   *   "url": "https://example.com/webhooks",
+   *   "description": "Handles all production events",
+   *   "topics": ["post.created", "post.updated", "comment.created"],
+   *   "requestConfig": {
+   *     "timeoutMs": 10000,
+   *     "headers": {
+   *       "X-Custom-Header": "value"
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "webhook",
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "name": "Production Webhook",
+   *   "url": "https://example.com/webhooks",
+   *   "secret": "whsec_abc123def456ghi789",
+   *   "topics": ["post.created", "post.updated", "comment.created"],
+   *   "status": "active",
+   *   ...
+   * }
+   * ```
+   *
+   * ### Limits
+   *
+   * Each organization has a maximum number of webhooks (default: 10). Creating a
+   * webhook when the limit is reached will return a 400 error.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const webhook = await client.webhooks.create({
+   *   name: 'Production Webhook',
+   *   topics: ['post.created', 'post.updated'],
+   *   url: 'https://example.com/webhooks',
+   * });
+   * ```
+   */
+  create(params: WebhookCreateParams, options?: RequestOptions): APIPromise<Webhook> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/webhooks', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Retrieves a single webhook by its unique identifier.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The webhook ID (24-character ObjectId)
+   *
+   * ### Response Format
+   *
+   * Returns a webhook object with:
+   *
+   * - `object` - Always "webhook"
+   * - `id` - Unique webhook identifier
+   * - `name` - Human-readable webhook name
+   * - `url` - Webhook endpoint URL
+   * - `description` - Optional description
+   * - `topics` - Array of subscribed event topics
+   * - `status` - Current status ("active", "paused", "suspended")
+   * - `requestConfig` - Request configuration (timeout, headers)
+   * - `lastStatus` - Last delivery attempt status
+   * - `health` - Health metrics
+   * - `createdAt` - Creation timestamp
+   * - `updatedAt` - Last update timestamp
+   *
+   * The response includes the webhook signing secret for payload verification.
+   *
+   * ### Example
+   *
+   * ```json
+   * {
+   *   "object": "webhook",
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "name": "Production Webhook",
+   *   "url": "https://example.com/webhooks",
+   *   "description": "Handles all production events",
+   *   "topics": ["post.created", "post.updated"],
+   *   "status": "active",
+   *   "requestConfig": {
+   *     "timeoutMs": 5000,
+   *     "headers": {}
+   *   },
+   *   "lastStatus": {
+   *     "code": 200,
+   *     "message": "Success",
+   *     "timestamp": "2025-01-15T10:30:00.000Z"
+   *   },
+   *   "health": {
+   *     "lastResponseTime": 150,
+   *     "avgResponseTime": 200,
+   *     "lastSuccessAt": "2025-01-15T10:30:00.000Z",
+   *     "errorsSinceLastSuccess": 0,
+   *     "consecutiveFailures": 0
+   *   },
+   *   "createdAt": "2025-01-01T00:00:00.000Z",
+   *   "updatedAt": "2025-01-15T10:30:00.000Z"
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const webhook = await client.webhooks.retrieve(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  retrieve(
+    id: string,
+    params: WebhookRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Webhook> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/webhooks/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Updates a webhook's properties. Supports partial updates - only provided fields
+   * will be updated.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The webhook ID (24-character ObjectId)
+   *
+   * ### Request Body
+   *
+   * All fields are optional. Only provided fields will be updated.
+   *
+   * | Field                   | Type        | Description                                        |
+   * | ----------------------- | ----------- | -------------------------------------------------- |
+   * | `name`                  | string      | Human-readable name (max 100 chars)                |
+   * | `url`                   | string      | Webhook endpoint URL (must be HTTPS)               |
+   * | `description`           | string/null | Description (null to clear)                        |
+   * | `topics`                | string[]    | Event topics to subscribe to                       |
+   * | `status`                | string      | "active" to reactivate, "paused" to pause delivery |
+   * | `requestConfig`         | object      | Request configuration                              |
+   * | `requestConfig.headers` | object      | Custom headers to send (max 10)                    |
+   *
+   * ### Pausing and Reactivating Webhooks
+   *
+   * You can pause a webhook to temporarily stop receiving events:
+   *
+   * ```json
+   * {
+   *   "status": "paused"
+   * }
+   * ```
+   *
+   * Webhooks may also be automatically paused or suspended due to delivery failures.
+   * To reactivate:
+   *
+   * ```json
+   * {
+   *   "status": "active"
+   * }
+   * ```
+   *
+   * Reactivating a webhook resets the health metrics and allows it to receive events
+   * again.
+   *
+   * ### Example: Update Topics
+   *
+   * ```json
+   * {
+   *   "topics": ["post.created", "post.updated", "post.deleted"]
+   * }
+   * ```
+   *
+   * ### Example: Update Request Config
+   *
+   * ```json
+   * {
+   *   "requestConfig": {
+   *     "headers": {
+   *       "X-Custom-Header": "new-value"
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const webhook = await client.webhooks.update(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  update(id: string, params: WebhookUpdateParams, options?: RequestOptions): APIPromise<Webhook> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.patch(path`/v2/webhooks/${id}`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns a list of webhooks in your organization using cursor-based pagination.
+   *
+   * ### Query Parameters
+   *
+   * - `limit` - Number of webhooks to return (1-100, default 10)
+   * - `cursor` - Cursor from previous response for pagination
+   * - `status` - Filter by status: "active", "paused", or "suspended"
+   *
+   * ### Response Format
+   *
+   * Returns a list object with:
+   *
+   * - `object` - Always "list"
+   * - `data` - Array of webhook objects
+   * - `nextCursor` - Cursor for the next page, or null if no more results
+   *
+   * ### Webhook Object
+   *
+   * Each webhook includes:
+   *
+   * - `id` - Unique webhook identifier
+   * - `name` - Human-readable webhook name
+   * - `url` - Webhook endpoint URL
+   * - `topics` - Array of subscribed event topics
+   * - `status` - Current status ("active", "paused", "suspended")
+   * - `health` - Health metrics (response times, error counts)
+   * - `createdAt` - Creation timestamp
+   * - `updatedAt` - Last update timestamp
+   *
+   * ### Example
+   *
+   * ```json
+   * {
+   *   "object": "list",
+   *   "data": [
+   *     {
+   *       "object": "webhook",
+   *       "id": "507f1f77bcf86cd799439011",
+   *       "name": "Production Webhook",
+   *       "url": "https://example.com/webhooks",
+   *       "topics": ["post.created", "post.updated"],
+   *       "status": "active",
+   *       ...
+   *     }
+   *   ],
+   *   "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const webhooks = await client.webhooks.list();
+   * ```
+   */
+  list(
+    params: WebhookListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WebhookListResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.get('/v2/webhooks', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Permanently deletes a webhook.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The webhook ID (24-character ObjectId)
+   *
+   * ### Response
+   *
+   * Returns a deletion confirmation object:
+   *
+   * ```json
+   * {
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "object": "webhook",
+   *   "deleted": true
+   * }
+   * ```
+   *
+   * ### Caution
+   *
+   * This operation is **irreversible**. The webhook and its configuration will be
+   * permanently deleted. After deletion, no events will be sent to the webhook
+   * endpoint.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const webhook = await client.webhooks.delete(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  delete(
+    id: string,
+    params: WebhookDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WebhookDeleteResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.delete(path`/v2/webhooks/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Generates a new signing secret for a webhook. The previous secret is immediately
+   * invalidated.
+   *
+   * ### Path Parameters
+   *
+   * - `id` - The webhook ID (24-character ObjectId)
+   *
+   * ### Response
+   *
+   * Returns the updated webhook object, including the new signing secret.
+   *
+   * ### Important
+   *
+   * After refreshing the secret, any integrations that verify webhook signatures
+   * using the old secret will stop working until they are updated with the new
+   * secret.
+   *
+   * ### Example Response
+   *
+   * ```json
+   * {
+   *   "object": "webhook",
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "name": "Production Webhook",
+   *   "url": "https://example.com/webhooks",
+   *   "secret": "whsec_newSecret123abc456def",
+   *   "topics": ["post.created", "post.updated"],
+   *   "status": "active",
+   *   ...
+   * }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const webhook = await client.webhooks.refreshSecret(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  refreshSecret(
+    id: string,
+    params: WebhookRefreshSecretParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Webhook> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.post(path`/v2/webhooks/${id}/secret`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface Webhook {
+  /**
+   * Unique identifier
+   */
+  id: string;
+
+  /**
+   * ISO timestamp when the webhook was created
+   */
+  createdAt: string;
+
+  /**
+   * Optional description of the webhook purpose
+   */
+  description: string | null;
+
+  health: Webhook.Health;
+
+  /**
+   * Last delivery attempt status
+   */
+  lastStatus: Webhook.LastStatus | null;
+
+  /**
+   * Human-readable webhook name
+   */
+  name: string;
+
+  /**
+   * Object type identifier
+   */
+  object: 'webhook';
+
+  requestConfig: Webhook.RequestConfig;
+
+  /**
+   * Webhook signing secret for verifying payloads
+   */
+  secret: string;
+
+  /**
+   * Current status of the webhook
+   */
+  status: 'active' | 'paused' | 'suspended';
+
+  /**
+   * Array of event topics the webhook subscribes to
+   */
+  topics: Array<
+    | 'post.created'
+    | 'post.updated'
+    | 'post.deleted'
+    | 'post.voted'
+    | 'ticket.created'
+    | 'ticket.updated'
+    | 'ticket.deleted'
+    | 'changelog.published'
+    | 'comment.created'
+    | 'comment.updated'
+    | 'comment.deleted'
+    | 'conversation.user.created'
+    | 'conversation.user.replied'
+    | 'conversation.admin.replied'
+    | 'conversation.admin.closed'
+    | 'conversation.handover_requested'
+    | 'conversation.admin.assigned'
+    | 'conversation.admin.noted'
+    | 'conversation.admin.snoozed'
+    | 'conversation.admin.unsnoozed'
+    | 'conversation.admin.opened'
+    | 'conversation.priority.updated'
+    | 'conversation.deleted'
+    | 'conversation.contact.attached'
+    | 'conversation.contact.detached'
+    | 'conversation.read'
+    | 'conversation_part.redacted'
+  >;
+
+  /**
+   * ISO timestamp when the webhook was last updated
+   */
+  updatedAt: string;
+
+  /**
+   * Webhook endpoint URL
+   */
+  url: string;
+
+  /**
+   * API version for webhook payloads
+   */
+  version: string;
+}
+
+export namespace Webhook {
+  export interface Health {
+    /**
+     * Average response time in milliseconds
+     */
+    avgResponseTime: number;
+
+    /**
+     * Number of consecutive delivery failures
+     */
+    consecutiveFailures: number;
+
+    /**
+     * Number of errors since last successful delivery
+     */
+    errorsSinceLastSuccess: number;
+
+    /**
+     * Last response time in milliseconds
+     */
+    lastResponseTime: number;
+
+    /**
+     * ISO timestamp of last successful delivery
+     */
+    lastSuccessAt: string | null;
+  }
+
+  /**
+   * Last delivery attempt status
+   */
+  export interface LastStatus {
+    /**
+     * HTTP status code from last delivery attempt
+     */
+    code: number;
+
+    /**
+     * Status message from last delivery attempt
+     */
+    message: string;
+
+    /**
+     * ISO timestamp of last status update
+     */
+    timestamp: string;
+  }
+
+  export interface RequestConfig {
+    /**
+     * Request timeout in milliseconds (1000-30000)
+     */
+    timeoutMs: number;
+
+    /**
+     * Custom headers to send with webhook requests
+     */
+    headers?: { [key: string]: string };
+  }
+}
+
+/**
+ * Request configuration for webhook delivery
+ */
+export interface WebhookRequestConfigInput {
+  /**
+   * Custom headers to send with webhook requests (max 10)
+   */
+  headers?: { [key: string]: string };
+}
+
+export interface WebhookListResponse {
+  /**
+   * Array of webhooks
+   */
+  data: Array<Webhook>;
+
+  /**
+   * Cursor for fetching the next page (cursor-based pagination)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+}
+
+export interface WebhookDeleteResponse {
+  /**
+   * Unique identifier of the deleted webhook
+   */
+  id: string;
+
+  /**
+   * Indicates the resource was deleted
+   */
+  deleted: true;
+
+  /**
+   * Object type identifier
+   */
+  object: 'webhook';
+}
+
+export interface WebhookCreateParams {
+  /**
+   * Body param: Human-readable name for the webhook
+   */
+  name: string;
+
+  /**
+   * Body param: Array of event topics to subscribe to
+   */
+  topics: Array<
+    | 'post.created'
+    | 'post.updated'
+    | 'post.deleted'
+    | 'post.voted'
+    | 'ticket.created'
+    | 'ticket.updated'
+    | 'ticket.deleted'
+    | 'changelog.published'
+    | 'comment.created'
+    | 'comment.updated'
+    | 'comment.deleted'
+    | 'conversation.user.created'
+    | 'conversation.user.replied'
+    | 'conversation.admin.replied'
+    | 'conversation.admin.closed'
+    | 'conversation.handover_requested'
+    | 'conversation.admin.assigned'
+    | 'conversation.admin.noted'
+    | 'conversation.admin.snoozed'
+    | 'conversation.admin.unsnoozed'
+    | 'conversation.admin.opened'
+    | 'conversation.priority.updated'
+    | 'conversation.deleted'
+    | 'conversation.contact.attached'
+    | 'conversation.contact.detached'
+    | 'conversation.read'
+    | 'conversation_part.redacted'
+  >;
+
+  /**
+   * Body param: Webhook endpoint URL (must be HTTPS)
+   */
+  url: string;
+
+  /**
+   * Body param: Optional description of the webhook purpose
+   */
+  description?: string;
+
+  /**
+   * Body param: Request configuration for webhook delivery
+   */
+  requestConfig?: WebhookRequestConfigInput;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface WebhookRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface WebhookUpdateParams {
+  /**
+   * Body param: Optional description of the webhook purpose (null to clear)
+   */
+  description?: string | null;
+
+  /**
+   * Body param: Human-readable name for the webhook
+   */
+  name?: string;
+
+  /**
+   * Body param: Request configuration for webhook delivery
+   */
+  requestConfig?: WebhookRequestConfigInput;
+
+  /**
+   * Body param: Set to "active" to reactivate or "paused" to pause webhook delivery
+   */
+  status?: 'active' | 'paused';
+
+  /**
+   * Body param: Array of event topics to subscribe to
+   */
+  topics?: Array<
+    | 'post.created'
+    | 'post.updated'
+    | 'post.deleted'
+    | 'post.voted'
+    | 'ticket.created'
+    | 'ticket.updated'
+    | 'ticket.deleted'
+    | 'changelog.published'
+    | 'comment.created'
+    | 'comment.updated'
+    | 'comment.deleted'
+    | 'conversation.user.created'
+    | 'conversation.user.replied'
+    | 'conversation.admin.replied'
+    | 'conversation.admin.closed'
+    | 'conversation.handover_requested'
+    | 'conversation.admin.assigned'
+    | 'conversation.admin.noted'
+    | 'conversation.admin.snoozed'
+    | 'conversation.admin.unsnoozed'
+    | 'conversation.admin.opened'
+    | 'conversation.priority.updated'
+    | 'conversation.deleted'
+    | 'conversation.contact.attached'
+    | 'conversation.contact.detached'
+    | 'conversation.read'
+    | 'conversation_part.redacted'
+  >;
+
+  /**
+   * Body param: Webhook endpoint URL (must be HTTPS)
+   */
+  url?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface WebhookListParams {
+  /**
+   * Query param: An opaque cursor for pagination. Use the nextCursor value from a
+   * previous response to fetch the next page of results.
+   */
+  cursor?: string;
+
+  /**
+   * Query param: A limit on the number of objects to be returned, between 1 and 100.
+   */
+  limit?: number;
+
+  /**
+   * Query param: Filter webhooks by status
+   */
+  status?: 'active' | 'paused' | 'suspended';
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface WebhookDeleteParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface WebhookRefreshSecretParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export declare namespace Webhooks {
+  export {
+    type Webhook as Webhook,
+    type WebhookRequestConfigInput as WebhookRequestConfigInput,
+    type WebhookListResponse as WebhookListResponse,
+    type WebhookDeleteResponse as WebhookDeleteResponse,
+    type WebhookCreateParams as WebhookCreateParams,
+    type WebhookRetrieveParams as WebhookRetrieveParams,
+    type WebhookUpdateParams as WebhookUpdateParams,
+    type WebhookListParams as WebhookListParams,
+    type WebhookDeleteParams as WebhookDeleteParams,
+    type WebhookRefreshSecretParams as WebhookRefreshSecretParams,
+  };
+}