@darqlabs/curator-sdk-react 0.1.0

package/dist/esm/useCuratorChat.js

@@ -0,0 +1,132 @@
+/**
+ * Headless chat hook for the Curator SDK.
+ *
+ * Manages a single conversation against a deployed agent. Owns the
+ * `Chat` instance from the SDK, exposes the rolling message list, a
+ * `send()` action, and the various pending/error states the UI needs.
+ *
+ * Bring your own UI on top of this hook, or use `<CuratorChat />` for
+ * the drop-in styled widget that consumes this hook internally.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { CuratorAgentError, CuratorApprovalRequiredError, CuratorAuthError, CuratorDeploymentRetiredError, CuratorForbiddenError, CuratorNotFoundError, CuratorRateLimitError, CuratorTimeoutError, } from "@darqlabs/curator-sdk";
+import { useCuratorOrNull } from "./CuratorProvider.js";
+let counter = 0;
+function localId() {
+    counter += 1;
+    return `local_${Date.now().toString(36)}_${counter}`;
+}
+export function useCuratorChat(opts) {
+    const { agent, project, environment, system, conversationId, onMessage, onError } = opts;
+    // Resolve the client: explicit prop wins, then context, then fail loud.
+    const contextClient = useCuratorOrNull();
+    const curator = opts.curator ?? contextClient;
+    if (!curator) {
+        throw new Error("useCuratorChat() requires a Curator client. Either pass `curator` explicitly " +
+            "or wrap your app in <CuratorProvider client={curator}>.");
+    }
+    // Construct the Chat on first render and whenever any addressing input
+    // changes. Re-creating on slug/project/env changes prevents accidentally
+    // sending to a stale agent if the consumer swaps props.
+    const chat = useMemo(() => {
+        const agentHandle = curator.agent(agent, { project, environment, system });
+        return conversationId ? agentHandle.conversation(conversationId) : agentHandle.chat();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [curator, agent, project, environment, system, conversationId]);
+    const [messages, setMessages] = useState([]);
+    const [sending, setSending] = useState(false);
+    const [error, setError] = useState(null);
+    const [conversationIdState, setConversationIdState] = useState(conversationId ?? null);
+    // Whenever the chat handle changes (consumer swapped props or called
+    // reset), wipe local message state to avoid mixing transcripts.
+    const lastChatRef = useRef(null);
+    useEffect(() => {
+        if (lastChatRef.current !== chat) {
+            lastChatRef.current = chat;
+            setMessages([]);
+            setError(null);
+            setConversationIdState(chat.id);
+        }
+    }, [chat]);
+    const send = useCallback(async (content, args = {}) => {
+        const trimmed = content.trim();
+        if (!trimmed && !args.files?.length)
+            return;
+        const userBubble = { kind: "user", content: trimmed, localId: localId() };
+        setMessages((prev) => [...prev, userBubble]);
+        setSending(true);
+        setError(null);
+        try {
+            const reply = await chat.send(trimmed, args);
+            setConversationIdState(reply.conversationId);
+            setMessages((prev) => [
+                ...prev,
+                {
+                    kind: "assistant",
+                    content: reply.content,
+                    sequence: reply.sequence,
+                    stepId: reply.stepId,
+                    createdAt: reply.createdAt,
+                    runId: reply.runId,
+                },
+            ]);
+            onMessage?.(reply);
+        }
+        catch (err) {
+            const message = renderError(err);
+            setError(err);
+            setMessages((prev) => [...prev, { kind: "error", message, localId: localId() }]);
+            onError?.(err);
+        }
+        finally {
+            setSending(false);
+        }
+    }, [chat, onMessage, onError]);
+    const reset = useCallback(() => {
+        // Force the memo to refresh by zeroing the ref; the consumer-controlled
+        // inputs determine the next Chat. For the no-prop-change case, we
+        // instead just clear local state — the existing Chat is still valid.
+        setMessages([]);
+        setError(null);
+        setConversationIdState(chat.id);
+    }, [chat]);
+    return {
+        messages,
+        send,
+        sending,
+        error,
+        chat,
+        conversationId: conversationIdState,
+        reset,
+    };
+}
+function renderError(err) {
+    if (err instanceof CuratorApprovalRequiredError) {
+        return `That action needs administrator approval. Please contact your administrator to review the request for "${err.approval.tool_name}".`;
+    }
+    if (err instanceof CuratorAgentError) {
+        return err.message || `Agent error (${err.failureClass}).`;
+    }
+    if (err instanceof CuratorTimeoutError) {
+        return "The agent is taking longer than expected. It may still complete in the background.";
+    }
+    if (err instanceof CuratorAuthError) {
+        return "Authentication failed. Check your API key.";
+    }
+    if (err instanceof CuratorForbiddenError) {
+        return err.message || "Permission denied.";
+    }
+    if (err instanceof CuratorNotFoundError) {
+        return err.message || "Deployment or conversation not found.";
+    }
+    if (err instanceof CuratorDeploymentRetiredError) {
+        return "This deployment has been retired by the operator.";
+    }
+    if (err instanceof CuratorRateLimitError) {
+        return "Rate limit reached. Please wait a moment and try again.";
+    }
+    if (err instanceof Error)
+        return err.message;
+    return "Something went wrong.";
+}
+//# sourceMappingURL=useCuratorChat.js.map

package/dist/esm/useCuratorChat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCuratorChat.js","sourceRoot":"","sources":["../../src/useCuratorChat.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@darqlabs/curator-sdk-react",
+  "version": "0.1.0",
+  "description": "Official React components for Curator — drop-in chat widget and headless hook backed by @darqlabs/curator-sdk.",
+  "license": "MIT",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/cjs/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@assistant-ui/react": "^0.14.26",
+    "react-markdown": "^10.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@darqlabs/curator-sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "jest": "^30.3.0",
+    "jest-environment-jsdom": "^30.0.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "ts-jest": "^29.4.9",
+    "typescript": "^5.9.3",
+    "@darqlabs/curator-sdk": "^0.1.0"
+  },
+  "keywords": [
+    "curator",
+    "ai",
+    "agents",
+    "react",
+    "chat",
+    "sdk"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist .tsbuild",
+    "build": "tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && node ./scripts/write-esm-marker.cjs",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:coverage": "jest --coverage"
+  }
+}