@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/types/io/airtable/AirtableService.d.mts

@@ -0,0 +1,268 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Airtable service
+ * @summary Extends {@link HttpApiServiceConfig} with the Airtable personal
+ * access token (sent as a bearer token) and the default `baseId` used when a
+ * call does not override it. When omitted, the `io.airtable` environment
+ * slice supplies the token (and optional `baseId`, `baseUrl`, `timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/airtable/service
+ */
+export interface AirtableServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Airtable personal access token
+     * @summary Sent as `Authorization: Bearer <token>` with every API call.
+     */
+    token?: string;
+    /**
+     * @description Default base ID used when a call does not override it
+     */
+    baseId?: string;
+}
+/**
+ * @description Normalized Airtable record descriptor
+ * @summary The Airtable record envelope: the record `id`, the `fields` map
+ * (column name to value), and the optional `createdTime` timestamp.
+ * @category IO
+ * @memberOf module:integrations/io/airtable/service
+ */
+export interface AirtableRecord {
+    id: string;
+    fields: Record<string, unknown>;
+    createdTime?: string;
+}
+/**
+ * @description Options for listing Airtable records
+ * @summary Carries the required `table` name plus the view, formula filter,
+ * record caps and paging offset, field projection, and first-sort configuration
+ * Airtable supports. Only the first sort entry is sent (Airtable's
+ * `sort[0][field]`/`sort[0][direction]` query parameters); paging works by
+ * passing the previous page's `offset` back as `offset`.
+ * @category IO
+ * @memberOf module:integrations/io/airtable/service
+ */
+export interface AirtableListOptions {
+    /**
+     * @description Table name or ID to list records from (required)
+     */
+    table: string;
+    /**
+     * @description View name or ID to restrict the listing to
+     */
+    view?: string;
+    /**
+     * @description Airtable formula restricting the returned records (e.g. `"{Status} = 'Active'"`)
+     */
+    filterByFormula?: string;
+    /**
+     * @description Maximum number of records to return in total
+     */
+    maxRecords?: number;
+    /**
+     * @description Number of records per page
+     */
+    pageSize?: number;
+    /**
+     * @description The `offset` from the previous page's result
+     */
+    offset?: string;
+    /**
+     * @description Column names to project
+     */
+    fields?: string[];
+    /**
+     * @description First sort entry applied to the listing
+     */
+    sort?: Array<{
+        field: string;
+        direction?: "asc" | "desc";
+    }>;
+}
+/**
+ * @description Result of an Airtable record listing
+ * @summary Carries the page of `records` and the `offset` cursor to pass back
+ * as `AirtableListOptions.offset` when more pages exist.
+ * @category IO
+ * @memberOf module:integrations/io/airtable/service
+ */
+export interface AirtableListResult {
+    records: AirtableRecord[];
+    offset?: string;
+}
+/**
+ * @description Input for creating or updating an Airtable record
+ * @summary Carries the required `table` name, the `fields` map to write, and
+ * the `typecast` flag letting Airtable convert values to the column types.
+ * `updateRecord` additionally carries the `recordId`.
+ * @category IO
+ * @memberOf module:integrations/io/airtable/service
+ */
+export interface AirtableWriteInput {
+    table: string;
+    fields: Record<string, unknown>;
+    typecast?: boolean;
+}
+/**
+ * @description Airtable Web API integration service
+ * @summary An undecorated HTTP service for listing records
+ * with filtering, sorting, and cursor paging; fetching, creating, updating,
+ * and deleting individual records. Base targets resolve per call from the
+ * `baseId` argument, falling back to the configured value, and throw
+ * `InternalError` when unresolved. Every operation requires a token
+ * (`requireToken()`), and transport failures are mapped to decaf errors via
+ * {@link httpError}.
+ * @class AirtableService
+ * @category IO
+ * @example
+ * ```ts
+ * import { AirtableService } from "@decaf-ts/integrations/io/airtable";
+ *
+ * const airtable = new AirtableService();
+ * await airtable.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_AIRTABLE_TOKEN,
+ *   baseId: "appExampleBase",
+ * });
+ * const created = await airtable.createRecord({
+ *   table: "Tasks",
+ *   fields: { Name: "Ship release", Status: "Todo" },
+ * });
+ * ```
+ * @memberOf module:integrations/io/airtable/service
+ */
+export declare class AirtableService extends HttpApiService<AirtableServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Airtable";
+    /**
+     * @description The Airtable Web API v0 base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://api.airtable.com/v0"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Airtable bearer authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries a token, and no headers otherwise.
+     * @param {AirtableServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: AirtableServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Airtable credentials and defaults from the environment
+     * @summary Reads the `io.airtable` environment slice and returns a partial
+     * config when a token is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<AirtableServiceConfig> | undefined} A partial config, or `undefined` when no Airtable token is configured.
+     */
+    protected configFromEnvironment(): Partial<AirtableServiceConfig> | undefined;
+    /**
+     * @description Resolves the URL-encoded base path for a call
+     * @summary Builds `/<baseId>` from the given base ID, falling back to the
+     * configured value, and throws when neither is available.
+     * @param {string} [baseId] - The per-call base override.
+     * @returns {string} The URL-encoded base API path.
+     * @throws {InternalError} When neither the input nor the config yields a base ID.
+     */
+    protected basePath(baseId?: string): string;
+    /**
+     * @description Resolves the URL-encoded table path for a call
+     * @summary Builds `<basePath>/<table>` with both segments URL-encoded, and
+     * throws when the table name is empty (or the base cannot be resolved).
+     * @param {string} table - The table name or ID.
+     * @param {string} [baseId] - The per-call base override.
+     * @returns {string} The URL-encoded table API path.
+     * @throws {InternalError} When the table name is empty or the base ID cannot be resolved.
+     */
+    protected tablePath(table: string, baseId?: string): string;
+    /**
+     * @description Lists records in an Airtable table with cursor paging
+     * @summary `GET`s the table endpoint with the configured view, formula
+     * filter, record caps, page size, page offset, field projection, and first
+     * sort entry. Return the `offset` cursor as the next call's
+     * `AirtableListOptions.offset` to fetch further pages.
+     * @param {AirtableListOptions} options - The table and filter/sort/paging options.
+     * @param {string} [baseId] - The base override; falls back to the configured `baseId`.
+     * @returns {Promise<AirtableListResult>} The page of records and the next offset cursor when more pages exist.
+     * @throws {InternalError} When no token is configured or the table/base cannot be resolved.
+     * @throws {NotFoundError} When the base or table does not exist (HTTP 404).
+     * @throws {ConflictError} When Airtable answers with HTTP 409.
+     * @throws {BadRequestError} When Airtable answers with any other HTTP error status (e.g. invalid formula).
+     * @example
+     * ```ts
+     * let offset: string | undefined;
+     * do {
+     *   const page = await airtable.listRecords({
+     *     table: "Tasks",
+     *     filterByFormula: "{Status} = 'Active'",
+     *     pageSize: 100,
+     *     offset,
+     *     sort: [{ field: "Name", direction: "asc" }],
+     *   });
+     *   console.log(page.records);
+     *   offset = page.offset;
+     * } while (offset);
+     * ```
+     */
+    listRecords(options: AirtableListOptions, baseId?: string): Promise<AirtableListResult>;
+    /**
+     * @description Fetches a single Airtable record
+     * @summary `GET`s the table endpoint with the record ID appended and
+     * returns the record envelope.
+     * @param {string} table - The table name or ID.
+     * @param {string} recordId - The record ID to fetch (e.g. `"rec1234567890"`).
+     * @param {string} [baseId] - The base override; falls back to the configured `baseId`.
+     * @returns {Promise<AirtableRecord>} The record envelope.
+     * @throws {InternalError} When no token is configured or the table/base cannot be resolved.
+     * @throws {NotFoundError} When the record does not exist (HTTP 404).
+     * @throws {ConflictError} When Airtable answers with HTTP 409.
+     * @throws {BadRequestError} When Airtable answers with any other HTTP error status.
+     */
+    getRecord(table: string, recordId: string, baseId?: string): Promise<AirtableRecord>;
+    /**
+     * @description Creates an Airtable record
+     * @summary `POST`s the fields map to the table endpoint; `typecast` lets
+     * Airtable coerce values into the column types (disabled by default).
+     * @param {AirtableWriteInput} input - The table, fields, and typecast option.
+     * @param {string} [baseId] - The base override; falls back to the configured `baseId`.
+     * @returns {Promise<AirtableRecord>} The created record envelope.
+     * @throws {InternalError} When no token is configured or the table/base cannot be resolved.
+     * @throws {NotFoundError} When the base or table does not exist (HTTP 404).
+     * @throws {ConflictError} When Airtable answers with HTTP 409.
+     * @throws {BadRequestError} When Airtable answers with any other HTTP error status (e.g. invalid field values).
+     */
+    createRecord(input: AirtableWriteInput, baseId?: string): Promise<AirtableRecord>;
+    /**
+     * @description Updates an Airtable record
+     * @summary `PATCH`es the fields map onto the record identified by
+     * `recordId`; only the provided fields change. `typecast` lets Airtable
+     * coerce values into the column types (disabled by default).
+     * @param {AirtableWriteInput & {recordId: string}} input - The table, fields, typecast option, and target record ID.
+     * @param {string} [baseId] - The base override; falls back to the configured `baseId`.
+     * @returns {Promise<AirtableRecord>} The updated record envelope.
+     * @throws {InternalError} When no token is configured or the table/base cannot be resolved.
+     * @throws {NotFoundError} When the record does not exist (HTTP 404).
+     * @throws {ConflictError} When Airtable answers with HTTP 409.
+     * @throws {BadRequestError} When Airtable answers with any other HTTP error status (e.g. invalid field values).
+     */
+    updateRecord(input: AirtableWriteInput & {
+        recordId: string;
+    }, baseId?: string): Promise<AirtableRecord>;
+    /**
+     * @description Deletes an Airtable record
+     * @summary `DELETE`s the record identified by `recordId` and returns the
+     * Airtable deletion confirmation.
+     * @param {string} table - The table name or ID.
+     * @param {string} recordId - The record ID to delete.
+     * @param {string} [baseId] - The base override; falls back to the configured `baseId`.
+     * @returns {Promise<{id: string, deleted: boolean}>} The deleted record's ID and Airtable's `deleted` confirmation.
+     * @throws {InternalError} When no token is configured or the table/base cannot be resolved.
+     * @throws {NotFoundError} When the record does not exist (HTTP 404).
+     * @throws {ConflictError} When Airtable answers with HTTP 409.
+     * @throws {BadRequestError} When Airtable answers with any other HTTP error status.
+     */
+    deleteRecord(table: string, recordId: string, baseId?: string): Promise<{
+        id: string;
+        deleted: boolean;
+    }>;
+}

package/lib/types/io/airtable/index.d.cts

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/io/airtable
+ * @summary Airtable Web API service (record CRUD).
+ * @description Re-exports the Airtable client-based service and its types.
+ */
+export * from "./AirtableService.d.cts";

package/lib/types/io/airtable/index.d.mts

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/io/airtable
+ * @summary Airtable Web API service (record CRUD).
+ * @description Re-exports the Airtable client-based service and its types.
+ */
+export * from "./AirtableService.d.mts";

package/lib/types/io/environment.d.cts

@@ -0,0 +1,67 @@
+/**
+ * @module integrations/io/environment
+ * @summary Environment contract and accumulated environment for the io integration services.
+ * @description Declares the `IoEnvironmentShape` consumed by the Airtable,
+ * Google Sheets, and GraphQL services' `configFromEnvironment()`
+ * implementations and the `IoEnvironment` singleton created via
+ * `LoggedEnvironment.accumulate`. Services read their credentials and
+ * defaults from the matching `io.<provider>` slice, using the
+ * `envString`/`envNumber` helpers from `shared/environmentValue` to reject
+ * unset-leaf proxies.
+ */
+/**
+ * @description Environment shape for the io integration services
+ * @summary Defines the `io` root with one slice per provider (`airtable`,
+ * `googleSheets`, `graphql`). Each slice carries the provider's required
+ * credentials (`token`, plus `baseId`/`apiKey`/`endpoint` where applicable)
+ * plus an optional `baseUrl` override and `timeout`. Fields are typed as
+ * required here so `LoggedEnvironment.accumulate` registers them; absent
+ * values resolve to proxy placeholders at runtime and must pass through
+ * `envString`/`envNumber`.
+ * @memberOf module:integrations/io/environment
+ */
+export interface IoEnvironmentShape {
+    io: {
+        airtable: {
+            token: string;
+            baseUrl: string;
+            baseId: string;
+            timeout?: number;
+        };
+        googleSheets: {
+            token: string;
+            apiKey: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        graphql: {
+            endpoint: string;
+            token: string;
+            timeout?: number;
+        };
+    };
+}
+/**
+ * @description Accumulated io environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `IoEnvironmentShape` contract. IO services read their provider slice
+ * (e.g. `IoEnvironment.io.airtable`) inside `configFromEnvironment()` and
+ * translate it into an `HttpApiServiceConfig`-derived config. Credentials
+ * come from environment variables; for as-graph node usage those are provided
+ * as `GRAPH_CREDENTIAL_*` values (placeholders in this example).
+ * @example
+ * ```ts
+ * import { AirtableService } from "@decaf-ts/integrations/io/airtable";
+ *
+ * // with io.airtable.token / io.airtable.baseId configured in the environment
+ * const airtable = new AirtableService();
+ * await airtable.initialize();
+ * ```
+ * @constant {LoggedEnvironment} IoEnvironment
+ * @memberOf module:integrations/io/environment
+ */
+export declare const IoEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & IoEnvironmentShape>;

package/lib/types/io/environment.d.mts

@@ -0,0 +1,67 @@
+/**
+ * @module integrations/io/environment
+ * @summary Environment contract and accumulated environment for the io integration services.
+ * @description Declares the `IoEnvironmentShape` consumed by the Airtable,
+ * Google Sheets, and GraphQL services' `configFromEnvironment()`
+ * implementations and the `IoEnvironment` singleton created via
+ * `LoggedEnvironment.accumulate`. Services read their credentials and
+ * defaults from the matching `io.<provider>` slice, using the
+ * `envString`/`envNumber` helpers from `shared/environmentValue` to reject
+ * unset-leaf proxies.
+ */
+/**
+ * @description Environment shape for the io integration services
+ * @summary Defines the `io` root with one slice per provider (`airtable`,
+ * `googleSheets`, `graphql`). Each slice carries the provider's required
+ * credentials (`token`, plus `baseId`/`apiKey`/`endpoint` where applicable)
+ * plus an optional `baseUrl` override and `timeout`. Fields are typed as
+ * required here so `LoggedEnvironment.accumulate` registers them; absent
+ * values resolve to proxy placeholders at runtime and must pass through
+ * `envString`/`envNumber`.
+ * @memberOf module:integrations/io/environment
+ */
+export interface IoEnvironmentShape {
+    io: {
+        airtable: {
+            token: string;
+            baseUrl: string;
+            baseId: string;
+            timeout?: number;
+        };
+        googleSheets: {
+            token: string;
+            apiKey: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        graphql: {
+            endpoint: string;
+            token: string;
+            timeout?: number;
+        };
+    };
+}
+/**
+ * @description Accumulated io environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `IoEnvironmentShape` contract. IO services read their provider slice
+ * (e.g. `IoEnvironment.io.airtable`) inside `configFromEnvironment()` and
+ * translate it into an `HttpApiServiceConfig`-derived config. Credentials
+ * come from environment variables; for as-graph node usage those are provided
+ * as `GRAPH_CREDENTIAL_*` values (placeholders in this example).
+ * @example
+ * ```ts
+ * import { AirtableService } from "@decaf-ts/integrations/io/airtable";
+ *
+ * // with io.airtable.token / io.airtable.baseId configured in the environment
+ * const airtable = new AirtableService();
+ * await airtable.initialize();
+ * ```
+ * @constant {LoggedEnvironment} IoEnvironment
+ * @memberOf module:integrations/io/environment
+ */
+export declare const IoEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & IoEnvironmentShape>;

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;
+    }>;
+}