@graph8/sdk 0.302.0 → 0.303.0

package/docs/api/objects.md

@@ -2,7 +2,7 @@
 
 # `g8.api.objects`: Objects
 
-18 operations (7 read, 8 write, 3 destructive).
+24 operations (9 read, 11 write, 4 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).
 
@@ -25,16 +25,22 @@ Exact TypeScript types for every operation on this page, and every schema they u
 | [`archiveAttribute`](#op-archiveattribute) ★ | `DELETE /api/v1/objects/{object_slug}/attributes/{attr_slug}` | destructive | `objects:manage` | Archive Attribute |
 | [`archiveObject`](#op-archiveobject) ★ | `DELETE /api/v1/objects/{object_slug}` | destructive | `objects:manage` | Archive Object |
 | [`archiveObjectRecord`](#op-archiveobjectrecord) ★ | `DELETE /api/v1/objects/{object_slug}/records/{record_id}` | destructive | `objects:delete` | Archive Object Record |
+| [`bulkUpdateObjectRecords`](#op-bulkupdateobjectrecords) | `PATCH /api/v1/objects/{object_slug}/records/bulk` | write | `objects:write` | Bulk Update Object Records |
 | [`createAttribute`](#op-createattribute) ★ | `POST /api/v1/objects/{object_slug}/attributes` | write | `objects:manage` | Create Attribute |
 | [`createObject`](#op-createobject) ★ | `POST /api/v1/objects` | write | `objects:manage` | Create Object |
 | [`createObjectRecord`](#op-createobjectrecord) ★ | `POST /api/v1/objects/{object_slug}/records` | write | `objects:write` | Create Object Record |
+| [`createObjectRelationship`](#op-createobjectrelationship) | `POST /api/v1/objects/{object_slug}/records/{record_id}/relationships` | write | `objects:write` | Create Object Relationship |
+| [`deleteObjectRelationship`](#op-deleteobjectrelationship) | `DELETE /api/v1/objects/{object_slug}/records/{record_id}/relationships/{relationship_id}` | destructive | `objects:write` | Delete Object Relationship |
 | [`getObject`](#op-getobject) ★ | `GET /api/v1/objects/{object_slug}` | read | `objects:read` | Get Object |
 | [`getObjectRecord`](#op-getobjectrecord) ★ | `GET /api/v1/objects/{object_slug}/records/{record_id}` | read | `objects:read` | Get Object Record |
 | [`getObjectRecordChanges`](#op-getobjectrecordchanges) ★ | `GET /api/v1/objects/{object_slug}/records/{record_id}/changes` | read | `objects:read` | Get Object Record Changes |
 | [`getObjectRecordHistory`](#op-getobjectrecordhistory) ★ | `GET /api/v1/objects/{object_slug}/records/{record_id}/history` | read | `objects:read` | Get Object Record History |
+| [`getObjectRelationshipDefinitions`](#op-getobjectrelationshipdefinitions) | `GET /api/v1/objects/{object_slug}/relationships` | read | `objects:read` | Get Object Relationship Definitions |
+| [`getObjectRelationships`](#op-getobjectrelationships) | `GET /api/v1/objects/{object_slug}/records/{record_id}/relationships` | read | `objects:read` | Get Object Relationships |
 | [`listObjectAttributes`](#op-listobjectattributes) ★ | `GET /api/v1/objects/{object_slug}/attributes` | read | `objects:read` | List Object Attributes |
 | [`listObjectRecords`](#op-listobjectrecords) ★ | `GET /api/v1/objects/{object_slug}/records` | read | `objects:read` | List Object Records |
 | [`listObjects`](#op-listobjects) ★ | `GET /api/v1/objects` | read | `objects:read` | List Objects |
+| [`mergeObjectRecords`](#op-mergeobjectrecords) | `POST /api/v1/objects/{object_slug}/records/merge` | write | `objects:write` | Merge Object Records |
 | [`restoreObjectRecord`](#op-restoreobjectrecord) ★ | `POST /api/v1/objects/{object_slug}/records/{record_id}/restore` | write | `objects:write` | Restore Object Record |
 | [`updateAttribute`](#op-updateattribute) ★ | `PATCH /api/v1/objects/{object_slug}/attributes/{attr_slug}` | write | `objects:manage` | Update Attribute |
 | [`updateObject`](#op-updateobject) ★ | `PATCH /api/v1/objects/{object_slug}` | write | `objects:manage` | Update Object |
@@ -196,6 +202,63 @@ const result = await g8.api.objects.archiveObjectRecord({ path: { object_slug: "
 
 ---
 
+<a id="op-bulkupdateobjectrecords"></a>
+
+### `g8.api.objects.bulkUpdateObjectRecords(input)`
+
+**Bulk Update Object Records**
+
+- HTTP: `PATCH /api/v1/objects/{object_slug}/records/bulk`
+- operationId: `bulk_update_object_records_objects__object_slug__records_bulk_patch` (also callable as `g8.api.call("bulk_update_object_records_objects__object_slug__records_bulk_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+
+Apply the same values to every record in an explicit or filtered scope.
+
+Registered before ``/{object_slug}/records/{record_id}``: routes match by
+path shape, so "bulk" would otherwise bind to ``{record_id}``. Needs
+objects:read as well as objects:write (a filtered scope echoes the ids that
+match caller-chosen predicates). Delegates to the Studio function, so the
+server-side filter resolution, the 500-row cursor, the per-row savepoints
+and the per-org ``records_core`` switch (404 while off) are identical.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `body` | `RecordBulkUpdate` | yes | Request body; fields below. |
+
+Body fields (`RecordBulkUpdate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.after_record_id` | `string (uuid) \| null` | no |  |
+| `body.filters` | `Array<RecordFilter> \| null` | no | max items 10 |
+| `body.record_ids` | `Array<string (uuid)> \| null` | no | max items 500 |
+| `body.values` | `Record<string, unknown>` | no |  |
+
+**Returns** `ApiResponse_RecordBulkUpdateResponse_`: the envelope `{ data: RecordBulkUpdateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RecordBulkUpdateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `failed` | `Array<RecordBulkUpdateFailure>` | yes |  |
+| `succeeded` | `Array<string (uuid)>` | yes |  |
+| `next_after_record_id` | `string (uuid) \| null` | no |  |
+| `truncated` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.bulkUpdateObjectRecords({ path: { object_slug: "example" }, body: {} });
+```
+
+---
+
 <a id="op-createattribute"></a>
 
 ### `g8.api.objects.createAttribute(input)`
@@ -388,6 +451,144 @@ const result = await g8.api.objects.createObjectRecord({ path: { object_slug: "e
 
 ---
 
+<a id="op-createobjectrelationship"></a>
+
+### `g8.api.objects.createObjectRelationship(input)`
+
+**Create Object Relationship**
+
+- HTTP: `POST /api/v1/objects/{object_slug}/records/{record_id}/relationships`
+- operationId: `create_object_relationship_objects__object_slug__records__record_id__relationships_post` (also callable as `g8.api.call("create_object_relationship_objects__object_slug__records__record_id__relationships_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+
+Link from a custom or canonical native record. The request's expected revisions are
+relative to the route's record; the response is always in the definition's canonical
+direction (source = the custom record, target = the native or custom target).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.record_id` | `string` | yes |  |
+| `body` | `RelationshipCreate` | yes | Request body; fields below. |
+
+Body fields (`RelationshipCreate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.definition_id` | `string (uuid)` | yes |  |
+| `body.expected_definition_revision` | `integer` | yes | > 0 |
+| `body.expected_source_revision` | `integer` | yes | > 0 |
+| `body.expected_target_revision` | `integer` | yes | > 0 |
+| `body.target_record_id` | `string` | yes | min length 1, max length 255 |
+
+**Returns** `ApiResponse_RelationshipResponse_`: the envelope `{ data: RelationshipResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RelationshipResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `definition_id` | `string (uuid)` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `source_kind` | `string` | yes |  |
+| `source_record_id` | `string` | yes |  |
+| `source_revision` | `integer` | yes |  |
+| `target_kind` | `string` | yes |  |
+| `target_record_id` | `string` | yes |  |
+| `target_revision` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.createObjectRelationship({
+  path: { object_slug: "example", record_id: "id" },
+  body: {
+    definition_id: "00000000-0000-0000-0000-000000000000",
+    expected_definition_revision: 1,
+    expected_source_revision: 1,
+    expected_target_revision: 1,
+    target_record_id: "id",
+  },
+});
+```
+
+---
+
+<a id="op-deleteobjectrelationship"></a>
+
+### `g8.api.objects.deleteObjectRelationship(input)`
+
+**Delete Object Relationship**
+
+- HTTP: `DELETE /api/v1/objects/{object_slug}/records/{record_id}/relationships/{relationship_id}`
+- operationId: `delete_object_relationship_objects__object_slug__records__record_id__relationships__relationship_id__delete` (also callable as `g8.api.call("delete_object_relationship_objects__object_slug__records__record_id__relationships__relationship_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `objects:write`
+
+Unlink only the edge; both records stay. All three revisions are required.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.record_id` | `string` | yes |  |
+| `path.relationship_id` | `string (uuid)` | yes |  |
+| `body` | `RelationshipCreate` | yes | Request body; fields below. |
+
+Body fields (`RelationshipCreate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.definition_id` | `string (uuid)` | yes |  |
+| `body.expected_definition_revision` | `integer` | yes | > 0 |
+| `body.expected_source_revision` | `integer` | yes | > 0 |
+| `body.expected_target_revision` | `integer` | yes | > 0 |
+| `body.target_record_id` | `string` | yes | min length 1, max length 255 |
+
+**Returns** `ApiResponse_RelationshipResponse_`: the envelope `{ data: RelationshipResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RelationshipResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `definition_id` | `string (uuid)` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `source_kind` | `string` | yes |  |
+| `source_record_id` | `string` | yes |  |
+| `source_revision` | `integer` | yes |  |
+| `target_kind` | `string` | yes |  |
+| `target_record_id` | `string` | yes |  |
+| `target_revision` | `integer` | yes |  |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.objects.deleteObjectRelationship({
+  path: {
+    object_slug: "example",
+    record_id: "id",
+    relationship_id: "00000000-0000-0000-0000-000000000000",
+  },
+  body: {
+    definition_id: "00000000-0000-0000-0000-000000000000",
+    expected_definition_revision: 1,
+    expected_source_revision: 1,
+    expected_target_revision: 1,
+    target_record_id: "id",
+  },
+});
+```
+
+---
+
 <a id="op-getobject"></a>
 
 ### `g8.api.objects.getObject(input)`
@@ -585,6 +786,89 @@ const result = await g8.api.objects.getObjectRecordHistory({ path: { object_slug
 
 ---
 
+<a id="op-getobjectrelationshipdefinitions"></a>
+
+### `g8.api.objects.getObjectRelationshipDefinitions(input)`
+
+**Get Object Relationship Definitions**
+
+- HTTP: `GET /api/v1/objects/{object_slug}/relationships`
+- operationId: `get_object_relationship_definitions_objects__object_slug__relationships_get` (also callable as `g8.api.call("get_object_relationship_definitions_objects__object_slug__relationships_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+
+Definitions involving a custom or native object, narrowed to the credential's native read scopes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `query.limit` | `integer` | no | default `50` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_RelationshipDefinitionListResponse_`: the envelope `{ data: RelationshipDefinitionListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RelationshipDefinitionListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `relationships` | `Array<RelationshipDefinitionResponse>` | yes |  |
+| `total` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.getObjectRelationshipDefinitions({ path: { object_slug: "example" } });
+```
+
+---
+
+<a id="op-getobjectrelationships"></a>
+
+### `g8.api.objects.getObjectRelationships(input)`
+
+**Get Object Relationships**
+
+- HTTP: `GET /api/v1/objects/{object_slug}/records/{record_id}/relationships`
+- operationId: `get_object_relationships_objects__object_slug__records__record_id__relationships_get` (also callable as `g8.api.call("get_object_relationships_objects__object_slug__records__record_id__relationships_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+
+Read authorized links of a custom or native record, both endpoints filtered
+before pagination. Needs objects:read plus the native kinds' explicit read
+scopes; an absent and an inaccessible record share a neutral 404.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.record_id` | `string` | yes |  |
+| `query.limit` | `integer` | no | default `50` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_RecordRelationshipsResponse_`: the envelope `{ data: RecordRelationshipsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RecordRelationshipsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `next_offset` | `integer \| null` | yes | Next visible page offset; null at the end |
+| `relationships` | `Array<RelatedRecordEdge>` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.getObjectRelationships({ path: { object_slug: "example", record_id: "id" } });
+```
+
+---
+
 <a id="op-listobjectattributes"></a>
 
 ### `g8.api.objects.listObjectAttributes(input)`
@@ -741,6 +1025,67 @@ const result = await g8.api.objects.listObjects();
 
 ---
 
+<a id="op-mergeobjectrecords"></a>
+
+### `g8.api.objects.mergeObjectRecords(input)`
+
+**Merge Object Records**
+
+- HTTP: `POST /api/v1/objects/{object_slug}/records/merge`
+- operationId: `merge_object_records_objects__object_slug__records_merge_post` (also callable as `g8.api.call("merge_object_records_objects__object_slug__records_merge_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+
+Eligible merge: resolve fields, archive the secondary (its values closed
+first), repoint links and associations onto the primary, write the primary.
+Needs objects:write AND objects:delete — both scope dependencies are real
+parameters so each carries its own ``required_api_key_scope`` marker.
+Delegates to the Studio function (same blockers, field resolution, cascade,
+far-end access rule and ``records_core`` switch).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `body` | `RecordMergeRequest` | yes | Request body; fields below. |
+
+Body fields (`RecordMergeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.primary_record_id` | `string (uuid)` | yes |  |
+| `body.secondary_record_id` | `string (uuid)` | yes |  |
+| `body.expected_primary_revision` | `integer \| null` | no | min 1 |
+| `body.expected_secondary_revision` | `integer \| null` | no | min 1 |
+| `body.field_overrides` | `Array<RecordMergeFieldOverride>` | no |  |
+
+**Returns** `ApiResponse_RecordMergeResponse_`: the envelope `{ data: RecordMergeResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RecordMergeResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `cascade` | `RecordMergeCascade` | yes |  |
+| `merge_history_id` | `string (uuid)` | yes |  |
+| `record` | `RecordResponse` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.mergeObjectRecords({
+  path: { object_slug: "example" },
+  body: {
+    primary_record_id: "00000000-0000-0000-0000-000000000000",
+    secondary_record_id: "00000000-0000-0000-0000-000000000000",
+  },
+});
+```
+
+---
+
 <a id="op-restoreobjectrecord"></a>
 
 ### `g8.api.objects.restoreObjectRecord(input)`
@@ -1065,6 +1410,27 @@ Valid attribute types for the Custom Objects type system.
 
 Type: `"text" | "number" | "currency" | "date" | "timestamp" | "checkbox" | "select" | "status" | …`.
 
+<a id="type-recordbulkupdatefailure"></a>
+
+### `RecordBulkUpdateFailure`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `error` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+
+<a id="type-recordfilter"></a>
+
+### `RecordFilter`
+
+Filter parameters for listing records.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `attribute_slug` | `string` | yes |  |
+| `operator` | `"eq" \| "ne" \| "gt" \| "gte" \| "lt" \| "lte" \| "contains" \| "starts_with" \| …` | yes |  |
+| `value` | `unknown \| null` | no |  |
+
 <a id="type-recordhistoryentry"></a>
 
 ### `RecordHistoryEntry`
@@ -1079,6 +1445,26 @@ One generation of one attribute's value. Values are TEMPORAL rather than mutable
 | `actor_id` | `string \| null` | no | Opaque id of whoever set it. |
 | `value` | `unknown` | no | The value held during this generation. |
 
+<a id="type-recordmergecascade"></a>
+
+### `RecordMergeCascade`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `associations_deleted` | `integer` | yes |  |
+| `associations_repointed` | `integer` | yes |  |
+| `relationships_deleted` | `integer` | yes |  |
+| `relationships_repointed` | `integer` | yes |  |
+
+<a id="type-recordmergefieldoverride"></a>
+
+### `RecordMergeFieldOverride`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `attribute_slug` | `string` | yes |  |
+| `winner` | `"primary" \| "secondary"` | yes |  |
+
 <a id="type-recordmutationentry"></a>
 
 ### `RecordMutationEntry`
@@ -1096,3 +1482,62 @@ One generation of one attribute's value. Values are TEMPORAL rather than mutable
 | `source` | `string` | yes |  |
 | `was_archived` | `boolean` | yes |  |
 | `app_id` | `string \| 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-relatedrecordedge"></a>
+
+### `RelatedRecordEdge`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `can_unlink` | `boolean` | yes |  |
+| `definition_id` | `string (uuid)` | yes |  |
+| `definition_revision` | `integer` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `relationship_label` | `string` | yes |  |
+| `source_kind` | `"custom" \| "contacts" \| "companies" \| "deals"` | yes |  |
+| `source_label` | `string \| null` | yes |  |
+| `source_object_slug` | `string` | yes |  |
+| `source_record_id` | `string` | yes |  |
+| `source_revision` | `integer` | yes |  |
+| `target_kind` | `"custom" \| "contacts" \| "companies" \| "deals"` | yes |  |
+| `target_label` | `string \| null` | yes |  |
+| `target_object_slug` | `string` | yes |  |
+| `target_record_id` | `string` | yes |  |
+| `target_revision` | `integer` | yes |  |
+
+<a id="type-relationshipdefinitionresponse"></a>
+
+### `RelationshipDefinitionResponse`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `api_slug` | `string` | yes |  |
+| `created_at` | `string (date-time)` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `is_archived` | `boolean` | yes |  |
+| `revision` | `integer` | yes |  |
+| `source_kind` | `string` | yes |  |
+| `source_label` | `string` | yes |  |
+| `source_many` | `boolean` | yes |  |
+| `source_object_definition_id` | `string (uuid) \| null` | yes |  |
+| `target_kind` | `string` | yes |  |
+| `target_label` | `string` | yes |  |
+| `target_many` | `boolean` | yes |  |
+| `target_object_definition_id` | `string (uuid) \| null` | yes |  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graph8/sdk",
-  "version": "0.302.0",
+  "version": "0.303.0",
   "description": "graph8 SDK - CRM, enrichment, sequences, campaigns, and tracking for B2B",
   "license": "MIT",
   "author": "graph8 <support@graph8.com> (https://graph8.com)",