Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
45.5 KB
Raw Blame
/**
 * google-clients — client-behavior tests against a scripted fetchImpl.
 *
 * Covers: 401 → single token refresh + retry, 429 Retry-After honoring,
 * 403 accessNotConfigured → CredentialError 'api_not_enabled' with the
 * project deep link, 404/410 → GoogleCursorExpiredError, drainPages
 * pagination, and the Gmail/Calendar/People client normalizations
 * (MIME body extraction, quote trimming, cap, sorting, syncToken vs window).
 *
 * Synthetic data only: example.com addresses, hex message ids. No real
 * network — every request routes through the scripted fetchImpl, and the
 * token refresh path is served by the same script (no live OAuth).
 */
import { describe, expect, test } from 'bun:test';

import { CredentialError } from '../src/core/creds/errors.ts';
import { GoogleTokenProvider } from '../src/core/creds/providers/google.ts';
import type {
  CredentialEntry,
  CredentialMeta,
  CredentialVault,
  ProviderClientRecord,
} from '../src/core/creds/vault.ts';
import {
  CalendarClient,
  CONTACT_PERSON_FIELDS,
  extractCalendarMethod,
  GmailClient,
  GoogleApiClient,
  GoogleCursorExpiredError,
  PeopleClient,
  rateLimitBackoffMs,
  type FetchImpl,
} from '../src/core/google/google-clients.ts';

// ── extractCalendarMethod (pure) ─────────────────────────────────────────────

describe('extractCalendarMethod', () => {
  // Gmail's MessagePart.mimeType is the BARE media type ('text/calendar');
  // the Content-Type parameters (method=, charset=) live on the part's own
  // headers[] (format=full). Fixtures mirror that real shape — two reviewers
  // confirmed the parameterized-mimeType fixture never occurs in production,
  // so a mimeType-only parser read '' for every real invite.
  const calendarPart = (contentType: string, mimeType = 'text/calendar') => ({
    partId: '1',
    mimeType,
    filename: 'invite.ics',
    headers: [
      { name: 'Content-Type', value: contentType },
      { name: 'Content-Transfer-Encoding', value: 'base64' },
    ],
    body: { size: 12, data: 'QkVHSU46VkNBTEVOREFS' },
  });

  test('real API shape: bare text/calendar mimeType + Content-Type header carrying method=REQUEST → REQUEST', () => {
    expect(
      extractCalendarMethod({
        mimeType: 'multipart/mixed',
        parts: [
          { mimeType: 'text/plain', body: { data: 'aGk=' } },
          calendarPart('text/calendar; charset="UTF-8"; method=REQUEST'),
        ],
      }),
    ).toBe('REQUEST');
  });

  test('quoted / lowercase methods normalize to the bare uppercase METHOD', () => {
    expect(
      extractCalendarMethod({ mimeType: 'multipart/mixed', parts: [calendarPart('text/calendar; method="reply"; charset=utf-8')] }),
    ).toBe('REPLY');
    expect(
      extractCalendarMethod({ mimeType: 'multipart/mixed', parts: [calendarPart('text/calendar; METHOD=cancel')] }),
    ).toBe('CANCEL');
  });

  test('a text/calendar part with no method= anywhere → "" (seen, but no METHOD)', () => {
    expect(
      extractCalendarMethod({ mimeType: 'multipart/mixed', parts: [calendarPart('text/calendar; charset="UTF-8"')] }),
    ).toBe('');
    // No headers at all on the part either.
    expect(
      extractCalendarMethod({ mimeType: 'multipart/mixed', parts: [{ mimeType: 'text/calendar', filename: 'invite.ics' }] }),
    ).toBe('');
  });

  test('fallback: a mimeType that still carries the Content-Type params parses too', () => {
    expect(
      extractCalendarMethod({
        mimeType: 'multipart/mixed',
        parts: [{ mimeType: 'text/calendar; charset="UTF-8"; method=REQUEST' }],
      }),
    ).toBe('REQUEST');
    // The header wins over the mimeType when both carry a method.
    expect(
      extractCalendarMethod({
        mimeType: 'multipart/mixed',
        parts: [calendarPart('text/calendar; method=REPLY', 'text/calendar; method=REQUEST')],
      }),
    ).toBe('REPLY');
  });

  test('bare .ics FILENAME with a non-calendar MIME type claims NOTHING (human attachment)', () => {
    // Pre-fix this returned '' and isCalendarSystemMail treated '' as system
    // mail, so a human email attaching an invite file could neither open nor
    // close loops.
    expect(
      extractCalendarMethod({
        mimeType: 'multipart/mixed',
        parts: [
          { mimeType: 'text/plain', body: { data: 'aGk=' } },
          { mimeType: 'application/octet-stream', filename: 'team-sync.ics' },
        ],
      }),
    ).toBeNull();
  });

  test('a real text/calendar part elsewhere in the tree still wins over an .ics filename', () => {
    expect(
      extractCalendarMethod({
        mimeType: 'multipart/mixed',
        parts: [
          { mimeType: 'application/octet-stream', filename: 'invite.ics' },
          {
            mimeType: 'multipart/alternative',
            parts: [
              { mimeType: 'text/html', body: { data: 'PHA+aGk8L3A+' } },
              calendarPart('text/calendar; charset="UTF-8"; method=CANCEL'),
            ],
          },
        ],
      }),
    ).toBe('CANCEL');
  });

  test('no calendar part at all → null', () => {
    expect(extractCalendarMethod({ mimeType: 'text/plain' })).toBeNull();
    expect(extractCalendarMethod(undefined)).toBeNull();
  });
});

// ── In-memory vault (no filesystem, no token-refresh HTTP unless scripted) ──

class FakeVault implements CredentialVault {
  entries = new Map<string, CredentialEntry>();
  clients = new Map<string, ProviderClientRecord>();
  async get(id: string): Promise<CredentialEntry | null> {
    return this.entries.get(id) ?? null;
  }
  async put(entry: CredentialEntry): Promise<void> {
    this.entries.set(entry.id, entry);
  }
  async list(): Promise<CredentialMeta[]> {
    return [];
  }
  async delete(id: string): Promise<boolean> {
    return this.entries.delete(id);
  }
  async getClient(provider: string): Promise<ProviderClientRecord | null> {
    return this.clients.get(provider) ?? null;
  }
  async putClient(rec: ProviderClientRecord): Promise<void> {
    this.clients.set(rec.provider, rec);
  }
  async deleteClient(provider: string): Promise<boolean> {
    return this.clients.delete(provider);
  }
}

const CLIENT_ID = '123-abc.apps.googleusercontent.com';

function makeEntry(): CredentialEntry {
  return {
    id: 'google:[email protected]',
    provider: 'google',
    kind: 'oauth2',
    client_ref: 'byo',
    secret: {
      access_token: 't',
      refresh_token: 'r',
      expiry: new Date(Date.now() + 3_600_000).toISOString(),
    },
    meta: {
      account: '[email protected]',
      sendas_aliases: ['[email protected]'],
      connected_at: new Date().toISOString(),
      client_id: CLIENT_ID,
    },
  };
}

function json(body: unknown, status = 200, headers: Record<string, string> = {}): Response {
  return new Response(JSON.stringify(body), {
    status,
    headers: { 'content-type': 'application/json', ...headers },
  });
}

interface Harness {
  vault: FakeVault;
  tokens: GoogleTokenProvider;
  fetchImpl: FetchImpl;
  calls: Array<{ url: string; auth: string | null }>;
  tokenPosts: () => number;
}

/** Every non-token request goes to `handler`; the token endpoint mints 't2'. */
function makeHarness(handler: (u: URL, init?: RequestInit) => Response | Promise<Response>): Harness {
  const vault = new FakeVault();
  vault.entries.set('google:[email protected]', makeEntry());
  vault.clients.set('google', {
    provider: 'google',
    client_id: CLIENT_ID,
    client_secret: 'GOCSPX-test-secret-0000',
    created_at: new Date().toISOString(),
  });
  const calls: Array<{ url: string; auth: string | null }> = [];
  let tokenPosts = 0;
  const fetchImpl: FetchImpl = async (url, init) => {
    const u = new URL(url);
    if (u.hostname === 'oauth2.googleapis.com') {
      tokenPosts++;
      return json({ access_token: 't2', expires_in: 3600 });
    }
    const headers = new Headers((init?.headers ?? {}) as HeadersInit);
    calls.push({ url, auth: headers.get('authorization') });
    return handler(u, init);
  };
  const tokens = new GoogleTokenProvider(vault, 'google:[email protected]', fetchImpl);
  return { vault, tokens, fetchImpl, calls, tokenPosts: () => tokenPosts };
}

function b64url(s: string): string {
  return Buffer.from(s, 'utf-8').toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

// ── rateLimitBackoffMs (pure) ────────────────────────────────────────────────

describe('rateLimitBackoffMs', () => {
  test('stays within [half, base] of the exponential-backoff schedule and never exceeds the 60s cap', () => {
    // attempt 0: base=2000, half=1000 → [1000, 2000]
    // attempt 4: base=32000, half=16000 → [16000, 32000]
    // attempt 10: base would exceed the cap, so base clamps to 60000 → [30000, 60000]
    for (const [attempt, [lo, hi]] of [
      [0, [1000, 2000]],
      [4, [16000, 32000]],
      [10, [30000, 60000]],
    ] as const) {
      for (let i = 0; i < 20; i++) {
        const ms = rateLimitBackoffMs(attempt);
        expect(ms).toBeGreaterThanOrEqual(lo);
        expect(ms).toBeLessThanOrEqual(hi);
      }
    }
  });
});

// ── GoogleApiClient core: auth, retry, error mapping ─────────────────────────

describe('GoogleApiClient request core', () => {
  test('401 then success: refreshes the token exactly once and retries', async () => {
    let apiCalls = 0;
    const h = makeHarness(() => {
      apiCalls++;
      if (apiCalls === 1) return json({ error: { code: 401, message: 'Invalid Credentials' } }, 401);
      return json({ emailAddress: '[email protected]', historyId: '77' });
    });
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const profile = await gmail.getProfile();
    expect(profile.emailAddress).toBe('[email protected]');
    expect(profile.historyId).toBe('77');
    expect(apiCalls).toBe(2);
    expect(h.tokenPosts()).toBe(1); // exactly one forceRefresh
    expect(h.calls[0].auth).toBe('Bearer t');
    expect(h.calls[1].auth).toBe('Bearer t2'); // retried with the refreshed token
    // The fake vault recorded the refresh.
    const entry = await h.vault.get('google:[email protected]');
    expect(entry?.secret.access_token).toBe('t2');
    expect(entry?.meta.last_refresh_ok_at).toBeDefined();
  });

  test('429 with Retry-After: 0 is retried', async () => {
    let apiCalls = 0;
    const h = makeHarness(() => {
      apiCalls++;
      if (apiCalls === 1) return json({ error: { message: 'rate limit' } }, 429, { 'retry-after': '0' });
      return json({ emailAddress: '[email protected]', historyId: '88' });
    });
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const profile = await gmail.getProfile();
    expect(profile.historyId).toBe('88');
    expect(apiCalls).toBe(2);
    expect(h.tokenPosts()).toBe(0); // no refresh on a rate limit
  });

  test('429 with NO Retry-After falls back to the jittered backoff: logs a delay inside the attempt-0 bounds, sleeps, retries once', async () => {
    let apiCalls = 0;
    const h = makeHarness(() => {
      apiCalls++;
      if (apiCalls === 1) return json({ error: { message: 'rate limit' } }, 429); // no retry-after header
      return json({ ok: true });
    });
    const logs: string[] = [];
    const client = new GoogleApiClient(h.tokens, h.fetchImpl, (m) => logs.push(m));
    const t0 = Date.now();
    const body = await client.fetchJSON<{ ok: boolean }>('https://gmail.googleapis.com/gmail/v1/fake', 'gmail', {
      rateLimitRetries: 1,
    });
    const elapsedMs = Date.now() - t0;
    expect(body.ok).toBe(true);
    expect(apiCalls).toBe(2); // exactly one retry
    expect(h.tokenPosts()).toBe(0);
    // rateLimitBackoffMs(0) ∈ [1000, 2000] → the log's rounded delay is 1s or 2s, never 0s.
    const line = logs.find((l) => l.startsWith('[google] HTTP 429; retrying in '));
    expect(line).toBeDefined();
    expect(line).toContain('(rate limit, attempt 1/1)');
    const secs = Number(/retrying in (\d+)s/.exec(line ?? '')?.[1]);
    expect(secs).toBeGreaterThanOrEqual(1);
    expect(secs).toBeLessThanOrEqual(2);
    // The jittered sleep really ran (not a fixed 0 delay): at least the lower bound, minus timer slack.
    expect(elapsedMs).toBeGreaterThanOrEqual(950);
  });

  test('403 accessNotConfigured maps to api_not_enabled with the project deep link', async () => {
    const h = makeHarness(() =>
      json(
        {
          error: {
            code: 403,
            status: 'PERMISSION_DENIED',
            message: 'Gmail API has not been used in project 123 before or it is disabled.',
            errors: [{ reason: 'accessNotConfigured' }],
          },
        },
        403,
      ),
    );
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    let thrown: unknown;
    try {
      await gmail.getProfile();
    } catch (e) {
      thrown = e;
    }
    expect(thrown).toBeInstanceOf(CredentialError);
    const err = thrown as CredentialError;
    expect(err.code).toBe('api_not_enabled');
    expect(err.message).toContain('gmail.googleapis.com');
    expect(err.message).toContain('?project=123'); // project number from the client id
  });

  test('404 on history.list surfaces GoogleCursorExpiredError', async () => {
    const h = makeHarness(() => json({ error: { code: 404, message: 'not found' } }, 404));
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    let thrown: unknown;
    try {
      await gmail.listHistoryThreadIds('999');
    } catch (e) {
      thrown = e;
    }
    expect(thrown).toBeInstanceOf(GoogleCursorExpiredError);
    expect((thrown as GoogleCursorExpiredError).status).toBe(404);
  });

  test('drainPages follows nextPageToken and concatenates in order', async () => {
    const h = makeHarness((u) => {
      const t = u.searchParams.get('pageToken');
      if (!t) return json({ items: ['a1', 'a2'], nextPageToken: 'p2' });
      if (t === 'p2') return json({ items: ['b1'], nextPageToken: 'p3' });
      return json({ items: ['c1'] });
    });
    const client = new GoogleApiClient(h.tokens, h.fetchImpl);
    const items = await client.drainPages<string>(
      (t) => `https://gmail.googleapis.com/gmail/v1/fake?x=1${t ? `&pageToken=${t}` : ''}`,
      (body) => ({
        items: (body.items as string[] | undefined) ?? [],
        nextPageToken: (body.nextPageToken as string | undefined) ?? null,
      }),
      'gmail',
    );
    expect(items).toEqual(['a1', 'a2', 'b1', 'c1']);
    expect(h.calls.length).toBe(3);
  });

  test('drainPages throws when the page cap is hit', async () => {
    const h = makeHarness(() => json({ items: ['x'], nextPageToken: 'again' }));
    const client = new GoogleApiClient(h.tokens, h.fetchImpl);
    await expect(
      client.drainPages<string>(
        (t) => `https://gmail.googleapis.com/gmail/v1/fake${t ? `?pageToken=${t}` : ''}`,
        (body) => ({
          items: (body.items as string[] | undefined) ?? [],
          nextPageToken: (body.nextPageToken as string | undefined) ?? null,
        }),
        'gmail',
        { maxPages: 2 },
      ),
    ).rejects.toThrow(/pagination cap/);
  });
});

describe('GoogleApiClient retry exhaustion + 403 mapping', () => {
  test("always-429 (Retry-After: 0) exhausts the RATE-LIMIT retry budget (bigger than the plain retry budget) and maps to 'rate_limited'", async () => {
    let apiCalls = 0;
    const h = makeHarness(() => {
      apiCalls++;
      return json({ error: { message: 'rate limit' } }, 429, { 'retry-after': '0' });
    });
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    let thrown: unknown;
    try {
      await gmail.getProfile();
    } catch (e) {
      thrown = e;
    }
    expect(thrown).toBeInstanceOf(CredentialError);
    expect((thrown as CredentialError).code).toBe('rate_limited');
    // Default rate-limit retries=6 (bigger than the plain retries=2 used for
    // 401): attempts 0-5 are retried, attempt 6 throws. This is deliberately
    // MORE patient than a plain retryable failure — the whole point of this
    // fix (a 403/429 used to give up after 3 calls and poison the thread).
    expect(apiCalls).toBe(7);
    expect(h.tokenPosts()).toBe(0); // a rate limit never triggers a token refresh
  });

  test('always-429 (Retry-After: 0) honors an explicit smaller rateLimitRetries override', async () => {
    let apiCalls = 0;
    const h = makeHarness(() => {
      apiCalls++;
      return json({ error: { message: 'rate limit' } }, 429, { 'retry-after': '0' });
    });
    const client = new GoogleApiClient(h.tokens, h.fetchImpl);
    let thrown: unknown;
    try {
      await client.fetchJSON('https://gmail.googleapis.com/gmail/v1/fake', 'gmail', {
        rateLimitRetries: 1,
      });
    } catch (e) {
      thrown = e;
    }
    expect(thrown).toBeInstanceOf(CredentialError);
    expect((thrown as CredentialError).code).toBe('rate_limited');
    expect(apiCalls).toBe(2); // attempt 0 retried, attempt 1 throws
  });

  test('a 403 quota reason gets the same patient rate-limit retry budget as 429', async () => {
    let apiCalls = 0;
    const h = makeHarness(() => {
      apiCalls++;
      return json(
        { error: { code: 403, message: 'Quota exceeded', errors: [{ reason: 'quotaExceeded' }] } },
        403,
        { 'retry-after': '0' },
      );
    });
    const client = new GoogleApiClient(h.tokens, h.fetchImpl);
    let thrown: unknown;
    try {
      await client.fetchJSON('https://gmail.googleapis.com/gmail/v1/fake', 'gmail');
    } catch (e) {
      thrown = e;
    }
    expect((thrown as CredentialError).code).toBe('rate_limited');
    expect(apiCalls).toBe(7);
  });

  test('a 401 still exhausts at its OWN (unchanged, smaller) retry budget even though the rate-limit budget is larger', async () => {
    let apiCalls = 0;
    const h = makeHarness(() => {
      apiCalls++;
      return json({ error: { code: 401, message: 'Invalid Credentials' } }, 401);
    });
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    let thrown: unknown;
    try {
      await gmail.getProfile();
    } catch (e) {
      thrown = e;
    }
    expect(thrown).toBeInstanceOf(CredentialError);
    expect((thrown as CredentialError).code).toBe('upstream');
    // Default retries=2 for 401 (unaffected by the bigger rate-limit budget):
    // attempts 0 and 1 retried (with a forceRefresh each), attempt 2 throws.
    expect(apiCalls).toBe(3);
    expect(h.tokenPosts()).toBe(2);
  });

  test("403 with a non-rate, non-quota reason maps to 'upstream' WITHOUT a retry", async () => {
    let apiCalls = 0;
    const h = makeHarness(() => {
      apiCalls++;
      return json(
        {
          error: {
            code: 403,
            status: 'PERMISSION_DENIED',
            message: 'Access blocked by admin policy.',
            errors: [{ reason: 'domainPolicy' }],
          },
        },
        403,
      );
    });
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    let thrown: unknown;
    try {
      await gmail.getProfile();
    } catch (e) {
      thrown = e;
    }
    expect(thrown).toBeInstanceOf(CredentialError);
    expect((thrown as CredentialError).code).toBe('upstream');
    expect((thrown as CredentialError).message).toContain('domainPolicy');
    expect(apiCalls).toBe(1); // fail-fast: no retry loop for a hard 403
    expect(h.tokenPosts()).toBe(0);
  });

  test('drainPages partialOk: returns the partial batch at maxPages instead of throwing', async () => {
    const h = makeHarness(() => json({ items: ['x'], nextPageToken: 'again' }));
    const client = new GoogleApiClient(h.tokens, h.fetchImpl);
    const build = (t: string | null): string =>
      `https://gmail.googleapis.com/gmail/v1/fake${t ? `?pageToken=${t}` : ''}`;
    const pick = (body: Record<string, unknown>) => ({
      items: (body.items as string[] | undefined) ?? [],
      nextPageToken: (body.nextPageToken as string | undefined) ?? null,
    });
    const partial = await client.drainPages<string>(build, pick, 'gmail', {
      maxPages: 2,
      partialOk: true,
    });
    // One item per page, two pages drained — the truncated batch comes back.
    expect(partial).toEqual(['x', 'x']);
    // Contrast: the SAME shape without partialOk still throws (reconciling
    // callers must never treat a truncated listing as complete).
    await expect(
      client.drainPages<string>(build, pick, 'gmail', { maxPages: 2 }),
    ).rejects.toThrow(/pagination cap/);
  });
});

// ── GmailClient ──────────────────────────────────────────────────────────────

describe('GmailClient', () => {
  test('listMessageIds passes q through and drains pages', async () => {
    const seenQ: Array<string | null> = [];
    const h = makeHarness((u) => {
      seenQ.push(u.searchParams.get('q'));
      const t = u.searchParams.get('pageToken');
      if (!t) {
        return json({
          messages: [{ id: '18c2f4a9b3d21e01', threadId: '17aa1111bbbb2222' }],
          nextPageToken: 'p2',
        });
      }
      return json({ messages: [{ id: '18c2f4a9b3d21e02', threadId: '17aa3333cccc4444' }] });
    });
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const ids = await gmail.listMessageIds('after:123 before:456');
    expect(ids).toEqual([
      { id: '18c2f4a9b3d21e01', threadId: '17aa1111bbbb2222' },
      { id: '18c2f4a9b3d21e02', threadId: '17aa3333cccc4444' },
    ]);
    expect(seenQ).toEqual(['after:123 before:456', 'after:123 before:456']);
  });

  test('listHistoryThreadIds dedupes thread ids across record kinds and returns the new cursor', async () => {
    const h = makeHarness(() =>
      json({
        historyId: '1010',
        history: [
          { messages: [{ threadId: '17aa1111bbbb2222' }] },
          { messagesAdded: [{ message: { threadId: '17aa1111bbbb2222' } }] },
          { labelsAdded: [{ message: { threadId: '17aa3333cccc4444' } }] },
        ],
      }),
    );
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const { threadIds, newHistoryId } = await gmail.listHistoryThreadIds('1000');
    expect(threadIds.sort()).toEqual(['17aa1111bbbb2222', '17aa3333cccc4444']);
    expect(newHistoryId).toBe('1010');
  });

  test('getThread: plain preferred, html stripped, quotes trimmed, oldest-first, listUnsubscribe', async () => {
    const rawThread = {
      id: '17aa1111bbbb2222',
      messages: [
        {
          // Newest served FIRST to prove the client sorts oldest-first.
          id: '18c2f4a9b3d21e03',
          threadId: '17aa1111bbbb2222',
          labelIds: ['SENT'],
          internalDate: String(Date.parse('2026-08-12T10:00:00Z')),
          payload: {
            mimeType: 'multipart/alternative',
            headers: [
              { name: 'From', value: 'A Example <[email protected]>' },
              { name: 'To', value: '[email protected]' },
              { name: 'Subject', value: 'Re: Zephyr roadmap' },
            ],
            parts: [
              {
                mimeType: 'text/plain',
                body: { data: b64url('Sounds good.\n\nOn Mon, Aug 10, 2026 Charlie Example wrote:\n> earlier\n> more') },
              },
            ],
          },
        },
        {
          id: '18c2f4a9b3d21e01',
          threadId: '17aa1111bbbb2222',
          labelIds: [],
          internalDate: String(Date.parse('2026-08-10T09:00:00Z')),
          payload: {
            mimeType: 'multipart/alternative',
            headers: [
              { name: 'From', value: 'Charlie Example <[email protected]>' },
              { name: 'To', value: '[email protected]' },
              { name: 'Cc', value: '[email protected]' },
              { name: 'Subject', value: 'Zephyr roadmap' },
              { name: 'List-Unsubscribe', value: '<mailto:[email protected]>' },
            ],
            parts: [
              { mimeType: 'text/plain', body: { data: b64url('plain body wins') } },
              { mimeType: 'text/html', body: { data: b64url('<p>html body loses</p>') } },
            ],
          },
        },
        {
          id: '18c2f4a9b3d21e02',
          threadId: '17aa1111bbbb2222',
          labelIds: [],
          internalDate: String(Date.parse('2026-08-11T09:00:00Z')),
          payload: {
            mimeType: 'text/html',
            headers: [
              { name: 'From', value: 'Dana Example <[email protected]>' },
              { name: 'To', value: '[email protected]' },
              { name: 'Subject', value: 'Re: Zephyr roadmap' },
            ],
            body: { data: b64url('<div>Hello &amp; <b>welcome</b></div><br><div>Second line</div>') },
          },
        },
      ],
    };
    const h = makeHarness(() => json(rawThread));
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const thread = await gmail.getThread('17aa1111bbbb2222', '[email protected]');

    expect(thread.threadId).toBe('17aa1111bbbb2222');
    expect(thread.account).toBe('[email protected]');
    // Sorted oldest-first regardless of the served order.
    expect(thread.messages.map((m) => m.id)).toEqual([
      '18c2f4a9b3d21e01',
      '18c2f4a9b3d21e02',
      '18c2f4a9b3d21e03',
    ]);

    const [first, second, third] = thread.messages;
    // text/plain preferred over text/html.
    expect(first.bodyText).toBe('plain body wins');
    expect(first.listUnsubscribe).toBe(true);
    expect(first.fromAddress).toBe('[email protected]');
    expect(first.to).toEqual(['[email protected]']);
    expect(first.cc).toEqual(['[email protected]']);
    // html fallback stripped to text.
    expect(second.bodyText).toBe('Hello & welcome\n\nSecond line');
    expect(second.listUnsubscribe).toBe(false);
    // quoted tail trimmed.
    expect(third.bodyText).toBe('Sounds good.');
    expect(third.labelIds).toEqual(['SENT']);
  });

  test('#5586: getThread stamps RFC 3834 Auto-Submitted: any keyword but "no", case-insensitive, parameters and comments ignored', async () => {
    const cases: Array<[string | null, boolean]> = [
      ['auto-generated', true], ['Auto-Replied', true], [' AUTO-NOTIFIED ; owner-email="[email protected]"', true],
      ['auto-generated (tracker)', true], ['x-custom-robot', true],
      ['no', false], ['No', false], [' no ; reason=human', false], ['no (sent by a person)', false], ['', false], [null, false],
    ];
    const rawThread = {
      id: '17aa9999ffff0000',
      messages: cases.map(([value], i) => ({
        id: `18c2f4a9b3d21f${String(i).padStart(2, '0')}`,
        threadId: '17aa9999ffff0000',
        labelIds: [],
        internalDate: String(Date.parse('2026-08-10T09:00:00Z') + i * 60_000),
        payload: {
          mimeType: 'text/plain',
          headers: [
            { name: 'From', value: 'Tracker <[email protected]>' },
            { name: 'To', value: '[email protected]' },
            { name: 'Subject', value: `Issue #${i}` },
            ...(value === null ? [] : [{ name: i % 2 ? 'auto-submitted' : 'Auto-Submitted', value }]),
          ],
          body: { data: b64url('Status changed.') },
        },
      })),
    };
    const h = makeHarness(() => json(rawThread));
    const thread = await new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID).getThread('17aa9999ffff0000', '[email protected]');
    expect(thread.messages.map((m) => m.autoSubmitted)).toEqual(cases.map(([, expected]) => expected));
  });

  test('#5012: getThread captures Precedence, List-Id and Reply-To; absent headers read as human mail', async () => {
    const headerSets: Array<Array<{ name: string; value: string }>> = [
      [{ name: 'Precedence', value: ' Bulk ' }],
      [{ name: 'list-id', value: 'Team updates <updates.example.com>' }],
      [{ name: 'Reply-To', value: 'Alerts <[email protected]>, [email protected]' }],
      [],
    ];
    const rawThread = {
      id: '17aa5555dddd0000',
      messages: headerSets.map((extra, i) => ({
        id: `18c2f4a9b3d21a${String(i).padStart(2, '0')}`,
        threadId: '17aa5555dddd0000',
        labelIds: [],
        internalDate: String(Date.parse('2026-08-10T09:00:00Z') + i * 60_000),
        payload: {
          mimeType: 'text/plain',
          headers: [
            { name: 'From', value: 'Sender <[email protected]>' },
            { name: 'To', value: '[email protected]' },
            { name: 'Subject', value: `Notice ${i}` },
            ...extra,
          ],
          body: { data: b64url('Your statement is ready.') },
        },
      })),
    };
    const h = makeHarness(() => json(rawThread));
    const thread = await new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID).getThread('17aa5555dddd0000', '[email protected]');
    const [bulk, list, replyTo, human] = thread.messages as unknown as Array<Record<string, unknown>>;
    expect(bulk.precedence).toBe('bulk');
    expect(list.listId).toBe(true);
    expect(replyTo.replyTo).toEqual(['[email protected]', '[email protected]']);
    expect([human.precedence, human.listId, human.replyTo]).toEqual(['', false, []]);
  });

  test('getThread stamps calendarMethod from a real-shape text/calendar part; plain messages get null', async () => {
    const rawThread = {
      id: '17aa7777eeee8888',
      messages: [
        {
          id: '18c2f4a9b3d21e10',
          threadId: '17aa7777eeee8888',
          labelIds: [],
          internalDate: String(Date.parse('2026-08-10T09:00:00Z')),
          payload: {
            mimeType: 'multipart/mixed',
            headers: [
              { name: 'From', value: 'Charlie Example <[email protected]>' },
              { name: 'To', value: '[email protected]' },
              { name: 'Subject', value: 'Invitation: Team sync @ Fri Aug 21, 2026 1pm' },
            ],
            parts: [
              {
                mimeType: 'multipart/alternative',
                parts: [
                  { mimeType: 'text/plain', body: { data: b64url('You have been invited.') } },
                  {
                    // Real Gmail shape: bare media type, params on the part headers.
                    partId: '0.1',
                    mimeType: 'text/calendar',
                    filename: 'invite.ics',
                    headers: [{ name: 'Content-Type', value: 'text/calendar; charset="UTF-8"; method=REQUEST' }],
                    body: { data: b64url('BEGIN:VCALENDAR') },
                  },
                ],
              },
            ],
          },
        },
        {
          id: '18c2f4a9b3d21e11',
          threadId: '17aa7777eeee8888',
          labelIds: [],
          internalDate: String(Date.parse('2026-08-10T10:00:00Z')),
          payload: {
            mimeType: 'text/plain',
            headers: [
              { name: 'From', value: 'Dana Example <[email protected]>' },
              { name: 'To', value: '[email protected]' },
              { name: 'Subject', value: 'Re: Team sync' },
            ],
            body: { data: b64url('Can we move it to 2pm?') },
          },
        },
      ],
    };
    const h = makeHarness(() => json(rawThread));
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const thread = await gmail.getThread('17aa7777eeee8888', '[email protected]');
    const [invite, plain] = thread.messages;
    expect(invite.calendarMethod).toBe('REQUEST');
    expect(invite.bodyText).toBe('You have been invited.');
    expect(plain.calendarMethod).toBeNull();
  });

  test('getThread caps bodies at 8KB with a [truncated] marker', async () => {
    const rawThread = {
      id: '17aa5555dddd6666',
      messages: [
        {
          id: '18c2f4a9b3d21e04',
          threadId: '17aa5555dddd6666',
          labelIds: [],
          internalDate: String(Date.parse('2026-08-10T09:00:00Z')),
          payload: {
            mimeType: 'text/plain',
            headers: [
              { name: 'From', value: 'Charlie Example <[email protected]>' },
              { name: 'To', value: '[email protected]' },
              { name: 'Subject', value: 'Big body' },
            ],
            body: { data: b64url('x'.repeat(9_000)) },
          },
        },
      ],
    };
    const h = makeHarness(() => json(rawThread));
    const gmail = new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const thread = await gmail.getThread('17aa5555dddd6666', '[email protected]');
    const body = thread.messages[0].bodyText;
    expect(body.endsWith('[truncated]')).toBe(true);
    expect(body.length).toBe(8_000 + '\n[truncated]'.length);
  });

  // #5752: a cap that cuts a UTF-16 code unit leaves a lone surrogate, which
  // Postgres rejects inside the managed request intent's jsonb.
  const emojiThread = (mimeType: string, text: string) => ({
    id: '17aa5555dddd7777',
    messages: [{
      id: '18c2f4a9b3d21e05', threadId: '17aa5555dddd7777', labelIds: [], internalDate: String(Date.parse('2026-08-10T09:00:00Z')),
      payload: { mimeType, headers: [{ name: 'From', value: 'Charlie Example <[email protected]>' }, { name: 'Subject', value: 'Emoji' }],
        body: { data: b64url(text) } },
    }],
  });
  test('the 8KB body cap never splits a surrogate pair (#5752)', async () => {
    const h = makeHarness(() => json(emojiThread('text/plain', 'x'.repeat(7_999) + '\u{1F600}' + 'y'.repeat(50))));
    const body = (await new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID).getThread('17aa5555dddd7777', '[email protected]')).messages[0].bodyText;
    expect(body.endsWith('[truncated]')).toBe(true);
    expect(body.isWellFormed()).toBe(true);
    expect(body.startsWith('x'.repeat(7_999))).toBe(true);
  });
  test('the HTML pre-truncation never splits a surrogate pair (#5752)', async () => {
    const markup = '<b></b>'.repeat(Math.floor(127_999 / 7));
    const html = markup + 'z'.repeat(127_999 - markup.length) + '\u{1F600}' + 'tail';
    const h = makeHarness(() => json(emojiThread('text/html', html)));
    const body = (await new GmailClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID).getThread('17aa5555dddd7777', '[email protected]')).messages[0].bodyText;
    expect(body.isWellFormed()).toBe(true);
  });
});

// ── CalendarClient ───────────────────────────────────────────────────────────

const RAW_EVENTS = [
  {
    id: 'evt0000000000001',
    status: 'confirmed',
    summary: 'Zephyr planning',
    description: '<b>Agenda</b>',
    start: { dateTime: '2026-08-12T17:00:00Z' },
    end: { dateTime: '2026-08-12T18:00:00Z' },
    organizer: { email: '[email protected]' },
    attendees: [
      { email: '[email protected]', self: true, responseStatus: 'accepted' },
      { email: '[email protected]', displayName: 'Charlie Example' },
    ],
    location: 'HQ',
    hangoutLink: 'https://meet.google.com/aaa-bbbb-ccc',
    htmlLink: 'https://calendar.google.com/calendar/event?eid=evt0000000000001',
  },
  { id: 'evt0000000000002', status: 'cancelled', start: { date: '2026-08-13' }, end: { date: '2026-08-14' } },
];

describe('CalendarClient', () => {
  test('windowed listing sends timeMin/timeMax and normalizes events', async () => {
    const h = makeHarness((u) => {
      expect(u.searchParams.get('syncToken')).toBeNull();
      return json({ items: RAW_EVENTS, nextSyncToken: 'cal-1' });
    });
    const cal = new CalendarClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const { events, nextSyncToken } = await cal.listEvents('[email protected]', {
      timeMinIso: '2026-05-01T00:00:00.000Z',
      timeMaxIso: '2026-10-01T00:00:00.000Z',
    });
    expect(nextSyncToken).toBe('cal-1');
    expect(h.calls[0].url).toContain('timeMin=');
    expect(h.calls[0].url).toContain('timeMax=');
    expect(h.calls[0].url).toContain('singleEvents=true');

    expect(events.length).toBe(2);
    const [timed, allDay] = events;
    expect(timed.summary).toBe('Zephyr planning');
    expect(timed.organizer).toBe('[email protected]'); // lowercased
    expect(timed.attendees[0]).toEqual({ email: '[email protected]', displayName: null, self: true, responseStatus: 'accepted' });
    expect(timed.attendees[1].displayName).toBe('Charlie Example');
    expect(timed.allDay).toBe(false);
    expect(timed.account).toBe('[email protected]');
    expect(allDay.allDay).toBe(true);
    expect(allDay.startIso).toBe('2026-08-13T00:00:00Z');
    expect(allDay.summary).toBe('(no title)');
    expect(allDay.status).toBe('cancelled');
  });

  test('syncToken listing sends syncToken instead of the window', async () => {
    const h = makeHarness((u) => {
      expect(u.searchParams.get('syncToken')).toBe('cal-1');
      expect(u.searchParams.get('timeMin')).toBeNull();
      return json({ items: [], nextSyncToken: 'cal-2' });
    });
    const cal = new CalendarClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const { events, nextSyncToken } = await cal.listEvents('[email protected]', { syncToken: 'cal-1' });
    expect(events).toEqual([]);
    expect(nextSyncToken).toBe('cal-2');
  });

  test('410 on an expired syncToken surfaces GoogleCursorExpiredError', async () => {
    const h = makeHarness(() => json({ error: { code: 410, message: 'Sync token is no longer valid' } }, 410));
    const cal = new CalendarClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    let thrown: unknown;
    try {
      await cal.listEvents('[email protected]', { syncToken: 'stale' });
    } catch (e) {
      thrown = e;
    }
    expect(thrown).toBeInstanceOf(GoogleCursorExpiredError);
    expect((thrown as GoogleCursorExpiredError).status).toBe(410);
  });

  test('defaults to the primary calendar when no calendarId is given', async () => {
    const h = makeHarness(() => json({ items: [], nextSyncToken: 'cal-1' }));
    const cal = new CalendarClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    await cal.listEvents('[email protected]', { timeMinIso: '2026-05-01T00:00:00.000Z' });
    expect(h.calls[0].url).toContain('/calendars/primary/events');
  });

  test('a secondary calendar id is URL-encoded into the path, not the query', async () => {
    const h = makeHarness(() => json({ items: [], nextSyncToken: 'cal-1' }));
    const cal = new CalendarClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    await cal.listEvents('[email protected]', {
      calendarId: '[email protected]',
      timeMinIso: '2026-05-01T00:00:00.000Z',
    });
    // '@' must be percent-encoded so the id cannot be read as URL userinfo.
    expect(h.calls[0].url).toContain(
      '/calendars/family0123456789%40group.calendar.google.com/events',
    );
    expect(h.calls[0].url).not.toContain('/calendars/primary/');
    // calendarId must not disturb the window params.
    expect(new URL(h.calls[0].url).searchParams.get('timeMin')).toBe('2026-05-01T00:00:00.000Z');
  });

  test('an empty/whitespace calendarId falls back to primary', async () => {
    const h = makeHarness(() => json({ items: [], nextSyncToken: 'cal-1' }));
    const cal = new CalendarClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    await cal.listEvents('[email protected]', { calendarId: '   ', syncToken: 'cal-1' });
    expect(h.calls[0].url).toContain('/calendars/primary/events');
  });

  test('listCalendars normalizes calendarList and flags the primary', async () => {
    const h = makeHarness((u) => {
      expect(u.pathname).toContain('/users/me/calendarList');
      return json({
        items: [
          { id: '[email protected]', summary: 'A Example', primary: true, accessRole: 'owner' },
          {
            id: '[email protected]',
            summary: 'Family',
            accessRole: 'owner',
          },
          { summary: 'dropped — no id', accessRole: 'reader' },
          { id: '[email protected]', accessRole: 'reader' },
        ],
      });
    });
    const cal = new CalendarClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const cals = await cal.listCalendars();
    // The id-less row is dropped — it cannot be passed to --calendar-id.
    expect(cals.length).toBe(3);
    expect(cals[0]).toEqual({
      id: '[email protected]',
      summary: 'A Example',
      primary: true,
      accessRole: 'owner',
    });
    expect(cals[1].primary).toBe(false);
    expect(cals[2].summary).toBe('(no name)');
  });
});

// ── PeopleClient ─────────────────────────────────────────────────────────────

describe('PeopleClient', () => {
  test.each([null, {}, [null], ['invalid'], []])('malformed expiry details preserve typed errors: %j', async details => {
    for (const expired of [true, false]) {
      const h = makeHarness(() => json({ error: {
        code: 400,
        message: expired ? 'Sync token is expired.' : 'Invalid personFields',
        details,
      } }, 400));
      const people = new PeopleClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
      await expect(people.listConnections({ syncToken: 'stale' })).rejects.toBeInstanceOf(
        expired ? GoogleCursorExpiredError : CredentialError,
      );
    }
  });

  test.each([
    { message: 'Sync token is expired. Clear local cache and retry call without the sync token.' },
    { details: [{ '@type': 'type.googleapis.com/google.rpc.ErrorInfo', reason: 'EXPIRED_SYNC_TOKEN' }] },
  ])('HTTP 400 expired sync tokens surface cursor expiry: %j', async error => {
    const h = makeHarness(() => json({ error: { code: 400, ...error } }, 400));
    const people = new PeopleClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    await expect(people.listConnections({ syncToken: 'stale' })).rejects.toBeInstanceOf(GoogleCursorExpiredError);
  });

  test.each([
    ['people', 'https://people.googleapis.com/v1/people/me/connections?syncToken=stale', { message: 'Invalid personFields' }],
    ['people', 'https://people.googleapis.com/v1/people/me/connections', { message: 'Sync token is expired.' }],
    ['gmail', 'https://gmail.googleapis.com/gmail/v1/users/me/history?syncToken=stale', { message: 'Sync token is expired.' }],
    ['calendar-json', 'https://www.googleapis.com/calendar/v3/calendars/primary/events?syncToken=stale', { message: 'Sync token is expired.' }],
    ['people', 'https://people.googleapis.com/v1/people/me/connections?syncToken=stale', { details: [{ reason: 'INVALID_ARGUMENT' }] }],
  ] as const)('other HTTP 400 errors remain upstream failures: %s %s', async (api, url, error) => {
    const h = makeHarness(() => json({ error: { code: 400, ...error } }, 400));
    const client = new GoogleApiClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    await expect(client.fetchJSON(url, api)).rejects.toBeInstanceOf(CredentialError);
  });

  test('listConnections requests personFields and normalizes contacts', async () => {
    const h = makeHarness((u) => {
      expect(u.searchParams.get('personFields')).toBe(CONTACT_PERSON_FIELDS);
      expect(u.searchParams.get('requestSyncToken')).toBe('true');
      return json({
        connections: [
          {
            resourceName: 'people/c000000001',
            names: [
              { displayName: 'Secondary Example' },
              { displayName: 'Alice Example', metadata: { primary: true } },
            ],
            emailAddresses: [{ value: ' [email protected] ' }, { value: 'not-an-email' }],
            organizations: [{ name: 'Acme Example', title: 'Engineer', metadata: { primary: true } }],
          },
          { resourceName: 'people/c000000002', metadata: { deleted: true } },
        ],
        nextSyncToken: 'ppl-1',
      });
    });
    const people = new PeopleClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const { contacts, nextSyncToken } = await people.listConnections({});
    expect(nextSyncToken).toBe('ppl-1');
    expect(contacts.length).toBe(2);
    expect(contacts[0]).toEqual({
      resourceName: 'people/c000000001',
      displayName: 'Alice Example', // primary name wins
      emails: ['[email protected]'], // trimmed, lowercased, non-addresses dropped
      phones: [],
      organization: 'Acme Example',
      title: 'Engineer',
      groups: [],
      deleted: false,
    });
    expect(contacts[1].deleted).toBe(true);
    expect(contacts[1].displayName).toBeNull();
    expect(contacts[1].emails).toEqual([]);
  });

  test('syncToken is forwarded; 410 surfaces GoogleCursorExpiredError', async () => {
    const h = makeHarness((u) => {
      if (u.searchParams.get('syncToken') === 'stale') {
        return json({ error: { code: 410, message: 'Sync token expired' } }, 410);
      }
      expect(u.searchParams.get('syncToken')).toBe('ppl-1');
      return json({ connections: [], nextSyncToken: 'ppl-2' });
    });
    const people = new PeopleClient(h.tokens, h.fetchImpl, () => {}, CLIENT_ID);
    const ok = await people.listConnections({ syncToken: 'ppl-1' });
    expect(ok.nextSyncToken).toBe('ppl-2');
    let thrown: unknown;
    try {
      await people.listConnections({ syncToken: 'stale' });
    } catch (e) {
      thrown = e;
    }
    expect(thrown).toBeInstanceOf(GoogleCursorExpiredError);
    expect((thrown as GoogleCursorExpiredError).status).toBe(410);
  });
});

// ── Calendar event privacy (fail closed) ─────────────────────────────────────

describe('CalendarClient event privacy', () => {
  test('Google private and confidential events map to private; default and public do not', async () => {
    const h = makeHarness(() => json({
      items: ['private', 'confidential', 'default', 'public', undefined].map((visibility, i) => ({
        id: `ev${i}`, summary: `Event ${i}`, start: { dateTime: '2026-10-01T10:00:00Z' }, end: { dateTime: '2026-10-01T11:00:00Z' },
        ...(visibility ? { visibility } : {}),
      })),
      nextSyncToken: 'sync-1',
    }));
    const { events } = await new CalendarClient(h.tokens, h.fetchImpl).listEvents('[email protected]', { timeMinIso: '2026-09-01T00:00:00Z' });
    expect(events.map((e) => [e.id, e.private])).toEqual([['ev0', true], ['ev1', true], ['ev2', false], ['ev3', false], ['ev4', false]]);
  });
});