@cogitator-ai/channels 0.15.12 → 0.16.0

package/dist/channels/github/channel.d.ts

@@ -0,0 +1,222 @@
+import { type RequestListener } from 'node:http';
+import type { Attachment, Channel, ChannelMessage, SendOptions } from '@cogitator-ai/types';
+import { type GitHubToken } from './client.js';
+/** The longest comment GitHub takes, in characters. */
+export declare const GITHUB_COMMENT_LIMIT = 65536;
+/** The shortest time between two edits of one comment, under GitHub's limit on content changes. */
+export declare const GITHUB_MIN_EDIT_INTERVAL = 3000;
+/** How an author is related to a repository, as GitHub's `author_association` says it. */
+export type GitHubAssociation = 'OWNER' | 'MEMBER' | 'COLLABORATOR' | 'CONTRIBUTOR' | 'FIRST_TIME_CONTRIBUTOR' | 'FIRST_TIMER' | 'MANNEQUIN' | 'NONE';
+/** The authors the bot answers by default: the repository's owner, the organization's members and collaborators. */
+export declare const GITHUB_TRUSTED_ASSOCIATIONS: readonly GitHubAssociation[];
+export interface GitHubWebhookConfig {
+    /** The secret set on the webhook, which signs every delivery. Required. */
+    secret: string;
+    /**
+     * Run an HTTP server of the channel's own on this port. Without it, mount
+     * `handleWebhook` or `webhookListener()` in a server of yours.
+     */
+    port?: number;
+    /** The path of the channel's own server (default `/github/webhook`). */
+    path?: string;
+    host?: string;
+}
+export interface GitHubChannelConfig {
+    /**
+     * A personal access token, a GitHub App installation token, or a function
+     * that returns a fresh one before every request. It needs to read and write
+     * issues and pull requests of the repositories the bot answers in.
+     */
+    token: GitHubToken;
+    /** Where deliveries come from: GitHub only pushes events, so the webhook is required. */
+    webhook: GitHubWebhookConfig;
+    /**
+     * The bot's login, for skipping its own comments and finding mentions of it.
+     * Loaded with `GET /user` when not set, which a GitHub App installation
+     * token cannot do: an app sets it to `<app-slug>[bot]`.
+     */
+    login?: string;
+    /**
+     * Which events the bot answers: `mention` (default) answers only those
+     * that mention `@login`, `all` every new issue, pull request, comment and
+     * review in the allowed repositories. Once the bot answered someone in a
+     * conversation, their next comment there reaches it without a mention (an
+     * answer to an approval prompt, a follow-up), and so does every comment in
+     * a review thread it replied in.
+     */
+    trigger?: 'mention' | 'all';
+    /**
+     * The repositories to answer in, as `owner/repo` or `owner/*` for every
+     * repository of an owner. Default: every repository that sends events,
+     * which `start()` warns about.
+     */
+    repositories?: string[];
+    /**
+     * Whose events the bot answers, by their relation to the repository
+     * (`author_association`). Default `OWNER`, `MEMBER` and `COLLABORATOR`,
+     * since what people write steers an agent that holds the token. `'any'`
+     * answers everyone, for a public bot whose agent has nothing to leak.
+     */
+    associations?: readonly GitHubAssociation[] | 'any';
+    /** Logins the bot answers whatever their association, such as private members of an organization. */
+    authors?: string[];
+    /** Answer other bots and apps too (default false, so two bots cannot answer each other forever). */
+    allowBots?: boolean;
+    /**
+     * Stream answers into a comment that is edited as the text grows (default
+     * false). GitHub notifies subscribers of a comment once, with its first
+     * text, and limits how often content may be changed, so answers are sent
+     * once finished unless this is on. Edits of one comment are at least
+     * `GITHUB_MIN_EDIT_INTERVAL` (3 s) apart, the latest text winning.
+     */
+    stream?: boolean;
+    /** The REST API root, `https://<host>/api/v3` on GitHub Enterprise Server. */
+    apiUrl?: string;
+    fetch?: typeof fetch;
+}
+/** A webhook delivery, as any HTTP server hands it over. */
+export interface GitHubWebhookRequest {
+    method: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** The body exactly as received, which the signature covers. */
+    rawBody?: string | Uint8Array;
+}
+export interface GitHubWebhookResponse {
+    status: number;
+    body: string;
+}
+/** Whether `signature` (`sha256=<hex>`) is the HMAC SHA-256 of `body` with `secret`. */
+export declare function verifyGitHubSignature(body: string | Uint8Array, signature: string | undefined, secret: string): boolean;
+/**
+ * A GitHub channel: an agent answers issues, pull requests, their comments
+ * and reviews, in the repositories a webhook sends events from. Each issue or
+ * pull request is one conversation, `channelId` `owner/repo#number`, and
+ * answers are comments on it. A comment on a line of a pull request is
+ * answered in its review thread, which is the message's `topicId` (the id of
+ * the thread's first comment), so every review thread is a conversation of
+ * its own. Deliveries are checked against the webhook secret, answered at
+ * once and handled after.
+ */
+export declare class GitHubChannel implements Channel {
+    readonly type = "github";
+    readonly editable: boolean;
+    readonly nativeMarkdown = true;
+    readonly maxMessageChars = 65536;
+    private readonly config;
+    private readonly client;
+    private handler;
+    private readonly deliveries;
+    private readonly handled;
+    private readonly reactions;
+    private readonly reacting;
+    private readonly edits;
+    /** People who wrote to the bot in a conversation and were not answered yet, by conversation. */
+    private readonly waiting;
+    /** The conversation and author of each message handed to the agent, by `channelId|messageId`. */
+    private readonly askers;
+    private readonly engaged;
+    private server?;
+    private identity?;
+    private botLogin?;
+    private running;
+    private stopped;
+    constructor(config: GitHubChannelConfig);
+    /** The bot's login, once known: as configured, or loaded by `start()` or the first delivery. */
+    get login(): string | undefined;
+    onMessage(handler: (msg: ChannelMessage) => Promise<void>): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Answers a webhook delivery: checks its signature, answers at once and
+     * hands the event to the agent after. Mount it in any HTTP server, with the
+     * raw body unparsed. It works before `start()` too, and answers `503` once
+     * the channel is stopped. A delivery GitHub sends again is handled once:
+     * by its `X-GitHub-Delivery` and by the comment, issue or review it
+     * carries, which the signature covers. Both are remembered in memory only,
+     * for the latest 1000, so a delivery sent again after a restart is
+     * handled again.
+     */
+    handleWebhook(request: GitHubWebhookRequest): Promise<GitHubWebhookResponse>;
+    /**
+     * A Node request listener that answers webhook deliveries on any path it
+     * is mounted at, such as a route of a server that serves other things too.
+     * Bodies over 1 MB are refused with `413`.
+     */
+    webhookListener(): RequestListener;
+    /**
+     * Comments on the issue or pull request of `channelId`, as several
+     * comments when the text is longer than GitHub takes. With a `topicId`, or
+     * a `replyTo` of a review comment, the comments are replies in that review
+     * thread. Resolves with the first comment's id.
+     */
+    sendText(channelId: string, text: string, options?: SendOptions): Promise<string>;
+    /**
+     * Replaces the text of a comment the bot made (`comment:<id>` or
+     * `review_comment:<id>`). Edits of one comment go out at least
+     * `GITHUB_MIN_EDIT_INTERVAL` apart: an edit made sooner waits, and edits
+     * made while it waits are folded into it, the latest text winning.
+     */
+    editText(channelId: string, messageId: string, text: string): Promise<void>;
+    /** Sends the latest text of an edit once the comment's last edit is far enough back. */
+    private flushEdit;
+    /**
+     * GitHub has no API to upload files to comments, so a file with a public
+     * `url` is sent as a comment that links it (an image shows inline), and a
+     * file that only has a `buffer` is refused.
+     */
+    sendFile(channelId: string, file: Attachment, options?: SendOptions): Promise<string>;
+    sendTyping(): Promise<void>;
+    /** Deletes a comment the bot made. */
+    deleteMessage(channelId: string, messageId: string): Promise<void>;
+    /**
+     * Reacts to an issue, pull request or comment, replacing the bot's earlier
+     * reaction on it. GitHub has eight reactions (+1, -1, laugh, confused,
+     * heart, hooray, rocket, eyes), named or as their emoji, and the status
+     * emojis of thinking, a tool and an error become eyes, rocket and
+     * confused. Other emojis are skipped, and so are reviews, which take no
+     * reactions. Reactions to one message are set one after another, so the
+     * last one called is the one that stays.
+     */
+    setReaction(channelId: string, messageId: string, emoji: string): Promise<void>;
+    private react;
+    private comment;
+    private commentPath;
+    private reactionsPath;
+    /**
+     * Notes that the bot answered in a conversation. The person the answer is
+     * for (its `replyTo`, or everyone waiting there when it names no message
+     * the bot was asked in) may write on without a mention, and in a review
+     * thread everyone may.
+     */
+    private answered;
+    private remember;
+    /** Whether a message reaches the bot without a mention: in a conversation it answered. */
+    private takesWithoutMention;
+    /**
+     * Hands a delivery's event to the agent when it is one to answer. Resolves
+     * false when the event was dropped because the bot's login could not be
+     * loaded or the channel stopped, so the delivery may be sent again.
+     */
+    private receive;
+    /**
+     * The bot's login for a delivery: loaded when it is not known yet, and
+     * tried again a few times, since GitHub does not send a delivery again by
+     * itself. The delivery is dropped, with an error logged, when it cannot be
+     * loaded.
+     */
+    private loginForDelivery;
+    /** Loads the bot's login once, unless it is configured. */
+    private identify;
+    private allowsRepository;
+    /** Whether the author may talk to the bot: by their association, or named in `authors`. */
+    private trusts;
+    private isOwnOrBot;
+    /** The name people mention the bot by: its login, without `[bot]` for an app. */
+    private mentionName;
+    private mentionsBot;
+    private stripMention;
+    private listen;
+}
+/** A GitHub channel that answers issues, pull requests, comments and reviews. */
+export declare function githubChannel(config: GitHubChannelConfig): GitHubChannel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channels/github/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/channels/github/channel.ts"],"names":[],"mappings":"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"}