supafone-labs 0.3.0 → 0.3.2

package/README.md

@@ -1,18 +1,18 @@
-# @supafonesupafone-labs
+# supafone-labs
 
 **The TypeScript client for the Supafone agent framework.**
 
 Use this package to create hosted Supafone agents from code: inbound
 receptionists, outbound sales agents, web agents, Supafone-managed phone
 numbers, built-in stages, tools, recordings, transcripts, widgets, and Supafone
-Pro watcher. It also includes the [Supafone Labs cloud](https:/supafone-labs.supafone.ai)
+Pro watcher. It also includes the [Supafone Labs cloud](https://labs.supafone.ai)
 sidecar oracle, hosted TTS/STT, live multilingual transcription, the builder,
 and the adversarial QA suite.
 
 Dependency-free. Works in Node 18+ and the browser (native `fetch` / `WebSocket`).
 
 ```bash
-npm i @supafonesupafone-labs
+npm i supafone-labs
 ```
 
 ## Keys
@@ -22,7 +22,7 @@ The SDK talks to two related APIs:
 | Environment variable | Key shape | Used for |
 | --- | --- | --- |
 | `SUPAFONE_LABS_API_KEY` | `sl_live_...` | Labs cloud oracle, hosted TTS/STT, logs, usage, QA, optimizer |
-| `SUPAFONE_API_KEY` | `sf_live_...` | Hosted Supafone agents on `/api/v1supafone-labs/*` |
+| `SUPAFONE_API_KEY` | `sf_live_...` | Hosted Supafone agents on `/api/v1/labs/*` |
 
 If you only use hosted-agent methods, `SUPAFONE_API_KEY` is enough. If you use
 both products from one SDK instance, pass `SUPAFONE_API_KEY` as
@@ -31,7 +31,7 @@ both products from one SDK instance, pass `SUPAFONE_API_KEY` as
 ## Quick start
 
 ```ts
-import { Supafone } from "@supafonesupafone-labs";
+import { Supafone } from "supafone-labs";
 
 const supafone = new Supafone({ apiKey: process.env.SUPAFONE_LABS_API_KEY! });
 
@@ -51,7 +51,7 @@ the agent is doing fine — say nothing.
 ## Spawn a hosted Supafone agent
 
 Use the same package to create finished Supafone agents from code. This hits the
-Supafone API (`/api/v1supafone-labs/*`), not a raw Ultravox endpoint: Supafone keeps the
+Supafone API (`/api/v1/labs/*`), not a raw Ultravox endpoint: Supafone keeps the
 multistage state machine, managed voice accounts, tools, recordings,
 transcripts, account sync, and Supafone Pro watcher attached.
 
@@ -59,8 +59,23 @@ The default path is fully Supafone-managed. Developers do **not** need a Twilio
 account, Ultravox account, or voice-provider account to buy a number and launch
 an agent.
 
+Supafone Labs has two main features:
+
+- **Agent Factory**: create the complete hosted agent with managed provider
+  defaults and one Supafone API key.
+- **Self-healing watcher**: enable `labs.enabled` to attach the Supafone Labs
+  second mind to a hosted or BYOK agent.
+
+BYOK is advanced and split into three independent lanes:
+
+| Lane | Examples |
+| --- | --- |
+| Agent/provider stack | Ultravox, Retell, Vapi, Bland, LiveKit, Pipecat, GPT Realtime, Grok |
+| Telephony | Twilio, Telnyx, Plivo, SignalWire, SIP/custom trunks |
+| TTS | Cartesia, ElevenLabs, Inworld, Deepgram, custom TTS |
+
 ```ts
-import { Supafone } from "@supafonesupafone-labs";
+import { Supafone } from "supafone-labs";
 
 const supafone = new Supafone({
   apiKey: process.env.SUPAFONE_LABS_API_KEY || process.env.SUPAFONE_API_KEY!,
@@ -88,6 +103,21 @@ const inbound = await supafone.labs.agents.createInboundWithNumber({
     enabled: true,
     model: "gemma",
   },
+  recording: {
+    enabled: true,
+    recordAudio: true,
+    consentRequired: true,
+    announcement: "This call may be recorded for quality and training.",
+    retentionDays: 30,
+    redactPii: true,
+  },
+  transcription: {
+    enabled: true,
+    provider: "supafone_managed",
+    language: "multi",
+    diarization: true,
+    timestamps: true,
+  },
   tools: {
     callRouting: true,
     scheduling: true,
@@ -128,8 +158,16 @@ const outbound = await supafone.labs.agents.createOutboundWithNumber({
 console.log(outbound.number?.assignment);
 ```
 
+Call artifacts are available from the same hosted-agent namespace:
+
+```ts
+await supafone.labs.calls.list({ agentKey: "medivoice-intake" });
+await supafone.labs.recordings.list({ agentKey: "medivoice-intake" });
+await supafone.labs.transcripts.list({ agentKey: "medivoice-intake" });
+```
+
 If you already own telephony, keep Supafone's agent framework and configure
-BYOK as the advanced path:
+that BYOK lane as the advanced path:
 
 ```ts
 await supafone.labs.telephony.configure({
@@ -143,6 +181,40 @@ await supafone.labs.telephony.configure({
 });
 ```
 
+Or configure all three BYOK lanes in one agent payload:
+
+```ts
+await supafone.labs.agents.createOutbound({
+  agentKey: "speed-to-lead-byok",
+  name: "Speed to lead BYOK",
+  byok: {
+    agentProvider: {
+      provider: "ultravox",
+      apiKey: process.env.ULTRAVOX_API_KEY!,
+    },
+    telephony: {
+      mode: "byok",
+      provider: "telnyx",
+      credentials: {
+        apiKey: process.env.TELNYX_API_KEY!,
+        connectionId: process.env.TELNYX_CONNECTION_ID!,
+        fromNumber: "+14155550123",
+      },
+    },
+    tts: {
+      provider: "cartesia",
+      apiKey: process.env.CARTESIA_API_KEY!,
+    },
+  },
+  labs: {
+    enabled: true,
+    mode: "byok",
+    managedInfrastructure: false,
+    tts: { provider: "cartesia" },
+  },
+});
+```
+
 ## Verify the hosted-agent path
 
 Use the production smoke example before handing a key to a customer or testing a
@@ -227,18 +299,18 @@ inspect gateway responses.
 
 ## Module format
 
-Ships **both ESM and CommonJS**. `import { Supafone } from "@supafonesupafone-labs"`
-and `const { Supafone } = require("@supafonesupafone-labs")` both work, with full types.
+Ships **both ESM and CommonJS**. `import { Supafone } from "supafone-labs"`
+and `const { Supafone } = require("supafone-labs")` both work, with full types.
 
 ## API
 
 | Method | Endpoint |
 | --- | --- |
-| `labs.capabilities()` | `GET /api/v1supafone-labs/capabilities` on the Supafone API |
-| `labs.agents.create/createInbound/createOutbound/list/get` | `/api/v1supafone-labs/agents*` on the Supafone API |
+| `labs.capabilities()` | `GET /api/v1/labs/capabilities` on the Supafone API |
+| `labs.agents.create/createInbound/createOutbound/list/get` | `/api/v1/labs/agents*` on the Supafone API |
 | `labs.agents.createInboundWithNumber/createOutboundWithNumber` | Agent creation plus Supafone-managed number buy/assign |
-| `labs.phoneNumbers.search/buy/assign/list/buyAndAssign` | `/api/v1supafone-labs/phone-numbers*` |
-| `labs.telephony.get/configure/useSupafoneManaged` | `/api/v1supafone-labs/telephony` |
+| `labs.phoneNumbers.search/buy/assign/list/buyAndAssign` | `/api/v1/labs/phone-numbers*` |
+| `labs.telephony.get/configure/useSupafoneManaged` | `/api/v1/labs/telephony` |
 | `labs.presets.list()` · `labs.tools.list()` · `labs.voices.list()` | Supafone hosted-agent discovery |
 | `whisper(transcript, opts?)` | convenience over the oracle |
 | `oracle({ messages, model?, ... })` | `POST /v1/oracle/complete` |
@@ -250,7 +322,7 @@ and `const { Supafone } = require("@supafonesupafone-labs")` both work, with ful
 | `qa.run/history` | `/v1/qa/*` |
 | `optimizer.improve/standing` | `/v1/optimizer/*` |
 
-Get a key (5 free minutes, no card): <https:/supafone-labs.supafone.ai/get-key.html>
+Get a key (5 free minutes, no card): <https://labs.supafone.ai/get-key.html>
 
 The runtime, all provider adapters, and the offline (bring-your-own-keys) mode
 are open source and MIT-licensed — the Python package `pip install supafone-labs`