@aigentyc/chat-sdk 0.1.3 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,189 @@
+# AGENTS.md — @aigentyc/chat-sdk
+
+Guide for AI coding assistants (Claude Code, Cursor, Windsurf, v0, Lovable, Bolt) using or contributing to this SDK. Humans: read `README.md` first.
+
+**Live docs (always current):** https://context7.com/llmstxt/unpkg_aigentyc_chat-sdk_0_1_5_llms_txt/llms.txt
+
+---
+
+## What this package is
+
+React 19 SDK for embedding an AI chat UI backed by the Aigentyc platform. Ships as a set of subpath exports so consumers only pull what they need.
+
+- Package name: `@aigentyc/chat-sdk`
+- Peer deps (required): `react>=19`, `react-dom>=19`
+- Bundled internally (no install needed): `@ai-sdk/react`, `ai`
+- Peer deps (optional, install only for that feature): `socket.io-client` (live chat), `recharts` (viz), `@json-render/*` + `zod` (json-render)
+- SSR: all client components emit `"use client"`; safe for Next.js App Router.
+
+---
+
+## Canonical install + usage (paste-ready)
+
+**New project?** Use the scaffolder — it's the lowest-risk path:
+
+```bash
+npm create aigentyc-chat@latest my-app -- --template=next --project-id=YOUR_ID
+```
+
+**Adding to an existing app:**
+
+```bash
+npm install @aigentyc/chat-sdk
+```
+
+```tsx
+import { Chat } from "@aigentyc/chat-sdk"
+import "@aigentyc/chat-sdk/theme/styles.css"
+
+export default function Page() {
+  return (
+    <Chat
+      projectId="YOUR_PROJECT_ID"
+      apiEndpoint="https://api.aigentyc.com"
+      apiKey="YOUR_API_KEY"
+    />
+  )
+}
+```
+
+**Required:** the CSS import. Without it the chat renders unstyled.
+
+---
+
+## Decision tree: which API to use
+
+```
+Need a full chat UI with zero config?           → <Chat />
+Need a floating bubble widget?                  → <ChatWidget />
+Need to customize header/input/messages only?   → <Chat slots={{...}} />
+Need custom layout around the chat?             → <ChatProvider> + <ChatInterface /> + <ChatInput />
+Need your own UI entirely?                      → useAigentycChat() (headless)
+Need to override one tool's rendering?          → slots.tools[toolName]
+```
+
+Don't reach for the headless hook just to change styling — use `theme` or `slots` first.
+
+---
+
+## Entry points (import from these, never from `dist/`)
+
+| Import | What you get |
+| --- | --- |
+| `@aigentyc/chat-sdk` | `Chat`, `ChatWidget`, `ChatProvider` |
+| `@aigentyc/chat-sdk/hooks` | `useAigentycChat`, other hooks |
+| `@aigentyc/chat-sdk/components` | Granular composable chat pieces |
+| `@aigentyc/chat-sdk/ai-elements` | `Message`, `Conversation` primitives |
+| `@aigentyc/chat-sdk/tools` | `ToolRenderer`, `VisualizationRenderer` |
+| `@aigentyc/chat-sdk/json-render` | json-render integration |
+| `@aigentyc/chat-sdk/ui` | shadcn-style primitives |
+| `@aigentyc/chat-sdk/theme` | `ThemeProvider`; CSS at `.../theme/styles.css` |
+| `@aigentyc/chat-sdk/i18n` | `addLanguage`, built-in `en`, `he` |
+| `@aigentyc/chat-sdk/core` | Types, transport, utilities |
+
+---
+
+## Slots
+
+`slots` prop on `<Chat>` / `<ChatWidget>`:
+
+- `header`, `welcome`, `message`, `input`, `footer`, `loader`, `suggestions`
+- `tools`: `Record<toolName, ComponentType>` — override per-tool rendering
+
+Each slot receives typed props — consult `.d.ts` of the entry points for exact signatures. Don't invent prop names.
+
+---
+
+## Tool rendering
+
+Tool results come back from the backend with a `uiRenderMode`:
+
+- `visualization` → recharts (requires `recharts` peer)
+- `json_render` → `@json-render/shadcn` (requires `@json-render/*` + `zod` peers)
+- `legacy` → HTML/CSS template from backend
+- `preset` → built-in renderer
+
+If a peer is missing, that tool's UI falls back; install the peer or override via `slots.tools[name]`.
+
+---
+
+## Theming
+
+CSS variables scoped under `[data-aigentyc-chat]`. Two ways to customize:
+
+```tsx
+<Chat theme={{ primaryColor: "#3b82f6" }} />
+```
+
+or plain CSS targeting `[data-aigentyc-chat]`. Do **not** edit `dist/styles.css` directly.
+
+---
+
+## i18n
+
+Built-in: `en`, `he`. Add more:
+
+```tsx
+import { addLanguage } from "@aigentyc/chat-sdk/i18n"
+addLanguage("fr", { welcomeTitle: "Bienvenue" })
+```
+
+---
+
+## Live chat handoff
+
+```tsx
+<Chat enableLiveChat chatServiceUrl="wss://..." />
+```
+
+Requires `socket.io-client`. Omit both props for AI-only mode.
+
+---
+
+## Rules for agents editing consumer projects
+
+**Do:**
+- Use the canonical quick start above verbatim for first-time setup.
+- Import CSS once, at the app root or layout file.
+- Prefer `slots` + `theme` before going headless.
+- Use React 19 features (Actions, `use`) — this SDK targets React 19.
+- Check `.d.ts` files under the published package for exact prop types.
+
+**Don't:**
+- Don't install React 18 — peer is `>=19`. If the project is on React 18, warn the user and stop.
+- Don't import from `@aigentyc/chat-sdk/dist/*` — those paths are not public API.
+- Don't reimplement message rendering when `slots.message` exists.
+- Don't call the Aigentyc API directly from the client — the SDK owns transport.
+- Don't add `"use client"` to files that wrap the SDK unnecessarily; it's already inside.
+- Don't commit `apiKey` to source control; use env vars (`NEXT_PUBLIC_*` only if the project is OK exposing it; otherwise proxy through a server route).
+
+---
+
+## Troubleshooting quick table
+
+| Symptom | Likely cause |
+| --- | --- |
+| Unstyled / broken layout | Missing `import "@aigentyc/chat-sdk/theme/styles.css"` |
+| "Cannot find module @ai-sdk/react" | Stale install — delete `node_modules` and reinstall (these are now bundled) |
+| Tool renders blank | Peer for that `uiRenderMode` not installed |
+| SSR hydration warning | Wrapping `<Chat>` in a non-client component — it's fine, the SDK handles `"use client"` internally; check for other client-only code in the tree |
+| React version error | Upgrade to React 19 |
+
+---
+
+## Repository layout (for contributors)
+
+- `src/` — source; barrel files per entry point
+- `dist/` — build output (tsup); do not edit
+- `stories/` — Storybook
+- `demo/` — local demo app (standalone Vite)
+- `src/styles/index.css` — Tailwind entry compiled to `dist/styles.css`
+
+Scripts: `pnpm build`, `pnpm storybook`, `pnpm test`, `pnpm lint`.
+
+---
+
+## Versioning
+
+- Current: `0.1.0` (pre-1.0 — API may shift).
+- Pin exact versions in consumer projects until 1.0.

package/bin/doctor.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+/**
+ * aigentyc doctor — diagnose Aigentyc Chat SDK install issues.
+ *
+ * Run inside a project that uses @aigentyc/chat-sdk:
+ *   npx aigentyc doctor
+ *
+ * Checks (in order):
+ *   1. Node >= 18
+ *   2. React >= 19 installed
+ *   3. @aigentyc/chat-sdk installed + version
+ *   4. CSS imported somewhere in source
+ *   5. Env vars (PROJECT_ID, API_ENDPOINT) present
+ *   6. API endpoint reachable
+ *   7. API key (if present) authorized for project
+ *   8. CORS allowed-origins includes localhost dev URL (best-effort)
+ *
+ * Exit code: 0 on all-pass, 1 if any check failed.
+ */
+
+import { readFile, readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+if (sub && sub !== "doctor") {
+  console.error(`Unknown command: ${sub}\nUsage: npx aigentyc doctor`);
+  process.exit(2);
+}
+
+const CWD = process.cwd();
+const C = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+
+const results = [];
+function pass(msg, hint) { results.push({ status: "ok", msg, hint }); }
+function warn(msg, hint) { results.push({ status: "warn", msg, hint }); }
+function fail(msg, hint) { results.push({ status: "fail", msg, hint }); }
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function readJson(path) {
+  try { return JSON.parse(await readFile(path, "utf8")); } catch { return null; }
+}
+
+async function readEnv() {
+  const candidates = [".env.local", ".env", ".env.development"];
+  const out = {};
+  for (const f of candidates) {
+    const path = join(CWD, f);
+    if (!existsSync(path)) continue;
+    const raw = await readFile(path, "utf8").catch(() => "");
+    for (const line of raw.split("\n")) {
+      const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+      if (!m) continue;
+      let v = m[2].trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+      }
+      if (out[m[1]] === undefined) out[m[1]] = v;
+    }
+  }
+  return out;
+}
+
+async function* walk(dir, depth = 0) {
+  if (depth > 4) return;
+  let entries;
+  try { entries = await readdir(dir); } catch { return; }
+  for (const name of entries) {
+    if (name === "node_modules" || name === ".next" || name === "dist" || name.startsWith(".")) continue;
+    const full = join(dir, name);
+    let s;
+    try { s = await stat(full); } catch { continue; }
+    if (s.isDirectory()) {
+      yield* walk(full, depth + 1);
+    } else if (/\.(tsx?|jsx?|mjs|cjs)$/.test(name)) {
+      yield full;
+    }
+  }
+}
+
+async function findCssImport() {
+  for await (const file of walk(CWD)) {
+    const src = await readFile(file, "utf8").catch(() => "");
+    if (/@aigentyc\/chat-sdk\/theme\/styles\.css/.test(src)) {
+      return file;
+    }
+  }
+  return null;
+}
+
+function semverMajor(v) {
+  if (!v) return 0;
+  const m = String(v).match(/(\d+)/);
+  return m ? Number(m[1]) : 0;
+}
+
+async function pingEndpoint(url) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 5000);
+  try {
+    const res = await fetch(url, { method: "GET", signal: ctrl.signal });
+    clearTimeout(t);
+    return { ok: res.ok || res.status < 500, status: res.status };
+  } catch (err) {
+    clearTimeout(t);
+    return { ok: false, error: String(err?.message || err) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+async function run() {
+  console.log(C.bold("\n  aigentyc doctor"));
+  console.log(C.dim(`  cwd: ${CWD}\n`));
+
+  // 1. Node version
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  if (nodeMajor >= 18) pass(`Node ${process.versions.node}`);
+  else fail(`Node ${process.versions.node} (need >= 18)`, "Update Node: https://nodejs.org");
+
+  // 2. package.json + React + SDK
+  const pkg = await readJson(join(CWD, "package.json"));
+  if (!pkg) {
+    fail("No package.json found in current directory.", `Run from your project root.`);
+    return finish();
+  }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  const reactV = deps.react;
+  if (!reactV) fail("`react` not in dependencies.", "npm install react@^19 react-dom@^19");
+  else if (semverMajor(reactV) < 19)
+    fail(`React ${reactV} (need >= 19)`, "npm install react@^19 react-dom@^19");
+  else pass(`React ${reactV}`);
+
+  const sdkV = deps["@aigentyc/chat-sdk"];
+  if (!sdkV) {
+    fail("`@aigentyc/chat-sdk` not in dependencies.", "npm install @aigentyc/chat-sdk");
+  } else {
+    pass(`@aigentyc/chat-sdk ${sdkV}`);
+  }
+
+  // 3. CSS import
+  const cssFile = await findCssImport();
+  if (cssFile) pass(`CSS imported in ${cssFile.replace(CWD + "/", "")}`);
+  else fail(
+    "Missing CSS import.",
+    `Add to your entry/layout file:\n     import "@aigentyc/chat-sdk/theme/styles.css"`
+  );
+
+  // 4. Env vars
+  const env = await readEnv();
+  const isNext = !!deps.next;
+  const prefix = isNext ? "NEXT_PUBLIC_AIGENTYC" : "VITE_AIGENTYC";
+
+  const projectId = env[`${prefix}_PROJECT_ID`];
+  const apiEndpoint = env[`${prefix}_API_ENDPOINT`];
+  const apiKey = env[`${prefix}_API_KEY`];
+
+  if (!projectId || projectId === "replace-me") {
+    fail(
+      `${prefix}_PROJECT_ID missing or placeholder.`,
+      "Get your projectId from https://app.aigentyc.ai/dashboard"
+    );
+  } else if (!/^proj_/.test(projectId)) {
+    warn(
+      `${prefix}_PROJECT_ID does not look like a project slug (expected proj_...).`,
+      `Got: ${projectId}`
+    );
+  } else {
+    pass(`${prefix}_PROJECT_ID = ${projectId}`);
+  }
+
+  if (!apiEndpoint) {
+    fail(
+      `${prefix}_API_ENDPOINT missing.`,
+      `Add ${prefix}_API_ENDPOINT=https://app.aigentyc.ai`
+    );
+  } else {
+    pass(`${prefix}_API_ENDPOINT = ${apiEndpoint}`);
+  }
+
+  if (apiKey) {
+    if (!/^tyco_pk_/.test(apiKey)) {
+      warn(
+        `${prefix}_API_KEY does not look like an Aigentyc key (expected tyco_pk_...).`,
+        `Got: ${apiKey.slice(0, 12)}...`
+      );
+    } else {
+      pass(`${prefix}_API_KEY = ${apiKey.slice(0, 12)}...`);
+    }
+  } else {
+    warn(
+      `${prefix}_API_KEY not set.`,
+      "OK if your project is public; required otherwise. Create one at https://app.aigentyc.ai/dashboard/<projectId>/api-keys"
+    );
+  }
+
+  // 5. Endpoint reachable
+  if (apiEndpoint) {
+    const ping = await pingEndpoint(apiEndpoint);
+    if (ping.ok) pass(`Reachable: ${apiEndpoint} (HTTP ${ping.status})`);
+    else fail(
+      `Cannot reach ${apiEndpoint}`,
+      ping.error ? `Network error: ${ping.error}` : `HTTP ${ping.status}`
+    );
+  }
+
+  // 6. CORS hint
+  const dev = isNext ? "http://localhost:3000" : "http://localhost:5173";
+  warn(
+    "CORS",
+    `Make sure your API key allows origin: ${dev} (set in dashboard → API Keys → Allowed Origins)`
+  );
+
+  finish();
+}
+
+function finish() {
+  console.log("");
+  let failed = 0;
+  for (const r of results) {
+    const tag =
+      r.status === "ok" ? C.green("✓") :
+      r.status === "warn" ? C.yellow("⚠") :
+      C.red("✗");
+    console.log(`  ${tag}  ${r.msg}`);
+    if (r.hint && r.status !== "ok") {
+      console.log(`     ${C.dim(r.hint)}`);
+    }
+    if (r.status === "fail") failed++;
+  }
+  console.log("");
+  if (failed === 0) {
+    console.log(C.green("  All checks passed."));
+    console.log(C.dim("  Run `npm run dev` and your chat should work.\n"));
+    process.exit(0);
+  } else {
+    console.log(C.red(`  ${failed} check${failed === 1 ? "" : "s"} failed. Fix the items above and rerun.\n`));
+    process.exit(1);
+  }
+}
+
+run();