@graph8/sdk 0.303.0 → 0.357.0

package/blocks/objects/components/object-table.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+/**
+ * ObjectTable: records of ANY object (custom or standard) as a table, with create, edit and archive.
+ *
+ * SDK operations, in order:
+ *   1. getObject + listObjectAttributes (via useObjectSchema)                 read   (columns come from the schema)
+ *   2. listObjectRecords (GET /objects/{object_slug}/records, cursor paged)   read
+ *   3. createObjectRecord / updateObjectRecord (RecordFormDialog)             write
+ *   4. archiveObjectRecord (DELETE /objects/{object_slug}/records/{id})       destructive -> ConfirmSpendDialog
+ * The list endpoint has no server-side search, so the search box filters the rows loaded so far;
+ * "Load more" fetches the next cursor page. Archived records are excluded by the API.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { usePaginated } from "@/g8/hooks/use-paginated";
+import { useObjectSchema } from "../hooks/use-object-schema";
+import { formatValue, isObjectsApiMissing, recordTitle } from "../lib/object-types";
+import { ObjectNotFound } from "./object-not-found";
+import type { ObjectRecord } from "../lib/object-types";
+import { RecordFormDialog } from "./record-form-dialog";
+
+export interface ObjectTableProps {
+  objectSlug: string;
+  /** Rows per request, 1-200. Default 50. */
+  pageSize?: number;
+  /** Called when a row is clicked, e.g. to open ObjectRecordDetail. */
+  onSelectRecord?: (record: ObjectRecord) => void;
+  /** Max columns shown (the first fields in display order). Default 6. */
+  maxColumns?: number;
+}
+
+export function ObjectTable({ objectSlug, pageSize = 50, onSelectRecord, maxColumns = 6 }: ObjectTableProps) {
+  const schema = useObjectSchema(objectSlug);
+  const slug = encodeURIComponent(objectSlug);
+  const records = usePaginated<ObjectRecord>(
+    (cursor, signal) => g8Get<ObjectRecord[]>(`/objects/${slug}/records`, { limit: pageSize, cursor }, { signal }),
+    [objectSlug, pageSize],
+  );
+  const [search, setSearch] = useState("");
+  const [form, setForm] = useState<{ record?: ObjectRecord } | null>(null);
+  const [toArchive, setToArchive] = useState<ObjectRecord | null>(null);
+  // Everything below belongs to ONE object: another object must not inherit its search, open dialog or pending archive.
+  useEffect(() => {
+    setSearch("");
+    setForm(null);
+    setToArchive(null);
+  }, [objectSlug]);
+  const archive = useG8Mutation((record: ObjectRecord) => g8Delete(`/objects/${slug}/records/${encodeURIComponent(record.id)}`), {
+    onSuccess: () => { setToArchive(null); void records.reload(); },
+  });
+
+  const noun = schema.definition?.singular_noun ?? "record";
+  const columns = schema.attributes.slice(0, maxColumns);
+  const needle = search.trim().toLowerCase();
+  const rows = needle
+    ? records.items.filter((r) => Object.values(r.values ?? {}).some((v) => formatValue(undefined, v).toLowerCase().includes(needle)))
+    : records.items;
+
+  if (isObjectsApiMissing(records.error) || isObjectsApiMissing(schema.error)) return <ObjectNotFound what="object" error={records.error ?? schema.error} />;
+  if (schema.error || records.error) {
+    return <ApiError error={schema.error ?? records.error} title="Could not load records" onRetry={() => { void schema.refetch(); void records.reload(); }} />;
+  }
+
+  return (
+    <div className="grid gap-3">
+      <div className="flex items-center justify-between gap-2">
+        <Input aria-label={`Search loaded ${schema.definition?.plural_noun ?? "records"}`} placeholder="Search loaded rows" className="max-w-xs" value={search} onChange={(e) => setSearch(e.target.value)} />
+        <Button onClick={() => setForm({})} disabled={schema.loading}>New {noun}</Button>
+      </div>
+      {records.loading || schema.loading ? (
+        <div className="grid gap-2" aria-busy="true">{[0, 1, 2, 3].map((i) => <Skeleton key={i} className="h-9 w-full" />)}</div>
+      ) : rows.length === 0 ? (
+        <EmptyState
+          title={needle ? "No loaded rows match" : `No ${schema.definition?.plural_noun?.toLowerCase() ?? "records"} yet`}
+          description={needle ? "Clear the search, or load more rows." : `Create the first ${noun} to see it here.`}
+          action={needle ? undefined : <Button onClick={() => setForm({})}>New {noun}</Button>}
+        />
+      ) : (
+        <Table>
+          <TableHeader>
+            <TableRow>
+              {columns.map((c) => <TableHead key={c.slug}>{c.title}</TableHead>)}
+              <TableHead className="w-32" />
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {rows.map((record) => (
+              <TableRow key={record.id} className={onSelectRecord ? "cursor-pointer" : undefined} onClick={() => onSelectRecord?.(record)}>
+                {columns.map((c, i) => (
+                  <TableCell key={c.slug}>{formatValue(c, record.values?.[c.slug]) || (i === 0 ? recordTitle(schema.definition, schema.attributes, record) : "")}</TableCell>
+                ))}
+                <TableCell className="text-right" onClick={(e) => e.stopPropagation()}>
+                  <Button variant="ghost" size="sm" onClick={() => setForm({ record })}>Edit</Button>
+                  <Button variant="ghost" size="sm" onClick={() => { archive.reset(); setToArchive(record); }}>Archive</Button>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+      {records.hasMore ? <div><Button variant="outline" onClick={() => void records.loadMore()} loading={records.loadingMore}>Load more</Button></div> : null}
+      <RecordFormDialog
+        open={form !== null}
+        objectSlug={objectSlug}
+        singularNoun={noun}
+        attributes={schema.attributes}
+        record={form?.record}
+        onClose={() => setForm(null)}
+        onSaved={() => { setForm(null); void records.reload(); }}
+      />
+      <ConfirmSpendDialog
+        open={toArchive !== null}
+        tier="destructive"
+        title={`Archive this ${noun}?`}
+        description={<><p>It leaves listings but stays readable by id, and its history is kept.</p>{archive.error ? <ApiError error={archive.error} title="Could not archive the record" /> : null}</>}
+        confirmLabel="Archive"
+        confirming={archive.loading}
+        onCancel={() => { archive.reset(); setToArchive(null); }}
+        onConfirm={() => { if (toArchive) void archive.mutate(toArchive); }}
+      />
+    </div>
+  );
+}

package/blocks/objects/components/record-form-dialog.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+/**
+ * RecordFormDialog: create or edit one record of any object.
+ *
+ * SDK operations, in order:
+ *   1. createObjectRecord (POST /objects/{object_slug}/records)           write  (new record)
+ *   2. updateObjectRecord (PATCH /objects/{object_slug}/records/{id})     write  (edit; sends expected_revision)
+ * Neither is billable, external or destructive, so no confirm dialog. Unknown or invalid values come back
+ * as a 422 listing every problem at once; they are shown inline. A 409 means a unique value collided or the
+ * record changed since it was loaded (reload and retry).
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { buildValues, fromInputValue, toInputValue } from "../lib/object-types";
+import type { ObjectAttribute, ObjectRecord } from "../lib/object-types";
+import { AttributeFieldInput } from "./attribute-field-input";
+
+export interface RecordFormDialogProps {
+  open: boolean;
+  objectSlug: string;
+  /** Singular label for the title, e.g. "Invoice". */
+  singularNoun?: string;
+  attributes: readonly ObjectAttribute[];
+  /** Edit this record; omit to create a new one. */
+  record?: ObjectRecord;
+  onClose: () => void;
+  onSaved: (record: ObjectRecord) => void;
+}
+
+function initialDrafts(attributes: readonly ObjectAttribute[], record?: ObjectRecord): Record<string, string | boolean> {
+  const drafts: Record<string, string | boolean> = {};
+  for (const attribute of attributes) {
+    if (attribute.is_system) continue;
+    const stored = record?.values?.[attribute.slug];
+    drafts[attribute.slug] = attribute.attribute_type === "checkbox" ? stored === true : toInputValue(attribute, stored);
+  }
+  return drafts;
+}
+
+export function RecordFormDialog({ open, objectSlug, singularNoun = "record", attributes, record, onClose, onSaved }: RecordFormDialogProps) {
+  const editable = attributes.filter((a) => !a.is_system && !a.is_archived && a.attribute_type !== "formula");
+  const [drafts, setDrafts] = useState<Record<string, string | boolean>>(() => initialDrafts(editable, record));
+  const slug = encodeURIComponent(objectSlug);
+
+  useEffect(() => {
+    if (open) setDrafts(initialDrafts(attributes.filter((a) => !a.is_system && !a.is_archived && a.attribute_type !== "formula"), record));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, record?.id, record?.revision]);
+
+  const save = useG8Mutation(async () => {
+    if (record) {
+      // Send only what changed: an untouched empty field would be an explicit null, which clears it (and is a 422 for required ones).
+      const before = initialDrafts(editable, record);
+      const values: Record<string, unknown> = {};
+      for (const attribute of editable) {
+        if (drafts[attribute.slug] !== before[attribute.slug]) values[attribute.slug] = fromInputValue(attribute, drafts[attribute.slug] ?? "");
+      }
+      const res = await g8Patch<ObjectRecord>(`/objects/${slug}/records/${encodeURIComponent(record.id)}`, { values, expected_revision: record.revision });
+      return res.data;
+    }
+    const res = await g8Post<ObjectRecord>(`/objects/${slug}/records`, { values: buildValues(editable, drafts) });
+    return res.data;
+  }, { onSuccess: (saved) => onSaved(saved) });
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => (next ? undefined : onClose())}>
+      <DialogContent className="max-h-[85vh] overflow-y-auto">
+        <DialogHeader>
+          <DialogTitle>{record ? `Edit ${singularNoun}` : `New ${singularNoun}`}</DialogTitle>
+          <DialogDescription>Required fields are marked with an asterisk.</DialogDescription>
+        </DialogHeader>
+        <form
+          className="grid gap-3"
+          onSubmit={(e) => {
+            e.preventDefault();
+            void save.mutate(undefined);
+          }}
+        >
+          {editable.map((attribute) => (
+            <div key={attribute.slug}>
+              <Label htmlFor={`g8-attr-${attribute.slug}`} className="mb-1">
+                {attribute.title}
+                {attribute.is_required ? " *" : ""}
+              </Label>
+              <AttributeFieldInput
+                attribute={attribute}
+                value={drafts[attribute.slug] ?? ""}
+                disabled={save.loading}
+                onChange={(value) => setDrafts((prev) => ({ ...prev, [attribute.slug]: value }))}
+              />
+            </div>
+          ))}
+          {editable.length === 0 ? <p className="text-muted-foreground text-sm">This object has no fields yet. Add fields in the schema editor first.</p> : null}
+          {save.error ? <ApiError error={save.error} title="Could not save the record" /> : null}
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={onClose} disabled={save.loading}>
+              Cancel
+            </Button>
+            <Button type="submit" loading={save.loading} disabled={editable.length === 0}>
+              {record ? "Save changes" : `Create ${singularNoun}`}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/blocks/objects/components/record-roles-panel.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+/**
+ * RecordRolesPanel: who owns a contact, company or deal (SDR, AE, CSM role slots).
+ *
+ * SDK operations, in order:
+ *   1. getRecordRoleSlots (GET /records/{entity_type}/{entity_id}/role-slots)                       read
+ *   2. assignRecordRole (POST /records/{entity_type}/{entity_id}/role-assignments)                  write
+ *   3. clearRecordRole (DELETE /records/{entity_type}/{entity_id}/role-assignments/{role_slot})     destructive -> ConfirmSpendDialog
+ * Only the standard objects (contacts, companies, deals) have role slots; custom objects do not.
+ * The API takes a user id, not a name: pass `userOptions` to give people a picker.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+
+type Slot = "sdr" | "ae" | "csm";
+const SLOTS: ReadonlyArray<{ slot: Slot; label: string }> = [
+  { slot: "sdr", label: "SDR" },
+  { slot: "ae", label: "Account executive" },
+  { slot: "csm", label: "Customer success" },
+];
+
+interface SlotInfo { user_id?: string | null; user_name?: string | null }
+interface RoleSlots { sdr?: SlotInfo | null; ae?: SlotInfo | null; csm?: SlotInfo | null; can_modify?: boolean }
+
+export interface RecordRolesPanelProps {
+  entityType: "contact" | "company" | "deal";
+  entityId: string;
+  /** Optional people to pick from. Without it the user id is typed. */
+  userOptions?: ReadonlyArray<{ id: string; name: string }>;
+}
+
+export function RecordRolesPanel({ entityType, entityId, userOptions }: RecordRolesPanelProps) {
+  const base = `/records/${entityType}/${encodeURIComponent(entityId)}`;
+  const slots = useG8Query((signal) => g8Get<RoleSlots>(`${base}/role-slots`, {}, { signal }).then((r) => r.data), [base]);
+  const [draft, setDraft] = useState<Record<string, string>>({});
+  const [clearing, setClearing] = useState<Slot | null>(null);
+  const [busySlot, setBusySlot] = useState<Slot | null>(null);
+  const assign = useG8Mutation((vars: { slot: Slot; userId: string }) => g8Post(`${base}/role-assignments`, { role_slot: vars.slot, user_id: vars.userId }), {
+    onSuccess: (_r, vars) => { setDraft((d) => ({ ...d, [vars.slot]: "" })); void slots.refetch(); },
+  });
+  const assignSlot = async (slot: Slot, userId: string): Promise<void> => {
+    setBusySlot(slot);
+    await assign.mutate({ slot, userId });
+    setBusySlot(null);
+  };
+  // Typed ids and open dialogs belong to ONE record.
+  useEffect(() => {
+    setDraft({});
+    setClearing(null);
+    assign.reset();
+    clear.reset();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [base]);
+  const clear = useG8Mutation((slot: Slot) => g8Delete(`${base}/role-assignments/${slot}`), { onSuccess: () => { setClearing(null); void slots.refetch(); } });
+
+  if (slots.error) return <ApiError error={slots.error} title="Could not load owners" onRetry={() => void slots.refetch()} />;
+  // Write controls only after the API has said the caller may modify: never while loading (they would flash for read-only users).
+  const canModify = slots.data != null && slots.data.can_modify !== false;
+  return (
+    <section aria-label="Owners" className="grid gap-2">
+      <h3 className="text-sm font-semibold">Owners</h3>
+      {slots.loading && !slots.data ? <p className="text-muted-foreground text-sm">Loading owners...</p> : null}
+      {SLOTS.map(({ slot, label }) => {
+        const holder = slots.data?.[slot];
+        return (
+          <div key={slot} className="flex items-center gap-2 text-sm">
+            <span className="w-40 shrink-0">{label}</span>
+            <span className="flex-1">{holder?.user_name ?? holder?.user_id ?? <span className="text-muted-foreground">Unassigned</span>}</span>
+            {canModify ? (
+              <>
+                {userOptions ? (
+                  <select aria-label={`${label} user`} value={draft[slot] ?? ""} onChange={(e) => setDraft((d) => ({ ...d, [slot]: e.target.value }))} className="border-input bg-background h-8 rounded-md border px-2 text-sm">
+                    <option value="">Choose...</option>
+                    {userOptions.map((u) => <option key={u.id} value={u.id}>{u.name}</option>)}
+                  </select>
+                ) : (
+                  <Input aria-label={`${label} user id`} placeholder="User id" className="h-8 w-40" value={draft[slot] ?? ""} onChange={(e) => setDraft((d) => ({ ...d, [slot]: e.target.value }))} />
+                )}
+                <Button size="sm" variant="outline" loading={busySlot === slot} disabled={!draft[slot] || busySlot !== null} onClick={() => void assignSlot(slot, draft[slot])}>Assign</Button>
+                {holder ? <Button size="sm" variant="ghost" onClick={() => { clear.reset(); setClearing(slot); }}>Clear</Button> : null}
+              </>
+            ) : null}
+          </div>
+        );
+      })}
+      {assign.error ? <ApiError error={assign.error} title="Could not assign the owner" /> : null}
+      <ConfirmSpendDialog
+        open={clearing !== null}
+        tier="destructive"
+        title="Remove this owner?"
+        description={<><p>The slot becomes unassigned. The change is kept in the role history.</p>{clear.error ? <ApiError error={clear.error} title="Could not clear the owner" /> : null}</>}
+        confirmLabel="Remove"
+        confirming={clear.loading}
+        onCancel={() => { clear.reset(); setClearing(null); }}
+        onConfirm={() => { if (clearing) void clear.mutate(clearing); }}
+      />
+    </section>
+  );
+}

package/blocks/objects/hooks/use-object-schema.ts

@@ -0,0 +1,36 @@
+"use client";
+
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { orderedAttributes } from "../lib/object-types";
+import type { ObjectAttribute, ObjectDefinition } from "../lib/object-types";
+
+/**
+ * Load one object's definition and its active attributes.
+ *
+ * Operations in order: getObject (GET /objects/{object_slug}), listObjectAttributes
+ * (GET /objects/{object_slug}/attributes). Both are `read`.
+ */
+export function useObjectSchema(objectSlug: string | undefined) {
+  const slug = objectSlug ? encodeURIComponent(objectSlug) : "";
+  const definition = useG8Query(
+    (signal) => g8Get<ObjectDefinition>(`/objects/${slug}`, {}, { signal }).then((r) => r.data),
+    [slug],
+    { enabled: Boolean(objectSlug) },
+  );
+  const attributes = useG8Query(
+    (signal) => g8Get<ObjectAttribute[]>(`/objects/${slug}/attributes`, {}, { signal }).then((r) => r.data ?? []),
+    [slug],
+    { enabled: Boolean(objectSlug) },
+  );
+  const refetch = async (): Promise<void> => {
+    await Promise.all([definition.refetch(), attributes.refetch()]);
+  };
+  return {
+    definition: definition.data,
+    attributes: orderedAttributes(attributes.data ?? []),
+    loading: definition.loading || attributes.loading,
+    error: definition.error ?? attributes.error,
+    refetch,
+  };
+}

package/blocks/objects/lib/object-types.ts

@@ -0,0 +1,214 @@
+"use client";
+
+/**
+ * Types and pure helpers shared by the objects block.
+ *
+ * Object records are untyped by design: the valid keys of `record.values` are the
+ * attribute slugs of YOUR object, which you only know at runtime. These helpers turn
+ * an attribute definition into the right input, display text and API value.
+ */
+
+import { G8Error } from "@graph8/sdk";
+
+export type AttributeType =
+  | "text" | "number" | "currency" | "date" | "timestamp" | "checkbox" | "select" | "status"
+  | "email_address" | "phone_number" | "domain" | "location" | "personal_name" | "record_reference"
+  | "rating" | "actor_reference";
+
+/** Types you can create from the editor. `formula` exists in the API but needs an expression tree, so it is left to recipes. */
+export const ATTRIBUTE_TYPES: ReadonlyArray<{ value: AttributeType; label: string }> = [
+  { value: "text", label: "Text" },
+  { value: "number", label: "Number" },
+  { value: "currency", label: "Currency" },
+  { value: "date", label: "Date" },
+  { value: "timestamp", label: "Date and time" },
+  { value: "checkbox", label: "Checkbox" },
+  { value: "select", label: "Select" },
+  { value: "status", label: "Status" },
+  { value: "email_address", label: "Email" },
+  { value: "phone_number", label: "Phone" },
+  { value: "domain", label: "Domain" },
+  { value: "location", label: "Location" },
+  { value: "personal_name", label: "Person name" },
+  { value: "record_reference", label: "Reference to a record" },
+  { value: "rating", label: "Rating" },
+  { value: "actor_reference", label: "Team member" },
+];
+
+export const OBJECT_ICONS = ["box", "briefcase", "building", "calendar", "flag", "folder", "globe", "heart", "layers", "package", "target", "users"] as const;
+export type ObjectIcon = (typeof OBJECT_ICONS)[number];
+
+export interface ObjectDefinition {
+  slug: string;
+  singular_noun: string;
+  plural_noun: string;
+  description?: string | null;
+  icon?: string | null;
+  display_attribute_slug?: string | null;
+  is_archived?: boolean;
+  is_system?: boolean;
+}
+
+export interface ObjectAttribute {
+  slug: string;
+  title: string;
+  attribute_type: string;
+  description?: string | null;
+  config?: Record<string, unknown>;
+  is_required?: boolean;
+  is_unique?: boolean;
+  is_multiselect?: boolean;
+  is_archived?: boolean;
+  is_system?: boolean;
+  sort_order?: number;
+}
+
+export interface ObjectRecord {
+  id: string;
+  object_slug: string;
+  values: Record<string, unknown>;
+  revision?: number;
+  is_archived?: boolean;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+/** Slugs are lowercase snake_case, start with a letter, max 63 characters. */
+export function slugify(text: string): string {
+  const slug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 63);
+  return /^[a-z]/.test(slug) ? slug : slug ? `f_${slug}`.slice(0, 63) : "";
+}
+
+export function isValidSlug(slug: string): boolean {
+  return /^[a-z][a-z0-9_]{0,62}$/.test(slug);
+}
+
+/** Active attributes in display order (sort_order, then slug). */
+export function orderedAttributes(attributes: readonly ObjectAttribute[]): ObjectAttribute[] {
+  return attributes
+    .filter((a) => !a.is_archived)
+    .sort((a, b) => (a.sort_order ?? 0) - (b.sort_order ?? 0) || a.slug.localeCompare(b.slug));
+}
+
+/** The allowed values of a select/status attribute. Options may be strings or {value|id|slug|label} objects. */
+export function selectOptions(attribute: ObjectAttribute): string[] {
+  const raw = attribute.config?.options;
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((o) => (typeof o === "string" ? o : o && typeof o === "object" ? String((o as Record<string, unknown>).value ?? (o as Record<string, unknown>).id ?? (o as Record<string, unknown>).slug ?? (o as Record<string, unknown>).label ?? "") : ""))
+    .filter(Boolean);
+}
+
+function scalarText(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value === "boolean") return value ? "Yes" : "No";
+  if (typeof value === "object") {
+    const o = value as Record<string, unknown>;
+    const named = o.full_name ?? o.name ?? o.label ?? o.title ?? o.record_id ?? o.id ?? o.actor_id;
+    return named != null ? String(named) : JSON.stringify(value);
+  }
+  return String(value);
+}
+
+/** Human text for a stored value. Lists are comma separated, booleans Yes/No, objects use their name. */
+export function formatValue(attribute: ObjectAttribute | undefined, value: unknown): string {
+  if (value == null || value === "") return "";
+  if (Array.isArray(value)) return value.map(scalarText).join(", ");
+  if (attribute?.attribute_type === "currency" && typeof value === "number") {
+    const code = typeof attribute.config?.currency_code === "string" ? attribute.config.currency_code : "USD";
+    try {
+      return new Intl.NumberFormat(undefined, { style: "currency", currency: code }).format(value);
+    } catch {
+      return `${value} ${code}`;
+    }
+  }
+  if ((attribute?.attribute_type === "date" || attribute?.attribute_type === "timestamp") && typeof value === "string") {
+    const d = new Date(value);
+    if (!Number.isNaN(d.getTime())) return attribute.attribute_type === "date" ? d.toISOString().slice(0, 10) : d.toLocaleString();
+  }
+  return scalarText(value);
+}
+
+/** An ISO instant as the local "YYYY-MM-DDTHH:mm" a datetime-local input shows. */
+export function toLocalDateTimeInput(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso.slice(0, 16);
+  const pad = (n: number): string => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/** The text shown in an `<input>` for the stored value. */
+export function toInputValue(attribute: ObjectAttribute, value: unknown): string {
+  if (value == null) return "";
+  if (Array.isArray(value)) return value.map(scalarText).join(", ");
+  if (typeof value === "object") return JSON.stringify(value);
+  if (attribute.attribute_type === "timestamp" && typeof value === "string") return toLocalDateTimeInput(value);
+  return String(value);
+}
+
+/**
+ * Turn what the user typed into the API value. Returns `null` for an empty input
+ * (which CLEARS an optional value on update) and a typed value otherwise.
+ */
+export function fromInputValue(attribute: ObjectAttribute, raw: string | boolean): unknown {
+  if (attribute.attribute_type === "checkbox") return raw === true || raw === "true";
+  const text = String(raw).trim();
+  if (text === "") return null;
+  if (attribute.is_multiselect) return text.split(",").map((s) => s.trim()).filter(Boolean);
+  if (["number", "currency", "rating"].includes(attribute.attribute_type)) return Number(text);
+  // A datetime-local value has no zone: read it as the person's local time and send the exact instant.
+  if (attribute.attribute_type === "timestamp") {
+    const d = new Date(text);
+    return Number.isNaN(d.getTime()) ? text : d.toISOString();
+  }
+  // Date-only values stay "YYYY-MM-DD": never routed through Date, which would shift the day by time zone.
+  if ((attribute.attribute_type === "location" || attribute.attribute_type === "personal_name") && text.startsWith("{")) {
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+/** Values to send on create: only attributes the user filled in (an unset one would be a null the API may reject). */
+export function buildValues(attributes: readonly ObjectAttribute[], drafts: Record<string, string | boolean>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const attribute of attributes) {
+    const draft = drafts[attribute.slug];
+    if (draft === undefined) continue;
+    const value = fromInputValue(attribute, draft);
+    if (value !== null) out[attribute.slug] = value;
+  }
+  return out;
+}
+
+/**
+ * A 404 from the objects API itself (not a single object/record): the backend at this base URL does not serve
+ * custom objects (wrong G8_API_URL or an older deployment). A missing scope or a proxy-blocked prefix is a 403.
+ */
+export function isObjectsApiMissing(error: unknown): boolean {
+  return error instanceof G8Error && error.status === 404;
+}
+
+/** @deprecated Renamed to {@link isObjectsApiMissing}; there is no platform gate. Kept so existing imports work. */
+export const isPlatformGated = isObjectsApiMissing;
+
+/** The attribute used as a record's title. */
+export function recordTitle(definition: ObjectDefinition | undefined, attributes: readonly ObjectAttribute[], record: ObjectRecord): string {
+  const slug = definition?.display_attribute_slug ?? attributes.find((a) => a.attribute_type === "text")?.slug ?? attributes[0]?.slug;
+  const text = slug ? formatValue(attributes.find((a) => a.slug === slug), record.values?.[slug]) : "";
+  return text || record.id;
+}
+
+/** The standard objects that support owner roles (SDR/AE/CSM), mapped to the role API's entity type. */
+export const ROLE_ENTITY_TYPES: Record<string, "contact" | "company" | "deal"> = {
+  contacts: "contact",
+  companies: "company",
+  deals: "deal",
+};

package/blocks/objects/recipes/define-object-and-add-records.ts

@@ -0,0 +1,24 @@
+/**
+ * @title Define a custom object, add its fields, create the first records
+ * @when Modelling something graph8 has no table for (an invoice, a shipment, a subscription) before the
+ * ObjectTable screen has anything to show. Needs an Admin key with objects:manage and objects:write.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// 1. The object. The slug is immutable and becomes the URL segment: /objects/invoices/...
+const invoices = await g8.objects.create({ slug: "invoices", singular_noun: "Invoice", plural_noun: "Invoices", icon: "package" });
+
+// 2. Fields, in display order. Slugs are lowercase snake_case. select/status need config.options.
+await g8.objects.createAttribute(invoices.slug, { slug: "number", title: "Number", attribute_type: "text", is_required: true, is_unique: true, sort_order: 1 });
+await g8.objects.createAttribute(invoices.slug, { slug: "amount", title: "Amount", attribute_type: "currency", config: { currency_code: "USD" }, sort_order: 2 });
+await g8.objects.createAttribute(invoices.slug, { slug: "status", title: "Status", attribute_type: "status", config: { options: ["draft", "sent", "paid", "overdue"] }, sort_order: 3 });
+await g8.objects.createAttribute(invoices.slug, { slug: "due", title: "Due date", attribute_type: "date", sort_order: 4 });
+
+// 3. Make the first text field the record title in lists and pickers.
+await g8.objects.update(invoices.slug, { display_attribute_slug: "number" });
+
+// 4. Records. Unknown fields are a 422 (never silently dropped); a duplicate unique value is a 409.
+const record = await g8.objects.createRecord(invoices.slug, { number: "INV-1001", amount: 1200, status: "sent", due: "2026-11-30" });
+console.log(record.id, record.revision, record.values);

package/blocks/objects/recipes/update-audit-and-archive-records.ts

@@ -0,0 +1,39 @@
+/**
+ * @title Page through records, update safely, read the history, archive and restore
+ * @when Building admin tooling or an agent that edits records. `expectedRevision` makes an update a conditional
+ * write so two editors cannot silently overwrite each other (the API answers 409 and you re-read).
+ */
+import { g8, G8Error } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// 1. Walk every record with the cursor (page numbers also work, the cursor wins when both are sent).
+const all: Array<{ id: string; revision?: number; values: Record<string, unknown> }> = [];
+let cursor: string | undefined;
+do {
+  const page = await g8.objects.listRecords("invoices", { limit: 100, cursor });
+  all.push(...page.data);
+  cursor = page.pagination?.next_cursor ?? undefined;
+} while (cursor);
+
+const overdue = all.filter((r) => r.values.status === "sent" && String(r.values.due ?? "") < new Date().toISOString().slice(0, 10));
+
+for (const record of overdue) {
+  try {
+    // 2. Partial update: only `status` changes, other values are left alone. Sending null would CLEAR a value.
+    await g8.objects.updateRecord("invoices", record.id, { status: "overdue" }, { expectedRevision: record.revision });
+  } catch (err) {
+    if (err instanceof G8Error && err.status === 409) continue; // changed since we read it: skip, a later run picks it up
+    throw err;
+  }
+}
+
+// 3. What changed, and who changed it.
+if (overdue[0]) {
+  const changes = await g8.objects.changes("invoices", overdue[0].id, { limit: 10 });
+  for (const entry of changes.entries) console.log(entry.occurred_at, entry.action, entry.actor_type, Object.keys(entry.changes));
+
+  // 4. Archive hides the record but keeps it and its history; restore brings it back.
+  await g8.objects.archiveRecord("invoices", overdue[0].id);
+  await g8.objects.restoreRecord("invoices", overdue[0].id);
+}