AbstractShape of the consumer-defined parameters the sync notification carries.
Releases the auto-sync timer and any retry-guard window; the instance must not be reused after disposal.
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).
Explicit username/password.
AuthenticationError when the server refuses the credentials.
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".
Cancels any pending auto-sync timer; subsequent setSyncInterval or sync calls re-arm it.
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:
tryReuseSession — if the subclass can reuse a persisted
session (and populate the registry in the process), we are
done.Callers should check isAuthenticated after create()
returns if they need to distinguish "empty state" from "ready".
AbstractisWhether a session is currently usable, from local state alone.
true while the instance holds a usable credential.
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.
Notify any registered events.onSyncComplete observer that a
sync just landed. Routed through the lifecycle emitter so a
misbehaving callback cannot break the caller.
SyncCallback-shaped payload.
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).
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).
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.
Cadence in minutes; pass false to disable.
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.
When true, the restore runs off
the caller's critical path and create() resolves immediately.
The session lifecycle and request pipeline shared by the SDK API clients: persisted credentials, the login-backoff gate, the logOut-epoch protocol, single-flight session refresh, the resilience pipeline around every request, and the sync-cycle template that keeps the registry and the auto-sync timer honest.
Protocol knowledge stays in the subclass, behind the abstract hooks: how to sign in, which headers carry the credential, what "persisted session" means, how the registry is refreshed.