@avakado.ai/schemas 1.1.15 → 1.1.17

package/media.d.ts

@@ -0,0 +1,46 @@
+export interface AudioWire {
+    encoding: string;
+    rate: number;
+}
+
+export interface MediaPlan {
+    channel: AudioWire;
+    provider: {
+        name: string;
+        input: AudioWire;
+        output: AudioWire;
+    };
+    uplink: string;
+    downlink: string;
+}
+
+export class MediaPlanError extends Error {
+    name: "MediaPlanError";
+}
+
+export const CONVERTERS: Set<string>;
+export const CHANNEL_CATALOGS: Record<string, {
+    symmetric: boolean;
+    wires: AudioWire[];
+    defaultWire: AudioWire;
+}>;
+export const PROVIDER_CARDS: Record<string, {
+    symmetric: boolean;
+    wires?: AudioWire[];
+    input?: AudioWire;
+    output?: AudioWire;
+}>;
+
+export function sameWire(a: AudioWire | null | undefined, b: AudioWire | null | undefined): boolean;
+export function wireKey(value: AudioWire): string;
+export function converterKey(from: AudioWire, to: AudioWire): string;
+export function normalizeChannelName(name: string): string;
+export function normalizeProviderName(name: string): string;
+export function resolveChannelWire(channelName: string, config?: { media?: AudioWire }): AudioWire;
+export function selectChannelMedia(channelName: string, selected: AudioWire): AudioWire;
+export function negotiateCall(input: {
+    channelName: string;
+    channelConfig?: { media?: AudioWire };
+    provider: string;
+}): MediaPlan;
+export function providerAudioFormat(provider: string, value: AudioWire): { type?: string; rate?: number; mimeType?: string };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avakado.ai/schemas",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "Canonical Mongo schemas, models, enums and index declarations shared by the Avakado services.",
   "license": "UNLICENSED",
   "type": "module",
@@ -31,6 +31,11 @@
       "import": "./src/enums/index.js",
       "default": "./src/enums/index.js"
     },
+    "./media": {
+      "types": "./media.d.ts",
+      "import": "./src/media.js",
+      "default": "./src/media.js"
+    },
     "./runtime": {
       "types": "./runtime.d.ts",
       "import": "./src/runtime.js",
@@ -43,6 +48,7 @@
     "types.d.ts",
     "models.d.ts",
     "enums.d.ts",
+    "media.d.ts",
     "runtime.d.ts",
     "README.md",
     "LICENSE"

package/src/enums/index.js

@@ -58,7 +58,7 @@ export const LEDGER_CATEGORY = {
 export const CONVERSATION_STATUS = ["open", "pending", "snoozed", "completed", "closed", "archived", "spam"];
 export const CONVERSATION_PRIORITY = ["low", "normal", "high", "urgent"];
 
-export const CAMPAIGN_STATUS = ["pending", "active", "completed"];
+export const CAMPAIGN_STATUS = ["pending", "active", "completed", "failed", "partial"];
 export const TASK_STATUS = ["pending", "in-progress", "completed", "failed", "skipped"];
 export const TASK_TYPES = ["quick", "webhook"];
 export const TASK_REFERENCE_TYPES = ["Message", "CallSession"];

package/src/index.js

@@ -1,4 +1,5 @@
 import "./models/index.js";
 export * from "./models/index.js";
 export * from "./enums/index.js";
+export * from "./media.js";
 export { configureSchemas, defineModel, getSchemaConfig } from "./runtime.js";

package/src/media.js

@@ -0,0 +1,200 @@
+// A wire is the only audio description the platform passes around: { encoding, rate }.
+// Channel menus and provider cards live here. A call stores the plan these two produce.
+// Adding a carrier is a catalog entry. Adding a conversion is a key in CONVERTERS.
+
+const PROVIDER_ALIASES = {
+    openai: "openai",
+    gemini: "gemini",
+    google: "gemini",
+};
+
+function wire(encoding, rate) {
+    return { encoding, rate: Number(rate) };
+}
+
+function copyWire(value) {
+    return wire(value.encoding, value.rate);
+}
+
+export function sameWire(a, b) {
+    return Boolean(a && b && a.encoding === b.encoding && Number(a.rate) === Number(b.rate));
+}
+
+export function wireKey(value) {
+    return `${value.encoding}:${Number(value.rate)}`;
+}
+
+export function converterKey(from, to) {
+    if (sameWire(from, to)) return "identity";
+    return `${wireKey(from)}->${wireKey(to)}`;
+}
+
+export class MediaPlanError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MediaPlanError";
+    }
+}
+
+// Pairs AudioConverter can run. identity is free. A missing key fails call creation.
+export const CONVERTERS = new Set([
+    "identity",
+    "pcm16:8000->pcm16:16000",
+    "pcm16:8000->pcm16:24000",
+    "pcm16:24000->pcm16:8000",
+    "pcm16:24000->pcm16:16000",
+    "pcm16:24000->g711_ulaw:8000",
+    "g711_ulaw:8000->pcm16:16000",
+]);
+
+export const CHANNEL_CATALOGS = {
+    exotel: {
+        symmetric: true,
+        wires: [wire("pcm16", 8000), wire("pcm16", 16000), wire("pcm16", 24000)],
+        defaultWire: wire("pcm16", 8000),
+    },
+    whatsapp: {
+        symmetric: true,
+        wires: [wire("g711_ulaw", 8000), wire("g711_alaw", 8000)],
+        defaultWire: wire("g711_ulaw", 8000),
+    },
+    twilio: {
+        symmetric: true,
+        wires: [wire("g711_ulaw", 8000)],
+        defaultWire: wire("g711_ulaw", 8000),
+    },
+    tatatele: {
+        symmetric: true,
+        wires: [wire("g711_ulaw", 8000)],
+        defaultWire: wire("g711_ulaw", 8000),
+    },
+};
+
+export const PROVIDER_CARDS = {
+    openai: {
+        symmetric: true,
+        wires: [
+            wire("pcm16", 8000),
+            wire("pcm16", 16000),
+            wire("pcm16", 24000),
+            wire("g711_ulaw", 8000),
+            wire("g711_alaw", 8000),
+        ],
+    },
+    gemini: {
+        symmetric: false,
+        input: wire("pcm16", 16000),
+        output: wire("pcm16", 24000),
+    },
+};
+
+export function normalizeChannelName(name) {
+    const key = String(name || "").trim().toLowerCase().replace(/[\s_-]+/g, "");
+    if (key === "tatatele") return "tatatele";
+    return key;
+}
+
+export function normalizeProviderName(name) {
+    const key = String(name || "").trim().toLowerCase();
+    return PROVIDER_ALIASES[key] || key;
+}
+
+function catalogFor(channelName) {
+    const key = normalizeChannelName(channelName);
+    const catalog = CHANNEL_CATALOGS[key];
+    if (!catalog) {
+        throw new MediaPlanError(`No audio catalog for channel "${channelName}"`);
+    }
+    return { key, catalog };
+}
+
+function requireWire(catalog, selected) {
+    const match = catalog.wires.find((item) => sameWire(item, selected));
+    if (!match) {
+        const allowed = catalog.wires.map(wireKey).join(", ");
+        throw new MediaPlanError(
+            `Channel wire ${wireKey(selected)} is not in [${allowed}]`
+        );
+    }
+    return copyWire(match);
+}
+
+export function resolveChannelWire(channelName, config = {}) {
+    const { catalog } = catalogFor(channelName);
+    const selected = config?.media;
+    if (selected?.encoding != null && selected?.rate != null) {
+        return requireWire(catalog, selected);
+    }
+    return copyWire(catalog.defaultWire);
+}
+
+export function selectChannelMedia(channelName, selected) {
+    const { catalog } = catalogFor(channelName);
+    return requireWire(catalog, selected);
+}
+
+function conversionCost(from, to) {
+    if (sameWire(from, to)) return 0;
+    if (Number(from.rate) === Number(to.rate)) return 1;
+    if (from.encoding === to.encoding) return 2;
+    return 3;
+}
+
+function assertConverter(from, to) {
+    const key = converterKey(from, to);
+    if (!CONVERTERS.has(key)) {
+        throw new MediaPlanError(`No converter for ${key}`);
+    }
+    return key;
+}
+
+function planFor(channel, providerName, input, output) {
+    return {
+        channel: copyWire(channel),
+        provider: {
+            name: providerName,
+            input: copyWire(input),
+            output: copyWire(output),
+        },
+        uplink: assertConverter(channel, input),
+        downlink: assertConverter(output, channel),
+    };
+}
+
+export function negotiateCall({ channelName, channelConfig, provider } = {}) {
+    const channel = resolveChannelWire(channelName, channelConfig);
+    const providerName = normalizeProviderName(provider);
+    const card = PROVIDER_CARDS[providerName];
+    if (!card) throw new MediaPlanError(`No audio card for provider "${provider}"`);
+
+    if (!card.symmetric) {
+        return planFor(channel, providerName, card.input, card.output);
+    }
+
+    const ranked = card.wires
+        .map((item) => ({ item, cost: conversionCost(channel, item) }))
+        .sort((a, b) => a.cost - b.cost);
+
+    let lastError = null;
+    for (const { item } of ranked) {
+        try {
+            return planFor(channel, providerName, item, item);
+        } catch (error) {
+            lastError = error;
+        }
+    }
+    throw lastError || new MediaPlanError(`No provider wire for ${wireKey(channel)}`);
+}
+
+export function providerAudioFormat(provider, value) {
+    const name = normalizeProviderName(provider);
+    if (name === "openai") {
+        if (value.encoding === "pcm16") return { type: "audio/pcm", rate: Number(value.rate) };
+        if (value.encoding === "g711_ulaw") return { type: "audio/pcmu" };
+        if (value.encoding === "g711_alaw") return { type: "audio/pcma" };
+    }
+    if (name === "gemini") {
+        return { mimeType: `audio/pcm;rate=${Number(value.rate)}` };
+    }
+    throw new MediaPlanError(`No session audio format for provider "${provider}"`);
+}

package/src/media.test.js

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { MediaPlanError, negotiateCall, selectChannelMedia } from "./media.js";
+
+test("exotel default and openai share pcm16 8 kHz", () => {
+    const plan = negotiateCall({ channelName: "Exotel", provider: "openai" });
+    assert.deepEqual(plan.channel, { encoding: "pcm16", rate: 8000 });
+    assert.deepEqual(plan.provider.input, plan.channel);
+    assert.deepEqual(plan.provider.output, plan.channel);
+    assert.equal(plan.uplink, "identity");
+    assert.equal(plan.downlink, "identity");
+});
+
+test("user can move exotel to 16 kHz and openai follows", () => {
+    const plan = negotiateCall({
+        channelName: "exotel",
+        channelConfig: { media: { encoding: "pcm16", rate: 16000 } },
+        provider: "openai",
+    });
+    assert.equal(plan.channel.rate, 16000);
+    assert.equal(plan.uplink, "identity");
+    assert.equal(plan.downlink, "identity");
+});
+
+test("exotel 8 kHz and gemini bridge 16 kHz in and 24 kHz out", () => {
+    const plan = negotiateCall({ channelName: "exotel", provider: "gemini" });
+    assert.deepEqual(plan.provider.input, { encoding: "pcm16", rate: 16000 });
+    assert.deepEqual(plan.provider.output, { encoding: "pcm16", rate: 24000 });
+    assert.equal(plan.uplink, "pcm16:8000->pcm16:16000");
+    assert.equal(plan.downlink, "pcm16:24000->pcm16:8000");
+});
+
+test("exotel 16 kHz into gemini only downsamples the model output", () => {
+    const plan = negotiateCall({
+        channelName: "exotel",
+        channelConfig: { media: { encoding: "pcm16", rate: 16000 } },
+        provider: "google",
+    });
+    assert.equal(plan.uplink, "identity");
+    assert.equal(plan.downlink, "pcm16:24000->pcm16:16000");
+});
+
+test("exotel 24 kHz into gemini only downsamples the caller audio", () => {
+    const plan = negotiateCall({
+        channelName: "exotel",
+        channelConfig: { media: { encoding: "pcm16", rate: 24000 } },
+        provider: "gemini",
+    });
+    assert.equal(plan.uplink, "pcm16:24000->pcm16:16000");
+    assert.equal(plan.downlink, "identity");
+});
+
+test("whatsapp and twilio default to g711 ulaw and match openai", () => {
+    for (const channelName of ["Whatsapp", "twilio", "tataTele"]) {
+        const plan = negotiateCall({ channelName, provider: "openai" });
+        assert.deepEqual(plan.channel, { encoding: "g711_ulaw", rate: 8000 });
+        assert.equal(plan.uplink, "identity");
+        assert.equal(plan.downlink, "identity");
+    }
+});
+
+test("whatsapp ulaw into gemini uses the registered converters", () => {
+    const plan = negotiateCall({ channelName: "whatsapp", provider: "gemini" });
+    assert.equal(plan.uplink, "g711_ulaw:8000->pcm16:16000");
+    assert.equal(plan.downlink, "pcm16:24000->g711_ulaw:8000");
+});
+
+test("a wire outside the channel menu is rejected", () => {
+    assert.throws(
+        () => selectChannelMedia("exotel", { encoding: "pcm16", rate: 48000 }),
+        MediaPlanError
+    );
+});
+
+test("alaw into gemini fails until a converter exists", () => {
+    assert.throws(
+        () => negotiateCall({
+            channelName: "whatsapp",
+            channelConfig: { media: { encoding: "g711_alaw", rate: 8000 } },
+            provider: "gemini",
+        }),
+        /No converter/
+    );
+});

package/src/models/Campaign.js

@@ -49,6 +49,8 @@ const CampaignSchema = new Schema({
         completedAt: Date,// end of chain
         cancelledAt: Date, // breaking the chain 
         lastTaskStartedAt: Date, // last task started time
+        partialAt: Date, // partial completion time
+        failedAt: Date, // failed time
     },
     cancel_requested: { type: Boolean, default: false }, // if true, the next task will be cancelled
     createdBy: { type: Schema.Types.ObjectId, ref: 'Users', required: true },