@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/recordRoles.md

@@ -0,0 +1,175 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.recordRoles`: Record Roles
+
+4 operations (2 read, 1 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.recordRoles.*` 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: [recordRoles.d.ts](recordRoles.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`assignRecordRole`](#op-assignrecordrole) | `POST /api/v1/records/{entity_type}/{entity_id}/role-assignments` | write | `contacts:write` | Assign Record Role |
+| [`clearRecordRole`](#op-clearrecordrole) | `DELETE /api/v1/records/{entity_type}/{entity_id}/role-assignments/{role_slot}` | destructive | `contacts:delete` | Clear Record Role |
+| [`getRecordRoleHistory`](#op-getrecordrolehistory) | `GET /api/v1/records/{entity_type}/{entity_id}/role-history` | read | `contacts:read` | Get Record Role History |
+| [`getRecordRoleSlots`](#op-getrecordroleslots) | `GET /api/v1/records/{entity_type}/{entity_id}/role-slots` | read | `contacts:read` | Get Record Role Slots |
+
+---
+
+<a id="op-assignrecordrole"></a>
+
+### `g8.api.recordRoles.assignRecordRole(input)`
+
+**Assign Record Role**
+
+- HTTP: `POST /api/v1/records/{entity_type}/{entity_id}/role-assignments`
+- operationId: `assign_record_role_records__entity_type___entity_id__role_assignments_post` (also callable as `g8.api.call("assign_record_role_records__entity_type___entity_id__role_assignments_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Put a member in a role slot. Other slots are untouched; re-assigning the holder is a no-op.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.entity_type` | `"contact" \| "company" \| "deal"` | yes | `contact`, `company` or `deal`. |
+| `path.entity_id` | `string` | yes | The record id. |
+| `body` | `RecordRoleAssignRequest` | yes | Request body; fields below. |
+
+Body fields (`RecordRoleAssignRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.role_slot` | `"sdr" \| "ae" \| "csm"` | yes |  |
+| `body.user_id` | `string` | yes | The org member to put in the slot. |
+| `body.reason` | `string \| null` | no | Why: manual_reassign \| rule_based \| account_owner_change \| import \| api. default `"manual_reassign"` |
+
+**Returns** `ApiResponse_RecordRolePayload_`: the envelope `{ data: RecordRolePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.recordRoles.assignRecordRole({
+  path: { entity_type: "contact", entity_id: "id" },
+  body: { role_slot: "sdr", user_id: "id" },
+});
+```
+
+---
+
+<a id="op-clearrecordrole"></a>
+
+### `g8.api.recordRoles.clearRecordRole(input)`
+
+**Clear Record Role**
+
+- HTTP: `DELETE /api/v1/records/{entity_type}/{entity_id}/role-assignments/{role_slot}`
+- operationId: `clear_record_role_records__entity_type___entity_id__role_assignments__role_slot__delete` (also callable as `g8.api.call("clear_record_role_records__entity_type___entity_id__role_assignments__role_slot__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `contacts:delete`
+
+Clear a role slot. Recorded as an unassignment in the history.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.entity_type` | `"contact" \| "company" \| "deal"` | yes | `contact`, `company` or `deal`. |
+| `path.entity_id` | `string` | yes | The record id. |
+| `path.role_slot` | `"sdr" \| "ae" \| "csm"` | yes | The slot to clear. |
+| `query.reason` | `string \| null` | no | Recorded on the history row. default `"manual_reassign"` |
+
+**Returns** `ApiResponse_RecordRolePayload_`: the envelope `{ data: RecordRolePayload, ... }`. `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.recordRoles.clearRecordRole({
+  path: { entity_type: "contact", entity_id: "id", role_slot: "sdr" },
+});
+```
+
+---
+
+<a id="op-getrecordrolehistory"></a>
+
+### `g8.api.recordRoles.getRecordRoleHistory(input)`
+
+**Get Record Role History**
+
+- HTTP: `GET /api/v1/records/{entity_type}/{entity_id}/role-history`
+- operationId: `get_record_role_history_records__entity_type___entity_id__role_history_get` (also callable as `g8.api.call("get_record_role_history_records__entity_type___entity_id__role_history_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Every assignment and unassignment on a record, in order.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.entity_type` | `"contact" \| "company" \| "deal"` | yes | `contact`, `company` or `deal`. |
+| `path.entity_id` | `string` | yes | The record id. |
+| `query.slot` | `"sdr" \| "ae" \| "csm" \| null` | no | Only this slot. |
+| `query.limit` | `integer` | no | default `100` |
+
+**Returns** `ApiResponse_RecordRolePayload_`: the envelope `{ data: RecordRolePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.recordRoles.getRecordRoleHistory({ path: { entity_type: "contact", entity_id: "id" } });
+```
+
+---
+
+<a id="op-getrecordroleslots"></a>
+
+### `g8.api.recordRoles.getRecordRoleSlots(input)`
+
+**Get Record Role Slots**
+
+- HTTP: `GET /api/v1/records/{entity_type}/{entity_id}/role-slots`
+- operationId: `get_record_role_slots_records__entity_type___entity_id__role_slots_get` (also callable as `g8.api.call("get_record_role_slots_records__entity_type___entity_id__role_slots_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Who currently holds each role slot on a record.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.entity_type` | `"contact" \| "company" \| "deal"` | yes | `contact`, `company` or `deal`. |
+| `path.entity_id` | `string` | yes | The record id. |
+
+**Returns** `ApiResponse_RecordRolePayload_`: the envelope `{ data: RecordRolePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.recordRoles.getRecordRoleSlots({ path: { entity_type: "contact", entity_id: "id" } });
+```

package/docs/api/repos.d.ts

@@ -0,0 +1,146 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.repos` (Repos): 4 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"connect_repo_repos_post">;
+ *
+ * Reference with examples: repos.md
+ */
+/* eslint-disable */
+
+/** `g8.api.repos.<member>` -> the operationId it calls. */
+export interface ReposMembers {
+  connectRepo: "connect_repo_repos_post";
+  deleteRepo: "delete_repo_repos__repo_id__delete";
+  getRepo: "get_repo_repos__repo_id__get";
+  listRepos: "list_repos_repos_get";
+}
+
+/** Input and output of every `g8.api.repos` operation, keyed by operationId. */
+export interface ReposOperations {
+  /**
+   * POST /repos
+   * Connect Repo
+   * tier: write · scope: campaigns:write
+   */
+  connect_repo_repos_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ConnectRepoRequest;
+  };
+    output: ApiResponse_RepoResponse_;
+  };
+  /**
+   * DELETE /repos/{repo_id}
+   * Delete Repo
+   * tier: destructive · scope: campaigns:delete
+   */
+  delete_repo_repos__repo_id__delete: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /repos/{repo_id}
+   * Get Repo
+   * tier: read · scope: campaigns:read
+   */
+  get_repo_repos__repo_id__get: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RepoResponse_;
+  };
+  /**
+   * GET /repos
+   * List Repos
+   * tier: read · scope: campaigns:read
+   */
+  list_repos_repos_get: {
+    input: {
+    query?: {
+      /** Page number (1-indexed) */
+      page?: number;
+      /** Items per page (max 200) */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_RepoResponse__;
+  };
+}
+
+// 6 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_RepoResponse_ {
+  data: RepoResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_RepoResponse__ {
+  data: Array<RepoResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ConnectRepoRequest {
+  /** Default branch name */
+  default_branch?: string;
+  /** Repository provider: github, gitlab, local */
+  provider?: string;
+  /** Repository name (e.g., my-saas-app) */
+  repo_name: string;
+  /** Repository URL (e.g., https://github.com/org/repo) */
+  repo_url: 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;
+}
+
+export interface RepoResponse {
+  created_at?: string | null;
+  default_branch: string;
+  id: string;
+  install_status: string;
+  project_id?: string | null;
+  provider: string;
+  repo_name: string;
+  repo_url: string;
+  scan_status: string;
+  updated_at?: string | null;
+  write_key?: string | null;
+}

package/docs/api/repos.md

@@ -0,0 +1,211 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.repos`: Repos
+
+4 operations (2 read, 1 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.repos.*` 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: [repos.d.ts](repos.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`connectRepo`](#op-connectrepo) | `POST /api/v1/repos` | write | `campaigns:write` | Connect Repo |
+| [`deleteRepo`](#op-deleterepo) | `DELETE /api/v1/repos/{repo_id}` | destructive | `campaigns:delete` | Delete Repo |
+| [`getRepo`](#op-getrepo) | `GET /api/v1/repos/{repo_id}` | read | `campaigns:read` | Get Repo |
+| [`listRepos`](#op-listrepos) | `GET /api/v1/repos` | read | `campaigns:read` | List Repos |
+
+---
+
+<a id="op-connectrepo"></a>
+
+### `g8.api.repos.connectRepo(input)`
+
+**Connect Repo**
+
+- HTTP: `POST /api/v1/repos`
+- operationId: `connect_repo_repos_post` (also callable as `g8.api.call("connect_repo_repos_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Connect a repository to the organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ConnectRepoRequest` | yes | Request body; fields below. |
+
+Body fields (`ConnectRepoRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.repo_name` | `string` | yes | Repository name (e.g., my-saas-app) |
+| `body.repo_url` | `string` | yes | Repository URL (e.g., https://github.com/org/repo) |
+| `body.default_branch` | `string` | no | Default branch name default `"main"` |
+| `body.provider` | `string` | no | Repository provider: github, gitlab, local default `"github"` |
+
+**Returns** `ApiResponse_RepoResponse_`: the envelope `{ data: RepoResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RepoResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `default_branch` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `install_status` | `string` | yes |  |
+| `provider` | `string` | yes |  |
+| `repo_name` | `string` | yes |  |
+| `repo_url` | `string` | yes |  |
+| `scan_status` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `project_id` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `write_key` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.repos.connectRepo({ body: { repo_name: "Example", repo_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-deleterepo"></a>
+
+### `g8.api.repos.deleteRepo(input)`
+
+**Delete Repo**
+
+- HTTP: `DELETE /api/v1/repos/{repo_id}`
+- operationId: `delete_repo_repos__repo_id__delete` (also callable as `g8.api.call("delete_repo_repos__repo_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Disconnect a repository from the organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.repos.deleteRepo({ path: { repo_id: "id" } });
+```
+
+---
+
+<a id="op-getrepo"></a>
+
+### `g8.api.repos.getRepo(input)`
+
+**Get Repo**
+
+- HTTP: `GET /api/v1/repos/{repo_id}`
+- operationId: `get_repo_repos__repo_id__get` (also callable as `g8.api.call("get_repo_repos__repo_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Get details of a connected repository.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.repo_id` | `string` | yes | Repository ID |
+
+**Returns** `ApiResponse_RepoResponse_`: the envelope `{ data: RepoResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RepoResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `default_branch` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `install_status` | `string` | yes |  |
+| `provider` | `string` | yes |  |
+| `repo_name` | `string` | yes |  |
+| `repo_url` | `string` | yes |  |
+| `scan_status` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `project_id` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `write_key` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.repos.getRepo({ path: { repo_id: "id" } });
+```
+
+---
+
+<a id="op-listrepos"></a>
+
+### `g8.api.repos.listRepos(input?)`
+
+**List Repos**
+
+- HTTP: `GET /api/v1/repos`
+- operationId: `list_repos_repos_get` (also callable as `g8.api.call("list_repos_repos_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+List all connected repositories in the organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | Page number (1-indexed) default `1` |
+| `query.limit` | `integer` | no | Items per page (max 200) default `50` |
+
+**Returns** `ApiResponse_list_RepoResponse__`: the envelope `{ data: Array<RepoResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RepoResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `default_branch` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `install_status` | `string` | yes |  |
+| `provider` | `string` | yes |  |
+| `repo_name` | `string` | yes |  |
+| `repo_url` | `string` | yes |  |
+| `scan_status` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `project_id` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `write_key` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.repos.listRepos();
+```