@decaf-ts/integrations 0.12.0 → 0.14.2

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/io/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oCAA2B;AAC3B,yCAAgC;AAChC,mCAA0B;AAC1B,uCAA8B;AAC9B,iCAA8B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/io/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oCAA2B;AAC3B,yCAAgC;AAChC,mCAA0B;AAC1B,uCAA8B;AAC9B,2CAAkC;AAClC,sCAA6B;AAC7B,gCAAuB;AACvB,uCAA8B;AAC9B,gDAAuC;AACvC,iCAA8B"}

package/lib/esm/io/jira/JiraService.js

@@ -0,0 +1,349 @@
+/**
+ * @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}.
+ */
+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";
+/** 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
+ */
+export class JiraService extends 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 = IoEnvironment.io.jira;
+        const token = envString(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            username: envString(env.username),
+            baseUrl: envString(env.baseUrl),
+            timeout: 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 InternalError("Jira requires an API token");
+        }
+        if (!this.config.baseUrl) {
+            throw new 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 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 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 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 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 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 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 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 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 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 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 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 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 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 httpError("Jira", "search issues", error);
+        }
+    }
+}
+//# sourceMappingURL=JiraService.js.map

package/lib/esm/io/jira/JiraService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JiraService.js","sourceRoot":"","sources":["../../../../src/io/jira/JiraService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;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;AA+H3B,gFAAgF;AAChF,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,OAAO,WAAY,SAAQ,cAAiC;IAAlE;;QACE;;WAEG;QACgB,gBAAW,GAAG,MAAM,CAAC;IAqS1C,CAAC;IAnSC;;;;;OAKG;IACO,cAAc;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;;;;;OAOG;IACO,WAAW,CAAC,MAAyB;QAC7C,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CACzB,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,KAAK,EAAE,EACpC,MAAM,CACP,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACrB,OAAO;gBACL,aAAa,EAAE,SAAS,OAAO,EAAE;gBACjC,MAAM,EAAE,kBAAkB;aAC3B,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,KAAK;YACjB,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;YACzE,CAAC,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACrC,CAAC;IAED;;;;;;OAMG;IACO,qBAAqB;QAC7B,MAAM,GAAG,GAAG,aAAa,CAAC,EAAE,CAAC,IAAI,CAAC;QAClC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,OAAO;YACL,KAAK;YACL,QAAQ,EAAE,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC;YACjC,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,kBAAkB;QAC1B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,MAAM,IAAI,aAAa,CAAC,4BAA4B,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,aAAa,CAAC,0BAA0B,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACK,SAAS,CAAC,QAAgB;QAChC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,aAAa,CAAC,4BAA4B,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,qBAAqB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC7D,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CAAC,KAAqB;QACrC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YACxC,MAAM,IAAI,aAAa,CACrB,qDAAqD,CACtD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE;gBAC3D,MAAM,EAAE;oBACN,OAAO,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,UAAU,EAAE;oBAClC,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,SAAS,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,IAAI,kBAAkB,EAAE;oBAC1D,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChE,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC;iBACxB;aACF,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,QAAQ,CAAC,QAAgB,EAAE,MAAiB;QAChD,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE;gBAC/D,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;aAC3D,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,WAAW,CAAC,KAAsB;QACtC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAClB,MAAM,IAAI,aAAa,CAAC,kCAAkC,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE;gBACpD,MAAM,EAAE,KAAK,CAAC,MAAM;aACrB,CAAC,CAAC;YACH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CAAC,QAAgB;QAChC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;YACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,UAAU,CAAC,KAAuB;QACtC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAChB,MAAM,IAAI,aAAa,CAAC,iCAAiC,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACrC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,EAC3C,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CACrB,CAAC;YACF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,cAAc,CAAC,QAAgB;QACnC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CACpC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,cAAc,CAC1C,CAAC;YACF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,eAAe,CAAC,KAA0B;QAC9C,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;YACxB,MAAM,IAAI,aAAa,CAAC,+CAA+C,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,cAAc,EAAE;gBACtE,UAAU,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,YAAY,EAAE;aACvC,CAAC,CAAC;YACH,OAAO;gBACL,YAAY,EAAE,IAAI;gBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,YAAY,EAAE,KAAK,CAAC,YAAY;aACjC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,MAAM,CAAC,KAAsB;QACjC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YACf,MAAM,IAAI,aAAa,CAAC,kCAAkC,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE;gBAC5D,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE;gBAClC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAClD,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;CACF"}

package/lib/esm/io/jira/index.js

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

package/lib/esm/io/jira/index.js.map

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

package/lib/esm/io/microsoft-excel/MicrosoftExcelService.js

@@ -0,0 +1,248 @@
+/**
+ * @module integrations/io/microsoft-excel/service
+ * @summary Microsoft Excel workbook integration service (Microsoft Graph).
+ * @description Exposes Graph workbook operations (worksheets, ranges, tables,
+ * and table rows) as an undecorated client-based service built on
+ * {@link HttpApiService}. Configuration comes from an explicit
+ * `MicrosoftExcelServiceConfig` or the `io.microsoftExcel` environment slice;
+ * the access token is sent as `Authorization: Bearer <token>`. Workbooks are
+ * addressed by OneDrive/SharePoint `itemId`, optionally within a `driveId`.
+ * Credentials are referenced from configuration (and, from as-graph nodes, from
+ * the resolved `microsoft-excel` 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 Microsoft Excel (Graph) workbook integration service
+ * @summary An undecorated HTTP service for listing worksheets and tables,
+ * reading and writing ranges, and appending table rows. Every operation
+ * requires a Graph access token and a workbook `itemId`; missing credentials or
+ * identifiers raise `InternalError`, and transport failures are mapped to decaf
+ * errors via {@link httpError}.
+ * @class MicrosoftExcelService
+ * @extends HttpApiService
+ * @category IO
+ * @example
+ * ```ts
+ * import { MicrosoftExcelService } from "@decaf-ts/integrations/io/microsoft-excel";
+ *
+ * const excel = new MicrosoftExcelService();
+ * await excel.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_MICROSOFT_EXCEL_TOKEN,
+ * });
+ * const range = await excel.getRange({
+ *   itemId: process.env.EXCEL_ITEM_ID ?? "",
+ *   worksheet: "Sheet1",
+ *   range: "A1:C10",
+ * });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as MicrosoftExcelService
+ *   participant Graph as Microsoft Graph
+ *   Caller->>Service: updateRange(input)
+ *   activate Service
+ *   Service->>Service: requireAccessToken()
+ *   Service->>Graph: PATCH /me/drive/items/{id}/workbook/worksheets/{name}/range(...)
+ *   activate Graph
+ *   Graph-->>Service: updated range payload
+ *   deactivate Graph
+ *   Service-->>Caller: updated range payload
+ *   deactivate Service
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export class MicrosoftExcelService extends HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.serviceName = "Microsoft Excel";
+    }
+    /**
+     * @description The Microsoft Graph base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://graph.microsoft.com/v1.0"`.
+     */
+    defaultBaseUrl() {
+        return "https://graph.microsoft.com/v1.0";
+    }
+    /**
+     * @description Builds the Microsoft Graph bearer authorization headers
+     * @summary Returns `Authorization: Bearer <token>` when configured, and no
+     * headers otherwise.
+     * @param {MicrosoftExcelServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    authHeaders(config) {
+        return config.token ? { Authorization: `Bearer ${config.token}` } : {};
+    }
+    /**
+     * @description Reads the Excel credentials and defaults from the environment
+     * @summary Reads the `io.microsoftExcel` slice and returns a partial config
+     * when an access token is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<MicrosoftExcelServiceConfig> | undefined} A partial config, or `undefined` when no Excel token is configured.
+     */
+    configFromEnvironment() {
+        const env = IoEnvironment.io.microsoftExcel;
+        const token = envString(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            baseUrl: envString(env.baseUrl),
+            timeout: envNumber(env.timeout),
+        };
+    }
+    /**
+     * @description Asserts that a Microsoft Graph access token is configured
+     * @summary Delegates to the shared `requireToken()` guard used by every
+     * operation.
+     * @returns {void}
+     * @throws {InternalError} When the resolved config has no `token`.
+     */
+    requireAccessToken() {
+        this.requireToken();
+    }
+    /**
+     * @description Builds the Graph workbook path for a drive item
+     * @summary Uses `/drives/<driveId>/items/<itemId>/workbook` when a `driveId`
+     * is set, otherwise the signed-in user's `/me/drive/...` path.
+     * @param {ExcelWorkbookRef} input - The workbook reference.
+     * @returns {string} The workbook API path.
+     * @throws {InternalError} When `itemId` is empty.
+     */
+    workbookPath(input) {
+        if (!input.itemId) {
+            throw new InternalError("Microsoft Excel requires a workbook item id");
+        }
+        const item = encodeURIComponent(input.itemId);
+        return input.driveId
+            ? `/drives/${encodeURIComponent(input.driveId)}/items/${item}/workbook`
+            : `/me/drive/items/${item}/workbook`;
+    }
+    /**
+     * @description Builds the Graph worksheet range path
+     * @summary Appends the encoded worksheet and A1 `range(address=...)`
+     * segments to the workbook path.
+     * @param {ExcelRangeInput} input - The workbook, worksheet, and range.
+     * @returns {string} The worksheet range API path.
+     * @throws {InternalError} When the worksheet or range is empty.
+     */
+    rangePath(input) {
+        if (!input.worksheet || !input.range) {
+            throw new InternalError("Microsoft Excel requires a worksheet and range");
+        }
+        return `${this.workbookPath(input)}/worksheets/${encodeURIComponent(input.worksheet)}/range(address='${encodeURIComponent(input.range)}')`;
+    }
+    /**
+     * @description Lists the worksheets in a workbook
+     * @summary `GET`s the workbook's `/worksheets` collection.
+     * @param {ExcelWorkbookRef} input - The workbook reference.
+     * @returns {Promise<unknown>} The Graph worksheet collection.
+     * @throws {InternalError} When no token is configured or `itemId` is empty.
+     * @throws {NotFoundError} When the workbook does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    async listWorksheets(input) {
+        this.requireAccessToken();
+        try {
+            const response = await this.client.get(`${this.workbookPath(input)}/worksheets`);
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Microsoft Excel", "list worksheets", error);
+        }
+    }
+    /**
+     * @description Reads values from a worksheet range
+     * @summary `GET`s the addressed range and returns its values and formatting
+     * payload.
+     * @param {ExcelRangeInput} input - The workbook, worksheet, and range.
+     * @returns {Promise<unknown>} The range payload.
+     * @throws {InternalError} When no token is configured, or the workbook, worksheet, or range is empty.
+     * @throws {NotFoundError} When the workbook or range does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    async getRange(input) {
+        this.requireAccessToken();
+        try {
+            const response = await this.client.get(this.rangePath(input));
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Microsoft Excel", "get range", error);
+        }
+    }
+    /**
+     * @description Writes values into a worksheet range
+     * @summary `PATCH`es the addressed range with the supplied `values` matrix
+     * and returns the updated range payload.
+     * @param {ExcelRangeWriteInput} input - The range reference and values to write.
+     * @returns {Promise<unknown>} The updated range payload.
+     * @throws {InternalError} When no token is configured, or the workbook, worksheet, or range is empty.
+     * @throws {NotFoundError} When the workbook or range does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    async updateRange(input) {
+        this.requireAccessToken();
+        try {
+            const response = await this.client.patch(this.rangePath(input), {
+                values: input.values,
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Microsoft Excel", "update range", error);
+        }
+    }
+    /**
+     * @description Lists the tables in a workbook
+     * @summary `GET`s the workbook's `/tables` collection.
+     * @param {ExcelWorkbookRef} input - The workbook reference.
+     * @returns {Promise<unknown>} The Graph table collection.
+     * @throws {InternalError} When no token is configured or `itemId` is empty.
+     * @throws {NotFoundError} When the workbook does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    async listTables(input) {
+        this.requireAccessToken();
+        try {
+            const response = await this.client.get(`${this.workbookPath(input)}/tables`);
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Microsoft Excel", "list tables", error);
+        }
+    }
+    /**
+     * @description Appends a row to an Excel table
+     * @summary `POST`s the single row to the table's `/rows/add` endpoint and
+     * returns the Graph row payload.
+     * @param {ExcelTableRowInput} input - The workbook, table, and row values.
+     * @returns {Promise<unknown>} The created table row payload.
+     * @throws {InternalError} When no token is configured, or the workbook, table, or values are missing.
+     * @throws {NotFoundError} When the workbook or table does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    async addTableRow(input) {
+        this.requireAccessToken();
+        if (!input.tableId || !input.values?.length) {
+            throw new InternalError("Microsoft Excel addTableRow requires a table id and values");
+        }
+        try {
+            const response = await this.client.post(`${this.workbookPath(input)}/tables/${encodeURIComponent(input.tableId)}/rows/add`, { values: [input.values] });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Microsoft Excel", "add table row", error);
+        }
+    }
+}
+//# sourceMappingURL=MicrosoftExcelService.js.map

package/lib/esm/io/microsoft-excel/MicrosoftExcelService.js.map

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

package/lib/esm/io/microsoft-excel/index.js

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

package/lib/esm/io/microsoft-excel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/io/microsoft-excel/index.ts"],"names":[],"mappings":"AAAA,2CAAwC"}