@vivoa/partner-sdk 0.2.0 → 0.4.0

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);
@@ -42,11 +42,62 @@ export class ProvisionStoreUseCase {
                 pollIntervalMs: options.pollIntervalMs,
             });
         }
-        progress('settled', merchant, status.deployStatus);
         if (status.deployStatus === 'failed' || status.deployStatus === 'unknown') {
-            throw new VivoaProvisioningFailedError(merchant.id, `the platform reported runtime status "${status.deployStatus}"`);
+            progress('settled', merchant, status.deployStatus);
+            throw new 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 = {}) {
@@ -63,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 {
@@ -65,6 +80,130 @@ export interface AdminTicketOptions {
 export interface MerchantAdminTicket {
     redirectUrl: string;
 }
+/** One plugin to install + configure on a merchant's store. */
+export interface PluginProvisionInput {
+    /** Plugin code (e.g. `boxful`). */
+    code: string;
+    /** Global-scope config, merged into the plugin's existing config. */
+    global?: Record<string, unknown>;
+    /** Per-country config slices (credentials, pickup origin…), merged per country. */
+    countries?: Array<{
+        countryCode: string;
+        config: Record<string, unknown>;
+    }>;
+    /** Activate the plugin (and its countries) so the store is ready to use. */
+    activate?: boolean;
+}
+/** Outcome of `merchants.configurePlugins()` for one plugin. */
+export interface PluginProvisionResult {
+    code: string;
+    installed: boolean;
+    configured: boolean;
+    error?: string;
+}
+/** Valid product type slugs (`physical` | `service` | `digital`). Unknown slugs fall back to `physical` store-side. */
+export type ProductTypeSlug = 'physical' | 'service' | 'digital';
+/**
+ * One inventory entry: stock by country (auto-creates a WH-XX location) or by an
+ * existing `locationCode`. `quantity` is a non-negative integer (the store
+ * rejects fractional stock).
+ */
+export type InventoryEntry = {
+    country: string;
+    quantity: number;
+    locationCode?: never;
+} | {
+    locationCode: string;
+    quantity: number;
+    country?: never;
+};
+/** One product to seed into a merchant's catalog. Mirrors the store import item. */
+export interface ProvisionProduct {
+    /** Slug, kebab-case `[a-z0-9-]`. */
+    handle: string;
+    name: string;
+    /**
+     * Product type: `physical` (has variants, requires shipping), `service` (no
+     * variants, no shipping), `digital` (has variants, no shipping). Unknown
+     * values fall back to `physical` store-side — prefer being explicit.
+     */
+    productTypeSlug: ProductTypeSlug;
+    price: number;
+    description?: string;
+    vendor?: string;
+    tags?: string[];
+    costPrice?: number;
+    barcode?: string;
+    weight?: number;
+    /** Remote image URLs — validated + ingested store-side. Max 20. */
+    images?: string[];
+    /**
+     * Sales channel handles to publish this product on. Omit to publish on the
+     * store's default channel.
+     */
+    channels?: string[];
+    /** Per-country or per-location stock. Import locations before products when using `locationCode`. */
+    inventory?: InventoryEntry[];
+}
+/** One row that failed during a product import. Mirrors the store import error. */
+export interface ImportProductError {
+    /** Zero-based index into the `products` array you sent. */
+    row: number;
+    /** Handle of the offending product, when the row carried one. */
+    handle?: string;
+    /** Machine code, e.g. `IMAGE_INVALID_URL`, `UNKNOWN_LOCATION`, `UNKNOWN_PRODUCT_TYPE`. */
+    code: string;
+    message: string;
+    /** Extra diagnostic payload, when the store attaches one. */
+    context?: Record<string, unknown>;
+}
+/** Aggregate result of `merchants.importProducts()`. */
+export interface ImportProductsResult {
+    /** Rows received (== `products.length`, or the rows that passed validation). */
+    total: number;
+    created: number;
+    updated: number;
+    skipped: number;
+    /** Per-row failures. Empty on full success. */
+    errors: ImportProductError[];
+}
+/** One warehouse / pickup point to seed into a merchant's inventory. Upserted by `code`. */
+export interface ProvisionLocation {
+    /** Your stable identifier — the upsert key (e.g. warehouse id). Max 60 chars. */
+    code: string;
+    /** Display name shown in the store admin. Max 120 chars. */
+    name: string;
+    /** ISO-3166-1 alpha-2 (e.g. `"SV"`, `"GT"`, `"HN"`). */
+    country: string;
+    /** Location type hint (e.g. `warehouse`, `pickup`, `shop`). */
+    type?: string;
+    address?: string;
+    city?: string;
+    postalCode?: string;
+    phone?: string;
+    email?: string;
+    isActive?: boolean;
+    /** Whether this location ships orders. Default `true`. */
+    handlesFulfillment?: boolean;
+    /** Whether customers can pick up here. Default `false`. */
+    pickupAvailable?: boolean;
+    /** Preferred carrier code for shipments dispatched from this location. */
+    preferredCarrier?: string;
+    latitude?: number;
+    longitude?: number;
+    referencePoint?: string;
+}
+/** Aggregate result of `merchants.importLocations()`. */
+export interface ImportLocationsResult {
+    total: number;
+    created: number;
+    updated: number;
+    errors: Array<{
+        row: number;
+        code: string;
+        message: string;
+    }>;
+}
 export interface ListMerchantsQuery {
     page?: number;
     /** Max 100. */
@@ -84,6 +223,8 @@ export interface Page<T> {
 }
 /** Max length the platform accepts for `CreateMerchantInput.externalId`. */
 export declare const MAX_EXTERNAL_ID_LENGTH = 120;
+/** Max length the platform accepts for `CreateMerchantInput.idempotencyKey`. */
+export declare const MAX_IDEMPOTENCY_KEY_LENGTH = 120;
 /** Runtime states where the platform accepts `activate` (first run or retry). */
 export declare function canActivate(runtime: MerchantRuntimeStatus): boolean;
 /** States that will not change without a new action from the partner. */

package/dist/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.2.0";
+export declare const SDK_VERSION = "0.4.0";

package/dist/esm/version.js

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

package/package.json

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