@authyon/auth 0.2.0-beta.0 → 0.2.0-beta.2

package/dist/index.d.ts

@@ -1,484 +1,75 @@
-/**
- * Organization membership (the Authyon API calls this a "tenant" on the
- * wire — the SDK exposes it as "organization").
- */
-interface Organization {
-    id: string;
-    slug: string;
-    name?: string;
-    description?: string;
-    roles?: string[];
-}
-/** POST /auth/tenants — creates an organization owned by the signed-in user. */
-interface CreateOrganizationParams {
-    name?: string;
-    slug?: string;
-    description?: string;
-}
-/** GET /auth/tenants/{organizationId}/members — confirmed against the live API. */
-interface OrganizationMember {
-    userId: string;
-    email?: string;
-    username?: string;
-    roles?: string[];
-    createdAt?: string;
-    lastLoginAt?: string | null;
-}
-/** POST /auth/tenants/{tenantId}/members — invites a member by e-mail. */
-interface InviteMemberParams {
-    email: string;
-    roles: string[];
-}
-/** Pagination options accepted by list endpoints. */
-interface PageParams {
-    skip?: number;
-    take?: number;
-}
-/** Authenticated user profile. */
-interface User {
-    id: string;
-    email: string;
-    username?: string;
-    emailConfirmed?: boolean;
-    firstName?: string | null;
-    lastName?: string | null;
-    roles?: string[];
-    permissions?: string[];
-    createdAt?: string;
-    lastLoginAt?: string;
-    organizations?: Organization[];
-    activeOrganization?: Organization | null;
-    /** Actions the user must complete before continuing (e.g. confirm e-mail). */
-    pendencies?: string[];
-}
-/** Token pair issued by login / refresh / tenant switch. */
-interface Session {
-    accessToken: string;
-    refreshToken: string;
-    /** Access-token lifetime in seconds (typically 1800). */
-    expiresIn: number;
-    /** Epoch ms when the access token expires (computed client-side). */
-    expiresAt: number;
-    user?: User;
-}
-type TwoFactorMethod = "authenticator" | "email" | "webauthn" | string;
-/** Returned by `login()` when the account has 2FA enabled. */
-interface TwoFactorChallenge {
-    twoFactorRequired: true;
-    challengeToken: string;
-    methods: TwoFactorMethod[];
-    emailHint?: string;
-}
-type LoginResult = {
-    twoFactorRequired: false;
-    session: Session;
-} | TwoFactorChallenge;
-interface RegisterParams {
-    email: string;
-    username?: string;
-    password: string;
-}
-interface LoginParams {
-    /** Provide `email` or `username`. */
-    email?: string;
-    username?: string;
-    password: string;
-    /** Optional organization to scope the session to (sent as `tenantSlug`). */
-    organizationSlug?: string;
-}
-/** A completed WebAuthn ceremony, handed back to the server to finish login/registration. */
-interface WebAuthnAssertion {
-    ceremonyToken: string;
-    /** JSON-serialized `PublicKeyCredential` returned by `navigator.credentials.get()`. */
-    assertionJson: string;
-}
-/** POST /auth/2fa/verify — redeems a challenge from `login()`. */
-interface TwoFactorVerifyParams {
-    challengeToken: string;
-    method: TwoFactorMethod;
-    /** TOTP / email / recovery code. Omit when `method` is `"webauthn"`. */
-    code?: string;
-    /** Required when `method` is `"webauthn"`. */
-    webAuthnAssertion?: WebAuthnAssertion;
-}
-/** GET /auth/2fa/status — per-method enrolment flags, confirmed against the live API. */
-interface TwoFactorStatus {
-    authenticatorEnabled: boolean;
-    authenticatorConfirmedAt?: string | null;
-    emailEnabled: boolean;
-    emailEnabledAt?: string | null;
-    /** Partially redacted (e.g. `"n**********@h***.com"`). */
-    emailHint?: string | null;
-    webAuthnEnabled: boolean;
-    webAuthnCredentialCount: number;
-    webAuthnCredentials: WebAuthnCredential[];
-    remainingRecoveryCodes: number;
-}
-interface AuthenticatorSetup {
-    secret: string;
-    qrSvg: string;
-    otpauthUri: string;
-}
-/**
- * Options handed back by a WebAuthn "start" endpoint: a ceremony token to
- * correlate the "finish" call, plus the WebAuthn options object to pass into
- * `navigator.credentials.get()` / `.create()` (after `JSON.parse`, per the
- * WebAuthn spec — challenge/user.id are base64url strings on the wire).
- *
- * ⚠️ The exact shape of `options` is not published in the OpenAPI schema (no
- * response bodies are documented for any endpoint at the time this SDK was
- * written) — treat it as opaque input to the WebAuthn API.
- */
-interface WebAuthnCeremonyStart {
-    ceremonyToken: string;
-    options: unknown;
-}
-interface WebAuthnCredential {
-    id: string;
-    nickname?: string;
-    createdAt?: string;
-}
-interface SsoProvider {
-    name: string;
-    slug: string;
-    /** URL to redirect the browser to in order to start this provider's flow. */
-    startUrl: string;
-}
-/** GET /auth/me/activities — one audit-trail entry, confirmed against the live API. */
-interface Activity {
-    id: string;
-    eventType: string;
-    occurredAt: string;
-    environmentId?: string;
-    ip?: string;
-    userAgent?: string;
-    /** JSON-encoded string — `JSON.parse` it for the event-specific payload. */
-    payloadJson?: string;
-}
-/** Paginated list envelope returned by `user.activities()`. */
-interface Page<T> {
-    data: T[];
-    /** Item count actually returned for this page. */
-    perPage?: number;
-    pageSize: number;
-    total: number;
-    pages: number;
-    hasNext: boolean;
-    hasPrev: boolean;
-}
-/** A role available within an organization (tenant). */
-interface Role {
-    id: string;
-    name: string;
-    description?: string;
-    permissions?: string[];
-}
-/** GET /auth/sessions — confirmed against the live API. */
-interface SessionInfo {
-    id: string;
-    createdAt: string;
-    expiresAt: string;
-    revokedAt?: string | null;
-    createdFromIp?: string;
-    isActive: boolean;
-    userAgent?: string;
-    lastUsedAt?: string | null;
-    lastUsedFromIp?: string | null;
-}
-/** POST /auth/introspect (RFC 7662) — confirmed against the live API. */
-interface IntrospectResult {
-    active: boolean;
-    sub?: string;
-    username?: string | null;
-    email?: string | null;
-    roles?: string[] | null;
-    permissions?: string[];
-    client_id?: string;
-    scope?: string;
-    exp?: number;
-    iat?: number;
-    jti?: string;
-    token_type?: string;
-}
-/**
- * POST /auth/validate — confirmed against the live API. The wire shape is
- * `{ valid, reason, profile }`, not `{ user, organization }` as the
- * OpenAPI schema (which didn't document response bodies) suggested.
- * `profile` is `null` for machine tokens (there's no user behind them) and
- * for tokens that fail validation.
- */
-interface ValidateResult {
-    valid: boolean;
-    reason?: string | null;
-    user: User | null;
-}
-type AuthEvent = {
-    type: "signed_in";
-    session: Session;
-} | {
-    type: "refreshed";
-    session: Session;
-} | {
-    type: "signed_out";
-};
-type AuthStateListener = (event: AuthEvent) => void;
-/** Pluggable persistence for the token pair. */
-interface TokenStorage {
-    get(): Session | null;
-    set(session: Session): void;
-    clear(): void;
-}
-interface AuthyonClientOptions {
-    /** Publishable environment key (`pk_live_...` / `pk_test_...`). */
-    envKey: string;
-    /** API origin. Defaults to `https://api.authyon.com`. */
-    baseUrl?: string;
-    /** Where tokens are persisted. Defaults to localStorage when available, memory otherwise. */
-    storage?: TokenStorage;
-    /**
-     * Automatically refresh the access token shortly before it expires and
-     * retry once on 401. Defaults to `true`.
-     */
-    autoRefresh?: boolean;
-    /** Custom fetch implementation (useful for tests / non-browser runtimes). */
-    fetch?: typeof fetch;
-}
+import { T as TokenStorage, H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonClient } from './ability-g6nBpOQM.js';
+export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRule, f as AbilitySubject, g as Activity, h as AuthEvent, i as AuthState, j as AuthStateListener, k as AuthenticatorSetup, l as AuthyonAbility, m as AuthyonAbilityBuilder, n as AuthyonAbilityOptions, o as AuthyonClientOptions, p as AuthyonPermissionSource, q as AuthyonSessionController, C as CreateOrganizationInput, F as FetchHttpAdapter, r as HttpAdapterRequest, s as HttpLogEvent, t as HttpLogger, I as IntrospectResult, u as InviteMemberInput, L as LoggingHttpAdapter, v as LoginInput, w as LoginResult, O as Organization, x as OrganizationMember, P as Paged, y as PaginationOptions, R as RegisterInput, z as Role, S as Session, B as SessionControllerOptions, D as SessionInfo, E as SessionSnapshot, G as SessionSnapshotListener, J as SessionStatus, K as SsoProvider, M as TwoFactorChallenge, N as TwoFactorMethod, Q as TwoFactorStatus, U as User, V as ValidateResult, W as VerifyTwoFactorInput, X as WebAuthnAssertion, Y as WebAuthnCeremonyStart, Z as WebAuthnCredential, _ as createAuthyonAbility, $ as createAuthyonRules, a0 as createClient, a1 as hasPermission } from './ability-g6nBpOQM.js';
 
-declare class AuthyonClient {
-    private readonly envKey;
-    private readonly baseUrl;
-    private readonly storage;
-    private readonly autoRefresh;
-    private readonly fetchImpl;
-    private readonly listeners;
-    private refreshInFlight;
-    constructor(options: AuthyonClientOptions);
-    /** Current persisted session, or null when signed out. */
-    getSession(): Session | null;
-    isAuthenticated(): boolean;
-    /**
-     * Returns a valid access token, refreshing it transparently when it is
-     * expired or about to expire. Returns null when signed out.
-     */
-    getAccessToken(): Promise<string | null>;
-    /** Subscribe to sign-in / refresh / sign-out events. Returns an unsubscribe fn. */
-    onAuthStateChange(listener: AuthStateListener): () => void;
-    private emit;
-    private setSession;
-    private clearSession;
-    /**
-     * `/auth/login` and the other endpoints that mint a session don't return
-     * a `user` object on the wire — only `tokens` (plus `twoFactor`, when a
-     * challenge is required). Fetch the profile right after so callers get a
-     * fully-populated `session.user` without an extra manual round trip.
-     * Best-effort: keeps the session usable even if this fetch fails.
-     */
-    private hydrateUser;
-    private request;
-    private toError;
-    /** POST /auth/register — creates a new user (rate-limited to 20/hour per IP). */
-    register(params: RegisterParams): Promise<{
-        id: string;
-    }>;
-    /**
-     * POST /auth/login — authenticates and stores the session, or returns a
-     * 2FA challenge to complete via `verifyTwoFactor()`.
-     */
-    login(params: LoginParams): Promise<LoginResult>;
-    /** POST /auth/2fa/verify — redeems a 2FA challenge from `login()` and stores the session. */
-    verifyTwoFactor(params: TwoFactorVerifyParams): Promise<Session>;
-    /** POST /auth/refresh — rotates the single-use refresh token (single-flight). */
-    refresh(): Promise<Session>;
-    /**
-     * POST /auth/logout — revokes the current refresh token and clears local
-     * state. Pass `{ everywhere: true }` to revoke every session for the user.
-     */
-    logout(options?: {
-        everywhere?: boolean;
-    }): Promise<void>;
-    readonly webauthn: {
-        /** POST /auth/webauthn/login/start — begins a passkey sign-in. */
-        loginStart: (email?: string) => Promise<WebAuthnCeremonyStart>;
-        /**
-         * POST /auth/webauthn/login/finish — completes the passkey ceremony and
-         * stores the session.
-         */
-        loginFinish: (assertion: WebAuthnAssertion) => Promise<Session>;
-    };
-    readonly sso: {
-        /** GET /auth/sso/providers — providers enabled for this environment. */
-        providers: () => Promise<SsoProvider[]>;
-        /**
-         * Builds the URL to redirect the browser to in order to start a
-         * provider's sign-in flow (`GET /auth/sso/{provider}/start`). Navigate
-         * to it directly — e.g. `window.location.href = client.sso.startUrl(...)`.
-         */
-        startUrl: (provider: string, params: {
-            redirectUri: string;
-            state?: string;
-            mode?: string;
-        }) => string;
-        /**
-         * POST /auth/sso/exchange — swaps the one-time code from the provider
-         * callback for tokens and stores the session.
-         */
-        exchange: (code: string) => Promise<Session>;
-    };
-    readonly user: {
-        /** GET /auth/me — fresh profile of the current user. */
-        me: () => Promise<User>;
-        /** GET /auth/sessions — active refresh-token sessions with device/IP data. */
-        sessions: () => Promise<SessionInfo[]>;
-        /** GET /auth/me/activities — paginated recent account activity for the current user. */
-        activities: (params?: PageParams) => Promise<Page<Activity>>;
-        /**
-         * Revokes a single session by id (e.g. one entry from `sessions()`),
-         * signing that device out without affecting the current one.
-         *
-         * ⚠️ Not directly confirmed against the published API reference at the
-         * time this SDK was written — `DELETE /auth/sessions/{id}` follows the
-         * REST convention the rest of the documented API uses, but verify it
-         * against the Authyon dashboard/API reference before relying on it. If
-         * the endpoint differs, override via a raw call to your own backend.
-         */
-        revokeSession: (sessionId: string) => Promise<void>;
-        /** POST /auth/password-reset/request — always resolves (no account enumeration). */
-        requestPasswordReset: (email: string) => Promise<void>;
-        /** POST /auth/password-reset/confirm — sets a new password and revokes all refresh tokens. */
-        confirmPasswordReset: (token: string, newPassword: string) => Promise<void>;
-    };
-    readonly organization: {
-        /** GET /auth/tenants — all organization memberships. */
-        list: () => Promise<Organization[]>;
-        /**
-         * POST /auth/tenants — creates an organization owned by the signed-in
-         * user (only available when self-service organization creation is
-         * enabled for the environment).
-         */
-        create: (params?: CreateOrganizationParams) => Promise<Organization>;
-        /** GET /auth/tenants/{organizationId} — fetch one of the user's organizations by id. */
-        get: (organizationId: string) => Promise<Organization>;
-        /**
-         * PATCH /auth/tenants/{organizationId} — renames the organization.
-         * Requires the `tenants:manage` custom permission on it.
-         */
-        rename: (organizationId: string, name: string) => Promise<Organization>;
-        /** POST /auth/switch-tenant — issues a fresh token scoped to the new organization. */
-        switch: (organizationSlug: string) => Promise<Session>;
-        /** The organization the current session is scoped to, from the cached session — no network call. */
-        current: () => Organization | null;
-        members: {
-            /**
-             * GET /auth/tenants/{organizationId}/members — paginated list of an
-             * organization's members. Consistent with the confirmed-live
-             * `Page<T>` envelope every other `skip`/`take` endpoint returns
-             * (`user.activities()`, `@authyon/server`'s `environment.users.list()`).
-             */
-            list: (organizationId: string, params?: PageParams) => Promise<Page<OrganizationMember>>;
-            /** POST /auth/tenants/{organizationId}/members — invite a member by e-mail. */
-            invite: (organizationId: string, params: InviteMemberParams) => Promise<void>;
-            /** DELETE /auth/tenants/{organizationId}/members/{userId} — remove a member. */
-            remove: (organizationId: string, userId: string) => Promise<void>;
-        };
-        roles: {
-            /** GET /auth/tenants/{organizationId}/roles — roles available in the organization. */
-            list: (organizationId: string) => Promise<Role[]>;
-        };
-    };
-    readonly twoFactor: {
-        /** GET /auth/2fa/status — enrolled methods and recovery code count. */
-        status: () => Promise<TwoFactorStatus>;
-        /** POST /auth/2fa/resend-email — resends the code for an in-flight login challenge. */
-        resendEmail: (challengeToken: string) => Promise<void>;
-        /** POST /auth/2fa/authenticator/setup — returns secret, QR SVG and otpauth URI. */
-        setupAuthenticator: () => Promise<AuthenticatorSetup>;
-        /** POST /auth/2fa/authenticator/confirm — returns 10 single-use recovery codes. */
-        confirmAuthenticator: (code: string) => Promise<{
-            recoveryCodes: string[];
-        }>;
-        /**
-         * POST /auth/2fa/email/enable — two-step opt-in for email-based OTP.
-         * Call without `code` to receive one by e-mail, then call again with
-         * that code to confirm enrolment.
-         */
-        enableEmail: (code?: string) => Promise<void>;
-        /** POST /auth/2fa/disable — turns off a specific 2FA method (requires current password). */
-        disable: (method: TwoFactorMethod, currentPassword: string) => Promise<void>;
-        /**
-         * POST /auth/2fa/recovery-codes/regenerate — rotates the 10 single-use
-         * recovery codes (requires current password).
-         */
-        regenerateRecoveryCodes: (currentPassword: string) => Promise<{
-            recoveryCodes: string[];
-        }>;
-        webauthn: {
-            /** POST /auth/2fa/webauthn/register/start — begins passkey enrolment for 2FA. */
-            registerStart: () => Promise<WebAuthnCeremonyStart>;
-            /** POST /auth/2fa/webauthn/register/finish — finishes passkey enrolment. */
-            registerFinish: (ceremonyToken: string, attestationJson: string, nickname?: string) => Promise<WebAuthnCredential>;
-            /** GET /auth/2fa/webauthn/credentials — the caller's registered passkeys. */
-            credentials: () => Promise<WebAuthnCredential[]>;
-            /** PATCH /auth/2fa/webauthn/credentials/{id} — renames a passkey. */
-            renameCredential: (id: string, nickname: string) => Promise<WebAuthnCredential>;
-            /** DELETE /auth/2fa/webauthn/credentials/{id} — removes a passkey (requires current password). */
-            removeCredential: (id: string, currentPassword: string) => Promise<void>;
-            /**
-             * POST /auth/2fa/webauthn/assertion/start — fetches WebAuthn assertion
-             * options for an in-flight login challenge (2FA method `"webauthn"`).
-             */
-            assertionStart: (challengeToken: string) => Promise<WebAuthnCeremonyStart>;
-        };
-    };
-    /**
-     * POST /auth/introspect — lightweight token introspection (RFC 7662).
-     *
-     * ⚠️ Confirmed live: this endpoint requires the CALLER to also
-     * authenticate, with an environment or tenant client-credentials bearer
-     * token — the end user's own access token doesn't satisfy that (401).
-     * A browser app has no client secret to present, so this will fail from
-     * `@authyon/auth` in practice; call it from your backend via
-     * `@authyon/server` instead.
-     */
-    introspect(token?: string): Promise<IntrospectResult>;
-    /**
-     * POST /auth/validate — recommended: cross-checks DB state, catches
-     * revocation immediately. Same caller-authentication requirement (and
-     * the same practical limitation from the browser) as `introspect()`.
-     */
-    validate(token?: string): Promise<ValidateResult>;
+/** Builds an Authyon browser client through explicit, progressive configuration. */
+declare class AuthyonClientBuilder {
+    private readonly options;
+    constructor(envKey: string);
+    withBaseUrl(baseUrl: string, allowInsecureHttp?: boolean): this;
+    withStorage(storage: TokenStorage): this;
+    withAutomaticRefresh(enabled?: boolean): this;
+    withTimeout(timeoutMs: number): this;
+    withHttpAdapter(httpAdapter: HttpAdapter): this;
+    withHttpLogger(httpLogger: HttpLoggerOptions): this;
+    build(): AuthyonClient;
 }
-/** Convenience factory: `const authyon = createClient({ envKey: "pk_live_..." })`. */
-declare function createClient(options: AuthyonClientOptions): AuthyonClient;
 
-/**
- * Error thrown for any non-2xx Authyon API response.
- *
- * The API uses RFC 7807 problem+json: `{ title, status, detail, code }`.
- * Match on the machine-readable `code` (e.g. `user.email_taken`), never on `title`.
- */
+declare const ErrorCodes: {
+    readonly Unknown: "unknown";
+    readonly NetworkError: "request.network_error";
+    readonly Timeout: "request.timeout";
+    readonly SessionMalformed: "session.malformed";
+    readonly NotAuthenticated: "auth.not_authenticated";
+    readonly InvalidToken: "auth.invalid_token";
+    readonly MissingToken: "auth.missing_token";
+    readonly EmailTaken: "user.email_taken";
+    readonly PasswordWeak: "user.password_weak";
+    readonly PasswordPwned: "user.password_pwned";
+    readonly RateLimited: "rate_limited";
+};
+type KnownErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+type AuthyonErrorCategory = "network" | "timeout" | "authentication" | "authorization" | "validation" | "not_found" | "conflict" | "rate_limit" | "server" | "unknown";
+type AuthyonErrorAction = "retry" | "reauthenticate" | "request_access" | "fix_input" | "not_found" | "resolve_conflict" | "contact_support";
+interface AuthyonErrorInterpretation {
+    category: AuthyonErrorCategory;
+    action: AuthyonErrorAction;
+    retryable: boolean;
+    retryAfter?: number;
+    requestId?: string;
+}
+/** Shared RFC 7807 error implementation used by both public SDKs. */
 declare class AuthyonError extends Error {
     readonly status: number;
     readonly code: string;
     readonly title: string;
     readonly detail?: string;
+    readonly requestId?: string;
+    readonly retryAfter?: number;
+    readonly cause?: unknown;
     constructor(status: number, body: Partial<{
         title: string;
         detail: string;
         code: string;
-    }>);
+    }>, options?: {
+        requestId?: string;
+        retryAfter?: number;
+        cause?: unknown;
+    });
     is(code: string): boolean;
+    isAny(...codes: readonly string[]): boolean;
+    hasPrefix(prefix: string): boolean;
+    isStatus(...statuses: readonly number[]): boolean;
+    /** Stable interpretation for UI decisions, retries, telemetry and support flows. */
+    interpret(): AuthyonErrorInterpretation;
+    get category(): AuthyonErrorCategory;
+    get retryable(): boolean;
+    toJSON(): Record<string, unknown>;
 }
-/** Well-known error codes documented by Authyon. */
-declare const ErrorCodes: {
-    readonly EmailTaken: "user.email_taken";
-    readonly PasswordWeak: "user.password_weak";
-    readonly PasswordPwned: "user.password_pwned";
-};
 
 /** Keeps the session in memory only (lost on page reload). */
-declare function memoryStorage(): TokenStorage;
+declare function createMemoryStorage(): TokenStorage;
 /** Persists the session in `localStorage` under a namespaced key. */
-declare function localStorageAdapter(key?: string): TokenStorage;
-declare function defaultStorage(): TokenStorage;
+declare function createLocalStorage(key?: string): TokenStorage;
+declare function createDefaultStorage(): TokenStorage;
 
-export { type Activity, type AuthEvent, type AuthStateListener, type AuthenticatorSetup, AuthyonClient, type AuthyonClientOptions, AuthyonError, type CreateOrganizationParams, ErrorCodes, type IntrospectResult, type InviteMemberParams, type LoginParams, type LoginResult, type Organization, type OrganizationMember, type Page, type PageParams, type RegisterParams, type Role, type Session, type SessionInfo, type SsoProvider, type TokenStorage, type TwoFactorChallenge, type TwoFactorMethod, type TwoFactorStatus, type TwoFactorVerifyParams, type User, type ValidateResult, type WebAuthnAssertion, type WebAuthnCeremonyStart, type WebAuthnCredential, createClient, defaultStorage, localStorageAdapter, memoryStorage };
+export { AuthyonClient, AuthyonClientBuilder, AuthyonError, type AuthyonErrorAction, type AuthyonErrorCategory, type AuthyonErrorInterpretation, ErrorCodes, HttpAdapter, HttpLoggerOptions, type KnownErrorCode, TokenStorage, createDefaultStorage, createLocalStorage, createMemoryStorage };