@vivoa/partner-sdk 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.0
+
+Store setup (plugins, locations, catalog) + a contract re-alignment with the platform.
+
+- feat: `merchants.importLocations()` and `provisionStore({ locations })` — upsert inventory locations by `code`, seeded **before** products so `inventory[].locationCode` resolves.
+- feat: `merchants.importProducts()` and `provisionStore({ products })` — catalog seeding with URL images and per-country or per-location stock. `ProvisionProduct.channels` selects sales channels.
+- feat: `merchants.configurePlugins()` and `provisionStore({ plugins })` — install + configure plugins (idempotent, doubles as re-sync).
+- feat: `MerchantStatus` now carries `provisionedAt` and `lastError`; `VivoaProvisioningFailedError` surfaces the platform's `lastError` as its reason.
+- **breaking:** `CreateMerchantInput.idempotencyKey` is now the dedup key (unique per operator). `externalId` becomes a non-unique CLIENT reference. `provisionStore()` now requires `idempotencyKey` (was `externalId`).
+- **breaking:** `ImportProductsResult` is now `{ total, created, updated, skipped, errors[] }` (was `{ created, updated, skipped, failed }`) — matches the platform and exposes per-row failure reasons.
+- **breaking:** `ProductTypeSlug` narrowed to `'physical' | 'service' | 'digital'` (was `string`); unknown slugs fall back to `physical` store-side.
+
 ## 0.1.1
 
 - fix: `provisionStore` now throws `VivoaProvisioningFailedError` on `'unknown'` runtime instead of returning a broken store silently.

package/README.md

@@ -34,19 +34,20 @@ const vivoa = createPartnerClient({
   apiSecret: process.env.VIVOA_PARTNER_SECRET!,
 });
 
-// Provision a store for one of your users — idempotent on externalId
+// Provision a store for one of your users — idempotent on idempotencyKey
 const { merchant, status } = await vivoa.provisionStore({
-  externalId: 'cus_9f3a2e10',   // your internal reference — customer id, order id, etc.
-  email:      'owner@acme.com',
-  name:       'Acme',
-  countries:  ['SV'],
+  idempotencyKey: 'order_42',   // safe-retry key, unique per operator
+  externalId:     'cus_9f3a2e10', // your CLIENT reference — may repeat across stores
+  email:          'owner@acme.com',
+  name:           'Acme',
+  countries:      ['SV'],
 });
 
 console.log(status.domain);     // store is live at this domain
 console.log(merchant.handle);   // Vivoa-assigned handle, guaranteed unique
 ```
 
-`externalId` is your key. Use it to find the store later (`findByExternalId`), and call `provisionStore` again safely — it won't create a duplicate.
+`idempotencyKey` is your retry key: call `provisionStore` again with the same key and it resumes the same store — never a duplicate. `externalId` is a separate, non-unique reference to YOUR client (one client can own several stores); list them later with `merchants.list({ externalId })`.
 
 ---
 
@@ -54,12 +55,11 @@ console.log(merchant.handle);   // Vivoa-assigned handle, guaranteed unique
 
 One call drives the entire lifecycle:
 
-1. Looks up `externalId` in your fleet — if it exists, resumes from current state.
-2. Creates the store if it doesn't exist (Vivoa assigns the `handle` from `name`).
-3. Activates if `not_activated` or `failed`.
-4. Polls until settled if `creating`.
-5. Recovers from a dropped `activate` by reading `GET /status`.
-6. Never silently retries a `failed` — throws `VivoaProvisioningFailedError` so you decide what happens next.
+1. Creates the store (Vivoa assigns the `handle` from `name`). The platform dedups on `idempotencyKey`, so a replay resumes the same store from its current state instead of creating a second one.
+2. Activates if `not_activated` or `failed`.
+3. Polls until settled if `creating`.
+4. Recovers from a dropped `activate` by reading `GET /status`.
+5. Never silently retries a `failed` — throws `VivoaProvisioningFailedError` so you decide what happens next.
 
 ---
 
@@ -90,7 +90,7 @@ All errors extend `VivoaError`. HTTP errors are `VivoaApiError` with `status`, `
 | `VivoaRateLimitError` (429) | Plan request limit exceeded |
 | `VivoaServerError` · `VivoaNetworkError` · `VivoaTimeoutError` · `VivoaProvisioningFailedError` | Server, network, polling, or provisioning failures |
 
-**Retry policy:** `GET` only, on 429 / 5xx / network errors, with exponential backoff. Writes are not retried at the transport level — but `merchants.create()` and `provisionStore()` are safe to repeat thanks to `externalId` idempotency.
+**Retry policy:** `GET` only, on 429 / 5xx / network errors, with exponential backoff. Writes are not retried at the transport level — but `merchants.create()` and `provisionStore()` are safe to repeat thanks to `idempotencyKey` idempotency.
 
 ---
 

package/dist/cjs/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/cjs/adapters/in-memory/fake-vivoa.js

@@ -16,7 +16,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
@@ -54,6 +54,7 @@ class FakeVivoa {
     operators = new Map();
     merchants = new Map();
     handles = new Set();
+    merchantLocations = new Map();
     constructor(options = {}) {
         this.clock = options.clock ?? system_clock_ts_1.systemClock;
         this.crypto = options.crypto ?? node_crypto_ts_1.nodeCrypto;
@@ -155,7 +156,7 @@ 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') {
@@ -202,6 +203,38 @@ 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')
@@ -218,6 +251,7 @@ 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');
@@ -228,11 +262,17 @@ class FakeVivoa {
         if (externalId !== undefined && externalId.length > merchant_ts_1.MAX_EXTERNAL_ID_LENGTH) {
             problems.push(`externalId must be shorter than or equal to ${merchant_ts_1.MAX_EXTERNAL_ID_LENGTH} characters`);
         }
+        if (idempotencyKey !== undefined && idempotencyKey.length > merchant_ts_1.MAX_IDEMPOTENCY_KEY_LENGTH) {
+            problems.push(`idempotencyKey must be shorter than or equal to ${merchant_ts_1.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);
         }
@@ -257,6 +297,9 @@ 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);
@@ -291,6 +334,7 @@ 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':
@@ -309,6 +353,8 @@ 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);
@@ -327,6 +373,8 @@ 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) {
@@ -457,7 +505,7 @@ class FakeVivoa {
 }
 exports.FakeVivoa = 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/cjs/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/cjs/application/resources/merchants.js

@@ -15,8 +15,9 @@ 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);
@@ -72,6 +73,43 @@ 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 errors_ts_1.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 errors_ts_1.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 errors_ts_1.VivoaValidationError('products must not be empty');
+        return this.http.request('POST', `/partner/v1/merchants/${encodeId(merchantId)}/products`, {
+            body: { products },
+        });
+    }
 }
 exports.MerchantsResource = MerchantsResource;
 function encodeId(id) {
@@ -98,6 +136,13 @@ function validateCreate(input) {
             problems.push(`externalId must be at most ${merchant_ts_1.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 > merchant_ts_1.MAX_IDEMPOTENCY_KEY_LENGTH) {
+            problems.push(`idempotencyKey must be at most ${merchant_ts_1.MAX_IDEMPOTENCY_KEY_LENGTH} chars`);
+        }
+    }
     if (problems.length > 0)
         throw new errors_ts_1.VivoaValidationError(problems.join('; '));
 }

package/dist/cjs/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;

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

@@ -8,12 +8,12 @@ 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.
+ * 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.
  */
 class ProvisionStoreUseCase {
     merchants;
@@ -23,8 +23,8 @@ class ProvisionStoreUseCase {
         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. ' +
+        if (!input.idempotencyKey?.trim()) {
+            throw new errors_ts_1.VivoaValidationError('provisionStore requires input.idempotencyKey — 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);
@@ -45,11 +45,62 @@ class ProvisionStoreUseCase {
                 pollIntervalMs: options.pollIntervalMs,
             });
         }
-        progress('settled', merchant, status.deployStatus);
         if (status.deployStatus === 'failed' || status.deployStatus === 'unknown') {
-            throw new errors_ts_1.VivoaProvisioningFailedError(merchant.id, `the platform reported runtime status "${status.deployStatus}"`);
+            progress('settled', merchant, status.deployStatus);
+            throw new errors_ts_1.VivoaProvisioningFailedError(merchant.id, status.lastError ?? `the platform reported runtime status "${status.deployStatus}"`);
+        }
+        // Seed plugins → locations → catalog once the store is live. Best-effort
+        // by design: a failed seed leaves the store live and reports the error, so
+        // the caller can re-run (all three are idempotent) rather than losing a
+        // provisioned store to a transient credential/catalog hiccup.
+        // Locations must come before products — products may reference locationCode.
+        let plugins;
+        let locations;
+        let products;
+        if (options.plugins?.length || options.locations?.length || options.products?.length) {
+            progress('seeding', merchant, status.deployStatus);
+            if (options.plugins?.length) {
+                plugins = await this.merchants
+                    .configurePlugins(merchant.id, options.plugins)
+                    .then((r) => r.plugins)
+                    .catch((err) => options.plugins.map((p) => ({
+                    code: p.code,
+                    installed: false,
+                    configured: false,
+                    error: err instanceof Error ? err.message : String(err),
+                })));
+            }
+            if (options.locations?.length) {
+                locations = await this.merchants
+                    .importLocations(merchant.id, options.locations)
+                    .catch((err) => ({
+                    total: options.locations.length,
+                    created: 0,
+                    updated: 0,
+                    errors: [{ row: 0, code: 'seed_error', message: err instanceof Error ? err.message : String(err) }],
+                }));
+            }
+            if (options.products?.length) {
+                products = await this.merchants
+                    .importProducts(merchant.id, options.products)
+                    .catch((err) => ({
+                    total: options.products.length,
+                    created: 0,
+                    updated: 0,
+                    skipped: 0,
+                    errors: [{ row: 0, code: 'seed_error', message: err instanceof Error ? err.message : String(err) }],
+                }));
+            }
         }
-        return { merchant: { ...merchant, runtime: status.deployStatus, domain: status.domain }, status, created };
+        progress('settled', merchant, status.deployStatus);
+        return {
+            merchant: { ...merchant, runtime: status.deployStatus, domain: status.domain },
+            status,
+            created,
+            ...(plugins ? { plugins } : {}),
+            ...(locations ? { locations } : {}),
+            ...(products ? { products } : {}),
+        };
     }
     /** Polls `GET /status` until the runtime leaves `creating`. */
     async waitUntilSettled(merchantId, options = {}) {
@@ -66,15 +117,16 @@ class ProvisionStoreUseCase {
         }
     }
     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 };
+        // The platform is idempotent on idempotencyKey: replaying create() with the
+        // same key returns the merchant it already made — never a duplicate, never a
+        // 409. So we just create; no pre-check needed. (externalId is NOT the key: it
+        // is a non-unique client reference and may map to several of your stores.)
+        const merchant = await this.merchants.create(input);
+        // A freshly created store is always 'not_activated' with nothing provisioned
+        // yet; any further-along runtime means this call replayed an existing
+        // merchant. A replay of a never-activated merchant reads created=true —
+        // harmless, since provisionStore then activates it, which is idempotent too.
+        return { merchant, created: merchant.runtime === 'not_activated' };
     }
     async activate(merchantId, deadline) {
         try {