Skip to main content

Interface: AuthProvider

Defined in: src/core/auth.ts:105

Decorates a request with credentials. Values the caller already put on the request win over the provider's.

Failure contract: apply and refresh THROW on failure, and request() never retries them (re-submitting credentials is the provider's decision), so a provider that wants to ride out transient errors retries internally. An SdvError thrown here reaches the caller unchanged; anything else becomes AssetFetchError("<family>: auth failed (apply|refresh)").

Example​

import { configure, type AuthProvider } from 'sportsdataverse';

const myAuth: AuthProvider = {
  async apply(req, ctx) {
    return { ...req, headers: { 'X-Api-Key': process.env.MY_KEY ?? '', ...req.headers } };
  },
};
configure({ auth: { my_api: myAuth } });

Remarks​

The built-ins — bearerAuth, headerAuth, queryAuth, tokenAuth, sessionAuth — cover the usual shapes; install one per family with configure({ auth }) or registerFamilyDefaults. refresh is called at most once per request, after a 401, and the request is then re-sent once.

Methods​

apply()​

apply(req, ctx): Promise<TransportRequest>

Defined in: src/core/auth.ts:107

The request with credentials added (values the caller set win). Throws on failure.

Parameters​

req​

TransportRequest

ctx​

AuthContext

Returns​

Promise<TransportRequest>

refresh()?​

optional refresh(ctx): Promise<void>

Defined in: src/core/auth.ts:112

Force new credentials (called once after a 401; ctx.request is the request that failed). Throws on failure, as apply does.

Parameters​

ctx​

AuthContext

Returns​

Promise<void>