@aglyn/plugins-outreach 1.0.0-beta.143

package/src/lib/subprocessors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/plugins/outreach/src/lib/subprocessors.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  PluginEgressHostDeclaration,\n  PluginEgressUseDeclaration,\n  PluginSubprocessorsAnswer,\n} from '@aglyn/aglyn/plugin-manager/plugin-subprocessors'\nimport { GMAIL_API_BASE } from './transport/gmail-client'\nimport { GOOGLE_OAUTH_ENDPOINTS } from './transport/google-oauth'\n\n/**\n * The hosts this plugin's code names (AGL-2978), declared here rather than in\n * the console's subprocessor inventory. Named under `subprocessors` in\n * `plugins.config.json`; the manifest generator calls\n * {@link outreachSubprocessors} and the inventory folds the answer in.\n *\n * A sequence sends a rep's one-to-one mail from the rep's OWN Google mailbox,\n * through the Gmail API, under an OAuth grant the rep gives from their own\n * Google account. `not-a-subprocessor` on the SECOND admissible reason: the\n * mailbox provider is the customer's, engaged by the customer for their own\n * mail, and a sequence acts in it at the rep's direction — Aglyn selects no\n * mail vendor for this, any more than it selects the video host an author\n * embeds. ⚑ A classification for legal to confirm when Sequences leaves staff\n * preview; the consent screen is Internal to the aglyn.com Workspace until\n * then.\n *\n * Google's token endpoint is already declared by the inventory, for the\n * platform's own service-account exchange, so this plugin adds its use of it\n * rather than a second declaration.\n *\n * Each host is read off the constant the transport calls, so a moved\n * endpoint moves its declaration with it.\n */\n\n/** The Gmail REST API: the rep's own mailbox. */\nexport const OUTREACH_GMAIL_HOST: PluginEgressHostDeclaration = {\n  host: new URL(GMAIL_API_BASE).host,\n  disposition: 'not-a-subprocessor',\n  reason:\n    \"Customer-chosen destination. The Gmail REST API of the rep's own Google Workspace mailbox, which the rep connects in Sequences → Mailboxes (`libs/plugins/outreach/src/lib/transport/gmail-client.ts`): the account's profile and verified send-as addresses at connect, a plain-text test the rep sends to themselves, and — for the sending runtime (AGL-2981) — the sequence messages it sends, and the reads and searches of that same mailbox that find what came back: replies, out-of-office answers, bounces and unsubscribe requests. The provider is the one the customer runs its mail on; nothing is sent to a mailbox the rep did not connect.\",\n  dataReceived:\n    \"The rep's own OAuth access token, and the mail the rep sends from their own mailbox — each recipient's address, the subject and the plain-text body. The runtime's searches carry the addresses of the people the rep is writing to, the rep's `+unsubscribe` address and the Message-IDs of mail it sent. What the runtime reads back is the rep's own mail: the ids of newly received messages, and whole messages — headers and plain-text or HTML bodies, delivery reports included — of the rep's sequence threads and of the replies, bounces and unsubscribe requests its searches find. No other customer record, and nothing about a site visitor.\",\n}\n\n/** Google's consent address, which only the rep's browser opens. */\nexport const OUTREACH_GOOGLE_CONSENT_HOST: PluginEgressHostDeclaration = {\n  host: new URL(GOOGLE_OAUTH_ENDPOINTS.authorize).host,\n  disposition: 'no-request',\n  reason:\n    \"Google's OAuth consent address, built by `buildGoogleAuthorizationUrl` in `libs/plugins/outreach/src/lib/transport/google-oauth.ts` and handed to the rep's own browser, which opens it to grant Sequences access to the rep's own mailbox. No server of ours requests it; the browser's visit is between the rep and their Google account.\",\n  dataReceived:\n    \"Nothing from our servers. The rep's browser carries the OAuth client id, the requested scopes, a signed state, a PKCE challenge and a login hint — the rep's own sign-in address.\",\n}\n\n/** Google's token and revocation endpoint, declared by the inventory. */\nexport const OUTREACH_GOOGLE_TOKEN_USE: PluginEgressUseDeclaration = {\n  host: new URL(GOOGLE_OAUTH_ENDPOINTS.token).host,\n  reason:\n    \"Since AGL-2978 also the Sequences OAuth token endpoint for a rep's own Google mailbox grant — the code exchange at connect, the access-token refresh before each Gmail call, and the revocation on disconnect, org erasure or account erasure — which is the rep's own account at the rep's own provider, the same footing as `gmail.googleapis.com`.\",\n  dataReceived:\n    \"For Sequences: the deployment's OAuth client credentials and, for the rep's own grant, the authorization code, PKCE verifier, refresh token and access token Google itself issued — credentials, never message content. ⚑ Legal to confirm the Annex III cell needs no change for the Sequences use.\",\n}\n\n/** The plugin's `subprocessors` entry: no recipient of its own, two hosts and one use. */\nexport function outreachSubprocessors(): PluginSubprocessorsAnswer {\n  return {\n    subprocessors: [],\n    hosts: [OUTREACH_GMAIL_HOST, OUTREACH_GOOGLE_CONSENT_HOST],\n    uses: [OUTREACH_GOOGLE_TOKEN_USE],\n  }\n}\n"],"names":["GMAIL_API_BASE","GOOGLE_OAUTH_ENDPOINTS","OUTREACH_GMAIL_HOST","host","URL","disposition","reason","dataReceived","OUTREACH_GOOGLE_CONSENT_HOST","authorize","OUTREACH_GOOGLE_TOKEN_USE","token","outreachSubprocessors","subprocessors","hosts","uses"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAOD,SAASA,cAAc,QAAQ,8BAA0B;AACzD,SAASC,sBAAsB,QAAQ,8BAA0B;AAEjE;;;;;;;;;;;;;;;;;;;;;;CAsBC,GAED,+CAA+C,GAC/C,OAAO,MAAMC,sBAAmD;IAC9DC,MAAM,IAAIC,IAAIJ,gBAAgBG,IAAI;IAClCE,aAAa;IACbC,QACE;IACFC,cACE;AACJ,EAAC;AAED,kEAAkE,GAClE,OAAO,MAAMC,+BAA4D;IACvEL,MAAM,IAAIC,IAAIH,uBAAuBQ,SAAS,EAAEN,IAAI;IACpDE,aAAa;IACbC,QACE;IACFC,cACE;AACJ,EAAC;AAED,uEAAuE,GACvE,OAAO,MAAMG,4BAAwD;IACnEP,MAAM,IAAIC,IAAIH,uBAAuBU,KAAK,EAAER,IAAI;IAChDG,QACE;IACFC,cACE;AACJ,EAAC;AAED,wFAAwF,GACxF,OAAO,SAASK;IACd,OAAO;QACLC,eAAe,EAAE;QACjBC,OAAO;YAACZ;YAAqBM;SAA6B;QAC1DO,MAAM;YAACL;SAA0B;IACnC;AACF"}

package/src/lib/transport/gmail-client.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { GmailApiMessage } from '../engine/thread-message';
+import { type TransportDeps } from './http';
+/**
+ * THE GMAIL REST TRANSPORT (AGL-2978): one connected mailbox, as the calls
+ * Outreach makes against it.
+ *
+ * Built per mailbox, per invocation, from the mailbox's refresh token. The
+ * access token is minted on first use and reused until a minute before it
+ * expires, so one cron pass over one mailbox — a send, a thread read, a
+ * bounce search — refreshes once. Concurrent callers share the one refresh
+ * in flight.
+ *
+ * A 401 from Gmail drops the cached token and retries the call once with a
+ * fresh one: an access token can be refused before its stated expiry (a
+ * password change, an admin action), and that is not yet a dead grant. If
+ * the REFRESH is refused, it is — `invalid_grant`, `reconnectRequired`.
+ *
+ * Every failure is a `GmailTransportError`; see `gmail-errors.ts` for how a
+ * caller decides between reconnecting, retrying later and giving up.
+ */
+export declare const GMAIL_API_BASE = "https://gmail.googleapis.com/gmail/v1/users/me";
+export interface GmailClientOptions extends TransportDeps {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+}
+/** `users.getProfile`. */
+export interface GmailProfile {
+    emailAddress: string;
+    messagesTotal: number;
+    threadsTotal: number;
+    historyId: string;
+}
+/** One entry of `users.settings.sendAs.list`. */
+export interface GmailSendAs {
+    sendAsEmail: string;
+    displayName: string;
+    replyToAddress: string | null;
+    isPrimary: boolean;
+    isDefault: boolean;
+    treatAsAlias: boolean;
+    /**
+     * `accepted` once Gmail verified the address; absent on the primary
+     * address, which needs no verification.
+     */
+    verificationStatus: string | null;
+}
+export interface GmailMessageHeader {
+    name: string;
+    value: string;
+}
+/** A message in `format=metadata`: ids, labels, snippet and the headers asked for. */
+export interface GmailMessageMetadata {
+    id: string;
+    threadId: string;
+    labelIds: string[];
+    snippet: string;
+    internalDateMs: number | null;
+    headers: GmailMessageHeader[];
+}
+export interface GmailThread {
+    id: string;
+    historyId: string | null;
+    messages: GmailMessageMetadata[];
+}
+/**
+ * A thread in `format=full`: every message as Gmail returns it — headers,
+ * MIME tree and base64url bodies — which is what the engine's
+ * `outreachThreadMessageFromGmail` reads replies and bounces from.
+ */
+export interface GmailFullThread {
+    id: string;
+    historyId: string | null;
+    messages: GmailApiMessage[];
+}
+export interface GmailMessageList {
+    messages: Array<{
+        id: string;
+        threadId: string;
+    }>;
+    nextPageToken: string | null;
+    resultSizeEstimate: number;
+}
+export interface GmailSentMessage {
+    id: string;
+    threadId: string;
+    labelIds: string[];
+}
+export interface GmailClient {
+    /** A live access token, minted or reused. */
+    getAccessToken(): Promise<string>;
+    getProfile(): Promise<GmailProfile>;
+    listSendAs(): Promise<GmailSendAs[]>;
+    /**
+     * `messages.send`: `raw` is the base64url RFC 5322 message
+     * (`encodeGmailRawMessage`), and `threadId` files a follow-up into the
+     * thread its first step started.
+     */
+    sendMessage(input: {
+        raw: string;
+        threadId?: string | null;
+    }): Promise<GmailSentMessage>;
+    /** `threads.get` with `format=metadata` and only the headers named. */
+    getThread(threadId: string, options?: {
+        metadataHeaders?: readonly string[];
+    }): Promise<GmailThread>;
+    /**
+     * `threads.get` with `format=full`: every message whole, unflattened, for
+     * the engine's classifier — a reply's text, a bounce's delivery report.
+     */
+    getFullThread(threadId: string): Promise<GmailFullThread>;
+    /** `messages.get` with `format=metadata` and only the headers named. */
+    getMessage(messageId: string, options?: {
+        metadataHeaders?: readonly string[];
+    }): Promise<GmailMessageMetadata>;
+    /** `messages.get` with `format=full` — a message a search found, read whole. */
+    getFullMessage(messageId: string): Promise<GmailApiMessage>;
+    /** `messages.list` with a Gmail search `q`. */
+    listMessages(options: {
+        q: string;
+        maxResults?: number;
+        pageToken?: string | null;
+        includeSpamTrash?: boolean;
+    }): Promise<GmailMessageList>;
+    /** Revokes the grant at Google. `already-invalid` when it was dead. */
+    revoke(): Promise<'revoked' | 'already-invalid'>;
+}
+/** A Gmail client for one mailbox. See the module comment. */
+export declare function createGmailClient(options: GmailClientOptions): GmailClient;

package/src/lib/transport/gmail-client.js

@@ -0,0 +1,229 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { GmailTransportError, gmailApiError } from "./gmail-errors.js";
+import { refreshGoogleAccessToken, revokeGoogleToken } from "./google-oauth.js";
+import { fetchWithBackoff, retryAfterMs } from "./http.js";
+/**
+ * THE GMAIL REST TRANSPORT (AGL-2978): one connected mailbox, as the calls
+ * Outreach makes against it.
+ *
+ * Built per mailbox, per invocation, from the mailbox's refresh token. The
+ * access token is minted on first use and reused until a minute before it
+ * expires, so one cron pass over one mailbox — a send, a thread read, a
+ * bounce search — refreshes once. Concurrent callers share the one refresh
+ * in flight.
+ *
+ * A 401 from Gmail drops the cached token and retries the call once with a
+ * fresh one: an access token can be refused before its stated expiry (a
+ * password change, an admin action), and that is not yet a dead grant. If
+ * the REFRESH is refused, it is — `invalid_grant`, `reconnectRequired`.
+ *
+ * Every failure is a `GmailTransportError`; see `gmail-errors.ts` for how a
+ * caller decides between reconnecting, retrying later and giving up.
+ */ export const GMAIL_API_BASE = 'https://gmail.googleapis.com/gmail/v1/users/me';
+/** Refresh this long before the stated expiry, so a slow call cannot cross it. */ const EXPIRY_MARGIN_MS = 60000;
+const text = (value)=>typeof value === 'string' ? value : '';
+function readMessage(value) {
+    var _record_payload;
+    const record = value != null ? value : {};
+    const payload = (_record_payload = record['payload']) != null ? _record_payload : {};
+    const headers = Array.isArray(payload.headers) ? payload.headers : [];
+    const internalDate = Number(record['internalDate']);
+    return {
+        id: text(record['id']),
+        threadId: text(record['threadId']),
+        labelIds: Array.isArray(record['labelIds']) ? record['labelIds'].map(String) : [],
+        snippet: text(record['snippet']),
+        internalDateMs: Number.isFinite(internalDate) ? internalDate : null,
+        headers: headers.map((header)=>header).filter((header)=>typeof header.name === 'string').map((header)=>({
+                name: String(header.name),
+                value: text(header.value)
+            }))
+    };
+}
+function readSendAs(value) {
+    const record = value != null ? value : {};
+    return {
+        sendAsEmail: text(record['sendAsEmail']).trim().toLowerCase(),
+        displayName: text(record['displayName']),
+        replyToAddress: text(record['replyToAddress']) || null,
+        isPrimary: record['isPrimary'] === true,
+        isDefault: record['isDefault'] === true,
+        treatAsAlias: record['treatAsAlias'] === true,
+        verificationStatus: text(record['verificationStatus']) || null
+    };
+}
+/**
+ * A `format=full` message, as Gmail sent it. Only the id is checked here: the
+ * engine's reader decodes the rest defensively and never throws.
+ */ function readFullMessage(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new GmailTransportError('unexpected', 'Gmail answered with a message that is not an object.');
+    }
+    const record = value;
+    return _extends({}, record, {
+        id: text(record['id'])
+    });
+}
+function metadataQuery(headers) {
+    const query = new URLSearchParams({
+        format: 'metadata'
+    });
+    for (const header of headers != null ? headers : [])query.append('metadataHeaders', header);
+    return query.toString();
+}
+/** A Gmail client for one mailbox. See the module comment. */ export function createGmailClient(options) {
+    var _options_now;
+    const deps = options;
+    const now = (_options_now = options.now) != null ? _options_now : Date.now;
+    let cached = null;
+    let refreshing = null;
+    const mint = ()=>{
+        refreshing != null ? refreshing : refreshing = refreshGoogleAccessToken({
+            clientId: options.clientId,
+            clientSecret: options.clientSecret,
+            refreshToken: options.refreshToken
+        }, deps).then((minted)=>{
+            cached = {
+                token: minted.accessToken,
+                expiresAtMs: now() + minted.expiresInSeconds * 1000
+            };
+            return minted.accessToken;
+        }).finally(()=>{
+            refreshing = null;
+        });
+        return refreshing;
+    };
+    const getAccessToken = async ()=>{
+        if (cached && cached.expiresAtMs - EXPIRY_MARGIN_MS > now()) return cached.token;
+        return mint();
+    };
+    /** One Gmail API call: authorized, retried per policy, 401 once refreshed. */ const call = async (path, init = {})=>{
+        for(let tries = 0;; tries += 1){
+            const token = await getAccessToken();
+            const response = await fetchWithBackoff(`${GMAIL_API_BASE}${path}`, _extends({}, init, {
+                headers: _extends({
+                    Accept: 'application/json'
+                }, init.body ? {
+                    'Content-Type': 'application/json'
+                } : {}, init.headers, {
+                    Authorization: `Bearer ${token}`
+                })
+            }), deps);
+            if (response.status === 401 && tries === 0) {
+                cached = null;
+                continue;
+            }
+            const body = await response.json().catch(()=>null);
+            if (response.ok) {
+                if (body === null) {
+                    throw new GmailTransportError('unexpected', 'Gmail answered with a body that is not JSON.', {
+                        status: response.status
+                    });
+                }
+                return body;
+            }
+            throw gmailApiError(response.status, body, {
+                retryAfterMs: retryAfterMs(response, now())
+            });
+        }
+    };
+    return {
+        getAccessToken,
+        async getProfile () {
+            const body = await call('/profile');
+            return {
+                emailAddress: text(body['emailAddress']).trim().toLowerCase(),
+                messagesTotal: Number(body['messagesTotal']) || 0,
+                threadsTotal: Number(body['threadsTotal']) || 0,
+                historyId: text(body['historyId'])
+            };
+        },
+        async listSendAs () {
+            const body = await call('/settings/sendAs');
+            return (Array.isArray(body.sendAs) ? body.sendAs : []).map(readSendAs);
+        },
+        async sendMessage (input) {
+            if (!(input == null ? void 0 : input.raw)) {
+                throw new GmailTransportError('invalid_request', 'A message to send needs its raw content.');
+            }
+            const body = await call('/messages/send', {
+                method: 'POST',
+                body: JSON.stringify(_extends({
+                    raw: input.raw
+                }, input.threadId ? {
+                    threadId: input.threadId
+                } : {}))
+            });
+            return {
+                id: text(body['id']),
+                threadId: text(body['threadId']),
+                labelIds: Array.isArray(body['labelIds']) ? body['labelIds'].map(String) : []
+            };
+        },
+        async getThread (threadId, threadOptions) {
+            const body = await call(`/threads/${encodeURIComponent(threadId)}?${metadataQuery(threadOptions == null ? void 0 : threadOptions.metadataHeaders)}`);
+            return {
+                id: text(body['id']),
+                historyId: text(body['historyId']) || null,
+                messages: (Array.isArray(body['messages']) ? body['messages'] : []).map(readMessage)
+            };
+        },
+        async getFullThread (threadId) {
+            const body = await call(`/threads/${encodeURIComponent(threadId)}?format=full`);
+            return {
+                id: text(body['id']),
+                historyId: text(body['historyId']) || null,
+                // An entry that is not a message object is not one to classify.
+                messages: (Array.isArray(body['messages']) ? body['messages'] : []).filter((entry)=>Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry)).map(readFullMessage)
+            };
+        },
+        async getMessage (messageId, messageOptions) {
+            const body = await call(`/messages/${encodeURIComponent(messageId)}?${metadataQuery(messageOptions == null ? void 0 : messageOptions.metadataHeaders)}`);
+            return readMessage(body);
+        },
+        async getFullMessage (messageId) {
+            return readFullMessage(await call(`/messages/${encodeURIComponent(messageId)}?format=full`));
+        },
+        async listMessages (listOptions) {
+            const query = new URLSearchParams({
+                q: listOptions.q
+            });
+            if (listOptions.maxResults) query.set('maxResults', String(listOptions.maxResults));
+            if (listOptions.pageToken) query.set('pageToken', listOptions.pageToken);
+            if (listOptions.includeSpamTrash) query.set('includeSpamTrash', 'true');
+            const body = await call(`/messages?${query.toString()}`);
+            const messages = Array.isArray(body['messages']) ? body['messages'] : [];
+            return {
+                messages: messages.map((entry)=>{
+                    const record = entry != null ? entry : {};
+                    return {
+                        id: text(record['id']),
+                        threadId: text(record['threadId'])
+                    };
+                }),
+                nextPageToken: text(body['nextPageToken']) || null,
+                resultSizeEstimate: Number(body['resultSizeEstimate']) || 0
+            };
+        },
+        revoke () {
+            return revokeGoogleToken(options.refreshToken, deps);
+        }
+    };
+}
+
+//# sourceMappingURL=gmail-client.js.map

package/src/lib/transport/gmail-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/transport/gmail-client.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { GmailApiMessage } from '../engine/thread-message'\nimport { GmailTransportError, gmailApiError } from './gmail-errors'\nimport {\n  refreshGoogleAccessToken,\n  revokeGoogleToken,\n} from './google-oauth'\nimport { fetchWithBackoff, retryAfterMs, type TransportDeps } from './http'\n\n/**\n * THE GMAIL REST TRANSPORT (AGL-2978): one connected mailbox, as the calls\n * Outreach makes against it.\n *\n * Built per mailbox, per invocation, from the mailbox's refresh token. The\n * access token is minted on first use and reused until a minute before it\n * expires, so one cron pass over one mailbox — a send, a thread read, a\n * bounce search — refreshes once. Concurrent callers share the one refresh\n * in flight.\n *\n * A 401 from Gmail drops the cached token and retries the call once with a\n * fresh one: an access token can be refused before its stated expiry (a\n * password change, an admin action), and that is not yet a dead grant. If\n * the REFRESH is refused, it is — `invalid_grant`, `reconnectRequired`.\n *\n * Every failure is a `GmailTransportError`; see `gmail-errors.ts` for how a\n * caller decides between reconnecting, retrying later and giving up.\n */\n\nexport const GMAIL_API_BASE = 'https://gmail.googleapis.com/gmail/v1/users/me'\n\nexport interface GmailClientOptions extends TransportDeps {\n  clientId: string\n  clientSecret: string\n  refreshToken: string\n}\n\n/** `users.getProfile`. */\nexport interface GmailProfile {\n  emailAddress: string\n  messagesTotal: number\n  threadsTotal: number\n  historyId: string\n}\n\n/** One entry of `users.settings.sendAs.list`. */\nexport interface GmailSendAs {\n  sendAsEmail: string\n  displayName: string\n  replyToAddress: string | null\n  isPrimary: boolean\n  isDefault: boolean\n  treatAsAlias: boolean\n  /**\n   * `accepted` once Gmail verified the address; absent on the primary\n   * address, which needs no verification.\n   */\n  verificationStatus: string | null\n}\n\nexport interface GmailMessageHeader {\n  name: string\n  value: string\n}\n\n/** A message in `format=metadata`: ids, labels, snippet and the headers asked for. */\nexport interface GmailMessageMetadata {\n  id: string\n  threadId: string\n  labelIds: string[]\n  snippet: string\n  internalDateMs: number | null\n  headers: GmailMessageHeader[]\n}\n\nexport interface GmailThread {\n  id: string\n  historyId: string | null\n  messages: GmailMessageMetadata[]\n}\n\n/**\n * A thread in `format=full`: every message as Gmail returns it — headers,\n * MIME tree and base64url bodies — which is what the engine's\n * `outreachThreadMessageFromGmail` reads replies and bounces from.\n */\nexport interface GmailFullThread {\n  id: string\n  historyId: string | null\n  messages: GmailApiMessage[]\n}\n\nexport interface GmailMessageList {\n  messages: Array<{ id: string; threadId: string }>\n  nextPageToken: string | null\n  resultSizeEstimate: number\n}\n\nexport interface GmailSentMessage {\n  id: string\n  threadId: string\n  labelIds: string[]\n}\n\nexport interface GmailClient {\n  /** A live access token, minted or reused. */\n  getAccessToken(): Promise<string>\n  getProfile(): Promise<GmailProfile>\n  listSendAs(): Promise<GmailSendAs[]>\n  /**\n   * `messages.send`: `raw` is the base64url RFC 5322 message\n   * (`encodeGmailRawMessage`), and `threadId` files a follow-up into the\n   * thread its first step started.\n   */\n  sendMessage(input: { raw: string; threadId?: string | null }): Promise<GmailSentMessage>\n  /** `threads.get` with `format=metadata` and only the headers named. */\n  getThread(threadId: string, options?: { metadataHeaders?: readonly string[] }): Promise<GmailThread>\n  /**\n   * `threads.get` with `format=full`: every message whole, unflattened, for\n   * the engine's classifier — a reply's text, a bounce's delivery report.\n   */\n  getFullThread(threadId: string): Promise<GmailFullThread>\n  /** `messages.get` with `format=metadata` and only the headers named. */\n  getMessage(messageId: string, options?: { metadataHeaders?: readonly string[] }): Promise<GmailMessageMetadata>\n  /** `messages.get` with `format=full` — a message a search found, read whole. */\n  getFullMessage(messageId: string): Promise<GmailApiMessage>\n  /** `messages.list` with a Gmail search `q`. */\n  listMessages(options: {\n    q: string\n    maxResults?: number\n    pageToken?: string | null\n    includeSpamTrash?: boolean\n  }): Promise<GmailMessageList>\n  /** Revokes the grant at Google. `already-invalid` when it was dead. */\n  revoke(): Promise<'revoked' | 'already-invalid'>\n}\n\n/** Refresh this long before the stated expiry, so a slow call cannot cross it. */\nconst EXPIRY_MARGIN_MS = 60_000\n\nconst text = (value: unknown): string => (typeof value === 'string' ? value : '')\n\nfunction readMessage(value: unknown): GmailMessageMetadata {\n  const record = (value ?? {}) as Record<string, unknown>\n  const payload = (record['payload'] ?? {}) as { headers?: unknown }\n  const headers = Array.isArray(payload.headers) ? payload.headers : []\n  const internalDate = Number(record['internalDate'])\n  return {\n    id: text(record['id']),\n    threadId: text(record['threadId']),\n    labelIds: Array.isArray(record['labelIds']) ? record['labelIds'].map(String) : [],\n    snippet: text(record['snippet']),\n    internalDateMs: Number.isFinite(internalDate) ? internalDate : null,\n    headers: headers\n      .map((header) => header as { name?: unknown; value?: unknown })\n      .filter((header) => typeof header.name === 'string')\n      .map((header) => ({ name: String(header.name), value: text(header.value) })),\n  }\n}\n\nfunction readSendAs(value: unknown): GmailSendAs {\n  const record = (value ?? {}) as Record<string, unknown>\n  return {\n    sendAsEmail: text(record['sendAsEmail']).trim().toLowerCase(),\n    displayName: text(record['displayName']),\n    replyToAddress: text(record['replyToAddress']) || null,\n    isPrimary: record['isPrimary'] === true,\n    isDefault: record['isDefault'] === true,\n    treatAsAlias: record['treatAsAlias'] === true,\n    verificationStatus: text(record['verificationStatus']) || null,\n  }\n}\n\n/**\n * A `format=full` message, as Gmail sent it. Only the id is checked here: the\n * engine's reader decodes the rest defensively and never throws.\n */\nfunction readFullMessage(value: unknown): GmailApiMessage {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    throw new GmailTransportError('unexpected', 'Gmail answered with a message that is not an object.')\n  }\n  const record = value as Record<string, unknown>\n  return { ...(record as unknown as GmailApiMessage), id: text(record['id']) }\n}\n\nfunction metadataQuery(headers: readonly string[] | undefined): string {\n  const query = new URLSearchParams({ format: 'metadata' })\n  for (const header of headers ?? []) query.append('metadataHeaders', header)\n  return query.toString()\n}\n\n/** A Gmail client for one mailbox. See the module comment. */\nexport function createGmailClient(options: GmailClientOptions): GmailClient {\n  const deps: TransportDeps = options\n  const now = options.now ?? Date.now\n  let cached: { token: string; expiresAtMs: number } | null = null\n  let refreshing: Promise<string> | null = null\n\n  const mint = (): Promise<string> => {\n    refreshing ??= refreshGoogleAccessToken(\n      {\n        clientId: options.clientId,\n        clientSecret: options.clientSecret,\n        refreshToken: options.refreshToken,\n      },\n      deps,\n    )\n      .then((minted) => {\n        cached = {\n          token: minted.accessToken,\n          expiresAtMs: now() + minted.expiresInSeconds * 1000,\n        }\n        return minted.accessToken\n      })\n      .finally(() => {\n        refreshing = null\n      })\n    return refreshing\n  }\n\n  const getAccessToken = async (): Promise<string> => {\n    if (cached && cached.expiresAtMs - EXPIRY_MARGIN_MS > now()) return cached.token\n    return mint()\n  }\n\n  /** One Gmail API call: authorized, retried per policy, 401 once refreshed. */\n  const call = async <T>(path: string, init: RequestInit = {}): Promise<T> => {\n    for (let tries = 0; ; tries += 1) {\n      const token = await getAccessToken()\n      const response = await fetchWithBackoff(\n        `${GMAIL_API_BASE}${path}`,\n        {\n          ...init,\n          headers: {\n            Accept: 'application/json',\n            ...(init.body ? { 'Content-Type': 'application/json' } : {}),\n            ...(init.headers as Record<string, string> | undefined),\n            Authorization: `Bearer ${token}`,\n          },\n        },\n        deps,\n      )\n      if (response.status === 401 && tries === 0) {\n        cached = null\n        continue\n      }\n      const body = await response.json().catch(() => null)\n      if (response.ok) {\n        if (body === null) {\n          throw new GmailTransportError('unexpected', 'Gmail answered with a body that is not JSON.', {\n            status: response.status,\n          })\n        }\n        return body as T\n      }\n      throw gmailApiError(response.status, body, { retryAfterMs: retryAfterMs(response, now()) })\n    }\n  }\n\n  return {\n    getAccessToken,\n\n    async getProfile() {\n      const body = await call<Record<string, unknown>>('/profile')\n      return {\n        emailAddress: text(body['emailAddress']).trim().toLowerCase(),\n        messagesTotal: Number(body['messagesTotal']) || 0,\n        threadsTotal: Number(body['threadsTotal']) || 0,\n        historyId: text(body['historyId']),\n      }\n    },\n\n    async listSendAs() {\n      const body = await call<{ sendAs?: unknown }>('/settings/sendAs')\n      return (Array.isArray(body.sendAs) ? body.sendAs : []).map(readSendAs)\n    },\n\n    async sendMessage(input) {\n      if (!input?.raw) {\n        throw new GmailTransportError('invalid_request', 'A message to send needs its raw content.')\n      }\n      const body = await call<Record<string, unknown>>('/messages/send', {\n        method: 'POST',\n        body: JSON.stringify({ raw: input.raw, ...(input.threadId ? { threadId: input.threadId } : {}) }),\n      })\n      return {\n        id: text(body['id']),\n        threadId: text(body['threadId']),\n        labelIds: Array.isArray(body['labelIds']) ? body['labelIds'].map(String) : [],\n      }\n    },\n\n    async getThread(threadId, threadOptions) {\n      const body = await call<Record<string, unknown>>(\n        `/threads/${encodeURIComponent(threadId)}?${metadataQuery(threadOptions?.metadataHeaders)}`,\n      )\n      return {\n        id: text(body['id']),\n        historyId: text(body['historyId']) || null,\n        messages: (Array.isArray(body['messages']) ? body['messages'] : []).map(readMessage),\n      }\n    },\n\n    async getFullThread(threadId) {\n      const body = await call<Record<string, unknown>>(\n        `/threads/${encodeURIComponent(threadId)}?format=full`,\n      )\n      return {\n        id: text(body['id']),\n        historyId: text(body['historyId']) || null,\n        // An entry that is not a message object is not one to classify.\n        messages: (Array.isArray(body['messages']) ? body['messages'] : [])\n          .filter((entry) => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry))\n          .map(readFullMessage),\n      }\n    },\n\n    async getMessage(messageId, messageOptions) {\n      const body = await call<unknown>(\n        `/messages/${encodeURIComponent(messageId)}?${metadataQuery(messageOptions?.metadataHeaders)}`,\n      )\n      return readMessage(body)\n    },\n\n    async getFullMessage(messageId) {\n      return readFullMessage(await call<unknown>(`/messages/${encodeURIComponent(messageId)}?format=full`))\n    },\n\n    async listMessages(listOptions) {\n      const query = new URLSearchParams({ q: listOptions.q })\n      if (listOptions.maxResults) query.set('maxResults', String(listOptions.maxResults))\n      if (listOptions.pageToken) query.set('pageToken', listOptions.pageToken)\n      if (listOptions.includeSpamTrash) query.set('includeSpamTrash', 'true')\n      const body = await call<Record<string, unknown>>(`/messages?${query.toString()}`)\n      const messages = Array.isArray(body['messages']) ? body['messages'] : []\n      return {\n        messages: messages.map((entry) => {\n          const record = (entry ?? {}) as Record<string, unknown>\n          return { id: text(record['id']), threadId: text(record['threadId']) }\n        }),\n        nextPageToken: text(body['nextPageToken']) || null,\n        resultSizeEstimate: Number(body['resultSizeEstimate']) || 0,\n      }\n    },\n\n    revoke() {\n      return revokeGoogleToken(options.refreshToken, deps)\n    },\n  }\n}\n"],"names":["GmailTransportError","gmailApiError","refreshGoogleAccessToken","revokeGoogleToken","fetchWithBackoff","retryAfterMs","GMAIL_API_BASE","EXPIRY_MARGIN_MS","text","value","readMessage","record","payload","headers","Array","isArray","internalDate","Number","id","threadId","labelIds","map","String","snippet","internalDateMs","isFinite","header","filter","name","readSendAs","sendAsEmail","trim","toLowerCase","displayName","replyToAddress","isPrimary","isDefault","treatAsAlias","verificationStatus","readFullMessage","metadataQuery","query","URLSearchParams","format","append","toString","createGmailClient","options","deps","now","Date","cached","refreshing","mint","clientId","clientSecret","refreshToken","then","minted","token","accessToken","expiresAtMs","expiresInSeconds","finally","getAccessToken","call","path","init","tries","response","Accept","body","Authorization","status","json","catch","ok","getProfile","emailAddress","messagesTotal","threadsTotal","historyId","listSendAs","sendAs","sendMessage","input","raw","method","JSON","stringify","getThread","threadOptions","encodeURIComponent","metadataHeaders","messages","getFullThread","entry","Boolean","getMessage","messageId","messageOptions","getFullMessage","listMessages","listOptions","q","maxResults","set","pageToken","includeSpamTrash","nextPageToken","resultSizeEstimate","revoke"],"mappings":"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"}

package/src/lib/transport/gmail-errors.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * WHAT A GOOGLE CALL CAN FAIL WITH, AS OUTREACH ACTS ON IT (AGL-2978).
+ *
+ * Google answers in two dialects — the OAuth token endpoint's
+ * `{ error: 'invalid_grant' }` and the Gmail API's
+ * `{ error: { code, status, errors: [{ reason }] } }` — and a caller should
+ * not have to speak either. Every failure the transport raises is one
+ * {@link GmailTransportError} carrying the three decisions a caller makes:
+ *
+ * - `reconnectRequired` — the grant itself is gone (revoked, expired, a
+ *   password change, a scope removed). Nothing will work until the rep
+ *   connects again, so the mailbox goes to `reconnect_required`.
+ * - `retryable` — the request may succeed later as it stands (a rate limit,
+ *   an outage, a dropped connection). `retryAfterMs` says when, if Google
+ *   said.
+ * - neither — the request itself is wrong, or the deployment is (a bad
+ *   client id or secret), and retrying it changes nothing.
+ */
+export type GmailTransportErrorCode = 
+/** The refresh token was refused: revoked, expired or otherwise dead. */
+'invalid_grant'
+/** The grant is missing a scope the call needs. */
+ | 'insufficient_scope'
+/** The OAuth client id or secret was refused — a deployment problem. */
+ | 'client_misconfigured'
+/** Rate-limited, still after backing off. */
+ | 'rate_limited'
+/** The account's sending or API quota for the day is spent. */
+ | 'quota_exceeded'
+/** Google answered 5xx, still after backing off. */
+ | 'unavailable'
+/** The request never got an answer: a network failure or a timeout. */
+ | 'network'
+/** The access token was refused even after a fresh one was minted. */
+ | 'unauthorized'
+/** The account has no Gmail service (a Workspace user without Gmail). */
+ | 'mail_service_unavailable' | 'not_found'
+/** Google refused the request as malformed. */
+ | 'invalid_request' | 'forbidden'
+/** An answer the transport could not read. */
+ | 'unexpected';
+export interface GmailTransportErrorInit {
+    status?: number | null;
+    retryAfterMs?: number | null;
+    /** The provider's own reason string, kept for logs and health rows. */
+    providerReason?: string | null;
+}
+export declare class GmailTransportError extends Error {
+    readonly code: GmailTransportErrorCode;
+    readonly status: number | null;
+    readonly retryAfterMs: number | null;
+    readonly providerReason: string | null;
+    constructor(code: GmailTransportErrorCode, message: string, init?: GmailTransportErrorInit);
+    /** The grant is gone; the mailbox needs connecting again. */
+    get reconnectRequired(): boolean;
+    /** The same request may succeed later. */
+    get retryable(): boolean;
+}
+/** Whether a thrown value says the mailbox's grant is gone. */
+export declare function isReconnectRequired(error: unknown): boolean;
+/** The OAuth token endpoint's error body: `{ error, error_description }`. */
+export declare function tokenEndpointError(status: number, body: unknown): GmailTransportError;
+/** Whether a Gmail API 403 is a rate limit, which backs off like a 429. */
+export declare function isRateLimitBody(body: unknown): boolean;
+/** A Gmail API error response, mapped. */
+export declare function gmailApiError(status: number, body: unknown, init?: {
+    retryAfterMs?: number | null;
+}): GmailTransportError;

package/src/lib/transport/gmail-errors.js

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * WHAT A GOOGLE CALL CAN FAIL WITH, AS OUTREACH ACTS ON IT (AGL-2978).
+ *
+ * Google answers in two dialects — the OAuth token endpoint's
+ * `{ error: 'invalid_grant' }` and the Gmail API's
+ * `{ error: { code, status, errors: [{ reason }] } }` — and a caller should
+ * not have to speak either. Every failure the transport raises is one
+ * {@link GmailTransportError} carrying the three decisions a caller makes:
+ *
+ * - `reconnectRequired` — the grant itself is gone (revoked, expired, a
+ *   password change, a scope removed). Nothing will work until the rep
+ *   connects again, so the mailbox goes to `reconnect_required`.
+ * - `retryable` — the request may succeed later as it stands (a rate limit,
+ *   an outage, a dropped connection). `retryAfterMs` says when, if Google
+ *   said.
+ * - neither — the request itself is wrong, or the deployment is (a bad
+ *   client id or secret), and retrying it changes nothing.
+ */ const RECONNECT = new Set([
+    'invalid_grant',
+    'insufficient_scope'
+]);
+const RETRYABLE = new Set([
+    'rate_limited',
+    'unavailable',
+    'network'
+]);
+export class GmailTransportError extends Error {
+    /** The grant is gone; the mailbox needs connecting again. */ get reconnectRequired() {
+        return RECONNECT.has(this.code);
+    }
+    /** The same request may succeed later. */ get retryable() {
+        return RETRYABLE.has(this.code);
+    }
+    constructor(code, message, init = {}){
+        var _init_status, _init_retryAfterMs, _init_providerReason;
+        super(message);
+        this.name = 'GmailTransportError';
+        this.code = code;
+        this.status = (_init_status = init.status) != null ? _init_status : null;
+        this.retryAfterMs = (_init_retryAfterMs = init.retryAfterMs) != null ? _init_retryAfterMs : null;
+        this.providerReason = (_init_providerReason = init.providerReason) != null ? _init_providerReason : null;
+    }
+}
+/** Whether a thrown value says the mailbox's grant is gone. */ export function isReconnectRequired(error) {
+    return error instanceof GmailTransportError && error.reconnectRequired;
+}
+/** The OAuth token endpoint's error body: `{ error, error_description }`. */ export function tokenEndpointError(status, body) {
+    const record = body != null ? body : {};
+    const reason = typeof record.error === 'string' ? record.error : null;
+    const described = typeof record.error_description === 'string' ? record.error_description : '';
+    if (reason === 'invalid_grant') {
+        return new GmailTransportError('invalid_grant', 'Google refused the mailbox grant. The mailbox must be connected again.', {
+            status,
+            providerReason: reason
+        });
+    }
+    if (reason === 'invalid_client' || reason === 'unauthorized_client') {
+        return new GmailTransportError('client_misconfigured', 'Google refused this deployment’s OAuth client. Check its client id and secret.', {
+            status,
+            providerReason: reason
+        });
+    }
+    if (reason === 'invalid_scope') {
+        return new GmailTransportError('insufficient_scope', 'Google refused a requested scope.', {
+            status,
+            providerReason: reason
+        });
+    }
+    return new GmailTransportError(status >= 500 ? 'unavailable' : 'invalid_request', `Google’s token endpoint refused the request${described ? `: ${described.slice(0, 200)}` : '.'}`, {
+        status,
+        providerReason: reason
+    });
+}
+/** Every reason string a Gmail API error body carries. */ function apiReasons(body) {
+    var _ref, _ref1;
+    const error = body == null ? void 0 : body.error;
+    return [
+        ...((_ref = error == null ? void 0 : error.errors) != null ? _ref : []).map((entry)=>entry == null ? void 0 : entry.reason),
+        ...((_ref1 = error == null ? void 0 : error.details) != null ? _ref1 : []).map((entry)=>entry == null ? void 0 : entry.reason),
+        error == null ? void 0 : error.status
+    ].filter((reason)=>typeof reason === 'string' && reason.length > 0);
+}
+/** Whether a Gmail API 403 is a rate limit, which backs off like a 429. */ export function isRateLimitBody(body) {
+    return apiReasons(body).some((reason)=>[
+            'rateLimitExceeded',
+            'userRateLimitExceeded',
+            'RESOURCE_EXHAUSTED'
+        ].includes(reason));
+}
+/** A Gmail API error response, mapped. */ export function gmailApiError(status, body, init = {}) {
+    var _reasons_;
+    var _body_error;
+    const reasons = apiReasons(body);
+    const providerReason = (_reasons_ = reasons[0]) != null ? _reasons_ : null;
+    const has = (...names)=>reasons.some((reason)=>names.includes(reason));
+    const message = body == null ? void 0 : (_body_error = body.error) == null ? void 0 : _body_error.message;
+    const detail = typeof message === 'string' && message ? `: ${message.slice(0, 200)}` : '.';
+    const make = (code, text)=>new GmailTransportError(code, text, {
+            status,
+            providerReason,
+            retryAfterMs: init.retryAfterMs
+        });
+    if (status === 429 || status === 403 && isRateLimitBody(body)) {
+        return make('rate_limited', 'Gmail is rate-limiting this mailbox. Try again later.');
+    }
+    if (has('dailyLimitExceeded', 'quotaExceeded')) {
+        return make('quota_exceeded', 'This mailbox has spent its Gmail quota for the day.');
+    }
+    if (has('insufficientPermissions', 'ACCESS_TOKEN_SCOPE_INSUFFICIENT')) {
+        return make('insufficient_scope', 'The mailbox grant is missing a permission Sequences needs.');
+    }
+    if (status >= 500) return make('unavailable', `Gmail is unavailable${detail}`);
+    if (status === 401) return make('unauthorized', 'Gmail refused the mailbox’s access token.');
+    if (status === 400 && has('failedPrecondition') && /mail service not enabled/i.test(String(message))) {
+        return make('mail_service_unavailable', 'This Google account has no Gmail service.');
+    }
+    if (status === 404) return make('not_found', `Gmail found nothing there${detail}`);
+    if (status === 400) return make('invalid_request', `Gmail refused the request${detail}`);
+    if (status === 403) return make('forbidden', `Gmail refused the request${detail}`);
+    return make('unexpected', `Gmail answered ${status}${detail}`);
+}
+
+//# sourceMappingURL=gmail-errors.js.map