@graph8/sdk 0.308.1 → 0.357.0

package/docs/api/processLists.md

@@ -0,0 +1,409 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.processLists`: Process Lists
+
+6 operations (2 read, 3 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.processLists.*` 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: [processLists.d.ts](processLists.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`archiveProcessListApi`](#op-archiveprocesslistapi) | `DELETE /api/v1/process-lists/{slug}` | destructive | `objects:manage` | Archive Process List Api |
+| [`createProcessListApi`](#op-createprocesslistapi) | `POST /api/v1/process-lists` | write | `objects:manage` | Create Process List Api |
+| [`createProcessListEntryApi`](#op-createprocesslistentryapi) | `POST /api/v1/process-lists/{slug}/entries` | write | `objects:write` | Create Process List Entry Api |
+| [`getProcessListApi`](#op-getprocesslistapi) | `GET /api/v1/process-lists/{slug}` | read | `objects:read` | Get Process List Api |
+| [`listProcessListsApi`](#op-listprocesslistsapi) | `GET /api/v1/process-lists` | read | `objects:read` | List Process Lists Api |
+| [`updateProcessListApi`](#op-updateprocesslistapi) | `PATCH /api/v1/process-lists/{slug}` | write | `objects:manage` | Update Process List Api |
+
+---
+
+<a id="op-archiveprocesslistapi"></a>
+
+### `g8.api.processLists.archiveProcessListApi(input)`
+
+**Archive Process List Api**
+
+- HTTP: `DELETE /api/v1/process-lists/{slug}`
+- operationId: `archive_process_list_api_process_lists__slug__delete` (also callable as `g8.api.call("archive_process_list_api_process_lists__slug__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `objects:manage`
+
+Archive a list without deleting its entries; restore with PATCH ``is_archived=false``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.slug` | `string` | yes |  |
+
+**Returns** `ApiResponse_ProcessListResponse_`: the envelope `{ data: ProcessListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ProcessListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_slug` | `string` | yes |  |
+| `created_at` | `string (date-time)` | yes |  |
+| `entries_label` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `is_archived` | `boolean` | yes |  |
+| `parent_kind` | `"custom" \| "contacts" \| "companies" \| "deals"` | yes |  |
+| `parent_label` | `string` | yes |  |
+| `parent_relationship_definition_id` | `string (uuid)` | yes |  |
+| `plural_noun` | `string` | yes |  |
+| `singular_noun` | `string` | yes |  |
+| `updated_at` | `string (date-time)` | yes |  |
+| `description` | `string \| null` | no |  |
+| `display_attribute_slug` | `string \| null` | no |  |
+| `icon` | `string \| null` | no |  |
+| `parent_object_id` | `string (uuid) \| null` | no |  |
+| `parent_object_slug` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.processLists.archiveProcessListApi({ path: { slug: "example" } });
+```
+
+---
+
+<a id="op-createprocesslistapi"></a>
+
+### `g8.api.processLists.createProcessListApi(input)`
+
+**Create Process List Api**
+
+- HTTP: `POST /api/v1/process-lists`
+- operationId: `create_process_list_api_process_lists_post` (also callable as `g8.api.call("create_process_list_api_process_lists_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:manage`
+
+Create a process list: its object, its parent relationship and the marker, atomically. Requires
+objects:manage and current Admin access, the same gate as ``POST /objects``. Add the list's fields with
+``POST /objects/{slug}/attributes``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProcessListCreate` | yes | Request body; fields below. |
+
+Body fields (`ProcessListCreate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.api_slug` | `string` | yes | min length 1, max length 93, pattern `^[a-z][a-z0-9_]*$` |
+| `body.entries_label` | `string` | yes | min length 1, max length 100 |
+| `body.parent` | `RelationshipTarget` | yes |  |
+| `body.parent_label` | `string` | yes | min length 1, max length 100 |
+| `body.plural_noun` | `string` | yes | min length 1, max length 100 |
+| `body.singular_noun` | `string` | yes | min length 1, max length 100 |
+| `body.description` | `string \| null` | no | max length 2000 |
+| `body.icon` | `"box" \| "briefcase" \| "building" \| "calendar" \| "flag" \| "folder" \| "globe" \| "heart" \| … \| null` | no |  |
+
+**Returns** `ApiResponse_ProcessListResponse_`: the envelope `{ data: ProcessListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ProcessListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_slug` | `string` | yes |  |
+| `created_at` | `string (date-time)` | yes |  |
+| `entries_label` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `is_archived` | `boolean` | yes |  |
+| `parent_kind` | `"custom" \| "contacts" \| "companies" \| "deals"` | yes |  |
+| `parent_label` | `string` | yes |  |
+| `parent_relationship_definition_id` | `string (uuid)` | yes |  |
+| `plural_noun` | `string` | yes |  |
+| `singular_noun` | `string` | yes |  |
+| `updated_at` | `string (date-time)` | yes |  |
+| `description` | `string \| null` | no |  |
+| `display_attribute_slug` | `string \| null` | no |  |
+| `icon` | `string \| null` | no |  |
+| `parent_object_id` | `string (uuid) \| null` | no |  |
+| `parent_object_slug` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.processLists.createProcessListApi({
+  body: {
+    api_slug: "example",
+    entries_label: "example",
+    parent: { kind: "custom" },
+    parent_label: "example",
+    plural_noun: "example",
+    singular_noun: "example",
+  },
+});
+```
+
+---
+
+<a id="op-createprocesslistentryapi"></a>
+
+### `g8.api.processLists.createProcessListEntryApi(input)`
+
+**Create Process List Entry Api**
+
+- HTTP: `POST /api/v1/process-lists/{slug}/entries`
+- operationId: `create_process_list_entry_api_process_lists__slug__entries_post` (also callable as `g8.api.call("create_process_list_entry_api_process_lists__slug__entries_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+
+Create one entry and link it to its parent, atomically. Repeated parents are allowed. A retry with the same
+``idempotency_key`` from the same credential within 24 hours returns the original entry (``replayed: true``);
+reusing the key for a different request is a 409. The entry's own id differs from the parent's.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.slug` | `string` | yes |  |
+| `body` | `ProcessListEntryCreate` | yes | Request body; fields below. |
+
+Body fields (`ProcessListEntryCreate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.parent_record_id` | `string` | yes | min length 1, max length 255 |
+| `body.expected_parent_revision` | `integer \| null` | no | > 0 |
+| `body.idempotency_key` | `string \| null` | no | min length 1, max length 255 |
+| `body.values` | `Record<string, unknown>` | no |  |
+
+**Returns** `ApiResponse_ProcessListEntryResponse_`: the envelope `{ data: ProcessListEntryResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ProcessListEntryResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `parent` | `ProcessListParentSummary` | yes |  |
+| `record` | `RecordResponse` | yes |  |
+| `relationship_id` | `string (uuid)` | yes |  |
+| `replayed` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.processLists.createProcessListEntryApi({ path: { slug: "example" }, body: { parent_record_id: "id" } });
+```
+
+---
+
+<a id="op-getprocesslistapi"></a>
+
+### `g8.api.processLists.getProcessListApi(input)`
+
+**Get Process List Api**
+
+- HTTP: `GET /api/v1/process-lists/{slug}`
+- operationId: `get_process_list_api_process_lists__slug__get` (also callable as `g8.api.call("get_process_list_api_process_lists__slug__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+
+Read one process list, including its parent binding.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.slug` | `string` | yes |  |
+
+**Returns** `ApiResponse_ProcessListResponse_`: the envelope `{ data: ProcessListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ProcessListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_slug` | `string` | yes |  |
+| `created_at` | `string (date-time)` | yes |  |
+| `entries_label` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `is_archived` | `boolean` | yes |  |
+| `parent_kind` | `"custom" \| "contacts" \| "companies" \| "deals"` | yes |  |
+| `parent_label` | `string` | yes |  |
+| `parent_relationship_definition_id` | `string (uuid)` | yes |  |
+| `plural_noun` | `string` | yes |  |
+| `singular_noun` | `string` | yes |  |
+| `updated_at` | `string (date-time)` | yes |  |
+| `description` | `string \| null` | no |  |
+| `display_attribute_slug` | `string \| null` | no |  |
+| `icon` | `string \| null` | no |  |
+| `parent_object_id` | `string (uuid) \| null` | no |  |
+| `parent_object_slug` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.processLists.getProcessListApi({ path: { slug: "example" } });
+```
+
+---
+
+<a id="op-listprocesslistsapi"></a>
+
+### `g8.api.processLists.listProcessListsApi(input?)`
+
+**List Process Lists Api**
+
+- HTTP: `GET /api/v1/process-lists`
+- operationId: `list_process_lists_api_process_lists_get` (also callable as `g8.api.call("list_process_lists_api_process_lists_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+
+List the process lists this credential may read. Backing objects are not part of ``GET /objects``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.include_archived` | `boolean` | no | default `false` |
+
+**Returns** `ApiResponse_ProcessListListResponse_`: the envelope `{ data: ProcessListListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ProcessListListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `process_lists` | `Array<ProcessListResponse>` | yes |  |
+| `total` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.processLists.listProcessListsApi();
+```
+
+---
+
+<a id="op-updateprocesslistapi"></a>
+
+### `g8.api.processLists.updateProcessListApi(input)`
+
+**Update Process List Api**
+
+- HTTP: `PATCH /api/v1/process-lists/{slug}`
+- operationId: `update_process_list_api_process_lists__slug__patch` (also callable as `g8.api.call("update_process_list_api_process_lists__slug__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:manage`
+
+Rename, describe or archive a list. The parent binding is identity, not a label: it is never accepted here.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.slug` | `string` | yes |  |
+| `body` | `ProcessListUpdate` | yes | Request body; fields below. |
+
+Body fields (`ProcessListUpdate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.description` | `string \| null` | no | max length 2000 |
+| `body.display_attribute_slug` | `string \| null` | no | min length 1, max length 100, pattern `^[a-z][a-z0-9_]*$` |
+| `body.icon` | `"box" \| "briefcase" \| "building" \| "calendar" \| "flag" \| "folder" \| "globe" \| "heart" \| … \| null` | no |  |
+| `body.is_archived` | `boolean \| null` | no |  |
+| `body.plural_noun` | `string \| null` | no | min length 1, max length 100 |
+| `body.singular_noun` | `string \| null` | no | min length 1, max length 100 |
+
+**Returns** `ApiResponse_ProcessListResponse_`: the envelope `{ data: ProcessListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ProcessListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_slug` | `string` | yes |  |
+| `created_at` | `string (date-time)` | yes |  |
+| `entries_label` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `is_archived` | `boolean` | yes |  |
+| `parent_kind` | `"custom" \| "contacts" \| "companies" \| "deals"` | yes |  |
+| `parent_label` | `string` | yes |  |
+| `parent_relationship_definition_id` | `string (uuid)` | yes |  |
+| `plural_noun` | `string` | yes |  |
+| `singular_noun` | `string` | yes |  |
+| `updated_at` | `string (date-time)` | yes |  |
+| `description` | `string \| null` | no |  |
+| `display_attribute_slug` | `string \| null` | no |  |
+| `icon` | `string \| null` | no |  |
+| `parent_object_id` | `string (uuid) \| null` | no |  |
+| `parent_object_slug` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.processLists.updateProcessListApi({ path: { slug: "example" }, body: {} });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-processlistparentsummary"></a>
+
+### `ProcessListParentSummary`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `kind` | `"custom" \| "contacts" \| "companies" \| "deals"` | yes |  |
+| `record_id` | `string` | yes |  |
+| `label` | `string \| null` | no |  |
+| `object_slug` | `string \| null` | no |  |
+| `revision` | `integer \| null` | no |  |
+
+<a id="type-recordresponse"></a>
+
+### `RecordResponse`
+
+Response for a record with its current attribute values.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string (date-time)` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `is_archived` | `boolean` | yes |  |
+| `object_definition_id` | `string (uuid)` | yes |  |
+| `organization_id` | `string` | yes |  |
+| `updated_at` | `string (date-time)` | yes |  |
+| `values` | `Record<string, unknown>` | yes |  |
+| `revision` | `integer` | no | default `1`, min 1 |
+
+<a id="type-relationshiptarget"></a>
+
+### `RelationshipTarget`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `kind` | `"custom" \| "contacts" \| "companies" \| "deals"` | yes |  |
+| `object_id` | `string (uuid) \| null` | no |  |