@vivoa/partner-sdk 0.1.0

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

@@ -0,0 +1,45 @@
+import type { 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';
+import { MeResource } from './resources/me.ts';
+import { MerchantsResource } from './resources/merchants.ts';
+import { WebhooksResource } from './resources/webhooks.ts';
+import { FleetResource } from './resources/fleet.ts';
+import { type ProvisionStoreOptions, type ProvisionStoreResult } from './use-cases/provision-store.ts';
+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";
+/** Every adapter is injected — the client itself has no I/O of its own. */
+export interface PartnerClientDeps {
+    baseUrl: string;
+    apiKey: string;
+    apiSecret: string;
+    transport: HttpTransport;
+    crypto: CryptoProvider;
+    clock: Clock;
+    logger?: SdkLogger;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+export declare class VivoaPartnerClient {
+    readonly me: MeResource;
+    readonly merchants: MerchantsResource;
+    readonly webhooks: WebhooksResource;
+    readonly fleet: FleetResource;
+    private readonly provisioning;
+    private readonly crypto;
+    constructor(deps: PartnerClientDeps);
+    /**
+     * Ensure a merchant exists for `input.externalId`, activate it and wait until
+     * it is live. Safe to call again with the same externalId — it resumes.
+     */
+    provisionStore(input: CreateMerchantInput, options?: ProvisionStoreOptions): Promise<ProvisionStoreResult>;
+    waitUntilSettled(merchantId: string, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<MerchantStatus>;
+    /** Verify + parse an incoming webhook with this client's crypto adapter. */
+    verifyWebhook(params: VerifyWebhookParams): Promise<WebhookEvent>;
+}

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

@@ -0,0 +1,51 @@
+import { silentLogger } from "../ports/logger.port.js";
+import { SignedHttpClient } from "./signed-http.js";
+import { MeResource } from "./resources/me.js";
+import { MerchantsResource } from "./resources/merchants.js";
+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';
+export class VivoaPartnerClient {
+    me;
+    merchants;
+    webhooks;
+    fleet;
+    provisioning;
+    crypto;
+    constructor(deps) {
+        const http = new SignedHttpClient({
+            baseUrl: deps.baseUrl,
+            apiKey: deps.apiKey,
+            apiSecret: deps.apiSecret,
+            transport: deps.transport,
+            crypto: deps.crypto,
+            clock: deps.clock,
+            logger: deps.logger ?? silentLogger,
+            timeoutMs: deps.timeoutMs ?? 30_000,
+            maxRetries: deps.maxRetries ?? 2,
+            userAgent: `vivoa-partner-sdk/${SDK_VERSION}`,
+        });
+        this.crypto = deps.crypto;
+        this.me = new MeResource(http);
+        this.merchants = new MerchantsResource(http);
+        this.webhooks = new WebhooksResource(http);
+        this.fleet = new FleetResource(http);
+        this.provisioning = new ProvisionStoreUseCase(this.merchants, deps.clock);
+    }
+    /**
+     * Ensure a merchant exists for `input.externalId`, activate it and wait until
+     * it is live. Safe to call again with the same externalId — it resumes.
+     */
+    provisionStore(input, options) {
+        return this.provisioning.execute(input, options);
+    }
+    waitUntilSettled(merchantId, options) {
+        return this.provisioning.waitUntilSettled(merchantId, options);
+    }
+    /** Verify + parse an incoming webhook with this client's crypto adapter. */
+    verifyWebhook(params) {
+        return verifyWebhook(this.crypto, params);
+    }
+}

package/dist/esm/application/resources/fleet.d.ts

@@ -0,0 +1,7 @@
+import type { SignedHttpClient } from '../signed-http.ts';
+import type { FleetAnalytics } from '../../domain/operator.ts';
+export declare class FleetResource {
+    private readonly http;
+    constructor(http: SignedHttpClient);
+    analytics(): Promise<FleetAnalytics>;
+}

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

@@ -0,0 +1,9 @@
+export class FleetResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    analytics() {
+        return this.http.request('GET', '/partner/v1/fleet/analytics');
+    }
+}

package/dist/esm/application/resources/me.d.ts

@@ -0,0 +1,13 @@
+import type { SignedHttpClient } from '../signed-http.ts';
+import type { OperatorProfile, RotatedApiSecret } from '../../domain/operator.ts';
+export declare class MeResource {
+    private readonly http;
+    constructor(http: SignedHttpClient);
+    /** Plan, quota usage (`storesUsed/maxStores`), allowed countries, rate limit. */
+    get(): Promise<OperatorProfile>;
+    /**
+     * Rotates the apiSecret. The new secret is returned ONCE and this client
+     * switches to it immediately; persist it before the process exits.
+     */
+    rotateSecret(): Promise<RotatedApiSecret>;
+}

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

@@ -0,0 +1,19 @@
+export 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;
+    }
+}

package/dist/esm/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/esm/application/resources/merchants.js

@@ -0,0 +1,87 @@
+import { VivoaValidationError } from "../../domain/errors.js";
+import { MAX_EXTERNAL_ID_LENGTH, } from "../../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. */
+export const DEFAULT_ACTIVATE_TIMEOUT_MS = 10 * 60_000;
+export 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 ?? 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`);
+    }
+}
+function encodeId(id) {
+    if (!id)
+        throw new VivoaValidationError('merchantId is required');
+    return encodeURIComponent(id);
+}
+export 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 > MAX_EXTERNAL_ID_LENGTH) {
+            problems.push(`externalId must be at most ${MAX_EXTERNAL_ID_LENGTH} chars`);
+        }
+    }
+    if (problems.length > 0)
+        throw new VivoaValidationError(problems.join('; '));
+}

package/dist/esm/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/esm/application/resources/webhooks.js

@@ -0,0 +1,26 @@
+export 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 } });
+    }
+}

package/dist/esm/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/esm/application/signed-http.js

@@ -0,0 +1,101 @@
+import { apiErrorFor, VivoaApiError, VivoaNetworkError } from "../domain/errors.js";
+import { canonicalRequestPayload, PARTNER_HEADERS } from "../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.
+ */
+export 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 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 = canonicalRequestPayload({
+            timestamp,
+            method: params.method,
+            path: params.path,
+            bodySha256Hex: await crypto.sha256Hex(params.body ?? ''),
+        });
+        const headers = {
+            accept: 'application/json',
+            'user-agent': userAgent,
+            [PARTNER_HEADERS.key]: apiKey,
+            [PARTNER_HEADERS.timestamp]: timestamp,
+            [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 };
+    }
+}
+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 VivoaNetworkError)
+        return true;
+    return err instanceof 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 VivoaApiError && err.status === 429 ? 2_000 : 0;
+    return Math.max(floor, Math.round(exp / 2 + Math.random() * (exp / 2)));
+}

package/dist/esm/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/esm/application/use-cases/provision-store.js

@@ -0,0 +1,99 @@
+import { canActivate, isSettled, } from "../../domain/merchant.js";
+import { VivoaConflictError, VivoaNetworkError, VivoaProvisioningFailedError, VivoaServerError, VivoaTimeoutError, VivoaValidationError, } from "../../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.
+ */
+export class ProvisionStoreUseCase {
+    merchants;
+    clock;
+    constructor(merchants, clock) {
+        this.merchants = merchants;
+        this.clock = clock;
+    }
+    async execute(input, options = {}) {
+        if (!input.externalId?.trim()) {
+            throw new 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 (canActivate(status.deployStatus)) {
+            progress('activating', merchant, status.deployStatus);
+            status = await this.activate(merchant.id, deadline);
+        }
+        if (options.waitUntilLive !== false && !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 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 (isSettled(status.deployStatus))
+                return status;
+            if (this.clock.nowMs() + interval > deadline) {
+                throw new 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 VivoaConflictError || err instanceof VivoaNetworkError) {
+                return this.merchants.status(merchantId);
+            }
+            if (err instanceof VivoaServerError) {
+                const status = await this.merchants.status(merchantId).catch(() => null);
+                if (status?.deployStatus === 'failed') {
+                    throw new VivoaProvisioningFailedError(merchantId, err.message, { cause: err });
+                }
+                if (status && !canActivate(status.deployStatus))
+                    return status;
+            }
+            throw err;
+        }
+    }
+}

package/dist/esm/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};