@decaf-ts/integrations 0.11.0 → 0.12.0

package/lib/cjs/comms/telegram/TelegramService.cjs

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramService = void 0;
+/**
+ * @module integrations/comms/telegram/service
+ * @summary Telegram Bot API integration service for sending messages and reading updates.
+ * @description Exposes the Telegram Bot API (`getMe`, `sendMessage`,
+ * `getUpdates`, `sendChatAction`) as an undecorated client-based service built
+ * on {@link HttpApiService}. The bot token is part of the request
+ * path (`/bot<token>/<method>`); configuration comes from an explicit
+ * `TelegramServiceConfig` or the `comms.telegram` environment slice, and
+ * 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 Telegram Bot API integration service
+ * @summary An undecorated HTTP service for verifying the bot
+ * identity, sending messages with parse modes and reply/thread options, long
+ * or short polling `getUpdates`, and posting chat actions. The bot token is
+ * required (`requireToken()`) and embedded in the request path; non-`ok` Bot
+ * API responses raise `InternalError`, and transport failures are mapped to
+ * decaf errors via {@link httpError}.
+ * @class TelegramService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { TelegramService } from "@decaf-ts/integrations/comms/telegram";
+ *
+ * const telegram = new TelegramService();
+ * await telegram.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_TELEGRAM_TOKEN,
+ * });
+ * await telegram.sendMessage({
+ *   chatId: "@mychannel",
+ *   text: "Release 1.2.0 is live",
+ *   parseMode: "HTML",
+ * });
+ * ```
+ * @memberOf module:integrations/comms/telegram/service
+ */
+class TelegramService extends index_js_1.HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.serviceName = "Telegram";
+    }
+    /**
+     * @description The Telegram Bot API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://api.telegram.org"`.
+     */
+    defaultBaseUrl() {
+        return "https://api.telegram.org";
+    }
+    /**
+     * @description Reads the Telegram credentials and defaults from the environment
+     * @summary Reads the `comms.telegram` environment slice and returns a
+     * partial config when a token is configured, `undefined` otherwise. Values
+     * pass through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<TelegramServiceConfig> | undefined} A partial config, or `undefined` when no Telegram token is configured.
+     */
+    configFromEnvironment() {
+        const env = environment_js_1.CommsEnvironment.comms.telegram;
+        const token = (0, environmentValue_js_1.envString)(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            baseUrl: (0, environmentValue_js_1.envString)(env.baseUrl),
+            timeout: (0, environmentValue_js_1.envNumber)(env.timeout),
+        };
+    }
+    /**
+     * @description Calls a Telegram Bot API method with the configured bot token
+     * @summary Shared request path for all Telegram operations: resolves the
+     * token (`requireToken()`), `POST`s the payload to
+     * `/bot<token>/<method>`, rejects non-`ok` Bot API responses with an
+     * `InternalError`, and maps transport failures through {@link httpError}.
+     * @template T - The expected `result` payload type of the Bot API response.
+     * @param {string} method - The Bot API method name (e.g. `"sendMessage"`).
+     * @param {Record<string, unknown>} [payload] - The JSON body for the method; defaults to an empty object.
+     * @returns {Promise<T>} The `result` payload of the Bot API response.
+     * @throws {InternalError} When no token is configured or the Bot API answers with `ok: false`.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    async call(method, payload = {}) {
+        const token = this.requireToken();
+        try {
+            const response = await this.client.post(`/bot${token}/${method}`, payload);
+            const data = response.data;
+            if (!data || data.ok !== true) {
+                throw new db_decorators_1.InternalError(`Telegram Bot API ${method} failed: ${data?.description ?? "unknown error"}`);
+            }
+            return data.result;
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Telegram", `Bot API ${method}`, error);
+        }
+    }
+    /**
+     * @description Fetches the authenticated bot's identity
+     * @summary Calls the `getMe` method and returns the raw bot descriptor
+     * (including `id`, `username`, and `can_join_groups` flags).
+     * @returns {Promise<Record<string, unknown>>} The raw `User` payload describing the bot.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the call.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    async getMe() {
+        return this.call("getMe");
+    }
+    /**
+     * @description Sends a message to a Telegram chat
+     * @summary Calls the `sendMessage` method with the destination chat, text,
+     * and the requested parse/notification/reply/thread options, returning the
+     * sent message descriptor.
+     * @param {TelegramSendMessageInput} input - The message destination, content, and options.
+     * @returns {Promise<TelegramMessage>} The sent message descriptor.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the message.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     * @example
+     * ```ts
+     * await telegram.sendMessage({
+     *   chatId: "-1001234567890",
+     *   text: "*Release* 1.2.0 is live",
+     *   parseMode: "MarkdownV2",
+     *   disableNotification: true,
+     * });
+     * ```
+     */
+    async sendMessage(input) {
+        return this.call("sendMessage", {
+            chat_id: input.chatId,
+            text: input.text,
+            parse_mode: input.parseMode,
+            disable_notification: input.disableNotification,
+            disable_web_page_preview: input.disablePreview,
+            reply_to_message_id: input.replyToMessageId,
+            message_thread_id: input.messageThreadId,
+        });
+    }
+    /**
+     * @description Polls pending bot updates
+     * @summary Calls the `getUpdates` method, optionally with an `offset`
+     * (confirmation of processed updates), a `limit` on returned updates, and a
+     * long-polling `timeoutSeconds`. Advance `offset` past each handled
+     * update's `update_id` to avoid re-reading them.
+     * @param {object} [options] - Polling options.
+     * @param {number} [options.offset] - The first update ID to return (previous ID + 1).
+     * @param {number} [options.limit] - Maximum number of updates to return (1-100).
+     * @param {number} [options.timeoutSeconds] - Long-polling timeout in seconds.
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw `Update` payloads.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the call.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409 (e.g. another `getUpdates` call is in flight).
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    async getUpdates(options = {}) {
+        return this.call("getUpdates", {
+            offset: options.offset,
+            limit: options.limit,
+            timeout: options.timeoutSeconds,
+        });
+    }
+    /**
+     * @description Posts a chat action (typing indicator)
+     * @summary Calls the `sendChatAction` method so clients display the given
+     * action (e.g. `"typing"`) for up to five seconds.
+     * @param {string | number} chatId - The destination chat ID or `@channelusername`.
+     * @param {string} [action] - The action to display; defaults to `"typing"`.
+     * @returns {Promise<boolean>} Whether the action was accepted.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the call.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    async sendChatAction(chatId, action = "typing") {
+        return this.call("sendChatAction", {
+            chat_id: chatId,
+            action,
+        });
+    }
+}
+exports.TelegramService = TelegramService;
+//# sourceMappingURL=TelegramService.js.map
+//# sourceMappingURL=TelegramService.cjs.map

package/lib/cjs/comms/telegram/TelegramService.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms/telegram/TelegramService.cjs","sourceRoot":"","sources":["comms/telegram/TelegramService.js"],"names":[],"mappings":"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"}

package/lib/cjs/comms/telegram/index.cjs

@@ -0,0 +1,24 @@
+"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 });
+/**
+ * @module integrations/comms/telegram
+ * @summary Telegram Bot API service (messaging, updates, chat actions).
+ * @description Re-exports the Telegram client-based service and its types.
+ */
+__exportStar(require("./TelegramService.cjs"), exports);
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map

package/lib/cjs/comms/telegram/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms/telegram/index.cjs","sourceRoot":"","sources":["comms/telegram/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;GAIG;AACH,uDAAqC;AACrC,iCAAiC"}

package/lib/cjs/devops/environment.cjs

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevopsEnvironment = void 0;
+const logging_1 = require("@decaf-ts/logging");
+/**
+ * @description Accumulated devops environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `DevopsEnvironmentShape` contract. Devops services read their provider
+ * slice (e.g. `DevopsEnvironment.devops.github`) 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 { GithubService } from "@decaf-ts/integrations/devops/github";
+ *
+ * // with devops.github.token / devops.github.owner / devops.github.repo configured
+ * const github = new GithubService();
+ * await github.initialize();
+ * ```
+ * @constant {LoggedEnvironment} DevopsEnvironment
+ * @memberOf module:integrations/devops/environment
+ */
+exports.DevopsEnvironment = logging_1.LoggedEnvironment.accumulate({
+    devops: {
+        github: {
+            token: "",
+            baseUrl: "",
+            owner: "",
+            repo: "",
+            timeout: undefined,
+        },
+        gitlab: {
+            token: "",
+            baseUrl: "",
+            projectId: "",
+            timeout: undefined,
+        },
+    },
+});
+//# sourceMappingURL=environment.js.map
+//# sourceMappingURL=environment.cjs.map

package/lib/cjs/devops/environment.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"devops/environment.cjs","sourceRoot":"","sources":["devops/environment.js"],"names":[],"mappings":";;;AAAA,+CAAsD;AACtD;;;;;;;;;;;;;;;;;;;GAmBG;AACU,QAAA,iBAAiB,GAAG,2BAAiB,CAAC,UAAU,CAAC;IAC1D,MAAM,EAAE;QACJ,MAAM,EAAE;YACJ,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,EAAE;YACT,IAAI,EAAE,EAAE;YACR,OAAO,EAAE,SAAS;SACrB;QACD,MAAM,EAAE;YACJ,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,SAAS,EAAE,EAAE;YACb,OAAO,EAAE,SAAS;SACrB;KACJ;CACJ,CAAC,CAAC;AACH,uCAAuC"}

package/lib/cjs/devops/github/GithubService.cjs

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GithubService = void 0;
+/**
+ * @module integrations/devops/github/service
+ * @summary GitHub REST API integration service for repositories, issues, and pull requests.
+ * @description Exposes a focused subset of the GitHub REST API (`/repos/*`:
+ * repository lookup, issue listing/creation/commenting, and pull-request
+ * listing) as an undecorated client-based service built on
+ * {@link HttpApiService}. Configuration comes from an explicit
+ * `GithubServiceConfig` or the `devops.github` environment slice; repository
+ * targets default to the configured `owner`/`repo` and can be overridden per
+ * call. Raw GitHub responses are normalized to camelCase issue descriptors,
+ * and 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 GitHub REST API integration service
+ * @summary An undecorated HTTP service for looking up
+ * repositories, listing issues (excluding pull requests), creating issues,
+ * commenting on issues, and listing pull requests. Repository targets resolve
+ * per call from the input's `owner`/`repo`, falling back to the configured
+ * config values, and throw `InternalError` when unresolved. The token is sent
+ * as a bearer token with the GitHub `Accept` and API-version headers, and
+ * transport failures are mapped to decaf errors via {@link httpError}.
+ * @class GithubService
+ * @category DevOps
+ * @example
+ * ```ts
+ * import { GithubService } from "@decaf-ts/integrations/devops/github";
+ *
+ * const github = new GithubService();
+ * await github.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GITHUB_TOKEN,
+ *   owner: "example-org",
+ *   repo: "example-repo",
+ * });
+ * const issue = await github.createIssue({
+ *   title: "Bug report",
+ *   body: "Something is broken",
+ *   labels: ["bug"],
+ * });
+ * ```
+ * @memberOf module:integrations/devops/github/service
+ */
+class GithubService extends index_js_1.HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.serviceName = "GitHub";
+    }
+    /**
+     * @description The GitHub REST API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://api.github.com"`.
+     */
+    defaultBaseUrl() {
+        return "https://api.github.com";
+    }
+    /**
+     * @description Builds the GitHub authentication and API version headers
+     * @summary Returns `Authorization: Bearer <token>`, the GitHub JSON
+     * `Accept` header, and the `X-GitHub-Api-Version` header when the config
+     * carries a token; without a token only the `Accept` headers are sent.
+     * @param {GithubServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization and version headers.
+     */
+    authHeaders(config) {
+        return config.token
+            ? {
+                Authorization: `Bearer ${config.token}`,
+                Accept: "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            }
+            : { Accept: "application/vnd.github+json" };
+    }
+    /**
+     * @description Reads the GitHub credentials and defaults from the environment
+     * @summary Reads the `devops.github` environment slice and returns a
+     * partial config when a token is configured, `undefined` otherwise. Values
+     * pass through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<GithubServiceConfig> | undefined} A partial config, or `undefined` when no GitHub token is configured.
+     */
+    configFromEnvironment() {
+        const env = environment_js_1.DevopsEnvironment.devops.github;
+        const token = (0, environmentValue_js_1.envString)(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            owner: (0, environmentValue_js_1.envString)(env.owner),
+            repo: (0, environmentValue_js_1.envString)(env.repo),
+            baseUrl: (0, environmentValue_js_1.envString)(env.baseUrl),
+            timeout: (0, environmentValue_js_1.envNumber)(env.timeout),
+        };
+    }
+    /**
+     * @description Resolves the URL-encoded repository path for a call
+     * @summary Builds `/repos/<owner>/<repo>` from the input's `owner`/`repo`,
+     * falling back to the configured config values, and throws when either
+     * value is missing.
+     * @param {GithubRepositoryRef} [input] - The per-call repository override.
+     * @returns {string} The URL-encoded repository API path.
+     * @throws {InternalError} When neither the input nor the config yields an owner and repository.
+     */
+    repoPath(input = {}) {
+        const owner = input.owner ?? this.config.owner;
+        const repo = input.repo ?? this.config.repo;
+        if (!owner || !repo) {
+            throw new db_decorators_1.InternalError("GitHub requires an owner and repository");
+        }
+        return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+    }
+    /**
+     * @description Normalizes a raw GitHub issue payload
+     * @summary Maps the raw issue JSON onto a {@link GithubIssue}: label objects
+     * are reduced to names, the author to its `login`, and numeric/string
+     * fields are coerced. The repository reference is echoed from the input,
+     * falling back to the configured `owner`/`repo`.
+     * @param {Record<string, unknown>} raw - The raw GitHub issue payload.
+     * @param {GithubRepositoryRef} ref - The repository reference the issue belongs to.
+     * @returns {GithubIssue} The normalized issue descriptor.
+     */
+    mapIssue(raw, ref) {
+        return {
+            owner: ref.owner ?? this.config.owner,
+            repo: ref.repo ?? this.config.repo,
+            number: Number(raw["number"] ?? 0),
+            title: String(raw["title"] ?? ""),
+            state: (0, environmentValue_js_1.envString)(raw["state"]),
+            htmlUrl: (0, environmentValue_js_1.envString)(raw["html_url"]),
+            body: (0, environmentValue_js_1.envString)(raw["body"]),
+            user: (0, environmentValue_js_1.envString)(raw["user"]?.login),
+            labels: Array.isArray(raw["labels"])
+                ? raw["labels"].map((label) => typeof label === "string" ? label : String(label.name ?? ""))
+                : undefined,
+            comments: typeof raw["comments"] === "number"
+                ? raw["comments"]
+                : undefined,
+            createdAt: (0, environmentValue_js_1.envString)(raw["created_at"]),
+            updatedAt: (0, environmentValue_js_1.envString)(raw["updated_at"]),
+        };
+    }
+    /**
+     * @description Fetches a GitHub repository
+     * @summary `GET`s `/repos/<owner>/<repo>` for the given reference (falling
+     * back to the configured `owner`/`repo`) and returns the raw repository
+     * payload.
+     * @param {GithubRepositoryRef} [ref] - The repository to look up; defaults to the configured `owner`/`repo`.
+     * @returns {Promise<unknown>} The raw GitHub repository payload.
+     * @throws {InternalError} When the repository reference cannot be resolved.
+     * @throws {NotFoundError} When the repository does not exist (HTTP 404).
+     * @throws {ConflictError} When GitHub answers with HTTP 409.
+     * @throws {BadRequestError} When GitHub answers with any other HTTP error status.
+     */
+    async getRepository(ref = {}) {
+        try {
+            const response = await this.client.get(this.repoPath(ref));
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("GitHub", "get repository", error);
+        }
+    }
+    /**
+     * @description Lists GitHub issues with state, label, and page filtering
+     * @summary `GET`s `/repos/<owner>/<repo>/issues` with a `state` filter
+     * (default `"open"`), a page size (`per_page`, default `30`), a page
+     * number, and a comma-separated `labels` filter. Entries carrying a
+     * `pull_request` key are filtered out so only true issues are returned.
+     * @param {GithubListOptions} [options] - Repository override, state, paging, and label options.
+     * @returns {Promise<GithubIssue[]>} The normalized issues for the requested page.
+     * @throws {InternalError} When the repository reference cannot be resolved.
+     * @throws {NotFoundError} When the repository does not exist (HTTP 404).
+     * @throws {ConflictError} When GitHub answers with HTTP 409.
+     * @throws {BadRequestError} When GitHub answers with any other HTTP error status.
+     * @example
+     * ```ts
+     * let page = 1;
+     * for (;;) {
+     *   const issues = await github.listIssues({
+     *     state: "open",
+     *     labels: "bug,priority:high",
+     *     limit: 50,
+     *     page,
+     *   });
+     *   if (issues.length === 0) break;
+     *   page += 1;
+     * }
+     * ```
+     */
+    async listIssues(options = {}) {
+        try {
+            const response = await this.client.get(`${this.repoPath(options)}/issues`, {
+                params: {
+                    state: options.state ?? "open",
+                    per_page: options.limit ?? 30,
+                    page: options.page,
+                    labels: options.labels,
+                },
+            });
+            return response.data
+                .filter((entry) => !entry["pull_request"])
+                .map((entry) => this.mapIssue(entry, options));
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("GitHub", "list issues", error);
+        }
+    }
+    /**
+     * @description Creates a GitHub issue
+     * @summary `POST`s the title, body, labels, assignees, and milestone to
+     * `/repos/<owner>/<repo>/issues` and returns the normalized issue
+     * descriptor. Requires a non-empty `title` and a resolvable repository
+     * reference.
+     * @param {GithubIssueInput} input - The issue content and repository targeting.
+     * @returns {Promise<GithubIssue>} The normalized created issue.
+     * @throws {InternalError} When the title is empty or the repository reference cannot be resolved.
+     * @throws {NotFoundError} When the repository does not exist (HTTP 404).
+     * @throws {ConflictError} When GitHub answers with HTTP 409.
+     * @throws {BadRequestError} When GitHub answers with any other HTTP error status (e.g. invalid labels or assignees).
+     */
+    async createIssue(input) {
+        if (!input.title) {
+            throw new db_decorators_1.InternalError("GitHub issue requires a title");
+        }
+        try {
+            const response = await this.client.post(`${this.repoPath(input)}/issues`, {
+                title: input.title,
+                body: input.body,
+                labels: input.labels,
+                assignees: input.assignees,
+                milestone: input.milestone,
+            });
+            return this.mapIssue(response.data, input);
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("GitHub", "create issue", error);
+        }
+    }
+    /**
+     * @description Comments on a GitHub issue
+     * @summary `POST`s the comment body to
+     * `/repos/<owner>/<repo>/issues/<number>/comments` and returns the comment
+     * identifier and its HTML URL. Requires a non-empty issue number and body.
+     * @param {GithubRepositoryRef & {number: number, body: string}} input - The repository targeting, issue number, and comment body.
+     * @returns {Promise<{id: number, htmlUrl?: string}>} The created comment's ID and HTML URL.
+     * @throws {InternalError} When the issue number or body is empty, or the repository reference cannot be resolved.
+     * @throws {NotFoundError} When the issue does not exist (HTTP 404).
+     * @throws {ConflictError} When GitHub answers with HTTP 409.
+     * @throws {BadRequestError} When GitHub answers with any other HTTP error status.
+     */
+    async commentOnIssue(input) {
+        if (!input.number || !input.body) {
+            throw new db_decorators_1.InternalError("GitHub comment requires an issue number and body");
+        }
+        try {
+            const response = await this.client.post(`${this.repoPath(input)}/issues/${input.number}/comments`, {
+                body: input.body,
+            });
+            return { id: Number(response.data.id ?? 0), htmlUrl: response.data.html_url };
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("GitHub", "comment on issue", error);
+        }
+    }
+    /**
+     * @description Lists GitHub pull requests with state and page filtering
+     * @summary `GET`s `/repos/<owner>/<repo>/pulls` with a `state` filter
+     * (default `"open"`), a page size (`per_page`, default `30`), and a page
+     * number. Pull requests are returned as raw GitHub payloads.
+     * @param {GithubListOptions} [options] - Repository override, state, and paging options.
+     * @returns {Promise<unknown[]>} The raw GitHub pull-request payloads.
+     * @throws {InternalError} When the repository reference cannot be resolved.
+     * @throws {NotFoundError} When the repository does not exist (HTTP 404).
+     * @throws {ConflictError} When GitHub answers with HTTP 409.
+     * @throws {BadRequestError} When GitHub answers with any other HTTP error status.
+     */
+    async listPullRequests(options = {}) {
+        try {
+            const response = await this.client.get(`${this.repoPath(options)}/pulls`, {
+                params: {
+                    state: options.state ?? "open",
+                    per_page: options.limit ?? 30,
+                    page: options.page,
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("GitHub", "list pull requests", error);
+        }
+    }
+}
+exports.GithubService = GithubService;
+//# sourceMappingURL=GithubService.js.map
+//# sourceMappingURL=GithubService.cjs.map

package/lib/cjs/devops/github/GithubService.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"devops/github/GithubService.cjs","sourceRoot":"","sources":["devops/github/GithubService.js"],"names":[],"mappings":"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"}

package/lib/cjs/devops/github/index.cjs

@@ -0,0 +1,24 @@
+"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 });
+/**
+ * @module integrations/devops/github
+ * @summary GitHub REST v3 service (repositories, issues, pull requests).
+ * @description Re-exports the GitHub client-based service and its types.
+ */
+__exportStar(require("./GithubService.cjs"), exports);
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map

package/lib/cjs/devops/github/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"devops/github/index.cjs","sourceRoot":"","sources":["devops/github/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;GAIG;AACH,qDAAmC;AACnC,iCAAiC"}