@myscheme/voice-navigation-sdk 0.1.0

package/README.md

@@ -0,0 +1,359 @@
+# Voice Navigation SDK
+
+A TypeScript SDK for voice-controlled navigation using Azure Speech-to-Text and AWS Bedrock for intent understanding.
+
+## Features
+
+- 🎤 Real-time speech recognition using Azure Speech SDK
+- 🤖 Intent extraction using AWS Bedrock (Claude)
+- 🧭 Voice-controlled navigation actions
+- 🖱️ Rich browser and media controls
+- ♿ Accessibility-first design
+- 🎨 Customizable floating UI control
+- 📦 Full TypeScript support
+
+## Installation
+
+```bash
+npm install @myscheme/voice-navigation-sdk
+```
+
+## Dependencies
+
+This SDK requires:
+
+- `@aws-sdk/client-bedrock-runtime` - For AWS Bedrock integration
+- `microsoft-cognitiveservices-speech-sdk` - For Azure Speech-to-Text
+
+These are automatically installed as dependencies.
+
+## Quick Start
+
+```typescript
+import { initNavigationOnMicrophone } from "@myscheme/voice-navigation-sdk";
+
+const controller = initNavigationOnMicrophone({
+  // Azure Speech configuration
+  azure: {
+    subscriptionKey: "your-azure-subscription-key",
+    region: "your-azure-region", // e.g., 'eastus'
+  },
+
+  // AWS Bedrock configuration
+  aws: {
+    accessKeyId: "your-aws-access-key-id",
+    secretAccessKey: "your-aws-secret-access-key",
+    modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
+    region: "ap-south-1", // or your preferred region
+  },
+
+  // Optional: Default language
+  language: "en-IN",
+
+  // Optional: Auto-start voice control
+  autoStart: false,
+});
+```
+
+## Configuration
+
+### NavigationConfig
+
+| Property                | Type      | Required | Description                                    |
+| ----------------------- | --------- | -------- | ---------------------------------------------- |
+| `azure.subscriptionKey` | `string`  | ✅       | Azure Speech subscription key                  |
+| `azure.region`          | `string`  | ✅       | Azure Speech region                            |
+| `aws.accessKeyId`       | `string`  | ✅       | AWS access key ID                              |
+| `aws.secretAccessKey`   | `string`  | ✅       | AWS secret access key                          |
+| `aws.modelId`           | `string`  | ✅       | AWS Bedrock model ID                           |
+| `aws.region`            | `string`  | ❌       | AWS region (default: 'ap-south-1')             |
+| `language`              | `string`  | ❌       | Speech recognition language (default: 'en-IN') |
+| `autoStart`             | `boolean` | ❌       | Auto-start voice control (default: false)      |
+| `actionHandlers`        | `object`  | ❌       | Map of custom callbacks keyed by action        |
+| `opensearch`            | `object`  | ❌       | OpenSearch vector search configuration         |
+
+When you provide the optional `opensearch` block, include the following fields:
+
+| Property        | Type     | Required | Description                                                        |
+| --------------- | -------- | -------- | ------------------------------------------------------------------ |
+| `node`          | `string` | ✅       | OpenSearch cluster URL (e.g. `https://cluster.example.com`)        |
+| `username`      | `string` | ✅       | OpenSearch user name                                               |
+| `password`      | `string` | ✅       | OpenSearch password                                                |
+| `index`         | `string` | ✅       | Index name containing your embeddings                              |
+| `vectorField`   | `string` | ❌       | Embedding field (default: `embedding`)                             |
+| `size`          | `number` | ❌       | Result count returned to the browser (default: `5`)                |
+| `numCandidates` | `number` | ❌       | Candidate pool size for k-NN search (default: `Math.max(size*4,20)`)|
+| `minScore`      | `number` | ❌       | Minimum score to accept a hit (default: `0`)                       |
+| `sourceFields`  | `string[]` | ❌     | Source fields to request from OpenSearch                           |
+| `apiPath`       | `string` | ❌       | Browser endpoint that proxies vector search (default: `/api/voice-navigation/vector-search`) |
+
+## Supported Actions
+
+The SDK supports the following voice commands:
+
+### Navigation Actions
+
+- `navigate_home` - Navigate to home page
+- `navigate_search` - Navigate to search page
+- `navigate_faqs` - Navigate to FAQs
+- `navigate_help` - Navigate to help
+- `navigate_contact` - Navigate to contact
+- `navigate_about` - Navigate to about
+- `navigate_screen_reader` - Navigate to screen reader access
+- `navigate_accessibility` - Navigate to accessibility page
+- `navigate_disclaimer` - Navigate to disclaimer
+- `navigate_terms_conditions` - Navigate to terms and conditions
+
+### Page & UI Actions
+
+- `zoom_in` / `zoom_out` - Adjust page zoom
+- `scroll_up` / `scroll_down` / `scroll_left` / `scroll_right` - Scroll in any direction
+- `page_up` / `page_down` - Jump by one viewport height
+- `scroll_top` / `scroll_bottom` - Jump to page edges
+- `go_back` / `go_forward` - Navigate browser history
+- `reload_page` - Reload current page
+- `print_page` - Open print dialog
+- `copy_url` - Copy current page URL to clipboard
+- `open_menu` / `close_menu` - Toggle navigation menus
+- `focus_search` - Focus the primary search input
+- `toggle_fullscreen` / `exit_fullscreen` - Control fullscreen mode
+- `play_media` / `pause_media` - Control media playback
+- `mute_media` / `unmute_media` - Control media volume
+- `stop` - Stop voice control
+
+## API Reference
+
+### VoiceNavigationController
+
+The main controller class for voice navigation.
+
+#### Methods
+
+##### `start(): Promise<void>`
+
+Start voice control and begin listening.
+
+```typescript
+await controller.start();
+```
+
+##### `stop(): Promise<void>`
+
+Stop voice control and process any pending speech.
+
+```typescript
+await controller.stop();
+```
+
+##### `setLanguage(language: string): void`
+
+Change the speech recognition language.
+
+```typescript
+controller.setLanguage("hi-IN"); // Switch to Hindi
+```
+
+##### `setAutoStart(enabled: boolean): void`
+
+Enable or disable auto-start on future page loads.
+
+```typescript
+controller.setAutoStart(true);
+```
+
+##### `destroy(): void`
+
+Clean up and remove the controller.
+
+```typescript
+controller.destroy();
+```
+
+### Events
+
+The SDK emits custom events that you can listen for:
+
+```typescript
+// Listen for state changes
+window.addEventListener("navigate:state-change", (event) => {
+  console.log("State:", event.detail.state);
+});
+
+// Listen for action detection
+window.addEventListener("navigate:action-detected", (event) => {
+  console.log("Action:", event.detail.action);
+});
+
+// Listen for action performance
+window.addEventListener("navigate:action-performed", (event) => {
+  console.log("Performed:", event.detail.performed);
+});
+
+// Listen for errors
+window.addEventListener("navigate:error", (event) => {
+  console.error("Error:", event.detail.error);
+});
+```
+
+## Advanced Usage
+
+### Vector Search with OpenSearch
+
+1. Supply OpenSearch credentials to the client when you initialise the library:
+
+```typescript
+import { initNavigationOnMicrophone } from "@myscheme/voice-navigation-sdk";
+
+initNavigationOnMicrophone({
+  azure: { /* ... */ },
+  aws: { /* ... */ },
+  opensearch: {
+    node: process.env.NEXT_PUBLIC_OPENSEARCH_NODE!,
+    username: process.env.NEXT_PUBLIC_OPENSEARCH_USERNAME!,
+    password: process.env.NEXT_PUBLIC_OPENSEARCH_PASSWORD!,
+    index: "my-embeddings-index",
+    // optional overrides:
+    // vectorField: "embedding",
+    // size: 5,
+    // apiPath: "/api/voice-navigation/vector-search",
+  },
+});
+```
+
+2. Expose a server-side proxy so the browser never talks to OpenSearch directly. In a Next.js project, create a route such as `pages/api/voice-navigation/vector-search.ts`:
+
+```typescript
+import type { NextApiRequest, NextApiResponse } from "next";
+import { createOpenSearchProxyHandler } from "@myscheme/voice-navigation-sdk/server";
+
+const handler = createOpenSearchProxyHandler({
+  // Optionally lock down allowed origins for CORS style checks.
+  allowedOrigins: process.env.OPENSEARCH_ALLOWED_ORIGINS?.split(",") ?? undefined,
+});
+
+export default async function vectorSearchProxy(
+  req: NextApiRequest,
+  res: NextApiResponse,
+) {
+  await handler(req, res);
+}
+
+// Disable Next.js body parsing so the proxy can stream the incoming payload.
+export const config = {
+  api: {
+    bodyParser: false,
+  },
+};
+```
+
+Mount the route at the same `apiPath` you configured on the client (defaults to `/api/voice-navigation/vector-search`). The handler lives in the `@myscheme/voice-navigation-sdk/server` export so it only runs on the server where the official OpenSearch client is available.
+
+### Custom Service Initialization
+
+You can use the individual services separately:
+
+```typescript
+import {
+  AzureSpeechService,
+  BedrockService,
+} from "@myscheme/voice-navigation-sdk";
+
+// Azure Speech Service
+const azureService = new AzureSpeechService({
+  subscriptionKey: "your-key",
+  region: "your-region",
+});
+
+const tokenResponse = await azureService.fetchToken();
+
+// Bedrock Service
+const bedrockService = new BedrockService({
+  region: "ap-south-1",
+  accessKeyId: "your-key",
+  secretAccessKey: "your-secret",
+  modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
+});
+
+const action = await bedrockService.extractAction("zoom in");
+```
+
+### Custom Action Handlers
+
+You can perform actions programmatically:
+
+```typescript
+import { performAgentAction } from "@myscheme/voice-navigation-sdk";
+
+const result = performAgentAction("zoom_in", {
+  onStop: () => console.log("Stopped"),
+});
+
+console.log("Action performed:", result.performed);
+console.log("New zoom:", result.info.newZoom);
+```
+
+## Configuration Tips
+
+Because this SDK executes in the browser, protect your credentials:
+
+- Use short-lived tokens (AWS Cognito, STS) instead of long-term keys.
+- Proxy Bedrock requests through a backend service when possible.
+- Keep Azure Speech keys in secured storage and rotate them regularly.
+- Provide configuration values via runtime injection, not hard-coded literals.
+
+## Browser Support
+
+This SDK requires:
+
+- Modern browser with ES2020 support
+- Microphone access
+- `MediaDevices` API support
+- `fetch` API support
+
+## Security Notes
+
+⚠️ **Important**: Never expose your AWS credentials or API keys in client-side code in production. Consider using:
+
+- AWS Cognito for temporary credentials
+- API Gateway with authorization
+- Backend proxy for sensitive operations
+
+For development, you can use environment variables and a build tool to inject them securely.
+
+## Migration from Script
+
+If you're migrating from the previous script-based approach:
+
+### Before (Script)
+
+```javascript
+// navigation_myscheme.js included in HTML
+// API routes in Next.js pages/api/
+```
+
+### After (Library)
+
+```typescript
+import { initNavigationOnMicrophone } from "@myscheme/voice-navigation-sdk";
+
+const controller = initNavigationOnMicrophone({
+  azure: {
+    /* config */
+  },
+  aws: {
+    /* config */
+  },
+});
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Support
+
+For issues and questions, please open an issue on GitHub.

package/dist/actions.d.ts

@@ -0,0 +1,8 @@
+import type { NavigationAction, ActionContext, ActionResult, AgentActionResponse } from "./types.js";
+export declare const setZoomScale: (scale: number) => number;
+export declare const adjustZoom: (delta: number) => number;
+export declare const formatActionLabel: (action: string) => string;
+export declare const performAgentAction: (action: NavigationAction, context?: ActionContext) => ActionResult;
+export declare const extractAgentAction: (result: any) => AgentActionResponse | null;
+export declare const isAllowedAction: (action: string) => action is NavigationAction;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,mBAAmB,EACpB,MAAM,YAAY,CAAC;AA0EpB,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAS5C,CAAC;AAKF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAM1C,CAAC;AAKF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,MAElD,CAAC;AAKF,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,gBAAgB,EACxB,UAAS,aAAkB,KAC1B,YAoaF,CAAC;AAKF,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,KAAG,mBAAmB,GAAG,IAgCtE,CAAC;AAKF,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,MAAM,IAAI,gBAE1D,CAAC"}