lemma-sdk 0.2.28 → 0.2.30

package/README.md

@@ -1,294 +1,174 @@
-# Lemma TypeScript SDK (`lemma-sdk`)
+# Lemma TypeScript SDK
 
-Official TypeScript SDK for Lemma APIs with:
-
-- Pod-scoped namespaces (`tables`, `records`, `files`, `assistants`,`agents` , `workflows`, `tasks`, .)
-- Built-in auth/session handling
-- SSE streaming helpers
-- React hooks and assistant UI components
+`lemma-sdk` is the headless TypeScript SDK for Lemma. Use `lemma-sdk/react` for hooks and auth primitives, and use the Lemma shadcn registry for stock UI blocks.
 
 ## Install
 
 ```bash
-npm i lemma-sdk
+npm install lemma-sdk
 ```
 
-## Quick Start
-
-```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();
+If your app uses shadcn/ui, configure the Lemma registry with:
 
-const tables = await client.tables.list();
-const assistants = await client.assistants.list({ limit: 20 });
-const supportAssistant = await client.assistants.get("support_assistant");
+```bash
+npx lemma-sdk init-shadcn
 ```
 
-## Configuration
-
-`LemmaClient` config resolution order:
-
-1. Constructor overrides
-2. `window.__LEMMA_CONFIG__`
-3. Environment variables
-4. Defaults
-
-Supported env keys:
-
-- `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`
-
-Defaults when unset:
-
-- `apiUrl`: `http://localhost:8000`
-- `authUrl`: `http://localhost:3000`
-
-## Pod Scoping
-
-Most namespaces are pod-scoped. You can set pod scope in three ways:
-
-```ts
-client.setPodId("pod_a");
-
-const podBClient = client.withPod("pod_b");
+That adds this namespace to your app's `components.json`:
 
-const conversations = await client.conversations.list({ pod_id: "pod_c" });
+```json
+{
+  "registries": {
+    "@lemma": "https://cdn.jsdelivr.net/gh/gappyai/lemma-typescript@main/public/r/{name}.json"
+  }
+}
 ```
 
-## Namespace Overview
-
-Common pod-scoped namespaces:
-
-- `client.tables`
-- `client.records`
-- `client.files`
-- `client.functions`
-- `client.agents`
-- `client.tasks`
-- `client.assistants`
-- `client.workflows`
-- `client.desks`
-- `client.integrations`
-- `client.resources`
+If your app does not have `components.json` yet, run `npx shadcn@latest init` first or after the command above.
 
-Org/user-level namespaces:
+## React Hooks
 
-- `client.users`
-- `client.icons`
-- `client.pods`
-- `client.podMembers`
-- `client.podJoinRequests`
-- `client.organizations`
-- `client.podSurfaces`
+Install React if your app needs it:
 
-Escape hatch for unmapped endpoints:
-
-```ts
-const result = await client.request("GET", "/models");
+```bash
+npm install react react-dom
 ```
 
-## CRUD Examples
+`lemma-sdk/react` is intentionally headless-first. It includes hooks plus `AuthGuard`, but not stock assistant or records UI.
 
-### Tables + Records
+```tsx
+import {
+  AuthGuard,
+  useAgentRun,
+  useConversationMessages,
+  useConversations,
+  useForeignKeyOptions,
+  useMembers,
+  useRecordForm,
+  useRecordSchema,
+  useRecords,
+  useSchemaForm,
+  useTables,
+  useWorkflowStart,
+} from "lemma-sdk/react";
+```
+
+Typical hook groups:
+
+- data tables: `useTables`, `useTable`, `useRecords`, `useRecord`, `useRelatedRecords`, `useReverseRelatedRecords`
+- record mutations and forms: `useCreateRecord`, `useUpdateRecord`, `useDeleteRecord`, `useBulkRecords`, `useRecordSchema`, `useRecordForm`, `useSchemaForm`
+- assistant and runs: `useConversation`, `useConversations`, `useConversationMessages`, `useAssistantController`, `useAssistantRun`, `useAgentRun`, `useWorkflowStart`
+- org and auth: `AuthGuard`, `useMembers`
+
+Minimal example:
 
-```ts
-await client.tables.create({ name: "todos" });
+```tsx
+import { LemmaClient } from "lemma-sdk";
+import { AuthGuard, useConversations, useConversationMessages } from "lemma-sdk/react";
 
-await client.records.create("todos", {
-  title: "Ship docs rewrite",
-  status: "todo",
-});
+const client = new LemmaClient({ podId: "<pod-id>" });
 
-const page = await client.records.list("todos", {
-  limit: 20,
-  sort: [{ field: "created_at", direction: "desc" }],
-});
-```
+function SupportThread() {
+  const conversations = useConversations({
+    client,
+    podId: "<pod-id>",
+    assistantName: "support_assistant",
+  });
 
-### Files (Datastore)
+  const thread = useConversationMessages({
+    client,
+    podId: "<pod-id>",
+    conversationId: conversations.effectiveSelectedConversationId,
+  });
 
-```ts
-await client.files.folder.create("reports", { directoryPath: "/" });
-await client.files.upload(fileBlob, { directoryPath: "/reports", name: "q1.pdf" });
+  return <pre>{thread.finalOutputText ?? "No assistant output yet."}</pre>;
+}
 
-const listing = await client.files.list({ directoryPath: "/reports" });
-const downloaded = await client.files.download("/reports/q1.pdf");
+export function App() {
+  return (
+    <AuthGuard client={client}>
+      <SupportThread />
+    </AuthGuard>
+  );
+}
 ```
 
-### Assistants + Conversations
+## Shadcn Registry
 
-```ts
-await client.assistants.create({
-  name: "support_assistant",
-  instruction: "Help with support triage.",
-});
+Lemma UI now lives in the registry, not in `lemma-sdk/react`.
 
-const conversation = await client.conversations.createForAssistant("support_assistant", {
-  title: "Ticket review",
-});
+After running `npx lemma-sdk init-shadcn`, install blocks like:
 
-await client.conversations.messages.send(conversation.id, {
-  content: "Summarize unresolved issues from today.",
-});
+```bash
+npx shadcn@latest add @lemma/lemma-records-page
+npx shadcn@latest add @lemma/lemma-assistant-embedded
+npx shadcn@latest add @lemma/lemma-workflow-start-form
 ```
 
-### Pod Join Requests
+Current registry items include:
 
-```ts
-// Current user requests access to a pod
-await client.podJoinRequests.create("pod_123");
-
-// Current user's pending request (or null)
-const mine = await client.podJoinRequests.me("pod_123");
+- `lemma-assistant-experience`
+- `lemma-assistant-embedded`
+- `lemma-schema-form`
+- `lemma-records-page`
+- `lemma-record-form`
+- `lemma-records-table`
+- `lemma-related-records-table`
+- `lemma-reverse-related-records-table`
+- `lemma-workflow-start-form`
 
-// Admin view of requests for a pod
-const requests = await client.podJoinRequests.list("pod_123", {
-  status: "PENDING",
-  limit: 50,
-});
+The registry is currently served from jsDelivr against this public repo:
 
-// Admin approval (defaults: ORG_MEMBER + POD_USER)
-await client.podJoinRequests.approve("pod_123", "join_req_abc", {
-  org_role: "ORG_MEMBER",
-  pod_role: "POD_USER",
-});
-```
+- 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`
 
-## Streaming (SSE)
+For more stable installs, prefer pinning the registry URL to a tag or commit SHA instead of `@main`.
 
-Use `readSSE` + `parseSSEJson` for incremental events.
+## Core Client
 
 ```ts
-import { readSSE, parseSSEJson } from "lemma-sdk";
-
-const stream = await client.conversations.sendMessageStream(conversationId, {
-  content: "Analyze recent incidents",
-});
-
-for await (const event of readSSE(stream)) {
-  const payload = parseSSEJson(event);
-  if (!payload) continue;
-  console.log(event.event, payload);
-}
-```
-
-Task stream example:
+import { LemmaClient } from "lemma-sdk";
 
-```ts
-const task = await client.tasks.create({
-  agent_name: "triage_agent",
-  input_data: { ticketId: "TCK-1042" },
+const client = new LemmaClient({
+  podId: "<pod-id>",
 });
 
-const taskStream = await client.tasks.stream(task.id);
-```
-
-## Access Grants (`accessible_tables`)
-
-When creating agents/functions/assistants, `accessible_tables` must use object entries:
-
-```ts
-import { TableAccessMode } from "lemma-sdk";
+await client.initialize();
 
-accessible_tables: [
-  { table_name: "expenses", mode: TableAccessMode.READ },
-  { table_name: "expense_notes", mode: TableAccessMode.WRITE },
-];
+const tables = await client.tables.list();
+const records = await client.records.list("tickets");
 ```
 
-`["expenses"]` is not valid.
+Pod-scoped namespaces include `tables`, `records`, `assistants`, `agents`, `workflows`, `functions`, `files`, and `resources`.  
+Org and user surfaces include `users`, `organizations`, `pods`, `podMembers`, and `podJoinRequests`.
 
 ## Auth
 
-Default mode is cookie/session auth (`credentials: "include"`).
-
-For local browser testing, token injection is supported via local storage key `lemma_token`:
+The SDK uses cookie or session auth by default.
 
-```ts
-import { setTestingToken, clearTestingToken } from "lemma-sdk";
-
-setTestingToken("<access-token>");
-clearTestingToken();
-```
-
-Auth helpers:
+Useful helpers:
 
 - `buildAuthUrl(...)`
 - `buildFederatedLogoutUrl(...)`
 - `resolveSafeRedirectUri(...)`
-- `client.auth.redirectToAuth(...)`
-- `client.auth.redirectToFederatedLogout(...)`
+- `setTestingToken(...)`
+- `clearTestingToken()`
 
-## React Package (`lemma-sdk/react`)
+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.
 
-Includes auth helpers, run hooks, and assistant UI primitives.
+## Local Development
 
-Install React peer dependency in your app if not already installed:
+From the root of this repository:
 
 ```bash
-npm i react react-dom
-```
-
-Import stylesheet once:
-
-```tsx
-import "lemma-sdk/react/styles.css";
-```
-
-Fastest assistant integration:
-
-```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>;
+npm install
+npm run build
+npm run registry:build
 ```
 
-Auth guard example:
+This repo includes:
 
-```tsx
-import { AuthGuard } from "lemma-sdk/react";
-
-<AuthGuard client={client}>
-  <App />
-</AuthGuard>;
-```
-
-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:
-
-- 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.`);
+}

package/dist/browser/lemma-client.js

@@ -55,6 +55,7 @@ const tables_js_1 = require("./namespaces/tables.js");
 const tasks_js_1 = require("./namespaces/tasks.js");
 const users_js_1 = require("./namespaces/users.js");
 const workflows_js_1 = require("./namespaces/workflows.js");
+const datastore_js_1 = require("./namespaces/datastore.js");
 class LemmaClient {
     constructor(overrides = {}, internalOptions = {}) {
         this._config = (0, config_js_1.resolveConfig)(overrides);
@@ -81,6 +82,7 @@ class LemmaClient {
         this.desks = new desks_js_1.DesksNamespace(this._generated, this._http, podIdFn);
         this.integrations = new integrations_js_1.IntegrationsNamespace(this._generated);
         this.resources = new resources_js_1.ResourcesNamespace(this._http);
+        this.datastore = new datastore_js_1.DatastoreNamespace(this._generated, podIdFn);
         this.users = new users_js_1.UsersNamespace(this._generated);
         this.icons = new icons_js_1.IconsNamespace(this._generated);
         this.pods = new pods_js_1.PodsNamespace(this._generated, this._http);
@@ -164,11 +166,11 @@ function resolveConfig(overrides = {}) {
     const apiUrl = overrides.apiUrl ??
         win.apiUrl ??
         fromEnv("API_URL") ??
-        "http://localhost:8000";
+        "https://api.asur.work";
     const authUrl = overrides.authUrl ??
         win.authUrl ??
         fromEnv("AUTH_URL") ??
-        "http://localhost:3000";
+        "https://auth.asur.work";
     const podId = overrides.podId ??
         win.podId ??
         fromEnv("POD_ID");
@@ -2125,7 +2127,7 @@ class FilesService {
         });
     }
     /**
-     * Delete File Or Folder. Deleting a folder will cleanup whole subtreee
+     * Delete File Or Folder
      * @param podId
      * @param path
      * @returns DatastoreMessageResponse Successful Response
@@ -2189,6 +2191,74 @@ class FilesService {
             },
         });
     }
+    /**
+     * Get Converted File Metadata
+     * @param podId
+     * @param path
+     * @returns ConvertedFileResponse Successful Response
+     * @throws ApiError
+     */
+    static fileConvertedGet(podId, path) {
+        return (0, request_js_1.request)(OpenAPI_js_1.OpenAPI, {
+            method: 'GET',
+            url: '/pods/{pod_id}/datastore/files/converted/by-path',
+            path: {
+                'pod_id': podId,
+            },
+            query: {
+                'path': path,
+            },
+            errors: {
+                422: `Validation Error`,
+            },
+        });
+    }
+    /**
+     * Download Converted File Artifact
+     * @param podId
+     * @param path
+     * @param artifact
+     * @returns any Successful Response
+     * @throws ApiError
+     */
+    static fileConvertedDownload(podId, path, artifact = 'document.md') {
+        return (0, request_js_1.request)(OpenAPI_js_1.OpenAPI, {
+            method: 'GET',
+            url: '/pods/{pod_id}/datastore/files/converted/download',
+            path: {
+                'pod_id': podId,
+            },
+            query: {
+                'path': path,
+                'artifact': artifact,
+            },
+            errors: {
+                422: `Validation Error`,
+            },
+        });
+    }
+    /**
+     * Render Converted File As HTML
+     * @param podId
+     * @param path
+     * @returns any Successful Response
+     * @throws ApiError
+     */
+    static fileConvertedRender(podId, path) {
+        return (0, request_js_1.request)(OpenAPI_js_1.OpenAPI, {
+            method: 'GET',
+            url: '/pods/{pod_id}/datastore/files/converted/render',
+            path: {
+                'pod_id': podId,
+            },
+            query: {
+                'path': path,
+            },
+            errors: {
+                422: `Validation Error`,
+            },
+        });
+    }
     /**
      * Download File
      * @param podId
@@ -4929,7 +4999,7 @@ class WorkflowsService {
     }
     /**
      * Install Workflow
-     * Install a workflow for runtime execution. Provide `account_id` when the workflow needs an integration account binding.
+     * Install a workflow for runtime execution. Provide `account_id` when the workflow needs an integration account binding, and provide `schedule` when installing a scheduled workflow.
      * @param podId
      * @param workflowName
      * @param requestBody
@@ -5022,6 +5092,57 @@ class WorkflowsService {
 }
 exports.WorkflowsService = WorkflowsService;
 
+},
+"./namespaces/datastore.js": function (module, exports, require) {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatastoreNamespace = void 0;
+const QueryService_js_1 = require("./openapi_client/services/QueryService.js");
+class DatastoreNamespace {
+    constructor(client, podId) {
+        this.client = client;
+        this.podId = podId;
+    }
+    query(request) {
+        const payload = typeof request === "string" ? { query: request } : request;
+        return this.client.request(() => QueryService_js_1.QueryService.queryExecute(this.podId(), payload));
+    }
+}
+exports.DatastoreNamespace = DatastoreNamespace;
+
+},
+"./openapi_client/services/QueryService.js": function (module, exports, require) {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryService = void 0;
+const OpenAPI_js_1 = require("./openapi_client/core/OpenAPI.js");
+const request_js_1 = require("./openapi_client/core/request.js");
+class QueryService {
+    /**
+     * Execute Query
+     * Execute a read-only SQL query inside the datastore schema. Joins, aggregates, subqueries, and cross-table reads are allowed as long as the statement is read only.
+     * @param podId
+     * @param requestBody
+     * @returns DatastoreQueryResponse Successful Response
+     * @throws ApiError
+     */
+    static queryExecute(podId, requestBody) {
+        return (0, request_js_1.request)(OpenAPI_js_1.OpenAPI, {
+            method: 'POST',
+            url: '/pods/{pod_id}/datastore/query',
+            path: {
+                'pod_id': podId,
+            },
+            body: requestBody,
+            mediaType: 'application/json',
+            errors: {
+                422: `Validation Error`,
+            },
+        });
+    }
+}
+exports.QueryService = QueryService;
+
 }
   };