@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/esm/io/environment.js

@@ -0,0 +1,70 @@
+import { LoggedEnvironment } from "@decaf-ts/logging";
+/**
+ * @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 const IoEnvironment = LoggedEnvironment.accumulate({
+    io: {
+        airtable: {
+            token: "",
+            baseUrl: "",
+            baseId: "",
+            timeout: undefined,
+        },
+        googleSheets: {
+            token: "",
+            apiKey: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        graphql: {
+            endpoint: "",
+            token: "",
+            timeout: undefined,
+        },
+        microsoftExcel: {
+            token: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        confluence: {
+            username: "",
+            token: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        jira: {
+            username: "",
+            token: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        googleDocs: {
+            token: "",
+            apiKey: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        microsoftSharePoint: {
+            token: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+    },
+});
+//# sourceMappingURL=environment.js.map

package/lib/esm/io/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../../src/io/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAsFtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,iBAAiB,CAAC,UAAU,CAAC;IACxD,EAAE,EAAE;QACF,QAAQ,EAAE;YACR,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,SAA8B;SACxC;QACD,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;QACD,OAAO,EAAE;YACP,QAAQ,EAAE,EAAE;YACZ,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,SAA8B;SACxC;QACD,cAAc,EAAE;YACd,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;QACD,UAAU,EAAE;YACV,QAAQ,EAAE,EAAE;YACZ,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;QACD,IAAI,EAAE;YACJ,QAAQ,EAAE,EAAE;YACZ,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;QACD,UAAU,EAAE;YACV,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;QACD,mBAAmB,EAAE;YACnB,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;KACF;CACoB,CAAC,CAAC"}

package/lib/esm/io/google-docs/GoogleDocsService.js

@@ -0,0 +1,270 @@
+/**
+ * @module integrations/io/google-docs/service
+ * @summary Google Docs API integration service for document content operations.
+ * @description Exposes Google Docs document operations (get, create, batch
+ * update, append text, and replace-all) as an undecorated client-based service
+ * built on {@link HttpApiService}. Configuration comes from an explicit
+ * `GoogleDocsServiceConfig` or the `io.googleDocs` environment slice. An OAuth
+ * access token is sent as a bearer token when present; otherwise an API key is
+ * sent as `X-Goog-Api-Key` (writes generally require OAuth). Credentials are
+ * referenced from configuration (and, from as-graph nodes, from the resolved
+ * `google-docs` credential secret) and are never embedded in source. Failures
+ * are mapped to decaf errors via {@link httpError}.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+import { IoEnvironment } from "./../environment.js";
+import { envNumber, envString } from "./../../shared/environmentValue.js";
+import { HttpApiService, httpError, } from "./../../shared/http/index.js";
+/**
+ * @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 class GoogleDocsService extends HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.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"`.
+     */
+    defaultBaseUrl() {
+        return "https://docs.googleapis.com/v1";
+    }
+    /**
+     * @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.
+     */
+    authHeaders(config) {
+        if (config.token)
+            return { Authorization: `Bearer ${config.token}` };
+        if (config.apiKey)
+            return { "X-Goog-Api-Key": config.apiKey };
+        return {};
+    }
+    /**
+     * @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.
+     */
+    configFromEnvironment() {
+        const env = IoEnvironment.io.googleDocs;
+        const token = envString(env?.token);
+        const apiKey = envString(env?.apiKey);
+        if (!token && !apiKey)
+            return undefined;
+        return {
+            token,
+            apiKey,
+            baseUrl: envString(env.baseUrl),
+            timeout: envNumber(env.timeout),
+        };
+    }
+    /**
+     * @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.
+     */
+    requireAuth() {
+        if (!this.config.token && !this.config.apiKey) {
+            throw new InternalError("Google Docs requires an OAuth token or an API key");
+        }
+    }
+    /**
+     * @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.
+     */
+    async getDocument(documentId) {
+        this.requireAuth();
+        if (!documentId) {
+            throw new InternalError("Google Docs requires a document id");
+        }
+        try {
+            const response = await this.client.get(`/documents/${encodeURIComponent(documentId)}`);
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Google Docs", "get document", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async createDocument(title) {
+        this.requireAuth();
+        if (!title) {
+            throw new InternalError("Google Docs requires a document title");
+        }
+        try {
+            const response = await this.client.post("/documents", { title });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Google Docs", "create document", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async batchUpdate(documentId, requests) {
+        this.requireAuth();
+        if (!documentId || !Array.isArray(requests) || !requests.length) {
+            throw new InternalError("Google Docs batchUpdate requires a document id and requests");
+        }
+        try {
+            const response = await this.client.post(`/documents/${encodeURIComponent(documentId)}:batchUpdate`, { requests });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Google Docs", "batch update", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async appendText(documentId, text) {
+        this.requireAuth();
+        if (!documentId || !text) {
+            throw new InternalError("Google Docs appendText requires a document id and text");
+        }
+        try {
+            const document = await this.client.get(`/documents/${encodeURIComponent(documentId)}`);
+            const content = document.data.body?.content ?? [];
+            const last = content[content.length - 1];
+            const endIndex = last?.endIndex ?? 1;
+            const response = await this.client.post(`/documents/${encodeURIComponent(documentId)}:batchUpdate`, {
+                requests: [
+                    {
+                        insertText: {
+                            location: { index: Math.max(endIndex - 1, 1) },
+                            text,
+                        },
+                    },
+                ],
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Google Docs", "append text", error);
+        }
+    }
+    /**
+     * @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,
+     * });
+     * ```
+     */
+    async replaceAllText(input) {
+        this.requireAuth();
+        if (!input.documentId || !input.find) {
+            throw new InternalError("Google Docs replaceAllText requires a document id and find text");
+        }
+        try {
+            const response = await this.client.post(`/documents/${encodeURIComponent(input.documentId)}:batchUpdate`, {
+                requests: [
+                    {
+                        replaceAllText: {
+                            containsText: {
+                                text: input.find,
+                                matchCase: input.matchCase ?? false,
+                            },
+                            replaceText: input.replace ?? "",
+                        },
+                    },
+                ],
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Google Docs", "replace all text", error);
+        }
+    }
+}
+//# sourceMappingURL=GoogleDocsService.js.map

package/lib/esm/io/google-docs/GoogleDocsService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoogleDocsService.js","sourceRoot":"","sources":["../../../../src/io/google-docs/GoogleDocsService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,4BAAuB;AAC/C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,2CAAsC;AACrE,OAAO,EACL,cAAc,EAEd,SAAS,GACV,qCAA0B;AA8D3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,OAAO,iBAAkB,SAAQ,cAAuC;IAA9E;;QACE;;WAEG;QACgB,gBAAW,GAAG,aAAa,CAAC;IAwOjD,CAAC;IAtOC;;;;OAIG;IACO,cAAc;QACtB,OAAO,gCAAgC,CAAC;IAC1C,CAAC;IAED;;;;;;OAMG;IACO,WAAW,CACnB,MAA+B;QAE/B,IAAI,MAAM,CAAC,KAAK;YAAE,OAAO,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;QACrE,IAAI,MAAM,CAAC,MAAM;YAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAC9D,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;;;;OAMG;IACO,qBAAqB;QAG7B,MAAM,GAAG,GAAG,aAAa,CAAC,EAAE,CAAC,UAAU,CAAC;QACxC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QACxC,OAAO;YACL,KAAK;YACL,MAAM;YACN,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC;YAC/B,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC;SAChC,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACO,WAAW;QACnB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAC9C,MAAM,IAAI,aAAa,CACrB,mDAAmD,CACpD,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CAAC,UAAkB;QAClC,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,aAAa,CAAC,oCAAoC,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CACpC,cAAc,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAC/C,CAAC;YACF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,aAAa,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,cAAc,CAAC,KAAa;QAChC,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,aAAa,CAAC,uCAAuC,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YACjE,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,aAAa,EAAE,iBAAiB,EAAE,KAAK,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,WAAW,CACf,UAAkB,EAClB,QAAmB;QAEnB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YAChE,MAAM,IAAI,aAAa,CACrB,6DAA6D,CAC9D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACrC,cAAc,kBAAkB,CAAC,UAAU,CAAC,cAAc,EAC1D,EAAE,QAAQ,EAAE,CACb,CAAC;YACF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,aAAa,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,UAAU,CAAC,UAAkB,EAAE,IAAY;QAC/C,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,EAAE,CAAC;YACzB,MAAM,IAAI,aAAa,CACrB,wDAAwD,CACzD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CACpC,cAAc,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAC/C,CAAC;YACF,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC;YAClD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACzC,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,CAAC,CAAC;YACrC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACrC,cAAc,kBAAkB,CAAC,UAAU,CAAC,cAAc,EAC1D;gBACE,QAAQ,EAAE;oBACR;wBACE,UAAU,EAAE;4BACV,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE;4BAC9C,IAAI;yBACL;qBACF;iBACF;aACF,CACF,CAAC;YACF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,cAAc,CAAC,KAA6B;QAChD,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACrC,MAAM,IAAI,aAAa,CACrB,iEAAiE,CAClE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACrC,cAAc,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAC,cAAc,EAChE;gBACE,QAAQ,EAAE;oBACR;wBACE,cAAc,EAAE;4BACd,YAAY,EAAE;gCACZ,IAAI,EAAE,KAAK,CAAC,IAAI;gCAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,KAAK;6BACpC;4BACD,WAAW,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;yBACjC;qBACF;iBACF;aACF,CACF,CAAC;YACF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,aAAa,EAAE,kBAAkB,EAAE,KAAK,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;CACF"}

package/lib/esm/io/google-docs/index.js

@@ -0,0 +1,2 @@
+export * from "./GoogleDocsService.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/io/google-docs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/io/google-docs/index.ts"],"names":[],"mappings":"AAAA,uCAAoC"}

package/lib/esm/io/google-sheets/GoogleSheetsService.js

@@ -0,0 +1,283 @@
+/**
+ * @module integrations/io/google-sheets/service
+ * @summary Google Sheets API integration service for reading and writing spreadsheet values.
+ * @description Exposes the Google Sheets v4 values API (`get`, `update`,
+ * `append`, `clear`) and spreadsheet creation as an undecorated
+ * client-based service built on
+ * {@link HttpApiService}. Authentication accepts either an OAuth token
+ * (bearer) or a plain API key (`X-Goog-Api-Key`); configuration comes from an
+ * explicit `GoogleSheetsServiceConfig` or the `io.googleSheets` environment
+ * slice, and failures are mapped to decaf errors via {@link httpError}.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+import { IoEnvironment } from "./../environment.js";
+import { envNumber, envString } from "./../../shared/environmentValue.js";
+import { HttpApiService, httpError, } from "./../../shared/http/index.js";
+/**
+ * @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 class GoogleSheetsService extends HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.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"`.
+     */
+    defaultBaseUrl() {
+        return "https://sheets.googleapis.com/v4/spreadsheets";
+    }
+    /**
+     * @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).
+     */
+    authHeaders(config) {
+        if (config.token)
+            return { Authorization: `Bearer ${config.token}` };
+        if (config.apiKey)
+            return { "X-Goog-Api-Key": config.apiKey };
+        return {};
+    }
+    /**
+     * @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.
+     */
+    configFromEnvironment() {
+        const env = IoEnvironment.io.googleSheets;
+        const token = envString(env?.token);
+        const apiKey = envString(env?.apiKey);
+        if (!token && !apiKey)
+            return undefined;
+        return {
+            token,
+            apiKey,
+            baseUrl: envString(env.baseUrl),
+            timeout: envNumber(env.timeout),
+        };
+    }
+    /**
+     * @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.
+     */
+    requireAuth() {
+        const config = this.config;
+        if (!config.token && !config.apiKey) {
+            throw new InternalError("Google Sheets requires an OAuth token or an API key");
+        }
+    }
+    /**
+     * @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.
+     */
+    rangePath(range) {
+        return encodeURIComponent(range);
+    }
+    /**
+     * @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).
+     */
+    async getValues(spreadsheetId, range) {
+        this.requireAuth();
+        if (!spreadsheetId || !range) {
+            throw new InternalError("Google Sheets getValues requires a spreadsheet ID and range");
+        }
+        try {
+            const response = await this.client.get(`/${encodeURIComponent(spreadsheetId)}/values/${this.rangePath(range)}`);
+            return {
+                spreadsheetId,
+                range: response.data.range ?? range,
+                majorDimension: response.data.majorDimension,
+                values: response.data.values ?? [],
+            };
+        }
+        catch (error) {
+            throw httpError("Google Sheets", "get values", error);
+        }
+    }
+    /**
+     * @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).
+     */
+    async updateValues(input) {
+        this.requireAuth();
+        try {
+            const response = await this.client.put(`/${encodeURIComponent(input.spreadsheetId)}/values/${this.rangePath(input.range)}`, {
+                range: input.range,
+                majorDimension: "ROWS",
+                values: input.values,
+            }, {
+                params: {
+                    valueInputOption: input.valueInputOption ?? "USER_ENTERED",
+                },
+            });
+            return {
+                spreadsheetId: input.spreadsheetId,
+                range: response.data.range ?? input.range,
+                majorDimension: response.data.majorDimension ?? "ROWS",
+                values: response.data.values ?? input.values,
+            };
+        }
+        catch (error) {
+            throw httpError("Google Sheets", "update values", error);
+        }
+    }
+    /**
+     * @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).
+     */
+    async appendValues(input) {
+        this.requireAuth();
+        try {
+            const response = await this.client.post(`/${encodeURIComponent(input.spreadsheetId)}/values/${this.rangePath(input.range)}:append`, {
+                range: input.range,
+                majorDimension: "ROWS",
+                values: input.values,
+            }, {
+                params: {
+                    valueInputOption: input.valueInputOption ?? "USER_ENTERED",
+                    insertDataOption: "INSERT_ROWS",
+                },
+            });
+            return {
+                spreadsheetId: input.spreadsheetId,
+                range: response.data.range ?? input.range,
+                majorDimension: response.data.majorDimension ?? "ROWS",
+                values: response.data.values ?? [],
+            };
+        }
+        catch (error) {
+            throw httpError("Google Sheets", "append values", error);
+        }
+    }
+    /**
+     * @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).
+     */
+    async clearValues(spreadsheetId, range) {
+        this.requireAuth();
+        try {
+            const response = await this.client.post(`/${encodeURIComponent(spreadsheetId)}/values/${this.rangePath(range)}:clear`, {});
+            return {
+                spreadsheetId,
+                clearedRange: response.data.clearedRange ?? range,
+            };
+        }
+        catch (error) {
+            throw httpError("Google Sheets", "clear values", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async createSpreadsheet(title) {
+        this.requireAuth();
+        if (!title) {
+            throw new InternalError("Google Sheets createSpreadsheet requires a title");
+        }
+        try {
+            const response = await this.client.post("/", {
+                properties: { title },
+            });
+            return {
+                spreadsheetId: response.data.spreadsheetId,
+                spreadsheetUrl: response.data.spreadsheetUrl,
+            };
+        }
+        catch (error) {
+            throw httpError("Google Sheets", "create spreadsheet", error);
+        }
+    }
+}
+//# sourceMappingURL=GoogleSheetsService.js.map

package/lib/esm/io/google-sheets/GoogleSheetsService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoogleSheetsService.js","sourceRoot":"","sources":["../../../../src/io/google-sheets/GoogleSheetsService.ts"],"names":[],"mappings":"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"}

package/lib/esm/io/google-sheets/index.js

@@ -0,0 +1,7 @@
+/**
+ * @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.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/io/google-sheets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/io/google-sheets/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,yCAAsC"}