@shogo-ai/voice 1.4.1

package/dist/react/index.d.ts

@@ -0,0 +1,423 @@
+import { B as BaseVoiceConversationOptions, a as BaseVoiceConversationResult, b as BaseChatConversationOptions, c as BaseChatConversationResult, O as OrganicSphereConfig, d as OrganicParticlesConfig } from '../organicParticlesShaders-DIva0vBO.js';
+export { e as BandReactivity, C as ChatClientToolFn, f as ChatConversationStatus, g as ChatToolDescriptor, D as DEFAULT_ORGANIC_PARTICLES_CONFIG, h as DEFAULT_ORGANIC_SPHERE_CONFIG, i as ORGANIC_PARTICLES_FRAGMENT_SHADER, j as ORGANIC_PARTICLES_VERTEX_SHADER, k as ORGANIC_SPHERE_FRAGMENT_SHADER, l as ORGANIC_SPHERE_VERTEX_SHADER, P as PERLIN_4D, r as resolveOrganicParticlesConfig, m as resolveOrganicSphereConfig } from '../organicParticlesShaders-DIva0vBO.js';
+import * as React from 'react';
+import React__default from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import 'ai';
+
+/**
+ * `useVoiceConversation` (web) — drop-in React hook wrapping
+ * `@elevenlabs/react`'s `useConversation` with batteries included:
+ *
+ *   1. Fetches a signed URL from the consumer's server (default: `/api/voice/signed-url`).
+ *   2. Registers the canonical `add_memory` client tool (POST-es to `/api/memory/add`).
+ *   3. Auto-injects relevant memory as a contextual update on each user message
+ *      (POST `/api/memory/retrieve`).
+ *   4. Accumulates a plain-text transcript and calls `onTranscript` on disconnect,
+ *      plus a `pagehide` `navigator.sendBeacon` fallback so nothing is lost on
+ *      tab close.
+ *
+ * Consumers can mix in additional `clientTools` and override every path.
+ *
+ * Requires the caller's app to have `@elevenlabs/react` installed (optional
+ * peer dependency). For React Native, import from
+ * `@shogo-ai/sdk/voice/native` instead.
+ */
+
+type UseVoiceConversationOptions = BaseVoiceConversationOptions;
+type UseVoiceConversationResult = BaseVoiceConversationResult;
+/**
+ * Hook that owns the voice session lifecycle end-to-end. See module docblock
+ * for the wire format of the various server endpoints.
+ */
+declare function useVoiceConversation(options: UseVoiceConversationOptions): UseVoiceConversationResult;
+
+/**
+ * `useShogoVoice` — zero-config voice hook for generated pod apps.
+ *
+ * This is a thin alias around {@link useVoiceConversation} with the
+ * pod-friendly defaults pre-applied:
+ *
+ *   - `characterName: 'Shogo'`
+ *   - `signedUrlPath: '/api/voice/signed-url'` — served same-origin by
+ *     the app's own Hono/Next route, which in turn proxies through the
+ *     Shogo API via the pod's runtime token. No API key is read by the
+ *     browser and no `Authorization` header is sent — the pod handles
+ *     auth server-side.
+ *   - `fetchCredentials: 'same-origin'`
+ *
+ * Provider requirement
+ * --------------------
+ * `@elevenlabs/react` ≥ 1.1 requires every `useConversation` caller —
+ * which includes this hook — to live under a `<ConversationProvider>`
+ * ancestor. The SDK re-exports that provider as `<ShogoVoiceProvider>`
+ * so consumer apps don't have to import from `@elevenlabs/react`
+ * directly. Without the provider you'll get:
+ *
+ *     useRegisterCallbacks must be used within a ConversationProvider
+ *
+ * Mount the provider once near the root of your app (NOT around each
+ * component individually — sibling voice components only share session
+ * state when they live under the same provider, so mounting separate
+ * providers around `<VoiceButton>` and `<VoiceSphere>` will give them
+ * disconnected sessions and the sphere will never visualize the
+ * button's audio).
+ *
+ * For third-party / external embeds (not pod-native), keep using
+ * `useVoiceConversation({ shogoApiKey, projectId })` — the bearer path
+ * is the correct choice when same-origin fetch can't reach the Shogo
+ * API directly. The provider requirement is the same.
+ *
+ * @example Minimum viable usage
+ * ```tsx
+ * import {
+ *   ShogoVoiceProvider,
+ *   useShogoVoice,
+ * } from '@shogo-ai/sdk/voice/react'
+ *
+ * function VoiceButton() {
+ *   const { start, end, status } = useShogoVoice()
+ *   const active = status === 'connected' || status === 'connecting'
+ *   return (
+ *     <button onClick={active ? end : start}>
+ *       {active ? 'End call' : 'Talk to Shogo'}
+ *     </button>
+ *   )
+ * }
+ *
+ * export default function App() {
+ *   return (
+ *     <ShogoVoiceProvider>
+ *       <VoiceButton />
+ *     </ShogoVoiceProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example Named secondary agents
+ * Declare additional agents in `shogo.config.json#agents`, run
+ * `bunx shogo deploy`, then pick which one a component talks to via
+ * `agentName`. Both `useShogoVoice({ agentName: 'architect' })` and
+ * `useShogoChat({ agentName: 'architect' })` resolve to the SAME
+ * `ProjectAgent` row, so voice + text can share one persona /
+ * tool-allowlist.
+ *
+ * ```jsonc
+ * // shogo.config.json
+ * {
+ *   "agents": {
+ *     "architect": {
+ *       "systemPrompt": "You design system architectures.",
+ *       "tools": ["lookup_user"],
+ *       "model": "claude-sonnet-4-5"
+ *     },
+ *     "narrator": {
+ *       "systemPrompt": "You narrate system events out loud.",
+ *       "voiceId": "voice_id_here",
+ *       "firstMessage": "Hi, I'll narrate updates."
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ```tsx
+ * function NarratorButton() {
+ *   const v = useShogoVoice({ agentName: 'narrator' })
+ *   return <button onClick={v.start}>Start narration</button>
+ * }
+ * ```
+ *
+ * Tool contract: the manifest declares the tools the agent is allowed
+ * to invoke — including the full `description` + JSON `inputSchema`
+ * for each — and the consumer's React code provides the matching
+ * handler implementations via `clientTools`. Manifest schemas win
+ * server-side, so a `shogo deploy` is a single source of truth for
+ * BOTH ElevenLabs (voice) AND `streamText` (chat).
+ *
+ * @example Per-user dynamic variables
+ * Surface fields from your own `Companion` row to the agent prompt
+ * via `dynamicVariables`. The values land in EL as
+ * `dynamic_variables` and the agent prompt can reference them via
+ * `{{user_display_name}}` etc. (assuming the variables are declared
+ * on the agent in `dynamic_variable_placeholders` at deploy time).
+ *
+ * The SDK's built-ins (`character_name`, `user_context`,
+ * `conversation_id`) always win on collision so you can't
+ * accidentally override them.
+ *
+ * ```tsx
+ * function NarratorButton() {
+ *   const companion = useCompanion() // your store
+ *   const v = useShogoVoice({
+ *     agentName: 'narrator',
+ *     dynamicVariables: {
+ *       user_display_name: companion.userDisplayName,
+ *       relationship_stage: companion.relationshipStage,
+ *       greeting_token: companion.firstMessage ?? '',
+ *     },
+ *   })
+ *   return <button onClick={v.start}>Start narration</button>
+ * }
+ * ```
+ */
+
+type UseShogoVoiceOptions = Partial<UseVoiceConversationOptions>;
+declare function useShogoVoice(opts?: UseShogoVoiceOptions): UseVoiceConversationResult;
+
+/**
+ * `useChatConversation` (web) — text-only sibling of
+ * {@link useVoiceConversation}.
+ *
+ * Wraps `@ai-sdk/react`'s `useChat` hook, pointed at a Shogo streaming
+ * chat endpoint (default `/api/chat/turn`). The same agent persona +
+ * memory + project context the voice hook drives over an ElevenLabs
+ * Convai websocket is reachable here over a plain HTTPS POST + SSE
+ * stream — no microphone, no `getUserMedia`, no audio context.
+ *
+ * Why a sibling instead of a flag on `useVoiceConversation`: the wire
+ * shapes are different enough (no signed URL, no audio frames, no
+ * `firstMessage`/`characterName` dynamic variables, no `setMuted`)
+ * that a single hook would have a surface area split-brain. The auth
+ * surface (`shogoApiKey` + `projectId` or session cookie) is shared
+ * verbatim, and `BaseChatConversationOptions.conversationId` lines up
+ * with the new `BaseVoiceConversationResult.conversationId` so a
+ * consumer can stitch a single logical conversation across both
+ * transports — see `packages/sdk/README.md` §"Voice + text bridge".
+ *
+ * Streaming + tool-calls
+ * ----------------------
+ * The server declares any caller-registered tools WITHOUT an `execute`
+ * function, so each tool call is streamed back to the client as a
+ * `tool-call` UI part. The hook resolves it by running the matching
+ * entry from `clientTools`, then forwards the result via
+ * `addToolOutput`. The wire pattern matches the existing internal
+ * `useTranslatorChat` (apps/mobile) — see that file for a longer
+ * walk-through of the AI-SDK callback flow.
+ *
+ * Provider requirement
+ * --------------------
+ * No provider required. Unlike `useVoiceConversation`, this hook
+ * doesn't depend on `@elevenlabs/react`'s `ConversationProvider`.
+ *
+ * Consumers should still mount `<ShogoVoiceProvider>` near the root
+ * if they're ALSO using `useShogoVoice`; that's the voice-side
+ * requirement and is unrelated to the chat path.
+ *
+ * Requires the host app to install `@ai-sdk/react` and `ai` as
+ * peer deps; both are optional from the SDK's perspective.
+ *
+ * @experimental V1 surface — shape may evolve before promotion.
+ */
+
+type UseChatConversationOptions = BaseChatConversationOptions;
+type UseChatConversationResult = BaseChatConversationResult;
+/**
+ * Hook that owns the text-chat session lifecycle end-to-end.
+ *
+ * Returns the message list plus imperative helpers (`sendMessage`,
+ * `setMessages`, `appendAssistantMessage`, `appendUserMessage`) and
+ * the AI-SDK status. State management is in-memory only — for durable
+ * threads, persist `messages` yourself (e.g. on `status === 'ready'`)
+ * and rehydrate via `setMessages(...)` on next mount.
+ */
+declare function useChatConversation(options?: UseChatConversationOptions): UseChatConversationResult;
+
+/**
+ * `useShogoChat` — zero-config text-chat hook for generated pod apps.
+ *
+ * Thin alias around {@link useChatConversation} with the pod-friendly
+ * defaults pre-applied:
+ *
+ *   - `api: '/api/chat/turn'` — served same-origin by the app's own
+ *     Hono/Next route, which proxies through the Shogo API via the
+ *     pod's runtime token. No API key is read by the browser.
+ *   - `fetchCredentials: 'same-origin'`
+ *
+ * For external / third-party SDK consumers, drive
+ * `useChatConversation({ shogoApiKey, projectId, ... })` directly —
+ * the bearer path is the right choice when the chat endpoint can't
+ * be reached same-origin.
+ *
+ * @example Minimum viable usage
+ * ```tsx
+ * import { useShogoChat } from '@shogo-ai/sdk/voice/react'
+ *
+ * function ChatBox() {
+ *   const { messages, sendMessage, status } = useShogoChat()
+ *   const [draft, setDraft] = useState('')
+ *   return (
+ *     <>
+ *       {messages.map((m) => <div key={m.id}>{m.parts.map(p => p.type === 'text' ? p.text : '').join('')}</div>)}
+ *       <input value={draft} onChange={(e) => setDraft(e.target.value)} />
+ *       <button onClick={() => { void sendMessage(draft); setDraft('') }} disabled={status === 'streaming'}>
+ *         Send
+ *       </button>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @example Named secondary agents
+ * Pass `agentName` to drive a project-specific persona declared in
+ * `shogo.config.json#agents` and reconciled to the cloud via
+ * `bunx shogo deploy`. Voice + text share one row per name — the
+ * same `agentName` reaches the same record from
+ * `useShogoVoice({ agentName })`.
+ *
+ * ```tsx
+ * function ArchitectChat() {
+ *   const chat = useShogoChat({ agentName: 'architect' })
+ *   // ...
+ * }
+ * ```
+ *
+ * Tool contract: the manifest's `tools: [...]` list is the
+ * server-enforced allowlist. The hook's `clientTools` map holds the
+ * matching handler implementations. Tools the hook registers that
+ * aren't on the manifest's allowlist are silently dropped server-
+ * side.
+ *
+ * @example Voice + text bridge (the customer use case)
+ * ```tsx
+ * const voice = useShogoVoice({ shogoApiKey, projectId })
+ * const chat  = useShogoChat({
+ *   shogoApiKey,
+ *   projectId,
+ *   conversationId: voice.conversationId ?? undefined,
+ * })
+ *
+ * // When the user types while voice is active, mirror it as
+ * // contextual input to the live voice agent rather than going
+ * // through the LLM:
+ * async function send(text) {
+ *   if (voice.status === 'connected') {
+ *     voice.sendContextualUpdate(text)
+ *     chat.appendUserMessage(text) // local-only echo for the bubble
+ *     return
+ *   }
+ *   await chat.sendMessage(text)
+ * }
+ *
+ * // When the voice agent speaks, mirror it into the text thread:
+ * useShogoVoice({
+ *   onMessage: ({ source, message }) => {
+ *     if (source === 'agent') chat.appendAssistantMessage(message)
+ *   },
+ * })
+ * ```
+ *
+ * @experimental V1 surface — shape may evolve before promotion.
+ */
+
+type UseShogoChatOptions = Partial<UseChatConversationOptions>;
+declare function useShogoChat(opts?: UseShogoChatOptions): UseChatConversationResult;
+
+/**
+ * `ShogoVoiceProvider` — root provider that every `useShogoVoice` /
+ * `useVoiceConversation` caller needs to live under.
+ *
+ * Why this exists
+ * ---------------
+ * `@elevenlabs/react` ≥ 1.1 split `useConversation` into a
+ * provider-backed API: every caller of the hook (and therefore every
+ * caller of our `useVoiceConversation` / `useShogoVoice` wrapper) must
+ * have a `<ConversationProvider>` somewhere above it in the tree.
+ * Without it the underlying `useRegisterCallbacks` throws:
+ *
+ *   useRegisterCallbacks must be used within a ConversationProvider
+ *
+ * Re-exporting the provider here keeps consumer code free of a direct
+ * `@elevenlabs/react` import — pods only ever import from
+ * `@shogo-ai/sdk/voice/react`, which means we can swap providers (or
+ * upgrade across breaking versions) without touching every app.
+ *
+ * Usage
+ * -----
+ * Wrap the SDK's voice-aware tree once, near the root of your app:
+ *
+ * ```tsx
+ * import { ShogoVoiceProvider } from '@shogo-ai/sdk/voice/react'
+ *
+ * export default function Root({ children }: { children: React.ReactNode }) {
+ *   return <ShogoVoiceProvider>{children}</ShogoVoiceProvider>
+ * }
+ * ```
+ *
+ * One provider is enough for an entire app — sibling components that
+ * use the voice hook share the same underlying convai session context.
+ * Mounting multiple providers is supported but isolates their
+ * sessions, so do that intentionally (e.g. two completely separate
+ * voice surfaces in one shell).
+ */
+
+interface ShogoVoiceProviderProps {
+    children: React.ReactNode;
+}
+declare function ShogoVoiceProvider(props: ShogoVoiceProviderProps): React.ReactElement;
+
+interface OrganicSphereProps {
+    /**
+     * Returns the current agent-output frequency buffer (length = fftSize,
+     * values 0–255). Typically `useVoiceConversation().getOutputByteFrequencyData`.
+     *
+     * Can also be pointed at `analyserNode.getByteFrequencyData` from any
+     * WebAudio graph for non-ElevenLabs callers.
+     */
+    getFrequencyData?: () => Uint8Array | null;
+    /**
+     * Whether audio is live. When `false` the sphere settles into its
+     * idle pose (no pulsing). Purely cosmetic — the component keeps the
+     * render loop running either way.
+     *
+     * @default true
+     */
+    active?: boolean;
+    /**
+     * Full configuration object (partial). Any unspecified keys fall back
+     * to `DEFAULT_ORGANIC_SPHERE_CONFIG`. Individual convenience props
+     * below (e.g. `lightAColor`) take precedence over the same key inside
+     * `config`, so you can combine a base preset with a single override.
+     */
+    config?: Partial<OrganicSphereConfig>;
+    /** Overrides `config.lightAColor`. */
+    lightAColor?: string;
+    /** Overrides `config.lightBColor`. */
+    lightBColor?: string;
+    /** Overrides `config.rimColor`. */
+    rimColor?: string;
+    /** Overrides `config.rimThreshold`. */
+    rimThreshold?: number;
+    /** Overrides `config.rimPower`. */
+    rimPower?: number;
+    /** Overrides `config.backgroundColor`. */
+    backgroundColor?: string | null;
+    /** Overrides `config.subdivisions` (re-init on change). */
+    subdivisions?: number;
+    /** Overrides `config.maxPixelRatio` (re-init on change). */
+    maxPixelRatio?: number;
+    /**
+     * Extra classes merged onto the wrapping `<div>`. Size the parent
+     * element; the canvas fills it.
+     */
+    className?: string;
+    /** Inline style override for the wrapping `<div>`. */
+    style?: React__default.CSSProperties;
+}
+/**
+ * Audio-reactive organic sphere. See the module docblock for usage.
+ */
+declare function OrganicSphere({ getFrequencyData, active, config: configProp, lightAColor, lightBColor, rimColor, rimThreshold, rimPower, backgroundColor, subdivisions, maxPixelRatio, className, style, }: OrganicSphereProps): react_jsx_runtime.JSX.Element;
+
+interface OrganicParticlesProps {
+    getFrequencyData?: () => Uint8Array | null;
+    active?: boolean;
+    config?: Partial<OrganicParticlesConfig>;
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+/**
+ * Audio-reactive particle cloud. See the module docblock for usage.
+ */
+declare function OrganicParticles({ getFrequencyData, active, config: configProp, className, style, }: OrganicParticlesProps): react_jsx_runtime.JSX.Element;
+
+export { BaseChatConversationOptions, BaseChatConversationResult, OrganicParticles, OrganicParticlesConfig, type OrganicParticlesProps, OrganicSphere, OrganicSphereConfig, type OrganicSphereProps, ShogoVoiceProvider, type ShogoVoiceProviderProps, type UseChatConversationOptions, type UseChatConversationResult, type UseShogoChatOptions, type UseShogoVoiceOptions, type UseVoiceConversationOptions, type UseVoiceConversationResult, useChatConversation, useShogoChat, useShogoVoice, useVoiceConversation };