` — the same shape the backend returns as `sdk_ui`. Use it to override `text` (greeting / placeholder / suggestions) and `theme` design tokens. Partial calls merge into the current config, so passing only `text.suggestions` keeps `text.greeting` and the loaded `theme` intact.\n- **`getRuntimeConfig()`** — synchronous read of the current merged `{ text, theme }`. Useful for snapshotting the resolved config (defaults + backend `sdk_ui` + your overrides) without subscribing via `useSidebarConfig`.\n\nRule of thumb: \"where the sidebar is and how it behaves\" → `updateSidenetConfig`. \"what the sidebar looks like and what copy it shows\" → `updateSidenetStyledConfig`.\n\n#### `copilotId` is init-only\n\nIt binds the whole session to a set of backend resources — the thread list, the agent list, the copilot's `sdk_ui` config, and the id of every thread created since init. Swapping it in place would leave all of that pointing at the previous copilot, so `updateSidenetConfig()` **ignores a changed value and warns**:\n\n```\n⚠️ SideNetAI SDK: copilotId is init-only and was ignored (still \"copilot-456\").\n Call destroySidenet() then initSidenet() to change it.\n```\n\nTo switch, tear down and start again:\n\n```javascript\nawait destroySidenet();\nawait initSidenet({ ...config, copilotId: 'copilot-789' });\n```\n\nRe-passing the *current* value is a silent no-op, so handing the SDK your whole config object on every update is safe — only an actual change warns.\n\nChanging **who the user is** works differently: identity lives in the session token, so mint a new session and pass it to `updateSidenetConfig({ auth })` — no teardown needed.\n\n### Tool Credentials\n\nCredentials the agent's **tools** use (GitHub, Slack, a database) — unrelated to the session token above.\n\nBind them when you mint the session, via `tools_auth` on `POST /v1/token`. The browser never carries them, and anything a page sends alongside a session token is ignored server-side — a client cannot substitute its own credentials.\n\nTo discover which fields each provider wants, call `GET /v1/copilots/{copilotId}` from your backend once; its `runtimeAuthProviders` list names them:\n\n```javascript\n// Backend. Both calls use the organization API key.\nconst { runtimeAuthProviders } = await api(`/v1/copilots/${copilotId}`, {\n headers: { 'X-User-Id': userId }, // required on this endpoint\n});\n// [{ providerId: 'f2f2…', providerName: 'github', authFields: ['token'], optionalFields: ['base_url'] }, …]\n\nconst tokens = await api('/v1/token', {\n user,\n billing_group,\n tools_auth: {\n 'f2f27032-…': { credentials: { token: 'ghp_…' }, base_url: 'https://api.example.com' },\n },\n});\n```\n\nKey each entry by `providerId`. `authFields` names what that provider needs in `credentials`; `optionalFields` (e.g. `base_url`) sit alongside it, as does `identityId` when one provider serves several end-user accounts. Include only the providers you are actually supplying — a provider whose `authFields` is empty is configured server-side and needs nothing from you.\n\nTo change a credential later, mint a new session with the updated `tools_auth` and hand it over with `updateSidenetConfig({ auth })`.\n\n### Prompt Variables\n\n| Function | Description |\n|----------|-------------|\n| `getSidenetVariables()` | Get the `{{placeholders}}` this copilot's agents declare, as a fillable object (async) |\n| `flattenSidenetVariables(declared)` | Turn that object into one `{ path, default }` entry per placeholder (sync) |\n\nIt tells you what you may put in `variables` without reading anyone's prompt or calling `GET /v1/copilots/{id}` yourself.\n\n```typescript\nimport { getSidenetVariables, flattenSidenetVariables, updateSidenetConfig } from 'sidenetai-sdk';\n\nconst declared = await getSidenetVariables();\n// { instance: { currency: 'EUR', store_count: null }, userName: null }\n\n// Fill what you have and hand the whole object back — same shape, no reshaping.\nupdateSidenetConfig({\n variables: { ...declared, userName: 'Maya' },\n});\n\n// Or list the paths: the ones with no default render as a literal {{name}} if you skip them\nconst required = flattenSidenetVariables(declared)\n .filter((v) => v.default === null)\n .map((v) => v.path);\n```\n\n`getSidenetVariables()` returns `SidenetDeclaredVariables` — an object whose leaves are `string | null` and whose branches are more of the same:\n\n| Leaf | Meaning |\n|------|---------|\n| `string` | The default this path renders when you omit it (from the block's `{{name \\|\\| 'fallback'}}`). |\n| `null` | No default — a literal `{{name}}` is left in the prompt. **These are the ones to fill in.** |\n\n`flattenSidenetVariables(declared)` returns `SidenetVariablePath[]`:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `path` | `string` | The placeholder path — `userName`, or a dot path like `instance.currency`. Valid as a key to send back as-is. |\n| `default` | `string \\| null` | The leaf's value, as above. |\n\nNotes:\n\n- Served from the object cached during `initSidenet()`, so it's free after boot. It fetches once only if that init fetch failed. Call `refreshSidenetConfig()` to pick up prompt edits made since.\n- Keys are alphabetical at every level.\n- Throws if the SDK isn't initialized, or if you initialized with only an `agentId` / `agentVersionId` — with no `copilotId` there's no network to enumerate.\n- An empty object is a real answer: the agents use no placeholders, or they still run the legacy single prompt string, which isn't templated.\n- Sending a `null` leaf back is a no-op — not stored, not counted against the 64-value limit, not reported as dropped. A namespace whose leaves are all `null` is dropped whole, so a wholesale `{{instance}}` stays visible rather than rendering `{}`.\n- A path that a prompt reads both wholesale (`{{user}}`) and by sub-path (`{{user.name}}`) comes back only as the namespace — that combination isn't fillable both ways, since `{ user: 'x', 'user.name': 'y' }` is rejected as a conflict.\n- Server builtins (`now.*`) are excluded — you can't supply those.\n\n### Agents\n\n| Function | Description |\n|----------|-------------|\n| `getAgents(copilotId)` | Fetch available agents (async). Uses the live session credential; pass a token as the 2nd argument to call it before `initSidenet()`. |\n\n```typescript\nimport { getAgents } from 'sidenetai-sdk';\n\n// Same values you pass to initSidenet — handy for building a\n// custom picker before the sidebar is mounted.\nconst agents = await getAgents('copilot-456');\n```\n\n### Defaults & Constants\n\n| Export | Description |\n|--------|-------------|\n| `DEFAULT_THEME` | `ThemeInput` — the full default token set the SDK ships with. Read it to inspect defaults, or spread it into `updateSidenetStyledConfig({ theme })` as a starting point. |\n| `SIDENET_EVENTS` | `{ OPEN, CLOSE, RESIZE, READY, SERVER_EVENT }` — typed event-name constants. Prefer these over raw `'sidenet:open'` strings for type safety. |\n\n```typescript\nimport { DEFAULT_THEME, SIDENET_EVENTS, updateSidenetStyledConfig } from 'sidenetai-sdk';\n\n// Start from defaults and tweak one token\nupdateSidenetStyledConfig({\n theme: { ...DEFAULT_THEME, accentColor: { light: '#ff5722', dark: '#ff8a65' } },\n});\n\nwindow.addEventListener(SIDENET_EVENTS.OPEN, (e) => {\n console.log('Opened at', e.detail.width);\n});\n```\n\n## Events\n\nThree ways to respond to sidebar state changes:\n\n### 1. Callbacks (Simplest)\n\n```typescript\ninitSidenet({\n copilotId: 'copilot-456',\n auth: { ...tokens },\n onOpen: (detail) => console.log('Opened', detail.width),\n onClose: (detail) => console.log('Closed'),\n onResize: (detail) => console.log('Resized to', detail.width),\n onReady: (detail) => console.log('Ready'),\n});\n```\n\n### 2. CSS Custom Properties (Zero-code layout)\n\n```css\n.my-content {\n margin-right: var(--sidenet-width, 0);\n transition: margin 0.3s ease;\n}\n```\n\nAvailable properties (set on the host page's `` element):\n- `--sidenet-width` — Current width (e.g., `400px`) or `0` when closed\n- `--sidenet-open` — `1` when open, `0` when closed\n- `--sidenet-position` — `left` or `right`\n\n> Theme token variables (`--background`, `--aui-accent-color`, etc.) live **inside the Shadow DOM** and are not exposed to the host page. To customize them, use `updateSidenetStyledConfig({ theme })` rather than CSS overrides.\n\n### 3. Window Events (Decoupled)\n\n```typescript\nimport { SIDENET_EVENTS } from 'sidenetai-sdk';\n\nwindow.addEventListener(SIDENET_EVENTS.OPEN, (e) => {\n console.log('Opened', e.detail.width, e.detail.position);\n});\n\nwindow.addEventListener(SIDENET_EVENTS.CLOSE, (e) => {\n console.log('Closed');\n});\n\nwindow.addEventListener(SIDENET_EVENTS.RESIZE, (e) => {\n console.log('Resized', e.detail.width);\n});\n\nwindow.addEventListener(SIDENET_EVENTS.READY, (e) => {\n console.log('Ready');\n});\n```\n\nRaw event-name strings (`'sidenet:open'`, `'sidenet:close'`, `'sidenet:resize'`, `'sidenet:ready'`) also work — the constants exist for type safety and refactor resilience.\n\nEvent detail shape:\n```typescript\ninterface SidenetEventDetail {\n width: string; // e.g., '400px'\n position: 'left' | 'right';\n layout: 'sidebar' | 'modal' | 'drawer';\n}\n```\n\n### 4. Server events (live thread list)\n\nWhile the chat is mounted the SDK keeps one server-sent-events connection open\n(`GET /v1/events`) and applies every push to its own thread list, so a\nconversation filed by a **scheduled workflow**, a reply that finished while the\ntab was away, or a freshly generated title shows up without a reload. The same\npush is handed to the host page so you can badge your own launcher while the\nsidebar is closed:\n\n```typescript\ninitSidenet({\n copilotId: 'copilot-456',\n auth: { ...tokens },\n onServerEvent: ({ event, unreadCount }) => {\n launcherBadge.textContent = unreadCount ? String(unreadCount) : '';\n if (event.type === 'workflow.run.finished' && event.run.status === 'failed') {\n toast(`Workflow \"${event.run.workflowName}\" failed`);\n }\n },\n});\n\n// or, decoupled:\nwindow.addEventListener(SIDENET_EVENTS.SERVER_EVENT, (e) => {\n console.log(e.detail.event.type, e.detail.unreadCount);\n});\n```\n\nEvent shapes (`ServerEvent`):\n\n| `event.type` | Payload | When |\n|---|---|---|\n| `thread.upserted` | `thread` — the same object `GET /v1/threads` lists (`id`, `title`, `updatedAt`, `metadata.unread`, `metadata.source`, …) | A conversation was created or changed: a workflow run filed its result, the unread flag flipped, a title landed |\n| `thread.deleted` | `threadId` | A conversation was removed |\n| `workflow.run.finished` | `run` — `runId`, `workflowId`, `workflowName`, `status` (`succeeded` \\| `failed`), `threadId`, `trigger`, `finishedAt`, `error?` | A workflow run for this user ended |\n\n`unreadCount` is the number of threads flagged unread in the SDK's list after the\nevent was applied. The connection reconnects on its own (with backoff, and\nimmediately when the tab returns to the foreground); on reconnect the SDK\nrefetches the thread list to cover the gap. Against a backend without\n`GET /v1/events` the SDK silently falls back to the load-on-open behaviour.\n\n## Automations\n\nThe thread list's **Tasks** section lists every automation the user built\nwith the assistant (their saved prompts, `GET /v1/prompts`, each carrying the\nschedules that run it) next to its schedule, from that one call. Clicking a\nrow opens the automation in place of the conversation:\n\n- an on/off switch for the schedule (`POST …/{id}/pause` / `…/resume`) with\n the next run next to it, **Run now** (`POST …/{id}/run-now`, or\n `POST /v1/prompts/{id}/run` for an automation with no schedule) and\n **Archive** (`DELETE /v1/prompts/{id}`, which disables its schedules).\n Run now opens the run's conversation as soon as the run log lists it\n (the backend files the thread the moment the run starts), and the\n conversation streams the run as it happens — the same resume the widget\n does for any conversation it opens;\n- the run history (`GET /v1/workflow-runs?promptId=`) — each run opens the\n conversation it filed its result in (the run's `thread_id`, else the listed\n thread whose `metadata.workflowRunId` points at it); a run with no\n conversation, such as one started inline from the chat, unfolds its result\n text in place;\n- the instructions the assistant receives at every run;\n- **Repeats**: the schedule as the workflow card's own picker, with the next\n run times previewed. Saving patches the schedule (`PATCH …/{id}`), creates\n one for an on-demand automation (`POST /v1/workflow-schedules`), or removes\n it (Manual only).\n\nEverything runs under the session token, so a user only ever sees and changes\ntheir own automations. A run started from the view refreshes the thread list\nwhen it starts and when it ends, so its result conversation shows up without\na reload.\n\n## Theming\n\n### Light/Dark Mode\n\n```typescript\ninitSidenet({\n copilotId: 'copilot-456',\n auth: { ...tokens },\n theme: 'dark', // or 'light'\n});\n\n// Update at runtime\nupdateSidenetConfig({ theme: 'light' });\n```\n\n### Design Tokens\n\nEach token accepts a `ThemeTokenInput` — either a plain `string` (applies to both light and dark) or a `{ light?: string; dark?: string }` object for per-mode values. If only one side is set, that value falls back to both modes.\n\nUse `updateSidenetStyledConfig()` to customize colors, radii, and fonts:\n\n```typescript\nupdateSidenetStyledConfig({\n theme: {\n // Single value applies to both modes\n radius: '0.5rem',\n fontFamily: '\"Inter\", sans-serif',\n\n // Per-mode values\n background: { light: '#ffffff', dark: '#09090b' },\n foreground: { light: '#09090b', dark: '#fafafa' },\n accentColor: { light: '#0ea5e9', dark: '#38bdf8' },\n userMessageBackground: { light: '#eff6ff', dark: '#1e3a5f' },\n },\n});\n```\n\nAvailable tokens:\n\n| Token | Description |\n|-------|-------------|\n| `radius` | Base border radius |\n| `composerRadius` | Input area radius |\n| `messageRadius` | Message bubble radius |\n| `suggestionRadius` | Suggestion card radius |\n| `sendButtonRadius` | Send button radius (default: pill) |\n| `headerButtonRadius` | Header icon button radius |\n| `selectRadius` | Dropdown trigger radius |\n| `containerRadius` | Outer panel radius — applies to all layouts (sidebar, drawer, modal). Default: `0` (square) |\n| `containerShadow` | Outer panel drop shadow. Applied to drawer + modal by default; sidebar stays flat. Set `none` to disable |\n| `modalRadius` | _Deprecated._ Overrides `containerRadius` for `layout: 'modal'` only, when set |\n| `threadMaxWidth` | Max width of conversation area |\n| `fontFamily` | Font family |\n| `accentColor` | Interactive element color |\n| `background` | Main background |\n| `foreground` | Main text color |\n| `muted` | Secondary surface background |\n| `mutedForeground` | Secondary text color |\n| `border` | Border color |\n| `userMessageBackground` | User bubble background |\n| `userMessageForeground` | User bubble text |\n| `userMessageBorder` | User bubble border |\n| `assistantMessageBackground` | Assistant bubble background |\n| `assistantMessageForeground` | Assistant bubble text |\n| `assistantMessageBorder` | Assistant bubble border |\n| `composerBackground` | Input area background |\n| `suggestionBackground` | Suggestion card background |\n| `suggestionBorder` | Suggestion card border |\n\n### Custom CSS\n\n```typescript\ninitSidenet({\n copilotId: 'copilot-456',\n auth: { ...tokens },\n customCSS: `\n .aui-message-content { font-size: 14px; }\n `,\n // Or structured:\n customStyles: {\n '.aui-message-content': { 'font-size': '14px' },\n },\n});\n```\n\n## Greeting & Suggestions\n\nThe empty-state greeting, composer placeholder, and suggestion cards are loaded from the backend's `sdk_ui.text`. You can override any of these via `initSidenet({ sdkUi })` or at runtime via `updateSidenetStyledConfig({ text })`. Suggestion cards can also bind a specific agent for one-shot routing on click.\n\n```typescript\nawait initSidenet({\n copilotId: 'copilot-456',\n auth: { ...tokens },\n sdkUi: {\n text: {\n greeting: { title: 'Hello!', subtitle: 'Pick a quick action below.' },\n placeholder: 'Ask anything…',\n suggestions: [\n // agentId binds the next send to a specific agent (matched against the\n // loaded agent list).\n { title: 'Refunds this week', subtitle: '', agentId: 'a3afed78-174a-43fe-8744-5598014d08bb' },\n // Looser editTolerance — user can rewrite up to 40% before the binding drops.\n { title: 'Top selling hotel', subtitle: 'today', agentId: 'ac5e1034-c2f9-4897-abf4-2665eb12f331', editTolerance: 0.4 },\n // System prompt only — biases the assistant for this one send (no agent binding).\n { title: 'Translate to French', subtitle: 'next message', prompt: 'Respond in concise French regardless of input language.' },\n // No agentId → routes through the default (dropdown selection or auto).\n { title: 'Free-form question', subtitle: 'no agent bound' },\n ],\n },\n },\n});\n\n// Or at runtime — partial updates merge into the existing config:\nupdateSidenetStyledConfig({\n text: {\n suggestions: [\n { title: 'New idea', subtitle: '', agentId: 'ac5e1034-c2f9-4897-abf4-2665eb12f331' },\n ],\n },\n});\n```\n\n**Per-suggestion bindings.** A suggestion can attach two pieces of intent to the next user send:\n\n- **`agentId`** — adds an `X-Agent-Id` header pointing at the bound agent. The id is matched against the loaded agent list at click time; if it doesn't match any agent, the binding is dropped silently (a `console.warn` appears when `debug: true`).\n- **`prompt`** — prepends a `system` message to the `messages` array sent for that single send (standard AI SDK pattern). Use it to bias the assistant for the suggestion's intent — persona, output format, language, etc. The backend sees a turn that starts with the system message and ends with the user's message.\n\nBoth are gated by **edit tolerance**: if the user edits the prefilled prompt before sending, the SDK computes the Levenshtein distance against the original suggestion text. If `distance > editTolerance × originalLength` (default `editTolerance: 0.25`, with an absolute floor of 6 characters), both bindings are dropped and the request goes through with the dropdown's defaults.\n\n`agentId` and `prompt` are independent — a suggestion can have either, both, or neither.\n\n## Content Push\n\nAutomatically push your page content when the sidebar opens:\n\n```typescript\ninitSidenet({\n copilotId: 'copilot-456',\n auth: { ...tokens },\n position: 'right',\n contentElement: '#app', // CSS selector for your main content\n});\n```\n\nThe element will receive `margin-right` (or `margin-left` for left position) matching the sidebar width.\n\n## TypeScript\n\nAll types are exported:\n\n```typescript\nimport type {\n SidenetOptions,\n SidenetEventDetail,\n SidenetCallbacks,\n RuntimeAuthProvider, // shape of runtimeAuthProviders from GET /v1/copilots/{id}\n SidenetVariables, // the map you send\n SidenetVariableValue, // one value in it: scalar | scalar[] | nested object\n SidenetVariableScalar, // string | number | boolean | null\n SidenetDeclaredVariables,// what the agents declare, as returned by getSidenetVariables()\n SidenetVariablePath, // one { path, default } from flattenSidenetVariables()\n Agent,\n SidebarSDKConfig,\n SidebarRuntimeConfig,\n SidebarTextConfig,\n SidebarSuggestionItem,\n ThemeTokens,\n ThemeInput,\n ThemeTokenInput,\n} from 'sidenetai-sdk';\n```\n\n## React Hook\n\nFor React apps, use the `useSidebarConfig` hook to access runtime config:\n\n```typescript\nimport { useSidebarConfig } from 'sidenetai-sdk';\n\nfunction MyComponent() {\n const config = useSidebarConfig();\n return Greeting: {config.text.greeting.title}
;\n}\n```\n\n## Advanced: Direct Component Usage\n\nFor full control, use the `Sidebar` component directly:\n\n```typescript\nimport { Sidebar } from 'sidenetai-sdk';\n\n console.log(width)}\n onAgentChange={(agentId) => console.log(agentId)}\n/>\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}