Phase 4 Stage 1: backend foundation (additive endpoints + schema)

Schema (idempotent migration):
- payment_sessions.is_free_trial -> is_first_session_discount (data copied)
- payment_sessions.mode TEXT NOT NULL DEFAULT 'chat' CHECK (chat|call)
- chat_sessions.topics TEXT[] for ESP picks (info-only)

New endpoints:
- GET /api/client/onboarding-state (drives verif sheet + S6 paywall gate)
- GET /api/client/chat-pricing (rewrite: chat+call groups + first-session
  discount block, per-customer eligibility)
- GET /api/shared/auth-providers (env-probed; replaces ENABLE_SOCIAL_AUTH
  build flag — frontend cutover lands in stage 2)
- GET /api/client/support-handles (Tanya Admin handles, CC-config-driven)

session_warning WS event fires once at 180s remaining.

app_config seeds (mock pricing tiers, first-session discount, support
handles, payment method order, end-session 2-step toggle).

CC SettingsPage: 3 new sections (first-session discount, pricing tiers
JSON editors, support handles).

15/15 Vitest passing. chat_sessions.is_free_trial also renamed for
consistency (plan only specified payment_sessions; pairing.service.js
read both).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/test/helpers/db.js

@@ -52,7 +52,8 @@ export const resetDbHard = async () => {
 
 /**
  * Drop and re-seed the configurable app_config rows back to their canonical defaults.
- * Tests that mutate config (e.g. flipping free_trial_enabled) call this in afterEach.
+ * Tests that mutate config (e.g. flipping first_session_discount_enabled) call this
+ * in afterEach.
  */
 export const resetAppConfig = async () => {
   const sql = db()
@@ -61,8 +62,6 @@ export const resetAppConfig = async () => {
   const defaults = [
     ['anonymity', { enabled: false }],
     ['max_customers_per_mitra', { value: 3 }],
-    ['free_trial_enabled', { value: true }],
-    ['free_trial_duration_minutes', { value: 5 }],
     ['extension_timeout_seconds', { value: 60 }],
     ['early_end_mitra_enabled', { value: false }],
     ['early_end_customer_enabled', { value: false }],
@@ -70,6 +69,13 @@ export const resetAppConfig = async () => {
     ['returning_chat_confirmation_timeout_seconds', { value: 20 }],
     ['extension_default_action_on_timeout', { value: 'auto_approve' }],
     ['pairing_blast_timeout_seconds', { value: 60 }],
+    // Phase 4
+    ['first_session_discount_enabled', { value: true }],
+    ['first_session_discount_actual_price_idr', { value: 2000 }],
+    ['first_session_discount_gimmick_price_idr', { value: 12000 }],
+    ['first_session_discount_duration_minutes', { value: 12 }],
+    ['first_session_discount_modes', { value: ['chat'] }],
+    ['three_minute_warning_enabled', { value: true }],
   ]
   for (const [key, value] of defaults) {
     await sql`

backend/test/routes/client.chat-pricing.routes.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeAll, beforeEach, afterAll, vi } from 'vitest'
+
+vi.mock('../../src/plugins/websocket.js', () => ({
+  sendToUser: vi.fn(() => false),
+  sendToSessionParticipant: vi.fn(() => false),
+  registerWebSocketPlugin: vi.fn(async () => {}),
+  registerWebSocketRoute: vi.fn(),
+  isUserOnlineWs: vi.fn(() => false),
+  getSessionConnections: vi.fn(() => ({})),
+}))
+
+vi.mock('../../src/services/notification.service.js', () => ({
+  sendPushNotification: vi.fn(async () => true),
+  registerDeviceToken: vi.fn(async () => {}),
+}))
+
+const { buildPublic } = await import('../helpers/server.js')
+const { resetDb, resetAppConfig, db } = await import('../helpers/db.js')
+const { createCustomer } = await import('../helpers/fixtures.js')
+const { customerJwt, authHeader } = await import('../helpers/jwt.js')
+
+describe('GET /api/client/chat/pricing (Phase 4)', () => {
+  let app
+  let customer
+  let token
+
+  beforeAll(async () => {
+    await resetAppConfig()
+    app = await buildPublic()
+  })
+
+  beforeEach(async () => {
+    await resetDb()
+    const phone = `+628${Math.floor(Math.random() * 1e10).toString().padStart(10, '0')}`
+    customer = await createCustomer({ callName: 'PricingTester', phone })
+    token = customerJwt(customer.id)
+  })
+
+  afterAll(async () => {
+    await app?.close()
+  })
+
+  it('returns chat + call tier groups and a discount block; eligibility flips when the customer has a completed session', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/client/chat/pricing',
+      headers: authHeader(token),
+    })
+    expect(res.statusCode).toBe(200)
+    const body = res.json()
+    expect(body.success).toBe(true)
+    const data = body.data
+
+    // Two tier groups, both non-empty
+    expect(Array.isArray(data.chat?.tiers)).toBe(true)
+    expect(Array.isArray(data.call?.tiers)).toBe(true)
+    expect(data.chat.tiers.length).toBeGreaterThan(0)
+    expect(data.call.tiers.length).toBeGreaterThan(0)
+
+    // Tier shape (chat 12-min should match the seed config)
+    const chat12 = data.chat.tiers.find((t) => t.minutes === 12)
+    expect(chat12).toBeDefined()
+    expect(chat12.price_idr).toBe(12000)
+
+    // Discount block — eligible (phone-verified + no completed sessions)
+    expect(data.first_session_discount.eligible).toBe(true)
+    expect(data.first_session_discount.actual_price_idr).toBe(2000)
+    expect(data.first_session_discount.gimmick_price_idr).toBe(12000)
+    expect(data.first_session_discount.duration_minutes).toBe(12)
+    expect(data.first_session_discount.modes).toEqual(['chat'])
+
+    // Insert a completed session — eligibility must flip.
+    const sql = db()
+    await sql`
+      INSERT INTO chat_sessions (customer_id, status, duration_minutes, price)
+      VALUES (${customer.id}, 'completed', 12, 12000)
+    `
+    const after = await app.inject({
+      method: 'GET',
+      url: '/api/client/chat/pricing',
+      headers: authHeader(token),
+    })
+    expect(after.statusCode).toBe(200)
+    expect(after.json().data.first_session_discount.eligible).toBe(false)
+  })
+
+  it('eligibility is false when phone is not set (anonymous customer)', async () => {
+    const anon = await createCustomer({ callName: 'AnonCust', phone: null })
+    const anonToken = customerJwt(anon.id)
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/client/chat/pricing',
+      headers: authHeader(anonToken),
+    })
+    expect(res.statusCode).toBe(200)
+    expect(res.json().data.first_session_discount.eligible).toBe(false)
+  })
+})

backend/test/routes/client.payment.routes.test.js

@@ -34,7 +34,11 @@ describe('POST /api/client/payment-sessions', () => {
 
   beforeEach(async () => {
     await resetDb()
-    customer = await createCustomer({ callName: 'PaymentTester' })
+    // Phone-verified customer (phone non-null) is required for first-session-discount
+    // eligibility under the Phase 4 predicate.
+    // Random suffix avoids the unique-phone constraint clashing with parallel test files.
+    const phone = `+628${Math.floor(Math.random() * 1e10).toString().padStart(10, '0')}`
+    customer = await createCustomer({ callName: 'PaymentTester', phone })
     token = customerJwt(customer.id)
   })
 
@@ -42,25 +46,25 @@ describe('POST /api/client/payment-sessions', () => {
     await app?.close()
   })
 
-  it('happy path returns 201 + a pending payment-session row', async () => {
+  it('happy path returns 201 + a pending payment-session row at the discounted price for an eligible customer', async () => {
     const res = await app.inject({
       method: 'POST',
       url: '/api/client/payment-sessions',
       headers: authHeader(token),
-      payload: { duration_minutes: 15 },
+      // Discount duration default is 12 minutes (config seed). Eligible customer →
+      // amount forced to actual_price_idr (2000), is_first_session_discount=true.
+      payload: { duration_minutes: 12 },
     })
 
     expect(res.statusCode).toBe(201)
     const body = res.json()
     expect(body.success).toBe(true)
     expect(body.data.status).toBe(PaymentSessionStatus.PENDING)
-    expect(body.data.duration_minutes).toBe(15)
-    // Default tier for 15min from migrate.js is 30000 — but the eligibility logic
-    // also needs `free_trial_enabled` to be true (default) AND no prior tx. Customer is
-    // brand-new so they get the trial → amount=0, is_free_trial=true. Verify accordingly.
-    expect(body.data.is_free_trial).toBe(true)
-    expect(body.data.amount).toBe(0)
+    expect(body.data.duration_minutes).toBe(12)
+    expect(body.data.is_first_session_discount).toBe(true)
+    expect(body.data.amount).toBe(2000)
     expect(body.data.is_extension).toBe(false)
+    expect(body.data.mode).toBe('chat')
 
     // Verify persistence
     const sql = db()
@@ -69,35 +73,41 @@ describe('POST /api/client/payment-sessions', () => {
     expect(row.customer_id).toBe(customer.id)
   })
 
-  it('POST /:id/confirm transitions the row and returns 200', async () => {
-    // Create a paid (non-trial) tier so the row has a non-zero amount and we exercise the
-    // confirm path with a "real" payment. Insert a transaction first so the customer is
-    // ineligible for the free trial.
+  it('non-eligible customer pays the standard tier price', async () => {
+    // Drop first-session-discount eligibility by inserting a completed session.
     const sql = db()
-    // Bootstrap: create a fake prior chat session + transaction so the customer is no
-    // longer eligible for the free trial. (The simpler alternative — flipping
-    // free_trial_enabled in app_config — would impact other tests.)
-    const [prior] = await sql`
-      INSERT INTO chat_sessions (customer_id, status, duration_minutes, price)
-      VALUES (${customer.id}, 'completed', 15, 30000)
-      RETURNING id
-    `
     await sql`
-      INSERT INTO customer_transactions (customer_id, session_id, type, amount)
-      VALUES (${customer.id}, ${prior.id}, 'paid', 30000)
+      INSERT INTO chat_sessions (customer_id, status, duration_minutes, price)
+      VALUES (${customer.id}, 'completed', 12, 12000)
     `
 
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/client/payment-sessions',
+      headers: authHeader(token),
+      payload: { duration_minutes: 12 },
+    })
+
+    expect(res.statusCode).toBe(201)
+    const body = res.json()
+    expect(body.data.is_first_session_discount).toBe(false)
+    // 12-minute tier in Phase 4 chat tiers = 12000 IDR.
+    expect(body.data.amount).toBe(12000)
+  })
+
+  it('POST /:id/confirm transitions the row and returns 200', async () => {
+    // Use a non-discount tier (5 min @ 5000 IDR) so we exercise the regular confirm path.
     const createRes = await app.inject({
       method: 'POST',
       url: '/api/client/payment-sessions',
       headers: authHeader(token),
-      payload: { duration_minutes: 15 },
+      payload: { duration_minutes: 5 },
     })
     expect(createRes.statusCode).toBe(201)
     const created = createRes.json().data
     expect(created.status).toBe(PaymentSessionStatus.PENDING)
-    expect(created.is_free_trial).toBe(false)
-    expect(created.amount).toBe(30000)
+    expect(created.is_first_session_discount).toBe(false)
+    expect(created.amount).toBe(5000)
 
     const confirmRes = await app.inject({
       method: 'POST',
@@ -112,4 +122,21 @@ describe('POST /api/client/payment-sessions', () => {
     expect(confirmed.status).toBe(PaymentSessionStatus.CONFIRMED)
     expect(confirmed.confirmed_at).toBeTruthy()
   })
+
+  it('call-mode payment session uses the call tier price group', async () => {
+    // 20-minute call tier in Phase 4 = 17000 IDR.
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/client/payment-sessions',
+      headers: authHeader(token),
+      payload: { duration_minutes: 20, mode: 'call' },
+    })
+
+    expect(res.statusCode).toBe(201)
+    const body = res.json()
+    expect(body.data.mode).toBe('call')
+    // Eligible customer but discount modes default = ['chat'], so call is full price.
+    expect(body.data.is_first_session_discount).toBe(false)
+    expect(body.data.amount).toBe(17000)
+  })
 })

backend/test/routes/shared.auth-providers.routes.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+// Same pattern as the other route tests — keep the websocket plugin no-op so
+// buildPublic doesn't try to open real WS upgrades.
+vi.mock('../../src/plugins/websocket.js', () => ({
+  sendToUser: vi.fn(() => false),
+  sendToSessionParticipant: vi.fn(() => false),
+  registerWebSocketPlugin: vi.fn(async () => {}),
+  registerWebSocketRoute: vi.fn(),
+  isUserOnlineWs: vi.fn(() => false),
+  getSessionConnections: vi.fn(() => ({})),
+}))
+
+vi.mock('../../src/services/notification.service.js', () => ({
+  sendPushNotification: vi.fn(async () => true),
+  registerDeviceToken: vi.fn(async () => {}),
+}))
+
+describe('GET /api/shared/auth-providers (Phase 4)', () => {
+  // Snapshot env so we can mutate freely and restore.
+  const ENV_KEYS = [
+    'GOOGLE_OAUTH_CLIENT_ID',
+    'GOOGLE_OAUTH_CLIENT_SECRET',
+    'APPLE_OAUTH_CLIENT_ID',
+    'APPLE_OAUTH_TEAM_ID',
+    'APPLE_OAUTH_KEY_ID',
+    'APPLE_OAUTH_PRIVATE_KEY',
+  ]
+  let original
+
+  beforeEach(() => {
+    original = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]))
+    for (const k of ENV_KEYS) delete process.env[k]
+  })
+
+  afterEach(() => {
+    for (const k of ENV_KEYS) {
+      if (original[k] === undefined) delete process.env[k]
+      else process.env[k] = original[k]
+    }
+  })
+
+  it('returns enabled:false for google + apple when env vars are unset; phone always true', async () => {
+    // Re-import service to drop the module-load cache, then reset its in-memory cache.
+    const svc = await import('../../src/services/auth-providers.service.js')
+    svc._resetAuthProvidersCache()
+
+    const { buildPublic } = await import('../helpers/server.js')
+    const app = await buildPublic()
+    try {
+      const res = await app.inject({ method: 'GET', url: '/api/shared/auth-providers' })
+      expect(res.statusCode).toBe(200)
+      const body = res.json()
+      expect(body.success).toBe(true)
+      expect(body.data.google.enabled).toBe(false)
+      expect(body.data.apple.enabled).toBe(false)
+      expect(body.data.phone.enabled).toBe(true)
+    } finally {
+      await app.close()
+    }
+  })
+
+  it('returns enabled:true for google + apple when all env vars are set', async () => {
+    process.env.GOOGLE_OAUTH_CLIENT_ID = 'id'
+    process.env.GOOGLE_OAUTH_CLIENT_SECRET = 'secret'
+    process.env.APPLE_OAUTH_CLIENT_ID = 'apple-id'
+    process.env.APPLE_OAUTH_TEAM_ID = 'team'
+    process.env.APPLE_OAUTH_KEY_ID = 'key'
+    process.env.APPLE_OAUTH_PRIVATE_KEY = 'priv'
+
+    const svc = await import('../../src/services/auth-providers.service.js')
+    svc._resetAuthProvidersCache()
+
+    const { buildPublic } = await import('../helpers/server.js')
+    const app = await buildPublic()
+    try {
+      const res = await app.inject({ method: 'GET', url: '/api/shared/auth-providers' })
+      expect(res.statusCode).toBe(200)
+      const body = res.json()
+      expect(body.data.google.enabled).toBe(true)
+      expect(body.data.apple.enabled).toBe(true)
+      expect(body.data.phone.enabled).toBe(true)
+    } finally {
+      await app.close()
+    }
+  })
+})

backend/test/services/payment.service.test.js

@@ -38,8 +38,9 @@ describe('payment.service', () => {
     expect(session.customer_id).toBe(customer.id)
     expect(session.duration_minutes).toBe(15)
     expect(session.amount).toBe(30000)
-    expect(session.is_free_trial).toBe(false)
+    expect(session.is_first_session_discount).toBe(false)
     expect(session.is_extension).toBe(false)
+    expect(session.mode).toBe('chat')
     expect(new Date(session.expires_at).getTime()).toBeGreaterThan(before)
 
     // Verify it's actually persisted (not just returned from the INSERT)

backend/test/services/session-timer.service.test.js

@@ -0,0 +1,91 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+// Capture calls to sendToSessionParticipant so we can assert the 3-min warning event.
+vi.mock('../../src/plugins/websocket.js', () => ({
+  sendToUser: vi.fn(() => true),
+  sendToSessionParticipant: vi.fn(() => true),
+  registerWebSocketPlugin: vi.fn(),
+  registerWebSocketRoute: vi.fn(),
+  isUserOnlineWs: vi.fn(() => true),
+  getSessionConnections: vi.fn(() => ({})),
+}))
+
+vi.mock('../../src/services/notification.service.js', () => ({
+  sendPushNotification: vi.fn(async () => true),
+  registerDeviceToken: vi.fn(async () => {}),
+}))
+
+vi.mock('../../src/plugins/valkey.js', () => ({
+  publish: vi.fn(async () => {}),
+  subscribe: vi.fn(() => () => {}),
+}))
+
+const { sendToSessionParticipant } = await import('../../src/plugins/websocket.js')
+const { startSessionTimer, clearSessionTimer } = await import('../../src/services/session-timer.service.js')
+const { WsMessage, UserType } = await import('../../src/constants.js')
+
+describe('session-timer 3-minute warning (Phase 4)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    sendToSessionParticipant.mockClear()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('emits session_warning kind:three_minutes_left exactly once at the 3-min mark', async () => {
+    const sessionId = 'sess-3min-test'
+    const expiresAt = new Date(Date.now() + 5 * 60_000) // 5 minutes from now
+
+    startSessionTimer(sessionId, expiresAt)
+
+    // Advance 1 min 59 s — well before the 2-min mark when the 3-min warning fires.
+    await vi.advanceTimersByTimeAsync(60_000 + 59_000)
+    const warnCallsEarly = sendToSessionParticipant.mock.calls.filter(
+      ([, , data]) => data?.type === WsMessage.SESSION_WARNING,
+    )
+    expect(warnCallsEarly).toHaveLength(0)
+
+    // Cross the 3-min-left threshold. 5 min total - 3 min = warning fires at t=2:00.
+    await vi.advanceTimersByTimeAsync(2_000)
+    // sendToSessionParticipant signature: (sessionId, userType, data)
+    const warnCalls = sendToSessionParticipant.mock.calls.filter(
+      ([, , data]) => data?.type === WsMessage.SESSION_WARNING,
+    )
+    expect(warnCalls).toHaveLength(1)
+    const [calledSessionId, userType, data] = warnCalls[0]
+    expect(calledSessionId).toBe(sessionId)
+    expect(userType).toBe(UserType.CUSTOMER)
+    expect(data.kind).toBe('three_minutes_left')
+    expect(data.session_id).toBe(sessionId)
+
+    // Cleanup before expiry hits.
+    clearSessionTimer(sessionId)
+  })
+
+  it('does NOT re-fire the 3-min warning when the timer is rescheduled (e.g. extension)', async () => {
+    const sessionId = 'sess-rescheduled'
+    const initial = new Date(Date.now() + 5 * 60_000)
+    startSessionTimer(sessionId, initial)
+
+    // Cross the 3-min mark on the original schedule.
+    await vi.advanceTimersByTimeAsync(2 * 60_000 + 1_000)
+    let warnCalls = sendToSessionParticipant.mock.calls.filter(
+      ([, , data]) => data?.type === WsMessage.SESSION_WARNING,
+    )
+    expect(warnCalls).toHaveLength(1)
+
+    // Extension reschedules — give a new 5-min window. The 3-min warning must NOT fire again.
+    const extended = new Date(Date.now() + 5 * 60_000)
+    startSessionTimer(sessionId, extended)
+    await vi.advanceTimersByTimeAsync(2 * 60_000 + 1_000)
+
+    warnCalls = sendToSessionParticipant.mock.calls.filter(
+      ([, , data]) => data?.type === WsMessage.SESSION_WARNING,
+    )
+    expect(warnCalls).toHaveLength(1) // still 1, no double-fire
+
+    clearSessionTimer(sessionId)
+  })
+})