@open-mercato/channel-gmail 0.6.4

package/src/modules/channel_gmail/lib/capabilities.ts

@@ -0,0 +1,22 @@
+import type { ChannelCapabilities } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import { baseEmailCapabilities } from '@open-mercato/core/modules/communication_channels/lib/email-capabilities'
+
+/**
+ * Gmail capabilities. `realtimePush: false` is deliberate: Gmail Pub/Sub push IS
+ * implemented (the adapter registers/renews `users.watch` and applies history
+ * notifications), but the hub keeps polling as a belt-and-suspenders fallback, so
+ * the capability flag stays false to preserve the polling cadence.
+ *
+ * Threading is supported natively via Gmail `threadId` plus RFC2822
+ * In-Reply-To/References. Attachment ceiling matches the shared email baseline.
+ *
+ * `fileSharing: false` (R2-M4 / F11, 2026-05-26): the adapter's
+ * `convertOutbound` does not yet stitch attachment URLs into the base64-encoded
+ * RFC2822 body it sends via `users.messages.send`. Re-enable when the URL-fetch
+ * + MIME stitching flow lands.
+ */
+export const gmailCapabilities: ChannelCapabilities = {
+  ...baseEmailCapabilities,
+  // Gmail supports moving a message to Trash via the API.
+  deleteMessage: true,
+}

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

@@ -0,0 +1,136 @@
+import type {
+  ChannelNativeContent,
+  ConvertOutboundInput,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import {
+  assembleRfc2822,
+  escapeQuotes,
+  generateMessageId,
+  htmlToText,
+  referencesFromMeta,
+  stringOrUndefined,
+  toAddressList,
+} from '@open-mercato/core/modules/communication_channels/lib/email-mime'
+import { GMAIL_THREAD_REF_PREFIX } from './normalize-inbound'
+
+/**
+ * Convert a hub-canonical outbound payload to a Gmail-ready native content shape.
+ *
+ * Unlike IMAP/SMTP (which hands the message to nodemailer), the Gmail adapter
+ * builds the RFC2822 message itself and sends via `gmail.users.messages.send`.
+ * The converter pre-builds the raw message so `sendMessage` is a pure
+ * "base64url-encode + POST" call, with no SMTP transport involved.
+ *
+ * Output metadata fields:
+ *   - rawMessage: Buffer  — the assembled RFC2822 message
+ *   - threadId: string?   — Gmail thread id (resolved by deriveGmailThreadId)
+ *   - subject / to / cc / bcc / inReplyTo / references — diagnostic copies
+ */
+
+export interface GmailEmailNativeMetadata {
+  subject?: string
+  to: string[]
+  cc?: string[]
+  bcc?: string[]
+  inReplyTo?: string
+  references?: string[]
+  messageId?: string
+  threadId?: string
+  fromAddress: string
+  fromName?: string
+  rawMessage: Buffer
+}
+
+export interface ConvertOutboundForGmailInput extends ConvertOutboundInput {
+  fromAddress: string
+  fromName?: string
+}
+
+/**
+ * Resolve the Gmail native `threadId` so replies attach to the original Gmail
+ * conversation. Order of precedence:
+ *   1. `gmailThreadId` — explicit, set by inbound normalization metadata.
+ *   2. `threadId` — survives the hub's convert→send double-conversion, where
+ *      `sendMessage` re-converts the already-converted metadata.
+ *   3. `thread_id` — the hub's generic conversation ref; for an existing Gmail
+ *      thread it is `gmail-thread:<rawId>` (see `normalize-inbound`). A new
+ *      outbound thread uses an `outbound:<uuid>` ref with no Gmail thread yet,
+ *      so `threadId` stays unset and Gmail opens a fresh server-side thread.
+ */
+function deriveGmailThreadId(meta: Record<string, unknown>): string | undefined {
+  const explicit = stringOrUndefined(meta.gmailThreadId) ?? stringOrUndefined(meta.threadId)
+  if (explicit) return explicit
+  const conversationRef = stringOrUndefined(meta.thread_id)
+  if (conversationRef && conversationRef.startsWith(GMAIL_THREAD_REF_PREFIX)) {
+    const rawThreadId = conversationRef.slice(GMAIL_THREAD_REF_PREFIX.length)
+    return rawThreadId.length > 0 ? rawThreadId : undefined
+  }
+  return undefined
+}
+
+export async function convertOutboundForGmail(
+  input: ConvertOutboundForGmailInput,
+): Promise<ChannelNativeContent> {
+  const meta = (input.channelMetadata ?? {}) as Record<string, unknown>
+  const subject = stringOrUndefined(meta.subject)
+  const to = toAddressList(meta.to)
+  if (to.length === 0) {
+    throw new Error('[internal] Gmail outbound conversion requires at least one recipient (channelMetadata.to)')
+  }
+  const cc = toAddressList(meta.cc)
+  const bcc = toAddressList(meta.bcc)
+  const inReplyTo = stringOrUndefined(meta.inReplyTo)
+  const references = referencesFromMeta(meta.references)
+  const messageId = stringOrUndefined(meta.messageId) ?? generateMessageId(input.fromAddress, 'gmail.com')
+  const threadId = deriveGmailThreadId(meta)
+
+  const html = input.bodyFormat === 'html' ? input.body : undefined
+  const text = input.bodyFormat === 'html' ? htmlToText(input.body) : input.body
+
+  const rawMessage = assembleRfc2822({
+    from: input.fromName ? `"${escapeQuotes(input.fromName)}" <${input.fromAddress}>` : input.fromAddress,
+    to,
+    cc,
+    bcc,
+    subject,
+    text,
+    html,
+    inReplyTo,
+    references,
+    messageId,
+  })
+
+  const metadata: GmailEmailNativeMetadata = {
+    subject,
+    to,
+    cc: cc.length ? cc : undefined,
+    bcc: bcc.length ? bcc : undefined,
+    inReplyTo,
+    references,
+    messageId,
+    threadId,
+    fromAddress: input.fromAddress,
+    fromName: input.fromName,
+    rawMessage,
+  }
+
+  return {
+    content: {
+      text,
+      html,
+      bodyFormat: input.bodyFormat,
+      attachments: input.attachments,
+      raw: {
+        subject,
+        to,
+        cc,
+        bcc,
+        inReplyTo,
+        references,
+        messageId,
+        threadId,
+      },
+    },
+    metadata: metadata as unknown as Record<string, unknown>,
+  }
+}

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

@@ -0,0 +1,90 @@
+import { z } from 'zod'
+
+/**
+ * Tenant-level OAuth client configuration. Stored on `IntegrationCredentials`
+ * for the `gmail` provider when the tenant has set up their own Google Cloud
+ * project. Per-user OAuth tokens layer on top via `userCredentialsSchema`.
+ */
+export const gmailClientCredentialsSchema = z
+  .object({
+    clientId: z.string().min(1, 'OAuth Client ID required'),
+    clientSecret: z.string().min(1, 'OAuth Client Secret required'),
+    /** Comma-separated scopes; blank uses defaults. */
+    scopes: z.string().optional(),
+  })
+  .strict()
+
+export type GmailClientCredentials = z.infer<typeof gmailClientCredentialsSchema>
+
+/**
+ * Per-user OAuth tokens stored on `CommunicationChannel.credentials` (encrypted).
+ * The hub injects the tenant client_id / client_secret at exchange/refresh time;
+ * the per-channel blob only persists the user-bound tokens.
+ */
+export const gmailUserCredentialsSchema = z
+  .object({
+    accessToken: z.string({ error: 'Access token required' }).min(1, 'Access token required'),
+    /**
+     * Gmail issues a refresh token only on the first consent. If the user
+     * re-authorises, Google does NOT send a new refresh token unless we pass
+     * `prompt=consent` and `access_type=offline`; we always do. We still mark
+     * the field optional so legacy migrations from accounts that never received
+     * one don't fail the schema — the runtime treats absence as "requires_reauth".
+     */
+    refreshToken: z.string().optional(),
+    /** ISO timestamp of access-token expiry. */
+    expiresAt: z.string().datetime().optional(),
+    /** Scopes that were actually granted (we may have requested a subset). */
+    scopes: z.array(z.string()).optional(),
+    /** Email address from the linked Google account. */
+    email: z.string().email().optional(),
+  })
+  .passthrough()
+
+export type GmailUserCredentials = z.infer<typeof gmailUserCredentialsSchema>
+
+/**
+ * Per-channel sync state stored on `CommunicationChannel.channelState`.
+ *
+ *   historyId — Gmail's per-mailbox monotonic cursor used by `history.list`
+ *               to fetch only changes since the previous poll. If history has
+ *               expired (Gmail keeps roughly 7 days), we fall back to a full
+ *               list using `gmail.users.messages.list`.
+ *
+ *   pendingHistoryPageToken — mid-drain resumption state when a single tick
+ *               can't ingest every page of `history.list` (e.g. a high-volume
+ *               mailbox returned more than our per-tick budget). The terminal
+ *               `historyId` is NOT advanced until the pages drain. The next tick
+ *               resumes via the stored `historyId` + this `pageToken`.
+ *
+ *   pendingMessagesPageToken / pendingMessagesHistoryIdSnapshot — same
+ *               contract for the 404-fallback path (`messages.list`).
+ *
+ * See https://developers.google.com/gmail/api/guides/sync for the contract.
+ */
+export const gmailChannelStateSchema = z
+  .object({
+    historyId: z.union([z.string(), z.number()]).optional(),
+    lastSyncedAt: z.string().datetime().optional(),
+    pendingHistoryPageToken: z.string().optional(),
+    pendingMessagesPageToken: z.string().optional(),
+    pendingMessagesHistoryIdSnapshot: z.string().optional(),
+  })
+  .partial()
+  .passthrough()
+
+export type GmailChannelState = z.infer<typeof gmailChannelStateSchema>
+
+export const GMAIL_DEFAULT_SCOPES = [
+  'https://www.googleapis.com/auth/gmail.modify',
+  'https://www.googleapis.com/auth/userinfo.email',
+  'https://www.googleapis.com/auth/userinfo.profile',
+]
+
+export function parseScopes(value: string | undefined): string[] {
+  if (!value || !value.trim()) return [...GMAIL_DEFAULT_SCOPES]
+  return value
+    .split(/[\s,]+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+}

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

@@ -0,0 +1,305 @@
+/**
+ * Thin Gmail REST API wrapper. Same trade-off as `oauth.ts`: we use `fetch`
+ * directly so the adapter doesn't import the `googleapis` SDK at runtime in
+ * environments that don't need it (tests, build-only checks). Production code
+ * paths still allow swapping to the SDK via `setGmailApiClient(...)` if a
+ * downstream package wants the SDK's extra ergonomics.
+ *
+ * Only the endpoints the adapter actually calls are exposed:
+ *   - listHistory      → gmail.users.history.list
+ *   - listMessages     → gmail.users.messages.list (fallback when historyId expired)
+ *   - getMessageRaw    → gmail.users.messages.get?format=raw
+ *   - sendRawMessage   → gmail.users.messages.send
+ *   - getProfile       → gmail.users.getProfile (health + initial historyId)
+ *   - deleteMessage    → gmail.users.messages.trash (move to trash; matches `deleteMessage: true` capability)
+ */
+
+const GMAIL_API_BASE = 'https://gmail.googleapis.com/gmail/v1'
+
+export interface GmailApiAuth {
+  accessToken: string
+}
+
+export interface GmailHistoryListInput {
+  startHistoryId: string
+  /** Optional page token for paging through history results. */
+  pageToken?: string
+  /** Optional label filter; defaults to INBOX-only changes. */
+  labelId?: string
+}
+
+export interface GmailHistoryRecord {
+  id: string
+  messagesAdded?: Array<{ message: { id: string; threadId: string; labelIds?: string[] } }>
+  messagesDeleted?: Array<{ message: { id: string; threadId: string } }>
+  labelsAdded?: Array<{ message: { id: string; threadId: string }; labelIds: string[] }>
+  labelsRemoved?: Array<{ message: { id: string; threadId: string }; labelIds: string[] }>
+}
+
+export interface GmailHistoryListResponse {
+  history?: GmailHistoryRecord[]
+  nextPageToken?: string
+  historyId: string
+}
+
+export interface GmailMessagesListInput {
+  query?: string
+  labelIds?: string[]
+  pageToken?: string
+  maxResults?: number
+}
+
+export interface GmailMessagesListResponse {
+  messages?: Array<{ id: string; threadId: string }>
+  nextPageToken?: string
+  resultSizeEstimate?: number
+}
+
+export interface GmailGetMessageRawResponse {
+  id: string
+  threadId: string
+  labelIds?: string[]
+  /** Base64URL-encoded RFC2822 message. */
+  raw: string
+  internalDate?: string
+  sizeEstimate?: number
+}
+
+export interface GmailSendRawInput {
+  /** Base64URL-encoded RFC2822 message body. */
+  rawBase64Url: string
+  /** Optional thread to attach to. */
+  threadId?: string
+}
+
+export interface GmailSendResponse {
+  id: string
+  threadId: string
+  labelIds?: string[]
+}
+
+export interface GmailProfileResponse {
+  emailAddress: string
+  messagesTotal?: number
+  threadsTotal?: number
+  historyId: string
+}
+
+export interface GmailWatchInput {
+  /** Fully-qualified Pub/Sub topic, e.g. `projects/myproj/topics/gmail-inbound`. */
+  topicName: string
+  /** Defaults to `['INBOX']` so only inbox changes generate notifications. */
+  labelIds?: string[]
+  /** `include` (default) or `exclude`. */
+  labelFilterAction?: 'include' | 'exclude'
+}
+
+export interface GmailWatchResponse {
+  historyId: string
+  /** Watch expiration timestamp, ms since epoch. Gmail caps at ~7 days. */
+  expiration: string
+}
+
+export interface GmailApiClient {
+  listHistory(auth: GmailApiAuth, input: GmailHistoryListInput): Promise<GmailHistoryListResponse>
+  listMessages(auth: GmailApiAuth, input: GmailMessagesListInput): Promise<GmailMessagesListResponse>
+  getMessageRaw(auth: GmailApiAuth, messageId: string): Promise<GmailGetMessageRawResponse>
+  sendRawMessage(auth: GmailApiAuth, input: GmailSendRawInput): Promise<GmailSendResponse>
+  getProfile(auth: GmailApiAuth): Promise<GmailProfileResponse>
+  trashMessage(auth: GmailApiAuth, messageId: string): Promise<void>
+  /** Spec C — `gmail.users.watch` registers a Pub/Sub topic for push delivery. */
+  watchInbox(auth: GmailApiAuth, input: GmailWatchInput): Promise<GmailWatchResponse>
+  /** Spec C — `gmail.users.stop` tears down the Pub/Sub registration. */
+  stopWatch(auth: GmailApiAuth): Promise<void>
+}
+
+const GMAIL_MAX_RETRIES = 3
+const GMAIL_BACKOFF_BASE_MS = 500
+const GMAIL_BACKOFF_CAP_MS = 8_000
+
+class FetchGmailApiClient implements GmailApiClient {
+  async listHistory(auth: GmailApiAuth, input: GmailHistoryListInput): Promise<GmailHistoryListResponse> {
+    const url = new URL(`${GMAIL_API_BASE}/users/me/history`)
+    url.searchParams.set('startHistoryId', input.startHistoryId)
+    if (input.pageToken) url.searchParams.set('pageToken', input.pageToken)
+    url.searchParams.set('labelId', input.labelId ?? 'INBOX')
+    url.searchParams.set('historyTypes', 'messageAdded')
+    return this.requestJson<GmailHistoryListResponse>(auth, url, 'GET')
+  }
+
+  async listMessages(auth: GmailApiAuth, input: GmailMessagesListInput): Promise<GmailMessagesListResponse> {
+    const url = new URL(`${GMAIL_API_BASE}/users/me/messages`)
+    if (input.query) url.searchParams.set('q', input.query)
+    for (const label of input.labelIds ?? []) url.searchParams.append('labelIds', label)
+    if (input.pageToken) url.searchParams.set('pageToken', input.pageToken)
+    if (input.maxResults) url.searchParams.set('maxResults', String(input.maxResults))
+    return this.requestJson<GmailMessagesListResponse>(auth, url, 'GET')
+  }
+
+  async getMessageRaw(auth: GmailApiAuth, messageId: string): Promise<GmailGetMessageRawResponse> {
+    const url = new URL(`${GMAIL_API_BASE}/users/me/messages/${encodeURIComponent(messageId)}`)
+    url.searchParams.set('format', 'raw')
+    return this.requestJson<GmailGetMessageRawResponse>(auth, url, 'GET')
+  }
+
+  async sendRawMessage(auth: GmailApiAuth, input: GmailSendRawInput): Promise<GmailSendResponse> {
+    const url = new URL(`${GMAIL_API_BASE}/users/me/messages/send`)
+    return this.requestJson<GmailSendResponse>(auth, url, 'POST', {
+      raw: input.rawBase64Url,
+      threadId: input.threadId,
+    })
+  }
+
+  async getProfile(auth: GmailApiAuth): Promise<GmailProfileResponse> {
+    const url = new URL(`${GMAIL_API_BASE}/users/me/profile`)
+    return this.requestJson<GmailProfileResponse>(auth, url, 'GET')
+  }
+
+  async trashMessage(auth: GmailApiAuth, messageId: string): Promise<void> {
+    const url = new URL(`${GMAIL_API_BASE}/users/me/messages/${encodeURIComponent(messageId)}/trash`)
+    await this.requestJson(auth, url, 'POST')
+  }
+
+  async watchInbox(auth: GmailApiAuth, input: GmailWatchInput): Promise<GmailWatchResponse> {
+    const url = new URL(`${GMAIL_API_BASE}/users/me/watch`)
+    return this.requestJson<GmailWatchResponse>(auth, url, 'POST', {
+      topicName: input.topicName,
+      labelIds: input.labelIds ?? ['INBOX'],
+      labelFilterAction: input.labelFilterAction ?? 'include',
+    })
+  }
+
+  async stopWatch(auth: GmailApiAuth): Promise<void> {
+    const url = new URL(`${GMAIL_API_BASE}/users/me/stop`)
+    await this.requestJson(auth, url, 'POST')
+  }
+
+  private async requestJson<T>(auth: GmailApiAuth, url: URL, method: 'GET' | 'POST', body?: unknown): Promise<T> {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${auth.accessToken}`,
+    }
+    let payload: BodyInit | undefined
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json'
+      payload = JSON.stringify(body)
+    }
+    // Retry transient failures (429, 5xx) with exponential backoff + jitter,
+    // honoring `Retry-After` when present. Per Gmail API docs at
+    // https://developers.google.com/gmail/api/guides/handle-errors this is the
+    // documented mitigation for rate-limit + server-side transient errors.
+    let attempt = 0
+    let lastError: GmailApiError | null = null
+    while (attempt <= GMAIL_MAX_RETRIES) {
+      const res = await fetch(url.toString(), { method, headers, body: payload })
+      const text = await res.text()
+      if (res.ok) {
+        if (!text) return undefined as unknown as T
+        return JSON.parse(text) as T
+      }
+      const detail = parseErrorMessage(text) ?? `${res.status} ${res.statusText}`
+      const apiError = new GmailApiError(
+        `Gmail API ${method} ${url.pathname} failed: ${detail}`,
+        res.status,
+        detail,
+      )
+      const transient =
+        res.status === 429 ||
+        (res.status >= 500 && res.status < 600) ||
+        // Gmail signals per-user/project quota exhaustion with HTTP 403 +
+        // `rateLimitExceeded`/`userRateLimitExceeded` (not only 429).
+        (res.status === 403 && isRateLimit403(text))
+      if (!transient || attempt === GMAIL_MAX_RETRIES) {
+        throw apiError
+      }
+      lastError = apiError
+      const retryAfterHeader = res.headers.get('retry-after')
+      const waitMs =
+        parseRetryAfter(retryAfterHeader) ?? computeBackoff(attempt)
+      await sleep(waitMs)
+      attempt += 1
+    }
+    throw lastError ?? new GmailApiError(`Gmail API ${method} ${url.pathname} exhausted retries`, 599, 'retries exhausted')
+  }
+}
+
+/**
+ * Gmail signals quota exhaustion with HTTP 403 + an error reason of
+ * `rateLimitExceeded` / `userRateLimitExceeded` (not only 429). Treat those as
+ * transient so the backoff/retry path applies; a genuine permission 403 (no
+ * rate-limit reason) stays non-retryable.
+ */
+function isRateLimit403(body: string): boolean {
+  return /rateLimitExceeded|userRateLimitExceeded/i.test(body)
+}
+
+function parseRetryAfter(value: string | null): number | null {
+  if (!value) return null
+  const asNumber = Number(value)
+  if (Number.isFinite(asNumber) && asNumber >= 0) {
+    return Math.min(asNumber * 1000, GMAIL_BACKOFF_CAP_MS)
+  }
+  const asDate = Date.parse(value)
+  if (Number.isFinite(asDate)) {
+    const delta = asDate - Date.now()
+    if (delta > 0) return Math.min(delta, GMAIL_BACKOFF_CAP_MS)
+  }
+  return null
+}
+
+function computeBackoff(attempt: number): number {
+  const raw = GMAIL_BACKOFF_BASE_MS * Math.pow(2, attempt)
+  const jitter = Math.floor(Math.random() * 100)
+  return Math.min(raw + jitter, GMAIL_BACKOFF_CAP_MS)
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+export class GmailApiError extends Error {
+  readonly status: number
+  readonly detail: string
+  constructor(message: string, status: number, detail: string) {
+    super(message)
+    this.name = 'GmailApiError'
+    this.status = status
+    this.detail = detail
+  }
+}
+
+function parseErrorMessage(text: string): string | null {
+  if (!text) return null
+  try {
+    const parsed = JSON.parse(text) as { error?: { message?: string } | string }
+    if (parsed && typeof parsed.error === 'object' && parsed.error && typeof parsed.error.message === 'string') {
+      return parsed.error.message
+    }
+    if (typeof parsed?.error === 'string') return parsed.error
+  } catch {
+    /* fall through */
+  }
+  return text.length > 200 ? text.slice(0, 200) : text
+}
+
+let cachedClient: GmailApiClient | null = null
+
+export function getGmailApiClient(): GmailApiClient {
+  if (!cachedClient) cachedClient = new FetchGmailApiClient()
+  return cachedClient
+}
+
+export function setGmailApiClient(client: GmailApiClient | null): void {
+  cachedClient = client
+}
+
+/** Encode an RFC2822 message buffer to base64url as required by gmail.users.messages.send. */
+export function encodeBase64Url(buffer: Buffer): string {
+  return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+/** Decode a base64url payload (e.g. `gmail.users.messages.get?format=raw`) to a buffer. */
+export function decodeBase64Url(value: string): Buffer {
+  const normalized = value.replace(/-/g, '+').replace(/_/g, '/')
+  const padding = normalized.length % 4 === 0 ? '' : '='.repeat(4 - (normalized.length % 4))
+  return Buffer.from(normalized + padding, 'base64')
+}

package/src/modules/channel_gmail/lib/health.ts

@@ -0,0 +1,14 @@
+import { makeClientConfigHealthCheck } from '@open-mercato/core/modules/communication_channels/lib/provider-health'
+import { gmailClientCredentialsSchema } from './credentials'
+
+/**
+ * Liveness probe for the Gmail integration. The hub resolves it by the service
+ * name declared in `integration.ts` (`channelGmailHealthCheck`) and passes the
+ * tenant-scoped OAuth client config (`clientId` / `clientSecret`), NOT per-user
+ * channel tokens — so the probe just confirms the client config is well-formed.
+ * Per-user token validity surfaces on the channel itself (`requires_reauth`).
+ */
+export const channelGmailHealthCheck = makeClientConfigHealthCheck({
+  schema: gmailClientCredentialsSchema,
+  providerLabel: 'Gmail',
+})

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

@@ -0,0 +1,57 @@
+import type { NormalizedInboundMessage } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import {
+  normalizeMimeInbound,
+  type ParsedMail,
+} from '@open-mercato/core/modules/communication_channels/lib/email-mime'
+
+/**
+ * Prefix for the hub conversation ref of a Gmail-threaded conversation; the raw
+ * Gmail `threadId` follows it. Single-sourced here (where the ref is formed) and
+ * re-used by the outbound converter to recover the thread id for replies.
+ */
+export const GMAIL_THREAD_REF_PREFIX = 'gmail-thread:'
+
+/**
+ * Convert a Gmail `messages.get?format=raw` response to the hub's canonical
+ * `NormalizedInboundMessage`. Gmail returns the full RFC2822 message base64url-encoded,
+ * so we parse with `mailparser` (same library the IMAP provider uses) and let the
+ * shared `normalizeMimeInbound` helper handle threading / attachments / headers,
+ * layering in Gmail-specific metadata (`threadId`, `labelIds`, Gmail message id).
+ *
+ * Threading uses Gmail's `threadId` (more reliable than In-Reply-To inside
+ * Gmail's mailbox).
+ */
+
+export interface NormalizeInboundGmailOptions {
+  rawMessage: Buffer
+  gmailMessageId: string
+  gmailThreadId: string
+  gmailLabelIds?: string[]
+  accountIdentifier: string
+  fallbackDate?: Date
+}
+
+export async function normalizeInboundGmailMessage(
+  options: NormalizeInboundGmailOptions,
+): Promise<NormalizedInboundMessage> {
+  const mailparser = (await import('mailparser')) as unknown as {
+    simpleParser: (buf: Buffer | string) => Promise<ParsedMail>
+  }
+  const parsed = await mailparser.simpleParser(options.rawMessage)
+
+  const gmailFields = {
+    gmailMessageId: options.gmailMessageId,
+    gmailThreadId: options.gmailThreadId,
+    gmailLabelIds: options.gmailLabelIds ?? [],
+  }
+  return normalizeMimeInbound({
+    parsed,
+    accountIdentifier: options.accountIdentifier,
+    fallbackMessageId: `gmail:${options.gmailMessageId}@${options.accountIdentifier}`,
+    // Gmail's threadId is authoritative for conversation grouping.
+    resolveConversationId: () => `${GMAIL_THREAD_REF_PREFIX}${options.gmailThreadId}`,
+    fallbackDate: options.fallbackDate,
+    channelMetadata: () => gmailFields,
+    channelPayload: () => gmailFields,
+  })
+}