@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/__tests__/invite-routes-http.test.ts

@@ -24,45 +24,44 @@ mock.module("../telegram/bot-username.js", () => ({
 }));
 
 // Mock startInviteCall from call-domain — test env lacks Twilio credentials.
+// Captures the last input so trigger-call tests can assert the gateway-supplied
+// fields flow through to the provider call.
 let mockStartInviteCallResult:
   | { ok: true; callSid: string }
   | { ok: false; error: string; status?: number } = {
   ok: true,
   callSid: "CA_test_sid_123",
 };
+let lastStartInviteCallInput: Record<string, unknown> | null = null;
 mock.module("../calls/call-domain.js", () => ({
-  startInviteCall: async () => mockStartInviteCallResult,
+  startInviteCall: async (input: Record<string, unknown>) => {
+    lastStartInviteCallInput = input;
+    return mockStartInviteCallResult;
+  },
 }));
 
-// Model the gateway: the redemption claim (record_invite_redemption) and the
-// gateway-owned activation (upsert_verified_channel) are both relayed. The
-// activation write fails closed in production, so the mock must serve a
-// verified upsert for the legitimate-success redemption paths.
-const gatewayIpc = {
-  claim: { ok: true, updated: true, mirrored: true },
-  activationVerified: true,
-};
+// Model the gateway `invites_redeem` IPC: the daemon redeem route is a thin
+// relay (the gateway redemption engine owns validation, the atomic claim,
+// and the ACL write), so the mock captures the relayed params and serves a
+// scripted gateway response or a scripted relay failure.
+import { IpcCallError } from "@vellumai/gateway-client/ipc-client";
+
+const redeemRelay: {
+  calls: Array<Record<string, unknown> | undefined>;
+  result: unknown;
+  error: Error | null;
+} = { calls: [], result: undefined, error: null };
 mock.module("../ipc/gateway-client.js", () => ({
   ipcCallPersistent: async (
     method: string,
     params?: Record<string, unknown>,
   ) => {
-    if (method === "record_invite_redemption") return gatewayIpc.claim;
-    if (method === "upsert_verified_channel") {
-      if (!gatewayIpc.activationVerified) return { ok: true, verified: false };
-      return {
-        ok: true,
-        verified: true,
-        channel: {
-          id: "gw-channel-id",
-          contactId: (params?.contactId as string) ?? "gw-contact",
-          type: (params?.type as string) ?? "telegram",
-          address: (params?.address as string) ?? "gw-addr",
-          status: "active",
-          verifiedAt: 1,
-          verifiedVia: (params?.verifiedVia as string) ?? "invite",
-        },
-      };
+    if (method === "invites_redeem") {
+      redeemRelay.calls.push(params);
+      if (redeemRelay.error) {
+        throw redeemRelay.error;
+      }
+      return redeemRelay.result;
     }
     return undefined;
   },
@@ -71,54 +70,48 @@ mock.module("../ipc/gateway-client.js", () => ({
 import { upsertContact } from "../contacts/contact-store.js";
 import { getSqlite } from "../persistence/db-connection.js";
 import { initializeDb } from "../persistence/db-init.js";
-import { revokeInvite } from "../persistence/invite-store.js";
 import {
-  createIngressInvite,
+  composeInvitePresentation,
   triggerInviteCall,
 } from "../runtime/invite-service.js";
 import { handleRedeemInvite as _handleRedeemInvite } from "../runtime/routes/contact-routes.js";
 import { RouteError } from "../runtime/routes/errors.js";
 
 /**
- * The CLI/HTTP create/list/revoke/trigger route handlers relay to the gateway
- * (see invite-relay-routes.test.ts). The assistant-native invite logic the
- * gateway invokes via `invites_mint` + its native handlers is exercised here
- * against the assistant DB through the `invite-service` functions. Redemption
- * stays daemon-local and is driven through the route handler.
+ * Invite create/list/revoke/redeem are gateway-native (the daemon route
+ * handlers relay; the gateway engine is exercised in
+ * gateway/src/__tests__/invite-redemption-engine*.test.ts and the gateway
+ * handlers in contacts-control-plane-proxy.test.ts +
+ * ipc-invite-routes.test.ts). What stays daemon-local — the redeem relay
+ * dispatch, the outbound call trigger, and the presentation composition
+ * layered onto the gateway's create payload — is exercised here.
  */
 function fakeResponse(body: unknown, status = 200) {
   return { status, json: async () => body };
 }
 
-async function handleCreateInvite(req: Request) {
-  const body = (await req.json()) as Record<string, string | number>;
-  const result = await createIngressInvite({
-    sourceChannel: body.sourceChannel as string | undefined,
-    note: body.note as string | undefined,
-    maxUses: body.maxUses as number | undefined,
-    expiresInMs: body.expiresInMs as number | undefined,
-    expectedExternalUserId: body.expectedExternalUserId as string | undefined,
-    contactId: body.contactId as string,
-  });
-  if (!result.ok) return fakeResponse({ ok: false, error: result.error }, 400);
-  return fakeResponse({ ok: true, invite: result.data }, 201);
-}
-
 async function handleRedeemInvite(req: Request) {
   const body = (await req.json()) as Record<string, unknown>;
   try {
     const result = await _handleRedeemInvite({ body });
     return fakeResponse(result);
   } catch (err) {
-    if (err instanceof RouteError)
+    if (err instanceof RouteError) {
       return fakeResponse({ ok: false, error: err.message }, err.statusCode);
+    }
     throw err;
   }
 }
 
-async function handleTriggerInviteCall(inviteId: string) {
-  const result = await triggerInviteCall(inviteId);
-  if (!result.ok) return fakeResponse({ ok: false, error: result.error }, 400);
+async function handleTriggerInviteCall(params: {
+  phoneNumber?: string;
+  friendName?: string | null;
+  guardianName?: string | null;
+}) {
+  const result = await triggerInviteCall(params);
+  if (!result.ok) {
+    return fakeResponse({ ok: false, error: result.error }, 400);
+  }
   return fakeResponse({ ok: true, callSid: result.data.callSid });
 }
 
@@ -130,129 +123,145 @@ function createTargetContact(displayName = "Test Contact"): string {
 }
 
 function resetTables() {
-  getSqlite().run("DELETE FROM assistant_ingress_invites");
   getSqlite().run("DELETE FROM contact_channels");
   getSqlite().run("DELETE FROM contacts");
 }
 
+function resetRedeemRelay() {
+  redeemRelay.calls.length = 0;
+  redeemRelay.result = undefined;
+  redeemRelay.error = null;
+}
+
 // ---------------------------------------------------------------------------
-// Invite routes
+// Redeem relay (gateway-native redemption behind the daemon route)
 // ---------------------------------------------------------------------------
 
-describe("ingress invite HTTP routes", () => {
-  beforeEach(resetTables);
+describe("invite redeem relay routes", () => {
+  beforeEach(() => {
+    resetTables();
+    resetRedeemRelay();
+  });
 
-  test("POST /v1/contacts/invites — creates an invite", async () => {
-    const req = new Request("http://localhost/v1/contacts/invites", {
+  test("POST /v1/contacts/invites/redeem — token body relays to the gateway and returns its payload", async () => {
+    redeemRelay.result = {
+      ok: true,
+      invite: { id: "inv-gw-1", status: "redeemed", useCount: 1 },
+      type: "redeemed",
+    };
+
+    const req = new Request("http://localhost/v1/contacts/invites/redeem", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
+        token: "raw-token-1",
+        externalUserId: "redeemer-1",
+        externalChatId: "chat-9",
         sourceChannel: "telegram",
-        contactId: createTargetContact(),
-        note: "Test invite",
-        maxUses: 5,
+        displayName: "Alice Example",
+        username: "alice",
+        notAContractField: "dropped",
       }),
     });
 
-    const res = await handleCreateInvite(req);
+    const res = await handleRedeemInvite(req);
     const body = (await res.json()) as Record<string, unknown>;
 
-    expect(res.status).toBe(201);
+    expect(res.status).toBe(200);
     expect(body.ok).toBe(true);
-    const invite = body.invite as Record<string, unknown>;
-    expect(invite.sourceChannel).toBe("telegram");
-    expect(invite.note).toBe("Test invite");
-    expect(invite.maxUses).toBe(5);
-    expect(invite.status).toBe("active");
-    // Raw token should be returned on create
-    expect(typeof invite.token).toBe("string");
-    expect((invite.token as string).length).toBeGreaterThan(0);
+    expect((body.invite as Record<string, unknown>).id).toBe("inv-gw-1");
+    expect(body.type).toBe("redeemed");
+    // The relay forwards every shared-contract field — including the sender
+    // identity fields (displayName/username) the gateway engine stamps onto
+    // the new member — and nothing voice-shaped or off-contract.
+    expect(redeemRelay.calls).toEqual([
+      {
+        token: "raw-token-1",
+        sourceChannel: "telegram",
+        externalUserId: "redeemer-1",
+        externalChatId: "chat-9",
+        displayName: "Alice Example",
+        username: "alice",
+      },
+    ]);
   });
 
-  test("POST /v1/contacts/invites — includes canonical share URL when bot username is configured", async () => {
-    mockTelegramBotUsername = "test_invite_bot";
+  test("POST /v1/contacts/invites/redeem — voice body relays code + caller and returns the voice shape", async () => {
+    redeemRelay.result = {
+      ok: true,
+      type: "redeemed",
+      memberId: "ct-target",
+      inviteId: "inv-gw-2",
+    };
+    const code = "123456";
 
-    try {
-      const req = new Request("http://localhost/v1/contacts/invites", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          sourceChannel: "telegram",
-          contactId: createTargetContact(),
-          note: "Share link test",
-        }),
-      });
+    const req = new Request("http://localhost/v1/contacts/invites/redeem", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        callerExternalUserId: "+15551234567",
+        code,
+        assistantId: "asst-1",
+      }),
+    });
 
-      const res = await handleCreateInvite(req);
-      const body = (await res.json()) as Record<string, unknown>;
-      const invite = body.invite as Record<string, unknown>;
-      const token = invite.token as string;
-      const share = invite.share as Record<string, unknown>;
+    const res = await handleRedeemInvite(req);
+    const body = (await res.json()) as Record<string, unknown>;
 
-      expect(res.status).toBe(201);
-      expect(body.ok).toBe(true);
-      expect(typeof token).toBe("string");
-      expect(token.length).toBeGreaterThan(0);
-      expect(share).toBeDefined();
-      expect(share.url).toBe(`https://t.me/test_invite_bot?start=iv_${token}`);
-      expect(typeof share.displayText).toBe("string");
-    } finally {
-      mockTelegramBotUsername = undefined;
-    }
+    expect(res.status).toBe(200);
+    expect(body).toEqual({
+      ok: true,
+      type: "redeemed",
+      memberId: "ct-target",
+      inviteId: "inv-gw-2",
+    });
+    expect(redeemRelay.calls).toEqual([
+      { code, callerExternalUserId: "+15551234567", assistantId: "asst-1" },
+    ]);
   });
 
-  test("POST /v1/contacts/invites — missing sourceChannel returns 400", async () => {
-    const req = new Request("http://localhost/v1/contacts/invites", {
+  test("POST /v1/contacts/invites/redeem — gateway 400 (engine reason) surfaces as 400", async () => {
+    redeemRelay.error = new IpcCallError("invalid_or_expired", {
+      statusCode: 400,
+      errorCode: "BAD_REQUEST",
+    });
+
+    const req = new Request("http://localhost/v1/contacts/invites/redeem", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ note: "No channel" }),
+      body: JSON.stringify({
+        callerExternalUserId: "+15551234567",
+        code: "000000",
+      }),
     });
 
-    const res = await handleCreateInvite(req);
+    const res = await handleRedeemInvite(req);
     const body = (await res.json()) as { ok: boolean; error: string };
 
     expect(res.status).toBe(400);
     expect(body.ok).toBe(false);
-    expect(body.error).toContain("sourceChannel");
+    expect(body.error).toBe("invalid_or_expired");
   });
 
-  test("POST /v1/contacts/invites/redeem — redeems an invite", async () => {
-    // Create an invite first
-    const createRes = await handleCreateInvite(
-      new Request("http://localhost/v1/contacts/invites", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          sourceChannel: "telegram",
-          contactId: createTargetContact(),
-          maxUses: 1,
-        }),
-      }),
-    );
-    const created = (await createRes.json()) as { invite: { token: string } };
+  test("POST /v1/contacts/invites/redeem — gateway unreachable fails CLOSED (500)", async () => {
+    // The gateway is the single redemption authority; a relay failure must
+    // surface as an error, never a locally-decided redemption.
+    redeemRelay.error = new IpcCallError("gateway unreachable");
 
     const req = new Request("http://localhost/v1/contacts/invites/redeem", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        token: created.invite.token,
-        externalUserId: "redeemer-1",
-        sourceChannel: "telegram",
+        callerExternalUserId: "+15551234567",
+        code: "123456",
       }),
     });
 
     const res = await handleRedeemInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
-
-    expect(res.status).toBe(200);
-    expect(body.ok).toBe(true);
-    const invite = body.invite as Record<string, unknown>;
-    expect(invite.useCount).toBe(1);
-    // Single-use invite should be fully redeemed
-    expect(invite.status).toBe("redeemed");
+    expect(res.status).toBe(500);
   });
 
-  test("POST /v1/contacts/invites/redeem — missing token returns 400", async () => {
+  test("POST /v1/contacts/invites/redeem — missing token returns 400 without relaying", async () => {
     const req = new Request("http://localhost/v1/contacts/invites/redeem", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -262,284 +271,107 @@ describe("ingress invite HTTP routes", () => {
     const res = await handleRedeemInvite(req);
     const body = (await res.json()) as { ok: boolean; error: string };
 
+    // No `code` and no `token` → token path; the shared contract schema
+    // rejects daemon-side before any gateway round-trip.
     expect(res.status).toBe(400);
     expect(body.ok).toBe(false);
     expect(body.error).toContain("token");
+    expect(redeemRelay.calls.length).toBe(0);
   });
 
-  test("POST /v1/contacts/invites/redeem — invalid token returns 400", async () => {
+  test("POST /v1/contacts/invites/redeem — voice code without caller identity is rejected daemon-side", async () => {
     const req = new Request("http://localhost/v1/contacts/invites/redeem", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ token: "invalid-token" }),
+      body: JSON.stringify({ code: "123456" }),
     });
 
     const res = await handleRedeemInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
+    const body = (await res.json()) as { ok: boolean; error: string };
 
     expect(res.status).toBe(400);
     expect(body.ok).toBe(false);
+    expect(body.error).toContain("callerExternalUserId");
+    // Rejected before any gateway round-trip.
+    expect(redeemRelay.calls.length).toBe(0);
   });
 });
 
 // ---------------------------------------------------------------------------
-// Shared logic round-trip
-// ---------------------------------------------------------------------------
-
-describe("ingress service shared logic", () => {
-  beforeEach(resetTables);
-
-  test("invite create + revoke round-trip through shared service", async () => {
-    const createRes = await handleCreateInvite(
-      new Request("http://localhost/v1/contacts/invites", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          sourceChannel: "telegram",
-          contactId: createTargetContact(),
-        }),
-      }),
-    );
-    const created = (await createRes.json()) as {
-      invite: { id: string; status: string };
-    };
-    expect(created.invite.status).toBe("active");
-
-    const revoked = revokeInvite(created.invite.id);
-    expect(revoked?.status).toBe("revoked");
-    expect(revoked?.id).toBe(created.invite.id);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Voice invite routes
+// Presentation composition (daemon-owned layer over the gateway mint payload)
 // ---------------------------------------------------------------------------
 
-describe("voice invite HTTP routes", () => {
+describe("composeInvitePresentation", () => {
   beforeEach(resetTables);
 
-  test("POST /v1/contacts/invites with sourceChannel voice — creates invite with voiceCode, stores hash only", async () => {
-    const req = new Request("http://localhost/v1/contacts/invites", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        sourceChannel: "phone",
-        contactId: createTargetContact("Alice"),
-        expectedExternalUserId: "+15551234567",
-        maxUses: 3,
-      }),
-    });
-
-    const res = await handleCreateInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
-
-    expect(res.status).toBe(201);
-    expect(body.ok).toBe(true);
-    const invite = body.invite as Record<string, unknown>;
-    expect(invite.sourceChannel).toBe("phone");
-    // Voice code should be returned (6 digits by default)
-    expect(typeof invite.voiceCode).toBe("string");
-    expect((invite.voiceCode as string).length).toBe(6);
-    expect(/^\d{6}$/.test(invite.voiceCode as string)).toBe(true);
-    // Hash should be stored
-    expect(typeof invite.tokenHash).toBe("string");
-    expect((invite.tokenHash as string).length).toBeGreaterThan(0);
-    // voiceCodeDigits should be recorded
-    expect(invite.voiceCodeDigits).toBe(6);
-    // expectedExternalUserId should be recorded
-    expect(invite.expectedExternalUserId).toBe("+15551234567");
-    // friendName is mirrored from the bound contact's displayName, not a flag
-    expect(invite.friendName).toBe("Alice");
-  });
-
-  test("voice invite creation requires expectedExternalUserId", async () => {
-    const req = new Request("http://localhost/v1/contacts/invites", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        sourceChannel: "phone",
-        contactId: createTargetContact(),
-      }),
-    });
-
-    const res = await handleCreateInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
-
-    expect(res.status).toBe(400);
-    expect(body.ok).toBe(false);
-    expect(body.error).toContain("expectedExternalUserId");
-  });
-
-  test("voice invite creation validates E.164 format", async () => {
-    const req = new Request("http://localhost/v1/contacts/invites", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        sourceChannel: "phone",
-        contactId: createTargetContact(),
-        expectedExternalUserId: "not-a-phone-number",
-      }),
-    });
-
-    const res = await handleCreateInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
-
-    expect(res.status).toBe(400);
-    expect(body.ok).toBe(false);
-    expect(body.error).toContain("E.164");
-  });
-
-  test("voiceCodeDigits is always 6 — custom values are ignored", async () => {
-    const req = new Request("http://localhost/v1/contacts/invites", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        sourceChannel: "phone",
-        contactId: createTargetContact(),
-        expectedExternalUserId: "+15551234567",
-        voiceCodeDigits: 8,
-      }),
-    });
-
-    const res = await handleCreateInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
+  test("voice invites get a guardianInstruction with the contact's first name", async () => {
+    const contactId = createTargetContact("Carolina Example");
 
-    expect(res.status).toBe(201);
-    expect(body.ok).toBe(true);
-    const invite = body.invite as Record<string, unknown>;
-    expect((invite.voiceCode as string).length).toBe(6);
-    expect(invite.voiceCodeDigits).toBe(6);
-  });
-
-  test("voice invites do NOT return token in response", async () => {
-    const req = new Request("http://localhost/v1/contacts/invites", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
+    const invite = await composeInvitePresentation({
+      contactId,
+      invite: {
+        id: "inv-voice-1",
         sourceChannel: "phone",
-        contactId: createTargetContact(),
-        expectedExternalUserId: "+15551234567",
-      }),
+        voiceCode: "123456",
+        voiceCodeDigits: 6,
+      },
     });
 
-    const res = await handleCreateInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
-
-    expect(res.status).toBe(201);
-    const invite = body.invite as Record<string, unknown>;
-    // Voice invites must not expose the raw token — callers redeem via
-    // the identity-bound voice code flow
-    expect(invite.token).toBeUndefined();
-  });
-
-  test("POST /v1/contacts/invites/redeem — redeems a voice invite code via unified endpoint", async () => {
-    // Create a voice invite
-    const createRes = await handleCreateInvite(
-      new Request("http://localhost/v1/contacts/invites", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          sourceChannel: "phone",
-          contactId: createTargetContact(),
-          expectedExternalUserId: "+15551234567",
-          maxUses: 1,
-        }),
-      }),
-    );
-    const created = (await createRes.json()) as {
-      invite: { voiceCode: string };
-    };
-
-    // Redeem the voice code via the unified /redeem endpoint
-    const redeemReq = new Request(
-      "http://localhost/v1/contacts/invites/redeem",
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          callerExternalUserId: "+15551234567",
-          code: created.invite.voiceCode,
-        }),
-      },
+    expect(invite.guardianInstruction).toBe(
+      "Carolina will need this code when they answer. Share it with them first.",
     );
-
-    const res = await handleRedeemInvite(redeemReq);
-    const body = (await res.json()) as Record<string, unknown>;
-
-    expect(res.status).toBe(200);
-    expect(body.ok).toBe(true);
-    expect(body.type).toBe("redeemed");
-    expect(typeof body.memberId).toBe("string");
-    expect(typeof body.inviteId).toBe("string");
+    // Voice invites never gain a share payload (no raw token exists).
+    expect(invite.share).toBeUndefined();
   });
 
-  test("POST /v1/contacts/invites/redeem — voice code missing fields returns 400", async () => {
-    const req = new Request("http://localhost/v1/contacts/invites/redeem", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ callerExternalUserId: "+15551234567" }),
+  test("voice invites fall back to the generic instruction when no contact name resolves", async () => {
+    const invite = await composeInvitePresentation({
+      contactId: "missing-contact",
+      invite: { id: "inv-voice-2", sourceChannel: "phone" },
     });
 
-    const res = await handleRedeemInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
-
-    // No `code` and no `token` → falls through to token-based path which requires token
-    expect(res.status).toBe(400);
-    expect(body.ok).toBe(false);
-  });
-
-  test("POST /v1/contacts/invites/redeem — wrong voice code returns 400", async () => {
-    // Create a voice invite
-    await handleCreateInvite(
-      new Request("http://localhost/v1/contacts/invites", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          sourceChannel: "phone",
-          contactId: createTargetContact(),
-          expectedExternalUserId: "+15551234567",
-          maxUses: 1,
-        }),
-      }),
+    expect(invite.guardianInstruction).toBe(
+      "Share this code with them — they'll need it when they answer the call.",
     );
+  });
 
-    const req = new Request("http://localhost/v1/contacts/invites/redeem", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        callerExternalUserId: "+15551234567",
-        code: "000000",
-      }),
-    });
+  test("telegram invites gain share URL + guardianInstruction when bot username is configured", async () => {
+    mockTelegramBotUsername = "test_invite_bot";
 
-    const res = await handleRedeemInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
+    try {
+      const rawToken = "raw-token-abc";
+      const invite = await composeInvitePresentation({
+        contactId: createTargetContact("Alice"),
+        invite: {
+          id: "inv-tg-1",
+          sourceChannel: "telegram",
+          token: rawToken,
+          inviteCode: "654321",
+        },
+        rawToken,
+      });
 
-    expect(res.status).toBe(400);
-    expect(body.ok).toBe(false);
+      const share = invite.share as Record<string, unknown>;
+      expect(share).toBeDefined();
+      expect(share.url).toBe(`https://t.me/test_invite_bot?start=iv_${rawToken}`);
+      expect(typeof share.displayText).toBe("string");
+      expect(typeof invite.guardianInstruction).toBe("string");
+      expect((invite.guardianInstruction as string).length).toBeGreaterThan(0);
+      // One-time secrets from the gateway payload pass through untouched.
+      expect(invite.token).toBe(rawToken);
+      expect(invite.inviteCode).toBe("654321");
+    } finally {
+      mockTelegramBotUsername = undefined;
+    }
   });
 
-  test("voice invite creation returns guardianInstruction with the contact's first name", async () => {
-    const req = new Request("http://localhost/v1/contacts/invites", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        sourceChannel: "phone",
-        contactId: createTargetContact("Carolina Flaherty"),
-        expectedExternalUserId: "+15551234567",
-      }),
+  test("non-voice payloads without an inviteCode pass through unchanged", async () => {
+    const payload = { id: "inv-x", sourceChannel: "telegram", status: "active" };
+    const invite = await composeInvitePresentation({
+      contactId: createTargetContact(),
+      invite: payload,
     });
-
-    const res = await handleCreateInvite(req);
-    const body = (await res.json()) as Record<string, unknown>;
-
-    expect(res.status).toBe(201);
-    expect(body.ok).toBe(true);
-    const invite = body.invite as Record<string, unknown>;
-    // First-token of the contact's displayName is used in the instruction
-    expect(invite.guardianInstruction).toBe(
-      "Carolina will need this code when they answer. Share it with them first.",
-    );
+    expect(invite).toEqual(payload);
   });
 });
 
@@ -547,86 +379,80 @@ describe("voice invite HTTP routes", () => {
 // Trigger invite call endpoint
 // ---------------------------------------------------------------------------
 
+// Invite lifecycle validation (existence/active/expiry/phone) lives in the
+// gateway's triggerInviteCallNative — see the gateway proxy tests. The daemon
+// only performs the provider call from the gateway-supplied fields.
 describe("POST /v1/contacts/invites/:id/call", () => {
   beforeEach(() => {
     resetTables();
     mockStartInviteCallResult = { ok: true, callSid: "CA_test_sid_123" };
+    lastStartInviteCallInput = null;
   });
 
-  test("triggers a call for an active phone invite", async () => {
-    const createRes = await handleCreateInvite(
-      new Request("http://localhost/v1/contacts/invites", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          sourceChannel: "phone",
-          contactId: createTargetContact(),
-          expectedExternalUserId: "+15551234567",
-        }),
-      }),
-    );
-    const created = (await createRes.json()) as { invite: { id: string } };
-
-    const res = await handleTriggerInviteCall(created.invite.id);
+  test("places the call from the gateway-supplied fields", async () => {
+    const res = await handleTriggerInviteCall({
+      phoneNumber: "+15551234567",
+      friendName: "Alice",
+      guardianName: "Guardian Label",
+    });
     const body = (await res.json()) as Record<string, unknown>;
 
     expect(res.status).toBe(200);
     expect(body.ok).toBe(true);
     expect(body.callSid).toBe("CA_test_sid_123");
+    expect(lastStartInviteCallInput).toEqual({
+      phoneNumber: "+15551234567",
+      friendName: "Alice",
+      guardianName: "Guardian Label",
+    });
   });
 
-  test("returns 400 for non-existent invite", async () => {
-    const res = await handleTriggerInviteCall("nonexistent-id");
+  test("returns 400 when phoneNumber is missing (no local invite fallback)", async () => {
+    // The gateway row is the lifecycle authority and supplies the call fields;
+    // the daemon has no invite store to fall back on.
+    const res = await handleTriggerInviteCall({});
     const body = (await res.json()) as Record<string, unknown>;
 
     expect(res.status).toBe(400);
     expect(body.ok).toBe(false);
-    expect(body.error).toBe("Invite not found");
+    expect(body.error).toBe("phoneNumber is required");
+    expect(lastStartInviteCallInput).toBeNull();
   });
 
-  test("returns 400 for a revoked (non-active) invite", async () => {
-    const createRes = await handleCreateInvite(
-      new Request("http://localhost/v1/contacts/invites", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          sourceChannel: "phone",
-          contactId: createTargetContact(),
-          expectedExternalUserId: "+15551234567",
-        }),
-      }),
-    );
-    const created = (await createRes.json()) as { invite: { id: string } };
+  test("empty friendName falls through to the neutral-greeting contract", async () => {
+    const res = await handleTriggerInviteCall({
+      phoneNumber: "+15551234567",
+      friendName: "   ",
+      guardianName: "Guardian Label",
+    });
 
-    // Revoke the invite
-    revokeInvite(created.invite.id);
+    expect(res.status).toBe(200);
+    expect(lastStartInviteCallInput).toMatchObject({ friendName: "" });
+  });
 
-    const res = await handleTriggerInviteCall(created.invite.id);
-    const body = (await res.json()) as Record<string, unknown>;
+  test("null guardianName falls back to the resolved guardian name", async () => {
+    const res = await handleTriggerInviteCall({
+      phoneNumber: "+15551234567",
+      friendName: "Alice",
+      guardianName: null,
+    });
 
-    expect(res.status).toBe(400);
-    expect(body.ok).toBe(false);
-    expect(body.error).toBe("Invite is not active");
+    expect(res.status).toBe(200);
+    // resolveGuardianName() has no persona in this env, so the fallback
+    // resolves to the empty-string default rather than the null passthrough.
+    expect(typeof lastStartInviteCallInput?.guardianName).toBe("string");
   });
 
-  test("returns 400 for a non-phone invite", async () => {
-    const createRes = await handleCreateInvite(
-      new Request("http://localhost/v1/contacts/invites", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          sourceChannel: "telegram",
-          contactId: createTargetContact(),
-        }),
-      }),
-    );
-    const created = (await createRes.json()) as { invite: { id: string } };
+  test("surfaces a failed provider call as 400", async () => {
+    mockStartInviteCallResult = {
+      ok: false,
+      error: "phone_number must be in E.164 format",
+    };
 
-    const res = await handleTriggerInviteCall(created.invite.id);
+    const res = await handleTriggerInviteCall({ phoneNumber: "+15551234567" });
     const body = (await res.json()) as Record<string, unknown>;
 
     expect(res.status).toBe(400);
-    expect(body.ok).toBe(false);
-    expect(body.error).toBe("Only phone invites support call triggering");
+    expect(body.error).toBe("phone_number must be in E.164 format");
   });
 });