@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/studioDocuments.d.ts

@@ -0,0 +1,244 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.studioDocuments` (Studio Documents): 9 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"compare_document_versions_document_versions__document_type___document_id__compare_get">;
+ *
+ * Reference with examples: studioDocuments.md
+ */
+/* eslint-disable */
+
+/** `g8.api.studioDocuments.<member>` -> the operationId it calls. */
+export interface StudioDocumentsMembers {
+  compareDocumentVersions: "compare_document_versions_document_versions__document_type___document_id__compare_get";
+  getBrandSnapshot: "get_brand_snapshot_org_brand_snapshot_get";
+  getCurrentDocumentVersion: "get_current_document_version_document_versions__document_type___document_id__current_get";
+  getDocumentVersion: "get_document_version_document_versions__document_type___document_id___version_number__get";
+  getStyleRules: "get_style_rules_style_rules_get";
+  listDocumentVersions: "list_document_versions_document_versions__document_type___document_id__get";
+  normalizeTextToStyle: "normalize_text_to_style_style_normalize_post";
+  refreshBrandSnapshot: "refresh_brand_snapshot_org_brand_snapshot_refresh_post";
+  revertDocumentVersion: "revert_document_version_document_versions__document_type___document_id__revert__version_number__post";
+}
+
+/** Input and output of every `g8.api.studioDocuments` operation, keyed by operationId. */
+export interface StudioDocumentsOperations {
+  /**
+   * GET /document-versions/{document_type}/{document_id}/compare
+   * Compare Document Versions
+   * tier: read · scope: campaigns:read
+   */
+  compare_document_versions_document_versions__document_type___document_id__compare_get: {
+    input: {
+    path: {
+      /** Which kind of document the id belongs to. */
+      document_type: "library" | "global_context" | "research" | "tam" | "campaign_document";
+      /** Document id. */
+      document_id: string;
+    };
+    query: {
+      /** The older version number. */
+      from: number;
+      /** A version number, or `current`. */
+      to?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * GET /org/brand-snapshot
+   * Get Brand Snapshot
+   * tier: read · scope: campaigns:read
+   */
+  get_brand_snapshot_org_brand_snapshot_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * GET /document-versions/{document_type}/{document_id}/current
+   * Get Current Document Version
+   * tier: read · scope: campaigns:read
+   */
+  get_current_document_version_document_versions__document_type___document_id__current_get: {
+    input: {
+    path: {
+      /** Which kind of document the id belongs to. */
+      document_type: "library" | "global_context" | "research" | "tam" | "campaign_document";
+      /** Document id. */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * GET /document-versions/{document_type}/{document_id}/{version_number}
+   * Get Document Version
+   * tier: read · scope: campaigns:read
+   */
+  get_document_version_document_versions__document_type___document_id___version_number__get: {
+    input: {
+    path: {
+      /** Which kind of document the id belongs to. */
+      document_type: "library" | "global_context" | "research" | "tam" | "campaign_document";
+      /** Document id. */
+      document_id: string;
+      /** Version number, from the history. */
+      version_number: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * GET /style/rules
+   * Get Style Rules
+   * tier: read · scope: campaigns:read
+   */
+  get_style_rules_style_rules_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * GET /document-versions/{document_type}/{document_id}
+   * List Document Versions
+   * tier: read · scope: campaigns:read
+   */
+  list_document_versions_document_versions__document_type___document_id__get: {
+    input: {
+    path: {
+      /** Which kind of document the id belongs to. */
+      document_type: "library" | "global_context" | "research" | "tam" | "campaign_document";
+      /** Document id. */
+      document_id: string;
+    };
+    query?: {
+      limit?: number;
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentListPayload_;
+  };
+  /**
+   * POST /style/normalize
+   * Normalize Text To Style
+   * tier: write · scope: campaigns:write
+   */
+  normalize_text_to_style_style_normalize_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: StyleNormalizeRequest;
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * POST /org/brand-snapshot/refresh
+   * Refresh Brand Snapshot
+   * tier: billable · scope: campaigns:run
+   */
+  refresh_brand_snapshot_org_brand_snapshot_refresh_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * POST /document-versions/{document_type}/{document_id}/revert/{version_number}
+   * Revert Document Version
+   * tier: write · scope: campaigns:write
+   */
+  revert_document_version_document_versions__document_type___document_id__revert__version_number__post: {
+    input: {
+    path: {
+      /** Which kind of document the id belongs to. */
+      document_type: "library" | "global_context" | "research" | "tam" | "campaign_document";
+      /** Document id. */
+      document_id: string;
+      /** Version number, from the history. */
+      version_number: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: DocumentRevertRequest | null;
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+}
+
+// 7 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_StudioContentListPayload_ {
+  data: StudioContentListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_StudioContentPayload_ {
+  data: StudioContentPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/** Optional note recorded on the revert's own version. */
+export interface DocumentRevertRequest {
+  change_summary?: string | 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;
+}
+
+/**
+ * A LIST result, open-shaped, with `items` always present.
+ *
+ * The app returns a bare list from some routes and a named key from others
+ * (`pages`, `grids`, `images`, `creatives`, `reports`, `items`). Both are
+ * published: the original key is preserved AND mirrored onto `items`, so a
+ * client can page any Studio collection the same way without a per-route
+ * lookup table.
+ */
+export interface StudioContentListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/** One Studio object, open-shaped. See the module docstring. */
+export type StudioContentPayload = Record<string, unknown>;
+
+/** Text to normalise to the org's writing style. */
+export interface StyleNormalizeRequest {
+  text: string;
+}

package/docs/api/studioDocuments.md

@@ -0,0 +1,348 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.studioDocuments`: Studio Documents
+
+9 operations (6 read, 2 write, 1 billable).
+
+No hand-written client covers this area. Call it through `g8.api.studioDocuments.*` 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: [studioDocuments.d.ts](studioDocuments.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`compareDocumentVersions`](#op-comparedocumentversions) | `GET /api/v1/document-versions/{document_type}/{document_id}/compare` | read | `campaigns:read` | Compare Document Versions |
+| [`getBrandSnapshot`](#op-getbrandsnapshot) | `GET /api/v1/org/brand-snapshot` | read | `campaigns:read` | Get Brand Snapshot |
+| [`getCurrentDocumentVersion`](#op-getcurrentdocumentversion) | `GET /api/v1/document-versions/{document_type}/{document_id}/current` | read | `campaigns:read` | Get Current Document Version |
+| [`getDocumentVersion`](#op-getdocumentversion) | `GET /api/v1/document-versions/{document_type}/{document_id}/{version_number}` | read | `campaigns:read` | Get Document Version |
+| [`getStyleRules`](#op-getstylerules) | `GET /api/v1/style/rules` | read | `campaigns:read` | Get Style Rules |
+| [`listDocumentVersions`](#op-listdocumentversions) | `GET /api/v1/document-versions/{document_type}/{document_id}` | read | `campaigns:read` | List Document Versions |
+| [`normalizeTextToStyle`](#op-normalizetexttostyle) | `POST /api/v1/style/normalize` | write | `campaigns:write` | Normalize Text To Style |
+| [`refreshBrandSnapshot`](#op-refreshbrandsnapshot) | `POST /api/v1/org/brand-snapshot/refresh` | billable | `campaigns:run` | Refresh Brand Snapshot |
+| [`revertDocumentVersion`](#op-revertdocumentversion) | `POST /api/v1/document-versions/{document_type}/{document_id}/revert/{version_number}` | write | `campaigns:write` | Revert Document Version |
+
+---
+
+<a id="op-comparedocumentversions"></a>
+
+### `g8.api.studioDocuments.compareDocumentVersions(input)`
+
+**Compare Document Versions**
+
+- HTTP: `GET /api/v1/document-versions/{document_type}/{document_id}/compare`
+- operationId: `compare_document_versions_document_versions__document_type___document_id__compare_get` (also callable as `g8.api.call("compare_document_versions_document_versions__document_type___document_id__compare_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+A unified text diff between two versions. FREE. Very large diffs are truncated.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.document_type` | `"library" \| "global_context" \| "research" \| "tam" \| "campaign_document"` | yes | Which kind of document the id belongs to. |
+| `path.document_id` | `string` | yes | Document id. |
+| `query.from` | `integer` | yes | The older version number. |
+| `query.to` | `string` | no | A version number, or `current`. default `"current"` |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.studioDocuments.compareDocumentVersions({
+  path: { document_type: "library", document_id: "id" },
+  query: { from: 1 },
+});
+```
+
+---
+
+<a id="op-getbrandsnapshot"></a>
+
+### `g8.api.studioDocuments.getBrandSnapshot(input?)`
+
+**Get Brand Snapshot**
+
+- HTTP: `GET /api/v1/org/brand-snapshot`
+- operationId: `get_brand_snapshot_org_brand_snapshot_get` (also callable as `g8.api.call("get_brand_snapshot_org_brand_snapshot_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The brand captured from the org's website: design tokens, logo, images. FREE.
+
+404 until a capture has run - `POST /org/brand-snapshot/refresh` starts one.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.studioDocuments.getBrandSnapshot();
+```
+
+---
+
+<a id="op-getcurrentdocumentversion"></a>
+
+### `g8.api.studioDocuments.getCurrentDocumentVersion(input)`
+
+**Get Current Document Version**
+
+- HTTP: `GET /api/v1/document-versions/{document_type}/{document_id}/current`
+- operationId: `get_current_document_version_document_versions__document_type___document_id__current_get` (also callable as `g8.api.call("get_current_document_version_document_versions__document_type___document_id__current_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The document's current version number. FREE.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.document_type` | `"library" \| "global_context" \| "research" \| "tam" \| "campaign_document"` | yes | Which kind of document the id belongs to. |
+| `path.document_id` | `string` | yes | Document id. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.studioDocuments.getCurrentDocumentVersion({ path: { document_type: "library", document_id: "id" } });
+```
+
+---
+
+<a id="op-getdocumentversion"></a>
+
+### `g8.api.studioDocuments.getDocumentVersion(input)`
+
+**Get Document Version**
+
+- HTTP: `GET /api/v1/document-versions/{document_type}/{document_id}/{version_number}`
+- operationId: `get_document_version_document_versions__document_type___document_id___version_number__get` (also callable as `g8.api.call("get_document_version_document_versions__document_type___document_id___version_number__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One saved version's full content. FREE.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.document_type` | `"library" \| "global_context" \| "research" \| "tam" \| "campaign_document"` | yes | Which kind of document the id belongs to. |
+| `path.document_id` | `string` | yes | Document id. |
+| `path.version_number` | `integer` | yes | Version number, from the history. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.studioDocuments.getDocumentVersion({
+  path: { document_type: "library", document_id: "id", version_number: 1 },
+});
+```
+
+---
+
+<a id="op-getstylerules"></a>
+
+### `g8.api.studioDocuments.getStyleRules(input?)`
+
+**Get Style Rules**
+
+- HTTP: `GET /api/v1/style/rules`
+- operationId: `get_style_rules_style_rules_get` (also callable as `g8.api.call("get_style_rules_style_rules_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The org's parsed writing-style rules. FREE.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.studioDocuments.getStyleRules();
+```
+
+---
+
+<a id="op-listdocumentversions"></a>
+
+### `g8.api.studioDocuments.listDocumentVersions(input)`
+
+**List Document Versions**
+
+- HTTP: `GET /api/v1/document-versions/{document_type}/{document_id}`
+- operationId: `list_document_versions_document_versions__document_type___document_id__get` (also callable as `g8.api.call("list_document_versions_document_versions__document_type___document_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+A document's saved versions, newest first. FREE.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.document_type` | `"library" \| "global_context" \| "research" \| "tam" \| "campaign_document"` | yes | Which kind of document the id belongs to. |
+| `path.document_id` | `string` | yes | Document id. |
+| `query.limit` | `integer` | no | default `50` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_StudioContentListPayload_`: the envelope `{ data: StudioContentListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`StudioContentListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.studioDocuments.listDocumentVersions({ path: { document_type: "library", document_id: "id" } });
+```
+
+---
+
+<a id="op-normalizetexttostyle"></a>
+
+### `g8.api.studioDocuments.normalizeTextToStyle(input)`
+
+**Normalize Text To Style**
+
+- HTTP: `POST /api/v1/style/normalize`
+- operationId: `normalize_text_to_style_style_normalize_post` (also callable as `g8.api.call("normalize_text_to_style_style_normalize_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Apply the org's writing-style rules (brand-name casing and the like) to a text. FREE.
+
+Deterministic - no model runs. The same normalisation generation applies.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `StyleNormalizeRequest` | yes | Request body; fields below. |
+
+Body fields (`StyleNormalizeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.text` | `string` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.studioDocuments.normalizeTextToStyle({ body: { text: "example" } });
+```
+
+---
+
+<a id="op-refreshbrandsnapshot"></a>
+
+### `g8.api.studioDocuments.refreshBrandSnapshot(input?)`
+
+**Refresh Brand Snapshot**
+
+- HTTP: `POST /api/v1/org/brand-snapshot/refresh`
+- operationId: `refresh_brand_snapshot_org_brand_snapshot_refresh_post` (also callable as `g8.api.call("refresh_brand_snapshot_org_brand_snapshot_refresh_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Re-capture the brand from the org's website. SPENDS PROVIDER CREDIT.
+
+A background job scrapes the site through a paid scraping provider.
+Returns a task id.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.studioDocuments.refreshBrandSnapshot();
+```
+
+---
+
+<a id="op-revertdocumentversion"></a>
+
+### `g8.api.studioDocuments.revertDocumentVersion(input)`
+
+**Revert Document Version**
+
+- HTTP: `POST /api/v1/document-versions/{document_type}/{document_id}/revert/{version_number}`
+- operationId: `revert_document_version_document_versions__document_type___document_id__revert__version_number__post` (also callable as `g8.api.call("revert_document_version_document_versions__document_type___document_id__revert__version_number__post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Restore a saved version as the document's content. FREE.
+
+The revert is itself recorded as a new version, so it can be undone.
+Everything generated from the document afterwards uses the restored text.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.document_type` | `"library" \| "global_context" \| "research" \| "tam" \| "campaign_document"` | yes | Which kind of document the id belongs to. |
+| `path.document_id` | `string` | yes | Document id. |
+| `path.version_number` | `integer` | yes | Version number, from the history. |
+| `body` | `DocumentRevertRequest \| null` | no | Request body; fields below. |
+
+Body fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.change_summary` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.studioDocuments.revertDocumentVersion({
+  path: { document_type: "library", document_id: "id", version_number: 1 },
+});
+```

package/docs/api/support.d.ts

@@ -0,0 +1,90 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.support` (Support): 1 operation.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"contact_support_support_contact_post">;
+ *
+ * Reference with examples: support.md
+ */
+/* eslint-disable */
+
+/** `g8.api.support.<member>` -> the operationId it calls. */
+export interface SupportMembers {
+  contactSupport: "contact_support_support_contact_post";
+}
+
+/** Input and output of every `g8.api.support` operation, keyed by operationId. */
+export interface SupportOperations {
+  /**
+   * POST /support/contact
+   * Contact Support
+   * tier: write · scope: account:write
+   */
+  contact_support_support_contact_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactSupportRequest;
+  };
+    output: ApiResponse_ContactSupportResponse_;
+  };
+}
+
+// 4 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_ContactSupportResponse_ {
+  data: ContactSupportResponse;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * A support request relayed from an AI client (or direct API caller).
+ *
+ * ``urgency`` is deliberately a free-form string, not an enum — LLM callers
+ * produce arbitrary phrasing and a 422 on vocabulary would block a user who
+ * is already asking for help. Urgent-flavored values ("high", "urgent",
+ * "critical", "asap") get a visible subject-line prefix; everything else is
+ * passed through as informational text.
+ */
+export interface ContactSupportRequest {
+  /** Where graph8 support should reply. Optional for personal API keys (the key's own user email is used); REQUIRED for org-scoped machine keys, which carry no personal email. */
+  contact_email?: string | null;
+  /** What the user needs help with, in their own words. */
+  message: string;
+  /** Free-form urgency hint, e.g. 'normal', 'high', 'urgent'. */
+  urgency?: string | null;
+}
+
+/**
+ * Acknowledgment for a support request.
+ *
+ * ``status`` is ``received`` on first delivery and ``already_received`` when
+ * the per-user cooldown swallowed a duplicate (still HTTP 200 — a retryable
+ * error code would make LLM callers loop harder).
+ */
+export interface ContactSupportResponse {
+  /** Human-readable summary for the caller to relay to the user. */
+  note?: string;
+  /** Support staff notified on this call (0 on cooldown). */
+  notified?: number;
+  /** Address graph8 support will reply to. */
+  reply_email?: string | null;
+  status: string;
+}
+
+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;
+}