@sinch/functions-runtime 0.1.0-beta.28

package/README.md

@@ -0,0 +1,207 @@
+# @sinch/functions-runtime
+
+Development runtime for Sinch Functions - build serverless voice applications with ease.
+
+## Installation
+
+```bash
+npm install @sinch/functions-runtime
+```
+
+## Quick Start
+
+Create a `function.js` file:
+
+```javascript
+import { IceSvamlBuilder, MenuBuilder, MenuTemplates } from '@sinch/functions-runtime';
+
+// Handle incoming calls
+export async function ice(context, event) {
+  return new IceSvamlBuilder()
+    .say('Welcome to our service! Press 1 for sales, 2 for support.')
+    .runMenu(MenuTemplates.business('Acme Corp').menus)
+    .build();
+}
+
+// Handle menu selections
+export async function pie(context, event) {
+  const selection = event.menuResult?.value;
+
+  if (selection === 'sales') {
+    return new IceSvamlBuilder()
+      .say('Connecting you to sales.')
+      .connectPstn('+15551234567')
+      .build();
+  }
+
+  return new IceSvamlBuilder()
+    .say('Goodbye!')
+    .hangup()
+    .build();
+}
+```
+
+Run locally:
+
+```bash
+npx sinch-runtime
+```
+
+## Features
+
+### SVAML Builders
+
+Build voice responses with a fluent API:
+
+```typescript
+import { IceSvamlBuilder, AceSvamlBuilder, PieSvamlBuilder } from '@sinch/functions-runtime';
+
+// ICE (Incoming Call Event) - handle incoming calls
+const iceResponse = new IceSvamlBuilder()
+  .say('Hello, welcome!')
+  .connectPstn('+15551234567', {
+    cli: '+15559999999',
+    enableAce: true,
+    enableDice: true
+  })
+  .build();
+
+// ACE (Answered Call Event) - handle answered outbound calls
+const aceResponse = new AceSvamlBuilder()
+  .say('The call has been answered.')
+  .continue()
+  .build();
+
+// PIE (Prompt Input Event) - handle user input
+const pieResponse = new PieSvamlBuilder()
+  .say('You pressed ' + selection)
+  .hangup()
+  .build();
+```
+
+### Menu Builder
+
+Create IVR menus with validation:
+
+```typescript
+import { MenuBuilder, MenuTemplates, createMenu } from '@sinch/functions-runtime';
+
+// Use pre-built templates
+const businessMenu = MenuTemplates.business('Acme Corp');
+const yesNoMenu = MenuTemplates.yesNo('Do you want to continue?');
+
+// Or build custom menus
+const customMenu = new MenuBuilder()
+  .prompt('Press 1 for English, 2 for Spanish')
+  .option('1', 'menu(english)')
+  .option('2', 'menu(spanish)')
+  .addSubmenu('english')
+  .prompt('Press 1 for sales, 2 for support')
+  .option('1', 'return(en-sales)')
+  .option('2', 'return(en-support)')
+  .build();
+```
+
+### Cache
+
+Store and retrieve data across function invocations:
+
+```typescript
+import { LocalCache } from '@sinch/functions-runtime';
+
+// In your function
+export async function ice(context, event) {
+  const cache = context.cache;
+
+  // Store data
+  await cache.set('call-count', 1, 3600); // TTL in seconds
+
+  // Retrieve data
+  const count = await cache.get('call-count');
+
+  // Check existence
+  if (await cache.has('call-count')) {
+    // ...
+  }
+}
+```
+
+### Configuration
+
+Access environment variables and secrets:
+
+```typescript
+import { createConfig } from '@sinch/functions-runtime';
+
+export async function ice(context, event) {
+  const config = createConfig(context);
+
+  // Get variables
+  const companyName = config.getVariable('COMPANY_NAME', 'Default');
+
+  // Get secrets
+  const apiKey = config.getSecret('API_KEY');
+
+  // Require variables (throws if missing)
+  const required = config.requireVariable('IMPORTANT_VAR');
+}
+```
+
+## Voice Callbacks
+
+| Callback | Description | Returns |
+|----------|-------------|---------|
+| `ice` | Incoming Call Event - first callback for incoming calls | SVAML |
+| `ace` | Answered Call Event - when outbound call is answered | SVAML |
+| `pie` | Prompt Input Event - user input (DTMF/voice) | SVAML |
+| `dice` | Disconnected Call Event - call ended | None |
+| `notify` | Notification events | None |
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive types:
+
+```typescript
+import type {
+  FunctionContext,
+  IceCallbackData,
+  AceCallbackData,
+  PieCallbackData,
+  SvamletResponse
+} from '@sinch/functions-runtime';
+
+export async function ice(
+  context: FunctionContext,
+  event: IceCallbackData
+): Promise<SvamletResponse> {
+  // Full type safety and IntelliSense!
+}
+```
+
+## API Reference
+
+### Builders
+
+- `IceSvamlBuilder` - Build ICE responses
+- `AceSvamlBuilder` - Build ACE responses
+- `PieSvamlBuilder` - Build PIE responses
+- `MenuBuilder` - Build IVR menus
+- `MenuTemplates` - Pre-built menu templates
+
+### Cache
+
+- `IFunctionCache` - Cache interface
+- `LocalCache` - In-memory cache (development)
+
+### Configuration
+
+- `UniversalConfig` - Configuration utility
+- `createConfig()` - Create config instance
+
+### Types
+
+All callback data types, SVAML types, and handler types are exported for TypeScript users.
+
+## License
+
+MIT