@coinlist-co/react 0.12.1 → 0.12.2-rc.0ff2d03

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-import { A as AuthorizationCode, C as CodeVerifier, aq as OAuthSession, v as OAuthAccessToken, ar as ClientCredentialsOAuth, u as Config, as as ClientSecret, at as Sender, L as Logger, w as OffersNamespace, J as Offer, au as PaginationParams, av as PaginatedResponse, O as OfferId, z as OfferDetail, R as RequirementsNamespace, d as OfferOptionId, s as Requirement, t as RequirementsNamespaceImpl, U as UniversalNamespaceContext, o as WalletsNamespace, E as Erc20Namespace, c as CoinListTokenSaleNamespace, S as SuperstateSwapNamespace, g as OndoNamespace, T as TokensNamespace, _ as PinoLoggerOptions } from '../tokens-namespace-CIWBtgt2.js';
+import { A as AuthorizationCode, C as CodeVerifier, af as OAuthSession, x as OAuthAccessToken, ag as ClientCredentialsOAuth, y as OffersNamespace, D as Offer, ah as PaginationParams, ai as PaginatedResponse, f as OfferId, G as OfferDetail, R as RequirementsNamespace, g as OfferOptionId, s as Requirement, v as WalletsNamespace, z as Erc20Namespace, i as CoinListTokenSaleNamespace, r as SuperstateSwapNamespace, m as OndoNamespace, e as CentrifugeNamespace, T as TokensNamespace, w as Config, aj as ClientSecret, M as Seconds, Z as PinoLoggerOptions, _ as Logger } from '../time-BDzqB806.js';
 import 'viem';
 
 interface SessionStore {
@@ -55,18 +55,36 @@ interface ServerAuthNamespace {
      * 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`.
+     * 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}.
+     * {@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.
-     * Returns `null` if there is no session or the refresh fails.
+     * 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
@@ -75,8 +93,14 @@ interface ServerAuthNamespace {
      * 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
-     * could not be refreshed.
+     * @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>;
     /**
@@ -95,56 +119,23 @@ interface ServerAuthNamespace {
     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
+     * @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 {@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;
-    private readonly log;
-    constructor(api: Sender, config: ServerAuthConfig);
-    completeOAuth(params: CompleteOAuthParams): Promise<OAuthSession>;
-    getAccessToken(): Promise<OAuthAccessToken | null>;
-    private readAccessToken;
-    private refreshSession;
-    clientCredentials(): Promise<ClientCredentialsOAuth>;
-    logout(): Promise<void>;
-    private revokeAndClear;
-    /**
-     * Returns the store's `setSession`, or throws — the guard every
-     * session-writing operation shares.
-     */
-    private writableSessionStore;
-}
-
-/**
- * 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
@@ -162,14 +153,6 @@ interface ServerOffersNamespace extends OffersNamespace {
     /** @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
@@ -184,20 +167,27 @@ 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;
-    /** 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.
+     * 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;
 }
@@ -222,7 +212,10 @@ interface ServerConfig extends Config {
  *   Next.js Server Components.
  *
  * Unless a namespace says otherwise, its methods require a user session and
- * throw {@link NotAuthenticatedError} when there is none.
+ * 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 {
     /**
@@ -274,6 +267,11 @@ interface CoinListServer {
      * 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.
@@ -351,4 +349,4 @@ declare class WritableSessionStoreRequiredError extends Error {
     constructor(message?: string);
 }
 
-export { type CoinListServer, type CompleteOAuthParams, type ServerAuthConfig, type ServerAuthNamespace, ServerAuthNamespaceImpl, type ServerConfig, type ServerNamespaceContext, type ServerOffersNamespace, ServerOffersNamespaceImpl, type ServerRequirementsNamespace, ServerRequirementsNamespaceImpl, type SessionStore, WritableSessionStoreRequiredError, createCoinListServer, emptySessionStore, pinoServerLogger };
+export { type CoinListServer, type CompleteOAuthParams, type ServerAuthNamespace, type ServerConfig, type ServerOffersNamespace, type ServerRequirementsNamespace, type SessionStore, WritableSessionStoreRequiredError, createCoinListServer, emptySessionStore, pinoServerLogger };