Class ClassicAPI

Readonlylogger

Optional ReadonlysettingManager

isRateLimited

• get isRateLimited(): boolean

  Whether the upstream rate-limit gate is currently holding a pause window after a recent 429 Retry-After response.

  Returns boolean

  true while the SDK is intentionally failing fast.

[dispose]

• "[dispose]"(): void

  Releases the auto-sync timer and any retry-guard timers; the instance must not be reused after disposal.

  Returns void

authenticate

• authenticate(credentials: LoginCredentials): Promise<void>

  Sign in with explicit credentials. The server refuses them in protocol-specific ways (Classic ClientLogin3 returning LoginData: null, Home BFF returning 401, etc.). Successful return guarantees the registry reflects server state — the post-auth sync is enforced here so subclasses cannot forget it.

  Use resumeSession for a best-effort restore from persisted credentials that logs + swallows errors.

  Credentials are persisted only once the server accepts them: a rejected attempt leaves the stored pair and any live session untouched (the backoff still arms and the error still surfaces).

  Parameters

  • credentials: LoginCredentials

    Explicit username/password.

  Returns Promise<void>

  Throws

  AuthenticationError when the server refuses the credentials.

clearSync

• clearSync(): void

  Cancels any pending auto-sync timer; subsequent setSyncInterval or fetch calls re-arm it.

  Returns void

ensureAuthenticated

• ensureAuthenticated(): Promise<boolean>

  Sync check first; when it reads false, a NON-DESTRUCTIVE probe — one registry sync, which exercises the persisted session without touching it — and only if that still leaves us unauthenticated, the best-effort resumeSession fallback. The order matters: resumeSession runs a full sign-in, which spends a real login attempt (server-side throttle counters, the local backoff on a rejection) and replaces a session that may have been merely unexercised (a boot-time context fetch that lost the network reads unauthenticated while a perfectly valid refresh token sits in storage).

  Returns Promise<boolean>

  true when a session is usable afterwards.

initialize

• initialize(): Promise<void>

  Post-construction lifecycle hook. Every subclass create() factory must delegate to this method — it is the sole path that guarantees the #1281-class invariant at instance-creation time: a successful return leaves the registry populated whenever credentials or a persisted session are available.

  Two-branch template:

  1. tryReuseSession — if the subclass can reuse a persisted session (and populate the registry in the process), we are done.
  2. Otherwise, resumeSession runs — best-effort restore from persisted credentials. Does nothing (silently) if no credentials are persisted, so the "no creds + no session" case falls through to a documented empty state.

  Callers should check isAuthenticated after create() returns if they need to distinguish "empty state" from "ready".

  Returns Promise<void>

logOut

• logOut(): void

  Log out: the inverse of authenticate. Clears the persisted session (tokens/context/expiry), the stored username/password and the automatic-login backoff, stops the auto-sync timer, and empties the registry — so isAuthenticated reads false and no stale devices linger, identically on Classic and Home.

  User-initiated, so unlike a rejected sign-in it neither arms the backoff nor emits onAuthenticationLost. A subsequent authenticate is the only way back in.

  Returns void

notifySync

• notifySync(
      ...args: [params?: { ids?: (string | number)[]; type?: DeviceType }],
  ): Promise<void>

  Notify any registered events.onSyncComplete observer that a sync just landed. Routed through the lifecycle emitter so a misbehaving callback cannot break the caller. Invoked by the @syncDevices decorator after each decorated mutation.

  Parameters

  • ...args: [params?: { ids?: (string | number)[]; type?: DeviceType }]

    SyncCallback-shaped payload (type, ids).

  Returns Promise<void>

resumeSession

• resumeSession(): Promise<boolean>

  Best-effort session restore from persisted credentials.

  Reads username/password from the SettingManager and signs in. Unlike authenticate, failures are logged and swallowed — the method never throws. Use this from lifecycle hooks (init, 401 retry, ensureSession) where a stale or missing persisted credential must not crash the caller.

  On success, the registry is populated (delegates to authenticate).

  Returns Promise<boolean>

  true when a sign-in round-trip succeeded and the instance is now authenticated; false for "no persisted credentials" or "sign-in failed" (both indistinguishable by the return value alone — check the logger / isAuthenticated if the distinction matters).

setSyncInterval

• setSyncInterval(minutes: number | false): void

  Reschedules the auto-sync timer.

  The timer is unref'd, so it never keeps the Node event loop alive on its own — auto-sync still fires on cadence whenever the host application has another reason to stay running (HTTP server, other timers, open streams). Apps that must run indefinitely should provide their own keep-alive (e.g. setInterval(() => {}, 1 << 30) or a long-lived server) rather than relying on this timer.

  Parameters

  • minutes: number | false

    Cadence in minutes; pass false to disable.

  Returns void

start

• start(shouldResumeInBackground?: boolean): Promise<void>

  Run the initial session restore, honoring the configured mode. initialize() never rejects by design (probe and resume failures are swallowed and surfaced through the lifecycle events), so the background variant only needs the fire-and-forget form.

  Parameters

  • shouldResumeInBackground: boolean = false

    When true, the restore runs off the caller's critical path and create() resolves immediately.

  Returns Promise<void>