byourside 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 By Your Side
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# By Your Side Node SDK
+
+Zero-dependency Node 18+ SDK for the By Your Side Agent Outbound-Call API. Place objective-driven AI calls, poll for results, and verify webhooks.
+
+## Quickstart
+
+```js
+import { Client, ByoursideError, verifyWebhook } from './src/index.js';
+
+const client = new Client({ apiKey: 'bys_ak_...' });
+```
+
+## Place a call and wait for the result
+
+```js
+try {
+  // Place the call
+  const { callId } = await client.placeCall({
+    to: '+14155550123',
+    objective: 'Confirm the appointment for tomorrow at 2 PM and ask if they need to reschedule.',
+    fields: [
+      { name: 'confirmed', type: 'boolean' },
+      { name: 'new_time', type: 'string' },
+    ],
+  });
+
+  // Poll until the call reaches a terminal status (default timeout: 3 minutes)
+  const call = await client.waitForCall(callId, { timeoutMs: 120_000, intervalMs: 5_000 });
+
+  console.log('Status:', call.status);        // completed | no_answer | voicemail | declined | failed
+  console.log('Extracted fields:', call.extracted);
+} catch (err) {
+  if (err instanceof ByoursideError) {
+    console.error(`[${err.code}] ${err.message}`);
+  } else {
+    throw err;
+  }
+}
+```
+
+## List recent calls
+
+```js
+const calls = await client.listCalls({ limit: 20 });
+calls.forEach((c) => console.log(c.callId, c.status));
+```
+
+## Verify a webhook (Express example)
+
+Receive real-time call events by setting a `webhookUrl` when placing a call. The header `X-BYS-Signature` carries the signature.
+
+```js
+import express from 'express';
+import { verifyWebhook } from './src/index.js';
+
+const app = express();
+
+// IMPORTANT: parse the body as raw bytes so the signature can be verified.
+app.post('/webhooks/bys', express.raw({ type: 'application/json' }), (req, res) => {
+  const sig = req.headers['x-bys-signature'];
+  const rawBody = req.body.toString('utf8');
+
+  if (!verifyWebhook(sig, rawBody, process.env.BYS_WEBHOOK_SECRET)) {
+    return res.status(400).send('Bad signature');
+  }
+
+  const event = JSON.parse(rawBody);
+  console.log('Webhook event:', event.callId, event.status);
+  res.status(200).send('OK');
+});
+```
+
+## Call status values
+
+| Status | Meaning |
+|---|---|
+| `queued` | Accepted, not yet dialing |
+| `in_progress` | Call is active |
+| `completed` | Call finished; summary + fields available |
+| `no_answer` | Rang but nobody picked up |
+| `voicemail` | Reached voicemail |
+| `declined` | Call rejected by the recipient |
+| `failed` | Carrier or trunk error |
+
+Terminal statuses (waitForCall stops here): `completed`, `no_answer`, `voicemail`, `declined`, `failed`.
+
+## Error codes
+
+`ByoursideError` instances carry `.code` (a token string) and `.status` (HTTP status, 0 for network errors).
+
+| Code | Meaning |
+|---|---|
+| `destination_blocked` | That destination is not allowed (premium, IRSF, or unsupported country). |
+| `invalid_number` | The destination number is invalid (use full E.164, e.g. +14155550123). |
+| `to_required` | A destination number (to) is required. |
+| `objective_required` | An objective for the call is required. |
+| `caller_id_not_owned` | That caller ID is not a number on your account. |
+| `rate_limited` | Rate limit reached. Try again shortly. |
+| `over_minute_cap` | Outbound usage limit reached for now. |
+| `unauthorized` | Invalid or missing API key. |
+| `not_found` | No call found with that id (or it does not belong to your account). |
+| `placement_failed` | The call could not be placed (carrier/trunk issue). Try again shortly. |
+| `store_error` | Temporary service error. Please retry shortly. |
+| `timeout` | waitForCall hit the timeout before reaching a terminal status. |
+| `network_error` | Could not reach the API (network failure). |
+
+## Constructor options
+
+```js
+new Client({
+  apiKey,                              // required
+  baseUrl,                             // default: 'https://api.byourside.ai'
+  fetchImpl,                           // override global fetch (useful for tests)
+  sleep,                               // override the poll sleep (useful for tests)
+})
+```
+
+## Development
+
+```
+node --check src/*.js   # syntax check
+node --test             # run all tests (run from sdks/node/)
+```
+
+No dependencies are required. Node 18+ is needed for built-in `fetch`.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "byourside",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "By Your Side SDK: give an AI a phone (outbound objective-driven calls).",
+  "license": "MIT",
+  "author": "By Your Side",
+  "homepage": "https://byourside.ai/docs/agent-api",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/allexp1/voip-agent.git",
+    "directory": "sdks/node"
+  },
+  "keywords": ["voice", "ai", "phone", "outbound", "agent", "sdk", "voip", "calls"],
+  "files": ["src", "README.md", "LICENSE"],
+  "main": "src/index.js",
+  "scripts": { "test": "node --test" },
+  "engines": { "node": ">=18" }
+}

package/src/client.js

@@ -0,0 +1,65 @@
+// By Your Side SDK client. Zero deps (built-in fetch). Throws ByoursideError on any
+// non-2xx or network failure. fetchImpl + sleep injectable for tests.
+import { mapError, ByoursideError } from './errors.js';
+
+const TERMINAL = new Set(['completed', 'no_answer', 'voicemail', 'declined', 'failed']);
+
+export class Client {
+  constructor({ apiKey, baseUrl = 'https://api.byourside.ai', fetchImpl = globalThis.fetch, sleep } = {}) {
+    if (!apiKey) throw new ByoursideError('apiKey is required', 0, 'no_api_key');
+    this._apiKey = apiKey;
+    this._base = String(baseUrl).replace(/\/+$/, '');
+    this._fetch = fetchImpl;
+    this._sleep = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  }
+
+  async _request(method, path, body) {
+    const opts = { method, headers: { Authorization: `Bearer ${this._apiKey}` } };
+    if (body !== undefined && method !== 'GET') {
+      opts.headers['content-type'] = 'application/json';
+      opts.body = JSON.stringify(body);
+    }
+    let res;
+    try { res = await this._fetch(`${this._base}${path}`, opts); }
+    catch (e) { throw new ByoursideError(mapError(0, null), 0, 'network_error'); }
+    let data = null;
+    try { data = await res.json(); } catch { data = null; }
+    if (!res.ok) throw new ByoursideError(mapError(res.status, data), res.status, (data && data.error) || 'error');
+    return data;
+  }
+
+  placeCall({ to, objective, context, fields, webhookUrl, callerId } = {}) {
+    const body = { to, objective };
+    if (context !== undefined) body.context = context;
+    if (fields !== undefined) body.fields = fields;
+    if (webhookUrl !== undefined) body.webhookUrl = webhookUrl;
+    if (callerId !== undefined) body.callerId = callerId;
+    return this._request('POST', '/v1/agent/calls', body);
+  }
+
+  getCall(callId) {
+    return this._request('GET', `/v1/agent/calls/${encodeURIComponent(callId)}`);
+  }
+
+  async listCalls({ limit = 20 } = {}) {
+    const n = Math.min(Math.max(1, Number(limit) || 20), 100);
+    const data = await this._request('GET', `/v1/agent/calls?limit=${n}`);
+    return (data && data.calls) || [];
+  }
+
+  // Poll getCall until status is terminal or timeoutMs elapses. Throws ByoursideError
+  // code 'timeout' if still non-terminal. timeoutMs/intervalMs in milliseconds.
+  async waitForCall(callId, { timeoutMs = 180000, intervalMs = 3000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const call = await this.getCall(callId);
+      if (call && TERMINAL.has(call.status)) return call;
+      if (Date.now() + intervalMs > deadline) {
+        throw new ByoursideError(`Call ${callId} did not finish within ${Math.round(timeoutMs / 1000)}s`, 0, 'timeout');
+      }
+      await this._sleep(intervalMs);
+    }
+  }
+}
+
+export { TERMINAL };

package/src/errors.js

@@ -0,0 +1,32 @@
+// Typed error + token->message mapping for the By Your Side SDK. Mirrors the table
+// used by the MCP server. Never includes the API key.
+const TOKEN_MESSAGES = {
+  destination_blocked: 'That destination is not allowed (premium, IRSF, or unsupported country).',
+  invalid_number: 'The destination number is invalid (use full E.164, e.g. +14155550123).',
+  to_required: 'A destination number (to) is required.',
+  objective_required: 'An objective for the call is required.',
+  caller_id_not_owned: 'That caller ID is not a number on your account.',
+  rate_limited: 'Rate limit reached. Try again shortly.',
+  over_minute_cap: 'Outbound usage limit reached for now.',
+  unauthorized: 'Invalid or missing API key.',
+  not_found: 'No call found with that id (or it does not belong to your account).',
+  placement_failed: 'The call could not be placed (carrier/trunk issue). Try again shortly.',
+  store_error: 'Temporary service error. Please retry shortly.',
+};
+
+export function mapError(status, body) {
+  const token = body && typeof body === 'object' ? String(body.error || '') : '';
+  if (token && TOKEN_MESSAGES[token]) return TOKEN_MESSAGES[token];
+  if (!status || status >= 500) return 'Temporary service error. Please retry shortly.';
+  if (token) return `Request failed (${token}).`;
+  return `Request failed with status ${status}.`;
+}
+
+export class ByoursideError extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.name = 'ByoursideError';
+    this.status = status;
+    this.code = code;
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { Client } from './client.js';
+export { ByoursideError } from './errors.js';
+export { verifyWebhook } from './webhooks.js';

package/src/webhooks.js

@@ -0,0 +1,18 @@
+// Verify a By Your Side webhook signature header. Never throws; returns boolean.
+// Header: "t=<unix_seconds>,v1=<hex>"; sig = HMAC-SHA256(secret, `${t}.${rawBody}`).
+import crypto from 'node:crypto';
+
+export function verifyWebhook(signatureHeader, rawBody, secret, { toleranceSec = 300 } = {}) {
+  try {
+    if (!signatureHeader || !secret) return false;
+    const parts = Object.fromEntries(String(signatureHeader).split(',').map((kv) => {
+      const i = kv.indexOf('='); return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
+    }));
+    const t = Number(parts.t); const v1 = parts.v1;
+    if (!Number.isFinite(t) || !v1) return false;
+    if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
+    const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
+    const a = Buffer.from(expected); const b = Buffer.from(String(v1));
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+  } catch { return false; }
+}