Zafirox SDK
SDK 1.1.0 Cuentas Empezar

Proyecto

Registro de cambios

Versiones publicadas del SDK y de la API pública, con los cambios relevantes para las integraciones.

SDK

2.1.0 — preparado localmente el 30 de octubre de 2026

  • Agrega barra pública importable, controlador de temas y puente de preferencia visual con el contrato Angular existente. Primer host: bienvenida, sin marca duplicada. No cambia API comercial, políticas de pedidos ni autenticación.
  • Nueva distribución, tarball y SRI; versiones y canales existentes se conservan. La publicación remota está pendiente.

2.0.3 — 25 de septiembre de 2026

  • Actualiza el artefacto generado a la política 1.0.5: - el catálogo de tallas Nacional incluye 33 y 33 (1/2); - la validación local evalúa el pedido completo con la misma función generada que replica al servidor, así que la primera violación que informa el SDK es la misma que devolvería el backend; - un contenedor vacío vale igual como [] o como {}, y un objeto con claves "0" a "n-1" se lee como lista, igual que en el servidor; - un valor como type: "constructor" produce un error de política en lugar de un TypeError.
  • En el servidor, 1.0.5 acepta además quantity: 1.0 como el entero 1 en todos los perfiles, aplica a los metadatos de diseño el mismo recorte de espacios que String.prototype.trim y decide la autorización urgente con una sola regla de política.
  • Los canales v2 y latest apuntan a 2.0.3. Las versiones 2.0.0, 2.0.1 y 2.0.2 siguen disponibles e inmutables.

2.0.2 — 25 de septiembre de 2026

  • Actualiza el artefacto generado a la política 1.0.4, que alinea el SDK con la decisión del servidor: - un peso o medida decimal admite como máximo 32 caracteres; - un hecho booleano ausente, como nona, cuenta como falso al elegir la regla, igual que en el servidor.
  • En el servidor, 1.0.4 corrige además comparaciones como "2.0" frente al mínimo 2 y el tratamiento de números JSON según la configuración de PHP. Tras el cambio, el SDK y el backend deciden igual los mismos valores.

2.0.1 — 25 de septiembre de 2026

  • Actualiza el artefacto generado a la política 1.0.3: Otros admite una talla solitario opcional cuando pertenece al catálogo de measurement_system; sin talla continúa siendo válido.

2.0.0 — 24 de septiembre de 2026

  • El SDK envía orders.create() a POST /api/v2/client/orders, valida el perfil generado external-create-v2 y comprueba versión y SHA-256 de política en la respuesta.
  • La joya de creación incluye datos no financieros completos y 1–5 designRefs opacas obtenidas del servicio de carga autorizado por HTTP. El SDK no incorpora carga ni edición de órdenes.
  • El canal v1 conserva la versión 1.1.0.

1.1.0 — 16 de septiembre de 2026

  • Nuevo createAuthorizationCodeProvider («Acceder con Zafirox», OAuth 2.0 Authorization Code + PKCE S256): createAuthorizationUrl(), login(), completeLogin(url), isAuthenticated(), session(), logout(); sesión en sessionStorage o memoria y renovación silenciosa con refresh token (rotación).
  • Utilidades generatePkce, base64UrlEncode, requestToken y constantes CLIENT_API_AUTHORIZE_PATH / CLIENT_API_TOKEN_PATH.
  • createClientCredentialsProvider comparte el mismo cliente del token endpoint; sin cambios de contrato.
  • AuthenticationError puede llevar INVALID_GRANT (HTTP 400) al canjear un code o renovar.

1.0.0 — 16 de septiembre de 2026

  • Primera versión pública de @zafirox/client-sdk (ESM + tipos, Node.js ≥ 22.18 y navegadores).
  • Módulos orders (create, list), account (get, transactions) y portfolio (get, payments).
  • Proveedores de token createClientCredentialsProvider (backend) y createStaticTokenProvider (navegador vía BFF).
  • Transporte con X-Request-Id, timeout por AbortController, límite de tamaño, validación del envelope y de api_version, reintentos sólo de errores transitorios en operaciones idempotentes.
  • Errores tipados con code, status, requestId, retryable, field, diagnosticId y retryAfterSeconds.

API pública

v2 de creación — preparada, pendiente de publicación

  • POST /api/v2/client/order-designs recibe 1–5 imágenes y devuelve referencias opacas certificadas; POST /api/v2/client/orders crea con el contrato de política versionado.
  • La creación v1 se retira con 410 ORDER_CREATE_VERSION_RETIRED al publicar v2; las lecturas y OAuth v1 siguen activas.
  • OpenAPI 3.1 v2 generado y expuesto en /openapi/v2.yaml; sus extensiones x-order-policy-* describen límites de texto tras String.trim() ECMAScript, medidos en UTF-16.

v1 — «Acceder con Zafirox» — 16 de septiembre de 2026

  • GET /oauth/authorize redirige a accounts.joyeriazafirox.com, donde la persona inicia sesión con su propia cuenta de Zafirox y autoriza los scopes.
  • POST /oauth/token admite grant_type=authorization_code (con code_verifier) y grant_type=refresh_token (rotación); la respuesta incluye refresh_token.
  • Clientes públicos (kind=public, sin secreto) con redirect_uris registradas; clientes confidenciales pueden combinar client_credentials y authorization_code.
  • Nuevos códigos: INVALID_GRANT (400), ACCOUNT_LOGIN_REJECTED (401, sólo en la pantalla de cuentas) y GATEWAY_KEY_INVALID (403, pasos reservados a accounts).
  • El token endpoint y el preflight OPTIONS reflejan Access-Control-Allow-Origin únicamente para orígenes registrados.

v1 — 16 de septiembre de 2026

  • Fachada /api/v1/client con OAuth 2.0 client_credentials, scopes y alcance resuelto en servidor (titular + masters activos).
  • Operaciones: emisión de token, crear y listar órdenes, cuenta, transacciones, cartera y pagos.
  • Envelope {data, meta, errors}, dinero como decimal string, fechas RFC 3339, paginación por cursor e idempotencia en la creación de órdenes.
  • CORS por origen registrado, límite por cliente con Retry-After y kill switch de mantenimiento (503 CLIENT_API_DISABLED).

Ciclo de vida y roadmap

Los tres temas del ciclo de vida operativo han quedado formalmente especificados en la documentación de arquitectura (documento 10 de ExternalClientSdk):

  • Publicación del SDK en un registro npm: Empaquetado oficial bajo @zafirox/client-sdk con distribución dual (registro npm con --provenance y CDN inmutable en sdk.joyeriazafirox.com/cdn/ con hashes SHA-384 / SRI), paquete ESM estricto sin dependencias de terceros. Permite instalación estándar vía npm install @zafirox/client-sdk.
  • Rotación de secretos con solapamiento: Ventana de gracia sin tiempo de inactividad (zero-downtime) en dos niveles: secreto secundario temporal (48-72 h) para clientes confidenciales durante despliegues de múltiples instancias, y cabecera kid con keyring de claves activas/en retiro para la firma de tokens JWT de la plataforma.
  • Revocación de todas las sesiones de una persona desde Zafirox: Marca temporal de revocación (revoked_before / Epoch) por subject_uid en «Acceder con Zafirox»; invalida en el acto todos los refresh tokens (HTTP 400 invalid_grant) y access tokens vigentes (HTTP 401 TOKEN_REVOKED) ante cambio de contraseña, suspensión de cuenta o cierre voluntario de sesiones conectadas.