@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/webhooks.d.ts

@@ -0,0 +1,251 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.webhooks` (Webhooks): 8 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_webhook_webhooks_post">;
+ *
+ * Reference with examples: webhooks.md
+ */
+/* eslint-disable */
+
+/** `g8.api.webhooks.<member>` -> the operationId it calls. */
+export interface WebhooksMembers {
+  createWebhook: "create_webhook_webhooks_post";
+  deleteWebhook: "delete_webhook_webhooks__webhook_id__delete";
+  getWebhook: "get_webhook_webhooks__webhook_id__get";
+  listWebhookDeliveries: "list_webhook_deliveries_webhooks__webhook_id__deliveries_get";
+  listWebhookEvents: "list_webhook_events_webhooks_events_get";
+  listWebhooks: "list_webhooks_webhooks_get";
+  rotateWebhookSecret: "rotate_webhook_secret_webhooks__webhook_id__rotate_secret_post";
+  updateWebhook: "update_webhook_webhooks__webhook_id__patch";
+}
+
+/** Input and output of every `g8.api.webhooks` operation, keyed by operationId. */
+export interface WebhooksOperations {
+  /**
+   * POST /webhooks
+   * Create Webhook
+   * tier: external · scope: webhooks:run
+   */
+  create_webhook_webhooks_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: WebhookCreateRequest;
+  };
+    output: ApiResponse_WebhookResponse_;
+  };
+  /**
+   * DELETE /webhooks/{webhook_id}
+   * Delete Webhook
+   * tier: destructive · scope: webhooks:delete
+   */
+  delete_webhook_webhooks__webhook_id__delete: {
+    input: {
+    path: {
+      /** Webhook subscription ID */
+      webhook_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: void;
+  };
+  /**
+   * GET /webhooks/{webhook_id}
+   * Get Webhook
+   * tier: read · scope: webhooks:read
+   */
+  get_webhook_webhooks__webhook_id__get: {
+    input: {
+    path: {
+      /** Webhook subscription ID */
+      webhook_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebhookResponse_;
+  };
+  /**
+   * GET /webhooks/{webhook_id}/deliveries
+   * List Webhook Deliveries
+   * tier: read · scope: webhooks:read
+   */
+  list_webhook_deliveries_webhooks__webhook_id__deliveries_get: {
+    input: {
+    path: {
+      /** Webhook subscription ID */
+      webhook_id: string;
+    };
+    query?: {
+      /** Page number */
+      page?: number;
+      /** Items per page */
+      limit?: number;
+      /** Filter by delivery status */
+      status?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_WebhookDeliveryResponse__;
+  };
+  /**
+   * GET /webhooks/events
+   * List Webhook Events
+   * tier: read · scope: webhooks:read
+   */
+  list_webhook_events_webhooks_events_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_WebhookEventResponse__;
+  };
+  /**
+   * GET /webhooks
+   * List Webhooks
+   * tier: read · scope: webhooks:read
+   */
+  list_webhooks_webhooks_get: {
+    input: {
+    query?: {
+      /** Filter by active status */
+      is_active?: boolean | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_WebhookResponse__;
+  };
+  /**
+   * POST /webhooks/{webhook_id}/rotate-secret
+   * Rotate Webhook Secret
+   * tier: external · scope: webhooks:run
+   */
+  rotate_webhook_secret_webhooks__webhook_id__rotate_secret_post: {
+    input: {
+    path: {
+      /** Webhook subscription ID */
+      webhook_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebhookResponse_;
+  };
+  /**
+   * PATCH /webhooks/{webhook_id}
+   * Update Webhook
+   * tier: external · scope: webhooks:run
+   */
+  update_webhook_webhooks__webhook_id__patch: {
+    input: {
+    path: {
+      /** Webhook subscription ID */
+      webhook_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: WebhookUpdateRequest;
+  };
+    output: ApiResponse_WebhookResponse_;
+  };
+}
+
+// 10 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_WebhookResponse_ {
+  data: WebhookResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_WebhookDeliveryResponse__ {
+  data: Array<WebhookDeliveryResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_WebhookEventResponse__ {
+  data: Array<WebhookEventResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_WebhookResponse__ {
+  data: Array<WebhookResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+export interface WebhookCreateRequest {
+  /** Event types to subscribe to */
+  events: Array<string>;
+  /** Human-readable name */
+  name?: string | null;
+  /** Target URL for webhook delivery */
+  url: string;
+}
+
+export interface WebhookDeliveryResponse {
+  attempts?: number;
+  completed_at?: string | null;
+  created_at?: string | null;
+  error_message?: string | null;
+  event: string;
+  id: string;
+  max_attempts?: number;
+  response_code?: number | null;
+  status: string;
+}
+
+export interface WebhookEventResponse {
+  category?: string | null;
+  description?: string | null;
+  event: string;
+}
+
+export interface WebhookResponse {
+  created_at?: string | null;
+  events?: Array<string>;
+  id: string;
+  is_active?: boolean;
+  name?: string | null;
+  /** Only returned on create and rotate-secret */
+  secret?: string | null;
+  updated_at?: string | null;
+  url: string;
+}
+
+export interface WebhookUpdateRequest {
+  /** Event types to subscribe to */
+  events?: Array<string> | null;
+  /** Whether the webhook is active */
+  is_active?: boolean | null;
+  /** Human-readable name */
+  name?: string | null;
+  /** Target URL for webhook delivery */
+  url?: string | null;
+}

package/docs/api/webhooks.md

@@ -0,0 +1,386 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.webhooks`: Webhooks
+
+8 operations (4 read, 1 destructive, 3 external).
+
+No hand-written client covers this area. Call it through `g8.api.webhooks.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [webhooks.d.ts](webhooks.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createWebhook`](#op-createwebhook) | `POST /api/v1/webhooks` | external | `webhooks:run` | Create Webhook |
+| [`deleteWebhook`](#op-deletewebhook) | `DELETE /api/v1/webhooks/{webhook_id}` | destructive | `webhooks:delete` | Delete Webhook |
+| [`getWebhook`](#op-getwebhook) | `GET /api/v1/webhooks/{webhook_id}` | read | `webhooks:read` | Get Webhook |
+| [`listWebhookDeliveries`](#op-listwebhookdeliveries) | `GET /api/v1/webhooks/{webhook_id}/deliveries` | read | `webhooks:read` | List Webhook Deliveries |
+| [`listWebhookEvents`](#op-listwebhookevents) | `GET /api/v1/webhooks/events` | read | `webhooks:read` | List Webhook Events |
+| [`listWebhooks`](#op-listwebhooks) | `GET /api/v1/webhooks` | read | `webhooks:read` | List Webhooks |
+| [`rotateWebhookSecret`](#op-rotatewebhooksecret) | `POST /api/v1/webhooks/{webhook_id}/rotate-secret` | external | `webhooks:run` | Rotate Webhook Secret |
+| [`updateWebhook`](#op-updatewebhook) | `PATCH /api/v1/webhooks/{webhook_id}` | external | `webhooks:run` | Update Webhook |
+
+---
+
+<a id="op-createwebhook"></a>
+
+### `g8.api.webhooks.createWebhook(input)`
+
+**Create Webhook**
+
+- HTTP: `POST /api/v1/webhooks`
+- operationId: `create_webhook_webhooks_post` (also callable as `g8.api.call("create_webhook_webhooks_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `webhooks:run`
+
+Create a new webhook subscription. Returns the secret (only shown once).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `WebhookCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`WebhookCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.events` | `Array<string>` | yes | Event types to subscribe to |
+| `body.url` | `string` | yes | Target URL for webhook delivery |
+| `body.name` | `string \| null` | no | Human-readable name |
+
+**Returns** `ApiResponse_WebhookResponse_`: the envelope `{ data: WebhookResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebhookResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `url` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `events` | `Array<string>` | no | default `[]` |
+| `is_active` | `boolean` | no | default `true` |
+| `name` | `string \| null` | no |  |
+| `secret` | `string \| null` | no | Only returned on create and rotate-secret |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.webhooks.createWebhook({ body: { events: ["example"], url: "https://example.com" } });
+```
+
+---
+
+<a id="op-deletewebhook"></a>
+
+### `g8.api.webhooks.deleteWebhook(input)`
+
+**Delete Webhook**
+
+- HTTP: `DELETE /api/v1/webhooks/{webhook_id}`
+- operationId: `delete_webhook_webhooks__webhook_id__delete` (also callable as `g8.api.call("delete_webhook_webhooks__webhook_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `webhooks:delete`
+
+Delete a webhook subscription.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.webhook_id` | `string` | yes | Webhook subscription ID |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webhooks.deleteWebhook({ path: { webhook_id: "https://example.com" } });
+```
+
+---
+
+<a id="op-getwebhook"></a>
+
+### `g8.api.webhooks.getWebhook(input)`
+
+**Get Webhook**
+
+- HTTP: `GET /api/v1/webhooks/{webhook_id}`
+- operationId: `get_webhook_webhooks__webhook_id__get` (also callable as `g8.api.call("get_webhook_webhooks__webhook_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `webhooks:read`
+
+Get webhook subscription details (secret is not returned).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.webhook_id` | `string` | yes | Webhook subscription ID |
+
+**Returns** `ApiResponse_WebhookResponse_`: the envelope `{ data: WebhookResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebhookResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `url` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `events` | `Array<string>` | no | default `[]` |
+| `is_active` | `boolean` | no | default `true` |
+| `name` | `string \| null` | no |  |
+| `secret` | `string \| null` | no | Only returned on create and rotate-secret |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webhooks.getWebhook({ path: { webhook_id: "https://example.com" } });
+```
+
+---
+
+<a id="op-listwebhookdeliveries"></a>
+
+### `g8.api.webhooks.listWebhookDeliveries(input)`
+
+**List Webhook Deliveries**
+
+- HTTP: `GET /api/v1/webhooks/{webhook_id}/deliveries`
+- operationId: `list_webhook_deliveries_webhooks__webhook_id__deliveries_get` (also callable as `g8.api.call("list_webhook_deliveries_webhooks__webhook_id__deliveries_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `webhooks:read`
+
+List delivery attempts for a webhook subscription.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.webhook_id` | `string` | yes | Webhook subscription ID |
+| `query.page` | `integer` | no | Page number default `1` |
+| `query.limit` | `integer` | no | Items per page default `50` |
+| `query.status` | `string \| null` | no | Filter by delivery status |
+
+**Returns** `ApiResponse_list_WebhookDeliveryResponse__`: the envelope `{ data: Array<WebhookDeliveryResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebhookDeliveryResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `event` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `attempts` | `integer` | no | default `0` |
+| `completed_at` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `error_message` | `string \| null` | no |  |
+| `max_attempts` | `integer` | no | default `3` |
+| `response_code` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webhooks.listWebhookDeliveries({ path: { webhook_id: "https://example.com" } });
+```
+
+---
+
+<a id="op-listwebhookevents"></a>
+
+### `g8.api.webhooks.listWebhookEvents(input?)`
+
+**List Webhook Events**
+
+- HTTP: `GET /api/v1/webhooks/events`
+- operationId: `list_webhook_events_webhooks_events_get` (also callable as `g8.api.call("list_webhook_events_webhooks_events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `webhooks:read`
+
+List all available webhook event types, each with a category + description.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_WebhookEventResponse__`: the envelope `{ data: Array<WebhookEventResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebhookEventResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `event` | `string` | yes |  |
+| `category` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webhooks.listWebhookEvents();
+```
+
+---
+
+<a id="op-listwebhooks"></a>
+
+### `g8.api.webhooks.listWebhooks(input?)`
+
+**List Webhooks**
+
+- HTTP: `GET /api/v1/webhooks`
+- operationId: `list_webhooks_webhooks_get` (also callable as `g8.api.call("list_webhooks_webhooks_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `webhooks:read`
+
+List all webhook subscriptions for the organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.is_active` | `boolean \| null` | no | Filter by active status |
+
+**Returns** `ApiResponse_list_WebhookResponse__`: the envelope `{ data: Array<WebhookResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebhookResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `url` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `events` | `Array<string>` | no | default `[]` |
+| `is_active` | `boolean` | no | default `true` |
+| `name` | `string \| null` | no |  |
+| `secret` | `string \| null` | no | Only returned on create and rotate-secret |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webhooks.listWebhooks();
+```
+
+---
+
+<a id="op-rotatewebhooksecret"></a>
+
+### `g8.api.webhooks.rotateWebhookSecret(input)`
+
+**Rotate Webhook Secret**
+
+- HTTP: `POST /api/v1/webhooks/{webhook_id}/rotate-secret`
+- operationId: `rotate_webhook_secret_webhooks__webhook_id__rotate_secret_post` (also callable as `g8.api.call("rotate_webhook_secret_webhooks__webhook_id__rotate_secret_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `webhooks:run`
+
+Rotate the signing secret for a webhook subscription. Returns the new secret (shown once).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.webhook_id` | `string` | yes | Webhook subscription ID |
+
+**Returns** `ApiResponse_WebhookResponse_`: the envelope `{ data: WebhookResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebhookResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `url` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `events` | `Array<string>` | no | default `[]` |
+| `is_active` | `boolean` | no | default `true` |
+| `name` | `string \| null` | no |  |
+| `secret` | `string \| null` | no | Only returned on create and rotate-secret |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.webhooks.rotateWebhookSecret({ path: { webhook_id: "https://example.com" } });
+```
+
+---
+
+<a id="op-updatewebhook"></a>
+
+### `g8.api.webhooks.updateWebhook(input)`
+
+**Update Webhook**
+
+- HTTP: `PATCH /api/v1/webhooks/{webhook_id}`
+- operationId: `update_webhook_webhooks__webhook_id__patch` (also callable as `g8.api.call("update_webhook_webhooks__webhook_id__patch", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `webhooks:run`
+
+Update a webhook subscription.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.webhook_id` | `string` | yes | Webhook subscription ID |
+| `body` | `WebhookUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`WebhookUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.events` | `Array<string> \| null` | no | Event types to subscribe to |
+| `body.is_active` | `boolean \| null` | no | Whether the webhook is active |
+| `body.name` | `string \| null` | no | Human-readable name |
+| `body.url` | `string \| null` | no | Target URL for webhook delivery |
+
+**Returns** `ApiResponse_WebhookResponse_`: the envelope `{ data: WebhookResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebhookResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `url` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `events` | `Array<string>` | no | default `[]` |
+| `is_active` | `boolean` | no | default `true` |
+| `name` | `string \| null` | no |  |
+| `secret` | `string \| null` | no | Only returned on create and rotate-secret |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.webhooks.updateWebhook({ path: { webhook_id: "https://example.com" }, body: {} });
+```