@graph8/sdk 0.13.1 → 0.15.0

package/README.md

@@ -251,11 +251,41 @@ export const CTA = () => {
 | `g8.webhooks.constructEvent(body, sig, ts, secret, opts?)` | Verify a delivery's HMAC signature and return the parsed event (throws `WebhookSignatureError`) |
 | `g8.webhooks.knownEvents` | The known event-type catalog |
 
+The unreleased CRM increment adds `crm.record.created`, `crm.record.updated`,
+`crm.record.archived`, and `crm.record.restored`. Their `data` contains
+`object_slug`, `record_id`, and `revision`, rather than private field values.
+The envelope `id` is a stable event ID; `X-Studio-Delivery-Id` identifies a
+subscription's delivery. Verify the original request bytes before processing,
+and deduplicate by the stable identifiers because delivery is at least once.
+CRM subscription creation, update, deletion and secret rotation through the API
+require explicit `webhooks:write` and `objects:read` scopes. Removing CRM events
+also requires these grants. Reading CRM subscriptions or their delivery history
+requires explicit `webhooks:read` and `objects:read` scopes; a subscription list
+containing CRM subscriptions enforces the same read grants before returning data.
+These checks refresh credentials and apply even during compatibility scope soak.
+The backend checks current credential, membership and record access again before
+sending. Native custom
+records currently follow workspace-level access; app-owned/delegated authority
+and configurable Enterprise object grants remain incomplete.
+
 ## Native custom objects
 
 Use an organization API key with explicit `objects:read` for schema/record/history
-reads, `objects:write` for create/PATCH, and `objects:delete` for archive. Unscoped
-keys receive 403. `objects:*` grants all three; grant only the operations the
+reads, `objects:write` for record create/PATCH, and `objects:delete` for record archive.
+Schema create/update/archive require `objects:manage` and current Admin access through
+a personal API key. `objects.update(slug, { is_archived: false })` restores an object.
+Object create accepts `description` and a typed `icon`. Update also accepts
+`display_attribute_slug` for an active, single-value label field. Omit presentation
+properties to preserve them or pass `null` to clear them. The current display field
+must be replaced or cleared before archiving it or making it multivalue.
+Attribute administration in the unreleased increment uses `objects.createAttribute`,
+`objects.updateAttribute`, and `objects.archiveAttribute` with the same scope and Admin requirement.
+Restore with `objects.updateAttribute(objectSlug, attributeSlug, { is_archived: false })`.
+Use `objects.listAttributes(objectSlug, { include_archived: true })` to find archived fields;
+normal discovery and record validation use active fields only. Attribute PATCH preserves
+omitted fields; `default_value: null` explicitly clears a default. Requires the matching backend.
+
+Unscoped keys receive 403. `objects:*` grants all object scopes; grant only the operations the
 integration needs.
 
 ```typescript
@@ -273,6 +303,36 @@ PATCH preserves omitted attributes. Enabled defaults apply only on create;
 unknown fields return 422 and unique-value collisions return 409. Standard
 contacts, companies, and deals continue using their existing SDK resources.
 
+### Create or update by a unique key
+
+Use an active, single-value unique attribute to match a native custom record.
+Supply its nonempty value with the fields to write. Existing matches retain
+their graph8 ID and omitted values; new records receive configured defaults.
+
+```typescript
+import { g8 } from '@graph8/sdk';
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+// Assumes invoices.reference is a unique text attribute in this workspace.
+const invoice = await g8.objects.upsertRecord('invoices', 'reference', {
+  reference: 'INV-1042',
+});
+// A conditional update fails with 409 if the record changed or no longer matches.
+await g8.objects.upsertRecord('invoices', 'reference', {
+  reference: 'INV-1042',
+}, { expectedRevision: invoice.revision });
+```
+
+The REST operation is `POST /api/v1/objects/{object_slug}/records/upsert` with
+`{ "matching_attribute": "reference", "values": { "reference": "INV-1042" } }`.
+It requires `objects:write`, returns 201 for creation or 200 for an update, and
+accepts optional `expected_revision`. MCP exposes `g8_object_record_upsert`
+with the same fields. Archived records do not match. Invalid or nonunique
+matching attributes return 422; another unique-field collision returns 409.
+Legacy values requiring a uniqueness backfill also return 409 rather than
+creating a duplicate. Repeated upserts can create additional update history;
+unique-key matching is not a promise of exactly-once side effects.
+
 ## App Platform
 
 Hosted apps do not carry a permanent org API key. Instead they **exchange** a
@@ -371,3 +431,68 @@ unique value has been reused. Validation failures leave the record archived.
 Ambiguous legacy history returns 422 with `archive_snapshot_unavailable` rather
 than guessing its prior values. Repeating a successful restore adds no revision
 or history entry.
+
+### Append or remove multivalue items
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: "YOUR_API_KEY" });
+const projectId = "your-project-record-id";
+const record = await g8.objects.getRecord("projects", projectId);
+await g8.objects.updateRecord("projects", projectId, {}, {
+  appendValues: { tags: ["priority"] },
+  removeValues: { reviewers: ["former-reviewer-id"] },
+  expectedRevision: record.revision,
+});
+```
+
+Native and app PATCH APIs use `append_values` and `remove_values`; the MCP
+`g8_object_record_update` tool accepts those same names. Each field must occur
+in exactly one of `values`, `append_values`, or `remove_values`. These operations
+require a multivalue attribute; `values` still replaces the entire supplied field.
+Append preserves existing order and adds only canonically distinct items. Remove
+deletes all matching items. The resulting values must satisfy required, unique,
+and reference constraints. Changes are atomic and read the current values under
+a record lock, so concurrent appends do not discard each other.
+
+Repeating an append can leave the values unchanged while still advancing the
+record revision and history. This is not an idempotency guarantee for events.
+Deploy the matching backend before using these optional request fields.
+
+### Record mutation history
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: "YOUR_API_KEY" });
+const firstPage = await g8.objects.changes("projects", "your-project-record-id", { limit: 50 });
+if (firstPage.next_cursor) {
+  const olderPage = await g8.objects.changes("projects", "your-project-record-id", {
+    limit: 50,
+    cursor: firstPage.next_cursor,
+  });
+  console.log(olderPage.entries);
+}
+```
+
+The matching native and app APIs expose `/objects/{object_slug}/records/{record_id}/changes`
+and `/app/objects/{object_slug}/records/{record_id}/changes`. The MCP tool is
+`g8_object_record_changes`. These additions require the matching backend deployment.
+Entries include the record revision, action, actor identity/type, source, time,
+and changed values. Presence flags distinguish a cleared field from a present null.
+An empty page means no mutation entries were recorded, not that the record never
+changed; the existing value-history endpoint remains available for older facts.
+Use the returned opaque cursor for older pages. A storage failure is an error,
+not an empty history. This interface does not establish broader object/record ACL parity.
+
+### Conditional deal updates (unreleased)
+
+Read the canonical deal record through `GET /api/v1/objects/deals/records/{id}`
+to obtain its CRM revision, then pass `expected_revision` to
+`g8.deals.update(id, { name: "Updated", expected_revision: revision })`.
+A stale edit returns HTTP 409; reload and reconcile before retrying. A successful
+conditional update returns `revision`. If tenant revision tracking is unavailable,
+the conditional write returns 503 before mutation. Omitting `expected_revision`
+retains the existing PATCH contract. The MCP `g8_update_deal` tool accepts the same
+field. Deal UI integration and deployed QA verification remain pending.