@shogo-ai/voice 1.10.0 → 2.4.2

package/dist/react/conversation.d.cts

@@ -0,0 +1,134 @@
+import { B as BaseVoiceConversationOptions, a as BaseVoiceConversationResult } from '../types-Bfhu-aQH.cjs';
+import * as React from 'react';
+
+/**
+ * Platform-agnostic memory plumbing for the voice hooks:
+ *
+ *   - `createMemoryAddTool` builds the canonical `add_memory` client
+ *     tool that POSTs to `memoryAddPath`. Mounted on the convai
+ *     session's `clientTools` map so the agent can persist user-stated
+ *     facts via a tool call.
+ *   - `createMemoryContextInjector` returns an `inject(userText)`
+ *     function that fetches `limit` relevant memory chunks from
+ *     `memoryRetrievePath` and forwards them to the active session as
+ *     a contextual update — but only if the chunks differ from the
+ *     last batch we sent (so we don't re-inject the same context every
+ *     turn).
+ *
+ * Both factories take only the bits they need (a `PostJson`, a couple
+ * of refs) so the same code runs on web and native without DOM hooks.
+ */
+
+type ClientToolFn = (params: Record<string, unknown>) => Promise<string> | string;
+
+/**
+ * `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;
+
+interface LiveVoiceSessionResponse {
+    sessionId: string;
+    sdp: string;
+}
+interface LiveTranscriptTurn {
+    role: 'user' | 'assistant';
+    text: string;
+}
+interface LiveDelegationRequest {
+    delegationId: string;
+    /** Recent conversation, oldest first, including the turn that triggered the delegation. */
+    transcript: LiveTranscriptTurn[];
+}
+interface UseLiveVoiceConversationOptions {
+    /** Mint a GPT-Live WebRTC answer from the browser's SDP offer. */
+    mintSession: (sdp: string) => Promise<LiveVoiceSessionResponse>;
+    /** Function tools for sessions that use Responses delegation. */
+    clientTools?: Record<string, ClientToolFn>;
+    /**
+     * Answer a client delegation. GPT-Live's delegation event carries no task
+     * text, so the handler gets the recent transcript instead. A returned
+     * string is sent back as spoken commentary for that delegation.
+     */
+    onDelegation?: (request: LiveDelegationRequest) => Promise<string | null | void>;
+    onError?: (error: unknown) => void;
+    onMessage?: (message: {
+        source: string;
+        message: string;
+    }) => void;
+}
+type UseLiveVoiceConversationResult = BaseVoiceConversationResult & {
+    /** Recent transcript across sessions started by this hook, oldest first. */
+    getTranscript: () => LiveTranscriptTurn[];
+};
+/**
+ * GPT-Live WebRTC conversation hook. The API route is injected so this
+ * package remains transport-focused and can be used by SDK consumers too.
+ */
+declare function useLiveVoiceConversation(options: UseLiveVoiceConversationOptions): UseLiveVoiceConversationResult;
+
+/**
+ * `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;
+
+export { type LiveDelegationRequest, type LiveTranscriptTurn, type LiveVoiceSessionResponse, ShogoVoiceProvider, type ShogoVoiceProviderProps, type UseLiveVoiceConversationOptions, type UseLiveVoiceConversationResult, type UseVoiceConversationOptions, type UseVoiceConversationResult, useLiveVoiceConversation, useVoiceConversation };

package/dist/react/conversation.d.ts

@@ -0,0 +1,134 @@
+import { B as BaseVoiceConversationOptions, a as BaseVoiceConversationResult } from '../types-Bfhu-aQH.js';
+import * as React from 'react';
+
+/**
+ * Platform-agnostic memory plumbing for the voice hooks:
+ *
+ *   - `createMemoryAddTool` builds the canonical `add_memory` client
+ *     tool that POSTs to `memoryAddPath`. Mounted on the convai
+ *     session's `clientTools` map so the agent can persist user-stated
+ *     facts via a tool call.
+ *   - `createMemoryContextInjector` returns an `inject(userText)`
+ *     function that fetches `limit` relevant memory chunks from
+ *     `memoryRetrievePath` and forwards them to the active session as
+ *     a contextual update — but only if the chunks differ from the
+ *     last batch we sent (so we don't re-inject the same context every
+ *     turn).
+ *
+ * Both factories take only the bits they need (a `PostJson`, a couple
+ * of refs) so the same code runs on web and native without DOM hooks.
+ */
+
+type ClientToolFn = (params: Record<string, unknown>) => Promise<string> | string;
+
+/**
+ * `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;
+
+interface LiveVoiceSessionResponse {
+    sessionId: string;
+    sdp: string;
+}
+interface LiveTranscriptTurn {
+    role: 'user' | 'assistant';
+    text: string;
+}
+interface LiveDelegationRequest {
+    delegationId: string;
+    /** Recent conversation, oldest first, including the turn that triggered the delegation. */
+    transcript: LiveTranscriptTurn[];
+}
+interface UseLiveVoiceConversationOptions {
+    /** Mint a GPT-Live WebRTC answer from the browser's SDP offer. */
+    mintSession: (sdp: string) => Promise<LiveVoiceSessionResponse>;
+    /** Function tools for sessions that use Responses delegation. */
+    clientTools?: Record<string, ClientToolFn>;
+    /**
+     * Answer a client delegation. GPT-Live's delegation event carries no task
+     * text, so the handler gets the recent transcript instead. A returned
+     * string is sent back as spoken commentary for that delegation.
+     */
+    onDelegation?: (request: LiveDelegationRequest) => Promise<string | null | void>;
+    onError?: (error: unknown) => void;
+    onMessage?: (message: {
+        source: string;
+        message: string;
+    }) => void;
+}
+type UseLiveVoiceConversationResult = BaseVoiceConversationResult & {
+    /** Recent transcript across sessions started by this hook, oldest first. */
+    getTranscript: () => LiveTranscriptTurn[];
+};
+/**
+ * GPT-Live WebRTC conversation hook. The API route is injected so this
+ * package remains transport-focused and can be used by SDK consumers too.
+ */
+declare function useLiveVoiceConversation(options: UseLiveVoiceConversationOptions): UseLiveVoiceConversationResult;
+
+/**
+ * `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;
+
+export { type LiveDelegationRequest, type LiveTranscriptTurn, type LiveVoiceSessionResponse, ShogoVoiceProvider, type ShogoVoiceProviderProps, type UseLiveVoiceConversationOptions, type UseLiveVoiceConversationResult, type UseVoiceConversationOptions, type UseVoiceConversationResult, useLiveVoiceConversation, useVoiceConversation };

package/dist/react/conversation.js

@@ -0,0 +1,13 @@
+import {
+  ShogoVoiceProvider,
+  useLiveVoiceConversation,
+  useVoiceConversation
+} from "../chunk-ME3SIZZU.js";
+import "../chunk-ZAW6F3YT.js";
+import "../chunk-Q3TJAJ54.js";
+export {
+  ShogoVoiceProvider,
+  useLiveVoiceConversation,
+  useVoiceConversation
+};
+//# sourceMappingURL=conversation.js.map