Conceptos

Andco tiene su propio vocabulario y el SDK lo usa tal cual en los nombres de sus métodos. Son cinco términos.

Andco Instance

Un cliente configurado, ligado a un entorno. Se crea con el constructor de ese entorno y su entorno decide qué credenciales, qué almacenamiento y qué presentaciones tiene disponibles. Una instancia de navegador no se puede mover a un servidor, y al revés tampoco.

const andco = createAndcoInstanceForBrowser({ clientId, redirectTo });

Construir una instancia no lee, no escribe, no pide nada por red y no programa ningún temporizador. Eso es deliberado: permite construirla dentro de un render que React puede descartar sin que quede nada a medias.

Sesión

La credencial de una persona: el token de acceso, su vencimiento, los scopes que aprobó y quién es. Vive en andco.session y tiene tres estados, no dos.

const session = andco.session.getSnapshot();
// undefined → todavía no se sabe
// null      → no hay sesión
// objeto    → hay sesión

undefined no es lo mismo que null. Confundirlos hace que tu aplicación muestre «inicia sesión» durante un instante en cada carga, incluso cuando la persona ya la tiene iniciada.

La sesión se carga sola la primera vez que alguien la lee —una suscripción, un await o una llamada a la API—, nunca al construir la instancia.

Grant

Lo que la persona aprobó para tu aplicación. No es algo que manejes desde el SDK: lo otorga la persona en la pantalla de Andco y el SDK lo refleja en session.scopes.

Un Grant se amplía pidiendo una autorización nueva con más scopes. No se amplía desde tu backend.

Scope

Un permiso concreto: openid, email, profile, bank_accounts:read. Los pides al autorizar y recibes exactamente los que la persona aprobó, que pueden ser menos.

await andco.auth.signIn({ scopes: ["openid", "email", "bank_accounts:read"] });

Pedir de más no es gratis: la pantalla de consentimiento crece y algunos scopes exigen que la persona complete verificaciones antes de poder aprobarlos. Pide lo que vas a usar.

Intent

Una operación financiera que Andco presenta por su cuenta: un depósito, un retiro, un cargo automático. Tu aplicación la crea y la presenta, pero no dibuja su interfaz ni ve sus datos.

Crear un depósito, un retiro o un cargo automático es específico del dominio bancario, así que vive en el Bank Resource Server Definition, no en el cliente principal. Se vincula una vez a las credenciales vigentes:

import { Bank } from "@andco/bank-sdk";

const bankDefinition = new Bank({ clientId, resource: "https://api.andco.cl" });
const bank = bankDefinition.use(andco);

const { data } = await bank.intents.createDeposit({ amount: 10000 });

El resultado autoritativo de una presentación no viene del callback: se lee del Intent después de la interacción. Eso evita que un mensaje perdido o duplicado se confunda con un resultado.