@bytexbyte/nxtlinq-ai-agent-react-native-development 0.2.0

package/src/context/NxtlinqAgentContext.tsx

@@ -0,0 +1,87 @@
+import {
+  NxtlinqAgent,
+  type AgentConfig,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import {
+  createNxtlinqAgentRN,
+  type CreateNxtlinqAgentRNOptions,
+} from '../createNxtlinqAgent';
+
+const NxtlinqAgentContext = createContext<NxtlinqAgent | null>(null);
+
+export type NxtlinqAgentProviderProps = CreateNxtlinqAgentRNOptions & {
+  children: ReactNode;
+  /** Replace messages when identity fields change (e.g. new chat session). */
+  resetOnIdentityChange?: boolean;
+};
+
+export function NxtlinqAgentProvider({
+  children,
+  resetOnIdentityChange = true,
+  storage,
+  fetchImpl,
+  getTimezone,
+  webrtcModule,
+  webrtc,
+  ...config
+}: NxtlinqAgentProviderProps): React.ReactElement {
+  const agent = useMemo(
+    () =>
+      createNxtlinqAgentRN({
+        storage,
+        fetchImpl,
+        getTimezone,
+        webrtcModule,
+        webrtc,
+        ...config,
+      }),
+    [
+      config.serviceId,
+      config.apiKey,
+      config.apiSecret,
+      config.environment,
+      config.pseudoId,
+      config.externalId,
+      config.defaultModel,
+      config.voiceMode,
+      storage,
+      fetchImpl,
+      getTimezone,
+      webrtcModule,
+      webrtc,
+    ],
+  );
+
+  useEffect(() => {
+    if (!resetOnIdentityChange) return;
+    agent.setMessages([]);
+  }, [agent, resetOnIdentityChange, config.pseudoId, config.externalId]);
+
+  useEffect(() => () => agent.destroy(), [agent]);
+
+  return (
+    <NxtlinqAgentContext.Provider value={agent}>
+      {children}
+    </NxtlinqAgentContext.Provider>
+  );
+}
+
+export function useNxtlinqAgentContext(): NxtlinqAgent {
+  const agent = useContext(NxtlinqAgentContext);
+  if (!agent) {
+    throw new Error(
+      'useNxtlinqAgentContext must be used within <NxtlinqAgentProvider>',
+    );
+  }
+  return agent;
+}
+
+/** Re-export for apps that build the agent manually. */
+export type { AgentConfig };

package/src/createNxtlinqAgent.ts

@@ -0,0 +1,32 @@
+import {
+  NxtlinqAgent,
+  type AgentConfig,
+  type PlatformPorts,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import { createRNPlatformPorts, type CreateRNPlatformPortsOptions } from './ports/createRNPlatformPorts';
+
+export type CreateNxtlinqAgentRNOptions = AgentConfig & CreateRNPlatformPortsOptions;
+
+export type { RNWebRTCModule } from './ports/createRNWebRTCPort';
+
+/**
+ * Create a platform-ready {@link NxtlinqAgent} for React Native custom UIs.
+ */
+export function createNxtlinqAgentRN(options: CreateNxtlinqAgentRNOptions): NxtlinqAgent {
+  const {
+    storage,
+    fetchImpl,
+    getTimezone,
+    webrtcModule,
+    webrtc,
+    ...config
+  } = options;
+  const ports: PlatformPorts = createRNPlatformPorts({
+    storage,
+    fetchImpl,
+    getTimezone,
+    webrtcModule,
+    webrtc,
+  });
+  return new NxtlinqAgent(config, ports);
+}

package/src/hooks/useNxtlinqAgent.ts

@@ -0,0 +1,76 @@
+import type {
+  Message,
+  NxtlinqAgentSnapshot,
+  PostTextTtsResult,
+  SendMessageOptions,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import { useCallback, useSyncExternalStore } from 'react';
+import { useNxtlinqAgentContext } from '../context/NxtlinqAgentContext';
+
+export type UseNxtlinqAgentResult = NxtlinqAgentSnapshot & {
+  agent: ReturnType<typeof useNxtlinqAgentContext>;
+  sendMessage: (
+    text: string,
+    options?: Omit<SendMessageOptions, 'text'>,
+  ) => Promise<void>;
+  loadHistory: (options?: { last?: number }) => Promise<void>;
+  syncVoiceTurnHistory: (options?: { last?: number }) => Promise<void>;
+  setMessages: (messages: Message[]) => void;
+  postTextTts: (text: string) => Promise<PostTextTtsResult>;
+  buildTextTtsPlaybackUri: (result: PostTextTtsResult) => string;
+};
+
+/**
+ * Subscribe to {@link NxtlinqAgent} state for custom RN chat UIs.
+ */
+export function useNxtlinqAgent(): UseNxtlinqAgentResult {
+  const agent = useNxtlinqAgentContext();
+
+  const snapshot = useSyncExternalStore(
+    (onStoreChange) => agent.subscribe(onStoreChange),
+    () => agent.getSnapshot(),
+    () => agent.getSnapshot(),
+  );
+
+  const sendMessage = useCallback(
+    (text: string, options?: Omit<SendMessageOptions, 'text'>) =>
+      agent.sendMessage(text, options),
+    [agent],
+  );
+
+  const loadHistory = useCallback(
+    (options?: { last?: number }) => agent.loadHistory(options),
+    [agent],
+  );
+
+  const syncVoiceTurnHistory = useCallback(
+    (options?: { last?: number }) => agent.syncVoiceTurnHistory(options),
+    [agent],
+  );
+
+  const setMessages = useCallback(
+    (messages: Message[]) => agent.setMessages(messages),
+    [agent],
+  );
+
+  const postTextTts = useCallback(
+    (text: string) => agent.postTextTts(text),
+    [agent],
+  );
+
+  const buildTextTtsPlaybackUri = useCallback(
+    (result: PostTextTtsResult) => agent.buildTextTtsPlaybackUri(result),
+    [agent],
+  );
+
+  return {
+    agent,
+    ...snapshot,
+    sendMessage,
+    loadHistory,
+    syncVoiceTurnHistory,
+    setMessages,
+    postTextTts,
+    buildTextTtsPlaybackUri,
+  };
+}

package/src/hooks/useNxtlinqVoice.ts

@@ -0,0 +1,148 @@
+import type {
+  StartVoiceSessionOptions,
+  VoiceGreetingOptions,
+  VoiceSession,
+  VoiceStatus,
+  VoiceUserInputOptions,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import { VoiceNotSupportedError } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
+import { useNxtlinqAgentContext } from '../context/NxtlinqAgentContext';
+
+export type UseNxtlinqVoiceOptions = Partial<
+  Omit<
+    StartVoiceSessionOptions,
+    'apiKey' | 'apiSecret' | 'pseudoId'
+  >
+>;
+
+export type UseNxtlinqVoiceResult = {
+  voiceStatus: VoiceStatus;
+  voiceSessionId: string | null;
+  isVoiceActive: boolean;
+  startVoice: (options?: UseNxtlinqVoiceOptions) => Promise<VoiceSession>;
+  stopVoice: (reason?: string) => Promise<void>;
+  muteMic: (muted: boolean) => void;
+  interrupt: () => void;
+  getRemoteAudioStream: () => MediaStream | null;
+  getOutputAudioLevel: () => number;
+  sendVoiceUserInput: (options: VoiceUserInputOptions) => void;
+  triggerVoiceGreeting: (
+    options: VoiceGreetingOptions,
+    greetOptions?: { waitForChannel?: boolean; timeoutMs?: number },
+  ) => Promise<void>;
+};
+
+/**
+ * Voice controls for custom RN UIs. Requires `webrtcModule` on {@link NxtlinqAgentProvider}.
+ */
+export function useNxtlinqVoice(): UseNxtlinqVoiceResult {
+  const agent = useNxtlinqAgentContext();
+  const sessionRef = useRef<VoiceSession | null>(null);
+
+  const snapshot = useSyncExternalStore(
+    (onStoreChange) => agent.subscribe(onStoreChange),
+    () => agent.getSnapshot(),
+    () => agent.getSnapshot(),
+  );
+
+  const refreshSessionRef = useCallback(() => {
+    sessionRef.current = agent.getVoiceSession();
+  }, [agent]);
+
+  const startVoice = useCallback(
+    async (options?: UseNxtlinqVoiceOptions) => {
+      try {
+        const session = await agent.startVoice(options);
+        sessionRef.current = session;
+        return session;
+      } catch (err) {
+        if (err instanceof VoiceNotSupportedError) {
+          throw new Error(
+            'Voice requires react-native-webrtc — pass webrtcModule to NxtlinqAgentProvider.',
+          );
+        }
+        throw err;
+      }
+    },
+    [agent],
+  );
+
+  const stopVoice = useCallback(
+    async (reason?: string) => {
+      await agent.stopVoice(reason);
+      sessionRef.current = null;
+    },
+    [agent],
+  );
+
+  const muteMic = useCallback(
+    (muted: boolean) => {
+      refreshSessionRef();
+      sessionRef.current?.muteMic(muted);
+    },
+    [refreshSessionRef],
+  );
+
+  const interrupt = useCallback(() => {
+    refreshSessionRef();
+    sessionRef.current?.interrupt();
+  }, [refreshSessionRef]);
+
+  const getRemoteAudioStream = useCallback(() => {
+    return agent.getVoiceSession()?.getRemoteAudioStream() ?? null;
+  }, [agent]);
+
+  const getOutputAudioLevel = useCallback(() => {
+    refreshSessionRef();
+    return sessionRef.current?.getOutputAudioLevel() ?? agent.getOutputAudioLevel();
+  }, [refreshSessionRef, agent]);
+
+  const sendVoiceUserInput = useCallback(
+    (options: VoiceUserInputOptions) => {
+      refreshSessionRef();
+      if (sessionRef.current) {
+        sessionRef.current.sendVoiceUserInput(options);
+        return;
+      }
+      agent.sendVoiceUserInput(options);
+    },
+    [refreshSessionRef, agent],
+  );
+
+  const triggerVoiceGreeting = useCallback(
+    (
+      options: VoiceGreetingOptions,
+      greetOptions?: { waitForChannel?: boolean; timeoutMs?: number },
+    ) => agent.triggerVoiceGreeting(options, greetOptions),
+    [agent],
+  );
+
+  return useMemo(
+    () => ({
+      voiceStatus: snapshot.voiceStatus,
+      voiceSessionId: snapshot.voiceSessionId,
+      isVoiceActive: snapshot.voiceSessionId != null,
+      startVoice,
+      stopVoice,
+      muteMic,
+      interrupt,
+      getRemoteAudioStream,
+      getOutputAudioLevel,
+      sendVoiceUserInput,
+      triggerVoiceGreeting,
+    }),
+    [
+      snapshot.voiceStatus,
+      snapshot.voiceSessionId,
+      startVoice,
+      stopVoice,
+      muteMic,
+      interrupt,
+      getRemoteAudioStream,
+      getOutputAudioLevel,
+      sendVoiceUserInput,
+      triggerVoiceGreeting,
+    ],
+  );
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+export {
+  createNxtlinqAgentRN,
+  type CreateNxtlinqAgentRNOptions,
+} from './createNxtlinqAgent';
+
+export {
+  NxtlinqAgentProvider,
+  useNxtlinqAgentContext,
+  type NxtlinqAgentProviderProps,
+  type AgentConfig,
+} from './context/NxtlinqAgentContext';
+
+export { useNxtlinqAgent, type UseNxtlinqAgentResult } from './hooks/useNxtlinqAgent';
+export { useNxtlinqVoice, type UseNxtlinqVoiceResult, type UseNxtlinqVoiceOptions } from './hooks/useNxtlinqVoice';
+
+export {
+  createAsyncStoragePort,
+  type AsyncStorageLike,
+} from './ports/createAsyncStoragePort';
+export { createRNHttpPort } from './ports/createRNHttpPort';
+export {
+  createRNPlatformPorts,
+  type CreateRNPlatformPortsOptions,
+} from './ports/createRNPlatformPorts';
+export {
+  createRNWebRTCPort,
+  type RNWebRTCModule,
+} from './ports/createRNWebRTCPort';
+export {
+  fetchUriAsDataUriAttachment,
+  uriToVoiceImageAttachment,
+} from './utils/fetchUriAsDataUri';
+export {
+  ensureRecordAudioPermission,
+  MicrophonePermissionDeniedError,
+} from './utils/ensureRecordAudioPermission';
+export {
+  ensureIOSAudioSessionForVoiceCapture,
+  markIOSAudioSessionReady,
+  markIOSVoiceCaptureCompleted,
+  notifyIOSVoiceSessionEnded,
+  setIOSAudioSessionPrewarmHandler,
+  waitForIOSAudioSessionReady,
+  waitForIOSVoiceCaptureRelease,
+} from './utils/iosAudioSessionReady';
+
+// Re-export core types consumers need in custom UIs
+export type {
+  Message,
+  Attachment,
+  AgentResponse,
+  AgentConfig as CoreAgentConfig,
+  SendMessageOptions,
+  NxtlinqAgentSnapshot,
+  ToolUse,
+  StartVoiceSessionOptions,
+  VoiceSession,
+  VoiceStatus,
+  VoiceTranscriptEvent,
+  VoiceDoneEvent,
+  VoiceUserInputOptions,
+  VoiceGreetingOptions,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';
+
+export {
+  NxtlinqAgent,
+  setApiHosts,
+  startVoiceSessionWithPort,
+  createBrowserWebRTCPort,
+  VoiceNotSupportedError,
+  mapServerHistoryToMessages,
+  appendServerHistoryIntoMessages,
+  STORAGE_KEYS,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';

package/src/ports/createAsyncStoragePort.ts

@@ -0,0 +1,16 @@
+import type { StoragePort } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+
+/** Minimal AsyncStorage surface (matches @react-native-async-storage/async-storage). */
+export type AsyncStorageLike = {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+};
+
+export function createAsyncStoragePort(storage: AsyncStorageLike): StoragePort {
+  return {
+    getItem: (key) => storage.getItem(key),
+    setItem: (key, value) => storage.setItem(key, value),
+    removeItem: (key) => storage.removeItem(key),
+  };
+}

package/src/ports/createRNHttpPort.ts

@@ -0,0 +1,11 @@
+import type { HttpPort } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+
+/** React Native global `fetch` (same signature as browser). */
+export function createRNHttpPort(fetchImpl: typeof fetch = globalThis.fetch): HttpPort {
+  if (!fetchImpl) {
+    throw new Error('fetch is not available — pass a fetch implementation to createRNHttpPort');
+  }
+  return {
+    fetch: (input, init) => fetchImpl(input, init),
+  };
+}

package/src/ports/createRNPlatformPorts.ts

@@ -0,0 +1,37 @@
+import type { PlatformPorts, WebRTCPort } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import { createAsyncStoragePort, type AsyncStorageLike } from './createAsyncStoragePort';
+import { createRNHttpPort } from './createRNHttpPort';
+import { createRNWebRTCPort, type RNWebRTCModule } from './createRNWebRTCPort';
+
+export type CreateRNPlatformPortsOptions = {
+  storage: AsyncStorageLike;
+  fetchImpl?: typeof fetch;
+  getTimezone?: () => string;
+  /** Pass `react-native-webrtc` exports to enable voice (M2). */
+  webrtcModule?: RNWebRTCModule;
+  /** Pre-built port (overrides `webrtcModule`). */
+  webrtc?: WebRTCPort;
+};
+
+export function createRNPlatformPorts(
+  options: CreateRNPlatformPortsOptions,
+): PlatformPorts {
+  const webrtc =
+    options.webrtc
+    ?? (options.webrtcModule ? createRNWebRTCPort(options.webrtcModule) : undefined);
+
+  return {
+    storage: createAsyncStoragePort(options.storage),
+    http: createRNHttpPort(options.fetchImpl),
+    webrtc,
+    getTimezone:
+      options.getTimezone
+      ?? (() => {
+        try {
+          return Intl.DateTimeFormat().resolvedOptions().timeZone;
+        } catch {
+          return 'UTC';
+        }
+      }),
+  };
+}