@vivoa/partner-sdk 0.2.0 → 0.3.0

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

@@ -155,7 +155,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|products)$/);
         if (method === 'GET' && path === '/me')
             return this.profile(op);
         if (method === 'POST' && path === '/me/rotate-secret') {
@@ -202,6 +202,20 @@ 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 === 'products') {
+                    const products = Array.isArray(body.products) ? body.products : [];
+                    return { created: products.length, updated: 0, skipped: 0, failed: 0 };
+                }
             }
         }
         if (method === 'GET' && path === '/fleet/analytics')

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 ImportProductsResult, type ListMerchantsQuery, type Merchant, type MerchantAdminTicket, type MerchantStatus, type Page, type PluginProvisionInput, type PluginProvisionResult, 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 {
@@ -39,5 +39,19 @@ 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 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

@@ -72,6 +72,30 @@ 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 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) {

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 ImportProductsResult, type Merchant, type MerchantRuntimeStatus, type MerchantStatus, type PluginProvisionInput, type PluginProvisionResult, type ProvisionProduct } from '../../domain/merchant.ts';
+export type ProvisionPhase = 'found' | 'created' | 'activating' | 'waiting' | 'seeding' | 'settled';
 export interface ProvisionProgress {
     phase: ProvisionPhase;
     merchantId: string;
@@ -18,12 +18,24 @@ 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[];
+    /** 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. */
     created: boolean;
+    /** Per-plugin seed outcome, when `options.plugins` was supplied. */
+    plugins?: PluginProvisionResult[];
+    /** Catalog seed outcome, when `options.products` was supplied. */
+    products?: ImportProductsResult;
 }
 /**
  * "Give me a live store" — the one call most partners need.

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

@@ -45,11 +45,43 @@ class ProvisionStoreUseCase {
                 pollIntervalMs: options.pollIntervalMs,
             });
         }
-        progress('settled', merchant, status.deployStatus);
         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}"`);
         }
-        return { merchant: { ...merchant, runtime: status.deployStatus, domain: status.domain }, status, created };
+        // 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.
+        let plugins;
+        let products;
+        if (options.plugins?.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.products?.length) {
+                products = await this.merchants
+                    .importProducts(merchant.id, options.products)
+                    .catch(() => ({ created: 0, updated: 0, skipped: 0, failed: options.products.length }));
+            }
+        }
+        progress('settled', merchant, status.deployStatus);
+        return {
+            merchant: { ...merchant, runtime: status.deployStatus, domain: status.domain },
+            status,
+            created,
+            ...(plugins ? { plugins } : {}),
+            ...(products ? { products } : {}),
+        };
     }
     /** Polls `GET /status` until the runtime leaves `creating`. */
     async waitUntilSettled(merchantId, options = {}) {

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

@@ -65,6 +65,56 @@ 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;
+}
+/** 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;
+    price: number;
+    description?: string;
+    vendor?: string;
+    tags?: string[];
+    costPrice?: number;
+    barcode?: string;
+    weight?: number;
+    /** Remote image URLs — validated + ingested store-side. */
+    images?: string[];
+    /** Per-country stock. */
+    inventory?: Array<{
+        country: string;
+        quantity: number;
+    }>;
+}
+/** Aggregate result of `merchants.importProducts()`. */
+export interface ImportProductsResult {
+    created: number;
+    updated: number;
+    skipped: number;
+    failed: number;
+}
 export interface ListMerchantsQuery {
     page?: number;
     /** Max 100. */

package/dist/cjs/version.d.ts

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

package/dist/cjs/version.js

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

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

@@ -152,7 +152,7 @@ export class FakeVivoa {
     async route(op, method, url, rawBody) {
         const path = url.pathname.replace(/^\/partner\/v1/, '');
         const body = rawBody ? JSON.parse(rawBody) : {};
-        const merchantRoute = path.match(/^\/merchants\/([^/]+)\/(status|activate|suspend|reactivate|admin-ticket)$/);
+        const merchantRoute = path.match(/^\/merchants\/([^/]+)\/(status|activate|suspend|reactivate|admin-ticket|plugins|products)$/);
         if (method === 'GET' && path === '/me')
             return this.profile(op);
         if (method === 'POST' && path === '/me/rotate-secret') {
@@ -199,6 +199,20 @@ export class FakeVivoa {
                         redirectUrl: `${base}/auth/admin-redeem?token=fake-${merchant.id}${returnPath === '/admin' ? '' : `&rp=${encodeURIComponent(returnPath)}`}`,
                     };
                 }
+                if (action === 'plugins') {
+                    const plugins = Array.isArray(body.plugins) ? body.plugins : [];
+                    return {
+                        plugins: plugins.map((p) => ({
+                            code: p.code,
+                            installed: true,
+                            configured: true,
+                        })),
+                    };
+                }
+                if (action === 'products') {
+                    const products = Array.isArray(body.products) ? body.products : [];
+                    return { created: products.length, updated: 0, skipped: 0, failed: 0 };
+                }
             }
         }
         if (method === 'GET' && path === '/fleet/analytics')

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

@@ -1,5 +1,5 @@
 import type { SignedHttpClient } from '../signed-http.ts';
-import { type AdminTicketOptions, type CreateMerchantInput, type ListMerchantsQuery, type Merchant, type MerchantAdminTicket, type MerchantStatus, type Page } from '../../domain/merchant.ts';
+import { type AdminTicketOptions, type CreateMerchantInput, type ImportProductsResult, type ListMerchantsQuery, type Merchant, type MerchantAdminTicket, type MerchantStatus, type Page, type PluginProvisionInput, type PluginProvisionResult, 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 {
@@ -39,5 +39,19 @@ 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 products into the merchant's catalog (URL images, per-country
+     * inventory). Idempotent on `handle`, so re-running updates rather than
+     * duplicates. 403 if the merchant is not in your fleet.
+     */
+    importProducts(merchantId: string, products: ProvisionProduct[]): Promise<ImportProductsResult>;
 }
 export declare function validateCreate(input: CreateMerchantInput): void;

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

@@ -68,6 +68,30 @@ export class MerchantsResource {
             body: options.returnPath ? { returnPath: options.returnPath } : {},
         });
     }
+    /**
+     * Installs + configures plugins on the merchant's store (credentials, pickup
+     * origin, activation). Idempotent — config is merged, not replaced — so it
+     * doubles as a re-sync. 403 if the merchant is not in your fleet.
+     */
+    async configurePlugins(merchantId, plugins) {
+        if (plugins.length === 0)
+            throw new VivoaValidationError('plugins must not be empty');
+        return this.http.request('POST', `/partner/v1/merchants/${encodeId(merchantId)}/plugins`, {
+            body: { plugins },
+        });
+    }
+    /**
+     * Bulk-imports products into the merchant's catalog (URL images, per-country
+     * inventory). Idempotent on `handle`, so re-running updates rather than
+     * duplicates. 403 if the merchant is not in your fleet.
+     */
+    async importProducts(merchantId, products) {
+        if (products.length === 0)
+            throw new VivoaValidationError('products must not be empty');
+        return this.http.request('POST', `/partner/v1/merchants/${encodeId(merchantId)}/products`, {
+            body: { products },
+        });
+    }
 }
 function encodeId(id) {
     if (!id)

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

@@ -1,7 +1,7 @@
 import type { Clock } from '../../ports/clock.port.ts';
 import type { MerchantsResource } from '../resources/merchants.ts';
-import { type CreateMerchantInput, type Merchant, type MerchantRuntimeStatus, type MerchantStatus } from '../../domain/merchant.ts';
-export type ProvisionPhase = 'found' | 'created' | 'activating' | 'waiting' | 'settled';
+import { type CreateMerchantInput, type ImportProductsResult, type Merchant, type MerchantRuntimeStatus, type MerchantStatus, type PluginProvisionInput, type PluginProvisionResult, type ProvisionProduct } from '../../domain/merchant.ts';
+export type ProvisionPhase = 'found' | 'created' | 'activating' | 'waiting' | 'seeding' | 'settled';
 export interface ProvisionProgress {
     phase: ProvisionPhase;
     merchantId: string;
@@ -18,12 +18,24 @@ 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[];
+    /** 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. */
     created: boolean;
+    /** Per-plugin seed outcome, when `options.plugins` was supplied. */
+    plugins?: PluginProvisionResult[];
+    /** Catalog seed outcome, when `options.products` was supplied. */
+    products?: ImportProductsResult;
 }
 /**
  * "Give me a live store" — the one call most partners need.

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

@@ -42,11 +42,43 @@ export class ProvisionStoreUseCase {
                 pollIntervalMs: options.pollIntervalMs,
             });
         }
-        progress('settled', merchant, status.deployStatus);
         if (status.deployStatus === 'failed' || status.deployStatus === 'unknown') {
+            progress('settled', merchant, status.deployStatus);
             throw new VivoaProvisioningFailedError(merchant.id, `the platform reported runtime status "${status.deployStatus}"`);
         }
-        return { merchant: { ...merchant, runtime: status.deployStatus, domain: status.domain }, status, created };
+        // 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.
+        let plugins;
+        let products;
+        if (options.plugins?.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.products?.length) {
+                products = await this.merchants
+                    .importProducts(merchant.id, options.products)
+                    .catch(() => ({ created: 0, updated: 0, skipped: 0, failed: options.products.length }));
+            }
+        }
+        progress('settled', merchant, status.deployStatus);
+        return {
+            merchant: { ...merchant, runtime: status.deployStatus, domain: status.domain },
+            status,
+            created,
+            ...(plugins ? { plugins } : {}),
+            ...(products ? { products } : {}),
+        };
     }
     /** Polls `GET /status` until the runtime leaves `creating`. */
     async waitUntilSettled(merchantId, options = {}) {

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

@@ -65,6 +65,56 @@ 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;
+}
+/** 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;
+    price: number;
+    description?: string;
+    vendor?: string;
+    tags?: string[];
+    costPrice?: number;
+    barcode?: string;
+    weight?: number;
+    /** Remote image URLs — validated + ingested store-side. */
+    images?: string[];
+    /** Per-country stock. */
+    inventory?: Array<{
+        country: string;
+        quantity: number;
+    }>;
+}
+/** Aggregate result of `merchants.importProducts()`. */
+export interface ImportProductsResult {
+    created: number;
+    updated: number;
+    skipped: number;
+    failed: number;
+}
 export interface ListMerchantsQuery {
     page?: number;
     /** Max 100. */

package/dist/esm/version.d.ts

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

package/dist/esm/version.js

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

package/package.json

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