convex-vapi 0.0.1

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "convex-vapi",
+  "description": "Sync Vapi voice AI calls into Convex reactively, and place outbound calls from Convex functions.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sholajegede/convex-vapi.git"
+  },
+  "homepage": "https://github.com/sholajegede/convex-vapi#readme",
+  "bugs": {
+    "url": "https://github.com/sholajegede/convex-vapi/issues"
+  },
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "keywords": [
+    "convex",
+    "component",
+    "vapi",
+    "voice-ai",
+    "calls",
+    "webhooks",
+    "telephony"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "run-p -r 'dev:*'",
+    "dev:backend": "convex dev --typecheck-components",
+    "dev:frontend": "cd example && vite --clearScreen false",
+    "dev:build": "chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'npm run build:codegen' --initial",
+    "predev": "path-exists .env.local dist || (npm run build && convex dev --once)",
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "npx convex codegen --component-dir ./src/component && npm run build",
+    "build:clean": "rm -rf dist *.tsbuildinfo && npm run build:codegen",
+    "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
+    "lint": "eslint .",
+    "all": "run-p -r 'dev:*' 'test:watch'",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "preversion": "npm install --legacy-peer-deps && npm run build:clean && run-p test lint typecheck",
+    "prepublishOnly": "npm whoami || npm login",
+    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push --follow-tags",
+    "version": "vim -c 'normal o' -c 'normal o## '$npm_package_version CHANGELOG.md && prettier -w CHANGELOG.md && git add CHANGELOG.md"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "peerDependencies": {
+    "convex": "^1.34.1"
+  },
+  "devDependencies": {
+    "@convex-dev/eslint-plugin": "^1.2.0",
+    "@edge-runtime/vm": "^5.0.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "9.39.4",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "chokidar-cli": "3.0.0",
+    "convex": "1.45.0",
+    "convex-test": "0.0.41",
+    "eslint": "9.39.4",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
+    "npm-run-all2": "8.0.4",
+    "path-exists-cli": "2.0.0",
+    "pkg-pr-new": "^0.0.66",
+    "prettier": "3.8.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.57.1",
+    "vite": "7.3.1",
+    "vitest": "4.1.0"
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js"
+}

package/src/client/_generated/_ignore.ts

@@ -0,0 +1 @@
+// This is only here so convex-test can detect a _generated folder

package/src/client/index.ts

@@ -0,0 +1,250 @@
+import { httpActionGeneric } from "convex/server";
+import type { GenericActionCtx, GenericDataModel } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+const VAPI_API_BASE = "https://api.vapi.ai";
+
+export type VapiOptions = {
+  /** A private API key from the Vapi dashboard. */
+  apiKey: string;
+  /**
+   * The shared secret configured in the assistant's `server.secret` field.
+   * Sent back by Vapi on every webhook request in the `X-Vapi-Secret` header.
+   */
+  webhookSecret: string;
+};
+
+export type CreateCallArgs = {
+  assistantId: string;
+  phoneNumberId: string;
+  customerNumber: string;
+};
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+
+async function sha256Hex(payload: string): Promise<string> {
+  const enc = new TextEncoder();
+  const digest = await crypto.subtle.digest("SHA-256", enc.encode(payload));
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function callRecordFromApiObject(call: Record<string, unknown>) {
+  const customer = call.customer as Record<string, unknown> | undefined;
+  return {
+    callId: String(call.id),
+    assistantId: (call.assistantId as string) ?? undefined,
+    phoneNumberId: (call.phoneNumberId as string) ?? undefined,
+    customerNumber: (customer?.number as string) ?? undefined,
+    status: (call.status as string) ?? "unknown",
+    endedReason: (call.endedReason as string) ?? undefined,
+    startedAt: call.startedAt
+      ? new Date(call.startedAt as string).getTime()
+      : undefined,
+    endedAt: call.endedAt
+      ? new Date(call.endedAt as string).getTime()
+      : undefined,
+    cost: (call.cost as number) ?? undefined,
+  };
+}
+
+export class Vapi {
+  webhookHandler: ReturnType<typeof httpActionGeneric>;
+
+  constructor(
+    private component: ComponentApi,
+    private options: VapiOptions,
+  ) {
+    const component_ = component;
+    const webhookSecret = options.webhookSecret;
+
+    this.webhookHandler = httpActionGeneric(async (ctx, request) => {
+      const rawBody = await request.text();
+      const secretHeader = request.headers.get("x-vapi-secret");
+
+      if (!secretHeader) {
+        return new Response(
+          JSON.stringify({ error: "Missing X-Vapi-Secret header" }),
+          {
+            status: 400,
+            headers: { "Content-Type": "application/json" },
+          },
+        );
+      }
+
+      if (!timingSafeEqual(secretHeader, webhookSecret)) {
+        console.error("convex-vapi: webhook secret mismatch");
+        return new Response(JSON.stringify({ error: "Invalid secret" }), {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+
+      // Vapi does not send a per-delivery id header, so duplicates are
+      // detected by hashing the raw payload itself.
+      const eventId = await sha256Hex(rawBody);
+
+      const payload = JSON.parse(rawBody) as {
+        message?: Record<string, unknown>;
+      };
+      const message = payload.message ?? {};
+      const eventType = (message.type as string) ?? "unknown";
+      const call = message.call as Record<string, unknown> | undefined;
+      const callId = call?.id ? String(call.id) : undefined;
+
+      const { alreadyProcessed } = await ctx.runMutation(
+        component_.lib.checkAndRecordEvent,
+        {
+          eventId,
+          eventType,
+          callId,
+          payload: rawBody,
+        },
+      );
+
+      if (alreadyProcessed) {
+        return new Response(
+          JSON.stringify({ success: true, duplicate: true }),
+          {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          },
+        );
+      }
+
+      if (eventType === "status-update" && call) {
+        await ctx.runMutation(component_.lib.recordCall, {
+          ...callRecordFromApiObject(call),
+          status:
+            (message.status as string) ?? (call.status as string) ?? "unknown",
+        });
+      } else if (eventType === "end-of-call-report" && call) {
+        const artifact = message.artifact as
+          | Record<string, unknown>
+          | undefined;
+        await ctx.runMutation(component_.lib.recordCall, {
+          ...callRecordFromApiObject(call),
+          status: "ended",
+          endedReason: (message.endedReason as string) ?? undefined,
+          transcript: (artifact?.transcript as string) ?? undefined,
+          summary: (artifact?.summary as string) ?? undefined,
+          recordingUrl:
+            (artifact?.recordingUrl as string) ??
+            ((artifact?.recording as Record<string, unknown> | undefined)
+              ?.stereoUrl as string) ??
+            undefined,
+        });
+      }
+      // Other event types (transcript, conversation-update, speech-update,
+      // tool-calls, etc.) are accepted and recorded in webhookEvents for
+      // idempotency/auditing, but do not update the calls table — see the
+      // README's Limitations section.
+
+      return new Response(JSON.stringify({ success: true }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.options.apiKey}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  async createCall(
+    ctx: GenericActionCtx<GenericDataModel>,
+    args: CreateCallArgs,
+  ): Promise<{ callId: string; status: string }> {
+    const res = await fetch(`${VAPI_API_BASE}/call`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({
+        assistantId: args.assistantId,
+        phoneNumberId: args.phoneNumberId,
+        customer: { number: args.customerNumber },
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `Failed to create Vapi call: ${res.status} ${await res.text()}`,
+      );
+    }
+    const json = (await res.json()) as Record<string, unknown>;
+
+    await ctx.runMutation(
+      this.component.lib.recordCall,
+      callRecordFromApiObject(json),
+    );
+
+    return {
+      callId: String(json.id),
+      status: (json.status as string) ?? "queued",
+    };
+  }
+
+  /** Fetches the latest call state directly from the Vapi API and re-records it. */
+  async refreshCall(
+    ctx: GenericActionCtx<GenericDataModel>,
+    args: { callId: string },
+  ): Promise<void> {
+    const res = await fetch(`${VAPI_API_BASE}/call/${args.callId}`, {
+      method: "GET",
+      headers: this.headers(),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `Failed to fetch Vapi call: ${res.status} ${await res.text()}`,
+      );
+    }
+    const json = (await res.json()) as Record<string, unknown>;
+    const artifact = json.artifact as Record<string, unknown> | undefined;
+
+    await ctx.runMutation(this.component.lib.recordCall, {
+      ...callRecordFromApiObject(json),
+      transcript: (artifact?.transcript as string) ?? undefined,
+      summary: (artifact?.summary as string) ?? undefined,
+      recordingUrl: (artifact?.recordingUrl as string) ?? undefined,
+    });
+  }
+
+  async getCall(ctx: RunQueryCtx, args: { callId: string }) {
+    return await ctx.runQuery(this.component.lib.getCall, args);
+  }
+
+  async listCallsByAssistant(
+    ctx: RunQueryCtx,
+    args: { assistantId: string; limit?: number },
+  ) {
+    return await ctx.runQuery(this.component.lib.listCallsByAssistant, args);
+  }
+
+  async getStats(ctx: RunQueryCtx) {
+    return await ctx.runQuery(this.component.lib.getStats, {});
+  }
+
+  async listRecentCalls(ctx: RunQueryCtx, args: { limit?: number } = {}) {
+    return await ctx.runQuery(this.component.lib.listRecentCalls, args);
+  }
+
+  async listRecentWebhookEvents(
+    ctx: RunQueryCtx,
+    args: { limit?: number } = {},
+  ) {
+    return await ctx.runQuery(this.component.lib.listRecentWebhookEvents, args);
+  }
+}
+
+type RunQueryCtx = {
+  runQuery: GenericActionCtx<GenericDataModel>["runQuery"];
+};

package/src/client/setup.test.ts

@@ -0,0 +1,26 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+import {
+  defineSchema,
+  type GenericSchema,
+  type SchemaDefinition,
+} from "convex/server";
+import { type ComponentApi } from "../component/_generated/component.js";
+import { componentsGeneric } from "convex/server";
+import { register } from "../test.js";
+
+export function initConvexTest<
+  Schema extends SchemaDefinition<GenericSchema, boolean>,
+>(schema?: Schema) {
+  const t = convexTest(schema ?? defineSchema({}), modules);
+  register(t);
+  return t;
+}
+export const components = componentsGeneric() as unknown as {
+  convexVapi: ComponentApi;
+};
+
+test("setup", () => {});

package/src/component/_generated/api.ts

@@ -0,0 +1,50 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as lib from "../lib.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  lib: typeof lib;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,159 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    lib: {
+      checkAndRecordEvent: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          callId?: string;
+          eventId: string;
+          eventType: string;
+          payload: string;
+        },
+        { alreadyProcessed: boolean },
+        Name
+      >;
+      getCall: FunctionReference<
+        "query",
+        "internal",
+        { callId: string },
+        null | {
+          _creationTime: number;
+          _id: string;
+          assistantId?: string;
+          callId: string;
+          cost?: number;
+          createdAt: number;
+          customerNumber?: string;
+          endedAt?: number;
+          endedReason?: string;
+          phoneNumberId?: string;
+          recordingUrl?: string;
+          startedAt?: number;
+          status: string;
+          summary?: string;
+          transcript?: string;
+          updatedAt: number;
+        },
+        Name
+      >;
+      getStats: FunctionReference<
+        "query",
+        "internal",
+        {},
+        {
+          callCount: number;
+          endedCount: number;
+          liveCount: number;
+          webhookEventCount: number;
+        },
+        Name
+      >;
+      listCallsByAssistant: FunctionReference<
+        "query",
+        "internal",
+        { assistantId: string; limit?: number },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          assistantId?: string;
+          callId: string;
+          cost?: number;
+          createdAt: number;
+          customerNumber?: string;
+          endedAt?: number;
+          endedReason?: string;
+          phoneNumberId?: string;
+          recordingUrl?: string;
+          startedAt?: number;
+          status: string;
+          summary?: string;
+          transcript?: string;
+          updatedAt: number;
+        }>,
+        Name
+      >;
+      listRecentCalls: FunctionReference<
+        "query",
+        "internal",
+        { limit?: number },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          assistantId?: string;
+          callId: string;
+          cost?: number;
+          createdAt: number;
+          customerNumber?: string;
+          endedAt?: number;
+          endedReason?: string;
+          phoneNumberId?: string;
+          recordingUrl?: string;
+          startedAt?: number;
+          status: string;
+          summary?: string;
+          transcript?: string;
+          updatedAt: number;
+        }>,
+        Name
+      >;
+      listRecentWebhookEvents: FunctionReference<
+        "query",
+        "internal",
+        { limit?: number },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          callId?: string;
+          eventId: string;
+          eventType: string;
+          payload: string;
+          receivedAt: number;
+        }>,
+        Name
+      >;
+      recordCall: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          assistantId?: string;
+          callId: string;
+          cost?: number;
+          customerNumber?: string;
+          endedAt?: number;
+          endedReason?: string;
+          phoneNumberId?: string;
+          recordingUrl?: string;
+          startedAt?: number;
+          status: string;
+          summary?: string;
+          transcript?: string;
+        },
+        string,
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;