@zackbart/connecta 0.34.1 → 0.36.0

package/dist/providers/sheets/lib/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The Sheets API root. Every path the tools send is beneath
+ * `/spreadsheets`; the delegated token decides which ones the user can open.
+ */
+export declare const SHEETS_API_BASE_URL = "https://sheets.googleapis.com/v4";
+/**
+ * Exactly the scope this connection requests, and what the Admin console's
+ * domain-wide delegation entry must add for it. One scope reads and writes
+ * every spreadsheet the user can open; Google offers no narrower one that
+ * writes.
+ */
+export declare const SHEETS_SCOPES: readonly ["https://www.googleapis.com/auth/spreadsheets"];
+/** A wide values read; Google itself recommends payloads under 2 MB. */
+export declare const SHEETS_MAX_RESPONSE_BYTES: number;

package/dist/providers/sheets/lib/constants.js

@@ -0,0 +1,14 @@
+/**
+ * The Sheets API root. Every path the tools send is beneath
+ * `/spreadsheets`; the delegated token decides which ones the user can open.
+ */
+export const SHEETS_API_BASE_URL = "https://sheets.googleapis.com/v4";
+/**
+ * Exactly the scope this connection requests, and what the Admin console's
+ * domain-wide delegation entry must add for it. One scope reads and writes
+ * every spreadsheet the user can open; Google offers no narrower one that
+ * writes.
+ */
+export const SHEETS_SCOPES = ["https://www.googleapis.com/auth/spreadsheets"];
+/** A wide values read; Google itself recommends payloads under 2 MB. */
+export const SHEETS_MAX_RESPONSE_BYTES = 16 * 1024 * 1024;

package/dist/providers/sheets/lib/hatch.js

@@ -0,0 +1,163 @@
+import { codePoints } from "../../../http/json-schema.js";
+import { googleBatchGuard, googleHatchBinding } from "../../_shared/google/hatch.js";
+import { OperationIndex } from "../../_shared/rest/operation-index.js";
+import { openapi } from "../openapi.generated.js";
+import { SHEETS_ADMITTED_KINDS, SHEETS_REFUSED_KINDS, sheetsExternalDataProblem } from "./requests.js";
+// Keep range/header nouns searchable alongside the reviewed 115-character action summary.
+// This discovery-only category changes no method, path, schema or execution verdict.
+const sheetsDiscovery = {
+    ...openapi,
+    tags: [...openapi.tags, "spreadsheets ranges headers", "spreadsheets.values rows headers"],
+    ops: openapi.ops.map((row) => {
+        const [method, path, operationId, summary, , ...server] = row;
+        if (row[2] === "sheets.spreadsheets.values.get" || row[2] === "sheets.spreadsheets.values.batchGet")
+            return [method, path, operationId, summary, openapi.tags.length + 1, ...server];
+        if (row[2] !== "sheets.spreadsheets.batchUpdate")
+            return row;
+        return [method, path, operationId, summary, openapi.tags.length, ...server];
+    }),
+};
+export const sheetsIndex = new OperationIndex(sheetsDiscovery, {
+    vendor: "sheets",
+    title: "Google Sheets",
+    pathMatching: "uri-template",
+});
+/** Decode range colons only. Encoded actions, ids and unreserved bytes still fail the shared backstop. */
+export function sheetsPath(path) {
+    const match = /^(\/spreadsheets\/[A-Za-z0-9_-]+\/values\/)([^/?#]+)$/.exec(path);
+    if (!match)
+        return path;
+    const tail = match[2];
+    const action = /:(append|clear)$/.exec(tail)?.[0] ?? "";
+    const range = action ? tail.slice(0, -action.length) : tail;
+    // An encoded trailing action could change the matched method; preserve its refusal.
+    if (/%3a(?:append|clear)$/i.test(range))
+        return path;
+    return `${match[1]}${range.replace(/%3a/gi, ":")}${action}`;
+}
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+/** Same scalar, range and write-cell ceilings as the named workflows, including filter-selected writes. */
+export function sheetsRequestProblem(call) {
+    const body = record(call.body);
+    if (call.op.path === "/spreadsheets/{spreadsheetId}:batchUpdate") {
+        const requests = body["requests"];
+        if (Array.isArray(requests))
+            for (const request of requests) {
+                for (const kind of Object.keys(record(request)))
+                    if (Object.hasOwn(SHEETS_REFUSED_KINDS, kind))
+                        return SHEETS_REFUSED_KINDS[kind];
+            }
+        const problem = googleBatchGuard(body, { kinds: SHEETS_ADMITTED_KINDS, revision: false });
+        if (problem)
+            return problem;
+    }
+    if (call.method !== "GET" &&
+        SHEETS_HATCH.verdicts[`${call.method} ${call.op.path}`] !== "read") {
+        const problem = sheetsExternalDataProblem(body);
+        if (problem)
+            return problem;
+    }
+    const isValue = call.op.path.includes("/values");
+    for (const [key, max] of [
+        ["ranges", 20],
+        ["dataFilters", 20],
+        ["data", 100],
+    ]) {
+        const list = body[key] ?? call.query[key];
+        if (Array.isArray(list) && (!list.length || list.length > max))
+            return `${key} needs 1–${max} entries.`;
+    }
+    const rangeProblem = (value) => typeof value !== "string" ||
+        !value.length ||
+        codePoints(value) > 512 ||
+        /[\r\n]/.test(value) ||
+        /^\.+$/.test(value);
+    const ranges = [
+        ...(Array.isArray(body["ranges"]) ? body["ranges"] : []),
+        ...(Array.isArray(call.query["ranges"]) ? call.query["ranges"] : []),
+    ];
+    if (call.params["range"] !== undefined)
+        ranges.push(call.params["range"]);
+    if (ranges.some(rangeProblem))
+        return "Ranges must be nonempty single-line A1 strings of at most 512 characters.";
+    let cells = 0;
+    const stack = [body];
+    while (stack.length) {
+        const value = stack.pop();
+        if (Array.isArray(value)) {
+            stack.push(...value);
+            continue;
+        }
+        const obj = record(value);
+        if (typeof obj["a1Range"] === "string" && rangeProblem(obj["a1Range"]))
+            return "Data-filter A1 ranges must be nonempty single-line strings of at most 512 characters.";
+        if (isValue && obj["range"] !== undefined && rangeProblem(obj["range"]))
+            return "Value ranges must be nonempty single-line strings of at most 512 characters.";
+        if (isValue && obj["values"] !== undefined) {
+            const rows = obj["values"];
+            if (!Array.isArray(rows) || !rows.length || rows.length > (obj["majorDimension"] === "COLUMNS" ? 18278 : 10000))
+                return "Values need 1–10000 rows or columns.";
+            for (const row of rows) {
+                if (!Array.isArray(row) || row.length > (obj["majorDimension"] === "COLUMNS" ? 10000 : 18278))
+                    return "Values must be a bounded two-dimensional cell array.";
+                cells += row.length;
+                for (const cell of row)
+                    if (!(cell === null ||
+                        typeof cell === "boolean" ||
+                        (typeof cell === "number" && Number.isFinite(cell)) ||
+                        (typeof cell === "string" && codePoints(cell) <= 50000)))
+                        return "Cells must be scalar strings (at most 50000 characters), finite numbers, booleans or null.";
+            }
+            if (cells > 50000)
+                return "A values write carries at most 50000 cells; split it into several calls.";
+        }
+        stack.push(...Object.values(obj));
+    }
+    return undefined;
+}
+export function sheetsBinding(connection) {
+    return {
+        ...googleHatchBinding(connection, {
+            index: sheetsIndex,
+            review: "Seventeen explicitly reviewed Sheets JSON methods, seven reads including three side-effect-free POST reads; bounded scalar value writes and reviewed non-preview batch kinds, delegated subject and permanent value safety.",
+            refuse: sheetsRequestProblem,
+        }),
+        // A1 references supply cell addresses, not resource nouns; technical nouns in other providers stay searchable.
+        searchNoun: (term) => !/^[a-z]{1,3}[1-9]\d*$/.test(term),
+        path: sheetsPath,
+    };
+}
+export const SHEETS_HATCH = {
+    name: "sheets",
+    title: "Google Sheets",
+    index: sheetsIndex,
+    pathExample: "/spreadsheets/sheet_123",
+    verdicts: {
+        "GET /spreadsheets/{spreadsheetId}": "read",
+        "GET /spreadsheets/{spreadsheetId}/developerMetadata/{metadataId}": "read",
+        "POST /spreadsheets/{spreadsheetId}/developerMetadata:search": "read",
+        "POST /spreadsheets/{spreadsheetId}:getByDataFilter": "read",
+        "GET /spreadsheets/{spreadsheetId}/values/{range}": "read",
+        "GET /spreadsheets/{spreadsheetId}/values:batchGet": "read",
+        "POST /spreadsheets/{spreadsheetId}/values:batchGetByDataFilter": "read",
+        "POST /spreadsheets": "write",
+        "POST /spreadsheets/{spreadsheetId}:batchUpdate": "destructive",
+        "POST /spreadsheets/{spreadsheetId}/sheets/{sheetId}:copyTo": "write",
+        "PUT /spreadsheets/{spreadsheetId}/values/{range}": "destructive",
+        "POST /spreadsheets/{spreadsheetId}/values/{range}:append": "destructive",
+        "POST /spreadsheets/{spreadsheetId}/values/{range}:clear": "destructive",
+        "POST /spreadsheets/{spreadsheetId}/values:batchUpdate": "destructive",
+        "POST /spreadsheets/{spreadsheetId}/values:batchUpdateByDataFilter": "destructive",
+        "POST /spreadsheets/{spreadsheetId}/values:batchClear": "destructive",
+        "POST /spreadsheets/{spreadsheetId}/values:batchClearByDataFilter": "destructive",
+    },
+    named: {
+        "GET /spreadsheets/{spreadsheetId}": "get_spreadsheet",
+        "GET /spreadsheets/{spreadsheetId}/values:batchGet": "get_values",
+        "POST /spreadsheets": "create_spreadsheet",
+        "POST /spreadsheets/{spreadsheetId}:batchUpdate": "batch_update_spreadsheet",
+        "POST /spreadsheets/{spreadsheetId}/values/{range}:append": "append_values",
+        "POST /spreadsheets/{spreadsheetId}/values:batchUpdate": "batch_update_values",
+        "POST /spreadsheets/{spreadsheetId}/values:batchClear": "clear_values",
+    },
+};

package/dist/providers/sheets/lib/requests.js

@@ -0,0 +1,105 @@
+export const SHEETS_REQUEST_KINDS = [
+    "addBanding",
+    "addChart",
+    "addCommentReply",
+    "addConditionalFormatRule",
+    "addDataSource",
+    "addDimensionGroup",
+    "addFilterView",
+    "addNamedRange",
+    "addProtectedRange",
+    "addSheet",
+    "addSlicer",
+    "addTable",
+    "appendCells",
+    "appendDimension",
+    "autoFill",
+    "autoResizeDimensions",
+    "cancelDataSourceRefresh",
+    "clearBasicFilter",
+    "copyPaste",
+    "createDeveloperMetadata",
+    "cutPaste",
+    "deleteBanding",
+    "deleteComment",
+    "deleteCommentReply",
+    "deleteConditionalFormatRule",
+    "deleteDataSource",
+    "deleteDeveloperMetadata",
+    "deleteDimension",
+    "deleteDimensionGroup",
+    "deleteDuplicates",
+    "deleteEmbeddedObject",
+    "deleteFilterView",
+    "deleteNamedRange",
+    "deleteProtectedRange",
+    "deleteRange",
+    "deleteSheet",
+    "deleteTable",
+    "duplicateFilterView",
+    "duplicateSheet",
+    "findReplace",
+    "insertComment",
+    "insertDimension",
+    "insertRange",
+    "mergeCells",
+    "moveDimension",
+    "pasteData",
+    "randomizeRange",
+    "refreshDataSource",
+    "repeatCell",
+    "setBasicFilter",
+    "setDataValidation",
+    "sortRange",
+    "textToColumns",
+    "trimWhitespace",
+    "unmergeCells",
+    "updateBanding",
+    "updateBorders",
+    "updateCells",
+    "updateChartSpec",
+    "updateCommentPost",
+    "updateConditionalFormatRule",
+    "updateDataSource",
+    "updateDeveloperMetadata",
+    "updateDimensionGroup",
+    "updateDimensionProperties",
+    "updateEmbeddedObjectBorder",
+    "updateEmbeddedObjectPosition",
+    "updateFilterView",
+    "updateNamedRange",
+    "updateProtectedRange",
+    "updateSheetProperties",
+    "updateSlicerSpec",
+    "updateSpreadsheetProperties",
+    "updateTable",
+];
+export const SHEETS_REFUSED_KINDS = {
+    addDataSource: "External data-source creation and execution are outside this connection.",
+    updateDataSource: "External data-source configuration and execution are outside this connection.",
+    deleteDataSource: "External data-source administration is outside this connection.",
+    refreshDataSource: "External data-source execution is outside this connection.",
+    cancelDataSourceRefresh: "External data-source execution is outside this connection.",
+    insertComment: "Preview comment mutations require separate product review.",
+    addCommentReply: "Preview comment mutations require separate product review.",
+    updateCommentPost: "Preview comment mutations require separate product review.",
+    deleteComment: "Preview comment mutations require separate product review.",
+    deleteCommentReply: "Preview comment mutations require separate product review.",
+};
+export const SHEETS_ADMITTED_KINDS = SHEETS_REQUEST_KINDS.filter((kind) => !SHEETS_REFUSED_KINDS[kind]);
+/** Creation and ordinary batch kinds must not smuggle external data-source configuration. */
+export function sheetsExternalDataProblem(body) {
+    const stack = [body];
+    while (stack.length) {
+        const value = stack.pop();
+        if (!value || typeof value !== "object")
+            continue;
+        if (!Array.isArray(value))
+            for (const key of ["dataSources", "dataSourceSheetProperties", "dataSourceId"]) {
+                if (Object.hasOwn(value, key))
+                    return "External data-source configuration and execution are outside this connection.";
+            }
+        stack.push(...Object.values(value));
+    }
+    return undefined;
+}

package/dist/providers/sheets/lib/schemas.js

@@ -0,0 +1,138 @@
+import { Schema } from "effect";
+import { Integer, isMinChars, isMaxChars } from "../../../http/json-schema.js";
+const optional = (fields) => Schema.Struct(Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, Schema.optionalKey(value)])));
+const str = (description, max, pattern) => Schema.String.check(isMinChars(1), isMaxChars(max), ...(pattern
+    ? [
+        Schema.makeFilter((value) => pattern.test(value), {
+            expected: `matching ${pattern.source}`,
+            toJsonSchema: () => ({ pattern: pattern.source }),
+        }),
+    ]
+    : [])).annotate({ description });
+const int = (description, min, max) => Integer.check(Schema.isGreaterThanOrEqualTo(min), Schema.isLessThanOrEqualTo(max)).annotate({ description });
+const id = str("Use a supplied spreadsheet id as is; search Drive only for a name.", 256, /^[A-Za-z0-9_-]+$/);
+const range = str("A1 range or named range; quote sheet titles and double internal apostrophes.", 512, /^[^\r\n]*[^.\r\n][^\r\n]*$/);
+const ranges = Schema.Array(range).check(Schema.isMinLength(1), Schema.isMaxLength(20));
+const cell = Schema.Union([Schema.String.check(isMaxChars(50000)), Schema.Finite, Schema.Boolean, Schema.Null]);
+const rows = Schema.Array(Schema.Array(cell).check(Schema.isMaxLength(18278)))
+    .check(Schema.isMinLength(1), Schema.isMaxLength(10000))
+    .annotate({
+    description: "Rows of scalar cells, at most 50000 cells total. null skips a cell; empty string clears it.",
+});
+const mode = Schema.Literals(["RAW", "USER_ENTERED"]).annotate({
+    description: "RAW stores literals; USER_ENTERED parses formulas, dates and numbers as typed.",
+});
+const title = (max) => str("Title on one line.", max, /^[^\r\n]*$/);
+const sheetFields = {
+    sheetId: Integer,
+    title: Schema.String,
+    index: Integer,
+    type: Schema.String,
+    hidden: Schema.Boolean,
+    rowCount: Integer,
+    columnCount: Integer,
+    frozenRowCount: Integer,
+    frozenColumnCount: Integer,
+};
+const updateFields = {
+    updatedRange: Schema.String,
+    updatedRows: Integer,
+    updatedColumns: Integer,
+    updatedCells: Integer,
+};
+const cuts = { truncated: Schema.Array(Schema.String) };
+const AnyObject = Schema.Record(Schema.String, Schema.Unknown);
+export const inputs = {
+    get_spreadsheet: Schema.Struct({ spreadsheetId: id }),
+    get_values: Schema.Struct({
+        spreadsheetId: id,
+        ranges,
+        valueRenderOption: Schema.optionalKey(Schema.Literals(["FORMATTED_VALUE", "UNFORMATTED_VALUE", "FORMULA"])),
+        dateTimeRenderOption: Schema.optionalKey(Schema.Literals(["SERIAL_NUMBER", "FORMATTED_STRING"])),
+        maxCells: Schema.optionalKey(int("Whole-row content budget; defaults to 2000 cells.", 1, 10000)),
+        maxBytes: Schema.optionalKey(int("Whole-page JSON byte budget; defaults to 192 KiB. Above that use a direct call.", 1024, 4194304)),
+        maxCellChars: Schema.optionalKey(int("Characters kept per cell; defaults to 5000. Read a cut cell alone with up to 50000.", 1, 50000)),
+        cursor: Schema.optionalKey(str("Opaque page.nextCursor; keep spreadsheet, ranges and render options unchanged.", 1024)),
+    }),
+    update_values: Schema.Struct({ spreadsheetId: id, range, values: rows, valueInputOption: mode }),
+    batch_update_values: Schema.Struct({
+        spreadsheetId: id,
+        data: Schema.Array(Schema.Struct({ range, values: rows })).check(Schema.isMinLength(1), Schema.isMaxLength(100)),
+        valueInputOption: mode,
+    }),
+    append_values: Schema.Struct({ spreadsheetId: id, range, values: rows, valueInputOption: mode }),
+    clear_values: Schema.Struct({ spreadsheetId: id, ranges }),
+    create_spreadsheet: Schema.Struct({
+        title: title(255),
+        sheetTitles: Schema.optionalKey(Schema.Array(title(100)).check(Schema.isMinLength(1), Schema.isMaxLength(50), Schema.makeFilter((values) => new Set(values).size === values.length, {
+            expected: "unique sheet titles",
+            toJsonSchema: () => ({ uniqueItems: true }),
+        }))),
+    }),
+    add_sheet: Schema.Struct({
+        spreadsheetId: id,
+        title: title(100),
+        index: Schema.optionalKey(int("Zero-based tab position; omit for last.", 0, 1000)),
+        rowCount: Schema.optionalKey(int("Grid rows.", 1, 1000000)),
+        columnCount: Schema.optionalKey(int("Grid columns.", 1, 18278)),
+    }),
+    batch_update_spreadsheet: Schema.Struct({
+        spreadsheetId: id,
+        requests: Schema.Array(Schema.Record(Schema.String, AnyObject)
+            .annotate({
+            description: "One reviewed Sheets Request kind and its object body; details provides nested contracts.",
+        })
+            .check(Schema.makeFilter((value) => Object.keys(value).length === 1, {
+            expected: "exactly one reviewed Sheets request kind",
+            toJsonSchema: () => ({ minProperties: 1, maxProperties: 1 }),
+        }))).check(Schema.isMinLength(1), Schema.isMaxLength(100)),
+    }),
+};
+export const outputs = {
+    get_spreadsheet: optional({
+        spreadsheetId: Schema.String,
+        title: Schema.String,
+        url: Schema.String,
+        locale: Schema.String,
+        timeZone: Schema.String,
+        sheets: Schema.Array(optional(sheetFields)),
+        namedRanges: Schema.Array(optional({ namedRangeId: Schema.String, name: Schema.String, sheetId: Integer, range: Schema.String })),
+        ...cuts,
+    }),
+    get_values: optional({
+        spreadsheetId: Schema.String,
+        valueRanges: Schema.Array(optional({
+            range: Schema.String,
+            values: Schema.Array(Schema.Array(cell)),
+            rowOffset: Integer,
+            rowCount: Integer,
+        })),
+        cellCount: Integer,
+        page: Schema.Struct({ hasMore: Schema.Boolean, nextCursor: Schema.optionalKey(Schema.String) }),
+        ...cuts,
+    }),
+    update_values: optional({ spreadsheetId: Schema.String, ...updateFields }),
+    batch_update_values: optional({
+        spreadsheetId: Schema.String,
+        totalUpdatedRows: Integer,
+        totalUpdatedColumns: Integer,
+        totalUpdatedCells: Integer,
+        totalUpdatedSheets: Integer,
+        updates: Schema.Array(optional(updateFields)),
+    }),
+    append_values: optional({ spreadsheetId: Schema.String, tableRange: Schema.String, ...updateFields }),
+    clear_values: optional({ spreadsheetId: Schema.String, clearedRanges: Schema.Array(Schema.String) }),
+    create_spreadsheet: optional({
+        spreadsheetId: Schema.String,
+        title: Schema.String,
+        url: Schema.String,
+        sheets: Schema.Array(optional({ sheetId: Integer, title: Schema.String })),
+    }),
+    add_sheet: optional({ spreadsheetId: Schema.String, ...sheetFields }),
+    batch_update_spreadsheet: optional({
+        spreadsheetId: Schema.String,
+        replies: Schema.Array(AnyObject),
+        note: Schema.String,
+        ...cuts,
+    }),
+};