brainerce 1.28.1 → 1.31.0

package/dist/index.d.ts

@@ -2736,6 +2736,37 @@ interface VariantInventoryResponse {
     canPurchase: boolean;
     lastInventorySyncAt?: string | null;
 }
+/**
+ * A media-library asset returned by the admin media endpoints
+ * (`/v1/media/*`). The CDN `url` is what you store in `images[].url` on a
+ * product. Requires an admin API key with `media:read` / `media:write`.
+ */
+interface MediaAsset {
+    id: string;
+    url: string;
+    key: string;
+    thumbnailUrl: string | null;
+    mimeType: string;
+    width: number | null;
+    height: number | null;
+    size: number;
+    /** Display name / title in the media library. */
+    name: string;
+    /** Accessibility alt text. */
+    alt: string | null;
+    createdAt: string;
+}
+/** Query params for `listMedia`. */
+interface ListMediaParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+}
+/** Body for `updateMediaAsset` — default metadata. */
+interface UpdateMediaAssetInput {
+    alt?: string;
+    name?: string;
+}
 type RefundType = 'full' | 'partial';
 interface RefundLineItem {
     lineItemId: string;
@@ -3807,6 +3838,35 @@ interface PublicRegionPaymentProvider {
 interface PublicRegionDetail extends PublicRegion {
     paymentProviders: PublicRegionPaymentProvider[];
 }
+/**
+ * Server-side region resolution for a buyer country (storefront seam).
+ * `matched=true` → the country was explicitly listed by a region. `false` →
+ * fell back to the default region (or `region=null` when no default exists).
+ */
+interface AutoRegionResponse {
+    region: PublicRegion | null;
+    matched: boolean;
+    /** Upper-cased ISO-3166-1 alpha-2. Empty string when caller omitted `country`. */
+    country: string;
+}
+/**
+ * Non-binding tax preview for PDP / PLP / cart. The authoritative calculation
+ * still runs at checkout against the full shipping address (state / postal /
+ * per-class). Render with an "Estimate" affordance.
+ */
+interface TaxEstimateResponse {
+    appliesTax: boolean;
+    /** Percent — e.g. 18 for 18%. `null` when no matching rule. */
+    rate: number | null;
+    rateName: string | null;
+    /** Tax portion of `subtotal` at the store's `pricesIncludeTax` mode. */
+    estimatedTax: number;
+    pricesIncludeTax: boolean;
+    /** Store currency — the cart / order currency, unchanged by FX display overlay. */
+    currency: string;
+    /** Disclaimer copy — always present to surface the "preview, not binding" nature. */
+    note: string;
+}
 interface CreateRegionDto {
     name: string;
     /** ISO 4217 */
@@ -5553,6 +5613,50 @@ declare class BrainerceClient {
      * ```
      */
     updateVariantInventory(productId: string, variantId: string, data: UpdateVariantInventoryDto): Promise<VariantInventoryResponse>;
+    /**
+     * Upload a file, or ingest a remote image URL, into the store's media
+     * library. Requires an admin API key with the `media:write` scope. Returns
+     * the created asset — store `asset.url` in `images[].url` on a product.
+     *
+     * @example
+     * ```typescript
+     * // Upload a File/Blob:
+     * const asset = await client.uploadMedia(fileInput.files[0]);
+     * // …or ingest by URL (fetched server-side via the SSRF-safe downloader):
+     * const asset = await client.uploadMedia({ sourceUrl: 'https://example.com/photo.jpg' });
+     * await client.updateProduct('prod_123', {
+     *   images: [{ url: asset.url, position: 0, isMain: true }],
+     * });
+     * ```
+     */
+    uploadMedia(input: File | Blob | {
+        sourceUrl: string;
+    }): Promise<MediaAsset>;
+    /**
+     * List media-library assets (paginated). Requires `media:read`.
+     *
+     * @example
+     * ```typescript
+     * const { data, meta } = await client.listMedia({ page: 1, limit: 50, search: 'hero' });
+     * ```
+     */
+    listMedia(params?: ListMediaParams): Promise<PaginatedResponse<MediaAsset>>;
+    /**
+     * Get a single media asset by ID. Requires `media:read`.
+     */
+    getMedia(id: string): Promise<MediaAsset>;
+    /**
+     * Update an asset's default metadata (`alt` / `name`). Requires `media:write`.
+     */
+    updateMediaAsset(id: string, data: UpdateMediaAssetInput): Promise<MediaAsset>;
+    /**
+     * Delete a media asset — soft-deletes it and removes its key from every
+     * product/variant/category/brand/store/modifier that referenced it.
+     * Requires `media:write`.
+     */
+    deleteMedia(id: string): Promise<{
+        success: boolean;
+    }>;
     /**
      * Get a list of orders with pagination
      */
@@ -8616,6 +8720,33 @@ declare class BrainerceClient {
      * `countries` includes `country`, else the default region, else null.
      */
     detectRegion(country: string, regions: Array<Region | PublicRegion>): Region | PublicRegion | null;
+    /**
+     * Server-side region resolution in one round trip (storefront seam). Pair
+     * with the country your edge runtime extracts — Cloudflare `CF-IPCountry`,
+     * Vercel `request.geo?.country`, Fastly `client-geo-country`, etc.
+     *
+     * Brainerce does NOT derive the country from the request IP server-side
+     * because the storefront server is what reaches the backend (not the end-
+     * customer). The storefront must extract + forward the country.
+     *
+     * Returns `{ region, matched, country }` — `matched=true` means the country
+     * was explicitly listed by a region; `false` means we fell back to the
+     * default region (or `region=null` if no default exists either).
+     */
+    getAutoRegion(country?: string): Promise<AutoRegionResponse>;
+    /**
+     * Non-binding tax preview for PDP / PLP / cart. Pass the buyer's country
+     * (from your edge runtime — same source as `getAutoRegion`) and the current
+     * items subtotal in the store currency. The authoritative tax still runs
+     * at checkout — render with an "Estimate" affordance.
+     *
+     * Returns `appliesTax=false` when tax is disabled, the country is missing,
+     * or no active rate covers it.
+     */
+    estimateTax(params: {
+        country?: string;
+        subtotal: number;
+    }): Promise<TaxEstimateResponse>;
     /**
      * List the store's tax classes (public, no apiKey — storeId mode). Storefront-
      * safe fields only (id/name/slug/description/isDefault) for transparency UIs

package/dist/index.js

@@ -1404,6 +1404,70 @@ var BrainerceClient = class {
       data
     );
   }
+  // -------------------- Media Library (Admin) --------------------
+  /**
+   * Upload a file, or ingest a remote image URL, into the store's media
+   * library. Requires an admin API key with the `media:write` scope. Returns
+   * the created asset — store `asset.url` in `images[].url` on a product.
+   *
+   * @example
+   * ```typescript
+   * // Upload a File/Blob:
+   * const asset = await client.uploadMedia(fileInput.files[0]);
+   * // …or ingest by URL (fetched server-side via the SSRF-safe downloader):
+   * const asset = await client.uploadMedia({ sourceUrl: 'https://example.com/photo.jpg' });
+   * await client.updateProduct('prod_123', {
+   *   images: [{ url: asset.url, position: 0, isMain: true }],
+   * });
+   * ```
+   */
+  async uploadMedia(input) {
+    const formData = new FormData();
+    if (typeof input === "object" && "sourceUrl" in input) {
+      formData.append("sourceUrl", input.sourceUrl);
+    } else {
+      formData.append("file", input);
+    }
+    return this.adminRequest("POST", "/api/v1/media", formData);
+  }
+  /**
+   * List media-library assets (paginated). Requires `media:read`.
+   *
+   * @example
+   * ```typescript
+   * const { data, meta } = await client.listMedia({ page: 1, limit: 50, search: 'hero' });
+   * ```
+   */
+  async listMedia(params) {
+    return this.adminRequest("GET", "/api/v1/media", void 0, {
+      page: params?.page,
+      limit: params?.limit,
+      search: params?.search
+    });
+  }
+  /**
+   * Get a single media asset by ID. Requires `media:read`.
+   */
+  async getMedia(id) {
+    return this.adminRequest("GET", `/api/v1/media/${encodePathSegment(id)}`);
+  }
+  /**
+   * Update an asset's default metadata (`alt` / `name`). Requires `media:write`.
+   */
+  async updateMediaAsset(id, data) {
+    return this.adminRequest("PATCH", `/api/v1/media/${encodePathSegment(id)}`, data);
+  }
+  /**
+   * Delete a media asset — soft-deletes it and removes its key from every
+   * product/variant/category/brand/store/modifier that referenced it.
+   * Requires `media:write`.
+   */
+  async deleteMedia(id) {
+    return this.adminRequest(
+      "DELETE",
+      `/api/v1/media/${encodePathSegment(id)}`
+    );
+  }
   // -------------------- Orders --------------------
   /**
    * Get a list of orders with pagination
@@ -7054,6 +7118,44 @@ var BrainerceClient = class {
     const code = country.toUpperCase();
     return regions.find((r) => r.countries.includes(code)) ?? regions.find((r) => r.isDefault) ?? null;
   }
+  /**
+   * Server-side region resolution in one round trip (storefront seam). Pair
+   * with the country your edge runtime extracts — Cloudflare `CF-IPCountry`,
+   * Vercel `request.geo?.country`, Fastly `client-geo-country`, etc.
+   *
+   * Brainerce does NOT derive the country from the request IP server-side
+   * because the storefront server is what reaches the backend (not the end-
+   * customer). The storefront must extract + forward the country.
+   *
+   * Returns `{ region, matched, country }` — `matched=true` means the country
+   * was explicitly listed by a region; `false` means we fell back to the
+   * default region (or `region=null` if no default exists either).
+   */
+  async getAutoRegion(country) {
+    return this.storefrontRequest(
+      "GET",
+      "/regions/auto",
+      void 0,
+      country ? { country } : void 0
+    );
+  }
+  /**
+   * Non-binding tax preview for PDP / PLP / cart. Pass the buyer's country
+   * (from your edge runtime — same source as `getAutoRegion`) and the current
+   * items subtotal in the store currency. The authoritative tax still runs
+   * at checkout — render with an "Estimate" affordance.
+   *
+   * Returns `appliesTax=false` when tax is disabled, the country is missing,
+   * or no active rate covers it.
+   */
+  async estimateTax(params) {
+    return this.storefrontRequest(
+      "GET",
+      "/tax/estimate",
+      void 0,
+      params.country ? { country: params.country, subtotal: params.subtotal } : { subtotal: params.subtotal }
+    );
+  }
   // -------------------- Tax Classes (Storefront mode, public — no apiKey) --------------------
   /**
    * List the store's tax classes (public, no apiKey — storeId mode). Storefront-

package/dist/index.mjs

@@ -1334,6 +1334,70 @@ var BrainerceClient = class {
       data
     );
   }
+  // -------------------- Media Library (Admin) --------------------
+  /**
+   * Upload a file, or ingest a remote image URL, into the store's media
+   * library. Requires an admin API key with the `media:write` scope. Returns
+   * the created asset — store `asset.url` in `images[].url` on a product.
+   *
+   * @example
+   * ```typescript
+   * // Upload a File/Blob:
+   * const asset = await client.uploadMedia(fileInput.files[0]);
+   * // …or ingest by URL (fetched server-side via the SSRF-safe downloader):
+   * const asset = await client.uploadMedia({ sourceUrl: 'https://example.com/photo.jpg' });
+   * await client.updateProduct('prod_123', {
+   *   images: [{ url: asset.url, position: 0, isMain: true }],
+   * });
+   * ```
+   */
+  async uploadMedia(input) {
+    const formData = new FormData();
+    if (typeof input === "object" && "sourceUrl" in input) {
+      formData.append("sourceUrl", input.sourceUrl);
+    } else {
+      formData.append("file", input);
+    }
+    return this.adminRequest("POST", "/api/v1/media", formData);
+  }
+  /**
+   * List media-library assets (paginated). Requires `media:read`.
+   *
+   * @example
+   * ```typescript
+   * const { data, meta } = await client.listMedia({ page: 1, limit: 50, search: 'hero' });
+   * ```
+   */
+  async listMedia(params) {
+    return this.adminRequest("GET", "/api/v1/media", void 0, {
+      page: params?.page,
+      limit: params?.limit,
+      search: params?.search
+    });
+  }
+  /**
+   * Get a single media asset by ID. Requires `media:read`.
+   */
+  async getMedia(id) {
+    return this.adminRequest("GET", `/api/v1/media/${encodePathSegment(id)}`);
+  }
+  /**
+   * Update an asset's default metadata (`alt` / `name`). Requires `media:write`.
+   */
+  async updateMediaAsset(id, data) {
+    return this.adminRequest("PATCH", `/api/v1/media/${encodePathSegment(id)}`, data);
+  }
+  /**
+   * Delete a media asset — soft-deletes it and removes its key from every
+   * product/variant/category/brand/store/modifier that referenced it.
+   * Requires `media:write`.
+   */
+  async deleteMedia(id) {
+    return this.adminRequest(
+      "DELETE",
+      `/api/v1/media/${encodePathSegment(id)}`
+    );
+  }
   // -------------------- Orders --------------------
   /**
    * Get a list of orders with pagination
@@ -6984,6 +7048,44 @@ var BrainerceClient = class {
     const code = country.toUpperCase();
     return regions.find((r) => r.countries.includes(code)) ?? regions.find((r) => r.isDefault) ?? null;
   }
+  /**
+   * Server-side region resolution in one round trip (storefront seam). Pair
+   * with the country your edge runtime extracts — Cloudflare `CF-IPCountry`,
+   * Vercel `request.geo?.country`, Fastly `client-geo-country`, etc.
+   *
+   * Brainerce does NOT derive the country from the request IP server-side
+   * because the storefront server is what reaches the backend (not the end-
+   * customer). The storefront must extract + forward the country.
+   *
+   * Returns `{ region, matched, country }` — `matched=true` means the country
+   * was explicitly listed by a region; `false` means we fell back to the
+   * default region (or `region=null` if no default exists either).
+   */
+  async getAutoRegion(country) {
+    return this.storefrontRequest(
+      "GET",
+      "/regions/auto",
+      void 0,
+      country ? { country } : void 0
+    );
+  }
+  /**
+   * Non-binding tax preview for PDP / PLP / cart. Pass the buyer's country
+   * (from your edge runtime — same source as `getAutoRegion`) and the current
+   * items subtotal in the store currency. The authoritative tax still runs
+   * at checkout — render with an "Estimate" affordance.
+   *
+   * Returns `appliesTax=false` when tax is disabled, the country is missing,
+   * or no active rate covers it.
+   */
+  async estimateTax(params) {
+    return this.storefrontRequest(
+      "GET",
+      "/tax/estimate",
+      void 0,
+      params.country ? { country: params.country, subtotal: params.subtotal } : { subtotal: params.subtotal }
+    );
+  }
   // -------------------- Tax Classes (Storefront mode, public — no apiKey) --------------------
   /**
    * List the store's tax classes (public, no apiKey — storeId mode). Storefront-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.28.1",
+  "version": "1.31.0",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -10,6 +10,11 @@
       "types": "./dist/index.d.ts",
       "require": "./dist/index.js",
       "import": "./dist/index.mjs"
+    },
+    "./bot": {
+      "types": "./dist/bot/index.d.ts",
+      "require": "./dist/bot/index.js",
+      "import": "./dist/bot/index.mjs"
     }
   },
   "files": [
@@ -17,7 +22,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "build": "tsup src/index.ts --format cjs,esm --dts && tsup src/bot/index.ts --format cjs,esm --dts --out-dir dist/bot && tsup src/bot/bootstrap.ts --format iife --minify --out-dir dist/bot",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "lint": "eslint \"src/**/*.ts\"",
     "test": "vitest run",