Class ClassicAPI

Readonlylogger

Optional ReadonlysettingManager

[dispose]

• "[dispose]"(): void

  Releases the auto-sync timer and any retry-guard window; 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, which the subclass's doAuthenticate hook normalises into AuthenticationError. 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.

  Throws

  RegistrySyncError when the enforced post-auth sync fails — the sync's own failure (a validation rejection, a transport failure, any registry error) rides its cause. The credential check happened FIRST, so the session is left signed in and the credentials persisted: this rejection says "signed in, but the registry could not be verified", never "sign-in refused". The dedicated type is what lets callers branch on that difference without re-deriving it from isAuthenticated() — a discriminator that misreads a transport blip during an account switch over a pre-existing live session as "signed in, stale list".

clearSync

• clearSync(): void

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

  Returns void

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 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, 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.

  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?: SyncParams]): 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.

  Parameters

  • ...args: [params?: SyncParams]

    SyncCallback-shaped payload.

  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. That covers the enforced post-auth sync too: authenticate surfaces what enforceRegistrySync raises as a RegistrySyncError, and this method catches it like any other rejection rather than letting a registry failure reach a lifecycle caller. Use it from lifecycle hooks (init, auth retry, ensureSession) where a stale or missing persisted credential must not crash the caller.

  SINGLE-FLIGHT: concurrent calls share one attempt — the lifecycle paths that race at boot (a background initialize, the first request's ensureSession, a reactive auth failure) collapse onto ONE sign-in round-trip, and every caller's verdict describes that shared attempt. Without the memo, two callers could both pass the login-backoff gate before either refusal armed it, spending two sign-ins against an upstream whose measured throttle threshold was four in seventy seconds.

  A refusal it swallows is also RECORDED (a definitive rejection only — never a throttle or a transport failure): the stored session stays untouched, but the sync-cycle epilogue stops reading it as signed-in until a sign-in is accepted again.

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

  Returns Promise<boolean>

  true when the sign-in round-trip was ACCEPTED — including one whose enforced post-auth sync then failed, because the session it established stands; false for "no persisted credentials", "sign-ins are backed off" and "the server refused the credentials" (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 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

  • OptionalshouldResumeInBackground: boolean

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

  Returns Promise<void>