@graph8/sdk 0.13.0 → 0.13.1

package/README.md

@@ -251,6 +251,28 @@ 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 |
 
+## 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
+integration needs.
+
+```typescript
+import { g8 } from '@graph8/sdk';
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+const { data: objects } = await g8.objects.list();
+const { data: attributes } = await g8.objects.listAttributes('invoices');
+// Assumes this workspace defines an invoices object with a reference attribute.
+const invoice = await g8.objects.createRecord('invoices', { reference: 'INV-1042' });
+const history = await g8.objects.history('invoices', invoice.id);
+```
+
+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.
+
 ## App Platform
 
 Hosted apps do not carry a permanent org API key. Instead they **exchange** a
@@ -275,8 +297,8 @@ const appClient = createGraph8AppClient({
 });
 
 // Reach the existing resources with the app token via request():
-const { data: contacts } = await appClient.request<{ data: unknown[] }>(
-  '/api/v1/contacts',
+const { data: objects } = await appClient.request<{ data: unknown[] }>(
+  '/api/v1/app/objects',
   { query: { limit: 10 } },
 );
 ```
@@ -295,12 +317,12 @@ const service = createGraph8ServiceClient({
   scopes: ['objects:read', 'objects:write'],
 });
 
-const { data: rows } = await service.request<{ data: unknown[] }>('/api/v1/contacts');
+const { data: objects } = await service.request<{ data: unknown[] }>('/api/v1/app/objects');
 ```
 
-> The typed `apps` (control-plane) and `objects` (custom-object CRUD) resource
-> modules are deferred until their backend routes ship (M6-3 / M6-5). Until then,
-> reach the Developer API through the token-bound `request()` shown above.
+> App-token clients use `request()` for their consented app-owned objects.
+> The `g8.objects` resource above uses an API key for native workspace objects;
+> it does not substitute for app-token authorization.
 
 ## Auth Modes
 
@@ -315,3 +337,37 @@ Get your API key at [app.graph8.com/settings](https://app.graph8.com/settings) u
 ## License
 
 MIT
+
+
+### Conditional custom-record updates
+
+Custom-record responses expose `revision`. Pass it when saving an interactive edit:
+
+```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);
+const updated = await g8.objects.updateRecord(
+  "projects", record.id, { name: "Updated project" },
+  { expectedRevision: record.revision },
+);
+```
+
+A stale revision returns HTTP 409 with code `revision_conflict`; reload the record
+and reconcile the edit before retrying. Native and app APIs accept
+`expected_revision` in the PATCH body, and the MCP update tool accepts the same
+argument. Omitting it retains unconditional PATCH behavior. Older servers may
+omit `revision`; deploy the revision-enabled backend before relying on this
+precondition. This applies to custom-object records.
+
+
+Restore a custom record with `g8.objects.restoreRecord(objectSlug, recordId)`.
+The native API uses `POST /api/v1/objects/{objectSlug}/records/{recordId}/restore`;
+MCP exposes `g8_object_record_restore`. Restoration preserves the original ID and
+old history, validates the current schema and references, and returns 409 if a
+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.

package/dist/index.d.mts

@@ -1765,6 +1765,10 @@ interface CustomObjectAttribute {
     /** No two ACTIVE records may hold the same value. A collision returns 409. */
     is_unique: boolean;
     is_multiselect: boolean;
+    /** Apply a non-null default to omitted create fields, never PATCH. Absent on older servers. */
+    is_default_value_enabled?: boolean;
+    /** Configured default; validated like an explicit value when enabled. */
+    default_value?: unknown;
     /** Type-specific configuration, e.g. the allowed options for a `select`. */
     config: Record<string, unknown>;
 }
@@ -1780,6 +1784,8 @@ interface CustomObjectRecord {
      */
     values: Record<string, unknown>;
     is_archived: boolean;
+    /** Revision for conditional updates; absent on older servers. */
+    revision?: number;
     created_at: string | null;
     updated_at: string | null;
 }
@@ -1824,10 +1830,7 @@ interface ObjectPagination {
  * Requires an API key (server-side). On the hardened HTTP core: throws a typed
  * `G8Error` on failure and retries transient errors.
  *
- * PREVIEW AND GATED. Every endpoint returns 403 `app_not_enabled` until the
- * custom-objects surface is switched on for the platform. It is off by default,
- * so a call fails fast rather than returning an empty list that reads as "you
- * have no objects".
+ * Access requires an authenticated credential with the applicable object scope.
  *
  * HOW THIS DIFFERS FROM `g8.fields`. A FIELD adds a column to an existing
  * contact or company. A CUSTOM OBJECT is a whole new record type with its own
@@ -1840,10 +1843,16 @@ interface ObjectPagination {
  *      lose your data, and the response lists every problem at once so a payload
  *      with three mistakes takes one round trip to fix.
  *   2. `update` is a PARTIAL write. Attributes you omit are left alone; sending
- *      an explicit `null` CLEARS one. The two are deliberately different.
+ *      an explicit `null` clears an optional attribute. Required attributes
+ *      cannot be cleared with `null` or an empty multivalue list (422).
  *   3. `archive` does not destroy anything. The record leaves listings, stays
  *      readable by id, and keeps its history.
  *
+ * Record references must resolve to an active record of `config.target_object`
+ * within the same organization and app. Unavailable targets return a 422 with
+ * `invalid_reference` in the field error's `reason`, without disclosing whether
+ * a target exists outside the caller's scope.
+ *
  * Backed by:
  *   GET    /api/v1/objects
  *   GET    /api/v1/objects/{slug}
@@ -1887,12 +1896,16 @@ declare const createObjectsClient: (apiKey: string, apiUrl?: string) => {
      * Values are versioned rather than overwritten, so the previous value stays
      * readable through `history`.
      */
-    updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
+    updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>, options?: {
+        expectedRevision?: number;
+    }): Promise<CustomObjectRecord>;
     /**
      * Archive a record. It leaves listings, stays readable by id, and keeps its
      * history and associations. Nothing is destroyed.
      */
     archiveRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+    /** Restore archived values under current constraints. Conflicts leave the record archived. */
+    restoreRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
     /**
      * A record's value timeline, newest first. An entry whose `active_until` is
      * null is the value currently in force.
@@ -3809,8 +3822,11 @@ declare class G8 {
         }>;
         createRecord(objectSlug: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
         getRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
-        updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
+        updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>, options?: {
+            expectedRevision?: number;
+        }): Promise<CustomObjectRecord>;
         archiveRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+        restoreRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
         history(objectSlug: string, recordId: string, limit?: number): Promise<CustomObjectHistory>;
     };
     /** Deals and pipelines (requires API key). */

package/dist/index.d.ts

@@ -1765,6 +1765,10 @@ interface CustomObjectAttribute {
     /** No two ACTIVE records may hold the same value. A collision returns 409. */
     is_unique: boolean;
     is_multiselect: boolean;
+    /** Apply a non-null default to omitted create fields, never PATCH. Absent on older servers. */
+    is_default_value_enabled?: boolean;
+    /** Configured default; validated like an explicit value when enabled. */
+    default_value?: unknown;
     /** Type-specific configuration, e.g. the allowed options for a `select`. */
     config: Record<string, unknown>;
 }
@@ -1780,6 +1784,8 @@ interface CustomObjectRecord {
      */
     values: Record<string, unknown>;
     is_archived: boolean;
+    /** Revision for conditional updates; absent on older servers. */
+    revision?: number;
     created_at: string | null;
     updated_at: string | null;
 }
@@ -1824,10 +1830,7 @@ interface ObjectPagination {
  * Requires an API key (server-side). On the hardened HTTP core: throws a typed
  * `G8Error` on failure and retries transient errors.
  *
- * PREVIEW AND GATED. Every endpoint returns 403 `app_not_enabled` until the
- * custom-objects surface is switched on for the platform. It is off by default,
- * so a call fails fast rather than returning an empty list that reads as "you
- * have no objects".
+ * Access requires an authenticated credential with the applicable object scope.
  *
  * HOW THIS DIFFERS FROM `g8.fields`. A FIELD adds a column to an existing
  * contact or company. A CUSTOM OBJECT is a whole new record type with its own
@@ -1840,10 +1843,16 @@ interface ObjectPagination {
  *      lose your data, and the response lists every problem at once so a payload
  *      with three mistakes takes one round trip to fix.
  *   2. `update` is a PARTIAL write. Attributes you omit are left alone; sending
- *      an explicit `null` CLEARS one. The two are deliberately different.
+ *      an explicit `null` clears an optional attribute. Required attributes
+ *      cannot be cleared with `null` or an empty multivalue list (422).
  *   3. `archive` does not destroy anything. The record leaves listings, stays
  *      readable by id, and keeps its history.
  *
+ * Record references must resolve to an active record of `config.target_object`
+ * within the same organization and app. Unavailable targets return a 422 with
+ * `invalid_reference` in the field error's `reason`, without disclosing whether
+ * a target exists outside the caller's scope.
+ *
  * Backed by:
  *   GET    /api/v1/objects
  *   GET    /api/v1/objects/{slug}
@@ -1887,12 +1896,16 @@ declare const createObjectsClient: (apiKey: string, apiUrl?: string) => {
      * Values are versioned rather than overwritten, so the previous value stays
      * readable through `history`.
      */
-    updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
+    updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>, options?: {
+        expectedRevision?: number;
+    }): Promise<CustomObjectRecord>;
     /**
      * Archive a record. It leaves listings, stays readable by id, and keeps its
      * history and associations. Nothing is destroyed.
      */
     archiveRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+    /** Restore archived values under current constraints. Conflicts leave the record archived. */
+    restoreRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
     /**
      * A record's value timeline, newest first. An entry whose `active_until` is
      * null is the value currently in force.
@@ -3809,8 +3822,11 @@ declare class G8 {
         }>;
         createRecord(objectSlug: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
         getRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
-        updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
+        updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>, options?: {
+            expectedRevision?: number;
+        }): Promise<CustomObjectRecord>;
         archiveRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+        restoreRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
         history(objectSlug: string, recordId: string, limit?: number): Promise<CustomObjectHistory>;
     };
     /** Deals and pipelines (requires API key). */

package/dist/index.js

@@ -1366,12 +1366,12 @@ var createObjectsClient = (apiKey, apiUrl) => {
      * Values are versioned rather than overwritten, so the previous value stays
      * readable through `history`.
      */
-    async updateRecord(objectSlug, recordId, values) {
+    async updateRecord(objectSlug, recordId, values, options) {
       const resp = await request(
         baseUrl,
         `/api/v1/objects/${encode(objectSlug)}/records/${encode(recordId)}`,
         apiKey,
-        { method: "PATCH", body: { values } }
+        { method: "PATCH", body: { values, ...options?.expectedRevision === void 0 ? {} : { expected_revision: options.expectedRevision } } }
       );
       return resp.data ?? resp;
     },
@@ -1388,6 +1388,16 @@ var createObjectsClient = (apiKey, apiUrl) => {
       );
       return resp.data ?? resp;
     },
+    /** Restore archived values under current constraints. Conflicts leave the record archived. */
+    async restoreRecord(objectSlug, recordId) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/objects/${encode(objectSlug)}/records/${encode(recordId)}/restore`,
+        apiKey,
+        { method: "POST" }
+      );
+      return resp.data ?? resp;
+    },
     /**
      * A record's value timeline, newest first. An entry whose `active_until` is
      * null is the value currently in force.