@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/channels.d.ts

@@ -0,0 +1,171 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.channels` (Channels): 5 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_channel_preferences_channels_preferences_get">;
+ *
+ * Reference with examples: channels.md
+ */
+/* eslint-disable */
+
+/** `g8.api.channels.<member>` -> the operationId it calls. */
+export interface ChannelsMembers {
+  getChannelPreferences: "get_channel_preferences_channels_preferences_get";
+  getSmsPhoneConfig: "get_sms_phone_config_sms_phone_numbers__phone_number__config_get";
+  listSmsPhoneNumbers: "list_sms_phone_numbers_sms_phone_numbers_get";
+  setChannelPreference: "set_channel_preference_channels_preferences_put";
+  updateSmsPhoneConfig: "update_sms_phone_config_sms_phone_numbers__phone_number__put";
+}
+
+/** Input and output of every `g8.api.channels` operation, keyed by operationId. */
+export interface ChannelsOperations {
+  /**
+   * GET /channels/preferences
+   * Get Channel Preferences
+   * tier: read · scope: campaigns:read
+   */
+  get_channel_preferences_channels_preferences_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /sms/phone-numbers/{phone_number}/config
+   * Get Sms Phone Config
+   * tier: read · scope: campaigns:read
+   */
+  get_sms_phone_config_sms_phone_numbers__phone_number__config_get: {
+    input: {
+    path: {
+      /** Phone number in E.164 form, e.g. +15551234567 */
+      phone_number: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * GET /sms/phone-numbers
+   * List Sms Phone Numbers
+   * tier: read · scope: campaigns:read
+   */
+  list_sms_phone_numbers_sms_phone_numbers_get: {
+    input: {
+    query?: {
+      enabled_only?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_MailboxDomainListPayload_;
+  };
+  /**
+   * PUT /channels/preferences
+   * Set Channel Preference
+   * tier: write · scope: campaigns:write
+   */
+  set_channel_preference_channels_preferences_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ChannelPreferenceRequest;
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+  /**
+   * PUT /sms/phone-numbers/{phone_number}
+   * Update Sms Phone Config
+   * tier: external · scope: campaigns:run
+   */
+  update_sms_phone_config_sms_phone_numbers__phone_number__put: {
+    input: {
+    path: {
+      /** Phone number in E.164 form, e.g. +15551234567 */
+      phone_number: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SmsPhoneConfigRequest;
+  };
+    output: ApiResponse_MailboxDomainPayload_;
+  };
+}
+
+// 7 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_MailboxDomainListPayload_ {
+  data: MailboxDomainListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_MailboxDomainPayload_ {
+  data: MailboxDomainPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/** Set ONE org-wide channel preference. */
+export interface ChannelPreferenceRequest {
+  /** Preference key, from GET /channels/preferences */
+  key: string;
+  /** New value. The service rejects a value the key does not accept with a 422. */
+  value: unknown;
+}
+
+/**
+ * An open envelope for a LIST result, so a bare list keeps its shape.
+ *
+ * A named collection (``{"plans": [...]}``) keeps its own key AND gains
+ * ``items``, so a caller can page every list surface the same way without
+ * memorising which key each route chose.
+ */
+export interface MailboxDomainListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An open envelope for one provider/deliverability result.
+ *
+ * Open on purpose. These payloads are provider state and advisory reads whose
+ * contents grow with the product, and a dropped field reads as "nothing to
+ * report" rather than "we did not tell you". Every value passes through
+ * ``scrub_vendor_names`` on the way in.
+ */
+export type MailboxDomainPayload = Record<string, unknown>;
+
+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;
+}
+
+/**
+ * Partial update of one SMS number's AI-inbox settings.
+ *
+ * Omitted fields are left alone; this is a PATCH in PUT's clothing, matching
+ * the app exactly rather than inventing a second spelling.
+ */
+export interface SmsPhoneConfigRequest {
+  /** Show this number's threads in the inbox */
+  ai_inbox_enabled?: boolean | null;
+  /** Let the AI reply on this number */
+  auto_respond?: boolean | null;
+}

package/docs/api/channels.md

@@ -0,0 +1,235 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.channels`: Channels
+
+5 operations (3 read, 1 write, 1 external).
+
+No hand-written client covers this area. Call it through `g8.api.channels.*` 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: [channels.d.ts](channels.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getChannelPreferences`](#op-getchannelpreferences) | `GET /api/v1/channels/preferences` | read | `campaigns:read` | Get Channel Preferences |
+| [`getSmsPhoneConfig`](#op-getsmsphoneconfig) | `GET /api/v1/sms/phone-numbers/{phone_number}/config` | read | `campaigns:read` | Get Sms Phone Config |
+| [`listSmsPhoneNumbers`](#op-listsmsphonenumbers) | `GET /api/v1/sms/phone-numbers` | read | `campaigns:read` | List Sms Phone Numbers |
+| [`setChannelPreference`](#op-setchannelpreference) | `PUT /api/v1/channels/preferences` | write | `campaigns:write` | Set Channel Preference |
+| [`updateSmsPhoneConfig`](#op-updatesmsphoneconfig) | `PUT /api/v1/sms/phone-numbers/{phone_number}` | external | `campaigns:run` | Update Sms Phone Config |
+
+---
+
+<a id="op-getchannelpreferences"></a>
+
+### `g8.api.channels.getChannelPreferences(input?)`
+
+**Get Channel Preferences**
+
+- HTTP: `GET /api/v1/channels/preferences`
+- operationId: `get_channel_preferences_channels_preferences_get` (also callable as `g8.api.call("get_channel_preferences_channels_preferences_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Every org-wide channel preference, with defaults already applied.
+
+A key that is missing from the org's stored settings still appears here
+carrying its default, so this is the complete list of what
+`PUT /channels/preferences` will accept - there is no separate schema
+endpoint to look one up in.
+
+Needs a personal API key whose user can read channel preferences.
+
+**Input**: none.
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.channels.getChannelPreferences();
+```
+
+---
+
+<a id="op-getsmsphoneconfig"></a>
+
+### `g8.api.channels.getSmsPhoneConfig(input)`
+
+**Get Sms Phone Config**
+
+- HTTP: `GET /api/v1/sms/phone-numbers/{phone_number}/config`
+- operationId: `get_sms_phone_config_sms_phone_numbers__phone_number__config_get` (also callable as `g8.api.call("get_sms_phone_config_sms_phone_numbers__phone_number__config_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One number's stored AI-inbox settings.
+
+404 when the number has never been configured - it is then running on the
+defaults `GET /sms/phone-numbers` shows for it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.phone_number` | `string` | yes | Phone number in E.164 form, e.g. +15551234567 |
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.channels.getSmsPhoneConfig({ path: { phone_number: "+15555550100" } });
+```
+
+---
+
+<a id="op-listsmsphonenumbers"></a>
+
+### `g8.api.channels.listSmsPhoneNumbers(input?)`
+
+**List Sms Phone Numbers**
+
+- HTTP: `GET /api/v1/sms/phone-numbers`
+- operationId: `list_sms_phone_numbers_sms_phone_numbers_get` (also callable as `g8.api.call("list_sms_phone_numbers_sms_phone_numbers_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The org's SMS numbers, each with its AI-inbox settings merged on.
+
+`enabled_only=true` narrows to the numbers whose conversations reach the
+inbox. A number with no stored settings still appears, carrying the
+defaults, so absence from this list means the number is not the org's -
+not that it is unconfigured.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.enabled_only` | `boolean` | no | default `false` |
+
+**Returns** `ApiResponse_MailboxDomainListPayload_`: the envelope `{ data: MailboxDomainListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`MailboxDomainListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.channels.listSmsPhoneNumbers();
+```
+
+---
+
+<a id="op-setchannelpreference"></a>
+
+### `g8.api.channels.setChannelPreference(input)`
+
+**Set Channel Preference**
+
+- HTTP: `PUT /api/v1/channels/preferences`
+- operationId: `set_channel_preference_channels_preferences_put` (also callable as `g8.api.call("set_channel_preference_channels_preferences_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Set ONE preference. Everything else is left alone.
+
+PUT of a single key/value pair rather than the whole object, matching the
+app: sending the full set would make a stale read overwrite a change
+someone else made between your GET and your PUT.
+
+`key` must be one `GET /channels/preferences` returned, and `value` must
+be a shape that key accepts - anything else is a 422 saying which.
+
+These are org-wide compliance switches. Needs a personal API key whose
+user can write channel preferences; org admins and owners always can.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ChannelPreferenceRequest` | yes | Request body; fields below. |
+
+Body fields (`ChannelPreferenceRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.key` | `string` | yes | Preference key, from GET /channels/preferences |
+| `body.value` | `unknown` | yes | New value. The service rejects a value the key does not accept with a 422. |
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.channels.setChannelPreference({ body: { key: "example", value: {} } });
+```
+
+---
+
+<a id="op-updatesmsphoneconfig"></a>
+
+### `g8.api.channels.updateSmsPhoneConfig(input)`
+
+**Update Sms Phone Config**
+
+- HTTP: `PUT /api/v1/sms/phone-numbers/{phone_number}`
+- operationId: `update_sms_phone_config_sms_phone_numbers__phone_number__put` (also callable as `g8.api.call("update_sms_phone_config_sms_phone_numbers__phone_number__put", 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: `campaigns:run`
+
+Change one number's AI-inbox settings. Omitted fields are left alone.
+
+`ai_inbox_enabled` decides whether the number's conversations appear in
+the inbox at all. `auto_respond` decides whether the AI REPLIES on it
+without a human - turning that on puts generated messages in front of real
+people, so it is the consequential one of the two.
+
+A PATCH in PUT's clothing, matching the app rather than inventing a second
+spelling for the same operation.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.phone_number` | `string` | yes | Phone number in E.164 form, e.g. +15551234567 |
+| `body` | `SmsPhoneConfigRequest` | yes | Request body; fields below. |
+
+Body fields (`SmsPhoneConfigRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.ai_inbox_enabled` | `boolean \| null` | no | Show this number's threads in the inbox |
+| `body.auto_respond` | `boolean \| null` | no | Let the AI reply on this number |
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**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.channels.updateSmsPhoneConfig({ path: { phone_number: "+15555550100" }, body: {} });
+```

package/docs/api/cliCampaigns.d.ts

@@ -0,0 +1,205 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.cliCampaigns` (CLI Campaigns): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_campaign_repos__repo_id__campaigns_post">;
+ *
+ * Reference with examples: cliCampaigns.md
+ */
+/* eslint-disable */
+
+/** `g8.api.cliCampaigns.<member>` -> the operationId it calls. */
+export interface CliCampaignsMembers {
+  createCampaign: "create_campaign_repos__repo_id__campaigns_post";
+  getCampaign: "get_campaign_repos__repo_id__campaigns__campaign_id__get";
+  getCampaignDocument: "get_campaign_document_repos__repo_id__campaigns__campaign_id__documents__document_id__get";
+  launchCampaign: "launch_campaign_repos__repo_id__campaigns__campaign_id__launch_post";
+  listCampaigns: "list_campaigns_repos__repo_id__campaigns_get";
+  updateCampaign: "update_campaign_repos__repo_id__campaigns__campaign_id__patch";
+}
+
+/** Input and output of every `g8.api.cliCampaigns` operation, keyed by operationId. */
+export interface CliCampaignsOperations {
+  /**
+   * POST /repos/{repo_id}/campaigns
+   * Create Campaign
+   * tier: write · scope: campaigns:write
+   */
+  create_campaign_repos__repo_id__campaigns_post: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: developer_api__interfaces__v1__cli_campaigns_router__CampaignCreateRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /repos/{repo_id}/campaigns/{campaign_id}
+   * Get Campaign
+   * tier: read · scope: campaigns:read
+   */
+  get_campaign_repos__repo_id__campaigns__campaign_id__get: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /repos/{repo_id}/campaigns/{campaign_id}/documents/{document_id}
+   * Get Campaign Document
+   * tier: read · scope: campaigns:read
+   */
+  get_campaign_document_repos__repo_id__campaigns__campaign_id__documents__document_id__get: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+      /** Campaign ID */
+      campaign_id: string;
+      /** Document ID */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /repos/{repo_id}/campaigns/{campaign_id}/launch
+   * Launch Campaign
+   * tier: external · scope: campaigns:launch
+   */
+  launch_campaign_repos__repo_id__campaigns__campaign_id__launch_post: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /repos/{repo_id}/campaigns
+   * List Campaigns
+   * tier: read · scope: campaigns:read
+   */
+  list_campaigns_repos__repo_id__campaigns_get: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    query?: {
+      /** Page number */
+      page?: number;
+      /** Items per page */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_dict__;
+  };
+  /**
+   * PATCH /repos/{repo_id}/campaigns/{campaign_id}
+   * Update Campaign
+   * tier: write · scope: campaigns:write
+   */
+  update_campaign_repos__repo_id__campaigns__campaign_id__patch: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: developer_api__interfaces__v1__cli_campaigns_router__CampaignUpdateRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+}
+
+// 5 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_dict__ {
+  data: Array<Record<string, unknown>>;
+  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 developer_api__interfaces__v1__cli_campaigns_router__CampaignCreateRequest {
+  /** Campaign brief */
+  brief?: string | null;
+  /** Campaign category */
+  category?: string;
+  /** Core concept */
+  core_concept?: string | null;
+  /** Campaign goal */
+  goal?: string | null;
+  /** Campaign name */
+  name: string;
+  /** Primary hook text */
+  primary_hook?: string | null;
+  /** Target persona */
+  target_persona?: string | null;
+}
+
+export interface developer_api__interfaces__v1__cli_campaigns_router__CampaignUpdateRequest {
+  /** Campaign brief */
+  brief?: string | null;
+  /** Campaign category */
+  category?: string | null;
+  /** Core concept */
+  core_concept?: string | null;
+  /** Campaign goal */
+  goal?: string | null;
+  /** Campaign name */
+  name?: string | null;
+  /** Primary hook text */
+  primary_hook?: string | null;
+  /** Target persona */
+  target_persona?: string | null;
+}