@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/types/io/confluence/ConfluenceService.d.mts

@@ -0,0 +1,250 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Confluence service
+ * @summary Extends {@link HttpApiServiceConfig} with the API `token`, the
+ * optional `username` that enables Basic authentication, and the required
+ * site `baseUrl`. When omitted, the `io.confluence` environment slice supplies
+ * the same values (plus optional `timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/confluence/service
+ */
+export interface ConfluenceServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Confluence API token
+     * @summary Used as the Basic-auth password when `username` is set, otherwise as a bearer token.
+     */
+    token?: string;
+    /**
+     * @description Confluence account username for Basic authentication
+     */
+    username?: string;
+}
+/**
+ * @description Input for creating a Confluence page
+ * @summary Carries the target `spaceKey`, page `title`, storage-format body,
+ * and optional `parentId` of the ancestor page.
+ * @category IO
+ * @memberOf module:integrations/io/confluence/service
+ */
+export interface ConfluencePageInput {
+    /**
+     * @description Space key that owns the new page
+     */
+    spaceKey: string;
+    /**
+     * @description Page title (unique within the space)
+     */
+    title: string;
+    /**
+     * @description Page body in Confluence storage format
+     */
+    body: string;
+    /**
+     * @description Optional parent page ID
+     */
+    parentId?: string;
+}
+/**
+ * @description Input for updating a Confluence page
+ * @summary Carries the `pageId`, new `title` and storage-format body, and an
+ * optional `version`. When `version` is omitted the service fetches the
+ * current version and submits the next one.
+ * @category IO
+ * @memberOf module:integrations/io/confluence/service
+ */
+export interface ConfluencePageUpdate {
+    /**
+     * @description ID of the page to update
+     */
+    pageId: string;
+    /**
+     * @description New page title
+     */
+    title: string;
+    /**
+     * @description New page body in Confluence storage format
+     */
+    body: string;
+    /**
+     * @description Explicit new version number (auto-incremented when omitted)
+     */
+    version?: number;
+}
+/**
+ * @description Input for a Confluence CQL search
+ * @summary Carries the `cql` query and an optional result `limit`.
+ * @category IO
+ * @memberOf module:integrations/io/confluence/service
+ */
+export interface ConfluenceSearchInput {
+    /**
+     * @description Confluence Query Language expression
+     */
+    cql: string;
+    /**
+     * @description Maximum number of results
+     */
+    limit?: number;
+}
+/**
+ * @description Confluence REST API integration service
+ * @summary An undecorated HTTP service for reading, creating, updating, and
+ * deleting pages, listing spaces, and running CQL searches. The site base URL
+ * and API token are required; supplying a `username` switches authentication to
+ * Basic, and transport failures are mapped to decaf errors via
+ * {@link httpError}.
+ * @class ConfluenceService
+ * @extends HttpApiService
+ * @category IO
+ * @example
+ * ```ts
+ * import { ConfluenceService } from "@decaf-ts/integrations/io/confluence";
+ *
+ * const confluence = new ConfluenceService();
+ * await confluence.initialize({
+ *   baseUrl: "https://example.atlassian.net/wiki",
+ *   username: process.env.CONFLUENCE_USERNAME,
+ *   token: process.env.GRAPH_CREDENTIAL_CONFLUENCE_TOKEN,
+ * });
+ * const page = await confluence.getPage("123456");
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as ConfluenceService
+ *   participant API as Confluence REST API
+ *   Caller->>Service: updatePage(input)
+ *   activate Service
+ *   Service->>Service: requireCredentials()
+ *   opt version omitted
+ *     Service->>API: GET /rest/api/content/{id}?expand=version
+ *     activate API
+ *     API-->>Service: current version
+ *     deactivate API
+ *   end
+ *   Service->>API: PUT /rest/api/content/{id}
+ *   activate API
+ *   API-->>Service: updated page
+ *   deactivate API
+ *   Service-->>Caller: updated page
+ *   deactivate Service
+ * @memberOf module:integrations/io/confluence/service
+ */
+export declare class ConfluenceService extends HttpApiService<ConfluenceServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Confluence";
+    /**
+     * @description The default base URL for Confluence
+     * @summary Returns an empty string; Confluence is site-hosted, so the
+     * resolved `baseUrl` (from config or `io.confluence.baseUrl`) is required.
+     * @returns {string} An empty string.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Confluence authentication headers
+     * @summary Uses HTTP Basic (`username:token`) when both values are present,
+     * otherwise a bearer token when only `token` is present, otherwise no
+     * headers.
+     * @param {ConfluenceServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers.
+     */
+    protected authHeaders(config: ConfluenceServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Confluence credentials and defaults from the environment
+     * @summary Reads the `io.confluence` slice and returns a partial config when
+     * an API token is configured, `undefined` otherwise. Values pass through
+     * `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<ConfluenceServiceConfig> | undefined} A partial config, or `undefined` when no Confluence token is configured.
+     */
+    protected configFromEnvironment(): Partial<ConfluenceServiceConfig> | undefined;
+    /**
+     * @description Asserts that the Confluence token and site base URL are configured
+     * @summary Called by every operation before it touches the network.
+     * @returns {void}
+     * @throws {InternalError} When no API token or base URL is configured.
+     */
+    protected requireCredentials(): void;
+    /**
+     * @description Wraps a body in the Confluence storage representation
+     * @summary Produces the `{ storage: { value, representation } }` envelope
+     * the content API expects.
+     * @param {string} body - The Confluence storage-format body.
+     * @returns {Record<string, unknown>} The storage body envelope.
+     */
+    private storageBody;
+    /**
+     * @description Fetches a Confluence page
+     * @summary `GET`s `/rest/api/content/<id>` with the requested `expand`
+     * fields (default `body.storage,version`).
+     * @param {string} pageId - The page ID.
+     * @param {string} [expand] - Comma-separated fields to expand; defaults to `"body.storage,version"`.
+     * @returns {Promise<unknown>} The page payload.
+     * @throws {InternalError} When credentials are missing or the page ID is empty.
+     * @throws {NotFoundError} When the page does not exist (HTTP 404).
+     * @throws {BadRequestError} When the API rejects the request.
+     */
+    getPage(pageId: string, expand?: string): Promise<unknown>;
+    /**
+     * @description Lists Confluence spaces
+     * @summary `GET`s `/rest/api/space` with a result `limit` (default `25`).
+     * @param {number} [limit] - Maximum number of spaces to return; defaults to `25`.
+     * @returns {Promise<unknown>} The space collection payload.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {BadRequestError} When the API rejects the request.
+     */
+    listSpaces(limit?: number): Promise<unknown>;
+    /**
+     * @description Creates a Confluence page
+     * @summary `POST`s a `page` content entry in the target space, optionally
+     * under a parent, with the body in storage format.
+     * @param {ConfluencePageInput} input - The space, title, body, and optional parent.
+     * @returns {Promise<unknown>} The created page payload.
+     * @throws {InternalError} When credentials are missing, or the space key or title is empty.
+     * @throws {BadRequestError} When the API rejects the page.
+     * @example
+     * ```ts
+     * await confluence.createPage({
+     *   spaceKey: "OPS",
+     *   title: "Release 1.2.0",
+     *   body: "<p>Details…</p>",
+     * });
+     * ```
+     */
+    createPage(input: ConfluencePageInput): Promise<unknown>;
+    /**
+     * @description Updates a Confluence page
+     * @summary `PUT`s the new title and storage body. When `version` is omitted
+     * the current version is read first and the next number is submitted, as
+     * Confluence requires optimistic versioning.
+     * @param {ConfluencePageUpdate} input - The page, new title/body, and optional version.
+     * @returns {Promise<unknown>} The updated page payload.
+     * @throws {InternalError} When credentials are missing, or the page ID or title is empty.
+     * @throws {NotFoundError} When the page does not exist (HTTP 404).
+     * @throws {ConflictError} When the submitted version is stale (HTTP 409).
+     * @throws {BadRequestError} When the API rejects the update.
+     */
+    updatePage(input: ConfluencePageUpdate): Promise<unknown>;
+    /**
+     * @description Deletes a Confluence page
+     * @summary `DELETE`s the content entry and returns `{ deleted: true, pageId }`.
+     * @param {string} pageId - The page ID to delete.
+     * @returns {Promise<unknown>} `{ deleted: true, pageId }` on success.
+     * @throws {InternalError} When credentials are missing or the page ID is empty.
+     * @throws {NotFoundError} When the page does not exist (HTTP 404).
+     * @throws {BadRequestError} When the API rejects the deletion.
+     */
+    deletePage(pageId: string): Promise<unknown>;
+    /**
+     * @description Searches Confluence content with CQL
+     * @summary `GET`s `/rest/api/content/search` with the CQL expression and an
+     * optional `limit`.
+     * @param {ConfluenceSearchInput} input - The CQL query and result limit.
+     * @returns {Promise<unknown>} The search result payload.
+     * @throws {InternalError} When credentials are missing or the CQL query is empty.
+     * @throws {BadRequestError} When the CQL query is invalid.
+     */
+    search(input: ConfluenceSearchInput): Promise<unknown>;
+}

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

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

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

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

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

@@ -0,0 +1,107 @@
+/**
+ * @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, GraphQL, Microsoft Excel, Confluence, Jira, Google Docs, and
+ * Microsoft SharePoint 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. The matching public
+ * subpath exports are `@decaf-ts/integrations/io/microsoft-excel`,
+ * `@decaf-ts/integrations/io/confluence`,
+ * `@decaf-ts/integrations/io/jira`,
+ * `@decaf-ts/integrations/io/google-docs`, and
+ * `@decaf-ts/integrations/io/microsoft-sharepoint`.
+ */
+/**
+ * @description Environment shape for the io integration services
+ * @summary Defines the `io` root with one slice per provider (`airtable`,
+ * `googleSheets`, `graphql`, `microsoftExcel`, `confluence`, `jira`,
+ * `googleDocs`, `microsoftSharePoint`). Each slice carries the provider's
+ * required credentials (`token`, plus `baseId`/`apiKey`/`endpoint`/`username`
+ * 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`. Values are credential references supplied by the
+ * environment, never literals embedded in source.
+ * @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;
+        };
+        /** Microsoft Graph access token for Excel workbooks (`io/microsoft-excel`). */
+        microsoftExcel: {
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        /** Confluence API token, optional Basic-auth username, and site base URL (`io/confluence`). */
+        confluence: {
+            username: string;
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        /** Jira API token, optional Basic-auth username, and site base URL (`io/jira`). */
+        jira: {
+            username: string;
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        /** Google Docs OAuth token or API key (`io/google-docs`). */
+        googleDocs: {
+            token: string;
+            apiKey: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        /** Microsoft Graph access token for SharePoint (`io/microsoft-sharepoint`). */
+        microsoftSharePoint: {
+            token: string;
+            baseUrl: 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,107 @@
+/**
+ * @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, GraphQL, Microsoft Excel, Confluence, Jira, Google Docs, and
+ * Microsoft SharePoint 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. The matching public
+ * subpath exports are `@decaf-ts/integrations/io/microsoft-excel`,
+ * `@decaf-ts/integrations/io/confluence`,
+ * `@decaf-ts/integrations/io/jira`,
+ * `@decaf-ts/integrations/io/google-docs`, and
+ * `@decaf-ts/integrations/io/microsoft-sharepoint`.
+ */
+/**
+ * @description Environment shape for the io integration services
+ * @summary Defines the `io` root with one slice per provider (`airtable`,
+ * `googleSheets`, `graphql`, `microsoftExcel`, `confluence`, `jira`,
+ * `googleDocs`, `microsoftSharePoint`). Each slice carries the provider's
+ * required credentials (`token`, plus `baseId`/`apiKey`/`endpoint`/`username`
+ * 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`. Values are credential references supplied by the
+ * environment, never literals embedded in source.
+ * @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;
+        };
+        /** Microsoft Graph access token for Excel workbooks (`io/microsoft-excel`). */
+        microsoftExcel: {
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        /** Confluence API token, optional Basic-auth username, and site base URL (`io/confluence`). */
+        confluence: {
+            username: string;
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        /** Jira API token, optional Basic-auth username, and site base URL (`io/jira`). */
+        jira: {
+            username: string;
+            token: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        /** Google Docs OAuth token or API key (`io/google-docs`). */
+        googleDocs: {
+            token: string;
+            apiKey: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        /** Microsoft Graph access token for SharePoint (`io/microsoft-sharepoint`). */
+        microsoftSharePoint: {
+            token: string;
+            baseUrl: 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-docs/GoogleDocsService.d.cts

@@ -0,0 +1,188 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @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>;
+}