@evandu/super-pi 0.1.151 → 0.1.153

package/dist/server/feishu-config.js

@@ -1,84 +0,0 @@
-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

@@ -1,187 +0,0 @@
-/**
- * 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;