@marianmeres/ownsuite 2.1.0 → 2.2.2

package/dist/types/auth.d.ts

@@ -33,17 +33,24 @@ export type SessionStatus =
  * `/me` returns plus the fields needed for role-gating.
  */
 export interface SessionSubject {
+    /** Server-assigned subject identifier. Empty string before `/me` lands. */
     id: string;
+    /** Verified or unverified email address of the subject. */
     email: string;
+    /** Authorization roles — drive UI gating, not security. */
     roles: string[];
+    /** True when the server has confirmed the email address. */
     isVerified: boolean;
     /** Whether the account has a password (OAuth-only accounts do not). */
     hasPassword: boolean;
 }
 /** Observable session state — stored by the SessionManager. */
 export interface SessionState {
+    /** Current lifecycle bucket; see {@link SessionStatus}. */
     status: SessionStatus;
+    /** Loaded subject, or `null` when anonymous. */
     subject: SessionSubject | null;
+    /** JWT for outgoing `Authorization` headers, `null` when anonymous. */
     jwt: string | null;
     /** Unix-seconds expiry (optional — not every server shape returns one). */
     expiresAt: number | null;
@@ -54,22 +61,39 @@ export interface SessionState {
  * matching this interface (useful for Tauri, WebExtensions, SSR guards).
  */
 export interface SessionStorage {
+    /** Read a value by key; return `null` when missing or unreadable. */
     get(key: string): string | null;
+    /** Write a value; silently no-op on quota errors. */
     set(key: string, value: string): void;
+    /** Delete a value; silently no-op when absent. */
     del(key: string): void;
 }
+/** Accepted `storage` option for `SessionManager`. String values resolve to
+ *  the three built-in backends; a {@link SessionStorage} object overrides
+ *  the defaults entirely (single custom backend — per-login `remember` is
+ *  silently ignored in that mode). */
 export type SessionStorageType = "local" | "session" | "memory" | SessionStorage;
+/** Supported OAuth provider identifiers — the server side (`@marianmeres/
+ *  stack-account`) decides which are actually enabled. */
 export type OAuthProvider = "google" | "facebook" | "apple" | "twitter";
+/** A single linked OAuth provider connection on the subject's account. */
 export interface OAuthConnection {
+    /** Which provider this connection represents. */
     provider: OAuthProvider;
+    /** Human-readable display name as reported by the provider. */
     display_name?: string;
+    /** Avatar URL reported by the provider (not proxied — may be public). */
     avatar_url?: string;
+    /** Email reported by the provider (may differ from the account email). */
     email?: string;
 }
 /** Action verb for the OAuth init URL — `login` creates/looks-up an account,
  *  `link` attaches the provider to the currently authenticated subject. */
 export type OAuthAction = "login" | "link";
+/** Options for starting an OAuth flow via `AuthManager.initiateOAuth`. */
 export interface OAuthInitOptions {
+    /** Whether this flow creates/looks-up an account (`login`) or attaches
+     *  the provider to the currently authenticated subject (`link`). */
     action: OAuthAction;
     /** Where to redirect after the provider callback (server honours this). */
     redirect?: string;
@@ -79,6 +103,26 @@ export interface OAuthInitOptions {
      *  whether to open a popup and wait for a postMessage, or redirect the
      *  top window. */
     mode?: "popup" | "redirect";
+    /** Same semantics as {@link AuthActionOptions.remember} — pins the
+     *  resulting session to `localStorage` (`true`) or `sessionStorage`
+     *  (`false`). Only meaningful for `action: "login"`. */
+    remember?: boolean;
+}
+/**
+ * Options accepted by `AuthManager.login` / `register` /
+ * `handleOAuthCallback` to express per-login storage preference
+ * ("Remember me").
+ */
+export interface AuthActionOptions {
+    /** `true` → persist the resulting session to `localStorage` (survives
+     *  browser restart).
+     *  `false` → persist to `sessionStorage` (dies with the tab).
+     *  `undefined` → use the `SessionManager`'s configured default backend.
+     *
+     *  Silently ignored when the `SessionManager` was constructed with a
+     *  custom `SessionStorage` object — the single custom backend is used
+     *  regardless. */
+    remember?: boolean;
 }
 /**
  * Uniform result shape for `register` / `login` / OAuth success. When the
@@ -87,33 +131,60 @@ export interface OAuthInitOptions {
  * manager flips session.status to "unverified".
  */
 export interface AuthTokenResult {
+    /** JWT to present on subsequent authenticated requests. Absent when
+     *  `requiresVerification` is `true`. */
     jwt?: string;
+    /** Email as recognised by the server (may be normalised). */
     email: string;
+    /** Roles granted by the server. */
     roles: string[];
+    /** True when the server confirms the email is already verified. */
     isVerified?: boolean;
+    /** JWT `not-before` claim in unix seconds (when server returns one). */
     validFrom?: number;
+    /** JWT `expires-at` claim in unix seconds (when server returns one). */
     validUntil?: number;
     /** Set by the server when login auto-login is declined for a not-yet-
      *  verified account. Mutually exclusive with jwt in practice. */
     requiresVerification?: boolean;
 }
+/** `/me` profile payload returned by `ProfileAdapter.get` / `update`. */
 export interface ProfileResult {
+    /** Current email on the account. */
     email: string;
+    /** Current authorization roles. */
     roles: string[];
+    /** Whether the email is verified. */
     isVerified: boolean;
+    /** Whether the account has a password. */
     hasPassword: boolean;
+    /** Linked OAuth provider connections. */
     oauthConnections: OAuthConnection[];
 }
+/**
+ * Contract the `AuthManager` uses to talk to the server. Implement this
+ * against whatever transport the backend exposes — `createStackAccountAuth
+ * Adapter` provides the default for `@marianmeres/stack-account`. Adapters
+ * hold no state; they forward `ctx.jwt` / `ctx.signal` per call.
+ */
 export interface AuthAdapter {
+    /** Create an account. When the verification gate is on, the returned
+     *  result sets `requiresVerification: true` and omits the JWT. */
     register(input: {
+        /** Email as entered; server normalises + stores. */
         email: string;
+        /** Plaintext password — server hashes. */
         password: string;
+        /** Plaintext confirmation, server cross-checks. */
         password_confirm: string;
+        /** Roles to request on the account (server may reject). */
         roles?: string[];
         /** Optional extras — consumer forwards any configured
          *  registrationFields the server expects. */
         extras?: Record<string, unknown>;
     }, ctx: OwnsuiteContext): Promise<AuthTokenResult>;
+    /** Exchange credentials for a JWT. Throws on bad credentials; sets
+     *  `requiresVerification: true` when the verification gate is on. */
     login(input: {
         email: string;
         password: string;
@@ -128,22 +199,32 @@ export interface AuthAdapter {
      *  URL (or a server-rendered payload) and return it. Popup-mode uses the
      *  `openOAuthPopup` helper directly and does not call this. */
     handleOAuthCallback?(ctx: OwnsuiteContext): Promise<AuthTokenResult>;
+    /** Request a fresh verification email. Anti-enumeration: must resolve
+     *  regardless of whether the address exists. */
     resendVerification(input: {
         email: string;
         lang?: string;
     }, ctx: OwnsuiteContext): Promise<void>;
+    /** Request a password-reset email. Anti-enumeration: must resolve
+     *  regardless of whether the address exists. */
     requestPasswordReset(input: {
         email: string;
         lang?: string;
     }, ctx: OwnsuiteContext): Promise<void>;
+    /** Change or reset the password. Provide `current_password` for an
+     *  authenticated self-change, or `token` for a reset-link flow. */
     changePassword(input: {
         /** Required for authenticated self-change. */
         current_password?: string;
+        /** New password (plaintext — hashed server-side). */
         new_password: string;
+        /** Confirmation — must match new_password. */
         confirm_password: string;
         /** Required for token-based reset. */
         token?: string;
     }, ctx: OwnsuiteContext): Promise<void>;
+    /** Irreversibly delete the authenticated account. Resolves with
+     *  `{ deleted: true }` on success; any failure rejects. */
     deleteAccount(input: {
         password?: string;
         confirm?: boolean;
@@ -151,12 +232,19 @@ export interface AuthAdapter {
         deleted: true;
     }>;
 }
+/** Contract the `ProfileManager` uses to read + mutate `/me`. Like
+ *  `AuthAdapter`, stateless — reads `ctx.jwt` per call. */
 export interface ProfileAdapter {
+    /** GET `/me` → current profile snapshot. */
     get(ctx: OwnsuiteContext): Promise<ProfileResult>;
+    /** PUT `/me` — update email and/or confirm current password. Returns
+     *  the refreshed profile. */
     update(input: {
         email?: string;
         current_password?: string;
     }, ctx: OwnsuiteContext): Promise<ProfileResult>;
+    /** GET linked OAuth connections for the authenticated subject. */
     listOAuth(ctx: OwnsuiteContext): Promise<OAuthConnection[]>;
+    /** DELETE a linked OAuth connection. */
     unlinkOAuth(provider: OAuthProvider, ctx: OwnsuiteContext): Promise<void>;
 }

package/dist/types/events.d.ts

@@ -20,82 +20,133 @@ export interface OwnsuiteEventBase {
     /** Domain that emitted the event */
     domain: DomainName;
 }
-/** State change event. */
+/** Emitted when a domain transitions between lifecycle states
+ *  (`initializing` → `ready` ↔ `syncing` → `error`). */
 export interface StateChangedEvent extends OwnsuiteEventBase {
+    /** Discriminator. */
     type: "domain:state:changed";
+    /** State before the transition. */
     previousState: DomainState;
+    /** State after the transition. */
     newState: DomainState;
 }
-/** Error event. */
+/** Emitted when a domain's mutation or read fails. */
 export interface ErrorEvent extends OwnsuiteEventBase {
+    /** Discriminator. */
     type: "domain:error";
+    /** The failure — normalized across list / get / mutation paths. */
     error: DomainError;
 }
-/** Sync completed event. */
+/** Emitted when a sync (initialize / refresh / mutation) completes. */
 export interface SyncedEvent extends OwnsuiteEventBase {
+    /** Discriminator. */
     type: "domain:synced";
 }
-/** List fetched event. */
+/** Emitted after a successful list read. */
 export interface ListFetchedEvent extends OwnsuiteEventBase {
+    /** Discriminator. */
     type: "own:list:fetched";
+    /** Number of rows returned. */
     count: number;
 }
-/** Single row fetched event. */
+/** Emitted after a successful single-row read (`getOne`). */
 export interface RowFetchedEvent extends OwnsuiteEventBase {
+    /** Discriminator. */
     type: "own:row:fetched";
+    /** Id of the row that was fetched. */
     rowId: string;
 }
-/** Row created event. */
+/** Emitted after a row is created on the server. */
 export interface RowCreatedEvent extends OwnsuiteEventBase {
+    /** Discriminator. */
     type: "own:row:created";
+    /** Server-assigned id of the new row. */
     rowId: string;
 }
-/** Row updated event. */
+/** Emitted after a row is updated on the server. */
 export interface RowUpdatedEvent extends OwnsuiteEventBase {
+    /** Discriminator. */
     type: "own:row:updated";
+    /** Id of the updated row. */
     rowId: string;
 }
-/** Row deleted event. */
+/** Emitted after a row is deleted on the server. */
 export interface RowDeletedEvent extends OwnsuiteEventBase {
+    /** Discriminator. */
     type: "own:row:deleted";
+    /** Id of the deleted row. */
     rowId: string;
 }
+/** Base fields shared by every auth / profile / session event. Unlike
+ *  {@link OwnsuiteEventBase} there is no `domain` — these events live at the
+ *  suite level, not a specific domain. */
 export interface AuthEventBase {
+    /** Unix millis at emission time. */
     timestamp: number;
 }
+/** Emitted after `AuthManager.register` returns a server response. Fires
+ *  whether or not the verification gate was hit. */
 export interface AuthRegisterEvent extends AuthEventBase {
+    /** Discriminator. */
     type: "auth:register";
+    /** Email the account was created with. */
     email: string;
     /** True when the server requires email verification (no auto-login). */
     requiresVerification: boolean;
 }
+/** Emitted after `AuthManager.login` completes a credential exchange. Does
+ *  not imply `status === "authenticated"` — the verification gate may still
+ *  flip it to `"unverified"` afterwards. */
 export interface AuthLoginEvent extends AuthEventBase {
+    /** Discriminator. */
     type: "auth:login";
+    /** Email used to log in. */
     email: string;
 }
+/** Emitted on `AuthManager.logout` and `deleteAccount` once the session has
+ *  been cleared locally. */
 export interface AuthLogoutEvent extends AuthEventBase {
+    /** Discriminator. */
     type: "auth:logout";
     /** Id of the subject that just logged out, if known. */
     subjectId?: string;
 }
+/** Emitted whenever `SessionManager` persists a new state — including
+ *  hydration-driven changes and `patchSubject` writes. */
 export interface AuthSessionChangedEvent extends AuthEventBase {
+    /** Discriminator. */
     type: "auth:session:changed";
+    /** Snapshot of the session *after* the change. */
     session: SessionState;
 }
+/** Emitted when the server rejects login/register because the account is
+ *  not yet verified. UI should surface a "check your inbox" prompt. */
 export interface AuthVerificationRequiredEvent extends AuthEventBase {
+    /** Discriminator. */
     type: "auth:verification:required";
+    /** Email that needs to be verified. */
     email: string;
 }
+/** Emitted after `ProfileManager.update` succeeds. The session subject has
+ *  already been patched in place by the time this fires. */
 export interface ProfileUpdatedEvent extends AuthEventBase {
+    /** Discriminator. */
     type: "profile:updated";
+    /** Email on the profile *after* the update. */
     email: string;
 }
+/** Emitted after a successful OAuth *link* flow (popup / redirect). */
 export interface OAuthLinkedEvent extends AuthEventBase {
+    /** Discriminator. */
     type: "oauth:linked";
+    /** Connection that was just added to the subject's account. */
     connection: OAuthConnection;
 }
+/** Emitted after `ProfileManager.unlinkOAuth` succeeds. */
 export interface OAuthUnlinkedEvent extends AuthEventBase {
+    /** Discriminator. */
     type: "oauth:unlinked";
+    /** Provider that was just unlinked. */
     provider: OAuthProvider;
 }
 /** All event types union. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/ownsuite",
-	"version": "2.1.0",
+	"version": "2.2.2",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",