stocker-sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+# Stocker SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cliente TypeScript de Stocker generado desde OpenAPI con Hey API.
+
+## Compatibilidad y dependencias
+
+El paquete se distribuye como ESM y declara Node.js 22.18 o superior. Para
+desarrollarlo usa Node.js 22.18+ de la rama 22 o Node.js 24.11+ de la rama 24,
+compatibles con las herramientas de compilación. La configuración se verifica
+actualmente con Node.js 24.14 y TypeScript 6.0.3.
+
+Hey API está fijado en la versión estable `0.99.0`. La versión `next` se utilizó
+para resolver una incompatibilidad con TypeScript 7; ya no es necesaria al usar
+TypeScript 6 y el generador `tsc` para declaraciones. Las versiones directas se
+fijan y `package-lock.json` conserva la resolución del árbol de dependencias.
+
+El override de `js-yaml` a `4.3.2` actualiza la dependencia del parser de OpenAPI
+dentro de la misma versión mayor para corregir sus avisos de seguridad. Debe
+revisarse cuando Hey API actualice esa dependencia.
+
+Jsona es la única dependencia de ejecución. Hey API, TypeScript, tsdown y Vitest
+son herramientas de desarrollo: no se instalan como dependencias del SDK en las
+aplicaciones consumidoras. Las exportaciones públicas incluyen las declaraciones
+TypeScript y el JavaScript compilado; el playground y las credenciales se excluyen
+del paquete.
+
+## Estructura
+
+```text
+openapi/                   Contratos OpenAPI y sus diagnósticos
+src/
+  index.ts                 Entrada pública: recursos, tipos y creación de clientes
+  client.ts                Inicialización común de clientes de Stocker
+  generated/stocker/       Código generado; no editar manualmente
+  jsonapi/                 Deserialización genérica y tipos derivados de OpenAPI
+playground/
+  index.ts                 Llamadas reales para probar durante el desarrollo
+  stocker.ts               Cliente local configurado mediante variables de entorno
+tests/
+  client.test.ts           Pruebas automatizadas sin conexión a la API
+  deserialize.test.ts      Pruebas de transformación y de tipos
+.env.example               Ejemplo de configuración local sin credenciales
+.env.local                 Configuración privada, ignorada por Git
+dist/                      Resultado de compilación, ignorado por Git
+```
+
+El paquete se construye desde `src/index.ts`. Importarlo expone el SDK sin
+realizar solicitudes ni cargar la configuración del playground.
+
+## Inicializar el cliente
+
+```ts
+import { createStockerClient, Products } from 'stocker-sdk';
+
+const client = createStockerClient({
+  baseUrl: 'https://api.example.com',
+  tenant: 'my-tenant',
+  apiKey: 'my-api-key',
+});
+
+const { data } = await Products.listProducts({ client });
+```
+
+La función configura `X-Tenant` y `api-key`, valida que las tres opciones estén
+presentes y usa `throwOnError: true` por defecto. Acepta también las opciones del
+cliente Fetch, como `fetch`, `headers`, `signal` y `throwOnError: false`. Los
+encabezados adicionales no reemplazan los valores de `tenant` y `apiKey`.
+
+Cada llamada crea un cliente independiente. El SDK no lee variables de entorno;
+puedes pasar directamente sus valores y la función validará los que falten:
+
+```ts
+const client = createStockerClient({
+  baseUrl: process.env.STOCKER_BASE_URL,
+  tenant: process.env.STOCKER_TENANT,
+  apiKey: process.env.STOCKER_API_KEY,
+});
+```
+
+El playground utiliza esta inicialización. Las solicitudes siguen recibiendo
+el cliente mediante `{ client }`.
+
+## Deserialización de respuestas
+
+`deserialize()` usa Jsona para convertir un documento JSON:API en modelos con
+atributos y relaciones accesibles directamente. Los tipos se infieren del
+contrato generado, sin definir un convertidor por recurso.
+
+```ts
+import { deserialize, Products } from './src/index';
+
+const { data: document } = await Products.listProducts({
+  client: backend,
+  query: {
+    include: ['category'],
+    'fields[products]': ['name', 'code', 'category'],
+  },
+});
+
+const products = deserialize(document);
+console.log(products?.[0]?.name);
+console.log(products?.[0]?.category?.name);
+```
+
+`backend` es un cliente configurado por la aplicación, como el del playground.
+La función recibe el documento JSON:API (`response.data`), no la respuesta HTTP
+completa. Una colección devuelve un arreglo; un documento individual devuelve
+un objeto. Se conservan `undefined`, `null` y los documentos con `data: null`.
+
+Las relaciones se resuelven usando `included` y los recursos principales del
+documento. Si faltan sus atributos, se conserva la referencia `{ type, id }`;
+no se hacen solicitudes adicionales. Los atributos siguen siendo opcionales
+para reflejar campos parciales. Los atributos y relaciones se convierten a
+camelCase: `product-sales` pasa a `productSales` y `created_at` a `createdAt`,
+incluyendo las propiedades de objetos anidados en atributos. El autocompletado
+refleja esos nombres. Los valores de `type`, los `links` y la metadata del recurso no cambian.
+La metadata de cada relación se expone como propiedades con el nombre de la relación
+como prefijo: `relationships.products.meta.count: 23` produce `productsCount: 23`,
+incluso si la relación no contiene `data`. Por ejemplo, `purchase-products.meta.total_pages`
+produce `purchaseProductsTotalPages`. Los valores se conservan tal cual, incluidos
+objetos anidados. Los atributos, relaciones y propiedades estructurales tienen prioridad
+ante colisiones. El tipado de `Model` solo expone claves de metadata declaradas
+explícitamente en el esquema, con sus tipos originales y como propiedades opcionales.
+No hay tratamiento especial para `count`. No se admiten claves dinámicas en el modelo: `productsCounts` produce
+un error de TypeScript. La deserialización sigue copiando todas las claves recibidas.
+Las consultas `include` y `fields` siguen usando los nombres originales de la API.
+
+También se pueden derivar tipos sin duplicar interfaces:
+
+```ts
+import type { Model, V1ProductsResource } from './src/index';
+
+type Product = Model<V1ProductsResource>;
+```
+
+El documento original no se modifica: consérvalo para acceder a paginación,
+`links`, `meta` y metadatos de relaciones. Los modelos conservan `type`, `id`,
+los atributos, las relaciones y los `links`/`meta` del recurso. Jsona agrega
+`relationshipNames` en los modelos que contienen relaciones.
+
+Esta función no valida el esquema en ejecución ni convierte fechas o números
+representados como texto. Los tipos dependen de que el servidor cumpla OpenAPI.
+Puede haber ciclos en los modelos; no se garantiza que dos apariciones de un
+recurso sean el mismo objeto por referencia, ni que `JSON.stringify()` funcione
+sobre un grafo con ciclos. Los cuerpos de escritura siguen usando JSON:API.
+
+## Desarrollo
+
+```bash
+npm install
+```
+
+Para regenerar el cliente después de modificar el contrato:
+
+```bash
+npm run generate:api
+```
+
+Para compilar el paquete y seguir los cambios:
+
+```bash
+npm run dev
+```
+
+Este comando compila la biblioteca; no ejecuta el playground.
+
+## Pruebas manuales con la API
+
+En una instalación nueva, copia `.env.example` a `.env.local` y configura
+`STOCKER_BASE_URL`, `STOCKER_TENANT` y `STOCKER_API_KEY`.
+
+```bash
+cp .env.example .env.local
+npm run playground
+```
+
+En este proyecto ya se migró la configuración local existente a `.env.local`.
+No es necesario reemplazarla. Las credenciales no se incluyen en Git.
+
+Edita `playground/index.ts` para probar productos, ventas u otros recursos. El
+playground importa la entrada pública del SDK desde `src/index.ts`.
+
+Para repetir las llamadas cada vez que guardes cambios:
+
+```bash
+npm run playground:watch
+```
+
+El playground realiza solicitudes reales al servidor configurado.
+
+## Pruebas automatizadas
+
+Las pruebas de `tests/` usan respuestas simuladas y no necesitan credenciales.
+
+```bash
+npm test
+npm run test:run
+```
+
+`npm test` mantiene las pruebas en modo observación. `test:run` las ejecuta una vez.
+
+## Verificación
+
+```bash
+npm run typecheck
+npm run test:run
+npm run build
+```
+
+Para ejecutar todas las comprobaciones, incluida la validación del paquete npm:
+
+```bash
+npm run check
+```
+
+`prepack` compila antes de crear el paquete y `prepublishOnly` ejecuta todas las
+comprobaciones antes de publicar. Estos scripts utilizan npm.