feat: phone credit (CoinPay), 71 countries, agents on the phone, qc call/phone (0.15.0, qc 0.10.0) (#336)

Anthony: "do it all" (paid credit, international, agents placing calls, qc).

- Credit: $5/$10/$25 on CoinPay's hosted checkout (business "qryptchat-web" made
  with coinpay-onboard; keys in vault + app.env). POST /api/phone/topup ->
  phone_topups row + checkout session; /api/phone/coinpay-webhook verifies the
  signature and credits exactly once (phone_credit_topup), by metadata or session.
- Billing in micro-dollars: US/Canada free minutes first, then 1 cent per started
  minute, charged at hang-up; other countries 2x the carrier cost read from Telnyx
  detail records (telnyx_session_id), settled when the records exist (retried, and on
  GET /api/phone). phone_charge_call charges once. Integer micros (2 * 0.0072 * 1e6
  is 14400.000000000002 in floating point).
- International: 71 countries on the Telnyx profile with max_destination_rate 0.10,
  libphonenumber-js parsing, premium/shared-cost/UAN refused, no free minutes abroad,
  allowance limited at the worst-case 20.4 cents/min.
- Agents: Call Control app "qrypt.chat agent calls" posts to /api/phone/agent-webhook,
  stored in phone_agent_events; the agent host long-polls /api/phone/agent-events
  (AGENT_PHONE_SECRET) because it takes no inbound connections. agent-phone (on the
  host) transcribes with Telnyx transcription_start and speaks with ElevenLabs via a
  Telnyx integration secret.
- qc phone (minutes, credit, recent calls) and qc call <number> (opens the dialer).
- /phone: credit and buy buttons, + for international numbers, per-call charges.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: ralyodio

README.md

@@ -218,6 +218,7 @@ QryptChat implements a **zero-knowledge post-quantum architecture** where:
 - [🔒 Encryption Details](./ENCRYPTION.md)
 - [✉️ Inviting agents and people](./docs/INVITES.md)
 - [🎙️ Voice mode](./docs/VOICE.md)
+- [📞 Phone calls](./docs/PHONE.md)
 
 ## 🧪 Development
 

bun.lock

@@ -0,0 +1,31 @@
+# Phone calls
+
+Call ordinary phones from qrypt.chat, the way Skype used to: [qrypt.chat/phone](https://qrypt.chat/phone),
+`qc call <number>` (opens the dialer) and `qc phone` (minutes, credit, recent calls).
+
+- **Free:** 10 minutes a day (UTC) to the US and Canada for every signed-in account. Anonymous accounts
+  get none.
+- **Credit:** $5, $10 or $25 on CoinPay's checkout (crypto or PayPal); it never expires. US/Canada past the
+  free minutes costs 1¢ a minute. Other countries (71 open, in `ALLOWED_COUNTRIES`) cost twice what our
+  carrier charges us for that call, read from Telnyx's call records; no destination over 10¢/min carrier cost
+  is allowed, so a call is limited up front as if it cost 20.4¢/min.
+- **Not end-to-end encrypted:** calls to phones go over the public phone network. Calls between qrypt.chat
+  users stay end-to-end encrypted.
+- The person you call sees +1 949-284-7328. 911 and other service codes, premium-rate and shared-cost numbers
+  cannot be called.
+
+## How it works
+
+The browser's line is a per-user Telnyx WebRTC credential that can only *receive* calls. `POST /api/phone/call`
+checks the number and the allowance, rings that line through a Call Control app, and when the browser answers
+transfers it to the number with `time_limit_secs` = the allowance, so Telnyx itself ends the call. Webhooks
+(`/api/phone/webhook`, Ed25519-signed) drive billing; `POST /api/phone/topup` + `/api/phone/coinpay-webhook`
+add credit exactly once per checkout. Code: `src/lib/phone/rules.js`, `src/lib/server/phone.js`,
+`src/lib/server/phone-credit.js`, `src/lib/server/telnyx-voice.js`.
+
+## Agents on the phone
+
+Anthony's agents can make calls for him (`agent-phone call <number> --goal "..."` on the agent host). Telnyx
+transcribes the other side and speaks the agent's lines in its ElevenLabs voice; the agent says it is an AI
+assistant in its first line and reports the outcome in the chat. The host takes no inbound connections:
+Telnyx posts events to `/api/phone/agent-webhook` and the agent long-polls `/api/phone/agent-events`.

docs/PHONE.md

@@ -1,7 +1,7 @@
 {
   "name": "qryptchat-web",
   "private": true,
-  "version": "0.14.0",
+  "version": "0.15.0",
   "type": "module",
   "bin": {
     "qc": "./bin/qc.js",
@@ -60,6 +60,7 @@
     "@noble/ciphers": "^2.0.0",
     "@noble/hashes": "^2.0.0",
     "@profullstack/autoblog": "github:profullstack/autoblog#75e54af77cbcf61dbd90fb3ed529c1b2dad1ed6f",
+    "@profullstack/coinpay-onboard": "0.2.0",
     "@profullstack/encrypt": "^0.1.0",
     "@profullstack/footer": "latest",
     "@profullstack/openprofile": "^0.2.0",
@@ -75,6 +76,7 @@
     "blessed": "^0.1.81",
     "dilithium-crystals": "^1.0.6",
     "dotenv": "^17.2.2",
+    "libphonenumber-js": "1.12.25",
     "mlkem": "^2.5.0",
     "next": "16.4.3",
     "openpgp": "^6.2.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/qryptchat",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "qc: qrypt.chat in your terminal. A full-screen end-to-end encrypted chat client (ML-KEM-1024), plus a scriptable CLI and an MCP server.",
   "type": "module",
   "bin": {

packages/qryptchat/package.json

@@ -0,0 +1,44 @@
+import crypto from 'node:crypto';
+import { NextResponse } from 'next/server';
+import { getServiceRoleClient } from '@/lib/supabase/service-role.js';
+
+export const dynamic = 'force-dynamic';
+
+const WAIT_MS = 20_000;
+const STEP_MS = 250;
+
+function authorized(request) {
+	const secret = process.env.AGENT_PHONE_SECRET;
+	const given = request.headers.get('x-agent-phone-secret') || '';
+	if (!secret || given.length !== secret.length) return false;
+	return crypto.timingSafeEqual(Buffer.from(given), Buffer.from(secret));
+}
+
+/**
+ * GET /api/phone/agent-events?session=<call_session_id>&after=<id>: the Telnyx
+ * events for one agent call, waiting up to 20 s for new ones (long poll).
+ * Only the agent host holds AGENT_PHONE_SECRET.
+ */
+export async function GET(request) {
+	if (!authorized(request)) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+	const url = new URL(request.url);
+	const session = url.searchParams.get('session') || '';
+	const after = Number(url.searchParams.get('after') || 0);
+	if (!session) return NextResponse.json({ error: 'session is required' }, { status: 400 });
+	const db = getServiceRoleClient();
+	const deadline = Date.now() + WAIT_MS;
+	while (true) {
+		const { data, error } = await db
+			.from('phone_agent_events')
+			.select('id, event')
+			.eq('session_id', session)
+			.gt('id', after)
+			.order('id', { ascending: true })
+			.limit(100);
+		if (error) return NextResponse.json({ error: error.message }, { status: 500 });
+		if (data?.length || Date.now() >= deadline || request.signal?.aborted) {
+			return NextResponse.json({ events: data || [] }, { headers: { 'Cache-Control': 'no-store' } });
+		}
+		await new Promise((r) => setTimeout(r, STEP_MS));
+	}
+}

src/app/api/phone/agent-events/route.js

@@ -0,0 +1,39 @@
+import { NextResponse } from 'next/server';
+import { getServiceRoleClient } from '@/lib/supabase/service-role.js';
+import { telnyxConfig, verifyWebhook } from '@/lib/server/telnyx-voice.js';
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * POST /api/phone/agent-webhook: Telnyx events for phone calls AI agents place
+ * (the "qrypt.chat agent calls" Call Control app). Stored for the agent to pick
+ * up from /api/phone/agent-events; old rows are pruned as new ones arrive.
+ */
+export async function POST(request) {
+	const body = await request.text();
+	const ok = verifyWebhook({
+		body,
+		signature: request.headers.get('telnyx-signature-ed25519'),
+		timestamp: request.headers.get('telnyx-timestamp'),
+		publicKey: telnyxConfig().publicKey,
+	});
+	if (!ok) return NextResponse.json({ error: 'Bad signature' }, { status: 401 });
+	let event;
+	try {
+		event = JSON.parse(body)?.data;
+	} catch {
+		return NextResponse.json({ error: 'Bad JSON' }, { status: 400 });
+	}
+	const sessionId = event?.payload?.call_session_id;
+	if (!sessionId) return NextResponse.json({ ok: true, ignored: 'no session' });
+	const db = getServiceRoleClient();
+	const { error } = await db.from('phone_agent_events').insert({ session_id: sessionId, event });
+	if (error) {
+		console.error('[phone/agent-webhook]', error.message);
+		return NextResponse.json({ error: 'failed' }, { status: 500 });
+	}
+	if (Math.random() < 0.02) {
+		await db.from('phone_agent_events').delete().lt('created_at', new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString());
+	}
+	return NextResponse.json({ ok: true });
+}

src/app/api/phone/agent-webhook/route.js

@@ -0,0 +1,25 @@
+import { NextResponse } from 'next/server';
+import { PhoneError } from '@/lib/server/phone.js';
+import { handleCoinpayWebhook } from '@/lib/server/phone-credit.js';
+import { phoneContext } from '@/lib/server/phone-route.js';
+
+export const dynamic = 'force-dynamic';
+
+/** POST /api/phone/coinpay-webhook: CoinPay payment events; a paid top-up adds phone credit once. */
+export async function POST(request) {
+	const rawBody = await request.text();
+	try {
+		const { store } = phoneContext();
+		const result = await handleCoinpayWebhook({
+			store,
+			rawBody,
+			signature: request.headers.get('x-coinpay-signature'),
+			secret: process.env.COINPAY_WEBHOOK_SECRET,
+		});
+		return NextResponse.json({ ok: true, ...result });
+	} catch (error) {
+		if (error instanceof PhoneError) return NextResponse.json({ error: error.message }, { status: error.status });
+		console.error('[phone/coinpay-webhook]', error?.message);
+		return NextResponse.json({ error: 'failed' }, { status: 500 });
+	}
+}

src/app/api/phone/coinpay-webhook/route.js

@@ -1,20 +1,31 @@
 import { NextResponse } from 'next/server';
 import { withAuth } from '@/lib/api/middleware/auth.js';
-import { accountState } from '@/lib/server/phone.js';
+import { accountState, settlePending } from '@/lib/server/phone.js';
+import { coinpayConfigured } from '@/lib/server/phone-credit.js';
 import { phoneContext, phoneError, phoneUser } from '@/lib/server/phone-route.js';
-import { CENTS_PER_MINUTE, FREE_SECONDS_PER_DAY } from '@/lib/phone/rules.js';
+import { ALLOWED_COUNTRIES, FREE_COUNTRIES, FREE_SECONDS_PER_DAY, INTL_MAX_MICROS_PER_MINUTE, TOPUP_DOLLARS, US_CA_MICROS_PER_MINUTE } from '@/lib/phone/rules.js';
 
 export const dynamic = 'force-dynamic';
 
-/** GET /api/phone: today's free minutes, recent calls, caller ID. */
+/** GET /api/phone: free minutes, credit, prices, recent calls, caller ID. */
 export const GET = withAuth(async ({ locals }) => {
 	try {
-		const { db, store, config } = phoneContext();
+		const { db, store, telnyx, config } = phoneContext();
 		const user = await phoneUser(db, locals.user.id);
+		await settlePending({ store, telnyx, userId: user.id });
 		const account = await accountState({ store, user });
 		const calls = (await store.recentCalls(user.id)) || [];
 		return NextResponse.json(
-			{ ...account, freeSecondsPerDay: FREE_SECONDS_PER_DAY, centsPerMinute: CENTS_PER_MINUTE, callerId: config.callerId, calls },
+			{
+				...account,
+				freeSecondsPerDay: FREE_SECONDS_PER_DAY,
+				freeCountries: FREE_COUNTRIES,
+				countries: ALLOWED_COUNTRIES,
+				prices: { usCaMicrosPerMinute: US_CA_MICROS_PER_MINUTE, intlMaxMicrosPerMinute: INTL_MAX_MICROS_PER_MINUTE, intl: 'twice the carrier cost' },
+				topups: coinpayConfigured() ? TOPUP_DOLLARS : [],
+				callerId: config.callerId,
+				calls,
+			},
 			{ headers: { 'Cache-Control': 'no-store' } }
 		);
 	} catch (error) {

src/app/api/phone/route.js

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server';
+import { withAuth } from '@/lib/api/middleware/auth.js';
+import { RateLimiter, applyRateLimitForKey } from '@/lib/server/rate-limiter.js';
+import { PhoneError } from '@/lib/server/phone.js';
+import { coinpayClient, coinpayConfigured, createTopup } from '@/lib/server/phone-credit.js';
+import { phoneContext, phoneError, phoneUser } from '@/lib/server/phone-route.js';
+
+const limiter = new RateLimiter({ maxRequests: 10, windowMs: 10 * 60 * 1000 });
+
+/** POST /api/phone/topup { dollars }: a CoinPay checkout for phone credit; returns { url }. */
+export const POST = withAuth(async ({ request, locals }) => {
+	const limited = applyRateLimitForKey(limiter, locals.user.id);
+	if (limited) return limited;
+	try {
+		if (!coinpayConfigured()) throw new PhoneError('Buying credit is not set up on this server.', 503);
+		const body = await request.json().catch(() => ({}));
+		const { db, store } = phoneContext();
+		const user = await phoneUser(db, locals.user.id);
+		const result = await createTopup({ store, coinpay: coinpayClient(), user, email: locals.user.email, dollars: body?.dollars });
+		return NextResponse.json(result, { headers: { 'Cache-Control': 'no-store' } });
+	} catch (error) {
+		if (error?.name === 'CoinPayError') {
+			console.error('[phone/topup] coinpay', error.status, error.message);
+			return NextResponse.json({ error: 'CoinPay could not start the checkout.' }, { status: 502 });
+		}
+		return phoneError(error, 'topup');
+	}
+});