@imessaging/avito 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@imessaging/avito",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Avito Messenger transport for imessaging",
+  "keywords": [
+    "avito",
+    "messaging",
+    "messenger",
+    "transport"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iconicompany/imessaging.git",
+    "directory": "packages/avito"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "bunx tsgo --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@imessaging/core": "^0.8.14"
+  }
+}

package/src/avito-transport.ts

@@ -0,0 +1,520 @@
+import type {
+  CursorStore,
+  IncomingAttachment,
+  IncomingLink,
+  IncomingMessage,
+  IncomingMessageKind,
+  IncomingMessageTransport,
+  MessageRecipient,
+  MessageTransport,
+  OutboundMessage,
+  ReadReceiptTransport,
+  SelfAccount,
+  SelfAwareTransport,
+  SendResult,
+  TransportStatus,
+} from "@imessaging/core";
+import { formattedOf, MemoryCursorStore, toPlainText } from "@imessaging/core";
+
+const DEFAULT_API_BASE_URL = "https://api.avito.ru";
+const DEFAULT_POLL_INTERVAL_MS = 30_000;
+/** Пределы API: `limit` до 100, `offset` до 1000. */
+const PAGE_LIMIT = 100;
+const MAX_OFFSET = 1000;
+/** Предел текста сообщения в API Avito. */
+const MAX_TEXT_LENGTH = 1000;
+/** Токен обновляется заранее, чтобы не истёк посреди запроса. */
+const TOKEN_MARGIN_MS = 60_000;
+const VOICE_PREFIX = "voice:";
+
+type Handler = (message: IncomingMessage) => void | Promise<void>;
+
+export type AvitoTransportOptions = {
+  accountId: string;
+  /** Учётка приложения Avito (client_credentials). Токен транспорт получает и обновляет сам. */
+  clientId: string;
+  clientSecret: string;
+  /** Номер пользователя Avito. Не задан — берётся из `/core/v1/accounts/self` при connect. */
+  userId?: string;
+  /** Базовый URL API — позволяет проверить транспорт без сети. */
+  apiBaseUrl?: string;
+  /** Курсоры опроса чатов. По умолчанию в памяти: после рестарта опрос начинает с текущего момента. */
+  cursorStore?: CursorStore;
+  /** Пауза между проходами опроса; 0 — без таймера, проход только через `poll()`. */
+  pollIntervalMs?: number;
+};
+
+export class AvitoApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly payload: unknown,
+  ) {
+    super(`Avito API returned HTTP ${status}: ${payloadText(payload)}`);
+    this.name = "AvitoApiError";
+  }
+}
+
+type AvitoContent = {
+  text?: string | null;
+  image?: { sizes?: Record<string, string> } | null;
+  link?: { text?: string; url?: string } | null;
+  item?: { title?: string; item_url?: string } | null;
+  location?: { text?: string; title?: string } | null;
+  voice?: { voice_id?: string } | null;
+};
+
+type AvitoMessage = {
+  id: string;
+  author_id?: number;
+  created: number;
+  direction?: "in" | "out";
+  type?: string;
+  content?: AvitoContent;
+  quote?: { id?: string } | null;
+};
+
+type AvitoChat = {
+  id: string;
+  updated?: number;
+  context?: { type?: string; value?: { title?: string } };
+  users?: { id?: number; name?: string }[];
+  last_message?: { id?: string; created?: number } | null;
+};
+
+/** Курсор чата: время последнего выданного сообщения и номера сообщений с этим временем (секунды совпадают). */
+type ChatCursor = { t: number; ids: string[] };
+
+/**
+ * Avito Messenger: чаты по объявлениям и между пользователями.
+ * Входящие — опросом списка чатов или через `handleWebhook`; дубли отсекаются курсором чата.
+ * Правки сообщений API Avito не поддерживает.
+ */
+export class AvitoTransport
+  implements MessageTransport, IncomingMessageTransport, ReadReceiptTransport, SelfAwareTransport
+{
+  readonly id: string;
+  private readonly apiBaseUrl: string;
+  private readonly cursors: CursorStore;
+  private readonly messageHandlers = new Set<Handler>();
+  private readonly chats = new Map<string, AvitoChat>();
+  private readonly chatLocks = new Map<string, Promise<void>>();
+  private userId?: string;
+  private me?: SelfAccount;
+  private token?: { value: string; expiresAt: number };
+  private connected = false;
+  private lastActivityAt?: Date;
+  private error?: string;
+  private pollTimer?: ReturnType<typeof setTimeout>;
+  private polling?: Promise<void>;
+
+  constructor(private readonly options: AvitoTransportOptions) {
+    if (!options.accountId.trim()) throw new Error("accountId must not be empty");
+    if (!options.clientId.trim()) throw new Error("clientId must not be empty");
+    if (!options.clientSecret.trim()) throw new Error("clientSecret must not be empty");
+    this.id = `avito:${options.accountId}`;
+    this.apiBaseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/u, "");
+    this.cursors = options.cursorStore ?? new MemoryCursorStore();
+    this.userId = options.userId?.trim() || undefined;
+  }
+
+  async connect(): Promise<void> {
+    try {
+      await this.self();
+      this.connected = true;
+      this.error = undefined;
+      this.schedulePoll(0);
+    } catch (cause) {
+      this.connected = false;
+      this.error = messageOf(cause);
+      throw cause;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+    clearTimeout(this.pollTimer);
+    this.pollTimer = undefined;
+    await this.polling;
+  }
+
+  async self(): Promise<SelfAccount> {
+    if (!this.me) {
+      const me = await this.request<{ id?: number | string; name?: string }>(
+        "/core/v1/accounts/self",
+      );
+      const id = String(me.id ?? "");
+      if (this.userId && this.userId !== id) {
+        throw new Error(`Avito token belongs to user ${id}, not configured userId ${this.userId}`);
+      }
+      this.userId = id;
+      this.me = { id, isBot: false };
+    }
+    return this.me;
+  }
+
+  async send(message: OutboundMessage): Promise<SendResult> {
+    if (!this.connected) throw new Error(`${this.id} is not connected`);
+    const chatId = avitoChatId(this.id, message.recipient);
+    if (message.documents?.length) throw new Error(`${this.id} does not send documents`);
+    const ft = formattedOf(message);
+    const text = ft ? toPlainText(ft) : message.text;
+    if (!text.trim()) throw new Error("Avito message text must not be empty");
+    if (text.length > MAX_TEXT_LENGTH) {
+      throw new Error(`Avito message text exceeds ${MAX_TEXT_LENGTH} characters`);
+    }
+
+    try {
+      const result = await this.request<{ id?: string }>(
+        `${this.accountPath("v1")}/chats/${encodeURIComponent(chatId)}/messages`,
+        json("POST", { message: { text }, type: "text" }),
+      );
+      this.lastActivityAt = new Date();
+      return { transportId: this.id, messageId: String(result.id ?? ""), recipientId: chatId };
+    } catch (cause) {
+      this.error = messageOf(cause);
+      throw cause;
+    }
+  }
+
+  /** Avito отмечает прочитанным чат целиком; `messageId` не используется. */
+  async markRead(recipient: MessageRecipient, _messageId: string): Promise<void> {
+    const chatId = avitoChatId(this.id, recipient);
+    await this.request(`${this.accountPath("v1")}/chats/${encodeURIComponent(chatId)}/read`, {
+      method: "POST",
+    });
+  }
+
+  onMessage(handler: Handler): () => void {
+    this.messageHandlers.add(handler);
+    this.schedulePoll(0);
+    return () => {
+      this.messageHandlers.delete(handler);
+    };
+  }
+
+  /** Картинка — прямой адрес; голосовое — `voice:<voice_id>`, адрес выдаёт API. */
+  async download(attachment: IncomingAttachment): Promise<Uint8Array> {
+    let url = attachment.id;
+    if (url.startsWith(VOICE_PREFIX)) {
+      const voiceId = url.slice(VOICE_PREFIX.length);
+      const files = await this.request<{ voices_urls?: Record<string, string> }>(
+        `${this.accountPath("v1")}/getVoiceFiles?voice_ids=${encodeURIComponent(voiceId)}`,
+      );
+      const voiceUrl = files.voices_urls?.[voiceId];
+      if (!voiceUrl) throw new Error(`Avito did not return a URL for voice ${voiceId}`);
+      url = voiceUrl;
+    }
+    const response = await fetch(url);
+    if (!response.ok) throw new AvitoApiError(response.status, await readPayload(response));
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  /** Включить вебхуки учётки. Адрес должен отвечать 200 за 2 секунды. */
+  async subscribeWebhook(url: string): Promise<void> {
+    await this.request("/messenger/v3/webhook", json("POST", { url }));
+  }
+
+  /** Тело вебхука v3. Сообщение берётся из API по курсору чата: так опрос и вебхук не выдают его дважды. */
+  async handleWebhook(body: unknown): Promise<void> {
+    const event = body as { payload?: { type?: string; value?: { chat_id?: string } } };
+    const chatId = event?.payload?.value?.chat_id;
+    if (event?.payload?.type !== "message" || typeof chatId !== "string" || !chatId) return;
+    await this.syncChat(chatId);
+  }
+
+  /** Один проход опроса: все чаты, у которых последнее сообщение новее курсора. */
+  async poll(): Promise<void> {
+    if (this.polling) return this.polling;
+    this.polling = this.pollOnce().finally(() => {
+      this.polling = undefined;
+    });
+    return this.polling;
+  }
+
+  async getStatus(): Promise<TransportStatus> {
+    return {
+      connected: this.connected,
+      transportId: this.id,
+      accountId: this.options.accountId,
+      lastActivityAt: this.lastActivityAt,
+      error: this.error,
+    };
+  }
+
+  private schedulePoll(delayMs: number): void {
+    const interval = this.options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (!this.connected || interval <= 0 || this.messageHandlers.size === 0 || this.pollTimer) {
+      return;
+    }
+    this.pollTimer = setTimeout(async () => {
+      try {
+        await this.poll();
+      } catch (cause) {
+        this.error = messageOf(cause);
+      }
+      this.pollTimer = undefined;
+      this.schedulePoll(interval);
+    }, delayMs);
+  }
+
+  private async pollOnce(): Promise<void> {
+    await this.self();
+    await this.since();
+    for (let offset = 0; offset <= MAX_OFFSET; offset += PAGE_LIMIT) {
+      const list = await this.request<{ chats?: AvitoChat[] }>(
+        `${this.accountPath("v2")}/chats?chat_types=u2i,u2u&limit=${PAGE_LIMIT}&offset=${offset}`,
+      );
+      const chats = list.chats ?? [];
+      for (const chat of chats) {
+        this.chats.set(chat.id, chat);
+        const last = chat.last_message;
+        if (!last?.id || last.created === undefined) continue;
+        const cursor = await this.cursor(chat.id);
+        if (cursor && !isNewer(cursor, last.created, last.id)) continue;
+        await this.syncChat(chat.id);
+      }
+      if (chats.length < PAGE_LIMIT) break;
+    }
+  }
+
+  /** Время первого запуска (секунды): без курсора чата старее него ничего не выдаётся. */
+  private async since(): Promise<number> {
+    const key = `${this.id}:since`;
+    const stored = await this.cursors.get(key);
+    if (stored) return Number(stored);
+    const now = Math.floor(Date.now() / 1000);
+    await this.cursors.set(key, String(now));
+    return now;
+  }
+
+  private syncChat(chatId: string): Promise<void> {
+    const previous = this.chatLocks.get(chatId) ?? Promise.resolve();
+    const next = previous.then(() => this.syncChatNow(chatId));
+    const settled = next.catch(() => undefined);
+    this.chatLocks.set(chatId, settled);
+    void settled.then(() => {
+      if (this.chatLocks.get(chatId) === settled) this.chatLocks.delete(chatId);
+    });
+    return next;
+  }
+
+  private async syncChatNow(chatId: string): Promise<void> {
+    await this.self();
+    const cursor = (await this.cursor(chatId)) ?? { t: await this.since(), ids: [] };
+    const fresh: AvitoMessage[] = [];
+    // Сообщения идут от новых к старым; листаем, пока не дойдём до курсора.
+    for (let offset = 0; offset <= MAX_OFFSET; offset += PAGE_LIMIT) {
+      const page = await this.request<AvitoMessage[] | { messages?: AvitoMessage[] }>(
+        `${this.accountPath("v3")}/chats/${encodeURIComponent(chatId)}/messages/?limit=${PAGE_LIMIT}&offset=${offset}`,
+      );
+      const messages = Array.isArray(page) ? page : (page.messages ?? []);
+      const newer = messages.filter((m) => isNewer(cursor, m.created, m.id));
+      fresh.push(...newer);
+      if (messages.length < PAGE_LIMIT || newer.length < messages.length) break;
+    }
+    if (fresh.length === 0) return;
+
+    const chat = await this.chatInfo(chatId);
+    let next = cursor;
+    for (const message of fresh.sort((a, b) => a.created - b.created)) {
+      if (message.direction === "in" && message.type !== "system" && message.type !== "deleted") {
+        await this.dispatch(this.incoming(chatId, chat, message));
+      }
+      next =
+        next.t === message.created
+          ? { t: next.t, ids: [...next.ids, message.id] }
+          : { t: message.created, ids: [message.id] };
+      await this.cursors.set(this.cursorKey(chatId), JSON.stringify(next));
+    }
+  }
+
+  private async dispatch(message: IncomingMessage): Promise<void> {
+    this.lastActivityAt = new Date();
+    for (const handler of this.messageHandlers) {
+      try {
+        await handler(message);
+      } catch (cause) {
+        // Сообщение не повторяется: иначе одно «ядовитое» остановило бы чат навсегда.
+        this.error = messageOf(cause);
+      }
+    }
+  }
+
+  /** Сведения о чате нужны для имени собеседника и заголовка; вебхук их не несёт. */
+  private async chatInfo(chatId: string): Promise<AvitoChat | undefined> {
+    const known = this.chats.get(chatId);
+    if (known) return known;
+    try {
+      const chat = await this.request<AvitoChat>(
+        `${this.accountPath("v2")}/chats/${encodeURIComponent(chatId)}`,
+      );
+      this.chats.set(chatId, chat);
+      return chat;
+    } catch (cause) {
+      this.error = messageOf(cause);
+      return undefined;
+    }
+  }
+
+  private incoming(
+    chatId: string,
+    chat: AvitoChat | undefined,
+    message: AvitoMessage,
+  ): IncomingMessage {
+    const content = message.content ?? {};
+    const sender = chat?.users?.find((user) => user.id === message.author_id);
+    const attachments: IncomingAttachment[] = [];
+    const image = largestImage(content.image?.sizes);
+    if (image) attachments.push({ id: image, filename: "image.jpg", mimeType: "image/jpeg" });
+    if (content.voice?.voice_id) {
+      attachments.push({ id: `${VOICE_PREFIX}${content.voice.voice_id}`, filename: "voice" });
+    }
+    const links: IncomingLink[] = [];
+    if (content.link?.url)
+      links.push({ url: content.link.url, label: content.link.text, origin: "preview" });
+    if (content.item?.item_url)
+      links.push({ url: content.item.item_url, label: content.item.title, origin: "preview" });
+
+    return {
+      transportId: this.id,
+      accountId: this.options.accountId,
+      chatId,
+      chatType: "user",
+      senderId: message.author_id === undefined ? null : String(message.author_id),
+      senderName: sender?.name,
+      chatTitle: chat?.context?.value?.title ?? sender?.name,
+      messageId: message.id,
+      text:
+        content.text ??
+        content.link?.text ??
+        content.location?.text ??
+        content.location?.title ??
+        content.item?.title ??
+        "",
+      kind: kindOf(message.type),
+      sentAt: new Date(message.created * 1000),
+      outgoing: false,
+      attachments,
+      links: links.length > 0 ? links : undefined,
+      replyToMessageId: message.quote?.id,
+    };
+  }
+
+  private async cursor(chatId: string): Promise<ChatCursor | null> {
+    const stored = await this.cursors.get(this.cursorKey(chatId));
+    return stored ? (JSON.parse(stored) as ChatCursor) : null;
+  }
+
+  private cursorKey(chatId: string): string {
+    return `${this.id}:chat:${chatId}`;
+  }
+
+  private accountPath(version: "v1" | "v2" | "v3"): string {
+    if (!this.userId) throw new Error(`${this.id} has no userId: call connect() first`);
+    return `/messenger/${version}/accounts/${encodeURIComponent(this.userId)}`;
+  }
+
+  private async request<T = Record<string, never>>(path: string, init?: RequestInit): Promise<T> {
+    const attempt = async () =>
+      fetch(`${this.apiBaseUrl}${path}`, {
+        ...init,
+        headers: { Authorization: `Bearer ${await this.accessToken()}`, ...init?.headers },
+      });
+    let response = await attempt();
+    if (response.status === 401) {
+      // Токен отозван раньше срока: получить новый и повторить один раз.
+      await response.body?.cancel();
+      this.token = undefined;
+      response = await attempt();
+    }
+    const payload = await readPayload(response);
+    if (!response.ok) throw new AvitoApiError(response.status, payload);
+    return payload as T;
+  }
+
+  private async accessToken(): Promise<string> {
+    if (this.token && this.token.expiresAt > Date.now() + TOKEN_MARGIN_MS) return this.token.value;
+    const response = await fetch(`${this.apiBaseUrl}/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "client_credentials",
+        client_id: this.options.clientId,
+        client_secret: this.options.clientSecret,
+      }).toString(),
+    });
+    const payload = (await readPayload(response)) as { access_token?: string; expires_in?: number };
+    if (!response.ok || !payload.access_token) throw new AvitoApiError(response.status, payload);
+    this.token = {
+      value: payload.access_token,
+      expiresAt: Date.now() + (payload.expires_in ?? 86_400) * 1000,
+    };
+    return this.token.value;
+  }
+}
+
+function avitoChatId(transportId: string, recipient: MessageRecipient): string {
+  // Ответ на входящее: шлюз адресует `{ type: "user", id: message.chatId }`, как в Telegram и MAX.
+  if (recipient.type !== "avito" && recipient.type !== "user") {
+    throw new Error(`${transportId} sends Avito messages and cannot address ${recipient.type}`);
+  }
+  const chatId = ("id" in recipient ? recipient.id : recipient.chatId).trim();
+  if (!chatId) throw new Error("Avito chatId must not be empty");
+  return chatId;
+}
+
+function isNewer(cursor: ChatCursor, created: number, id: string): boolean {
+  return created > cursor.t || (created === cursor.t && !cursor.ids.includes(id));
+}
+
+function kindOf(type: string | undefined): IncomingMessageKind {
+  switch (type) {
+    case "text":
+    case "link":
+      return "text";
+    case "image":
+      return "photo";
+    case "voice":
+      return "voice";
+    case "location":
+      return "geo";
+    case undefined:
+      return "unsupported";
+    default:
+      return "other";
+  }
+}
+
+/** Ключи вида `1280x960`; берётся самая большая картинка. */
+function largestImage(sizes: Record<string, string> | undefined): string | undefined {
+  if (!sizes) return undefined;
+  const area = (key: string) => key.split("x").reduce((product, side) => product * Number(side), 1);
+  const best = Object.keys(sizes).sort((a, b) => area(b) - area(a))[0];
+  return best ? sizes[best] : undefined;
+}
+
+function json(method: string, body: unknown): RequestInit {
+  return {
+    method,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  };
+}
+
+async function readPayload(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function payloadText(value: unknown): string {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+function messageOf(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { AvitoApiError, AvitoTransport, type AvitoTransportOptions } from "./avito-transport";

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.