brainerce 2.0.0 → 2.0.2

package/dist/index.js

@@ -204,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.0.0";
+var SDK_VERSION = "2.0.1";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -763,7 +763,7 @@ var _BrainerceClient = class _BrainerceClient {
     }
     if (!options.salesChannelId && options.connectionId) {
       console.warn(
-        "BrainerceClient: `connectionId` is deprecated \u2014 use `salesChannelId` instead. `connectionId` will be removed in SDK 2.0."
+        "BrainerceClient: `connectionId` is deprecated \u2014 use `salesChannelId` instead. `connectionId` is a permanent backward-compat alias and is not scheduled for removal."
       );
     }
     if (options.apiKey && typeof window !== "undefined") {
@@ -2639,6 +2639,36 @@ var _BrainerceClient = class _BrainerceClient {
   async getOrderShipments(orderId) {
     return this.request("GET", `/api/v1/orders/${encodePathSegment(orderId)}/shipments`);
   }
+  /**
+   * Buy a return label the merchant sends to their customer to print.
+   *
+   * Requires admin mode (`apiKey`) with `FULFILL_ORDERS` permission — it
+   * spends the store's carrier balance, same as {@link createShippingLabel}.
+   *
+   * Unlike {@link createShippingLabel}, this is **not** on the API-key `/v1`
+   * surface — it calls the internal `/api/orders/:id/shipments/return-label`
+   * route, which takes `storeId` explicitly rather than resolving it from the
+   * key. There is no `rateId` in the body: a return is quoted and bought in
+   * one call at the shipping app, because the carrier fixes a shipment as a
+   * return when it is created and will not amend it afterwards.
+   *
+   * @example
+   * ```typescript
+   * const label = await client.createReturnLabel('store_abc', 'order_abc', {
+   *   reason: 'Wrong size',
+   *   returnForShipmentId: 'shp_original123',
+   * });
+   * console.log('Return label URL:', label.labelUrl);
+   * ```
+   */
+  async createReturnLabel(storeId, orderId, data) {
+    return this.adminRequest(
+      "POST",
+      `/api/orders/${encodePathSegment(orderId)}/shipments/return-label`,
+      data,
+      { storeId }
+    );
+  }
   /**
    * Cancel an order.
    *
@@ -10074,6 +10104,156 @@ var _BrainerceClient = class _BrainerceClient {
       `/api/v1/oauth-providers/${encodePathSegment(provider)}`
     );
   }
+  // -------------------- Translations (Admin) --------------------
+  // These methods require Admin mode (apiKey) with a scope-bearing key —
+  // `products:read`/`products:write` cover most entity types via
+  // StorePermissionGuard's STORE_PERMISSION_TO_SCOPE mapping (VIEW_PRODUCTS /
+  // EDIT_PRODUCTS). Routes: /api/stores/:storeId/translations/...
+  //
+  // Reads and writes the SAME `translations` JSON blob the dashboard editor
+  // uses — this is not a separate translation system, it's API-key access to
+  // the dashboard's own persistence path. Use it for bulk-importing
+  // pre-translated content or automating locale coverage without a human in
+  // the dashboard.
+  /**
+   * Get translation completeness across every translatable entity type, for
+   * one or more locales. Useful as a pre-flight before a bulk import to see
+   * which entity types/locales still need coverage.
+   * Requires Admin mode (apiKey).
+   *
+   * @param storeId - Store to inspect.
+   * @param locales - BCP-47 locale codes to check (e.g. `['he', 'fr']`). Omit
+   *   or pass an empty array to get rows with `total` populated but no
+   *   locale breakdown.
+   *
+   * @example
+   * ```typescript
+   * const status = await client.getTranslationStatus('store_123', ['he', 'fr']);
+   * const blogHe = status.find((s) => s.entityType === 'blogPost' && s.locale === 'he');
+   * console.log(`${blogHe?.missing} blog posts still need Hebrew`);
+   * ```
+   */
+  async getTranslationStatus(storeId, locales) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${encodePathSegment(storeId)}/translations/status`,
+      void 0,
+      locales && locales.length > 0 ? { locales: locales.join(",") } : void 0
+    );
+  }
+  /**
+   * Get every persisted translation for a single entity, keyed by locale.
+   * Requires Admin mode (apiKey).
+   *
+   * @example
+   * ```typescript
+   * const translations = await client.getTranslations('store_123', 'product', 'prod_abc');
+   * console.log(translations.he?.name); // Hebrew product name, if set
+   * ```
+   */
+  async getTranslations(storeId, entityType, entityId) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}`
+    );
+  }
+  /**
+   * Set/update one locale's translation for an entity. Only the fields valid
+   * for `entityType` are persisted (e.g. `title`/`excerpt`/`content` for
+   * `blogPost`, `name`/`description` for `category`) — fields outside that
+   * entity's allowlist are silently ignored server-side, and omitted fields
+   * leave any existing translation for them untouched (this is a merge, not
+   * a replace, of the locale's fields).
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @example
+   * ```typescript
+   * // Bulk-import a pre-translated blog post
+   * await client.setTranslation('store_123', 'blogPost', 'post_abc', 'fr', {
+   *   title: 'Le titre en français',
+   *   excerpt: "L'extrait en français",
+   *   content: '<p>Le contenu en français</p>',
+   * });
+   * ```
+   */
+  async setTranslation(storeId, entityType, entityId, locale, fields) {
+    return this.adminRequest(
+      "PUT",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/${encodePathSegment(locale)}`,
+      fields
+    );
+  }
+  /**
+   * Delete one locale's translation for an entity. The entity's base
+   * (default-locale) fields are unaffected.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   */
+  async deleteTranslation(storeId, entityType, entityId, locale) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/${encodePathSegment(locale)}`
+    );
+  }
+  /**
+   * AI-translate a single entity into one target locale and persist the
+   * result inline (synchronous — the response already reflects the write).
+   * Only fields that are still empty for `targetLocale` are filled; existing
+   * translated values are never overwritten.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @param sourceFields - Optional override of the source-language text to
+   *   translate from (e.g. unsaved edits from an open editor), instead of the
+   *   entity's persisted base fields. Keys outside the entity's translatable
+   *   field set are ignored.
+   *
+   * @example
+   * ```typescript
+   * const translations = await client.aiTranslateSingle('store_123', {
+   *   entityType: 'product',
+   *   entityId: 'prod_abc',
+   *   targetLocale: 'he',
+   * });
+   * ```
+   */
+  async aiTranslateSingle(storeId, input) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${encodePathSegment(storeId)}/translations/ai-translate-single`,
+      input
+    );
+  }
+  /**
+   * Bulk AI-translate — enqueues a background job per entity (and, for
+   * `entityType: 'attribute'`, one per attribute option too) rather than
+   * translating inline. Returns the number of jobs queued, not the finished
+   * translations; poll `getTranslationStatus` or `getTranslations` to see
+   * results land.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @param entityIds - Optional explicit ids to translate. Omit to target
+   *   every entity of `entityType` in the store that isn't already fully
+   *   translated for `targetLocale`.
+   *
+   * @example
+   * ```typescript
+   * // Translate every blog post missing French coverage
+   * const { queued } = await client.aiTranslateBulk('store_123', {
+   *   entityType: 'blogPost',
+   *   targetLocale: 'fr',
+   * });
+   * ```
+   */
+  async aiTranslateBulk(storeId, input) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${encodePathSegment(storeId)}/translations/ai-translate`,
+      input
+    );
+  }
 };
 /**
  * Fields present on `getAddressDetails().address` that the address endpoints

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.0.0";
+var SDK_VERSION = "2.0.1";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -674,7 +674,7 @@ var _BrainerceClient = class _BrainerceClient {
     }
     if (!options.salesChannelId && options.connectionId) {
       console.warn(
-        "BrainerceClient: `connectionId` is deprecated \u2014 use `salesChannelId` instead. `connectionId` will be removed in SDK 2.0."
+        "BrainerceClient: `connectionId` is deprecated \u2014 use `salesChannelId` instead. `connectionId` is a permanent backward-compat alias and is not scheduled for removal."
       );
     }
     if (options.apiKey && typeof window !== "undefined") {
@@ -2550,6 +2550,36 @@ var _BrainerceClient = class _BrainerceClient {
   async getOrderShipments(orderId) {
     return this.request("GET", `/api/v1/orders/${encodePathSegment(orderId)}/shipments`);
   }
+  /**
+   * Buy a return label the merchant sends to their customer to print.
+   *
+   * Requires admin mode (`apiKey`) with `FULFILL_ORDERS` permission — it
+   * spends the store's carrier balance, same as {@link createShippingLabel}.
+   *
+   * Unlike {@link createShippingLabel}, this is **not** on the API-key `/v1`
+   * surface — it calls the internal `/api/orders/:id/shipments/return-label`
+   * route, which takes `storeId` explicitly rather than resolving it from the
+   * key. There is no `rateId` in the body: a return is quoted and bought in
+   * one call at the shipping app, because the carrier fixes a shipment as a
+   * return when it is created and will not amend it afterwards.
+   *
+   * @example
+   * ```typescript
+   * const label = await client.createReturnLabel('store_abc', 'order_abc', {
+   *   reason: 'Wrong size',
+   *   returnForShipmentId: 'shp_original123',
+   * });
+   * console.log('Return label URL:', label.labelUrl);
+   * ```
+   */
+  async createReturnLabel(storeId, orderId, data) {
+    return this.adminRequest(
+      "POST",
+      `/api/orders/${encodePathSegment(orderId)}/shipments/return-label`,
+      data,
+      { storeId }
+    );
+  }
   /**
    * Cancel an order.
    *
@@ -9985,6 +10015,156 @@ var _BrainerceClient = class _BrainerceClient {
       `/api/v1/oauth-providers/${encodePathSegment(provider)}`
     );
   }
+  // -------------------- Translations (Admin) --------------------
+  // These methods require Admin mode (apiKey) with a scope-bearing key —
+  // `products:read`/`products:write` cover most entity types via
+  // StorePermissionGuard's STORE_PERMISSION_TO_SCOPE mapping (VIEW_PRODUCTS /
+  // EDIT_PRODUCTS). Routes: /api/stores/:storeId/translations/...
+  //
+  // Reads and writes the SAME `translations` JSON blob the dashboard editor
+  // uses — this is not a separate translation system, it's API-key access to
+  // the dashboard's own persistence path. Use it for bulk-importing
+  // pre-translated content or automating locale coverage without a human in
+  // the dashboard.
+  /**
+   * Get translation completeness across every translatable entity type, for
+   * one or more locales. Useful as a pre-flight before a bulk import to see
+   * which entity types/locales still need coverage.
+   * Requires Admin mode (apiKey).
+   *
+   * @param storeId - Store to inspect.
+   * @param locales - BCP-47 locale codes to check (e.g. `['he', 'fr']`). Omit
+   *   or pass an empty array to get rows with `total` populated but no
+   *   locale breakdown.
+   *
+   * @example
+   * ```typescript
+   * const status = await client.getTranslationStatus('store_123', ['he', 'fr']);
+   * const blogHe = status.find((s) => s.entityType === 'blogPost' && s.locale === 'he');
+   * console.log(`${blogHe?.missing} blog posts still need Hebrew`);
+   * ```
+   */
+  async getTranslationStatus(storeId, locales) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${encodePathSegment(storeId)}/translations/status`,
+      void 0,
+      locales && locales.length > 0 ? { locales: locales.join(",") } : void 0
+    );
+  }
+  /**
+   * Get every persisted translation for a single entity, keyed by locale.
+   * Requires Admin mode (apiKey).
+   *
+   * @example
+   * ```typescript
+   * const translations = await client.getTranslations('store_123', 'product', 'prod_abc');
+   * console.log(translations.he?.name); // Hebrew product name, if set
+   * ```
+   */
+  async getTranslations(storeId, entityType, entityId) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}`
+    );
+  }
+  /**
+   * Set/update one locale's translation for an entity. Only the fields valid
+   * for `entityType` are persisted (e.g. `title`/`excerpt`/`content` for
+   * `blogPost`, `name`/`description` for `category`) — fields outside that
+   * entity's allowlist are silently ignored server-side, and omitted fields
+   * leave any existing translation for them untouched (this is a merge, not
+   * a replace, of the locale's fields).
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @example
+   * ```typescript
+   * // Bulk-import a pre-translated blog post
+   * await client.setTranslation('store_123', 'blogPost', 'post_abc', 'fr', {
+   *   title: 'Le titre en français',
+   *   excerpt: "L'extrait en français",
+   *   content: '<p>Le contenu en français</p>',
+   * });
+   * ```
+   */
+  async setTranslation(storeId, entityType, entityId, locale, fields) {
+    return this.adminRequest(
+      "PUT",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/${encodePathSegment(locale)}`,
+      fields
+    );
+  }
+  /**
+   * Delete one locale's translation for an entity. The entity's base
+   * (default-locale) fields are unaffected.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   */
+  async deleteTranslation(storeId, entityType, entityId, locale) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/stores/${encodePathSegment(storeId)}/translations/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/${encodePathSegment(locale)}`
+    );
+  }
+  /**
+   * AI-translate a single entity into one target locale and persist the
+   * result inline (synchronous — the response already reflects the write).
+   * Only fields that are still empty for `targetLocale` are filled; existing
+   * translated values are never overwritten.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @param sourceFields - Optional override of the source-language text to
+   *   translate from (e.g. unsaved edits from an open editor), instead of the
+   *   entity's persisted base fields. Keys outside the entity's translatable
+   *   field set are ignored.
+   *
+   * @example
+   * ```typescript
+   * const translations = await client.aiTranslateSingle('store_123', {
+   *   entityType: 'product',
+   *   entityId: 'prod_abc',
+   *   targetLocale: 'he',
+   * });
+   * ```
+   */
+  async aiTranslateSingle(storeId, input) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${encodePathSegment(storeId)}/translations/ai-translate-single`,
+      input
+    );
+  }
+  /**
+   * Bulk AI-translate — enqueues a background job per entity (and, for
+   * `entityType: 'attribute'`, one per attribute option too) rather than
+   * translating inline. Returns the number of jobs queued, not the finished
+   * translations; poll `getTranslationStatus` or `getTranslations` to see
+   * results land.
+   * Requires Admin mode (apiKey) with `products:write` (or the equivalent
+   * scope for the target entity type).
+   *
+   * @param entityIds - Optional explicit ids to translate. Omit to target
+   *   every entity of `entityType` in the store that isn't already fully
+   *   translated for `targetLocale`.
+   *
+   * @example
+   * ```typescript
+   * // Translate every blog post missing French coverage
+   * const { queued } = await client.aiTranslateBulk('store_123', {
+   *   entityType: 'blogPost',
+   *   targetLocale: 'fr',
+   * });
+   * ```
+   */
+  async aiTranslateBulk(storeId, input) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${encodePathSegment(storeId)}/translations/ai-translate`,
+      input
+    );
+  }
 };
 /**
  * Fields present on `getAddressDetails().address` that the address endpoints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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",