@excitedjs/feishu-transport 0.0.1

package/dist/render/render.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Render a Markdown source into one or more Feishu v2 interactive cards.
+ *
+ * Feishu's `tag: markdown` body element accepts only the "lark_md" subset —
+ * bold, italic, strikethrough, inline code, fenced code, links, and (on
+ * Feishu 7.6+) lists. It does NOT support headings or GFM tables: a `#` is
+ * shown as a literal `#`, and `| a | b |` is shown as the source pipes.
+ * Routing every block through `tag: markdown` therefore leaks raw markup into
+ * the rendered card whenever the body has a heading or a table.
+ *
+ * This module parses the source into block tokens (via `marked.lexer`) and
+ * routes each block to the v2 card component that actually renders it:
+ *
+ *   - The first `# h1` becomes the card's `header.title` plain-text slot.
+ *     A later `# h1`, and every `##`/`###`/... heading, becomes a body
+ *     element wrapping the flattened heading text in `**...**` so lark_md
+ *     renders it as visible bold.
+ *   - A GFM `| ... |` table becomes a dedicated `tag: table` element with
+ *     the header alignment markers mapped to each column's
+ *     `horizontal_align`. Cells that contain inline markup flip the
+ *     column's `data_type` from `text` to `lark_md`. A cell over
+ *     `CELL_MAX_BYTES` is a render-time error — splitting one row's cell
+ *     across multiple rows would break alignment, and silently truncating
+ *     hides the data the caller asked to deliver.
+ *   - A horizontal rule (`---`) becomes a `tag: hr` element.
+ *   - Every other block — paragraphs, lists, blockquotes, fenced code —
+ *     is emitted as a `tag: markdown` element with the block's raw source,
+ *     since lark_md renders those natively.
+ *
+ * Elements are then packed greedily into cards by a dual budget: Feishu's
+ * ~30 KB request body cap AND the v2 card per-card element-count cap.
+ * Only the first card carries the header — splitting the body produces
+ * follow-up cards with no header, the way a long thread reads. A markdown
+ * element body too large for one card is split with `splitMarkdownByBytes`,
+ * which counts UTF-8 bytes (so a CJK-heavy body is not budgeted as if it
+ * were ASCII) and respects grapheme cluster boundaries (so a ZWJ emoji
+ * does not get cut in half).
+ *
+ * `renderMarkdownToCards` validates every produced card against both
+ * budgets before returning; if any card would still exceed them despite
+ * splitting, it throws. Callers therefore know that the array they get
+ * back is wire-ready — there is no path where the renderer hands the
+ * sender a card Feishu would reject. This is the structural half of the
+ * "atomic" semantic the channel offers; the network half (every send
+ * succeeds or all sends fail) cannot be guaranteed on Feishu's IM API,
+ * which has no message-batch transaction.
+ *
+ * The result is `RenderedCard[]`. `cardToContent(card)` turns one card into
+ * the JSON string the `im.message.create` `content` field expects.
+ *
+ * The 9-row × 9-column limit in `markdown-ref.md` belongs to a different
+ * surface (the docs-create pipeline that turns markdown into Feishu document
+ * blocks); v2 card tables accept up to 50 columns, paginate rows in-card via
+ * `page_size`, and have no per-table row cap of their own. This renderer
+ * therefore column-splits at 50 (with the first column preserved on each
+ * split half as the identifier) and never row-splits when row-splitting
+ * would not actually reduce a card's size.
+ */
+/** A v2 card's header field — only the plain-text title slot is populated. */
+interface CardHeader {
+    title: {
+        tag: 'plain_text';
+        content: string;
+    };
+}
+/** Body element rendering a chunk of lark_md text. */
+interface MarkdownElement {
+    tag: 'markdown';
+    content: string;
+}
+/** Body element rendering a horizontal rule. */
+interface HrElement {
+    tag: 'hr';
+}
+/** Per-cell horizontal alignment, matched to GFM's `:---`, `:---:`, `---:`. */
+type CellAlign = 'left' | 'center' | 'right';
+/** One column of a `tag: table` element. */
+interface TableColumn {
+    /** Key the row records use to look up the cell value. */
+    name: string;
+    /** Header label shown to the reader. */
+    display_name: string;
+    /**
+     * `text` for plain cells; `lark_md` when any cell in this column carries
+     * inline markup. Per the API, `data_type` is column-scoped, not cell-scoped.
+     */
+    data_type: 'text' | 'lark_md';
+    /** Cell alignment, derived from the GFM header separator row. */
+    horizontal_align?: CellAlign;
+}
+/** Body element rendering a GFM table. */
+interface TableElement {
+    tag: 'table';
+    page_size: number;
+    row_height: 'low';
+    header_style: {
+        bold: true;
+        background_style: 'grey';
+    };
+    columns: TableColumn[];
+    rows: Array<Record<string, string>>;
+}
+/** Any body element this renderer emits. */
+type CardElement = MarkdownElement | HrElement | TableElement;
+/** One v2 interactive card, ready to JSON-serialise into `content`. */
+export interface RenderedCard {
+    schema: '2.0';
+    config: {
+        update_multi: true;
+    };
+    header?: CardHeader;
+    body: {
+        elements: CardElement[];
+    };
+}
+/**
+ * Feishu's documented hard limit for a card request body. Past this the API
+ * rejects the call outright; the packer keeps each card's serialised content
+ * below `CARD_CONTENT_SAFE_BYTES` so HTTP headers and the request envelope
+ * still fit underneath the hard cap.
+ */
+export declare const FEISHU_CARD_REQUEST_LIMIT_BYTES: number;
+/**
+ * v2 card per-card element-count cap. Observed in PR #73 review: a card with
+ * 250 short markdown elements is rejected by Feishu, though the JSON itself
+ * is well under the byte cap. The exact upper bound is not in the open
+ * docs; the reviewer-cited 200 figure is treated as the hard limit and a
+ * lower number is used as the safe budget so a card on the boundary does
+ * not silently fail under server-side counting differences.
+ */
+export declare const FEISHU_CARD_ELEMENT_HARD_CAP = 200;
+/**
+ * Per-cell byte cap. A cell larger than this is rejected at render time:
+ * splitting one row's cell across multiple rows breaks alignment with the
+ * other columns, and silently truncating drops the data the caller asked
+ * to deliver. The author is expected to move the oversized content into a
+ * paragraph or fenced code block, where the byte-aware splitter handles
+ * arbitrary sizes.
+ *
+ * 4 KB is comfortably above any reasonable cell value (a long sentence is
+ * ~200 bytes) while small enough that a 50-column table of full-budget
+ * cells still leaves room for the card envelope inside the byte cap.
+ */
+export declare const CELL_MAX_BYTES: number;
+/**
+ * Render a Markdown source into one or more v2 cards.
+ *
+ * The output is always non-empty: an empty source produces one card with a
+ * single empty `tag: markdown` element, so the caller always has something
+ * to send. Splitting happens automatically when the serialised card would
+ * exceed Feishu's 30 KB request cap, when the body would exceed the
+ * 200-element cap, or when a table has more than 50 columns.
+ *
+ * Throws when a single block cannot be made to fit even after splitting —
+ * for example a table whose row, after every cell has been validated under
+ * `CELL_MAX_BYTES`, still serialises above the per-card byte cap. The
+ * caller therefore sees a render-time error before any send is attempted,
+ * instead of the channel posting some cards and then failing on a later
+ * one (partial visible state).
+ */
+export declare function renderMarkdownToCards(text: string): RenderedCard[];
+/**
+ * Serialise one card into the JSON string Feishu's `im.message.create`
+ * `content` field expects. Pure: no side effects, no I/O.
+ */
+export declare function cardToContent(card: RenderedCard): string;
+/** Byte length of `card`'s serialised content, in UTF-8. */
+export declare function cardContentBytes(card: RenderedCard): number;
+/**
+ * Split a Markdown block's source into pieces whose UTF-8 byte length each
+ * stays at or under `byteBudget`. The input is one block's `raw` field from
+ * `marked.lexer`, so the block kind drives the split strategy:
+ *
+ *   - A fenced code block (opens with ``` or ~~~ and closes with the same
+ *     run) is split by line and the open / close lines are repeated on
+ *     every piece, so each piece is itself a well-formed fenced block.
+ *   - Any other block is split at line boundaries; a single line longer
+ *     than the budget is split by grapheme cluster, so a ZWJ-bound emoji
+ *     cluster or a Hangul syllable is not cut in half.
+ *
+ * Every returned piece is non-empty and fits the budget — the caller can
+ * use them directly as `tag: markdown` element bodies.
+ */
+export declare function splitMarkdownByBytes(text: string, byteBudget: number): string[];
+export {};
+//# sourceMappingURL=render.d.ts.map

package/dist/render/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/render/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAIH,8EAA8E;AAC9E,UAAU,UAAU;IAClB,KAAK,EAAE;QAAE,GAAG,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9C;AAED,sDAAsD;AACtD,UAAU,eAAe;IACvB,GAAG,EAAE,UAAU,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,gDAAgD;AAChD,UAAU,SAAS;IACjB,GAAG,EAAE,IAAI,CAAA;CACV;AAED,+EAA+E;AAC/E,KAAK,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE5C,4CAA4C;AAC5C,UAAU,WAAW;IACnB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAA;IACZ,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,SAAS,CAAA;CAC7B;AAED,0CAA0C;AAC1C,UAAU,YAAY;IACpB,GAAG,EAAE,OAAO,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,KAAK,CAAA;IACjB,YAAY,EAAE;QACZ,IAAI,EAAE,IAAI,CAAA;QACV,gBAAgB,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACpC;AAED,4CAA4C;AAC5C,KAAK,WAAW,GAAG,eAAe,GAAG,SAAS,GAAG,YAAY,CAAA;AAE7D,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,KAAK,CAAA;IACb,MAAM,EAAE;QAAE,YAAY,EAAE,IAAI,CAAA;KAAE,CAAA;IAC9B,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,IAAI,EAAE;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAA;KAAE,CAAA;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,QAAY,CAAA;AAGxD;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAa/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,QAAW,CAAA;AA4BtC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CA2BlE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAExD;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE3D;AA0WD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAc/E"}