@coinlist-co/react 0.11.0 → 0.11.1-rc.22d81d4

package/dist/{config-B5mwS_2l.d.ts → config-C6vlghJY.d.ts}

@@ -1,4 +1,4 @@
-import { Hex } from 'viem';
+import { Hash, Hex } from 'viem';
 
 declare const __brand: unique symbol;
 type Newtype<Base, Branding> = Base & {
@@ -20,6 +20,523 @@ declare const ClientId: (value: string) => ClientId;
 type ClientSecret = Newtype<string, 'ClientSecret'>;
 declare const ClientSecret: (value: string) => ClientSecret;
 
+/**
+ * A classified wallet or transaction failure. The SDK derives this from
+ * whatever the {@link EvmWallet} throws, so hosts get a stable, typed error
+ * shape regardless of the wallet library underneath.
+ *
+ * Lives here rather than beside its classifier because it is the failure half
+ * of the {@link EvmWallet} contract, and because both `@/shared` and
+ * `@/client` name it: {@link LogCause} carries one, and classifying a thrown
+ * error into one needs viem's error classes, which are browser-side.
+ */
+type WalletError = {
+    type: 'user_rejected';
+} | {
+    type: 'insufficient_funds';
+} | {
+    type: 'contract_reverted';
+    /**
+     * What the contract said, when it said anything: a `require` string, a
+     * panic description, a custom error's name, or the four-byte selector of
+     * an error the ABI could not decode.
+     *
+     * `null` when a revert carried no data, since the string the RPC node
+     * offers in its place is not the contract's - see `classifyWalletError`.
+     * Nullable rather than optional so that every arm has to answer the
+     * question: "it reverted and said nothing" is a fact about the revert,
+     * and a caller should have to read it rather than miss it.
+     *
+     * Never the custom error's arguments. A name is a compile-time
+     * identifier; its operands are runtime values - an address, a balance -
+     * and those are `'debug'` material.
+     */
+    reason: string | null;
+} | {
+    type: 'timeout';
+    hash: Hash;
+} | {
+    type: 'unknown';
+    cause: unknown;
+};
+/**
+ * A {@link WalletError} as it may be reported above `'debug'`: the
+ * classification, never the throw.
+ *
+ * Only the `unknown` arm differs, and it differs because it is the one arm
+ * carrying a value the SDK did not author - the raw error the wallet library
+ * threw, whose message and metadata hold the transaction's `from`, `to`,
+ * `value` and calldata. The other four carry compile-time constants or a
+ * server-minted identifier already, so they pass through as they stand.
+ *
+ * This exists as a type rather than as a scrub some function remembers to
+ * apply: `LogCause` names it, so an arm that grew a raw field would fail the
+ * build instead of quietly reaching {@link Logger.error}.
+ */
+type RedactedWalletError = Exclude<WalletError, {
+    type: 'unknown';
+}> | {
+    type: 'unknown';
+};
+declare const RedactedWalletError: {
+    fromWalletError: (error: WalletError) => RedactedWalletError;
+};
+
+/**
+ * The observability seam a host implements to see inside the SDK.
+ *
+ * Pass an implementation as {@link Config.logger} and the SDK reports every
+ * request it makes, every failure it classifies, and every state a hook
+ * settles into. Leave it out and the SDK logs nothing at all - there is no
+ * fallback to `console`, at any level, on any codepath.
+ *
+ * Four methods over a {@link LogEvent} lambda, plus {@link level}. An event is
+ * a constant `msg`, the {@link LogScope} it came from, the accumulated
+ * {@link LogBindings}, and a bag of `fields` - so a host forwards structured
+ * records rather than parsing strings.
+ *
+ * ```ts
+ * const logger: Logger = {
+ *   level: () => 'info',
+ *   debug: () => {},
+ *   info: (event) => sink.info(toRecord(event())),
+ *   warn: (event) => sink.warn(toRecord(event())),
+ *   error: (event) => sink.error(toRecord(event())),
+ * };
+ * ```
+ *
+ * {@link pinoClientLogger} and {@link pinoServerLogger} are ready-made
+ * implementations over pino, and are what most hosts should reach for.
+ *
+ * ## Where to run it
+ *
+ * **Not in production, as the default answer.** Development, tests, staging,
+ * and reproducing a reported bug are where this seam earns its keep. Left
+ * undefined elsewhere it discloses nothing, and that holds no matter what a
+ * later revision of the SDK puts on a line.
+ *
+ * Where you do run one in production, `'info'` and above is the only sane
+ * choice, and the shipped implementations make the alternative unrepresentable
+ * rather than merely discouraged: `isDev: false` narrows the level to
+ * {@link ProductionLogLevel}, so `'debug'` does not compile. That narrowing is
+ * a guard for the partner who ignored this paragraph, not an endorsement of
+ * the practice.
+ *
+ * The distinction worth holding onto: `'info'` and above are **redacted by
+ * construction** - see the next section for exactly what that covers, and the
+ * type that enforces it. Redacted is a mechanism the SDK can hold itself to. A
+ * blanket "safe in production" is a promise about your environment that the
+ * SDK is in no position to make, and one that a single future field could
+ * quietly break.
+ *
+ * `'debug'` is for reproducing a bug: a developer's machine, tests, and beta
+ * or staging environments where the data flowing through the SDK is not real
+ * customer data.
+ *
+ * ## What each level may disclose
+ *
+ * **`'debug'` is unredacted. Every other level is not.**
+ *
+ * At `'debug'` the SDK reports request and response bodies, request headers,
+ * the full URL including its query string, and operation parameters
+ * **verbatim** - bearer tokens, KYC answers, tax-document fields, wallet
+ * signatures, the lot. There is no denylist and no redaction: see ADR-8 for
+ * why a partial guarantee was rejected in favour of an honest absence of one.
+ *
+ * At `'info'`, `'warn'` and `'error'` the SDK emits only its own
+ * classification of what happened and identifiers the server minted: a method
+ * and a bare path, a status, a duration, a {@link RequestId}, a frontline
+ * error code and event id, a {@link LogCause} arm. No request body, no
+ * response body, no query string, no host-supplied parameters, and no message
+ * text read off a thrown error the SDK did not author.
+ *
+ * The type carries that boundary rather than merely documenting it:
+ * {@link SafeEvent} constrains every field value to a {@link LogValue} scalar,
+ * so spreading a body, a DTO or an operation's params into an `info`, `warn`
+ * or `error` line does not compile. Only {@link DebugEvent} accepts arbitrary
+ * values.
+ *
+ * The one deliberate exception is an SDK-authored validation message, which
+ * quotes the single scalar that failed to map - `Unsupported chain:
+ * "solana_mainnet"`. It is a hand-written template naming one offending value,
+ * not a payload, and it is the whole reason this seam exists.
+ *
+ * ## Your responsibility
+ *
+ * The SDK hands you events. What happens next is yours: **you own the final
+ * filtering, redaction and retention** before anything is written to a file, a
+ * console, or a third-party sink such as Sentry or Datadog. In particular, if
+ * you implement {@link debug} and forward it anywhere durable, you have taken
+ * on storing live credentials and personal data, deliberately. Implement
+ * `debug` as a no-op - or return a level below it from {@link level} - in any
+ * environment where that is not acceptable.
+ *
+ * **Every event is a lambda, and that is load bearing.** The SDK consults
+ * {@link level} first and never invokes the lambda when the level forbids it,
+ * so an expensive debug event - a serialized DTO, a loop over balances - costs
+ * nothing in production where the level is `'error'` or `'none'`. Build the
+ * event inside the lambda, never outside it.
+ *
+ * ## Every method must be total
+ *
+ * **None of the five methods may throw, and that includes {@link level}.** The
+ * SDK calls them inline, on the codepath of the work it is reporting, and it
+ * does not catch them: a `logger.error` that throws while reporting a failed
+ * request turns that request's rejection into your logger's exception, and a
+ * `level()` that throws breaks the call it was asked about even when nothing
+ * else went wrong.
+ *
+ * That is deliberate. Swallowing would hide a logger that is broken in every
+ * environment, and the SDK cannot tell a transport blip in your sink from a
+ * bug in your implementation. So the contract is on this side of the seam:
+ * catch inside your implementation, and never let an exception out. The
+ * shipped pino implementations do exactly that.
+ *
+ * ```ts
+ * error: (event) => {
+ *   try {
+ *     const e = event();
+ *     Sentry.captureMessage(e.msg, { extra: e });
+ *   } catch {
+ *     // never rethrow: the SDK is on the other side of this call
+ *   }
+ * },
+ * ```
+ */
+interface Logger {
+    /**
+     * The most detailed level this logger wants. Consulted before **every** log
+     * call, so keep it cheap and pure: return a captured constant or read a
+     * plain field. Do not read an environment variable, hit storage, or call
+     * out to a feature-flag service here.
+     *
+     * Returning `'none'` silences the SDK as completely as omitting the logger.
+     *
+     * **Must not throw.** It is consulted inside every SDK operation, so an
+     * exception here fails the operation itself.
+     */
+    level(): LogLevel;
+    /**
+     * Fine-grained detail: request and response bodies, full URLs, headers,
+     * operation parameters, hook transitions.
+     *
+     * **Unredacted.** This is the only level that may carry credentials or
+     * personal data, and it always may. Its event is a {@link DebugEvent}, whose
+     * fields accept arbitrary values for exactly that reason. Do not forward it
+     * to a durable or third-party sink outside development and beta.
+     *
+     * **Must not throw**, here and on every method below.
+     */
+    debug(event: () => DebugEvent): void;
+    /** Notable, expected events: a request completing, a flow advancing. */
+    info(event: () => SafeEvent): void;
+    /**
+     * Recoverable trouble: a retried request, a renewed session, a poll tick
+     * that failed while the last value still stands.
+     *
+     * Carries a {@link LogCause} when one was classified, the same as
+     * {@link error} does. What separates the two levels is whether anything
+     * actually broke, not how much is known about it.
+     */
+    warn(event: () => SafeEvent): void;
+    /**
+     * A failure. {@link SafeEvent.cause} carries what the SDK knows about it,
+     * classified into {@link LogCause}, and is absent when the failure is not an
+     * error the SDK caught - a flow reporting the step it stopped at, for
+     * instance.
+     *
+     * Every part of the event is SDK-authored classification or server-authored
+     * identifiers, so forwarding it as it stands is safe. `scope` says which
+     * part of the SDK the line came from, which is what to route or filter on.
+     */
+    error(event: () => SafeEvent): void;
+}
+/**
+ * A value the SDK is willing to put in a structured field above `'debug'`.
+ *
+ * Scalars only, and that is the redaction boundary made structural rather than
+ * documentary. Every leak ADR-8 found was an *object* spread onto a line that
+ * a host forwards to a tracker - an operation's params, a thrown wallet error,
+ * a response body. None of them is assignable to this, so each is now a
+ * compile error rather than a review catch.
+ *
+ * It does not stop a call site writing `{ token: accessToken }`, and it is not
+ * meant to: a string is a string. What it stops is the mistake that actually
+ * happened.
+ */
+type LogValue = string | number | boolean | null;
+/**
+ * Fields safe at every level: SDK-authored classification and server-minted
+ * identifiers, constrained to {@link LogValue}.
+ */
+type SafeFields = Readonly<Record<string, LogValue>>;
+/**
+ * Fields for `'debug'` only: bodies, headers, full URLs, operation params,
+ * raw thrown values. Arbitrary values, because that is the point of the level.
+ *
+ * The SDK's own implementations render these into a form that cannot fail to
+ * serialize - a `bigint`, a cycle or a getter that throws must never turn a
+ * log line into a second failure - but they are otherwise passed through.
+ */
+type UnredactedFields = Readonly<Record<string, unknown>>;
+/**
+ * One narrowing applied to a logger by {@link InternalLogger.child}.
+ *
+ * A union of single-key objects rather than a positional `string`, because the
+ * three things the SDK narrows by are not the same kind of thing: a request id
+ * correlates retries of one wire call, a flow name names an on-chain
+ * procedure, a hook name names a React binding. Rendered into one `[SCOPE:x]`
+ * prefix they were indistinguishable; as fields they must not be.
+ *
+ * `requestId` keeps its {@link RequestId} newtype rather than widening to
+ * `string` at the seam.
+ */
+type LogBinding = {
+    readonly requestId: RequestId;
+} | {
+    readonly flow: string;
+} | {
+    readonly hook: string;
+} | {
+    readonly op: string;
+};
+/**
+ * Every {@link LogBinding} applied so far, merged. This is what reaches a
+ * host, so a line from `prepareOndoSwap` carries `flow: 'prepareSwap'` as its
+ * own key and is filterable without parsing anything.
+ */
+type LogBindings = {
+    readonly [K in LogBinding as keyof K]?: K[keyof K];
+};
+type BaseEvent = {
+    /**
+     * What happened, as a **constant string literal**.
+     *
+     * Never interpolated. A log aggregator groups by message, so a `msg` that
+     * embeds a status, a count or a reason produces one group per distinct
+     * value and is not groupable at all. Every varying value belongs in
+     * `fields`, which is what a host filters and facets on.
+     *
+     * This is a convention, not a checked rule: deslop reasons about import
+     * edges and cannot see a template literal, and the type-level approximations
+     * catch only some interpolations. ADR-8 records why a partial guarantee was
+     * refused here as elsewhere.
+     */
+    readonly msg: string;
+    /**
+     * Which part of the SDK reported this. Stamped by
+     * {@link internalLogger}, never by a call site.
+     */
+    readonly scope: LogScope;
+    /** Every {@link LogBinding} applied by {@link InternalLogger.child}. */
+    readonly bindings: LogBindings;
+};
+/**
+ * An event for `'info'`, `'warn'` and `'error'` - the levels a host may run in
+ * production.
+ *
+ * Its fields are {@link SafeFields}, so nothing but a scalar can reach it.
+ */
+type SafeEvent = BaseEvent & {
+    readonly fields: SafeFields;
+    /**
+     * What the SDK knows about an accompanying failure, classified. Absent when
+     * there is nothing to classify.
+     */
+    readonly cause?: LogCause;
+};
+/**
+ * An event for `'debug'`, the unredacted level. Its fields accept anything.
+ */
+type DebugEvent = BaseEvent & {
+    readonly fields: UnredactedFields;
+};
+/**
+ * How much the SDK may report, from silent to everything.
+ *
+ * Ordered: each level admits itself and everything before it, so `'info'`
+ * shows errors, warnings and info but not debug. `'none'` admits nothing.
+ *
+ * `'debug'` is the unredacted level, and it is deliberately the bottom of the
+ * ladder: the guarantee "`debug` is unredacted and every other level is not"
+ * only closes if there is nothing below it. That is why the SDK keeps its own
+ * five levels rather than adopting pino's seven, which put `trace` underneath.
+ */
+type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+/**
+ * The redacted levels: the only ones to consider running in production.
+ *
+ * Every level except `'debug'`, which is unredacted by design. Used by the
+ * shipped pino implementations to make a production `'debug'` logger
+ * unrepresentable rather than merely discouraged - see
+ * {@link PinoLoggerOptions}.
+ *
+ * The name marks which levels are *redacted*, not a verdict that running them
+ * in production is safe. The SDK's advice is to leave {@link Config.logger}
+ * undefined there; this type is what stops the partner who does not take it
+ * from reaching the unredacted level as well.
+ */
+type ProductionLogLevel = Exclude<LogLevel, 'debug'>;
+/**
+ * How to build one of the SDK's pino-backed loggers.
+ *
+ * A union rather than `{ level, isDev }`, and that is the whole point:
+ * `{ isDev: false, level: 'debug' }` does not typecheck, so a production
+ * build cannot ship a logger that prints bearer tokens to a browser console.
+ *
+ * `isDev` does exactly one thing - decide whether `'debug'` is a legal level.
+ * It changes no formatting: dev output and production output are the same
+ * shape, so what you debug is what you ship. Pretty-printing is a pipe the
+ * host owns (`node server.js | npx pino-pretty`), not a dependency the SDK
+ * takes.
+ */
+type PinoLoggerOptions = {
+    readonly isDev: true;
+    readonly level: LogLevel;
+} | {
+    readonly isDev: false;
+    readonly level: ProductionLogLevel;
+};
+/**
+ * Which part of the SDK a line came from, carried as the `scope` field on
+ * every event.
+ *
+ * It names the seam that **reported** the line, not the layer that raised what
+ * it reports: an error from `OFFERS` surfaced by `useOffers` is reported on a
+ * `HOOKS` line, because that is the hook telling you what it did with it. The
+ * `OFFERS` line for the same error is emitted separately, by the namespace.
+ *
+ * A closed union rather than a free string so that `ONDO` and `Ondo` cannot
+ * both appear, so that adding a namespace without giving it a scope fails to
+ * compile, and so that a host can `switch` on it when routing. Anything finer
+ * - an operation, a flow, a hook - is a {@link LogBinding} and appears as its
+ * own field.
+ */
+type LogScope = 'HTTP' | 'AUTH' | 'OFFERS' | 'REQUIREMENTS' | 'WALLETS' | 'ERC20' | 'TOKEN_SALE' | 'SUPERSTATE' | 'ONDO' | 'TOKENS' | 'SUPPORT' | 'HOOKS';
+/**
+ * Correlates every line one logical request produces. The first attempt, each
+ * retry, and the re-send after a session renewal all carry the same id, so a
+ * failure can be read back to the request that caused it.
+ */
+type RequestId = Newtype<string, 'RequestId'>;
+/**
+ * The id frontline keys its own logs by, minted server-side and returned as
+ * `event_id` on an error envelope. Quote it when raising a ticket with
+ * CoinList support: it is what leads from a partner's log line to the request
+ * as the backend saw it.
+ *
+ * A {@link Newtype} rather than a bare `string` because it sits next to
+ * {@link RequestId} and frontline's `code` on the same cause, and the three
+ * are not interchangeable: an id swapped for a code reads plausibly and points
+ * a support engineer at nothing.
+ */
+type FrontlineEventId = Newtype<string, 'FrontlineEventId'>;
+/**
+ * What the SDK knows about a failure, classified.
+ *
+ * **Safe to forward as it stands.** Every arm is SDK-authored classification
+ * or a server-authored identifier: no request or response body, no host-
+ * supplied parameter, and no value read off a thrown error the SDK did not
+ * author. There is nothing here to strip before handing it to an error
+ * tracker, which is deliberate - a `LogCause` reaches {@link Logger.error},
+ * the level a host actually runs in production, and a guarantee that depends
+ * on the host remembering to strip a field is not a guarantee.
+ *
+ * It is the SDK's **only** structured classification of a thrown error, and it
+ * reaches {@link Logger.warn} as well as {@link Logger.error}: a recoverable
+ * failure is no less worth naming than a fatal one, and rendering it into a
+ * string instead would have meant interpolating into `msg`.
+ *
+ * Bodies are a `'debug'`-only disclosure and stay on the `HTTP` lines, which
+ * {@link RequestId} points at.
+ *
+ * The arms are the remedies, not the exception classes: a `validation` cause
+ * means the backend sent something the SDK does not understand and is worth
+ * reporting to CoinList, while an `invariant` cause means the SDK itself
+ * computed something impossible and is worth reporting as an SDK bug. Reading
+ * `type` should tell you who has to fix it.
+ *
+ * It carries no scope of its own. The {@link SafeEvent} it arrives on has one,
+ * and a cause could only ever have repeated it: the scope is stamped by the
+ * logger that *emits* the line, not by the layer that raised the error, so a
+ * `validation` failure from `OFFERS` surfaced by `useOffers` would have been
+ * tagged `HOOKS` on the hook's line. Forward the event, not the cause alone.
+ */
+type LogCause = 
+/**
+ * A request reached the backend and came back non-2xx.
+ *
+ * Deliberately carries no response body. `requestId` is how you get the
+ * rest: the `HTTP` lines for the same request carry the method, the path,
+ * the duration, every retry, and at `'debug'` the body itself. `code` and
+ * `eventId` are frontline's own - quote `eventId` when raising a ticket with
+ * CoinList support.
+ */
+{
+    type: 'http';
+    requestId: RequestId | null;
+    status: number;
+    code: string | null;
+    eventId: FrontlineEventId | null;
+}
+/**
+ * The wire succeeded; the payload was not a shape the SDK can map.
+ *
+ * `message` is an SDK-authored template and may quote the single scalar that
+ * failed - `Unsupported chain: "solana_mainnet"`, `expires_at: not a date
+ * ("13/40/2026")`. That one value is the point of the arm; it is never a
+ * body and never a whole field set.
+ */
+ | {
+    type: 'validation';
+    message: string;
+}
+/**
+ * The SDK computed something impossible. An SDK bug - please report it.
+ * `message` is an SDK-authored template, like `validation`'s.
+ */
+ | {
+    type: 'invariant';
+    message: string;
+}
+/** An API-backed call was made without a logged-in user. */
+ | {
+    type: 'not-authenticated';
+}
+/** A code path the SDK has not shipped yet. */
+ | {
+    type: 'not-implemented';
+}
+/**
+ * The user's wallet, or the chain, refused.
+ *
+ * {@link RedactedWalletError} rather than the full `WalletError`: its
+ * `unknown` arm arrives with its `cause` dropped, that field holding the raw
+ * wallet-library error whose message and metadata carry the transaction's
+ * `from`, `to`, `value` and calldata. It is still on the flow's own returned
+ * result, and on the `'debug'` line the flow seam emits beside this one.
+ *
+ * A type rather than a scrub applied at the call site, so an arm that grew a
+ * raw field would fail the build.
+ */
+ | {
+    type: 'wallet';
+    error: RedactedWalletError;
+}
+/**
+ * Something the SDK does not recognise - usually a host-supplied lambda
+ * (`getAccessToken`, an {@link EvmWallet} method) throwing, or a
+ * network-level `fetch` failure.
+ *
+ * `name` is the error's class name and nothing else. The message and the
+ * thrown value itself are host-authored, so they are a `'debug'` disclosure:
+ * the paired debug line renders them in full.
+ */
+ | {
+    type: 'generic-error';
+    name: string;
+};
+
 /**
  * The exhaustive chain set: a new {@link EthereumChain} is a compile error
  * here until it is listed, which is what keeps the constructor total.
@@ -147,11 +664,25 @@ declare const MAX_UINT_256: bigint;
  */
 type Uint256 = bigint;
 /**
- * Asserts a raw bigint falls within uint256 bounds, throwing otherwise. Use at
- * on-chain arithmetic boundaries (bps math, price computation) where a computed
- * value could underflow below zero or overflow above 2^256-1.
+ * Asserts a computed bigint falls within uint256 bounds. Use at on-chain
+ * arithmetic boundaries (bps math, price computation) where the SDK's own
+ * arithmetic could underflow below zero or overflow above 2^256-1.
+ *
+ * Throws {@link InvariantError}, because reaching it means the SDK computed
+ * something no chain could represent. **For a value that came off the wire,
+ * use {@link parseUint256} instead**: the backend sending an unrepresentable
+ * number is a {@link ValidationError}, and the two have different remedies.
  */
 declare const assertUint256: (value: bigint) => Uint256;
+/**
+ * {@link assertUint256} at a wire boundary: the same bounds check, reported as
+ * a {@link ValidationError} against the named field, because a value out of
+ * range here is the backend's, not the SDK's.
+ *
+ * `label` names the field the way a DTO mapper's other failures do, so a log
+ * line says which one - `SwapPreview.pay_input_amount`, not `a number`.
+ */
+declare const parseUint256: (value: bigint, label: string) => Uint256;
 type BlockchainAmount = Newtype<{
     raw: Uint256;
     decimals: AssetDecimals;
@@ -225,6 +756,13 @@ declare const OAuthSession: {
 };
 
 type HttpRequestAttributes = {
+    /**
+     * Correlates the log lines of one logical request. Minted by
+     * {@link HttpClient} on the first attempt and carried onto every retry and
+     * post-renewal re-send by {@link concat}, which is what lets a reader tell
+     * three attempts of one request from three separate requests.
+     */
+    requestId?: RequestId;
     protected?: boolean;
     userAgent?: boolean;
     idempotencyKey?: boolean;
@@ -272,10 +810,25 @@ type HttpResponse<TBody = unknown> = {
     status: number;
     headers?: Record<string, string>;
     body: TBody | null;
+    /**
+     * The id of the request that produced this response, stamped by
+     * {@link HttpClient} so that whoever turns a non-2xx into an
+     * {@link HttpError} can carry it without threading the request alongside.
+     * Absent when the response did not come from an `HttpClient`.
+     */
+    requestId?: RequestId;
 };
 declare class HttpError<TBody = unknown> extends Error {
     readonly response: HttpResponse<TBody>;
     constructor(response: HttpResponse<TBody>);
+    /**
+     * Correlates this failure with the `[HTTP]` log lines for the same request,
+     * which carry the method, the URL, the duration and every retry. `null` when
+     * the response did not come from an {@link HttpClient}.
+     *
+     * Worth quoting in a bug report: it is what makes a log excerpt readable.
+     */
+    get requestId(): RequestId | null;
 }
 /**
  * The machine-readable `code` frontline attaches to an error, or `null` for
@@ -304,6 +857,15 @@ interface Sender {
 
 interface SharedNamespaceContext {
     readonly api: Sender;
+    /**
+     * The host's logger, or `null` when they supplied none.
+     *
+     * Deliberately the raw port rather than a pre-scoped {@link InternalLogger}:
+     * one context serves every namespace, and each namespace owns its own scope.
+     * A namespace turns it into something usable in its constructor, with
+     * `internalLogger(ctx.logger, 'OFFERS')`.
+     */
+    readonly logger: Logger | null;
     ensureUserAuthenticated(): Promise<void>;
 }
 
@@ -430,11 +992,89 @@ interface Erc20Namespace {
 }
 declare class Erc20NamespaceImpl implements Erc20Namespace {
     private readonly ctx;
+    private readonly log;
     constructor(ctx: SharedNamespaceContext);
     getAllowance(params: GetTokenAllowanceParams): Promise<TokenAllowance>;
     getBalance(params: GetTokenBalanceParams): Promise<TokenBalance>;
 }
 
+/**
+ * The logging surface SDK code uses. Never exported to hosts: they implement
+ * {@link Logger}, which is deliberately smaller.
+ */
+type InternalLogger = {
+    /**
+     * A logger narrowed by one more {@link LogBinding}, which every line it
+     * emits carries as its own field.
+     */
+    child(binding: LogBinding): InternalLogger;
+    /**
+     * The unredacted level. Request and response bodies, full URLs, headers,
+     * operation params and raw thrown errors belong here and **only** here.
+     */
+    debug(event: () => InternalDebugEvent): void;
+    info(event: () => InternalSafeEvent): void;
+    warn(event: () => InternalSafeEvent): void;
+    /**
+     * Reports a failure whose cause is already known, or has none. Prefer
+     * {@link failure}, which classifies a thrown error for you.
+     */
+    error(event: () => InternalSafeEvent): void;
+    /**
+     * Reports a thrown error, classifying it into a {@link LogCause}. Prefer
+     * this over `error` at a `catch`: classification only happens when the level
+     * admits it.
+     *
+     * The `error` line names the error's class but never its message, since an
+     * error the SDK did not author may say anything at all. The verbatim
+     * rendering goes onto a paired `debug` line instead.
+     *
+     * For a failure the SDK recovers from, use {@link warning} instead. An
+     * `error` line a host cannot act on is worse than no line at all: it trains
+     * them to ignore the ones that matter.
+     */
+    failure(event: () => InternalSafeEvent, error: unknown): void;
+    /**
+     * {@link failure} for trouble that did not break anything: a poll tick that
+     * failed while the last value still stands, a retried request.
+     *
+     * Carries the classified {@link LogCause} exactly as `failure` does. The two
+     * differ in level and in nothing else, because what separates them is
+     * whether anything actually broke - not how much is known about it.
+     */
+    warning(event: () => InternalSafeEvent, error: unknown): void;
+    /**
+     * Runs one namespace operation with logging around it: the call and its
+     * params at `debug`, and any throw at `error` with the cause classified.
+     * Every line carries `op` as a binding.
+     *
+     * **The params never reach the `error` line.** They routinely hold the
+     * things this SDK must not put in front of a production error tracker - an
+     * app bearer token, a document's signing fields, a wallet signature - and
+     * the `debug` line plus the request id is how you get them back. The type
+     * says so: `params` is `unknown`, which is not a {@link SafeFields} value.
+     *
+     * Always rethrows. Logging observes behaviour, it never changes it.
+     */
+    wrap<T>(op: string, params: unknown, run: () => Promise<T>): Promise<T>;
+};
+/**
+ * What a call site hands to `info`, `warn`, `error`, `failure` or `warning` -
+ * a {@link SafeEvent} minus the scope and bindings the logger stamps itself.
+ */
+type InternalSafeEvent = {
+    /** A **constant** string literal. Every varying value belongs in `fields`. */
+    readonly msg: string;
+    readonly fields?: SafeFields;
+    readonly cause?: LogCause;
+};
+/** What a call site hands to `debug`. Its fields accept anything. */
+type InternalDebugEvent = {
+    /** A **constant** string literal. Every varying value belongs in `fields`. */
+    readonly msg: string;
+    readonly fields?: UnredactedFields;
+};
+
 /**
  * The product an offer is checked out through. The backend sends one compound
  * `{supplier}::{saleType}` string, verbatim as spelled below: a double colon
@@ -456,6 +1096,12 @@ type OfferDto = {
     logo_url: string;
     starts_at: string;
     ends_at: string | null;
+    tokens: OfferTokenDto[];
+};
+type OfferTokenDto = {
+    role: 'funding' | 'distribution' | 'swap';
+    chain: string;
+    address: string;
 };
 
 type OfferId = Newtype<string, 'OfferId'>;
@@ -472,10 +1118,20 @@ type Offer = {
     logoUrl: string;
     startsAt: Date;
     endsAt: Date | null;
+    tokens: OfferToken[];
 };
 declare const Offer: {
     fromDto: (dto: OfferDto) => Offer;
 };
+type TokenRole = 'funding' | 'distribution' | 'swap';
+type OfferToken = {
+    role: TokenRole;
+    chain: Chain;
+    address: EvmContractAddress;
+};
+declare const OfferToken: {
+    fromDto: (dto: OfferTokenDto) => OfferToken;
+};
 
 /**
  * The cursor-paginated envelope every list endpoint returns.
@@ -563,7 +1219,7 @@ type OfferDetailDto = {
     asset: AssetDto;
     faqs: OfferDetailFaqDto[];
     funding_assets: AssetDto[];
-    tokens: OfferDetailTokenDto[];
+    tokens: OfferTokenDto[];
     id: string;
     links: OfferDetailLinkDto[];
     milestones: OfferDetailMilestoneDto[];
@@ -608,11 +1264,6 @@ type OfferDetailTermDto = {
     key: string | null;
     value: string | null;
 };
-type OfferDetailTokenDto = {
-    role: 'funding' | 'distribution' | 'swap';
-    chain: string;
-    address: string;
-};
 
 type OfferOptionId = Newtype<string, 'OfferOptionId'>;
 declare const OfferOptionId: (value: string) => OfferOptionId;
@@ -684,15 +1335,6 @@ type Milestone = {
 declare const Milestone: {
     fromDto: (dto: OfferDetailMilestoneDto) => Milestone;
 };
-type TokenRole = 'funding' | 'distribution' | 'swap';
-type OfferToken = {
-    role: TokenRole;
-    chain: Chain;
-    address: EvmContractAddress;
-};
-declare const OfferToken: {
-    fromDto: (dto: OfferDetailTokenDto) => OfferToken;
-};
 
 /** Unique identifier for a participation. */
 type ParticipationId = Newtype<string, 'ParticipationId'>;
@@ -812,6 +1454,7 @@ interface CoinListTokenSaleNamespace {
 }
 declare class CoinListTokenSaleNamespaceImpl implements CoinListTokenSaleNamespace {
     private readonly ctx;
+    protected readonly log: InternalLogger;
     constructor(ctx: SharedNamespaceContext);
     list(offerId?: OfferId): Promise<Participation[]>;
     listPage(params: ParticipationsPaginationParams): Promise<PaginatedResponse<Participation>>;
@@ -1216,6 +1859,7 @@ interface OndoNamespace {
 }
 declare class OndoNamespaceImpl implements OndoNamespace {
     private readonly ctx;
+    protected readonly log: InternalLogger;
     constructor(ctx: SharedNamespaceContext);
     getTradingStatus(params: GetOndoTradingStatusParams): Promise<OndoTradingStatus>;
     getQuote(params: GetOndoQuoteParams): Promise<OndoQuote>;
@@ -1272,6 +1916,7 @@ interface SuperstateSwapNamespace {
 }
 declare class SuperstateSwapNamespaceImpl implements SuperstateSwapNamespace {
     private readonly ctx;
+    protected readonly log: InternalLogger;
     constructor(ctx: SharedNamespaceContext);
     getAuthorization(params: GetSwapAuthorizationParams): Promise<SwapAuthorization>;
     getPreview(params: GetSwapPreviewParams): Promise<SwapPreview>;
@@ -1465,6 +2110,7 @@ interface WalletsNamespace {
 }
 declare class WalletsNamespaceImpl implements WalletsNamespace {
     private readonly ctx;
+    private readonly log;
     constructor(ctx: SharedNamespaceContext);
     createOwnershipChallenge(params: CreateWalletOwnershipChallengeParams): Promise<WalletOwnershipChallenge>;
     connectExternal(params: ConnectExternalWalletParams): Promise<OfferOptionAddress>;
@@ -1577,7 +2223,7 @@ declare const Pii: {
     fromDto: (dto: PiiDto) => Pii;
 };
 
-type RequirementTypeDto = 'kyc_approved' | 'identity_verified' | 'proof_of_address' | 'source_of_funds' | 'external_wallet' | 'whitelisted_wallet' | 'jurisdiction' | 'accreditation' | 'document';
+type RequirementTypeDto = 'kyc_approved' | 'external_wallet' | 'whitelisted_wallet' | 'jurisdiction' | 'accreditation' | 'document';
 type RequirementDto = {
     object: 'requirement';
     id: string;
@@ -1701,6 +2347,7 @@ interface RequirementsNamespace {
 }
 declare class RequirementsNamespaceImpl implements RequirementsNamespace {
     protected readonly ctx: SharedNamespaceContext;
+    protected readonly log: InternalLogger;
     constructor(ctx: SharedNamespaceContext);
     forOffer(offerId: OfferId): Promise<Record<OfferOptionId, Requirement[]>>;
     statuses(offerId: OfferId): Promise<RequirementStatusInfo[]>;
@@ -1738,6 +2385,7 @@ interface OffersNamespace {
 }
 declare class OffersNamespaceImpl implements OffersNamespace {
     private readonly ctx;
+    private readonly log;
     constructor(ctx: SharedNamespaceContext);
     list(): Promise<Offer[]>;
     listPage(params: PaginationParams): Promise<PaginatedResponse<Offer>>;
@@ -1891,12 +2539,13 @@ interface TokensNamespace {
 }
 declare class TokensNamespaceImpl implements TokensNamespace {
     private readonly api;
+    private readonly log;
     /**
      * Takes the registry origin rather than a `SharedNamespaceContext`: the
      * registry is unauthenticated and on its own host, so the frontline sender
      * and the auth check would both be dead weight here.
      */
-    constructor(baseUrl: string);
+    constructor(baseUrl: string, logger?: Logger | null);
     get(token: TokenIdentifier): Promise<TokenMetadata | null>;
     list(chain: EthereumChain): Promise<TokenMetadata[]>;
 }
@@ -1921,6 +2570,48 @@ interface Config {
      * registry.
      */
     readonly tokensBaseUrl?: string;
+    /**
+     * Where the SDK reports what it is doing. **Omit it and the SDK logs nothing
+     * at all** - no `console` fallback, at any level, on any codepath. Supply
+     * one and every request, every classified failure and every hook state
+     * transition is reported at the level your logger asks for.
+     *
+     * Absent, the SDK says nothing at all - there is no fallback to `console`,
+     * at any level, on any codepath.
+     *
+     * **Running the SDK's logging in production is not advised.** The safest
+     * posture is to leave this undefined outside development, staging and
+     * incident reproduction: a seam that emits nothing cannot disclose anything,
+     * and that property does not depend on the SDK continuing to get redaction
+     * right.
+     *
+     * If you do run one there, run it at `'info'` or above and know what that
+     * does and does not buy you. Those levels are **redacted by construction**:
+     * they carry only SDK-authored classification and server-authored
+     * identifiers, and the type system holds that line rather than a convention -
+     * an event at those levels accepts scalar fields only, so a body, a DTO or
+     * an operation's parameters cannot be put on one. What the SDK does **not**
+     * give you is a warranty that the result is safe for your environment. The
+     * mechanism is checkable and stated; the conclusion depends on your sink,
+     * your retention and your threat model, and it is yours to draw.
+     *
+     * **`'debug'` is not.** It reports request and response bodies, full URLs,
+     * headers and operation parameters verbatim - bearer tokens, KYC answers,
+     * tax-document fields, wallet signatures - and **the SDK does not redact**.
+     * Run it on a developer's machine, in tests, and in beta or staging
+     * environments where the data flowing through is not real customer data.
+     * The shipped implementations make that structural: built with
+     * `isDev: false`, `'debug'` does not typecheck. Either way, filtering,
+     * redaction and retention at your sink are yours, not the SDK's.
+     *
+     * Every method you implement here **must be total**: the SDK calls them on
+     * the codepath of the work they report and does not catch them, so a logger
+     * that throws fails the operation it was describing.
+     *
+     * See {@link Logger} for the full contract, and {@link pinoClientLogger} or
+     * {@link pinoServerLogger} for a ready-made implementation over pino.
+     */
+    readonly logger?: Logger;
 }
 
-export { type HttpResponse as $, AuthorizationCode as A, BlockchainAmount as B, CodeVerifier as C, type RequirementType as D, EvmWalletAddress as E, type RequirementStatusValue as F, OfferOptionAddress as G, RequirementId as H, type WalletChallengeType as I, DocumentSubmission as J, type KycLevelName as K, OndoTradingStatus as L, AssetDecimals as M, OndoQuote as N, OfferId as O, Participation as P, type OrderBookSide as Q, type RequirementsNamespace as R, type SharedNamespaceContext as S, type Tx as T, type OndoQuoteSize as U, type BuildOndoSwapTransactionParams as V, type WalletsNamespace as W, OfferOptionAddressId as X, TokenMetadata as Y, type TokenIdentifier as Z, HttpError as _, EthereumChain as a, type RemoveOptionAddressParams as a$, KycToken as a0, OAuthSession as a1, ClientCredentialsOAuth as a2, ClientSecret as a3, type Sender as a4, PaginationParams as a5, PaginatedResponse as a6, type Uint256 as a7, KnownAssetSymbol as a8, DecimalString as a9, type GetTokenBalanceParams as aA, HexEncodedTransactionData as aB, Iso2CountryCode as aC, Link as aD, type ListOptionAddressesParams as aE, MAX_ASSET_DECIMALS as aF, MAX_UINT_256 as aG, Milestone as aH, OAuthRefreshToken as aI, OfferOption as aJ, OfferOptionSlug as aK, OfferSlug as aL, OfferToken as aM, OffersNamespaceImpl as aN, type OndoQuoteDuration as aO, PKCEState as aP, type PaginatedResponseDto as aQ, ParticipationId as aR, type ParticipationStatus as aS, ParticipationsPaginationParams as aT, Pii as aU, PiiAddress as aV, PiiJurisdiction as aW, type PiiKind as aX, type QueryParamValue as aY, type QueryParamValues as aZ, RedirectUri as a_, SwapStatus as aa, type Newtype as ab, type AllowWalletParams as ac, AllowWalletResponse as ad, Asset as ae, AssetCode as af, Blockchain as ag, Chain as ah, ClientId as ai, CodeChallenge as aj, ConnectExternalWalletParams as ak, type CreateKycTokenParams as al, CreateParticipationParams as am, CreateWalletOwnershipChallengeParams as an, Cursor as ao, type DocumentFormType as ap, type DocumentSubmissionStatus as aq, type DocumentType as ar, ETHEREUM_CHAINS as as, Erc20NamespaceImpl as at, FaqItem as au, type GetOndoQuoteParams as av, type GetOndoTradingStatusParams as aw, type GetSwapAuthorizationParams as ax, type GetSwapPreviewParams as ay, type GetTokenAllowanceParams as az, type Erc20Namespace as b, type RequirementActionNeededReason as b0, SOLANA_CHAINS as b1, STABLE_DECIMALS as b2, SolanaChain as b3, type SubmitDocumentParams as b4, SwapAuthorization as b5, type SwapContractRef as b6, SwapPreview as b7, TermItem as b8, Ticker as b9, TokenAllowance as ba, TokenBalance as bb, TokenLogo as bc, type TokenLogoImage as bd, TokenLogoUrl as be, type TokenRole as bf, TokensNamespaceImpl as bg, WalletAddress as bh, WalletOwnershipChallenge as bi, type WalletProtocol as bj, WalletsNamespaceImpl as bk, apiErrorCode as bl, assertUint256 as bm, EvmContractAddress as c, type CoinListTokenSaleNamespace as d, OfferOptionId as e, AssetId as f, CoinListTokenSaleNamespaceImpl as g, type OndoNamespace as h, AssetSymbol as i, OndoSwapTransaction as j, OndoNamespaceImpl as k, type SuperstateSwapNamespace as l, Bps as m, SuperstateSwapNamespaceImpl as n, Requirement as o, RequirementsNamespaceImpl as p, type Config as q, type OAuthAccessToken as r, type OffersNamespace as s, type TokensNamespace as t, type Erc20Asset as u, OfferDetail as v, StablecoinSymbol as w, type OfferType as x, Offer as y, RequirementStatusInfo as z };
+export { type TokenIdentifier as $, AuthorizationCode as A, BlockchainAmount as B, CodeVerifier as C, type RequirementType as D, type Erc20Namespace as E, type RequirementStatusValue as F, OfferOptionAddress as G, RequirementId as H, DocumentSubmission as I, type WalletChallengeType as J, type KycLevelName as K, type Logger as L, type PinoLoggerOptions as M, OndoTradingStatus as N, OfferId as O, Participation as P, AssetDecimals as Q, type RequirementsNamespace as R, type SharedNamespaceContext as S, type TokensNamespace as T, OndoQuote as U, type OrderBookSide as V, type WalletError as W, type OndoQuoteSize as X, type BuildOndoSwapTransactionParams as Y, OfferOptionAddressId as Z, TokenMetadata as _, EthereumChain as a, OfferSlug as a$, type DebugEvent as a0, type FrontlineEventId as a1, HttpError as a2, type HttpResponse as a3, KycToken as a4, type LogBinding as a5, type LogBindings as a6, type LogCause as a7, type LogLevel as a8, type LogScope as a9, ConnectExternalWalletParams as aA, type CreateKycTokenParams as aB, CreateParticipationParams as aC, CreateWalletOwnershipChallengeParams as aD, Cursor as aE, type DocumentFormType as aF, type DocumentSubmissionStatus as aG, type DocumentType as aH, ETHEREUM_CHAINS as aI, Erc20NamespaceImpl as aJ, FaqItem as aK, type GetOndoQuoteParams as aL, type GetOndoTradingStatusParams as aM, type GetSwapAuthorizationParams as aN, type GetSwapPreviewParams as aO, type GetTokenAllowanceParams as aP, type GetTokenBalanceParams as aQ, HexEncodedTransactionData as aR, Iso2CountryCode as aS, Link as aT, type ListOptionAddressesParams as aU, MAX_ASSET_DECIMALS as aV, MAX_UINT_256 as aW, Milestone as aX, OAuthRefreshToken as aY, OfferOption as aZ, OfferOptionSlug as a_, type LogValue as aa, type ProductionLogLevel as ab, RedactedWalletError as ac, type RequestId as ad, type SafeEvent as ae, type SafeFields as af, type UnredactedFields as ag, OAuthSession as ah, ClientCredentialsOAuth as ai, ClientSecret as aj, type Sender as ak, PaginationParams as al, PaginatedResponse as am, type Uint256 as an, KnownAssetSymbol as ao, DecimalString as ap, SwapStatus as aq, type Newtype as ar, type AllowWalletParams as as, AllowWalletResponse as at, Asset as au, AssetCode as av, Blockchain as aw, Chain as ax, ClientId as ay, CodeChallenge as az, EvmContractAddress as b, OfferToken as b0, OffersNamespaceImpl as b1, type OndoQuoteDuration as b2, PKCEState as b3, type PaginatedResponseDto as b4, ParticipationId as b5, type ParticipationStatus as b6, ParticipationsPaginationParams as b7, Pii as b8, PiiAddress as b9, type WalletProtocol as bA, WalletsNamespaceImpl as bB, apiErrorCode as bC, assertUint256 as bD, parseUint256 as bE, PiiJurisdiction as ba, type PiiKind as bb, type QueryParamValue as bc, type QueryParamValues as bd, RedirectUri as be, type RemoveOptionAddressParams as bf, type RequirementActionNeededReason as bg, SOLANA_CHAINS as bh, STABLE_DECIMALS as bi, SolanaChain as bj, type SubmitDocumentParams as bk, SwapAuthorization as bl, type SwapContractRef as bm, SwapPreview as bn, TermItem as bo, Ticker as bp, TokenAllowance as bq, TokenBalance as br, TokenLogo as bs, type TokenLogoImage as bt, TokenLogoUrl as bu, type TokenRole as bv, TokensNamespaceImpl as bw, type Tx as bx, WalletAddress as by, WalletOwnershipChallenge as bz, type CoinListTokenSaleNamespace as c, OfferOptionId as d, AssetId as e, CoinListTokenSaleNamespaceImpl as f, type OndoNamespace as g, AssetSymbol as h, OndoSwapTransaction as i, OndoNamespaceImpl as j, type SuperstateSwapNamespace as k, type WalletsNamespace as l, Bps as m, EvmWalletAddress as n, SuperstateSwapNamespaceImpl as o, Requirement as p, RequirementsNamespaceImpl as q, type Config as r, type OAuthAccessToken as s, type OffersNamespace as t, type Erc20Asset as u, OfferDetail as v, StablecoinSymbol as w, type OfferType as x, Offer as y, RequirementStatusInfo as z };