@vivoa/partner-sdk 0.3.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|plugins|products)$/);
+        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') {
@@ -212,9 +213,27 @@ class FakeVivoa {
                         })),
                     };
                 }
+                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 { created: products.length, updated: 0, skipped: 0, failed: 0 };
+                    return { total: products.length, created: products.length, updated: 0, skipped: 0, errors: [] };
                 }
             }
         }
@@ -232,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');
@@ -242,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);
         }
@@ -271,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);
@@ -305,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':
@@ -323,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);
@@ -341,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) {
@@ -471,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 ImportProductsResult, type ListMerchantsQuery, type Merchant, type MerchantAdminTicket, type MerchantStatus, type Page, type PluginProvisionInput, type PluginProvisionResult, type ProvisionProduct } 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>>;
@@ -47,6 +48,13 @@ export declare class MerchantsResource {
     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

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);
@@ -84,6 +85,19 @@ class MerchantsResource {
             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
@@ -122,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,6 +1,6 @@
 import type { Clock } from '../../ports/clock.port.ts';
 import type { MerchantsResource } from '../resources/merchants.ts';
-import { type CreateMerchantInput, type ImportProductsResult, type Merchant, type MerchantRuntimeStatus, type MerchantStatus, type PluginProvisionInput, type PluginProvisionResult, type ProvisionProduct } from '../../domain/merchant.ts';
+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;
@@ -24,28 +24,40 @@ export interface ProvisionStoreOptions {
      * 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);
@@ -47,15 +47,17 @@ class ProvisionStoreUseCase {
         }
         if (status.deployStatus === 'failed' || status.deployStatus === 'unknown') {
             progress('settled', merchant, status.deployStatus);
-            throw new errors_ts_1.VivoaProvisioningFailedError(merchant.id, `the platform reported runtime status "${status.deployStatus}"`);
+            throw new errors_ts_1.VivoaProvisioningFailedError(merchant.id, status.lastError ?? `the platform reported runtime status "${status.deployStatus}"`);
         }
-        // Seed plugins + 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 (`configurePlugins`/`importProducts` are idempotent) rather than
-        // losing a provisioned store to a transient catalog/credential hiccup.
+        // 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.products?.length) {
+        if (options.plugins?.length || options.locations?.length || options.products?.length) {
             progress('seeding', merchant, status.deployStatus);
             if (options.plugins?.length) {
                 plugins = await this.merchants
@@ -68,10 +70,26 @@ class ProvisionStoreUseCase {
                     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(() => ({ created: 0, updated: 0, skipped: 0, failed: options.products.length }));
+                    .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) }],
+                }));
             }
         }
         progress('settled', merchant, status.deployStatus);
@@ -80,6 +98,7 @@ class ProvisionStoreUseCase {
             status,
             created,
             ...(plugins ? { plugins } : {}),
+            ...(locations ? { locations } : {}),
             ...(products ? { products } : {}),
         };
     }
@@ -98,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 {

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 {
@@ -86,13 +101,33 @@ export interface PluginProvisionResult {
     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 slug the store catalog knows (e.g. `default`). */
-    productTypeSlug: 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;
@@ -100,20 +135,74 @@ export interface ProvisionProduct {
     costPrice?: number;
     barcode?: string;
     weight?: number;
-    /** Remote image URLs — validated + ingested store-side. */
+    /** Remote image URLs — validated + ingested store-side. Max 20. */
     images?: string[];
-    /** Per-country stock. */
-    inventory?: Array<{
-        country: string;
-        quantity: number;
-    }>;
+    /**
+     * 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;
-    failed: 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;
@@ -134,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.3.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.3.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|plugins|products)$/);
+        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') {
@@ -209,9 +210,27 @@ export class FakeVivoa {
                         })),
                     };
                 }
+                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 { created: products.length, updated: 0, skipped: 0, failed: 0 };
+                    return { total: products.length, created: products.length, updated: 0, skipped: 0, errors: [] };
                 }
             }
         }
@@ -229,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');
@@ -239,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);
         }
@@ -268,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);
@@ -302,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':
@@ -320,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);
@@ -338,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) {
@@ -467,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 ImportProductsResult, type ListMerchantsQuery, type Merchant, type MerchantAdminTicket, type MerchantStatus, type Page, type PluginProvisionInput, type PluginProvisionResult, type ProvisionProduct } 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>>;
@@ -47,6 +48,13 @@ export declare class MerchantsResource {
     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

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);
@@ -80,6 +81,19 @@ export class MerchantsResource {
             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
@@ -117,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,6 +1,6 @@
 import type { Clock } from '../../ports/clock.port.ts';
 import type { MerchantsResource } from '../resources/merchants.ts';
-import { type CreateMerchantInput, type ImportProductsResult, type Merchant, type MerchantRuntimeStatus, type MerchantStatus, type PluginProvisionInput, type PluginProvisionResult, type ProvisionProduct } from '../../domain/merchant.ts';
+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;
@@ -24,28 +24,40 @@ export interface ProvisionStoreOptions {
      * 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/esm/application/use-cases/provision-store.js

@@ -5,12 +5,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.
  */
 export class ProvisionStoreUseCase {
     merchants;
@@ -20,8 +20,8 @@ export class ProvisionStoreUseCase {
         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. ' +
+        if (!input.idempotencyKey?.trim()) {
+            throw new 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);
@@ -44,15 +44,17 @@ export class ProvisionStoreUseCase {
         }
         if (status.deployStatus === 'failed' || status.deployStatus === 'unknown') {
             progress('settled', merchant, status.deployStatus);
-            throw new VivoaProvisioningFailedError(merchant.id, `the platform reported runtime status "${status.deployStatus}"`);
+            throw new VivoaProvisioningFailedError(merchant.id, status.lastError ?? `the platform reported runtime status "${status.deployStatus}"`);
         }
-        // Seed plugins + 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 (`configurePlugins`/`importProducts` are idempotent) rather than
-        // losing a provisioned store to a transient catalog/credential hiccup.
+        // 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.products?.length) {
+        if (options.plugins?.length || options.locations?.length || options.products?.length) {
             progress('seeding', merchant, status.deployStatus);
             if (options.plugins?.length) {
                 plugins = await this.merchants
@@ -65,10 +67,26 @@ export class ProvisionStoreUseCase {
                     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(() => ({ created: 0, updated: 0, skipped: 0, failed: options.products.length }));
+                    .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) }],
+                }));
             }
         }
         progress('settled', merchant, status.deployStatus);
@@ -77,6 +95,7 @@ export class ProvisionStoreUseCase {
             status,
             created,
             ...(plugins ? { plugins } : {}),
+            ...(locations ? { locations } : {}),
             ...(products ? { products } : {}),
         };
     }
@@ -95,15 +114,16 @@ export 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 {

package/dist/esm/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 {
@@ -86,13 +101,33 @@ export interface PluginProvisionResult {
     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 slug the store catalog knows (e.g. `default`). */
-    productTypeSlug: 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;
@@ -100,20 +135,74 @@ export interface ProvisionProduct {
     costPrice?: number;
     barcode?: string;
     weight?: number;
-    /** Remote image URLs — validated + ingested store-side. */
+    /** Remote image URLs — validated + ingested store-side. Max 20. */
     images?: string[];
-    /** Per-country stock. */
-    inventory?: Array<{
-        country: string;
-        quantity: number;
-    }>;
+    /**
+     * 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;
-    failed: 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;
@@ -134,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/esm/domain/merchant.js

@@ -13,6 +13,8 @@ export const MERCHANT_RUNTIME_STATUSES = [
 ];
 /** Max length the platform accepts for `CreateMerchantInput.externalId`. */
 export const MAX_EXTERNAL_ID_LENGTH = 120;
+/** Max length the platform accepts for `CreateMerchantInput.idempotencyKey`. */
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 120;
 /** Runtime states where the platform accepts `activate` (first run or retry). */
 export function canActivate(runtime) {
     return runtime === 'not_activated' || runtime === 'failed';

package/dist/esm/version.d.ts

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

package/dist/esm/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '0.3.0';
+export const SDK_VERSION = '0.4.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vivoa/partner-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Official SDK for the Vivoa Partner API — create and operate stores for your merchants",
   "license": "UNLICENSED",
   "type": "module",