itd-api 0.1.0 → 0.3.0

package/dist/multi-storage-BhcA2Izn.d.ts

@@ -0,0 +1,198 @@
+import { r as TokenStorage, t as ItdSession } from "./storage-BjNRlkbE.js";
+//#region src/core/attachments.d.ts
+/** Способ передачи содержимого вложения. */
+declare const FileTransferMode: Readonly<{
+  /** Сначала получить файл целиком, затем отправить его как `Blob`. */
+  readonly Buffer: "buffer";
+  /** Передавать данные по мере чтения, не собирая файл целиком в памяти. */
+  readonly Stream: "stream";
+}>;
+type FileTransferMode = (typeof FileTransferMode)[keyof typeof FileTransferMode];
+/** Размер очереди потокового вложения по умолчанию — 4 МиБ. */
+declare const DEFAULT_FILE_STREAM_BUFFER_BYTES: number;
+/** Предел размера файла, скачиваемого по адресу, — 100 МиБ. */
+declare const DEFAULT_URL_FILE_MAX_BYTES: number;
+/** Что доступно источнику при открытии файла. */
+interface FileContext {
+  /** Общая отмена текущей попытки, включая её таймаут. */
+  signal?: AbortSignal | undefined;
+  /** `fetch` клиента — с переданными пользователем настройками. */
+  fetch: typeof fetch;
+  /** Номер попытки отправки, начиная с 1. */
+  attempt: number;
+}
+/** Готовое содержимое файла. */
+interface FileContent {
+  file: Blob | ArrayBuffer | Uint8Array;
+  /** Имя влияет на определение MIME, если `contentType` не задан. */
+  filename?: string | undefined;
+  /** MIME без параметров. Если не указан, определяется по имени или `Blob`. */
+  contentType?: string | undefined;
+}
+/** Открытый поток файла. */
+interface FileStreamContent {
+  stream: ReadableStream<Uint8Array>;
+  filename?: string | undefined;
+  contentType?: string | undefined;
+  /** Размер, если он известен до чтения. */
+  size?: number | undefined;
+  /** Освобождает внешний ресурс после завершения попытки. */
+  close?: (() => void | Promise<void>) | undefined;
+}
+/** Буферный источник, который вычисляется непосредственно перед первой попыткой. */
+interface LazyFile {
+  load: (context: FileContext) => FileContent | Promise<FileContent>;
+}
+/**
+ * Повторяемый потоковый источник.
+ *
+ * `open` вызывается для каждой попытки отправки. Он обязан возвращать новый поток:
+ * уже прочитанный `ReadableStream` повторно использовать нельзя.
+ */
+interface StreamFile {
+  open: (context: FileContext) => FileStreamContent | Promise<FileStreamContent>;
+}
+/** Общие настройки потоковой передачи. */
+interface FileStreamOptions {
+  /** Буферный или потоковый режим. По умолчанию `'buffer'`. */
+  mode?: FileTransferMode | undefined;
+  /** Максимальный размер файла. Без значения размер не ограничивается. */
+  maxBytes?: number | undefined;
+  /**
+   * Верхняя граница очереди, которой управляет библиотека. По умолчанию 4 МиБ.
+   *
+   * Сетевой рантайм может иметь собственные внутренние буферы сверх этого значения.
+   */
+  streamBufferBytes?: number | undefined;
+}
+/** Файл, который нужно получить по HTTP(S). */
+interface UrlFile extends UrlFileOptions {
+  url: string;
+}
+/** Настройки файла по HTTP(S). */
+interface UrlFileOptions extends FileStreamOptions {
+  filename?: string | undefined;
+  /** По умолчанию берётся из `Content-Type` ответа. */
+  contentType?: string | undefined;
+}
+/** Файл для загрузки. Голый поток не принимается, потому что его нельзя повторить. */
+type FileInput = Blob | ArrayBuffer | Uint8Array | FileContent | UrlFile | LazyFile | StreamFile;
+/** Настройки фабрики пользовательского потока. */
+interface FromStreamOptions extends Omit<FileStreamOptions, 'mode'> {
+  filename?: string | undefined;
+  contentType?: string | undefined;
+  /** Размер, если он известен заранее. */
+  size?: number | undefined;
+}
+/** Создаёт URL-источник в выбранном режиме. */
+declare function fromUrl(url: string, options: UrlFileOptions & {
+  mode: typeof FileTransferMode.Stream;
+}): StreamFile;
+declare function fromUrl(url: string, options?: UrlFileOptions & {
+  mode?: typeof FileTransferMode.Buffer;
+}): LazyFile;
+declare function fromUrl(url: string, options: UrlFileOptions): LazyFile | StreamFile;
+/**
+ * Создаёт повторяемый пользовательский поток.
+ *
+ * Фабрика вызывается заново для каждой попытки; возвращать один и тот же поток нельзя.
+ */
+declare function fromStream(factory: (context: FileContext) => ReadableStream<Uint8Array> | FileStreamContent | Promise<ReadableStream<Uint8Array> | FileStreamContent>, options?: FromStreamOptions): StreamFile;
+//#endregion
+//#region src/core/multi-storage.d.ts
+/**
+ * Хранилище сессий нескольких аккаунтов.
+ *
+ * Отличается от {@link TokenStorage} тем, что каждый метод получает **имя аккаунта**:
+ * так адаптер сам решает, как строить ключ, и Redis, БД или связка ключей получают то,
+ * что им нужно. Имя приходит ровно тем, под которым аккаунт заведён в {@link ItdAccounts}:
+ * библиотека его не нормализует и не экранирует — префиксы, экранирование и ограничения
+ * на длину ключа остаются за адаптером.
+ *
+ * Все методы могут быть как синхронными, так и асинхронными.
+ *
+ * @example Своё хранилище поверх Redis
+ * ```ts
+ * const storage = createMultiTokenStorage({
+ *   get: async (account) => JSON.parse((await redis.get(`itd:session:${account}`)) ?? 'null'),
+ *   set: async (account, session) => {
+ *     await redis.set(`itd:session:${account}`, JSON.stringify(session));
+ *     await redis.sadd('itd:accounts', account);
+ *   },
+ *   clear: async (account) => {
+ *     await redis.del(`itd:session:${account}`);
+ *     await redis.srem('itd:accounts', account);
+ *   },
+ *   accounts: () => redis.smembers('itd:accounts'),
+ * });
+ * ```
+ */
+interface MultiTokenStorage {
+  /** Прочитать сессию аккаунта. `null`, если её нет. */
+  get(account: string): ItdSession | null | Promise<ItdSession | null>;
+  /** Сохранить сессию аккаунта целиком. */
+  set(account: string, session: ItdSession): void | Promise<void>;
+  /** Удалить сессию аккаунта. Вызывается при выходе и при неудачном обновлении токена. */
+  clear(account: string): void | Promise<void>;
+  /**
+   * Имена сохранённых записей — по ним `ItdAccounts.restore()` находит кандидатов
+   * после перезапуска процесса.
+   *
+   * Список ведёт сам адаптер: у файлового и памятного он виден из самой записи,
+   * а хранилищу «ключ — значение» придётся держать множество имён рядом с сессиями.
+   * Перед восстановлением контейнер читает каждую запись и пропускает оставшийся после
+   * выхода одинокий `deviceId`: без токена или refresh-сессии авторизоваться невозможно.
+   * Пустой список означает лишь то, что кандидатов нет, — сами записи при этом могут быть
+   * доступны по имени.
+   */
+  accounts(): readonly string[] | Promise<readonly string[]>;
+}
+/**
+ * Срез мультихранилища как обычное {@link TokenStorage} — в таком виде его получает
+ * отдельный `ItdClient`, который про соседние аккаунты ничего не знает.
+ */
+declare function scopedTokenStorage(storage: MultiTokenStorage, account: string): TokenStorage;
+/**
+ * Мультихранилище в памяти процесса — вариант по умолчанию.
+ *
+ * Сессии теряются при перезапуске. Для долгоживущих ботов возьмите `FileMultiTokenStorage`
+ * из `itd-api/node` либо соберите своё через {@link createMultiTokenStorage}.
+ */
+declare class MemoryMultiTokenStorage implements MultiTokenStorage {
+  #private;
+  constructor(initial?: Readonly<Record<string, ItdSession>> | null);
+  get(account: string): ItdSession | null;
+  set(account: string, session: ItdSession): void;
+  clear(account: string): void;
+  accounts(): string[];
+}
+/**
+ * Собирает {@link MultiTokenStorage} из четырёх функций — когда заводить класс избыточно.
+ * Аналог `createTokenStorage` для нескольких аккаунтов.
+ */
+declare function createMultiTokenStorage(handlers: MultiTokenStorage): MultiTokenStorage;
+/** Источник, который читается и пишется целиком: файл, ключ в `localStorage`, строка в БД. */
+interface RecordStorageSource {
+  /** Прочитать все сессии разом. `null` — записи ещё нет. */
+  read(): Promise<Record<string, ItdSession> | null>;
+  /** Записать все сессии разом. */
+  write(record: Record<string, ItdSession>): Promise<void>;
+  /** Вызывается вместо {@link RecordStorageSource.write}, когда не осталось ни одной сессии. */
+  remove?(): Promise<void>;
+}
+/**
+ * Мультихранилище поверх источника, который читается и пишется целиком.
+ *
+ * Решает главную проблему такого способа хранения — **гонку «прочитать, изменить,
+ * записать»**: десять аккаунтов пишут в одну запись, и наивная реализация теряла бы
+ * чужие сессии. Источник читается один раз, дальше слепок живёт в памяти, а записи
+ * выстраиваются в цепочку и идут по очереди.
+ *
+ * Внутри процесса этого достаточно. Несколько процессов, пишущих в одну запись,
+ * по-прежнему затирают друг друга — как и несколько экземпляров этого адаптера,
+ * направленных на один источник в одном процессе.
+ */
+declare function createRecordMultiStorage(source: RecordStorageSource): MultiTokenStorage;
+//#endregion
+export { StreamFile as _, createRecordMultiStorage as a, fromStream as b, DEFAULT_URL_FILE_MAX_BYTES as c, FileInput as d, FileStreamContent as f, LazyFile as g, FromStreamOptions as h, createMultiTokenStorage as i, FileContent as l, FileTransferMode as m, MultiTokenStorage as n, scopedTokenStorage as o, FileStreamOptions as p, RecordStorageSource as r, DEFAULT_FILE_STREAM_BUFFER_BYTES as s, MemoryMultiTokenStorage as t, FileContext as u, UrlFile as v, fromUrl as x, UrlFileOptions as y };
+//# sourceMappingURL=multi-storage-BhcA2Izn.d.ts.map