brainerce 2.1.0 → 2.2.0

package/dist/index.js

@@ -204,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.0.3";
+var SDK_VERSION = "2.2.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -450,7 +450,7 @@ var _BrainerceClient = class _BrainerceClient {
      * Works in all three SDK modes (vibe-coded, storefront, admin):
      *   - **Public reads** (`get`, `list`, `getBySlug`): work in any mode.
      *   - **Write operations** (`create`, `update`, `publish`, `unpublish`,
-     *     `remove`): admin mode only — they call `/api/v1/content/...` with
+     *     `remove`): admin mode only — they call `/api/content/...` with
      *     the API key. Calling from storefront / vibe-coded mode throws.
      *
      * **Default key:** every type has `'main'` as its universal default key.
@@ -487,7 +487,7 @@ var _BrainerceClient = class _BrainerceClient {
     this.content = (() => {
       const DEFAULT_KEY = "main";
       const publicGetPath = (type, key) => `/content/${encodeURIComponent(type)}/${encodeURIComponent(key)}`;
-      const adminBase = () => "/api/v1/content";
+      const adminBase = () => "/api/content";
       const publicGet = async (type, key, locale) => {
         const query = locale ? { locale } : void 0;
         const path = publicGetPath(type, key);
@@ -2107,11 +2107,9 @@ var _BrainerceClient = class _BrainerceClient {
         queryParams
       );
     }
-    return this.adminRequest(
-      "GET",
-      "/api/v1/search/suggestions",
-      void 0,
-      queryParams
+    throw new BrainerceError(
+      "getSearchSuggestions is a storefront API. There is no admin suggestions endpoint \u2014 construct the client with `salesChannelId` or `storeId` to use it, or call getProducts({ search }) in admin mode.",
+      400
     );
   }
   /**
@@ -5812,6 +5810,166 @@ var _BrainerceClient = class _BrainerceClient {
     return this.adminRequest("POST", "/api/v1/gift-cards/balance", { code });
   }
   // ==========================================================================
+  // Gift cards — administration (API key only)
+  //
+  // Full programmatic management, unlike Shopify, which requires you to ask
+  // their support for the equivalent scope. The gate here is the SCOPE the
+  // merchant granted your key, so the separation matters: `gift_cards:issue`
+  // mints stored value and `gift_cards:adjust` rewrites a balance, and neither
+  // is implied by `gift_cards:read`. Ask for the least your integration needs.
+  //
+  // Every call reaches the same service the dashboard uses, so the rules hold
+  // identically: a note is mandatory on anything that moves value, a debit
+  // cannot cross what live checkout holds have reserved, and there is no delete
+  // anywhere — the ledger is append-only.
+  // ==========================================================================
+  /**
+   * List gift cards.
+   *
+   * `search` matches the LAST FOUR of a code or part of a recipient email. It
+   * cannot match a full code: only an HMAC is stored, so there is nothing to
+   * search against.
+   *
+   * Requires `gift_cards:read`.
+   */
+  async listGiftCards(params) {
+    const q = new URLSearchParams();
+    if (params?.page) q.set("page", String(params.page));
+    if (params?.limit) q.set("limit", String(params.limit));
+    if (params?.filter) q.set("filter", params.filter);
+    if (params?.search) q.set("search", params.search);
+    const qs = q.toString();
+    return this.adminRequest(
+      "GET",
+      `/api/v1/gift-cards${qs ? `?${qs}` : ""}`
+    );
+  }
+  /**
+   * Outstanding gift card liability, per currency.
+   *
+   * This is the month-end number. Read `byCurrency` if the store sells in more
+   * than one — currencies are never summed together.
+   *
+   * Requires `gift_cards:read`.
+   */
+  async getGiftCardLiability() {
+    return this.adminRequest("GET", "/api/v1/gift-cards/liability");
+  }
+  /**
+   * One gift card with its full ledger.
+   *
+   * Requires `gift_cards:read`.
+   */
+  async getGiftCard(giftCardId) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}`
+    );
+  }
+  /**
+   * Issue a gift card.
+   *
+   * ⚠️ **The code comes back exactly once.** It is stored only as an HMAC, so
+   * this response is the only time it exists in readable form anywhere. Persist
+   * it or deliver it before you discard the response — no later call, dashboard
+   * screen or database query can recover it.
+   *
+   * A `note` is required. Refused when gift cards are switched off for the
+   * store. Pass an `Idempotency-Key` header to make a retry safe.
+   *
+   * Requires `gift_cards:issue`.
+   *
+   * @example
+   * ```typescript
+   * const card = await client.issueGiftCard({
+   *   amount: '200.00',
+   *   note: 'Compensation for order #1042',
+   *   recipientEmail: 'dana@example.com',
+   * });
+   * await sendToCustomer(card.plaintextCode); // your only chance
+   * ```
+   */
+  async issueGiftCard(data) {
+    return this.adminRequest("POST", "/api/v1/gift-cards", data);
+  }
+  /**
+   * Re-issue a gift card onto a new code.
+   *
+   * The answer to a customer losing their code. Mints a new code, moves the
+   * WHOLE balance to it, and REVOKES the old card.
+   *
+   * **This is not a resend.** The old code stops working the moment this
+   * returns — if the customer still holds a printed card, it dies. Refused
+   * while a checkout holds value on the card. The original expiry carries
+   * forward, so this cannot be used to restart an expiry clock.
+   *
+   * The new code is returned exactly once, under the same rules as issuance.
+   *
+   * Requires `gift_cards:issue`.
+   */
+  async reissueGiftCard(giftCardId, note) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/reissue`,
+      { note }
+    );
+  }
+  /**
+   * Adjust a gift card balance.
+   *
+   * `delta` is a SIGNED decimal string: `"25.00"` adds, `"-25.00"` takes away.
+   * The `note` is required and is written to the ledger permanently — it is the
+   * row a finance review reads a year from now.
+   *
+   * A debit cannot take the balance below what live checkout holds have already
+   * reserved; that refusal names the held amount so you can act on it.
+   *
+   * Requires `gift_cards:adjust`.
+   */
+  async adjustGiftCardBalance(giftCardId, delta, note) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/adjust`,
+      { delta, note }
+    );
+  }
+  /**
+   * Enable, disable or revoke one gift card.
+   *
+   * Deliberately does NOT touch live holds: a checkout that already reserved
+   * value settles normally, because pulling it out from under a shopper
+   * mid-payment would strand a provider charge already in flight. Disabling
+   * stops NEW holds, which is what "off" actually means.
+   *
+   * Requires `gift_cards:write`.
+   */
+  async setGiftCardStatus(giftCardId, status) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/gift-cards/${encodePathSegment(giftCardId)}/status`,
+      { status }
+    );
+  }
+  /**
+   * Disable or reactivate many gift cards at once.
+   *
+   * `REVOKED` is not accepted here — it belongs to re-issue, which moves the
+   * balance to a replacement first. Revoking in bulk would strand balances with
+   * nowhere to go. Cards already revoked are skipped, so the returned count is
+   * the honest one and may be lower than the ids you sent.
+   *
+   * There is no bulk delete, here or anywhere: the ledger is append-only and a
+   * card may carry a statutory retention life.
+   *
+   * Requires `gift_cards:write`.
+   */
+  async bulkSetGiftCardStatus(giftCardIds, status) {
+    return this.adminRequest("PATCH", "/api/v1/gift-cards/bulk/status", {
+      giftCardIds,
+      status
+    });
+  }
+  // ==========================================================================
   // Donations
   // ==========================================================================
   /**
@@ -5954,10 +6112,7 @@ var _BrainerceClient = class _BrainerceClient {
         "/checkouts/shipping-destinations"
       );
     }
-    return this.adminRequest(
-      "GET",
-      "/api/v1/checkouts/shipping-destinations"
-    );
+    return this.adminRequest("GET", "/api/checkouts/shipping-destinations");
   }
   /**
    * Set shipping address on checkout (includes customer email).
@@ -6216,7 +6371,7 @@ var _BrainerceClient = class _BrainerceClient {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest("GET", "/pickup-locations");
     }
-    return this.adminRequest("GET", "/api/v1/checkouts/pickup-locations");
+    return this.adminRequest("GET", "/api/checkouts/pickup-locations");
   }
   /**
    * Set delivery type on checkout (shipping or pickup).
@@ -9190,10 +9345,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async applyTaxPreset(presetKey) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/tax/presets/${encodePathSegment(presetKey)}/apply`
-    );
+    return this.adminRequest("POST", `/api/v1/tax/presets/${encodePathSegment(presetKey)}/apply`);
   }
   /**
    * Get a single tax rate by ID
@@ -9823,6 +9975,27 @@ var _BrainerceClient = class _BrainerceClient {
   }
   // -------------------- Store Team Management (Admin) --------------------
   // Store-level team management. Each store has its own team with roles and permissions.
+  /**
+   * Every store-level team operation is dashboard-only.
+   *
+   * `store-team.controller.ts:53` carries `DashboardOnlyGuard`, which rejects
+   * `api_key` and `app_installation` principals outright, so no SDK caller can
+   * reach these however the URL is spelled. They additionally pointed at
+   * `/api/v1/stores/:storeId/team*`, and `@Controller('v1')`
+   * (external-api.controller.ts:181) has no `stores` root — so what they
+   * actually returned was a 404, not the 403 you would expect from the guard.
+   *
+   * Throwing beats either status code: a 404 reads as "wrong id" and a 403 as
+   * "missing permission", and both send the caller looking for a fix that does
+   * not exist. Use the account-level `getTeamMembers()` family, or the
+   * dashboard.
+   */
+  dashboardOnlyTeamOperation(operation) {
+    throw new BrainerceError(
+      `${operation} is a dashboard-only operation. Store-level team management sits behind DashboardOnlyGuard, which rejects API-key principals, so there is no SDK path to it in any mode. Use the account-level team methods (getTeamMembers, inviteTeamMember, ...) or the Brainerce dashboard.`,
+      403
+    );
+  }
   /**
    * Get the team for a specific store (members + pending invitations)
    * Requires Admin mode (apiKey) and MANAGE_TEAM permission
@@ -9832,11 +10005,8 @@ var _BrainerceClient = class _BrainerceClient {
    * const { members, invitations } = await client.getStoreTeam('store_id');
    * ```
    */
-  async getStoreTeam(storeId) {
-    return this.adminRequest(
-      "GET",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team`
-    );
+  async getStoreTeam(_storeId) {
+    return this.dashboardOnlyTeamOperation("getStoreTeam");
   }
   /**
    * Invite a new member to a store
@@ -9853,12 +10023,8 @@ var _BrainerceClient = class _BrainerceClient {
    * });
    * ```
    */
-  async inviteStoreMember(storeId, data) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/invite`,
-      data
-    );
+  async inviteStoreMember(_storeId, _data) {
+    return this.dashboardOnlyTeamOperation("inviteStoreMember");
   }
   /**
    * Update a store team member's role and/or permissions
@@ -9875,12 +10041,8 @@ var _BrainerceClient = class _BrainerceClient {
    * });
    * ```
    */
-  async updateStoreMember(storeId, memberId, data) {
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/${encodePathSegment(memberId)}`,
-      data
-    );
+  async updateStoreMember(_storeId, _memberId, _data) {
+    return this.dashboardOnlyTeamOperation("updateStoreMember");
   }
   /**
    * Replace the set of vibe-coded sales channels a store member is restricted to.
@@ -9901,42 +10063,29 @@ var _BrainerceClient = class _BrainerceClient {
    * });
    * ```
    */
-  async updateStoreMemberSalesChannels(storeId, memberId, data) {
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/${encodePathSegment(memberId)}/sales-channels`,
-      data
-    );
+  async updateStoreMemberSalesChannels(_storeId, _memberId, _data) {
+    return this.dashboardOnlyTeamOperation("updateStoreMemberSalesChannels");
   }
   /**
    * Remove a member from a store team
    * Requires Admin mode (apiKey) and MANAGE_TEAM permission
    */
-  async removeStoreMember(storeId, memberId) {
-    await this.adminRequest(
-      "DELETE",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/${encodePathSegment(memberId)}`
-    );
+  async removeStoreMember(_storeId, _memberId) {
+    return this.dashboardOnlyTeamOperation("removeStoreMember");
   }
   /**
    * Resend a store invitation email
    * Requires Admin mode (apiKey) and MANAGE_TEAM permission
    */
-  async resendStoreInvitation(storeId, invitationId) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/invitations/${encodePathSegment(invitationId)}/resend`
-    );
+  async resendStoreInvitation(_storeId, _invitationId) {
+    return this.dashboardOnlyTeamOperation("resendStoreInvitation");
   }
   /**
    * Revoke a store invitation
    * Requires Admin mode (apiKey) and MANAGE_TEAM permission
    */
-  async revokeStoreInvitation(storeId, invitationId) {
-    await this.adminRequest(
-      "DELETE",
-      `/api/v1/stores/${encodePathSegment(storeId)}/team/invitations/${encodePathSegment(invitationId)}`
-    );
+  async revokeStoreInvitation(_storeId, _invitationId) {
+    return this.dashboardOnlyTeamOperation("revokeStoreInvitation");
   }
   /**
    * Get public invitation details by token (no auth required)
@@ -9945,7 +10094,7 @@ var _BrainerceClient = class _BrainerceClient {
   async getStoreInvitationByToken(token) {
     return this.request(
       "GET",
-      `/api/v1/store-invitations/${encodePathSegment(token)}`
+      `/api/store-invitations/${encodePathSegment(token)}`
     );
   }
   /**
@@ -9953,9 +10102,9 @@ var _BrainerceClient = class _BrainerceClient {
    * Requires Admin mode (apiKey)
    */
   async acceptStoreInvitation(token) {
-    await this.adminRequest(
-      "POST",
-      `/api/v1/store-invitations/${encodePathSegment(token)}/accept`
+    throw new BrainerceError(
+      "acceptStoreInvitation requires a dashboard session belonging to the invited user: the invitation is matched against the email address of that user, which an API key does not have. Send the invitee to the invitation link instead.",
+      403
     );
   }
   /**
@@ -9972,7 +10121,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async getMyStores() {
-    return this.adminRequest("GET", "/api/v1/me/stores");
+    return this.dashboardOnlyUserContext("getMyStores");
   }
   /**
    * Get the current user's resolved permissions for a specific store
@@ -9986,10 +10135,23 @@ var _BrainerceClient = class _BrainerceClient {
    * }
    * ```
    */
-  async getMyStorePermissions(storeId) {
-    return this.adminRequest(
-      "GET",
-      `/api/v1/me/stores/${encodePathSegment(storeId)}/permissions`
+  async getMyStorePermissions(_storeId) {
+    return this.dashboardOnlyUserContext("getMyStorePermissions");
+  }
+  /**
+   * `/me/*` answers "who am I and what can I reach", which only a real user can
+   * ask. `UserContextController` (store-team.controller.ts:246) is guarded by
+   * `DashboardOnlyGuard` for a load-bearing reason its own G16 comment spells
+   * out: both routes resolve access purely from `@CurrentUserId()`, which is
+   * `undefined` for an api_key principal, so the store filter would be stripped
+   * and every store on the platform returned. The guard is the control. These
+   * also pointed at `/api/v1/me/*`, which no controller serves, so the observed
+   * failure was a 404 rather than the guard's 403.
+   */
+  dashboardOnlyUserContext(operation) {
+    throw new BrainerceError(
+      `${operation} resolves the CURRENT USER, so it requires a dashboard session and is rejected for API-key principals by design. An API key is already scoped to one store: read it with getStore(), and read the permissions of a member from getStoreTeam() in the dashboard.`,
+      403
     );
   }
   // -------------------- Email Settings & Templates (Admin) --------------------
@@ -10132,7 +10294,7 @@ var _BrainerceClient = class _BrainerceClient {
    * Requires Admin mode (apiKey)
    */
   async getSyncConflicts() {
-    return this.adminRequest("GET", "/api/v1/sync-conflicts");
+    return this.syncConflictsNotImplemented("getSyncConflicts");
   }
   /**
    * Resolve a sync conflict
@@ -10142,12 +10304,28 @@ var _BrainerceClient = class _BrainerceClient {
    * @param resolution - 'MERGE' to link to existing product, 'CREATE_NEW' to create new product
    */
   async resolveSyncConflict(conflictId, resolution) {
-    return this.adminRequest(
-      "POST",
-      `/api/v1/sync-conflicts/${encodePathSegment(conflictId)}/resolve`,
-      {
-        resolution
-      }
+    void conflictId;
+    void resolution;
+    return this.syncConflictsNotImplemented("resolveSyncConflict");
+  }
+  /**
+   * Sync conflicts were never implemented on the server.
+   *
+   * There is no `sync-conflict` route anywhere in the backend — not under
+   * `@Controller('v1')`, not on any other controller. These two methods have
+   * called a URL that has never existed, and `SyncConflict` /
+   * `SyncConflictResolution` / `ResolveSyncConflictDto` are exported types with
+   * no producer. The METAFIELD conflict siblings below are real
+   * (external-api.controller.ts:4788, :4802) and are easy to mistake for these.
+   *
+   * Kept as throwing stubs rather than deleted: removing exported methods from a
+   * published package is a breaking change, and a caller who has been swallowing
+   * a 404 deserves to be told why.
+   */
+  syncConflictsNotImplemented(operation) {
+    throw new BrainerceError(
+      `${operation} is not implemented: the platform exposes no sync-conflict endpoint. If you are looking for metafield sync conflicts, use getMetafieldConflicts() / resolveMetafieldConflict().`,
+      501
     );
   }
   // -------------------- Metafield Conflicts (Admin) --------------------