@vivoa/partner-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+Primera versión.
+
+- `createPartnerClient()` con recursos `me`, `merchants`, `webhooks` y `fleet`, que cubren la Partner API `/partner/v1`.
+- `provisionStore()`: crea la tienda, la activa y espera a que esté en vivo. Es idempotente por `externalId` (tu propia referencia) — la plataforma asigna el `handle`, así que nunca es algo que el socio elige o que puede chocar.
+- `verifyWebhook()` para `X-Vivoa-Signature`, con ventana contra reenvíos.
+- Errores tipados por código HTTP. Solo se reintentan los `GET`.
+- `@vivoa/partner-sdk/testing`: `FakeVivoa` y `ManualClock`.
+- CLI `vivoa-partner`.
+- Salida dual ESM + CommonJS.

package/README.md

@@ -0,0 +1,162 @@
+# @vivoa/partner-sdk
+
+```bash
+pnpm add @vivoa/partner-sdk      # o npm i / yarn add
+```
+
+SDK oficial de la **Partner API de Vivoa**, para crear y operar tiendas de tus comercios desde tu backend.
+
+- **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.
+
+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).
+
+## Quickstart
+
+```ts
+import { createPartnerClient } from '@vivoa/partner-sdk';
+
+const vivoa = createPartnerClient({
+  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
+
+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
+```
+
+`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.
+
+`provisionStore` hace lo siguiente:
+
+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.
+
+## Superficie
+
+| Recurso | Métodos |
+|---|---|
+| `me` | `get()`, `rotateSecret()` (el cliente pasa a usar el secreto nuevo de inmediato) |
+| `merchants` | `create`, `list`, `listAll()` (iterador async), `findByExternalId`, `status`, `activate`, `suspend`, `reactivate` |
+| `webhooks` | `get`, `set`, `remove`, `rotateSecret`, `test`, `deliveries` |
+| `fleet` | `analytics()` |
+| cliente | `provisionStore`, `waitUntilSettled`, `verifyWebhook` |
+
+## Errores
+
+Todos los errores extienden `VivoaError`. Los errores HTTP son `VivoaApiError` e incluyen `status`, `method`, `path` y `body`.
+
+| Clase | Cuándo |
+|---|---|
+| `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 |
+
+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.
+
+## Webhooks
+
+```ts
+import express from 'express';
+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
+      signatureHeader: req.header('x-vivoa-signature'),
+      signingSecret: process.env.VIVOA_WEBHOOK_SECRET!,
+    });
+    res.sendStatus(204);                                   // responder rápido
+    queue.push(event);                                     // procesar en segundo plano
+  } catch (err) {
+    res.sendStatus(err instanceof VivoaWebhookSignatureError ? 401 : 500);
+  }
+});
+```
+
+## Testing sin tocar Vivoa
+
+```ts
+import { createPartnerClient } from '@vivoa/partner-sdk';
+import { FakeVivoa, ManualClock } from '@vivoa/partner-sdk/testing';
+
+const clock = new ManualClock();
+const vivoa = new FakeVivoa({
+  clock,
+  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 });
+```
+
+## Arquitectura
+
+```
+src/
+  domain/        tipos, reglas de ciclo de vida, errores, payload canónico (puro)
+  ports/         HttpTransport · CryptoProvider · Clock · SdkLogger
+  application/   SignedHttpClient · resources/ · use-cases/provision-store · VivoaPartnerClient
+  adapters/      fetch · node-crypto · system/manual clock · in-memory/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
+
+```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.
+
+## Desarrollo
+
+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
+```
+
+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.

package/dist/cjs/adapters/fetch-transport.d.ts

@@ -0,0 +1,7 @@
+import type { HttpRequest, HttpResponse, HttpTransport } from '../ports/http-transport.port.ts';
+/** Default transport: the runtime's global `fetch` (Node ≥ 18, Deno, Bun, edge). */
+export declare class FetchTransport implements HttpTransport {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: typeof fetch);
+    send(request: HttpRequest): Promise<HttpResponse>;
+}

package/dist/cjs/adapters/fetch-transport.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FetchTransport = void 0;
+const errors_ts_1 = require("../domain/errors.js");
+/** Default transport: the runtime's global `fetch` (Node ≥ 18, Deno, Bun, edge). */
+class FetchTransport {
+    fetchImpl;
+    constructor(fetchImpl = globalThis.fetch) {
+        if (!fetchImpl)
+            throw new Error('FetchTransport: no global fetch available — pass one explicitly');
+        this.fetchImpl = fetchImpl;
+    }
+    async send(request) {
+        let res;
+        try {
+            res = await this.fetchImpl(request.url, {
+                method: request.method,
+                headers: request.headers,
+                body: request.body,
+                signal: AbortSignal.timeout(request.timeoutMs),
+            });
+        }
+        catch (err) {
+            const reason = err.name === 'TimeoutError' ? `timed out after ${request.timeoutMs} ms` : err.message;
+            throw new errors_ts_1.VivoaNetworkError(`${request.method} ${request.url}: ${reason}`, { cause: err });
+        }
+        const headers = {};
+        res.headers.forEach((value, key) => {
+            headers[key.toLowerCase()] = value;
+        });
+        return { status: res.status, headers, body: await res.text() };
+    }
+}
+exports.FetchTransport = FetchTransport;

package/dist/cjs/adapters/in-memory/fake-vivoa.d.ts

@@ -0,0 +1,93 @@
+import type { HttpRequest, HttpResponse, HttpTransport } from '../../ports/http-transport.port.ts';
+import type { CryptoProvider } from '../../ports/crypto.port.ts';
+import type { Clock } from '../../ports/clock.port.ts';
+import { type MerchantRuntimeStatus } from '../../domain/merchant.ts';
+import type { OperatorProfile, OperatorStatus } from '../../domain/operator.ts';
+/**
+ * How `POST /activate` behaves:
+ * - `live`: provisions synchronously and returns live (the platform's happy path).
+ * - `slow`: returns `creating`; stays creating for `pollsUntilLive` status reads.
+ * - `fail`: responds 500 and leaves the merchant `failed` (retry allowed).
+ * - `drop`: the connection drops (network error) but provisioning continues → live.
+ */
+export type FakeActivationMode = 'live' | 'slow' | 'fail' | 'drop';
+export interface FakeOperatorSeed {
+    apiKey: string;
+    apiSecret: string;
+    name?: string;
+    status?: OperatorStatus;
+    plan?: string;
+    maxStores?: number;
+    allowedRegions?: string[];
+    rateLimitPerMin?: number;
+}
+export interface FakeWebhookDispatch {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface FakeVivoaOptions {
+    operators?: FakeOperatorSeed[];
+    /**
+     * Handles already in use platform-wide — seed this to force the auto-assigned
+     * handle to fall back to its `-xxxx` suffixed form, the same way a real
+     * collision would. A partner never sends a handle (the platform always
+     * assigns one), so this can no longer produce a 409 on create.
+     */
+    takenHandles?: string[];
+    activation?: FakeActivationMode;
+    pollsUntilLive?: number;
+    failureReason?: string;
+    clock?: Clock;
+    crypto?: CryptoProvider;
+    /** Receives every signed webhook the fake "delivers". */
+    onWebhook?: (dispatch: FakeWebhookDispatch) => void;
+}
+/**
+ * In-memory Vivoa Partner API behind the `HttpTransport` port. It verifies the
+ * real HMAC signature and enforces the same rules as the platform
+ * (`engine/partner-api`): quota, allowed countries, unique handle, active-only
+ * writes, fleet scoping, activation state machine and per-minute rate limit.
+ * The shared contract suite (`test/contract`) runs against this fake AND the
+ * live API, so the two cannot silently drift.
+ */
+export declare class FakeVivoa implements HttpTransport {
+    readonly clock: Clock;
+    activation: FakeActivationMode;
+    pollsUntilLive: number;
+    failureReason: string;
+    private readonly crypto;
+    private readonly onWebhook?;
+    private readonly operators;
+    private readonly merchants;
+    private readonly handles;
+    constructor(options?: FakeVivoaOptions);
+    addOperator(seed: FakeOperatorSeed): OperatorProfile;
+    setOperatorStatus(apiKey: string, status: OperatorStatus): void;
+    /** Test helper: flip a merchant's runtime (e.g. simulate ops tearing it down). */
+    setRuntime(merchantId: string, runtime: MerchantRuntimeStatus): void;
+    send(req: HttpRequest): Promise<HttpResponse>;
+    private authenticate;
+    private rateLimit;
+    private requireActive;
+    private route;
+    private create;
+    /**
+     * Mirrors `StoreService.allocateHandle`: the readable slug of `name` first,
+     * a random `-xxxx` suffix if it (or a seeded `takenHandles` entry) is
+     * already used. The platform assigns this — a partner never sends one.
+     */
+    private allocateHandle;
+    private activate;
+    private goLive;
+    private statusView;
+    private list;
+    private analytics;
+    private webhookRoute;
+    private emit;
+    private deliver;
+    private fleet;
+    private owned;
+    private profile;
+    private requireOperatorByKey;
+}