@msgly/gmail 0.2.1

package/README.md

@@ -0,0 +1,241 @@
+# @msgly/gmail
+
+> Gmail adapter for [Msgly](https://github.com/AyushJain070401/msgly). Receive new messages as `hub.on('message')` events via Google Cloud Pub/Sub push, send threaded replies via the Gmail REST API. **Built for "agent on email channel" use cases — one bot mailbox, OAuth refresh token, pure WebCrypto.**
+
+## Scope (v1)
+
+This release ships **text-only send + receive** for a **single mailbox per adapter** (the bot's own inbox). It is the right shape for shared support inboxes, reply-bots, and agent automations on a dedicated mailbox.
+
+Out of scope for v1 — these are planned, but absent today:
+- Sending attachments / inline images
+- Surfacing inbound attachments as media (the body text comes through; attachment bytes are not extracted)
+- Multi-user mailbox routing (one adapter = one mailbox)
+- Reading historical mail (only push-triggered fetch)
+
+## Install
+
+```bash
+npm install @msgly/core @msgly/gmail
+```
+
+## How Gmail receive works
+
+Gmail does not push email bodies to webhooks. The flow is:
+
+1. You call `users.watch()` **once** with a Pub/Sub topic name. Gmail starts publishing notifications to that topic whenever the inbox changes.
+2. Your Pub/Sub push subscription forwards each event to your webhook (`<PUBLIC_URL>/webhook/gmail`). The payload contains `{ emailAddress, historyId }` — just the historyId, no message body.
+3. The adapter calls `users.history.list` from the previously-seen historyId, finds new message ids, fetches each via `users.messages.get?format=full`, and emits an inbound message per item.
+
+The "last seen historyId" is held in adapter memory. On first notification after process boot, the adapter falls back to fetching recent unread INBOX messages so nothing is lost across deploys.
+
+## Quick start
+
+```typescript
+import express from 'express';
+import { createHub } from '@msgly/core';
+import { createGmailAdapter } from '@msgly/gmail';
+
+const hub = createHub();
+
+hub.register(
+  createGmailAdapter({
+    clientId: process.env.GMAIL_CLIENT_ID!,
+    clientSecret: process.env.GMAIL_CLIENT_SECRET!,
+    refreshToken: process.env.GMAIL_REFRESH_TOKEN!,
+    emailAddress: process.env.GMAIL_EMAIL!,
+    pushAuth: {
+      kind: 'jwt',
+      expectedAudience: 'https://yourdomain.com/webhook/gmail',
+    },
+  }),
+);
+
+await hub.connect({ throwOnFailure: true });
+
+hub.on('message', async (msg) => {
+  if (msg.content.type === 'text') {
+    await hub.send({
+      channel: 'gmail',
+      account: msg.account,
+      contact: msg.contact,
+      content: { type: 'text', text: `Auto-reply: I received "${msg.content.text}"` },
+      // Thread the reply onto the original conversation.
+      metadata: {
+        threadId: msg.metadata?.threadId,
+        messageId: msg.metadata?.messageId,
+        subject: msg.metadata?.subject,
+        references: msg.metadata?.references,
+      },
+    });
+  }
+});
+
+const app = express();
+app.use(express.json({ verify: (req, _r, buf) => ((req as any).rawBody = new Uint8Array(buf)) }));
+
+const handlers = hub.createWebhookHandler();
+app.post('/webhook/:channel', handlers.post);
+
+app.listen(3000);
+```
+
+## Config
+
+```typescript
+interface GmailConfig {
+  /** OAuth client (Google Cloud Console → Credentials → OAuth 2.0 Client ID). */
+  clientId: string;
+  clientSecret: string;
+  /**
+   * Long-lived refresh token for the agent mailbox. Run the OAuth consent
+   * flow once with `prompt=consent&access_type=offline` to obtain.
+   */
+  refreshToken: string;
+  /** The mailbox email (used as From: and account.channelAccountId). */
+  emailAddress: string;
+
+  /** How to verify inbound Pub/Sub webhooks. Pick one. */
+  pushAuth:
+    | { kind: 'jwt'; expectedAudience: string; expectedServiceAccountEmail?: string }
+    | { kind: 'token'; token: string }
+    | { kind: 'none' };  // dev only — DO NOT use in production
+
+  maxMessagesPerNotification?: number;  // default 25
+  // overrides for testing / private clouds:
+  tokenUrl?: string;
+  apiBase?: string;
+  jwksUrl?: string;
+  clockSkewSec?: number;  // default 300
+}
+```
+
+## Setup (one-time, ~30 minutes)
+
+The setup is more involved than the chat channels because Pub/Sub needs to be wired up. Walk through it once and the runtime is just two env vars + a webhook URL.
+
+### 1. Create an OAuth client
+
+[Google Cloud Console](https://console.cloud.google.com/apis/credentials):
+
+- **APIs & Services → Library** → enable **Gmail API**
+- **APIs & Services → OAuth consent screen** → External or Internal — fill in basics, add scope `https://www.googleapis.com/auth/gmail.modify`. Add the bot's email as a test user.
+- **Credentials → Create credentials → OAuth client ID** → Web application → add `http://localhost:8080/oauth-callback` (or whatever you'll use) as a redirect URI
+- Copy **Client ID** → `GMAIL_CLIENT_ID`
+- Copy **Client secret** → `GMAIL_CLIENT_SECRET`
+
+### 2. Get a refresh token for the agent mailbox
+
+Run the consent flow once. Quickest path locally:
+
+```bash
+# Open in your browser, signed in as the agent mailbox:
+https://accounts.google.com/o/oauth2/v2/auth\
+?client_id=YOUR_CLIENT_ID\
+&response_type=code\
+&scope=https://www.googleapis.com/auth/gmail.modify\
+&redirect_uri=http://localhost:8080/oauth-callback\
+&access_type=offline\
+&prompt=consent
+```
+
+After consenting, you'll be redirected to your localhost URL with `?code=...`. Exchange that code for a refresh token:
+
+```bash
+curl https://oauth2.googleapis.com/token \
+  -d code=THE_CODE \
+  -d client_id=$GMAIL_CLIENT_ID \
+  -d client_secret=$GMAIL_CLIENT_SECRET \
+  -d redirect_uri=http://localhost:8080/oauth-callback \
+  -d grant_type=authorization_code
+```
+
+Copy `refresh_token` from the JSON response → `GMAIL_REFRESH_TOKEN`.
+
+> Note: Google issues a refresh token **only on the first consent**. If you need to re-issue, revoke the app at [myaccount.google.com/permissions](https://myaccount.google.com/permissions) and consent again.
+
+### 3. Create the Pub/Sub topic and subscription
+
+In the same Google Cloud project:
+
+- **Pub/Sub → Topics → Create topic** — name it `gmail-inbox` (or anything).
+- On the topic → **Permissions** → **Add principal** → `gmail-api-push@system.gserviceaccount.com` → role `Pub/Sub Publisher`. **This is what lets Gmail publish into your topic.**
+- **Subscriptions → Create subscription** on that topic:
+  - Delivery type: **Push**
+  - Endpoint: `<PUBLIC_URL>/webhook/gmail`
+  - **Authentication** (recommended): tick "Enable authentication", create or pick a service account, and set audience to `<PUBLIC_URL>/webhook/gmail` (this matches `pushAuth.expectedAudience` in your config).
+  - Or simpler-but-less-secure: append `?token=YOUR_RANDOM_SECRET` to the endpoint URL and use `pushAuth: { kind: 'token', token: '...' }` instead.
+
+### 4. Call `watch()` on the mailbox
+
+Once at deploy time (and on a periodic schedule — watches expire after ~7 days):
+
+```typescript
+const adapter = createGmailAdapter({ /* ... */ });
+hub.register(adapter);
+
+await adapter.watch('projects/your-project-id/topics/gmail-inbox');
+// Returns { historyId } — the baseline.
+```
+
+Schedule a cron to call `watch()` daily so the subscription never expires.
+
+### 5. Test
+
+Send an email to the agent mailbox from another account. Your `hub.on('message')` handler should receive it.
+
+## Inbound shape
+
+| Email field           | msgly mapping                                         |
+| --------------------- | ----------------------------------------------------- |
+| From `<addr>`         | `contact.channelUserId`                               |
+| From "Name"           | `contact.displayName`                                 |
+| To (bot's address)    | `account.channelAccountId`                            |
+| text/plain body       | `content.text`                                        |
+| Subject               | `metadata.subject`                                    |
+| Message-ID            | `metadata.messageId`                                  |
+| Gmail threadId        | `metadata.threadId`                                   |
+| References            | `metadata.references`                                 |
+| internalDate          | `timestamp`                                           |
+
+When inbound has only HTML, the adapter strips tags into a best-effort plain-text body. Attachments are not yet surfaced as `MediaContent` (planned for v2).
+
+## Reply path
+
+Pass any combination of these through `metadata` and the adapter does the right thing:
+
+| metadata field    | Effect on outbound                                           |
+| ----------------- | ------------------------------------------------------------ |
+| `threadId`        | Sent in the API call body — Gmail keeps the reply in-thread. |
+| `messageId`       | Becomes the `In-Reply-To` header on the outgoing email.      |
+| `references`      | Becomes the `References` header (chain preservation).        |
+| `subject`         | Used (with auto `Re:` prefix) as the reply subject.          |
+
+Without any of these, the adapter still sends — just as a fresh email with subject `(no subject)` to the contact address.
+
+## Capabilities
+
+| Feature       | Supported |
+| ------------- | --------- |
+| text          | ✓         |
+| image / video / audio / file | — (v2) |
+| location      | —         |
+| buttons       | —         |
+| reactions     | —         |
+| typing        | —         |
+| templates     | —         |
+
+## Common pitfalls
+
+- **No notifications arriving**: confirm the Pub/Sub topic grants `gmail-api-push@system.gserviceaccount.com` publish access. Confirm `users.watch()` returned a `historyId` (didn't error). Watches expire after ~7 days — schedule a daily re-call.
+- **`401 unauthorized` on the webhook**: if you used `pushAuth: { kind: 'jwt' }`, the Pub/Sub subscription must have authentication enabled and the audience must match `expectedAudience` exactly (case-sensitive, no trailing slash mismatch).
+- **`invalid_grant` from the token endpoint**: refresh token revoked or never had `access_type=offline`. Re-run consent with `prompt=consent`.
+- **Inbound shows wrong sender**: this adapter parses `From:` as `"Name" <addr>` or bare address. Exotic header forms (group syntax, etc.) fall back to the raw header — file a bug if you hit one.
+- **Reply doesn't thread correctly in some clients**: pass through both `metadata.threadId` AND `metadata.messageId`. Gmail uses threadId; other clients honor In-Reply-To.
+
+## Documentation
+
+Full multi-channel docs: https://github.com/AyushJain070401/msgly
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import { Adapter } from '@msgly/core';
+
+interface GmailConfig {
+    /** OAuth client id from Google Cloud Console → Credentials → OAuth 2.0 Client ID. */
+    clientId: string;
+    /** OAuth client secret from the same place. */
+    clientSecret: string;
+    /**
+     * Long-lived refresh token for the agent's mailbox. Generated once via the
+     * OAuth 2.0 consent flow with `prompt=consent` and `access_type=offline`.
+     * Required scopes: `https://www.googleapis.com/auth/gmail.modify` (read +
+     * send + watch).
+     */
+    refreshToken: string;
+    /**
+     * The email address of the mailbox the refresh token belongs to.
+     * Used as the `From:` header on outgoing replies and as
+     * `account.channelAccountId`.
+     */
+    emailAddress: string;
+    /**
+     * How Pub/Sub push requests prove they came from Google. Pick ONE:
+     *
+     *   { kind: 'jwt', expectedAudience }
+     *     — Verify the OIDC JWT in `Authorization: Bearer <token>`.
+     *       expectedAudience should match the audience you configured on the
+     *       Pub/Sub push subscription (often the webhook URL itself).
+     *
+     *   { kind: 'token', token }
+     *     — Simpler: configure your push subscription with
+     *       `?token=...` and we'll match it against `req.query.token`.
+     *
+     *   { kind: 'none' } — DEV ONLY. No verification.
+     */
+    pushAuth: {
+        kind: 'jwt';
+        expectedAudience: string;
+        expectedServiceAccountEmail?: string;
+    } | {
+        kind: 'token';
+        token: string;
+    } | {
+        kind: 'none';
+    };
+    /** Cap how many messages we fetch per Pub/Sub notification. Default: 25. */
+    maxMessagesPerNotification?: number;
+    /** Override the Google OAuth token endpoint. Default: oauth2.googleapis.com. */
+    tokenUrl?: string;
+    /** Override the Gmail API base. Default: gmail.googleapis.com. */
+    apiBase?: string;
+    /** Override the JWKS URL used when `pushAuth.kind === 'jwt'`. Default: Google certs. */
+    jwksUrl?: string;
+    /** Allowed clock skew (sec) when validating JWT exp/nbf. Default: 300. */
+    clockSkewSec?: number;
+}
+interface GmailAdapter extends Adapter {
+    readonly channel: 'gmail';
+    /**
+     * Call once at deploy time to subscribe the mailbox to a Pub/Sub topic.
+     * The topic must already grant publish permission to
+     * `gmail-api-push@system.gserviceaccount.com`. Returns the historyId
+     * baseline.
+     */
+    watch(topicName: string, labelIds?: string[]): Promise<{
+        historyId: string;
+    }>;
+    /** Stop the existing watch. Mailbox stops emitting notifications. */
+    stopWatch(): Promise<void>;
+}
+/**
+ * Gmail adapter for Msgly — receives via Pub/Sub push notifications,
+ * sends via the Gmail REST API.
+ *
+ * **Receive flow.** Gmail publishes change notifications to a Pub/Sub topic
+ * (you set this up once via `users.watch`). Pub/Sub forwards each event to
+ * your webhook with body `{ message: { data: base64, ... }, subscription }`.
+ * `data` decodes to `{ emailAddress, historyId }`. The adapter calls
+ * `history.list` from the previously-seen historyId to discover new message
+ * IDs, fetches each via `messages.get?format=full`, and emits an inbound
+ * message per item.
+ *
+ * **State.** The "last seen historyId" is held in adapter memory. On the
+ * very first notification (cold start), the adapter falls back to fetching
+ * recent unread INBOX messages so nothing gets lost between deploys.
+ *
+ * **Send flow.** Builds an RFC 5322 email with proper In-Reply-To /
+ * References headers and posts to `users.messages.send`. If you pass
+ * `metadata.threadId` from the inbound message, Gmail keeps the reply in
+ * the original thread.
+ *
+ * **Auth.** Pub/Sub authenticates inbound webhooks via OIDC JWT
+ * (Authorization: Bearer) or a shared verification token, configurable via
+ * `pushAuth`. JWT verification uses Google's public JWKS and runs on pure
+ * WebCrypto (Node 18+, Bun, Deno, browsers).
+ */
+declare function createGmailAdapter(config: GmailConfig): GmailAdapter;
+
+export { type GmailAdapter, type GmailConfig, createGmailAdapter };

package/dist/index.js

@@ -0,0 +1,507 @@
+// src/index.ts
+var DEFAULT_TOKEN_URL = "https://oauth2.googleapis.com/token";
+var DEFAULT_API_BASE = "https://gmail.googleapis.com";
+var DEFAULT_JWKS_URL = "https://www.googleapis.com/oauth2/v3/certs";
+var DEFAULT_CLOCK_SKEW_SEC = 300;
+var DEFAULT_MAX_MESSAGES = 25;
+var CAPABILITIES = {
+  text: true,
+  media: { image: false, video: false, audio: false, file: false },
+  interactive: { buttons: false, quickReplies: false },
+  templates: false,
+  reactions: false,
+  typing: false
+};
+function randomId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function headerValue(headers, name) {
+  const v = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(v)) return v[0];
+  return v;
+}
+function b64urlEncode(input) {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/=+$/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function b64urlDecodeToBytes(input) {
+  const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, "=");
+  const binary = atob(padded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function b64urlDecodeToString(input) {
+  return new TextDecoder().decode(b64urlDecodeToBytes(input));
+}
+function createJwksCache(jwksUrl, ttlMs) {
+  let cache = null;
+  let inflight = null;
+  async function load(force = false) {
+    if (!force && cache && Date.now() - cache.fetchedAt < ttlMs) return cache;
+    if (inflight) return inflight;
+    inflight = (async () => {
+      const res = await fetch(jwksUrl);
+      if (!res.ok) throw new Error(`JWKS fetch failed: ${res.status}`);
+      const data = await res.json();
+      const keys = /* @__PURE__ */ new Map();
+      for (const jwk of data.keys ?? []) {
+        if (!jwk.kid || jwk.kty !== "RSA") continue;
+        try {
+          const key = await globalThis.crypto.subtle.importKey(
+            "jwk",
+            jwk,
+            { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+            false,
+            ["verify"]
+          );
+          keys.set(jwk.kid, key);
+        } catch {
+        }
+      }
+      const entry = { keys, fetchedAt: Date.now() };
+      cache = entry;
+      return entry;
+    })();
+    try {
+      return await inflight;
+    } finally {
+      inflight = null;
+    }
+  }
+  async function getKey(kid) {
+    let jwks = await load();
+    if (jwks.keys.has(kid)) return jwks.keys.get(kid);
+    jwks = await load(true);
+    return jwks.keys.get(kid) ?? null;
+  }
+  return { getKey };
+}
+async function verifyGoogleJwt(token, getKey, expectedAudience, expectedServiceAccountEmail, clockSkewSec) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return false;
+  const [headerB64, payloadB64, sigB64] = parts;
+  let header;
+  let claims;
+  try {
+    header = JSON.parse(b64urlDecodeToString(headerB64));
+    claims = JSON.parse(b64urlDecodeToString(payloadB64));
+  } catch {
+    return false;
+  }
+  if (header.alg !== "RS256" || !header.kid) return false;
+  const key = await getKey(header.kid);
+  if (!key) return false;
+  const signature = b64urlDecodeToBytes(sigB64);
+  const signedInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+  const ok = await globalThis.crypto.subtle.verify(
+    "RSASSA-PKCS1-v1_5",
+    key,
+    signature,
+    signedInput
+  );
+  if (!ok) return false;
+  const nowSec = Math.floor(Date.now() / 1e3);
+  if (typeof claims.exp === "number" && nowSec > claims.exp + clockSkewSec) return false;
+  if (typeof claims.nbf === "number" && nowSec + clockSkewSec < claims.nbf) return false;
+  if (claims.iss !== "https://accounts.google.com" && claims.iss !== "accounts.google.com") {
+    return false;
+  }
+  if (claims.aud !== expectedAudience) return false;
+  if (expectedServiceAccountEmail && claims.email !== expectedServiceAccountEmail) {
+    return false;
+  }
+  return true;
+}
+function createTokenCache(tokenUrl, clientId, clientSecret, refreshToken) {
+  let accessToken = null;
+  let expiresAt = 0;
+  let inflight = null;
+  async function fetchToken() {
+    const res = await fetch(tokenUrl, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: clientId,
+        client_secret: clientSecret,
+        refresh_token: refreshToken
+      }).toString()
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok || !data.access_token) {
+      throw new Error(
+        `Google token refresh failed (${res.status}): ${data.error_description ?? data.error ?? "no body"}`
+      );
+    }
+    accessToken = data.access_token;
+    expiresAt = Date.now() + (data.expires_in ?? 3600) * 1e3 - 6e4;
+    return accessToken;
+  }
+  async function get() {
+    if (accessToken && Date.now() < expiresAt) return accessToken;
+    if (inflight) return inflight;
+    inflight = fetchToken();
+    try {
+      return await inflight;
+    } finally {
+      inflight = null;
+    }
+  }
+  return { get };
+}
+function findHeader(payload, name) {
+  const lower = name.toLowerCase();
+  for (const h of payload?.headers ?? []) {
+    if (h.name.toLowerCase() === lower) return h.value;
+  }
+  return void 0;
+}
+function findBodyByMimeType(payload, mimeType) {
+  if (!payload) return null;
+  if (payload.mimeType === mimeType && payload.body?.data) {
+    try {
+      return b64urlDecodeToString(payload.body.data);
+    } catch {
+      return null;
+    }
+  }
+  for (const part of payload.parts ?? []) {
+    const t = findBodyByMimeType(part, mimeType);
+    if (t !== null) return t;
+  }
+  return null;
+}
+function extractPlainText(payload) {
+  const plain = findBodyByMimeType(payload, "text/plain");
+  if (plain !== null) return plain.trim() || null;
+  const html = findBodyByMimeType(payload, "text/html");
+  if (html === null) return null;
+  return html.replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim() || null;
+}
+function parseEmailAddress(header) {
+  if (!header) return null;
+  const trimmed = header.trim();
+  const angle = trimmed.match(/^(?:"?([^"<]+?)"?\s*)?<([^>]+)>$/);
+  if (angle) {
+    return {
+      address: angle[2].trim(),
+      displayName: angle[1]?.trim() || void 0
+    };
+  }
+  if (/^\S+@\S+$/.test(trimmed)) return { address: trimmed };
+  return null;
+}
+function buildReplyEmail(opts) {
+  const headers = [
+    `From: ${opts.from}`,
+    `To: ${opts.to}`,
+    `Subject: ${opts.subject}`,
+    "MIME-Version: 1.0",
+    "Content-Type: text/plain; charset=utf-8",
+    "Content-Transfer-Encoding: 8bit",
+    `Date: ${(/* @__PURE__ */ new Date()).toUTCString()}`
+  ];
+  if (opts.inReplyTo) headers.push(`In-Reply-To: ${opts.inReplyTo}`);
+  if (opts.references) headers.push(`References: ${opts.references}`);
+  return `${headers.join("\r\n")}\r
+\r
+${opts.body}`;
+}
+function stripReplyPrefix(subject) {
+  return subject.replace(/^(?:re|RE|Re)\s*:\s*/i, "").trim();
+}
+function createGmailAdapter(config) {
+  const tokenUrl = config.tokenUrl ?? DEFAULT_TOKEN_URL;
+  const apiBase = config.apiBase ?? DEFAULT_API_BASE;
+  const jwksUrl = config.jwksUrl ?? DEFAULT_JWKS_URL;
+  const clockSkewSec = config.clockSkewSec ?? DEFAULT_CLOCK_SKEW_SEC;
+  const maxMessages = config.maxMessagesPerNotification ?? DEFAULT_MAX_MESSAGES;
+  const tokens = createTokenCache(tokenUrl, config.clientId, config.clientSecret, config.refreshToken);
+  const jwks = createJwksCache(jwksUrl, 24 * 60 * 60 * 1e3);
+  let lastHistoryId = null;
+  async function authedFetch(path, init = {}) {
+    const token = await tokens.get();
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${token}`);
+    if (!headers.has("content-type") && init.body) {
+      headers.set("content-type", "application/json");
+    }
+    return fetch(`${apiBase}${path}`, { ...init, headers });
+  }
+  async function watch(topicName, labelIds = ["INBOX"]) {
+    const res = await authedFetch("/gmail/v1/users/me/watch", {
+      method: "POST",
+      body: JSON.stringify({ topicName, labelIds, labelFilterAction: "include" })
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok || !data.historyId) {
+      throw new Error(`Gmail watch failed (${res.status}): ${data.error?.message ?? "no historyId"}`);
+    }
+    lastHistoryId = data.historyId;
+    return { historyId: data.historyId };
+  }
+  async function stopWatch() {
+    await authedFetch("/gmail/v1/users/me/stop", { method: "POST" });
+  }
+  async function fetchMessage(messageId) {
+    const res = await authedFetch(
+      `/gmail/v1/users/me/messages/${encodeURIComponent(messageId)}?format=full`
+    );
+    if (!res.ok) return null;
+    return await res.json();
+  }
+  async function listRecentInboxMessageIds(limit) {
+    const res = await authedFetch(
+      `/gmail/v1/users/me/messages?maxResults=${limit}&q=${encodeURIComponent("in:inbox -in:drafts is:unread")}`
+    );
+    if (!res.ok) return [];
+    const data = await res.json();
+    return (data.messages ?? []).map((m) => m.id);
+  }
+  async function listMessageIdsSince(startHistoryId) {
+    const res = await authedFetch(
+      `/gmail/v1/users/me/history?startHistoryId=${encodeURIComponent(startHistoryId)}&historyTypes=messageAdded&labelId=INBOX`
+    );
+    if (!res.ok) return [];
+    const data = await res.json();
+    const ids = /* @__PURE__ */ new Set();
+    for (const entry of data.history ?? []) {
+      for (const added of entry.messagesAdded ?? []) {
+        if (added.message?.id) ids.add(added.message.id);
+      }
+    }
+    return [...ids].slice(0, maxMessages);
+  }
+  function messageToInbound(msg) {
+    const text = extractPlainText(msg.payload);
+    if (!text) return null;
+    const from = parseEmailAddress(findHeader(msg.payload, "From"));
+    if (!from) return null;
+    const messageIdHeader = findHeader(msg.payload, "Message-ID") ?? findHeader(msg.payload, "Message-Id");
+    const subject = findHeader(msg.payload, "Subject") ?? "";
+    const references = findHeader(msg.payload, "References");
+    const dateHeader = findHeader(msg.payload, "Date");
+    const timestamp = (() => {
+      if (msg.internalDate) {
+        const ms = Number(msg.internalDate);
+        if (Number.isFinite(ms)) return new Date(ms).toISOString();
+      }
+      if (dateHeader) {
+        const parsed = Date.parse(dateHeader);
+        if (Number.isFinite(parsed)) return new Date(parsed).toISOString();
+      }
+      return (/* @__PURE__ */ new Date()).toISOString();
+    })();
+    return {
+      id: randomId(),
+      externalId: msg.id,
+      channel: "gmail",
+      direction: "inbound",
+      account: { channel: "gmail", channelAccountId: config.emailAddress },
+      contact: {
+        channel: "gmail",
+        channelUserId: from.address,
+        ...from.displayName ? { displayName: from.displayName } : {}
+      },
+      content: { type: "text", text },
+      timestamp,
+      raw: msg,
+      metadata: {
+        ...msg.threadId ? { threadId: msg.threadId } : {},
+        ...messageIdHeader ? { messageId: messageIdHeader } : {},
+        ...subject ? { subject } : {},
+        ...references ? { references } : {}
+      }
+    };
+  }
+  async function handleWebhook(req) {
+    const body = req.body;
+    const dataB64 = body?.message?.data;
+    if (!dataB64) return [];
+    let notification;
+    try {
+      notification = JSON.parse(b64urlDecodeToString(dataB64.replace(/=+$/g, "")));
+    } catch {
+      return [];
+    }
+    if (!notification.historyId) return [];
+    let messageIds;
+    if (lastHistoryId) {
+      messageIds = await listMessageIdsSince(lastHistoryId);
+    } else {
+      messageIds = await listRecentInboxMessageIds(maxMessages);
+    }
+    lastHistoryId = notification.historyId;
+    const out = [];
+    for (const id of messageIds) {
+      const msg = await fetchMessage(id);
+      if (!msg) continue;
+      const inbound = messageToInbound(msg);
+      if (inbound) out.push(inbound);
+    }
+    return out;
+  }
+  async function verifySignature(req) {
+    switch (config.pushAuth.kind) {
+      case "none":
+        return true;
+      case "token": {
+        const provided = req.query["token"];
+        const value = Array.isArray(provided) ? provided[0] : provided;
+        return value === config.pushAuth.token;
+      }
+      case "jwt": {
+        const auth = headerValue(req.headers, "authorization");
+        if (!auth || !auth.toLowerCase().startsWith("bearer ")) return false;
+        const token = auth.slice(7).trim();
+        if (!token) return false;
+        try {
+          return await verifyGoogleJwt(
+            token,
+            (kid) => jwks.getKey(kid),
+            config.pushAuth.expectedAudience,
+            config.pushAuth.expectedServiceAccountEmail,
+            clockSkewSec
+          );
+        } catch {
+          return false;
+        }
+      }
+    }
+  }
+  async function send(message) {
+    if (message.content.type !== "text") {
+      return {
+        messageId: message.id,
+        status: "failed",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        error: {
+          code: "gmail_unsupported_content",
+          message: `Gmail adapter only supports text content in v1 (received: ${message.content.type})`
+        }
+      };
+    }
+    const subjectMeta = message.metadata?.["subject"];
+    const baseSubject = subjectMeta ? stripReplyPrefix(subjectMeta) : "";
+    const subject = baseSubject ? `Re: ${baseSubject}` : "(no subject)";
+    const inReplyTo = message.metadata?.["messageId"];
+    const referencesPrev = message.metadata?.["references"];
+    const references = inReplyTo ? referencesPrev ? `${referencesPrev} ${inReplyTo}` : inReplyTo : void 0;
+    const raw = buildReplyEmail({
+      from: config.emailAddress,
+      to: message.contact.channelUserId,
+      subject,
+      body: message.content.text,
+      inReplyTo,
+      references
+    });
+    const payload = { raw: b64urlEncode(raw) };
+    const threadId = message.metadata?.["threadId"];
+    if (threadId) payload["threadId"] = threadId;
+    const res = await authedFetch("/gmail/v1/users/me/messages/send", {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+    const data = await res.json().catch(() => ({}));
+    if (res.status >= 200 && res.status < 300 && data.id) {
+      return {
+        messageId: message.id,
+        externalId: data.id,
+        status: "sent",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+    return {
+      messageId: message.id,
+      status: "failed",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      error: {
+        code: `gmail_${data.error?.code ?? res.status}`,
+        message: data.error?.message ?? `HTTP ${res.status}`
+      }
+    };
+  }
+  async function verifyCredentials() {
+    if (!config.clientId || !config.clientSecret) {
+      return {
+        ok: false,
+        reason: "unauthorized",
+        hint: "GmailConfig.clientId / clientSecret missing. Generate them in Google Cloud Console \u2192 APIs & Services \u2192 Credentials \u2192 OAuth 2.0 Client ID."
+      };
+    }
+    if (!config.refreshToken) {
+      return {
+        ok: false,
+        reason: "unauthorized",
+        hint: "GmailConfig.refreshToken missing. Run the consent flow once with prompt=consent and access_type=offline to obtain a long-lived refresh token."
+      };
+    }
+    if (!config.emailAddress) {
+      return {
+        ok: false,
+        reason: "unauthorized",
+        hint: "GmailConfig.emailAddress missing. Set this to the mailbox the refresh token belongs to (e.g. agent@yourcompany.com)."
+      };
+    }
+    try {
+      const token = await tokens.get();
+      const res = await fetch(`${apiBase}/gmail/v1/users/me/profile`, {
+        headers: { authorization: `Bearer ${token}` }
+      });
+      if (res.status === 401 || res.status === 403) {
+        return {
+          ok: false,
+          reason: "unauthorized",
+          hint: "Google rejected the access token. Check scopes (need gmail.modify) and re-run consent with prompt=consent."
+        };
+      }
+      if (!res.ok) {
+        return {
+          ok: false,
+          reason: "unknown",
+          hint: `Gmail profile lookup returned ${res.status}`
+        };
+      }
+      const data = await res.json();
+      return { ok: true, accountInfo: data.emailAddress ?? config.emailAddress };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/401|invalid_grant|invalid_client/i.test(msg)) {
+        return {
+          ok: false,
+          reason: "unauthorized",
+          hint: `Google rejected credentials: ${msg}. Re-check clientId/clientSecret/refreshToken.`
+        };
+      }
+      return { ok: false, reason: "network_error", hint: msg };
+    }
+  }
+  async function uploadMedia(_file) {
+    throw new Error("Gmail uploadMedia is not yet implemented in v1.");
+  }
+  async function downloadMedia(_ref) {
+    throw new Error("Gmail downloadMedia is not yet implemented in v1.");
+  }
+  return {
+    channel: "gmail",
+    capabilities: CAPABILITIES,
+    send,
+    handleWebhook,
+    verifySignature,
+    verifyCredentials,
+    uploadMedia,
+    downloadMedia,
+    watch,
+    stopWatch
+  };
+}
+export {
+  createGmailAdapter
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@msgly/gmail",
+  "version": "0.2.1",
+  "description": "Gmail adapter for Msgly — receive and reply to emails via Gmail API + Pub/Sub push",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@msgly/core": "0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AyushJain070401/msgly.git",
+    "directory": "packages/adapter-gmail"
+  },
+  "keywords": [
+    "gmail",
+    "email",
+    "google",
+    "pubsub",
+    "agent",
+    "messaging",
+    "webhook"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}