convex-vapi 0.0.1

package/src/component/_generated/server.ts

@@ -0,0 +1,169 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * `convex.config.ts`.
+ */
+type Env = {
+  readonly CONVEX_CLOUD_URL: string;
+  readonly CONVEX_SITE_URL: string;
+};
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+export const env: Env = (globalThis as unknown as { process: { env: Env } })
+  .process.env;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,5 @@
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("convexVapi");
+
+export default component;

package/src/component/lib.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "vitest";
+import { initConvexTest } from "./setup.test.js";
+import { api } from "./_generated/api.js";
+
+describe("calls", () => {
+  test("recordCall inserts then merges a sparser status-update without blanking fields", async () => {
+    const t = initConvexTest();
+
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_1",
+      assistantId: "assistant_1",
+      status: "ended",
+      transcript: "Hello, how can I help you today?",
+      summary: "Customer asked about pricing.",
+    });
+
+    let call = await t.query(api.lib.getCall, { callId: "call_1" });
+    expect(call?.transcript).toBe("Hello, how can I help you today?");
+
+    // A later, sparser event (e.g. a duplicate status-update) must not erase
+    // the transcript/summary already recorded by the end-of-call-report.
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_1",
+      status: "ended",
+    });
+
+    call = await t.query(api.lib.getCall, { callId: "call_1" });
+    expect(call?.status).toBe("ended");
+    expect(call?.transcript).toBe("Hello, how can I help you today?");
+    expect(call?.summary).toBe("Customer asked about pricing.");
+  });
+
+  test("recordCall never lets a late, out-of-order status-update regress a call away from ended", async () => {
+    const t = initConvexTest();
+
+    // The end-of-call-report arrives first and marks the call ended.
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_2",
+      assistantId: "assistant_1",
+      status: "ended",
+      endedReason: "customer-ended-call",
+    });
+
+    // Vapi gives no delivery ordering guarantee, so a status-update from
+    // earlier in the call can still arrive after the end-of-call-report.
+    // It must not regress the call's status back to an in-progress state.
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_2",
+      assistantId: "assistant_1",
+      status: "in-progress",
+    });
+
+    const call = await t.query(api.lib.getCall, { callId: "call_2" });
+    expect(call?.status).toBe("ended");
+    expect(call?.endedReason).toBe("customer-ended-call");
+  });
+
+  test("listCallsByAssistant scopes by assistantId", async () => {
+    const t = initConvexTest();
+
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_a",
+      assistantId: "assistant_a",
+      status: "queued",
+    });
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_b",
+      assistantId: "assistant_b",
+      status: "queued",
+    });
+
+    const results = await t.query(api.lib.listCallsByAssistant, {
+      assistantId: "assistant_a",
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0].callId).toBe("call_a");
+  });
+});
+
+describe("dashboard queries", () => {
+  test("getStats counts calls by status and webhook events", async () => {
+    const t = initConvexTest();
+
+    await t.mutation(api.lib.recordCall, { callId: "call_a", status: "ended" });
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_b",
+      status: "ringing",
+    });
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_c",
+      status: "in-progress",
+    });
+    await t.mutation(api.lib.checkAndRecordEvent, {
+      eventId: "hash_a",
+      eventType: "status-update",
+      payload: "{}",
+    });
+
+    const stats = await t.query(api.lib.getStats, {});
+    expect(stats).toEqual({
+      callCount: 3,
+      endedCount: 1,
+      liveCount: 2,
+      webhookEventCount: 1,
+    });
+  });
+
+  test("listRecentCalls returns calls most-recently-updated first", async () => {
+    const t = initConvexTest();
+
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_old",
+      status: "ended",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    await t.mutation(api.lib.recordCall, {
+      callId: "call_new",
+      status: "ended",
+    });
+
+    const recent = await t.query(api.lib.listRecentCalls, { limit: 10 });
+    expect(recent.map((c) => c.callId)).toEqual(["call_new", "call_old"]);
+  });
+
+  test("listRecentWebhookEvents returns events most-recent first", async () => {
+    const t = initConvexTest();
+
+    await t.mutation(api.lib.checkAndRecordEvent, {
+      eventId: "hash_old",
+      eventType: "status-update",
+      payload: "{}",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    await t.mutation(api.lib.checkAndRecordEvent, {
+      eventId: "hash_new",
+      eventType: "end-of-call-report",
+      payload: "{}",
+    });
+
+    const recent = await t.query(api.lib.listRecentWebhookEvents, {
+      limit: 10,
+    });
+    expect(recent.map((e) => e.eventId)).toEqual(["hash_new", "hash_old"]);
+  });
+});
+
+describe("webhook idempotency", () => {
+  test("checkAndRecordEvent flags duplicate payload hashes", async () => {
+    const t = initConvexTest();
+
+    const first = await t.mutation(api.lib.checkAndRecordEvent, {
+      eventId: "hash_1",
+      eventType: "status-update",
+      callId: "call_1",
+      payload: "{}",
+    });
+    expect(first.alreadyProcessed).toBe(false);
+
+    const second = await t.mutation(api.lib.checkAndRecordEvent, {
+      eventId: "hash_1",
+      eventType: "status-update",
+      callId: "call_1",
+      payload: "{}",
+    });
+    expect(second.alreadyProcessed).toBe(true);
+  });
+});

package/src/component/lib.ts

@@ -0,0 +1,193 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+
+const callValidator = v.object({
+  _id: v.id("calls"),
+  _creationTime: v.number(),
+  callId: v.string(),
+  assistantId: v.optional(v.string()),
+  phoneNumberId: v.optional(v.string()),
+  customerNumber: v.optional(v.string()),
+  status: v.string(),
+  endedReason: v.optional(v.string()),
+  transcript: v.optional(v.string()),
+  summary: v.optional(v.string()),
+  recordingUrl: v.optional(v.string()),
+  cost: v.optional(v.number()),
+  startedAt: v.optional(v.number()),
+  endedAt: v.optional(v.number()),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+// ─── Queries ────────────────────────────────────────────────────────────────
+
+export const getCall = query({
+  args: { callId: v.string() },
+  returns: v.union(v.null(), callValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("calls")
+      .withIndex("by_callId", (q) => q.eq("callId", args.callId))
+      .first();
+  },
+});
+
+export const listCallsByAssistant = query({
+  args: { assistantId: v.string(), limit: v.optional(v.number()) },
+  returns: v.array(callValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("calls")
+      .withIndex("by_assistantId", (q) => q.eq("assistantId", args.assistantId))
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+// ─── Mutations ──────────────────────────────────────────────────────────────
+
+export const recordCall = mutation({
+  args: {
+    callId: v.string(),
+    assistantId: v.optional(v.string()),
+    phoneNumberId: v.optional(v.string()),
+    customerNumber: v.optional(v.string()),
+    status: v.string(),
+    endedReason: v.optional(v.string()),
+    transcript: v.optional(v.string()),
+    summary: v.optional(v.string()),
+    recordingUrl: v.optional(v.string()),
+    cost: v.optional(v.number()),
+    startedAt: v.optional(v.number()),
+    endedAt: v.optional(v.number()),
+  },
+  returns: v.id("calls"),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const existing = await ctx.db
+      .query("calls")
+      .withIndex("by_callId", (q) => q.eq("callId", args.callId))
+      .first();
+
+    if (existing) {
+      // Merge rather than blanket-overwrite: a later, sparser event (e.g. a
+      // status-update with no transcript yet) must never erase fields an
+      // earlier, richer event (e.g. end-of-call-report) already recorded.
+      //
+      // status is a special case: Vapi's webhook deliveries carry no
+      // timestamp or sequence number, and delivery order is never
+      // guaranteed by any webhook provider, so a status-update that
+      // arrives late could otherwise regress a call backward (e.g. from
+      // "ended" back to "ringing"). "ended" is the one status Vapi never
+      // revises once sent, so once we've recorded it, later events are
+      // treated as stragglers and can't downgrade it back.
+      const status =
+        existing.status === "ended" ? existing.status : args.status;
+      const merged = {
+        callId: args.callId,
+        assistantId: args.assistantId ?? existing.assistantId,
+        phoneNumberId: args.phoneNumberId ?? existing.phoneNumberId,
+        customerNumber: args.customerNumber ?? existing.customerNumber,
+        status,
+        endedReason: args.endedReason ?? existing.endedReason,
+        transcript: args.transcript ?? existing.transcript,
+        summary: args.summary ?? existing.summary,
+        recordingUrl: args.recordingUrl ?? existing.recordingUrl,
+        cost: args.cost ?? existing.cost,
+        startedAt: args.startedAt ?? existing.startedAt,
+        endedAt: args.endedAt ?? existing.endedAt,
+      };
+      await ctx.db.patch(existing._id, { ...merged, updatedAt: now });
+      return existing._id;
+    }
+
+    return await ctx.db.insert("calls", {
+      ...args,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const checkAndRecordEvent = mutation({
+  args: {
+    eventId: v.string(),
+    eventType: v.string(),
+    callId: v.optional(v.string()),
+    payload: v.string(),
+  },
+  returns: v.object({ alreadyProcessed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("webhookEvents")
+      .withIndex("by_eventId", (q) => q.eq("eventId", args.eventId))
+      .first();
+    if (existing) {
+      return { alreadyProcessed: true };
+    }
+    await ctx.db.insert("webhookEvents", { ...args, receivedAt: Date.now() });
+    return { alreadyProcessed: false };
+  },
+});
+
+// ─── Dashboard queries ──────────────────────────────────────────────────────
+// These do full, un-indexed scans across every call/event the component has
+// ever recorded, on purpose — they power a demo's stats bar and activity
+// history, not high-volume production use.
+
+export const getStats = query({
+  args: {},
+  returns: v.object({
+    callCount: v.number(),
+    endedCount: v.number(),
+    liveCount: v.number(),
+    webhookEventCount: v.number(),
+  }),
+  handler: async (ctx) => {
+    const [calls, webhookEvents] = await Promise.all([
+      ctx.db.query("calls").collect(),
+      ctx.db.query("webhookEvents").collect(),
+    ]);
+    const live = (status: string) =>
+      status === "queued" || status === "ringing" || status === "in-progress";
+    return {
+      callCount: calls.length,
+      endedCount: calls.filter((c) => c.status === "ended").length,
+      liveCount: calls.filter((c) => live(c.status)).length,
+      webhookEventCount: webhookEvents.length,
+    };
+  },
+});
+
+export const listRecentCalls = query({
+  args: { limit: v.optional(v.number()) },
+  returns: v.array(callValidator),
+  handler: async (ctx, args) => {
+    const calls = await ctx.db.query("calls").collect();
+    return calls
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .slice(0, args.limit ?? 20);
+  },
+});
+
+export const listRecentWebhookEvents = query({
+  args: { limit: v.optional(v.number()) },
+  returns: v.array(
+    v.object({
+      _id: v.id("webhookEvents"),
+      _creationTime: v.number(),
+      eventId: v.string(),
+      eventType: v.string(),
+      callId: v.optional(v.string()),
+      payload: v.string(),
+      receivedAt: v.number(),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    const events = await ctx.db.query("webhookEvents").collect();
+    return events
+      .sort((a, b) => b.receivedAt - a.receivedAt)
+      .slice(0, args.limit ?? 20);
+  },
+});

package/src/component/schema.ts

@@ -0,0 +1,31 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  calls: defineTable({
+    callId: v.string(), // Vapi's call id
+    assistantId: v.optional(v.string()),
+    phoneNumberId: v.optional(v.string()),
+    customerNumber: v.optional(v.string()),
+    status: v.string(), // "queued" | "ringing" | "in-progress" | "forwarding" | "ended" | ...
+    endedReason: v.optional(v.string()),
+    transcript: v.optional(v.string()),
+    summary: v.optional(v.string()),
+    recordingUrl: v.optional(v.string()),
+    cost: v.optional(v.number()),
+    startedAt: v.optional(v.number()),
+    endedAt: v.optional(v.number()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_callId", ["callId"])
+    .index("by_assistantId", ["assistantId"]),
+
+  webhookEvents: defineTable({
+    eventId: v.string(), // sha256 hex of the raw body — Vapi sends no per-delivery id
+    eventType: v.string(), // message.type
+    callId: v.optional(v.string()),
+    payload: v.string(),
+    receivedAt: v.number(),
+  }).index("by_eventId", ["eventId"]),
+});

package/src/component/setup.test.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import schema from "./schema.js";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  return t;
+}
+test("setup", () => {});

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "convexVapi",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };