@graph8/sdk 0.308.1 → 0.357.0

package/docs/api/objects.md

@@ -2,7 +2,7 @@
 
 # `g8.api.objects`: Objects
 
-41 operations (13 read, 22 write, 6 destructive).
+42 operations (14 read, 22 write, 6 destructive).
 
 18 of these also have a hand-written method (`g8.objects`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
 
@@ -63,6 +63,7 @@ Exact TypeScript types for every operation on this page, and every schema they u
 | [`updateObjectRecord`](#op-updateobjectrecord) ★ | `PATCH /api/v1/objects/{object_slug}/records/{record_id}` | write | `objects:write` | Update Object Record |
 | [`updateObjectView`](#op-updateobjectview) | `PUT /api/v1/objects/{object_slug}/views/{view_id}` | write | `objects:write` | Update Object View |
 | [`upsertObjectRecord`](#op-upsertobjectrecord) ★ | `POST /api/v1/objects/{object_slug}/records/upsert` | write | `objects:write` | Upsert Object Record |
+| [`validateFormula`](#op-validateformula) | `POST /api/v1/objects/{object_slug}/attributes/formula/validate` | read | `objects:read` | Validate Formula |
 
 ---
 
@@ -78,7 +79,8 @@ Exact TypeScript types for every operation on this page, and every schema they u
 - API-key scope: `objects:manage`
 - ★ Hand-written: [`g8.objects.archiveAttribute()`](../sdk-clients.md#g8-objects-archiveattribute)
 
-Archive a custom field, retaining its values. Restore with PATCH is_archived=false.
+Archive a custom field, retaining its values. Restore with PATCH is_archived=false. Refused (409
+`formula_dependency`) while a computed field reads it, with every dependent the credential may see.
 
 **Input**
 
@@ -134,7 +136,8 @@ const result = await g8.api.objects.archiveAttribute({ path: { object_slug: "exa
 
 PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
 
-Archive a custom object without deleting data; restore with PATCH is_archived=false.
+Archive a custom object without deleting data; restore with PATCH is_archived=false. Refused (409
+`formula_dependency`) while a computed field elsewhere reads it, naming every dependent the credential may see.
 
 **Input**
 
@@ -366,7 +369,9 @@ const result = await g8.api.objects.commitObjectCsvImport({
 
 PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
 
-Create a typed CRM field. Requires objects:manage and current Admin access.
+Create a typed CRM field. Requires objects:manage and current Admin access. A computed field is checked against
+the schema the credential may see (an admin key included): a field it cannot see or an object it cannot read is
+`unknown_field` / `unknown_relationship` (422), exactly as validate answers.
 
 **Input**
 
@@ -1940,7 +1945,8 @@ const result = await g8.api.objects.setDefaultObjectView({ path: { object_slug:
 - API-key scope: `objects:manage`
 - ★ Hand-written: [`g8.objects.updateAttribute()`](../sdk-clients.md#g8-objects-updateattribute)
 
-Edit or restore a field; omitted values remain unchanged. Type and slug are immutable.
+Edit or restore a field; omitted values remain unchanged. Type and slug are immutable. A change that would
+break a computed field is refused (409 `formula_dependency`) with every dependent the credential may see.
 
 **Input**
 
@@ -2012,7 +2018,8 @@ const result = await g8.api.objects.updateAttribute({ path: { object_slug: "exam
 
 PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
 
-Rename, archive or restore a custom object while retaining its slug and data.
+Rename, archive or restore a custom object while retaining its slug and data. Archiving is refused (409
+`formula_dependency`) while a computed field elsewhere reads it, naming every dependent the credential may see.
 
 **Input**
 
@@ -2314,6 +2321,64 @@ const result = await g8.api.objects.upsertObjectRecord({
 
 ---
 
+<a id="op-validateformula"></a>
+
+### `g8.api.objects.validateFormula(input)`
+
+**Validate Formula**
+
+- HTTP: `POST /api/v1/objects/{object_slug}/attributes/formula/validate`
+- operationId: `validate_formula_objects__object_slug__attributes_formula_validate_post` (also callable as `g8.api.call("validate_formula_objects__object_slug__attributes_formula_validate_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+
+Dry-run type-check and cycle-check of a typed formula expression, optionally evaluated on one record.
+Nothing is stored. Read-only (`objects:read`) despite the POST verb: the expression travels in the body. The
+check uses YOUR view of the schema: a field you cannot see or an object you cannot read is unknown, and a preview
+that names one is `valid: false` with `unknown_field` (200), exactly like a name that does not exist. An admin key
+is held to the same object grants: API keys never bypass them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `body` | `FormulaValidateRequest` | yes | Request body; fields below. |
+
+Body fields (`FormulaValidateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.expression` | `Record<string, unknown>` | yes | The typed JSON expression (a node tree; a rollup is a `rollup` node). |
+| `body.attribute_slug` | `string \| null` | no | Slug of the computed field being EDITED (checked against its own place in the dependency graph); omit for a new one. max length 100 |
+| `body.preview_record_id` | `string \| null` | no | Evaluate the expression against this record's current values. max length 64 |
+
+**Returns** `ApiResponse_FormulaValidateResponse_`: the envelope `{ data: FormulaValidateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`FormulaValidateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `valid` | `boolean` | yes |  |
+| `currency_code` | `string \| null` | no |  |
+| `depends_on` | `Array<Record<string, unknown>>` | no |  |
+| `errors` | `Array<Record<string, unknown>>` | no | Field-level problems (`reason` is a stable code). |
+| `preview_error` | `string \| null` | no | Why the preview record could not be evaluated (a code, never a value). |
+| `preview_rollups` | `Array<PreviewRollup>` | no | With a preview record: one entry per rollup in the expression, counted over the records the caller may read. |
+| `preview_value` | `unknown` | no |  |
+| `referenced_object_slugs` | `Array<string>` | no |  |
+| `result_type` | `string \| null` | no | number, currency, text, checkbox, date or timestamp. |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.validateFormula({ path: { object_slug: "example" }, body: { expression: {} } });
+```
+
+---
+
 ## Referenced types
 
 Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
@@ -2327,6 +2392,7 @@ Configuration for specific attribute types.
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `currency_code` | `string \| null` | no |  |
+| `formula` | `FormulaInput \| null` | no |  |
 | `max_value` | `integer \| null` | no |  |
 | `options` | `Array<Record<string, unknown>> \| null` | no |  |
 | `referenced_object` | `string \| null` | no |  |
@@ -2406,6 +2472,17 @@ Column mapping (CSV header -> field slug) and match mode. May be incomplete whil
 | `matching_attribute` | `string \| null` | no | max length 100 |
 | `mode` | `"create" \| "upsert"` | no | default `"create"` |
 
+<a id="type-previewrollup"></a>
+
+### `PreviewRollup`
+
+How many linked records one rollup of a previewed expression counted.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `matched_count` | `integer` | yes | Linked records the rollup counted for the preview record (the ones its filters keep). |
+| `node_path` | `string` | yes | Where the rollup sits in the expression: `$` is the root, `$.left`, `$.args[1]`, `$.then_branch`. |
+
 <a id="type-recordbulkupdatefailure"></a>
 
 ### `RecordBulkUpdateFailure`
@@ -2471,7 +2548,7 @@ One generation of one attribute's value. Values are TEMPORAL rather than mutable
 
 | Field | Type | Required | Description |
 |---|---|---|---|
-| `action` | `"created" \| "updated" \| "archived" \| "restored"` | yes |  |
+| `action` | `"created" \| "updated" \| "archived" \| "restored" \| "recalculated"` | yes |  |
 | `actor_id` | `string \| null` | yes |  |
 | `actor_type` | `"user" \| "api" \| "app" \| "integration" \| "system"` | yes |  |
 | `changes` | `Record<string, RecordMutationValueChange>` | yes |  |

package/docs/api/processLists.d.ts

@@ -0,0 +1,247 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.processLists` (Process Lists): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"archive_process_list_api_process_lists__slug__delete">;
+ *
+ * Reference with examples: processLists.md
+ */
+/* eslint-disable */
+
+/** `g8.api.processLists.<member>` -> the operationId it calls. */
+export interface ProcessListsMembers {
+  archiveProcessListApi: "archive_process_list_api_process_lists__slug__delete";
+  createProcessListApi: "create_process_list_api_process_lists_post";
+  createProcessListEntryApi: "create_process_list_entry_api_process_lists__slug__entries_post";
+  getProcessListApi: "get_process_list_api_process_lists__slug__get";
+  listProcessListsApi: "list_process_lists_api_process_lists_get";
+  updateProcessListApi: "update_process_list_api_process_lists__slug__patch";
+}
+
+/** Input and output of every `g8.api.processLists` operation, keyed by operationId. */
+export interface ProcessListsOperations {
+  /**
+   * DELETE /process-lists/{slug}
+   * Archive Process List Api
+   * tier: destructive · scope: objects:manage
+   */
+  archive_process_list_api_process_lists__slug__delete: {
+    input: {
+    path: {
+      slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ProcessListResponse_;
+  };
+  /**
+   * POST /process-lists
+   * Create Process List Api
+   * tier: write · scope: objects:manage
+   */
+  create_process_list_api_process_lists_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ProcessListCreate;
+  };
+    output: ApiResponse_ProcessListResponse_;
+  };
+  /**
+   * POST /process-lists/{slug}/entries
+   * Create Process List Entry Api
+   * tier: write · scope: objects:write
+   */
+  create_process_list_entry_api_process_lists__slug__entries_post: {
+    input: {
+    path: {
+      slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ProcessListEntryCreate;
+  };
+    output: ApiResponse_ProcessListEntryResponse_;
+  };
+  /**
+   * GET /process-lists/{slug}
+   * Get Process List Api
+   * tier: read · scope: objects:read
+   */
+  get_process_list_api_process_lists__slug__get: {
+    input: {
+    path: {
+      slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ProcessListResponse_;
+  };
+  /**
+   * GET /process-lists
+   * List Process Lists Api
+   * tier: read · scope: objects:read
+   */
+  list_process_lists_api_process_lists_get: {
+    input: {
+    query?: {
+      include_archived?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ProcessListListResponse_;
+  };
+  /**
+   * PATCH /process-lists/{slug}
+   * Update Process List Api
+   * tier: write · scope: objects:manage
+   */
+  update_process_list_api_process_lists__slug__patch: {
+    input: {
+    path: {
+      slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ProcessListUpdate;
+  };
+    output: ApiResponse_ProcessListResponse_;
+  };
+}
+
+// 13 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_ProcessListEntryResponse_ {
+  data: ProcessListEntryResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ProcessListListResponse_ {
+  data: ProcessListListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ProcessListResponse_ {
+  data: ProcessListResponse;
+  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;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
+}
+
+export interface ProcessListCreate {
+  api_slug: string;
+  description?: string | null;
+  entries_label: string;
+  icon?: ("box" | "briefcase" | "building" | "calendar" | "flag" | "folder" | "globe" | "heart" | "layers" | "package" | "target" | "users") | null;
+  parent: RelationshipTarget;
+  parent_label: string;
+  plural_noun: string;
+  singular_noun: string;
+}
+
+/**
+ * Create one entry (a record of the list's object) and link it to its parent, atomically.
+ *
+ * The parent KIND is not repeated: the list's own relationship definition fixes it.
+ */
+export interface ProcessListEntryCreate {
+  expected_parent_revision?: number | null;
+  idempotency_key?: string | null;
+  parent_record_id: string;
+  values?: Record<string, unknown>;
+}
+
+export interface ProcessListEntryResponse {
+  parent: ProcessListParentSummary;
+  record: RecordResponse;
+  relationship_id: string;
+  replayed?: boolean;
+}
+
+export interface ProcessListListResponse {
+  process_lists: Array<ProcessListResponse>;
+  total: number;
+}
+
+export interface ProcessListParentSummary {
+  kind: "custom" | "contacts" | "companies" | "deals";
+  label?: string | null;
+  object_slug?: string | null;
+  record_id: string;
+  revision?: number | null;
+}
+
+export interface ProcessListResponse {
+  api_slug: string;
+  created_at: string;
+  description?: string | null;
+  display_attribute_slug?: string | null;
+  entries_label: string;
+  icon?: string | null;
+  id: string;
+  is_archived: boolean;
+  parent_kind: "custom" | "contacts" | "companies" | "deals";
+  parent_label: string;
+  parent_object_id?: string | null;
+  parent_object_slug?: string | null;
+  parent_relationship_definition_id: string;
+  plural_noun: string;
+  singular_noun: string;
+  updated_at: string;
+}
+
+/** Rename, describe or archive a list. The parent binding is never accepted here. */
+export interface ProcessListUpdate {
+  description?: string | null;
+  display_attribute_slug?: string | null;
+  icon?: ("box" | "briefcase" | "building" | "calendar" | "flag" | "folder" | "globe" | "heart" | "layers" | "package" | "target" | "users") | null;
+  is_archived?: boolean | null;
+  plural_noun?: string | null;
+  singular_noun?: string | null;
+}
+
+/** Response for a record with its current attribute values. */
+export interface RecordResponse {
+  created_at: string;
+  id: string;
+  is_archived: boolean;
+  object_definition_id: string;
+  organization_id: string;
+  revision?: number;
+  updated_at: string;
+  values: Record<string, unknown>;
+}
+
+export interface RelationshipTarget {
+  kind: "custom" | "contacts" | "companies" | "deals";
+  object_id?: string | null;
+}