stream-chat 9.50.3 → 10.0.0-rc.2

package/src/connection_fallback.ts

@@ -8,7 +8,11 @@ import {
   sleep,
 } from './utils';
 import { isAPIError, isConnectionIDError, isErrorRetryable } from './errors';
-import type { ConnectionOpen, Event, LogLevel, UR } from './types';
+import { chatLoggerSystem } from './logger';
+import type { ConnectionOpen, UR } from './types';
+import type { WSEvent } from './gen/models';
+
+const logger = chatLoggerSystem.getLogger('connection-fallback');
 
 export enum ConnectionState {
   Closed = 'CLOSED',
@@ -33,15 +37,8 @@ export class WSConnectionFallback {
     addConnectionEventListeners(this._onlineStatusChanged);
   }
 
-  _log(msg: string, extra: UR = {}, level: LogLevel = 'info') {
-    this.client.logger(level, 'WSConnectionFallback:' + msg, {
-      tags: ['connection_fallback', 'connection'],
-      ...extra,
-    });
-  }
-
   _setState(state: ConnectionState) {
-    this._log(`_setState() - ${state}`);
+    logger.withExtraTags('_setState').debug(`Transitioning to state: ${state}.`);
 
     // transition from connecting => connected
     if (
@@ -60,7 +57,9 @@ export class WSConnectionFallback {
 
   /** @private */
   _onlineStatusChanged = (event: { type: string }) => {
-    this._log(`_onlineStatusChanged() - ${event.type}`);
+    logger
+      .withExtraTags('_onlineStatusChanged')
+      .info(`Network status changed to ${event.type}.`);
 
     if (event.type === 'offline') {
       this._setState(ConnectionState.Closed);
@@ -85,24 +84,22 @@ export class WSConnectionFallback {
     }
 
     try {
-      const res = await this.client.doAxiosRequest<T>(
+      const res = await this.client.api.doAxiosRequest<T>(
         'get',
         (this.client.baseURL as string).replace(':3030', ':8900') + '/longpoll', // replace port if present for testing with local API
         undefined,
-        {
-          config: { ...config, cancelToken: this.cancelToken?.token },
-          params,
-        },
+        { ...config, cancelToken: this.cancelToken?.token, params },
       );
 
       this.consecutiveFailures = 0; // always reset in case of no error
       return res;
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
     } catch (error: any) {
       this.consecutiveFailures += 1;
 
       if (retry && isErrorRetryable(error)) {
-        this._log(`_req() - Retryable error, retrying request`);
+        logger
+          .withExtraTags('_req')
+          .debug('Encountered a retryable error. Retrying the request.');
         await sleep(retryInterval(this.consecutiveFailures));
         return this._req<T>(params, config, retry);
       }
@@ -116,7 +113,7 @@ export class WSConnectionFallback {
     while (this.state === ConnectionState.Connected) {
       try {
         const data = await this._req<{
-          events: Event[];
+          events: WSEvent[];
         }>({}, { timeout: 30000 }, true); // 30s => API responds in 20s if there is no event
 
         if (data.events?.length) {
@@ -124,17 +121,18 @@ export class WSConnectionFallback {
             this.client.dispatchEvent(data.events[i]);
           }
         }
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
       } catch (error: any) {
         if (axios.isCancel(error)) {
-          this._log(`_poll() - axios canceled request`);
+          logger.withExtraTags('_poll').debug('Axios canceled the request.');
           return;
         }
 
         /** client.doAxiosRequest will take care of TOKEN_EXPIRED error */
 
         if (isConnectionIDError(error)) {
-          this._log(`_poll() - ConnectionID error, connecting without ID...`);
+          logger
+            .withExtraTags('_poll')
+            .warn('Received a connection ID error. Reconnecting without an ID.');
           this._setState(ConnectionState.Disconnected);
           this.connect(true);
           return;
@@ -152,15 +150,20 @@ export class WSConnectionFallback {
 
   /**
    * connect try to open a longpoll request
-   * @param reconnect should be false for first call and true for subsequent calls to keep the connection alive and call recoverState
+   *
+   * @param reconnect - should be false for first call and true for subsequent calls to keep the connection alive and call recoverState
    */
   connect = async (reconnect = false) => {
     if (this.state === ConnectionState.Connecting) {
-      this._log('connect() - connecting already in progress', { reconnect }, 'warn');
+      logger
+        .withExtraTags('connect')
+        .warn('A connection attempt is already in progress.', { reconnect });
       return;
     }
     if (this.state === ConnectionState.Connected) {
-      this._log('connect() - already connected and polling', { reconnect }, 'warn');
+      logger
+        .withExtraTags('connect')
+        .warn('Already connected and polling.', { reconnect });
       return;
     }
 
@@ -175,7 +178,6 @@ export class WSConnectionFallback {
 
       this._setState(ConnectionState.Connected);
       this.connectionID = event.connection_id;
-      // @ts-expect-error type mismatch
       this.client.dispatchEvent(event);
       this._poll();
       if (reconnect) {
@@ -205,9 +207,9 @@ export class WSConnectionFallback {
 
     try {
       await this._req({ close: true, connection_id }, { timeout }, false);
-      this._log(`disconnect() - Closed connectionID`);
+      logger.withExtraTags('disconnect').info('Closed the connection ID.');
     } catch (err) {
-      this._log(`disconnect() - Failed`, { err }, 'error');
+      logger.withExtraTags('disconnect').error('Disconnect failed.', { error: err });
     }
   };
 }

package/src/constants.ts

@@ -1,9 +1,5 @@
 export const DEFAULT_QUERY_CHANNELS_MESSAGE_LIST_PAGE_SIZE = 25;
 export const DEFAULT_QUERY_CHANNEL_MESSAGE_LIST_PAGE_SIZE = 100;
-export const DEFAULT_MESSAGE_SET_PAGINATION = Object.freeze({
-  hasNext: false,
-  hasPrev: false,
-});
 export const DEFAULT_UPLOAD_SIZE_LIMIT_BYTES = 100 * 1024 * 1024; // 100 MB
 export const API_MAX_FILES_ALLOWED_PER_MESSAGE = 10;
 export const MAX_CHANNEL_MEMBER_COUNT_IN_CHANNEL_QUERY = 100;
@@ -23,7 +19,7 @@ export const RESERVED_UPDATED_MESSAGE_FIELDS = Object.freeze({
   own_reactions: true,
   reaction_counts: true,
   reply_count: true,
-  // Message text related fields that shouldn't be in update
+  // MessageRequest text related fields that shouldn't be in update
   i18n: true,
   type: true,
   html: true,

package/src/custom_types.ts

@@ -1,4 +1,7 @@
-export interface CustomAttachmentData {}
+export interface CustomAttachmentData {
+  mime_type?: string;
+  file_size?: number;
+}
 export interface CustomChannelData {}
 export interface CustomCommandData {}
 export interface CustomEventData {}

package/src/entityStore/EntityStore.ts

@@ -0,0 +1,208 @@
+import type { Unsubscribe } from '../store';
+
+/**
+ * A batch of entity-store changes delivered to a subscriber in a single notification.
+ *
+ * `changedIds` are the ids the subscriber watches whose canonical object changed reference this
+ * flush (an upsert, or a removal — a removal makes `store.get(id)` return `undefined`).
+ */
+export type EntityStoreChangeBatch = {
+  changedIds: ReadonlySet<string>;
+};
+
+/**
+ * Anything that observes entities held in an {@link EntityStore}.
+ *
+ * A subscriber watches a *set* of entity ids (a paginator watches all ids in its
+ * intervals; a thread watches its single parent id). It is notified at most once
+ * per store transaction with the subset of its watched ids that changed.
+ */
+export type EntityStoreSubscriber = {
+  onEntitiesChanged: (batch: EntityStoreChangeBatch) => void;
+  /**
+   * Optional: emit any throttled/pending state notification immediately. Called by
+   * {@link EntityStore.flushSubscribers} after an optimistic (local-user) write so the change
+   * renders without throttle delay. A paginator implements this by flushing its throttled window
+   * publish.
+   */
+  flushState?: () => void;
+};
+
+export type EntityStoreOptions<T> = {
+  /** Extracts the canonical id an entity is stored and addressed under. */
+  getEntityId: (entity: T) => string;
+};
+
+/**
+ * A client-global, normalized store for domain entities addressed by id.
+ *
+ * The store holds exactly **one** canonical `T` per id and lets any number of entities
+ * (paginators, threads, ad-hoc consumers) subscribe to individual ids. Every mutation of a
+ * stored entity becomes a single `upsert`, and the store fans the change out to exactly the
+ * subscribers holding that id — replacing the manual copy-to-copy fan-out that keeping N
+ * per-consumer copies in sync required.
+ *
+ * The store is entity-agnostic: it learns how to extract an id from a `T` via the `getEntityId`
+ * function passed to its constructor. The client holds one as `client.messageStore`, an
+ * `EntityStore<LocalMessage>`, for message content.
+ *
+ * ## Design
+ *
+ * - **Content:** `byId` (`Map<id, T>`) is the single source of truth. Objects are immutable
+ *   snapshots: `upsert` *replaces*, never mutates in place, so the reference-equality
+ *   short-circuit (mirroring {@link StateStore.next}) and every downstream selector keep working.
+ * - **Subscription registry / refcount:** `subscribers` (`Map<id, Set<subscriber>>`) is both the
+ *   per-id notification list and the reference count — when the last subscriber of an id unlinks,
+ *   the canonical copy is garbage-collected.
+ * - **Batching:** `transaction` coalesces a bulk write (e.g. a page of N entities) so each affected
+ *   subscriber is notified **once** with the full changed-id set, instead of N times.
+ * - **Signal-then-pull:** subscribers receive the set of changed ids and pull the new content via
+ *   `get`; the store never pushes objects.
+ *
+ * This is deliberately a hand-rolled per-id registry rather than a {@link StateStore}: a single
+ * `StateStore` would run every subscriber's selector on every change (O(all subscribers) per emit),
+ * and a store-per-entity would allocate a full `StateStore` per id with no cross-id batching. The
+ * `Map<id, Set>` gives O(subscribers-of-changed-id) fan-out — the same idiom as `PollManager`'s
+ * cache.
+ *
+ * @template T The domain entity type held by the store.
+ */
+export class EntityStore<T> {
+  private byId = new Map<string, T>();
+  private subscribers = new Map<string, Set<EntityStoreSubscriber>>();
+  private readonly getEntityId: (entity: T) => string;
+
+  private transactionDepth = 0;
+  private pendingChanged = new Map<EntityStoreSubscriber, Set<string>>();
+
+  constructor({ getEntityId }: EntityStoreOptions<T>) {
+    this.getEntityId = getEntityId;
+  }
+
+  // ---- reads ----
+
+  get(id: string | undefined): T | undefined {
+    return typeof id === 'string' ? this.byId.get(id) : undefined;
+  }
+
+  has(id: string): boolean {
+    return this.byId.has(id);
+  }
+
+  // ---- writes ----
+
+  /**
+   * Replaces the canonical copy of `entity` and notifies every subscriber watching its id —
+   * except `subscriber`, the one that performed the write, which is expected to re-render itself
+   * (the paginator that performed the write already emits its own window inline, so it must not be
+   * notified a second time through the subscription).
+   */
+  upsert(entity: T, subscriber?: EntityStoreSubscriber): void {
+    const id = this.getEntityId(entity);
+    const previous = this.byId.get(id);
+    // do not notify if the value hasn't changed (mirrors StateStore.next)
+    if (previous === entity) return;
+    this.byId.set(id, entity);
+    this.markDirty(id, subscriber);
+    this.autoFlush();
+  }
+
+  // ---- subscription registry / refcount ----
+
+  /** Registers `subscriber` for `id` (notification target + refcount). */
+  link(id: string, subscriber: EntityStoreSubscriber): void {
+    let subscribers = this.subscribers.get(id);
+    if (!subscribers) {
+      subscribers = new Set();
+      this.subscribers.set(id, subscribers);
+    }
+    subscribers.add(subscriber);
+  }
+
+  /** Drops `subscriber` from `id`; GCs the canonical copy when none remain. */
+  unlink(id: string, subscriber: EntityStoreSubscriber): void {
+    const subscribers = this.subscribers.get(id);
+    if (!subscribers) return;
+    subscribers.delete(subscriber);
+    if (subscribers.size === 0) {
+      this.subscribers.delete(id);
+      // refcount GC: nobody holds this entity any longer.
+      this.byId.delete(id);
+    }
+  }
+
+  /**
+   * Sugar for atomic / ad-hoc consumers that watch a single id (e.g. a thread watching its parent
+   * message). Fires `handler` immediately with the current value (mirroring
+   * {@link StateStore.subscribe}) and on every subsequent change.
+   */
+  subscribe(id: string, handler: (entity: T | undefined) => void): Unsubscribe {
+    const subscriber: EntityStoreSubscriber = {
+      onEntitiesChanged: () => handler(this.byId.get(id)),
+    };
+    this.link(id, subscriber);
+    handler(this.byId.get(id));
+    return () => this.unlink(id, subscriber);
+  }
+
+  // ---- batching ----
+
+  /**
+   * Runs `fn`, coalescing all notifications produced by writes inside it into a single flush on
+   * exit. Re-entrant: nested transactions flush only when the outermost exits.
+   */
+  transaction<R>(fn: () => R): R {
+    this.transactionDepth += 1;
+    try {
+      return fn();
+    } finally {
+      this.transactionDepth -= 1;
+      if (this.transactionDepth === 0) this.flush();
+    }
+  }
+
+  /**
+   * Immediately flushes any throttled/pending state publish on the subscribers of `id` (via
+   * {@link EntityStoreSubscriber.flushState}). Called after an optimistic (local-user) write to
+   * `id` so it renders without the throttle delay. Only that id's own subscribers are flushed — the
+   * write touched no other id — and flushing a subscriber with nothing pending is a no-op.
+   */
+  flushSubscribers(id: string): void {
+    const subscribers = this.subscribers.get(id);
+    if (!subscribers) return;
+    for (const subscriber of subscribers) subscriber.flushState?.();
+  }
+
+  /**
+   * Records `id` as changed for every subscriber watching it, except `subscriber` — the one that
+   * wrote it and is resposible for updating itself (see {@link EntityStore.upsert}).
+   */
+  private markDirty(id: string, subscriber?: EntityStoreSubscriber): void {
+    const subscribers = this.subscribers.get(id);
+    if (!subscribers) return;
+    for (const other of subscribers) {
+      if (other === subscriber) continue;
+      let changed = this.pendingChanged.get(other);
+      if (!changed) {
+        changed = new Set();
+        this.pendingChanged.set(other, changed);
+      }
+      changed.add(id);
+    }
+  }
+
+  private autoFlush(): void {
+    if (this.transactionDepth === 0) this.flush();
+  }
+
+  private flush(): void {
+    if (this.pendingChanged.size === 0) return;
+    // swap out the pending map before notifying so writes made from within a
+    // subscriber accumulate into the next flush rather than mutating this one.
+    const changedBySubscriber = this.pendingChanged;
+    this.pendingChanged = new Map();
+    for (const [subscriber, changedIds] of changedBySubscriber) {
+      subscriber.onEntitiesChanged({ changedIds });
+    }
+  }
+}

package/src/entityStore/StoreBackedItemIndex.ts

@@ -0,0 +1,115 @@
+import type { ItemIndexApi } from '../pagination/ItemIndex';
+import { EntityStore, type EntityStoreSubscriber } from './EntityStore';
+
+export type StoreBackedItemIndexOptions<T> = {
+  getEntityId: (item: T) => string;
+  /**
+   * The entity that owns this index; used as the store subscriber, which also holds its refcount.
+   * Optional: an index over a private store (see `store`) has no one to fan out to, so an
+   * owner-less index just uses an internal no-op subscriber to hold its refcount. Message paginators pass themselves so
+   * cross-collection updates reach them; single-home collections (channels, reminders, …) omit it.
+   */
+  owner?: EntityStoreSubscriber;
+  /**
+   * The shared, client-global store that holds the canonical content. Optional: when omitted the
+   * index provisions a **private** {@link EntityStore} of its own, so it behaves exactly like a
+   * plain, per-instance index — same code path, no shared content, no fan-out. This is the mode used
+   * by single-home collections and by detached paginators (e.g. built without a client, in tests).
+   */
+  store?: EntityStore<T>;
+};
+
+/** No-op subscriber that holds the refcount for an owner-less (private-store) index. */
+const NOOP_OWNER: EntityStoreSubscriber = { onEntitiesChanged: () => undefined };
+
+/**
+ * An {@link ItemIndexApi} implementation that keeps entity **content** in an {@link EntityStore}
+ * while keeping **membership** local.
+ *
+ * A consumer sees the same minimal CRUD surface ({@link ItemIndexApi}), but:
+ *
+ * - `get`/`has`/`values`/`entries` are scoped to *this* index's membership (`memberIds`), so
+ *   `getItem(id)` still means "does THIS index hold the id" — even though the canonical object
+ *   lives in the (possibly shared) store. This is what keeps e.g. reaction routing
+ *   (`threadPaginator.getItem(id) ? thread : channel`) correct and keeps the `.values()` scans
+ *   from ever walking other channels' entities.
+ * - `setOne` writes content once into the store and links the owner as a subscriber (drives both
+ *   notification fan-out and refcount GC). The write passes the owner as the `subscriber` to skip, so
+ *   the owner is not notified of its own write (it re-emits its window inline); other subscribers of
+ *   the same id ARE notified and re-project.
+ * - `remove`/`clear` unlink the owner rather than hard-deleting content, so an entity still held by
+ *   another index (e.g. a `show_in_channel` reply in both the channel list and its thread) survives;
+ *   the store GCs it only when the last subscriber unlinks.
+ *
+ * When no shared store is supplied the index holds a private store — every id it links has exactly
+ * one subscriber (its own owner), so no fan-out ever fires and removal GCs immediately, matching a plain
+ * per-instance index.
+ *
+ * @template T The domain item type held by the index; collocated with the {@link EntityStore}'s.
+ */
+export class StoreBackedItemIndex<T> implements ItemIndexApi<T> {
+  private memberIds = new Set<string>();
+  private readonly store: EntityStore<T>;
+  private readonly owner: EntityStoreSubscriber;
+  private readonly getEntityId: (item: T) => string;
+
+  constructor({ store, owner, getEntityId }: StoreBackedItemIndexOptions<T>) {
+    this.store = store ?? new EntityStore<T>({ getEntityId });
+    this.owner = owner ?? NOOP_OWNER;
+    this.getEntityId = getEntityId;
+  }
+
+  setMany(items: T[]) {
+    this.store.transaction(() => {
+      for (const item of items) this.setOne(item);
+    });
+  }
+
+  setOne(item: T) {
+    const id = this.getEntityId(item);
+    this.store.link(id, this.owner);
+    this.memberIds.add(id);
+    this.store.upsert(item, this.owner);
+  }
+
+  get(id: string): T | undefined {
+    return this.memberIds.has(id) ? this.store.get(id) : undefined;
+  }
+
+  has(id: string): boolean {
+    return this.memberIds.has(id);
+  }
+
+  remove(id: string) {
+    if (!this.memberIds.has(id)) return;
+    this.memberIds.delete(id);
+    this.store.unlink(id, this.owner);
+  }
+
+  clear() {
+    for (const id of this.memberIds) this.store.unlink(id, this.owner);
+    this.memberIds.clear();
+  }
+
+  entries(): [string, T][] {
+    const result: [string, T][] = [];
+    for (const id of this.memberIds) {
+      const item = this.store.get(id);
+      if (item) result.push([id, item]);
+    }
+    return result;
+  }
+
+  values(): T[] {
+    const result: T[] = [];
+    for (const id of this.memberIds) {
+      const item = this.store.get(id);
+      if (item) result.push(item);
+    }
+    return result;
+  }
+
+  batch<R>(fn: () => R): R {
+    return this.store.transaction(fn);
+  }
+}

package/src/entityStore/applyReactionLocally.ts

@@ -0,0 +1,113 @@
+import type { StreamChat } from '../client';
+import type { ReactionRequest, ReactionResponse, UserResponse } from '../types';
+import {
+  computeOwnReactions,
+  messageWithReactionAdded,
+  messageWithReactionRemoved,
+} from '../utils';
+
+/**
+ * Applies a reaction to the single canonical copy of a message in the client-global
+ * {@link EntityStore} (`client.messageStore`), addressed purely by id — NOT through any paginator's
+ * membership. It reads the
+ * current message POJO (`store.get`), produces a new POJO with the reaction folded into its
+ * `reaction_groups` / `latest_reactions` (shared count helpers) and `own_reactions`
+ * ({@link computeOwnReactions}), and writes it back (`store.upsert`). The store then notifies every
+ * collection currently holding that id — the main-list / thread-reply paginators, a thread's
+ * subscribed parent, any future consumer — and each re-projects. The message stays a plain object;
+ * the store's per-id registry is the reactivity.
+ *
+ * Because it is keyed by id rather than by a paginator's `getItem`, it reaches a message held by ANY
+ * collection, including the thread parent that lives in no paginator — with no per-home wiring.
+ *
+ * Writes memory (synchronous) + the offline DB (fire-and-forget), and returns an `undo()` reversing
+ * both on the current state (inverse deltas, concurrency-safe), or `undefined` when the user isn't
+ * connected or the message isn't in the store.
+ */
+export const applyReactionLocally = (
+  client: StreamChat,
+  {
+    enforceUnique = false,
+    messageId,
+    reaction,
+    removed = false,
+  }: {
+    messageId: string;
+    reaction: ReactionRequest;
+    enforceUnique?: boolean;
+    removed?: boolean;
+  },
+): (() => void) | undefined => {
+  const store = client.messageStore;
+  const user = client.user;
+  const existing = store.get(messageId);
+  if (!user || !existing) return;
+
+  const now = new Date();
+  // Spread `reaction` first so the authoritative fields below win, while still preserving any values
+  // the caller already carried (e.g. the original `created_at` when undo re-applies a captured
+  // reaction) via `?? now`. `message_id`/`user`/`user_id` are always derived from this message and
+  // the connected user, so they never need to come off `reaction`.
+  const reactionResponse: ReactionResponse = {
+    ...reaction,
+    created_at: reaction.created_at ?? now,
+    custom: reaction.custom ?? {},
+    message_id: messageId,
+    score: reaction.score ?? 1,
+    type: reaction.type,
+    updated_at: reaction.updated_at ?? now,
+    user: user as UserResponse,
+    user_id: user.id,
+  };
+
+  // Capture what this op removes so undo() can restore it faithfully (reaction spread last): the
+  // deleted reaction for a removal, or the user's displaced reactions for an enforce_unique add.
+  const removedReactions: ReactionResponse[] = removed
+    ? (existing.own_reactions?.filter((r) => r.type === reactionResponse.type) ?? [])
+    : enforceUnique
+      ? (existing.own_reactions ?? [])
+      : [];
+
+  const withCounts = removed
+    ? messageWithReactionRemoved(existing, reactionResponse)
+    : messageWithReactionAdded(existing, reactionResponse, enforceUnique);
+  const own_reactions = computeOwnReactions({
+    current: existing.own_reactions ?? [],
+    enforceUnique,
+    reaction: reactionResponse,
+    removed,
+    userId: user.id,
+  });
+  store.upsert({ ...withCounts, own_reactions });
+  store.flushSubscribers(messageId);
+
+  const persisted = store.get(messageId);
+  if (persisted) {
+    client.offlineDb?.executeQuerySafely(
+      (db) =>
+        removed
+          ? db.deleteReaction({ message: persisted, reaction: reactionResponse })
+          : enforceUnique
+            ? db.updateReaction({ message: persisted, reaction: reactionResponse })
+            : db.insertReaction({ message: persisted, reaction: reactionResponse }),
+      { method: 'applyReactionLocally' },
+    );
+  }
+
+  return () => {
+    if (!removed) {
+      applyReactionLocally(client, {
+        messageId,
+        reaction: reactionResponse,
+        removed: true,
+      });
+    }
+    for (const removedReaction of removedReactions) {
+      applyReactionLocally(client, {
+        messageId,
+        reaction: removedReaction,
+        removed: false,
+      });
+    }
+  };
+};

package/src/entityStore/index.ts

@@ -0,0 +1,2 @@
+export * from './applyReactionLocally';
+export * from './EntityStore';

package/src/errors.ts

@@ -1,5 +1,5 @@
 import type { AxiosResponse } from 'axios';
-import type { APIErrorResponse } from './types';
+import type { APIError as Gen_APIError } from './types';
 
 export const APIErrorCodes: Record<string, { name: string; retryable: boolean }> = {
   '-1': { name: 'InternalSystemError', retryable: true },
@@ -48,6 +48,18 @@ export function isErrorRetryable(error: APIError) {
   return err.retryable;
 }
 
+/**
+ * Whether an error is EPHEMERAL — a transient failure worth queueing/retrying rather than a
+ * definitive rejection. True when the server never responded (connection/network/offline error - no
+ * `response`, i.e an axios network error or an `OfflineError`) and when the server responded with a
+ * retryable code (see {@link APIErrorCodes}); false only when the server responded with a
+ * non-retryable code (InputError 4, DoesNotExist 16, NotAllowed 17, …).
+ */
+export function isEphemeral(error: Error): boolean {
+  if (!(error as { response?: unknown }).response) return true;
+  return isErrorRetryable(error as APIError);
+}
+
 export function isConnectionIDError(error: APIError) {
   return error.code === 46; // ConnectionIDNotFoundError
 }
@@ -66,6 +78,6 @@ export function isWSFailure(err: APIError): boolean {
 
 export function isErrorResponse(
   res: AxiosResponse<unknown>,
-): res is AxiosResponse<APIErrorResponse> {
+): res is AxiosResponse<Gen_APIError> {
   return !res.status || res.status < 200 || 300 <= res.status;
 }