@vivoa/partner-sdk 0.1.0

package/dist/esm/cli.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * vivoa-partner — thin driving adapter over the SDK. Credentials come ONLY from
+ * the environment (never flags, so they stay out of shell history):
+ *   VIVOA_PARTNER_KEY, VIVOA_PARTNER_SECRET, VIVOA_API_URL (default https://api.vivoa.app)
+ */
+import { parseArgs } from 'node:util';
+import { createPartnerClient, DEFAULT_BASE_URL } from "./index.js";
+import { VivoaError } from "./domain/errors.js";
+const USAGE = `vivoa-partner <command> [options]
+
+  me                                     Profile, plan and quota
+  merchants list [--search s] [--external-id id] [--page n] [--limit n]
+  merchants status <id>
+  merchants suspend <id> | reactivate <id>
+  store create --external-id id --name n --email e --countries SV,GT [--industry i] --yes
+                                         Create (or resume) + activate + wait until live.
+                                         The platform assigns the handle; --external-id is
+                                         your own reference and the retry-safety key.
+  fleet                                  Fleet analytics
+  webhook get | webhook set --url u [--events a,b] | webhook test | webhook deliveries
+
+Env: VIVOA_PARTNER_KEY, VIVOA_PARTNER_SECRET, VIVOA_API_URL (default ${DEFAULT_BASE_URL})`;
+async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            search: { type: 'string' },
+            'external-id': { type: 'string' },
+            page: { type: 'string' },
+            limit: { type: 'string' },
+            name: { type: 'string' },
+            email: { type: 'string' },
+            countries: { type: 'string' },
+            industry: { type: 'string' },
+            url: { type: 'string' },
+            events: { type: 'string' },
+            yes: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+    });
+    const [command, sub, arg] = positionals;
+    if (!command || values.help) {
+        console.log(USAGE);
+        return undefined;
+    }
+    const apiKey = process.env.VIVOA_PARTNER_KEY;
+    const apiSecret = process.env.VIVOA_PARTNER_SECRET;
+    if (!apiKey || !apiSecret)
+        throw new VivoaError('Set VIVOA_PARTNER_KEY and VIVOA_PARTNER_SECRET');
+    const client = createPartnerClient({ apiKey, apiSecret, baseUrl: process.env.VIVOA_API_URL || undefined });
+    const list = (v) => (v ? v.split(',').map((s) => s.trim()).filter(Boolean) : undefined);
+    switch (`${command} ${sub ?? ''}`.trim()) {
+        case 'me':
+            return client.me.get();
+        case 'fleet':
+            return client.fleet.analytics();
+        case 'merchants list':
+            return client.merchants.list({
+                search: values.search,
+                externalId: values['external-id'],
+                page: values.page ? Number(values.page) : undefined,
+                limit: values.limit ? Number(values.limit) : undefined,
+            });
+        case 'merchants status':
+            return client.merchants.status(required(arg, '<id>'));
+        case 'merchants suspend':
+            return client.merchants.suspend(required(arg, '<id>'));
+        case 'merchants reactivate':
+            return client.merchants.reactivate(required(arg, '<id>'));
+        case 'store create': {
+            if (!values.yes)
+                throw new VivoaError('store create provisions REAL infrastructure — re-run with --yes');
+            return client.provisionStore({
+                name: required(values.name, '--name'),
+                email: required(values.email, '--email'),
+                countries: list(required(values.countries, '--countries')) ?? [],
+                industry: values.industry,
+                externalId: required(values['external-id'], '--external-id'),
+            }, { onProgress: (p) => console.error(`· ${p.phase} ${p.handle} (${p.merchantId}) ${p.runtime ?? ''}`) });
+        }
+        case 'webhook get':
+            return client.webhooks.get();
+        case 'webhook set':
+            return client.webhooks.set({ url: required(values.url, '--url'), events: list(values.events) });
+        case 'webhook test':
+            return client.webhooks.test();
+        case 'webhook deliveries':
+            return client.webhooks.deliveries(values.limit ? Number(values.limit) : undefined);
+        default:
+            throw new VivoaError(`Unknown command "${positionals.join(' ')}"\n\n${USAGE}`);
+    }
+}
+function required(value, name) {
+    if (!value)
+        throw new VivoaError(`Missing ${name}`);
+    return value;
+}
+main(process.argv.slice(2)).then((result) => {
+    if (result !== undefined)
+        console.log(JSON.stringify(result, null, 2));
+}, (err) => {
+    console.error(`${err.name}: ${err.message}`);
+    process.exitCode = 1;
+});

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

@@ -0,0 +1,72 @@
+/**
+ * Typed error hierarchy. Every failed call surfaces as a `VivoaApiError`
+ * subclass keyed by HTTP status, so partners branch on `instanceof` instead of
+ * parsing strings.
+ */
+export declare class VivoaError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Input rejected client-side before any request is sent. */
+export declare class VivoaValidationError extends VivoaError {
+}
+/** The request never produced an HTTP response (DNS, reset, timeout). */
+export declare class VivoaNetworkError extends VivoaError {
+}
+/** A long-running wait (e.g. `waitUntilSettled`) ran out of time. */
+export declare class VivoaTimeoutError extends VivoaError {
+}
+export declare class VivoaApiError extends VivoaError {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly body: unknown;
+    constructor(params: {
+        status: number;
+        method: string;
+        path: string;
+        message: string;
+        body: unknown;
+    });
+}
+/** 400 — invalid payload or country outside allowedRegions. */
+export declare class VivoaBadRequestError extends VivoaApiError {
+}
+/** 401 — bad signature, unknown key or clock skew > 300 s. */
+export declare class VivoaAuthenticationError extends VivoaApiError {
+}
+/** 403 — operator not active or quota full. */
+export declare class VivoaForbiddenError extends VivoaApiError {
+}
+/** 404 — merchant does not exist or is not in your fleet. */
+export declare class VivoaNotFoundError extends VivoaApiError {
+}
+/** 409 — handle taken, or activation on a creating/live/suspended merchant. */
+export declare class VivoaConflictError extends VivoaApiError {
+}
+/** 429 — requests-per-minute limit for the plan. */
+export declare class VivoaRateLimitError extends VivoaApiError {
+}
+/** 5xx. */
+export declare class VivoaServerError extends VivoaApiError {
+}
+/** Extracts NestJS's `{ message }` (string or validation array) from a body. */
+export declare function messageFromBody(body: unknown, fallback: string): string;
+export declare function apiErrorFor(params: {
+    status: number;
+    method: string;
+    path: string;
+    body: unknown;
+}): VivoaApiError;
+/** Provisioning ended in `failed`. `activate` again (or `provisionStore`) to retry. */
+export declare class VivoaProvisioningFailedError extends VivoaError {
+    readonly merchantId: string;
+    readonly reason: string;
+    constructor(merchantId: string, reason: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A webhook body whose `X-Vivoa-Signature` does not verify. Reject it (401/400). */
+export declare class VivoaWebhookSignatureError extends VivoaError {
+}

package/dist/esm/domain/errors.js

@@ -0,0 +1,92 @@
+/**
+ * Typed error hierarchy. Every failed call surfaces as a `VivoaApiError`
+ * subclass keyed by HTTP status, so partners branch on `instanceof` instead of
+ * parsing strings.
+ */
+export class VivoaError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/** Input rejected client-side before any request is sent. */
+export class VivoaValidationError extends VivoaError {
+}
+/** The request never produced an HTTP response (DNS, reset, timeout). */
+export class VivoaNetworkError extends VivoaError {
+}
+/** A long-running wait (e.g. `waitUntilSettled`) ran out of time. */
+export class VivoaTimeoutError extends VivoaError {
+}
+export class VivoaApiError extends VivoaError {
+    status;
+    method;
+    path;
+    body;
+    constructor(params) {
+        super(`${params.method} ${params.path} → ${params.status}: ${params.message}`);
+        this.status = params.status;
+        this.method = params.method;
+        this.path = params.path;
+        this.body = params.body;
+    }
+}
+/** 400 — invalid payload or country outside allowedRegions. */
+export class VivoaBadRequestError extends VivoaApiError {
+}
+/** 401 — bad signature, unknown key or clock skew > 300 s. */
+export class VivoaAuthenticationError extends VivoaApiError {
+}
+/** 403 — operator not active or quota full. */
+export class VivoaForbiddenError extends VivoaApiError {
+}
+/** 404 — merchant does not exist or is not in your fleet. */
+export class VivoaNotFoundError extends VivoaApiError {
+}
+/** 409 — handle taken, or activation on a creating/live/suspended merchant. */
+export class VivoaConflictError extends VivoaApiError {
+}
+/** 429 — requests-per-minute limit for the plan. */
+export class VivoaRateLimitError extends VivoaApiError {
+}
+/** 5xx. */
+export class VivoaServerError extends VivoaApiError {
+}
+const BY_STATUS = {
+    400: VivoaBadRequestError,
+    401: VivoaAuthenticationError,
+    403: VivoaForbiddenError,
+    404: VivoaNotFoundError,
+    409: VivoaConflictError,
+    429: VivoaRateLimitError,
+};
+/** Extracts NestJS's `{ message }` (string or validation array) from a body. */
+export function messageFromBody(body, fallback) {
+    if (body && typeof body === 'object' && 'message' in body) {
+        const m = body.message;
+        if (Array.isArray(m))
+            return m.join('; ');
+        if (typeof m === 'string')
+            return m;
+    }
+    if (typeof body === 'string' && body.length > 0)
+        return body;
+    return fallback;
+}
+export function apiErrorFor(params) {
+    const Ctor = BY_STATUS[params.status] ?? (params.status >= 500 ? VivoaServerError : VivoaApiError);
+    return new Ctor({ ...params, message: messageFromBody(params.body, `HTTP ${params.status}`) });
+}
+/** Provisioning ended in `failed`. `activate` again (or `provisionStore`) to retry. */
+export class VivoaProvisioningFailedError extends VivoaError {
+    merchantId;
+    reason;
+    constructor(merchantId, reason, options) {
+        super(`Provisioning failed for merchant ${merchantId}: ${reason}`, options);
+        this.merchantId = merchantId;
+        this.reason = reason;
+    }
+}
+/** A webhook body whose `X-Vivoa-Signature` does not verify. Reject it (401/400). */
+export class VivoaWebhookSignatureError extends VivoaError {
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Merchant vocabulary — mirrors `engine/partner-api/domain/merchant-views.ts`
+ * on the platform. A partner speaks in merchants, never in stores/deployments.
+ * Pure: no I/O, no Node APIs.
+ */
+export declare const MERCHANT_RUNTIME_STATUSES: readonly ["not_activated", "creating", "live", "suspended", "failed", "unknown"];
+/** Where a merchant's runtime is, from the partner's point of view. */
+export type MerchantRuntimeStatus = (typeof MERCHANT_RUNTIME_STATUSES)[number];
+/** A merchant as returned by `POST /merchants` and `GET /merchants`. */
+export interface Merchant {
+    id: string;
+    name: string;
+    /** Assigned by the platform from `name` — never chosen by the caller. */
+    handle: string;
+    /** Commercial status (active | suspended | …). */
+    status: string;
+    runtime: MerchantRuntimeStatus;
+    countries: string[];
+    plan: string;
+    domain: string | null;
+    ownerEmail: string | null;
+    /** Your own reference for this merchant, if you gave one at creation. */
+    externalId: string | null;
+    /** ISO-8601. */
+    createdAt: string;
+}
+/** Snapshot returned by `GET /merchants/:id/status` and `activate`. */
+export interface MerchantStatus {
+    storeId: string;
+    handle: string;
+    status: string;
+    deployStatus: MerchantRuntimeStatus;
+    domain: string | null;
+    apiBaseUrl: string | null;
+}
+export interface CreateMerchantInput {
+    /** Email of the store owner (receives their own merchant account). */
+    email: string;
+    name: string;
+    /** ISO-3166 codes; must be a subset of the operator's allowedRegions. */
+    countries: string[];
+    industry?: string;
+    /**
+     * Your own reference for this merchant (customer id, order id…). Optional
+     * here, but it is the idempotency key of `merchants.create()`: replaying the
+     * same value returns the merchant you already created instead of a second
+     * one. `provisionStore()` requires it for exactly that reason. Unique per
+     * operator, max 120 chars.
+     */
+    externalId?: string;
+}
+export interface ListMerchantsQuery {
+    page?: number;
+    /** Max 100. */
+    limit?: number;
+    /** Matches name or handle. */
+    search?: string;
+    /** Exact match on your own reference, passed at creation. */
+    externalId?: string;
+}
+export interface Page<T> {
+    data: T[];
+    meta: {
+        total: number;
+        page: number;
+        limit: number;
+    };
+}
+/** Max length the platform accepts for `CreateMerchantInput.externalId`. */
+export declare const MAX_EXTERNAL_ID_LENGTH = 120;
+/** Runtime states where the platform accepts `activate` (first run or retry). */
+export declare function canActivate(runtime: MerchantRuntimeStatus): boolean;
+/** States that will not change without a new action from the partner. */
+export declare function isSettled(runtime: MerchantRuntimeStatus): boolean;

package/dist/esm/domain/merchant.js

@@ -0,0 +1,23 @@
+/**
+ * Merchant vocabulary — mirrors `engine/partner-api/domain/merchant-views.ts`
+ * on the platform. A partner speaks in merchants, never in stores/deployments.
+ * Pure: no I/O, no Node APIs.
+ */
+export const MERCHANT_RUNTIME_STATUSES = [
+    'not_activated', // created, `activate` never called
+    'creating', // provisioning in flight
+    'live', // serving traffic
+    'suspended', // stopped by the operator / ops
+    'failed', // last provisioning attempt failed — `activate` again to retry
+    'unknown', // torn down / unexpected state
+];
+/** Max length the platform accepts for `CreateMerchantInput.externalId`. */
+export const MAX_EXTERNAL_ID_LENGTH = 120;
+/** Runtime states where the platform accepts `activate` (first run or retry). */
+export function canActivate(runtime) {
+    return runtime === 'not_activated' || runtime === 'failed';
+}
+/** States that will not change without a new action from the partner. */
+export function isSettled(runtime) {
+    return runtime !== 'creating';
+}

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

@@ -0,0 +1,32 @@
+export type OperatorStatus = 'active' | 'pending' | 'suspended';
+/** `GET /me` — the partner's own profile and quota usage. */
+export interface OperatorProfile {
+    id: string;
+    name: string;
+    status: OperatorStatus;
+    plan: string;
+    storesUsed: number;
+    maxStores: number;
+    allowedRegions: string[];
+    rateLimitPerMin: number;
+}
+export interface RotatedApiSecret {
+    apiSecret: string;
+}
+export interface FleetAnalytics {
+    operatorId: string;
+    stores: {
+        total: number;
+        active: number;
+        suspended: number;
+        byStatus: Record<string, number>;
+    };
+    revenue: {
+        grossVolume: number;
+        currency: string;
+        pendingAmount: number;
+        completedPayments: number;
+        avgTicket: number;
+    };
+}
+export declare function remainingQuota(profile: OperatorProfile): number;

package/dist/esm/domain/operator.js

@@ -0,0 +1,3 @@
+export function remainingQuota(profile) {
+    return Math.max(0, profile.maxStores - profile.storesUsed);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Canonical request payload signed with the operator's apiSecret. Must match
+ * the platform verifier (`shared/crypto/management-hmac.ts`, v2 strict):
+ *
+ *   `${timestamp}.${METHOD}.${pathWithoutQuery}.${sha256hex(rawBody)}`
+ */
+export declare function canonicalRequestPayload(params: {
+    timestamp: string;
+    method: string;
+    path: string;
+    bodySha256Hex: string;
+}): string;
+export declare const PARTNER_HEADERS: {
+    readonly key: "x-partner-key";
+    readonly timestamp: "x-partner-timestamp";
+    readonly signature: "x-partner-signature";
+};
+export declare const WEBHOOK_SIGNATURE_HEADER = "x-vivoa-signature";
+export declare const WEBHOOK_EVENT_HEADER = "x-vivoa-event";
+/** Server accepts ±300 s of clock skew. */
+export declare const MAX_CLOCK_SKEW_SECONDS = 300;

package/dist/esm/domain/signature.js

@@ -0,0 +1,19 @@
+/**
+ * Canonical request payload signed with the operator's apiSecret. Must match
+ * the platform verifier (`shared/crypto/management-hmac.ts`, v2 strict):
+ *
+ *   `${timestamp}.${METHOD}.${pathWithoutQuery}.${sha256hex(rawBody)}`
+ */
+export function canonicalRequestPayload(params) {
+    const path = params.path.split('?')[0];
+    return `${params.timestamp}.${params.method.toUpperCase()}.${path}.${params.bodySha256Hex}`;
+}
+export const PARTNER_HEADERS = {
+    key: 'x-partner-key',
+    timestamp: 'x-partner-timestamp',
+    signature: 'x-partner-signature',
+};
+export const WEBHOOK_SIGNATURE_HEADER = 'x-vivoa-signature';
+export const WEBHOOK_EVENT_HEADER = 'x-vivoa-event';
+/** Server accepts ±300 s of clock skew. */
+export const MAX_CLOCK_SKEW_SECONDS = 300;

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

@@ -0,0 +1,48 @@
+export declare const MERCHANT_EVENT_TYPES: readonly ["merchant.created", "merchant.live", "merchant.failed", "merchant.suspended", "merchant.reactivated"];
+export type MerchantEventType = (typeof MERCHANT_EVENT_TYPES)[number];
+export type WebhookEventType = MerchantEventType | 'platform.test';
+export interface WebhookConfig {
+    configured: boolean;
+    url: string | null;
+    /** [] = all merchant events. */
+    events: string[];
+    active: boolean;
+    updatedAt: string | null;
+}
+export interface SetWebhookInput {
+    url: string;
+    /** Omit or [] to receive every merchant event. */
+    events?: MerchantEventType[];
+}
+export interface SetWebhookResult {
+    webhook: WebhookConfig;
+    /** Only on first creation. Store it — it is never readable again. */
+    signingSecret: string | null;
+}
+export interface WebhookDelivery {
+    id: string;
+    event: string;
+    statusCode: number | null;
+    success: boolean;
+    error: string | null;
+    durationMs: number | null;
+    attempt: number;
+    createdAt: string;
+}
+export interface MerchantEventData {
+    merchantId: string;
+    handle: string;
+    operatorId: string;
+    occurredAt: string;
+    /** Present on `merchant.failed`. */
+    reason?: string;
+    /** Present on `merchant.created` when the create call gave one. */
+    externalId?: string | null;
+    [key: string]: unknown;
+}
+/** Body POSTed to the partner's endpoint. */
+export interface WebhookEvent<T extends WebhookEventType = WebhookEventType> {
+    event: T;
+    data: T extends MerchantEventType ? MerchantEventData : Record<string, unknown>;
+    sentAt: string;
+}

package/dist/esm/domain/webhook.js

@@ -0,0 +1,7 @@
+export const MERCHANT_EVENT_TYPES = [
+    'merchant.created',
+    'merchant.live',
+    'merchant.failed',
+    'merchant.suspended',
+    'merchant.reactivated',
+];

package/dist/esm/index.d.ts

@@ -0,0 +1,25 @@
+import { VivoaPartnerClient, type PartnerClientDeps } from './application/partner-client.ts';
+import { type VerifyWebhookParams } from './webhooks/verify-webhook.ts';
+import type { WebhookEvent } from './domain/webhook.ts';
+export declare const DEFAULT_BASE_URL = "https://api.vivoa.app";
+export type CreatePartnerClientOptions = Omit<PartnerClientDeps, 'baseUrl' | 'transport' | 'crypto' | 'clock'> & Partial<Pick<PartnerClientDeps, 'baseUrl' | 'transport' | 'crypto' | 'clock'>>;
+/**
+ * Composition root with production adapters (global fetch, node:crypto, wall
+ * clock). Any of them can be overridden — e.g. `transport: new FakeVivoa()`.
+ */
+export declare function createPartnerClient(options: CreatePartnerClientOptions): VivoaPartnerClient;
+/** Standalone webhook verification (no client needed in your webhook handler). */
+export declare function verifyWebhook(params: VerifyWebhookParams): Promise<WebhookEvent>;
+export { VivoaPartnerClient, SDK_VERSION } from './application/partner-client.ts';
+export type { PartnerClientDeps } from './application/partner-client.ts';
+export type { ProvisionStoreOptions, ProvisionStoreResult, ProvisionProgress, ProvisionPhase, } from './application/use-cases/provision-store.ts';
+export type { VerifyWebhookParams } from './webhooks/verify-webhook.ts';
+export * from './domain/errors.ts';
+export * from './domain/merchant.ts';
+export * from './domain/operator.ts';
+export * from './domain/webhook.ts';
+export { canonicalRequestPayload, PARTNER_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER } from './domain/signature.ts';
+export * from './ports/index.ts';
+export { FetchTransport } from './adapters/fetch-transport.ts';
+export { nodeCrypto } from './adapters/node-crypto.ts';
+export { systemClock } from './adapters/system-clock.ts';

package/dist/esm/index.js

@@ -0,0 +1,33 @@
+import { VivoaPartnerClient } from "./application/partner-client.js";
+import { FetchTransport } from "./adapters/fetch-transport.js";
+import { nodeCrypto } from "./adapters/node-crypto.js";
+import { systemClock } from "./adapters/system-clock.js";
+import { verifyWebhook as verifyWithCrypto } from "./webhooks/verify-webhook.js";
+export const DEFAULT_BASE_URL = 'https://api.vivoa.app';
+/**
+ * Composition root with production adapters (global fetch, node:crypto, wall
+ * clock). Any of them can be overridden — e.g. `transport: new FakeVivoa()`.
+ */
+export function createPartnerClient(options) {
+    return new VivoaPartnerClient({
+        ...options,
+        baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+        transport: options.transport ?? new FetchTransport(),
+        crypto: options.crypto ?? nodeCrypto,
+        clock: options.clock ?? systemClock,
+    });
+}
+/** Standalone webhook verification (no client needed in your webhook handler). */
+export function verifyWebhook(params) {
+    return verifyWithCrypto(nodeCrypto, params);
+}
+export { VivoaPartnerClient, SDK_VERSION } from "./application/partner-client.js";
+export * from "./domain/errors.js";
+export * from "./domain/merchant.js";
+export * from "./domain/operator.js";
+export * from "./domain/webhook.js";
+export { canonicalRequestPayload, PARTNER_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER } from "./domain/signature.js";
+export * from "./ports/index.js";
+export { FetchTransport } from "./adapters/fetch-transport.js";
+export { nodeCrypto } from "./adapters/node-crypto.js";
+export { systemClock } from "./adapters/system-clock.js";

package/dist/esm/ports/clock.port.d.ts

@@ -0,0 +1,5 @@
+/** Driven port: time. Tests inject a manual clock to make polling instant. */
+export interface Clock {
+    nowMs(): number;
+    sleep(ms: number): Promise<void>;
+}

package/dist/esm/ports/clock.port.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/ports/crypto.port.d.ts

@@ -0,0 +1,7 @@
+/** Driven port: the three primitives the SDK needs. Node, WebCrypto or HSM. */
+export interface CryptoProvider {
+    sha256Hex(data: string): string | Promise<string>;
+    hmacSha256Hex(secret: string, data: string): string | Promise<string>;
+    /** Constant-time comparison of two hex strings. */
+    timingSafeEqualHex(a: string, b: string): boolean | Promise<boolean>;
+}

package/dist/esm/ports/crypto.port.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/ports/http-transport.port.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Driven port: moves one already-signed request over the wire. The SDK core
+ * never touches `fetch` — swap in undici, axios, a recording proxy, or the
+ * in-memory fake Vivoa (`@vivoa/partner-sdk/testing`) without changing a line
+ * of application code.
+ */
+export interface HttpRequest {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Absolute URL. */
+    url: string;
+    headers: Record<string, string>;
+    /** Exact bytes that were signed; undefined for bodyless requests. */
+    body?: string;
+    /** Per-request timeout in ms. */
+    timeoutMs: number;
+}
+export interface HttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    /** Raw text; the core parses JSON. */
+    body: string;
+}
+export interface HttpTransport {
+    send(request: HttpRequest): Promise<HttpResponse>;
+}

package/dist/esm/ports/http-transport.port.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/ports/index.d.ts

@@ -0,0 +1,5 @@
+export type { HttpTransport, HttpRequest, HttpResponse } from './http-transport.port.ts';
+export type { CryptoProvider } from './crypto.port.ts';
+export type { Clock } from './clock.port.ts';
+export type { SdkLogger } from './logger.port.ts';
+export { silentLogger } from './logger.port.ts';

package/dist/esm/ports/index.js

@@ -0,0 +1 @@
+export { silentLogger } from "./logger.port.js";

package/dist/esm/ports/logger.port.d.ts

@@ -0,0 +1,6 @@
+/** Optional observability hook. Never receives secrets or signatures. */
+export interface SdkLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+}
+export declare const silentLogger: SdkLogger;

package/dist/esm/ports/logger.port.js

@@ -0,0 +1,4 @@
+export const silentLogger = {
+    debug: () => { },
+    warn: () => { },
+};

package/dist/esm/testing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@vivoa/partner-sdk/testing` — test your integration without touching the
+ * platform: plug `FakeVivoa` in as the transport and a `ManualClock` so polling
+ * and backoff run instantly.
+ *
+ *   const clock = new ManualClock();
+ *   const vivoa = new FakeVivoa({ clock, operators: [{ apiKey: 'k', apiSecret: 's' }] });
+ *   const client = createPartnerClient({ apiKey: 'k', apiSecret: 's', transport: vivoa, clock });
+ */
+export { FakeVivoa } from './adapters/in-memory/fake-vivoa.ts';
+export type { FakeVivoaOptions, FakeOperatorSeed, FakeActivationMode, FakeWebhookDispatch, } from './adapters/in-memory/fake-vivoa.ts';
+export { ManualClock } from './adapters/manual-clock.ts';