@vivoa/partner-sdk 0.1.0

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

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeResource = void 0;
+class MeResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Plan, quota usage (`storesUsed/maxStores`), allowed countries, rate limit. */
+    get() {
+        return this.http.request('GET', '/partner/v1/me');
+    }
+    /**
+     * Rotates the apiSecret. The new secret is returned ONCE and this client
+     * switches to it immediately; persist it before the process exits.
+     */
+    async rotateSecret() {
+        const rotated = await this.http.request('POST', '/partner/v1/me/rotate-secret');
+        this.http.setApiSecret(rotated.apiSecret);
+        return rotated;
+    }
+}
+exports.MeResource = MeResource;

package/dist/cjs/application/resources/merchants.d.ts

@@ -0,0 +1,37 @@
+import type { SignedHttpClient } from '../signed-http.ts';
+import { type CreateMerchantInput, type ListMerchantsQuery, type Merchant, type MerchantStatus, type Page } from '../../domain/merchant.ts';
+/** Provisioning is synchronous on the platform: allow it minutes, not seconds. */
+export declare const DEFAULT_ACTIVATE_TIMEOUT_MS: number;
+export declare class MerchantsResource {
+    private readonly http;
+    constructor(http: SignedHttpClient);
+    /**
+     * Creates owner + store in your fleet. Not live until `activate`. The
+     * platform assigns the handle. Pass `externalId` and replaying the same
+     * value returns the merchant you already created — never a second one.
+     */
+    create(input: CreateMerchantInput): Promise<Merchant>;
+    list(query?: ListMerchantsQuery): Promise<Page<Merchant>>;
+    /** Walks every page of the fleet. */
+    listAll(query?: Omit<ListMerchantsQuery, 'page'>): AsyncGenerator<Merchant>;
+    /** The merchant created with this reference, or `null` — an exact server-side match. */
+    findByExternalId(externalId: string): Promise<Merchant | null>;
+    status(merchantId: string): Promise<MerchantStatus>;
+    /**
+     * Provisions the store and installs your default plugins. 409 if it is
+     * already creating/live/suspended; retry allowed after `failed`.
+     * Prefer `client.provisionStore()` which handles all of that.
+     */
+    activate(merchantId: string, options?: {
+        timeoutMs?: number;
+    }): Promise<MerchantStatus>;
+    suspend(merchantId: string): Promise<{
+        storeId: string;
+        status: 'suspended';
+    }>;
+    reactivate(merchantId: string): Promise<{
+        storeId: string;
+        status: 'active';
+    }>;
+}
+export declare function validateCreate(input: CreateMerchantInput): void;

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

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MerchantsResource = exports.DEFAULT_ACTIVATE_TIMEOUT_MS = void 0;
+exports.validateCreate = validateCreate;
+const errors_ts_1 = require("../../domain/errors.js");
+const merchant_ts_1 = require("../../domain/merchant.js");
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const COUNTRY_RE = /^[A-Z]{2}$/;
+/** Provisioning is synchronous on the platform: allow it minutes, not seconds. */
+exports.DEFAULT_ACTIVATE_TIMEOUT_MS = 10 * 60_000;
+class MerchantsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Creates owner + store in your fleet. Not live until `activate`. The
+     * platform assigns the handle. Pass `externalId` and replaying the same
+     * value returns the merchant you already created — never a second one.
+     */
+    async create(input) {
+        validateCreate(input);
+        return this.http.request('POST', '/partner/v1/merchants', { body: input });
+    }
+    list(query = {}) {
+        return this.http.request('GET', '/partner/v1/merchants', {
+            query: { page: query.page, limit: query.limit, search: query.search, externalId: query.externalId },
+        });
+    }
+    /** Walks every page of the fleet. */
+    async *listAll(query = {}) {
+        const limit = query.limit ?? 100;
+        for (let page = 1;; page++) {
+            const res = await this.list({ ...query, page, limit });
+            yield* res.data;
+            if (res.data.length === 0 || page * limit >= res.meta.total)
+                return;
+        }
+    }
+    /** The merchant created with this reference, or `null` — an exact server-side match. */
+    async findByExternalId(externalId) {
+        const page = await this.list({ limit: 1, externalId });
+        return page.data[0] ?? null;
+    }
+    async status(merchantId) {
+        return this.http.request('GET', `/partner/v1/merchants/${encodeId(merchantId)}/status`);
+    }
+    /**
+     * Provisions the store and installs your default plugins. 409 if it is
+     * already creating/live/suspended; retry allowed after `failed`.
+     * Prefer `client.provisionStore()` which handles all of that.
+     */
+    async activate(merchantId, options = {}) {
+        return this.http.request('POST', `/partner/v1/merchants/${encodeId(merchantId)}/activate`, {
+            timeoutMs: options.timeoutMs ?? exports.DEFAULT_ACTIVATE_TIMEOUT_MS,
+        });
+    }
+    async suspend(merchantId) {
+        return this.http.request('POST', `/partner/v1/merchants/${encodeId(merchantId)}/suspend`);
+    }
+    async reactivate(merchantId) {
+        return this.http.request('POST', `/partner/v1/merchants/${encodeId(merchantId)}/reactivate`);
+    }
+}
+exports.MerchantsResource = MerchantsResource;
+function encodeId(id) {
+    if (!id)
+        throw new errors_ts_1.VivoaValidationError('merchantId is required');
+    return encodeURIComponent(id);
+}
+function validateCreate(input) {
+    const problems = [];
+    if (!EMAIL_RE.test(input.email ?? ''))
+        problems.push('email must be a valid address');
+    if (!input.name?.trim())
+        problems.push('name is required');
+    if (!Array.isArray(input.countries) || input.countries.length === 0) {
+        problems.push('countries must contain at least one ISO-3166 code');
+    }
+    else if (input.countries.some((c) => !COUNTRY_RE.test(c))) {
+        problems.push('countries must be uppercase ISO-3166 alpha-2 codes (e.g. "SV")');
+    }
+    if (input.externalId !== undefined) {
+        if (!input.externalId.trim())
+            problems.push('externalId must not be empty');
+        else if (input.externalId.length > merchant_ts_1.MAX_EXTERNAL_ID_LENGTH) {
+            problems.push(`externalId must be at most ${merchant_ts_1.MAX_EXTERNAL_ID_LENGTH} chars`);
+        }
+    }
+    if (problems.length > 0)
+        throw new errors_ts_1.VivoaValidationError(problems.join('; '));
+}

package/dist/cjs/application/resources/webhooks.d.ts

@@ -0,0 +1,16 @@
+import type { SignedHttpClient } from '../signed-http.ts';
+import type { SetWebhookInput, SetWebhookResult, WebhookConfig, WebhookDelivery } from '../../domain/webhook.ts';
+export declare class WebhooksResource {
+    private readonly http;
+    constructor(http: SignedHttpClient);
+    get(): Promise<WebhookConfig>;
+    /** `signingSecret` comes back only when the endpoint is first created. */
+    set(input: SetWebhookInput): Promise<SetWebhookResult>;
+    remove(): Promise<WebhookConfig>;
+    rotateSecret(): Promise<{
+        signingSecret: string;
+    }>;
+    /** Sends a signed `platform.test` event to your endpoint now. */
+    test(): Promise<WebhookDelivery>;
+    deliveries(limit?: number): Promise<WebhookDelivery[]>;
+}

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

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhooksResource = void 0;
+class WebhooksResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    get() {
+        return this.http.request('GET', '/partner/v1/webhooks');
+    }
+    /** `signingSecret` comes back only when the endpoint is first created. */
+    set(input) {
+        return this.http.request('PUT', '/partner/v1/webhooks', { body: input });
+    }
+    remove() {
+        return this.http.request('DELETE', '/partner/v1/webhooks');
+    }
+    rotateSecret() {
+        return this.http.request('POST', '/partner/v1/webhooks/rotate-secret');
+    }
+    /** Sends a signed `platform.test` event to your endpoint now. */
+    test() {
+        return this.http.request('POST', '/partner/v1/webhooks/test');
+    }
+    deliveries(limit = 25) {
+        return this.http.request('GET', '/partner/v1/webhooks/deliveries', { query: { limit } });
+    }
+}
+exports.WebhooksResource = WebhooksResource;

package/dist/cjs/application/signed-http.d.ts

@@ -0,0 +1,41 @@
+import type { HttpRequest, 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 { SdkLogger } from '../ports/logger.port.ts';
+export type HttpMethod = HttpRequest['method'];
+export type QueryValue = string | number | boolean | undefined | null;
+export interface SignedHttpConfig {
+    /** Origin of the platform API, e.g. `https://api.vivoa.app` (no path). */
+    baseUrl: string;
+    apiKey: string;
+    apiSecret: string;
+    transport: HttpTransport;
+    crypto: CryptoProvider;
+    clock: Clock;
+    logger: SdkLogger;
+    /** Default per-request timeout. */
+    timeoutMs: number;
+    /** Retries for safe (GET) requests on 429 / 5xx / network errors. */
+    maxRetries: number;
+    userAgent: string;
+}
+export interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, QueryValue>;
+    timeoutMs?: number;
+}
+/**
+ * The only place that talks to the transport. Signs every attempt with a fresh
+ * timestamp over the EXACT bytes it sends, parses JSON and turns non-2xx into a
+ * typed `VivoaApiError`. Only GETs are retried: writes are not idempotent on
+ * the platform yet, so a retried POST could create a second merchant.
+ */
+export declare class SignedHttpClient {
+    private readonly config;
+    private apiSecret;
+    constructor(config: SignedHttpConfig);
+    /** Used after `me.rotateSecret()` — the old secret stops working immediately. */
+    setApiSecret(secret: string): void;
+    request<T>(method: HttpMethod, path: string, options?: RequestOptions): Promise<T>;
+    private sign;
+}

package/dist/cjs/application/signed-http.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignedHttpClient = void 0;
+const errors_ts_1 = require("../domain/errors.js");
+const signature_ts_1 = require("../domain/signature.js");
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_MAX_MS = 15_000;
+/**
+ * The only place that talks to the transport. Signs every attempt with a fresh
+ * timestamp over the EXACT bytes it sends, parses JSON and turns non-2xx into a
+ * typed `VivoaApiError`. Only GETs are retried: writes are not idempotent on
+ * the platform yet, so a retried POST could create a second merchant.
+ */
+class SignedHttpClient {
+    config;
+    apiSecret;
+    constructor(config) {
+        if (!config.apiKey)
+            throw new Error('apiKey is required');
+        if (!config.apiSecret)
+            throw new Error('apiSecret is required');
+        this.config = { ...config, baseUrl: config.baseUrl.replace(/\/+$/, '') };
+        this.apiSecret = config.apiSecret;
+    }
+    /** Used after `me.rotateSecret()` — the old secret stops working immediately. */
+    setApiSecret(secret) {
+        this.apiSecret = secret;
+    }
+    async request(method, path, options = {}) {
+        const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+        const url = this.config.baseUrl + path + queryString(options.query);
+        const timeoutMs = options.timeoutMs ?? this.config.timeoutMs;
+        const maxAttempts = method === 'GET' ? this.config.maxRetries + 1 : 1;
+        for (let attempt = 1;; attempt++) {
+            try {
+                const res = await this.config.transport.send(await this.sign({ method, url, path, body, timeoutMs }));
+                this.config.logger.debug('vivoa.request', { method, path, status: res.status, attempt });
+                if (res.status >= 200 && res.status < 300)
+                    return parseBody(res);
+                throw (0, errors_ts_1.apiErrorFor)({ status: res.status, method, path, body: parseBody(res) });
+            }
+            catch (err) {
+                if (attempt >= maxAttempts || !isRetryable(err))
+                    throw err;
+                const delay = backoffMs(attempt, err);
+                this.config.logger.warn('vivoa.retry', { method, path, attempt, delayMs: delay, reason: err.message });
+                await this.config.clock.sleep(delay);
+            }
+        }
+    }
+    async sign(params) {
+        const { crypto, clock, apiKey, userAgent } = this.config;
+        const timestamp = Math.floor(clock.nowMs() / 1000).toString();
+        const payload = (0, signature_ts_1.canonicalRequestPayload)({
+            timestamp,
+            method: params.method,
+            path: params.path,
+            bodySha256Hex: await crypto.sha256Hex(params.body ?? ''),
+        });
+        const headers = {
+            accept: 'application/json',
+            'user-agent': userAgent,
+            [signature_ts_1.PARTNER_HEADERS.key]: apiKey,
+            [signature_ts_1.PARTNER_HEADERS.timestamp]: timestamp,
+            [signature_ts_1.PARTNER_HEADERS.signature]: await crypto.hmacSha256Hex(this.apiSecret, payload),
+        };
+        if (params.body !== undefined)
+            headers['content-type'] = 'application/json';
+        return { method: params.method, url: params.url, headers, body: params.body, timeoutMs: params.timeoutMs };
+    }
+}
+exports.SignedHttpClient = SignedHttpClient;
+function queryString(query) {
+    if (!query)
+        return '';
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null && value !== '')
+            params.set(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+}
+function parseBody(res) {
+    if (!res.body)
+        return undefined;
+    try {
+        return JSON.parse(res.body);
+    }
+    catch {
+        return res.body;
+    }
+}
+function isRetryable(err) {
+    if (err instanceof errors_ts_1.VivoaNetworkError)
+        return true;
+    return err instanceof errors_ts_1.VivoaApiError && RETRYABLE_STATUS.has(err.status);
+}
+function backoffMs(attempt, err) {
+    const exp = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** (attempt - 1));
+    // Rate limits are per minute: waiting less than a few seconds just burns the next attempt.
+    const floor = err instanceof errors_ts_1.VivoaApiError && err.status === 429 ? 2_000 : 0;
+    return Math.max(floor, Math.round(exp / 2 + Math.random() * (exp / 2)));
+}

package/dist/cjs/application/use-cases/provision-store.d.ts

@@ -0,0 +1,50 @@
+import type { Clock } from '../../ports/clock.port.ts';
+import type { MerchantsResource } from '../resources/merchants.ts';
+import { type CreateMerchantInput, type Merchant, type MerchantRuntimeStatus, type MerchantStatus } from '../../domain/merchant.ts';
+export type ProvisionPhase = 'found' | 'created' | 'activating' | 'waiting' | 'settled';
+export interface ProvisionProgress {
+    phase: ProvisionPhase;
+    merchantId: string;
+    handle: string;
+    runtime?: MerchantRuntimeStatus;
+}
+export interface ProvisionStoreOptions {
+    /** Call `activate` (default true). `false` only ensures the merchant exists. */
+    activate?: boolean;
+    /** Wait for a settled runtime (live/failed/…) — default true. */
+    waitUntilLive?: boolean;
+    /** Overall budget for activation + waiting. Default 15 min. */
+    timeoutMs?: number;
+    /** Status poll cadence while `creating`. Default 5 s. */
+    pollIntervalMs?: number;
+    onProgress?: (progress: ProvisionProgress) => void;
+}
+export interface ProvisionStoreResult {
+    merchant: Merchant;
+    status: MerchantStatus;
+    /** false when a merchant with this externalId already existed in your fleet. */
+    created: boolean;
+}
+/**
+ * "Give me a live store" — the one call most partners need.
+ *
+ * Requires `input.externalId`: it is what makes retrying safe. Re-running
+ * after a crash, a timeout or a double click resumes the same merchant
+ * instead of creating a second one — the platform is idempotent on it (see
+ * `PARTNERS.md` §5.2), and it never runs out (unlike a handle, which the
+ * platform now assigns and a partner never sees before creation). Never
+ * retries a failed activation on its own.
+ */
+export declare class ProvisionStoreUseCase {
+    private readonly merchants;
+    private readonly clock;
+    constructor(merchants: MerchantsResource, clock: Clock);
+    execute(input: CreateMerchantInput, options?: ProvisionStoreOptions): Promise<ProvisionStoreResult>;
+    /** Polls `GET /status` until the runtime leaves `creating`. */
+    waitUntilSettled(merchantId: string, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<MerchantStatus>;
+    private ensureMerchant;
+    private activate;
+}

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

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProvisionStoreUseCase = void 0;
+const merchant_ts_1 = require("../../domain/merchant.js");
+const errors_ts_1 = require("../../domain/errors.js");
+const DEFAULT_TIMEOUT_MS = 15 * 60_000;
+const DEFAULT_POLL_MS = 5_000;
+/**
+ * "Give me a live store" — the one call most partners need.
+ *
+ * Requires `input.externalId`: it is what makes retrying safe. Re-running
+ * after a crash, a timeout or a double click resumes the same merchant
+ * instead of creating a second one — the platform is idempotent on it (see
+ * `PARTNERS.md` §5.2), and it never runs out (unlike a handle, which the
+ * platform now assigns and a partner never sees before creation). Never
+ * retries a failed activation on its own.
+ */
+class ProvisionStoreUseCase {
+    merchants;
+    clock;
+    constructor(merchants, clock) {
+        this.merchants = merchants;
+        this.clock = clock;
+    }
+    async execute(input, options = {}) {
+        if (!input.externalId?.trim()) {
+            throw new errors_ts_1.VivoaValidationError('provisionStore requires input.externalId — it is the key that makes retrying safe. ' +
+                'Use merchants.create() directly if you do not need that guarantee.');
+        }
+        const deadline = this.clock.nowMs() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        const progress = (phase, merchant, runtime) => options.onProgress?.({ phase, merchantId: merchant.id, handle: merchant.handle, runtime });
+        const { merchant, created } = await this.ensureMerchant(input);
+        progress(created ? 'created' : 'found', merchant, merchant.runtime);
+        let status = await this.merchants.status(merchant.id);
+        if (options.activate === false)
+            return { merchant, status, created };
+        if ((0, merchant_ts_1.canActivate)(status.deployStatus)) {
+            progress('activating', merchant, status.deployStatus);
+            status = await this.activate(merchant.id, deadline);
+        }
+        if (options.waitUntilLive !== false && !(0, merchant_ts_1.isSettled)(status.deployStatus)) {
+            progress('waiting', merchant, status.deployStatus);
+            status = await this.waitUntilSettled(merchant.id, {
+                timeoutMs: Math.max(0, deadline - this.clock.nowMs()),
+                pollIntervalMs: options.pollIntervalMs,
+            });
+        }
+        progress('settled', merchant, status.deployStatus);
+        if (status.deployStatus === 'failed') {
+            throw new errors_ts_1.VivoaProvisioningFailedError(merchant.id, 'the platform reported runtime status "failed"');
+        }
+        return { merchant: { ...merchant, runtime: status.deployStatus, domain: status.domain }, status, created };
+    }
+    /** Polls `GET /status` until the runtime leaves `creating`. */
+    async waitUntilSettled(merchantId, options = {}) {
+        const deadline = this.clock.nowMs() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        const interval = options.pollIntervalMs ?? DEFAULT_POLL_MS;
+        for (;;) {
+            const status = await this.merchants.status(merchantId);
+            if ((0, merchant_ts_1.isSettled)(status.deployStatus))
+                return status;
+            if (this.clock.nowMs() + interval > deadline) {
+                throw new errors_ts_1.VivoaTimeoutError(`Merchant ${merchantId} still "${status.deployStatus}" after the wait budget`);
+            }
+            await this.clock.sleep(interval);
+        }
+    }
+    async ensureMerchant(input) {
+        const existing = await this.merchants.findByExternalId(input.externalId);
+        if (existing)
+            return { merchant: existing, created: false };
+        // The platform is idempotent on externalId: even if a concurrent call for
+        // the same externalId wins the race between the check above and this
+        // request, `create` still resolves to ITS merchant — never a 409 or a
+        // second store. `created` can read `true` in that narrow window; harmless,
+        // since the merchant returned is the same either way.
+        return { merchant: await this.merchants.create(input), created: true };
+    }
+    async activate(merchantId, deadline) {
+        try {
+            return await this.merchants.activate(merchantId, {
+                timeoutMs: Math.max(1_000, deadline - this.clock.nowMs()),
+            });
+        }
+        catch (err) {
+            // 409: someone else already activated it. Network/timeout: the request may
+            // still be provisioning server-side. Either way, the status endpoint knows.
+            if (err instanceof errors_ts_1.VivoaConflictError || err instanceof errors_ts_1.VivoaNetworkError) {
+                return this.merchants.status(merchantId);
+            }
+            if (err instanceof errors_ts_1.VivoaServerError) {
+                const status = await this.merchants.status(merchantId).catch(() => null);
+                if (status?.deployStatus === 'failed') {
+                    throw new errors_ts_1.VivoaProvisioningFailedError(merchantId, err.message, { cause: err });
+                }
+                if (status && !(0, merchant_ts_1.canActivate)(status.deployStatus))
+                    return status;
+            }
+            throw err;
+        }
+    }
+}
+exports.ProvisionStoreUseCase = ProvisionStoreUseCase;

package/dist/cjs/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 {
+}