XamiLib Node.js — Referencia de clases

Paquete: xamisdk-client. El punto de entrada es la clase XamiSDK. Los métodos siguen la convención camelCase de JavaScript. Todos son async y devuelven Promise. Incluye tipados .d.ts para TypeScript.

`XamiSDK`

Punto de entrada de la librería.

Constructor

new XamiSDK(config)

config acepta:

Clave	Descripción
`endpoint`	URL del servicio local (por defecto `http://127.0.0.1:8300`).
`wrapperKey`	Credencial de aplicación (`wrp_...`).
`wrapperSecret`	Secret de la credencial (`wsec_...`).
`timeout`	Timeout HTTP en segundos (opcional, 30 por defecto).

Métodos

Método	Devuelve	Descripción
`pades()`	`Pades`	Servicio de firma de documentos PDF.
`blockchain()`	`Blockchain`	Servicio de firma de transacciones EVM.
`credentials()`	`Credentials`	Consulta de credenciales.
`designs()`	`Designs`	Consulta de diseños de sello.
`health()`	`Health`	Estado del servicio local.
`results()`	`Results`	Resultados de firma recientes. (xamiSDK ≥ 0.2.0)
`errors()`	`Errors`	Errores registrados por el servicio local. (xamiSDK ≥ 0.2.0)
`sync(): Promise<object>`	resumen	Recarga credenciales y diseños desde Xami sin reiniciar. (xamiSDK ≥ 0.2.0)

`Pades`

Firma de documentos PDF (PAdES).

Métodos

`sign(pdfBytes: Buffer, opts): Promise<string>`

Envía un PDF a firmar. Devuelve el request_id. opts: credential_key (requerido), design_key, variables, reason, location, signer_name.

`result(requestId): Promise<object>`

Consulta el estado. Cuando está DONE, incluye el PDF firmado en pdf_base64.

`wait(requestId, timeoutSeconds = 60, pollSeconds = 1.0): Promise<Buffer>`

Bloquea hasta que la firma esté lista y devuelve el PDF firmado.

`signAndWait(pdfBytes, opts, timeoutSeconds = 60): Promise<Buffer>`

Atajo: sign() + wait(). Devuelve el PDF firmado.

Ejemplo

const pdfFirmado = await xami.pades().signAndWait(
  fs.readFileSync('documento.pdf'),
  {
    credential_key: 'TU_CREDENCIAL',
    signer_name: 'Tu Nombre',
    reason: 'Aprobación',
    variables: { name: 'Tu Nombre' },
  }
);
fs.writeFileSync('documento_firmado.pdf', pdfFirmado);

`Blockchain`

Firma de transacciones / mensajes EVM. El chip actúa como wallet y devuelve r/s/v; tú ensamblas la transacción con tu web3.

Métodos

`sign(txHash: string, opts): Promise<string>`

Envía el hash a firmar. Devuelve el request_id. opts: credential_key (requerido, credencial EVM), chain_id.

`result(requestId): Promise<object>`

Consulta el estado.

`wait(requestId, timeoutSeconds = 60, pollSeconds = 1.0): Promise<object>`

Bloquea hasta tener la firma. Devuelve { r, s, v, signature, ... }.

`signAndWait(txHash, opts, timeoutSeconds = 60): Promise<object>`

Atajo: sign() + wait().

Ejemplo

const firma = await xami.blockchain().signAndWait('0xHASH_DE_LA_TX', {
  credential_key: 'TU_CREDENCIAL_EVM',
  chain_id: 648541,
});
// firma.r, firma.s, firma.v

`Credentials`

Consulta de credenciales en la caché local.

Método	Devuelve	Descripción
`all(): Promise<object[]>`	lista	Todas las credenciales disponibles.
`get(key): Promise<object\\|null>`	credencial o `null`	Una credencial por su `credential_key`.

`Designs`

Consulta de diseños de sello en la caché local.

Método	Devuelve	Descripción
`all(): Promise<object[]>`	lista	Todos los diseños disponibles.
`get(key): Promise<object\\|null>`	diseño o `null`	Un diseño por su `design_key`.

`Health`

Método	Devuelve	Descripción
`self(): Promise<object>`	estado	Estado del servicio local (pareado, tenant, versión, etc.).
`version(): Promise<string\\|null>`	versión	Versión del xamiSDK local. `null` si es anterior a 0.2.0.
`apiVersion(): Promise<number>`	entero	Versión del contrato local. `1` = sin `sync()`, `results()` ni `errors()`.

`Results`

Requiere xamiSDK ≥ 0.2.0.

Pades.result() necesita que conserves el requestId. Si tu proceso se reinició o el push no llegó, ese documento quedaba inalcanzable desde la librería. Con Results puedes recuperar lo firmado sin depender de tu propio almacenamiento.

Método	Devuelve	Descripción
`recent(limit = 50): Promise<object[]>`	lista	Últimos resultados (`PENDING` / `DONE` / `ERROR`).
`pending(limit = 50): Promise<object[]>`	lista	Solo los que siguen esperando la firma del chip.

for (const r of await xami.results().pending()) {
  console.log(r.request_id, 'esperando desde', r.created_at);
}

`Errors`

Requiere xamiSDK ≥ 0.2.0.

Devuelve el mensaje corto y el error_id de cada fallo. Nunca devuelve el traceback: el detalle técnico solo sale del equipo del cliente cuando alguien ejecuta xamisdk report. Está pensado para que tu aplicación pueda decirle al usuario qué falló y con qué identificador pedir soporte.

Método	Devuelve	Descripción
`recent(limit = 20): Promise<object[]>`	lista	Últimos errores registrados.
`forRequest(requestId): Promise<object[]>`	lista	Errores de un request concreto.

const fallos = await xami.errors().forRequest(requestId);
if (fallos.length) {
  console.log('No se pudo firmar:', fallos[0].short);
  console.log('Menciona', fallos[0].error_id, 'al pedir soporte.');
}

Compatibilidad de versiones

Los métodos marcados con xamiSDK ≥ 0.2.0 devuelven 404 contra un servicio anterior. Compruébalo antes si no controlas la versión instalada:

if ((await xami.health().apiVersion()) >= 2) {
  await xami.sync();
}

Manejo de errores

Todos los métodos lanzan (rechazan la Promise con) XamiException ante un fallo (credencial inválida, servicio caído, timeout). Expone message y code.

const { XamiException } = require('xamisdk-client');

try {
  const pdf = await xami.pades().signAndWait(pdfBytes, { credential_key: '...' });
} catch (e) {
  if (e instanceof XamiException) {
    console.error('Error al firmar:', e.message, e.code);
  } else {
    throw e;
  }
}

Descargar este manual (.md)