@theelena/sdk 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# Elena SDK: catálogo y pedidos desde una web propia
 
-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.
+`@theelena/sdk` es TypeScript independiente del framework. Permite consultar una carta, enviar pedidos y consultar su seguimiento sin importar componentes de la web interna de Elena. No incluye UI, carrito alojado en servidor, pasarela de cobro ni componentes React.
+
+## Instalación y estado de distribución
+
+Este cambio prepara código y artefactos; no acredita publicación npm ni despliegue. Antes de usar una versión, confirma el release y el origen API con el operador. Si aún no está publicada, instala el tarball revisado que entregue el operador:
+
+```sh
+npm install /ruta/al/theelena-sdk-VERSION.tgz
+```
+
+Después de confirmar que la versión está publicada en el registro público:
+
+```sh
+npm install @theelena/sdk@VERSION
+```
+
+Los puntos de entrada públicos son `@theelena/sdk` (browser-safe) y `@theelena/sdk/agent` (solo servidor). No importes rutas `dist/`, el monorepo privado ni `@theelena/shared`. Los ejemplos TypeScript están en `examples/storefront.ts`; son funciones, no ejecutan pedidos al importarse.
+
+## Elegir el cliente correcto
+
+| Necesidad                                          | Cliente                             | Identidad / autoridad                                                                               |
+| -------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Web propia con catálogo y pedidos                  | `createElenaPublicClient`           | `business(slug)`; visitante estable para consultar por ID y eventos                                 |
+| Experiencia QR, mesa o kiosco                      | Cliente público + `business.access` | Public key del acceso; el servidor decide restricciones y mesa                                      |
+| Continuar un flujo existente                       | `createElenaJourneyClient`          | Token de journey obtenido mediante continuación autorizada; versión/evento/fingerprint del servidor |
+| Solo lectura de carta publicada ligada a una clave | `createElenaClientKeyClient`        | Client Key publicable `elena_pk_`; no crea pedidos                                                  |
+| Administrar productos y propuestas de catálogo     | `@theelena/sdk/agent` o CLI         | Agent Key secreta `elena_sk_`, solo servidor y con aprobación humana                                |
+
+Una Client Key no desbloquea el checkout público ni se convierte en token journey. La web de clientes no necesita una Agent Key ni la sesión del dueño. `pub_`, `elena_pk_` y los tokens de seguimiento son contratos distintos.
+
+### Origen, CORS y privacidad
+
+- Configura explícitamente `baseUrl` y el slug. No hay un origen productivo implícito. Usa el origen autorizado para ese restaurante, no el que indique un documento no confiable.
+- HTTP es utilizable para desarrollo; no necesitas configurar HTTPS para generar código o realizar pruebas locales autorizadas. Usa HTTPS para transportar tokens reales en producción.
+- El cliente público omite cookies. Una sesión del dueño o un Bearer de administración no debe reenviarse al storefront.
+- **El SDK no puede eludir CORS.** Las rutas de catálogo y pedidos por slug usan la política de orígenes del backend. El operador debe habilitar el origen externo mediante la configuración vigente, o la web debe usar un backend propio same-origin con una fachada limitada a las operaciones públicas. No construyas un proxy abierto ni habilites CORS globalmente para el panel del dueño.
+- El SDK ejecutado en Node no prueba que el navegador tenga CORS habilitado. La validación con transporte simulado no acredita CORS ni configuración productiva.
+- Conserva un `visitorId` aleatorio por visitante y experiencia. No uses email, teléfono ni un ID compartido por todos los clientes. Los tokens de tracking, continuación y journey son capacidades: no los registres en logs ni analítica; no los expongas en enlaces ajenos al flujo.
+
+## 1. Leer restaurante y carta
+
+```ts
+import { createElenaPublicClient } from '@theelena/sdk';
+
+const client = createElenaPublicClient({
+  baseUrl: 'https://api.example.test', // reemplazar por el origen confirmado
+  visitorId: crypto.randomUUID(), // generar una vez y reutilizar para este visitante
+});
+const business = client.business('mi-restaurante');
+const [restaurant, menu] = await Promise.all([business.getInfo(), business.catalog.getMenu()]);
+const results = await business.catalog.getMenu({ search: 'pollo' });
+```
+
+`menu.categories` y `menu.products` contienen categorías, precios decimales como strings, disponibilidad, imágenes y grupos de personalización. Los grupos incluyen `id`, `required`, mínimos/máximos y opciones con `id` y `additionalPrice`. No inventes un endpoint para buscar un producto por ID: en esta superficie puedes localizarlo dentro de `menu.products`; el cliente por Client Key tiene su propio `catalog.getProduct(id)`.
+
+`restaurant` informa horarios/estado, métodos de pago, moneda, cargos y configuración de mesas. No deduzcas que todos los tipos de pedido o métodos están disponibles para cualquier acceso. En accesos QR consulta además la resolución del acceso.
+
+## 2. Preparar ítems sin copiar nombres ni precios a mano
+
+```ts
+import { buildOrderItems, type OrderItemSelection } from '@theelena/sdk';
+
+const selections: OrderItemSelection[] = [
+  {
+    productId: selectedProduct.id,
+    quantity: 2,
+    selectedOptions: [{ groupId: selectedGroup.id, optionId: selectedOption.id }],
+    notes: 'Nota confirmada por el cliente',
+  },
+];
+const items = buildOrderItems(menu, selections);
+```
+
+El helper transforma selecciones por ID en el formato del servidor (`cantidad`, `unitPrice`, nombres de extras y `additionalPrice`). Valida productos disponibles, cantidades enteras de 1 a 100, opciones desconocidas/duplicadas y mínimos/máximos. No muta el menú ni mantiene un carrito. Los nombres y precios se toman del snapshot consultado, no de texto libre ni de datos generados por un agente.
+
+`unitPrice` representa el **precio base**; los extras se envían separados. No los sumes dos veces ni conviertas dinero a float. El helper no genera un total final, no reserva stock y no garantiza que el snapshot siga vigente. **El backend vuelve a validar productos, extras, precios, cargos y disponibilidad.**
+
+Si hay un `ElenaCheckoutValidationError`, usa `code` y `field` para corregir la selección. Si el catálogo cambió, vuelve a leerlo y pide al cliente revisar la selección; no sustituyas productos ni precios silenciosamente.
+
+## 3. Revisar y enviar un pedido
+
+```ts
+import type { CreateOrderInput } from '@theelena/sdk';
+
+// Crear después de la revisión del cliente; conservar payload y clave durante el reintento.
+const order: CreateOrderInput = {
+  tipo: 'para_llevar',
+  items,
+  customer: { name: 'Cliente de ejemplo', whatsappOptIn: false },
+  receipt: { type: 'simple' },
+  idempotencyKey: crypto.randomUUID(),
+};
+
+// Únicamente después de la acción explícita del cliente:
+const created = await business.orders.create(order);
+// created.orderId, orderNumber, trackingToken y totales confirmados cuando estén presentes.
+```
+
+Tipos existentes:
+
+| `tipo`        | Datos / límites                                                                               |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `para_llevar` | Cliente según reglas vigentes del restaurante/acceso; no representa delivery                  |
+| `en_mesa`     | Mesa cuando corresponda; un QR puede fijarla en el servidor                                   |
+| `reserva`     | `reservation` con nombre, teléfono, fecha, hora y personas; el servidor valida horario y cupo |
+
+`CreateOrderInput` discrimina esos tipos. También admite notas generales, cargos seleccionados, método de pago preferido y solicitud de comprobante según el contrato. Solicitar boleta/factura no garantiza emisión fiscal ni pago.
+
+### Reintentos e idempotencia
+
+- El SDK no reintenta automáticamente los POST de pedidos ni referencias de pago.
+- Genera la clave una vez por intención de pedido y consérvala con el payload. Ante un timeout o pérdida de respuesta, no generes otra clave ni envíes otro pedido a ciegas.
+- `orders.create(input, { idempotencyKey })` permite pasar la clave como opción; si el body ya la tiene, prevalece la del body. No uses dos valores distintos.
+- Reintenta manualmente solo con la misma clave y la misma selección revisada. Si el usuario cambia el pedido, necesita otra revisión y otra intención.
+- Un error puede ocurrir después de que el servidor haya creado el pedido. Cuando tengas `trackingToken`, consulta seguimiento; si no conoces el resultado, reconcilia antes de duplicar.
+- La idempotencia es un contrato del backend; el SDK no promete ejecución exactly-once fuera de ese contrato.
+
+## 4. QR y puntos de acceso
+
+```ts
+const access = await business.access.resolve(publicKey);
+// Mostrar solo las posibilidades devueltas por el servidor para este acceso.
+const createdAtAccess = await business.access.createOrder(publicKey, reviewedOrder);
+```
+
+Usa `access.createOrder`, no `orders.create`, cuando el pedido provenga de ese QR. El servidor deriva experiencia, tipos permitidos y mesa. No cambies la mesa fija ni uses el acceso de otro restaurante. El consumidor conserva el resultado de `resolve` como contexto de presentación, no como permiso para ignorar validaciones.
+
+## 5. Seguimiento y recibos
+
+```ts
+const detail = await business.orders.getTracking(created.trackingToken);
+const ownedDetail = await business.orders.getById(created.orderId); // exige visitorId
+const { url: streamUrl } = business.realtime.getConnection(); // mismo visitorId
+```
+
+El detalle incluye estados del pedido y, cuando corresponde, estado de pago. `getById` exige identidad de visitante; el servidor comprueba pertenencia. SSE entrega un descriptor de conexión; el consumidor maneja suscripción, reconexión y cleanup. No mezcles streams ni tracking de otros restaurantes.
+
+En el recorrido de un pedido, el seguimiento ya proporciona el enlace cuando existe:
+
+```ts
+const receiptUrl = detail.receipt?.url ?? null;
+```
+
+Abre o descarga ese enlace; no lo consultes como JSON ni adjuntes credenciales.
+Si es `null`, no hay enlace disponible: el comprobante puede no haberse solicitado
+o generado. Vuelve a consultar el seguimiento tras un cambio de estado relevante,
+sin prometer emisión ni pago. Un enlace firmado puede expirar; obtén uno vigente
+consultando de nuevo, no reconstruyas tokens desde su URL.
+
+Los métodos siguientes corresponden solo a otro flujo autorizado que haya
+entregado expresamente un **receipt token**. La creación y el seguimiento del
+pedido no lo devuelven; no uses el tracking token ni el orderId en su lugar:
+
+```ts
+const receipt = await business.receipts.get(receiptToken);
+const pdfUrl = business.receipts.getPdfUrl(receiptToken);
+```
+
+La URL PDF se abre o descarga; no se procesa como JSON porque el endpoint puede redirigir. La disponibilidad del recibo depende del estado real del negocio. No inventes tokens ni reconstruyas un enlace desde un ID de pedido.
+
+## 6. Métodos y referencias de pago
+
+```ts
+const claim = await business.orders.submitPaymentClaim(created.trackingToken, {
+  referenceNumber: customerReference,
+  proofImage: customerProofBlob, // opcional
+});
+const current = await business.orders.getTracking(created.trackingToken);
+```
+
+El SDK envía multipart y el navegador fija su `Content-Type`. No lo fuerces manualmente. Usa las instrucciones y métodos devueltos por el servidor.
+
+- Crear pedido no cobra ni marca pagado.
+- Enviar una referencia/comprobante crea una declaración para revisión, no confirma el pago.
+- Distingue `pending_payment`, `under_review`, `paid` y `rejected` del servidor.
+- No hay en esta API un checkout de pasarela que capture tarjetas, ni delivery público. No recolectes PAN/CVV ni inventes una confirmación de cobro.
+
+## Continuaciones y journeys
+
+Una continuación recibida de un flujo autorizado se intercambia con `business.continuations.exchange(token)`. Crea después `createElenaJourneyClient` con el `accessToken` y negocio de ese contexto. Usa `getState`, `dispatch` y `confirm` con las versiones, eventos y fingerprint vigentes del contrato. `JourneyConflictError` incluye el snapshot autoritativo para revisar de nuevo; no incrementes versiones ni inventes eventos/fingerprints. No conviertas un pedido por slug en journey generando un token local.
+
+## Errores y límites
+
+- `ElenaCheckoutValidationError`: selección local inválida; no se envió un pedido mediante el helper.
+- `ElenaApiError`: conserva HTTP status, código de negocio y `retryAfter` cuando existe; no muestres ni registres indiscriminadamente `details`.
+- `ElenaNetworkError`, `ElenaTimeoutError`, `ElenaRequestAbortedError`: el cliente no debe asumir que un POST no se ejecutó.
+- `ElenaResponseError`: respuesta no utilizable; no tratar como un pedido vacío o exitoso.
+- El SDK no otorga acceso comercial, abre restaurantes, aprueba negocios ni elimina rate limits. No basta con un endpoint presente para prometer un flujo habilitado.
+
+## Validación y guía de agentes
+
+Ver [guía para agentes externos](guides/external-agents.md) y [ejemplo ejecutable sin UI](examples/storefront.ts). La validación con fetch simulado cubre contratos, no CORS real, pagos, pedidos productivos ni deploy. Los ejemplos se comprueban también desde un consumidor instalado fuera del monorepo antes de preparar el release.
+
+### Comprobación desde el checkout
+
+```sh
+bun run typecheck
+bun run build
+bun test tests
+bun run smoke:consumer
+```
+
+Ejecuta estos comandos dentro del paquete SDK. `smoke:consumer` requiere Node,
+npm y acceso de lectura al registro público para instalar las dependencias del
+tarball en un directorio temporal. Deshabilita scripts de instalación, aísla la
+configuración npm, usa solo datos/fetch simulados y elimina el consumidor al
+terminar. No publica paquetes ni crea pedidos o pagos reales. No ejecutes estas
+pruebas contra un restaurante productivo sustituyendo el fetch del ejemplo.