@oomol-lab/open-connector 1.7.0 → 1.8.0

package/src/providers/googledrive/trigger-on-file-change.js

@@ -0,0 +1,258 @@
+import { eventsPollOutputs, maximumPollEventsPerPage, PermanentPollError, PollConnectionError, TransientPollError, } from "../../triggers/common/poll.js";
+import { snapshot } from "./trigger-on-file-change.definition.js";
+const folderMimeType = "application/vnd.google-apps.folder";
+const listFields = "nextPageToken,incompleteSearch,files(id,name,mimeType,createdTime,modifiedTime,parents,trashed,webViewLink,driveId,size,version,lastModifyingUser(displayName,emailAddress))";
+const transientReasons = new Set([
+    "rateLimitExceeded",
+    "userRateLimitExceeded",
+    "dailyLimitExceeded",
+    "sharingRateLimitExceeded",
+]);
+const permanentReasons = new Set(["insufficientFilePermissions", "appNotAuthorizedToFile"]);
+export const googleDriveFileChange = {
+    buildOutputs: eventsPollOutputs,
+    snapshot,
+    async poll(context) {
+        const config = resolveConfig(context.config);
+        if (context.checkpoint === null)
+            return seed(context, config);
+        const checkpoint = readCheckpoint(context.checkpoint);
+        if (checkpoint.changeType !== config.changeType) {
+            return {
+                checkpoint: seeded(context.now, config.changeType),
+                events: [],
+            };
+        }
+        return pollFolder(context, config, checkpoint);
+    },
+};
+function resolveConfig(value) {
+    return {
+        changeType: value.changeType,
+        driveId: value.driveId,
+        folderId: value.folderId,
+        itemTypes: new Set(value.itemTypes),
+        maxFilesPerPoll: value.maxFilesPerPoll,
+        mimeTypes: value.mimeTypes,
+        namePrefix: value.namePrefix,
+    };
+}
+function readCheckpoint(value) {
+    const checkpoint = record(value);
+    if (typeof checkpoint?.since != "string" || Number.isNaN(Date.parse(checkpoint.since))) {
+        throw new PermanentPollError("Google Drive checkpoint is invalid; recreate the Trigger.");
+    }
+    const boundary = checkpoint.boundaryKeys;
+    return {
+        since: checkpoint.since,
+        ...(typeof checkpoint.floor == "string" ? { floor: checkpoint.floor } : {}),
+        ...(typeof checkpoint.pageToken == "string" ? { pageToken: checkpoint.pageToken } : {}),
+        ...(typeof checkpoint.pageQuery == "string" ? { pageQuery: checkpoint.pageQuery } : {}),
+        ...(typeof checkpoint.changeType == "string" ? { changeType: checkpoint.changeType } : {}),
+        ...(typeof checkpoint.maxSeen == "string" ? { maxSeen: checkpoint.maxSeen } : {}),
+        ...(Array.isArray(boundary)
+            ? { boundaryKeys: boundary.filter((key) => typeof key == "string") }
+            : {}),
+    };
+}
+async function seed(context, config) {
+    const result = await get(context, `/drive/v3/files/${encodeURIComponent(config.folderId)}`, {
+        fields: "id,name,mimeType,driveId,trashed",
+        supportsAllDrives: "true",
+    });
+    success(result, "folder probe");
+    const probe = record(result.data);
+    if (probe == null)
+        throw new TransientPollError("Google Drive folder probe returned no payload.");
+    if (probe.mimeType !== folderMimeType)
+        throw new PermanentPollError("Google Drive folderId does not point to a folder.");
+    if (probe.trashed === true)
+        throw new PermanentPollError("The Google Drive folder is in the trash.");
+    if (config.driveId.length > 0 && (probe.driveId ?? "") !== config.driveId) {
+        throw new PermanentPollError("The configured Google Drive shared drive does not contain this folder.");
+    }
+    return { checkpoint: seeded(context.now, config.changeType), events: [] };
+}
+function seeded(now, change) {
+    const since = now.toISOString();
+    return { changeType: change, floor: since, since };
+}
+async function pollFolder(context, config, checkpoint) {
+    const query = filesQuery(config, checkpoint.since, checkpoint.floor);
+    const fingerprint = `${config.driveId}|${query}`;
+    const pageToken = checkpoint.pageQuery == fingerprint ? checkpoint.pageToken : undefined;
+    const result = await get(context, "/drive/v3/files", {
+        corpora: config.driveId.length == 0 ? "allDrives" : "drive",
+        driveId: config.driveId.length == 0 ? undefined : config.driveId,
+        fields: listFields,
+        includeItemsFromAllDrives: "true",
+        pageSize: Math.min(config.maxFilesPerPoll, maximumPollEventsPerPage),
+        pageToken,
+        q: query,
+        spaces: "drive",
+        supportsAllDrives: "true",
+    });
+    success(result, "files list");
+    const page = (record(result.data) ?? {});
+    const delivered = new Set(checkpoint.boundaryKeys ?? []);
+    const events = [];
+    const consumed = [];
+    let maxSeen = pageToken == null ? undefined : checkpoint.maxSeen;
+    for (const file of page.files ?? []) {
+        if (file.id == null || file.id.length == 0)
+            continue;
+        const timestamp = trackedTime(file, config.changeType);
+        if (timestamp == null)
+            continue;
+        const value = event(file, file.id, timestamp, config.changeType);
+        consumed.push(value.dedupeKey);
+        if (later(timestamp, maxSeen))
+            maxSeen = timestamp;
+        if (!delivered.has(value.dedupeKey))
+            events.push(value);
+    }
+    if (page.incompleteSearch === true) {
+        const drain = pageToken == null ? {} : pageState(pageToken, fingerprint, maxSeen);
+        return {
+            checkpoint: checkpointValue(checkpoint, config.changeType, checkpoint.since, consumed, drain),
+            events,
+        };
+    }
+    if (page.nextPageToken) {
+        return {
+            checkpoint: checkpointValue(checkpoint, config.changeType, checkpoint.since, consumed, pageState(page.nextPageToken, fingerprint, maxSeen)),
+            events,
+            hasMore: true,
+        };
+    }
+    const since = maxSeen ?? checkpoint.since;
+    return {
+        checkpoint: checkpointValue(checkpoint, config.changeType, since, consumed),
+        events,
+    };
+}
+function pageState(pageToken, pageQuery, maxSeen) {
+    return { pageQuery, pageToken, ...(maxSeen == null ? {} : { maxSeen }) };
+}
+function checkpointValue(previous, change, since, consumed, page = {}) {
+    const boundaryKeys = [...new Set([...(previous.boundaryKeys ?? []), ...consumed])]
+        .map((key) => ({ at: Date.parse(key.slice(key.indexOf(":") + 1)), key }))
+        .filter(({ at }) => at >= windowStart(since, previous.floor))
+        .toSorted((left, right) => right.at - left.at)
+        .slice(0, 200)
+        .map(({ key }) => key);
+    return {
+        changeType: change,
+        since,
+        ...floorField(previous.floor, since),
+        ...page,
+        ...(boundaryKeys.length == 0 ? {} : { boundaryKeys }),
+    };
+}
+function filesQuery(config, since, floorValue) {
+    const field = config.changeType == "created" ? "createdTime" : "modifiedTime";
+    const terms = [
+        `'${escape(config.folderId)}' in parents`,
+        "trashed = false",
+        `${field} >= '${new Date(windowStart(since, floorValue)).toISOString()}'`,
+    ];
+    if (!config.itemTypes.has("folder"))
+        terms.push(`mimeType != '${folderMimeType}'`);
+    else if (!config.itemTypes.has("file"))
+        terms.push(`mimeType = '${folderMimeType}'`);
+    if (config.mimeTypes.length > 0)
+        terms.push(`(${config.mimeTypes.map((type) => `mimeType = '${escape(type)}'`).join(" or ")})`);
+    if (config.namePrefix.length > 0)
+        terms.push(`name contains '${escape(config.namePrefix)}'`);
+    return terms.join(" and ");
+}
+function windowStart(since, floorValue) {
+    const start = Date.parse(since) - 60_000;
+    const minimum = floorValue == null ? Number.NaN : Date.parse(floorValue);
+    return Number.isNaN(minimum) ? start : Math.max(start, minimum);
+}
+function floorField(value, since) {
+    if (value == null || Number.isNaN(Date.parse(value)) || Date.parse(since) - 60_000 >= Date.parse(value))
+        return {};
+    return { floor: value };
+}
+function trackedTime(file, change) {
+    const value = change == "created" ? file.createdTime : file.modifiedTime;
+    return value == null || value.length == 0 || Number.isNaN(Date.parse(value)) ? undefined : value;
+}
+function event(file, id, timestamp, change) {
+    const itemType = file.mimeType == folderMimeType ? "folder" : "file";
+    const user = file.lastModifyingUser;
+    return {
+        dedupeKey: `${id}:${timestamp}`,
+        payload: {
+            createdTime: file.createdTime ?? null,
+            driveId: file.driveId ?? null,
+            eventType: `${itemType}_${change}`,
+            fileId: id,
+            itemType,
+            lastModifyingUser: user == null ? null : { displayName: user.displayName ?? "", emailAddress: user.emailAddress ?? "" },
+            mimeType: file.mimeType ?? "",
+            modifiedTime: file.modifiedTime ?? null,
+            name: file.name ?? "",
+            parents: file.parents ?? [],
+            ...(file.size == null ? {} : { size: file.size }),
+            webViewLink: file.webViewLink ?? null,
+        },
+    };
+}
+async function get(context, endpoint, query) {
+    try {
+        return await context.connector.execute({
+            endpoint,
+            method: "GET",
+            query: Object.fromEntries(Object.entries(query).filter((entry) => entry[1] != null)),
+        }, context.signal);
+    }
+    catch (cause) {
+        throw new TransientPollError(`Google Drive proxy request to ${endpoint} failed.`, { cause });
+    }
+}
+function success(result, operation) {
+    if (result.status >= 200 && result.status < 300)
+        return;
+    if (result.status == 400 || result.status == 404)
+        throw new PermanentPollError(`Google Drive ${operation} rejected the configuration.`);
+    if (result.status == 401)
+        throw new PollConnectionError(`Google Drive ${operation} rejected the Connection.`);
+    if (result.status == 403) {
+        const values = reasons(result.data);
+        if (values.some((reason) => transientReasons.has(reason)))
+            throw new TransientPollError(`Google Drive ${operation} was rate limited.`);
+        if (values.some((reason) => permanentReasons.has(reason)))
+            throw new PermanentPollError(`Google Drive ${operation} was rejected by an ACL.`);
+        if (insufficientScopes(result.data))
+            throw new PollConnectionError(`Google Drive ${operation} needs additional scopes.`);
+    }
+    throw new TransientPollError(`Google Drive ${operation} failed with status ${result.status}.`);
+}
+function reasons(data) {
+    const error = record(record(data)?.error);
+    const nested = [error?.errors, error?.details].flatMap((value) => (Array.isArray(value) ? value : []));
+    return [...nested.map((value) => record(value)?.reason), error?.status].filter((value) => typeof value == "string");
+}
+function insufficientScopes(data) {
+    if (reasons(data).includes("ACCESS_TOKEN_SCOPE_INSUFFICIENT"))
+        return true;
+    const message = record(record(data)?.error)?.message;
+    return typeof message == "string" && message.toLowerCase().includes("insufficient authentication scopes");
+}
+function escape(value) {
+    return value.replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+}
+function later(candidate, current) {
+    const candidateMs = Date.parse(candidate);
+    if (Number.isNaN(candidateMs))
+        return false;
+    return current == null || Number.isNaN(Date.parse(current)) || candidateMs > Date.parse(current);
+}
+function record(value) {
+    return value != null && typeof value == "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/src/providers/googlesheets/executors.d.ts

@@ -1,4 +1,6 @@
 import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
+import type { IntegrationDefinition } from "../../triggers/common/integration.ts";
+import type { PollDefinition } from "../../triggers/common/poll.ts";
 import type { ProviderActionHandlers } from "../provider-runtime.ts";
 import type { OAuthProviderContext } from "../provider-runtime.ts";
 type ActionContext = OAuthProviderContext;
@@ -7,4 +9,5 @@ export declare const googlesheetsActionHandlers: ProviderActionHandlers<"googles
 export declare const executors: ProviderExecutors;
 export declare const credentialValidators: CredentialValidators;
 export declare const proxy: ProviderProxyExecutor;
+export declare const triggers: readonly (IntegrationDefinition | PollDefinition)[];
 export {};

package/src/providers/googlesheets/executors.js

@@ -7,6 +7,7 @@ import { aggregateColumnData, createSpreadsheetColumn, createSpreadsheetRow, loo
 import { batchGetValues, batchGetValuesByDataFilter, getValues } from "./runtime-values.js";
 import { appendValues, batchClearValues, batchClearValuesByDataFilter, batchUpdateValuesByDataFilter, clearValues, updateValues, updateValuesBatch, } from "./runtime-values.js";
 import { googlesheetsOAuthScopes } from "./scopes.js";
+import { googleSheetsRowAdded } from "./trigger-on-row-added.js";
 const service = "googlesheets";
 const implementedActionHandlers = {
     search_spreadsheets(input, { accessToken, fetcher }) {
@@ -158,3 +159,4 @@ export const proxy = defineProviderProxy({
     baseUrl: "https://sheets.googleapis.com/v4",
     auth: googleBearerProxyAuth(googlesheetsOAuthScopes),
 });
+export const triggers = [googleSheetsRowAdded];

package/src/providers/googlesheets/trigger-on-row-added.d.ts

@@ -0,0 +1,2 @@
+import type { PollDefinition } from "../../triggers/common/poll.ts";
+export declare const googleSheetsRowAdded: PollDefinition;

package/src/providers/googlesheets/trigger-on-row-added.definition.d.ts

@@ -0,0 +1,4 @@
+import type { TriggerKeySnapshot } from "../../triggers/common/types.ts";
+export declare const snapshot: TriggerKeySnapshot & {
+    readonly type: "poll";
+};

package/src/providers/googlesheets/trigger-on-row-added.definition.js

@@ -0,0 +1,54 @@
+import { jsonSchema as s } from "../../core/json-schema.js";
+const eventSchema = s.object({
+    row: { type: "object" },
+    rowNumber: s.integer(),
+    sheetId: s.integer(),
+    sheetTitle: s.string(),
+    spreadsheetId: s.string(),
+    values: s.array({}),
+}, { additionalProperties: false, required: ["spreadsheetId", "sheetId", "sheetTitle", "rowNumber", "row", "values"] });
+export const snapshot = {
+    configInputs: [
+        {
+            handle: "columnRange",
+            jsonSchema: s.string({ pattern: "^[A-Za-z]{1,3}(?::[A-Za-z]{1,3})?$" }),
+            nullable: false,
+            value: "A:ZZZ",
+        },
+        {
+            handle: "dateTimeRender",
+            jsonSchema: s.stringEnum(["FORMATTED_STRING", "SERIAL_NUMBER"]),
+            nullable: false,
+            value: "FORMATTED_STRING",
+        },
+        {
+            handle: "firstDataRow",
+            jsonSchema: s.integer({ minimum: 1 }),
+            nullable: false,
+            value: 2,
+        },
+        { handle: "headerRow", jsonSchema: s.integer({ minimum: 1 }), nullable: false, value: 1 },
+        {
+            handle: "maxRowsPerPoll",
+            jsonSchema: s.integer({ maximum: 500, minimum: 1 }),
+            nullable: false,
+            value: 100,
+        },
+        { handle: "sheet", jsonSchema: s.string({ minLength: 1 }), nullable: false },
+        { handle: "spreadsheetId", jsonSchema: s.string({ minLength: 1 }), nullable: false },
+        {
+            handle: "valueRender",
+            jsonSchema: s.stringEnum(["UNFORMATTED_VALUE", "FORMATTED_VALUE", "FORMULA"]),
+            nullable: false,
+            value: "UNFORMATTED_VALUE",
+        },
+    ],
+    definitionVersion: 2,
+    description: "Polls a sheet and triggers once for every new row appended below the last row already seen.",
+    displayName: "New Row Added",
+    key: "googlesheets.on_row_added",
+    name: "on_row_added",
+    outputs: [{ handle: "events", jsonSchema: s.array(eventSchema), nullable: false }],
+    provider: "googlesheets",
+    type: "poll",
+};

package/src/providers/googlesheets/trigger-on-row-added.js

@@ -0,0 +1,234 @@
+import { eventsPollOutputs, maximumPollEventsPerPage, PermanentPollError, PollConnectionError, TransientPollError, } from "../../triggers/common/poll.js";
+import { snapshot } from "./trigger-on-row-added.definition.js";
+const permissionMarkers = [
+    "permission_denied",
+    "accessnotconfigured",
+    "insufficientfilepermissions",
+    "appnotauthorizedtofile",
+    "the caller does not have permission",
+    "has not been used in project",
+];
+const quotaMarkers = ["ratelimitexceeded", "dailylimitexceeded"];
+export const googleSheetsRowAdded = {
+    buildOutputs: eventsPollOutputs,
+    snapshot,
+    async poll(context) {
+        const config = resolveConfig(context.config);
+        if (context.checkpoint === null) {
+            const sheet = await resolveSheet(context, config);
+            return { checkpoint: await anchor(context, config, sheet), events: [] };
+        }
+        const checkpoint = readCheckpoint(context.checkpoint);
+        const sheet = await resolveSheet(context, config);
+        if (checkpoint.spreadsheetId !== config.spreadsheetId || checkpoint.sheetId !== sheet.sheetId) {
+            return { checkpoint: await anchor(context, config, sheet), events: [] };
+        }
+        if (checkpoint.lastRowNumber > sheet.rowCount)
+            return { checkpoint: await anchor(context, config, sheet), events: [] };
+        const headers = await header(context, config, sheet);
+        const start = Math.min(Math.max(config.firstDataRow, checkpoint.lastRowNumber + 1), sheet.rowCount);
+        const end = Math.min(start + Math.min(config.maxRowsPerPoll, maximumPollEventsPerPage) - 1, sheet.rowCount);
+        const rows = await values(context, config, sheet, start, end, "row window fetch");
+        let last = start + rows.length - 1;
+        if (rows.length < end - start + 1) {
+            // API 会省略窗口尾部的空行，确认实际表尾后才能推进游标。
+            const tail = await lastNonEmptyRow(context, config, sheet);
+            if (tail < checkpoint.lastRowNumber)
+                return { checkpoint: { ...checkpoint, lastRowNumber: tail }, events: [] };
+            last = Math.min(end, tail);
+        }
+        if (last <= checkpoint.lastRowNumber)
+            return { checkpoint, events: [] };
+        const events = [];
+        let filtered = 0;
+        for (const [index, cells] of rows.entries()) {
+            const rowNumber = start + index;
+            if (rowNumber <= checkpoint.lastRowNumber)
+                continue;
+            if (rowNumber == config.headerRow || empty(cells)) {
+                filtered += 1;
+                continue;
+            }
+            events.push(await event(config, sheet, rowNumber, cells, headers));
+        }
+        const hasMore = last == end && end < sheet.rowCount;
+        return {
+            checkpoint: {
+                lastRowNumber: last,
+                sheetId: sheet.sheetId,
+                spreadsheetId: config.spreadsheetId,
+            },
+            events,
+            filtered,
+            ...(hasMore ? { hasMore: true } : {}),
+        };
+    },
+};
+function resolveConfig(value) {
+    const range = value.columnRange.trim();
+    const separator = range.indexOf(":");
+    const colStart = separator < 0 ? range : range.slice(0, separator);
+    const colEnd = separator < 0 ? range : range.slice(separator + 1);
+    const spreadsheet = value.spreadsheetId.trim();
+    return {
+        colEnd,
+        colStart,
+        dateTimeRender: value.dateTimeRender,
+        firstDataRow: value.firstDataRow,
+        headerRow: value.headerRow,
+        maxRowsPerPoll: value.maxRowsPerPoll,
+        sheet: value.sheet,
+        spreadsheetId: /\/spreadsheets\/d\/([A-Za-z0-9_-]+)/.exec(spreadsheet)?.[1] ?? spreadsheet,
+        valueRender: value.valueRender,
+    };
+}
+function readCheckpoint(value) {
+    const checkpoint = record(value);
+    if (typeof checkpoint?.spreadsheetId != "string" ||
+        !Number.isInteger(checkpoint.sheetId) ||
+        !Number.isInteger(checkpoint.lastRowNumber)) {
+        throw new PermanentPollError("Google Sheets checkpoint is invalid; recreate the Trigger.");
+    }
+    return {
+        lastRowNumber: checkpoint.lastRowNumber,
+        sheetId: checkpoint.sheetId,
+        spreadsheetId: checkpoint.spreadsheetId,
+    };
+}
+async function resolveSheet(context, config) {
+    const result = await get(context, `/spreadsheets/${encodeURIComponent(config.spreadsheetId)}`, {
+        fields: "sheets.properties(sheetId,title,sheetType,gridProperties)",
+    });
+    if (result.status == 404)
+        throw new PermanentPollError("The Google Sheets spreadsheet was not found.");
+    success(result, "spreadsheet metadata fetch");
+    const raw = record(result.data)?.sheets;
+    const properties = Array.isArray(raw)
+        ? raw.map((value) => record(record(value)?.properties))
+        : [];
+    const candidates = properties.filter((value) => value != null);
+    const byId = /^\d+$/.test(config.sheet)
+        ? candidates.find(({ sheetId }) => sheetId === Number(config.sheet))
+        : undefined;
+    const match = byId ?? candidates.find(({ title }) => title === config.sheet);
+    if (match == null)
+        throw new PermanentPollError(`Google Sheets tab "${config.sheet}" does not exist.`);
+    if (match.sheetType != null && match.sheetType !== "GRID")
+        throw new PermanentPollError("The Google Sheets tab is not a grid sheet.");
+    const rowCount = match.gridProperties?.rowCount;
+    if (match.sheetId == null || match.title == null || rowCount == null) {
+        throw new TransientPollError("Google Sheets tab metadata is incomplete.");
+    }
+    return { rowCount, sheetId: match.sheetId, title: match.title };
+}
+async function anchor(context, config, sheet) {
+    return {
+        lastRowNumber: await lastNonEmptyRow(context, config, sheet),
+        sheetId: sheet.sheetId,
+        spreadsheetId: config.spreadsheetId,
+    };
+}
+async function lastNonEmptyRow(context, config, sheet) {
+    if (sheet.rowCount < config.firstDataRow)
+        return config.firstDataRow - 1;
+    const rows = await values(context, config, sheet, config.firstDataRow, sheet.rowCount, "full-range scan");
+    return rows.length == 0 ? config.firstDataRow - 1 : config.firstDataRow + rows.length - 1;
+}
+async function header(context, config, sheet) {
+    const result = await get(context, valuesEndpoint(config, sheet, config.headerRow, config.headerRow), {
+        majorDimension: "ROWS",
+        valueRenderOption: "FORMATTED_VALUE",
+    });
+    success(result, "header row fetch");
+    return readValues(result.data)[0] ?? [];
+}
+async function values(context, config, sheet, start, end, operation) {
+    const result = await get(context, valuesEndpoint(config, sheet, start, end), {
+        dateTimeRenderOption: config.dateTimeRender,
+        majorDimension: "ROWS",
+        valueRenderOption: config.valueRender,
+    });
+    success(result, operation);
+    return readValues(result.data);
+}
+function readValues(data) {
+    const rows = record(data)?.values;
+    return Array.isArray(rows) ? rows : [];
+}
+function empty(cells) {
+    return cells.every((cell) => cell === "" || cell == null);
+}
+async function event(config, sheet, rowNumber, cells, headers) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(cells)));
+    const hash = [...new Uint8Array(digest)]
+        .slice(0, 8)
+        .map((value) => value.toString(16).padStart(2, "0"))
+        .join("");
+    const row = {};
+    const start = columnNumber(config.colStart);
+    for (const [index, cell] of cells.entries()) {
+        const heading = headers[index];
+        row[typeof heading == "string" && heading.length > 0 ? heading : columnLetters(start + index)] = cell;
+    }
+    return {
+        dedupeKey: `${sheet.sheetId}:${rowNumber}:${hash}`,
+        payload: {
+            row,
+            rowNumber,
+            sheetId: sheet.sheetId,
+            sheetTitle: sheet.title,
+            spreadsheetId: config.spreadsheetId,
+            values: cells,
+        },
+    };
+}
+function valuesEndpoint(config, sheet, start, end) {
+    const title = encodeURIComponent(`'${sheet.title.replaceAll("'", "''")}'`);
+    return `/spreadsheets/${encodeURIComponent(config.spreadsheetId)}/values/${title}!${config.colStart}${start}:${config.colEnd}${end}`;
+}
+async function get(context, endpoint, query) {
+    try {
+        return await context.connector.execute({ endpoint, method: "GET", query }, context.signal);
+    }
+    catch (cause) {
+        throw new TransientPollError(`Google Sheets proxy request to ${endpoint} failed.`, { cause });
+    }
+}
+function success(result, operation) {
+    if (result.status >= 200 && result.status < 300)
+        return;
+    if (result.status == 401)
+        throw new PollConnectionError(`Google Sheets ${operation} rejected the Connection.`);
+    const haystack = JSON.stringify(result.data ?? null).toLowerCase();
+    if (result.status == 403) {
+        if (quotaMarkers.some((marker) => haystack.includes(marker)))
+            throw new TransientPollError(`Google Sheets ${operation} was rate limited.`);
+        if (permissionMarkers.some((marker) => haystack.includes(marker))) {
+            throw new PollConnectionError(`Google Sheets ${operation} rejected the Connection.`);
+        }
+    }
+    if (result.status == 400 && haystack.includes("unable to parse range")) {
+        throw new PermanentPollError("Google Sheets rejected the configured range.");
+    }
+    if (result.status == 413)
+        throw new PermanentPollError("Google Sheets response is too large; narrow columnRange.");
+    throw new TransientPollError(`Google Sheets ${operation} failed with status ${result.status}.`);
+}
+function columnNumber(letters) {
+    let value = 0;
+    for (const letter of letters.toUpperCase())
+        value = value * 26 + letter.charCodeAt(0) - 64;
+    return value;
+}
+function columnLetters(value) {
+    let letters = "";
+    for (let rest = value; rest > 0; rest = Math.floor((rest - 1) / 26)) {
+        letters = String.fromCharCode(65 + ((rest - 1) % 26)) + letters;
+    }
+    return letters;
+}
+function record(value) {
+    return value != null && typeof value == "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/src/providers/hithink_finance/runtime.js

@@ -393,7 +393,7 @@ function getPool(get, path, input, context) {
 function getFinancialStatements(path, input, context) {
     return get(path, {
         thscode: requiredInputString(input.thscode, "thscode"),
-        period: optionalString(input.period),
+        period: optionalString(input.period) ?? "annual",
         limit: optionalNumber(input.limit),
         start: optionalNumber(input.startTimeMs),
         end: optionalNumber(input.endTimeMs),

package/src/providers/indexed/executors.d.ts

@@ -0,0 +1,4 @@
+import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
+export declare const executors: ProviderExecutors;
+export declare const proxy: ProviderProxyExecutor;
+export declare const credentialValidators: CredentialValidators;

package/src/providers/indexed/executors.js

@@ -0,0 +1,16 @@
+import { defineApiKeyProviderExecutors, defineProviderProxy } from "../provider-runtime.js";
+import { indexedActionHandlers, indexedApiBaseUrl, readIndexedError, validateIndexedCredential } from "./runtime.js";
+const service = "indexed";
+export const executors = defineApiKeyProviderExecutors(service, indexedActionHandlers, {
+    skipDnsValidation: true,
+});
+export const proxy = defineProviderProxy({
+    service,
+    baseUrl: indexedApiBaseUrl,
+    auth: { type: "api_key_header", name: "X-API-Key" },
+    readError: readIndexedError,
+    skipDnsValidation: true,
+});
+export const credentialValidators = {
+    apiKey: validateIndexedCredential,
+};

package/src/providers/indexed/runtime.d.ts

@@ -0,0 +1,26 @@
+import type { CredentialValidationResult } from "../../core/types.ts";
+import type { ApiKeyProviderContext, ProviderActionHandlers } from "../provider-runtime.ts";
+import { ProviderRequestError } from "../provider-runtime.ts";
+export declare const indexedApiBaseUrl = "https://indexed.vc/api/v1";
+type IndexedPhase = "validate" | "execute";
+type IndexedActionHandler = (input: Record<string, unknown>, context: ApiKeyProviderContext) => Promise<unknown>;
+export declare const indexedActionHandlers: ProviderActionHandlers<"indexed", IndexedActionHandler>;
+/**
+ * Validate a key with GET /usage, which the API documents as free of credit charges.
+ */
+export declare function validateIndexedCredential(input: {
+    apiKey: string;
+}, options: {
+    fetcher: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<CredentialValidationResult>;
+/**
+ * Read an Indexed error response and map it onto the runtime's status conventions.
+ * 402 is a billing state (credits exhausted), reported as insufficient_credit.
+ * 403 TIER_UPGRADE_REQUIRED is a plan limit rather than a credential failure, so
+ * it is reported as invalid input instead of prompting a reconnect. During key
+ * validation a 401 or 403 is a field error on the submitted key. Every other
+ * status keeps its upstream value, so a 404 stays a not-found result.
+ */
+export declare function readIndexedError(response: Response, phase?: IndexedPhase): Promise<ProviderRequestError>;
+export {};