@automate.ax/integration-contracts 0.112.10 → 0.113.0

package/dist/google-sheets/google-sheets.d.ts

@@ -0,0 +1,37 @@
+import { type GoogleSheetsGridRange } from "./schemas.js";
+export interface ParsedGoogleSheetsA1Range extends Omit<GoogleSheetsGridRange, "sheet"> {
+    /** Sheet title. Omit to use the spreadsheet's first visible sheet. */
+    sheet?: string;
+}
+/**
+ * Accepts either a raw spreadsheet ID or a standard Google Sheets URL.
+ *
+ * @param spreadsheet - Spreadsheet ID or URL.
+ * @throws When a URL is not a standard Google Sheets URL.
+ */
+export declare function normalizeGoogleSheetsSpreadsheetId(spreadsheet: string): string;
+/**
+ * Parses the practical A1 range forms accepted by Google Sheets.
+ *
+ * Partial two-ended ranges preserve the v5 parser's normalization: a missing
+ * coordinate is inferred from the opposite endpoint where needed, then left
+ * unbounded on the ending side.
+ *
+ * @param input - A1 cell or range with an optional sheet prefix.
+ */
+export declare function parseGoogleSheetsA1Range(input: string): ParsedGoogleSheetsA1Range;
+/**
+ * Converts a one-based column number to its A1 label.
+ *
+ * @param column - One-based column number.
+ * @throws When the number is outside the Google Sheets column limit.
+ */
+export declare function googleSheetsColumnToA1(column: number): string;
+/**
+ * Builds a canonical, quoted A1 cell reference.
+ *
+ * @param sheetTitle - Sheet title to quote.
+ * @param row - One-based row number.
+ * @param column - One-based column number.
+ */
+export declare function buildGoogleSheetsCellA1(sheetTitle: string, row: number, column: number): string;

package/dist/google-sheets/google-sheets.js

@@ -0,0 +1,252 @@
+import { GOOGLE_SHEETS_MAX_COLUMN, GOOGLE_SHEETS_MAX_ROW, } from "./schemas.js";
+const GOOGLE_SHEETS_URL_HOSTS = new Set([
+    "docs.google.com",
+    "sheets.google.com",
+]);
+const A1_ENDPOINT_PATTERN = /^(\$?[A-Za-z]{1,3})?(\$?\d+)?$/;
+/**
+ * Accepts either a raw spreadsheet ID or a standard Google Sheets URL.
+ *
+ * @param spreadsheet - Spreadsheet ID or URL.
+ * @throws When a URL is not a standard Google Sheets URL.
+ */
+export function normalizeGoogleSheetsSpreadsheetId(spreadsheet) {
+    const value = spreadsheet.trim();
+    if (!URL.canParse(value))
+        return value;
+    const url = new URL(value);
+    if (!GOOGLE_SHEETS_URL_HOSTS.has(url.hostname)) {
+        throw new Error(`Expected a Google Sheets URL, received "${value}".`);
+    }
+    const parts = url.pathname.split("/");
+    const spreadsheetsIndex = parts.indexOf("spreadsheets");
+    const documentIndex = spreadsheetsIndex === -1 ? -1 : parts.indexOf("d", spreadsheetsIndex + 1);
+    const spreadsheetId = documentIndex === -1 ? undefined : parts[documentIndex + 1];
+    if (!spreadsheetId) {
+        throw new Error(`Could not find a spreadsheet ID in "${value}".`);
+    }
+    return spreadsheetId;
+}
+/**
+ * Parses the practical A1 range forms accepted by Google Sheets.
+ *
+ * Partial two-ended ranges preserve the v5 parser's normalization: a missing
+ * coordinate is inferred from the opposite endpoint where needed, then left
+ * unbounded on the ending side.
+ *
+ * @param input - A1 cell or range with an optional sheet prefix.
+ */
+export function parseGoogleSheetsA1Range(input) {
+    const { range, sheet } = splitSheetPrefix(input.trim());
+    const endpointTexts = range.split(":");
+    if (endpointTexts.length > 2)
+        return invalidA1Range(input);
+    if (endpointTexts.length === 1) {
+        const endpoint = parseEndpoint(endpointTexts[0] ?? "", input);
+        if (endpoint.column === undefined || endpoint.row === undefined) {
+            return invalidA1Range(input);
+        }
+        return {
+            endColumn: endpoint.column,
+            endRow: endpoint.row,
+            ...(sheet !== undefined && { sheet }),
+            startColumn: endpoint.column,
+            startRow: endpoint.row,
+        };
+    }
+    const start = parseEndpoint(endpointTexts[0] ?? "", input);
+    const end = parseEndpoint(endpointTexts[1] ?? "", input);
+    // Naming the endpoint mask keeps the preserved v5 case matrix legible.
+    const mask = (start.column === undefined ? 0 : 0b1000) |
+        (start.row === undefined ? 0 : 0b0100) |
+        (end.column === undefined ? 0 : 0b0010) |
+        (end.row === undefined ? 0 : 0b0001);
+    let parsed;
+    switch (mask) {
+        case 0b0101:
+            parsed = {
+                endRow: end.row,
+                startColumn: 1,
+                startRow: start.row,
+            };
+            break;
+        case 0b1101:
+            parsed = {
+                endRow: end.row,
+                startColumn: start.column,
+                startRow: start.row,
+            };
+            break;
+        case 0b0111:
+            parsed = {
+                endRow: end.row,
+                startColumn: end.column,
+                startRow: start.row,
+            };
+            break;
+        case 0b1010:
+            parsed = {
+                endColumn: end.column,
+                startColumn: start.column,
+                startRow: 1,
+            };
+            break;
+        case 0b1110:
+            parsed = {
+                endColumn: end.column,
+                startColumn: start.column,
+                startRow: start.row,
+            };
+            break;
+        case 0b1011:
+            parsed = {
+                endColumn: end.column,
+                startColumn: start.column,
+                startRow: end.row,
+            };
+            break;
+        case 0b1111:
+            parsed = {
+                endColumn: end.column,
+                endRow: end.row,
+                startColumn: start.column,
+                startRow: start.row,
+            };
+            break;
+        default:
+            return invalidA1Range(input);
+    }
+    if (parsed.endColumn !== undefined &&
+        parsed.startColumn !== undefined &&
+        parsed.endColumn < parsed.startColumn) {
+        return invalidA1Range(input);
+    }
+    if (parsed.endRow !== undefined &&
+        parsed.startRow !== undefined &&
+        parsed.endRow < parsed.startRow) {
+        return invalidA1Range(input);
+    }
+    return { ...parsed, ...(sheet !== undefined && { sheet }) };
+}
+/**
+ * Converts a one-based column number to its A1 label.
+ *
+ * @param column - One-based column number.
+ * @throws When the number is outside the Google Sheets column limit.
+ */
+export function googleSheetsColumnToA1(column) {
+    if (!Number.isInteger(column) ||
+        column < 1 ||
+        column > GOOGLE_SHEETS_MAX_COLUMN) {
+        throw new Error(`Invalid Google Sheets column number: ${column}`);
+    }
+    let remaining = column;
+    let label = "";
+    while (remaining > 0) {
+        remaining--;
+        label = String.fromCharCode(65 + (remaining % 26)) + label;
+        remaining = Math.floor(remaining / 26);
+    }
+    return label;
+}
+/**
+ * Builds a canonical, quoted A1 cell reference.
+ *
+ * @param sheetTitle - Sheet title to quote.
+ * @param row - One-based row number.
+ * @param column - One-based column number.
+ */
+export function buildGoogleSheetsCellA1(sheetTitle, row, column) {
+    return `'${sheetTitle.replaceAll("'", "''")}'!${googleSheetsColumnToA1(column)}${row}`;
+}
+/**
+ * Parses one possibly partial A1 endpoint.
+ *
+ * @param value - Endpoint text.
+ * @param input - Original range used in errors.
+ */
+function parseEndpoint(value, input) {
+    const match = A1_ENDPOINT_PATTERN.exec(value);
+    if (!match || (!match[1] && !match[2]))
+        return invalidA1Range(input);
+    const row = match[2] ? Number(match[2].replace("$", "")) : undefined;
+    if (row !== undefined &&
+        (!Number.isSafeInteger(row) || row < 1 || row > GOOGLE_SHEETS_MAX_ROW)) {
+        return invalidA1Range(input);
+    }
+    return {
+        column: match[1]
+            ? googleSheetsA1ColumnToNumber(match[1].replace("$", ""))
+            : undefined,
+        row,
+    };
+}
+/**
+ * Converts an A1 column label to a one-based number.
+ *
+ * @param label - A1 column label.
+ */
+function googleSheetsA1ColumnToNumber(label) {
+    let result = 0;
+    for (const character of label.toUpperCase()) {
+        result = result * 26 + character.charCodeAt(0) - 64;
+    }
+    if (result > GOOGLE_SHEETS_MAX_COLUMN)
+        return invalidA1Range(label);
+    return result;
+}
+/**
+ * Splits an optional quoted sheet prefix from an A1 range.
+ *
+ * @param value - Trimmed A1 input.
+ */
+function splitSheetPrefix(value) {
+    if (!value)
+        return invalidA1Range(value);
+    let quoted = false;
+    let separator = -1;
+    for (let index = 0; index < value.length; index++) {
+        if (value[index] === "'") {
+            if (quoted && value[index + 1] === "'") {
+                index++;
+            }
+            else {
+                quoted = !quoted;
+            }
+        }
+        else if (value[index] === "!" && !quoted) {
+            if (separator !== -1)
+                return invalidA1Range(value);
+            separator = index;
+        }
+    }
+    if (quoted)
+        return invalidA1Range(value);
+    if (separator === -1)
+        return { range: value, sheet: undefined };
+    const rawSheet = value.slice(0, separator);
+    const range = value.slice(separator + 1);
+    if (!rawSheet || !range)
+        return invalidA1Range(value);
+    if (rawSheet.startsWith("'") || rawSheet.endsWith("'")) {
+        if (!(rawSheet.startsWith("'") && rawSheet.endsWith("'"))) {
+            return invalidA1Range(value);
+        }
+        const sheet = rawSheet.slice(1, -1).replaceAll("''", "'");
+        if (!sheet)
+            return invalidA1Range(value);
+        return { range, sheet };
+    }
+    if (rawSheet.includes("'"))
+        return invalidA1Range(value);
+    return { range, sheet: rawSheet };
+}
+/**
+ * Throws the canonical invalid-A1-range error.
+ *
+ * @param input - Invalid range input.
+ * @throws Always.
+ */
+function invalidA1Range(input) {
+    throw new Error(`Invalid Google Sheets A1 range "${input}". Expected a cell or two-ended range such as A1, A1:B2, A:B, or 1:10, optionally prefixed by a sheet name.`);
+}

package/dist/google-sheets/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./google-sheets.js";
+export * from "./schemas.js";

package/dist/google-sheets/index.js

@@ -0,0 +1,2 @@
+export * from "./google-sheets.js";
+export * from "./schemas.js";

package/dist/google-sheets/schemas.d.ts

@@ -0,0 +1,165 @@
+import * as z from "zod";
+export declare const GOOGLE_SHEETS_MAX_COLUMN = 18278;
+export declare const GOOGLE_SHEETS_MAX_ROW = 10000000;
+export declare const GOOGLE_SHEETS_CELL_VALUE_SCHEMA: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+export declare const GOOGLE_SHEETS_GRID_RANGE_SCHEMA: z.ZodObject<{
+    endColumn: z.ZodOptional<z.ZodNumber>;
+    endRow: z.ZodOptional<z.ZodNumber>;
+    sheet: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    startColumn: z.ZodOptional<z.ZodNumber>;
+    startRow: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** A monitored range supplied as A1 notation or one-based grid bounds. */
+export declare const GOOGLE_SHEETS_TRIGGER_RANGE_SCHEMA: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    endColumn: z.ZodOptional<z.ZodNumber>;
+    endRow: z.ZodOptional<z.ZodNumber>;
+    sheet: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    startColumn: z.ZodOptional<z.ZodNumber>;
+    startRow: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>]>;
+/** Canonical subscription configuration shared by authoring and ingestion. */
+export declare const GOOGLE_SHEETS_TRIGGER_CONFIG_SCHEMA: z.ZodObject<{
+    spreadsheetId: z.ZodString;
+    range: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        endColumn: z.ZodOptional<z.ZodNumber>;
+        endRow: z.ZodOptional<z.ZodNumber>;
+        sheet: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        startColumn: z.ZodOptional<z.ZodNumber>;
+        startRow: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+export declare const GOOGLE_SHEETS_CELL_ERROR_SCHEMA: z.ZodObject<{
+    type: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Formula and effective value observed for one cell. */
+export declare const GOOGLE_SHEETS_CELL_STATE_SCHEMA: z.ZodObject<{
+    error: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    formula: z.ZodOptional<z.ZodString>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+}, z.core.$strip>;
+export declare const GOOGLE_SHEETS_CELL_CHANGE_SCHEMA: z.ZodObject<{
+    before: z.ZodObject<{
+        error: z.ZodOptional<z.ZodObject<{
+            type: z.ZodString;
+            message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        formula: z.ZodOptional<z.ZodString>;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    }, z.core.$strip>;
+    cell: z.ZodObject<{
+        a1: z.ZodString;
+        column: z.ZodNumber;
+        row: z.ZodNumber;
+    }, z.core.$strip>;
+    after: z.ZodObject<{
+        error: z.ZodOptional<z.ZodObject<{
+            type: z.ZodString;
+            message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        formula: z.ZodOptional<z.ZodString>;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    }, z.core.$strip>;
+    sheet: z.ZodObject<{
+        id: z.ZodNumber;
+        title: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** One bounded batch of net cell changes from a spreadsheet observation. */
+export declare const GOOGLE_SHEETS_CELLS_CHANGED_EVENT_SCHEMA: z.ZodObject<{
+    changes: z.ZodArray<z.ZodObject<{
+        before: z.ZodObject<{
+            error: z.ZodOptional<z.ZodObject<{
+                type: z.ZodString;
+                message: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            formula: z.ZodOptional<z.ZodString>;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        }, z.core.$strip>;
+        cell: z.ZodObject<{
+            a1: z.ZodString;
+            column: z.ZodNumber;
+            row: z.ZodNumber;
+        }, z.core.$strip>;
+        after: z.ZodObject<{
+            error: z.ZodOptional<z.ZodObject<{
+                type: z.ZodString;
+                message: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            formula: z.ZodOptional<z.ZodString>;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        }, z.core.$strip>;
+        sheet: z.ZodObject<{
+            id: z.ZodNumber;
+            title: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    chunk: z.ZodObject<{
+        index: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strip>;
+    observedAt: z.ZodISODateTime;
+    spreadsheet: z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        url: z.ZodURL;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const googleSheetsTriggerContracts: {
+    readonly "googleSheets.cells.changed": {
+        readonly configSchema: z.ZodObject<{
+            spreadsheetId: z.ZodString;
+            range: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                endColumn: z.ZodOptional<z.ZodNumber>;
+                endRow: z.ZodOptional<z.ZodNumber>;
+                sheet: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+                startColumn: z.ZodOptional<z.ZodNumber>;
+                startRow: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            changes: z.ZodArray<z.ZodObject<{
+                before: z.ZodObject<{
+                    error: z.ZodOptional<z.ZodObject<{
+                        type: z.ZodString;
+                        message: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>;
+                    formula: z.ZodOptional<z.ZodString>;
+                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                }, z.core.$strip>;
+                cell: z.ZodObject<{
+                    a1: z.ZodString;
+                    column: z.ZodNumber;
+                    row: z.ZodNumber;
+                }, z.core.$strip>;
+                after: z.ZodObject<{
+                    error: z.ZodOptional<z.ZodObject<{
+                        type: z.ZodString;
+                        message: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>;
+                    formula: z.ZodOptional<z.ZodString>;
+                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                }, z.core.$strip>;
+                sheet: z.ZodObject<{
+                    id: z.ZodNumber;
+                    title: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+            chunk: z.ZodObject<{
+                index: z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$strip>;
+            observedAt: z.ZodISODateTime;
+            spreadsheet: z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodString;
+                url: z.ZodURL;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    };
+};
+export type GoogleSheetsGridRange = z.input<typeof GOOGLE_SHEETS_GRID_RANGE_SCHEMA>;
+export type GoogleSheetsTriggerRange = z.input<typeof GOOGLE_SHEETS_TRIGGER_RANGE_SCHEMA>;

package/dist/google-sheets/schemas.js

@@ -0,0 +1,100 @@
+import * as z from "zod";
+export const GOOGLE_SHEETS_MAX_COLUMN = 18_278;
+export const GOOGLE_SHEETS_MAX_ROW = 10_000_000;
+export const GOOGLE_SHEETS_CELL_VALUE_SCHEMA = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+]);
+export const GOOGLE_SHEETS_GRID_RANGE_SCHEMA = z
+    .object({
+    /** Inclusive one-based ending column. Omit for an unbounded range. */
+    endColumn: z
+        .number()
+        .int()
+        .positive()
+        .max(GOOGLE_SHEETS_MAX_COLUMN)
+        .optional(),
+    /** Inclusive one-based ending row. Omit for an unbounded range. */
+    endRow: z.number().int().positive().max(GOOGLE_SHEETS_MAX_ROW).optional(),
+    /** Sheet title or immutable numeric sheet ID. */
+    sheet: z.union([z.string().trim().min(1), z.number().int().nonnegative()]),
+    /** Inclusive one-based starting column. */
+    startColumn: z
+        .number()
+        .int()
+        .positive()
+        .max(GOOGLE_SHEETS_MAX_COLUMN)
+        .optional(),
+    /** Inclusive one-based starting row. */
+    startRow: z.number().int().positive().max(GOOGLE_SHEETS_MAX_ROW).optional(),
+})
+    .refine(({ endColumn, startColumn }) => endColumn === undefined ||
+    startColumn === undefined ||
+    endColumn >= startColumn, "The ending column must not precede the starting column.")
+    .refine(({ endRow, startRow }) => endRow === undefined || startRow === undefined || endRow >= startRow, "The ending row must not precede the starting row.");
+/** A monitored range supplied as A1 notation or one-based grid bounds. */
+export const GOOGLE_SHEETS_TRIGGER_RANGE_SCHEMA = z.union([
+    z.string().trim().min(1),
+    GOOGLE_SHEETS_GRID_RANGE_SCHEMA,
+]);
+/** Canonical subscription configuration shared by authoring and ingestion. */
+export const GOOGLE_SHEETS_TRIGGER_CONFIG_SCHEMA = z.object({
+    /** Immutable spreadsheet ID. */
+    spreadsheetId: z.string().trim().min(1),
+    /** Optional range. Omit to monitor every sheet in the spreadsheet. */
+    range: GOOGLE_SHEETS_TRIGGER_RANGE_SCHEMA.optional(),
+});
+export const GOOGLE_SHEETS_CELL_ERROR_SCHEMA = z.object({
+    /** Provider error category, such as `DIVIDE_BY_ZERO`. */
+    type: z.string().min(1),
+    /** Provider explanation when available. */
+    message: z.string().optional(),
+});
+/** Formula and effective value observed for one cell. */
+export const GOOGLE_SHEETS_CELL_STATE_SCHEMA = z.object({
+    /** Provider error when the effective value cannot be calculated. */
+    error: GOOGLE_SHEETS_CELL_ERROR_SCHEMA.optional(),
+    /** User-entered formula, including its leading `=`. */
+    formula: z.string().optional(),
+    /** Effective unformatted value. Empty and error cells use `null`. */
+    value: GOOGLE_SHEETS_CELL_VALUE_SCHEMA,
+});
+export const GOOGLE_SHEETS_CELL_CHANGE_SCHEMA = z.object({
+    /** State from the preceding complete observation. */
+    before: GOOGLE_SHEETS_CELL_STATE_SCHEMA,
+    /** One-based cell coordinates and canonical A1 reference. */
+    cell: z.object({
+        a1: z.string().min(1),
+        column: z.number().int().positive(),
+        row: z.number().int().positive(),
+    }),
+    /** State from the current complete observation. */
+    after: GOOGLE_SHEETS_CELL_STATE_SCHEMA,
+    /** Immutable sheet identity and current or last-known title. */
+    sheet: z.object({
+        id: z.number().int().nonnegative(),
+        title: z.string().min(1),
+    }),
+});
+/** One bounded batch of net cell changes from a spreadsheet observation. */
+export const GOOGLE_SHEETS_CELLS_CHANGED_EVENT_SCHEMA = z.object({
+    changes: GOOGLE_SHEETS_CELL_CHANGE_SCHEMA.array().min(1).max(500),
+    chunk: z.object({
+        index: z.number().int().nonnegative(),
+        total: z.number().int().positive(),
+    }),
+    observedAt: z.iso.datetime({ offset: true }),
+    spreadsheet: z.object({
+        id: z.string().min(1),
+        title: z.string().min(1),
+        url: z.url(),
+    }),
+});
+export const googleSheetsTriggerContracts = {
+    "googleSheets.cells.changed": {
+        configSchema: GOOGLE_SHEETS_TRIGGER_CONFIG_SCHEMA,
+        eventSchema: GOOGLE_SHEETS_CELLS_CHANGED_EVENT_SCHEMA,
+    },
+};

package/dist/triggers.d.ts

@@ -10,6 +10,7 @@ import type { gmailTriggerContracts } from "./gmail/index.js";
 import type { googleCalendarTriggerContracts } from "./google-calendar/index.js";
 import type { googleFormsTriggerContracts } from "./google-forms/index.js";
 import type { googleMeetTriggerContracts } from "./google-meet/index.js";
+import type { googleSheetsTriggerContracts } from "./google-sheets/index.js";
 import type { linearTriggerContracts } from "./linear/index.js";
 import type { notionTriggerContracts } from "./notion/index.js";
 import type { outlookTriggerContracts } from "./outlook/index.js";
@@ -22,7 +23,7 @@ import type { vercelTriggerContracts } from "./vercel/index.js";
 import type { webflowTriggerContracts } from "./webflow/index.js";
 import type { whatsappTriggerContracts } from "./whatsapp/index.js";
 import type { z } from "zod";
-export type TriggerContractMap = typeof airtableTriggerContracts & typeof automateTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof convexTriggerContracts & typeof closeTriggerContracts & typeof cloudflareTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof linearTriggerContracts & typeof notionTriggerContracts & typeof outlookTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof stripeTriggerContracts & typeof teamsTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof webflowTriggerContracts & typeof whatsappTriggerContracts;
+export type TriggerContractMap = typeof airtableTriggerContracts & typeof automateTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof convexTriggerContracts & typeof closeTriggerContracts & typeof cloudflareTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof googleSheetsTriggerContracts & typeof linearTriggerContracts & typeof notionTriggerContracts & typeof outlookTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof stripeTriggerContracts & typeof teamsTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof webflowTriggerContracts & typeof whatsappTriggerContracts;
 export type IntegrationTriggerType = keyof TriggerContractMap;
 /** Canonical authoring configuration for one integration trigger type. */
 export type TriggerConfig<TType extends IntegrationTriggerType> = z.input<TriggerContractMap[TType]["configSchema"]> extends Record<string, never> ? object : z.input<TriggerContractMap[TType]["configSchema"]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/integration-contracts",
-  "version": "0.112.10",
+  "version": "0.113.0",
   "description": "Shared integration payload contracts and provider primitives for Automate.ax.",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,7 @@
       "./google-calendar": "./src/google-calendar/index.ts",
       "./google-forms": "./src/google-forms/index.ts",
       "./google-meet": "./src/google-meet/index.ts",
+      "./google-sheets": "./src/google-sheets/index.ts",
       "./github": "./src/github/index.ts",
       "./jobnimbus": "./src/jobnimbus/index.ts",
       "./linear": "./src/linear/index.ts",
@@ -50,7 +51,7 @@
     }
   },
   "dependencies": {
-    "@automate.ax/codec": "0.112.10",
+    "@automate.ax/codec": "0.113.0",
     "@cfworker/json-schema": "^4.1.1",
     "@googleapis/calendar": "^15.0.0",
     "@googleapis/forms": "^6.0.1",
@@ -156,6 +157,11 @@
       "types": "./dist/google-meet/index.d.ts",
       "default": "./dist/google-meet/index.js"
     },
+    "./google-sheets": {
+      "bun": "./src/google-sheets/index.ts",
+      "types": "./dist/google-sheets/index.d.ts",
+      "default": "./dist/google-sheets/index.js"
+    },
     "./github": {
       "bun": "./src/github/index.ts",
       "types": "./dist/github/index.d.ts",

package/src/google-sheets/google-sheets.ts

@@ -0,0 +1,283 @@
+import {
+  GOOGLE_SHEETS_MAX_COLUMN,
+  GOOGLE_SHEETS_MAX_ROW,
+  type GoogleSheetsGridRange,
+} from "./schemas"
+
+const GOOGLE_SHEETS_URL_HOSTS = new Set([
+  "docs.google.com",
+  "sheets.google.com",
+])
+const A1_ENDPOINT_PATTERN = /^(\$?[A-Za-z]{1,3})?(\$?\d+)?$/
+
+export interface ParsedGoogleSheetsA1Range
+  extends Omit<GoogleSheetsGridRange, "sheet"> {
+  /** Sheet title. Omit to use the spreadsheet's first visible sheet. */
+  sheet?: string
+}
+
+/**
+ * Accepts either a raw spreadsheet ID or a standard Google Sheets URL.
+ *
+ * @param spreadsheet - Spreadsheet ID or URL.
+ * @throws When a URL is not a standard Google Sheets URL.
+ */
+export function normalizeGoogleSheetsSpreadsheetId(spreadsheet: string) {
+  const value = spreadsheet.trim()
+  if (!URL.canParse(value)) return value
+
+  const url = new URL(value)
+  if (!GOOGLE_SHEETS_URL_HOSTS.has(url.hostname)) {
+    throw new Error(`Expected a Google Sheets URL, received "${value}".`)
+  }
+  const parts = url.pathname.split("/")
+  const spreadsheetsIndex = parts.indexOf("spreadsheets")
+  const documentIndex =
+    spreadsheetsIndex === -1 ? -1 : parts.indexOf("d", spreadsheetsIndex + 1)
+  const spreadsheetId =
+    documentIndex === -1 ? undefined : parts[documentIndex + 1]
+  if (!spreadsheetId) {
+    throw new Error(`Could not find a spreadsheet ID in "${value}".`)
+  }
+  return spreadsheetId
+}
+
+/**
+ * Parses the practical A1 range forms accepted by Google Sheets.
+ *
+ * Partial two-ended ranges preserve the v5 parser's normalization: a missing
+ * coordinate is inferred from the opposite endpoint where needed, then left
+ * unbounded on the ending side.
+ *
+ * @param input - A1 cell or range with an optional sheet prefix.
+ */
+export function parseGoogleSheetsA1Range(
+  input: string,
+): ParsedGoogleSheetsA1Range {
+  const { range, sheet } = splitSheetPrefix(input.trim())
+  const endpointTexts = range.split(":")
+  if (endpointTexts.length > 2) return invalidA1Range(input)
+
+  if (endpointTexts.length === 1) {
+    const endpoint = parseEndpoint(endpointTexts[0] ?? "", input)
+    if (endpoint.column === undefined || endpoint.row === undefined) {
+      return invalidA1Range(input)
+    }
+    return {
+      endColumn: endpoint.column,
+      endRow: endpoint.row,
+      ...(sheet !== undefined && { sheet }),
+      startColumn: endpoint.column,
+      startRow: endpoint.row,
+    }
+  }
+
+  const start = parseEndpoint(endpointTexts[0] ?? "", input)
+  const end = parseEndpoint(endpointTexts[1] ?? "", input)
+  // Naming the endpoint mask keeps the preserved v5 case matrix legible.
+  const mask =
+    (start.column === undefined ? 0 : 0b1000) |
+    (start.row === undefined ? 0 : 0b0100) |
+    (end.column === undefined ? 0 : 0b0010) |
+    (end.row === undefined ? 0 : 0b0001)
+
+  let parsed: Omit<ParsedGoogleSheetsA1Range, "sheet">
+  switch (mask) {
+    case 0b0101:
+      parsed = {
+        endRow: end.row,
+        startColumn: 1,
+        startRow: start.row,
+      }
+      break
+    case 0b1101:
+      parsed = {
+        endRow: end.row,
+        startColumn: start.column,
+        startRow: start.row,
+      }
+      break
+    case 0b0111:
+      parsed = {
+        endRow: end.row,
+        startColumn: end.column,
+        startRow: start.row,
+      }
+      break
+    case 0b1010:
+      parsed = {
+        endColumn: end.column,
+        startColumn: start.column,
+        startRow: 1,
+      }
+      break
+    case 0b1110:
+      parsed = {
+        endColumn: end.column,
+        startColumn: start.column,
+        startRow: start.row,
+      }
+      break
+    case 0b1011:
+      parsed = {
+        endColumn: end.column,
+        startColumn: start.column,
+        startRow: end.row,
+      }
+      break
+    case 0b1111:
+      parsed = {
+        endColumn: end.column,
+        endRow: end.row,
+        startColumn: start.column,
+        startRow: start.row,
+      }
+      break
+    default:
+      return invalidA1Range(input)
+  }
+
+  if (
+    parsed.endColumn !== undefined &&
+    parsed.startColumn !== undefined &&
+    parsed.endColumn < parsed.startColumn
+  ) {
+    return invalidA1Range(input)
+  }
+  if (
+    parsed.endRow !== undefined &&
+    parsed.startRow !== undefined &&
+    parsed.endRow < parsed.startRow
+  ) {
+    return invalidA1Range(input)
+  }
+  return { ...parsed, ...(sheet !== undefined && { sheet }) }
+}
+
+/**
+ * Converts a one-based column number to its A1 label.
+ *
+ * @param column - One-based column number.
+ * @throws When the number is outside the Google Sheets column limit.
+ */
+export function googleSheetsColumnToA1(column: number) {
+  if (
+    !Number.isInteger(column) ||
+    column < 1 ||
+    column > GOOGLE_SHEETS_MAX_COLUMN
+  ) {
+    throw new Error(`Invalid Google Sheets column number: ${column}`)
+  }
+  let remaining = column
+  let label = ""
+  while (remaining > 0) {
+    remaining--
+    label = String.fromCharCode(65 + (remaining % 26)) + label
+    remaining = Math.floor(remaining / 26)
+  }
+  return label
+}
+
+/**
+ * Builds a canonical, quoted A1 cell reference.
+ *
+ * @param sheetTitle - Sheet title to quote.
+ * @param row - One-based row number.
+ * @param column - One-based column number.
+ */
+export function buildGoogleSheetsCellA1(
+  sheetTitle: string,
+  row: number,
+  column: number,
+) {
+  return `'${sheetTitle.replaceAll("'", "''")}'!${googleSheetsColumnToA1(column)}${row}`
+}
+
+/**
+ * Parses one possibly partial A1 endpoint.
+ *
+ * @param value - Endpoint text.
+ * @param input - Original range used in errors.
+ */
+function parseEndpoint(value: string, input: string) {
+  const match = A1_ENDPOINT_PATTERN.exec(value)
+  if (!match || (!match[1] && !match[2])) return invalidA1Range(input)
+  const row = match[2] ? Number(match[2].replace("$", "")) : undefined
+  if (
+    row !== undefined &&
+    (!Number.isSafeInteger(row) || row < 1 || row > GOOGLE_SHEETS_MAX_ROW)
+  ) {
+    return invalidA1Range(input)
+  }
+  return {
+    column: match[1]
+      ? googleSheetsA1ColumnToNumber(match[1].replace("$", ""))
+      : undefined,
+    row,
+  }
+}
+
+/**
+ * Converts an A1 column label to a one-based number.
+ *
+ * @param label - A1 column label.
+ */
+function googleSheetsA1ColumnToNumber(label: string) {
+  let result = 0
+  for (const character of label.toUpperCase()) {
+    result = result * 26 + character.charCodeAt(0) - 64
+  }
+  if (result > GOOGLE_SHEETS_MAX_COLUMN) return invalidA1Range(label)
+  return result
+}
+
+/**
+ * Splits an optional quoted sheet prefix from an A1 range.
+ *
+ * @param value - Trimmed A1 input.
+ */
+function splitSheetPrefix(value: string) {
+  if (!value) return invalidA1Range(value)
+  let quoted = false
+  let separator = -1
+  for (let index = 0; index < value.length; index++) {
+    if (value[index] === "'") {
+      if (quoted && value[index + 1] === "'") {
+        index++
+      } else {
+        quoted = !quoted
+      }
+    } else if (value[index] === "!" && !quoted) {
+      if (separator !== -1) return invalidA1Range(value)
+      separator = index
+    }
+  }
+  if (quoted) return invalidA1Range(value)
+  if (separator === -1) return { range: value, sheet: undefined }
+
+  const rawSheet = value.slice(0, separator)
+  const range = value.slice(separator + 1)
+  if (!rawSheet || !range) return invalidA1Range(value)
+  if (rawSheet.startsWith("'") || rawSheet.endsWith("'")) {
+    if (!(rawSheet.startsWith("'") && rawSheet.endsWith("'"))) {
+      return invalidA1Range(value)
+    }
+    const sheet = rawSheet.slice(1, -1).replaceAll("''", "'")
+    if (!sheet) return invalidA1Range(value)
+    return { range, sheet }
+  }
+  if (rawSheet.includes("'")) return invalidA1Range(value)
+  return { range, sheet: rawSheet }
+}
+
+/**
+ * Throws the canonical invalid-A1-range error.
+ *
+ * @param input - Invalid range input.
+ * @throws Always.
+ */
+function invalidA1Range(input: string): never {
+  throw new Error(
+    `Invalid Google Sheets A1 range "${input}". Expected a cell or two-ended range such as A1, A1:B2, A:B, or 1:10, optionally prefixed by a sheet name.`,
+  )
+}

package/src/google-sheets/index.ts

@@ -0,0 +1,2 @@
+export * from "./google-sheets"
+export * from "./schemas"

package/src/google-sheets/schemas.ts

@@ -0,0 +1,136 @@
+import * as z from "zod"
+
+export const GOOGLE_SHEETS_MAX_COLUMN = 18_278
+export const GOOGLE_SHEETS_MAX_ROW = 10_000_000
+
+export const GOOGLE_SHEETS_CELL_VALUE_SCHEMA = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+])
+
+export const GOOGLE_SHEETS_GRID_RANGE_SCHEMA = z
+  .object({
+    /** Inclusive one-based ending column. Omit for an unbounded range. */
+    endColumn: z
+      .number()
+      .int()
+      .positive()
+      .max(GOOGLE_SHEETS_MAX_COLUMN)
+      .optional(),
+
+    /** Inclusive one-based ending row. Omit for an unbounded range. */
+    endRow: z.number().int().positive().max(GOOGLE_SHEETS_MAX_ROW).optional(),
+
+    /** Sheet title or immutable numeric sheet ID. */
+    sheet: z.union([z.string().trim().min(1), z.number().int().nonnegative()]),
+
+    /** Inclusive one-based starting column. */
+    startColumn: z
+      .number()
+      .int()
+      .positive()
+      .max(GOOGLE_SHEETS_MAX_COLUMN)
+      .optional(),
+
+    /** Inclusive one-based starting row. */
+    startRow: z.number().int().positive().max(GOOGLE_SHEETS_MAX_ROW).optional(),
+  })
+  .refine(
+    ({ endColumn, startColumn }) =>
+      endColumn === undefined ||
+      startColumn === undefined ||
+      endColumn >= startColumn,
+    "The ending column must not precede the starting column.",
+  )
+  .refine(
+    ({ endRow, startRow }) =>
+      endRow === undefined || startRow === undefined || endRow >= startRow,
+    "The ending row must not precede the starting row.",
+  )
+
+/** A monitored range supplied as A1 notation or one-based grid bounds. */
+export const GOOGLE_SHEETS_TRIGGER_RANGE_SCHEMA = z.union([
+  z.string().trim().min(1),
+  GOOGLE_SHEETS_GRID_RANGE_SCHEMA,
+])
+
+/** Canonical subscription configuration shared by authoring and ingestion. */
+export const GOOGLE_SHEETS_TRIGGER_CONFIG_SCHEMA = z.object({
+  /** Immutable spreadsheet ID. */
+  spreadsheetId: z.string().trim().min(1),
+
+  /** Optional range. Omit to monitor every sheet in the spreadsheet. */
+  range: GOOGLE_SHEETS_TRIGGER_RANGE_SCHEMA.optional(),
+})
+
+export const GOOGLE_SHEETS_CELL_ERROR_SCHEMA = z.object({
+  /** Provider error category, such as `DIVIDE_BY_ZERO`. */
+  type: z.string().min(1),
+
+  /** Provider explanation when available. */
+  message: z.string().optional(),
+})
+
+/** Formula and effective value observed for one cell. */
+export const GOOGLE_SHEETS_CELL_STATE_SCHEMA = z.object({
+  /** Provider error when the effective value cannot be calculated. */
+  error: GOOGLE_SHEETS_CELL_ERROR_SCHEMA.optional(),
+
+  /** User-entered formula, including its leading `=`. */
+  formula: z.string().optional(),
+
+  /** Effective unformatted value. Empty and error cells use `null`. */
+  value: GOOGLE_SHEETS_CELL_VALUE_SCHEMA,
+})
+
+export const GOOGLE_SHEETS_CELL_CHANGE_SCHEMA = z.object({
+  /** State from the preceding complete observation. */
+  before: GOOGLE_SHEETS_CELL_STATE_SCHEMA,
+
+  /** One-based cell coordinates and canonical A1 reference. */
+  cell: z.object({
+    a1: z.string().min(1),
+    column: z.number().int().positive(),
+    row: z.number().int().positive(),
+  }),
+
+  /** State from the current complete observation. */
+  after: GOOGLE_SHEETS_CELL_STATE_SCHEMA,
+
+  /** Immutable sheet identity and current or last-known title. */
+  sheet: z.object({
+    id: z.number().int().nonnegative(),
+    title: z.string().min(1),
+  }),
+})
+
+/** One bounded batch of net cell changes from a spreadsheet observation. */
+export const GOOGLE_SHEETS_CELLS_CHANGED_EVENT_SCHEMA = z.object({
+  changes: GOOGLE_SHEETS_CELL_CHANGE_SCHEMA.array().min(1).max(500),
+  chunk: z.object({
+    index: z.number().int().nonnegative(),
+    total: z.number().int().positive(),
+  }),
+  observedAt: z.iso.datetime({ offset: true }),
+  spreadsheet: z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    url: z.url(),
+  }),
+})
+
+export const googleSheetsTriggerContracts = {
+  "googleSheets.cells.changed": {
+    configSchema: GOOGLE_SHEETS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: GOOGLE_SHEETS_CELLS_CHANGED_EVENT_SCHEMA,
+  },
+} as const
+
+export type GoogleSheetsGridRange = z.input<
+  typeof GOOGLE_SHEETS_GRID_RANGE_SCHEMA
+>
+export type GoogleSheetsTriggerRange = z.input<
+  typeof GOOGLE_SHEETS_TRIGGER_RANGE_SCHEMA
+>

package/src/triggers.ts

@@ -10,6 +10,7 @@ import type { gmailTriggerContracts } from "./gmail"
 import type { googleCalendarTriggerContracts } from "./google-calendar"
 import type { googleFormsTriggerContracts } from "./google-forms"
 import type { googleMeetTriggerContracts } from "./google-meet"
+import type { googleSheetsTriggerContracts } from "./google-sheets"
 import type { linearTriggerContracts } from "./linear"
 import type { notionTriggerContracts } from "./notion"
 import type { outlookTriggerContracts } from "./outlook"
@@ -35,6 +36,7 @@ export type TriggerContractMap = typeof airtableTriggerContracts &
   typeof googleCalendarTriggerContracts &
   typeof googleFormsTriggerContracts &
   typeof googleMeetTriggerContracts &
+  typeof googleSheetsTriggerContracts &
   typeof linearTriggerContracts &
   typeof notionTriggerContracts &
   typeof outlookTriggerContracts &