@amykit/plugin-slack 0.5.0

package/README.md

@@ -0,0 +1,61 @@
+<!-- Generated by `npm run docs:generate` from the package itself. Do not edit by hand. -->
+
+# @amykit/plugin-slack
+
+A Slack thread per piece of work, over the Web API, as the conversation port.
+
+A plugin for [amy](https://github.com/nicolasmelo1/amy). It provides the `conversation` port.
+
+## Install
+
+```sh
+# Add @amykit/plugin-slack to amy.yaml, then install configured plugins:
+amy init --install
+```
+
+Then name it in `~/.amy/config.yaml`:
+
+```yaml
+workflows:
+  your-profile:
+    plugins:
+      - "@amykit/plugin-slack"
+```
+
+## Configuration
+
+```yaml
+plugins:
+  "@amykit/plugin-slack":
+    channel: <string>
+    defaultRetryAfterSeconds: 60
+    directory: "slack"
+    maxRateLimitRetries: 5
+    operator: <string>
+    retentionDays: 30
+    token: <string>
+```
+
+| Setting | Type | Required | Default | What it is |
+| :-- | :-- | :-- | :-- | :-- |
+| `channel` | `string` | **yes** |  | the channel id every work thread opens in, such as C0XXXXXXX — an id, not a name |
+| `defaultRetryAfterSeconds` | `number` | no | `60` | how long to wait after a 429 that carries no Retry-After; one names its own wait, and that wins |
+| `directory` | `string` | no | `slack` | where each work item's thread is remembered, relative to the state directory |
+| `maxRateLimitRetries` | `number` | no | `5` | how many times a call Slack rate limits (HTTP 429) is waited out and tried again before it fails |
+| `operator` | `string` | **yes** |  | the user id, such as U0XXXXXXX, whose replies are answers; everybody else's are ignored |
+| `retentionDays` | `number` | no | `30` | days a downloaded file or a thread's memory stays unused before it is pruned, 0 to keep everything. A pruned file is fetched again when its reply is read; a pruned thread means the next question opens a new one |
+| `token` | `string` | **yes** |  | where the bot token lives: `env:SLACK_BOT_TOKEN` or `file:<path>#<KEY>`, never the token itself |
+
+Every field is checked at boot against the schema this package declares. A key that is
+not one of the above is a refusal naming the plugin and the key, not a setting that
+silently never applied.
+
+## Where the reasoning is
+
+- [Writing a plugin](https://github.com/nicolasmelo1/amy/tree/main/docs/build/write-a-plugin.md)
+- [Reference: plugins](https://github.com/nicolasmelo1/amy/tree/main/docs/reference/plugins.md)
+- [Ports and the registry](https://github.com/nicolasmelo1/amy/tree/main/docs/concepts/ports.md)
+
+## Licence
+
+MIT

package/dist/SlackApi.d.ts

@@ -0,0 +1,67 @@
+/** One HTTP exchange, small enough to script in a test. */
+export interface HttpRequest {
+    url: string;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    body?: string;
+    /** Refuse the answer once its body passes this many bytes, while it arrives. */
+    maxBytes?: number;
+}
+export interface HttpResponse {
+    status: number;
+    /** Lower-cased names. */
+    headers: Record<string, string>;
+    body: Uint8Array;
+}
+export type HttpTransport = (request: HttpRequest) => Promise<HttpResponse>;
+/** An answer larger than the request allowed, refused before it was held whole. */
+export declare class TooLarge extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+export declare const fetchTransport: HttpTransport;
+export declare const SLACK_API = "https://slack.com/api";
+/** What one Web API method answered, with the headers that carry the scopes. */
+export interface SlackAnswer {
+    body: Record<string, unknown>;
+    headers: Record<string, string>;
+}
+export interface SlackApiOptions {
+    transport?: HttpTransport;
+    sleep?: (ms: number) => Promise<void>;
+    /** How many times a `429` is waited out before the call fails. */
+    maxRateLimitRetries?: number;
+    /** How long a `429` that names no `Retry-After` is waited out. */
+    defaultRetryAfterSeconds?: number;
+}
+/**
+ * Slack's answer when it waits without saying for how long: the one-a-minute
+ * limit on `conversations.replies` is the one this plugin is likeliest to hit.
+ */
+export declare const DEFAULT_RETRY_AFTER_S = 60;
+export declare const DEFAULT_RATE_LIMIT_RETRIES = 5;
+/**
+ * The Web API, and only the Web API.
+ *
+ * No Socket Mode: Slack hands each event to one of an app's connections, so
+ * a connection opened here would take events from whatever else is connected.
+ */
+export declare class SlackApi {
+    private readonly token;
+    private readonly transport;
+    private readonly sleep;
+    private readonly maxRetries;
+    private readonly defaultRetryAfterS;
+    constructor(token: string, options?: SlackApiOptions);
+    /** Calls a method form-encoded, which every method accepts, and refuses `ok: false`. */
+    call(method: string, args?: Record<string, string | undefined>): Promise<SlackAnswer>;
+    /**
+     * A file's bytes, with the bot token.
+     *
+     * Only ever to Slack's own hosts over https: the URL comes out of a message,
+     * and the token must not follow one anywhere else.
+     */
+    download(url: string, maxBytes?: number): Promise<Uint8Array>;
+    private send;
+}
+//# sourceMappingURL=SlackApi.d.ts.map

package/dist/SlackApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlackApi.d.ts","sourceRoot":"","sources":["../src/SlackApi.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE5E,mFAAmF;AACnF,qBAAa,QAAS,SAAQ,KAAK;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAGnC;AAED,eAAO,MAAM,cAAc,EAAE,aAW5B,CAAC;AAkCF,eAAO,MAAM,SAAS,0BAA0B,CAAC;AAEjD,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;;;;GAKG;AACH,qBAAa,QAAQ;IAOjB,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;gBAGzB,KAAK,EAAE,MAAM,EAC9B,OAAO,GAAE,eAAoB;IAQ/B,wFAAwF;IAClF,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAwB/F;;;;;OAKG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;YAYrD,IAAI;CAUnB"}

package/dist/SlackApi.js

@@ -0,0 +1,143 @@
+/** An answer larger than the request allowed, refused before it was held whole. */
+export class TooLarge extends Error {
+    limit;
+    constructor(limit) {
+        super(`the answer is larger than ${limit} bytes`);
+        this.limit = limit;
+    }
+}
+export const fetchTransport = async (request) => {
+    const response = await fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+    });
+    const headers = {};
+    response.headers.forEach((value, name) => {
+        headers[name.toLowerCase()] = value;
+    });
+    return { status: response.status, headers, body: await readBody(response, request.maxBytes) };
+};
+/**
+ * The body, counted as it arrives: a declared length over the limit is
+ * refused unread, and a missing or wrong one is caught by the count.
+ */
+async function readBody(response, maxBytes) {
+    if (maxBytes === undefined || !response.body)
+        return new Uint8Array(await response.arrayBuffer());
+    if (Number(response.headers.get("content-length") ?? 0) > maxBytes) {
+        await response.body.cancel();
+        throw new TooLarge(maxBytes);
+    }
+    const chunks = [];
+    let total = 0;
+    const reader = response.body.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new TooLarge(maxBytes);
+        }
+        chunks.push(value);
+    }
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+export const SLACK_API = "https://slack.com/api";
+/**
+ * Slack's answer when it waits without saying for how long: the one-a-minute
+ * limit on `conversations.replies` is the one this plugin is likeliest to hit.
+ */
+export const DEFAULT_RETRY_AFTER_S = 60;
+export const DEFAULT_RATE_LIMIT_RETRIES = 5;
+/**
+ * The Web API, and only the Web API.
+ *
+ * No Socket Mode: Slack hands each event to one of an app's connections, so
+ * a connection opened here would take events from whatever else is connected.
+ */
+export class SlackApi {
+    token;
+    transport;
+    sleep;
+    maxRetries;
+    defaultRetryAfterS;
+    constructor(token, options = {}) {
+        this.token = token;
+        this.transport = options.transport ?? fetchTransport;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.maxRetries = options.maxRateLimitRetries ?? DEFAULT_RATE_LIMIT_RETRIES;
+        this.defaultRetryAfterS = options.defaultRetryAfterSeconds ?? DEFAULT_RETRY_AFTER_S;
+    }
+    /** Calls a method form-encoded, which every method accepts, and refuses `ok: false`. */
+    async call(method, args = {}) {
+        const form = new URLSearchParams();
+        for (const [key, value] of Object.entries(args))
+            if (value !== undefined)
+                form.set(key, value);
+        const response = await this.send({
+            url: `${SLACK_API}/${method}`,
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: form.toString(),
+        });
+        if (response.status !== 200)
+            throw new Error(`slack ${method} answered HTTP ${response.status}`);
+        const body = JSON.parse(new TextDecoder().decode(response.body));
+        if (body.ok !== true) {
+            // `missing_scope` carries the scope it wanted, which is the fix.
+            const needed = typeof body.needed === "string" ? ` (needs ${body.needed})` : "";
+            throw new Error(`slack ${method} refused: ${String(body.error ?? "unknown error")}${needed}`);
+        }
+        return { body, headers: response.headers };
+    }
+    /**
+     * A file's bytes, with the bot token.
+     *
+     * Only ever to Slack's own hosts over https: the URL comes out of a message,
+     * and the token must not follow one anywhere else.
+     */
+    async download(url, maxBytes) {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:" || !isSlackHost(parsed.hostname)) {
+            throw new Error(`refusing to send the slack token to ${parsed.origin}`);
+        }
+        const response = await this.send({ url, method: "GET", headers: { Authorization: `Bearer ${this.token}` }, maxBytes });
+        if (response.status !== 200)
+            throw new Error(`slack file ${parsed.pathname} answered HTTP ${response.status}`);
+        // Checked again here for a transport that does not honour the limit.
+        if (maxBytes !== undefined && response.body.byteLength > maxBytes)
+            throw new TooLarge(maxBytes);
+        return response.body;
+    }
+    async send(request) {
+        for (let attempt = 0;; attempt++) {
+            const response = await this.transport(request);
+            if (response.status !== 429)
+                return response;
+            if (attempt >= this.maxRetries) {
+                throw new Error(`slack kept rate limiting ${request.url} after ${attempt + 1} tries`);
+            }
+            await this.sleep(retryAfterMs(response.headers["retry-after"], this.defaultRetryAfterS));
+        }
+    }
+}
+function retryAfterMs(header, fallbackS) {
+    const seconds = header?.trim() ? Number(header) : Number.NaN;
+    return (Number.isFinite(seconds) && seconds >= 0 ? seconds : fallbackS) * 1000;
+}
+function isSlackHost(hostname) {
+    return hostname === "slack.com" || hostname.endsWith(".slack.com");
+}
+//# sourceMappingURL=SlackApi.js.map

package/dist/SlackApi.js.map

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

package/dist/SlackConversation.d.ts

@@ -0,0 +1,111 @@
+import { Conversation, Reply, ThreadRef } from "@amykit/core";
+import { SlackApi } from "./SlackApi.js";
+export interface SlackConversationOptions {
+    /** A channel id, not a name. */
+    channel: string;
+    /** The only user whose replies are answers. */
+    operator: string;
+    /** Where the thread map and downloaded files live. */
+    directory: string;
+    /** How long to wait for another process opening a thread. */
+    lockWaitMs?: number;
+    /** How long a claim on a thread holds without being renewed. */
+    leaseMs?: number;
+    /** The largest attachment downloaded; a larger one is named in the reply instead. */
+    maxFileBytes?: number;
+    /**
+     * Days a downloaded file or a thread's memory stays unused before it is
+     * pruned; `0` keeps everything.
+     */
+    retentionDays?: number;
+    now?: () => Date;
+}
+/** What `amy doctor` prints for this plugin, one line per question. */
+export interface SlackCheck {
+    label: string;
+    ok: boolean;
+    detail?: string;
+}
+/** Long enough for an operator's holiday, short enough that screenshots do not pile up. */
+export declare const DEFAULT_RETENTION_DAYS = 30;
+export declare class SlackConversation implements Conversation {
+    private readonly api;
+    private readonly options;
+    private readonly threads;
+    private readonly filesDirectory;
+    private readonly opening;
+    private botUser?;
+    private prunedAt;
+    constructor(api: SlackApi, options: SlackConversationOptions);
+    open(workId: string, title: string): Promise<ThreadRef>;
+    post(thread: ThreadRef, message: {
+        text: string;
+        files?: string[];
+    }): Promise<string>;
+    replies(thread: ThreadRef, since: string): Promise<Reply[]>;
+    /**
+     * Whether the token can do what this plugin does, asked of Slack itself.
+     *
+     * `auth.test` for the token, its `x-oauth-scopes` header for the scopes,
+     * and `conversations.info` for whether the channel is one the bot can see
+     * — which also says whether the history scope it needs is the public or
+     * the private one.
+     */
+    checks(): Promise<SlackCheck[]>;
+    /**
+     * Forgets one piece of work: its thread's memory and every file downloaded
+     * from it. The thread stays in Slack; the next `open` starts a new one.
+     */
+    forget(workId: string): void;
+    /**
+     * Removes what nobody used within the retention: a downloaded file, which
+     * the next read of its reply fetches again, and a thread's memory, whose
+     * files go with it. Returns how many of each went.
+     */
+    prune(now?: Date): {
+        threads: number;
+        files: number;
+    };
+    private clock;
+    /** Where one thread's downloads live, so forgetting it takes them too. */
+    private threadFiles;
+    /** Beside the thread's files, not in them, so removing those leaves it. */
+    private forgottenMarker;
+    /**
+     * Marks the thread forgotten, then removes its files. The marker is what a
+     * download still in flight — in this process or another — reads after it
+     * publishes, so it cannot bring a forgotten thread's file back.
+     */
+    private dropFiles;
+    /** Throttled, and never the reason a call fails: pruning is housekeeping. */
+    private pruneNowAndThen;
+    private channelChecks;
+    /**
+     * Exactly one process posts a root per attempt; an attempt that follows
+     * one that may have reached Slack looks for that root before posting.
+     */
+    private startThread;
+    /**
+     * The root this bot posted for this work since `since`, if Slack took one.
+     *
+     * Matched by the work id carried in the root's metadata, never by its
+     * text: two items can share a title, and a title can change.
+     */
+    private findRoot;
+    /** Every message in the thread after `afterMicros`, across pages. */
+    private threadMessages;
+    private pages;
+    /** By author id, never by a marker in the text. */
+    private isOperatorAnswer;
+    /** Cached once known; a failure is not, so the next poll asks again. */
+    private botUserId;
+    /**
+     * The attachments as local paths, and a line naming each one too large to
+     * fetch — declared so by Slack, or found so while it arrived — so the
+     * reader knows a file was there rather than never seeing it.
+     */
+    private downloadAll;
+    /** The file's local path, or nothing when its thread was forgotten. */
+    private download;
+}
+//# sourceMappingURL=SlackConversation.d.ts.map

package/dist/SlackConversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlackConversation.d.ts","sourceRoot":"","sources":["../src/SlackConversation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAY,MAAM,eAAe,CAAC;AAGnD,MAAM,WAAW,wBAAwB;IACvC,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAgCD,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAUzC,qBAAa,iBAAkB,YAAW,YAAY;IAQlD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,QAAQ,CAA4B;gBAGzB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,wBAAwB;IAapD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAoBjD,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBrF,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAyBjE;;;;;;;OAOG;IACG,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAWrC;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;OAIG;IACH,KAAK,CAAC,GAAG,GAAE,IAAmB,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAanE,OAAO,CAAC,KAAK;IAIb,0EAA0E;IAC1E,OAAO,CAAC,WAAW;IAInB,2EAA2E;IAC3E,OAAO,CAAC,eAAe;IAIvB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAMjB,6EAA6E;IAC7E,OAAO,CAAC,eAAe;YAWT,aAAa;IAgC3B;;;OAGG;YACW,WAAW;IAmBzB;;;;;OAKG;YACW,QAAQ;IAetB,qEAAqE;IACrE,OAAO,CAAC,cAAc;YAIR,KAAK;IAYnB,mDAAmD;IACnD,OAAO,CAAC,gBAAgB;IAOxB,wEAAwE;IACxE,OAAO,CAAC,SAAS;IAWjB;;;;OAIG;YACW,WAAW;IAwBzB,uEAAuE;YACzD,QAAQ;CAqBvB"}