@coinlist-co/react 0.10.1 → 0.11.0

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-import { h as AuthorizationCode, i as CodeVerifier, I as OAuthSession, J as ClientCredentialsOAuth, k as OAuthAccessToken, l as Offer, m as PaginationParams, n as PaginatedResponse, O as OfferId, o as OfferDetail, p as CreateWalletOwnershipChallengeParams, W as WalletOwnershipChallenge, q as ConnectExternalWalletParams, r as OfferOptionAddress, g as OfferOptionId, s as OfferOptionAddressId, R as Requirement, t as RequirementStatusInfo, u as Pii, D as DocumentType, v as DocumentSubmission, c as CoinListErc20Namespace, f as CoinListTokenSaleNamespace, C as CoinListSwapNamespace, K as KycLevelName, w as KycToken, j as Config, L as ClientSecret } from '../requirement-oVZA1INj.js';
+import { A as AuthorizationCode, C as CodeVerifier, a1 as OAuthSession, r as OAuthAccessToken, a2 as ClientCredentialsOAuth, q as Config, a3 as ClientSecret, a4 as Sender, s as OffersNamespace, y as Offer, a5 as PaginationParams, a6 as PaginatedResponse, O as OfferId, v as OfferDetail, R as RequirementsNamespace, e as OfferOptionId, o as Requirement, p as RequirementsNamespaceImpl, S as SharedNamespaceContext, W as WalletsNamespace, b as Erc20Namespace, d as CoinListTokenSaleNamespace, l as SuperstateSwapNamespace, h as OndoNamespace, t as TokensNamespace } from '../config-B5mwS_2l.js';
 import 'viem';
 
 interface SessionStore {
@@ -18,67 +18,39 @@ interface SessionStore {
      * invalidated refresh token. Simply **omit** `setSession` to prevent any
      * refresh from being attempted.
      *
-     * {@link CoinListServer.completeOAuth} and {@link CoinListServer.logout}
-     * always require a writable store and throw
-     * {@link WritableSessionStoreRequiredError} if `setSession` is absent.
+     * {@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>;
 }
-interface ServerConfig extends Config {
-    readonly clientSecret: ClientSecret;
-    readonly sessionStore: SessionStore;
-    /** Buffer in seconds before expiry to consider token expired for refresh. */
-    readonly accessTokenExpiryBufferSeconds?: number;
-    /**
-     * Whether SDK will throw an exception in cases it can be silent.
-     * For example, if token revokation on logout fails.
-     */
-    readonly strict?: boolean;
+/** 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;
 }
 /**
- * Server-side CoinList SDK client.
+ * OAuth session lifecycle on your backend: exchanging authorization codes,
+ * keeping the access token fresh, minting app-level tokens, and logging out.
  *
- * Operates in one of two modes depending on whether {@link SessionStore}
- * includes a `setSession` implementation:
- *
- * - **Writable store** (`setSession` provided) — full functionality: token
- *   refresh, {@link completeOAuth}, and {@link 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.
- *   {@link completeOAuth} and {@link logout} throw
- *   {@link WritableSessionStoreRequiredError}. {@link accessToken} 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.
+ * This namespace is server-only: every method needs the `clientSecret` and the
+ * {@link SessionStore}, neither of which may exist in a browser.
  */
-interface CoinListServer {
+interface ServerAuthNamespace {
     /**
-     * Exchanges an authorization code for an OAuth session and persists it via
-     * {@link SessionStore.setSession}.
+     * Exchanges an authorization code from `CoinListClient#auth.completeOAuth`
+     * for an OAuth session and persists it via {@link SessionStore.setSession}.
      *
      * Throws {@link WritableSessionStoreRequiredError} if the session store does
      * not provide `setSession`.
      */
-    completeOAuth(code: AuthorizationCode, codeVerifier: CodeVerifier): Promise<OAuthSession>;
+    completeOAuth(params: CompleteOAuthParams): Promise<OAuthSession>;
     /**
-     * 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 {@link fetchOffers}, {@link fetchOffersPage},
-     * {@link fetchOfferDetails}, or {@link fetchOfferRequirements} to call them
-     * without a user session.
-     */
-    clientCredentialsOAuth(): Promise<ClientCredentialsOAuth>;
-    /**
-     * Returns a valid access token for the current session, refreshing it if
-     * it is expired or near expiry.
+     * 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}.
      *
      * **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.
@@ -94,152 +66,207 @@ interface CoinListServer {
      * @returns the access token, or `null` if there is no session or the session
      * could not be refreshed.
      */
-    accessToken(): Promise<OAuthAccessToken | null>;
-    /**
-     * Revokes the current token via POST /oauth/revoke and clears the session.
-     *
-     * Throws {@link WritableSessionStoreRequiredError} if the session store does
-     * not provide `setSession`.
-     */
-    logout(): Promise<void>;
-    /**
-     * Fetches all offers by iterating through every paginated response.
-     *
-     * @param clientCreds optional app-level token from
-     * {@link clientCredentialsOAuth}. When provided, no user session is
-     * required; if a user session exists it takes precedence and `clientCreds`
-     * is used as a fallback.
-     *
-     * Throws {@link NotAuthenticatedError} if there is neither a user session
-     * nor `clientCreds`.
-     */
-    fetchOffers(clientCreds?: ClientCredentialsOAuth): Promise<Offer[]>;
-    /**
-     * Fetches a single page of offers.
-     *
-     * @param clientCreds optional app-level token from
-     * {@link clientCredentialsOAuth}. When provided, no user session is
-     * required; if a user session exists it takes precedence and `clientCreds`
-     * is used as a fallback.
-     *
-     * Throws {@link NotAuthenticatedError} if there is neither a user session
-     * nor `clientCreds`.
-     */
-    fetchOffersPage(params: PaginationParams, clientCreds?: ClientCredentialsOAuth): Promise<PaginatedResponse<Offer>>;
+    getAccessToken(): Promise<OAuthAccessToken | null>;
     /**
-     * Fetches details for a given offer by its id.
+     * 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.
      *
-     * @param clientCreds optional app-level token from
-     * {@link clientCredentialsOAuth}. When provided, no user session is
-     * required; if a user session exists it takes precedence and `clientCreds`
-     * is used as a fallback.
+     * 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.
      *
-     * Throws {@link NotAuthenticatedError} if there is neither a user session
-     * nor `clientCreds`.
+     * Pass the result to `ServerOffersNamespace` or
+     * `ServerRequirementsNamespace.forOffer` to read without a user session.
      */
-    fetchOfferDetails(id: OfferId, clientCreds?: ClientCredentialsOAuth): Promise<OfferDetail>;
+    clientCredentials(): Promise<ClientCredentialsOAuth>;
     /**
-     * Creates a single-use wallet-ownership challenge for the given wallet and
-     * chain. The user signs the returned {@link WalletOwnershipChallenge.message}
-     * with their wallet, then passes the signature to
-     * {@link connectExternalWallet}.
+     * Revokes the current token via `POST /oauth/revoke` and clears the session.
      *
-     * Throws {@link NotAuthenticatedError} if the user is not authenticated.
+     * Throws {@link WritableSessionStoreRequiredError} if the session store does
+     * not provide `setSession`.
      */
-    createWalletOwnershipChallenge(params: CreateWalletOwnershipChallengeParams): Promise<WalletOwnershipChallenge>;
+    logout(): Promise<void>;
+}
+/** What {@link ServerAuthNamespaceImpl} needs out of `ServerConfig`. */
+type ServerAuthConfig = Config & {
+    readonly clientSecret: ClientSecret;
+    readonly sessionStore: SessionStore;
+    /** Seconds before expiry at which a token counts as expired for refresh. */
+    readonly accessTokenExpiryBufferSeconds: number;
+    /** Whether to rethrow errors the SDK could otherwise swallow (e.g. revoke). */
+    readonly strict: boolean;
+};
+declare class ServerAuthNamespaceImpl implements ServerAuthNamespace {
+    private readonly api;
+    private readonly config;
+    constructor(api: Sender, config: ServerAuthConfig);
+    completeOAuth({ code, codeVerifier, }: CompleteOAuthParams): Promise<OAuthSession>;
+    getAccessToken(): Promise<OAuthAccessToken | null>;
+    private refreshSession;
+    clientCredentials(): Promise<ClientCredentialsOAuth>;
+    logout(): Promise<void>;
     /**
-     * Connects a proven external wallet to an offer option, using a signature of
-     * a challenge from {@link createWalletOwnershipChallenge}.
-     *
-     * Throws {@link NotAuthenticatedError} if the user is not authenticated.
+     * Returns the store's `setSession`, or throws — the guard every
+     * session-writing operation shares.
      */
-    connectExternalWallet(offerId: OfferId, params: ConnectExternalWalletParams): Promise<OfferOptionAddress>;
+    private writableSessionStore;
+}
+
+/**
+ * What the server-only namespaces need, on top of what
+ * {@link SharedNamespaceContext} provides: authentication that a caller can
+ * satisfy with an app-level token instead of a user session.
+ */
+interface ServerNamespaceContext {
+    readonly api: Sender;
     /**
-     * Lists the user's proven wallet bindings for a single offer option.
-     *
-     * Throws {@link NotAuthenticatedError} if the user is not authenticated.
+     * 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.
      */
-    listOptionAddresses(offerId: OfferId, offerOptionId: OfferOptionId): Promise<OfferOptionAddress[]>;
+    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;
+    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: SharedNamespaceContext & ServerNamespaceContext);
+    forOffer(offerId: OfferId, clientCreds?: ClientCredentialsOAuth): Promise<Record<OfferOptionId, Requirement[]>>;
+}
+
+interface ServerConfig extends Config {
+    readonly clientSecret: ClientSecret;
+    readonly sessionStore: SessionStore;
+    /** Buffer in seconds before expiry to consider token expired for refresh. */
+    readonly accessTokenExpiryBufferSeconds?: number;
     /**
-     * Removes one of the user's wallet bindings and returns the removed binding.
-     *
-     * Throws {@link NotAuthenticatedError} if the user is not authenticated.
+     * Whether SDK will throw an exception in cases it can be silent.
+     * For example, if token revokation on logout fails.
      */
-    removeOptionAddress(offerId: OfferId, addressId: OfferOptionAddressId): Promise<OfferOptionAddress>;
+    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.
+ */
+interface CoinListServer {
     /**
-     * Fetches the requirements for all options of a given offer, grouped by option ID.
-     *
-     * @param clientCreds optional app-level token from
-     * {@link clientCredentialsOAuth}. When provided, no user session is
-     * required; if a user session exists it takes precedence and `clientCreds`
-     * is used as a fallback.
-     *
-     * Throws {@link NotAuthenticatedError} if there is neither a user session
-     * nor `clientCreds`.
+     * 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()`.
      */
-    fetchOfferRequirements(offerId: OfferId, clientCreds?: ClientCredentialsOAuth): Promise<Record<OfferOptionId, Requirement[]>>;
+    readonly auth: ServerAuthNamespace;
     /**
-     * Fetches the user's requirement statuses for a given offer.
-     *
-     * Throws {@link NotAuthenticatedError} if the user is not authenticated.
+     * 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.
      */
-    fetchRequirementStatuses(offerId: OfferId): Promise<RequirementStatusInfo[]>;
+    readonly offers: ServerOffersNamespace;
     /**
-     * Fetches the user's PII (tax form pre-fill data) — full legal name, date
-     * of birth, jurisdiction, tax ID, and permanent address for an individual;
-     * or the equivalent entity fields for a company/trust, used to pre-fill a
-     * W-8BEN. Fields the entity hasn't provided are `null`.
-     *
-     * Throws {@link NotAuthenticatedError} if the user is not authenticated.
+     * 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.
      */
-    fetchPii(): Promise<Pii>;
+    readonly requirements: ServerRequirementsNamespace;
     /**
-     * Starts (or resumes) a document signing submission for the given type
-     * (currently only `tax_certification`, e.g. W-8BEN/W-8BEN-E). `fields` are
-     * signing-form values keyed by the document's DocuSeal field names,
-     * forwarded verbatim to Passport to pre-fill the document.
-     *
-     * Throws {@link NotAuthenticatedError} if the user is not authenticated.
+     * The user's external wallets: ownership proofs and offer-option bindings —
+     * e.g. `coinlist.wallets.list({ offerId, offerOptionId })`.
      */
-    submitDocument(documentType: DocumentType, fields: Record<string, string>): Promise<DocumentSubmission>;
+    readonly wallets: WalletsNamespace;
     /**
      * Generic ERC-20 reads (token allowance and balance) — e.g.
-     * `coinlist.erc20.getTokenBalance({ ... })`.
-     *
-     * These methods require a user session and throw
-     * {@link NotAuthenticatedError} if the user is not authenticated.
+     * `coinlist.erc20.getBalance({ ... })`.
      */
-    readonly erc20: CoinListErc20Namespace;
+    readonly erc20: Erc20Namespace;
     /**
      * Token-sale operations: listing, reading, and recording participations —
-     * e.g. `coinlist.tokenSale.fetchParticipations()`. The on-chain
-     * `executeTokenSale` flow is client-only and is not exposed here.
-     *
-     * These methods require a user session and throw
-     * {@link NotAuthenticatedError} if the user is not authenticated.
+     * 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
-     * proving/allow-listing wallet ownership — e.g.
-     * `coinlist.swap.getOutputToken({ contractAddress, chain })`.
+     * 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.
      *
-     * These methods require a user session and throw
-     * {@link NotAuthenticatedError} if the user is not authenticated.
-     */
-    readonly swap: CoinListSwapNamespace;
-    /**
-     * Creates a short-lived Sumsub WebSDK access token for the current user so
-     * an identity verification (KYC) flow can be started, e.g. to seed the
-     * client-side `IdentityVerification` component when server-rendering.
-     * `levelName` selects the Sumsub verification level; defaults to the
-     * backend's standard level. `reset` resets the Sumsub applicant first, so
-     * an already-approved level can be executed again (e.g. to update stale
-     * PII).
+     * 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;
+    /**
+     * 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
+     * `OfferDetail.tokens`, or `coinlist.tokens.list(chain)` for a whole
+     * catalogue in one request.
      *
-     * Throws {@link NotAuthenticatedError} if the user is not authenticated.
+     * Public and unauthenticated: unlike the other namespaces, its methods never
+     * require a session, so it also works with a read-only store.
      */
-    createKycToken(levelName?: KycLevelName, reset?: boolean): Promise<KycToken>;
+    readonly tokens: TokensNamespace;
 }
 declare function createCoinListServer(config: ServerConfig): CoinListServer;
 
@@ -247,4 +274,4 @@ declare class WritableSessionStoreRequiredError extends Error {
     constructor(message?: string);
 }
 
-export { type CoinListServer, type ServerConfig, type SessionStore, WritableSessionStoreRequiredError, createCoinListServer };
+export { type CoinListServer, type CompleteOAuthParams, type ServerAuthConfig, type ServerAuthNamespace, ServerAuthNamespaceImpl, type ServerConfig, type ServerNamespaceContext, type ServerOffersNamespace, ServerOffersNamespaceImpl, type ServerRequirementsNamespace, ServerRequirementsNamespaceImpl, type SessionStore, WritableSessionStoreRequiredError, createCoinListServer };