@marianmeres/ownsuite 2.2.1 → 2.2.3

package/AGENTS.md

@@ -6,7 +6,7 @@ Machine-readable documentation for AI coding assistants.
 
 ```yaml
 name: "@marianmeres/ownsuite"
-version: "2.0.0"
+version: "2.1.0"
 type: "library"
 language: "typescript"
 runtime: "deno"
@@ -153,7 +153,14 @@ export {
 	createMockAuthAdapter, createMockProfileAdapter,
 	createMockAuthStore, verifyMockAccount,
 } from "./adapters/mod.ts";
-export type { MockAuthStore } from "./adapters/mod.ts";
+export type { MockAccount, MockAuthStore } from "./adapters/mod.ts";
+
+// Upstream types re-exported so they appear in the public doc graph
+// (they already surface as return types of subscribe / on). Not intended
+// as primary consumer API — use them only when typing wrappers.
+export type { PubSub, Subscriber, Unsubscriber } from "@marianmeres/pubsub";
+export type { StoreLike } from "@marianmeres/store";
+export type { Clog } from "@marianmeres/clog";
 ```
 
 ## Account lifecycle (optional)

package/API.md

@@ -360,8 +360,6 @@ interface OwnedRowResult<TRow> {
 }
 ```
 
-Matches `@marianmeres/collection`'s REST envelope.
-
 ### `OwnedCollectionState<TRow>`
 
 ```typescript
@@ -515,7 +513,7 @@ Attached automatically when `adapters.auth` is passed to `createOwnsuite`. See a
 
 ### `createStackAccountAuthAdapter(options?)`
 
-Default `AuthAdapter` pointing at the `@marianmeres/stack-account` REST surface.
+Default `AuthAdapter` pointing at a conventional account REST surface (register / login / logout / OAuth / verify).
 
 **Parameters:**
 - `options` (`StackAccountAdapterOptions`, optional)
@@ -797,9 +795,18 @@ interface StackAccountAdapterOptions {
 
 See [src/oauth/popup.ts](src/oauth/popup.ts) for full definitions. `OAuthPopupMessage` is a union of `OAuthPopupLoginMessage` (`{ type: "oauth_login_success", jwt, email, roles?, ... }`) and `OAuthPopupLinkMessage` (`{ type: "oauth_link_success", provider }`). Errors posted by the server (`{ type: "oauth_error", error }`) cause the promise to reject.
 
-### `MockAuthStore`
+### `MockAccount` / `MockAuthStore`
 
 ```typescript
+interface MockAccount {
+    email: string;
+    password: string;         // plaintext — mock does no hashing
+    roles: string[];
+    isVerified: boolean;
+    hasPassword: boolean;
+    oauthConnections: OAuthConnection[];
+}
+
 interface MockAuthStore {
     accounts: Map<string, MockAccount>;
     requireVerifiedEmail: boolean;
@@ -807,6 +814,8 @@ interface MockAuthStore {
 }
 ```
 
+Fields are public by design so test code can peek at / mutate them directly.
+
 ---
 
 ## Account-lifecycle events

package/README.md

@@ -8,10 +8,7 @@ Client-side helper library for owner-scoped UIs. Generic domain managers with op
 
 ## What it does
 
-Ownsuite gives front-end applications a uniform way to read, create, update and delete records from owner-scoped REST endpoints (typically `/me/*`). Each row is implicitly scoped to the authenticated subject by the server — the client never sets `owner_id`. The library pairs with:
-
-- **@marianmeres/collection** — the `ownerIdScope` route hook enforces owner-based filtering on the server.
-- **@marianmeres/stack-common** — the `ownsuiteOptions()` helper wires the server mount.
+Ownsuite gives front-end applications a uniform way to read, create, update and delete records from owner-scoped REST endpoints (typically `/me/*`). Each row is implicitly scoped to the authenticated subject by the server — the client never sets `owner_id`.
 
 ## Features
 
@@ -24,11 +21,11 @@ Ownsuite gives front-end applications a uniform way to read, create, update and
 - **Event system** — subscribe to list fetches, row CRUD, and lifecycle transitions
 - **Mock adapter** — in-memory fixture for tests, with configurable failure injection and latency
 - **Explicit lifecycle** — `suite.destroy()` aborts in-flight work and releases listeners cleanly
-- **Account lifecycle (opt-in)** — `suite.auth` / `suite.session` / `suite.profile` for register / login / OAuth / verify / logout / profile edit / delete account, wired to pair with `@marianmeres/stack-account` via the bundled default adapters
+- **Account lifecycle (opt-in)** — `suite.auth` / `suite.session` / `suite.profile` for register / login / OAuth / verify / logout / profile edit / delete account, with bundled default adapters for a standard account REST surface
 
 ## Authentication (optional)
 
-Pass an `AuthAdapter` to `createOwnsuite` to attach the account-lifecycle managers. The default adapters target the `@marianmeres/stack-account` REST surface; apps with custom routes can write their own against the `AuthAdapter` / `ProfileAdapter` interfaces exported from this package.
+Pass an `AuthAdapter` to `createOwnsuite` to attach the account-lifecycle managers. The bundled default adapters target a conventional account REST surface (register / login / logout / OAuth / verify / profile CRUD); apps with custom routes can write their own against the `AuthAdapter` / `ProfileAdapter` interfaces exported from this package.
 
 ```typescript
 import {
@@ -58,7 +55,7 @@ suite.session!.subscribe(({ status, subject }) => {
   if (status === "anonymous")    console.log("signed out");
 });
 
-// Register → server requires email verification (default gate in stack-account)
+// Register → server requires email verification by default
 await suite.auth!.register({
   email: "alice@example.com",
   password: "mysecretpassword",
@@ -84,8 +81,8 @@ await suite.profile!.update({
   current_password: "mysecretpassword",
 });
 
-// Logout — revokes JWT server-side (via stack-account's jti deletion) and
-// clears local session storage. Owner-scoped domains reset to initializing.
+// Logout — revokes JWT server-side and clears local session storage.
+// Owner-scoped domains reset to initializing.
 await suite.auth!.logout();
 ```
 

package/dist/adapters/mock-auth.d.ts

@@ -10,15 +10,27 @@
  * adapters close over, so tests can peek at or mutate state directly.
  */
 import type { AuthAdapter, OAuthConnection, ProfileAdapter } from "../types/mod.js";
-interface MockAccount {
+/** In-memory account record held by {@link MockAuthStore}. Test code may
+ *  construct these via the `seed` option of {@link createMockAuthStore}. */
+export interface MockAccount {
+    /** Email (and implicit primary key in the mock store). */
     email: string;
+    /** Plaintext password — the mock runs no hashing. */
     password: string;
+    /** Authorization roles returned on the next login / `/me` read. */
     roles: string[];
+    /** Verified flag — flipped by {@link verifyMockAccount}. */
     isVerified: boolean;
+    /** Whether the account has a local password (OAuth-only accounts: `false`). */
     hasPassword: boolean;
+    /** Linked OAuth provider connections. */
     oauthConnections: OAuthConnection[];
 }
+/** In-memory store backing the mock auth + profile adapters. Pass the same
+ *  store to `createMockAuthAdapter` and `createMockProfileAdapter` so they
+ *  share state. Fields are public so test code can peek or mutate them. */
 export interface MockAuthStore {
+    /** Account records, keyed by email. */
     accounts: Map<string, MockAccount>;
     /** If true, register/login return requiresVerification=true until the
      *  email is explicitly verified via `verifyMockAccount()`. */
@@ -26,13 +38,23 @@ export interface MockAuthStore {
     /** Last-issued JWT per email (just a synthetic string). */
     jwtsByEmail: Map<string, string>;
 }
+/** Create a fresh in-memory {@link MockAuthStore}. Pass `seed` to preload
+ *  accounts, `requireVerifiedEmail: true` to make login gate on verification. */
 export declare function createMockAuthStore(init?: {
+    /** When true, register/login return `requiresVerification: true` until
+     *  the account is verified via {@link verifyMockAccount}. Default: `false`. */
     requireVerifiedEmail?: boolean;
+    /** Accounts to preload into the store. */
     seed?: MockAccount[];
 }): MockAuthStore;
+/** Build an {@link AuthAdapter} backed by the given in-memory
+ *  {@link MockAuthStore}. Simulates register / login / password change /
+ *  delete without a server. JWTs are synthetic strings — do not ship. */
 export declare function createMockAuthAdapter(store: MockAuthStore): AuthAdapter;
+/** Build a {@link ProfileAdapter} backed by the given {@link MockAuthStore}.
+ *  Shares state with an auth adapter created from the same store so login-
+ *  then-`/me` round-trips reflect each other. */
 export declare function createMockProfileAdapter(store: MockAuthStore): ProfileAdapter;
 /** Test helper — mark a mock account as verified as if the user had clicked
  *  the link in the verification email. */
 export declare function verifyMockAccount(store: MockAuthStore, email: string): void;
-export {};

package/dist/adapters/mock-auth.js

@@ -9,6 +9,8 @@
  * Deliberately small: everything is held in a shared `Store` object the
  * adapters close over, so tests can peek at or mutate state directly.
  */
+/** Create a fresh in-memory {@link MockAuthStore}. Pass `seed` to preload
+ *  accounts, `requireVerifiedEmail: true` to make login gate on verification. */
 export function createMockAuthStore(init = {}) {
     const store = {
         accounts: new Map(),
@@ -23,6 +25,9 @@ export function createMockAuthStore(init = {}) {
 function mintJwt(email) {
     return `mock.${btoa(email)}.${Date.now().toString(36)}`;
 }
+/** Build an {@link AuthAdapter} backed by the given in-memory
+ *  {@link MockAuthStore}. Simulates register / login / password change /
+ *  delete without a server. JWTs are synthetic strings — do not ship. */
 export function createMockAuthAdapter(store) {
     return {
         register(input, _ctx) {
@@ -148,6 +153,9 @@ export function createMockAuthAdapter(store) {
         },
     };
 }
+/** Build a {@link ProfileAdapter} backed by the given {@link MockAuthStore}.
+ *  Shares state with an auth adapter created from the same store so login-
+ *  then-`/me` round-trips reflect each other. */
 export function createMockProfileAdapter(store) {
     function emailFromCtx(ctx) {
         const jwt = ctx.jwt;

package/dist/adapters/mock.d.ts

@@ -8,6 +8,8 @@
  * path deterministically.
  */
 import type { OwnedCollectionAdapter } from "../types/adapter.js";
+/** Options for {@link createMockOwnedCollectionAdapter}. Only present in
+ *  tests / storybooks — production code never calls this. */
 export interface MockAdapterOptions<TRow> {
     /** Initial seed rows. */
     seed?: TRow[];

package/dist/adapters/stack-account.d.ts

@@ -28,11 +28,18 @@
  * AuthAdapter / ProfileAdapter interfaces.
  */
 import type { AuthAdapter, ProfileAdapter } from "../types/mod.js";
+/** Options shared by the two stack-account adapter factories. */
 export interface StackAccountAdapterOptions {
     /** Base URL of the mounted stack-account app. Default: "/api/account". */
     baseUrl?: string;
     /** Override the `fetch` implementation (useful for tests / SSR). */
     fetch?: typeof fetch;
 }
+/** Build the default {@link AuthAdapter} for `@marianmeres/stack-account`.
+ *  Points at `{baseUrl}/auth/*` (register/login/logout/verify/password/
+ *  delete) and `{baseUrl}/oauth/*` (init + callback). */
 export declare function createStackAccountAuthAdapter(opts?: StackAccountAdapterOptions): AuthAdapter;
+/** Build the default {@link ProfileAdapter} for `@marianmeres/stack-account`.
+ *  Points at `{baseUrl}/me` (GET + PUT) and `{baseUrl}/me/oauth/*` for
+ *  connection listing / unlinking. */
 export declare function createStackAccountProfileAdapter(opts?: StackAccountAdapterOptions): ProfileAdapter;

package/dist/adapters/stack-account.js

@@ -82,6 +82,9 @@ async function requestJson(doFetch, url, init, ctx) {
         return undefined;
     return (await res.json());
 }
+/** Build the default {@link AuthAdapter} for `@marianmeres/stack-account`.
+ *  Points at `{baseUrl}/auth/*` (register/login/logout/verify/password/
+ *  delete) and `{baseUrl}/oauth/*` (init + callback). */
 export function createStackAccountAuthAdapter(opts = {}) {
     const base = opts.baseUrl ?? "/api/account";
     const doFetch = resolveFetch(opts);
@@ -123,6 +126,9 @@ export function createStackAccountAuthAdapter(opts = {}) {
         },
     };
 }
+/** Build the default {@link ProfileAdapter} for `@marianmeres/stack-account`.
+ *  Points at `{baseUrl}/me` (GET + PUT) and `{baseUrl}/me/oauth/*` for
+ *  connection listing / unlinking. */
 export function createStackAccountProfileAdapter(opts = {}) {
     const base = opts.baseUrl ?? "/api/account";
     const doFetch = resolveFetch(opts);

package/dist/domains/auth.d.ts

@@ -15,13 +15,19 @@ import { type PubSub } from "@marianmeres/pubsub";
 import type { AuthActionOptions, AuthAdapter, AuthTokenResult, OAuthInitOptions, OAuthProvider, OwnsuiteContext, ProfileAdapter } from "../types/mod.js";
 import type { SessionManager } from "./session.js";
 import type { ProfileManager } from "./profile.js";
+/** Construction-time options for {@link AuthManager}. Normally assembled
+ *  by `createOwnsuite` — call sites rarely instantiate this directly. */
 export interface AuthManagerOptions {
+    /** Server adapter. The manager is stateless beyond what it pushes into
+     *  {@link SessionManager}. */
     adapter: AuthAdapter;
+    /** Session manager that receives the JWT / subject / status writes. */
     session: SessionManager;
     /** Profile manager — auth hydrates the session subject from `/me`
      *  immediately after login so subscribers see roles/isVerified/etc.
      *  without a second await. */
     profile: ProfileManager;
+    /** Shared pubsub for event emission. Created privately when omitted. */
     pubsub?: PubSub;
     /** Called after a successful identity change (register/login/OAuth
      *  login/logout). The orchestrator wires this to reset + re-init every
@@ -35,11 +41,30 @@ export interface AuthManagerOptions {
      *  tests that don't need a separate profile fetch. */
     profileAdapter?: ProfileAdapter;
 }
+/**
+ * Verbs for the account lifecycle: register / login / logout / OAuth /
+ * password-reset / delete account. Holds no state of its own — every
+ * outcome is piped into the linked {@link SessionManager}, which is the
+ * single source of truth for JWT + subject + status. Usually accessed via
+ * `suite.auth`, not constructed directly.
+ */
 export declare class AuthManager {
     #private;
+    /** Construct a new `AuthManager`. Normally called by `createOwnsuite`,
+     *  not by consumers. */
     constructor(options: AuthManagerOptions);
+    /** Merge `ctx` into the current adapter context. Keys not in `ctx`
+     *  are preserved. */
     setContext(ctx: OwnsuiteContext): void;
+    /** Replace the adapter context wholesale. Callers use this when
+     *  switching subjects or clearing host-app context. */
     replaceContext(ctx: OwnsuiteContext): void;
+    /** Create a new account. Returns the server's {@link AuthTokenResult}.
+     *  When the verification gate is on, the result carries
+     *  `requiresVerification: true` and the session flips to `"unverified"`
+     *  (no JWT). Otherwise the session flips to `"authenticated"` and the
+     *  profile is hydrated from `/me`. `options.remember` pins the session's
+     *  storage backend — see {@link AuthActionOptions.remember}. */
     register(input: {
         email: string;
         password: string;
@@ -47,25 +72,42 @@ export declare class AuthManager {
         roles?: string[];
         extras?: Record<string, unknown>;
     }, options?: AuthActionOptions): Promise<AuthTokenResult>;
+    /** Exchange credentials for a JWT. On success the session flips to
+     *  `"authenticated"` and the profile is hydrated from `/me`. Rejects
+     *  on bad credentials (session untouched) or — when the server's
+     *  verification gate is on for an unverified account — throws through
+     *  the adapter. `options.remember` controls storage persistence. */
     login(input: {
         email: string;
         password: string;
     }, options?: AuthActionOptions): Promise<AuthTokenResult>;
+    /** Log out. Best-effort server revoke + unconditional local clear;
+     *  the session is always wiped even if the server call fails. Fires
+     *  `auth:logout` and the `onIdentityChanged` hook. Safe to call when
+     *  already anonymous. */
     logout(): Promise<void>;
+    /** Trigger a fresh verification email. Anti-enumeration: always resolves
+     *  regardless of whether the address corresponds to a real account. */
     resendVerification(input: {
         email: string;
         lang?: string;
     }): Promise<void>;
+    /** Trigger a password-reset email. Anti-enumeration: always resolves. */
     requestPasswordReset(input: {
         email: string;
         lang?: string;
     }): Promise<void>;
+    /** Change the password. Pass `current_password` for an authenticated
+     *  self-change, or `token` for a reset-link flow. `new_password` and
+     *  `confirm_password` are always required. */
     changePassword(input: {
         current_password?: string;
         new_password: string;
         confirm_password: string;
         token?: string;
     }): Promise<void>;
+    /** Irreversibly delete the authenticated account. On success clears the
+     *  local session and fires `auth:logout` + `onIdentityChanged`. */
     deleteAccount(input: {
         password?: string;
         confirm?: boolean;

package/dist/domains/auth.js

@@ -13,6 +13,13 @@
  */
 import { createPubSub } from "@marianmeres/pubsub";
 import { openOAuthPopup } from "../oauth/popup.js";
+/**
+ * Verbs for the account lifecycle: register / login / logout / OAuth /
+ * password-reset / delete account. Holds no state of its own — every
+ * outcome is piped into the linked {@link SessionManager}, which is the
+ * single source of truth for JWT + subject + status. Usually accessed via
+ * `suite.auth`, not constructed directly.
+ */
 export class AuthManager {
     #pubsub;
     #adapter;
@@ -20,6 +27,8 @@ export class AuthManager {
     #profile;
     #onIdentityChanged;
     #context;
+    /** Construct a new `AuthManager`. Normally called by `createOwnsuite`,
+     *  not by consumers. */
     constructor(options) {
         this.#adapter = options.adapter;
         this.#session = options.session;
@@ -28,9 +37,13 @@ export class AuthManager {
         this.#onIdentityChanged = options.onIdentityChanged;
         this.#context = options.context ?? {};
     }
+    /** Merge `ctx` into the current adapter context. Keys not in `ctx`
+     *  are preserved. */
     setContext(ctx) {
         this.#context = { ...this.#context, ...ctx };
     }
+    /** Replace the adapter context wholesale. Callers use this when
+     *  switching subjects or clearing host-app context. */
     replaceContext(ctx) {
         this.#context = { ...ctx };
     }
@@ -101,6 +114,12 @@ export class AuthManager {
         return result;
     }
     // ─────────────────────── verbs ──────────────────────────────────────────
+    /** Create a new account. Returns the server's {@link AuthTokenResult}.
+     *  When the verification gate is on, the result carries
+     *  `requiresVerification: true` and the session flips to `"unverified"`
+     *  (no JWT). Otherwise the session flips to `"authenticated"` and the
+     *  profile is hydrated from `/me`. `options.remember` pins the session's
+     *  storage backend — see {@link AuthActionOptions.remember}. */
     async register(input, options) {
         const result = await this.#adapter.register(input, this.#ctx());
         this.#pubsub.publish("auth:register", {
@@ -111,6 +130,11 @@ export class AuthManager {
         });
         return await this.#applyAuthResult(result, options?.remember);
     }
+    /** Exchange credentials for a JWT. On success the session flips to
+     *  `"authenticated"` and the profile is hydrated from `/me`. Rejects
+     *  on bad credentials (session untouched) or — when the server's
+     *  verification gate is on for an unverified account — throws through
+     *  the adapter. `options.remember` controls storage persistence. */
     async login(input, options) {
         const result = await this.#adapter.login(input, this.#ctx());
         this.#pubsub.publish("auth:login", {
@@ -120,6 +144,10 @@ export class AuthManager {
         });
         return await this.#applyAuthResult(result, options?.remember);
     }
+    /** Log out. Best-effort server revoke + unconditional local clear;
+     *  the session is always wiped even if the server call fails. Fires
+     *  `auth:logout` and the `onIdentityChanged` hook. Safe to call when
+     *  already anonymous. */
     async logout() {
         const subjectId = this.#session.get().subject?.id;
         try {
@@ -143,15 +171,23 @@ export class AuthManager {
             }
         }
     }
+    /** Trigger a fresh verification email. Anti-enumeration: always resolves
+     *  regardless of whether the address corresponds to a real account. */
     async resendVerification(input) {
         await this.#adapter.resendVerification(input, this.#ctx());
     }
+    /** Trigger a password-reset email. Anti-enumeration: always resolves. */
     async requestPasswordReset(input) {
         await this.#adapter.requestPasswordReset(input, this.#ctx());
     }
+    /** Change the password. Pass `current_password` for an authenticated
+     *  self-change, or `token` for a reset-link flow. `new_password` and
+     *  `confirm_password` are always required. */
     async changePassword(input) {
         await this.#adapter.changePassword(input, this.#ctx());
     }
+    /** Irreversibly delete the authenticated account. On success clears the
+     *  local session and fires `auth:logout` + `onIdentityChanged`. */
     async deleteAccount(input) {
         await this.#adapter.deleteAccount(input, this.#ctx());
         // Clear session locally and fire logout/identity-change.

package/dist/domains/base.d.ts

@@ -27,12 +27,24 @@ export interface BaseDomainOptions {
  */
 export declare abstract class BaseDomainManager<TData, TAdapter> {
     #private;
+    /** Reactive store holding the full {@link DomainStateWrapper} for this
+     *  domain. Subclasses read + publish through it. */
     protected readonly store: StoreLike<DomainStateWrapper<TData>>;
+    /** Shared pubsub used to emit domain lifecycle / CRUD events. */
     protected readonly pubsub: PubSub;
+    /** Stable name of this domain (used as event `domain` and log prefix). */
     protected readonly domainName: DomainName;
+    /** Scoped logger, prefixed with `ownsuite:<domainName>`. */
     protected readonly clog: Clog;
+    /** Server adapter instance; `null` until `setAdapter()` / constructor
+     *  installs one. */
     protected adapter: TAdapter | null;
+    /** Current context forwarded to every adapter call (jwt, subjectId,
+     *  signal, plus any consumer-supplied extras). */
     protected context: OwnsuiteContext;
+    /** Construct a new domain manager. Not called directly — subclasses like
+     *  {@link OwnedCollectionManager} extend this and are instantiated by
+     *  the suite. */
     constructor(domainName: DomainName, options?: BaseDomainOptions);
     /** Svelte-compatible subscribe method. */
     get subscribe(): StoreLike<DomainStateWrapper<TData>>["subscribe"];
@@ -40,7 +52,11 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
     get(): DomainStateWrapper<TData>;
     /** True after `destroy()` has been called. */
     get isDestroyed(): boolean;
+    /** Install or replace the server adapter for this domain. Call
+     *  {@link refresh} afterwards to pick up data from the new source. */
     setAdapter(adapter: TAdapter): void;
+    /** Current adapter, or `null` when none installed (typically only in
+     *  tests or between `destroy()` and re-attachment). */
     getAdapter(): TAdapter | null;
     /**
      * Merge `ctx` into the current context. Keys not present in `ctx` are
@@ -49,6 +65,8 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
     setContext(context: OwnsuiteContext): void;
     /** Replace the context object entirely (no merge with existing). */
     replaceContext(context: OwnsuiteContext): void;
+    /** Snapshot of the current context. Mutating the returned object does
+     *  not affect the manager. */
     getContext(): OwnsuiteContext;
     /** Transition to a new state. */
     protected setState(state: DomainState): void;
@@ -101,6 +119,8 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
      * callers that prefer a whole-data restore over per-change inversion.
      */
     protected withOptimisticUpdate<T>(operation: string, optimisticUpdate: () => void, serverSync: () => Promise<T>, onSuccess?: (result: T) => void, onError?: (error: DomainError, snapshot: TData | null) => void): Promise<void>;
+    /** Boot the domain — typically fetch its initial list. Subclasses
+     *  implement this; see {@link OwnedCollectionManager.initialize}. */
     abstract initialize(): Promise<void>;
     /**
      * Reset to `initializing` state. Aborts any in-flight reads/mutations

package/dist/domains/base.js

@@ -38,11 +38,20 @@ function safeClone(value) {
  * @typeParam TAdapter - The adapter interface type for server communication.
  */
 export class BaseDomainManager {
+    /** Reactive store holding the full {@link DomainStateWrapper} for this
+     *  domain. Subclasses read + publish through it. */
     store;
+    /** Shared pubsub used to emit domain lifecycle / CRUD events. */
     pubsub;
+    /** Stable name of this domain (used as event `domain` and log prefix). */
     domainName;
+    /** Scoped logger, prefixed with `ownsuite:<domainName>`. */
     clog;
+    /** Server adapter instance; `null` until `setAdapter()` / constructor
+     *  installs one. */
     adapter = null;
+    /** Current context forwarded to every adapter call (jwt, subjectId,
+     *  signal, plus any consumer-supplied extras). */
     context = {};
     /** Mutation chain head. Each create/update/delete appends itself here. */
     #mutationChain = Promise.resolve();
@@ -51,6 +60,9 @@ export class BaseDomainManager {
     /** All active controllers created via `newController()`, for bulk abort. */
     #activeControllers = new Set();
     #destroyed = false;
+    /** Construct a new domain manager. Not called directly — subclasses like
+     *  {@link OwnedCollectionManager} extend this and are instantiated by
+     *  the suite. */
     constructor(domainName, options = {}) {
         this.domainName = domainName;
         this.clog = createClog(`ownsuite:${domainName}`, { color: "auto" });
@@ -76,9 +88,13 @@ export class BaseDomainManager {
     get isDestroyed() {
         return this.#destroyed;
     }
+    /** Install or replace the server adapter for this domain. Call
+     *  {@link refresh} afterwards to pick up data from the new source. */
     setAdapter(adapter) {
         this.adapter = adapter;
     }
+    /** Current adapter, or `null` when none installed (typically only in
+     *  tests or between `destroy()` and re-attachment). */
     getAdapter() {
         return this.adapter;
     }
@@ -93,6 +109,8 @@ export class BaseDomainManager {
     replaceContext(context) {
         this.context = { ...context };
     }
+    /** Snapshot of the current context. Mutating the returned object does
+     *  not affect the manager. */
     getContext() {
         return { ...this.context };
     }

package/dist/domains/owned-collection.d.ts

@@ -16,7 +16,10 @@
 import type { OwnedCollectionAdapter } from "../types/adapter.js";
 import type { OwnedCollectionState } from "../types/state.js";
 import { BaseDomainManager, type BaseDomainOptions } from "./base.js";
+/** Construction-time options for {@link OwnedCollectionManager}. */
 export interface OwnedCollectionManagerOptions<TRow, TCreate, TUpdate> extends BaseDomainOptions {
+    /** Server adapter for this domain. Optional at construction — can be
+     *  installed later with `setAdapter()`. */
     adapter?: OwnedCollectionAdapter<TRow, TCreate, TUpdate>;
     /** Function that extracts the row id from a row. Defaults to `row.model_id`. */
     getRowId?: (row: TRow) => string;
@@ -30,6 +33,8 @@ export interface OwnedCollectionManagerOptions<TRow, TCreate, TUpdate> extends B
  */
 export declare class OwnedCollectionManager<TRow = Record<string, unknown>, TCreate = Partial<TRow>, TUpdate = Partial<TRow>> extends BaseDomainManager<OwnedCollectionState<TRow>, OwnedCollectionAdapter<TRow, TCreate, TUpdate>> {
     #private;
+    /** Build a new manager. Normally called by `Ownsuite.registerDomain`,
+     *  not consumers. */
     constructor(domainName: string, options?: OwnedCollectionManagerOptions<TRow, TCreate, TUpdate>);
     /** Initialize by fetching the list from the server. */
     initialize(): Promise<void>;

package/dist/domains/owned-collection.js

@@ -32,6 +32,8 @@ const defaultGetRowId = (row) => {
  */
 export class OwnedCollectionManager extends BaseDomainManager {
     #getRowId;
+    /** Build a new manager. Normally called by `Ownsuite.registerDomain`,
+     *  not consumers. */
     constructor(domainName, options = {}) {
         super(domainName, options);
         this.#getRowId = options.getRowId ?? defaultGetRowId;

package/dist/domains/profile.d.ts

@@ -20,8 +20,14 @@ import { type StoreLike } from "@marianmeres/store";
 import { type PubSub } from "@marianmeres/pubsub";
 import type { OAuthConnection, OAuthProvider, OwnsuiteContext, ProfileAdapter, ProfileResult } from "../types/mod.js";
 import type { SessionManager } from "./session.js";
+/** Construction-time options for {@link ProfileManager}. Assembled by
+ *  `createOwnsuite` when a profile adapter is supplied. */
 export interface ProfileManagerOptions {
+    /** Profile adapter — talks to `/me`. */
     adapter: ProfileAdapter;
+    /** Session manager — used to patch the subject in place on fetch /
+     *  update so consumers reading the session see updates without a second
+     *  subscription. */
     session: SessionManager;
     /** Shared pubsub for event emission. Private if omitted. */
     pubsub?: PubSub;
@@ -29,6 +35,7 @@ export interface ProfileManagerOptions {
      *  `jwt` and `signal` by the manager. */
     context?: OwnsuiteContext;
 }
+/** Reactive state exposed by {@link ProfileManager.get} / `subscribe`. */
 export interface ProfileState {
     /** Null until the first successful fetch. */
     profile: ProfileResult | null;
@@ -42,10 +49,15 @@ export interface ProfileState {
  */
 export declare class ProfileManager {
     #private;
+    /** Build a new profile manager. Normally called by `createOwnsuite`. */
     constructor(options: ProfileManagerOptions);
+    /** Svelte-compatible subscribe method over {@link ProfileState}. */
     get subscribe(): StoreLike<ProfileState>["subscribe"];
+    /** Current profile state snapshot. */
     get(): ProfileState;
+    /** Merge `ctx` into the adapter context (keys not present are kept). */
     setContext(ctx: OwnsuiteContext): void;
+    /** Replace the adapter context wholesale. */
     replaceContext(ctx: OwnsuiteContext): void;
     /** Fetch `/me`. Supersedes any in-flight fetch. */
     fetch(): Promise<ProfileResult>;
@@ -55,8 +67,14 @@ export declare class ProfileManager {
         email?: string;
         current_password?: string;
     }): Promise<ProfileResult>;
+    /** List OAuth provider connections linked to the authenticated account. */
     listOAuth(): Promise<OAuthConnection[]>;
+    /** Unlink an OAuth provider. Emits `oauth:unlinked` and best-effort
+     *  re-fetches the profile so the connection list reflects the change. */
     unlinkOAuth(provider: OAuthProvider): Promise<void>;
+    /** Abort any in-flight fetch and clear cached profile state. */
     reset(): void;
+    /** Tear down the manager — aborts in-flight fetches and clears state.
+     *  Called by `Ownsuite.destroy()`. */
     destroy(): void;
 }

package/dist/domains/profile.js

@@ -34,6 +34,7 @@ export class ProfileManager {
     #context;
     /** Currently-active read controller, for abort-supersede semantics. */
     #readController = null;
+    /** Build a new profile manager. Normally called by `createOwnsuite`. */
     constructor(options) {
         this.#adapter = options.adapter;
         this.#session = options.session;
@@ -41,15 +42,19 @@ export class ProfileManager {
         this.#context = options.context ?? {};
         this.#store = createStore({ ...EMPTY });
     }
+    /** Svelte-compatible subscribe method over {@link ProfileState}. */
     get subscribe() {
         return this.#store.subscribe;
     }
+    /** Current profile state snapshot. */
     get() {
         return this.#store.get();
     }
+    /** Merge `ctx` into the adapter context (keys not present are kept). */
     setContext(ctx) {
         this.#context = { ...this.#context, ...ctx };
     }
+    /** Replace the adapter context wholesale. */
     replaceContext(ctx) {
         this.#context = { ...ctx };
     }
@@ -139,10 +144,13 @@ export class ProfileManager {
             throw e;
         }
     }
+    /** List OAuth provider connections linked to the authenticated account. */
     async listOAuth() {
         const ctrl = new AbortController();
         return await this.#adapter.listOAuth(this.#ctxFor(ctrl.signal));
     }
+    /** Unlink an OAuth provider. Emits `oauth:unlinked` and best-effort
+     *  re-fetches the profile so the connection list reflects the change. */
     async unlinkOAuth(provider) {
         const ctrl = new AbortController();
         await this.#adapter.unlinkOAuth(provider, this.#ctxFor(ctrl.signal));
@@ -159,10 +167,13 @@ export class ProfileManager {
             // swallow — caller already got a successful unlink
         }
     }
+    /** Abort any in-flight fetch and clear cached profile state. */
     reset() {
         this.#abortActiveRead("reset");
         this.#store.set({ ...EMPTY });
     }
+    /** Tear down the manager — aborts in-flight fetches and clears state.
+     *  Called by `Ownsuite.destroy()`. */
     destroy() {
         this.#abortActiveRead("destroyed");
         this.#store.set({ ...EMPTY });

package/dist/domains/session.d.ts

@@ -22,6 +22,7 @@ export declare function createMemorySessionStorage(): SessionStorage;
  *  Gracefully falls back to memory storage when running in an environment
  *  without Web Storage (SSR, worker without storage, etc). */
 export declare function resolveSessionStorage(type?: SessionStorageType): SessionStorage;
+/** Construction-time options for {@link SessionManager}. */
 export interface SessionManagerOptions {
     /** Storage backend for session persistence. Default: "local". */
     storage?: SessionStorageType;
@@ -45,13 +46,21 @@ export interface SessionManagerOptions {
  */
 export declare class SessionManager {
     #private;
+    /** Build a new session manager. Hydrates synchronously from storage
+     *  (probing `local → session → memory` in the built-in case) before the
+     *  constructor returns, so consumers can read `get()` immediately. */
     constructor(options?: SessionManagerOptions);
     /** Svelte-compatible subscribe. */
     get subscribe(): StoreLike<SessionState>["subscribe"];
     /** Current session state snapshot. */
     get(): SessionState;
+    /** True when `status === "authenticated"`. Shorthand for `get().status`
+     *  checks in consumer code. */
     get isAuthenticated(): boolean;
+    /** True when `status === "unverified"` — account exists but the server
+     *  gates login behind email verification. */
     get isUnverified(): boolean;
+    /** True when `status === "anonymous"` — no session. */
     get isAnonymous(): boolean;
     /** JWT for adapter `Authorization` headers, or null when anonymous. */
     getJwt(): string | null;

package/dist/domains/session.js

@@ -109,6 +109,9 @@ export class SessionManager {
     #defaultStorageType;
     #activeStorage;
     #activeStorageType;
+    /** Build a new session manager. Hydrates synchronously from storage
+     *  (probing `local → session → memory` in the built-in case) before the
+     *  constructor returns, so consumers can read `get()` immediately. */
     constructor(options = {}) {
         this.#pubsub = options.pubsub ?? createPubSub();
         this.#storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
@@ -212,12 +215,17 @@ export class SessionManager {
     get() {
         return this.#store.get();
     }
+    /** True when `status === "authenticated"`. Shorthand for `get().status`
+     *  checks in consumer code. */
     get isAuthenticated() {
         return this.#store.get().status === "authenticated";
     }
+    /** True when `status === "unverified"` — account exists but the server
+     *  gates login behind email verification. */
     get isUnverified() {
         return this.#store.get().status === "unverified";
     }
+    /** True when `status === "anonymous"` — no session. */
     get isAnonymous() {
         return this.#store.get().status === "anonymous";
     }

package/dist/mod.d.ts

@@ -30,3 +30,6 @@ export * from "./domains/mod.js";
 export * from "./types/mod.js";
 export * from "./adapters/mod.js";
 export * from "./oauth/popup.js";
+export type { PubSub, Subscriber, Unsubscriber } from "@marianmeres/pubsub";
+export type { StoreLike } from "@marianmeres/store";
+export type { Clog } from "@marianmeres/clog";

package/dist/oauth/popup.d.ts

@@ -11,37 +11,62 @@
  * For tests, an injectable window-like interface lets us shim `postMessage`
  * via a MessageChannel without a real browser.
  */
+/** `postMessage` shape the server's OAuth callback posts on successful
+ *  login (`action: "login"`). */
 export interface OAuthPopupLoginMessage {
+    /** Discriminator. */
     type: "oauth_login_success";
+    /** Freshly minted JWT. */
     jwt: string;
+    /** Email on the account (after provider-email resolution). */
     email: string;
+    /** Roles assigned to the account. */
     roles?: string[];
+    /** True when the account was created as part of this flow. */
     isNewAccount?: boolean;
+    /** Optional post-login redirect hint the server proposes. */
     redirectUrl?: string;
 }
+/** `postMessage` shape the server posts on successful link
+ *  (`action: "link"`). */
 export interface OAuthPopupLinkMessage {
+    /** Discriminator. */
     type: "oauth_link_success";
+    /** Which provider was just linked. */
     provider: string;
 }
+/** `postMessage` shape the server posts on error. Rejects the promise. */
 export interface OAuthPopupErrorMessage {
+    /** Discriminator. */
     type: "oauth_error";
+    /** Error string suitable for surfacing to the user. */
     error: string;
 }
+/** Union returned by {@link openOAuthPopup}. */
 export type OAuthPopupMessage = OAuthPopupLoginMessage | OAuthPopupLinkMessage;
 /**
  * Minimal window-like surface we need. Real `Window` satisfies this; tests
  * supply a shim.
  */
 export interface PopupWindowHost {
+    /** Open a popup and return a handle, or `null` when blocked. */
     open(url: string, target: string, features?: string): PopupWindowHandle | null;
+    /** Listen for `"message"` events emitted by the popup. */
     addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    /** Stop listening for `"message"` events. */
     removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
 }
+/** Minimal surface of a popup window handle that {@link openOAuthPopup}
+ *  interacts with after `host.open(...)`. */
 export interface PopupWindowHandle {
+    /** Reflects whether the popup has been closed (by the user or server). */
     closed: boolean;
+    /** Bring the popup to the front, when the host supports it. */
     focus?(): void;
+    /** Close the popup programmatically. */
     close?(): void;
 }
+/** Options for {@link openOAuthPopup}. */
 export interface OpenOAuthPopupOptions {
     /** Host window — defaults to `globalThis` when running in the browser. */
     host?: PopupWindowHost;

package/dist/ownsuite.d.ts

@@ -25,7 +25,10 @@ import { SessionManager } from "./domains/session.js";
  * (defaults to reading `row.model_id` or `row.id`).
  */
 export interface OwnsuiteDomainConfig<TRow = any, TCreate = any, TUpdate = any> {
+    /** Adapter that talks to the server for this domain. */
     adapter: OwnedCollectionAdapter<TRow, TCreate, TUpdate>;
+    /** Row-id extractor — used for optimistic update / delete matching.
+     *  Defaults to reading `row.model_id` or `row.id`. */
     getRowId?: (row: TRow) => string;
 }
 /** Top-level ownsuite configuration. */
@@ -76,11 +79,18 @@ export interface SetContextOptions {
  */
 export declare class Ownsuite {
     #private;
-    /** Optional auth/session/profile managers. Present iff `adapters.auth`
-     *  was supplied at construction. */
+    /** Session manager. Present iff `adapters.auth` was supplied at
+     *  construction; otherwise `null`. */
     readonly session: SessionManager | null;
+    /** Auth manager (register/login/OAuth verbs). Present iff
+     *  `adapters.auth` was supplied; otherwise `null`. */
     readonly auth: AuthManager | null;
+    /** Profile manager for `/me`. Present iff BOTH `adapters.auth` and
+     *  `adapters.profile` were supplied; otherwise `null`. */
     readonly profile: ProfileManager | null;
+    /** Build a new suite. See {@link OwnsuiteConfig} for every knob.
+     *  Account-lifecycle managers are attached only when `adapters.auth`
+     *  is supplied. */
     constructor(config?: OwnsuiteConfig);
     /** True after `destroy()` has been called. */
     get isDestroyed(): boolean;
@@ -109,6 +119,7 @@ export declare class Ownsuite {
      *   linger when, e.g., `subjectId` changes).
      */
     setContext(ctx: OwnsuiteContext, options?: SetContextOptions): void;
+    /** Snapshot of the shared context propagated to every domain adapter. */
     getContext(): OwnsuiteContext;
     /** Subscribe to a specific event type. */
     on(type: OwnsuiteEventType, subscriber: Subscriber): Unsubscriber;

package/dist/ownsuite.js

@@ -41,11 +41,18 @@ export class Ownsuite {
     // deno-lint-ignore no-explicit-any
     #domains = new Map();
     #destroyed = false;
-    /** Optional auth/session/profile managers. Present iff `adapters.auth`
-     *  was supplied at construction. */
+    /** Session manager. Present iff `adapters.auth` was supplied at
+     *  construction; otherwise `null`. */
     session = null;
+    /** Auth manager (register/login/OAuth verbs). Present iff
+     *  `adapters.auth` was supplied; otherwise `null`. */
     auth = null;
+    /** Profile manager for `/me`. Present iff BOTH `adapters.auth` and
+     *  `adapters.profile` were supplied; otherwise `null`. */
     profile = null;
+    /** Build a new suite. See {@link OwnsuiteConfig} for every knob.
+     *  Account-lifecycle managers are attached only when `adapters.auth`
+     *  is supplied. */
     constructor(config = {}) {
         this.#pubsub = createPubSub();
         this.#context = { ...(config.context ?? {}) };
@@ -221,6 +228,7 @@ export class Ownsuite {
             }
         }
     }
+    /** Snapshot of the shared context propagated to every domain adapter. */
     getContext() {
         return { ...this.#context };
     }

package/dist/types/adapter.d.ts

@@ -15,7 +15,9 @@ import type { OwnsuiteContext } from "./state.js";
  * whatever shape their server uses and map it here.
  */
 export interface OwnedListResult<TRow> {
+    /** Rows returned by the list call. */
     data: TRow[];
+    /** Pagination / total-count / any arbitrary server-supplied metadata. */
     meta: Record<string, unknown>;
 }
 /**
@@ -23,7 +25,9 @@ export interface OwnedListResult<TRow> {
  * collection package's REST envelope.
  */
 export interface OwnedRowResult<TRow> {
+    /** The row. */
     data: TRow;
+    /** Optional per-row metadata from the server. */
     meta?: Record<string, unknown>;
 }
 /**

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;
@@ -107,33 +131,60 @@ export interface AuthActionOptions {
  * 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;
@@ -148,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;
@@ -171,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.2.1",
+	"version": "2.2.3",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",