@decaf-ts/integrations 0.12.0 → 0.14.0

package/lib/cjs/io/google-docs/GoogleDocsService.cjs

@@ -0,0 +1,275 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleDocsService = void 0;
+/**
+ * @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}.
+ */
+const db_decorators_1 = require("@decaf-ts/db-decorators");
+const environment_js_1 = require("./../environment.cjs");
+const environmentValue_js_1 = require("./../../shared/environmentValue.cjs");
+const index_js_1 = require("./../../shared/http/index.cjs");
+/**
+ * @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
+ */
+class GoogleDocsService extends index_js_1.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 = environment_js_1.IoEnvironment.io.googleDocs;
+        const token = (0, environmentValue_js_1.envString)(env?.token);
+        const apiKey = (0, environmentValue_js_1.envString)(env?.apiKey);
+        if (!token && !apiKey)
+            return undefined;
+        return {
+            token,
+            apiKey,
+            baseUrl: (0, environmentValue_js_1.envString)(env.baseUrl),
+            timeout: (0, environmentValue_js_1.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 db_decorators_1.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 db_decorators_1.InternalError("Google Docs requires a document id");
+        }
+        try {
+            const response = await this.client.get(`/documents/${encodeURIComponent(documentId)}`);
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.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 db_decorators_1.InternalError("Google Docs requires a document title");
+        }
+        try {
+            const response = await this.client.post("/documents", { title });
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.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 db_decorators_1.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 (0, index_js_1.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 db_decorators_1.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 (0, index_js_1.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 db_decorators_1.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 (0, index_js_1.httpError)("Google Docs", "replace all text", error);
+        }
+    }
+}
+exports.GoogleDocsService = GoogleDocsService;
+//# sourceMappingURL=GoogleDocsService.js.map
+//# sourceMappingURL=GoogleDocsService.cjs.map

package/lib/cjs/io/google-docs/GoogleDocsService.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io/google-docs/GoogleDocsService.cjs","sourceRoot":"","sources":["io/google-docs/GoogleDocsService.js"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,2DAAwD;AACxD,wDAAoD;AACpD,4EAA0E;AAC1E,2DAA0E;AAC1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAa,iBAAkB,SAAQ,yBAAc;IACjD;QACI,KAAK,CAAC,GAAG,SAAS,CAAC,CAAC;QACpB;;WAEG;QACH,IAAI,CAAC,WAAW,GAAG,aAAa,CAAC;IACrC,CAAC;IACD;;;;OAIG;IACH,cAAc;QACV,OAAO,gCAAgC,CAAC;IAC5C,CAAC;IACD;;;;;;OAMG;IACH,WAAW,CAAC,MAAM;QACd,IAAI,MAAM,CAAC,KAAK;YACZ,OAAO,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;QACvD,IAAI,MAAM,CAAC,MAAM;YACb,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/C,OAAO,EAAE,CAAC;IACd,CAAC;IACD;;;;;;OAMG;IACH,qBAAqB;QACjB,MAAM,GAAG,GAAG,8BAAa,CAAC,EAAE,CAAC,UAAU,CAAC;QACxC,MAAM,KAAK,GAAG,IAAA,+BAAS,EAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,IAAA,+BAAS,EAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM;YACjB,OAAO,SAAS,CAAC;QACrB,OAAO;YACH,KAAK;YACL,MAAM;YACN,OAAO,EAAE,IAAA,+BAAS,EAAC,GAAG,CAAC,OAAO,CAAC;YAC/B,OAAO,EAAE,IAAA,+BAAS,EAAC,GAAG,CAAC,OAAO,CAAC;SAClC,CAAC;IACN,CAAC;IACD;;;;;OAKG;IACH,WAAW;QACP,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAC5C,MAAM,IAAI,6BAAa,CAAC,mDAAmD,CAAC,CAAC;QACjF,CAAC;IACL,CAAC;IACD;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CAAC,UAAU;QACxB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,MAAM,IAAI,6BAAa,CAAC,oCAAoC,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACvF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACX,MAAM,IAAA,oBAAS,EAAC,aAAa,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;QAC1D,CAAC;IACL,CAAC;IACD;;;;;;;;OAQG;IACH,KAAK,CAAC,cAAc,CAAC,KAAK;QACtB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,MAAM,IAAI,6BAAa,CAAC,uCAAuC,CAAC,CAAC;QACrE,CAAC;QACD,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YACjE,OAAO,QAAQ,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACX,MAAM,IAAA,oBAAS,EAAC,aAAa,EAAE,iBAAiB,EAAE,KAAK,CAAC,CAAC;QAC7D,CAAC;IACL,CAAC;IACD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,QAAQ;QAClC,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YAC9D,MAAM,IAAI,6BAAa,CAAC,6DAA6D,CAAC,CAAC;QAC3F,CAAC;QACD,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,kBAAkB,CAAC,UAAU,CAAC,cAAc,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;YAClH,OAAO,QAAQ,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACX,MAAM,IAAA,oBAAS,EAAC,aAAa,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;QAC1D,CAAC;IACL,CAAC;IACD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,UAAU,CAAC,UAAU,EAAE,IAAI;QAC7B,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,EAAE,CAAC;YACvB,MAAM,IAAI,6BAAa,CAAC,wDAAwD,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACvF,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,CAAC,cAAc,kBAAkB,CAAC,UAAU,CAAC,cAAc,EAAE;gBAChG,QAAQ,EAAE;oBACN;wBACI,UAAU,EAAE;4BACR,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE;4BAC9C,IAAI;yBACP;qBACJ;iBACJ;aACJ,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACX,MAAM,IAAA,oBAAS,EAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;QACzD,CAAC;IACL,CAAC;IACD;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,cAAc,CAAC,KAAK;QACtB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,IAAI,6BAAa,CAAC,iEAAiE,CAAC,CAAC;QAC/F,CAAC;QACD,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAC,cAAc,EAAE;gBACtG,QAAQ,EAAE;oBACN;wBACI,cAAc,EAAE;4BACZ,YAAY,EAAE;gCACV,IAAI,EAAE,KAAK,CAAC,IAAI;gCAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,KAAK;6BACtC;4BACD,WAAW,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;yBACnC;qBACJ;iBACJ;aACJ,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACX,MAAM,IAAA,oBAAS,EAAC,aAAa,EAAE,kBAAkB,EAAE,KAAK,CAAC,CAAC;QAC9D,CAAC;IACL,CAAC;CACJ;AAlND,8CAkNC;AACD,6CAA6C"}

package/lib/cjs/io/google-docs/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./GoogleDocsService.cjs"), exports);
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map

package/lib/cjs/io/google-docs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io/google-docs/index.cjs","sourceRoot":"","sources":["io/google-docs/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,iCAAiC"}

package/lib/cjs/io/index.cjs

@@ -25,6 +25,11 @@ __exportStar(require("./airtable/index.cjs"), exports);
 __exportStar(require("./google-sheets/index.cjs"), exports);
 __exportStar(require("./graphql/index.cjs"), exports);
 __exportStar(require("./spreadsheet/index.cjs"), exports);
+__exportStar(require("./microsoft-excel/index.cjs"), exports);
+__exportStar(require("./confluence/index.cjs"), exports);
+__exportStar(require("./jira/index.cjs"), exports);
+__exportStar(require("./google-docs/index.cjs"), exports);
+__exportStar(require("./microsoft-sharepoint/index.cjs"), exports);
 __exportStar(require("./environment.cjs"), exports);
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.cjs.map

package/lib/cjs/io/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"io/index.cjs","sourceRoot":"","sources":["io/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;GAMG;AACH,sDAAoC;AACpC,2DAAyC;AACzC,qDAAmC;AACnC,yDAAuC;AACvC,mDAAiC;AACjC,iCAAiC"}
+{"version":3,"file":"io/index.cjs","sourceRoot":"","sources":["io/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;GAMG;AACH,sDAAoC;AACpC,2DAAyC;AACzC,qDAAmC;AACnC,yDAAuC;AACvC,6DAA2C;AAC3C,wDAAsC;AACtC,kDAAgC;AAChC,yDAAuC;AACvC,kEAAgD;AAChD,mDAAiC;AACjC,iCAAiC"}

package/lib/cjs/io/jira/JiraService.cjs

@@ -0,0 +1,354 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JiraService = void 0;
+/**
+ * @module integrations/io/jira/service
+ * @summary Jira REST API integration service for issues, comments, and workflows.
+ * @description Exposes Jira issue operations (create, read, update, delete,
+ * comment, transition, and JQL search) through the Jira REST `api/2` surface as
+ * an undecorated client-based service built on {@link HttpApiService}.
+ * Configuration comes from an explicit `JiraServiceConfig` or the `io.jira`
+ * environment slice. When both `username` and `token` are configured the
+ * service sends HTTP Basic authentication (API token as the password);
+ * otherwise the token is sent as a bearer token. The site `baseUrl` is
+ * required. Credentials are referenced from configuration (and, from as-graph
+ * nodes, from the resolved `jira` credential secret) and are never embedded in
+ * source. Failures are mapped to decaf errors via {@link httpError}.
+ */
+const db_decorators_1 = require("@decaf-ts/db-decorators");
+const environment_js_1 = require("./../environment.cjs");
+const environmentValue_js_1 = require("./../../shared/environmentValue.cjs");
+const index_js_1 = require("./../../shared/http/index.cjs");
+/** Default issue type written when a create does not specify one (`"Task"`). */
+const DEFAULT_ISSUE_TYPE = "Task";
+/**
+ * @description Jira REST API integration service
+ * @summary An undecorated HTTP service for issue CRUD, comments, workflow
+ * transitions, and JQL search. 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 JiraService
+ * @extends HttpApiService
+ * @category IO
+ * @example
+ * ```ts
+ * import { JiraService } from "@decaf-ts/integrations/io/jira";
+ *
+ * const jira = new JiraService();
+ * await jira.initialize({
+ *   baseUrl: "https://example.atlassian.net",
+ *   username: process.env.JIRA_USERNAME,
+ *   token: process.env.GRAPH_CREDENTIAL_JIRA_TOKEN,
+ * });
+ * const issue = await jira.createIssue({
+ *   projectKey: "OPS",
+ *   summary: "Deployment failed",
+ * });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as JiraService
+ *   participant API as Jira REST API
+ *   Caller->>Service: createIssue(input)
+ *   activate Service
+ *   Service->>Service: requireCredentials()
+ *   Service->>API: POST /rest/api/2/issue
+ *   activate API
+ *   API-->>Service: { id, key }
+ *   deactivate API
+ *   Service-->>Caller: created issue
+ *   deactivate Service
+ * @memberOf module:integrations/io/jira/service
+ */
+class JiraService extends index_js_1.HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.serviceName = "Jira";
+    }
+    /**
+     * @description The default base URL for Jira
+     * @summary Returns an empty string; Jira is site-hosted, so the resolved
+     * `baseUrl` (from config or `io.jira.baseUrl`) is required.
+     * @returns {string} An empty string.
+     */
+    defaultBaseUrl() {
+        return "";
+    }
+    /**
+     * @description Builds the Jira authentication headers
+     * @summary Uses HTTP Basic (`username:token`) when both values are present,
+     * otherwise a bearer token when only `token` is present. Always requests
+     * JSON responses.
+     * @param {JiraServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization and accept headers.
+     */
+    authHeaders(config) {
+        if (config.username && config.token) {
+            const encoded = Buffer.from(`${config.username}:${config.token}`, "utf8").toString("base64");
+            return {
+                Authorization: `Basic ${encoded}`,
+                Accept: "application/json",
+            };
+        }
+        return config.token
+            ? { Authorization: `Bearer ${config.token}`, Accept: "application/json" }
+            : { Accept: "application/json" };
+    }
+    /**
+     * @description Reads the Jira credentials and defaults from the environment
+     * @summary Reads the `io.jira` 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<JiraServiceConfig> | undefined} A partial config, or `undefined` when no Jira token is configured.
+     */
+    configFromEnvironment() {
+        const env = environment_js_1.IoEnvironment.io.jira;
+        const token = (0, environmentValue_js_1.envString)(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            username: (0, environmentValue_js_1.envString)(env.username),
+            baseUrl: (0, environmentValue_js_1.envString)(env.baseUrl),
+            timeout: (0, environmentValue_js_1.envNumber)(env.timeout),
+        };
+    }
+    /**
+     * @description Asserts that the Jira 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.
+     */
+    requireCredentials() {
+        if (!this.config.token) {
+            throw new db_decorators_1.InternalError("Jira requires an API token");
+        }
+        if (!this.config.baseUrl) {
+            throw new db_decorators_1.InternalError("Jira requires a base URL");
+        }
+    }
+    /**
+     * @description Builds the encoded issue path
+     * @summary Validates the issue key and URL-encodes it into
+     * `/rest/api/2/issue/<key>`.
+     * @param {string} issueKey - The Jira issue key.
+     * @returns {string} The issue API path.
+     * @throws {InternalError} When `issueKey` is empty.
+     */
+    issuePath(issueKey) {
+        if (!issueKey) {
+            throw new db_decorators_1.InternalError("Jira requires an issue key");
+        }
+        return `/rest/api/2/issue/${encodeURIComponent(issueKey)}`;
+    }
+    /**
+     * @description Creates a Jira issue
+     * @summary `POST`s the project, summary, issue type (default `Task`),
+     * optional description, and extra fields to `/rest/api/2/issue`.
+     * @param {JiraIssueInput} input - The issue definition.
+     * @returns {Promise<unknown>} The created issue payload (including `id` and `key`).
+     * @throws {InternalError} When credentials are missing, or the project key or summary is empty.
+     * @throws {BadRequestError} When Jira rejects the issue.
+     */
+    async createIssue(input) {
+        this.requireCredentials();
+        if (!input.projectKey || !input.summary) {
+            throw new db_decorators_1.InternalError("Jira createIssue requires a project key and summary");
+        }
+        try {
+            const response = await this.client.post("/rest/api/2/issue", {
+                fields: {
+                    project: { key: input.projectKey },
+                    summary: input.summary,
+                    issuetype: { name: input.issueType ?? DEFAULT_ISSUE_TYPE },
+                    ...(input.description ? { description: input.description } : {}),
+                    ...(input.fields ?? {}),
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Jira", "create issue", error);
+        }
+    }
+    /**
+     * @description Fetches a Jira issue
+     * @summary `GET`s the issue by key, optionally projecting the given field
+     * names.
+     * @param {string} issueKey - The issue key to fetch.
+     * @param {string[]} [fields] - Field names to include in the response.
+     * @returns {Promise<unknown>} The issue payload.
+     * @throws {InternalError} When credentials are missing or the issue key is empty.
+     * @throws {NotFoundError} When the issue does not exist (HTTP 404).
+     * @throws {BadRequestError} When Jira rejects the request.
+     */
+    async getIssue(issueKey, fields) {
+        this.requireCredentials();
+        try {
+            const response = await this.client.get(this.issuePath(issueKey), {
+                params: fields?.length ? { fields: fields.join(",") } : {},
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Jira", "get issue", error);
+        }
+    }
+    /**
+     * @description Updates fields on a Jira issue
+     * @summary `PUT`s the `fields` map to the issue and returns
+     * `{ updated: true, issueKey }`.
+     * @param {JiraIssueUpdate} input - The issue key and fields to update.
+     * @returns {Promise<unknown>} `{ updated: true, issueKey }` on success.
+     * @throws {InternalError} When credentials are missing, or the issue key or fields are empty.
+     * @throws {NotFoundError} When the issue does not exist (HTTP 404).
+     * @throws {BadRequestError} When Jira rejects the update.
+     */
+    async updateIssue(input) {
+        this.requireCredentials();
+        if (!input.fields) {
+            throw new db_decorators_1.InternalError("Jira updateIssue requires fields");
+        }
+        try {
+            await this.client.put(this.issuePath(input.issueKey), {
+                fields: input.fields,
+            });
+            return { updated: true, issueKey: input.issueKey };
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Jira", "update issue", error);
+        }
+    }
+    /**
+     * @description Deletes a Jira issue
+     * @summary `DELETE`s the issue and returns `{ deleted: true, issueKey }`.
+     * @param {string} issueKey - The issue key to delete.
+     * @returns {Promise<unknown>} `{ deleted: true, issueKey }` on success.
+     * @throws {InternalError} When credentials are missing or the issue key is empty.
+     * @throws {NotFoundError} When the issue does not exist (HTTP 404).
+     * @throws {BadRequestError} When Jira rejects the deletion.
+     */
+    async deleteIssue(issueKey) {
+        this.requireCredentials();
+        try {
+            await this.client.delete(this.issuePath(issueKey));
+            return { deleted: true, issueKey };
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Jira", "delete issue", error);
+        }
+    }
+    /**
+     * @description Adds a comment to a Jira issue
+     * @summary `POST`s the comment body to the issue's `/comment` endpoint.
+     * @param {JiraCommentInput} input - The issue key and comment body.
+     * @returns {Promise<unknown>} The created comment payload.
+     * @throws {InternalError} When credentials are missing, or the issue key or body is empty.
+     * @throws {NotFoundError} When the issue does not exist (HTTP 404).
+     * @throws {BadRequestError} When Jira rejects the comment.
+     */
+    async addComment(input) {
+        this.requireCredentials();
+        if (!input.body) {
+            throw new db_decorators_1.InternalError("Jira addComment requires a body");
+        }
+        try {
+            const response = await this.client.post(`${this.issuePath(input.issueKey)}/comment`, { body: input.body });
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Jira", "add comment", error);
+        }
+    }
+    /**
+     * @description Lists the available workflow transitions for a Jira issue
+     * @summary `GET`s the issue's `/transitions` collection, whose IDs feed
+     * {@link JiraService.transitionIssue}.
+     * @param {string} issueKey - The issue key.
+     * @returns {Promise<unknown>} The available transitions payload.
+     * @throws {InternalError} When credentials are missing or the issue key is empty.
+     * @throws {NotFoundError} When the issue does not exist (HTTP 404).
+     * @throws {BadRequestError} When Jira rejects the request.
+     */
+    async getTransitions(issueKey) {
+        this.requireCredentials();
+        try {
+            const response = await this.client.get(`${this.issuePath(issueKey)}/transitions`);
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Jira", "get transitions", error);
+        }
+    }
+    /**
+     * @description Transitions a Jira issue through its workflow
+     * @summary `POST`s the transition ID to the issue's `/transitions` endpoint
+     * and returns the applied transition identifiers.
+     * @param {JiraTransitionInput} input - The issue key and transition ID.
+     * @returns {Promise<unknown>} `{ transitioned: true, issueKey, transitionId }` on success.
+     * @throws {InternalError} When credentials are missing, or the issue key or transition ID is empty.
+     * @throws {NotFoundError} When the issue does not exist (HTTP 404).
+     * @throws {BadRequestError} When Jira rejects the transition.
+     */
+    async transitionIssue(input) {
+        this.requireCredentials();
+        if (!input.transitionId) {
+            throw new db_decorators_1.InternalError("Jira transitionIssue requires a transition id");
+        }
+        try {
+            await this.client.post(`${this.issuePath(input.issueKey)}/transitions`, {
+                transition: { id: input.transitionId },
+            });
+            return {
+                transitioned: true,
+                issueKey: input.issueKey,
+                transitionId: input.transitionId,
+            };
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Jira", "transition issue", error);
+        }
+    }
+    /**
+     * @description Searches Jira issues with JQL
+     * @summary `POST`s the JQL query to `/rest/api/2/search` with a result cap
+     * (default `50`) and optional field projection.
+     * @param {JiraSearchInput} input - The JQL query and search options.
+     * @returns {Promise<unknown>} The search result payload.
+     * @throws {InternalError} When credentials are missing or the JQL query is empty.
+     * @throws {BadRequestError} When the JQL query is invalid.
+     * @example
+     * ```ts
+     * const results = await jira.search({
+     *   jql: 'project = "OPS" AND status = "Open"',
+     *   maxResults: 100,
+     *   fields: ["summary", "status"],
+     * });
+     * ```
+     */
+    async search(input) {
+        this.requireCredentials();
+        if (!input.jql) {
+            throw new db_decorators_1.InternalError("Jira search requires a JQL query");
+        }
+        try {
+            const response = await this.client.post("/rest/api/2/search", {
+                jql: input.jql,
+                maxResults: input.maxResults ?? 50,
+                ...(input.fields ? { fields: input.fields } : {}),
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Jira", "search issues", error);
+        }
+    }
+}
+exports.JiraService = JiraService;
+//# sourceMappingURL=JiraService.js.map
+//# sourceMappingURL=JiraService.cjs.map