itd-api 0.7.0 → 0.7.1

package/dist/shared/auth-provider-BfogACAb.js

@@ -0,0 +1,91 @@
+import { et as createDeviceId } from "./url-CYXgxqGx.js";
+//#region src/core/auth-provider.ts
+/**
+* Идентификатор устройства, общий для провайдеров без сессии.
+*
+* Значение своё у каждого провайдера: сервер различает по нему записи в списке сессий,
+* поэтому делить его между клиентами нельзя. Хранилища нет, так что перезапуск процесса
+* значение не переживает — в этом и разница с полноценной сессией.
+*/
+function localDeviceId() {
+	let deviceId;
+	return () => {
+		deviceId ??= createDeviceId();
+		return Promise.resolve(deviceId);
+	};
+}
+/**
+* Авторизации нет: заголовок не подставляется, ответ `401` не восстанавливается.
+*
+* @example
+* ```ts
+* const api = createRestClient(); // публичные эндпоинты доступны и без токена
+* ```
+*/
+function anonymousAuth() {
+	return {
+		token: () => Promise.resolve(null),
+		prepare: () => Promise.resolve(),
+		currentHeaders: () => ({}),
+		recover: () => Promise.resolve(false),
+		deviceId: localDeviceId(),
+		dispose: () => {}
+	};
+}
+/**
+* Готовый Bearer-токен: ни хранилища, ни продления.
+*
+* Ответ `401` уходит вызывающему коду как есть — обновить токен провайдеру нечем.
+* Для сессии, которая продлевает себя сама, нужен полный клиент.
+*
+* @example
+* ```ts
+* const api = createRestClient({ auth: bearerToken(process.env.ITD_TOKEN) });
+* ```
+*/
+function bearerToken(accessToken) {
+	const headers = { Authorization: `Bearer ${accessToken}` };
+	return {
+		token: () => Promise.resolve(accessToken),
+		prepare: () => Promise.resolve(),
+		currentHeaders: () => headers,
+		recover: () => Promise.resolve(false),
+		deviceId: localDeviceId(),
+		dispose: () => {}
+	};
+}
+/**
+* Токен из внешнего источника — хранилища секретов, кэша, соседнего сервиса.
+*
+* Источник спрашивается на стадии подготовки, до входа в очередь: там ожидание безопасно,
+* а слот транспорта ещё не занят. Значение держится до следующей подготовки, потому что
+* подстановка заголовков обязана быть синхронной.
+*
+* @example
+* ```ts
+* const api = createRestClient({ auth: tokenProvider(() => vault.read('itd')) });
+* ```
+*/
+function tokenProvider(getToken) {
+	let cached = null;
+	const read = async () => {
+		cached = await getToken();
+		return cached;
+	};
+	return {
+		token: read,
+		prepare: async () => {
+			await read();
+		},
+		currentHeaders: () => cached ? { Authorization: `Bearer ${cached}` } : {},
+		recover: () => Promise.resolve(false),
+		deviceId: localDeviceId(),
+		dispose: () => {
+			cached = null;
+		}
+	};
+}
+//#endregion
+export { bearerToken as n, tokenProvider as r, anonymousAuth as t };
+
+//# sourceMappingURL=auth-provider-BfogACAb.js.map

package/dist/shared/auth-provider-BfogACAb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provider-BfogACAb.js","names":[],"sources":["../../src/core/auth-provider.ts"],"sourcesContent":["import type { UserId } from '../models/common.js';\nimport type { ResolvedRuntimeConfig } from './config.js';\nimport type { CookieJar } from './cookies.js';\nimport type { RequestHandler } from './execution/pipeline.js';\nimport { createDeviceId } from './runtime.js';\n\n/** Области аккаунта и конкретной сессии для локального состояния плагинов. */\nexport interface AuthIdentity {\n  /** Идентификатор пользователя; отсутствует у непрозрачного или повреждённого токена. */\n  userId?: UserId | undefined;\n  /** Идентификатор серверной сессии; отсутствует у непрозрачного или повреждённого токена. */\n  sessionId?: string | undefined;\n}\n\n/**\n * Что конвейер запросов спрашивает у авторизации.\n *\n * Узкий контракт вместо полноценного менеджера сессии: pipeline не должен знать ни про\n * refresh-токены, ни про хранилище, ни про вход по паролю. Благодаря этому клиент с готовым\n * токеном не тянет за собой сессионную машинерию — она подставляется вызывающим кодом.\n *\n * Каждый метод соответствует ровно одной стадии конвейера. Готовые реализации —\n * {@link bearerToken}, {@link tokenProvider} и {@link anonymousAuth}.\n */\nexport interface AuthProvider {\n  /**\n   * Текущий токен доступа.\n   *\n   * Нужен там, где заголовок не поставить: SSE в браузере и WebSocket передают токен\n   * параметром адреса. Конвейеру запросов достаточно {@link currentHeaders}.\n   */\n  token(): Promise<string | null>;\n  /**\n   * Готовит состояние авторизации до входа транспортной попытки в очередь.\n   *\n   * Чтение хранилища, обращение к внешнему источнику токена и отложенный вход асинхронны,\n   * поэтому обязаны завершиться до захвата слота очереди.\n   */\n  prepare(): Promise<void>;\n  /**\n   * Заголовки уже подготовленной авторизации.\n   *\n   * Синхронность существенна: слой стоит внутри очереди, непосредственно перед транспортом,\n   * и не должен запускать I/O. Зато запрос, отстоявший в очереди, получает самый свежий токен.\n   */\n  currentHeaders(): Record<string, string>;\n  /**\n   * Реакция на ответ `401`.\n   *\n   * @returns `true`, если токен обновлён и повторять попытку имеет смысл\n   */\n  recover(): Promise<boolean>;\n  /** Значение заголовка `X-Device-Id`. Отправляется и с анонимными запросами. */\n  deviceId(): Promise<string>;\n  /** Снимает подписки при терминальном освобождении владельца. */\n  dispose(): void;\n}\n\n/**\n * Что фабрика авторизации получает от собранного runtime.\n *\n * `handler` — тот же обработчик, которым пользуются ресурсы: вход и продление проходят\n * через общий конвейер с точечными skip-флагами, а не через второй, независимо\n * эволюционирующий путь.\n *\n * @internal\n */\nexport interface AuthProviderDeps {\n  config: ResolvedRuntimeConfig;\n  handler: RequestHandler;\n  cookies: CookieJar;\n  /** Вызывается синхронно перед сменой владельца авторизации. */\n  onAccountChange?: (() => void) | undefined;\n}\n\n/**\n * Идентификатор устройства, общий для провайдеров без сессии.\n *\n * Значение своё у каждого провайдера: сервер различает по нему записи в списке сессий,\n * поэтому делить его между клиентами нельзя. Хранилища нет, так что перезапуск процесса\n * значение не переживает — в этом и разница с полноценной сессией.\n */\nfunction localDeviceId(): () => Promise<string> {\n  let deviceId: string | undefined;\n\n  return () => {\n    deviceId ??= createDeviceId();\n    return Promise.resolve(deviceId);\n  };\n}\n\n/**\n * Авторизации нет: заголовок не подставляется, ответ `401` не восстанавливается.\n *\n * @example\n * ```ts\n * const api = createRestClient(); // публичные эндпоинты доступны и без токена\n * ```\n */\nexport function anonymousAuth(): AuthProvider {\n  return {\n    token: () => Promise.resolve(null),\n    prepare: () => Promise.resolve(),\n    currentHeaders: () => ({}),\n    recover: () => Promise.resolve(false),\n    deviceId: localDeviceId(),\n    dispose: () => {},\n  };\n}\n\n/**\n * Готовый Bearer-токен: ни хранилища, ни продления.\n *\n * Ответ `401` уходит вызывающему коду как есть — обновить токен провайдеру нечем.\n * Для сессии, которая продлевает себя сама, нужен полный клиент.\n *\n * @example\n * ```ts\n * const api = createRestClient({ auth: bearerToken(process.env.ITD_TOKEN) });\n * ```\n */\nexport function bearerToken(accessToken: string): AuthProvider {\n  const headers = { Authorization: `Bearer ${accessToken}` };\n\n  return {\n    token: () => Promise.resolve(accessToken),\n    prepare: () => Promise.resolve(),\n    currentHeaders: () => headers,\n    recover: () => Promise.resolve(false),\n    deviceId: localDeviceId(),\n    dispose: () => {},\n  };\n}\n\n/**\n * Токен из внешнего источника — хранилища секретов, кэша, соседнего сервиса.\n *\n * Источник спрашивается на стадии подготовки, до входа в очередь: там ожидание безопасно,\n * а слот транспорта ещё не занят. Значение держится до следующей подготовки, потому что\n * подстановка заголовков обязана быть синхронной.\n *\n * @example\n * ```ts\n * const api = createRestClient({ auth: tokenProvider(() => vault.read('itd')) });\n * ```\n */\nexport function tokenProvider(\n  getToken: () => string | null | Promise<string | null>,\n): AuthProvider {\n  let cached: string | null = null;\n\n  const read = async () => {\n    cached = await getToken();\n    return cached;\n  };\n\n  return {\n    token: read,\n    prepare: async () => {\n      await read();\n    },\n    currentHeaders: () => (cached ? { Authorization: `Bearer ${cached}` } : {}),\n    recover: () => Promise.resolve(false),\n    deviceId: localDeviceId(),\n    dispose: () => {\n      cached = null;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AAkFA,SAAS,gBAAuC;CAC9C,IAAI;CAEJ,aAAa;EACX,aAAa,eAAe;EAC5B,OAAO,QAAQ,QAAQ,QAAQ;CACjC;AACF;;;;;;;;;AAUA,SAAgB,gBAA8B;CAC5C,OAAO;EACL,aAAa,QAAQ,QAAQ,IAAI;EACjC,eAAe,QAAQ,QAAQ;EAC/B,uBAAuB,CAAC;EACxB,eAAe,QAAQ,QAAQ,KAAK;EACpC,UAAU,cAAc;EACxB,eAAe,CAAC;CAClB;AACF;;;;;;;;;;;;AAaA,SAAgB,YAAY,aAAmC;CAC7D,MAAM,UAAU,EAAE,eAAe,UAAU,cAAc;CAEzD,OAAO;EACL,aAAa,QAAQ,QAAQ,WAAW;EACxC,eAAe,QAAQ,QAAQ;EAC/B,sBAAsB;EACtB,eAAe,QAAQ,QAAQ,KAAK;EACpC,UAAU,cAAc;EACxB,eAAe,CAAC;CAClB;AACF;;;;;;;;;;;;;AAcA,SAAgB,cACd,UACc;CACd,IAAI,SAAwB;CAE5B,MAAM,OAAO,YAAY;EACvB,SAAS,MAAM,SAAS;EACxB,OAAO;CACT;CAEA,OAAO;EACL,OAAO;EACP,SAAS,YAAY;GACnB,MAAM,KAAK;EACb;EACA,sBAAuB,SAAS,EAAE,eAAe,UAAU,SAAS,IAAI,CAAC;EACzE,eAAe,QAAQ,QAAQ,KAAK;EACpC,UAAU,cAAc;EACxB,eAAe;GACb,SAAS;EACX;CACF;AACF"}

package/dist/shared/auth-provider-CTJkKfgy.cjs

@@ -0,0 +1,108 @@
+const require_url = require("./url-yjl2c8Ie.cjs");
+//#region src/core/auth-provider.ts
+/**
+* Идентификатор устройства, общий для провайдеров без сессии.
+*
+* Значение своё у каждого провайдера: сервер различает по нему записи в списке сессий,
+* поэтому делить его между клиентами нельзя. Хранилища нет, так что перезапуск процесса
+* значение не переживает — в этом и разница с полноценной сессией.
+*/
+function localDeviceId() {
+	let deviceId;
+	return () => {
+		deviceId ??= require_url.createDeviceId();
+		return Promise.resolve(deviceId);
+	};
+}
+/**
+* Авторизации нет: заголовок не подставляется, ответ `401` не восстанавливается.
+*
+* @example
+* ```ts
+* const api = createRestClient(); // публичные эндпоинты доступны и без токена
+* ```
+*/
+function anonymousAuth() {
+	return {
+		token: () => Promise.resolve(null),
+		prepare: () => Promise.resolve(),
+		currentHeaders: () => ({}),
+		recover: () => Promise.resolve(false),
+		deviceId: localDeviceId(),
+		dispose: () => {}
+	};
+}
+/**
+* Готовый Bearer-токен: ни хранилища, ни продления.
+*
+* Ответ `401` уходит вызывающему коду как есть — обновить токен провайдеру нечем.
+* Для сессии, которая продлевает себя сама, нужен полный клиент.
+*
+* @example
+* ```ts
+* const api = createRestClient({ auth: bearerToken(process.env.ITD_TOKEN) });
+* ```
+*/
+function bearerToken(accessToken) {
+	const headers = { Authorization: `Bearer ${accessToken}` };
+	return {
+		token: () => Promise.resolve(accessToken),
+		prepare: () => Promise.resolve(),
+		currentHeaders: () => headers,
+		recover: () => Promise.resolve(false),
+		deviceId: localDeviceId(),
+		dispose: () => {}
+	};
+}
+/**
+* Токен из внешнего источника — хранилища секретов, кэша, соседнего сервиса.
+*
+* Источник спрашивается на стадии подготовки, до входа в очередь: там ожидание безопасно,
+* а слот транспорта ещё не занят. Значение держится до следующей подготовки, потому что
+* подстановка заголовков обязана быть синхронной.
+*
+* @example
+* ```ts
+* const api = createRestClient({ auth: tokenProvider(() => vault.read('itd')) });
+* ```
+*/
+function tokenProvider(getToken) {
+	let cached = null;
+	const read = async () => {
+		cached = await getToken();
+		return cached;
+	};
+	return {
+		token: read,
+		prepare: async () => {
+			await read();
+		},
+		currentHeaders: () => cached ? { Authorization: `Bearer ${cached}` } : {},
+		recover: () => Promise.resolve(false),
+		deviceId: localDeviceId(),
+		dispose: () => {
+			cached = null;
+		}
+	};
+}
+//#endregion
+Object.defineProperty(exports, "anonymousAuth", {
+	enumerable: true,
+	get: function() {
+		return anonymousAuth;
+	}
+});
+Object.defineProperty(exports, "bearerToken", {
+	enumerable: true,
+	get: function() {
+		return bearerToken;
+	}
+});
+Object.defineProperty(exports, "tokenProvider", {
+	enumerable: true,
+	get: function() {
+		return tokenProvider;
+	}
+});
+
+//# sourceMappingURL=auth-provider-CTJkKfgy.cjs.map

package/dist/shared/auth-provider-CTJkKfgy.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provider-CTJkKfgy.cjs","names":["createDeviceId"],"sources":["../../src/core/auth-provider.ts"],"sourcesContent":["import type { UserId } from '../models/common.js';\nimport type { ResolvedRuntimeConfig } from './config.js';\nimport type { CookieJar } from './cookies.js';\nimport type { RequestHandler } from './execution/pipeline.js';\nimport { createDeviceId } from './runtime.js';\n\n/** Области аккаунта и конкретной сессии для локального состояния плагинов. */\nexport interface AuthIdentity {\n  /** Идентификатор пользователя; отсутствует у непрозрачного или повреждённого токена. */\n  userId?: UserId | undefined;\n  /** Идентификатор серверной сессии; отсутствует у непрозрачного или повреждённого токена. */\n  sessionId?: string | undefined;\n}\n\n/**\n * Что конвейер запросов спрашивает у авторизации.\n *\n * Узкий контракт вместо полноценного менеджера сессии: pipeline не должен знать ни про\n * refresh-токены, ни про хранилище, ни про вход по паролю. Благодаря этому клиент с готовым\n * токеном не тянет за собой сессионную машинерию — она подставляется вызывающим кодом.\n *\n * Каждый метод соответствует ровно одной стадии конвейера. Готовые реализации —\n * {@link bearerToken}, {@link tokenProvider} и {@link anonymousAuth}.\n */\nexport interface AuthProvider {\n  /**\n   * Текущий токен доступа.\n   *\n   * Нужен там, где заголовок не поставить: SSE в браузере и WebSocket передают токен\n   * параметром адреса. Конвейеру запросов достаточно {@link currentHeaders}.\n   */\n  token(): Promise<string | null>;\n  /**\n   * Готовит состояние авторизации до входа транспортной попытки в очередь.\n   *\n   * Чтение хранилища, обращение к внешнему источнику токена и отложенный вход асинхронны,\n   * поэтому обязаны завершиться до захвата слота очереди.\n   */\n  prepare(): Promise<void>;\n  /**\n   * Заголовки уже подготовленной авторизации.\n   *\n   * Синхронность существенна: слой стоит внутри очереди, непосредственно перед транспортом,\n   * и не должен запускать I/O. Зато запрос, отстоявший в очереди, получает самый свежий токен.\n   */\n  currentHeaders(): Record<string, string>;\n  /**\n   * Реакция на ответ `401`.\n   *\n   * @returns `true`, если токен обновлён и повторять попытку имеет смысл\n   */\n  recover(): Promise<boolean>;\n  /** Значение заголовка `X-Device-Id`. Отправляется и с анонимными запросами. */\n  deviceId(): Promise<string>;\n  /** Снимает подписки при терминальном освобождении владельца. */\n  dispose(): void;\n}\n\n/**\n * Что фабрика авторизации получает от собранного runtime.\n *\n * `handler` — тот же обработчик, которым пользуются ресурсы: вход и продление проходят\n * через общий конвейер с точечными skip-флагами, а не через второй, независимо\n * эволюционирующий путь.\n *\n * @internal\n */\nexport interface AuthProviderDeps {\n  config: ResolvedRuntimeConfig;\n  handler: RequestHandler;\n  cookies: CookieJar;\n  /** Вызывается синхронно перед сменой владельца авторизации. */\n  onAccountChange?: (() => void) | undefined;\n}\n\n/**\n * Идентификатор устройства, общий для провайдеров без сессии.\n *\n * Значение своё у каждого провайдера: сервер различает по нему записи в списке сессий,\n * поэтому делить его между клиентами нельзя. Хранилища нет, так что перезапуск процесса\n * значение не переживает — в этом и разница с полноценной сессией.\n */\nfunction localDeviceId(): () => Promise<string> {\n  let deviceId: string | undefined;\n\n  return () => {\n    deviceId ??= createDeviceId();\n    return Promise.resolve(deviceId);\n  };\n}\n\n/**\n * Авторизации нет: заголовок не подставляется, ответ `401` не восстанавливается.\n *\n * @example\n * ```ts\n * const api = createRestClient(); // публичные эндпоинты доступны и без токена\n * ```\n */\nexport function anonymousAuth(): AuthProvider {\n  return {\n    token: () => Promise.resolve(null),\n    prepare: () => Promise.resolve(),\n    currentHeaders: () => ({}),\n    recover: () => Promise.resolve(false),\n    deviceId: localDeviceId(),\n    dispose: () => {},\n  };\n}\n\n/**\n * Готовый Bearer-токен: ни хранилища, ни продления.\n *\n * Ответ `401` уходит вызывающему коду как есть — обновить токен провайдеру нечем.\n * Для сессии, которая продлевает себя сама, нужен полный клиент.\n *\n * @example\n * ```ts\n * const api = createRestClient({ auth: bearerToken(process.env.ITD_TOKEN) });\n * ```\n */\nexport function bearerToken(accessToken: string): AuthProvider {\n  const headers = { Authorization: `Bearer ${accessToken}` };\n\n  return {\n    token: () => Promise.resolve(accessToken),\n    prepare: () => Promise.resolve(),\n    currentHeaders: () => headers,\n    recover: () => Promise.resolve(false),\n    deviceId: localDeviceId(),\n    dispose: () => {},\n  };\n}\n\n/**\n * Токен из внешнего источника — хранилища секретов, кэша, соседнего сервиса.\n *\n * Источник спрашивается на стадии подготовки, до входа в очередь: там ожидание безопасно,\n * а слот транспорта ещё не занят. Значение держится до следующей подготовки, потому что\n * подстановка заголовков обязана быть синхронной.\n *\n * @example\n * ```ts\n * const api = createRestClient({ auth: tokenProvider(() => vault.read('itd')) });\n * ```\n */\nexport function tokenProvider(\n  getToken: () => string | null | Promise<string | null>,\n): AuthProvider {\n  let cached: string | null = null;\n\n  const read = async () => {\n    cached = await getToken();\n    return cached;\n  };\n\n  return {\n    token: read,\n    prepare: async () => {\n      await read();\n    },\n    currentHeaders: () => (cached ? { Authorization: `Bearer ${cached}` } : {}),\n    recover: () => Promise.resolve(false),\n    deviceId: localDeviceId(),\n    dispose: () => {\n      cached = null;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AAkFA,SAAS,gBAAuC;CAC9C,IAAI;CAEJ,aAAa;EACX,aAAaA,YAAAA,eAAe;EAC5B,OAAO,QAAQ,QAAQ,QAAQ;CACjC;AACF;;;;;;;;;AAUA,SAAgB,gBAA8B;CAC5C,OAAO;EACL,aAAa,QAAQ,QAAQ,IAAI;EACjC,eAAe,QAAQ,QAAQ;EAC/B,uBAAuB,CAAC;EACxB,eAAe,QAAQ,QAAQ,KAAK;EACpC,UAAU,cAAc;EACxB,eAAe,CAAC;CAClB;AACF;;;;;;;;;;;;AAaA,SAAgB,YAAY,aAAmC;CAC7D,MAAM,UAAU,EAAE,eAAe,UAAU,cAAc;CAEzD,OAAO;EACL,aAAa,QAAQ,QAAQ,WAAW;EACxC,eAAe,QAAQ,QAAQ;EAC/B,sBAAsB;EACtB,eAAe,QAAQ,QAAQ,KAAK;EACpC,UAAU,cAAc;EACxB,eAAe,CAAC;CAClB;AACF;;;;;;;;;;;;;AAcA,SAAgB,cACd,UACc;CACd,IAAI,SAAwB;CAE5B,MAAM,OAAO,YAAY;EACvB,SAAS,MAAM,SAAS;EACxB,OAAO;CACT;CAEA,OAAO;EACL,OAAO;EACP,SAAS,YAAY;GACnB,MAAM,KAAK;EACb;EACA,sBAAuB,SAAS,EAAE,eAAe,UAAU,SAAS,IAAI,CAAC;EACzE,eAAe,QAAQ,QAAQ,KAAK;EACpC,UAAU,cAAc;EACxB,eAAe;GACb,SAAS;EACX;CACF;AACF"}

package/dist/shared/contracts-BoT7msmq.d.cts

@@ -0,0 +1,84 @@
+//#region src/core/attachments/contracts.d.ts
+/** Способ передачи содержимого вложения. */
+declare const FileTransferMode: Readonly<{
+  /** Сначала получить файл целиком, затем отправить его как `Blob`. */
+  readonly Buffer: "buffer";
+  /** Передавать данные по мере чтения, не собирая файл целиком в памяти. */
+  readonly Stream: "stream";
+}>;
+type FileTransferMode = (typeof FileTransferMode)[keyof typeof FileTransferMode];
+/** Что доступно источнику при открытии файла. */
+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;
+}
+//#endregion
+export { FileStreamOptions as a, LazyFile as c, UrlFileOptions as d, FileStreamContent as i, StreamFile as l, FileContext as n, FileTransferMode as o, FileInput as r, FromStreamOptions as s, FileContent as t, UrlFile as u };
+//# sourceMappingURL=contracts-BoT7msmq.d.cts.map

package/dist/shared/contracts-BoT7msmq.d.ts

@@ -0,0 +1,84 @@
+//#region src/core/attachments/contracts.d.ts
+/** Способ передачи содержимого вложения. */
+declare const FileTransferMode: Readonly<{
+  /** Сначала получить файл целиком, затем отправить его как `Blob`. */
+  readonly Buffer: "buffer";
+  /** Передавать данные по мере чтения, не собирая файл целиком в памяти. */
+  readonly Stream: "stream";
+}>;
+type FileTransferMode = (typeof FileTransferMode)[keyof typeof FileTransferMode];
+/** Что доступно источнику при открытии файла. */
+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;
+}
+//#endregion
+export { FileStreamOptions as a, LazyFile as c, UrlFileOptions as d, FileStreamContent as i, StreamFile as l, FileContext as n, FileTransferMode as o, FileInput as r, FromStreamOptions as s, FileContent as t, UrlFile as u };
+//# sourceMappingURL=contracts-BoT7msmq.d.ts.map