@onebots/adapter-instagram 0.1.0

package/lib/types.d.ts

@@ -0,0 +1,171 @@
+import type { MetaGraphCallOptions, MetaGraphMethod, MetaHttpRequest, MetaHttpResponse, MetaIngestResult } from "@onebots/meta";
+export type InstagramReceiveMode = "webhook" | "manual";
+export interface InstagramConfig {
+    account_id: string;
+    instagram_user_id: string;
+    access_token: string;
+    app_secret?: string;
+    verify_token?: string;
+    receive_mode?: InstagramReceiveMode;
+    http_path?: string;
+    api_version?: string;
+    api_origin?: string;
+    max_body_bytes?: number;
+    auto_subscribe?: boolean;
+    subscribed_fields?: string[];
+    event_types?: InstagramEventType[];
+    declared_permissions?: string[];
+}
+export interface InstagramActor {
+    id: string;
+}
+export interface InstagramAttachment {
+    type: string;
+    payload: Record<string, unknown>;
+}
+export interface InstagramMessage {
+    mid: string;
+    text?: string;
+    is_echo?: boolean;
+    is_deleted?: boolean;
+    is_self?: boolean;
+    is_unsupported?: boolean;
+    attachments?: InstagramAttachment[];
+    quick_reply?: {
+        payload: string;
+    };
+    reply_to?: Record<string, unknown>;
+    referral?: Record<string, unknown>;
+}
+export interface InstagramMessagingItem {
+    sender: InstagramActor;
+    recipient: InstagramActor;
+    timestamp: number;
+    message?: InstagramMessage;
+    message_edit?: Record<string, unknown>;
+    reaction?: Record<string, unknown>;
+    postback?: Record<string, unknown>;
+    read?: Record<string, unknown>;
+    referral?: Record<string, unknown>;
+    optin?: Record<string, unknown>;
+    pass_thread_control?: Record<string, unknown>;
+    take_thread_control?: Record<string, unknown>;
+    request_thread_control?: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}
+export interface InstagramChange {
+    field: string;
+    value: Record<string, unknown>;
+}
+export interface InstagramEntry {
+    id: string;
+    time: number;
+    messaging: InstagramMessagingItem[];
+    standby: InstagramMessagingItem[];
+    changes: InstagramChange[];
+    raw: Record<string, unknown>;
+}
+export interface InstagramWebhookEnvelope {
+    object: "instagram";
+    entry: InstagramEntry[];
+    raw: Record<string, unknown>;
+}
+export declare const INSTAGRAM_EVENT_TYPES: readonly ["message", "message_echo", "message_deleted", "message_unsupported", "message_edit", "reaction", "postback", "read", "referral", "optin", "handover", "change", "unknown"];
+export type InstagramEventType = (typeof INSTAGRAM_EVENT_TYPES)[number];
+export declare const INSTAGRAM_WEBHOOK_FIELDS: readonly ["messages", "messaging_postbacks", "messaging_seen", "messaging_handover", "messaging_referral", "messaging_optins", "message_reactions", "standby", "comments", "live_comments", "mentions", "story_insights"];
+export interface InstagramEvent {
+    event_type: InstagramEventType;
+    source: "messaging" | "standby" | "change";
+    instagram_user_id: string;
+    entry_time: number;
+    messaging?: InstagramMessagingItem;
+    change?: InstagramChange;
+}
+export interface InstagramDelivery {
+    id: string;
+    event: InstagramEvent;
+    rawEnvelope: InstagramWebhookEnvelope;
+}
+export type InstagramIngestResult = MetaIngestResult<InstagramEvent, InstagramWebhookEnvelope>;
+export interface InstagramClientEvents {
+    event: [delivery: InstagramDelivery];
+    ready: [];
+    error: [error: Error];
+    stop: [];
+}
+export interface InstagramBusinessProfile {
+    id: string;
+    user_id?: string;
+    username?: string;
+    name?: string;
+    profile_picture_url?: string;
+    account_type?: string;
+}
+export interface InstagramUserProfile {
+    id: string;
+    name?: string;
+    username?: string;
+    profile_pic?: string;
+    follower_count?: number;
+    is_user_follow_business?: boolean;
+    is_business_follow_user?: boolean;
+    is_verified_user?: boolean;
+}
+export interface InstagramSendResponse {
+    recipient_id: string;
+    message_id: string;
+}
+export interface InstagramApiMessage {
+    id: string;
+    created_time: string;
+    from?: {
+        id: string;
+        username?: string;
+    };
+    to?: {
+        data: Array<{
+            id: string;
+            username?: string;
+        }>;
+    };
+    message?: string;
+}
+export interface InstagramConversation {
+    id: string;
+    updated_time?: string;
+    participants?: {
+        data: Array<{
+            id: string;
+            username?: string;
+        }>;
+    };
+    messages?: {
+        data: InstagramApiMessage[];
+        paging?: InstagramPaging;
+    };
+}
+export interface InstagramPaging {
+    cursors?: {
+        before?: string;
+        after?: string;
+    };
+}
+export interface InstagramList<T> {
+    data: T[];
+    paging?: InstagramPaging;
+}
+export interface InstagramOutgoingMessage extends Record<string, unknown> {
+    text?: string;
+    attachment?: Record<string, unknown>;
+    quick_replies?: Record<string, unknown>[];
+    reply_to?: {
+        mid: string;
+    };
+}
+export interface InstagramHttpRequest extends MetaHttpRequest {
+}
+export interface InstagramHttpResponse extends MetaHttpResponse {
+}
+export interface InstagramCallOptions extends MetaGraphCallOptions {
+}
+export type InstagramGraphMethod = MetaGraphMethod;

package/lib/types.js

@@ -0,0 +1,29 @@
+export const INSTAGRAM_EVENT_TYPES = [
+    "message",
+    "message_echo",
+    "message_deleted",
+    "message_unsupported",
+    "message_edit",
+    "reaction",
+    "postback",
+    "read",
+    "referral",
+    "optin",
+    "handover",
+    "change",
+    "unknown",
+];
+export const INSTAGRAM_WEBHOOK_FIELDS = [
+    "messages",
+    "messaging_postbacks",
+    "messaging_seen",
+    "messaging_handover",
+    "messaging_referral",
+    "messaging_optins",
+    "message_reactions",
+    "standby",
+    "comments",
+    "live_comments",
+    "mentions",
+    "story_insights",
+];

package/lib/validation.d.ts

@@ -0,0 +1,12 @@
+import { isRecord as isMetaRecord } from "@onebots/meta";
+import { type InstagramConfig } from "./types.js";
+export declare const isRecord: typeof isMetaRecord;
+export declare function requireRecord(value: unknown, field: string): Record<string, unknown>;
+export declare function requireString(value: unknown, field: string): string;
+export declare function optionalString(value: unknown, field: string): string | undefined;
+export declare function requireNumber(value: unknown, field: string): number;
+export declare function requireArray(value: unknown, field: string): unknown[];
+export declare function assertInstagramConfig(config: InstagramConfig): void;
+export declare function assertMetaId(value: unknown, field: string): string;
+export declare function assertNumericMetaId(value: unknown, field: string): string;
+export declare function assertHttpsUrl(value: unknown, field: string): string;

package/lib/validation.js

@@ -0,0 +1,96 @@
+import { isRecord as isMetaRecord } from "@onebots/meta";
+import { InstagramError } from "./errors.js";
+import { INSTAGRAM_EVENT_TYPES, INSTAGRAM_WEBHOOK_FIELDS } from "./types.js";
+export const isRecord = isMetaRecord;
+export function requireRecord(value, field) {
+    if (!isRecord(value))
+        throw InstagramError.invalid(`${field} 必须是对象`);
+    return value;
+}
+export function requireString(value, field) {
+    if (typeof value !== "string" || !value) {
+        throw InstagramError.invalid(`${field} 必须是非空字符串`);
+    }
+    return value;
+}
+export function optionalString(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    return requireString(value, field);
+}
+export function requireNumber(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw InstagramError.invalid(`${field} 必须是有限数字`);
+    }
+    return value;
+}
+export function requireArray(value, field) {
+    if (!Array.isArray(value))
+        throw InstagramError.invalid(`${field} 必须是数组`);
+    return value;
+}
+export function assertInstagramConfig(config) {
+    requireString(config.account_id, "account_id");
+    assertNumericMetaId(config.instagram_user_id, "instagram_user_id");
+    requireString(config.access_token, "access_token");
+    const mode = config.receive_mode || "webhook";
+    if (mode !== "webhook" && mode !== "manual") {
+        throw InstagramError.invalid("receive_mode 必须是 webhook 或 manual");
+    }
+    if (mode === "webhook" && (!config.app_secret || !config.verify_token)) {
+        throw InstagramError.invalid("webhook 模式必须配置 app_secret 与 verify_token");
+    }
+    if (config.http_path && !/^\/(?!\/)[^?#\u0000-\u001f\u007f]*$/u.test(config.http_path)) {
+        throw InstagramError.invalid("http_path 必须是安全绝对 pathname");
+    }
+    if (config.max_body_bytes !== undefined &&
+        (!Number.isSafeInteger(config.max_body_bytes) ||
+            config.max_body_bytes <= 0 ||
+            config.max_body_bytes > 50 * 1024 * 1024)) {
+        throw InstagramError.invalid("max_body_bytes 必须是 1 到 50 MiB 的安全整数");
+    }
+    assertStringList(config.subscribed_fields, "subscribed_fields");
+    assertStringList(config.event_types, "event_types");
+    assertStringList(config.declared_permissions, "declared_permissions");
+    if (config.subscribed_fields?.some(field => !INSTAGRAM_WEBHOOK_FIELDS.includes(field))) {
+        throw InstagramError.invalid("subscribed_fields 包含当前 Instagram API 未定义字段");
+    }
+    if (config.event_types?.some(type => !INSTAGRAM_EVENT_TYPES.includes(type))) {
+        throw InstagramError.invalid("event_types 包含当前适配器未定义事件");
+    }
+}
+export function assertMetaId(value, field) {
+    const id = requireString(value, field);
+    if (!/^[A-Za-z0-9_.:-]+$/u.test(id)) {
+        throw InstagramError.invalid(`${field} 包含不安全字符`);
+    }
+    return id;
+}
+export function assertNumericMetaId(value, field) {
+    const id = requireString(value, field);
+    if (!/^\d+$/u.test(id)) {
+        throw InstagramError.invalid(`${field} 必须是十进制 Meta ID`);
+    }
+    return id;
+}
+export function assertHttpsUrl(value, field) {
+    const raw = requireString(value, field);
+    if (!URL.canParse(raw))
+        throw InstagramError.invalid(`${field} 不是有效 URL`);
+    const url = new URL(raw);
+    if (url.protocol !== "https:" || url.username || url.password) {
+        throw InstagramError.invalid(`${field} 必须是无凭据 HTTPS URL`);
+    }
+    return url.toString();
+}
+function assertStringList(value, field) {
+    if (value === undefined)
+        return;
+    const values = requireArray(value, field);
+    if (values.some(item => typeof item !== "string" || !item)) {
+        throw InstagramError.invalid(`${field} 必须只包含非空字符串`);
+    }
+    if (new Set(values).size !== values.length) {
+        throw InstagramError.invalid(`${field} 不能包含重复项`);
+    }
+}

package/lib/webhook-codec.d.ts

@@ -0,0 +1,10 @@
+import type { MetaWebhookCodec, MetaWebhookDelivery } from "@onebots/meta";
+import { type InstagramEvent, type InstagramEventType, type InstagramWebhookEnvelope } from "./types.js";
+/** 将 Instagram webhook batch 严格展开为可独立去重和提交的事件。 */
+export declare class InstagramWebhookCodec implements MetaWebhookCodec<InstagramEvent, InstagramWebhookEnvelope> {
+    private readonly instagramUserId;
+    private readonly enabled?;
+    constructor(instagramUserId: string, eventTypes?: readonly InstagramEventType[]);
+    parse(value: unknown): InstagramWebhookEnvelope;
+    expand(envelope: InstagramWebhookEnvelope): MetaWebhookDelivery<InstagramEvent, InstagramWebhookEnvelope>[];
+}

package/lib/webhook-codec.js

@@ -0,0 +1,263 @@
+import { sha256Json } from "onebots";
+import { InstagramError } from "./errors.js";
+import { INSTAGRAM_EVENT_TYPES, } from "./types.js";
+import { assertNumericMetaId, optionalString, requireArray, requireNumber, requireRecord, requireString, } from "./validation.js";
+const EVENT_TYPE_SET = new Set(INSTAGRAM_EVENT_TYPES);
+/** 将 Instagram webhook batch 严格展开为可独立去重和提交的事件。 */
+export class InstagramWebhookCodec {
+    instagramUserId;
+    enabled;
+    constructor(instagramUserId, eventTypes) {
+        this.instagramUserId = instagramUserId;
+        assertNumericMetaId(instagramUserId, "instagram_user_id");
+        if (eventTypes?.some(type => !EVENT_TYPE_SET.has(type))) {
+            invalid("event_types 包含未知 Instagram 事件");
+        }
+        this.enabled = eventTypes?.length ? new Set(eventTypes) : undefined;
+    }
+    parse(value) {
+        const root = requireRecord(value, "webhook");
+        if (root.object !== "instagram") {
+            invalid("Instagram webhook.object 必须是 instagram");
+        }
+        const entries = requireArray(root.entry, "webhook.entry").map((entry, index) => parseEntry(entry, `webhook.entry[${index}]`));
+        if (!entries.length)
+            invalid("Instagram webhook.entry 不能为空");
+        if (entries.some(entry => entry.id !== this.instagramUserId)) {
+            invalid("Instagram webhook entry.id 与配置 instagram_user_id 不匹配");
+        }
+        return { object: "instagram", entry: entries, raw: root };
+    }
+    expand(envelope) {
+        const deliveries = [];
+        for (const entry of envelope.entry) {
+            for (const [source, items] of [
+                ["messaging", entry.messaging],
+                ["standby", entry.standby],
+            ]) {
+                for (const item of items) {
+                    const eventType = classify(item);
+                    if (this.enabled && !this.enabled.has(eventType))
+                        continue;
+                    const event = {
+                        event_type: eventType,
+                        source,
+                        instagram_user_id: entry.id,
+                        entry_time: entry.time,
+                        messaging: item,
+                    };
+                    deliveries.push({
+                        id: deliveryIdentity(event),
+                        event,
+                        rawEnvelope: envelope,
+                    });
+                }
+            }
+            for (const change of entry.changes) {
+                if (this.enabled && !this.enabled.has("change"))
+                    continue;
+                const event = {
+                    event_type: "change",
+                    source: "change",
+                    instagram_user_id: entry.id,
+                    entry_time: entry.time,
+                    change,
+                };
+                deliveries.push({
+                    id: `change:${entry.id}:${entry.time}:${change.field}:${sha256Json(change.value)}`,
+                    event,
+                    rawEnvelope: envelope,
+                });
+            }
+        }
+        return deliveries;
+    }
+}
+function parseEntry(value, field) {
+    const raw = requireRecord(value, field);
+    const id = assertNumericMetaId(raw.id, `${field}.id`);
+    const time = requireTimestamp(raw.time, `${field}.time`);
+    const messaging = parseMessagingArray(raw.messaging, `${field}.messaging`);
+    const standby = parseMessagingArray(raw.standby, `${field}.standby`);
+    const changes = parseEntryChange(raw, field);
+    if (!messaging.length && !standby.length && !changes.length) {
+        invalid(`${field} 没有 messaging、standby 或 field/value 事件`);
+    }
+    return { id, time, messaging, standby, changes, raw };
+}
+function parseEntryChange(raw, field) {
+    if (raw.field === undefined && raw.value === undefined)
+        return [];
+    if (raw.field === undefined || raw.value === undefined) {
+        invalid(`${field}.field 与 ${field}.value 必须同时存在`);
+    }
+    return [
+        {
+            field: requireString(raw.field, `${field}.field`),
+            value: requireRecord(raw.value, `${field}.value`),
+        },
+    ];
+}
+function parseMessagingArray(value, field) {
+    if (value === undefined)
+        return [];
+    return requireArray(value, field).map((item, index) => parseMessagingItem(item, `${field}[${index}]`));
+}
+function parseMessagingItem(value, field) {
+    const raw = requireRecord(value, field);
+    const item = {
+        sender: parseActor(raw.sender, `${field}.sender`),
+        recipient: parseActor(raw.recipient, `${field}.recipient`),
+        timestamp: requireTimestamp(raw.timestamp, `${field}.timestamp`),
+        raw,
+    };
+    if (raw.message !== undefined)
+        item.message = parseMessage(raw.message, `${field}.message`);
+    for (const key of [
+        "message_edit",
+        "reaction",
+        "postback",
+        "read",
+        "referral",
+        "optin",
+        "pass_thread_control",
+        "take_thread_control",
+        "request_thread_control",
+    ]) {
+        if (raw[key] !== undefined)
+            item[key] = requireRecord(raw[key], `${field}.${key}`);
+    }
+    validateKnownPayloads(item, field);
+    if (classify(item) === "unknown" && Object.keys(raw).length <= 3) {
+        invalid(`${field} 缺少 Instagram 事件 payload`);
+    }
+    return item;
+}
+function parseActor(value, field) {
+    const actor = requireRecord(value, field);
+    return { id: assertNumericMetaId(actor.id, `${field}.id`) };
+}
+function parseMessage(value, field) {
+    const raw = requireRecord(value, field);
+    const message = {
+        mid: requireString(raw.mid, `${field}.mid`),
+        text: optionalString(raw.text, `${field}.text`),
+        is_echo: optionalBoolean(raw.is_echo, `${field}.is_echo`),
+        is_deleted: optionalBoolean(raw.is_deleted, `${field}.is_deleted`),
+        is_self: optionalBoolean(raw.is_self, `${field}.is_self`),
+        is_unsupported: optionalBoolean(raw.is_unsupported, `${field}.is_unsupported`),
+    };
+    if (raw.attachments !== undefined) {
+        message.attachments = requireArray(raw.attachments, `${field}.attachments`).map((item, index) => parseAttachment(item, `${field}.attachments[${index}]`));
+    }
+    if (raw.quick_reply !== undefined) {
+        const quickReply = requireRecord(raw.quick_reply, `${field}.quick_reply`);
+        message.quick_reply = {
+            payload: requireString(quickReply.payload, `${field}.quick_reply.payload`),
+        };
+    }
+    if (raw.reply_to !== undefined) {
+        message.reply_to = requireRecord(raw.reply_to, `${field}.reply_to`);
+    }
+    if (raw.referral !== undefined) {
+        message.referral = requireRecord(raw.referral, `${field}.referral`);
+    }
+    return message;
+}
+function parseAttachment(value, field) {
+    const raw = requireRecord(value, field);
+    return {
+        type: requireString(raw.type, `${field}.type`),
+        payload: requireRecord(raw.payload, `${field}.payload`),
+    };
+}
+function validateKnownPayloads(item, field) {
+    if (item.message_edit) {
+        requireString(item.message_edit.mid, `${field}.message_edit.mid`);
+        requireString(item.message_edit.text, `${field}.message_edit.text`);
+        const count = requireNumber(item.message_edit.num_edit, `${field}.message_edit.num_edit`);
+        if (!Number.isSafeInteger(count) || count < 1) {
+            invalid(`${field}.message_edit.num_edit 必须是正安全整数`);
+        }
+    }
+    if (item.reaction) {
+        requireString(item.reaction.mid, `${field}.reaction.mid`);
+        const action = requireString(item.reaction.action, `${field}.reaction.action`);
+        if (action !== "react" && action !== "unreact") {
+            invalid(`${field}.reaction.action 必须是 react 或 unreact`);
+        }
+        optionalString(item.reaction.emoji, `${field}.reaction.emoji`);
+    }
+    if (item.postback) {
+        requireString(item.postback.mid, `${field}.postback.mid`);
+        requireString(item.postback.title, `${field}.postback.title`);
+        requireString(item.postback.payload, `${field}.postback.payload`);
+    }
+    if (item.read)
+        requireString(item.read.mid, `${field}.read.mid`);
+    if (item.referral) {
+        requireString(item.referral.ref, `${field}.referral.ref`);
+        requireString(item.referral.source, `${field}.referral.source`);
+        requireString(item.referral.type, `${field}.referral.type`);
+    }
+}
+function classify(item) {
+    if (item.message?.is_deleted)
+        return "message_deleted";
+    if (item.message?.is_unsupported)
+        return "message_unsupported";
+    if (item.message)
+        return item.message.is_echo ? "message_echo" : "message";
+    if (item.message_edit)
+        return "message_edit";
+    if (item.reaction)
+        return "reaction";
+    if (item.postback)
+        return "postback";
+    if (item.read)
+        return "read";
+    if (item.referral)
+        return "referral";
+    if (item.optin)
+        return "optin";
+    if (item.pass_thread_control || item.take_thread_control || item.request_thread_control) {
+        return "handover";
+    }
+    return "unknown";
+}
+function deliveryIdentity(event) {
+    const item = event.messaging;
+    if (!item)
+        return sha256Json(event);
+    const prefix = `${event.instagram_user_id}:${event.source}`;
+    if (item.message)
+        return `${prefix}:message:${item.message.mid}:${event.event_type}`;
+    if (item.message_edit) {
+        return `${prefix}:edit:${item.message_edit.mid}:${item.message_edit.num_edit}`;
+    }
+    if (item.reaction) {
+        return `${prefix}:reaction:${item.reaction.mid}:${item.sender.id}:${item.reaction.action}`;
+    }
+    if (item.postback)
+        return `${prefix}:postback:${item.postback.mid}:${item.sender.id}`;
+    if (item.read)
+        return `${prefix}:read:${item.read.mid}:${item.sender.id}`;
+    return `${prefix}:${classify(item)}:${item.timestamp}:${sha256Json(item.raw)}`;
+}
+function requireTimestamp(value, field) {
+    const timestamp = requireNumber(value, field);
+    if (!Number.isSafeInteger(timestamp) || timestamp < 0) {
+        invalid(`${field} 必须是非负毫秒时间戳安全整数`);
+    }
+    return timestamp;
+}
+function optionalBoolean(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        invalid(`${field} 必须是 boolean`);
+    return value;
+}
+function invalid(message) {
+    throw InstagramError.invalid(message);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@onebots/adapter-instagram",
+  "version": "0.1.0",
+  "description": "OneBots Instagram Messaging 与 Instagram Graph API 适配器",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "keywords": [
+    "onebots",
+    "instagram",
+    "messaging",
+    "meta",
+    "adapter"
+  ],
+  "author": "凉菜",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "/lib/**/*.js",
+    "/lib/**/*.d.ts",
+    "!lib/**/*.spec.*",
+    "!lib/**/*.test.*",
+    "!lib/**/__tests__/**"
+  ],
+  "dependencies": {
+    "@onebots/meta": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsc-alias": "latest",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "onebots": "1.2.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lc-cn/onebots.git"
+  },
+  "scripts": {
+    "build": "rm -f *.tsbuildinfo && tsc --project tsconfig.json && tsc-alias -p tsconfig.json",
+    "clean": "rm -rf lib *.tsbuildinfo"
+  }
+}