@pollar/core 0.6.0 → 0.7.1

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { S as Storage, O as OnStorageDegrade } from './types-DqgJIJBl.mjs';
+export { a as StorageDegradeReason } from './types-DqgJIJBl.mjs';
 import * as openapi_fetch from 'openapi-fetch';
 
 type StellarNetwork = 'mainnet' | 'testnet';
@@ -21,10 +23,70 @@ declare class StellarClient {
     }>;
 }
 
+/**
+ * Public JWK shape for an EC P-256 key. Only the four required members for
+ * RFC 7638 thumbprint computation; never includes private fields or extras
+ * like `alg` / `use` / `kid`.
+ */
+interface PublicEcJwk {
+    kty: 'EC';
+    crv: 'P-256';
+    /** Base64url-encoded big-endian X coordinate (32 bytes). */
+    x: string;
+    /** Base64url-encoded big-endian Y coordinate (32 bytes). */
+    y: string;
+}
+/**
+ * Manages the per-session ECDSA P-256 keypair used to sign DPoP proofs.
+ *
+ * Implementations:
+ * - `WebCryptoKeyManager` (web): non-extractable `CryptoKey` persisted in
+ *   IndexedDB. Private key bytes never leave the browser's crypto context.
+ * - `NobleKeyManager` (React Native): private scalar bytes stored through an
+ *   injected `Storage` adapter (Keychain / SecureStore). Pure-JS ECDSA via
+ *   `@noble/curves`.
+ */
+interface KeyManager {
+    /**
+     * Load an existing key for this session or generate a new one. Idempotent.
+     * Must be called before `getPublicJwk`, `getThumbprint`, or `sign`.
+     */
+    init(): Promise<void>;
+    /**
+     * Destroy the key. Removes it from persistent storage and clears any
+     * cached state. Used on logout.
+     */
+    reset(): Promise<void>;
+    /**
+     * The public JWK that goes into the DPoP proof header. Returns a fresh
+     * object every call (callers may mutate without affecting the manager).
+     */
+    getPublicJwk(): Promise<PublicEcJwk>;
+    /**
+     * RFC 7638 JWK thumbprint, base64url(SHA-256(canonical JWK)). The server
+     * compares this to the access token's `cnf.jkt` claim.
+     */
+    getThumbprint(): Promise<string>;
+    /**
+     * Sign the given bytes with ECDSA-P256-SHA256. Returns 64-byte raw r||s
+     * (IEEE P1363 / JOSE format), NOT DER. Suitable for direct base64url
+     * encoding into the JWS signature segment.
+     */
+    sign(payload: Uint8Array): Promise<Uint8Array>;
+}
+
 declare enum WalletType {
     FREIGHTER = "freighter",
     ALBEDO = "albedo"
 }
+/**
+ * A wallet identifier. Accepts the internal `WalletType` enum values
+ * (`'freighter'`, `'albedo'`) plus any opaque string id used by external
+ * adapter packages (e.g. Stellar Wallets Kit ids like `'xbull'`, `'lobstr'`).
+ * The `(string & {})` keeps autocomplete on the enum values without rejecting
+ * arbitrary strings.
+ */
+type WalletId = WalletType | (string & {});
 interface ConnectWalletResponse {
     address: string;
     publicKey: string;
@@ -44,7 +106,7 @@ interface SignAuthEntryResponse {
     signedAuthEntry: string;
 }
 interface WalletAdapter {
-    type: WalletType;
+    type: WalletId;
     isAvailable(): Promise<boolean>;
     connect(): Promise<ConnectWalletResponse>;
     disconnect(): Promise<void>;
@@ -52,6 +114,12 @@ interface WalletAdapter {
     signTransaction(xdr: string, options?: SignTransactionOptions): Promise<SignTransactionResponse>;
     signAuthEntry(entryXdr: string, options?: SignAuthEntryOptions): Promise<SignAuthEntryResponse>;
 }
+/**
+ * Resolves a {@link WalletAdapter} for a given wallet id. Injected through
+ * `PollarClientConfig.walletAdapter` so wallet implementations (Stellar
+ * Wallets Kit, custom modules, etc.) can live outside `@pollar/core`.
+ */
+type WalletAdapterResolver = (id: WalletId) => WalletAdapter | Promise<WalletAdapter>;
 
 declare class FreighterAdapter implements WalletAdapter {
     readonly type = WalletType.FREIGHTER;
@@ -76,11 +144,102 @@ declare class AlbedoAdapter implements WalletAdapter {
 }
 
 type PollarApplicationConfigResponse = paths['/auth/login']['post']['responses'][200]['content']['application/json'];
+/** Full `/auth/login` response shape — used in transit but NOT persisted. */
 type PollarApplicationConfigContent = PollarApplicationConfigResponse['content'];
+/**
+ * What we actually write to `Storage`. Drops the PII subtree (`data.*`)
+ * which is held in memory only on `PollarClient._profile` after auth.
+ */
+interface PollarPersistedSession {
+    clientSessionId: string;
+    userId: string | null;
+    status: string;
+    token: {
+        accessToken: string;
+        refreshToken: string;
+        expiresAt: number;
+    };
+    user: {
+        id?: string;
+        ready: boolean;
+    };
+    wallet: {
+        publicKey: string | null;
+        existsOnStellar?: boolean;
+        createdAt?: number;
+    };
+}
+/** In-memory user profile (kept on `PollarClient`, never persisted). */
+interface PollarUserProfile {
+    mail: string;
+    first_name: string;
+    last_name: string;
+    avatar: string;
+    providers: {
+        email: {
+            address: string;
+        } | null;
+        google: {
+            id: string;
+        } | null;
+        github: {
+            id: string;
+        } | null;
+        wallet: {
+            address: string;
+        } | null;
+    };
+}
 interface PollarClientConfig {
     stellarNetwork?: StellarNetwork;
     baseUrl?: string;
     apiKey: string;
+    /**
+     * Pluggable storage. Defaults to `defaultStorage()` on web (localStorage
+     * with memory fallback). On RN you must inject one of the adapters from
+     * `@pollar/core/adapters/expo` or `@pollar/core/adapters/react-native-keychain`.
+     */
+    storage?: Storage;
+    /**
+     * Pluggable DPoP key manager. Defaults to `defaultKeyManager(storage,
+     * apiKeyHash)`: WebCrypto in browsers, `@noble/curves` in RN.
+     */
+    keyManager?: KeyManager;
+    /**
+     * Notified when persistent storage silently degrades to in-memory mode
+     * (Safari private browsing quota errors, sandboxed iframes, etc.). Useful
+     * for telemetry — the SDK keeps working but sessions won't survive reload.
+     */
+    onStorageDegrade?: OnStorageDegrade;
+    /**
+     * Resolves a {@link WalletAdapter} for a given wallet id. If omitted, the
+     * SDK falls back to its built-in `FreighterAdapter` / `AlbedoAdapter`,
+     * which only know `WalletType.FREIGHTER` and `WalletType.ALBEDO`. Inject
+     * `@pollar/stellar-wallets-kit-adapter` (or your own resolver) to support
+     * additional wallets without bundling those dependencies into `@pollar/core`.
+     */
+    walletAdapter?: WalletAdapterResolver;
+    /**
+     * Optional human-friendly label sent at /auth/login time and recorded on
+     * the server-side refresh-token row so the user can identify it in the
+     * "active sessions" UI (e.g. "iPhone — Safari", "Mac — Chrome 126").
+     * If unset, the server-recorded `user_agent` header is the fallback.
+     */
+    deviceLabel?: string;
+}
+/**
+ * One row in the active-sessions list (returned by `PollarClient.listSessions()`).
+ * Mirrors the sdk-api `SessionsListContent` schema.
+ */
+interface SessionInfo {
+    familyId: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    userAgent: string | null;
+    ipHash: string | null;
+    deviceLabel: string | null;
+    current: boolean;
+    expiresAt: string;
 }
 type TxBuildBody = NonNullable<paths['/tx/build']['post']['requestBody']>['content']['application/json'];
 type TxBuildResponse = paths['/tx/build']['post']['responses'][200]['content']['application/json'];
@@ -95,7 +254,7 @@ type PollarLoginOptions = {
     email: string;
 } | {
     provider: 'wallet';
-    type: WalletType;
+    type: WalletId;
 };
 type TxBuildContent = TxBuildResponse['content'];
 type TransactionState = {
@@ -155,17 +314,17 @@ type AuthState = {
     provider: 'google' | 'github';
 } | {
     step: 'connecting_wallet';
-    walletType: WalletType;
+    walletType: WalletId;
 } | {
     step: 'wallet_not_installed';
-    walletType: WalletType;
+    walletType: WalletId;
 } | {
     step: 'authenticating_wallet';
 } | {
     step: 'authenticating';
 } | {
     step: 'authenticated';
-    session: PollarApplicationConfigContent;
+    session: PollarPersistedSession;
 } | {
     step: 'error';
     previousStep: string;
@@ -231,12 +390,27 @@ type RampsTransactionResponse = paths['/ramps/transaction/{txId}']['get']['respo
 type RampTxStatus = RampsTransactionResponse['status'];
 type RampDirection = RampsTransactionResponse['direction'];
 type PaymentInstructions = RampsOnrampResponse['paymentInstructions'];
-type EscrowFn<TParams = unknown> = (params: TParams) => Promise<{
+type DistributionRule = paths['/distribution/rules']['get']['responses'][200]['content']['application/json']['content']['rules'][number];
+type RulePeriod = DistributionRule['period'];
+type DistributionClaimBody = NonNullable<paths['/distribution/claim']['post']['requestBody']>['content']['application/json'];
+type DistributionClaimContent = paths['/distribution/claim']['post']['responses'][200]['content']['application/json']['content'];
+type DistributionRulesState = {
+    step: 'idle';
+} | {
+    step: 'loading';
+} | {
+    step: 'loaded';
+    rules: DistributionRule[];
+} | {
+    step: 'error';
+    message: string;
+};
+type AdapterFn<TParams = unknown> = (params: TParams) => Promise<{
     unsignedTransaction: string;
 }>;
-type EscrowAdapter = Record<string, EscrowFn<any>>;
+type PollarAdapter = Record<string, AdapterFn<any>>;
 interface PollarAdapters {
-    [key: string]: EscrowAdapter;
+    [key: string]: PollarAdapter;
 }
 
 declare class PollarClient {
@@ -244,7 +418,39 @@ declare class PollarClient {
     readonly id: string;
     readonly basePath: string;
     private readonly _api;
+    private readonly _storage;
+    private readonly _keyManager;
+    /** Resolves once `keyManager.init()` and the initial session restore complete. */
+    private readonly _initialized;
+    /**
+     * Per-API-key storage namespace. Computed asynchronously inside
+     * `_initialize()` because SHA-256 lives behind `crypto.subtle.digest`.
+     * Accessing `apiKeyHash` before `await client.ready()` throws.
+     */
+    private _apiKeyHash;
+    /**
+     * Short SHA-256-derived namespace for this client's persisted state.
+     * Available after `await client.ready()` (or any awaited method); throws
+     * if read before initialization completes.
+     */
+    get apiKeyHash(): string;
     private _session;
+    private _profile;
+    /** Last `DPoP-Nonce` we saw from a server response. Carried into the next proof. */
+    private _dpopNonce;
+    /**
+     * Snapshot of each in-flight request's body, taken in `onRequest` before
+     * `fetch()` consumes the stream. Needed because `Request.clone()` throws
+     * once the body is disturbed, so the auto-retry path (DPoP nonce challenge
+     * / 401 refresh) must rebuild the request from scratch instead of cloning.
+     */
+    private _requestBodyCache;
+    /** Singleton in-flight refresh — concurrent 401s coalesce into one /auth/refresh call. */
+    private _refreshPromise;
+    private _storageEventHandler;
+    /** Optional UI label sent to the server at /auth/login so the sessions UI
+     *  can show a recognizable device name. Set via PollarClientConfig.deviceLabel. */
+    private readonly _deviceLabel;
     private _transactionState;
     private _transactionStateListeners;
     private _txHistoryState;
@@ -256,17 +462,61 @@ declare class PollarClient {
     private _networkState;
     private _networkStateListeners;
     private _walletAdapter;
+    private readonly _walletAdapterResolver;
     private _loginController;
     constructor(config: PollarClientConfig);
+    /** Awaitable handle for the initial keypair + session restore. */
+    ready(): Promise<void>;
+    private _initialize;
+    /** Detach the cross-tab storage listener and abort any in-flight login. */
+    destroy(): void;
+    private _wireMiddlewares;
+    private _buildProofForRequest;
+    private _retryRequest;
+    /**
+     * Coalesce concurrent refresh attempts. The first caller does the work;
+     * everyone else awaits the same promise and sees the new tokens.
+     */
+    refresh(): Promise<void>;
+    private _doRefresh;
     getAuthState(): AuthState;
     onAuthStateChange(cb: (state: AuthState) => void): () => void;
+    /** PII (email, names, avatar, providers). Held in memory only — never persisted. */
+    getUserProfile(): PollarUserProfile | null;
     login(options: PollarLoginOptions): void;
     beginEmailLogin(): void;
     sendEmailCode(email: string): void;
     verifyEmailCode(code: string): void;
-    loginWallet(type: WalletType): void;
+    loginWallet(type: WalletId): void;
     cancelLogin(): void;
-    logout(): void;
+    /**
+     * Revoke the current session server-side, then clear local storage.
+     *
+     * Server revocation is best-effort: if the POST fails (offline, server
+     * down), local state is wiped regardless. The orphan refresh token then
+     * remains unused until its natural expiry. The in-flight access token
+     * stays valid until its own TTL elapses (≤10 min for DPoP-bound tokens).
+     *
+     * Pass `everywhere: true` to revoke every active session for this user
+     * across all devices.
+     */
+    logout(options?: {
+        everywhere?: boolean;
+    }): Promise<void>;
+    /** Convenience: revoke every active session for this user (all devices). */
+    logoutEverywhere(): Promise<void>;
+    /**
+     * List active sessions for the authenticated user. Returns one entry per
+     * refresh-token family with the metadata captured at issuance time. The
+     * `current` flag identifies which entry corresponds to this client.
+     */
+    listSessions(): Promise<SessionInfo[]>;
+    /**
+     * Revoke a specific refresh-token family (a single device session). Use
+     * `listSessions` to enumerate the familyIds. Revoking the current session
+     * does NOT clear local state — call `logout()` for that case.
+     */
+    revokeSession(familyId: string): Promise<void>;
     getNetwork(): StellarNetwork;
     getNetworkState(): NetworkState;
     setNetwork(network: StellarNetwork): void;
@@ -280,7 +530,7 @@ declare class PollarClient {
     onWalletBalanceStateChange(cb: (state: WalletBalanceState) => void): () => void;
     refreshBalance(publicKey?: string): Promise<void>;
     buildTx(operation: TxBuildBody['operation'], params: TxBuildBody['params'], options?: TxBuildBody['options']): Promise<void>;
-    getWalletType(): WalletType | null;
+    getWalletType(): WalletId | null;
     signAndSubmitTx(unsignedXdr: string): Promise<void>;
     getAppConfig(): Promise<unknown>;
     getKycStatus(providerId?: string): Promise<{
@@ -316,12 +566,19 @@ declare class PollarClient {
         intervalMs?: number;
         timeoutMs?: number;
     }): Promise<RampTxStatus>;
+    listDistributionRules(): Promise<DistributionRule[]>;
+    claimDistributionRule(body: DistributionClaimBody): Promise<DistributionClaimContent>;
     private _setTxHistoryState;
     private _setWalletBalanceState;
-    /** Creates a new AbortController, cancelling any existing flow first. */
     private _newController;
-    /** Builds the deps object passed to flow functions via bind pattern. */
     private _flowDeps;
+    /**
+     * Resolves a wallet adapter for the requested id. Uses the consumer's
+     * injected `walletAdapter` resolver when present; otherwise falls back to
+     * the built-in `FreighterAdapter` / `AlbedoAdapter`. Throws if the id is
+     * unknown and no resolver is configured.
+     */
+    private _resolveWalletAdapter;
     private _handleFlowError;
     private _restoreSession;
     private _storeSession;
@@ -332,6 +589,179 @@ declare class PollarClient {
     private _setTransactionState;
 }
 
+/**
+ * In-memory storage backed by a `Map`. Always available, never throws.
+ * Used as the default fallback for SSR, private browsing, sandboxed iframes
+ * without `allow-same-origin`, or any environment where `localStorage` is
+ * unusable.
+ */
+declare function createMemoryAdapter(): Storage;
+interface LocalStorageAdapterOptions {
+    /**
+     * Optional callback invoked the first time the adapter degrades to its
+     * in-memory fallback (e.g. quota exceeded, throwing `localStorage`).
+     */
+    onDegrade?: OnStorageDegrade;
+}
+/**
+ * `localStorage`-backed adapter that wraps every operation in try/catch and
+ * silently degrades to an in-memory fallback for the rest of the process
+ * lifetime on any throw. A single warning is logged when the degrade happens.
+ *
+ * Why every op (not just the probe): Safari private mode and sandboxed iframes
+ * may expose `localStorage` but throw `QuotaExceededError` / `SecurityError`
+ * on the first write — a successful probe at construction time isn't enough.
+ *
+ * Tokens persisted here are DPoP-bound to a non-extractable WebCrypto
+ * keypair, so XSS exposure is limited to a signing-oracle attack (the key
+ * itself never leaves the browser's crypto subsystem). Consumers who need
+ * stricter isolation can inject a custom `Storage` adapter — e.g. one that
+ * proxies to an httpOnly cookie on a host origin.
+ */
+declare function createLocalStorageAdapter(options?: LocalStorageAdapterOptions): Storage;
+
+/**
+ * Returns `localStorage`-backed storage when it works, otherwise an in-memory
+ * fallback. The probe writes-reads-removes a sentinel; any throw, value
+ * mismatch, or missing `localStorage` (SSR / disabled storage) falls back.
+ *
+ * Run-time degrade still happens inside `createLocalStorageAdapter` — see its
+ * docstring for the rationale.
+ */
+declare function defaultStorage(options?: LocalStorageAdapterOptions): Storage;
+
+/**
+ * Construct the default `KeyManager` for the current runtime. Throws if no
+ * factory has been registered — that only happens if `@pollar/core` was
+ * imported in a way that bypassed the entry-point module (a bundler or
+ * test setup bug).
+ */
+declare function defaultKeyManager(storage: Storage, apiKey: string): KeyManager;
+
+declare class WebCryptoKeyManager implements KeyManager {
+    private readonly apiKey;
+    private apiKeyHash;
+    private keyPair;
+    private publicJwk;
+    private thumbprint;
+    /**
+     * Cached in-flight init. Lets `init()` be called concurrently (or implicitly
+     * from `getPublicJwk` / `sign`) without doing the work twice. Cleared on
+     * failure so callers can retry, and cleared on `reset()`.
+     */
+    private _initPromise;
+    constructor(apiKey: string);
+    /**
+     * Idempotent and safe under concurrency. The first call kicks off the real
+     * init; subsequent (and concurrent) calls return the same in-flight promise.
+     * Other methods (`getPublicJwk`, `getThumbprint`, `sign`) auto-await this so
+     * the manager is self-healing if `init()` was never explicitly invoked.
+     */
+    init(): Promise<void>;
+    private _doInit;
+    reset(): Promise<void>;
+    getPublicJwk(): Promise<PublicEcJwk>;
+    getThumbprint(): Promise<string>;
+    sign(payload: Uint8Array): Promise<Uint8Array>;
+}
+
+/**
+ * Compute the RFC 7638 JWK thumbprint for an EC P-256 public JWK.
+ *
+ * Algorithm (RFC 7638 §3):
+ *  1. Build a JSON object containing ONLY the required members of the JWK,
+ *     ordered lexicographically by member name (Unicode code point).
+ *     For EC keys, that's exactly {crv, kty, x, y}.
+ *  2. Serialize to UTF-8 with no whitespace and no line breaks.
+ *  3. Hash with SHA-256.
+ *  4. Base64url-encode the hash (no padding).
+ *
+ * Common bugs guarded against:
+ * - Including extra fields (`alg`, `use`, `kid`, `ext`, `key_ops`).
+ * - Wrong member ordering (must be lex by Unicode code point).
+ * - Padded base64 instead of base64url unpadded.
+ * - Using `JSON.stringify(jwk)` of an arbitrary-key-order object — we build
+ *   a fresh literal in canonical order to make the order explicit and not
+ *   rely on V8's insertion-order semantics.
+ */
+declare function computeJwkThumbprint(jwk: PublicEcJwk): Promise<string>;
+/**
+ * Strip a JWK to only the four required EC public members. Useful when the
+ * input came from `crypto.subtle.exportKey('jwk', publicKey)` which adds
+ * `ext` / `key_ops`. Returns a fresh object — never mutates input.
+ */
+declare function canonicalEcJwk(jwk: {
+    kty?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+}): PublicEcJwk;
+
+/**
+ * RFC 9449 DPoP proof builder.
+ *
+ * Produces a compact JWS that the consumer attaches as the `DPoP` HTTP
+ * header. The header `jwk` is the public part of the SDK's per-session
+ * keypair; the server verifies the signature, validates the `htm` / `htu` /
+ * `iat` / `jti` / optional `nonce` / optional `ath` claims, and matches the
+ * proof's JWK thumbprint against the access token's `cnf.jkt` claim.
+ *
+ * Server-issued nonce flow (RFC 9449 §8/§9): the server may respond with
+ * `WWW-Authenticate: DPoP ... error="use_dpop_nonce"` plus a `DPoP-Nonce`
+ * header. The client should re-build the proof with the new nonce and retry.
+ * `buildProof` accepts an optional nonce; the SDK client tracks it across
+ * requests and feeds it back here.
+ *
+ * The last seen `DPoP-Nonce` is stored verbatim and embedded in the next
+ * proof. The server validates it as an HMAC token, so an attacker who
+ * injects an arbitrary nonce cannot escalate — verification fails and the
+ * server replies with a fresh nonce on the next request.
+ */
+interface BuildProofArgs {
+    /** HTTP method, e.g. `"GET"`. Will be uppercased before signing. */
+    htm: string;
+    /**
+     * HTTP target URI. Will be normalized per RFC 3986 §6.2 (lowercase scheme
+     * + host, default port elided, query+fragment+userinfo stripped, path
+     * dot-segments resolved, trailing slash preserved exactly as provided).
+     */
+    htu: string;
+    /**
+     * Access token to bind the proof to (its base64url(SHA-256) goes in the
+     * `ath` claim). Omit for proofs sent to the token endpoint per RFC 9449
+     * §5 / §6.1 (those proofs MUST NOT include `ath`).
+     */
+    accessToken?: string;
+    /**
+     * Server-issued DPoP nonce, if the server has previously challenged this
+     * client with `WWW-Authenticate: DPoP ... error="use_dpop_nonce"`. RFC
+     * 9449 §8.
+     */
+    nonce?: string;
+}
+/**
+ * Build a DPoP proof JWS for the given request. Returns the compact-form
+ * JWS string (`<header>.<payload>.<signature>`).
+ */
+declare function buildProof(args: BuildProofArgs, keyManager: KeyManager): Promise<string>;
+/**
+ * Normalize an HTTP URI for use as the `htu` claim.
+ *
+ * RFC 9449 §4.3 + RFC 3986 §6.2:
+ *  - lowercase scheme + host
+ *  - elide default port (`:443` for https, `:80` for http)
+ *  - strip userinfo (never appears in `htu`)
+ *  - strip query + fragment
+ *  - apply path dot-segment removal (handled by the URL constructor)
+ *  - **preserve trailing slash exactly** — `/foo` and `/foo/` are distinct
+ *    paths per RFC 3986 §6 and must round-trip identically.
+ *  - preserve IPv6 brackets in host
+ *
+ * Both client and server must apply the same normalization so the `htu`
+ * claim matches deterministically.
+ */
+declare function normalizeHtu(rawUrl: string): string;
+
 /**
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
@@ -435,6 +865,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/auth/oidc": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Redirect to Authentik OIDC
+         * @description Redirects the user to the Authentik authorization endpoint (PKCE, per-app).
+         */
+        get: operations["getAuthOidc"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/auth/email": {
         parameters: {
             query?: never;
@@ -506,6 +956,83 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/auth/refresh": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Rotate a DPoP-bound refresh token
+         * @description Single-use rotation per RFC 9449 §5. Requires a DPoP proof (no `ath`) bound to the same key as the refresh token (`cnf.jkt`). On reuse outside the 30s grace window, the entire token family is revoked.
+         */
+        post: operations["postAuthRefresh"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/logout": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Revoke the current session (or all sessions)
+         * @description Server-side logout. Default behavior revokes the refresh-token family bound to the current access token. Pass `{"everywhere":true}` to revoke every active family for the authenticated user (logout from all devices).
+         */
+        post: operations["postAuthLogout"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/sessions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List active sessions for the authenticated user
+         * @description Returns one row per active refresh-token family with the metadata captured at issuance (user agent, hashed IP, optional device label). The session whose `current: true` flag matches the access token in use can be highlighted in the UI.
+         */
+        get: operations["getAuthSessions"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/sessions/{familyId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /** Revoke a specific session (refresh-token family) */
+        delete: operations["deleteAuthSessionsByFamilyId"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/applications/config": {
         parameters: {
             query?: never;
@@ -786,6 +1313,46 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/distribution/rules": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List distribution rules
+         * @description Returns every distribution rule defined for the calling application, each decorated with a `claimable` flag and (when not claimable) a `reason` ErrorCode the SDK can map to a UI message (expired, already claimed in window, exhausted, etc.).
+         */
+        get: operations["getDistributionRules"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/distribution/claim": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Claim a distribution rule
+         * @description Executes a claim against the given rule for the authenticated sdk-user. The server runs the same claimability checks as GET /distribution/rules against fresh counts; only the txHash and amount are returned on success.
+         */
+        post: operations["postDistributionClaim"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 interface operations {
     getHealth: {
@@ -905,29 +1472,8 @@ interface operations {
                     "text/event-stream": {
                         status: string;
                         user: {
-                            id?: string;
                             ready: boolean;
                         };
-                        data: {
-                            mail: string;
-                            first_name: string;
-                            last_name: string;
-                            avatar: string;
-                            providers: {
-                                email: {
-                                    address: string;
-                                } | null;
-                                google: {
-                                    id: string;
-                                } | null;
-                                github: {
-                                    id: string;
-                                } | null;
-                                wallet: {
-                                    address: string;
-                                } | null;
-                            };
-                        };
                     };
                 };
             };
@@ -1081,6 +1627,66 @@ interface operations {
             };
         };
     };
+    getAuthOidc: {
+        parameters: {
+            query: {
+                api_key: string;
+                client_session_id: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Redirect to Authentik */
+            302: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Validation error */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+        };
+    };
     postAuthEmail: {
         parameters: {
             query?: never;
@@ -1257,7 +1863,226 @@ interface operations {
             };
         };
     };
-    postAuthWallet: {
+    postAuthWallet: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    clientSessionId: string;
+                    walletAddress: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Wallet authenticated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        code: "SDK_WALLET_AUTHENTICATED";
+                        /** @constant */
+                        success: true;
+                        content: {
+                            clientSessionId: string;
+                            walletAddress: string;
+                        };
+                    };
+                };
+            };
+            /** @description Validation error */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+        };
+    };
+    postAuthLogin: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    clientSessionId: string;
+                    dpopJwk?: {
+                        /** @constant */
+                        kty: "EC";
+                        /** @constant */
+                        crv: "P-256";
+                        x: string;
+                        y: string;
+                    };
+                    deviceLabel?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Authenticated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        code: "SDK_LOGIN_SUCCESS";
+                        /** @constant */
+                        success: true;
+                        content: {
+                            clientSessionId: string;
+                            userId: string | null;
+                            status: string;
+                            token: {
+                                accessToken: string;
+                                refreshToken: string;
+                                expiresAt: number;
+                            };
+                            user: {
+                                id?: string;
+                                ready: boolean;
+                            };
+                            wallet: {
+                                publicKey: string | null;
+                                existsOnStellar?: boolean;
+                                createdAt?: number;
+                            };
+                            data: {
+                                mail: string;
+                                first_name: string;
+                                last_name: string;
+                                avatar: string;
+                                providers: {
+                                    email: {
+                                        address: string;
+                                    } | null;
+                                    google: {
+                                        id: string;
+                                    } | null;
+                                    github: {
+                                        id: string;
+                                    } | null;
+                                    wallet: {
+                                        address: string;
+                                    } | null;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+            /** @description Validation error */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+        };
+    };
+    postAuthRefresh: {
         parameters: {
             query?: never;
             header?: never;
@@ -1267,13 +2092,12 @@ interface operations {
         requestBody: {
             content: {
                 "application/json": {
-                    clientSessionId: string;
-                    walletAddress: string;
+                    refreshToken: string;
                 };
             };
         };
         responses: {
-            /** @description Wallet authenticated */
+            /** @description New token pair issued */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -1281,12 +2105,15 @@ interface operations {
                 content: {
                     "application/json": {
                         /** @constant */
-                        code: "SDK_WALLET_AUTHENTICATED";
+                        code: "SDK_TOKEN_REFRESHED";
                         /** @constant */
                         success: true;
                         content: {
-                            clientSessionId: string;
-                            walletAddress: string;
+                            token: {
+                                accessToken: string;
+                                refreshToken: string;
+                                expiresAt: number;
+                            };
                         };
                     };
                 };
@@ -1345,7 +2172,7 @@ interface operations {
             };
         };
     };
-    postAuthLogin: {
+    postAuthLogout: {
         parameters: {
             query?: never;
             header?: never;
@@ -1355,12 +2182,12 @@ interface operations {
         requestBody: {
             content: {
                 "application/json": {
-                    clientSessionId: string;
+                    everywhere?: boolean;
                 };
             };
         };
         responses: {
-            /** @description Authenticated */
+            /** @description Sessions revoked */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -1368,53 +2195,17 @@ interface operations {
                 content: {
                     "application/json": {
                         /** @constant */
-                        code: "SDK_LOGIN_SUCCESS";
+                        code: "SDK_LOGOUT_SUCCESS";
                         /** @constant */
                         success: true;
                         content: {
-                            clientSessionId: string;
-                            userId: string | null;
-                            status: string;
-                            token: {
-                                accessToken: string;
-                                refreshToken: string;
-                                expiresAt: number;
-                            };
-                            user: {
-                                id?: string;
-                                ready: boolean;
-                            };
-                            wallet: {
-                                publicKey: string | null;
-                                existsOnStellar?: boolean;
-                                createdAt?: number;
-                            };
-                            data: {
-                                mail: string;
-                                first_name: string;
-                                last_name: string;
-                                avatar: string;
-                                providers: {
-                                    email: {
-                                        address: string;
-                                    } | null;
-                                    google: {
-                                        id: string;
-                                    } | null;
-                                    github: {
-                                        id: string;
-                                    } | null;
-                                    wallet: {
-                                        address: string;
-                                    } | null;
-                                };
-                            };
+                            revoked: number;
                         };
                     };
                 };
             };
-            /** @description Validation error */
-            400: {
+            /** @description Unauthorized */
+            401: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -1426,6 +2217,43 @@ interface operations {
                     };
                 };
             };
+        };
+    };
+    getAuthSessions: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Sessions list */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        code: "SDK_SESSIONS_LIST";
+                        /** @constant */
+                        success: true;
+                        content: {
+                            sessions: {
+                                familyId: string;
+                                createdAt: string;
+                                lastUsedAt: string | null;
+                                userAgent: string | null;
+                                ipHash: string | null;
+                                deviceLabel: string | null;
+                                current: boolean;
+                                expiresAt: string;
+                            }[];
+                        };
+                    };
+                };
+            };
             /** @description Unauthorized */
             401: {
                 headers: {
@@ -1439,8 +2267,38 @@ interface operations {
                     };
                 };
             };
-            /** @description Forbidden */
-            403: {
+        };
+    };
+    deleteAuthSessionsByFamilyId: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                familyId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Session revoked */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        code: "SDK_SESSION_REVOKED";
+                        /** @constant */
+                        success: true;
+                        content: {
+                            revoked: number;
+                        };
+                    };
+                };
+            };
+            /** @description Unauthorized */
+            401: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -2677,12 +3535,153 @@ interface operations {
             };
         };
     };
+    getDistributionRules: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description List of distribution rules with claimability verdict per rule */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        code: "SDK_DISTRIBUTION_RULES_LIST";
+                        /** @constant */
+                        success: true;
+                        content: {
+                            rules: {
+                                id: string;
+                                name: string;
+                                assetCode: string;
+                                amount: string;
+                                /** @enum {string} */
+                                period: "DAY" | "DAY_CALENDAR" | "WEEK" | "MONTH" | "MONTH_CALENDAR" | "LIFETIME";
+                                validFrom: string | null;
+                                validUntil: string | null;
+                                claimable: boolean;
+                                reason: string | null;
+                            }[];
+                        };
+                    };
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+        };
+    };
+    postDistributionClaim: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    ruleId: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Claim succeeded — payment submitted to Stellar */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        code: "SDK_DISTRIBUTION_CLAIM_OK";
+                        /** @constant */
+                        success: true;
+                        content: {
+                            ruleId: string;
+                            assetCode: string;
+                            amount: string;
+                            txHash: string | null;
+                        };
+                    };
+                };
+            };
+            /** @description Validation error */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Rule not found, user has no wallet, or application has no distribution wallet */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+            /** @description Rule not claimable (disabled, expired, exhausted, rate-limited) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        error: string;
+                    };
+                };
+            };
+        };
+    };
 }
 
 type PollarApiClient = ReturnType<typeof createApiClient>;
 declare function createApiClient(baseUrl: string): openapi_fetch.Client<paths, `${string}/${string}`>;
 
-declare function isValidSession(value: unknown): value is PollarApplicationConfigContent;
+declare function isValidSession(value: unknown): value is PollarPersistedSession;
 
 /**
  * GET /kyc/status
@@ -2761,4 +3760,18 @@ declare function pollRampTransaction(api: PollarApiClient, txId: string, { inter
     timeoutMs?: number;
 }): Promise<RampTxStatus>;
 
-export { AUTH_ERROR_CODES, AlbedoAdapter, type AuthErrorCode, type AuthState, type ConnectWalletResponse, type EscrowAdapter, type EscrowFn, FreighterAdapter, type KycFlow, type KycLevel, type KycProvider, type KycStartBody, type KycStartResponse, type KycStatus, type NetworkState, type PaymentInstructions, type PollarAdapters, type PollarApiClient, type PollarApplicationConfigContent, type PollarApplicationConfigResponse, PollarClient, type PollarClientConfig, PollarFlowError, type PollarLoginOptions, type RampDirection, type RampQuote, type RampTxStatus, type RampsOfframpBody, type RampsOfframpResponse, type RampsOnrampBody, type RampsOnrampResponse, type RampsQuoteQuery, type RampsQuoteResponse, type RampsTransactionResponse, type SignAuthEntryOptions, type SignAuthEntryResponse, type SignTransactionOptions, type SignTransactionResponse, type StellarBalance, StellarClient, type StellarClientConfig, type StellarNetwork, type TransactionState, type TxBuildBody, type TxBuildContent, type TxBuildResponse, type TxHistoryContent, type TxHistoryParams, type TxHistoryRecord, type TxHistoryState, type TxSignAndSendBody, type TxSignSendResponse, type WalletAdapter, type WalletBalanceContent, type WalletBalanceRecord, type WalletBalanceState, WalletType, createOffRamp, createOnRamp, getKycProviders, getKycStatus, getRampTransaction, getRampsQuote, isValidSession, pollKycStatus, pollRampTransaction, type paths as pollarPaths, resolveKyc, startKyc };
+/**
+ * GET /distribution/rules
+ * Returns the distribution rules visible to the calling sdk-user, each
+ * decorated with `claimable` and (when not claimable) a `reason` ErrorCode
+ * the UI maps to a friendly message.
+ */
+declare function listDistributionRules(api: PollarApiClient): Promise<DistributionRule[]>;
+/**
+ * POST /distribution/claim
+ * Claims the given rule for the authenticated sdk-user. Returns the tx hash
+ * once the payment is submitted to Stellar.
+ */
+declare function claimDistributionRule(api: PollarApiClient, body: DistributionClaimBody): Promise<DistributionClaimContent>;
+
+export { AUTH_ERROR_CODES, type AdapterFn, AlbedoAdapter, type AuthErrorCode, type AuthState, type BuildProofArgs, type ConnectWalletResponse, type DistributionClaimBody, type DistributionClaimContent, type DistributionRule, type DistributionRulesState, FreighterAdapter, type KeyManager, type KycFlow, type KycLevel, type KycProvider, type KycStartBody, type KycStartResponse, type KycStatus, type LocalStorageAdapterOptions, type NetworkState, OnStorageDegrade, type PaymentInstructions, type PollarAdapter, type PollarAdapters, type PollarApiClient, type PollarApplicationConfigContent, type PollarApplicationConfigResponse, PollarClient, type PollarClientConfig, PollarFlowError, type PollarLoginOptions, type PollarPersistedSession, type PollarUserProfile, type PublicEcJwk, type RampDirection, type RampQuote, type RampTxStatus, type RampsOfframpBody, type RampsOfframpResponse, type RampsOnrampBody, type RampsOnrampResponse, type RampsQuoteQuery, type RampsQuoteResponse, type RampsTransactionResponse, type RulePeriod, type SessionInfo, type SignAuthEntryOptions, type SignAuthEntryResponse, type SignTransactionOptions, type SignTransactionResponse, type StellarBalance, StellarClient, type StellarClientConfig, type StellarNetwork, Storage, type TransactionState, type TxBuildBody, type TxBuildContent, type TxBuildResponse, type TxHistoryContent, type TxHistoryParams, type TxHistoryRecord, type TxHistoryState, type TxSignAndSendBody, type TxSignSendResponse, type WalletAdapter, type WalletAdapterResolver, type WalletBalanceContent, type WalletBalanceRecord, type WalletBalanceState, type WalletId, WalletType, WebCryptoKeyManager, buildProof, canonicalEcJwk, claimDistributionRule, computeJwkThumbprint, createLocalStorageAdapter, createMemoryAdapter, createOffRamp, createOnRamp, defaultKeyManager, defaultStorage, getKycProviders, getKycStatus, getRampTransaction, getRampsQuote, isValidSession, listDistributionRules, normalizeHtu, pollKycStatus, pollRampTransaction, type paths as pollarPaths, resolveKyc, startKyc };