@assembly-js/app-foundation 0.0.15 → 0.0.16

package/dist/gmail.d.ts

@@ -0,0 +1,38 @@
+import { type IntegrationClient } from './nango.js';
+export interface GmailSendArgs {
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject: string;
+    /** Plain-text body. At least one of text/html is required. */
+    text?: string;
+    /** HTML body. With both, the message is multipart/alternative. */
+    html?: string;
+    replyTo?: string;
+    /** Gmail thread to append to — take it from a previous send's result. */
+    threadId?: string;
+    /**
+     * Message-ID of the message being replied to. threadId only threads inside
+     * Gmail; recipients' mail clients thread on In-Reply-To/References.
+     */
+    inReplyTo?: string;
+}
+export interface GmailSendResult {
+    id: string;
+    threadId: string;
+}
+export declare function buildMimeMessage(args: GmailSendArgs): string;
+/**
+ * Send an email through the workspace's Gmail connection. Use this instead of
+ * calling the send-message action yourself: it builds the RFC 2822 MIME
+ * message (multipart/alternative when both text and html are given, RFC 2047
+ * subject encoding, CRLF line endings) and base64url-encodes it into `raw`.
+ *
+ * Gmail sends from the connected account; there is no `from` override. To
+ * reply on an existing thread pass `threadId` from a previous send's result —
+ * and `inReplyTo` (the original Message-ID) so recipients' clients thread too.
+ *
+ * Broker-level failures (provider not connected, throttled) throw
+ * ConnectorError like every other connector call.
+ */
+export declare function gmailSendEmail(gmail: IntegrationClient, args: GmailSendArgs): Promise<GmailSendResult>;

package/dist/gmail.js

@@ -0,0 +1,137 @@
+const CRLF = '\r\n';
+// RFC 2045 caps encoded body lines at 76 characters.
+const MIME_LINE_LENGTH = 76;
+// Addresses and message ids are interpolated into headers verbatim, so a value
+// carrying CR/LF (or another control char) would inject arbitrary headers —
+// e.g. a user-supplied "a@x.com\r\nBcc: …". Reject instead of sanitizing so the
+// caller surfaces the bad input. (Subjects are exempt: encodeHeaderValue
+// base64-encodes anything outside printable ASCII.)
+function assertNoControlChars(value, field) {
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(value)) {
+        throw new Error(`gmailSendEmail: \`${field}\` contains control characters`);
+    }
+    return value;
+}
+function toList(value, field) {
+    if (value === undefined)
+        return [];
+    return (Array.isArray(value) ? value : [value])
+        .map((addr) => assertNoControlChars(addr.trim(), field))
+        .filter(Boolean);
+}
+function base64Encode(bytes) {
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+function base64Url(bytes) {
+    return base64Encode(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function utf8(value) {
+    return new TextEncoder().encode(value);
+}
+// RFC 2047 caps each encoded-word at 75 characters. "=?UTF-8?B?" + "?=" is 12,
+// leaving 63 base64 chars = 45 source bytes per word.
+const ENCODED_WORD_BYTE_LIMIT = 45;
+// RFC 2047 encoded-word(s) for header values; ASCII-only values pass through.
+// Long values fold into multiple words joined by CRLF + space — decoders
+// concatenate adjacent encoded-words, dropping the whitespace between them.
+// Chunks break on UTF-8 sequence boundaries since each word decodes alone.
+function encodeHeaderValue(value) {
+    // eslint-disable-next-line no-control-regex
+    if (/^[\x20-\x7e]*$/.test(value))
+        return value;
+    const bytes = utf8(value);
+    const words = [];
+    let start = 0;
+    while (start < bytes.length) {
+        let end = Math.min(start + ENCODED_WORD_BYTE_LIMIT, bytes.length);
+        while (end < bytes.length && (bytes[end] & 0xc0) === 0x80)
+            end--;
+        words.push(`=?UTF-8?B?${base64Encode(bytes.subarray(start, end))}?=`);
+        start = end;
+    }
+    return words.join(`${CRLF} `);
+}
+function wrapBase64(encoded) {
+    const lines = [];
+    for (let i = 0; i < encoded.length; i += MIME_LINE_LENGTH) {
+        lines.push(encoded.slice(i, i + MIME_LINE_LENGTH));
+    }
+    return lines.join(CRLF);
+}
+function bodyPart(mimeType, content) {
+    return [
+        `Content-Type: ${mimeType}; charset=UTF-8`,
+        'Content-Transfer-Encoding: base64',
+        '',
+        wrapBase64(base64Encode(utf8(content))),
+    ].join(CRLF);
+}
+export function buildMimeMessage(args) {
+    const to = toList(args.to, 'to');
+    if (to.length === 0)
+        throw new Error('gmailSendEmail: `to` is required');
+    if (!args.text && !args.html) {
+        throw new Error('gmailSendEmail: at least one of `text` or `html` is required');
+    }
+    const headers = [`To: ${to.join(', ')}`];
+    const cc = toList(args.cc, 'cc');
+    if (cc.length > 0)
+        headers.push(`Cc: ${cc.join(', ')}`);
+    const bcc = toList(args.bcc, 'bcc');
+    if (bcc.length > 0)
+        headers.push(`Bcc: ${bcc.join(', ')}`);
+    if (args.replyTo)
+        headers.push(`Reply-To: ${assertNoControlChars(args.replyTo, 'replyTo')}`);
+    if (args.inReplyTo) {
+        const raw = assertNoControlChars(args.inReplyTo, 'inReplyTo');
+        const messageId = raw.startsWith('<') ? raw : `<${raw}>`;
+        headers.push(`In-Reply-To: ${messageId}`, `References: ${messageId}`);
+    }
+    headers.push(`Subject: ${encodeHeaderValue(args.subject)}`, 'MIME-Version: 1.0');
+    if (args.text && args.html) {
+        const boundary = `=_assembly_${crypto.randomUUID()}`;
+        return [
+            ...headers,
+            `Content-Type: multipart/alternative; boundary="${boundary}"`,
+            '',
+            `--${boundary}`,
+            // Plain text first: multipart/alternative parts go least- to
+            // most-preferred, and clients render the last part they support.
+            bodyPart('text/plain', args.text),
+            `--${boundary}`,
+            bodyPart('text/html', args.html),
+            `--${boundary}--`,
+            '',
+        ].join(CRLF);
+    }
+    const single = args.html
+        ? bodyPart('text/html', args.html)
+        : bodyPart('text/plain', args.text);
+    return [...headers, single].join(CRLF);
+}
+/**
+ * Send an email through the workspace's Gmail connection. Use this instead of
+ * calling the send-message action yourself: it builds the RFC 2822 MIME
+ * message (multipart/alternative when both text and html are given, RFC 2047
+ * subject encoding, CRLF line endings) and base64url-encodes it into `raw`.
+ *
+ * Gmail sends from the connected account; there is no `from` override. To
+ * reply on an existing thread pass `threadId` from a previous send's result —
+ * and `inReplyTo` (the original Message-ID) so recipients' clients thread too.
+ *
+ * Broker-level failures (provider not connected, throttled) throw
+ * ConnectorError like every other connector call.
+ */
+export async function gmailSendEmail(gmail, args) {
+    const raw = base64Url(utf8(buildMimeMessage(args)));
+    const input = { raw };
+    if (args.threadId)
+        input.threadId = args.threadId;
+    return gmail.action('send-message', input);
+}

package/dist/server.d.ts

@@ -5,6 +5,7 @@ export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
 export * from './airtable.js';
+export * from './gmail.js';
 export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';

package/dist/server.js

@@ -9,6 +9,7 @@ export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
 export * from './airtable.js';
+export * from './gmail.js';
 export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-integrations/providers/gmail.md

@@ -2,6 +2,22 @@
 
 Send-only: `gmail.send` is Google's one sensitive-tier Gmail scope; every read/draft scope is restricted (CASA audit), so those actions are unvendored. Do not invent a list or read action, and do not declare a read scope.
 
-`send-message` takes `raw`: the complete RFC 2822 MIME message, base64url-encoded. `threadId` makes it a reply; there is no in-catalog resolver for threads, so collect it from a previous send result, not a picker.
+**Send with `gmailSendEmail` from `@assembly-js/app-foundation/server` — never build the `raw` MIME message yourself.** The `send-message` action takes a complete RFC 2822 MIME message, base64url-encoded; hand-rolled construction gets header folding, multipart boundaries, non-ASCII subjects, or CRLF endings wrong. The helper builds it (multipart/alternative when both `text` and `html` are given) and calls the action:
+
+```ts
+import { getIntegration, gmailSendEmail } from '@assembly-js/app-foundation/server';
+
+const gmail = await getIntegration('gmail');
+const { id, threadId } = await gmailSendEmail(gmail, {
+  to: 'client@example.com',
+  subject: 'Your monthly report',
+  text: 'Plain-text fallback',
+  html: '<p>Rich body</p>',
+});
+```
+
+Mail sends from the connected account — there is no `from` override; use `replyTo` if replies should land elsewhere.
+
+Replies: pass `threadId` from a previous send's result to stay on the Gmail thread, and `inReplyTo` (the original Message-ID) so recipients' clients thread it too. There is no in-catalog resolver for threads, so collect `threadId` from your own send results, not a picker.
 
 <!-- ASSEMBLY_ACTIONS:gmail -->

package/skills/assembly-integrations/providers/google-calendar.md

@@ -1,7 +1,11 @@
 # Google Calendar
 
-`calendarId` defaults to `primary` on `list-events`. `create-event` requires `calendarId` plus `start` / `end` as `{ dateTime, timeZone? }` in RFC3339.
+`calendarId` defaults to `"primary"` — the connected account's own calendar. Don't build a calendar picker unless the app genuinely targets shared calendars; there is no in-catalog calendar resolver, so a picker would need the proxy.
 
-`list-events` paginates with `cursor` in and `nextPageToken` out. `update-event` is a patch — only supplied fields change.
+Event `start` and `end` are objects, not strings: `{ dateTime: "2026-08-27T14:00:00-04:00", timeZone: "America/New_York" }` (RFC3339 with offset). All-day events use `{ date: "2026-08-27" }` instead of `dateTime`. Passing a bare ISO string where the object is expected is the most common failure.
+
+`attendees` is `[{ email }]`. Creating or updating with attendees does **not** email them unless `sendUpdates: "all"` is passed on `update-event` (create sends per Google defaults) — surface this as an explicit choice in the UI, not a surprise.
+
+For listing over a window pass `timeMin`/`timeMax` (RFC3339) and `singleEvents: true` so recurring events expand into instances — without it you get the recurring master only, which renders as one event instead of many. `recurrence` on create takes RRULE strings, e.g. `["RRULE:FREQ=WEEKLY;BYDAY=MO"]`.
 
 <!-- ASSEMBLY_ACTIONS:google-calendar -->

package/skills/assembly-integrations/providers/google-sheet.md

@@ -2,8 +2,17 @@
 
 Sheets has no in-provider listing. Spreadsheets live in Drive.
 
-When `google-drive` is on the supported-provider list, declare it too and resolve `spreadsheetId` via Drive `find-file` with query `mimeType='application/vnd.google-apps.spreadsheet'` (id field `id`, label `name`). When Drive is not connectable, collect the spreadsheet URL and extract the id — never a bare "enter the ID" box.
+When `google-drive` is on the supported-provider list, declare it too and resolve `spreadsheetId` via Drive `find-file` with query `mimeType='application/vnd.google-apps.spreadsheet'` (id field `id`, label `name`). When Drive is not connectable, collect the **spreadsheet URL** and extract the id — never a bare "enter the ID" box:
 
-Ranges are A1 notation; `values` is a 2D array of rows. `get-values` reads, `append-values-to-spreadsheet` appends to the table found in the range, `update-values` overwrites an exact range.
+```ts
+// https://docs.google.com/spreadsheets/d/<spreadsheetId>/edit#gid=0
+const id = url.match(/\/spreadsheets\/d\/([a-zA-Z0-9-_]+)/)?.[1];
+```
+
+Ranges are A1 notation (`Sheet1!A1:D10`; quote sheet names with spaces: `'Q3 Data'!A:D`); `values` is a 2D array of rows — one inner array per row, cells as strings/numbers, never objects. `get-values` reads, `append-values-to-spreadsheet` appends to the table found in the range, `update-values` overwrites an exact range.
+
+Writes take `valueInputOption`: `RAW` stores values verbatim; `USER_ENTERED` parses them as if typed in the UI (strings that look like numbers/dates convert, `=SUM(...)` becomes a formula). Default to `USER_ENTERED` for user-facing data entry and `RAW` when round-tripping values the app will read back.
+
+`get-values` returns rows only up to the last non-empty cell — inner arrays can be shorter than the header row, so index defensively when mapping rows to objects.
 
 <!-- ASSEMBLY_ACTIONS:google-sheet -->

package/skills/assembly-integrations/providers/stripe.md

@@ -1,7 +1,22 @@
 # Stripe
 
-List cursors are the id of the last item on the previous page (Stripe's `starting_after`), not an opaque token. Passing a `next_cursor` from another provider, or anything that is not an item id, skips or repeats pages.
+Read-only: the vendored actions cover listing and looking up customers, payment intents, and invoices. There are no write actions — do not plan flows that create charges, invoices, or customers, and do not fall back to the proxy for writes; apps report on the connected Stripe account, they don't bill through it.
 
-`get-customer` returns the customer flat, not wrapped. Email filters on `list-customers` are case-sensitive exact matches.
+List cursors are the id of the last item on the previous page (Stripe's `starting_after`), not an opaque token. Passing a `next_cursor` from another provider, or anything that is not an item id, skips or repeats pages:
+
+```ts
+let cursor: string | undefined;
+do {
+  const page = await stripe.action('list-invoices', { customer, cursor, limit: 100 });
+  all.push(...page.items);
+  cursor = page.next_cursor; // the last item's id, pass back verbatim
+} while (cursor);
+```
+
+Money amounts are integers in the smallest currency unit (cents): render `amount / 100` with the item's `currency`, never the raw integer. Timestamps (`created`, `period_*`) are unix seconds.
+
+`get-customer` returns the customer flat, not wrapped. Email filters on `list-customers` are case-sensitive exact matches — for a "search by email" UI, prefer listing and filtering client-side unless the exact address is known.
+
+Status filters take Stripe's enums verbatim: invoices `draft | open | paid | uncollectible | void`; payment intents `requires_payment_method | requires_confirmation | requires_action | processing | requires_capture | canceled | succeeded`.
 
 <!-- ASSEMBLY_ACTIONS:stripe -->