@vivoa/partner-sdk 0.2.0 → 0.4.0

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

@@ -32,6 +32,14 @@ export interface MerchantStatus {
     deployStatus: MerchantRuntimeStatus;
     domain: string | null;
     apiBaseUrl: string | null;
+    /** ISO-8601 when the store reached `live` (null before it provisions). */
+    provisionedAt: string | null;
+    /**
+     * Why the LAST provisioning attempt failed — surfaced only while
+     * `deployStatus === 'failed'`, null otherwise (a stale error never leaks once
+     * the store is live). The queryable "why" behind a failed activation.
+     */
+    lastError: string | null;
 }
 export interface CreateMerchantInput {
     /** Email of the store owner (receives their own merchant account). */
@@ -41,13 +49,20 @@ export interface CreateMerchantInput {
     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.
+     * Your reference for the CLIENT who owns this store (your customer id). **Not
+     * unique**: one client can own several stores, all sharing this value — list
+     * them with `merchants.list({ externalId })`. This is NOT the idempotency key
+     * (see `idempotencyKey`). Max 120 chars.
      */
     externalId?: string;
+    /**
+     * Idempotency key for THIS creation (e.g. your order id). Replaying the same
+     * key returns the SAME merchant instead of creating a duplicate — safe
+     * retries. **Unique per operator**, max 120 chars. `provisionStore()`
+     * requires it for exactly that reason. Omit it and every call creates a new
+     * store.
+     */
+    idempotencyKey?: string;
 }
 /** Options for `merchants.adminTicket()`. */
 export interface AdminTicketOptions {
@@ -65,6 +80,130 @@ export interface AdminTicketOptions {
 export interface MerchantAdminTicket {
     redirectUrl: string;
 }
+/** One plugin to install + configure on a merchant's store. */
+export interface PluginProvisionInput {
+    /** Plugin code (e.g. `boxful`). */
+    code: string;
+    /** Global-scope config, merged into the plugin's existing config. */
+    global?: Record<string, unknown>;
+    /** Per-country config slices (credentials, pickup origin…), merged per country. */
+    countries?: Array<{
+        countryCode: string;
+        config: Record<string, unknown>;
+    }>;
+    /** Activate the plugin (and its countries) so the store is ready to use. */
+    activate?: boolean;
+}
+/** Outcome of `merchants.configurePlugins()` for one plugin. */
+export interface PluginProvisionResult {
+    code: string;
+    installed: boolean;
+    configured: boolean;
+    error?: string;
+}
+/** Valid product type slugs (`physical` | `service` | `digital`). Unknown slugs fall back to `physical` store-side. */
+export type ProductTypeSlug = 'physical' | 'service' | 'digital';
+/**
+ * One inventory entry: stock by country (auto-creates a WH-XX location) or by an
+ * existing `locationCode`. `quantity` is a non-negative integer (the store
+ * rejects fractional stock).
+ */
+export type InventoryEntry = {
+    country: string;
+    quantity: number;
+    locationCode?: never;
+} | {
+    locationCode: string;
+    quantity: number;
+    country?: never;
+};
+/** One product to seed into a merchant's catalog. Mirrors the store import item. */
+export interface ProvisionProduct {
+    /** Slug, kebab-case `[a-z0-9-]`. */
+    handle: string;
+    name: string;
+    /**
+     * Product type: `physical` (has variants, requires shipping), `service` (no
+     * variants, no shipping), `digital` (has variants, no shipping). Unknown
+     * values fall back to `physical` store-side — prefer being explicit.
+     */
+    productTypeSlug: ProductTypeSlug;
+    price: number;
+    description?: string;
+    vendor?: string;
+    tags?: string[];
+    costPrice?: number;
+    barcode?: string;
+    weight?: number;
+    /** Remote image URLs — validated + ingested store-side. Max 20. */
+    images?: string[];
+    /**
+     * Sales channel handles to publish this product on. Omit to publish on the
+     * store's default channel.
+     */
+    channels?: string[];
+    /** Per-country or per-location stock. Import locations before products when using `locationCode`. */
+    inventory?: InventoryEntry[];
+}
+/** One row that failed during a product import. Mirrors the store import error. */
+export interface ImportProductError {
+    /** Zero-based index into the `products` array you sent. */
+    row: number;
+    /** Handle of the offending product, when the row carried one. */
+    handle?: string;
+    /** Machine code, e.g. `IMAGE_INVALID_URL`, `UNKNOWN_LOCATION`, `UNKNOWN_PRODUCT_TYPE`. */
+    code: string;
+    message: string;
+    /** Extra diagnostic payload, when the store attaches one. */
+    context?: Record<string, unknown>;
+}
+/** Aggregate result of `merchants.importProducts()`. */
+export interface ImportProductsResult {
+    /** Rows received (== `products.length`, or the rows that passed validation). */
+    total: number;
+    created: number;
+    updated: number;
+    skipped: number;
+    /** Per-row failures. Empty on full success. */
+    errors: ImportProductError[];
+}
+/** One warehouse / pickup point to seed into a merchant's inventory. Upserted by `code`. */
+export interface ProvisionLocation {
+    /** Your stable identifier — the upsert key (e.g. warehouse id). Max 60 chars. */
+    code: string;
+    /** Display name shown in the store admin. Max 120 chars. */
+    name: string;
+    /** ISO-3166-1 alpha-2 (e.g. `"SV"`, `"GT"`, `"HN"`). */
+    country: string;
+    /** Location type hint (e.g. `warehouse`, `pickup`, `shop`). */
+    type?: string;
+    address?: string;
+    city?: string;
+    postalCode?: string;
+    phone?: string;
+    email?: string;
+    isActive?: boolean;
+    /** Whether this location ships orders. Default `true`. */
+    handlesFulfillment?: boolean;
+    /** Whether customers can pick up here. Default `false`. */
+    pickupAvailable?: boolean;
+    /** Preferred carrier code for shipments dispatched from this location. */
+    preferredCarrier?: string;
+    latitude?: number;
+    longitude?: number;
+    referencePoint?: string;
+}
+/** Aggregate result of `merchants.importLocations()`. */
+export interface ImportLocationsResult {
+    total: number;
+    created: number;
+    updated: number;
+    errors: Array<{
+        row: number;
+        code: string;
+        message: string;
+    }>;
+}
 export interface ListMerchantsQuery {
     page?: number;
     /** Max 100. */
@@ -84,6 +223,8 @@ export interface Page<T> {
 }
 /** Max length the platform accepts for `CreateMerchantInput.externalId`. */
 export declare const MAX_EXTERNAL_ID_LENGTH = 120;
+/** Max length the platform accepts for `CreateMerchantInput.idempotencyKey`. */
+export declare const MAX_IDEMPOTENCY_KEY_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. */

package/dist/cjs/domain/merchant.js

@@ -5,7 +5,7 @@
  * Pure: no I/O, no Node APIs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_EXTERNAL_ID_LENGTH = exports.MERCHANT_RUNTIME_STATUSES = void 0;
+exports.MAX_IDEMPOTENCY_KEY_LENGTH = exports.MAX_EXTERNAL_ID_LENGTH = exports.MERCHANT_RUNTIME_STATUSES = void 0;
 exports.canActivate = canActivate;
 exports.isSettled = isSettled;
 exports.MERCHANT_RUNTIME_STATUSES = [
@@ -18,6 +18,8 @@ exports.MERCHANT_RUNTIME_STATUSES = [
 ];
 /** Max length the platform accepts for `CreateMerchantInput.externalId`. */
 exports.MAX_EXTERNAL_ID_LENGTH = 120;
+/** Max length the platform accepts for `CreateMerchantInput.idempotencyKey`. */
+exports.MAX_IDEMPOTENCY_KEY_LENGTH = 120;
 /** Runtime states where the platform accepts `activate` (first run or retry). */
 function canActivate(runtime) {
     return runtime === 'not_activated' || runtime === 'failed';

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.2.0";
+export declare const SDK_VERSION = "0.4.0";

package/dist/cjs/version.js

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

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

@@ -61,6 +61,7 @@ export declare class FakeVivoa implements HttpTransport {
     private readonly operators;
     private readonly merchants;
     private readonly handles;
+    private readonly merchantLocations;
     constructor(options?: FakeVivoaOptions);
     addOperator(seed: FakeOperatorSeed): OperatorProfile;
     setOperatorStatus(apiKey: string, status: OperatorStatus): void;

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

@@ -3,7 +3,7 @@ import { nodeCrypto } from "../node-crypto.js";
 import { systemClock } from "../system-clock.js";
 import { VivoaNetworkError } from "../../domain/errors.js";
 import { canonicalRequestPayload, MAX_CLOCK_SKEW_SECONDS, PARTNER_HEADERS, } from "../../domain/signature.js";
-import { MAX_EXTERNAL_ID_LENGTH } from "../../domain/merchant.js";
+import { MAX_EXTERNAL_ID_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, } from "../../domain/merchant.js";
 import { MERCHANT_EVENT_TYPES } from "../../domain/webhook.js";
 class HttpError extends Error {
     status;
@@ -13,7 +13,7 @@ class HttpError extends Error {
     }
 }
 /** `POST /merchants` body — matches CreateMerchantDto's whitelist exactly (a stale `handle` 400s, like on the real platform). */
-const CREATE_MERCHANT_KEYS = new Set(['email', 'name', 'countries', 'industry', 'externalId']);
+const CREATE_MERCHANT_KEYS = new Set(['email', 'name', 'countries', 'industry', 'externalId', 'idempotencyKey']);
 /** Mirrors `shared/utils/slugify.ts` on the platform closely enough for a fake. */
 function slugify(value) {
     return value
@@ -51,6 +51,7 @@ export class FakeVivoa {
     operators = new Map();
     merchants = new Map();
     handles = new Set();
+    merchantLocations = new Map();
     constructor(options = {}) {
         this.clock = options.clock ?? systemClock;
         this.crypto = options.crypto ?? nodeCrypto;
@@ -152,7 +153,7 @@ export class FakeVivoa {
     async route(op, method, url, rawBody) {
         const path = url.pathname.replace(/^\/partner\/v1/, '');
         const body = rawBody ? JSON.parse(rawBody) : {};
-        const merchantRoute = path.match(/^\/merchants\/([^/]+)\/(status|activate|suspend|reactivate|admin-ticket)$/);
+        const merchantRoute = path.match(/^\/merchants\/([^/]+)\/(status|activate|suspend|reactivate|admin-ticket|plugins|locations|products)$/);
         if (method === 'GET' && path === '/me')
             return this.profile(op);
         if (method === 'POST' && path === '/me/rotate-secret') {
@@ -199,6 +200,38 @@ export class FakeVivoa {
                         redirectUrl: `${base}/auth/admin-redeem?token=fake-${merchant.id}${returnPath === '/admin' ? '' : `&rp=${encodeURIComponent(returnPath)}`}`,
                     };
                 }
+                if (action === 'plugins') {
+                    const plugins = Array.isArray(body.plugins) ? body.plugins : [];
+                    return {
+                        plugins: plugins.map((p) => ({
+                            code: p.code,
+                            installed: true,
+                            configured: true,
+                        })),
+                    };
+                }
+                if (action === 'locations') {
+                    const locations = Array.isArray(body.locations) ? body.locations : [];
+                    if (locations.length === 0)
+                        throw new HttpError(400, 'locations must not be empty');
+                    const m = this.merchantLocations.get(merchant.id) ?? [];
+                    let created = 0;
+                    let updated = 0;
+                    for (const loc of locations) {
+                        if (m.some((l) => l === loc.code))
+                            updated++;
+                        else {
+                            m.push(loc.code);
+                            created++;
+                        }
+                    }
+                    this.merchantLocations.set(merchant.id, m);
+                    return { total: locations.length, created, updated, errors: [] };
+                }
+                if (action === 'products') {
+                    const products = Array.isArray(body.products) ? body.products : [];
+                    return { total: products.length, created: products.length, updated: 0, skipped: 0, errors: [] };
+                }
             }
         }
         if (method === 'GET' && path === '/fleet/analytics')
@@ -215,6 +248,7 @@ export class FakeVivoa {
         const name = String(body.name ?? '');
         const countries = Array.isArray(body.countries) ? body.countries.map(String) : [];
         const externalId = body.externalId === undefined ? undefined : String(body.externalId);
+        const idempotencyKey = body.idempotencyKey === undefined ? undefined : String(body.idempotencyKey);
         const problems = [];
         if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
             problems.push('email must be an email');
@@ -225,11 +259,17 @@ export class FakeVivoa {
         if (externalId !== undefined && externalId.length > MAX_EXTERNAL_ID_LENGTH) {
             problems.push(`externalId must be shorter than or equal to ${MAX_EXTERNAL_ID_LENGTH} characters`);
         }
+        if (idempotencyKey !== undefined && idempotencyKey.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+            problems.push(`idempotencyKey must be shorter than or equal to ${MAX_IDEMPOTENCY_KEY_LENGTH} characters`);
+        }
         if (problems.length)
             throw new HttpError(400, problems.join('; '));
-        // Idempotent replay BEFORE quota/region checks — mirrors the platform.
-        if (externalId) {
-            const existing = this.fleet(op).find((m) => m.externalId === externalId);
+        // Idempotent replay BEFORE quota/region checks — mirrors the platform. The
+        // dedup key is idempotencyKey (unique per operator), NOT externalId: that is
+        // a non-unique client reference and may map to several of the operator's
+        // stores.
+        if (idempotencyKey) {
+            const existing = this.fleet(op).find((m) => m.idempotencyKey === idempotencyKey);
             if (existing)
                 return publicMerchant(existing);
         }
@@ -254,6 +294,9 @@ export class FakeVivoa {
             createdAt: new Date(this.clock.nowMs()).toISOString(),
             operatorId: op.id,
             pollsLeft: 0,
+            idempotencyKey: idempotencyKey ?? null,
+            provisionedAt: null,
+            lastError: null,
         };
         this.handles.add(merchant.handle);
         this.merchants.set(merchant.id, merchant);
@@ -288,6 +331,7 @@ export class FakeVivoa {
         switch (this.activation) {
             case 'fail':
                 m.runtime = 'failed';
+                m.lastError = this.failureReason;
                 this.emit(op, 'merchant.failed', m, { reason: this.failureReason });
                 throw new HttpError(500, this.failureReason);
             case 'slow':
@@ -306,6 +350,8 @@ export class FakeVivoa {
     goLive(m) {
         m.runtime = 'live';
         m.domain = `${m.handle}.vivoa.store`;
+        m.provisionedAt = new Date(this.clock.nowMs()).toISOString();
+        m.lastError = null;
         const op = [...this.operators.values()].find((o) => o.id === m.operatorId);
         if (op)
             this.emit(op, 'merchant.live', m);
@@ -324,6 +370,8 @@ export class FakeVivoa {
             deployStatus: m.runtime,
             domain: m.domain,
             apiBaseUrl: m.runtime === 'live' ? 'https://shared-api.vivoa.app' : null,
+            provisionedAt: m.provisionedAt,
+            lastError: m.runtime === 'failed' ? m.lastError : null,
         };
     }
     list(op, qs) {
@@ -453,7 +501,7 @@ export class FakeVivoa {
     }
 }
 function publicMerchant(m) {
-    const { operatorId: _op, pollsLeft: _polls, ...view } = m;
+    const { operatorId: _op, pollsLeft: _polls, idempotencyKey: _key, provisionedAt: _prov, lastError: _err, ...view } = m;
     return { ...view, countries: [...view.countries] };
 }
 function webhookView(op) {

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

@@ -1,5 +1,5 @@
 import type { SignedHttpClient } from '../signed-http.ts';
-import { type AdminTicketOptions, type CreateMerchantInput, type ListMerchantsQuery, type Merchant, type MerchantAdminTicket, type MerchantStatus, type Page } from '../../domain/merchant.ts';
+import { type AdminTicketOptions, type CreateMerchantInput, type ImportLocationsResult, type ImportProductsResult, type ListMerchantsQuery, type Merchant, type MerchantAdminTicket, type MerchantStatus, type Page, type PluginProvisionInput, type PluginProvisionResult, type ProvisionLocation, type ProvisionProduct } 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 {
@@ -7,8 +7,9 @@ export declare class MerchantsResource {
     constructor(http: SignedHttpClient);
     /**
      * Creates owner + store in your fleet. Not live until `activate`. The
-     * platform assigns the handle. Pass `externalId` and replaying the same
+     * platform assigns the handle. Pass `idempotencyKey` and replaying the same
      * value returns the merchant you already created — never a second one.
+     * `externalId` is a non-unique client reference, not a dedup key.
      */
     create(input: CreateMerchantInput): Promise<Merchant>;
     list(query?: ListMerchantsQuery): Promise<Page<Merchant>>;
@@ -39,5 +40,26 @@ export declare class MerchantsResource {
      * not store it. 403 if the merchant is not in your fleet or is not active.
      */
     adminTicket(merchantId: string, options?: AdminTicketOptions): Promise<MerchantAdminTicket>;
+    /**
+     * Installs + configures plugins on the merchant's store (credentials, pickup
+     * origin, activation). Idempotent — config is merged, not replaced — so it
+     * doubles as a re-sync. 403 if the merchant is not in your fleet.
+     */
+    configurePlugins(merchantId: string, plugins: PluginProvisionInput[]): Promise<{
+        plugins: PluginProvisionResult[];
+    }>;
+    /**
+     * Bulk-imports inventory locations (warehouses, pickup points) into the
+     * merchant's store. Upserted on `code` — idempotent, re-running updates
+     * rather than duplicates. Import locations **before** products when you
+     * reference `inventory[].locationCode`. 409 if the merchant is not live.
+     */
+    importLocations(merchantId: string, locations: ProvisionLocation[]): Promise<ImportLocationsResult>;
+    /**
+     * Bulk-imports products into the merchant's catalog (URL images, per-country
+     * inventory). Idempotent on `handle`, so re-running updates rather than
+     * duplicates. 403 if the merchant is not in your fleet.
+     */
+    importProducts(merchantId: string, products: ProvisionProduct[]): Promise<ImportProductsResult>;
 }
 export declare function validateCreate(input: CreateMerchantInput): void;

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

@@ -1,5 +1,5 @@
 import { VivoaValidationError } from "../../domain/errors.js";
-import { MAX_EXTERNAL_ID_LENGTH, } from "../../domain/merchant.js";
+import { MAX_EXTERNAL_ID_LENGTH, MAX_IDEMPOTENCY_KEY_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. */
@@ -11,8 +11,9 @@ export class MerchantsResource {
     }
     /**
      * Creates owner + store in your fleet. Not live until `activate`. The
-     * platform assigns the handle. Pass `externalId` and replaying the same
+     * platform assigns the handle. Pass `idempotencyKey` and replaying the same
      * value returns the merchant you already created — never a second one.
+     * `externalId` is a non-unique client reference, not a dedup key.
      */
     async create(input) {
         validateCreate(input);
@@ -68,6 +69,43 @@ export class MerchantsResource {
             body: options.returnPath ? { returnPath: options.returnPath } : {},
         });
     }
+    /**
+     * Installs + configures plugins on the merchant's store (credentials, pickup
+     * origin, activation). Idempotent — config is merged, not replaced — so it
+     * doubles as a re-sync. 403 if the merchant is not in your fleet.
+     */
+    async configurePlugins(merchantId, plugins) {
+        if (plugins.length === 0)
+            throw new VivoaValidationError('plugins must not be empty');
+        return this.http.request('POST', `/partner/v1/merchants/${encodeId(merchantId)}/plugins`, {
+            body: { plugins },
+        });
+    }
+    /**
+     * Bulk-imports inventory locations (warehouses, pickup points) into the
+     * merchant's store. Upserted on `code` — idempotent, re-running updates
+     * rather than duplicates. Import locations **before** products when you
+     * reference `inventory[].locationCode`. 409 if the merchant is not live.
+     */
+    async importLocations(merchantId, locations) {
+        if (locations.length === 0)
+            throw new VivoaValidationError('locations must not be empty');
+        return this.http.request('POST', `/partner/v1/merchants/${encodeId(merchantId)}/locations`, {
+            body: { locations },
+        });
+    }
+    /**
+     * Bulk-imports products into the merchant's catalog (URL images, per-country
+     * inventory). Idempotent on `handle`, so re-running updates rather than
+     * duplicates. 403 if the merchant is not in your fleet.
+     */
+    async importProducts(merchantId, products) {
+        if (products.length === 0)
+            throw new VivoaValidationError('products must not be empty');
+        return this.http.request('POST', `/partner/v1/merchants/${encodeId(merchantId)}/products`, {
+            body: { products },
+        });
+    }
 }
 function encodeId(id) {
     if (!id)
@@ -93,6 +131,13 @@ export function validateCreate(input) {
             problems.push(`externalId must be at most ${MAX_EXTERNAL_ID_LENGTH} chars`);
         }
     }
+    if (input.idempotencyKey !== undefined) {
+        if (!input.idempotencyKey.trim())
+            problems.push('idempotencyKey must not be empty');
+        else if (input.idempotencyKey.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+            problems.push(`idempotencyKey must be at most ${MAX_IDEMPOTENCY_KEY_LENGTH} chars`);
+        }
+    }
     if (problems.length > 0)
         throw new VivoaValidationError(problems.join('; '));
 }

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

@@ -1,7 +1,7 @@
 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';
+import { type CreateMerchantInput, type ImportLocationsResult, type ImportProductsResult, type Merchant, type MerchantRuntimeStatus, type MerchantStatus, type PluginProvisionInput, type PluginProvisionResult, type ProvisionLocation, type ProvisionProduct } from '../../domain/merchant.ts';
+export type ProvisionPhase = 'found' | 'created' | 'activating' | 'waiting' | 'seeding' | 'settled';
 export interface ProvisionProgress {
     phase: ProvisionPhase;
     merchantId: string;
@@ -18,22 +18,46 @@ export interface ProvisionStoreOptions {
     /** Status poll cadence while `creating`. Default 5 s. */
     pollIntervalMs?: number;
     onProgress?: (progress: ProvisionProgress) => void;
+    /**
+     * Plugins to install + configure once the store is live (credentials, pickup
+     * origin, activation). Best-effort: a live store with a failed seed still
+     * resolves — the result carries the error and the caller can re-run.
+     */
+    plugins?: PluginProvisionInput[];
+    /**
+     * Inventory locations (warehouses, pickup points) to import once the store
+     * is live. Seeded **before** products so `inventory[].locationCode`
+     * references resolve. Best-effort.
+     */
+    locations?: ProvisionLocation[];
+    /** Products to seed into the catalog once the store is live. Best-effort. */
+    products?: ProvisionProduct[];
 }
 export interface ProvisionStoreResult {
     merchant: Merchant;
     status: MerchantStatus;
-    /** false when a merchant with this externalId already existed in your fleet. */
+    /**
+     * false when this call replayed a merchant already past `not_activated` (a
+     * definite prior run). A fresh create — or a replay of a merchant that never
+     * activated — reads `true`.
+     */
     created: boolean;
+    /** Per-plugin seed outcome, when `options.plugins` was supplied. */
+    plugins?: PluginProvisionResult[];
+    /** Location import outcome, when `options.locations` was supplied. */
+    locations?: ImportLocationsResult;
+    /** Catalog seed outcome, when `options.products` was supplied. */
+    products?: ImportProductsResult;
 }
 /**
  * "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.
+ * Requires `input.idempotencyKey`: 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). `externalId` is a separate, non-unique client reference
+ * (one client may own several stores) and is NOT a dedup key. Never retries a
+ * failed activation on its own.
  */
 export declare class ProvisionStoreUseCase {
     private readonly merchants;