@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/types/io/google-docs/GoogleDocsService.d.mts

@@ -0,0 +1,188 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Google Docs service
+ * @summary Extends {@link HttpApiServiceConfig} with an optional OAuth
+ * `token` (preferred) and an optional `apiKey`. When omitted, the
+ * `io.googleDocs` environment slice supplies the same values (plus optional
+ * `baseUrl`/`timeout`). At least one credential is required; the token wins
+ * when both are set.
+ * @category IO
+ * @memberOf module:integrations/io/google-docs/service
+ */
+export interface GoogleDocsServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Google OAuth access token
+     * @summary Sent as `Authorization: Bearer <token>` when present.
+     */
+    token?: string;
+    /**
+     * @description Google API key
+     * @summary Sent as `X-Goog-Api-Key` only when no OAuth token is configured.
+     */
+    apiKey?: string;
+}
+/**
+ * @description Input for replacing all matching text in a document
+ * @summary Carries the `documentId`, the `find` text, its `replace`ment, and
+ * whether matching is case-sensitive.
+ * @category IO
+ * @memberOf module:integrations/io/google-docs/service
+ */
+export interface GoogleDocsReplaceInput {
+    /**
+     * @description Document ID to update
+     */
+    documentId: string;
+    /**
+     * @description Text to search for
+     */
+    find: string;
+    /**
+     * @description Replacement text (defaults to the empty string)
+     */
+    replace: string;
+    /**
+     * @description Whether matching is case-sensitive (default `false`)
+     */
+    matchCase?: boolean;
+}
+/**
+ * @description Google Docs API integration service
+ * @summary An undecorated HTTP service for reading and creating documents,
+ * running raw batch updates, appending text, and replacing all matching text.
+ * Every operation needs either an OAuth token or an API key; missing
+ * credentials or identifiers raise `InternalError`, and transport failures are
+ * mapped to decaf errors via {@link httpError}.
+ * @class GoogleDocsService
+ * @extends HttpApiService
+ * @category IO
+ * @example
+ * ```ts
+ * import { GoogleDocsService } from "@decaf-ts/integrations/io/google-docs";
+ *
+ * const docs = new GoogleDocsService();
+ * await docs.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GOOGLE_DOCS_TOKEN,
+ * });
+ * await docs.appendText(process.env.GOOGLE_DOC_ID ?? "", "New paragraph");
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as GoogleDocsService
+ *   participant API as Google Docs API
+ *   Caller->>Service: appendText(documentId, text)
+ *   activate Service
+ *   Service->>Service: requireAuth()
+ *   Service->>API: GET /documents/{id}
+ *   activate API
+ *   API-->>Service: body content endIndex
+ *   deactivate API
+ *   Service->>API: POST /documents/{id}:batchUpdate
+ *   activate API
+ *   API-->>Service: batch update result
+ *   deactivate API
+ *   Service-->>Caller: batch update result
+ *   deactivate Service
+ * @memberOf module:integrations/io/google-docs/service
+ */
+export declare class GoogleDocsService extends HttpApiService<GoogleDocsServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Google Docs";
+    /**
+     * @description The Google Docs API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://docs.googleapis.com/v1"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Google Docs authentication headers
+     * @summary Prefers `Authorization: Bearer <token>`, falls back to
+     * `X-Goog-Api-Key: <apiKey>`, and returns no headers when neither is set.
+     * @param {GoogleDocsServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authentication headers.
+     */
+    protected authHeaders(config: GoogleDocsServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Google Docs credentials and defaults from the environment
+     * @summary Reads the `io.googleDocs` slice and returns a partial config when
+     * a token or API key is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<GoogleDocsServiceConfig> | undefined} A partial config, or `undefined` when no credential is configured.
+     */
+    protected configFromEnvironment(): Partial<GoogleDocsServiceConfig> | undefined;
+    /**
+     * @description Asserts that an OAuth token or API key is configured
+     * @summary Called by every operation before it touches the network.
+     * @returns {void}
+     * @throws {InternalError} When neither a token nor an API key is configured.
+     */
+    protected requireAuth(): void;
+    /**
+     * @description Fetches a Google Docs document
+     * @summary `GET`s `/documents/<id>` and returns the full document payload.
+     * @param {string} documentId - The document ID.
+     * @returns {Promise<unknown>} The document payload.
+     * @throws {InternalError} When no credential is configured or the document ID is empty.
+     * @throws {NotFoundError} When the document does not exist (HTTP 404).
+     * @throws {BadRequestError} When Google rejects the request.
+     */
+    getDocument(documentId: string): Promise<unknown>;
+    /**
+     * @description Creates a Google Docs document
+     * @summary `POST`s a new document with the given title and returns its
+     * payload (including `documentId`).
+     * @param {string} title - The new document title.
+     * @returns {Promise<unknown>} The created document payload.
+     * @throws {InternalError} When no credential is configured or the title is empty.
+     * @throws {BadRequestError} When Google rejects the request.
+     */
+    createDocument(title: string): Promise<unknown>;
+    /**
+     * @description Applies a raw Google Docs batch update
+     * @summary `POST`s the `requests` array to `/documents/<id>:batchUpdate`
+     * unchanged, allowing any Docs API request type.
+     * @param {string} documentId - The document ID.
+     * @param {unknown[]} requests - The Docs API request objects.
+     * @returns {Promise<unknown>} The batch update response payload.
+     * @throws {InternalError} When no credential is configured, or the document ID or requests are missing.
+     * @throws {NotFoundError} When the document does not exist (HTTP 404).
+     * @throws {BadRequestError} When Google rejects a request.
+     */
+    batchUpdate(documentId: string, requests: unknown[]): Promise<unknown>;
+    /**
+     * @description Appends text to the end of a Google Docs document
+     * @summary Reads the document to find the final `endIndex`, then inserts the
+     * text just before it through a `batchUpdate`.
+     * @param {string} documentId - The document ID.
+     * @param {string} text - The text to append.
+     * @returns {Promise<unknown>} The batch update response payload.
+     * @throws {InternalError} When no credential is configured, or the document ID or text is empty.
+     * @throws {NotFoundError} When the document does not exist (HTTP 404).
+     * @throws {BadRequestError} When Google rejects the update.
+     */
+    appendText(documentId: string, text: string): Promise<unknown>;
+    /**
+     * @description Replaces all matching text in a Google Docs document
+     * @summary Sends a `replaceAllText` request honoring the `matchCase` option
+     * and returns the batch update response payload.
+     * @param {GoogleDocsReplaceInput} input - The document, find/replace text, and case option.
+     * @returns {Promise<unknown>} The batch update response payload.
+     * @throws {InternalError} When no credential is configured, or the document ID or find text is empty.
+     * @throws {NotFoundError} When the document does not exist (HTTP 404).
+     * @throws {BadRequestError} When Google rejects the update.
+     * @example
+     * ```ts
+     * await docs.replaceAllText({
+     *   documentId: "abc123",
+     *   find: "TODO",
+     *   replace: "DONE",
+     *   matchCase: true,
+     * });
+     * ```
+     */
+    replaceAllText(input: GoogleDocsReplaceInput): Promise<unknown>;
+}

package/lib/types/io/google-docs/index.d.cts

@@ -0,0 +1 @@
+export * from "./GoogleDocsService.d.cts";

package/lib/types/io/google-docs/index.d.mts

@@ -0,0 +1 @@
+export * from "./GoogleDocsService.d.mts";

package/lib/types/io/google-sheets/GoogleSheetsService.d.cts

@@ -0,0 +1,204 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @description Configuration for the Google Sheets service
+ * @summary Extends {@link HttpApiServiceConfig} with either an OAuth token
+ * (preferred, sent as a bearer token) or an API key (sent as
+ * `X-Goog-Api-Key`; read-only against public spreadsheets). When omitted, the
+ * `io.googleSheets` environment slice supplies both (and optional
+ * `baseUrl`/`timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Google OAuth access token
+     * @summary Sent as `Authorization: Bearer <token>`; takes precedence over the API key.
+     */
+    token?: string;
+    /**
+     * @description Google API key
+     * @summary Sent as `X-Goog-Api-Key` when no OAuth token is configured.
+     */
+    apiKey?: string;
+}
+/**
+ * @description Result of a Google Sheets values read or write
+ * @summary Echoes the target `spreadsheetId` and the A1 `range` Google
+ * actually served, the `majorDimension` of the payload, and the grid
+ * `values` as an array of rows (arrays of cell strings).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsValuesResult {
+    spreadsheetId: string;
+    range: string;
+    majorDimension?: string;
+    values: string[][];
+}
+/**
+ * @description Input for writing values into a Google Sheets range
+ * @summary Carries the target `spreadsheetId` and A1 `range`, the row
+ * `values` to write, and the `valueInputOption` controlling how Google
+ * interprets the cells (`"RAW"` stores text as-is, `"USER_ENTERED"` applies
+ * spreadsheet parsing and formulas; defaults to `"USER_ENTERED"`).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsWriteInput {
+    spreadsheetId: string;
+    range: string;
+    values: unknown[][];
+    valueInputOption?: "RAW" | "USER_ENTERED";
+}
+/**
+ * @description Google Sheets API integration service
+ * @summary An undecorated HTTP service for reading,
+ * updating, appending, and clearing values in A1 ranges of a spreadsheet, and
+ * for creating new spreadsheets. Every operation requires either an OAuth
+ * token or an API key (`requireAuth()`); ranges and spreadsheet IDs are
+ * URL-encoded, and transport failures are mapped to decaf errors via
+ * {@link httpError}.
+ * @class GoogleSheetsService
+ * @category IO
+ * @example
+ * ```ts
+ * import { GoogleSheetsService } from "@decaf-ts/integrations/io/google-sheets";
+ *
+ * const sheets = new GoogleSheetsService();
+ * await sheets.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GOOGLE_SHEETS_TOKEN,
+ * });
+ * const created = await sheets.createSpreadsheet("Metrics");
+ * await sheets.updateValues({
+ *   spreadsheetId: created.spreadsheetId,
+ *   range: "Sheet1!A1:B2",
+ *   values: [
+ *     ["date", "count"],
+ *     ["2026-01-01", "42"],
+ *   ],
+ * });
+ * ```
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export declare class GoogleSheetsService extends HttpApiService<GoogleSheetsServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Google Sheets";
+    /**
+     * @description The Google Sheets v4 values API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://sheets.googleapis.com/v4/spreadsheets"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Google Sheets authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries an OAuth token, otherwise the `X-Goog-Api-Key` header when
+     * an API key is configured, and no headers otherwise.
+     * @param {GoogleSheetsServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token or API key).
+     */
+    protected authHeaders(config: GoogleSheetsServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Google Sheets credentials and defaults from the environment
+     * @summary Reads the `io.googleSheets` environment slice and returns a
+     * partial config when a token or API key is configured, `undefined`
+     * otherwise. Values pass through `envString`/`envNumber` to reject
+     * unset-leaf proxies.
+     * @returns {Partial<GoogleSheetsServiceConfig> | undefined} A partial config, or `undefined` when neither token nor API key is configured.
+     */
+    protected configFromEnvironment(): Partial<GoogleSheetsServiceConfig> | undefined;
+    /**
+     * @description Asserts that the service was configured with OAuth credentials
+     * @summary Throws when the resolved config carries neither a `token` nor an
+     * `apiKey`; every operation calls this before issuing requests.
+     * @returns {void}
+     * @throws {InternalError} When neither an OAuth token nor an API key is configured.
+     */
+    protected requireAuth(): void;
+    /**
+     * @description URL-encodes an A1 range for the values API path
+     * @summary Ranges such as `Sheet1!A1:B2` contain characters that must be
+     * percent-encoded; all operations route the range through this helper.
+     * @param {string} range - The A1 notation range to encode.
+     * @returns {string} The URL-encoded range.
+     */
+    protected rangePath(range: string): string;
+    /**
+     * @description Reads values from an A1 range of a spreadsheet
+     * @summary `GET`s the values endpoint for the given `spreadsheetId` and
+     * `range` and returns the served range, major dimension, and the grid
+     * values (rows of cell strings). Requires credentials and both arguments.
+     * @param {string} spreadsheetId - The spreadsheet to read from.
+     * @param {string} range - The A1 notation range to read (e.g. `"Sheet1!A1:C10"`).
+     * @returns {Promise<GoogleSheetsValuesResult>} The served range and grid values.
+     * @throws {InternalError} When credentials are missing or the spreadsheet ID/range is empty.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    getValues(spreadsheetId: string, range: string): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Overwrites values in an A1 range of a spreadsheet
+     * @summary `PUT`s the row values to the values endpoint for the given
+     * `spreadsheetId` and `range`. Cells are interpreted according to
+     * `valueInputOption` (`"USER_ENTERED"` by default, `"RAW"` to store text
+     * verbatim), and the existing range content is replaced.
+     * @param {GoogleSheetsWriteInput} input - The target spreadsheet, range, values, and input interpretation.
+     * @returns {Promise<GoogleSheetsValuesResult>} The served range and the written values.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    updateValues(input: GoogleSheetsWriteInput): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Appends values after the last row of an A1 range's table
+     * @summary `POST`s the row values to the `:append` endpoint for the given
+     * `spreadsheetId` and `range`, inserting new rows after existing table data
+     * (`insertDataOption: "INSERT_ROWS"`). Cells are interpreted according to
+     * `valueInputOption` (`"USER_ENTERED"` by default). Use a single-row or
+     * single-column A1 range to anchor the table; Google reports the range the
+     * data actually landed in.
+     * @param {GoogleSheetsWriteInput} input - The target spreadsheet, anchor range, values, and input interpretation.
+     * @returns {Promise<GoogleSheetsValuesResult>} The range the appended rows landed in and the appended values.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    appendValues(input: GoogleSheetsWriteInput): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Clears all values in an A1 range of a spreadsheet
+     * @summary `POST`s the `:clear` endpoint for the given `spreadsheetId` and
+     * `range`, emptying the cells while preserving formatting, and returns the
+     * range Google actually cleared.
+     * @param {string} spreadsheetId - The spreadsheet to clear values in.
+     * @param {string} range - The A1 notation range to clear.
+     * @returns {Promise<{spreadsheetId: string, clearedRange: string}>} The cleared range as reported by Google.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    clearValues(spreadsheetId: string, range: string): Promise<{
+        spreadsheetId: string;
+        clearedRange: string;
+    }>;
+    /**
+     * @description Creates a new spreadsheet with the given title
+     * @summary `POST`s a spreadsheet resource with `properties.title` to the
+     * spreadsheets endpoint and returns the new spreadsheet's ID and URL.
+     * @param {string} title - The title for the new spreadsheet.
+     * @returns {Promise<{spreadsheetId: string, spreadsheetUrl?: string}>} The created spreadsheet's ID and URL.
+     * @throws {InternalError} When credentials are missing or the title is empty.
+     * @throws {NotFoundError} When Google answers with HTTP 404.
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status.
+     */
+    createSpreadsheet(title: string): Promise<{
+        spreadsheetId: string;
+        spreadsheetUrl?: string;
+    }>;
+}

package/lib/types/io/google-sheets/GoogleSheetsService.d.mts

@@ -0,0 +1,204 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Google Sheets service
+ * @summary Extends {@link HttpApiServiceConfig} with either an OAuth token
+ * (preferred, sent as a bearer token) or an API key (sent as
+ * `X-Goog-Api-Key`; read-only against public spreadsheets). When omitted, the
+ * `io.googleSheets` environment slice supplies both (and optional
+ * `baseUrl`/`timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Google OAuth access token
+     * @summary Sent as `Authorization: Bearer <token>`; takes precedence over the API key.
+     */
+    token?: string;
+    /**
+     * @description Google API key
+     * @summary Sent as `X-Goog-Api-Key` when no OAuth token is configured.
+     */
+    apiKey?: string;
+}
+/**
+ * @description Result of a Google Sheets values read or write
+ * @summary Echoes the target `spreadsheetId` and the A1 `range` Google
+ * actually served, the `majorDimension` of the payload, and the grid
+ * `values` as an array of rows (arrays of cell strings).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsValuesResult {
+    spreadsheetId: string;
+    range: string;
+    majorDimension?: string;
+    values: string[][];
+}
+/**
+ * @description Input for writing values into a Google Sheets range
+ * @summary Carries the target `spreadsheetId` and A1 `range`, the row
+ * `values` to write, and the `valueInputOption` controlling how Google
+ * interprets the cells (`"RAW"` stores text as-is, `"USER_ENTERED"` applies
+ * spreadsheet parsing and formulas; defaults to `"USER_ENTERED"`).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsWriteInput {
+    spreadsheetId: string;
+    range: string;
+    values: unknown[][];
+    valueInputOption?: "RAW" | "USER_ENTERED";
+}
+/**
+ * @description Google Sheets API integration service
+ * @summary An undecorated HTTP service for reading,
+ * updating, appending, and clearing values in A1 ranges of a spreadsheet, and
+ * for creating new spreadsheets. Every operation requires either an OAuth
+ * token or an API key (`requireAuth()`); ranges and spreadsheet IDs are
+ * URL-encoded, and transport failures are mapped to decaf errors via
+ * {@link httpError}.
+ * @class GoogleSheetsService
+ * @category IO
+ * @example
+ * ```ts
+ * import { GoogleSheetsService } from "@decaf-ts/integrations/io/google-sheets";
+ *
+ * const sheets = new GoogleSheetsService();
+ * await sheets.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GOOGLE_SHEETS_TOKEN,
+ * });
+ * const created = await sheets.createSpreadsheet("Metrics");
+ * await sheets.updateValues({
+ *   spreadsheetId: created.spreadsheetId,
+ *   range: "Sheet1!A1:B2",
+ *   values: [
+ *     ["date", "count"],
+ *     ["2026-01-01", "42"],
+ *   ],
+ * });
+ * ```
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export declare class GoogleSheetsService extends HttpApiService<GoogleSheetsServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Google Sheets";
+    /**
+     * @description The Google Sheets v4 values API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://sheets.googleapis.com/v4/spreadsheets"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Google Sheets authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries an OAuth token, otherwise the `X-Goog-Api-Key` header when
+     * an API key is configured, and no headers otherwise.
+     * @param {GoogleSheetsServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token or API key).
+     */
+    protected authHeaders(config: GoogleSheetsServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Google Sheets credentials and defaults from the environment
+     * @summary Reads the `io.googleSheets` environment slice and returns a
+     * partial config when a token or API key is configured, `undefined`
+     * otherwise. Values pass through `envString`/`envNumber` to reject
+     * unset-leaf proxies.
+     * @returns {Partial<GoogleSheetsServiceConfig> | undefined} A partial config, or `undefined` when neither token nor API key is configured.
+     */
+    protected configFromEnvironment(): Partial<GoogleSheetsServiceConfig> | undefined;
+    /**
+     * @description Asserts that the service was configured with OAuth credentials
+     * @summary Throws when the resolved config carries neither a `token` nor an
+     * `apiKey`; every operation calls this before issuing requests.
+     * @returns {void}
+     * @throws {InternalError} When neither an OAuth token nor an API key is configured.
+     */
+    protected requireAuth(): void;
+    /**
+     * @description URL-encodes an A1 range for the values API path
+     * @summary Ranges such as `Sheet1!A1:B2` contain characters that must be
+     * percent-encoded; all operations route the range through this helper.
+     * @param {string} range - The A1 notation range to encode.
+     * @returns {string} The URL-encoded range.
+     */
+    protected rangePath(range: string): string;
+    /**
+     * @description Reads values from an A1 range of a spreadsheet
+     * @summary `GET`s the values endpoint for the given `spreadsheetId` and
+     * `range` and returns the served range, major dimension, and the grid
+     * values (rows of cell strings). Requires credentials and both arguments.
+     * @param {string} spreadsheetId - The spreadsheet to read from.
+     * @param {string} range - The A1 notation range to read (e.g. `"Sheet1!A1:C10"`).
+     * @returns {Promise<GoogleSheetsValuesResult>} The served range and grid values.
+     * @throws {InternalError} When credentials are missing or the spreadsheet ID/range is empty.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    getValues(spreadsheetId: string, range: string): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Overwrites values in an A1 range of a spreadsheet
+     * @summary `PUT`s the row values to the values endpoint for the given
+     * `spreadsheetId` and `range`. Cells are interpreted according to
+     * `valueInputOption` (`"USER_ENTERED"` by default, `"RAW"` to store text
+     * verbatim), and the existing range content is replaced.
+     * @param {GoogleSheetsWriteInput} input - The target spreadsheet, range, values, and input interpretation.
+     * @returns {Promise<GoogleSheetsValuesResult>} The served range and the written values.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    updateValues(input: GoogleSheetsWriteInput): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Appends values after the last row of an A1 range's table
+     * @summary `POST`s the row values to the `:append` endpoint for the given
+     * `spreadsheetId` and `range`, inserting new rows after existing table data
+     * (`insertDataOption: "INSERT_ROWS"`). Cells are interpreted according to
+     * `valueInputOption` (`"USER_ENTERED"` by default). Use a single-row or
+     * single-column A1 range to anchor the table; Google reports the range the
+     * data actually landed in.
+     * @param {GoogleSheetsWriteInput} input - The target spreadsheet, anchor range, values, and input interpretation.
+     * @returns {Promise<GoogleSheetsValuesResult>} The range the appended rows landed in and the appended values.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    appendValues(input: GoogleSheetsWriteInput): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Clears all values in an A1 range of a spreadsheet
+     * @summary `POST`s the `:clear` endpoint for the given `spreadsheetId` and
+     * `range`, emptying the cells while preserving formatting, and returns the
+     * range Google actually cleared.
+     * @param {string} spreadsheetId - The spreadsheet to clear values in.
+     * @param {string} range - The A1 notation range to clear.
+     * @returns {Promise<{spreadsheetId: string, clearedRange: string}>} The cleared range as reported by Google.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    clearValues(spreadsheetId: string, range: string): Promise<{
+        spreadsheetId: string;
+        clearedRange: string;
+    }>;
+    /**
+     * @description Creates a new spreadsheet with the given title
+     * @summary `POST`s a spreadsheet resource with `properties.title` to the
+     * spreadsheets endpoint and returns the new spreadsheet's ID and URL.
+     * @param {string} title - The title for the new spreadsheet.
+     * @returns {Promise<{spreadsheetId: string, spreadsheetUrl?: string}>} The created spreadsheet's ID and URL.
+     * @throws {InternalError} When credentials are missing or the title is empty.
+     * @throws {NotFoundError} When Google answers with HTTP 404.
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status.
+     */
+    createSpreadsheet(title: string): Promise<{
+        spreadsheetId: string;
+        spreadsheetUrl?: string;
+    }>;
+}

package/lib/types/io/google-sheets/index.d.cts

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/io/google-sheets
+ * @summary Google Sheets REST v4 service (values read/write/append/clear, spreadsheet creation).
+ * @description Re-exports the Google Sheets client-based service and its types.
+ */
+export * from "./GoogleSheetsService.d.cts";

package/lib/types/io/google-sheets/index.d.mts

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/io/google-sheets
+ * @summary Google Sheets REST v4 service (values read/write/append/clear, spreadsheet creation).
+ * @description Re-exports the Google Sheets client-based service and its types.
+ */
+export * from "./GoogleSheetsService.d.mts";