Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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 & <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]]);
});
});