@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/contentGridSkills.d.ts

@@ -0,0 +1,177 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.contentGridSkills` (Content Grid Skills): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"add_content_grid_column_content_grids__grid_id__columns_post">;
+ *
+ * Reference with examples: contentGridSkills.md
+ */
+/* eslint-disable */
+
+/** `g8.api.contentGridSkills.<member>` -> the operationId it calls. */
+export interface ContentGridSkillsMembers {
+  addContentGridColumn: "add_content_grid_column_content_grids__grid_id__columns_post";
+  getContentSkillRun: "get_content_skill_run_content_skill_runs__execution_id__get";
+  removeContentGridColumn: "remove_content_grid_column_content_grids__grid_id__columns__column_id__delete";
+  runContentGridCell: "run_content_grid_cell_content_grids__grid_id__rows__row_id__run__column_id__post";
+  runContentGridColumn: "run_content_grid_column_content_grids__grid_id__columns__column_id__run_post";
+  updateContentGridColumn: "update_content_grid_column_content_grids__grid_id__columns__column_id__put";
+}
+
+/** Input and output of every `g8.api.contentGridSkills` operation, keyed by operationId. */
+export interface ContentGridSkillsOperations {
+  /**
+   * POST /content/grids/{grid_id}/columns
+   * Add Content Grid Column
+   * tier: write · scope: campaigns:write
+   */
+  add_content_grid_column_content_grids__grid_id__columns_post: {
+    input: {
+    path: {
+      /** Grid id. */
+      grid_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContentGridColumnRequest;
+  };
+    output: ApiResponse_ContentGridSkillPayload_;
+  };
+  /**
+   * GET /content/skill-runs/{execution_id}
+   * Get Content Skill Run
+   * tier: read · scope: campaigns:read
+   */
+  get_content_skill_run_content_skill_runs__execution_id__get: {
+    input: {
+    path: {
+      /** Run id returned when the run was queued. */
+      execution_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ContentGridSkillPayload_;
+  };
+  /**
+   * DELETE /content/grids/{grid_id}/columns/{column_id}
+   * Remove Content Grid Column
+   * tier: destructive · scope: campaigns:delete
+   */
+  remove_content_grid_column_content_grids__grid_id__columns__column_id__delete: {
+    input: {
+    path: {
+      /** Grid id. */
+      grid_id: string;
+      /** Column id. */
+      column_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ContentGridSkillPayload_;
+  };
+  /**
+   * POST /content/grids/{grid_id}/rows/{row_id}/run/{column_id}
+   * Run Content Grid Cell
+   * tier: billable · scope: campaigns:run
+   */
+  run_content_grid_cell_content_grids__grid_id__rows__row_id__run__column_id__post: {
+    input: {
+    path: {
+      /** Grid id. */
+      grid_id: string;
+      /** Row (content job) id. */
+      row_id: string;
+      /** Skill column id. */
+      column_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ContentGridSkillPayload_;
+  };
+  /**
+   * POST /content/grids/{grid_id}/columns/{column_id}/run
+   * Run Content Grid Column
+   * tier: billable · scope: campaigns:run
+   */
+  run_content_grid_column_content_grids__grid_id__columns__column_id__run_post: {
+    input: {
+    path: {
+      /** Grid id. */
+      grid_id: string;
+      /** Skill column id. */
+      column_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: ContentGridRunRequest | null;
+  };
+    output: ApiResponse_ContentGridSkillPayload_;
+  };
+  /**
+   * PUT /content/grids/{grid_id}/columns/{column_id}
+   * Update Content Grid Column
+   * tier: write · scope: campaigns:write
+   */
+  update_content_grid_column_content_grids__grid_id__columns__column_id__put: {
+    input: {
+    path: {
+      /** Grid id. */
+      grid_id: string;
+      /** Column id. */
+      column_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContentGridColumnRequest;
+  };
+    output: ApiResponse_ContentGridSkillPayload_;
+  };
+}
+
+// 5 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_ContentGridSkillPayload_ {
+  data: ContentGridSkillPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ContentGridColumnRequest {
+  column_name: string;
+  /** Skill input name -> row field it reads, e.g. `{"keyword": "target_keyword"}`. */
+  input_mapping?: Record<string, string> | null;
+  /** The content skill this column runs. */
+  skill_id: string;
+}
+
+export interface ContentGridRunRequest {
+  /** Only these rows. Omit for every row. */
+  row_ids?: Array<string> | null;
+}
+
+/** A grid column, a queued run, or a run's result. */
+export type ContentGridSkillPayload = 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;
+}

package/docs/api/contentGridSkills.md

@@ -0,0 +1,271 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.contentGridSkills`: Content Grid Skills
+
+6 operations (1 read, 2 write, 1 destructive, 2 billable).
+
+No hand-written client covers this area. Call it through `g8.api.contentGridSkills.*` 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: [contentGridSkills.d.ts](contentGridSkills.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`addContentGridColumn`](#op-addcontentgridcolumn) | `POST /api/v1/content/grids/{grid_id}/columns` | write | `campaigns:write` | Add Content Grid Column |
+| [`getContentSkillRun`](#op-getcontentskillrun) | `GET /api/v1/content/skill-runs/{execution_id}` | read | `campaigns:read` | Get Content Skill Run |
+| [`removeContentGridColumn`](#op-removecontentgridcolumn) | `DELETE /api/v1/content/grids/{grid_id}/columns/{column_id}` | destructive | `campaigns:delete` | Remove Content Grid Column |
+| [`runContentGridCell`](#op-runcontentgridcell) | `POST /api/v1/content/grids/{grid_id}/rows/{row_id}/run/{column_id}` | billable | `campaigns:run` | Run Content Grid Cell |
+| [`runContentGridColumn`](#op-runcontentgridcolumn) | `POST /api/v1/content/grids/{grid_id}/columns/{column_id}/run` | billable | `campaigns:run` | Run Content Grid Column |
+| [`updateContentGridColumn`](#op-updatecontentgridcolumn) | `PUT /api/v1/content/grids/{grid_id}/columns/{column_id}` | write | `campaigns:write` | Update Content Grid Column |
+
+---
+
+<a id="op-addcontentgridcolumn"></a>
+
+### `g8.api.contentGridSkills.addContentGridColumn(input)`
+
+**Add Content Grid Column**
+
+- HTTP: `POST /api/v1/content/grids/{grid_id}/columns`
+- operationId: `add_content_grid_column_content_grids__grid_id__columns_post` (also callable as `g8.api.call("add_content_grid_column_content_grids__grid_id__columns_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Add a skill column to a grid. Nothing runs until you run it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.grid_id` | `string (uuid)` | yes | Grid id. |
+| `body` | `ContentGridColumnRequest` | yes | Request body; fields below. |
+
+Body fields (`ContentGridColumnRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.column_name` | `string` | yes |  |
+| `body.skill_id` | `string (uuid)` | yes | The content skill this column runs. |
+| `body.input_mapping` | `Record<string, string> \| null` | no | Skill input name -> row field it reads, e.g. `{"keyword": "target_keyword"}`. |
+
+**Returns** `ApiResponse_ContentGridSkillPayload_`: the envelope `{ data: ContentGridSkillPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.contentGridSkills.addContentGridColumn({
+  path: { grid_id: "00000000-0000-0000-0000-000000000000" },
+  body: {
+    column_name: "Example",
+    skill_id: "00000000-0000-0000-0000-000000000000",
+  },
+});
+```
+
+---
+
+<a id="op-getcontentskillrun"></a>
+
+### `g8.api.contentGridSkills.getContentSkillRun(input)`
+
+**Get Content Skill Run**
+
+- HTTP: `GET /api/v1/content/skill-runs/{execution_id}`
+- operationId: `get_content_skill_run_content_skill_runs__execution_id__get` (also callable as `g8.api.call("get_content_skill_run_content_skill_runs__execution_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One skill run: its status, inputs and output.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Run id returned when the run was queued. |
+
+**Returns** `ApiResponse_ContentGridSkillPayload_`: the envelope `{ data: ContentGridSkillPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.contentGridSkills.getContentSkillRun({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-removecontentgridcolumn"></a>
+
+### `g8.api.contentGridSkills.removeContentGridColumn(input)`
+
+**Remove Content Grid Column**
+
+- HTTP: `DELETE /api/v1/content/grids/{grid_id}/columns/{column_id}`
+- operationId: `remove_content_grid_column_content_grids__grid_id__columns__column_id__delete` (also callable as `g8.api.call("remove_content_grid_column_content_grids__grid_id__columns__column_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Remove a column from a grid.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.grid_id` | `string (uuid)` | yes | Grid id. |
+| `path.column_id` | `string` | yes | Column id. |
+
+**Returns** `ApiResponse_ContentGridSkillPayload_`: the envelope `{ data: ContentGridSkillPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.contentGridSkills.removeContentGridColumn({
+  path: { grid_id: "00000000-0000-0000-0000-000000000000", column_id: "id" },
+});
+```
+
+---
+
+<a id="op-runcontentgridcell"></a>
+
+### `g8.api.contentGridSkills.runContentGridCell(input)`
+
+**Run Content Grid Cell**
+
+- HTTP: `POST /api/v1/content/grids/{grid_id}/rows/{row_id}/run/{column_id}`
+- operationId: `run_content_grid_cell_content_grids__grid_id__rows__row_id__run__column_id__post` (also callable as `g8.api.call("run_content_grid_cell_content_grids__grid_id__rows__row_id__run__column_id__post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Run one skill column on one row (runs a model; billable).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.grid_id` | `string (uuid)` | yes | Grid id. |
+| `path.row_id` | `string` | yes | Row (content job) id. |
+| `path.column_id` | `string` | yes | Skill column id. |
+
+**Returns** `ApiResponse_ContentGridSkillPayload_`: the envelope `{ data: ContentGridSkillPayload, ... }`. `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.contentGridSkills.runContentGridCell({
+  path: {
+    grid_id: "00000000-0000-0000-0000-000000000000",
+    row_id: "id",
+    column_id: "id",
+  },
+});
+```
+
+---
+
+<a id="op-runcontentgridcolumn"></a>
+
+### `g8.api.contentGridSkills.runContentGridColumn(input)`
+
+**Run Content Grid Column**
+
+- HTTP: `POST /api/v1/content/grids/{grid_id}/columns/{column_id}/run`
+- operationId: `run_content_grid_column_content_grids__grid_id__columns__column_id__run_post` (also callable as `g8.api.call("run_content_grid_column_content_grids__grid_id__columns__column_id__run_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Run one skill column on every row, or on `row_ids` (one model call per row; billable).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.grid_id` | `string (uuid)` | yes | Grid id. |
+| `path.column_id` | `string` | yes | Skill column id. |
+| `body` | `ContentGridRunRequest \| null` | no | Request body; fields below. |
+
+Body fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.row_ids` | `Array<string> \| null` | no | Only these rows. Omit for every row. |
+
+**Returns** `ApiResponse_ContentGridSkillPayload_`: the envelope `{ data: ContentGridSkillPayload, ... }`. `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.contentGridSkills.runContentGridColumn({
+  path: { grid_id: "00000000-0000-0000-0000-000000000000", column_id: "id" },
+});
+```
+
+---
+
+<a id="op-updatecontentgridcolumn"></a>
+
+### `g8.api.contentGridSkills.updateContentGridColumn(input)`
+
+**Update Content Grid Column**
+
+- HTTP: `PUT /api/v1/content/grids/{grid_id}/columns/{column_id}`
+- operationId: `update_content_grid_column_content_grids__grid_id__columns__column_id__put` (also callable as `g8.api.call("update_content_grid_column_content_grids__grid_id__columns__column_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Rename a column or change its input mapping.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.grid_id` | `string (uuid)` | yes | Grid id. |
+| `path.column_id` | `string` | yes | Column id. |
+| `body` | `ContentGridColumnRequest` | yes | Request body; fields below. |
+
+Body fields (`ContentGridColumnRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.column_name` | `string` | yes |  |
+| `body.skill_id` | `string (uuid)` | yes | The content skill this column runs. |
+| `body.input_mapping` | `Record<string, string> \| null` | no | Skill input name -> row field it reads, e.g. `{"keyword": "target_keyword"}`. |
+
+**Returns** `ApiResponse_ContentGridSkillPayload_`: the envelope `{ data: ContentGridSkillPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.contentGridSkills.updateContentGridColumn({
+  path: { grid_id: "00000000-0000-0000-0000-000000000000", column_id: "id" },
+  body: {
+    column_name: "Example",
+    skill_id: "00000000-0000-0000-0000-000000000000",
+  },
+});
+```