@ai-matrx/auth 0.2.0 → 0.2.2

package/dist/active-organization-Dy4UtiyR.d.ts

@@ -0,0 +1,594 @@
+import { SupabaseClient, User, Session, AuthChangeEvent, Provider, UserAttributes } from '@supabase/supabase-js';
+
+/**
+ * @ai-matrx/auth — sign-in and session doors (moved from @ai-matrx/data/auth, 2026-10-09).
+ *
+ * auth owns Supabase sign-in; @ai-matrx/data reads the same client and session for its doors. A package or app asks these doors instead of reaching into
+ * `client.auth.*`; the session leaves for `@ai-matrx/api` only as the `user` credential
+ * (`sessionCredentials(client)`, the shape api's `CredentialsPort` takes, and the same port
+ * `@ai-matrx/data`'s `createDb(...).credentials` returns), so api reads the token and never
+ * signs anyone in.
+ *
+ *   const session = await getSession(supabase);            // Session | null
+ *   const person  = await getPerson(supabase);             // User | null (verified by the server)
+ *   const stop    = onSessionChange(supabase, (event, session) => …);
+ *   await signInWithPassword(supabase, { email, password }); // throws SignInError
+ *   const { url } = await signInWithOAuth(supabase, { provider: "google", redirectTo });
+ *   await signOut(supabase);
+ *   await updatePerson(supabase, { data: { full_name } });
+ *
+ * Every refusal throws `SignInError` carrying the auth server's own message, status and code.
+ */
+
+/** Any supabase-js client (browser, server, route, extension) — only its `auth` is used here. */
+type AuthClient = Pick<SupabaseClient<any, any, any>, "auth">;
+/** A refusal from the auth server — its own message, plus status/code when it sent them. */
+declare class SignInError extends Error {
+    readonly door: string;
+    readonly status?: number;
+    readonly code?: string;
+    constructor(door: string, message: string, status?: number, code?: string);
+}
+/** The stored session (no network unless a refresh is due), or null when signed out. */
+declare function getSession(client: AuthClient): Promise<Session | null>;
+/**
+ * Forget the cached person for this client, so the next {@link getPerson} asks the auth server.
+ * Sign-in, sign-out, a profile edit and an organization switch already call this; call it yourself
+ * only after changing the person outside this package.
+ */
+declare function invalidatePerson(client: AuthClient): void;
+/**
+ * The signed-in person, verified by the auth server, or null when signed out. The verified read is
+ * kept per client until the session changes (sign-in, sign-out, profile edit, organization switch),
+ * so repeated access checks cost zero extra auth-server calls; concurrent callers share one read.
+ */
+declare function getPerson(client: AuthClient): Promise<User | null>;
+/** Hear every session change (sign-in, refresh, sign-out). Returns the unsubscribe. */
+declare function onSessionChange(client: AuthClient, cb: (event: AuthChangeEvent, session: Session | null) => void): () => void;
+declare function signInWithPassword(client: AuthClient, credentials: {
+    email: string;
+    password: string;
+} | {
+    phone: string;
+    password: string;
+}): Promise<{
+    session: Session;
+    person: User;
+}>;
+declare function signInWithOAuth(client: AuthClient, options: {
+    provider: Provider;
+    redirectTo?: string;
+    scopes?: string;
+    queryParams?: Record<string, string>;
+    skipBrowserRedirect?: boolean;
+}): Promise<{
+    provider: Provider;
+    url: string | null;
+}>;
+declare function signOut(client: AuthClient, scope?: "global" | "local" | "others"): Promise<void>;
+/** Change the signed-in person's email, phone, password or metadata. */
+declare function updatePerson(client: AuthClient, attributes: UserAttributes): Promise<User>;
+/** The slice of a client the session credential reads: its `auth`, when it has one. */
+interface SessionSourceLike {
+    auth?: {
+        getSession(): PromiseLike<{
+            data: {
+                session: {
+                    access_token: string;
+                } | null;
+            };
+        }>;
+        onAuthStateChange(cb: (event: string, session: unknown) => void): {
+            data: {
+                subscription: {
+                    unsubscribe(): void;
+                };
+            };
+        };
+    } | undefined;
+}
+/** The `user` credential port (structural; the shape `@ai-matrx/api`'s `CredentialsPort` takes). */
+interface UserCredentialsPort {
+    get(): Promise<{
+        kind: "user";
+        accessToken: string;
+    } | null>;
+    onChange?(cb: () => void): () => void;
+}
+/**
+ * THE ONE session → credential mapping: the current access token as api's `user` credential,
+ * re-read on every call (a refresh rotates it), with `onChange` on every session change.
+ * A client with no `auth` is anonymous (null), never an error.
+ */
+declare function sessionCredentials(client: SessionSourceLike): UserCredentialsPort;
+/** The session as `@ai-matrx/api`'s `user` credential — the name `@ai-matrx/data/auth` shipped. */
+declare const userCredentials: typeof sessionCredentials;
+/**
+ * Refresh the session now (a long-lived script, a desktop app waking from sleep, a tab that was
+ * frozen). Returns the new session; throws `SignInError` when the refresh token is refused.
+ */
+declare function refreshSession(client: AuthClient): Promise<Session>;
+
+/**
+ * Organization-question plumbing that is LOGIC, not store binding (moved from the website's
+ * `orgBootstrapGate`, `organizationRefusal`, `childOrganization`, `adminOrganization`).
+ * Pure: every host input is injected; no Redux, no Next, no window.
+ */
+/** How long a write may wait for the first answer before it is refused anyway. */
+declare const ORGANIZATION_RESOLUTION_TIMEOUT_MS = 10000;
+interface OrganizationBootstrapGate {
+    isResolved(): boolean;
+    /** The organization question has been answered (with an organization or without). Idempotent. */
+    markResolved(): void;
+    /** Wait for the answer or the timeout, whichever first. Always resolves; never rejects. */
+    whenResolved(timeoutMs?: number): Promise<void>;
+    /** Tests and in-place identity swaps only. */
+    reset(): void;
+}
+/** "Nobody has looked yet" is a race, not a fact: a held write waits on this, bounded. */
+declare function createOrganizationBootstrapGate(defaultTimeoutMs?: number): OrganizationBootstrapGate;
+/** True when an error body is the server's "you are not a member of the organization you carried". */
+declare function isNotAMemberRefusal(body: unknown): boolean;
+declare const NOT_A_MEMBER_RECHECK_GAP_MS = 30000;
+interface NotAMemberRefusalNotice {
+    /** True when a recheck was started (at most one per gap, so a burst reads memberships once). */
+    notice(body: unknown, now?: number): boolean;
+    reset(): void;
+}
+declare function createNotAMemberRefusalNotice(recheck: () => void, gapMs?: number): NotAMemberRefusalNotice;
+type ParentOrganization = string | {
+    organization_id?: string | null;
+} | null | undefined;
+/**
+ * A record created as part of an existing parent lives in the PARENT's organization; the explicit
+ * one applies only when the parent names none. A disagreement is announced (`onDisagree`,
+ * default console.warn), never obeyed.
+ */
+declare function resolveChildOrganizationId(parent: ParentOrganization, explicit?: string | null, label?: string, onDisagree?: (message: string) => void): string | null;
+/** What the host knows about the admin lane. */
+interface AdminSeatInput {
+    readonly laneOpen: boolean;
+    readonly organizationId?: string | null;
+    readonly organizationName?: string | null;
+}
+interface AdminSeat {
+    readonly id: string;
+    readonly name: string | null;
+}
+/** The admin organization in force right now, or null (off the lane, or none set). */
+declare function resolveAdminSeat(input: AdminSeatInput | null | undefined): AdminSeat | null;
+/** True when the admin seat differs from the person's own active organization (scope/project/task never ride across). */
+declare function adminSeatReplacesUserContext(input: AdminSeatInput | null | undefined, personOrganizationId: string | null | undefined): boolean;
+
+/**
+ * @ai-matrx/auth/organizations (moved from @ai-matrx/data/organizations, 2026-10-09) — THE active-organization ladder and the account's organization
+ * facts, for every Matrx client (the web, Matrx 2, the extension, Studio).
+ *
+ * 🚨 ONE ACTIVE ORGANIZATION, SET ONCE WHEN THE APP LOADS, NEVER NONE (Arman, 2026-10-07;
+ * organizations STATE rules 10–15). The ladder picks what the UI OPENS to; from then on every
+ * request carries the one active organization the person can see. Reads never filter by it.
+ *
+ * THE RUNGS, each kept only if it is a CURRENT membership:
+ *   1. HELD     — what this tab (web) or this running app (desktop, in memory) already works in;
+ *   2. LAST ACTIVE — `users.user_preferences.last_active_organization_id` (follows the person
+ *                 across devices: STATE rule 12);
+ *   3. START-UP — `users.user_preferences.startup_organization_id` (the "Start-up organization"
+ *                 setting);
+ *   4. FIRST    — the oldest active membership.
+ * Zero memberships → null. A failed read THROWS (the host shows "could not check" and a retry,
+ * never a guess). The ladder's own answer never writes anything (rule 14): only a person's click
+ * writes last active.
+ *
+ * Hosts with extra rungs keep them (the web's `?org=` link rung) and call the pure core here.
+ */
+
+/** One organization the person is an active member of, as every picker draws it. */
+interface OrganizationMembership {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string | null;
+    /** The database-validated 2–3 letters, when the organization has them. */
+    readonly abbreviation: string | null;
+    readonly logoUrl: string | null;
+    /** owner | admin | member (the membership's role). */
+    readonly role: string;
+    /** The person created it (drawn under the favourites, before the rest). */
+    readonly isOwn: boolean;
+    /** Classified in `iam.organizations.settings.test_fixture` — never guessed from a name. */
+    readonly isTestFixture: boolean;
+    /** When the membership began (ISO): the oldest is rung 4. */
+    readonly joinedAt: string;
+    /** When the organization was archived (ISO), or null. Present on every row `readMemberships` returns. */
+    readonly archivedAt?: string | null;
+}
+interface AccountOrganizationChoices {
+    readonly lastActiveOrganizationId: string | null;
+    readonly startupOrganizationId: string | null;
+}
+type OrganizationRung = "held" | "last-active" | "startup" | "first";
+interface ResolvedOrganization<T extends {
+    id: string;
+}> {
+    readonly organization: T;
+    /** Which rung answered (for logs and tests; never shown as a choice). */
+    readonly rung: OrganizationRung;
+}
+interface LadderInput<T extends {
+    id: string;
+}> {
+    readonly memberships: readonly T[];
+    readonly held?: string | null;
+    readonly account?: AccountOrganizationChoices | null;
+    /** Rung 4: the oldest active membership. Omitted: the oldest by `joinedAt`, else the first given. */
+    readonly first?: T | null;
+}
+/**
+ * THE LADDER. Pure: no read, no write. Null only when there are no memberships.
+ */
+declare function resolveActiveOrganization<T extends {
+    id: string;
+    joinedAt?: string;
+}>(input: LadderInput<T>): ResolvedOrganization<T> | null;
+/**
+ * The ladder with its reads deferred: the account's choices are read only when no held
+ * organization answers, and the first membership only when nothing else does. A failed read
+ * throws through.
+ */
+declare function resolveActiveOrganizationLazily<T extends {
+    id: string;
+    joinedAt?: string;
+}>(input: {
+    readonly memberships: readonly T[];
+    readonly held?: string | null;
+    readonly readAccount: () => Promise<AccountOrganizationChoices>;
+    readonly first?: () => Promise<T | null>;
+}): Promise<ResolvedOrganization<T> | null>;
+/** The oldest membership by `joinedAt` (ties and missing dates keep the given order). */
+declare function oldestMembership<T extends {
+    joinedAt?: string;
+}>(memberships: readonly T[]): T | null;
+/**
+ * THE ORDER every organization list uses (the shared OrganizationPicker's): favourites, then the
+ * person's own organizations, then the rest; inside each band the given order is kept.
+ */
+declare function orderOrganizations<T extends {
+    id: string;
+    isOwn?: boolean;
+}>(organizations: readonly T[], favouriteIds: readonly string[]): T[];
+/** Search over the two things a person types: the name and the abbreviation. */
+declare function organizationMatches(org: {
+    name: string;
+    abbreviation?: string | null;
+}, query: string): boolean;
+/** Any supabase-js client (typed or not). */
+type OrganizationsDb = SupabaseClient<any, any, any>;
+/** Which organizations a membership read keeps: the live ones, only the archived ones, or both. */
+type ArchiveFilter = "active" | "archived" | "all";
+interface ReadMembershipsOptions {
+    /** Default `"active"` (archived organizations left out): the ladder and every picker read this. */
+    readonly archived?: ArchiveFilter | undefined;
+}
+/**
+ * Every organization the signed-in person is an ACTIVE member of, through the canonical
+ * membership door (`mbr_for_user`, paged) and the organizations' own rows. By default archived
+ * organizations are left out; `{ archived: "archived" | "all" }` returns the archived ones (view
+ * only: they never answer the ladder) too. Throws when either read fails; [] when there are
+ * none. Ordered by name.
+ */
+declare function readMemberships(db: OrganizationsDb, userId: string, options?: ReadMembershipsOptions): Promise<OrganizationMembership[]>;
+interface ChoicesRow {
+    last_active_organization_id: string | null;
+    startup_organization_id: string | null;
+}
+/** The two columns as the ladder's input. A person with no preferences row has neither. */
+declare function toAccountOrganizationChoices(row: Partial<ChoicesRow> | null | undefined): AccountOrganizationChoices;
+/**
+ * The account's last active and start-up organizations. 🚨 ONLY THE LADDER READS THESE: they
+ * choose what the shell opens to and nothing else. Throws when the read fails.
+ */
+declare function readAccountOrganizationChoices(db: OrganizationsDb, userId: string): Promise<AccountOrganizationChoices>;
+/** Save where the person now works, for their next load on any device. Only a click calls this. Throws on refusal. */
+declare function writeLastActiveOrganization(db: OrganizationsDb, organizationId: string): Promise<void>;
+/** Set (or clear, with null) the Start-up organization setting. Throws on refusal. */
+declare function writeStartupOrganization(db: OrganizationsDb, organizationId: string | null): Promise<void>;
+/** The favourites store's entity type (`platform.user_entity_state`). */
+declare const ORGANIZATION_ENTITY_TYPE = "organization";
+/**
+ * The person's favourite organizations: the platform's per-person flag store
+ * (`public.ues_list`, kind favorite), the same store agent and model favourites use. Throws on
+ * failure.
+ */
+declare function readOrganizationFavourites(db: OrganizationsDb): Promise<string[]>;
+/** Star (true) or unstar (false) one organization. `ues_set` refuses one the person cannot open. Throws on refusal. */
+declare function setOrganizationFavourite(db: OrganizationsDb, organizationId: string, favourite: boolean): Promise<void>;
+/**
+ * What the AI Matrx server's refusal of a request's organization means for the ladder
+ * (`matrx_connect` AuthMiddleware._organization_admission_words via `organization_free.py`):
+ *   - 400 with `detail.organization_admission` "denied" (not a member), "unknown" (no such
+ *     organization) or "archived" → the organization is gone for this person: re-run the ladder;
+ *   - 503 with "unverifiable" (the lookup failed; Retry-After 5) → keep it and retry;
+ *   - anything else → not an organization refusal.
+ */
+type OrganizationRefusal = "lapsed" | "retry" | null;
+declare function classifyOrganizationRefusal(status: number, body: unknown): OrganizationRefusal;
+
+/**
+ * The query key, platform-wide. The server stamps this on every deep link it
+ * emits; `features/admin/users/components/OrganizationsAdminClient.tsx` has
+ * read it since before this module existed. One spelling, in one place.
+ */
+declare const LINK_ORGANIZATION_QUERY_KEY = "org";
+type LinkOrganizationParam = 
+/** No link said anything about an organization. The ladder is untouched. */
+{
+    kind: "absent";
+}
+/** Something was said and it is neither a uuid nor an address. Refused in words, never used. */
+ | {
+    kind: "malformed";
+    raw: string;
+}
+/** A well-formed organization id. Still has to survive the membership check. */
+ | {
+    kind: "named";
+    organizationId: string;
+}
+/** An organization's address (slug). Survives only by matching a membership's slug. */
+ | {
+    kind: "addressed";
+    slug: string;
+};
+/**
+ * Classify one bare `org=` value. The ONE rule for what a value may be, shared
+ * by the URL reader below and the boot resolver's bare-value path.
+ */
+declare function classifyLinkOrganizationValue(raw: string): LinkOrganizationParam;
+/**
+ * Read the key out of a query string, a `URLSearchParams`, or a full URL.
+ * Never throws: a URL this cannot parse is `absent`, because a crash on
+ * arrival is a worse answer than the ladder's own.
+ */
+declare function readLinkOrganizationParam(source: string | URLSearchParams | null | undefined): LinkOrganizationParam;
+interface LinkOrganizationMembership {
+    id: string;
+    name: string;
+    /** The organization's address, so an `addressed` link can be matched. */
+    slug?: string | null;
+}
+interface LinkOrganizationDecisionInput {
+    param: LinkOrganizationParam;
+    /** The person's LIVE memberships. The only authority on what they may open. */
+    memberships: ReadonlyArray<LinkOrganizationMembership>;
+    /** The organization they are working in right now, or null. */
+    currentOrganizationId: string | null;
+    currentOrganizationName?: string | null;
+    /**
+     * The knob `userPreferences.organization.switchOnLinkPrompt` — "switch
+     * organization when a link asks". DEFAULT ON, so an omitted value is `true`.
+     */
+    switchWhenALinkAsks?: boolean;
+    /** The account they are signed in as, for the refusal sentence. */
+    signedInAs?: string | null;
+    /**
+     * The link's organization is one this person is not a member of but IS let into
+     * by a share they accepted (`lib/organizations/linkOrganizationAdmission.ts`).
+     * A share admits and never makes a member, so the answer is `admitted`: nobody
+     * is moved, nothing is refused, and the page opens it as that organization's
+     * guest. Omitted, the answer is exactly what it was before (VERIFIER-15 H4).
+     */
+    admittedByAShare?: boolean;
+    /** Replace any of the default English sentences (a localising host). */
+    messages?: Partial<LinkOrganizationMessages>;
+}
+interface LinkOrganizationMessages {
+    notAMember(signedInAs?: string | null): string;
+    malformed(raw: string): string;
+    switched(toName: string, fromName: string | null): string;
+    offer(toName: string, fromName: string | null): string;
+    offerAction(toName: string): string;
+}
+type LinkOrganizationDecision = 
+/** Nothing to do. No toast, no change. */
+{
+    kind: "no-link";
+}
+/** The link names the organization they are already in. Silent no-op. */
+ | {
+    kind: "already-current";
+    organizationId: string;
+}
+/** Use this organization for this session. `announcement` non-null = they moved. */
+ | {
+    kind: "honoured";
+    organizationId: string;
+    organizationName: string;
+    announcement: string | null;
+}
+/** The knob is off and this would be a real switch. Offer it as a click. */
+ | {
+    kind: "offered";
+    organizationId: string;
+    organizationName: string;
+    message: string;
+    actionLabel: string;
+}
+/**
+ * Not a member, but let in by a share they accepted. Silent: nobody is moved
+ * (a share never makes a member) and nothing was refused (the page opens it).
+ */
+ | {
+    kind: "admitted";
+    organizationId: string;
+}
+/** Malformed, or not theirs. Changes nothing; says so. */
+ | {
+    kind: "refused";
+    reason: "malformed" | "not-a-member";
+    message: string;
+};
+/** What a person reads when the link's organization is not theirs to open. */
+declare function linkOrganizationNotAMemberMessage(signedInAs?: string | null): string;
+/** What a person reads when `org=` is not an organization id at all. */
+declare function linkOrganizationMalformedMessage(raw: string): string;
+/** What a person reads when a link actually moved them. Law 4: never silent. */
+declare function linkOrganizationSwitchAnnouncement(toName: string, fromName: string | null): string;
+/** What a person reads with the knob turned off and a link asking to move them. */
+declare function linkOrganizationOfferMessage(toName: string, fromName: string | null): string;
+/**
+ * The decision. One function, every branch, no side effects.
+ *
+ * 🚨 WHY THE KNOB GOVERNS ONLY A REAL SWITCH. The knob protects the
+ * organization a person is WORKING IN from being yanked out from under them by
+ * a link someone else composed. With `currentOrganizationId === null` there is
+ * nothing to protect and nothing to switch away from: the alternative to
+ * honouring the link is the picker, which is the very dead end this module was
+ * built to end. So the knob turns a SWITCH into an offer; it never turns an
+ * arrival into a refusal. This is deliberate and it is not a hidden default —
+ * with no link present, a null selection stays null exactly as before.
+ */
+declare function decideLinkOrganization(input: LinkOrganizationDecisionInput): LinkOrganizationDecision;
+interface ResolveWithLinkInput<T extends {
+    id: string;
+    name: string;
+    slug?: string | null;
+    joinedAt?: string;
+}> {
+    readonly memberships: readonly T[];
+    /** This tab's held organization (rung 1; a refresh keeps it). */
+    readonly held?: string | null;
+    readonly readAccount: () => Promise<AccountOrganizationChoices>;
+    readonly first?: () => Promise<T | null>;
+    /** The raw `?org=` value, a query string, a URL or URLSearchParams. Omitted = no link. */
+    readonly link?: string | URLSearchParams | null;
+    readonly switchWhenALinkAsks?: boolean | undefined;
+    readonly signedInAs?: string | null | undefined;
+    readonly messages?: Partial<LinkOrganizationMessages> | undefined;
+    /** Asked only when the link already failed the membership check (a share admits, never joins). */
+    readonly admittedByAShare?: ((organizationId: string) => Promise<boolean>) | undefined;
+}
+interface ResolvedWithLink<T> {
+    readonly organization: T;
+    readonly rung: OrganizationRung | "link";
+    /** What the link meant, when it said anything — the host SAYS it (refused / announced / offered). */
+    readonly link: LinkOrganizationDecision;
+}
+/**
+ * The ONE load ladder with the link folded in: held → last active → start-up → first, then the
+ * link's own organization wins ONLY when it is a current membership. Every other link outcome
+ * (refused, offered, already-current, admitted) leaves the ladder's answer standing. Null when
+ * the person has no memberships. A failed read throws through.
+ */
+declare function resolveOrganizationWithLink<T extends {
+    id: string;
+    name: string;
+    slug?: string | null;
+    joinedAt?: string;
+}>(input: ResolveWithLinkInput<T>): Promise<ResolvedWithLink<T> | null>;
+
+/**
+ * THE ACTIVE ORGANIZATION — one per tab / running app, set once when the app loads, never none
+ * while the person has a membership (Arman, 2026-10-07; organizations STATE rules 10–15).
+ *
+ *   const active = createActiveOrganization({ client: supabase });
+ *   await active.load();                       // the ladder: held → last active → start-up → first
+ *   const orgId = await active.ensureOrgId();  // HELD until the ladder answers; never a guess
+ *   await active.switchTo(otherId);            // a person's click: saves last active for next load
+ *
+ * HELD-REQUEST SEMANTICS. A write or server call that needs the organization asks
+ * `ensureOrgId()`: while the ladder is still resolving the call WAITS (it is held, never sent
+ * without an organization and never sent with a guessed one); once resolved it gets the one
+ * active organization; with zero memberships or a failed read it is REFUSED with a named error.
+ * Acting on a record passes that record's own organization (`ensureOrgId(record.organization_id)`),
+ * which wins and never switches the active one.
+ *
+ * 🚨 NEVER A LIST FILTER. Reads show everything the person can see across all their
+ * organizations; nothing here narrows a read. The active organization is only where new things
+ * are saved and which organization a server call runs in.
+ *
+ * The held id is identity-keyed: a different person signing in on the same device never inherits
+ * the last person's organization, and a sign-out resets the store.
+ */
+
+/** Where this tab / app remembers its organization between reloads (identity-keyed). */
+interface HeldOrganizationStore {
+    read(userId: string): string | null | Promise<string | null>;
+    write(userId: string, organizationId: string): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error";
+interface ActiveOrganizationSnapshot {
+    readonly status: ActiveOrganizationStatus;
+    readonly userId: string | null;
+    readonly organizationId: string | null;
+    readonly organization: OrganizationMembership | null;
+    readonly memberships: readonly OrganizationMembership[];
+    /** Which ladder rung answered (or "switched" after a person's click). */
+    readonly rung: OrganizationRung | "switched" | "link" | null;
+    readonly error: string | null;
+}
+declare class NoActiveOrganizationError extends Error {
+    readonly reason: "signed-out" | "no-memberships" | "unreadable";
+    constructor(reason: "signed-out" | "no-memberships" | "unreadable", detail?: string);
+}
+declare class NotAMemberError extends Error {
+    readonly organizationId: string;
+    constructor(organizationId: string);
+}
+interface ActiveOrganization {
+    snapshot(): ActiveOrganizationSnapshot;
+    subscribe(listener: () => void): () => void;
+    /** Run the ladder (again). Resolves with the settled snapshot; never throws. */
+    load(): Promise<ActiveOrganizationSnapshot>;
+    /** The active organization id now, or null while resolving / with none. Sync (api's getter). */
+    current(): string | null;
+    /** THE HELD REQUEST: the record's own organization, else the active one once resolved. */
+    ensureOrgId(recordOrganizationId?: string | null): Promise<string>;
+    /** A person's click: switch, remember for this tab, save as last active for the next load. */
+    switchTo(organizationId: string): Promise<void>;
+    /** Feed a server refusal in: a lapsed organization re-runs the ladder. Returns the class. */
+    handleRefusal(status: number, body: unknown): Promise<"lapsed" | "retry" | null>;
+    dispose(): void;
+}
+interface CreateActiveOrganizationOptions {
+    /** The person's Supabase client (any supabase-js client). */
+    readonly client: OrganizationsDb & AuthClient;
+    /** Where this tab/app holds its choice. Default: browser `sessionStorage` (per tab), else memory. */
+    readonly held?: HeldOrganizationStore | undefined;
+    /** An extra first rung (the web's `?org=` link). Kept only if it is a current membership. */
+    readonly linked?: (() => string | null | undefined) | undefined;
+    /**
+     * The link's own organization (`?org=` uuid or address) as a first-class rung: honoured only when
+     * it is a current membership, otherwise the ladder stands and `onDecision` receives the refusal /
+     * offer / announcement for the host to SAY. Supersedes `linked` when both are given.
+     */
+    readonly link?: {
+        readonly source: () => string | URLSearchParams | null | undefined;
+        readonly switchWhenALinkAsks?: (() => boolean | undefined) | undefined;
+        readonly signedInAs?: (() => string | null | undefined) | undefined;
+        readonly messages?: Partial<LinkOrganizationMessages> | undefined;
+        /** A share admits without making a member (asked only after a not-a-member verdict). */
+        readonly admittedByAShare?: ((organizationId: string) => Promise<boolean>) | undefined;
+        readonly onDecision?: ((decision: LinkOrganizationDecision) => void) | undefined;
+    } | undefined;
+    /**
+     * THE ADMIN SEAT: while the host's admin lane is open, the admin's own organization IS the active
+     * one for every reader (`current()`, `ensureOrgId()`); off the lane the person's own is untouched.
+     * Ignored unless the seat is a current membership. The snapshot always keeps the person's own.
+     */
+    readonly adminSeat?: (() => AdminSeatInput | null | undefined) | undefined;
+    /** Marked resolved whenever the ladder settles (organization or none). */
+    readonly bootstrapGate?: OrganizationBootstrapGate | undefined;
+    /** Minimum gap between ladder re-runs caused by a not-a-member refusal. Default 30 s. */
+    readonly refusalRecheckGapMs?: number | undefined;
+    /** Load as soon as it is created (default true). */
+    readonly autoLoad?: boolean | undefined;
+}
+/** A held store over a `Storage` (browser `sessionStorage` = per tab), identity-keyed. */
+declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, key?: string): HeldOrganizationStore & {
+    read(userId: string): string | null;
+};
+/** Held in memory: the running app's own choice (desktop, scripts, tests). */
+declare function memoryHeldOrganization(): HeldOrganizationStore;
+declare function createActiveOrganization(options: CreateActiveOrganizationOptions): ActiveOrganization;
+
+export { decideLinkOrganization as $, type AuthClient as A, NotAMemberError as B, type CreateActiveOrganizationOptions as C, type NotAMemberRefusalNotice as D, ORGANIZATION_RESOLUTION_TIMEOUT_MS as E, type OrganizationBootstrapGate as F, type OrganizationMembership as G, type HeldOrganizationStore as H, type OrganizationRefusal as I, type OrganizationRung as J, type OrganizationsDb as K, LINK_ORGANIZATION_QUERY_KEY as L, type ResolveWithLinkInput as M, NOT_A_MEMBER_RECHECK_GAP_MS as N, ORGANIZATION_ENTITY_TYPE as O, type ParentOrganization as P, type ResolvedOrganization as Q, type ReadMembershipsOptions as R, type SessionSourceLike as S, type ResolvedWithLink as T, type UserCredentialsPort as U, adminSeatReplacesUserContext as V, classifyLinkOrganizationValue as W, classifyOrganizationRefusal as X, createActiveOrganization as Y, createNotAMemberRefusalNotice as Z, createOrganizationBootstrapGate as _, SignInError as a, isNotAMemberRefusal as a0, linkOrganizationMalformedMessage as a1, linkOrganizationNotAMemberMessage as a2, linkOrganizationOfferMessage as a3, linkOrganizationSwitchAnnouncement as a4, memoryHeldOrganization as a5, oldestMembership as a6, orderOrganizations as a7, organizationMatches as a8, readAccountOrganizationChoices as a9, readLinkOrganizationParam as aa, readMemberships as ab, readOrganizationFavourites as ac, resolveActiveOrganization as ad, resolveActiveOrganizationLazily as ae, resolveAdminSeat as af, resolveChildOrganizationId as ag, resolveOrganizationWithLink as ah, setOrganizationFavourite as ai, storageHeldOrganization as aj, toAccountOrganizationChoices as ak, writeLastActiveOrganization as al, writeStartupOrganization as am, getSession as b, signInWithOAuth as c, signInWithPassword as d, signOut as e, userCredentials as f, getPerson as g, type AccountOrganizationChoices as h, invalidatePerson as i, type ActiveOrganization as j, type ActiveOrganizationSnapshot as k, type ActiveOrganizationStatus as l, type AdminSeat as m, type AdminSeatInput as n, onSessionChange as o, type ArchiveFilter as p, type LadderInput as q, refreshSession as r, sessionCredentials as s, type LinkOrganizationDecision as t, updatePerson as u, type LinkOrganizationDecisionInput as v, type LinkOrganizationMembership as w, type LinkOrganizationMessages as x, type LinkOrganizationParam as y, NoActiveOrganizationError as z };