SDK Reference

Referencia de @accesly/react y @accesly/core. Provider, hooks, componentes del kit y helpers.

Paquetes

Paquete	Versión	Descripción
`@accesly/react`	2.6.0	Provider, hooks React, componentes prearmados
`@accesly/core`	1.21.0	Cliente API, tipos, helpers criptográficos, DeviceStore
`@accesly/react/kit`	Sub path de react	Componentes UI listos para renderizar

AcceslyProvider

El provider raíz. Envolvés tu app con esto y todos los hooks + componentes del kit funcionan.

Props

Prop	Tipo	Requerido	Descripción
`appId`	string	Sí	App ID del dashboard. Determina branding, redes, providers de auth.
`env`	"dev" \| "staging" \| "prod"	Sí	Environment del backend. Determina qué API URL usar.
`authCallbackPath`	string	No	Path del callback OAuth. Default: `/auth/callback`. Setear si tu app vive en sub path.
`overrides`	object	No	Override de `deviceStore`, `sessionStorage`, `authClient`. Ver Overrides.
`cognitoConfig`	object	No	Skipea el bootstrap fetch del appConfig. Útil para tests.
`loadingFallback`	ReactNode	No	UI mientras se resuelve el appConfig inicial.
`errorFallback`	(err) => ReactNode	No	UI si falla el bootstrap del appConfig.

Overrides

Para producción siempre pasá deviceStore: new IndexedDbDeviceStore(). Sin esto el default es InMemoryDeviceStore y el usuario pierde acceso al recargar la página.

import { IndexedDbDeviceStore } from '@accesly/core';

<AcceslyProvider
  appId={appId}
  env="dev"
  overrides={{
    deviceStore: new IndexedDbDeviceStore(),
  }}
>

useAccesly

El hook principal. Devuelve namespaces con toda la API del SDK.

const {
  auth,       // signIn, signUp, signInWithGoogle, signOut, handleAuthCallback
  wallet,     // bootstrap, unlockForSigning, fetchRemote, getStoredCredential
  tx,         // send, swap, swapViaSdex
  recovery,   // requestOtp, verifyOtp, finalize, reconstructSeed
  fiat,       // startOnRamp, startOffRamp, checkStatus
  contacts,   // list, add, remove, resolve
  _internal,  // context avanzado
} = useAccesly();

auth

Método	Uso
`signUp(email, password)`	Registra un user con email + password. Cognito manda código de confirmación.
`confirmSignUp(email, code)`	Confirma el signup con el código del email.
`signIn(email, password)`	Login clásico.
`signInWithGoogle(redirectUri?)`	Redirige a Cognito Hosted UI con Google IdP.
`handleAuthCallback(code, redirectUri?)`	Intercambia el code del OAuth callback por tokens.
`signOut()`	Borra tokens de session storage.
`status`	"anonymous" \| "authenticated" \| "expired" \| "bootstrapping"
`username`	Email del usuario actual, o null si no autenticado.

wallet

Método	Uso
`bootstrap({ email, password, passkey })`	Crea passkey, genera seed, deploya Smart Account on chain.
`unlockForSigning(username)`	Pide biométrico al chip, devuelve material listo para firmar.
`fetchRemote()`	GET /wallets. Devuelve datos on chain del user actual, o null si no tiene wallet.
`getStoredCredential(username)`	Lee del DeviceStore. Devuelve el CredentialRecord local o null.
`bootstrapG(input)`	Crea la G address bridge (cuenta Stellar classic). Auto disparado por flows que lo requieren.
`addTrustlineG(input)`	Agrega trustline a la G address para un asset específico.
`sweepGToSA(input)`	Mueve balance de la G al Smart Account.

tx

Método	Uso
`send({ to, amount, asset, ...material })`	Transfer XLM o USDC on chain. `material` viene de unlockForSigning.
`swap({ fromAsset, toAsset, amountIn, slippageBps, ...material })`	Swap XLM ↔ USDC vía Soroswap.
`swapViaSdex(...)`	Fallback SDEX classic. El kit lo dispara auto si Soroswap no tiene path.

recovery

Método	Uso
`requestOtp({ email })`	Manda OTP al email. Rate limited: 3/hora.
`verifyOtp({ email, code, idToken? })`	Verifica OTP, devuelve recoveryJwt.
`finalize({ email, password, recoveryJwt, passkey })`	Orquesta el flow completo: reconstruye seed, rota signer, guarda nuevos fragments.
`reconstructSeed({ cognitoPassword, recoveryJwt })`	Bajo nivel. Reconstruye la seed sin rotar. Para casos custom.

fiat

Método	Uso
`registerBankAccount({ clabe, ...kycData })`	Registra CLABE + CURP + datos KYC en Dynerox.
`startOnRamp({ amount, currency })`	Crea route MXN → USDC Stellar. Devuelve authorizationUrl.
`startOffRamp({ amount, clabeId })`	Crea route USDC Stellar → MXN. Devuelve authorizationUrl.
`checkStatus(routeId)`	Consulta status de una route específica.

Hooks

useAppConfig

Lee la config del app (branding, providers, network). Cached module level: un solo poll a backend por appId sin importar cuántos componentes lo consuman.

const { appConfig, status, error } = useAppConfig();

// appConfig.network: "testnet" | "mainnet"
// appConfig.branding: colores, logos, textos
// appConfig.auth.providers: ["email", "google"]

useBranding

Escribe CSS vars al :root con los colores del app. Devuelve textos brandeados (loginButtonText, landingTitle, etc.).

const branding = useBranding();

// document.documentElement tiene ahora:
//   --accesly-primary: #a78bfa
//   --accesly-grad: linear-gradient(...)
// Y branding.loginButtonText = "Ingresar" o el custom del dev

useBalance

Devuelve balance XLM + USDC de la wallet actual. Poll + SSE, cached module level.

const { xlm, usdc, loading, refetch } = useBalance();

useWalletHistory

Historia paginada de transacciones. Poll cada 30s + optimistic updates.

const { history, nextPage, loading } = useWalletHistory({ limit: 20 });

useAuthProviders

Devuelve qué providers de auth están habilitados en el appConfig. Los componentes del kit usan esto para renderizar botones condicionales.

const { providers } = useAuthProviders();
// providers: ["email", "google"]

if (providers.includes('google')) {
  // renderizar botón Google
}

useKyc

Status de KYC del usuario en Dynerox.

const { status, authorizationUrl, refetch } = useKyc();

// status: "not-started" | "pending_identity" | "pending_authorization" | "active" | "inactive"
// authorizationUrl: link a auth.dynerox.com para completar el KYC

Otros hooks

useWalletStatus: onChain state del Smart Account.
useWalletActivity: eventos en tiempo real (SSE).
useContacts: address book del user.
useHandle: username global reservado (ejemplo @luis.accesly).
useStatus: health check del backend.
useUpgradeRecommendation: si hay upgrade disponible del contract.

Componentes del kit

Import: import { ComponentName } from '@accesly/react/kit';

Auth

<AuthForm mode="sign-in|sign-up" onSuccess onError />: email + password + Google en un solo componente.
<AuthCallback onSuccess onError redirectUri? />: handler de OAuth callback.
<GoogleSignInButton onError />: botón standalone.
<AuthGuard>children</AuthGuard>: HOC que redirige si no hay sesión.

Wallet

<CreateWalletFlow onDone onError onRecoverInstead />: bootstrap flow con passphrase input y detection de wallet existente.
<WalletHome />: dashboard con balance + botones + activity list.
<BalanceCard />: solo el balance card, standalone.
<MovementsList source="history|activity" pageSize />: lista de movimientos.
<WalletStatusBadge />: chip on chain / pending deploy / offline.
<WalletLauncher>children</WalletLauncher>: modal launcher para wallet embebida.

Transacciones

<SendFlow onSuccess onCancel defaultAsset? />: send con contact picker y validación.
<SwapFlow onSuccess onCancel defaultFrom defaultTo />: swap XLM ↔ USDC con quote y slippage.
<ReceiveFlow />: address + QR + copy.
<ContactPicker onSelect />: selector de contacto.
<HandleShareCard />: card para compartir tu handle global.

Recovery y KYC

<RecoveryFlow onDone onCancel passkeyRpName? />: recovery completo con selector de método.
<AddFundsFlow onDone />: on ramp Dynerox con KYC preflight.

Overrides + custom UI

Todos los componentes leen tu branding automáticamente. Si querés customizar más:

Override CSS vars (--accesly-primary, --accesly-grad, --accesly-card, etc.) en tu propio CSS.
Pasar prop className a la mayoría de componentes para reemplazar el wrapper.
Los componentes son function exports, podés forkarlos si necesitás customización de fondo. El source está en el package de node_modules/@accesly/react/dist.

Integración con Astro

El SDK depende de APIs browser (IndexedDB, WebAuthn). Si tu Astro app usa output: 'server', montá los componentes como client:only="react":

---
import { DemoEntry } from '../components/demo/DemoEntry';
---

<DemoEntry client:only="react" />

Y en astro.config.mjs agregá node polyfills scopeados solo al client build:

import { nodePolyfills } from 'vite-plugin-node-polyfills';

const polyfills = nodePolyfills({
  include: ['buffer', 'crypto', 'stream', 'util', 'process'],
  globals: { Buffer: true, global: true, process: true },
});

const clientOnly = (Array.isArray(polyfills) ? polyfills : [polyfills]).map((p) => ({
  ...p,
  apply: (_c, env) => !env.isSsrBuild,
}));

export default {
  vite: {
    plugins: clientOnly,
    ssr: {
      external: ['@accesly/react', '@accesly/core', '@stellar/stellar-sdk'],
    },
  },
};

Errores

El SDK exporta clases de error específicas para try/catch preciso:

WalletNotEnrolledError: rule missing para un asset.
GAddressNotBootstrappedError: la G bridge no existe todavía.
GMissingTrustlineError: falta trustline en la G.
WalletAlreadyExistsError: intentaste bootstrap y ya hay wallet en backend.
RotateWriteCapExceededError: la wallet tiene 4+ context rules y el rotate atómico excede el cap P27 de writeBytes. El SDK atrapa esta clase internamente y ejecuta el flow multi tx del Smart Account v3.2.0; solo llega al caller si el flow multi tx también falla. Trae walletAddress, writeBytes, cap, rotatableRuleIds.
AuthError, ValidationError, RateLimitError, etc.

Catálogo completo con códigos HTTP y remediation en Errores.

Siguientes pasos

API Reference: endpoints REST directos.
Quickstart: integrar el SDK en 5 minutos.
Dashboard: crear tu app y obtener el appId.