@pollar/core 0.9.0-rc.0 → 0.9.0-rc.2

package/README.md

@@ -205,6 +205,41 @@ Same as React (`useSyncExternalStore`), plus the entry-file polyfills and inject
 React Native sections above. OAuth and external-wallet logins require `openAuthUrl` / `walletAdapter` to be injected
 (the built-in popup/extension adapters are web-only).
 
+## Logging
+
+The SDK logs through a level-gated logger. Configure it on `PollarClient`:
+
+```ts
+const client = new PollarClient({
+  apiKey: 'pk_...',
+  logLevel: 'warn', // 'silent' | 'error' | 'warn' | 'info' | 'debug' (default 'info')
+});
+```
+
+Levels are ordered `silent` < `error` < `warn` < `info` < `debug`; setting one emits that level and every more
+important one. `silent` disables all SDK logging. State-transition chatter (`auth:…`, `transaction:…`, `network:…`)
+and retry warnings live at `debug`, so the default `info` keeps the console quiet while still showing lifecycle events
+(Initialized, Session stored/restored, Tokens refreshed) and all warnings/errors.
+
+Route logs to your own sink (pino, Sentry breadcrumbs, a test spy…) with `logger` — filtering by `logLevel` still
+applies on top:
+
+```ts
+import { PollarClient, type PollarLogger } from '@pollar/core';
+
+const sink: PollarLogger = {
+  error: (...a) => myLogger.error(...a),
+  warn: (...a) => myLogger.warn(...a),
+  info: (...a) => myLogger.info(...a),
+  debug: (...a) => myLogger.debug(...a),
+};
+
+const client = new PollarClient({ apiKey: 'pk_...', logLevel: 'debug', logger: sink });
+```
+
+`client.getLogger()` returns the configured logger (used internally by `@pollar/react` so its own logs honor the same
+level + sink). `@pollar/stellar-wallets-kit-adapter` accepts the same `logLevel` / `logger` on its options.
+
 ## Preserved-on-disk storage shape
 
 0.7.0 persists exactly:

package/dist/index.d.mts

@@ -3,6 +3,34 @@ export { a as StorageDegradeReason } from './types-DqgJIJBl.mjs';
 import { V as VisibilityProvider } from './types-Dyky8g0p.mjs';
 import * as openapi_fetch from 'openapi-fetch';
 
+/**
+ * Log levels in increasing verbosity. Setting a level emits that level and
+ * every more-important one; `silent` disables all SDK logging.
+ *
+ *   silent < error < warn < info < debug
+ */
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/**
+ * Sink the SDK writes logs to. The global `console` already satisfies this
+ * shape, so it's the default. Inject your own (pino, Sentry breadcrumbs, a test
+ * spy…) via `PollarClientConfig.logger` to route SDK logs wherever you want.
+ */
+interface PollarLogger {
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+/**
+ * Build a level-gated logger over a sink. The returned object has the same
+ * method surface as {@link PollarLogger}; each call is silently dropped when its
+ * level is more verbose than the configured `level`. Messages keep their own
+ * `[PollarClient…]` prefixes, so this only adds filtering + sink routing.
+ *
+ * Defaults: `level = 'info'`, `sink = console`.
+ */
+declare function createLogger(level?: LogLevel, sink?: PollarLogger): PollarLogger;
+
 type StellarNetwork = 'mainnet' | 'testnet';
 type StellarClientConfig = StellarNetwork | {
     horizonUrl: string;
@@ -173,7 +201,7 @@ interface PollarPersistedSession {
         ready: boolean;
     };
     wallet: {
-        type: 'custodial' | 'smart' | 'external';
+        type: 'internal' | 'smart' | 'external';
         address: string | null;
         existsOnStellar?: boolean;
         createdAt?: number;
@@ -218,6 +246,19 @@ interface PollarClientConfig {
      * apiKey)`: WebCrypto in browsers, `@noble/curves` in RN.
      */
     keyManager?: KeyManager;
+    /**
+     * Minimum severity the SDK logs. `silent` disables all SDK logging; the rest
+     * emit that level and everything more important (`error` < `warn` < `info` <
+     * `debug`). State-transition chatter (auth/tx/network) is at `debug`.
+     * Defaults to `'info'`.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Sink the SDK writes logs to. Defaults to the global `console`. Inject your
+     * own (pino, Sentry breadcrumbs, a test spy…) to route SDK logs anywhere.
+     * Filtering by `logLevel` still applies on top of whatever you pass.
+     */
+    logger?: PollarLogger;
     /**
      * Notified when persistent storage silently degrades to in-memory mode
      * (Safari private browsing quota errors, sandboxed iframes, etc.). Useful
@@ -683,6 +724,7 @@ declare class PollarClient {
     readonly id: string;
     readonly basePath: string;
     private readonly _api;
+    private readonly _log;
     private readonly _storage;
     private readonly _keyManager;
     /** Resolves once `keyManager.init()` and the initial session restore complete. */
@@ -873,6 +915,12 @@ declare class PollarClient {
     revokeSession(familyId: string): Promise<void>;
     getNetwork(): StellarNetwork;
     getNetworkState(): NetworkState;
+    /**
+     * The client's level-gated logger (built from `logLevel` / `logger`). Exposed
+     * so the runtime layer (`@pollar/react`) can route its own logs through the
+     * same level and sink instead of calling `console` directly.
+     */
+    getLogger(): PollarLogger;
     setNetwork(network: StellarNetwork): void;
     onNetworkStateChange(cb: (state: NetworkState) => void): () => void;
     getTransactionState(): TransactionState | null;
@@ -1097,6 +1145,11 @@ interface LocalStorageAdapterOptions {
      * in-memory fallback (e.g. quota exceeded, throwing `localStorage`).
      */
     onDegrade?: OnStorageDegrade;
+    /**
+     * Logger for the one-shot degrade warning. Defaults to the global `console`;
+     * `PollarClient` passes its level-gated logger so `logLevel` applies here too.
+     */
+    logger?: PollarLogger;
 }
 /**
  * `localStorage`-backed adapter that wraps every operation in try/catch and
@@ -5751,7 +5804,7 @@ interface operations {
 type PollarApiClient = ReturnType<typeof createApiClient>;
 declare function createApiClient(baseUrl: string): openapi_fetch.Client<paths, `${string}/${string}`>;
 
-declare function isValidSession(value: unknown): value is PollarPersistedSession;
+declare function isValidSession(value: unknown, logger?: PollarLogger): value is PollarPersistedSession;
 
 /**
  * GET /kyc/status
@@ -5844,4 +5897,4 @@ declare function listDistributionRules(api: PollarApiClient): Promise<Distributi
  */
 declare function claimDistributionRule(api: PollarApiClient, body: DistributionClaimBody): Promise<DistributionClaimContent>;
 
-export { AUTH_ERROR_CODES, type AdapterFn, AlbedoAdapter, type AuthErrorCode, type AuthOpenContext, type AuthState, type AuthUrlOpener, type BuildOutcome, type BuildProofArgs, type ConnectWalletResponse, type DistributionClaimBody, type DistributionClaimContent, type DistributionRule, type DistributionRulesState, type EnabledAssetRecord, type EnabledAssetsState, FreighterAdapter, type KeyManager, type KycFlow, type KycLevel, type KycProvider, type KycStartBody, type KycStartResponse, type KycStatus, type LocalStorageAdapterOptions, type NetworkState, OnStorageDegrade, POLLAR_CORE_VERSION, type PasskeyCeremony, type PasskeySigner, 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 SessionsState, type SignAuthEntryOptions, type SignAuthEntryResponse, type SignOutcome, type SignTransactionOptions, type SignTransactionResponse, type StellarBalance, StellarClient, type StellarClientConfig, type StellarNetwork, Storage, type SubmitOutcome, type TransactionState, type TxBuildBody, type TxBuildContent, type TxBuildResponse, type TxBuildSignSubmitBody, type TxBuildSignSubmitContent, type TxBuildSignSubmitResponse, type TxErrorPhase, type TxHistoryContent, type TxHistoryParams, type TxHistoryRecord, type TxHistoryState, type TxSignAndSendBody, type TxSignBody, type TxSignContent, type TxSignResponse, type TxSignSendResponse, type TxSubmitSignedBody, type WalletAdapter, type WalletAdapterResolver, type WalletAssetsContent, 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 };
+export { AUTH_ERROR_CODES, type AdapterFn, AlbedoAdapter, type AuthErrorCode, type AuthOpenContext, type AuthState, type AuthUrlOpener, type BuildOutcome, type BuildProofArgs, type ConnectWalletResponse, type DistributionClaimBody, type DistributionClaimContent, type DistributionRule, type DistributionRulesState, type EnabledAssetRecord, type EnabledAssetsState, FreighterAdapter, type KeyManager, type KycFlow, type KycLevel, type KycProvider, type KycStartBody, type KycStartResponse, type KycStatus, type LocalStorageAdapterOptions, type LogLevel, type NetworkState, OnStorageDegrade, POLLAR_CORE_VERSION, type PasskeyCeremony, type PasskeySigner, type PaymentInstructions, type PollarAdapter, type PollarAdapters, type PollarApiClient, type PollarApplicationConfigContent, type PollarApplicationConfigResponse, PollarClient, type PollarClientConfig, PollarFlowError, type PollarLogger, 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 SessionsState, type SignAuthEntryOptions, type SignAuthEntryResponse, type SignOutcome, type SignTransactionOptions, type SignTransactionResponse, type StellarBalance, StellarClient, type StellarClientConfig, type StellarNetwork, Storage, type SubmitOutcome, type TransactionState, type TxBuildBody, type TxBuildContent, type TxBuildResponse, type TxBuildSignSubmitBody, type TxBuildSignSubmitContent, type TxBuildSignSubmitResponse, type TxErrorPhase, type TxHistoryContent, type TxHistoryParams, type TxHistoryRecord, type TxHistoryState, type TxSignAndSendBody, type TxSignBody, type TxSignContent, type TxSignResponse, type TxSignSendResponse, type TxSubmitSignedBody, type WalletAdapter, type WalletAdapterResolver, type WalletAssetsContent, type WalletBalanceContent, type WalletBalanceRecord, type WalletBalanceState, type WalletId, WalletType, WebCryptoKeyManager, buildProof, canonicalEcJwk, claimDistributionRule, computeJwkThumbprint, createLocalStorageAdapter, createLogger, createMemoryAdapter, createOffRamp, createOnRamp, defaultKeyManager, defaultStorage, getKycProviders, getKycStatus, getRampTransaction, getRampsQuote, isValidSession, listDistributionRules, normalizeHtu, pollKycStatus, pollRampTransaction, type paths as pollarPaths, resolveKyc, startKyc };

package/dist/index.d.ts

@@ -3,6 +3,34 @@ export { a as StorageDegradeReason } from './types-DqgJIJBl.js';
 import { V as VisibilityProvider } from './types-Dyky8g0p.js';
 import * as openapi_fetch from 'openapi-fetch';
 
+/**
+ * Log levels in increasing verbosity. Setting a level emits that level and
+ * every more-important one; `silent` disables all SDK logging.
+ *
+ *   silent < error < warn < info < debug
+ */
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/**
+ * Sink the SDK writes logs to. The global `console` already satisfies this
+ * shape, so it's the default. Inject your own (pino, Sentry breadcrumbs, a test
+ * spy…) via `PollarClientConfig.logger` to route SDK logs wherever you want.
+ */
+interface PollarLogger {
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+/**
+ * Build a level-gated logger over a sink. The returned object has the same
+ * method surface as {@link PollarLogger}; each call is silently dropped when its
+ * level is more verbose than the configured `level`. Messages keep their own
+ * `[PollarClient…]` prefixes, so this only adds filtering + sink routing.
+ *
+ * Defaults: `level = 'info'`, `sink = console`.
+ */
+declare function createLogger(level?: LogLevel, sink?: PollarLogger): PollarLogger;
+
 type StellarNetwork = 'mainnet' | 'testnet';
 type StellarClientConfig = StellarNetwork | {
     horizonUrl: string;
@@ -173,7 +201,7 @@ interface PollarPersistedSession {
         ready: boolean;
     };
     wallet: {
-        type: 'custodial' | 'smart' | 'external';
+        type: 'internal' | 'smart' | 'external';
         address: string | null;
         existsOnStellar?: boolean;
         createdAt?: number;
@@ -218,6 +246,19 @@ interface PollarClientConfig {
      * apiKey)`: WebCrypto in browsers, `@noble/curves` in RN.
      */
     keyManager?: KeyManager;
+    /**
+     * Minimum severity the SDK logs. `silent` disables all SDK logging; the rest
+     * emit that level and everything more important (`error` < `warn` < `info` <
+     * `debug`). State-transition chatter (auth/tx/network) is at `debug`.
+     * Defaults to `'info'`.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Sink the SDK writes logs to. Defaults to the global `console`. Inject your
+     * own (pino, Sentry breadcrumbs, a test spy…) to route SDK logs anywhere.
+     * Filtering by `logLevel` still applies on top of whatever you pass.
+     */
+    logger?: PollarLogger;
     /**
      * Notified when persistent storage silently degrades to in-memory mode
      * (Safari private browsing quota errors, sandboxed iframes, etc.). Useful
@@ -683,6 +724,7 @@ declare class PollarClient {
     readonly id: string;
     readonly basePath: string;
     private readonly _api;
+    private readonly _log;
     private readonly _storage;
     private readonly _keyManager;
     /** Resolves once `keyManager.init()` and the initial session restore complete. */
@@ -873,6 +915,12 @@ declare class PollarClient {
     revokeSession(familyId: string): Promise<void>;
     getNetwork(): StellarNetwork;
     getNetworkState(): NetworkState;
+    /**
+     * The client's level-gated logger (built from `logLevel` / `logger`). Exposed
+     * so the runtime layer (`@pollar/react`) can route its own logs through the
+     * same level and sink instead of calling `console` directly.
+     */
+    getLogger(): PollarLogger;
     setNetwork(network: StellarNetwork): void;
     onNetworkStateChange(cb: (state: NetworkState) => void): () => void;
     getTransactionState(): TransactionState | null;
@@ -1097,6 +1145,11 @@ interface LocalStorageAdapterOptions {
      * in-memory fallback (e.g. quota exceeded, throwing `localStorage`).
      */
     onDegrade?: OnStorageDegrade;
+    /**
+     * Logger for the one-shot degrade warning. Defaults to the global `console`;
+     * `PollarClient` passes its level-gated logger so `logLevel` applies here too.
+     */
+    logger?: PollarLogger;
 }
 /**
  * `localStorage`-backed adapter that wraps every operation in try/catch and
@@ -5751,7 +5804,7 @@ interface operations {
 type PollarApiClient = ReturnType<typeof createApiClient>;
 declare function createApiClient(baseUrl: string): openapi_fetch.Client<paths, `${string}/${string}`>;
 
-declare function isValidSession(value: unknown): value is PollarPersistedSession;
+declare function isValidSession(value: unknown, logger?: PollarLogger): value is PollarPersistedSession;
 
 /**
  * GET /kyc/status
@@ -5844,4 +5897,4 @@ declare function listDistributionRules(api: PollarApiClient): Promise<Distributi
  */
 declare function claimDistributionRule(api: PollarApiClient, body: DistributionClaimBody): Promise<DistributionClaimContent>;
 
-export { AUTH_ERROR_CODES, type AdapterFn, AlbedoAdapter, type AuthErrorCode, type AuthOpenContext, type AuthState, type AuthUrlOpener, type BuildOutcome, type BuildProofArgs, type ConnectWalletResponse, type DistributionClaimBody, type DistributionClaimContent, type DistributionRule, type DistributionRulesState, type EnabledAssetRecord, type EnabledAssetsState, FreighterAdapter, type KeyManager, type KycFlow, type KycLevel, type KycProvider, type KycStartBody, type KycStartResponse, type KycStatus, type LocalStorageAdapterOptions, type NetworkState, OnStorageDegrade, POLLAR_CORE_VERSION, type PasskeyCeremony, type PasskeySigner, 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 SessionsState, type SignAuthEntryOptions, type SignAuthEntryResponse, type SignOutcome, type SignTransactionOptions, type SignTransactionResponse, type StellarBalance, StellarClient, type StellarClientConfig, type StellarNetwork, Storage, type SubmitOutcome, type TransactionState, type TxBuildBody, type TxBuildContent, type TxBuildResponse, type TxBuildSignSubmitBody, type TxBuildSignSubmitContent, type TxBuildSignSubmitResponse, type TxErrorPhase, type TxHistoryContent, type TxHistoryParams, type TxHistoryRecord, type TxHistoryState, type TxSignAndSendBody, type TxSignBody, type TxSignContent, type TxSignResponse, type TxSignSendResponse, type TxSubmitSignedBody, type WalletAdapter, type WalletAdapterResolver, type WalletAssetsContent, 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 };
+export { AUTH_ERROR_CODES, type AdapterFn, AlbedoAdapter, type AuthErrorCode, type AuthOpenContext, type AuthState, type AuthUrlOpener, type BuildOutcome, type BuildProofArgs, type ConnectWalletResponse, type DistributionClaimBody, type DistributionClaimContent, type DistributionRule, type DistributionRulesState, type EnabledAssetRecord, type EnabledAssetsState, FreighterAdapter, type KeyManager, type KycFlow, type KycLevel, type KycProvider, type KycStartBody, type KycStartResponse, type KycStatus, type LocalStorageAdapterOptions, type LogLevel, type NetworkState, OnStorageDegrade, POLLAR_CORE_VERSION, type PasskeyCeremony, type PasskeySigner, type PaymentInstructions, type PollarAdapter, type PollarAdapters, type PollarApiClient, type PollarApplicationConfigContent, type PollarApplicationConfigResponse, PollarClient, type PollarClientConfig, PollarFlowError, type PollarLogger, 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 SessionsState, type SignAuthEntryOptions, type SignAuthEntryResponse, type SignOutcome, type SignTransactionOptions, type SignTransactionResponse, type StellarBalance, StellarClient, type StellarClientConfig, type StellarNetwork, Storage, type SubmitOutcome, type TransactionState, type TxBuildBody, type TxBuildContent, type TxBuildResponse, type TxBuildSignSubmitBody, type TxBuildSignSubmitContent, type TxBuildSignSubmitResponse, type TxErrorPhase, type TxHistoryContent, type TxHistoryParams, type TxHistoryRecord, type TxHistoryState, type TxSignAndSendBody, type TxSignBody, type TxSignContent, type TxSignResponse, type TxSignSendResponse, type TxSubmitSignedBody, type WalletAdapter, type WalletAdapterResolver, type WalletAssetsContent, type WalletBalanceContent, type WalletBalanceRecord, type WalletBalanceState, type WalletId, WalletType, WebCryptoKeyManager, buildProof, canonicalEcJwk, claimDistributionRule, computeJwkThumbprint, createLocalStorageAdapter, createLogger, createMemoryAdapter, createOffRamp, createOnRamp, defaultKeyManager, defaultStorage, getKycProviders, getKycStatus, getRampTransaction, getRampsQuote, isValidSession, listDistributionRules, normalizeHtu, pollKycStatus, pollRampTransaction, type paths as pollarPaths, resolveKyc, startKyc };