@graph8/sdk 0.308.1 → 0.357.0

package/blocks/nurture/components/nurture-stats.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+/**
+ * NurtureStats: where a nurture stands and how it is performing.
+ *
+ * SDK operations, in order:
+ *   1. getNurture (GET /nurtures/{id})                                                    read
+ *   2. listLists (GET /lists)                                                              read   (audience size)
+ *   3. getSequencePerformanceById (GET /analytics/outbound/sequence-performance/{id}?days) read   (contacts, emails sent, replies, meetings)
+ * There is no nurture-specific analytics endpoint. A nurture is a sequence row, so the outbound sequence report is
+ * asked for it; if the report has nothing for it (cached for ~5 minutes, or not yet sending) the panel says so
+ * instead of showing zeros. Per-step funnels are not exposed by the API.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { isNurtureMissing, isNurtureOff, percentOf, statusOf } from "../lib/nurture-types";
+import type { ListOption, Nurture, NurturePerformance } from "../lib/nurture-types";
+
+export interface NurtureStatsProps {
+  nurtureId: string;
+  /** Window of the report in days. Default 30. */
+  days?: number;
+}
+
+function Tile({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="rounded-md border p-3">
+      <p className="text-muted-foreground text-xs">{label}</p>
+      <p className="text-xl font-semibold">{value}</p>
+    </div>
+  );
+}
+
+export function NurtureStats({ nurtureId, days = 30 }: NurtureStatsProps) {
+  const [windowDays, setWindowDays] = useState(days);
+  const nurture = useG8Query((signal) => g8Get<Nurture>(`/nurtures/${encodeURIComponent(nurtureId)}`, {}, { signal }).then((r) => r.data), [nurtureId]);
+  const lists = useG8Query((signal) => g8Get<ListOption[]>("/lists", { limit: 200 }, { signal }).then((r) => r.data ?? []), []);
+  const perf = useG8Query(
+    (signal) => g8Get<{ data?: NurturePerformance }>(`/analytics/outbound/sequence-performance/${encodeURIComponent(nurtureId)}`, { days: windowDays }, { signal }).then((r) => (r.data?.data ?? (r.data as NurturePerformance | undefined)) ?? null),
+    [nurtureId, windowDays],
+  );
+
+  if (isNurtureOff(nurture.error)) return <EmptyState title="Nurture is not enabled" description="Nurture is behind a feature flag for this workspace." />;
+  if (isNurtureMissing(nurture.error)) return <EmptyState title="This nurture no longer exists" description="It may have been deleted, or it is not yours to see. Pick another nurture." />;
+  if (nurture.error) return <ApiError error={nurture.error} title="Could not load the nurture" onRetry={() => void nurture.refetch()} />;
+  if (!nurture.data) return <Skeleton className="h-32 w-full" aria-busy="true" />;
+  const audience = (lists.data ?? []).find((l) => l.id === nurture.data?.associated_list_id);
+  const p = perf.data;
+  const hasNumbers = Boolean(p && (p.contacts_total || p.emails_sent));
+  return (
+    <Card>
+      <CardHeader><CardTitle>{nurture.data.name} <span className="text-muted-foreground text-sm font-normal">{statusOf(nurture.data)}</span></CardTitle></CardHeader>
+      <CardContent className="grid gap-4">
+        <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+          <Tile label="Audience" value={audience ? (audience.contact_count ?? 0).toLocaleString() : "No list"} />
+          <Tile label="Emails" value={String(nurture.data.steps?.length ?? "n/a")} />
+          <Tile label="Stops on reply" value={nurture.data.finish_on_reply === false ? "No" : "Yes"} />
+          <Tile label="Opt-out line" value={nurture.data.include_unsubscribe_cta === false ? "No" : "Yes"} />
+        </div>
+        <div className="flex items-center gap-2" role="group" aria-label="Report window">
+          {[7, 30, 90].map((d) => <Button key={d} size="sm" variant={windowDays === d ? "secondary" : "ghost"} onClick={() => setWindowDays(d)}>{d} days</Button>)}
+        </div>
+        {perf.error ? <p className="text-muted-foreground text-sm">Performance numbers are not available for this nurture yet.</p> : perf.loading && !perf.data ? <Skeleton className="h-20 w-full" /> : !hasNumbers ? (
+          <p className="text-muted-foreground text-sm">No sends in the last {windowDays} days. Numbers appear after the first emails go out (the report refreshes every few minutes).</p>
+        ) : (
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+            <Tile label="Contacts" value={(p?.contacts_total ?? 0).toLocaleString()} />
+            <Tile label="Emails sent" value={(p?.emails_sent ?? 0).toLocaleString()} />
+            <Tile label="Replies" value={`${(p?.emails_replied ?? 0).toLocaleString()} (${percentOf(p?.reply_rate)})`} />
+            <Tile label="Meetings" value={(p?.meetings_booked ?? 0).toLocaleString()} />
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/blocks/nurture/lib/nurture-types.ts

@@ -0,0 +1,109 @@
+"use client";
+
+/**
+ * Types and helpers for the nurture block.
+ *
+ * A nurture is a sequence of kind `nurture`: a series of emails to a CONSENTED audience (a list), sent from ONE
+ * pinned mailbox, stopping per contact when they reply. It is not cold outreach. There is no nurture-specific stats
+ * endpoint; status, audience size and the sequence-performance report are what the API gives.
+ */
+
+import { G8Error } from "@graph8/sdk";
+
+export interface Nurture {
+  id: string;
+  name: string;
+  status?: string;
+  is_shared?: boolean;
+  description?: string | null;
+  associated_list_id?: number | null;
+  pinned_mailbox_id?: number | null;
+  finish_on_reply?: boolean;
+  send_in_same_thread?: boolean;
+  include_unsubscribe_cta?: boolean;
+  steps?: unknown[];
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface MailboxOption {
+  id: number;
+  email: string;
+  channel_type: string;
+  status?: string;
+  is_archived?: boolean;
+}
+
+export interface ListOption {
+  id: number;
+  title: string;
+  contact_count?: number;
+}
+
+export interface StepDraft {
+  waitDays: number;
+  subject: string;
+  body: string;
+}
+
+export interface NurturePerformance {
+  contacts_total?: number;
+  emails_sent?: number;
+  emails_replied?: number;
+  meetings_booked?: number;
+  reply_rate?: number;
+}
+
+/** The nurture feature is behind a flag: the API answers 404 "Nurture is not enabled" until it is on. */
+export function isNurtureOff(error: unknown): boolean {
+  if (!(error instanceof G8Error) || error.status !== 404) return false;
+  const text = `${typeof error.detail === "string" ? error.detail : JSON.stringify(error.detail ?? "")} ${error.message}`;
+  return /not enabled/i.test(text);
+}
+
+/** A 404 that is NOT the flag: the nurture does not exist, or is not yours to see. */
+export function isNurtureMissing(error: unknown): boolean {
+  return error instanceof G8Error && error.status === 404 && !isNurtureOff(error);
+}
+
+export function statusOf(n: Pick<Nurture, "status">): string {
+  return (n.status ?? "drafted").toLowerCase();
+}
+
+export function isDrafted(n: Pick<Nurture, "status">): boolean {
+  return /^draft/.test(statusOf(n));
+}
+
+export function isLiveLike(n: Pick<Nurture, "status">): boolean {
+  return /live|running|active|waiting|scheduling/.test(statusOf(n));
+}
+
+export function isPaused(n: Pick<Nurture, "status">): boolean {
+  return /paus/.test(statusOf(n));
+}
+
+export function isFinished(n: Pick<Nurture, "status">): boolean {
+  return /complet|terminat|archiv/.test(statusOf(n));
+}
+
+/** Email steps for the create call. Step 1 has no wait; later steps wait `waitDays` (the API takes seconds). */
+export function stepsPayload(drafts: readonly StepDraft[]) {
+  return drafts.map((d, i) => ({
+    step_order: i + 1,
+    step_type: "EMAIL",
+    input_type: "MANUAL_TEMPLATE",
+    time_interval: i === 0 ? 0 : Math.max(0, Math.round(d.waitDays * 86400)),
+    step_data: { subject: d.subject.trim(), body: d.body, email_type: "plain" },
+  }));
+}
+
+/** A nurture sends from exactly one mailbox; the same mailbox is attached as its email channel. */
+export function channelPayload(mailbox: MailboxOption) {
+  return [{ channel_id: mailbox.id, channel_value: mailbox.email, channel_type: mailbox.channel_type }];
+}
+
+export function percentOf(rate: number | undefined): string {
+  if (rate == null) return "n/a";
+  const pct = rate <= 1 ? rate * 100 : rate;
+  return `${Math.round(pct * 10) / 10}%`;
+}

package/blocks/nurture/recipes/create-a-nurture.ts

@@ -0,0 +1,34 @@
+/**
+ * @title Create a drafted nurture with its emails, pinned to one mailbox
+ * @when Setting up a lifecycle series (welcome, onboarding, re-engagement) for CONSENTED contacts. A nurture is not
+ * cold outreach: it is pinned to ONE mailbox, which must already be connected in the graph8 app (Google and Microsoft
+ * sign-in cannot be done through the API). Creating it only drafts it; nothing is sent until launch.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// 1. The sender. Its id is the nurture's pinned_mailbox_id AND the id of its email channel.
+const mine = await g8.api.mailboxes.listMyMailboxes({});
+const mailbox = mine.data.mailboxes?.find((m) => !m.is_archived && m.id != null);
+if (!mailbox || mailbox.id == null) throw new Error("No mailbox connected. Connect one in the graph8 app first.");
+
+// 2. The audience: a list of people who agreed to hear from you.
+const audience = await g8.lists.create("Newsletter signups - welcome series");
+
+// 3. Create. time_interval is SECONDS before the step; step 1 sends at launch.
+const nurture = await g8.api.sequences.createNurture({
+  body: {
+    name: "Welcome series",
+    pinned_mailbox_id: mailbox.id,
+    associated_list_id: Number(audience.id),
+    finish_on_reply: true,
+    include_unsubscribe_cta: true,
+    steps: [
+      { step_order: 1, step_type: "EMAIL", input_type: "MANUAL_TEMPLATE", time_interval: 0, step_data: { subject: "Welcome", body: "Glad you are here...", email_type: "plain" } },
+      { step_order: 2, step_type: "EMAIL", input_type: "MANUAL_TEMPLATE", time_interval: 3 * 86400, step_data: { subject: "Getting started", body: "Three things to try first...", email_type: "plain" } },
+    ],
+    channels: [{ channel_id: mailbox.id, channel_value: mailbox.email, channel_type: mailbox.channel_type }],
+  },
+});
+console.log("drafted nurture", nurture.data.id);

package/blocks/nurture/recipes/enroll-contacts-and-launch.ts

@@ -0,0 +1,24 @@
+/**
+ * @title Add consented contacts to a nurture's audience and (with approval) launch it
+ * @when A contact opted in (form, signup, purchase) and should start the series. "Enrolling" is adding them to the
+ * nurture's audience list. Launching SENDS REAL EMAIL: the last call is guarded and must be approved by a person.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function enroll(nurtureId: string, contactIds: number[], approvedToLaunch = false): Promise<void> {
+  const nurture = await g8.api.sequences.getNurture({ path: { nurture_id: nurtureId } });
+  const listId = (nurture.data as { associated_list_id?: number | null }).associated_list_id;
+  if (!listId) throw new Error("Point the nurture at a list first (updateNurture associated_list_id).");
+
+  // 1. Put the contacts in the audience (write). They must have consented.
+  await g8.api.lists.addContactsToList({ path: { list_id: listId }, body: { contact_ids: contactIds } });
+
+  // 2. Launch only on an explicit yes, and only for a nurture that is still a draft.
+  if (!approvedToLaunch) {
+    console.log(`Added ${contactIds.length} contacts. Not launched: ask the owner to approve going live.`);
+    return;
+  }
+  await g8.api.sequences.launchNurture({ path: { nurture_id: nurtureId } });
+}

package/blocks/nurture/recipes/nurture-health-check.ts

@@ -0,0 +1,28 @@
+/**
+ * @title Check every nurture's status and recent results
+ * @when A daily check or a dashboard backend. The performance report is cached for about five minutes and is the
+ * outbound sequence report (a nurture is a sequence row); a nurture with no sends yet has no numbers, which is not an error.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function healthCheck(days = 30): Promise<Array<{ id: string; name: string; status: string; sent: number; replies: number }>> {
+  const page = await g8.api.sequences.listNurtures({ query: { limit: 100 } });
+  const out: Array<{ id: string; name: string; status: string; sent: number; replies: number }> = [];
+  for (const n of page.data.nurtures ?? []) {
+    if (!n.id) continue;
+    let sent = 0;
+    let replies = 0;
+    try {
+      const report = await g8.api.analytics.getSequencePerformanceById({ path: { sequence_id: n.id }, query: { days } });
+      const row = (report.data as { data?: { emails_sent?: number; emails_replied?: number } }).data;
+      sent = row?.emails_sent ?? 0;
+      replies = row?.emails_replied ?? 0;
+    } catch {
+      // no report for this nurture yet
+    }
+    out.push({ id: n.id, name: n.name ?? "", status: n.status ?? "", sent, replies });
+  }
+  return out;
+}

package/blocks/objects/README.md

@@ -0,0 +1,120 @@
+# objects: custom objects
+
+Define your own record types (an invoice, a shipment, a subscription) with typed fields, then list, create,
+edit and archive their records. `ObjectTable` and `ObjectRecordDetail` are generic: point them at ANY object
+slug, including the standard `contacts`, `companies` and `deals`. This is the HubSpot "custom objects" / Salesforce
+"custom object" screen set.
+
+## Install
+
+```
+npx @graph8/sdk add objects
+```
+
+Installs `foundation` first if it is missing. Everything lands under `g8/objects/`.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| graph8 workspace | Creating objects and fields needs `objects:manage` **and an Admin** behind the key. Records need `objects:read`, `objects:write`, `objects:delete`. | `g8.api.me.describeCurrentKey()` |
+| Your app | Add `"objects"` and `"records"` to `allowedPrefixes` in `app/api/g8/[...path]/route.ts`. | The route file lists both prefixes. |
+
+## The flow, in order
+
+1. **Define the schema** (once, an admin): render `<ObjectSchemaEditor />`.
+   `createObject` returns `{ slug, singular_noun, plural_noun }`. The `slug` is immutable and is the id every other call uses
+   (`/objects/{slug}/...`). Then `createAttribute` for each field; its `slug` is the key inside `record.values`.
+   Select and status fields need `config.options` (a list of strings); the editor takes one option per line.
+2. **List records**: `<ObjectTable objectSlug="invoices" onSelectRecord={...} />`. Columns come from `listObjectAttributes`
+   (display order), rows from `listObjectRecords`, paged with `pagination.next_cursor` ("Load more").
+3. **Create or edit a record**: `RecordFormDialog` builds one input per field. Create sends only the fields the person filled in.
+   Edit sends only the fields that **changed**, plus `expected_revision` from the record, so a concurrent edit is a `409` instead of a silent overwrite.
+4. **Open one record**: `<ObjectRecordDetail objectSlug="invoices" recordId={record.id} />` loads `getObjectRecord`, then
+   `getObjectRecordChanges` (history) and `getObjectRelationships` (links to other records).
+5. **Archive**: the only delete. The record leaves lists but stays readable by id with its history; `restoreObjectRecord` brings it back.
+   Archiving a record, a field or a whole object always goes through `ConfirmSpendDialog`.
+
+For `contacts`, `companies` and `deals`, `ObjectRecordDetail` also renders `RecordRolesPanel` (SDR / AE / CSM owner slots).
+Custom objects have no role slots.
+
+```tsx
+// app/invoices/page.tsx
+"use client";
+import { useState } from "react";
+import { ObjectTable } from "@/g8/objects/components/object-table";
+import { ObjectRecordDetail } from "@/g8/objects/components/object-record-detail";
+
+export default function Invoices() {
+  const [open, setOpen] = useState<string | null>(null);
+  return open ? (
+    <ObjectRecordDetail objectSlug="invoices" recordId={open} onBack={() => setOpen(null)} onArchived={() => setOpen(null)} />
+  ) : (
+    <ObjectTable objectSlug="invoices" onSelectRecord={(r) => setOpen(r.id)} />
+  );
+}
+```
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| Who can open `ObjectSchemaEditor` | Only signed-in admins (put it behind an admin route) | **yes** |
+| How records are deleted | Archive (hidden, readable by id, history kept). The API has no hard delete for records | no |
+| Which field titles a record | `display_attribute_slug`, else the first text field | no |
+| Page size | 50 rows per request with "Load more" | no |
+| Field types in the editor | All except `formula` (needs an expression tree: use a recipe or `validateFormula`) | no |
+
+## Things that surprise people
+
+- **Unknown fields are a 422, not ignored.** The response lists every problem at once; the dialogs show them inline.
+- **`null` clears a value** on update. Omitted fields are left alone. Required fields cannot be cleared.
+- **No server-side search** on `listObjectRecords`. `ObjectTable` filters the rows already loaded; for big objects use `upsert` recipes and your own index,.
+- **Values are plain scalars** keyed by field slug (`{ number: "INV-1", amount: 1200 }`). A multiselect field takes a list; a reference field takes a record id.
+
+## Recipes (server-side, `recipes/`)
+
+- `define-object-and-add-records.ts`: create the object, its fields and the first records.
+- `upsert-records-from-your-system.ts`: idempotent sync keyed on a unique field.
+- `update-audit-and-archive-records.ts`: cursor paging, conditional update, change history, archive and restore.
+
+## What is in the block
+
+| Component | File | What it is |
+|---|---|---|
+| `ObjectSchemaEditor` | `components/object-schema-editor.tsx` | Create objects, edit their labels, add/edit/archive fields (text, number, select, reference...). |
+| `AttributeFormDialog` | `components/attribute-form-dialog.tsx` | Dialog to add or edit one field of an object. |
+| `ObjectTable` | `components/object-table.tsx` | Records of any object as a table with search over loaded rows, load-more, create, edit and archive. |
+| `RecordFormDialog` | `components/record-form-dialog.tsx` | Dialog to create or edit one record; builds inputs from the object's fields and shows 422 field errors. |
+| `AttributeFieldInput` | `components/attribute-field-input.tsx` | One form control chosen by attribute type (text, number, date, select, checkbox...). |
+| `ObjectNotFound` | `components/object-not-found.tsx` | Tells an unreachable custom-objects API (the list call itself 404s) apart from a deleted, mistyped or inaccessible object/record. |
+| `ObjectRecordDetail` | `components/object-record-detail.tsx` | One record: values, related records, change history, edit, archive and restore. |
+| `RecordRolesPanel` | `components/record-roles-panel.tsx` | Owner slots (SDR, AE, CSM) of a contact, company or deal: view, assign, clear. |
+| `useObjectSchema` (hook) | `hooks/use-object-schema.ts` | Load one object's definition and its active fields in display order. |
+
+## Operations
+
+Tiers: `read` and `write` need no confirmation; `destructive` always opens `ConfirmSpendDialog` first.
+
+| Operation | Method and path | Tier | Scope | Used by |
+|---|---|---|---|---|
+| `objects.listObjects` | `GET /api/v1/objects` | read | `objects:read` | ObjectSchemaEditor |
+| `objects.createObject` | `POST /api/v1/objects` | write | `objects:manage` | ObjectSchemaEditor |
+| `objects.getObject` | `GET /api/v1/objects/{object_slug}` | read | `objects:read` | ObjectSchemaEditor, ObjectTable, ObjectRecordDetail, useObjectSchema |
+| `objects.listObjectAttributes` | `GET /api/v1/objects/{object_slug}/attributes` | read | `objects:read` | ObjectSchemaEditor, ObjectTable, ObjectRecordDetail, useObjectSchema |
+| `objects.updateObject` | `PATCH /api/v1/objects/{object_slug}` | write | `objects:manage` | ObjectSchemaEditor |
+| `objects.createAttribute` | `POST /api/v1/objects/{object_slug}/attributes` | write | `objects:manage` | ObjectSchemaEditor, AttributeFormDialog |
+| `objects.updateAttribute` | `PATCH /api/v1/objects/{object_slug}/attributes/{attr_slug}` | write | `objects:manage` | ObjectSchemaEditor, AttributeFormDialog |
+| `objects.archiveAttribute` | `DELETE /api/v1/objects/{object_slug}/attributes/{attr_slug}` | destructive | `objects:manage` | ObjectSchemaEditor |
+| `objects.archiveObject` | `DELETE /api/v1/objects/{object_slug}` | destructive | `objects:manage` | ObjectSchemaEditor |
+| `objects.listObjectRecords` | `GET /api/v1/objects/{object_slug}/records` | read | `objects:read` | ObjectTable |
+| `objects.createObjectRecord` | `POST /api/v1/objects/{object_slug}/records` | write | `objects:write` | ObjectTable, RecordFormDialog |
+| `objects.updateObjectRecord` | `PATCH /api/v1/objects/{object_slug}/records/{record_id}` | write | `objects:write` | ObjectTable, RecordFormDialog, ObjectRecordDetail |
+| `objects.archiveObjectRecord` | `DELETE /api/v1/objects/{object_slug}/records/{record_id}` | destructive | `objects:delete` | ObjectTable, ObjectRecordDetail |
+| `objects.getObjectRecord` | `GET /api/v1/objects/{object_slug}/records/{record_id}` | read | `objects:read` | ObjectRecordDetail |
+| `objects.getObjectRecordChanges` | `GET /api/v1/objects/{object_slug}/records/{record_id}/changes` | read | `objects:read` | ObjectRecordDetail |
+| `objects.getObjectRelationships` | `GET /api/v1/objects/{object_slug}/records/{record_id}/relationships` | read | `objects:read` | ObjectRecordDetail |
+| `objects.restoreObjectRecord` | `POST /api/v1/objects/{object_slug}/records/{record_id}/restore` | write | `objects:write` | ObjectRecordDetail |
+| `recordRoles.getRecordRoleSlots` | `GET /api/v1/records/{entity_type}/{entity_id}/role-slots` | read | `contacts:read` | RecordRolesPanel |
+| `recordRoles.assignRecordRole` | `POST /api/v1/records/{entity_type}/{entity_id}/role-assignments` | write | `contacts:write` | RecordRolesPanel |
+| `recordRoles.clearRecordRole` | `DELETE /api/v1/records/{entity_type}/{entity_id}/role-assignments/{role_slot}` | destructive | `contacts:delete` | RecordRolesPanel |

package/blocks/objects/block.json

@@ -0,0 +1,243 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "objects",
+  "title": "Custom objects",
+  "summary": "Define your own record types (invoices, shipments, subscriptions) with typed fields, then list, create, edit and archive their records.",
+  "features": [
+    "object and field schema editor",
+    "generic records table for any object",
+    "record detail with owners, relationships and change history",
+    "optimistic concurrency on edits",
+    "archive and restore with history kept"
+  ],
+  "dependsOn": [
+    "foundation"
+  ],
+  "operations": [
+    "list_objects_objects_get",
+    "create_object_objects_post",
+    "get_object_objects__object_slug__get",
+    "list_object_attributes_objects__object_slug__attributes_get",
+    "update_object_objects__object_slug__patch",
+    "create_attribute_objects__object_slug__attributes_post",
+    "update_attribute_objects__object_slug__attributes__attr_slug__patch",
+    "archive_attribute_objects__object_slug__attributes__attr_slug__delete",
+    "archive_object_objects__object_slug__delete",
+    "list_object_records_objects__object_slug__records_get",
+    "create_object_record_objects__object_slug__records_post",
+    "update_object_record_objects__object_slug__records__record_id__patch",
+    "archive_object_record_objects__object_slug__records__record_id__delete",
+    "get_object_record_objects__object_slug__records__record_id__get",
+    "get_object_record_changes_objects__object_slug__records__record_id__changes_get",
+    "get_object_relationships_objects__object_slug__records__record_id__relationships_get",
+    "restore_object_record_objects__object_slug__records__record_id__restore_post",
+    "get_record_role_slots_records__entity_type___entity_id__role_slots_get",
+    "assign_record_role_records__entity_type___entity_id__role_assignments_post",
+    "clear_record_role_records__entity_type___entity_id__role_assignments__role_slot__delete"
+  ],
+  "components": [
+    {
+      "name": "ObjectSchemaEditor",
+      "file": "components/object-schema-editor.tsx",
+      "purpose": "Create objects, edit their labels, add/edit/archive fields (text, number, select, reference...).",
+      "operations": [
+        "list_objects_objects_get",
+        "create_object_objects_post",
+        "get_object_objects__object_slug__get",
+        "list_object_attributes_objects__object_slug__attributes_get",
+        "update_object_objects__object_slug__patch",
+        "create_attribute_objects__object_slug__attributes_post",
+        "update_attribute_objects__object_slug__attributes__attr_slug__patch",
+        "archive_attribute_objects__object_slug__attributes__attr_slug__delete",
+        "archive_object_objects__object_slug__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AttributeFormDialog",
+      "file": "components/attribute-form-dialog.tsx",
+      "purpose": "Dialog to add or edit one field of an object.",
+      "operations": [
+        "create_attribute_objects__object_slug__attributes_post",
+        "update_attribute_objects__object_slug__attributes__attr_slug__patch"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "ObjectTable",
+      "file": "components/object-table.tsx",
+      "purpose": "Records of any object as a table with search over loaded rows, load-more, create, edit and archive.",
+      "operations": [
+        "get_object_objects__object_slug__get",
+        "list_object_attributes_objects__object_slug__attributes_get",
+        "list_object_records_objects__object_slug__records_get",
+        "create_object_record_objects__object_slug__records_post",
+        "update_object_record_objects__object_slug__records__record_id__patch",
+        "archive_object_record_objects__object_slug__records__record_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "RecordFormDialog",
+      "file": "components/record-form-dialog.tsx",
+      "purpose": "Dialog to create or edit one record; builds inputs from the object's fields and shows 422 field errors.",
+      "operations": [
+        "create_object_record_objects__object_slug__records_post",
+        "update_object_record_objects__object_slug__records__record_id__patch"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "AttributeFieldInput",
+      "file": "components/attribute-field-input.tsx",
+      "purpose": "One form control chosen by attribute type (text, number, date, select, checkbox...).",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "ObjectNotFound",
+      "file": "components/object-not-found.tsx",
+      "purpose": "Tells an unreachable custom-objects API (the list call itself 404s) apart from a deleted, mistyped or inaccessible object/record.",
+      "operations": [
+        "list_objects_objects_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ObjectRecordDetail",
+      "file": "components/object-record-detail.tsx",
+      "purpose": "One record: values, related records, change history, edit, archive and restore.",
+      "operations": [
+        "get_object_objects__object_slug__get",
+        "list_object_attributes_objects__object_slug__attributes_get",
+        "get_object_record_objects__object_slug__records__record_id__get",
+        "get_object_record_changes_objects__object_slug__records__record_id__changes_get",
+        "get_object_relationships_objects__object_slug__records__record_id__relationships_get",
+        "update_object_record_objects__object_slug__records__record_id__patch",
+        "archive_object_record_objects__object_slug__records__record_id__delete",
+        "restore_object_record_objects__object_slug__records__record_id__restore_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "RecordRolesPanel",
+      "file": "components/record-roles-panel.tsx",
+      "purpose": "Owner slots (SDR, AE, CSM) of a contact, company or deal: view, assign, clear.",
+      "operations": [
+        "get_record_role_slots_records__entity_type___entity_id__role_slots_get",
+        "assign_record_role_records__entity_type___entity_id__role_assignments_post",
+        "clear_record_role_records__entity_type___entity_id__role_assignments__role_slot__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useObjectSchema",
+      "file": "hooks/use-object-schema.ts",
+      "purpose": "Load one object's definition and its active fields in display order.",
+      "operations": [
+        "get_object_objects__object_slug__get",
+        "list_object_attributes_objects__object_slug__attributes_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/object-types.ts",
+      "purpose": "Object/field/record types and pure helpers: slugify, value formatting, input to API value conversion, missing-API detection."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/define-object-and-add-records.ts",
+      "title": "Define a custom object, add its fields, create the first records",
+      "when": "Modelling something graph8 has no table for, before ObjectTable has anything to show."
+    },
+    {
+      "file": "recipes/upsert-records-from-your-system.ts",
+      "title": "Sync records from your own system (idempotent upsert)",
+      "when": "Nightly or webhook-driven sync where the same external row can arrive twice."
+    },
+    {
+      "file": "recipes/update-audit-and-archive-records.ts",
+      "title": "Page through records, update safely, read history, archive and restore",
+      "when": "Admin tooling or an agent that edits records; uses expected revision to avoid overwrites."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "admin-schema-key",
+      "description": "Creating objects and fields needs the objects:manage scope and an Admin user behind the key; records need objects:read / objects:write / objects:delete.",
+      "where": "api",
+      "verify": "g8.api.me.describeCurrentKey() lists the objects:* scopes and the key owner is an Admin."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"objects\" and \"records\" to allowedPrefixes in app/api/g8/[...path]/route.ts so the browser can reach these areas through the proxy.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains \"objects\" and \"records\"."
+    }
+  ],
+  "scopes": [
+    "contacts:delete",
+    "contacts:read",
+    "contacts:write",
+    "objects:delete",
+    "objects:manage",
+    "objects:read",
+    "objects:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Who can open ObjectSchemaEditor in the app",
+      "default": "Only signed-in admins (put it behind an admin route); ObjectTable and ObjectRecordDetail are for everyone with access",
+      "askHuman": true
+    },
+    {
+      "decision": "How records are deleted",
+      "default": "Archive: hidden from lists, still readable by id, history kept (the API has no hard delete for records)",
+      "askHuman": false
+    },
+    {
+      "decision": "Which field titles a record",
+      "default": "The object's display_attribute_slug, else the first text field",
+      "askHuman": false
+    },
+    {
+      "decision": "Page size of ObjectTable",
+      "default": "50 rows per request with Load more",
+      "askHuman": false
+    },
+    {
+      "decision": "Field types offered in the editor",
+      "default": "All types except formula (formulas need an expression tree: use a recipe)",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}