@open-mercato/channel-gmail 0.6.4

package/src/modules/channel_gmail/lib/__tests__/convert-outbound.test.ts

@@ -0,0 +1,128 @@
+import { convertOutboundForGmail } from '../convert-outbound'
+
+describe('convertOutboundForGmail', () => {
+  it('assembles a multipart/alternative RFC2822 message when html and text both present', async () => {
+    const result = await convertOutboundForGmail({
+      body: '<p>Hello <b>world</b></p>',
+      bodyFormat: 'html',
+      channelMetadata: { subject: 'Hi', to: ['bob@example.com'] },
+      fromAddress: 'alice@gmail.com',
+      fromName: 'Alice',
+    })
+    const meta = result.metadata as Record<string, unknown>
+    const raw = (meta.rawMessage as Buffer).toString('utf-8')
+    expect(raw).toContain('From: "Alice" <alice@gmail.com>')
+    expect(raw).toContain('To: bob@example.com')
+    expect(raw).toContain('Subject: Hi')
+    expect(raw).toContain('MIME-Version: 1.0')
+    expect(raw).toContain('multipart/alternative')
+    expect(raw).toContain('Content-Type: text/plain')
+    expect(raw).toContain('Content-Type: text/html')
+    expect(raw).toContain('<p>Hello <b>world</b></p>')
+  })
+
+  it('preserves the inReplyTo / references headers when threading', async () => {
+    const result = await convertOutboundForGmail({
+      body: 'reply',
+      bodyFormat: 'text',
+      channelMetadata: {
+        to: ['root@example.com'],
+        inReplyTo: '<root@example.com>',
+        references: ['<root@example.com>', '<parent@example.com>'],
+      },
+      fromAddress: 'alice@gmail.com',
+    })
+    const meta = result.metadata as Record<string, unknown>
+    const raw = (meta.rawMessage as Buffer).toString('utf-8')
+    expect(raw).toContain('In-Reply-To: <root@example.com>')
+    expect(raw).toContain('References: <root@example.com> <parent@example.com>')
+  })
+
+  it('passes gmailThreadId through metadata.threadId', async () => {
+    const result = await convertOutboundForGmail({
+      body: 'hi',
+      bodyFormat: 'text',
+      channelMetadata: { to: 'bob@example.com', gmailThreadId: 'thread-abc' },
+      fromAddress: 'alice@gmail.com',
+    })
+    expect((result.metadata as Record<string, unknown>).threadId).toBe('thread-abc')
+  })
+
+  it('derives the Gmail threadId from the hub gmail-thread conversation ref', async () => {
+    const result = await convertOutboundForGmail({
+      body: 'reply',
+      bodyFormat: 'text',
+      channelMetadata: { to: ['bob@example.com'], thread_id: 'gmail-thread:18cabc123' },
+      fromAddress: 'alice@gmail.com',
+    })
+    expect((result.metadata as Record<string, unknown>).threadId).toBe('18cabc123')
+  })
+
+  it('leaves threadId unset for a new outbound thread ref so Gmail starts a fresh thread', async () => {
+    const result = await convertOutboundForGmail({
+      body: 'new',
+      bodyFormat: 'text',
+      channelMetadata: { to: ['bob@example.com'], thread_id: 'outbound:550e8400-e29b-41d4-a716-446655440000' },
+      fromAddress: 'alice@gmail.com',
+    })
+    expect((result.metadata as Record<string, unknown>).threadId).toBeUndefined()
+  })
+
+  it('preserves the Gmail threadId across the hub convert→send double-conversion', async () => {
+    const firstPass = await convertOutboundForGmail({
+      body: 'reply',
+      bodyFormat: 'text',
+      channelMetadata: { to: ['bob@example.com'], thread_id: 'gmail-thread:18cabc123' },
+      fromAddress: 'alice@gmail.com',
+    })
+    const secondPass = await convertOutboundForGmail({
+      body: 'reply',
+      bodyFormat: 'text',
+      channelMetadata: firstPass.metadata as Record<string, unknown>,
+      fromAddress: 'alice@gmail.com',
+    })
+    expect((secondPass.metadata as Record<string, unknown>).threadId).toBe('18cabc123')
+  })
+
+  it('rejects when there are no recipients', async () => {
+    await expect(
+      convertOutboundForGmail({
+        body: 'hi',
+        bodyFormat: 'text',
+        channelMetadata: {},
+        fromAddress: 'alice@gmail.com',
+      }),
+    ).rejects.toThrow(/at least one recipient/i)
+  })
+
+  it('auto-generates a Message-ID rooted in the From address when missing', async () => {
+    const result = await convertOutboundForGmail({
+      body: 'hi',
+      bodyFormat: 'text',
+      channelMetadata: { to: ['bob@example.com'] },
+      fromAddress: 'alice@gmail.com',
+    })
+    const meta = result.metadata as Record<string, unknown>
+    const generated = meta.messageId as string
+    expect(generated).toMatch(/^<[^@]+@gmail\.com>$/)
+  })
+
+  it('neutralizes CRLF header injection in subject / fromName', async () => {
+    const result = await convertOutboundForGmail({
+      body: 'hi',
+      bodyFormat: 'text',
+      channelMetadata: {
+        subject: 'Hello\r\nBcc: attacker@evil.com',
+        to: ['bob@example.com'],
+      },
+      fromAddress: 'alice@gmail.com',
+      fromName: 'Alice\r\nX-Injected: 1',
+    })
+    const meta = result.metadata as Record<string, unknown>
+    const raw = (meta.rawMessage as Buffer).toString('utf-8')
+    // The injected CRLF must collapse into the header value, not start a new header.
+    expect(raw).not.toMatch(/^Bcc: attacker@evil\.com/m)
+    expect(raw).not.toMatch(/^X-Injected:/m)
+    expect(raw).toMatch(/^Subject: /m)
+  })
+})

package/src/modules/channel_gmail/lib/__tests__/credentials.test.ts

@@ -0,0 +1,76 @@
+import {
+  gmailClientCredentialsSchema,
+  gmailUserCredentialsSchema,
+  gmailChannelStateSchema,
+  GMAIL_DEFAULT_SCOPES,
+  parseScopes,
+} from '../credentials'
+
+describe('gmailClientCredentialsSchema', () => {
+  it('accepts a fully populated tenant OAuth client config', () => {
+    expect(
+      gmailClientCredentialsSchema.parse({
+        clientId: '1234.apps.googleusercontent.com',
+        clientSecret: 'secret',
+        scopes: 'https://www.googleapis.com/auth/gmail.modify',
+      }),
+    ).toMatchObject({ clientId: '1234.apps.googleusercontent.com', clientSecret: 'secret' })
+  })
+
+  it('rejects missing required fields', () => {
+    expect(() => gmailClientCredentialsSchema.parse({ clientId: '', clientSecret: 'x' })).toThrow(/OAuth Client ID/i)
+    expect(() => gmailClientCredentialsSchema.parse({ clientId: 'a', clientSecret: '' })).toThrow(/OAuth Client Secret/i)
+  })
+})
+
+describe('gmailUserCredentialsSchema', () => {
+  it('accepts an access+refresh token pair', () => {
+    expect(
+      gmailUserCredentialsSchema.parse({
+        accessToken: 'a',
+        refreshToken: 'r',
+        expiresAt: '2026-05-26T10:00:00.000Z',
+        scopes: ['https://www.googleapis.com/auth/gmail.modify'],
+        email: 'alice@gmail.com',
+      }),
+    ).toMatchObject({ accessToken: 'a', refreshToken: 'r', email: 'alice@gmail.com' })
+  })
+
+  it('treats refresh token as optional but access token as required', () => {
+    expect(gmailUserCredentialsSchema.parse({ accessToken: 'a' })).toMatchObject({ accessToken: 'a' })
+    expect(() => gmailUserCredentialsSchema.parse({ refreshToken: 'r' })).toThrow(/Access token/i)
+  })
+
+  it('rejects invalid expiresAt format', () => {
+    expect(() => gmailUserCredentialsSchema.parse({ accessToken: 'a', expiresAt: 'soon' })).toThrow()
+  })
+
+  it('rejects non-email email', () => {
+    expect(() => gmailUserCredentialsSchema.parse({ accessToken: 'a', email: 'not-an-email' })).toThrow()
+  })
+})
+
+describe('gmailChannelStateSchema', () => {
+  it('accepts a numeric or string historyId', () => {
+    expect(gmailChannelStateSchema.parse({ historyId: 12345 })).toMatchObject({ historyId: 12345 })
+    expect(gmailChannelStateSchema.parse({ historyId: '12345' })).toMatchObject({ historyId: '12345' })
+  })
+
+  it('accepts an empty state', () => {
+    expect(gmailChannelStateSchema.parse({})).toEqual({})
+  })
+})
+
+describe('parseScopes', () => {
+  it('returns Gmail defaults when input is blank or undefined', () => {
+    expect(parseScopes(undefined)).toEqual(GMAIL_DEFAULT_SCOPES)
+    expect(parseScopes('')).toEqual(GMAIL_DEFAULT_SCOPES)
+    expect(parseScopes('   ')).toEqual(GMAIL_DEFAULT_SCOPES)
+  })
+
+  it('splits comma and whitespace separated scope lists', () => {
+    expect(parseScopes('a,b,c')).toEqual(['a', 'b', 'c'])
+    expect(parseScopes('a b c')).toEqual(['a', 'b', 'c'])
+    expect(parseScopes('a, b,  c\n d')).toEqual(['a', 'b', 'c', 'd'])
+  })
+})

package/src/modules/channel_gmail/lib/__tests__/gmail-client.test.ts

@@ -0,0 +1,209 @@
+import { decodeBase64Url, encodeBase64Url, getGmailApiClient, GmailApiError, setGmailApiClient } from '../gmail-client'
+
+describe('base64url encoding helpers', () => {
+  it('encodeBase64Url uses URL-safe alphabet without padding', () => {
+    const buffer = Buffer.from('Hello, world?', 'utf-8')
+    const encoded = encodeBase64Url(buffer)
+    expect(encoded).not.toContain('+')
+    expect(encoded).not.toContain('/')
+    expect(encoded).not.toContain('=')
+    expect(decodeBase64Url(encoded).toString('utf-8')).toBe('Hello, world?')
+  })
+
+  it('decodeBase64Url tolerates padded inputs', () => {
+    const buffer = Buffer.from('1', 'utf-8')
+    const encoded = buffer.toString('base64') // produces '1' → 'MQ=='
+    expect(decodeBase64Url(encoded).toString('utf-8')).toBe('1')
+  })
+
+  it('round-trips arbitrary binary data', () => {
+    const input = Buffer.from([0, 1, 2, 250, 251, 252, 253, 254, 255])
+    expect(decodeBase64Url(encodeBase64Url(input))).toEqual(input)
+  })
+})
+
+describe('GmailApiError', () => {
+  it('captures status + detail for downstream classification', () => {
+    const e = new GmailApiError('Gmail API GET /history failed: invalid_grant', 401, 'invalid_grant')
+    expect(e.name).toBe('GmailApiError')
+    expect(e.status).toBe(401)
+    expect(e.detail).toBe('invalid_grant')
+  })
+})
+
+type FakeResponseInit = {
+  ok?: boolean
+  status: number
+  statusText?: string
+  body?: string
+  headers?: Record<string, string>
+}
+
+function fakeResponse(init: FakeResponseInit): Response {
+  const headerMap = new Map(
+    Object.entries(init.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]),
+  )
+  return {
+    ok: init.ok ?? (init.status >= 200 && init.status < 300),
+    status: init.status,
+    statusText: init.statusText ?? '',
+    headers: { get: (name: string) => headerMap.get(name.toLowerCase()) ?? null },
+    text: async () => init.body ?? '',
+  } as unknown as Response
+}
+
+describe('FetchGmailApiClient.requestJson retry/backoff', () => {
+  const originalFetch = globalThis.fetch
+  const originalSetTimeout = globalThis.setTimeout
+  const originalRandom = Math.random
+  let capturedDelays: number[]
+
+  beforeEach(() => {
+    // Reset the cached singleton so each test gets the real FetchGmailApiClient
+    // (other suites may have swapped in a mock via setGmailApiClient).
+    setGmailApiClient(null)
+    capturedDelays = []
+    // Replace the backoff sleep with a synchronous no-wait shim that records the
+    // requested delay and fires the callback immediately, so the retry loop runs
+    // without real timers while we assert the computed wait durations.
+    globalThis.setTimeout = ((callback: () => void, ms?: number) => {
+      capturedDelays.push(typeof ms === 'number' ? ms : 0)
+      callback()
+      return 0 as unknown as ReturnType<typeof setTimeout>
+    }) as unknown as typeof globalThis.setTimeout
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    globalThis.setTimeout = originalSetTimeout
+    Math.random = originalRandom
+    setGmailApiClient(null)
+  })
+
+  it('retries a 429 then succeeds on the following 200', async () => {
+    let calls = 0
+    globalThis.fetch = (() => {
+      calls += 1
+      if (calls === 1) {
+        return Promise.resolve(
+          fakeResponse({ status: 429, statusText: 'Too Many Requests', body: '', headers: { 'retry-after': '2' } }),
+        )
+      }
+      return Promise.resolve(
+        fakeResponse({ status: 200, statusText: 'OK', body: JSON.stringify({ emailAddress: 'a@gmail.com', historyId: '7' }) }),
+      )
+    }) as unknown as typeof globalThis.fetch
+
+    const profile = await getGmailApiClient().getProfile({ accessToken: 'token' })
+
+    expect(calls).toBe(2)
+    expect(profile.historyId).toBe('7')
+    // Numeric Retry-After: `2` seconds → 2000ms, bounded by the 8s cap.
+    expect(capturedDelays).toEqual([2000])
+  })
+
+  it('retries a transient 503 then succeeds, honoring computeBackoff when no Retry-After header', async () => {
+    Math.random = () => 0 // strip jitter so the backoff is deterministic
+    let calls = 0
+    globalThis.fetch = (() => {
+      calls += 1
+      if (calls <= 2) {
+        return Promise.resolve(fakeResponse({ status: 503, statusText: 'Service Unavailable', body: '' }))
+      }
+      return Promise.resolve(
+        fakeResponse({ status: 200, statusText: 'OK', body: JSON.stringify({ emailAddress: 'a@gmail.com', historyId: '9' }) }),
+      )
+    }) as unknown as typeof globalThis.fetch
+
+    const profile = await getGmailApiClient().getProfile({ accessToken: 'token' })
+
+    expect(calls).toBe(3)
+    expect(profile.historyId).toBe('9')
+    // computeBackoff(attempt) = 500 * 2^attempt (+0 jitter): attempt 0 → 500ms, attempt 1 → 1000ms.
+    expect(capturedDelays).toEqual([500, 1000])
+  })
+
+  it('caps computeBackoff growth at the 8s ceiling across successive attempts', async () => {
+    Math.random = () => 0
+    // Always-5xx so the client exhausts all retries; this walks attempts 0..2 of
+    // computeBackoff (the 4th call has no further retry). 500, 1000, 2000 — all
+    // below the cap, but the doubling growth + ceiling math is exercised; assert
+    // each step is min(500 * 2^attempt, 8000) and monotonically non-decreasing.
+    globalThis.fetch = (() =>
+      Promise.resolve(fakeResponse({ status: 500, statusText: 'Server Error', body: '' }))) as unknown as typeof globalThis.fetch
+
+    await expect(getGmailApiClient().getProfile({ accessToken: 'token' })).rejects.toBeInstanceOf(GmailApiError)
+
+    expect(capturedDelays).toEqual([500, 1000, 2000])
+    for (const delay of capturedDelays) expect(delay).toBeLessThanOrEqual(8000)
+    for (let i = 1; i < capturedDelays.length; i += 1) {
+      expect(capturedDelays[i]).toBeGreaterThanOrEqual(capturedDelays[i - 1])
+    }
+  })
+
+  it('honors an HTTP-date Retry-After value, bounded by the 8s cap', async () => {
+    let calls = 0
+    // 3 seconds in the future → ~3000ms wait, still under the 8s ceiling.
+    const retryAt = new Date(Date.now() + 3_000).toUTCString()
+    globalThis.fetch = (() => {
+      calls += 1
+      if (calls === 1) {
+        return Promise.resolve(
+          fakeResponse({ status: 429, statusText: 'Too Many Requests', body: '', headers: { 'retry-after': retryAt } }),
+        )
+      }
+      return Promise.resolve(
+        fakeResponse({ status: 200, statusText: 'OK', body: JSON.stringify({ emailAddress: 'a@gmail.com', historyId: '1' }) }),
+      )
+    }) as unknown as typeof globalThis.fetch
+
+    await getGmailApiClient().getProfile({ accessToken: 'token' })
+
+    expect(calls).toBe(2)
+    expect(capturedDelays).toHaveLength(1)
+    // Date.parse(retryAt) drops sub-second precision, so the delta is ~2000-3000ms.
+    expect(capturedDelays[0]).toBeGreaterThan(1000)
+    expect(capturedDelays[0]).toBeLessThanOrEqual(8000)
+  })
+
+  it('throws GmailApiError carrying the upstream status after exhausting retries', async () => {
+    Math.random = () => 0
+    let calls = 0
+    globalThis.fetch = (() => {
+      calls += 1
+      return Promise.resolve(
+        fakeResponse({ status: 503, statusText: 'Service Unavailable', body: JSON.stringify({ error: { message: 'backend overloaded' } }) }),
+      )
+    }) as unknown as typeof globalThis.fetch
+
+    const thrown = await getGmailApiClient()
+      .getProfile({ accessToken: 'token' })
+      .catch((error: unknown) => error)
+
+    expect(thrown).toBeInstanceOf(GmailApiError)
+    expect((thrown as GmailApiError).status).toBe(503)
+    expect((thrown as GmailApiError).detail).toBe('backend overloaded')
+    // GMAIL_MAX_RETRIES = 3 → 1 initial + 3 retries = 4 total attempts.
+    expect(calls).toBe(4)
+    expect(capturedDelays).toEqual([500, 1000, 2000])
+  })
+
+  it('does not retry a permanent 401 — fails fast with no backoff', async () => {
+    let calls = 0
+    globalThis.fetch = (() => {
+      calls += 1
+      return Promise.resolve(
+        fakeResponse({ status: 401, statusText: 'Unauthorized', body: JSON.stringify({ error: { message: 'invalid_grant' } }) }),
+      )
+    }) as unknown as typeof globalThis.fetch
+
+    const thrown = await getGmailApiClient()
+      .getProfile({ accessToken: 'token' })
+      .catch((error: unknown) => error)
+
+    expect(thrown).toBeInstanceOf(GmailApiError)
+    expect((thrown as GmailApiError).status).toBe(401)
+    expect(calls).toBe(1)
+    expect(capturedDelays).toEqual([])
+  })
+})

package/src/modules/channel_gmail/lib/__tests__/normalize-inbound.test.ts

@@ -0,0 +1,106 @@
+import { normalizeInboundGmailMessage } from '../normalize-inbound'
+
+function buildMime(parts: {
+  messageId?: string
+  inReplyTo?: string
+  references?: string
+  subject?: string
+  from?: string
+  to?: string
+  date?: string
+  text?: string
+  html?: string
+}): Buffer {
+  const headers: string[] = []
+  if (parts.messageId) headers.push(`Message-ID: ${parts.messageId}`)
+  if (parts.inReplyTo) headers.push(`In-Reply-To: ${parts.inReplyTo}`)
+  if (parts.references) headers.push(`References: ${parts.references}`)
+  if (parts.subject) headers.push(`Subject: ${parts.subject}`)
+  if (parts.from) headers.push(`From: ${parts.from}`)
+  if (parts.to) headers.push(`To: ${parts.to}`)
+  if (parts.date) headers.push(`Date: ${parts.date}`)
+  headers.push('MIME-Version: 1.0')
+  if (parts.html) {
+    headers.push('Content-Type: text/html; charset=utf-8')
+    return Buffer.from(headers.join('\r\n') + '\r\n\r\n' + parts.html, 'utf-8')
+  }
+  headers.push('Content-Type: text/plain; charset=utf-8')
+  return Buffer.from(headers.join('\r\n') + '\r\n\r\n' + (parts.text ?? ''), 'utf-8')
+}
+
+describe('normalizeInboundGmailMessage', () => {
+  it('uses Gmail threadId for externalConversationId, not the RFC2822 root', async () => {
+    const result = await normalizeInboundGmailMessage({
+      rawMessage: buildMime({
+        messageId: '<reply@example.com>',
+        inReplyTo: '<parent@example.com>',
+        references: '<root@example.com> <parent@example.com>',
+        from: '"Alice" <alice@gmail.com>',
+        to: 'bob@example.com',
+        subject: 'Re: original',
+        text: 'replying',
+      }),
+      gmailMessageId: 'gm-msg-100',
+      gmailThreadId: 'gm-thread-1',
+      gmailLabelIds: ['INBOX', 'IMPORTANT'],
+      accountIdentifier: 'bob@example.com',
+    })
+    expect(result.externalMessageId).toBe('reply@example.com')
+    expect(result.externalConversationId).toBe('gmail-thread:gm-thread-1')
+    expect(result.replyToExternalId).toBe('parent@example.com')
+    expect((result.channelMetadata as { gmailLabelIds: string[] }).gmailLabelIds).toEqual(['INBOX', 'IMPORTANT'])
+  })
+
+  it('synthesises a deterministic fallback message id when missing', async () => {
+    const result = await normalizeInboundGmailMessage({
+      rawMessage: buildMime({
+        from: 'eve@example.com',
+        to: 'bob@example.com',
+        subject: 'no id',
+        text: 'hi',
+      }),
+      gmailMessageId: 'gm-msg-7',
+      gmailThreadId: 'gm-thread-2',
+      accountIdentifier: 'bob@example.com',
+    })
+    expect(result.externalMessageId).toBe('gmail:gm-msg-7@bob@example.com')
+    expect(result.externalConversationId).toBe('gmail-thread:gm-thread-2')
+  })
+
+  it('prefers html body when html is present', async () => {
+    const result = await normalizeInboundGmailMessage({
+      rawMessage: buildMime({
+        messageId: '<html@example.com>',
+        from: 'alice@example.com',
+        to: 'bob@example.com',
+        subject: 'rich',
+        html: '<p><b>rich</b></p>',
+      }),
+      gmailMessageId: 'gm-msg-1',
+      gmailThreadId: 'gm-thread-1',
+      accountIdentifier: 'bob@example.com',
+    })
+    expect(result.bodyFormat).toBe('html')
+    expect(result.body).toContain('<b>rich</b>')
+  })
+
+  it('exposes Gmail ids via channelPayload for downstream widgets', async () => {
+    const result = await normalizeInboundGmailMessage({
+      rawMessage: buildMime({
+        messageId: '<msg@example.com>',
+        from: 'alice@example.com',
+        to: 'bob@example.com',
+        subject: 'subj',
+        text: 'hi',
+      }),
+      gmailMessageId: 'gm-msg-9',
+      gmailThreadId: 'gm-thread-9',
+      gmailLabelIds: ['INBOX'],
+      accountIdentifier: 'bob@example.com',
+    })
+    const payload = result.channelPayload as Record<string, unknown>
+    expect(payload.gmailMessageId).toBe('gm-msg-9')
+    expect(payload.gmailThreadId).toBe('gm-thread-9')
+    expect(payload.gmailLabelIds).toEqual(['INBOX'])
+  })
+})

package/src/modules/channel_gmail/lib/__tests__/oauth.test.ts

@@ -0,0 +1,148 @@
+import {
+  GMAIL_OAUTH_AUTHORIZE_URL,
+  GMAIL_OAUTH_TOKEN_URL,
+  GMAIL_OAUTH_USERINFO_URL,
+  getGoogleOAuthClient,
+  setGoogleOAuthClient,
+  tokenResponseToExpiresAt,
+} from '../oauth'
+
+afterEach(() => setGoogleOAuthClient(null))
+
+describe('buildAuthorizeUrl', () => {
+  it('builds a Google OAuth2 URL with all required params', () => {
+    const url = new URL(
+      getGoogleOAuthClient().buildAuthorizeUrl({
+        clientId: 'cid',
+        redirectUri: 'https://example.com/cb',
+        state: 'state-123',
+        scopes: ['https://www.googleapis.com/auth/gmail.modify'],
+      }),
+    )
+    expect(url.origin + url.pathname).toBe(GMAIL_OAUTH_AUTHORIZE_URL)
+    expect(url.searchParams.get('client_id')).toBe('cid')
+    expect(url.searchParams.get('redirect_uri')).toBe('https://example.com/cb')
+    expect(url.searchParams.get('response_type')).toBe('code')
+    expect(url.searchParams.get('state')).toBe('state-123')
+    expect(url.searchParams.get('access_type')).toBe('offline')
+    expect(url.searchParams.get('prompt')).toBe('consent')
+    expect(url.searchParams.get('include_granted_scopes')).toBe('true')
+    expect(url.searchParams.get('scope')).toBe('https://www.googleapis.com/auth/gmail.modify')
+  })
+
+  it('includes login_hint when provided', () => {
+    const url = new URL(
+      getGoogleOAuthClient().buildAuthorizeUrl({
+        clientId: 'cid',
+        redirectUri: 'https://example.com/cb',
+        state: 's',
+        scopes: ['scope'],
+        loginHint: 'alice@example.com',
+      }),
+    )
+    expect(url.searchParams.get('login_hint')).toBe('alice@example.com')
+  })
+
+  it('falls back to default scopes when scopes is empty', () => {
+    const url = new URL(
+      getGoogleOAuthClient().buildAuthorizeUrl({
+        clientId: 'cid',
+        redirectUri: 'https://example.com/cb',
+        state: 's',
+        scopes: [],
+      }),
+    )
+    expect(url.searchParams.get('scope')).toContain('gmail.modify')
+  })
+})
+
+describe('exchangeCode + refreshToken (transport-level)', () => {
+  const originalFetch = globalThis.fetch
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('POSTs form-encoded params and parses the token response', async () => {
+    const captured: { url?: string; body?: string; headers?: Record<string, string> } = {}
+    globalThis.fetch = ((url: string, init?: RequestInit) => {
+      captured.url = url
+      captured.body = typeof init?.body === 'string' ? init.body : ''
+      captured.headers = init?.headers as Record<string, string>
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        text: async () =>
+          JSON.stringify({
+            access_token: 'access',
+            refresh_token: 'refresh',
+            expires_in: 3600,
+            scope: 'https://www.googleapis.com/auth/gmail.modify',
+            token_type: 'Bearer',
+          }),
+      } as unknown as Response)
+    }) as unknown as typeof globalThis.fetch
+    const token = await getGoogleOAuthClient().exchangeCode({
+      clientId: 'cid',
+      clientSecret: 'secret',
+      redirectUri: 'https://example.com/cb',
+      code: 'code123',
+    })
+    expect(captured.url).toBe(GMAIL_OAUTH_TOKEN_URL)
+    expect(captured.body).toContain('grant_type=authorization_code')
+    expect(captured.body).toContain('code=code123')
+    expect(captured.body).toContain('client_id=cid')
+    expect(captured.body).toContain('client_secret=secret')
+    expect(token.access_token).toBe('access')
+    expect(token.refresh_token).toBe('refresh')
+  })
+
+  it('throws when token endpoint responds with error', async () => {
+    globalThis.fetch = (() =>
+      Promise.resolve({
+        ok: false,
+        status: 401,
+        statusText: 'Unauthorized',
+        text: async () => JSON.stringify({ error: 'invalid_grant', error_description: 'Token expired' }),
+      } as unknown as Response)) as unknown as typeof globalThis.fetch
+    await expect(
+      getGoogleOAuthClient().refreshToken({ clientId: 'c', clientSecret: 's', refreshToken: 'r' }),
+    ).rejects.toThrow(/Token expired|invalid_grant/i)
+  })
+})
+
+describe('fetchUserInfo', () => {
+  const originalFetch = globalThis.fetch
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+  it('GETs the userinfo endpoint with Bearer auth and parses the response', async () => {
+    const captured: { url?: string; headers?: Record<string, string> } = {}
+    globalThis.fetch = ((url: string, init?: RequestInit) => {
+      captured.url = url
+      captured.headers = init?.headers as Record<string, string>
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        json: async () => ({ sub: 'g-123', email: 'alice@gmail.com', name: 'Alice' }),
+      } as unknown as Response)
+    }) as unknown as typeof globalThis.fetch
+    const info = await getGoogleOAuthClient().fetchUserInfo('access')
+    expect(captured.url).toBe(GMAIL_OAUTH_USERINFO_URL)
+    expect(captured.headers?.Authorization).toBe('Bearer access')
+    expect(info.email).toBe('alice@gmail.com')
+  })
+})
+
+describe('tokenResponseToExpiresAt', () => {
+  it('returns the absolute expiry derived from expires_in seconds', () => {
+    const t = tokenResponseToExpiresAt({ access_token: 'x', expires_in: 60 }, 1_700_000_000_000)
+    expect(t).toBeInstanceOf(Date)
+    expect(t!.getTime()).toBe(1_700_000_060_000)
+  })
+
+  it('returns undefined when expires_in missing', () => {
+    expect(tokenResponseToExpiresAt({ access_token: 'x' })).toBeUndefined()
+  })
+})