@evandu/super-pi 0.1.132 → 0.1.135

package/dist/server/feishu-config.d.ts

@@ -0,0 +1,68 @@
+import type { FeishuDomain } from "./feishu.js";
+/**
+ * THE FEISHU CREDENTIALS, and where they live.
+ *
+ * WHY A FILE IN THE DATA DIRECTORY AND NOT A FIELD IN THE APP STATE. The App State is broadcast to
+ * every browser that connects, and it is written to disk in a form that is meant to be readable.
+ * A secret does not belong there - the same rule the provider registry follows, where the API key
+ * lives in `<dataDir>/providers.json` with restrictive permissions and the browser is told only
+ * that a key exists.
+ *
+ * WHY THE ENVIRONMENT OVERRIDES THE FILE. A deployment that provisions the credential through the
+ * environment should not have to write a file as well, and the environment is the harder thing to
+ * override accidentally. The file is the fallback, not the other way round.
+ *
+ * WHY THERE IS ONE SET OF CREDENTIALS FOR THE WHOLE SERVER. Feishu credentials belong to an
+ * application inside one enterprise, and Super Pi runs on one person's machine. A per-workspace
+ * credential would be a second enterprise's application, and the user of that workspace would have
+ * to be handed a secret they never asked for.
+ */
+export type FeishuConfig = {
+    /** The application's App ID. */
+    appId?: string;
+    /** The application's App Secret. Never leaves the server. */
+    appSecret?: string;
+    /** Which Feishu the calls go to. */
+    domain?: FeishuDomain;
+};
+/** Where the credentials come from, for the panel to show. */
+export type FeishuConfigSource = "environment" | "file" | "none";
+export declare class FeishuConfigStore {
+    private readonly file;
+    constructor(file: string);
+    /**
+     * The credentials in force, and where they came from.
+     *
+     * The environment wins over the file, and the file is read only when the environment has not
+     * said anything - so a machine that provisions the credential through the environment never
+     * touches the file at all.
+     */
+    read(): Promise<{
+        config: FeishuConfig;
+        source: FeishuConfigSource;
+    }>;
+    /**
+     * The file's own contents, and only its own contents.
+     *
+     * A file that cannot be read is a file that is not there, and a file that cannot be parsed is a
+     * file this server did not write. Both are reported rather than thrown: a broken credential
+     * file must not stop the server from starting.
+     */
+    private readFile;
+    /**
+     * Writes the credentials.
+     *
+     * The write is atomic (a temporary file and a rename) so a crash cannot leave half a JSON file
+     * behind, and the file's mode is 0600 so that a secret is not readable by every account on the
+     * machine. On Windows the mode is not enforced the same way, and there is nothing this code can
+     * do about that.
+     */
+    write(config: FeishuConfig): Promise<void>;
+}
+/**
+ * The domain a name means, defaulting to Feishu.
+ *
+ * A name this does not recognise is Feishu rather than an error: the domain is a convenience for
+ * Lark users, and refusing to start over a typo in it would be worse than trying Feishu.
+ */
+export declare function domainOf(value: string | undefined): FeishuDomain;

package/dist/server/feishu-config.js

@@ -0,0 +1,84 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+export class FeishuConfigStore {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    /**
+     * The credentials in force, and where they came from.
+     *
+     * The environment wins over the file, and the file is read only when the environment has not
+     * said anything - so a machine that provisions the credential through the environment never
+     * touches the file at all.
+     */
+    async read() {
+        const fromEnv = {
+            ...(process.env.SUPER_PI_FEISHU_APP_ID ? { appId: process.env.SUPER_PI_FEISHU_APP_ID.trim() } : {}),
+            ...(process.env.SUPER_PI_FEISHU_APP_SECRET ? { appSecret: process.env.SUPER_PI_FEISHU_APP_SECRET.trim() } : {}),
+            ...(process.env.SUPER_PI_FEISHU_DOMAIN ? { domain: domainOf(process.env.SUPER_PI_FEISHU_DOMAIN) } : {}),
+        };
+        if (fromEnv.appId && fromEnv.appSecret)
+            return { config: fromEnv, source: "environment" };
+        const stored = await this.readFile();
+        if (fromEnv.appId || fromEnv.appSecret)
+            return { config: { ...stored, ...fromEnv }, source: "environment" };
+        return { config: stored, source: stored.appId && stored.appSecret ? "file" : "none" };
+    }
+    /**
+     * The file's own contents, and only its own contents.
+     *
+     * A file that cannot be read is a file that is not there, and a file that cannot be parsed is a
+     * file this server did not write. Both are reported rather than thrown: a broken credential
+     * file must not stop the server from starting.
+     */
+    async readFile() {
+        try {
+            const raw = await readFile(this.file, "utf8");
+            const parsed = JSON.parse(raw);
+            return {
+                ...(typeof parsed.appId === "string" ? { appId: parsed.appId } : {}),
+                ...(typeof parsed.appSecret === "string" ? { appSecret: parsed.appSecret } : {}),
+                ...(parsed.domain ? { domain: domainOf(parsed.domain) } : {}),
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Writes the credentials.
+     *
+     * The write is atomic (a temporary file and a rename) so a crash cannot leave half a JSON file
+     * behind, and the file's mode is 0600 so that a secret is not readable by every account on the
+     * machine. On Windows the mode is not enforced the same way, and there is nothing this code can
+     * do about that.
+     */
+    async write(config) {
+        await mkdir(dirname(this.file), { recursive: true });
+        const temporary = `${this.file}.${randomUUID()}.tmp`;
+        const value = {
+            ...(config.appId ? { appId: config.appId } : {}),
+            ...(config.appSecret ? { appSecret: config.appSecret } : {}),
+            ...(config.domain ? { domain: config.domain } : {}),
+        };
+        try {
+            await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+            await rename(temporary, this.file);
+        }
+        catch (error) {
+            await writeFile(temporary, "{}", { mode: 0o600 }).catch(() => undefined);
+            throw error;
+        }
+    }
+}
+/**
+ * The domain a name means, defaulting to Feishu.
+ *
+ * A name this does not recognise is Feishu rather than an error: the domain is a convenience for
+ * Lark users, and refusing to start over a typo in it would be worse than trying Feishu.
+ */
+export function domainOf(value) {
+    return String(value ?? "").trim().toLowerCase() === "lark" ? "lark" : "feishu";
+}

package/dist/server/feishu.d.ts

@@ -0,0 +1,187 @@
+/**
+ * THE FEISHU CLIENT: everything Super Pi knows how to do with a cloud document on Feishu.
+ *
+ * WHY THIS LAYER EXISTS AT ALL. Feishu's document API is not "read a file" and "write a file". A
+ * document is a TREE OF BLOCKS, the API refuses to create a document with content in it, and the
+ * official way to put Markdown into a document is a three-step dance (convert to blocks, then
+ * insert them as nested blocks under the page block). An agent that had to know that would be
+ * writing protocol details into every prompt. So the protocol lives here, once, and what is left
+ * above it is "read this document" and "write this document".
+ *
+ * WHY AN HTTP CLIENT AND NOT THE OFFICIAL SDK. The official SDK (`@larksuiteoapi/node-sdk`) is a
+ * good library, but it is a dependency of the PACKAGE, and this package's whole point is that it
+ * installs and runs. Every call it makes is a plain HTTP call with a bearer token, so the four
+ * endpoints this feature needs are four functions - and the credential handling (a token that
+ * expires, a token that has to be refreshed, a rate limit that has to be waited out) is the part
+ * that is worth writing carefully and testing on its own.
+ *
+ * WHAT THE IDENTITY IS. Everything here runs as the APPLICATION (`tenant_access_token`), never as
+ * a person. That is the identity that needs no OAuth dance and no browser, and it is also the
+ * identity that can only touch the documents the application has been made a collaborator on.
+ * See `docs/FEISHU.md` for the setup that implies, because it is the one thing a user must do
+ * before any of this works.
+ */
+/** The tool that reads a Feishu document. */
+export declare const FEISHU_READ_TOOL_NAME = "feishu_doc_read";
+/** The tool that writes a Feishu document. */
+export declare const FEISHU_WRITE_TOOL_NAME = "feishu_doc_write";
+/** Which flavour of Feishu we talk to. The API paths differ, the shapes do not. */
+export type FeishuDomain = "feishu" | "lark";
+/** A block in a Feishu document. Only the fields this code reads are named. */
+export type FeishuBlock = {
+    block_id: string;
+    parent_id?: string;
+    children?: string[];
+    block_type: number;
+    [key: string]: unknown;
+};
+/**
+ * A REFUSAL FROM FEISHU, with the code kept alongside the message.
+ *
+ * The code is kept because the message Feishu sends is written for a developer reading a log,
+ * and the part a person needs - "add this application as a collaborator", "open this permission
+ * point" - is not in it.
+ */
+export declare class FeishuError extends Error {
+    readonly code: number;
+    readonly hint?: string | undefined;
+    constructor(code: number, message: string, hint?: string | undefined);
+}
+/**
+ * The message a refusal is shown with: what Feishu said, and what to do about it.
+ */
+export declare function describeFeishuError(code: number, message: string): string;
+/**
+ * WHAT A URL OR A TOKEN NAMES.
+ *
+ * `kind` is "docx" for a document and "wiki" for a knowledge-base node. The distinction is not
+ * cosmetic: a wiki URL's token is NOT the document id, and passing it as one produces a document
+ * that does not exist. A wiki link has to be resolved through the wiki API first.
+ */
+export type FeishuTarget = {
+    kind: "docx" | "wiki";
+    token: string;
+    /** The tenant host the link came from, when it came from a link. Used to build a URL for a new document. */
+    host?: string;
+};
+/**
+ * Reads a document reference: a full URL, or a bare token.
+ *
+ * WHY BARE TOKENS ARE ACCEPTED. A person reading a document's URL sees the token in it, and an
+ * agent that has been handed `doxcn...` should not have to be told to wrap it in a URL first.
+ */
+export declare function parseFeishuTarget(input: string): FeishuTarget;
+/**
+ * Renders a document's blocks as Markdown.
+ *
+ * WHY MARKDOWN AND NOT THE RAW TEXT. `raw_content` gives the words without the shape: a heading
+ * arrives as a heading's text, a list arrives as separate lines, and a reader cannot tell them
+ * apart. The block tree is the document, and Markdown is the closest plain-text shape this side of
+ * the product already understands.
+ */
+export declare function blocksToMarkdown(blocks: FeishuBlock[]): string;
+/** The client the service drives. Every call goes through here. */
+export type FeishuClientOptions = {
+    appId: string;
+    appSecret: string;
+    domain?: FeishuDomain;
+    /** Injected in tests, so the suite never touches the network. */
+    fetchImpl?: typeof fetch;
+};
+export declare class FeishuClient {
+    private readonly options;
+    private token?;
+    /** Whether the newer OAuth token endpoint works for this application. */
+    private useLegacyAuth;
+    /** The write queue. One write at a time, spaced by the interval the API allows. */
+    private writeChain;
+    private lastWriteAt;
+    constructor(options: FeishuClientOptions);
+    private get apiBase();
+    private get accountsBase();
+    private get fetchImpl();
+    /**
+     * THE ACCESS TOKEN, fetched once and reused.
+     *
+     * The lifetime is two hours and the API says to believe the number it returns rather than a
+     * hardcoded one, so the expiry comes from the response and the token is renewed a couple of
+     * minutes before it runs out.
+     */
+    accessToken(force?: boolean): Promise<string>;
+    /**
+     * The current OAuth endpoint: `POST https://accounts.feishu.cn/oauth/v3/token`.
+     *
+     * It is the one the documentation recommends. If it refuses - an older application, a tenant
+     * that has not been migrated - the legacy endpoint is tried instead, and the client remembers
+     * so the failing call is not made again on every token refresh.
+     */
+    private fetchOAuthToken;
+    /**
+     * The historical endpoint: `POST /open-apis/auth/v3/tenant_access_token/internal`.
+     *
+     * It is documented as superseded, but it is the endpoint every 自建应用 has worked with for
+     * years, and a fallback that costs one request is cheaper than a feature that does not run.
+     */
+    private fetchLegacyToken;
+    /**
+     * ONE CALL, with the bearer token attached.
+     *
+     * A 429 is waited out rather than reported: the API tells us how many seconds until the window
+     * resets, and a write that gives up because it was 200ms early is a write that did not happen.
+     */
+    private request;
+    /**
+     * Runs one write, spaced from the last one.
+     */
+    private withWriteSlot;
+    /** The basic information about a document: its title and its version. */
+    documentMeta(documentId: string): Promise<{
+        documentId: string;
+        title?: string;
+        revisionId?: number;
+    }>;
+    /** Every block of a document, across every page. */
+    documentBlocks(documentId: string): Promise<FeishuBlock[]>;
+    /** The plain text of a document, without any structure. */
+    rawContent(documentId: string): Promise<string>;
+    /** The blocks directly under the page block - the document's top level. */
+    rootChildren(documentId: string): Promise<string[]>;
+    /** Creates an empty document. The content goes in afterwards, because the API has no other way. */
+    createDocument(title: string, folderToken?: string): Promise<{
+        documentId: string;
+        revisionId?: number;
+    }>;
+    /** Resolves a knowledge-base node to the document behind it. */
+    wikiNode(token: string): Promise<{
+        objToken: string;
+        objType: string;
+        title?: string;
+    }>;
+    /**
+     * Turns Markdown into the blocks that represent it.
+     *
+     * The API will not create a document with content in it, and building the blocks by hand would
+     * mean reimplementing the conversion Feishu already does - tables, code fences, todos and all.
+     */
+    convertMarkdown(markdown: string): Promise<{
+        blocks: FeishuBlock[];
+        firstLevelBlockIds: string[];
+    }>;
+    /**
+     * Inserts blocks under the page block.
+     *
+     * THE CHUNKING IS NOT AN OPTIMISATION. The API accepts at most 1000 blocks per call, and the
+     * blocks of one subtree cannot be split across calls - so the top-level blocks are packed into
+     * batches that each fit, and a document of any length goes in.
+     */
+    insertBlocks(documentId: string, blocks: FeishuBlock[], firstLevelBlockIds: string[], index?: number): Promise<number | undefined>;
+    /** Deletes a range of the page block's children. The range is left-closed and right-open. */
+    deleteChildren(documentId: string, startIndex: number, endIndex: number): Promise<number | undefined>;
+}
+/**
+ * Removes the read-only merge information from a table block.
+ *
+ * The API rejects a table block that carries `merge_info`, and the conversion endpoint hands it
+ * back with that field on it. The documentation says to strip it, so it is stripped.
+ */
+export declare function stripTableMergeInfo(block: FeishuBlock): FeishuBlock;