Instalación del SDK

El SDK se publica como módulo ESM con tipos TypeScript y cero dependencias. Puede incorporarse mediante el registro npm (@zafirox/client-sdk), descargarse como tarball desde el CDN de este sitio o importarse directamente por URL en navegadores.

Requisitos

• Node.js 22.18 o superior (usa fetch, AbortController y crypto.randomUUID nativos) o un navegador moderno.
• TypeScript ≥ 5.7 si quieres los tipos; el paquete incluye .d.ts.
• Sin dependencias: el SDK no instala dependencias de terceros en tu proyecto.

Node.js y entornos con npm

Método 1: Desde el registro npm (Recomendado)

Instala el paquete oficial @zafirox/client-sdk:

npm install @zafirox/client-sdk

Si tu empresa utiliza un registro npm privado o GitHub Packages, configura el scope en tu archivo .npmrc:

@zafirox:registry=https://registry.npmjs.org/

Método 2: Desde el CDN (tarball directo)

Si tu entorno no tiene acceso directo al registro npm o prefieres fijar el tarball exacto verificado:

npm install https://sdk.joyeriazafirox.com/cdn/v1/zafirox-client-sdk-1.1.0.tgz

Para fijar una versión exacta usa la ruta de versión en lugar del canal, por ejemplo /cdn/1.1.0/zafirox-client-sdk-1.1.0.tgz. El nombre del tarball figura en [/cdn/manifest.json](/cdn/manifest.json).

import { ZafiroxClient, createClientCredentialsProvider } from '@zafirox/client-sdk';

Si prefieres no usar npm, descarga los archivos .js y .d.ts de una versión y cárgalos como módulos locales; los import internos son relativos (./client.js) y funcionan sin bundler.

Navegador (ESM por URL)

<script type="module">
  import { ZafiroxClient, createStaticTokenProvider }
    from 'https://sdk.joyeriazafirox.com/cdn/1.1.0/index.js';
</script>

• /cdn/v1/… sigue la última versión 1.x (revalidación cada 5 minutos). Úsalo en desarrollo.
• /cdn/1.1.0/… es inmutable y cacheable un año. Úsalo en producción.
• El CDN responde con Access-Control-Allow-Origin: *, ETag y X-Sdk-Version.

Consejo: los módulos ESM importados con import no admiten el atributo integrity en todos los navegadores. Si necesitas SRI, usa un import map o descarga los archivos y sírvelos desde tu propio origen comparando el hash publicado en el manifiesto.

Verificar la integridad

Cada archivo publicado tiene un hash SHA-384 en manifest.json:

curl -sS https://sdk.joyeriazafirox.com/cdn/1.1.0/index.js | openssl dgst -sha384 -binary | openssl base64 -A
# debe coincidir con "integrity": "sha384-…" del manifiesto

TypeScript

Los tipos se resuelven automáticamente desde package.json (types: ./index.d.ts). Con moduleResolution: "bundler" o "nodenext" no hace falta configuración adicional. Los importes monetarios son del tipo DecimalString (un alias de string) para que el compilador te impida operar con ellos como números por accidente.

Actualizar

Las versiones siguen semver. Una versión mayor nueva del SDK acompaña una versión incompatible de la API (/api/v2/…). Revisa el registro de cambios antes de subir de versión.