@onebots/adapter-instagram 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @onebots/adapter-instagram
+
+Instagram Messaging adapter for OneBots, based on the current Instagram API with Instagram Login and Graph v25.0. It uses `graph.instagram.com`, does not require a Facebook Page, and never opens its own listener port.
+
+## 特性
+
+- 可嵌入 `InstagramClient`，支持已有 Fetch/Koa Host 的 `acceptHttp()` / `ingestHttp()` 与最底层 `ingest(rawEvent)`；
+- 精确 raw-body `X-Hub-Signature-256` 校验、batch 展开、可靠去重与严格外部 JSON 校验；
+- Send API、附件上传、Conversations、消息详情与 IGSID User Profile；
+- quick replies、generic/button 原生消息、like-heart、published post media share 与 reaction；
+- Messenger Profile、Professional Account webhook subscription 与 Welcome Message Flows；
+- comment private reply 与显式 Human Agent 动作，并保留官方时间窗和用途限制；
+- 配置的 webhook fields、事件和已声明权限会动态收敛账号能力。
+
+## Standalone client
+
+```ts
+import { InstagramClient } from "@onebots/adapter-instagram";
+
+const client = new InstagramClient({
+  account_id: "support",
+  instagram_user_id: "1234567890",
+  access_token: process.env.INSTAGRAM_ACCESS_TOKEN!,
+  receive_mode: "manual",
+});
+
+client.on("event", delivery => dispatch(delivery));
+await client.start();
+await client.ingest(rawInstagramWebhookEnvelope);
+```
+
+Webhook 模式必须把宿主收到的精确原始字节交给 Client，不能先解析再序列化。Human Agent 只允许 7 天内由真实人工客服发送；适配器不会把它设为普通消息默认行为。
+
+## English
+
+The typed client shares one Graph transport and reliable webhook pipeline with the OneBots adapter. Existing hosts can pass a Fetch `Request` to `acceptHttp()`, use structured `ingestHttp()` with exact raw bytes, or pass a decoded envelope to `ingest()`. See the [Chinese platform guide](../../docs/src/platform/instagram.md) or [English platform guide](../../docs/src/en/platform/instagram.md).

package/lib/adapter-support.d.ts

@@ -0,0 +1,10 @@
+import { Account, Adapter } from "onebots";
+import type { InstagramConfig } from "./types.js";
+export declare function normalizeInstagramConfig(config: Account.Config<"instagram">): InstagramConfig;
+export declare function instagramUploadSource(params: Adapter.UploadFileParams): {
+    url: string;
+} | {
+    blob: Blob;
+    filename: string;
+};
+export declare function instagramAttachmentType(filename: string): "image" | "video" | "audio";

package/lib/adapter-support.js

@@ -0,0 +1,78 @@
+import { InstagramError } from "./errors.js";
+const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+export function normalizeInstagramConfig(config) {
+    const receiveMode = config.receive_mode || "webhook";
+    return {
+        ...config,
+        receive_mode: receiveMode,
+        http_path: receiveMode === "manual"
+            ? config.http_path
+            : config.http_path || `/instagram/${config.account_id}/events`,
+        api_version: config.api_version || "v25.0",
+        api_origin: config.api_origin || "https://graph.instagram.com",
+        subscribed_fields: config.subscribed_fields?.length
+            ? [...config.subscribed_fields]
+            : ["messages", "messaging_postbacks", "messaging_seen", "message_reactions"],
+    };
+}
+export function instagramUploadSource(params) {
+    const sources = [params.url, params.path, params.data].filter(value => value !== undefined);
+    if (sources.length !== 1) {
+        throw InstagramError.invalid("upload_file 必须且只能提供 url、path、data 之一");
+    }
+    if (params.path) {
+        throw new InstagramError("Instagram upload_file 不读取宿主本地路径", {
+            code: "INSTAGRAM_LOCAL_PATH_REJECTED",
+        });
+    }
+    if (params.url) {
+        if (!URL.canParse(params.url)) {
+            throw InstagramError.invalid("upload_file.url 不是有效 URL");
+        }
+        const url = new URL(params.url);
+        if (url.protocol !== "https:" || url.username || url.password) {
+            throw InstagramError.invalid("upload_file.url 必须是无凭据 HTTPS URL");
+        }
+        return { url: url.toString() };
+    }
+    const raw = params.data || "";
+    const match = raw.match(/^data:([^;,]+);base64,(.*)$/su);
+    const encoded = match ? match[2] : raw;
+    if (!encoded || encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/u.test(encoded)) {
+        throw InstagramError.invalid("upload_file.data 不是有效 base64");
+    }
+    const bytes = new Uint8Array(Buffer.from(encoded, "base64"));
+    if (!bytes.byteLength || bytes.byteLength > MAX_UPLOAD_BYTES) {
+        throw InstagramError.invalid("upload_file.data 必须介于 1 byte 与 25 MiB");
+    }
+    return {
+        blob: new Blob([bytes], { type: match?.[1] || contentType(params.name) }),
+        filename: params.name,
+    };
+}
+export function instagramAttachmentType(filename) {
+    const mime = contentType(filename);
+    if (mime.startsWith("image/"))
+        return "image";
+    if (mime.startsWith("video/"))
+        return "video";
+    if (mime.startsWith("audio/"))
+        return "audio";
+    throw InstagramError.invalid("Instagram Messaging 仅支持 image、video 与 audio 附件");
+}
+function contentType(filename) {
+    const extension = filename.toLowerCase().split(".").at(-1);
+    return ({
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        mp4: "video/mp4",
+        mov: "video/quicktime",
+        webm: "video/webm",
+        mp3: "audio/mpeg",
+        ogg: "audio/ogg",
+        wav: "audio/wav",
+    }[extension || ""] || "application/octet-stream");
+}

package/lib/adapter.d.ts

@@ -0,0 +1,24 @@
+import { Account, Adapter, BaseApp, type AdapterCapabilityManifest } from "onebots";
+import { InstagramClient } from "./client.js";
+export declare class InstagramAdapter extends Adapter<InstagramClient, "instagram"> {
+    private readonly httpHost;
+    constructor(app: BaseApp);
+    describeCapabilities(uin?: string): AdapterCapabilityManifest;
+    sendMessage(uin: string, params: Adapter.SendMessageParams): Promise<Adapter.SendMessageResult>;
+    getMessage(uin: string, params: Adapter.GetMessageParams): Promise<Adapter.MessageInfo>;
+    getMessageHistory(uin: string, params: Adapter.GetMessageHistoryParams): Promise<Adapter.MessageInfo[]>;
+    getLoginInfo(uin: string): Promise<Adapter.UserInfo>;
+    getUserInfo(uin: string, params: Adapter.GetUserInfoParams): Promise<Adapter.UserInfo>;
+    uploadFile(uin: string, params: Adapter.UploadFileParams): Promise<Adapter.FileInfo>;
+    executePlatformAction(uin: string, action: string, params: Readonly<Record<string, unknown>>): Promise<unknown>;
+    isPlatformActionImplemented(action: string): boolean;
+    getVersion(): Promise<Adapter.VersionInfo>;
+    getStatus(uin: string): Promise<Adapter.StatusInfo>;
+    canSendImage(): Promise<boolean>;
+    canSendRecord(): Promise<boolean>;
+    createAccount(config: Account.Config<"instagram">): Account<"instagram", InstagramClient>;
+    private requireClient;
+    private assertDirect;
+    private userInfo;
+    private messageInfo;
+}

package/lib/adapter.js

@@ -0,0 +1,191 @@
+import { Account, AccountStatus, Adapter, readPackageVersion, } from "onebots";
+import { instagramAttachmentType, instagramUploadSource, normalizeInstagramConfig, } from "./adapter-support.js";
+import { describeInstagramCapabilities, instagramCapabilities } from "./capabilities.js";
+import { InstagramClient } from "./client.js";
+import { parseApiMessage, parseBusinessProfile } from "./entities.js";
+import { InstagramError } from "./errors.js";
+import { projectInstagramEvent } from "./events.js";
+import { InstagramHttpHost } from "./http-host.js";
+import { compileInstagramMessage, projectApiMessage } from "./messages.js";
+import { executeInstagramPlatformAction, INSTAGRAM_PLATFORM_ACTIONS } from "./platform-actions.js";
+import { assertMetaId } from "./validation.js";
+export class InstagramAdapter extends Adapter {
+    httpHost;
+    constructor(app) {
+        super(app, "instagram", instagramCapabilities);
+        this.icon = "https://static.cdninstagram.com/rsrc.php/v4/yR/r/lam-fZmwmvn.png";
+        this.httpHost = new InstagramHttpHost(app, accountId => this.getAccount(accountId)?.client);
+    }
+    describeCapabilities(uin) {
+        const config = uin ? this.getAccount(uin)?.client.config : undefined;
+        return config ? describeInstagramCapabilities(config) : instagramCapabilities;
+    }
+    async sendMessage(uin, params) {
+        this.assertDirect(params.scene_type);
+        const client = this.requireClient(uin);
+        const message = await compileInstagramMessage(params.message, {
+            upload: (type, source, reusable) => client.uploadAttachment(type, source, reusable),
+        });
+        const result = await client.send(params.scene_id.string, message);
+        return { message_id: this.createId(result.message_id) };
+    }
+    async getMessage(uin, params) {
+        const message = parseApiMessage(await this.requireClient(uin).call("GET", `/${assertMetaId(params.message_id.string, "message_id")}`, { query: { fields: "id,created_time,from,to,message" } }));
+        return this.messageInfo(this.requireClient(uin), message);
+    }
+    async getMessageHistory(uin, params) {
+        this.assertDirect(params.scene_type);
+        if (params.offset !== undefined || params.start_message_id) {
+            throw new InstagramError("Instagram 使用不透明 cursor；canonical offset/start_message_id 无等价语义", { code: "INSTAGRAM_UNSUPPORTED_PAGINATION" });
+        }
+        const client = this.requireClient(uin);
+        const conversation = await client.findConversation(params.scene_id.string);
+        if (!conversation)
+            return [];
+        const full = await client.getConversation(conversation.id, params.limit || 20);
+        return (full.messages?.data || []).map(message => this.messageInfo(client, message));
+    }
+    async getLoginInfo(uin) {
+        const client = this.requireClient(uin);
+        const profile = client.businessProfile ||
+            parseBusinessProfile(await client.call("GET", `/${client.config.instagram_user_id}`, {
+                query: { fields: "id,username" },
+            }));
+        return {
+            user_id: this.createId(profile.id),
+            user_name: profile.username || profile.name || profile.id,
+            user_displayname: profile.name,
+            avatar: profile.profile_picture_url,
+        };
+    }
+    async getUserInfo(uin, params) {
+        return this.userInfo(await this.requireClient(uin).getUserProfile(params.user_id.string));
+    }
+    async uploadFile(uin, params) {
+        this.assertDirect(params.scene_type);
+        const attachmentId = await this.requireClient(uin).uploadAttachment(instagramAttachmentType(params.name), instagramUploadSource(params), true);
+        return {
+            file_id: this.createId(attachmentId),
+            file_name: params.name,
+            url: `instagram://attachment/${attachmentId}`,
+            expire_time: Math.floor(Date.now() / 1000) + 90 * 24 * 60 * 60,
+        };
+    }
+    executePlatformAction(uin, action, params) {
+        return INSTAGRAM_PLATFORM_ACTIONS.has(action)
+            ? executeInstagramPlatformAction(this.requireClient(uin), action, params)
+            : super.executePlatformAction(uin, action, params);
+    }
+    isPlatformActionImplemented(action) {
+        return INSTAGRAM_PLATFORM_ACTIONS.has(action);
+    }
+    async getVersion() {
+        return {
+            app_name: "onebots Instagram Adapter",
+            app_version: await readPackageVersion(import.meta.url),
+            impl: "Instagram API with Instagram Login",
+            version: "Graph v25.0",
+        };
+    }
+    async getStatus(uin) {
+        const account = this.getAccount(uin);
+        const online = account?.status === AccountStatus.Online;
+        return {
+            online,
+            good: online,
+            bots: account
+                ? [{ self: this.createId(account.client.config.instagram_user_id), online }]
+                : [],
+        };
+    }
+    async canSendImage() {
+        return true;
+    }
+    async canSendRecord() {
+        return true;
+    }
+    createAccount(config) {
+        const client = new InstagramClient(normalizeInstagramConfig(config), {
+            reportError: error => this.logger.error("Instagram 接收管线异常", error),
+        });
+        const account = new Account(this, client, config);
+        client.on("event", (delivery) => account.dispatchManyAwaited(projectInstagramEvent(delivery, {
+            botId: this.createId(client.config.instagram_user_id),
+            createId: value => this.createId(value),
+        })));
+        this.httpHost.mount(account.account_id, client);
+        account.on("start", async () => {
+            try {
+                await client.start();
+                account.status = AccountStatus.Online;
+                account.nickname =
+                    client.businessProfile?.username ||
+                        client.businessProfile?.name ||
+                        client.config.instagram_user_id;
+                this.logger.info(`Instagram ${account.account_id} 已就绪（${client.receiveMode}）`);
+            }
+            catch (error) {
+                account.status = AccountStatus.OffLine;
+                this.logger.error(`启动 Instagram ${account.account_id} 失败`, error);
+                throw error;
+            }
+        });
+        account.on("stop", async () => {
+            try {
+                await client.stop();
+            }
+            finally {
+                account.status = AccountStatus.OffLine;
+            }
+        });
+        return account;
+    }
+    requireClient(uin) {
+        const client = this.getAccount(uin)?.client;
+        if (!client) {
+            throw new InstagramError(`Instagram 账号 ${uin} 不存在`, {
+                code: "ACCOUNT_NOT_FOUND",
+                status: 404,
+            });
+        }
+        return client;
+    }
+    assertDirect(scene) {
+        if (scene !== "direct") {
+            throw InstagramError.invalid("Instagram Messaging 只支持 Professional Account 与 IGSID 的一对一 direct 会话");
+        }
+    }
+    userInfo(profile) {
+        return {
+            user_id: this.createId(profile.id),
+            user_name: profile.username || profile.name || profile.id,
+            user_displayname: profile.name,
+            avatar: profile.profile_pic,
+        };
+    }
+    messageInfo(client, message) {
+        const from = message.from;
+        if (!from)
+            throw InstagramError.invalid("Instagram message response 缺少 from");
+        const selfId = client.config.instagram_user_id;
+        const peer = from.id === selfId ? message.to?.data.find(person => person.id !== selfId) : from;
+        if (!peer)
+            throw InstagramError.invalid("Instagram message response 缺少对端 IGSID");
+        const timestamp = Date.parse(message.created_time);
+        if (!Number.isFinite(timestamp)) {
+            throw InstagramError.invalid("Instagram message.created_time 无效");
+        }
+        return {
+            message_id: this.createId(message.id),
+            time: Math.floor(timestamp / 1000),
+            sender: {
+                scene_type: "direct",
+                sender_id: this.createId(from.id),
+                scene_id: this.createId(peer.id),
+                sender_name: from.username || from.id,
+                scene_name: peer.username || peer.id,
+            },
+            message: projectApiMessage(message),
+        };
+    }
+}

package/lib/capabilities.d.ts

@@ -0,0 +1,6 @@
+import { type AdapterCapabilityManifest } from "onebots";
+import { INSTAGRAM_EVENT_TYPES, INSTAGRAM_WEBHOOK_FIELDS, type InstagramConfig } from "./types.js";
+export { INSTAGRAM_EVENT_TYPES, INSTAGRAM_WEBHOOK_FIELDS };
+/** Instagram Login 当前稳定接口的真实边界；Instagram Messaging 不支持群聊。 */
+export declare const instagramCapabilities: AdapterCapabilityManifest;
+export declare function describeInstagramCapabilities(config: Pick<InstagramConfig, "declared_permissions" | "event_types" | "receive_mode" | "subscribed_fields">): AdapterCapabilityManifest;

package/lib/capabilities.js

@@ -0,0 +1,167 @@
+import { defineAdapterCapabilities, definePlatformActionCapabilities, restrictAdapterEventCapabilities, } from "onebots";
+import { INSTAGRAM_PLATFORM_ACTIONS } from "./platform-actions.js";
+import { INSTAGRAM_EVENT_TYPES, INSTAGRAM_WEBHOOK_FIELDS, } from "./types.js";
+export { INSTAGRAM_EVENT_TYPES, INSTAGRAM_WEBHOOK_FIELDS };
+const permission = (permissions, note) => ({
+    support: "native",
+    availability: "permission",
+    permissions,
+    note,
+});
+const basic = permission(["instagram_business_basic"]);
+const messaging = permission(["instagram_business_manage_messages"], "仅可联系已主动开启会话的用户，并受标准消息窗口约束");
+const conversations = permission(["instagram_business_manage_messages"], "Requests 文件夹中 30 天未活跃会话不会返回；单次最多读取最近 20 条消息详情");
+const platformActions = definePlatformActionCapabilities(INSTAGRAM_PLATFORM_ACTIONS, action => {
+    if (action === "call_instagram_api")
+        return permission(["目标 Graph edge 要求的 permission"]);
+    if (action === "send_instagram_human_agent") {
+        return permission(["instagram_business_manage_messages", "Human Agent"], "仅限 7 天内由真实人工客服发送，不得用于自动化或无关内容");
+    }
+    if (action === "send_instagram_private_reply") {
+        return permission(["instagram_business_manage_messages", "instagram_business_manage_comments"], "每条评论只能私信回复一次，须在评论后 7 天内发送");
+    }
+    if (action.includes("welcome_message_flow"))
+        return messaging;
+    if (action.includes("profile"))
+        return messaging;
+    if (action.includes("conversation"))
+        return conversations;
+    if (action.includes("subscribed") || action.startsWith("subscribe_"))
+        return messaging;
+    return messaging;
+});
+/** Instagram Login 当前稳定接口的真实边界；Instagram Messaging 不支持群聊。 */
+export const instagramCapabilities = defineAdapterCapabilities({
+    actions: {
+        send_message: { ...messaging, scenes: ["direct"] },
+        get_message: { ...conversations, scenes: ["direct"] },
+        get_message_history: { ...conversations, scenes: ["direct"] },
+        get_login_info: basic,
+        get_user_info: permission([
+            "instagram_business_basic",
+            "instagram_business_manage_messages",
+        ]),
+        upload_file: { ...messaging, scenes: ["direct"] },
+        can_send_image: { support: "native" },
+        can_send_record: { support: "native" },
+        get_version: { support: "native" },
+        get_status: { support: "native" },
+        get_supported_actions: { support: "native" },
+        ...platformActions,
+    },
+    events: {
+        message: { support: "native", scenes: ["direct"] },
+        message_deleted: { support: "native" },
+        message_updated: { support: "native" },
+        message_status: { support: "native" },
+        reaction_added: { support: "native" },
+        reaction_removed: { support: "native" },
+        interaction: { support: "native" },
+        custom: {
+            support: "native",
+            note: "unsupported message、referral、opt-in、handover、standby、comment 与其他 field/value 原样保留",
+        },
+    },
+    segments: {
+        text: { support: "native", direction: "both" },
+        reply: { support: "native", direction: "both" },
+        image: { support: "native", direction: "both" },
+        video: { support: "native", direction: "both" },
+        audio: { support: "native", direction: "both" },
+        instagram_quick_replies: { support: "native", direction: "send" },
+        instagram_quick_reply: { support: "native", direction: "receive" },
+        instagram_referral: { support: "native", direction: "receive" },
+        instagram_reply_context: { support: "native", direction: "receive" },
+        instagram: { support: "native", direction: "send" },
+        instagram_attachment: { support: "native", direction: "receive" },
+    },
+    transports: {
+        webhook: {
+            support: "native",
+            mode: "webhook",
+            note: "GET challenge、精确 raw-body SHA256、batch 展开与可靠去重",
+        },
+        manual: {
+            support: "native",
+            mode: "native",
+            note: "ingest(rawEvent) 与已有 Host 共用 Client 和事件投影",
+        },
+    },
+});
+const eventProjection = {
+    message: ["message"],
+    message_deleted: ["message_deleted"],
+    message_updated: ["message_edit"],
+    message_status: ["message_echo", "read"],
+    reaction_added: ["reaction"],
+    reaction_removed: ["reaction"],
+    interaction: ["postback"],
+    custom: ["message_unsupported", "referral", "optin", "handover", "change", "unknown"],
+};
+const fieldEvents = {
+    messages: ["message", "message_echo", "message_deleted", "message_unsupported", "message_edit"],
+    messaging_postbacks: ["postback"],
+    messaging_seen: ["read"],
+    messaging_handover: ["handover"],
+    messaging_referral: ["referral"],
+    messaging_optins: ["optin"],
+    message_reactions: ["reaction"],
+    standby: ["unknown"],
+    comments: ["change"],
+    live_comments: ["change"],
+    mentions: ["change"],
+    story_insights: ["change"],
+};
+export function describeInstagramCapabilities(config) {
+    const configuredEvents = new Set(config.event_types?.length ? config.event_types : INSTAGRAM_EVENT_TYPES);
+    if (config.subscribed_fields?.length) {
+        const fromFields = new Set(config.subscribed_fields.flatMap(field => fieldEvents[field] || ["unknown"]));
+        for (const event of configuredEvents) {
+            if (!fromFields.has(event))
+                configuredEvents.delete(event);
+        }
+    }
+    const enabledCanonical = new Set();
+    for (const [canonical, sources] of Object.entries(eventProjection)) {
+        if (sources.some(source => configuredEvents.has(source)))
+            enabledCanonical.add(canonical);
+    }
+    let manifest = restrictAdapterEventCapabilities(instagramCapabilities, enabledCanonical, event => `当前 event_types/subscribed_fields 不会生成 ${event}`);
+    if (config.receive_mode === "manual") {
+        manifest = {
+            ...manifest,
+            transports: {
+                ...manifest.transports,
+                webhook: {
+                    support: "unsupported",
+                    availability: "context",
+                    mode: "webhook",
+                    note: "当前 receive_mode 为 manual",
+                },
+            },
+        };
+    }
+    return restrictDeclaredPermissions(manifest, config.declared_permissions);
+}
+function restrictDeclaredPermissions(manifest, permissions) {
+    if (!permissions?.length)
+        return manifest;
+    const declared = new Set(permissions);
+    const actions = { ...manifest.actions };
+    for (const [action, descriptor] of Object.entries(actions)) {
+        if (action === "call_instagram_api")
+            continue;
+        const required = descriptor.permissions || [];
+        if (!required.length)
+            continue;
+        if (required.every(permissionName => declared.has(permissionName)))
+            continue;
+        actions[action] = {
+            support: "unsupported",
+            availability: "permission",
+            permissions: required,
+            note: "declared_permissions 未包含该动作要求的全部权限",
+        };
+    }
+    return { ...manifest, actions };
+}

package/lib/client.d.ts

@@ -0,0 +1,49 @@
+import { EventEmitter } from "node:events";
+import type { InstagramBusinessProfile, InstagramCallOptions, InstagramClientEvents, InstagramConfig, InstagramConversation, InstagramGraphMethod, InstagramHttpRequest, InstagramHttpResponse, InstagramIngestResult, InstagramList, InstagramOutgoingMessage, InstagramSendResponse, InstagramUserProfile } from "./types.js";
+export interface InstagramClientDependencies {
+    fetcher?: typeof fetch;
+    reportError?(error: Error): void;
+}
+/** Graph API 与 Webhook/manual ingress 共用的可嵌入 Instagram Client。 */
+export declare class InstagramClient extends EventEmitter<InstagramClientEvents> {
+    readonly config: InstagramConfig;
+    private readonly dependencies;
+    private readonly transport;
+    private readonly webhook;
+    private profile?;
+    private startTask?;
+    private startAbort?;
+    private generation;
+    private started;
+    constructor(config: InstagramConfig, dependencies?: InstagramClientDependencies);
+    get receiveMode(): InstagramReceiveMode;
+    get isStarted(): boolean;
+    get businessProfile(): InstagramBusinessProfile | undefined;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    call<T = unknown>(method: InstagramGraphMethod, path: string, options?: InstagramCallOptions): Promise<T>;
+    ingest(rawEvent: unknown): Promise<InstagramIngestResult[]>;
+    ingestHttp(request: InstagramHttpRequest): Promise<InstagramHttpResponse>;
+    acceptHttp(request: Request): Promise<Response>;
+    send(recipientId: string, message: InstagramOutgoingMessage, options?: {
+        humanAgent?: boolean;
+    }): Promise<InstagramSendResponse>;
+    sendPrivateReply(commentId: string, text: string): Promise<InstagramSendResponse>;
+    react(recipientId: string, messageId: string, action: "react" | "unreact"): Promise<unknown>;
+    uploadAttachment(type: "image" | "video" | "audio" | "file", source: {
+        url: string;
+    } | {
+        blob: Blob;
+        filename: string;
+    }, reusable?: boolean): Promise<string>;
+    getUserProfile(userId: string): Promise<InstagramUserProfile>;
+    listConversations(after?: string, limit?: number): Promise<InstagramList<InstagramConversation>>;
+    findConversation(userId: string): Promise<InstagramConversation | undefined>;
+    getConversation(conversationId: string, limit?: number): Promise<InstagramConversation>;
+    private startInternal;
+    private subscribe;
+    private forward;
+    private reportError;
+}
+type InstagramReceiveMode = "webhook" | "manual";
+export {};