@coinlist-co/react 0.12.2-rc.bc20f5b → 0.12.2-rc.e1f6c82

package/dist/server/index.d.cts

@@ -1,382 +0,0 @@
-import { A as AuthorizationCode, C as CodeVerifier, aF as OAuthSession, D as OAuthAccessToken, aG as ClientCredentialsOAuth, aH as Sender, L as Logger, F as OffersNamespace, $ as Offer, aI as PaginationParams, aJ as PaginatedResponse, i as OfferId, I as OfferDetail, R as RequirementsNamespace, j as OfferOptionId, x as Requirement, y as RequirementsNamespaceImpl, U as UniversalNamespaceContext, t as WalletsNamespace, E as Erc20Namespace, h as CoinListTokenSaleNamespace, S as SuperstateSwapNamespace, m as OndoNamespace, c as CentrifugeNamespace, T as TokensNamespace, z as Config, aK as ClientSecret, Y as Seconds, a8 as PinoLoggerOptions } from '../time-CVZpAkGY.cjs';
-import 'viem';
-
-interface SessionStore {
-    getSession(): Promise<OAuthSession | null>;
-    /**
-     * Persists or clears the OAuth session.
-     *
-     * **Omit this method to create a read-only store.** When absent, the SDK
-     * skips token refresh entirely — no network call is made and no refresh
-     * token is consumed. This is the correct approach for contexts that can read
-     * the session but cannot write it back, such as Next.js Server Components.
-     *
-     * ⚠️ Do **not** implement this as a no-op (`async () => {}`). If the method
-     * is present, the SDK assumes writes succeed: it will fire a token refresh
-     * network call, consume the refresh token, then invoke `setSession` — which
-     * would silently discard the new session and leave the browser holding an
-     * invalidated refresh token. Simply **omit** `setSession` to prevent any
-     * refresh from being attempted.
-     *
-     * {@link ServerAuthNamespace.completeOAuth} and
-     * {@link ServerAuthNamespace.logout} always require a writable store and
-     * throw {@link WritableSessionStoreRequiredError} if `setSession` is absent.
-     */
-    setSession?(session: OAuthSession | null): Promise<void>;
-}
-/**
- * The empty session store: holds no session, reads nothing, never writes.
- *
- * For server contexts that act without a user — the client-credentials grant
- * (`auth.clientCredentials`) and the public token registry (`tokens`) read
- * nothing from the store, so hosts building those paths need no store of
- * their own.
- *
- * `setSession` is deliberately absent, not a no-op — see
- * {@link SessionStore.setSession} for why a no-op is a bug.
- */
-declare function emptySessionStore(): SessionStore;
-/** The PKCE pair `CoinListClient#auth.completeOAuth` hands to the backend. */
-interface CompleteOAuthParams {
-    /** The short-lived authorization code parsed out of the redirect URL. */
-    code: AuthorizationCode;
-    /** The `code_verifier` the browser generated when starting the flow. */
-    codeVerifier: CodeVerifier;
-}
-/**
- * OAuth session lifecycle on your backend: exchanging authorization codes,
- * keeping the access token fresh, minting app-level tokens, and logging out.
- *
- * This namespace is server-only: every method needs the `clientSecret` and the
- * {@link SessionStore}, neither of which may exist in a browser.
- */
-interface ServerAuthNamespace {
-    /**
-     * Exchanges an authorization code from `CoinListClient#auth.completeOAuth`
-     * for an OAuth session and persists it via {@link SessionStore.setSession}.
-     *
-     * The exchange is never retried automatically: an authorization code is
-     * single-use, so a retry of an attempt that reached the server would fail
-     * anyway, and could mask why the first one did.
-     *
-     * @throws {@link WritableSessionStoreRequiredError} if the session store
-     * does not provide `setSession`.
-     * @throws {@link HttpError} if CoinList refuses the exchange.
-     */
-    completeOAuth(params: CompleteOAuthParams): Promise<OAuthSession>;
-    /**
-     * Returns a valid access token for the current session, refreshing it if it
-     * is expired or near expiry. This is what you serve to
-     * {@link ClientConfig.getAccessToken}: answer `null` with "no session"
-     * (e.g. a 204) and a throw with a failure (e.g. a 503), never the other way
-     * round - the browser signs the user out on the first and not the second.
-     *
-     * **Writable store**: if the token is expired, the SDK exchanges the refresh
-     * token for a new session, persists it, and returns the fresh access token.
-     * Concurrent calls for the same session in this process share one exchange.
-     *
-     * A rejected refresh token (`400 invalid_grant`) is only a *suspicion* at
-     * first, because the backend answers "rotated a moment ago by a concurrent
-     * request" and "expired or revoked" identically: the SDK writes nothing,
-     * so it cannot overwrite the session the winning request just stored, and
-     * returns `null` - or the current access token, if that has not actually
-     * expired yet. Only a second rejection of the same refresh token, 5 to 60
-     * seconds later in this process, is the verdict: the session is cleared via
-     * {@link SessionStore.setSession} and {@link Config.onSessionExpired} is
-     * called. A browser confirming through your endpoint asks again after one
-     * second, so it signs out on its own verdict and not on this one.
-     *
-     * **Read-only store** (no `setSession`): refresh is skipped entirely. The
-     * stored token is returned as-is, even if it is expired — a non-null return
-     * value does **not** guarantee the token is accepted by the API. Before
-     * making API calls, check `token.expiresAt > new Date()`. Use a writable
-     * store (e.g. in a Route Handler) when you need the SDK to renew the session
-     * automatically.
-     *
-     * @returns the access token, or `null` if there is no session, or the
-     * session was rejected (suspected or confirmed).
-     * @throws the underlying error - an {@link HttpError} for a 5xx or
-     * `invalid_client`, the `fetch` error for a network failure - when the SDK
-     * could not find out whether a session exists and the current access token
-     * has already expired. The session is left untouched. **Never treat this as
-     * logged out**: it means "try again", and during an outage treating it as
-     * logged out would sign out every user at once.
-     */
-    getAccessToken(): Promise<OAuthAccessToken | null>;
-    /**
-     * Obtains an app-level access token via the OAuth 2.0 `client_credentials`
-     * grant (RFC 6749 §4.4). No user is involved: the token authenticates the
-     * partner application itself and only grants access to app-level resources
-     * such as offers and offer requirements.
-     *
-     * The token is **not** persisted to the {@link SessionStore} and has no
-     * refresh token. It expires at `expiresAt`; once expired, call this method
-     * again to obtain a fresh token — the SDK does not renew it automatically.
-     *
-     * Pass the result to `ServerOffersNamespace` or
-     * `ServerRequirementsNamespace.forOffer` to read without a user session.
-     */
-    clientCredentials(): Promise<ClientCredentialsOAuth>;
-    /**
-     * Revokes the current token via `POST /oauth/revoke` and clears the session.
-     * Does nothing when there is no session.
-     *
-     * The revoke is best-effort: if it fails for any reason - an
-     * {@link HttpError}, a network failure, anything else - the failure is
-     * logged at `'warn'` and the session is cleared regardless, because the
-     * cleared session is what logs the user out. Set `strict` on the server
-     * config to rethrow it instead.
-     *
-     * @throws {@link WritableSessionStoreRequiredError} if the session store does
-     * not provide `setSession`.
-     * @throws whatever the {@link SessionStore} throws, in either mode. A failed
-     * `setSession(null)` means the session was not cleared.
-     * @throws the revoke failure, only when `strict` is set. The session is then
-     * left untouched, so the call can be retried.
-     */
-    logout(): Promise<void>;
-}
-
-/**
- * What the server-only namespaces need, on top of what
- * {@link UniversalNamespaceContext} provides: authentication that a caller can
- * satisfy with an app-level token instead of a user session.
- */
-interface ServerNamespaceContext {
-    readonly api: Sender;
-    /** As {@link UniversalNamespaceContext.logger}: the raw port, scoped per namespace. */
-    readonly logger: Logger | null;
-    /**
-     * Requires a user session, unless `clientCreds` is supplied — an app-level
-     * token authenticates the request on its own. Throws
-     * {@link NotAuthenticatedError} when neither is present.
-     */
-    ensureAuthenticated(clientCreds?: ClientCredentialsOAuth): Promise<void>;
-}
-
-/**
- * The server-side offers namespace: the same reads as the shared
- * {@link OffersNamespace}, each additionally callable with an app-level token
- * from `ServerAuthNamespace.clientCredentials` instead of a user session.
- *
- * When a user session exists it takes precedence and `clientCreds` acts as a
- * fallback. Without either, the reads throw {@link NotAuthenticatedError}.
- */
-interface ServerOffersNamespace extends OffersNamespace {
-    /** @param clientCreds app-level token to read without a user session. */
-    list(clientCreds?: ClientCredentialsOAuth): Promise<Offer[]>;
-    /** @param clientCreds app-level token to read without a user session. */
-    listPage(params: PaginationParams, clientCreds?: ClientCredentialsOAuth): Promise<PaginatedResponse<Offer>>;
-    /** @param clientCreds app-level token to read without a user session. */
-    get(id: OfferId, clientCreds?: ClientCredentialsOAuth): Promise<OfferDetail>;
-}
-declare class ServerOffersNamespaceImpl implements ServerOffersNamespace {
-    private readonly ctx;
-    private readonly log;
-    constructor(ctx: ServerNamespaceContext);
-    list(clientCreds?: ClientCredentialsOAuth): Promise<Offer[]>;
-    listPage(params: PaginationParams, clientCreds?: ClientCredentialsOAuth): Promise<PaginatedResponse<Offer>>;
-    get(id: OfferId, clientCreds?: ClientCredentialsOAuth): Promise<OfferDetail>;
-}
-
-/**
- * The server-side requirements namespace: the same surface as the shared
- * {@link RequirementsNamespace}, except {@link forOffer} — the offer's
- * requirement definitions are app-level data, so it is additionally callable
- * with a token from `ServerAuthNamespace.clientCredentials`.
- *
- * Everything else is per-user data and needs a user session. `handle` is
- * client-only: there is no browser tab to open on a server.
- */
-interface ServerRequirementsNamespace extends RequirementsNamespace {
-    /** @param clientCreds app-level token to read without a user session. */
-    forOffer(offerId: OfferId, clientCreds?: ClientCredentialsOAuth): Promise<Record<OfferOptionId, Requirement[]>>;
-}
-declare class ServerRequirementsNamespaceImpl extends RequirementsNamespaceImpl implements ServerRequirementsNamespace {
-    private readonly serverCtx;
-    constructor(serverCtx: UniversalNamespaceContext & ServerNamespaceContext);
-    forOffer(offerId: OfferId, clientCreds?: ClientCredentialsOAuth): Promise<Record<OfferOptionId, Requirement[]>>;
-}
-
-interface ServerConfig extends Config {
-    readonly clientSecret: ClientSecret;
-    readonly sessionStore: SessionStore;
-    /**
-     * How many seconds before its expiry an access token is refreshed. Defaults
-     * to 60. Refreshing early moves the work to a single request while the
-     * current token still works, and a refresh that fails inside this window
-     * keeps serving the current token rather than failing the request.
-     *
-     * Build it with `Seconds.of(n)`, which throws a `ValidationError` unless
-     * `n` is a non-negative integer.
-     */
-    readonly accessTokenExpiryBufferSeconds?: Seconds;
-    /**
-     * Whether the SDK throws where it would otherwise recover and log a
-     * `'warn'` line. Defaults to `false`.
-     *
-     * Today it governs one thing: a failed token revoke in `auth.logout()`. By
-     * default the session is cleared regardless; with `strict` the failure is
-     * rethrown and the session is left untouched.
-     */
-    readonly strict?: boolean;
-}
-/**
- * Server-side CoinList SDK client.
- *
- * Functionality is grouped into namespaces — `coinlist.auth.getAccessToken()`,
- * `coinlist.offers.list()`, `coinlist.requirements.statuses(offerId)`.
- *
- * Operates in one of two modes depending on whether {@link SessionStore}
- * includes a `setSession` implementation:
- *
- * - **Writable store** (`setSession` provided) — full functionality: token
- *   refresh, `auth.completeOAuth`, and `auth.logout` all work normally.
- *
- * - **Read-only store** (no `setSession`) — token refresh is skipped entirely,
- *   meaning no network call is made and no refresh token is consumed.
- *   `auth.completeOAuth` and `auth.logout` throw
- *   {@link WritableSessionStoreRequiredError}. `auth.getAccessToken` may
- *   return an expired token (see its docs). Use this mode in execution
- *   contexts that can read the session but cannot write it back, such as
- *   Next.js Server Components.
- *
- * Unless a namespace says otherwise, its methods require a user session and
- * throw {@link NotAuthenticatedError} when there is none. When the SDK could
- * not find out whether there is one - CoinList's token endpoint failing, or
- * the network - they throw that underlying error instead: see
- * {@link ServerAuthNamespace.getAccessToken}.
- */
-interface CoinListServer {
-    /**
-     * OAuth session lifecycle: exchanging an authorization code, serving a valid
-     * access token to the browser, minting app-level tokens, and logging out —
-     * e.g. `coinlist.auth.getAccessToken()`.
-     */
-    readonly auth: ServerAuthNamespace;
-    /**
-     * The offer catalogue — e.g. `coinlist.offers.list()`. Every read also
-     * accepts an app-level token from {@link ServerAuthNamespace.clientCredentials}
-     * so it can run without a user session.
-     */
-    readonly offers: ServerOffersNamespace;
-    /**
-     * Offer requirements and the operations that satisfy them — e.g.
-     * `coinlist.requirements.statuses(offerId)`. `forOffer` also accepts an
-     * app-level token; the rest is per-user data and needs a user session.
-     */
-    readonly requirements: ServerRequirementsNamespace;
-    /**
-     * The user's external wallets: ownership proofs and offer-option bindings —
-     * e.g. `coinlist.wallets.list({ offerId, offerOptionId })`.
-     */
-    readonly wallets: WalletsNamespace;
-    /**
-     * Generic ERC-20 reads (token allowance and balance) — e.g.
-     * `coinlist.erc20.getBalance({ ... })`.
-     */
-    readonly erc20: Erc20Namespace;
-    /**
-     * Token-sale operations: listing, reading, and recording participations —
-     * e.g. `coinlist.tokenSale.list()`. The on-chain `execute`
-     * flow is client-only and is not exposed here.
-     */
-    readonly tokenSale: CoinListTokenSaleNamespace;
-    /**
-     * On-chain swap operations: quoting a swap, reading swap-contract state, and
-     * allow-listing a proven wallet — e.g.
-     * `coinlist.superstate.getOutputToken({ contractAddress, chain })`.
-     */
-    readonly superstate: SuperstateSwapNamespace;
-    /**
-     * Ondo swap reads: trading status and quoting. Both are free to poll.
-     *
-     * No CoinList fee is applied to a quote; see {@link OndoNamespace}.
-     *
-     * This is Ondo's whole surface for now — the wallet-driven half arrives with
-     * ENG-1680 and will be client-only, since it needs a wallet to sign with.
-     */
-    readonly ondo: OndoNamespace;
-    /**
-     * Centrifuge vault reads: the vault-wide ordering gate, and each wallet's
-     * position. The status read is free to poll.
-     */
-    readonly centrifuge: CentrifugeNamespace;
-    /**
-     * Token display metadata (name, symbol, decimals, logos) from CoinList's
-     * public token registry, keyed by chain + contract address — e.g.
-     * `coinlist.tokens.get({ chain, address })` for an entry of
-     * `Offer.tokens`, or `coinlist.tokens.list()` for the whole
-     * catalogue in one request.
-     *
-     * Public and unauthenticated: unlike the other namespaces, its methods never
-     * require a session, so it also works with a read-only store.
-     */
-    readonly tokens: TokensNamespace;
-}
-declare function createCoinListServer(config: ServerConfig): CoinListServer;
-
-/**
- * A {@link Logger} that writes newline-delimited JSON to stdout through pino.
- *
- * ```ts
- * createCoinListServer({
- *   ...config,
- *   logger: pinoServerLogger({ isDev: false, level: 'info' }),
- * });
- * ```
- *
- * The Node counterpart of {@link pinoClientLogger}, for a route handler, a BFF
- * or SSR. One line per record, which is what every log aggregator ingests
- * without configuration.
- *
- * ## What it deliberately does not do
- *
- * **No transport, and no `pino-pretty`.** A pino transport runs on a worker
- * thread through `thread-stream`, which every bundler has to be told about
- * (`serverExternalPackages` in Next) and which edge runtimes cannot run at
- * all. Pretty-printing is a pipe the host owns rather than a dependency the
- * SDK takes on their behalf:
- *
- * ```sh
- * node server.js | npx pino-pretty
- * ```
- *
- * **No environment-dependent formatting.** `isDev` decides which levels are
- * legal and nothing else, so a development record and a production record are
- * the same shape - what you debug is what you ship.
- *
- * If you already run pino, or want transports, redaction or `destination`,
- * implement {@link Logger} yourself: it is four methods over an event, and
- * `@opentelemetry/instrumentation-pino` patches the pino module rather than an
- * instance, so trace correlation reaches this logger either way.
- *
- * ## Production
- *
- * **Not advised in production**, the same as everywhere else this seam is
- * documented: the SDK's default answer is to leave {@link Config.logger}
- * undefined outside development, staging and incident reproduction. A backend
- * is the least bad place to disregard that - the records go to your process
- * and your sink rather than to a page the end user can read - but it is still
- * a disregard, and the retention and access questions become yours.
- *
- * If you run one, `isDev: false` restricts you to `'error'`, `'warn'` and
- * `'info'` - `{ isDev: false, level: 'debug' }` does not compile, see
- * {@link PinoLoggerOptions}. Those levels are redacted by construction, which
- * is a mechanism the SDK holds itself to; whether that clears your bar is a
- * judgement the SDK is not in a position to make for you.
- *
- * Holds no module-level state: every call builds its own pino instance, and
- * the level is fixed at construction, so two loggers never interfere. Fixed is
- * this implementation's choice, not the seam's - the SDK re-reads
- * {@link Logger.level} before every log call - so if you want a level you can
- * change at runtime, implement {@link Logger} over your own pino instance
- * rather than calling this.
- */
-declare function pinoServerLogger(options: PinoLoggerOptions): Logger;
-
-declare class WritableSessionStoreRequiredError extends Error {
-    constructor(message?: string);
-}
-
-export { type CoinListServer, type CompleteOAuthParams, type ServerAuthNamespace, type ServerConfig, type ServerNamespaceContext, type ServerOffersNamespace, ServerOffersNamespaceImpl, type ServerRequirementsNamespace, ServerRequirementsNamespaceImpl, type SessionStore, WritableSessionStoreRequiredError, createCoinListServer, emptySessionStore, pinoServerLogger };