@graph8/sdk 0.303.0 → 0.357.0

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

@@ -0,0 +1,111 @@
+"use client";
+
+/**
+ * Shapes the copilot block reads, and the helpers that turn the copilot's `events` array into something a
+ * chat bubble can show. `POST /copilot/chat` answers `{ response, events }` in one piece (no streaming):
+ * `events` is every text, tool and source event, in order.
+ */
+
+import type { G8Envelope } from "@/g8/lib/g8-client";
+
+export interface CopilotEvent {
+  type: string;
+  content?: string;
+  tool_name?: string;
+  inputs?: unknown;
+  result?: unknown;
+  sources?: unknown[];
+  message?: string;
+  [key: string]: unknown;
+}
+
+export interface CopilotReply {
+  response?: string;
+  events?: CopilotEvent[];
+  session_id?: string;
+}
+
+export interface ChatTurn {
+  id: number;
+  role: "user" | "assistant";
+  text: string;
+  /** Tools the copilot ran for this reply, in order. */
+  tools?: string[];
+  /** Tools it proposed but that need a person's approval before they run. */
+  needsApproval?: string[];
+  sources?: number;
+  error?: boolean;
+}
+
+export interface MentionHit {
+  id?: string;
+  type?: string;
+  label?: string;
+  name?: string;
+  title?: string;
+  [key: string]: unknown;
+}
+
+export interface MemoryRow {
+  id?: string;
+  memory_id?: string;
+  content: string;
+  scope?: string;
+  created_at?: string;
+}
+
+export interface ToolRow {
+  name: string;
+  description?: string;
+  requires_approval?: boolean;
+  needs_approval?: boolean;
+}
+
+export interface WorkChannel {
+  id?: string;
+  name?: string;
+  displayName?: string;
+  kind?: string;
+  description?: string;
+}
+
+export interface WorkMessageRow {
+  id?: string;
+  text?: string;
+  createdAt?: string;
+  author?: { name?: string; displayName?: string; kind?: string; type?: string } | null;
+}
+
+export function bodyOf<T = Record<string, unknown>>(res: G8Envelope<unknown> | null | undefined): T {
+  const data = (res as { data?: unknown } | null | undefined)?.data;
+  return (data ?? res ?? {}) as T;
+}
+
+export function listOf<T>(res: G8Envelope<unknown> | null | undefined, ...keys: string[]): T[] {
+  const body = bodyOf<unknown>(res);
+  if (Array.isArray(body)) return body as T[];
+  const rec = (body ?? {}) as Record<string, unknown>;
+  for (const k of keys) if (Array.isArray(rec[k])) return rec[k] as T[];
+  return [];
+}
+
+/** Fold a reply into what the bubble shows. Text comes from `response`, else from the text events. */
+export function summariseReply(reply: CopilotReply | undefined, id: number): ChatTurn {
+  const events = reply?.events ?? [];
+  const tools = events.filter((e) => e.type === "tool_start" && e.tool_name).map((e) => String(e.tool_name));
+  const needsApproval = events.filter((e) => e.type === "approval_required").map((e) => String(e.tool_name ?? e.message ?? "an action"));
+  const text = reply?.response ?? events.filter((e) => e.type === "text").map((e) => e.content ?? "").join("");
+  const done = events.find((e) => e.type === "done");
+  const failure = events.find((e) => e.type === "error");
+  return {
+    id,
+    role: "assistant",
+    text: failure && !text ? String(failure.message ?? failure.content ?? "The copilot hit an error.") : text,
+    tools: tools.length ? tools : undefined,
+    needsApproval: needsApproval.length ? needsApproval : undefined,
+    sources: Array.isArray(done?.sources) ? done.sources.length : undefined,
+    error: Boolean(failure && !text),
+  };
+}
+
+export const mentionLabel = (m: MentionHit): string => String(m.label ?? m.name ?? m.title ?? m.id ?? "mention");

package/blocks/copilot/recipes/ask-the-copilot.ts

@@ -0,0 +1,35 @@
+/**
+ * @title Ask the copilot a question and read its answer and tool events
+ * @when Server-side copilot calls (a cron summary, a Slack bot). `chatWithCopilot` is billable and answers in
+ * one piece: `response` is the full text and `events` is every text, tool and source event in order. There
+ * is no stream. Tools that need a person's approval are PROPOSED as `approval_required` events and are not
+ * executed; the person approves them in the graph8 app. `research` costs the most, then `thinking`, then
+ * `web_search`; a 402 means the workspace is out of credit.
+ */
+import { g8, G8Error } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function ask(message: string, history: Array<{ role: "user" | "assistant"; content: string }> = []) {
+  try {
+    const res = await g8.api.copilot.chatWithCopilot({
+      body: { message, conversation_history: history, web_search: false, thinking: false, research: false },
+    });
+    const data = res.data as { response?: string; events?: Array<{ type: string; tool_name?: string }> };
+    const events = data.events ?? [];
+    return {
+      answer: data.response ?? "",
+      toolsUsed: events.filter((e) => e.type === "tool_start").map((e) => e.tool_name),
+      needsApproval: events.filter((e) => e.type === "approval_required").map((e) => e.tool_name),
+    };
+  } catch (err) {
+    if (err instanceof G8Error && err.status === 402) return { answer: "", outOfCredit: true as const };
+    throw err;
+  }
+}
+
+/** What the copilot can call, and which of those need a person's approval. Free. */
+export async function toolCatalog() {
+  const res = await g8.api.copilot.listCopilotTools();
+  return res.data.items ?? [];
+}

package/blocks/copilot/recipes/post-in-a-work-channel.ts

@@ -0,0 +1,33 @@
+/**
+ * @title Post in a Work channel, ask an agent, and read the reply
+ * @when Putting a question to a teammate or an agent in a shared channel. Mentioning an agent starts an agent
+ * turn in the background: the send returns as soon as the message is stored and the answer shows up as a new
+ * message, so poll the conversation (newest first). The channel id comes from `listWorkChannels`; agent ids
+ * from `listWorkAgents`. An organisation key may only post in the built-in channels (403 elsewhere).
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+export async function askInChannel(question: string) {
+  const channels = await g8.api.work.listWorkChannels();
+  const channel = channels.data.channels?.[0];
+  if (!channel?.id) throw new Error("No channel this key may use");
+  const agents = await g8.api.work.listWorkAgents({ query: { limit: 50 } });
+  const agent = agents.data.items?.[0];
+
+  const sent = await g8.api.work.createWorkMessage({
+    body: { channel: channel.id, message: question, mentionAgentIds: agent?.agent_id ? [agent.agent_id] : undefined },
+  });
+  const sentId = (sent.data as { id?: string }).id;
+
+  for (let i = 0; i < 20; i++) {
+    await sleep(3000);
+    const page = await g8.api.work.listWorkConversationMessages({ path: { conversation_id: channel.id }, query: { limit: 10 } });
+    const newer = (page.data.messages ?? []).find((m) => m.id !== sentId && (m.createdAt ?? "") > ((sent.data as { createdAt?: string }).createdAt ?? ""));
+    if (newer) return newer.text;
+  }
+  return null;
+}

package/blocks/copilot/recipes/remember-and-recall.ts

@@ -0,0 +1,19 @@
+/**
+ * @title Teach the copilot a standing fact and forget it again
+ * @when A rule should shape every answer ("never discount below 15%", "we sell to mid-market only").
+ * Memories are read on every chat, so keep them short and true. The id to forget comes from the list
+ * response, never a guess. Forgetting is permanent.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function remember(content: string) {
+  await g8.api.copilot.createCopilotMemory({ body: { content, scope: "user" } });
+  const list = await g8.api.copilot.listCopilotMemories({ query: { scope: "user", limit: 100 } });
+  return list.data.items ?? [];
+}
+
+export async function forget(memoryId: string) {
+  return g8.api.copilot.deleteCopilotMemory({ path: { memory_id: memoryId } });
+}

package/blocks/crm/README.md

@@ -0,0 +1,122 @@
+# crm: contacts and companies
+
+The base every other block builds on. Ten editable components: tables, detail pages, a create/edit form
+that understands the org's custom fields, notes, tasks, an activity feed, a file import wizard and a
+duplicate-review screen. Other blocks embed these (a list shows a `ContactTable`, search saves into a
+list, the dialer opens a `ContactDetail`), so their props are part of the contract: keep them when you edit.
+
+Install: `npx @graph8/sdk add crm` (installs `foundation` first).
+
+## What you get
+
+| Component | Use it for | Embed props |
+|---|---|---|
+| `ContactTable` | Contacts grid: filters, paging, selection, bulk delete, custom-field columns | `listId`, `companyId`, `selectable`, `customFields`, `onOpen`, `onSelectionChange`, `renderBulkActions`, `toolbar`, `refreshKey` |
+| `ContactDetail` | One contact: header, editable overview, Activity / Notes / Tasks tabs | `contactId`, `renderActions`, `extraTabs`, `onOpenCompany`, `onDeleted` |
+| `CompanyTable` | Companies grid, same shape as `ContactTable` | same minus `listId`/`companyId` |
+| `CompanyDetail` | One company: overview, People tab (a `ContactTable`), Activity / Notes / Tasks | `companyId`, `renderActions`, `extraTabs`, `onOpenContact`, `onDeleted` |
+| `RecordForm` | Create or edit a contact or company, with custom fields | `entity`, `record`, `listId`, `onSaved`, `onDuplicate` |
+| `ActivityTimeline` | Combined feed (notes, tasks, emails, calls, meetings, changes) | `entityType`, `entityId`, `types`, `refreshKey` |
+| `NotesPanel` / `TaskList` | Notes and tasks on a record | `entity`, `entityId`, `onChanged` |
+| `ImportWizard` | CSV/Excel into a list | `listId`, `onImported` |
+| `DedupeReview` | Duplicate suggestions, merge, undo | `entity`, `onChanged` |
+
+Hooks: `usePageQuery` (page-number pagination, resets on filter change), `useCustomFields` and `useDebouncedValue`. `ImportWizard` refuses files over `maxBytes` (default 5 MiB, the proxy cap) with a pointer to the prerequisite.
+
+## The flow, with the ids that pass between steps
+
+1. **List**: `ContactTable` calls `GET /contacts?page&limit&...` and gets `{ data: [{ id, ... }], pagination: { total, has_next } }`.
+2. **Open**: a row click hands you the contact; route to `ContactDetail contactId={row.id}`.
+3. **Detail**: `GET /contacts/{id}?include_custom_fields=true`. `contact.company.id` is the id for `CompanyDetail`.
+4. **Edit**: `RecordForm record={contact}` sends only changed base fields (`PATCH /contacts/{id}`) and changed
+   custom values (`PATCH /fields/values/batch` with `column_id` from `GET /fields`).
+5. **Create**: `RecordForm entity="contact"` posts `/contacts`; the response `contact_id` goes to `onSaved`.
+   A 409 means the contact exists: `onDuplicate(existingId)` receives its id (open it instead).
+6. **Activity**: notes and tasks write, then `onChanged` bumps `refreshKey` so `ActivityTimeline` reloads.
+7. **Import**: `POST /imports` (file) -> `datafile_id`; `POST /imports/{datafile_id}/preview` with the mapping;
+   `POST /imports/{datafile_id}/contacts` with `list_id`, `column_mapping`, `update_policy`.
+8. **Dedupe**: `GET /duplicates?entity_type=contact` -> `suggestion_id`, `a_id`, `b_id`; merge posts
+   `/contacts/{keep_id}/merge` with `secondary_id` and `suggestion_id`.
+
+Minimal screen (`add` installs under `components/g8/crm/`, or `src/components/g8/crm/`; adjust the import alias):
+
+```tsx
+"use client";
+import { useState } from "react";
+import { ContactTable } from "@/components/g8/crm/contact-table";
+import { ContactDetail } from "@/components/g8/crm/contact-detail";
+
+export default function ContactsPage() {
+  const [openId, setOpenId] = useState<number | null>(null);
+  return openId ? <ContactDetail contactId={openId} onDeleted={() => setOpenId(null)} />
+                 : <ContactTable customFields selectable onOpen={(c) => setOpenId(c.id)} />;
+}
+```
+
+## Locked (masked) fields
+
+Credit-locked contacts come back with `work_email: "***"` (also phones). The components show **Locked** and
+never copy, link or send the placeholder. To reveal: save the contact into a list (see the `search` block) or
+enrich it (see `enrichment`). Do not "fix" a masked value by editing it: writing `"***"` back would store it.
+
+## Tiers and confirmations
+
+Reads and writes run directly. Everything `destructive` goes through `ConfirmSpendDialog`: deleting contacts
+or companies (tables and detail pages), deleting notes and tasks, merging duplicates, bulk merge. The import
+asks first when it overwrites existing values or fills fields from graph8 (credits). Nothing here sends a
+message to a person.
+
+## Prerequisites (the human or app owner must do these)
+
+- `proxy-allowlist` (app): `allowedPrefixes` in `app/api/g8/[...path]/route.ts` includes `contacts`, `companies`,
+  `fields`, `notes`, `tasks`, `activity-feed`, `imports`, `duplicates`, `lists`, and `authorize` checks your session.
+- `api-key-scopes` (api): the server key has the scopes in `block.json` (`contacts:delete` is needed for bulk merge).
+- `import-size-limit` (app): the proxy caps bodies at 5 MiB; larger files need a raised cap or a server-side import.
+
+## Defaults the agent can use without asking
+
+| Decision | Default |
+|---|---|
+| List new contacts join | none (pass `listId` to choose) |
+| Import update policy | `autofill` (fill blanks only); overwrite is opt-in |
+| Fill missing import fields from graph8 | off (uses credits) |
+| Table page size | 25 |
+
+Ask the person: who may delete or merge records (decide it in the proxy's `authorize`).
+
+## Recipes
+
+| File | Does |
+|---|---|
+| `recipes/upsert-contact-with-company.ts` | Idempotent contact write with company link and custom fields, read back by email |
+| `recipes/custom-fields-and-values.ts` | Create a field, batch-write values |
+| `recipes/notes-tasks-and-activity.ts` | Log a note and task, read the feed |
+| `recipes/dedupe-and-merge.ts` | List, preview and (after a human says so) merge duplicates |
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| listContacts | GET /contacts | read | ContactTable |
+| getContact | GET /contacts/{contact_id} | read | ContactDetail |
+| createContacts | POST /contacts | write | RecordForm |
+| updateContact | PATCH /contacts/{contact_id} | write | RecordForm |
+| deleteContact | DELETE /contacts/{contact_id} | destructive | ContactTable, ContactDetail |
+| listCompanies / getCompany | GET /companies, /companies/{company_id} | read | CompanyTable, CompanyDetail |
+| createCompany / updateCompany | POST /companies, PATCH /companies/{company_id} | write | RecordForm |
+| deleteCompany | DELETE /companies/{company_id} | destructive | CompanyTable, CompanyDetail |
+| listContactFields / listCompanyFields | GET /fields, /fields/companies | read | tables, RecordForm |
+| createField / setFieldValuesBatch | POST /fields, PATCH /fields/values/batch | write | RecordForm |
+| getActivityFeed | GET /activity-feed | read | ActivityTimeline |
+| listNotes / listCompanyNotes | GET /contacts/{id}/notes, /companies/{id}/notes | read | NotesPanel |
+| createNote / createCompanyNote / updateNote | POST, PATCH /notes/{note_id} | write | NotesPanel |
+| deleteNote | DELETE /notes/{note_id} | destructive | NotesPanel |
+| listContactTasks / listCompanyTasks | GET .../tasks | read | TaskList |
+| createTask / createCompanyTask / updateTask | POST, PATCH /tasks/{task_id} | write | TaskList |
+| deleteTask | DELETE /tasks/{task_id} | destructive | TaskList |
+| uploadImportFile / previewImportFile / importContacts | POST /imports... | write / read / write | ImportWizard |
+| listLists / createList | GET, POST /lists | read / write | ImportWizard |
+| duplicateCounts / listDuplicates / listRecentMerges / getBulkMergeStatus | GET /duplicates... | read | DedupeReview |
+| rejectSuggestion / startBulkMerge / undoMerge | POST /duplicates... | write | DedupeReview |
+| mergeContact / mergeCompany | POST /contacts/{id}/merge, /companies/{id}/merge | destructive | DedupeReview |
+| assertContact, assertCompany (+ batch) | PUT /contacts/assert, /companies/assert | write | recipes (`g8.contacts.upsert`) |