itd-api 0.10.4 → 0.11.0

package/dist/shared/{url-yB6T_H_-.d.cts → url-BOi-_mJT.d.ts}

@@ -1041,6 +1041,28 @@ interface ItdClock {
 /** Системные часы, используемые клиентом по умолчанию. */
 declare const systemClock: ItdClock;
 //#endregion
+//#region src/core/logger.d.ts
+/**
+ * Логгер библиотеки. Совместим с `console`: к сообщению прилагается не больше одного
+ * аргумента — объект с деталями либо ошибка.
+ */
+interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  /** Пишет ли логгер этот уровень; без метода считается, что пишет все. Есть у winston и pino. */
+  isLevelEnabled?(level: LogLevel): boolean;
+}
+/** Уровень записи журнала. */
+declare const LogLevel: Readonly<{
+  readonly Debug: "debug";
+  readonly Info: "info";
+  readonly Warn: "warn";
+  readonly Error: "error";
+}>;
+type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+//#endregion
 //#region src/core/runtime.d.ts
 /**
  * Как библиотека обращается с cookie.
@@ -1096,13 +1118,6 @@ type QueryValue = string | number | boolean | null | undefined | readonly (strin
 type QueryParams = Record<string, QueryValue>;
 //#endregion
 //#region src/core/options.d.ts
-/** Логгер библиотеки. Совместим с `console`. */
-interface Logger {
-  debug(message: string, ...args: unknown[]): void;
-  info(message: string, ...args: unknown[]): void;
-  warn(message: string, ...args: unknown[]): void;
-  error(message: string, ...args: unknown[]): void;
-}
 /** Настройки повторных попыток. */
 interface RetryOptions {
   /** Сколько всего попыток, включая первую. По умолчанию 3. */
@@ -1186,39 +1201,39 @@ interface RateLimitOptions {
    */
   retryDelays?: readonly number[] | undefined;
 }
-/** Данные о запросе, доступные хукам. */
+/** Данные о запросе, доступные хукам. Изменяем только объект `headers`. */
 interface RequestContext {
   /** Стабильная семантическая операция; `raw` у низкоуровневого вызова без явного ID. */
-  operationId: OperationId;
-  /** Общий сигнал пользовательской отмены, timeout и освобождения клиента. */
-  signal: AbortSignal | undefined;
-  method: string;
+  readonly operationId: OperationId;
+  /** Общий сигнал пользовательской отмены, истёкших сроков и освобождения клиента. */
+  readonly signal: AbortSignal | undefined;
+  readonly method: string;
   /** Путь без базового URL, например `/api/posts`. */
-  path: string;
+  readonly path: string;
   /** Итоговый URL со строкой запроса. */
-  url: string;
-  headers: Headers;
+  readonly url: string;
+  readonly headers: Headers;
   /** Номер попытки, начиная с 1. */
-  attempt: number;
+  readonly attempt: number;
 }
 /** Данные об успешном ответе. */
 interface ResponseContext extends RequestContext {
-  status: number;
+  readonly status: number;
   /** Длительность запроса в мс. */
-  duration: number;
+  readonly duration: number;
   /** Отдельная копия ответа: её тело можно прочитать, не мешая разбору внутри SDK. */
-  response: Response;
+  readonly response: Response;
 }
 /** Данные об ошибке запроса. */
 interface ErrorContextHook extends RequestContext {
-  duration: number;
-  error: unknown;
+  readonly duration: number;
+  readonly error: unknown;
 }
 /** Данные о предстоящем повторе. */
 interface RetryContext extends RequestContext {
-  error: unknown;
+  readonly error: unknown;
   /** Пауза перед следующей попыткой в мс. */
-  delay: number;
+  readonly delay: number;
 }
 /**
  * Хуки запроса.
@@ -1273,8 +1288,24 @@ interface RuntimeOptions {
    * ```
    */
   services?: Record<string, string | Omit<ServiceDefinition, 'name'>> | undefined;
-  /** Таймаут запроса в мс. По умолчанию 30000 — столько же использует сайт итд.com. `0` снимает ограничение. */
+  /**
+   * Таймаут одной транспортной попытки в мс. По умолчанию 30000 — столько же использует
+   * сайт итд.com. `0` снимает ограничение.
+   *
+   * Охватывает сборку заголовков, хуки `onRequest` и `onResponse`, перехватчики попытки,
+   * запрос и чтение тела ответа. Ожидание очереди, паузы между повторами и хук `onError`
+   * в него не входят. Истечение даёт {@link ItdTimeoutError} с `budget: 'attempt'`;
+   * safe- и idempotent-операции повторяются.
+   */
   timeout?: number | undefined;
+  /**
+   * Общий срок логической операции в мс: очередь, повторы, обновление авторизации, плагины
+   * и хуки. По умолчанию не ограничен.
+   *
+   * Истечение даёт {@link ItdTimeoutError} с `budget: 'deadline'` и не повторяется. Тот же
+   * эффект даёт `signal: AbortSignal.timeout(ms)`, но с {@link ItdAbortError}.
+   */
+  deadline?: number | undefined;
   /**
    * Сколько `close()` и `dispose()` ждут чужой код, мс. По умолчанию 10000.
    *
@@ -1305,8 +1336,8 @@ interface RuntimeOptions {
   userAgent?: string | false | undefined;
   /** Хуки запросов. */
   hooks?: ClientHooks | undefined;
-  /** Логгер. `true` — использовать `console`. */
-  logger?: Logger | boolean | undefined;
+  /** Логгер. `true` — консоль с уровня `info`, `LogLevel` — с указанного уровня, объект — свой. */
+  logger?: Logger | LogLevel | boolean | undefined;
 }
 /**
  * Настройки плагинов для отдельной операции.
@@ -1318,11 +1349,16 @@ interface RequestExtensions {}
 interface RequestOptions {
   /** Отмена запроса извне. */
   signal?: AbortSignal | undefined;
-  /** Таймаут только для этого запроса, мс. */
+  /** Таймаут одной транспортной попытки только для этого запроса, мс. */
   timeout?: number | undefined;
+  /** Общий срок только для этого запроса, мс. См. {@link RuntimeOptions.deadline}. */
+  deadline?: number | undefined;
   /** Дополнительные заголовки. */
   headers?: Record<string, string> | undefined;
-  /** Повторы только для этого запроса. Переопределяют глобальную настройку `retry`. */
+  /**
+   * Повторы только для этого запроса. Переопределяют глобальную настройку `retry`.
+   * Лестницу пауз после `429` не затрагивают — как и глобальное `retry: false`.
+   */
   retry?: RetryOptions | false | undefined;
   /**
    * Явно переопределяет безопасность повтора операции.
@@ -1400,7 +1436,14 @@ interface OperationRequestOptions extends RawRequestOptions {
 //#endregion
 //#region src/core/operation.d.ts
 /** HTTP-метод операции. */
-type OperationMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+declare const OperationMethod: Readonly<{
+  readonly Get: "GET";
+  readonly Post: "POST";
+  readonly Put: "PUT";
+  readonly Patch: "PATCH";
+  readonly Delete: "DELETE";
+}>;
+type OperationMethod = (typeof OperationMethod)[keyof typeof OperationMethod];
 /** ID операции подключаемого модуля: `<featureName>.<operationName>`. */
 type FeatureOperationId<TFeatureName extends string = string, TOperationName extends string = string> = `${TFeatureName}.${TOperationName}`;
 /** Семантическая безопасность автоматического повтора операции. */
@@ -1450,7 +1493,7 @@ interface OperationDefinition extends OperationMetadata {
 //#endregion
 //#region src/core/version.d.ts
 /** Версия библиотеки. Попадает в `User-Agent`. */
-declare const LIBRARY_VERSION = "0.10.4";
+declare const LIBRARY_VERSION = "0.11.0";
 //#endregion
 //#region src/core/config.d.ts
 /** Базовый URL API итд.com. Домен записан в punycode: `итд.com`. */
@@ -1458,49 +1501,6 @@ declare const DEFAULT_BASE_URL = "https://xn--d1ah4a.com";
 /** Имя встроенного сервиса статуса. */
 declare const STATUS_SERVICE = "status";
 //#endregion
-//#region src/core/emitter.d.ts
-/** Обработчик события. */
-type Listener<T> = (payload: T) => void;
-/** Функция отписки, которую возвращает подписка на событие. */
-type Unsubscribe = () => void;
-/**
- * Минимальный типизированный источник событий.
- *
- * Своя реализация вместо `EventTarget` и `EventEmitter`: первый есть не везде и требует
- * обёрток `CustomEvent`, второй существует только в Node. Нужны ровно подписка и рассылка.
- *
- * Исключение в обработчике не прерывает рассылку остальным и не роняет библиотеку.
- *
- * @typeParam Events карта «имя события → тип полезной нагрузки». Задаётся интерфейсом,
- * поэтому ограничение на индексную сигнатуру намеренно не накладывается.
- */
-declare class Emitter<Events> {
-  #private;
-  constructor(onListenerError?: (error: unknown) => void);
-  /**
-   * Подписывается на событие.
-   *
-   * @returns функция отписки
-   *
-   * @example
-   * ```ts
-   * const off = events.on('notification', (event) => console.log(event));
-   * off();
-   * ```
-   */
-  on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): Unsubscribe;
-  /** Подписывается на одно срабатывание. */
-  once<K extends keyof Events>(event: K, listener: Listener<Events[K]>): Unsubscribe;
-  /** Отписывается от события. */
-  off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void;
-  /** Рассылает событие подписчикам. */
-  emit<K extends keyof Events>(event: K, payload: Events[K]): void;
-  /** Сколько подписчиков у события. */
-  listenerCount(event: keyof Events): number;
-  /** Снимает все подписки. */
-  removeAllListeners(): void;
-}
-//#endregion
 //#region src/core/auth-provider.d.ts
 /** Области аккаунта и конкретной сессии для локального состояния плагинов. */
 interface AuthIdentity {
@@ -1535,7 +1535,7 @@ interface AuthProvider {
    */
   preflight?(allowRefresh: boolean): Promise<void>;
   /** Перед каждой попыткой читает внешний источник токена до захвата слота очереди. */
-  prepare(): Promise<void>;
+  prepare?(): Promise<void>;
   /**
    * Заголовки уже подготовленной авторизации.
    *
@@ -1615,6 +1615,49 @@ interface ClientConnection {
   refreshAuth(): Promise<boolean>;
 }
 //#endregion
+//#region src/core/emitter.d.ts
+/** Обработчик события. */
+type Listener<T> = (payload: T) => void;
+/** Функция отписки, которую возвращает подписка на событие. */
+type Unsubscribe = () => void;
+/**
+ * Минимальный типизированный источник событий.
+ *
+ * Своя реализация вместо `EventTarget` и `EventEmitter`: первый есть не везде и требует
+ * обёрток `CustomEvent`, второй существует только в Node. Нужны ровно подписка и рассылка.
+ *
+ * Исключение в обработчике не прерывает рассылку остальным и не роняет библиотеку.
+ *
+ * @typeParam Events карта «имя события → тип полезной нагрузки». Задаётся интерфейсом,
+ * поэтому ограничение на индексную сигнатуру намеренно не накладывается.
+ */
+declare class Emitter<Events> {
+  #private;
+  constructor(onListenerError?: (error: unknown) => void);
+  /**
+   * Подписывается на событие.
+   *
+   * @returns функция отписки
+   *
+   * @example
+   * ```ts
+   * const off = events.on('notification', (event) => console.log(event));
+   * off();
+   * ```
+   */
+  on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): Unsubscribe;
+  /** Подписывается на одно срабатывание. */
+  once<K extends keyof Events>(event: K, listener: Listener<Events[K]>): Unsubscribe;
+  /** Отписывается от события. */
+  off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void;
+  /** Рассылает событие подписчикам. */
+  emit<K extends keyof Events>(event: K, payload: Events[K]): void;
+  /** Сколько подписчиков у события. */
+  listenerCount(event: keyof Events): number;
+  /** Снимает все подписки. */
+  removeAllListeners(): void;
+}
+//#endregion
 //#region src/core/errors.d.ts
 /** Бренд, по которому ошибки библиотеки распознаются надёжнее, чем через `instanceof`. */
 declare const ITD_ERROR: unique symbol;
@@ -1786,7 +1829,12 @@ declare class ItdApiError extends ItdError {
    * ```
    */
   hasCode(...codes: ItdErrorCode[]): boolean;
-  /** Имеет ли смысл повторить запрос: `429` и серверные ошибки `5xx`. */
+  /**
+   * Временная ошибка сервера, которую политика повторов считает повторяемой: `429` или `5xx`.
+   *
+   * Повторит ли библиотека саму операцию, зависит ещё от её `retrySafety`: `5xx` на
+   * небезопасной операции не повторяется, `429` — повторяется всегда.
+   */
   get isRetryable(): boolean;
 }
 /** `400` / `422` — данные не прошли валидацию. Подробности в {@link ItdApiError.fieldErrors}. */
@@ -1883,18 +1931,34 @@ declare class ItdNetworkError extends ItdError {
     cause?: unknown;
   });
 }
-/** Истёк таймаут запроса, заданный опцией `timeout`. */
+/** Какой бюджет времени исчерпан. */
+declare const TimeoutBudget: Readonly<{
+  /** Срок одной транспортной попытки — опция `timeout`. */
+  readonly Attempt: "attempt";
+  /** Общий срок логической операции — опция `deadline`. */
+  readonly Deadline: "deadline";
+}>;
+type TimeoutBudget = (typeof TimeoutBudget)[keyof typeof TimeoutBudget];
+/**
+ * Истёк срок, заданный опцией `timeout` (одна попытка) или `deadline` (операция целиком).
+ *
+ * Истёкший `timeout` для safe- и idempotent-операций повторяется; истёкший `deadline` —
+ * нет.
+ */
 declare class ItdTimeoutError extends ItdError {
-  /** Значение таймаута в миллисекундах. */
+  /** Истёкший срок в миллисекундах. */
   readonly timeout: number;
   /** HTTP-метод запроса. */
   readonly method: string;
   /** Путь запроса без базового URL. */
   readonly path: string;
+  /** Какой из двух сроков истёк. */
+  readonly budget: TimeoutBudget;
   constructor(init: {
     timeout: number;
     method: string;
     path: string;
+    budget?: TimeoutBudget | undefined;
   });
 }
 /** Запрос отменён через переданный `AbortSignal`. */
@@ -2298,5 +2362,5 @@ declare function isKnownNotificationType(type: string): boolean;
  */
 declare function resolveNotificationUrl(notification: Notification): string;
 //#endregion
-export { isItdStateError as $, DEFAULT_RATE_LIMIT_BUCKET as $t, ItdErrorKind as A, RequestOptions as At, ItdStateError as B, RuntimeMode as Bt, ItdApiError as C, SpanType as Cn, PaginationOptions as Ct, ItdConfigError as D, RawRequestOptions as Dt, ItdAuthError as E, WallAccess as En, RateLimitOptions as Et, ItdNetworkError as F, RuntimeOptions as Ft, isItdConflictError as G, ItdOperationDefinition as Gt, ItdValidationError as H, systemClock as Ht, ItdNotFoundError as I, QueryParams as It, isItdForbiddenError as J, isBuiltInOperationId as Jt, isItdError as K, OPERATIONS as Kt, ItdPhoneVerificationError as L, QueryValue as Lt, ItdFileError as M, RetryContext as Mt, ItdFileErrorReason as N, RetryDecisionContext as Nt, ItdConflictError as O, RequestContext as Ot, ItdForbiddenError as P, RetryOptions as Pt, isItdServerError as Q, BUCKET_LIMITS as Qt, ItdRateLimitError as R, ServiceDefinition as Rt, ItdAbortError as S, ServiceState as Sn, OperationRequestOptions as St, ItdApiErrorKind as T, ViewSource as Tn, RateLimitBucketOverride as Tt, isItdApiError as U, BuiltInOperationId as Ut, ItdTimeoutError as V, ItdClock as Vt, isItdAuthError as W, CustomOperationId as Wt, isItdPhoneVerificationError as X, operationMethod as Xt, isItdNotFoundError as Y, operationBucket as Yt, isItdRateLimitError as Z, operationRetrySafety as Zt, PrivacySettings as _, Loose as _n, OperationMethod as _t, NotificationEvent as a, AccessType as an, bearerToken as at, SubscriptionState as b, ReportReason as bn, ErrorContextHook as bt, NotificationSettings as c, CaptchaField as cn, Listener as ct, AuthUser as d, EventChannelStatus as dn, STATUS_SERVICE as dt, RateLimitBucket as en, isItdValidationError as et, Author as f, FeedTab as fn, LIBRARY_VERSION as ft, PinsResult as g, LikesVisibility as gn, OperationMetadata as gt, Pin as h, ItdErrorCode as hn, OperationContract as ht, formatNotificationText as i, UserRef as in, anonymousAuth as it, ItdFieldErrors as j, ResponseContext as jt, ItdError as k, RequestExtensions as kt, Actor as l, CaptchaType as ln, Unsubscribe as lt, MyProfile as m, InteractionType as mn, OperationAnnotations as mt, canonicalNotificationType as n, Span as nn, AuthIdentity as nt, normalizeNotification as o, AttachmentType as on, tokenProvider as ot, FollowResult as p, IncidentKind as pn, FeatureOperationId as pt, isItdFileError as q, OperationId as qt, isKnownNotificationType as r, UserId as rn, AuthProvider as rt, Notification as s, CaptchaChoice as sn, Emitter as st, resolveNotificationUrl as t, IsoDate as tn, ClientConnection as tt, AuthState as u, CommentSort as un, DEFAULT_BASE_URL as ut, Profile as v, NotificationType as vn, RetrySafety as vt, ItdApiErrorInit as w, ViewReason as wn, RateLimitBucketContext as wt, UserSummary as x, ReportTargetType as xn, Logger as xt, PublicProfile as y, QrLocationPrecision as yn, ClientHooks as yt, ItdServerError as z, RateLimitPacing as zt };
-//# sourceMappingURL=url-yB6T_H_-.d.cts.map
+export { isItdServerError as $, operationRetrySafety as $t, ItdErrorKind as A, RequestOptions as At, ItdStateError as B, RuntimeMode as Bt, ItdApiError as C, ReportTargetType as Cn, PaginationOptions as Ct, ItdConfigError as D, ViewSource as Dn, RawRequestOptions as Dt, ItdAuthError as E, ViewReason as En, RateLimitOptions as Et, ItdNetworkError as F, RuntimeOptions as Ft, isItdAuthError as G, BuiltInOperationId as Gt, ItdValidationError as H, Logger as Ht, ItdNotFoundError as I, QueryParams as It, isItdFileError as J, OPERATIONS as Jt, isItdConflictError as K, CustomOperationId as Kt, ItdPhoneVerificationError as L, QueryValue as Lt, ItdFileError as M, RetryContext as Mt, ItdFileErrorReason as N, RetryDecisionContext as Nt, ItdConflictError as O, WallAccess as On, RequestContext as Ot, ItdForbiddenError as P, RetryOptions as Pt, isItdRateLimitError as Q, operationMethod as Qt, ItdRateLimitError as R, ServiceDefinition as Rt, ItdAbortError as S, ReportReason as Sn, OperationRequestOptions as St, ItdApiErrorKind as T, SpanType as Tn, RateLimitBucketOverride as Tt, TimeoutBudget as U, ItdClock as Ut, ItdTimeoutError as V, LogLevel as Vt, isItdApiError as W, systemClock as Wt, isItdNotFoundError as X, isBuiltInOperationId as Xt, isItdForbiddenError as Y, OperationId as Yt, isItdPhoneVerificationError as Z, operationBucket as Zt, PrivacySettings as _, ItdErrorCode as _n, OperationMetadata as _t, NotificationEvent as a, UserId as an, ClientConnection as at, SubscriptionState as b, NotificationType as bn, ClientHooks as bt, NotificationSettings as c, AttachmentType as cn, anonymousAuth as ct, AuthUser as d, CaptchaType as dn, DEFAULT_BASE_URL as dt, BUCKET_LIMITS as en, isItdStateError as et, Author as f, CommentSort as fn, STATUS_SERVICE as ft, PinsResult as g, InteractionType as gn, OperationContract as gt, Pin as h, IncidentKind as hn, OperationAnnotations as ht, formatNotificationText as i, Span as in, Unsubscribe as it, ItdFieldErrors as j, ResponseContext as jt, ItdError as k, RequestExtensions as kt, Actor as l, CaptchaChoice as ln, bearerToken as lt, MyProfile as m, FeedTab as mn, FeatureOperationId as mt, canonicalNotificationType as n, RateLimitBucket as nn, Emitter as nt, normalizeNotification as o, UserRef as on, AuthIdentity as ot, FollowResult as p, EventChannelStatus as pn, LIBRARY_VERSION as pt, isItdError as q, ItdOperationDefinition as qt, isKnownNotificationType as r, IsoDate as rn, Listener as rt, Notification as s, AccessType as sn, AuthProvider as st, resolveNotificationUrl as t, DEFAULT_RATE_LIMIT_BUCKET as tn, isItdValidationError as tt, AuthState as u, CaptchaField as un, tokenProvider as ut, Profile as v, LikesVisibility as vn, OperationMethod as vt, ItdApiErrorInit as w, ServiceState as wn, RateLimitBucketContext as wt, UserSummary as x, QrLocationPrecision as xn, ErrorContextHook as xt, PublicProfile as y, Loose as yn, RetrySafety as yt, ItdServerError as z, RateLimitPacing as zt };
+//# sourceMappingURL=url-BOi-_mJT.d.ts.map