lemma-sdk 0.2.28 → 0.2.31

package/README.md

@@ -1,294 +1,334 @@
-# Lemma TypeScript SDK (`lemma-sdk`)
+# Lemma TypeScript SDK
 
-Official TypeScript SDK for Lemma APIs with:
+`lemma-sdk` is the headless TypeScript SDK for Lemma. Use `lemma-sdk` for the core client, `lemma-sdk/react` for hooks and auth primitives, and the Lemma shadcn registry for stock UI blocks.
 
-- Pod-scoped namespaces (`tables`, `records`, `files`, `assistants`,`agents` , `workflows`, `tasks`, .)
-- Built-in auth/session handling
-- SSE streaming helpers
-- React hooks and assistant UI components
+`AuthGuard` intentionally stays in `lemma-sdk/react`. Stock assistant, table, workflow, agent, member, and function UI lives in the registry.
 
 ## Install
 
 ```bash
-npm i lemma-sdk
+npm install lemma-sdk
 ```
 
-## Quick Start
+If your app uses shadcn/ui, configure the Lemma registry with:
+
+```bash
+npx lemma-sdk init-shadcn
+```
+
+That adds this namespace to your app's `components.json`:
+
+```json
+{
+  "registries": {
+    "@lemma": "https://cdn.jsdelivr.net/gh/gappyai/lemma-typescript@main/public/r/{name}.json"
+  }
+}
+```
+
+If your app does not have `components.json` yet, run `npx shadcn@latest init` first or after the command above.
+
+## Core Client
 
 ```ts
 import { LemmaClient } from "lemma-sdk";
 
 const client = new LemmaClient({
-  apiUrl: "https://api.lemma.work",
-  authUrl: "https://auth.lemma.work/auth",
   podId: "<pod-id>",
 });
 
 await client.initialize();
 
 const tables = await client.tables.list();
-const assistants = await client.assistants.list({ limit: 20 });
-const supportAssistant = await client.assistants.get("support_assistant");
+const records = await client.records.list("tickets");
 ```
 
-## Configuration
+Pod-scoped namespaces include `tables`, `records`, `assistants`, `agents`, `tasks`, `workflows`, `functions`, `files`, `desks`, `integrations`, `resources`, and `datastore`.
+
+Org and user surfaces include `users`, `organizations`, `pods`, `podMembers`, `podJoinRequests`, and `podSurfaces`.
 
-`LemmaClient` config resolution order:
+## React Package
 
-1. Constructor overrides
-2. `window.__LEMMA_CONFIG__`
-3. Environment variables
-4. Defaults
+Install React if your app needs hooks:
 
-Supported env keys:
+```bash
+npm install react react-dom
+```
 
-- `VITE_LEMMA_API_URL`, `REACT_APP_LEMMA_API_URL`, `LEMMA_API_URL`
-- `VITE_LEMMA_AUTH_URL`, `REACT_APP_LEMMA_AUTH_URL`, `LEMMA_AUTH_URL`
-- `VITE_LEMMA_POD_ID`, `REACT_APP_LEMMA_POD_ID`, `LEMMA_POD_ID`
+`lemma-sdk/react` is headless-first. It exports hooks plus `AuthGuard`; it does not export stock UI components or CSS.
 
-Defaults when unset:
+```tsx
+import {
+  AuthGuard,
+  useAgentRun,
+  useConversationMessages,
+  useConversations,
+  useRecords,
+  useSchemaForm,
+  useWorkflowStart,
+} from "lemma-sdk/react";
+```
 
-- `apiUrl`: `http://localhost:8000`
-- `authUrl`: `http://localhost:3000`
+### Hook Matrix
 
-## Pod Scoping
+| Area | Hooks | Stability | Use when |
+| --- | --- | --- | --- |
+| Auth | `AuthGuard`, `useAuth`, `useCurrentUser`, `usePodAccess` | Stable | Gate an app, read signed-in user state, or request pod access. |
+| Tables | `useTables`, `useTable`, `useRecords`, `useRecord`, `useJoinedRecords`, `useRelatedRecords`, `useReverseRelatedRecords` | Stable | Build custom table browsers, details views, related-record views, and relational reads. |
+| Record mutations | `useCreateRecord`, `useUpdateRecord`, `useDeleteRecord`, `useBulkRecords` | Stable | Create, update, delete, or bulk-delete rows from headless UI. |
+| Record forms | `useRecordSchema`, `useRecordForm`, `useForeignKeyOptions`, `useSchemaForm` | Stable | Render schema-driven forms, enum fields, and foreign-key selectors. |
+| Assistant | `useConversations`, `useConversation`, `useConversationMessages`, `useAssistantRun`, `useAssistantSession`, `useAssistantRuntime`, `useAssistantController` | Stable except controller/runtime | Build custom chat, conversation lists, streaming output, and final-output views. |
+| Agents | `useAgentRun`, `useAgentRuns`, `useAgentInputSchema`, `useTaskSession` | Stable except raw session | Start agent tasks, submit follow-up input, read task history, and inspect input/output schemas. |
+| Workflows | `useWorkflowStart`, `useWorkflowRun`, `useWorkflowRuns`, `useWorkflowResume` | Stable | Start, poll, resume, cancel, retry, and inspect workflow runs. |
+| Workflow compatibility | `useFlowSession`, `useFlowRunHistory` | Deprecated naming | Kept for existing callers; prefer workflow-named hooks for new code. |
+| Functions | `useFunctionRun`, `useFunctionRuns`, `useFunctionSession` | Stable except raw session | Run functions, poll function runs, and list function history. |
+| Members and org | `useMembers`, `useOrganizationMembers` | Stable | Read pod and organization member lists. `useMembers` is intentionally read-only. |
 
-Most namespaces are pod-scoped. You can set pod scope in three ways:
+### Common Hook Shapes
 
-```ts
-client.setPodId("pod_a");
+List hooks generally expose:
 
-const podBClient = client.withPod("pod_b");
+- `items` named for the resource, such as `records`, `runs`, or `members`
+- `isLoading`
+- `error`
+- `nextPageToken`
+- `refresh(...)`
+- `loadMore(...)` where pagination is useful
 
-const conversations = await client.conversations.list({ pod_id: "pod_c" });
-```
+Run hooks generally expose:
 
-## Namespace Overview
+- `run` or `task`
+- `status`
+- `isPolling`, `isStreaming`, or `isRunning`
+- `output`
+- `finalOutput`
+- `start(...)`
+- `refresh(...)`
+- follow-up helpers such as `resume(...)`, `submitInput(...)`, `cancel(...)`, or `retry(...)`
 
-Common pod-scoped namespaces:
+### Headless Examples
 
-- `client.tables`
-- `client.records`
-- `client.files`
-- `client.functions`
-- `client.agents`
-- `client.tasks`
-- `client.assistants`
-- `client.workflows`
-- `client.desks`
-- `client.integrations`
-- `client.resources`
+Records:
 
-Org/user-level namespaces:
+```tsx
+import { LemmaClient } from "lemma-sdk";
+import { useRecords } from "lemma-sdk/react";
 
-- `client.users`
-- `client.icons`
-- `client.pods`
-- `client.podMembers`
-- `client.podJoinRequests`
-- `client.organizations`
-- `client.podSurfaces`
+const client = new LemmaClient({ podId: "<pod-id>" });
 
-Escape hatch for unmapped endpoints:
+function TicketList() {
+  const tickets = useRecords({
+    client,
+    tableName: "tickets",
+    limit: 25,
+    sortBy: "created_at",
+    order: "desc",
+  });
 
-```ts
-const result = await client.request("GET", "/models");
+  if (tickets.error) return <p>{tickets.error.message}</p>;
+
+  return (
+    <ul>
+      {tickets.records.map((ticket) => (
+        <li key={String(ticket.id)}>{String(ticket.title ?? ticket.id)}</li>
+      ))}
+    </ul>
+  );
+}
 ```
 
-## CRUD Examples
+Assistant final output:
 
-### Tables + Records
+```tsx
+import { useConversationMessages, useConversations } from "lemma-sdk/react";
 
-```ts
-await client.tables.create({ name: "todos" });
+function SupportThread({ client }: { client: LemmaClient }) {
+  const conversations = useConversations({
+    client,
+    assistantName: "support_assistant",
+  });
 
-await client.records.create("todos", {
-  title: "Ship docs rewrite",
-  status: "todo",
-});
+  const messages = useConversationMessages({
+    client,
+    conversationId: conversations.effectiveSelectedConversationId,
+    autoResume: true,
+  });
 
-const page = await client.records.list("todos", {
-  limit: 20,
-  sort: [{ field: "created_at", direction: "desc" }],
-});
+  return <pre>{messages.finalOutputText || messages.outputText || "No output yet."}</pre>;
+}
 ```
 
-### Files (Datastore)
+Agent run:
 
-```ts
-await client.files.folder.create("reports", { directoryPath: "/" });
-await client.files.upload(fileBlob, { directoryPath: "/reports", name: "q1.pdf" });
+```tsx
+import { useAgentRun } from "lemma-sdk/react";
+
+function AgentButton({ client }: { client: LemmaClient }) {
+  const agent = useAgentRun({
+    client,
+    agentName: "triage_agent",
+  });
 
-const listing = await client.files.list({ directoryPath: "/reports" });
-const downloaded = await client.files.download("/reports/q1.pdf");
+  return (
+    <button
+      disabled={agent.isStreaming}
+      onClick={() => {
+        void agent.start({ ticket_id: "ticket_123" });
+      }}
+    >
+      {agent.status ?? "Run agent"}
+    </button>
+  );
+}
 ```
 
-### Assistants + Conversations
+Workflow run:
 
-```ts
-await client.assistants.create({
-  name: "support_assistant",
-  instruction: "Help with support triage.",
-});
+```tsx
+import { useWorkflowRun } from "lemma-sdk/react";
 
-const conversation = await client.conversations.createForAssistant("support_assistant", {
-  title: "Ticket review",
-});
+function WorkflowButton({ client }: { client: LemmaClient }) {
+  const workflow = useWorkflowRun({
+    client,
+    workflowName: "approve_ticket",
+  });
 
-await client.conversations.messages.send(conversation.id, {
-  content: "Summarize unresolved issues from today.",
-});
+  return (
+    <button
+      disabled={workflow.isPolling}
+      onClick={() => {
+        void workflow.start({ ticket_id: "ticket_123" });
+      }}
+    >
+      {workflow.status ?? "Start workflow"}
+    </button>
+  );
+}
 ```
 
-### Pod Join Requests
+## Shadcn Registry
 
-```ts
-// Current user requests access to a pod
-await client.podJoinRequests.create("pod_123");
+Lemma UI lives in the registry, not in `lemma-sdk/react`.
 
-// Current user's pending request (or null)
-const mine = await client.podJoinRequests.me("pod_123");
+After running `npx lemma-sdk init-shadcn`, install blocks like:
 
-// Admin view of requests for a pod
-const requests = await client.podJoinRequests.list("pod_123", {
-  status: "PENDING",
-  limit: 50,
-});
-
-// Admin approval (defaults: ORG_MEMBER + POD_USER)
-await client.podJoinRequests.approve("pod_123", "join_req_abc", {
-  org_role: "ORG_MEMBER",
-  pod_role: "POD_USER",
-});
+```bash
+npx shadcn@latest add @lemma/lemma-records-page
+npx shadcn@latest add @lemma/lemma-agent-runner-page
+npx shadcn@latest add @lemma/lemma-workflow-launcher-page
+npx shadcn@latest add @lemma/lemma-function-runner-page
 ```
 
-## Streaming (SSE)
+Current registry items:
 
-Use `readSSE` + `parseSSEJson` for incremental events.
+| Area | Items |
+| --- | --- |
+| Assistant | `lemma-assistant-experience`, `lemma-assistant-embedded` |
+| Schema | `lemma-schema-form` |
+| Tables | `lemma-table-picker`, `lemma-record-picker`, `lemma-record-filters-bar`, `lemma-records-table`, `lemma-record-details-card`, `lemma-record-form`, `lemma-related-records-table`, `lemma-reverse-related-records-table`, `lemma-bulk-actions-bar`, `lemma-records-page` |
+| Agents | `lemma-agent-run-panel`, `lemma-agent-output-card`, `lemma-agent-messages`, `lemma-agent-runner-page` |
+| Workflows | `lemma-workflow-start-form`, `lemma-workflow-history`, `lemma-workflow-run-status`, `lemma-workflow-run-details`, `lemma-workflow-launcher-page` |
+| Members and access | `lemma-members-table`, `lemma-member-picker`, `lemma-org-member-picker`, `lemma-pod-access-card` |
+| Functions | `lemma-function-run-panel`, `lemma-function-run-history`, `lemma-function-runner-page` |
 
-```ts
-import { readSSE, parseSSEJson } from "lemma-sdk";
+The registry is currently served from jsDelivr against this public repo:
 
-const stream = await client.conversations.sendMessageStream(conversationId, {
-  content: "Analyze recent incidents",
-});
+- registry root: `https://cdn.jsdelivr.net/gh/gappyai/lemma-typescript@main/public/r/registry.json`
+- item shape: `https://cdn.jsdelivr.net/gh/gappyai/lemma-typescript@main/public/r/{name}.json`
 
-for await (const event of readSSE(stream)) {
-  const payload = parseSSEJson(event);
-  if (!payload) continue;
-  console.log(event.event, payload);
-}
-```
+For more stable installs, pin the registry URL to a tag or commit SHA instead of `@main`.
 
-Task stream example:
+### Records Workspace Customization
 
-```ts
-const task = await client.tasks.create({
-  agent_name: "triage_agent",
-  input_data: { ticketId: "TCK-1042" },
-});
+The records blocks are meant to be configured with props before you reach for a fork.
 
-const taskStream = await client.tasks.stream(task.id);
-```
+`lemma-records-page` supports:
 
-## Access Grants (`accessible_tables`)
+- capability toggles such as `allowCreate`, `allowEdit`, `allowSelection`, `allowBulkDelete`, `allowSearch`, `allowFilters`, `allowSorting`, `allowPageSizeSelect`, and `allowColumnVisibility`
+- layout toggles such as `showTablePicker`, `showRecordPicker`, and `showRecordDetails`
+- column control through `columns`, `hiddenColumnNames`, `defaultHiddenColumnNames`, and `onHiddenColumnNamesChange`
+- non-`id` primary keys through `recordIdField` or `getRecordId`
+- record-form overrides through `recordFormHiddenFields`, `recordFormFieldOrder`, `recordFormFieldLabels`, `recordFormFieldDescriptions`, `createFormTitle`, `editFormTitle`, `createSubmitLabel`, and `editSubmitLabel`
 
-When creating agents/functions/assistants, `accessible_tables` must use object entries:
+`lemma-records-table` supports richer column definitions:
 
-```ts
-import { TableAccessMode } from "lemma-sdk";
+- `label`, `description`, `type`, `width`, `minWidth`, `align`
+- `searchable`, `hideable`, `hidden`
+- `renderCell(...)` for custom cell output
+- per-row buttons through `rowActions`
 
-accessible_tables: [
-  { table_name: "expenses", mode: TableAccessMode.READ },
-  { table_name: "expense_notes", mode: TableAccessMode.WRITE },
+```tsx
+import { LemmaRecordsPage } from "@/components/lemma/lemma-records-page";
+import type { LemmaRecordsTableColumn } from "@/components/lemma/lemma-records-table";
+
+const columns: LemmaRecordsTableColumn[] = [
+  { name: "item_id", label: "Item ID", hideable: false, width: 180 },
+  { name: "group_id", label: "Group", width: 160 },
+  { name: "name", label: "Name", minWidth: 320, searchable: true },
+  {
+    name: "sellable",
+    label: "Sellable",
+    type: "boolean",
+    width: 120,
+    align: "center",
+    renderCell: ({ value }) => (value ? "Yes" : "No"),
+  },
 ];
-```
 
-`["expenses"]` is not valid.
+<LemmaRecordsPage
+  allowColumnVisibility
+  allowCreate
+  allowEdit
+  columns={columns}
+  createButtonLabel="New SKU"
+  defaultHiddenColumnNames={["group_id"]}
+  editSubmitLabel="Save SKU"
+  recordFormFieldLabels={{ item_id: "Item ID" }}
+  recordIdField="item_id"
+  tableName="catalog_items"
+/>;
+```
 
 ## Auth
 
-Default mode is cookie/session auth (`credentials: "include"`).
+The SDK uses cookie or session auth by default.
 
-For local browser testing, token injection is supported via local storage key `lemma_token`:
-
-```ts
-import { setTestingToken, clearTestingToken } from "lemma-sdk";
-
-setTestingToken("<access-token>");
-clearTestingToken();
-```
-
-Auth helpers:
+Useful helpers:
 
 - `buildAuthUrl(...)`
 - `buildFederatedLogoutUrl(...)`
 - `resolveSafeRedirectUri(...)`
-- `client.auth.redirectToAuth(...)`
-- `client.auth.redirectToFederatedLogout(...)`
-
-## React Package (`lemma-sdk/react`)
+- `setTestingToken(...)`
+- `clearTestingToken()`
 
-Includes auth helpers, run hooks, and assistant UI primitives.
+When `client.podId` is set and the signed-in user is not a pod member, `AuthGuard` can render the request-access flow and create or show pod join requests.
 
-Install React peer dependency in your app if not already installed:
-
-```bash
-npm i react react-dom
-```
+`usePodAccess` exposes the same membership/request-access state as a hook for custom UI.
 
-Import stylesheet once:
+## Migration Notes
 
-```tsx
-import "lemma-sdk/react/styles.css";
-```
+From `0.2.30` onward:
 
-Fastest assistant integration:
+- `lemma-sdk/react` should be treated as hooks plus auth primitives.
+- `AuthGuard` remains in `lemma-sdk/react`.
+- Stock UI should be installed from the shadcn registry.
+- Assistant UI source and CSS are no longer part of the React SDK internals.
+- `react-markdown` and `remark-gfm` are registry-block dependencies for assistant UI, not core SDK dependencies.
+- New workflow code should prefer `useWorkflowRun`, `useWorkflowRuns`, and `useWorkflowResume` over the older `flow`-named hooks.
 
-```tsx
-import { AssistantEmbedded } from "lemma-sdk/react";
-
-<div style={{ height: 720, minHeight: 0 }}>
-  <AssistantEmbedded
-    client={client}
-    podId="<pod-id>"
-    assistantName="support_assistant"
-    title="Support Assistant"
-    placeholder="Message Support Assistant"
-    showConversationList
-  />
-</div>;
-```
+## Local Development
 
-Auth guard example:
+From the root of this repository:
 
-```tsx
-import { AuthGuard } from "lemma-sdk/react";
-
-<AuthGuard client={client}>
-  <App />
-</AuthGuard>;
+```bash
+npm install
+npm run build
+npm run registry:build
 ```
 
-When `client.podId` is set and the signed-in user is not a pod member, `AuthGuard` automatically renders a request-access state and can create/view pod join requests.
-
-## Browser Bundle
-
-The package also ships a standalone browser bundle:
+This repo includes:
 
-- npm artifact path: `dist/browser/lemma-client.js`
-- export path: `lemma-sdk/browser-bundle`
-- global: `window.LemmaClient.LemmaClient`
-
-Example:
-
-```html
-<script src="https://unpkg.com/lemma-sdk@latest/dist/browser/lemma-client.js"></script>
-<script>
-  const client = new window.LemmaClient.LemmaClient({
-    apiUrl: "https://api.lemma.work",
-    authUrl: "https://auth.lemma.work/auth",
-    podId: "<pod-id>"
-  });
-</script>
-```
+- `registry.json` for registry source definitions
+- `public/r` for the generated flat registry output
+- `.github/workflows/deploy-registry-pages.yml` for GitHub Pages deployment
+- `.github/workflows/publish-npm.yml` for npm publishing

package/bin/lemma-sdk.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const SHADCN_SCHEMA_URL = "https://ui.shadcn.com/schema.json";
+const LEMMA_REGISTRY_URL =
+  "https://cdn.jsdelivr.net/gh/gappyai/lemma-typescript@main/public/r/{name}.json";
+
+function printUsage() {
+  console.log(`Usage:
+  lemma-sdk init-shadcn
+
+Commands:
+  init-shadcn   Add the @lemma shadcn registry to components.json in the current directory.`);
+}
+
+function fail(message) {
+  console.error(`lemma-sdk: ${message}`);
+  process.exit(1);
+}
+
+function ensureObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    fail(`${label} must be a JSON object.`);
+  }
+
+  return value;
+}
+
+function loadComponentsConfig(configPath) {
+  if (!existsSync(configPath)) {
+    return {
+      config: {
+        $schema: SHADCN_SCHEMA_URL,
+        registries: {},
+      },
+      existed: false,
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    fail(`Could not parse ${configPath}: ${message}`);
+  }
+
+  const config = ensureObject(parsed, "components.json");
+
+  if (config.$schema == null) {
+    config.$schema = SHADCN_SCHEMA_URL;
+  }
+
+  if (config.registries == null) {
+    config.registries = {};
+  }
+
+  ensureObject(config.registries, "components.json registries");
+
+  return {
+    config,
+    existed: true,
+  };
+}
+
+function writeComponentsConfig(configPath, config) {
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+function initShadcn() {
+  const configPath = resolve(process.cwd(), "components.json");
+  const { config, existed } = loadComponentsConfig(configPath);
+
+  const currentUrl = config.registries["@lemma"];
+  const alreadyConfigured = currentUrl === LEMMA_REGISTRY_URL;
+
+  config.registries["@lemma"] = LEMMA_REGISTRY_URL;
+  writeComponentsConfig(configPath, config);
+
+  if (alreadyConfigured) {
+    console.log(`@lemma is already configured in ${configPath}`);
+  } else if (existed) {
+    console.log(`Added @lemma registry to ${configPath}`);
+  } else {
+    console.log(`Created ${configPath} with the @lemma registry`);
+    console.log("If you have not initialized shadcn yet, run: npx shadcn@latest init");
+  }
+
+  console.log(`Registry URL: ${LEMMA_REGISTRY_URL}`);
+}
+
+const command = process.argv[2];
+
+switch (command) {
+  case "init-shadcn":
+    initShadcn();
+    break;
+  case "-h":
+  case "--help":
+  case "help":
+  case undefined:
+    printUsage();
+    break;
+  default:
+    fail(`Unknown command "${command}". Run "lemma-sdk --help" for usage.`);
+}