eve-lark 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,258 @@
+import { Channel } from 'eve/channels';
+
+/**
+ * Public types for eve-lark.
+ */
+/**
+ * Discriminated union of normalized inbound message parts (text vs file).
+ * Useful for consumers that want to inspect what eve-lark handed to `send()`.
+ */
+type LarkInboundMessage = LarkInboundResult;
+type LarkReplyMode = "streaming" | "static";
+/**
+ * Branded string for a continuation token in the wire format `${chatId}:${rootMessageId ?? "_"}`.
+ * Use {@link larkContinuationToken} to mint one.
+ */
+type LarkContinuationToken = string & {
+    readonly __larkContinuationTokenBrand: unique symbol;
+};
+interface LarkChannelOptions {
+    appId?: string | undefined;
+    appSecret?: string | undefined;
+    verificationToken?: string | undefined;
+    encryptKey?: string | undefined;
+    baseUrl?: string | undefined;
+    botOpenId?: string | undefined;
+    webhookPath?: string | undefined;
+    replyMode?: LarkReplyMode | undefined;
+    streamPatchIntervalMs?: number | undefined;
+    streamCreateThresholdMs?: number | undefined;
+    dedupTtlMs?: number | undefined;
+    dedupMaxEntries?: number | undefined;
+    requestTimeoutMs?: number | undefined;
+    maxRetries?: number | undefined;
+    tokenRefreshBufferMs?: number | undefined;
+    signatureSkewMs?: number | undefined;
+    fetch?: typeof fetch | undefined;
+    /**
+     * Emoji type to react to the inbound user message with as soon as it arrives
+     * (acknowledgement feedback). Set to a Feishu emoji type string like
+     * "TYPING", an array of candidates (one is picked at random per message),
+     * or `false` to disable. Default: "TYPING".
+     */
+    ackReaction?: string | readonly string[] | false | undefined;
+}
+interface ResolvedLarkOptions {
+    appId: string;
+    appSecret: string;
+    verificationToken: string;
+    encryptKey: string | undefined;
+    baseUrl: string;
+    botOpenId: string | undefined;
+    webhookPath: string;
+    replyMode: LarkReplyMode;
+    streamPatchIntervalMs: number;
+    streamCreateThresholdMs: number;
+    dedupTtlMs: number;
+    dedupMaxEntries: number;
+    requestTimeoutMs: number;
+    maxRetries: number;
+    tokenRefreshBufferMs: number;
+    signatureSkewMs: number;
+    fetch: typeof fetch;
+    ackReaction: string | readonly string[] | false;
+}
+type LarkSenderType = "user" | "app";
+type LarkChatType = "p2p" | "group";
+interface LarkMention {
+    key: string;
+    id: LarkMentionId;
+    name: string;
+    idType: LarkMentionIdType;
+    isOpenIdOfBot: boolean;
+    isAll: boolean;
+}
+interface LarkMentionId {
+    openId?: string | undefined;
+    userId?: string | undefined;
+    unionId?: string | undefined;
+}
+type LarkMentionIdType = "open_id" | "user_id" | "union_id";
+interface LarkInboundFile {
+    fileKey: string;
+    mediaType: string;
+    kind: "image" | "file";
+}
+interface LarkInboundResult {
+    text: string;
+    files: LarkInboundFile[];
+    chatId: string;
+    rootId: string | null;
+    parentId: string | null;
+    messageId: string;
+    senderOpenId: string;
+    senderType: LarkSenderType;
+    chatType: LarkChatType;
+    mentions: LarkMention[];
+}
+/** Subset of the official v2 `im.message.receive_v1` event payload we depend on. */
+interface LarkInboundEvent {
+    message: {
+        message_id: string;
+        root_id?: string | undefined;
+        parent_id?: string | undefined;
+        chat_id: string;
+        message_type: string;
+        content: string;
+        create_time?: string | undefined;
+        mentions?: LarkRawMention[] | undefined;
+    };
+    sender: {
+        sender_id: {
+            open_id?: string | undefined;
+            user_id?: string | undefined;
+            union_id?: string | undefined;
+        };
+        sender_type?: string | undefined;
+    };
+    chat_type?: string | undefined;
+}
+interface LarkRawMention {
+    key: string;
+    id: {
+        open_id?: string | undefined;
+        user_id?: string | undefined;
+        union_id?: string | undefined;
+    };
+    name: string;
+    id_type?: LarkMentionIdType | undefined;
+}
+interface LarkContext {
+    client: unknown;
+    options: ResolvedLarkOptions;
+    anchorThread(rootMessageId: string): void;
+}
+interface LarkAdapterState {
+    client: unknown;
+    dedup: unknown;
+    options: ResolvedLarkOptions;
+}
+/**
+ * Minimal interactive card payload (template_blue).
+ */
+interface LarkCard {
+    config: {
+        wide_screen_mode?: boolean | undefined;
+        update_multi?: boolean | undefined;
+    };
+    elements: LarkCardElement[];
+}
+type LarkCardElement = {
+    tag: "markdown";
+    content: string;
+} | {
+    tag: "hr";
+} | {
+    tag: "note";
+    elements: Array<{
+        tag: "plain_text";
+        content: string;
+    }>;
+};
+
+/**
+ * Continuation token format: `${chatId}:${rootMessageId ?? "_"}`.
+ * The framework prepends the channel file stem before handing the token to
+ * the runtime; consumers should call this helper rather than concatenate.
+ */
+declare function larkContinuationToken(chatId: string, rootMessageId: string | null): LarkContinuationToken;
+/**
+ * Create a Lark/Feishu channel for the eve agent framework.
+ *
+ * The channel mounts a single POST webhook that verifies the request,
+ * decrypts the body when an encrypt key is configured, deduplicates events
+ * by id, parses the inbound message, and starts or resumes an eve session.
+ *
+ * Streaming happens via eve's native channel events: `message.appended`
+ * drives live card patches, `message.completed` finalizes the card, and
+ * `turn.failed` aborts it. In `replyMode: "static"` the controller is
+ * skipped and `message.completed` delivers a single card.
+ */
+declare function createLarkChannel(optionsInput: LarkChannelOptions): Channel<undefined, Record<string, unknown>, Record<string, unknown>>;
+
+declare class LarkClient {
+    #private;
+    private readonly options;
+    private token;
+    private refreshPromise;
+    constructor(options: ResolvedLarkOptions);
+    getTenantAccessToken(): Promise<string>;
+    sendText(args: {
+        chatId: string;
+        content: string;
+        rootId?: string;
+        parentId?: string;
+    }): Promise<{
+        messageId: string;
+    }>;
+    sendCard(args: {
+        chatId: string;
+        card: LarkCard;
+        rootId?: string;
+        parentId?: string;
+    }): Promise<{
+        messageId: string;
+    }>;
+    patchCard(args: {
+        messageId: string;
+        card: LarkCard;
+    }): Promise<void>;
+    downloadResource(args: {
+        messageId: string;
+        fileKey: string;
+        type: "image" | "file";
+    }): Promise<Buffer>;
+    addReaction(args: {
+        messageId: string;
+        emojiType: string;
+    }): Promise<{
+        reactionId: string;
+    }>;
+    removeReaction(args: {
+        messageId: string;
+        reactionId: string;
+    }): Promise<void>;
+}
+
+/**
+ * Typed error hierarchy for eve-lark.
+ *
+ * All errors extend a common base so consumers can `instanceof LarkChannelError`
+ * to catch anything thrown by the channel.
+ */
+declare class LarkChannelError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+declare class LarkConfigError extends LarkChannelError {
+}
+declare class LarkSignatureError extends LarkChannelError {
+}
+declare class LarkDecryptError extends LarkChannelError {
+}
+interface LarkApiErrorBody {
+    code?: number | undefined;
+    msg?: string | undefined;
+}
+declare class LarkApiError extends LarkChannelError {
+    readonly code: number | undefined;
+    readonly body: LarkApiErrorBody | undefined;
+    readonly status: number | undefined;
+    constructor(message: string, opts?: {
+        code?: number | undefined;
+        body?: LarkApiErrorBody | undefined;
+        status?: number | undefined;
+        cause?: unknown;
+    });
+}
+
+export { type LarkAdapterState, LarkApiError, type LarkApiErrorBody, type LarkCard, type LarkCardElement, LarkChannelError, type LarkChannelOptions, LarkClient, LarkConfigError, type LarkContext, type LarkContinuationToken, LarkDecryptError, type LarkInboundEvent, type LarkInboundFile, type LarkInboundMessage, type LarkInboundResult, type LarkMention, type LarkReplyMode, LarkSignatureError, type ResolvedLarkOptions, createLarkChannel, larkContinuationToken };