@vivoa/partner-sdk 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.1
+
+- fix: `provisionStore` now throws `VivoaProvisioningFailedError` on `'unknown'` runtime instead of returning a broken store silently.
+- fix: `FakeVivoa.activate` now returns 409 on merchants in `'unknown'` state, matching platform behavior.
+- fix: `SDK_VERSION` extracted to `src/version.ts` — User-Agent header stays in sync with `package.json` on every bump.
+- fix: `WebhookConfig.events` typed as `MerchantEventType[]` instead of `string[]`.
+- fix: `listAll` throws after 10 000 pages instead of looping forever on a misbehaving server.
+- test: contract suite covers `suspend → reactivate` lifecycle.
+
 ## 0.1.0
 
 Primera versión.

package/README.md

@@ -1,18 +1,28 @@
 # @vivoa/partner-sdk
 
+**Embed full commerce stores in your product — provisioned via API, branded as yours.**
+
+Your users launch their store through your platform. Vivoa runs the infrastructure. They never see Vivoa.
+
 ```bash
-pnpm add @vivoa/partner-sdk      # o npm i / yarn add
+pnpm add @vivoa/partner-sdk
 ```
 
-SDK oficial de la **Partner API de Vivoa**, para crear y operar tiendas de tus comercios desde tu backend.
+[![npm](https://img.shields.io/npm/v/@vivoa/partner-sdk)](https://www.npmjs.com/package/@vivoa/partner-sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/Node-%E2%89%A522.18-green)](https://nodejs.org/)
+
+---
 
-- **Sin dependencias de runtime**: usa `fetch` y `node:crypto`, ambos reemplazables.
-- **Arquitectura hexagonal**: el núcleo no hace I/O. El transporte, la criptografía y el reloj son puertos que puedes cambiar.
-- **El handle lo asigna Vivoa**: no lo eliges tú al crear un merchant — la plataforma lo genera a partir de `name` y garantiza que sea único. Menos que validar, nada que pueda chocar.
-- **Seguro ante reintentos**: `provisionStore()` usa tu propio `externalId` como clave de idempotencia. Si lo vuelves a llamar después de un crash o un timeout, retoma la misma tienda en vez de crear otra.
-- **Testeable sin Vivoa**: `@vivoa/partner-sdk/testing` trae un Vivoa en memoria que verifica la firma HMAC real y aplica las mismas reglas que la plataforma.
+## What you get
 
-Guía de producto: [`docs/PARTNERS.md`](https://github.com/VivoaPlatform/vivoa-platform/blob/main/docs/PARTNERS.md). Contrato del servidor: [`engine/partner-api/CONTRACT.md`](https://github.com/VivoaPlatform/vivoa-platform/blob/main/packages/backend/src/engine/partner-api/CONTRACT.md).
+- **One call to provision a store.** `provisionStore()` handles creation, activation, and recovery — idempotent by design. Crash, retry, same store.
+- **Your brand, your API.** Merchants interact with your product. The Vivoa layer is yours to expose however you want.
+- **Production-safe from day one.** Fully typed errors, automatic retries on reads, HMAC-signed requests, webhook verification included.
+- **Test without hitting Vivoa.** The built-in `FakeVivoa` runs the same business rules as production — including real HMAC verification. No brittle mocks.
+- **Zero runtime dependencies.** Uses native `fetch` and `node:crypto`. No supply-chain risk. Drop-in on any runtime.
+
+---
 
 ## Quickstart
 
@@ -20,56 +30,69 @@ Guía de producto: [`docs/PARTNERS.md`](https://github.com/VivoaPlatform/vivoa-p
 import { createPartnerClient } from '@vivoa/partner-sdk';
 
 const vivoa = createPartnerClient({
-  apiKey: process.env.VIVOA_PARTNER_KEY!,
+  apiKey:    process.env.VIVOA_PARTNER_KEY!,
   apiSecret: process.env.VIVOA_PARTNER_SECRET!,
-  // baseUrl: 'https://api.vivoa.app' (default)
 });
 
-const me = await vivoa.me.get();              // plan, storesUsed/maxStores, allowedRegions
+// Provision a store for one of your users — idempotent on externalId
+const { merchant, status } = await vivoa.provisionStore({
+  externalId: 'cus_9f3a2e10',   // your internal reference — customer id, order id, etc.
+  email:      'owner@acme.com',
+  name:       'Acme',
+  countries:  ['SV'],
+});
 
-const { merchant, status, created } = await vivoa.provisionStore(
-  { email: 'owner@acme.com', name: 'Acme', countries: ['SV'], externalId: 'cus_9f3a2e10' },
-  { onProgress: (p) => console.log(p.phase, p.runtime) },
-);
-// merchant.handle → asignado por Vivoa; status.deployStatus === 'live'; status.domain → dominio de la tienda
+console.log(status.domain);     // store is live at this domain
+console.log(merchant.handle);   // Vivoa-assigned handle, guaranteed unique
 ```
 
-`externalId` es tu propia referencia (id de cliente, de orden…) — la usas para encontrar la tienda después (`findByExternalId`) y es la llave de idempotencia: `provisionStore` la exige justo por eso.
+`externalId` is your key. Use it to find the store later (`findByExternalId`), and call `provisionStore` again safely — it won't create a duplicate.
+
+---
 
-`provisionStore` hace lo siguiente:
+## `provisionStore` — full flow
 
-1. Busca el `externalId` en tu flota y, si no existe, crea la tienda (Vivoa asigna el `handle`).
-2. Activa la tienda si está `not_activated` o `failed`.
-3. Si queda `creating`, consulta el estado hasta que se asiente.
-4. Si el `activate` devuelve 409 o se cae la conexión, se recupera leyendo `GET /status`.
-5. Nunca reintenta por su cuenta un `failed`: lanza `VivoaProvisioningFailedError` y la decisión queda en tus manos.
+One call drives the entire lifecycle:
 
-## Superficie
+1. Looks up `externalId` in your fleet — if it exists, resumes from current state.
+2. Creates the store if it doesn't exist (Vivoa assigns the `handle` from `name`).
+3. Activates if `not_activated` or `failed`.
+4. Polls until settled if `creating`.
+5. Recovers from a dropped `activate` by reading `GET /status`.
+6. Never silently retries a `failed` — throws `VivoaProvisioningFailedError` so you decide what happens next.
 
-| Recurso | Métodos |
+---
+
+## API surface
+
+| Resource | Methods |
 |---|---|
-| `me` | `get()`, `rotateSecret()` (el cliente pasa a usar el secreto nuevo de inmediato) |
-| `merchants` | `create`, `list`, `listAll()` (iterador async), `findByExternalId`, `status`, `activate`, `suspend`, `reactivate` |
+| `me` | `get()`, `rotateSecret()` |
+| `merchants` | `create`, `list`, `listAll()` (async iterator), `findByExternalId`, `status`, `activate`, `suspend`, `reactivate` |
 | `webhooks` | `get`, `set`, `remove`, `rotateSecret`, `test`, `deliveries` |
 | `fleet` | `analytics()` |
-| cliente | `provisionStore`, `waitUntilSettled`, `verifyWebhook` |
+| client | `provisionStore`, `waitUntilSettled`, `verifyWebhook` |
+
+---
 
-## Errores
+## Errors
 
-Todos los errores extienden `VivoaError`. Los errores HTTP son `VivoaApiError` e incluyen `status`, `method`, `path` y `body`.
+All errors extend `VivoaError`. HTTP errors are `VivoaApiError` with `status`, `method`, `path`, and `body`.
 
-| Clase | Cuándo |
+| Class | When |
 |---|---|
-| `VivoaValidationError` | Input inválido, detectado en el cliente antes de enviar nada |
-| `VivoaBadRequestError` (400) | Payload inválido o país fuera de `allowedRegions` |
-| `VivoaAuthenticationError` (401) | Firma, key o reloj (±300 s) |
-| `VivoaForbiddenError` (403) | Cuenta no `active` o cupo lleno |
-| `VivoaNotFoundError` (404) | La tienda no es de tu flota |
-| `VivoaConflictError` (409) | `activate` sobre una tienda que ya está creándose, en vivo o suspendida |
-| `VivoaRateLimitError` (429) | Superaste las requests por minuto del plan |
-| `VivoaServerError` (5xx) · `VivoaNetworkError` · `VivoaTimeoutError` · `VivoaProvisioningFailedError` | Fallos del servidor, de red, de espera o del aprovisionamiento |
+| `VivoaValidationError` | Invalid input caught client-side before any request |
+| `VivoaBadRequestError` (400) | Invalid payload or country outside `allowedRegions` |
+| `VivoaAuthenticationError` (401) | HMAC signature, key, or clock skew (±300 s) |
+| `VivoaForbiddenError` (403) | Inactive account or quota exhausted |
+| `VivoaNotFoundError` (404) | Store not in your fleet |
+| `VivoaConflictError` (409) | `activate` on a store already live or in progress |
+| `VivoaRateLimitError` (429) | Plan request limit exceeded |
+| `VivoaServerError` · `VivoaNetworkError` · `VivoaTimeoutError` · `VivoaProvisioningFailedError` | Server, network, polling, or provisioning failures |
 
-Solo se reintentan los `GET`, ante 429, 5xx o errores de red, con backoff exponencial. Las escrituras no se reintentan a nivel de transporte — pero `merchants.create()` y `provisionStore()` son seguros de repetir de todas formas: con `externalId`, la plataforma responde con el mismo merchant en vez de un 409 o un duplicado.
+**Retry policy:** `GET` only, on 429 / 5xx / network errors, with exponential backoff. Writes are not retried at the transport level — but `merchants.create()` and `provisionStore()` are safe to repeat thanks to `externalId` idempotency.
+
+---
 
 ## Webhooks
 
@@ -80,83 +103,66 @@ import { verifyWebhook, VivoaWebhookSignatureError } from '@vivoa/partner-sdk';
 app.post('/vivoa-hooks', express.raw({ type: 'application/json' }), async (req, res) => {
   try {
     const event = await verifyWebhook({
-      rawBody: req.body,                                   // body CRUDO
+      rawBody:         req.body,
       signatureHeader: req.header('x-vivoa-signature'),
-      signingSecret: process.env.VIVOA_WEBHOOK_SECRET!,
+      signingSecret:   process.env.VIVOA_WEBHOOK_SECRET!,
     });
-    res.sendStatus(204);                                   // responder rápido
-    queue.push(event);                                     // procesar en segundo plano
+    res.sendStatus(204);   // respond fast, process async
+    queue.push(event);
   } catch (err) {
     res.sendStatus(err instanceof VivoaWebhookSignatureError ? 401 : 500);
   }
 });
 ```
 
-## Testing sin tocar Vivoa
+---
+
+## Testing
+
+`@vivoa/partner-sdk/testing` ships a `FakeVivoa` that runs the same rules as the real server — real HMAC verification, real business logic, zero network.
 
 ```ts
 import { createPartnerClient } from '@vivoa/partner-sdk';
 import { FakeVivoa, ManualClock } from '@vivoa/partner-sdk/testing';
 
-const clock = new ManualClock();
-const vivoa = new FakeVivoa({
+const clock  = new ManualClock();
+const fake   = new FakeVivoa({
   clock,
-  operators: [{ apiKey: 'k', apiSecret: 's', allowedRegions: ['SV'], maxStores: 3 }],
-  activation: 'slow',            // 'live' | 'slow' | 'fail' | 'drop'
-  onWebhook: (d) => deliveries.push(d),
+  operators:  [{ apiKey: 'k', apiSecret: 's', allowedRegions: ['SV'], maxStores: 3 }],
+  activation: 'slow',   // 'live' | 'slow' | 'fail' | 'drop'
+  onWebhook:  (d) => deliveries.push(d),
 });
-const client = createPartnerClient({ apiKey: 'k', apiSecret: 's', transport: vivoa, clock });
+const client = createPartnerClient({ apiKey: 'k', apiSecret: 's', transport: fake, clock });
 ```
 
-## Arquitectura
+The same contract suite runs against `FakeVivoa` and against production. If the fake drifts from the real server, the live run fails on the same assertion.
+
+---
+
+## Architecture
 
 ```
 src/
-  domain/        tipos, reglas de ciclo de vida, errores, payload canónico (puro)
+  domain/        types, lifecycle rules, errors (pure — no I/O)
   ports/         HttpTransport · CryptoProvider · Clock · SdkLogger
-  application/   SignedHttpClient · resources/ · use-cases/provision-store · VivoaPartnerClient
-  adapters/      fetch · node-crypto · system/manual clock · in-memory/FakeVivoa
+  application/   SignedHttpClient · resources/ · provision-store · VivoaPartnerClient
+  adapters/      fetch · node-crypto · system clock · ManualClock · FakeVivoa
   webhooks/      verifyWebhook
   index.ts       composition root (createPartnerClient)
   cli.ts         driving adapter (vivoa-partner)
 ```
 
-Dependencias permitidas: `domain` no importa nada; `application` importa solo `domain` y `ports`; `adapters` implementan `ports`.
-
-Para llevar el SDK a otro runtime basta con un adapter nuevo, por ejemplo WebCrypto para edge o un transporte con métricas. Cuando el backend sume endpoints, se agregan como recursos. En ningún caso hay que tocar el núcleo.
-
-## CLI
-
-```bash
-export VIVOA_PARTNER_KEY=… VIVOA_PARTNER_SECRET=…   # solo por env, nunca por flags
-node src/cli.ts me
-node src/cli.ts merchants list --search acme
-node src/cli.ts store create --external-id cus_1 --name Acme --email owner@acme.com --countries SV --yes
-```
-
-## Publicar
+`domain` imports nothing external. `application` imports only `domain` and `ports`. `adapters` implement `ports`. A new runtime needs only a new adapter — the core is untouched.
 
-```bash
-# subir "version" en package.json + CHANGELOG.md
-pnpm publish      # prepublishOnly: typecheck + test + build + test:dist
-```
+---
 
-O deja que lo haga CI: sube la versión, mergea a `main` y crea un **GitHub Release** (tag `vX.Y.Z` igual al `version` de `package.json`) — `.github/workflows/release.yml` corre el mismo gate y publica con el secreto `NPM_TOKEN` del repo.
+## Further reading
 
-## Desarrollo
+- [Partner program guide](https://github.com/VivoaPlatform/vivoa-platform/blob/main/docs/PARTNERS.md)
+- [Server contract](https://github.com/VivoaPlatform/vivoa-platform/blob/main/packages/backend/src/engine/partner-api/CONTRACT.md)
 
-Requiere Node ≥ 22.18, que ejecuta TypeScript de forma nativa. Los tests corren sin `pnpm install`.
+---
 
-```bash
-pnpm test         # unit + contrato contra FakeVivoa
-pnpm typecheck    # tsc (src + tests)
-pnpm build        # dist/esm + dist/cjs (+ .d.ts)
-pnpm test:dist    # smoke de los entry points publicados (require + import)
-
-# Mismo contrato contra la API real. Por defecto solo lee:
-VIVOA_LIVE=1 VIVOA_PARTNER_KEY=… VIVOA_PARTNER_SECRET=… pnpm test:live
-# Crea y activa UNA tienda sdk-e2e-<ts> (consume cupo e infraestructura real):
-VIVOA_LIVE=1 VIVOA_LIVE_WRITE=1 … pnpm test:live
-```
+## License
 
-La suite de contrato (`test/contract/partner-api.contract.ts`) es una sola y corre contra el fake y contra producción. Si el fake se aparta del servidor real, la corrida live falla en la misma aserción.
+Private — authorized Vivoa partners only.

package/dist/cjs/adapters/in-memory/fake-vivoa.js

@@ -271,10 +271,12 @@ class FakeVivoa {
         throw new HttpError(500, `Could not allocate a free handle for "${name}"`);
     }
     activate(op, m) {
-        if (m.runtime === 'creating' || m.runtime === 'live' || m.runtime === 'suspended') {
+        if (m.runtime === 'creating' || m.runtime === 'live' || m.runtime === 'suspended' || m.runtime === 'unknown') {
             throw new HttpError(409, m.runtime === 'suspended'
                 ? `Merchant '${m.handle}' is suspended — use reactivate instead`
-                : `Merchant '${m.handle}' is already ${m.runtime}`);
+                : m.runtime === 'unknown'
+                    ? `Merchant '${m.handle}' is in an unrecoverable state`
+                    : `Merchant '${m.handle}' is already ${m.runtime}`);
         }
         switch (this.activation) {
             case 'fail':

package/dist/cjs/application/partner-client.d.ts

@@ -10,7 +10,8 @@ import { type ProvisionStoreOptions, type ProvisionStoreResult } from './use-cas
 import { type VerifyWebhookParams } from '../webhooks/verify-webhook.ts';
 import type { CreateMerchantInput, MerchantStatus } from '../domain/merchant.ts';
 import type { WebhookEvent } from '../domain/webhook.ts';
-export declare const SDK_VERSION = "0.1.0";
+import { SDK_VERSION } from '../version.ts';
+export { SDK_VERSION };
 /** Every adapter is injected — the client itself has no I/O of its own. */
 export interface PartnerClientDeps {
     baseUrl: string;

package/dist/cjs/application/partner-client.js

@@ -9,7 +9,8 @@ const webhooks_ts_1 = require("./resources/webhooks.js");
 const fleet_ts_1 = require("./resources/fleet.js");
 const provision_store_ts_1 = require("./use-cases/provision-store.js");
 const verify_webhook_ts_1 = require("../webhooks/verify-webhook.js");
-exports.SDK_VERSION = '0.1.0';
+const version_ts_1 = require("../version.js");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return version_ts_1.SDK_VERSION; } });
 class VivoaPartnerClient {
     me;
     merchants;
@@ -28,7 +29,7 @@ class VivoaPartnerClient {
             logger: deps.logger ?? logger_port_ts_1.silentLogger,
             timeoutMs: deps.timeoutMs ?? 30_000,
             maxRetries: deps.maxRetries ?? 2,
-            userAgent: `vivoa-partner-sdk/${exports.SDK_VERSION}`,
+            userAgent: `vivoa-partner-sdk/${version_ts_1.SDK_VERSION}`,
         });
         this.crypto = deps.crypto;
         this.me = new me_ts_1.MeResource(http);

package/dist/cjs/application/resources/merchants.js

@@ -30,12 +30,13 @@ class MerchantsResource {
     /** Walks every page of the fleet. */
     async *listAll(query = {}) {
         const limit = query.limit ?? 100;
-        for (let page = 1;; page++) {
+        for (let page = 1; page <= 10_000; page++) {
             const res = await this.list({ ...query, page, limit });
             yield* res.data;
             if (res.data.length === 0 || page * limit >= res.meta.total)
                 return;
         }
+        throw new Error('listAll: exceeded maximum page limit (10 000)');
     }
     /** The merchant created with this reference, or `null` — an exact server-side match. */
     async findByExternalId(externalId) {

package/dist/cjs/application/use-cases/provision-store.js

@@ -46,8 +46,8 @@ class ProvisionStoreUseCase {
             });
         }
         progress('settled', merchant, status.deployStatus);
-        if (status.deployStatus === 'failed') {
-            throw new errors_ts_1.VivoaProvisioningFailedError(merchant.id, 'the platform reported runtime status "failed"');
+        if (status.deployStatus === 'failed' || status.deployStatus === 'unknown') {
+            throw new errors_ts_1.VivoaProvisioningFailedError(merchant.id, `the platform reported runtime status "${status.deployStatus}"`);
         }
         return { merchant: { ...merchant, runtime: status.deployStatus, domain: status.domain }, status, created };
     }

package/dist/cjs/domain/webhook.d.ts

@@ -5,7 +5,7 @@ export interface WebhookConfig {
     configured: boolean;
     url: string | null;
     /** [] = all merchant events. */
-    events: string[];
+    events: MerchantEventType[];
     active: boolean;
     updatedAt: string | null;
 }

package/dist/cjs/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.1.1";

package/dist/cjs/version.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+exports.SDK_VERSION = '0.1.1';

package/dist/esm/adapters/in-memory/fake-vivoa.js

@@ -268,10 +268,12 @@ export class FakeVivoa {
         throw new HttpError(500, `Could not allocate a free handle for "${name}"`);
     }
     activate(op, m) {
-        if (m.runtime === 'creating' || m.runtime === 'live' || m.runtime === 'suspended') {
+        if (m.runtime === 'creating' || m.runtime === 'live' || m.runtime === 'suspended' || m.runtime === 'unknown') {
             throw new HttpError(409, m.runtime === 'suspended'
                 ? `Merchant '${m.handle}' is suspended — use reactivate instead`
-                : `Merchant '${m.handle}' is already ${m.runtime}`);
+                : m.runtime === 'unknown'
+                    ? `Merchant '${m.handle}' is in an unrecoverable state`
+                    : `Merchant '${m.handle}' is already ${m.runtime}`);
         }
         switch (this.activation) {
             case 'fail':

package/dist/esm/application/partner-client.d.ts

@@ -10,7 +10,8 @@ import { type ProvisionStoreOptions, type ProvisionStoreResult } from './use-cas
 import { type VerifyWebhookParams } from '../webhooks/verify-webhook.ts';
 import type { CreateMerchantInput, MerchantStatus } from '../domain/merchant.ts';
 import type { WebhookEvent } from '../domain/webhook.ts';
-export declare const SDK_VERSION = "0.1.0";
+import { SDK_VERSION } from '../version.ts';
+export { SDK_VERSION };
 /** Every adapter is injected — the client itself has no I/O of its own. */
 export interface PartnerClientDeps {
     baseUrl: string;

package/dist/esm/application/partner-client.js

@@ -6,7 +6,8 @@ import { WebhooksResource } from "./resources/webhooks.js";
 import { FleetResource } from "./resources/fleet.js";
 import { ProvisionStoreUseCase, } from "./use-cases/provision-store.js";
 import { verifyWebhook } from "../webhooks/verify-webhook.js";
-export const SDK_VERSION = '0.1.0';
+import { SDK_VERSION } from "../version.js";
+export { SDK_VERSION };
 export class VivoaPartnerClient {
     me;
     merchants;

package/dist/esm/application/resources/merchants.js

@@ -26,12 +26,13 @@ export class MerchantsResource {
     /** Walks every page of the fleet. */
     async *listAll(query = {}) {
         const limit = query.limit ?? 100;
-        for (let page = 1;; page++) {
+        for (let page = 1; page <= 10_000; page++) {
             const res = await this.list({ ...query, page, limit });
             yield* res.data;
             if (res.data.length === 0 || page * limit >= res.meta.total)
                 return;
         }
+        throw new Error('listAll: exceeded maximum page limit (10 000)');
     }
     /** The merchant created with this reference, or `null` — an exact server-side match. */
     async findByExternalId(externalId) {

package/dist/esm/application/use-cases/provision-store.js

@@ -43,8 +43,8 @@ export class ProvisionStoreUseCase {
             });
         }
         progress('settled', merchant, status.deployStatus);
-        if (status.deployStatus === 'failed') {
-            throw new VivoaProvisioningFailedError(merchant.id, 'the platform reported runtime status "failed"');
+        if (status.deployStatus === 'failed' || status.deployStatus === 'unknown') {
+            throw new VivoaProvisioningFailedError(merchant.id, `the platform reported runtime status "${status.deployStatus}"`);
         }
         return { merchant: { ...merchant, runtime: status.deployStatus, domain: status.domain }, status, created };
     }

package/dist/esm/domain/webhook.d.ts

@@ -5,7 +5,7 @@ export interface WebhookConfig {
     configured: boolean;
     url: string | null;
     /** [] = all merchant events. */
-    events: string[];
+    events: MerchantEventType[];
     active: boolean;
     updatedAt: string | null;
 }

package/dist/esm/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.1.1";

package/dist/esm/version.js

@@ -0,0 +1 @@
+export const SDK_VERSION = '0.1.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vivoa/partner-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official SDK for the Vivoa Partner API — create and operate stores for your merchants",
   "license": "UNLICENSED",
   "type": "module",