@andco/sdk

El paquete base. No asume entorno: corre en cualquier runtime con fetch. Los constructores por entorno están en sus propias entradas: /browser, /server y /cli.

AndcoClient

Una instancia configurada y ligada a un entorno: configuración y capacidad, construida sin esperar a que una sesión se resuelva.

new AndcoClient(options: AndcoClientOptions)

rest e intents ya existen sin sesión: session responde sin token hasta que hay una, y la API responde 401. No hace falta with() solo para tener a quién llamar.

with(credentials: AndcoCredentials | AndcoSession | string): AndcoClientAuthed
authorized(): AndcoClientAuthed

with() acepta un token suelto, una sesión completa o cualquier implementación de AndcoCredentials, y devuelve un objeto nuevo con su propio rest/intents ligados a esa credencial — pensado para un servidor que liga credenciales distintas en cada petición, sin mutar la instancia compartida. authorized() no crea credenciales nuevas: expone la sesión propia de la instancia con isAuthed: true, compartiendo rest, intents, auth y session por referencia con la instancia original.

AndcoClientAuthed tiene la misma forma que AndcoClient, con isAuthed: true y accessTokenFor(resource).

AndcoRest

class AndcoRest {
  readonly http: AndcoHttpClient;
  readonly raw: AndCoRestClient;
}

Ambos son clientes de openapi-fetch generados desde el contrato OpenAPI, y ambos resuelven el token por petición: uno vencido se renueva sin que quien llama se entere.

http es el que usas. Nunca lanza — cada llamada resuelve { data, error, response } — y su fallo es un AndcoAPIError. Además expone .throwOnError() por llamada, para quien prefiera un throw.

const { data, error } = await andco.rest.http.GET("/accounts");
if (error) return report(error.code);

raw es el mismo cliente sin envolver: su error es el cuerpo que devuelve la API, tal cual. Úsalo solo si necesitas exactamente eso.

http sigue siendo asignable a un cliente de openapi-fetch, así que una biblioteca que pida uno lo acepta — es lo que permite pasárselo a openapi-react-query sin adaptadores. Nombra el mapa de rutas con AndCoRestPaths, de @andco/protocol/transport; TypeScript no lo deduce solo.

AndcoAuth

signIn(options?: AndcoSignInOptions): Promise<Result<AndcoSession | null>>
signOut(): Promise<Result<void>>
onChange(listener: (session: AndcoSession | null) => void): () => void
getSession(): Promise<Result<AndcoSession | null>>

signIn devuelve null sin error cuando la persona cierra la ventana o cuando el documento se reemplaza por una redirección. onChange devuelve la función de baja y dispara la carga inicial.

AndcoSignInOptions incluye scopes, presentation ("popup" o "redirect"), redirectTo, authorizations, loginHint y state.

AndcoSessionStore

El único objeto con estado del SDK. Construirlo no hace nada; la carga empieza en la primera lectura.

getSnapshot(): AndcoSession | null | undefined
getServerSnapshot(): AndcoSession | null | undefined
subscribe(listener: () => void): () => void
get ready: Promise<Result<void>>
accessTokenFor(resource: string): Promise<string | null>
set(session: AndcoSession | null): Promise<Result<void>>

getSnapshot es puro y nunca inicia la carga; subscribe, ready y accessTokenFor sí. Esa asimetría es lo que hace seguro construir una instancia dentro de un render que el framework puede descartar.

Los tres estados de getSnapshot son undefined (sin resolver), null (sin sesión) y la sesión.

AndcoOAuth

createAuthorizationRequest(options?): Promise<Result<AndcoAuthorizationRequest>>
exchangeCallback({ callbackUrl, request }): Promise<Result<AndcoSession>>
resolveAuthorizationUrl(parameters: URLSearchParams): Promise<Result<URL>>
refresh(refreshToken: string): Promise<Result<AndcoSession>>
userInfo(accessToken: string): Promise<Result<AndcoUser>>
createDeviceAuthorizationRequest(options?): Promise<Result<AndcoDeviceAuthorization>>
awaitDeviceAuthorization(device, options?): Promise<Result<AndcoSession>>
configuration(): Promise<oidc.Configuration>
get isConfidential: boolean

createAuthorizationRequest decide sola entre una petición directa y una PAR: usa PAR cuando la URL sería demasiado larga o cuando lleva parámetros que no deben quedar en el historial, como login_hint o authorization_details.

configuration() lee la descripción que el servidor publica de sí mismo y la memoriza. Existe porque openid-client/passport la recibe directamente.

AndcoIntents

Domain-neutral únicamente: crea y lee Intents bajo el Grant vigente, y observa los hechos que producen. Nada específico de un Resource Server en particular vive aquí.

create<T>(type: string, input, options?): Promise<Result<T>>
get<T>(intentId): Promise<Result<T>>
execute(intentId): Promise<Result<void>>
events(intentId, after?, signal?): Promise<Result<AndcoEventPage>>
subscribe<E>(subject, read, decode, handler, options): () => void

createDeposit, createWithdrawal, createAutomaticCharge, closeDeposit, getAccountEvents y los listeners tipados (onIntentDepositEvent, onIntentWithdrawalEvent, onDepositEvent, onWithdrawalEvent) son específicos del dominio bancario: viven en BankIntents, que compone create, events y subscribe de aquí exactamente como lo haría un Resource Server de terceros. Ver @andco/bank-sdk.

AndcoConfig

AndcoConfig.from(input: AndcoConfigInput): AndcoConfig

Normaliza y valida una vez. Lanza si algo está mal, porque un valor inválido es un defecto de arranque y no un error en tiempo de ejecución.

Errores

class AndcoError extends Error {
  readonly code: string;
  readonly status: number | undefined;
  readonly details: Readonly<Record<string, unknown>> | undefined;
}

class AndcoAPIError extends AndcoError {
  readonly error: string;
  readonly response: Response;
  static fromOpenAPIFetch(payload: unknown, response: Response): AndcoAPIError;
}

type Result<T> = { data: T; error: null } | { data: null; error: AndcoError };

function ok<T>(data: T): Result<T>;
function fail(code: string, options?): Result<never>;

AndcoError cubre todo lo que el SDK reporta. AndcoAPIError es el subconjunto que viene de un intercambio con la API: siempre trae el response — cuando la petición nunca llegó, es Response.error(), y entonces status queda en undefined.

Ramifica por code. error es el mismo identificador con el nombre que le da el contrato, y existe para que el cliente envuelto siga encajando donde se espera uno de openapi-fetch. Los campos que el contrato declara en un fallo (required_scope, required_action) quedan tanto en la raíz como en details.

Almacenamiento y bloqueo

interface AndcoStorage {
  getItem(key: string): string | null | Promise<string | null>;
  setItem(key: string, value: string): void | Promise<void>;
  removeItem(key: string): void | Promise<void>;
}

interface AndcoLock {
  acquire<T>(key: string, work: () => Promise<T>): Promise<T>;
}

Implementaciones incluidas: MemoryStorage, WebStorage e InProcessLock. El almacenamiento puede ser asíncrono a propósito: un llavero del sistema o un almacén cifrado también son almacenamiento.

Entrega tu propio AndcoLock cuando varios procesos compartan una sesión: los refresh tokens rotan y dos renovaciones simultáneas se invalidan entre sí.

Credenciales

interface AndcoCredentials {
  accessTokenFor(resource: string): Promise<string | null>;
}

Esa es toda la interfaz de autorización del SDK. Cualquier cosa que resuelva un token puede ligarse con with().