@krischoichoi/channel-lark 0.6.0

package/lib/auth/device-authorization.js

@@ -0,0 +1,169 @@
+import { ControlError, } from '@krischoichoi/channel-control';
+import { z } from 'zod';
+const deviceAuthorizationResponseSchema = z
+    .object({
+    device_code: z.string().trim().min(1).optional(),
+    verification_uri_complete: z.string().trim().min(1).optional(),
+    verification_uri: z.string().trim().min(1).optional(),
+    expires_in: z.number().positive().optional(),
+    interval: z.number().positive().optional(),
+    error: z.string().trim().min(1).optional(),
+    error_description: z.string().trim().min(1).optional(),
+})
+    .passthrough();
+const tokenResponseSchema = z
+    .object({
+    access_token: z.string().trim().min(1).optional(),
+    refresh_token: z.string().trim().min(1).optional(),
+    error: z.string().trim().min(1).optional(),
+    error_description: z.string().trim().min(1).optional(),
+    code: z.union([z.string(), z.number()]).optional(),
+    msg: z.string().trim().min(1).optional(),
+})
+    .passthrough();
+const providerStateSchema = z.object({
+    brand: z.enum(['feishu', 'lark']),
+    appId: z.string().trim().min(1),
+    appSecret: z.string().trim().min(1),
+    deviceCode: z.string().trim().min(1),
+    scope: z.string().trim().min(1),
+});
+function authError(message, cause) {
+    return new ControlError('CONTROL_ERROR', message, cause === undefined ? undefined : { cause });
+}
+function endpoint(domain, resource) {
+    return domain === 'lark'
+        ? `https://accounts.larksuite.com/oauth/v1/${resource}`
+        : `https://accounts.feishu.cn/oauth/v1/${resource}`;
+}
+function tokenEndpoints(brand) {
+    return brand === 'lark'
+        ? [
+            'https://accounts.larksuite.com/oauth/v1/token',
+            'https://open.larksuite.com/open-apis/authen/v2/oauth/token',
+        ]
+        : [
+            'https://accounts.feishu.cn/oauth/v1/token',
+            'https://open.feishu.cn/open-apis/authen/v2/oauth/token',
+        ];
+}
+async function readJson(response, provider) {
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        throw authError(`${provider} authorization returned invalid JSON`, error);
+    }
+}
+function parseDeviceResponse(value) {
+    const parsed = deviceAuthorizationResponseSchema.safeParse(value);
+    if (!parsed.success)
+        throw authError('lark device authorization returned an invalid response', parsed.error);
+    return parsed.data;
+}
+function parseTokenResponse(value) {
+    const parsed = tokenResponseSchema.safeParse(value);
+    if (!parsed.success)
+        throw authError('lark authorization polling returned an invalid response', parsed.error);
+    return parsed.data;
+}
+function parseProviderState(value) {
+    const parsed = providerStateSchema.safeParse(value);
+    if (!parsed.success)
+        throw authError('lark auth session is missing provider state', parsed.error);
+    return parsed.data;
+}
+/** Begin Feishu/Lark device authorization. Secrets remain in opaque host state. */
+export async function beginLarkDeviceAuthorization(options) {
+    const appId = options.appId.trim();
+    const appSecret = options.appSecret.trim();
+    if (!appId || !appSecret)
+        throw new ControlError('AUTH_NOT_READY', 'lark QR authorization requires configured appId and appSecret');
+    const fetcher = options.fetcher ?? fetch;
+    const brand = options.domain === 'lark' ? 'lark' : 'feishu';
+    const scope = 'offline_access';
+    let response;
+    try {
+        response = await fetcher(endpoint(options.domain, 'device_authorization'), {
+            method: 'POST',
+            headers: {
+                authorization: `Basic ${Buffer.from(`${appId}:${appSecret}`).toString('base64')}`,
+                'content-type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({ client_id: appId, scope }).toString(),
+        });
+    }
+    catch (error) {
+        throw authError('lark device authorization request failed', error);
+    }
+    const payload = parseDeviceResponse(await readJson(response, 'lark'));
+    if (!response.ok || payload.error)
+        throw authError('lark device authorization request failed');
+    const deviceCode = payload.device_code;
+    const completeUrl = payload.verification_uri_complete ?? payload.verification_uri;
+    if (!deviceCode || !completeUrl)
+        throw authError('lark did not return a device authorization challenge');
+    const expiresAt = Date.now() + (payload.expires_in ?? 240) * 1000;
+    const providerState = { brand, appId, appSecret, deviceCode, scope };
+    return {
+        provider: 'lark-device-authorization',
+        expiresAt,
+        pollingIntervalMs: Math.max(3000, (payload.interval ?? 5) * 1000),
+        qr: { kind: 'content', value: completeUrl, expiresAt },
+        prompt: { kind: 'confirm-on-phone', message: '请使用飞书/Lark 扫码并确认授权' },
+        deviceCode,
+        providerState,
+    };
+}
+/** Poll a device authorization session without exposing provider tokens. */
+export async function pollLarkDeviceAuthorization(session, options = {}) {
+    const provider = parseProviderState(session.providerState);
+    const fetcher = options.fetcher ?? fetch;
+    const attempts = [
+        { grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: provider.deviceCode, client_id: provider.appId },
+        { grant_type: 'device_code', device_code: provider.deviceCode, client_id: provider.appId },
+        { grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: provider.deviceCode },
+        { grant_type: 'device_code', device_code: provider.deviceCode },
+    ];
+    let lastError;
+    for (const tokenUrl of tokenEndpoints(provider.brand)) {
+        for (const attempt of attempts) {
+            let response;
+            try {
+                response = await fetcher(tokenUrl, {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Basic ${Buffer.from(`${provider.appId}:${provider.appSecret}`).toString('base64')}`,
+                        'content-type': 'application/x-www-form-urlencoded',
+                    },
+                    body: new URLSearchParams(attempt).toString(),
+                });
+            }
+            catch (error) {
+                lastError = error;
+                continue;
+            }
+            let payload;
+            try {
+                payload = parseTokenResponse(await readJson(response, 'lark'));
+            }
+            catch (error) {
+                lastError = error;
+                continue;
+            }
+            if (response.ok && (payload.access_token || payload.refresh_token)) {
+                return { state: 'authenticated', phase: 'authorized', expiresAt: session.expiresAt, detail: '飞书/Lark 扫码授权已完成' };
+            }
+            const code = payload.error ?? (payload.code === undefined ? '' : String(payload.code));
+            if (code === 'authorization_pending' || code === 'slow_down') {
+                return { state: 'pending', phase: 'waiting-scan', expiresAt: session.expiresAt, detail: '等待飞书/Lark 扫码授权中' };
+            }
+            if (code === 'expired_token' || code === 'invalid_grant' || response.status === 401) {
+                return { state: 'expired', phase: 'expired', expiresAt: session.expiresAt, detail: '二维码已失效，请重新生成' };
+            }
+            lastError = new Error(payload.error_description ?? payload.msg ?? `HTTP ${response.status}`);
+        }
+    }
+    throw authError('lark authorization polling failed', lastError);
+}
+//# sourceMappingURL=device-authorization.js.map

package/lib/auth/device-authorization.js.map

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

package/lib/card.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Lark CardKit 2.0 native streaming reply — the streaming reply
+ * (`ReplyHandle`).
+ *
+ * Lark streaming rides the OFFICIAL CardKit native typewriter flow — never the
+ * legacy `message.patch` pseudo-stream:
+ *
+ *   1. create a Card JSON 2.0 card entity with `streaming_mode: true`
+ *      (`cardkit.v1.card.create`);
+ *   2. send it as an interactive card reference
+ *      (`im.v1.message.create` with `{ type: 'card', data: { card_id } }`);
+ *   3. for every streamed delta, replace the markdown element's full content
+ *      via `cardkit.v1.cardElement.content` with a monotonically increasing
+ *      `sequence` and a stable `uuid` (idempotency);
+ *   4. `finish()`/`fail()` close the stream by setting `streaming_mode: false`
+ *      through `cardkit.v1.card.settings`, writing the final summary.
+ *
+ * Rollover: when a single markdown element approaches the platform's
+ * ~30,000-char element cap (the official SDK's `Channel` guard), the handle
+ * finalizes the current card, creates + sends a fresh streaming card, and
+ * continues on it. `chunkIds` records every rollover card's message id.
+ *
+ * The handle does NOT throttle internally — ReplyRouter owns throttling via
+ * config `reply.updateIntervalMs`. It guards no-op updates (skip when the text
+ * is unchanged) and serializes card operations so concurrent router flushes
+ * cannot interleave. State is observable for tests: `status`, `cardId`,
+ * `text`, `error`, `sequence` and an `updates` record of applied operations.
+ */
+import type { ChannelLogger, ChannelTarget, OutboundMessage, ReplyHandle } from '@krischoichoi/channel-core';
+import type { LarkUpstream } from './upstream.js';
+export type LarkCardStatus = 'idle' | 'active' | 'finished' | 'failed';
+/** One applied card operation (observable test surface). */
+export interface LarkCardUpdate {
+    kind: 'created' | 'streamed' | 'rollover' | 'finished' | 'failed';
+    /** Card text at the time of the operation. */
+    text?: string;
+    /** Monotonic element sequence after the operation. */
+    sequence?: number;
+    /** Previous card entity id that a rollover finalized. */
+    cardId?: string;
+    /** Clock timestamp (injectable). */
+    at: number;
+    /** Error detail when the operation itself failed. */
+    error?: string;
+}
+export interface LarkCardReplyOptions {
+    /** The upstream outbound driver (official OpenAPI or an injected fake). */
+    upstream: LarkUpstream;
+    /** Conversation the card is attached to. */
+    target: ChannelTarget;
+    logger: ChannelLogger;
+    /** Create the card on the first delta; otherwise only at `finish`. */
+    createOnFirstDelta: boolean;
+    /** Injectable clock (tests). */
+    now?: () => number;
+}
+/**
+ * Hard cap for ONE markdown element before rolling over into a fresh card.
+ * Feishu rejects oversized elements (error 230099); the official SDK's
+ * high-level Channel uses the same 30,000-char default threshold.
+ */
+export declare const LARK_STREAM_ELEMENT_MAX_CHARS = 30000;
+export declare class LarkCardReply implements ReplyHandle {
+    private readonly options;
+    status: LarkCardStatus;
+    /** Current (latest) CardKit card entity; undefined until first create. */
+    cardId?: string;
+    /** Message id of the current card reference (changes on rollover). */
+    messageId?: string;
+    text: string;
+    /** Monotonic per-element sequence (restarts on each rollover card). */
+    sequence: number;
+    /** Every card sent during this reply, in order (the first is the primary one). */
+    readonly chunkIds: string[];
+    /** Original failure value passed to `fail()`, if any. */
+    error?: unknown;
+    /** Ordered record of applied card operations. */
+    readonly updates: LarkCardUpdate[];
+    private readonly now;
+    private queue;
+    /** Text currently owned by the active card; finalized card heads are excluded. */
+    private content;
+    private hasRolledOver;
+    /** A previous failure was already written to the card — do not overwrite it. */
+    private failedShown;
+    constructor(options: LarkCardReplyOptions);
+    append(delta: string): Promise<void>;
+    replace(message: OutboundMessage): Promise<void>;
+    finish(message?: OutboundMessage): Promise<void>;
+    fail(error: unknown): Promise<void>;
+    private get finalized();
+    private push;
+    /** Create a CardKit entity and send its card reference (one-shot per card). */
+    private createCardAndSend;
+    /**
+     * Push the full element content through `cardElement.content`, rolling over
+     * into a fresh card when the element exceeds the platform cap. Sequence is
+     * monotonically increased and a stable uuid is derived from cardId +
+     * sequence (idempotent on retry).
+     */
+    private pushContent;
+    /**
+     * Finalize the current card with the head content and start a fresh
+     * streaming card for the tail. Mirrors the official SDK Channel rollover:
+     * the current element is pinned to the head, streaming is closed on it, and
+     * a new streaming entity is created + sent seeded with the tail.
+     */
+    private rollover;
+    /** Close the stream: `streaming_mode: false` + final summary. */
+    private closeStreaming;
+    private record;
+    private enqueue;
+    private replaceText;
+}
+/** Shorten markdown to a single-line preview for the card summary. */
+export declare function truncateSummary(text: string, max?: number): string;
+/**
+ * Split long content at ~`limit` chars while keeping fenced code blocks whole
+ * (mirrors the official SDK Channel splitter). A single line that alone
+ * exceeds `limit` (an unbreakable token) is hard-wrapped so the caller can
+ * always roll over instead of being stuck with an oversized element.
+ */
+export declare function splitForRollover(text: string, limit: number): string[];
+//# sourceMappingURL=card.d.ts.map

package/lib/card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../src/card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,WAAW,EACZ,MAAM,4BAA4B,CAAC;AAMpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEvE,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;IAClE,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,EAAE,YAAY,CAAC;IACvB,4CAA4C;IAC5C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,sEAAsE;IACtE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAKpD,qBAAa,aAAc,YAAW,WAAW;IAwBnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAvBpC,MAAM,EAAE,cAAc,CAAU;IAChC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,SAAM;IACV,uEAAuE;IACvE,QAAQ,SAAK;IACb,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAM;IACjC,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,CAAM;IAExC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,KAAK,CAAoC;IACjD,kFAAkF;IAClF,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,aAAa,CAAS;IAC9B,gFAAgF;IAChF,OAAO,CAAC,WAAW,CAAS;gBAEC,OAAO,EAAE,oBAAoB;IAI1D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAapC,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhD,MAAM,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BhD,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCnC,OAAO,KAAK,SAAS,GAEpB;YAEa,IAAI;IAUlB,+EAA+E;YACjE,iBAAiB;IAY/B;;;;;OAKG;YACW,WAAW;IAiBzB;;;;;OAKG;YACW,QAAQ;IA6CtB,iEAAiE;YACnD,cAAc;IAU5B,OAAO,CAAC,MAAM;IAkBd,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,WAAW;CAepB;AAOD,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,MAAM,CAI9D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgDtE"}

package/lib/card.js

@@ -0,0 +1,347 @@
+import { ChannelError } from '@krischoichoi/channel-core';
+import { STREAM_MARKDOWN_ELEMENT_ID, streamingCardJson, } from './openapi-outbound.js';
+/**
+ * Hard cap for ONE markdown element before rolling over into a fresh card.
+ * Feishu rejects oversized elements (error 230099); the official SDK's
+ * high-level Channel uses the same 30,000-char default threshold.
+ */
+export const LARK_STREAM_ELEMENT_MAX_CHARS = 30_000;
+/** Stable summary shown in chat previews while the card is still streaming. */
+const GENERATING_SUMMARY = '[Generating...]';
+export class LarkCardReply {
+    options;
+    status = 'idle';
+    /** Current (latest) CardKit card entity; undefined until first create. */
+    cardId;
+    /** Message id of the current card reference (changes on rollover). */
+    messageId;
+    text = '';
+    /** Monotonic per-element sequence (restarts on each rollover card). */
+    sequence = 0;
+    /** Every card sent during this reply, in order (the first is the primary one). */
+    chunkIds = [];
+    /** Original failure value passed to `fail()`, if any. */
+    error;
+    /** Ordered record of applied card operations. */
+    updates = [];
+    now;
+    queue = Promise.resolve();
+    /** Text currently owned by the active card; finalized card heads are excluded. */
+    content = '';
+    hasRolledOver = false;
+    /** A previous failure was already written to the card — do not overwrite it. */
+    failedShown = false;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    append(delta) {
+        return this.enqueue(async () => {
+            if (this.finalized)
+                return;
+            if (!delta)
+                return;
+            const merged = mergeStreamingText(this.text, delta);
+            const appended = merged.slice(this.text.length);
+            if (!appended)
+                return;
+            this.text = merged;
+            this.content += appended;
+            await this.push();
+        });
+    }
+    replace(message) {
+        return this.enqueue(async () => {
+            if (this.finalized)
+                return;
+            if (message.text === undefined)
+                return;
+            // No-op guard: skip the network round-trip when nothing changed.
+            if (message.text === this.text)
+                return;
+            this.replaceText(message.text);
+            await this.push();
+        });
+    }
+    finish(message) {
+        return this.enqueue(async () => {
+            if (this.finalized)
+                return;
+            const finalText = message?.text;
+            let needsSync = false;
+            if (finalText !== undefined && finalText !== this.text) {
+                this.replaceText(finalText);
+                needsSync = true;
+            }
+            if (!this.cardId) {
+                // Nothing was streamed eagerly: create the final card now and write
+                // the accumulated content into its markdown element (or do nothing
+                // when there is no content to show).
+                if (this.text) {
+                    await this.createCardAndSend();
+                    await this.pushContent(this.content);
+                }
+            }
+            else if (needsSync) {
+                await this.pushContent(this.content);
+            }
+            if (this.cardId) {
+                await this.closeStreaming(this.content);
+                this.record('finished', this.text);
+            }
+            else {
+                this.record('finished', undefined);
+            }
+            this.status = 'finished';
+        });
+    }
+    fail(error) {
+        return this.enqueue(async () => {
+            if (this.finalized)
+                return;
+            this.error = error;
+            if (this.cardId && !this.failedShown) {
+                const failureContent = this.content ? `${this.content}\n\n— _(Generation interrupted)_` : '— _(Generation interrupted)_';
+                let updateError;
+                try {
+                    // Write the failure into the card content first, then close the
+                    // stream. A secondary failure must NOT overwrite the original error.
+                    this.failedShown = true;
+                    await this.pushContent(failureContent);
+                }
+                catch (secondary) {
+                    updateError = secondary;
+                }
+                try {
+                    await this.closeStreaming(failureContent);
+                }
+                catch (secondary) {
+                    updateError ??= secondary;
+                }
+                if (updateError) {
+                    // Marking the card failed must not mask the original error.
+                    this.options.logger.error('[channel-lark] failed to mark card failed', updateError);
+                    this.record('failed', this.text, updateError);
+                }
+                else
+                    this.record('failed', this.text);
+            }
+            else {
+                this.record('failed', this.text);
+            }
+            this.status = 'failed';
+        });
+    }
+    get finalized() {
+        return this.status === 'finished' || this.status === 'failed';
+    }
+    async push() {
+        if (this.cardId) {
+            await this.pushContent(this.content);
+            return;
+        }
+        if (!this.options.createOnFirstDelta)
+            return; // buffer until finish
+        await this.createCardAndSend();
+        await this.pushContent(this.content);
+    }
+    /** Create a CardKit entity and send its card reference (one-shot per card). */
+    async createCardAndSend() {
+        const cardJson = streamingCardJson('...', GENERATING_SUMMARY);
+        const entity = await this.options.upstream.createCardEntity(cardJson);
+        const sent = await this.options.upstream.sendCardEntity(this.options.target.conversationId, entity.cardId);
+        this.cardId = entity.cardId;
+        this.messageId = sent.messageId;
+        this.sequence = 0;
+        this.chunkIds.push(sent.messageId);
+        this.status = 'active';
+        this.record('created', this.text);
+    }
+    /**
+     * Push the full element content through `cardElement.content`, rolling over
+     * into a fresh card when the element exceeds the platform cap. Sequence is
+     * monotonically increased and a stable uuid is derived from cardId +
+     * sequence (idempotent on retry).
+     */
+    async pushContent(content) {
+        if (!this.cardId)
+            return;
+        if (content.length > LARK_STREAM_ELEMENT_MAX_CHARS) {
+            await this.rollover(content);
+            return;
+        }
+        this.sequence += 1;
+        await this.options.upstream.updateCardElementContent(this.cardId, STREAM_MARKDOWN_ELEMENT_ID, content || ' ', this.sequence, uuidFor(this.cardId, this.sequence));
+        this.record('streamed', content, undefined, this.sequence);
+    }
+    /**
+     * Finalize the current card with the head content and start a fresh
+     * streaming card for the tail. Mirrors the official SDK Channel rollover:
+     * the current element is pinned to the head, streaming is closed on it, and
+     * a new streaming entity is created + sent seeded with the tail.
+     */
+    async rollover(content) {
+        if (!this.cardId)
+            return;
+        // A rollover cannot produce a single splittable piece below the cap.
+        const chunks = splitForRollover(content, LARK_STREAM_ELEMENT_MAX_CHARS);
+        if (chunks.length < 2)
+            throw new Error('rollover: content not splittable below limit');
+        const head = chunks[0];
+        const joinedWithNewlines = chunks.slice(1).join('\n');
+        const joinedWithoutSeparators = chunks.slice(1).join('');
+        // Keep the splitter's original character sequence intact. Line-oriented
+        // chunks need their delimiters; hard-wrapped tokens must not gain '\n'.
+        const tail = joinedWithNewlines.length + head.length === content.length
+            ? joinedWithNewlines
+            : joinedWithoutSeparators;
+        // 1. Pin the current element to the head.
+        this.sequence += 1;
+        await this.options.upstream.updateCardElementContent(this.cardId, STREAM_MARKDOWN_ELEMENT_ID, head, this.sequence, uuidFor(this.cardId, this.sequence));
+        // 2. Close streaming on the old card (best-effort).
+        try {
+            await this.closeStreaming(head);
+        }
+        catch {
+            // Feishu auto-closes an idle stream; a transient failure is recoverable.
+        }
+        this.hasRolledOver = true;
+        // 3. Create + send the fresh streaming card seeded with the tail.
+        const previousCardId = this.cardId;
+        const cardJson = streamingCardJson(tail || '...', GENERATING_SUMMARY);
+        const entity = await this.options.upstream.createCardEntity(cardJson);
+        const sent = await this.options.upstream.sendCardEntity(this.options.target.conversationId, entity.cardId);
+        this.cardId = entity.cardId;
+        this.messageId = sent.messageId;
+        this.sequence = 0;
+        this.content = tail;
+        this.chunkIds.push(sent.messageId);
+        this.record('rollover', tail, undefined, 0, previousCardId);
+        // Continue streaming the tail immediately.
+        await this.pushContent(tail);
+    }
+    /** Close the stream: `streaming_mode: false` + final summary. */
+    async closeStreaming(summaryText) {
+        if (!this.cardId)
+            return;
+        this.sequence += 1;
+        await this.options.upstream.finishStreamingCard(this.cardId, this.sequence, truncateSummary(summaryText));
+    }
+    record(kind, text, error, sequence, cardId) {
+        const update = {
+            kind,
+            text,
+            at: this.now(),
+        };
+        if (sequence !== undefined)
+            update.sequence = sequence;
+        if (cardId !== undefined)
+            update.cardId = cardId;
+        if (error !== undefined)
+            update.error = String(error);
+        this.updates.push(update);
+    }
+    enqueue(task) {
+        const next = this.queue.then(task, task);
+        this.queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    replaceText(next) {
+        if (!this.hasRolledOver) {
+            this.text = next;
+            this.content = next;
+            return;
+        }
+        if (!next.startsWith(this.text)) {
+            throw new ChannelError('CHANNEL_ERROR', 'lark streaming replacement cannot rewrite content already finalized by card rollover');
+        }
+        this.content += next.slice(this.text.length);
+        this.text = next;
+    }
+}
+/** Stable request uuid derived from the card entity id + sequence. */
+function uuidFor(cardId, sequence) {
+    return `c_${cardId}_${sequence}`;
+}
+/** Shorten markdown to a single-line preview for the card summary. */
+export function truncateSummary(text, max = 50) {
+    if (!text)
+        return '';
+    const cleaned = text.replace(/\s+/g, ' ').trim();
+    return cleaned.length <= max ? cleaned : `${cleaned.slice(0, max - 1)}…`;
+}
+/**
+ * Split long content at ~`limit` chars while keeping fenced code blocks whole
+ * (mirrors the official SDK Channel splitter). A single line that alone
+ * exceeds `limit` (an unbreakable token) is hard-wrapped so the caller can
+ * always roll over instead of being stuck with an oversized element.
+ */
+export function splitForRollover(text, limit) {
+    if (text.length <= limit)
+        return [text];
+    const lines = text.split('\n');
+    const out = [];
+    let buf = [];
+    let bufLen = 0;
+    let fenceLang = null;
+    const flush = () => {
+        if (buf.length === 0)
+            return;
+        let chunk = buf.join('\n');
+        if (fenceLang !== null)
+            chunk += '\n```';
+        out.push(chunk);
+        buf = [];
+        bufLen = 0;
+        if (fenceLang !== null) {
+            // Reopen the fence in the next chunk.
+            buf.push(`\`\`\`${fenceLang}`);
+            bufLen = buf[0].length;
+        }
+    };
+    for (const line of lines) {
+        const match = line.match(/^```(\w*)$/);
+        const lineLen = line.length + (buf.length > 0 ? 1 : 0);
+        const isHeading = /^#{1,6}\s/.test(line);
+        const nearFull = bufLen > limit * 0.75;
+        if (bufLen + lineLen > limit || (isHeading && nearFull && buf.length > 0)) {
+            flush();
+        }
+        buf.push(line);
+        bufLen += lineLen;
+        if (match) {
+            fenceLang = fenceLang === null ? (match[1] ?? '') : null;
+        }
+    }
+    flush();
+    // Hard-wrap any remaining oversized chunk (a single unbreakable line/token
+    // cannot be split at a line boundary — never leave it above the cap).
+    const final = [];
+    for (const chunk of out) {
+        if (chunk.length <= limit) {
+            final.push(chunk);
+            continue;
+        }
+        for (let i = 0; i < chunk.length; i += limit) {
+            final.push(chunk.slice(i, i + limit));
+        }
+    }
+    return final.length > 0 ? final : [text];
+}
+function mergeStreamingText(previous, next) {
+    if (!previous)
+        return next;
+    if (!next)
+        return previous;
+    if (next.startsWith(previous))
+        return next;
+    if (previous.startsWith(next))
+        return previous;
+    const maxOverlap = Math.min(previous.length, next.length);
+    for (let length = maxOverlap; length > 0; length -= 1) {
+        if (previous.endsWith(next.slice(0, length)))
+            return previous + next.slice(length);
+    }
+    return previous + next;
+}
+//# sourceMappingURL=card.js.map