@waffo/pancake-ts 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to `@waffo/pancake-ts` will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-05-21
+
+Adds flat dual-key external-id fields across write inputs, response entities, and webhook payload. The same field name now appears at every layer (REST request body / REST response / webhook payload / GraphQL).
+
+### Added
+
+- `CreateCheckoutSessionParams.orderMerchantExternalId` — order business identifier (optional, max 128 chars). Inherited by orders, payments, and refunds; surfaces in webhook payload (`data.orderMerchantExternalId`) and GraphQL (`Order.orderMerchantExternalId` / `Payment.orderMerchantExternalId` / `Refund.orderMerchantExternalId`).
+- `CreateRefundTicketParams.refundTicketMerchantExternalId` — refund-ticket business identifier (optional, max 128 chars). Inherited by the executed refund record on PSP success; surfaces in webhook payload (`data.refundTicketMerchantExternalId`) and GraphQL (`RefundTicket.refundTicketMerchantExternalId` / `Refund.refundTicketMerchantExternalId`).
+- `RefundTicket.refundTicketMerchantExternalId` — response field (immutable across resubmits, max 128 chars).
+- `WebhookEventData.orderMerchantExternalId` — present on order/payment events and on refund events (inherited from the related order).
+- `WebhookEventData.refundTicketMerchantExternalId` — only present on `refund.*` events; coexists with `orderMerchantExternalId` on the same refund payload.
+
+### Notes
+
+Non-breaking for SDK users — all five new fields are additive. The dual flat key naming is the canonical wire surface from this version onward.
+
+## [0.8.0] - 2026-05-17
+
+### Fixed
+
+- **GraphQL queries actually return data.** Prior versions assumed a double-wrapped envelope (`{data:{data,errors,warnings}}`) and stripped one layer too many, so `result.data` was always `undefined` regardless of what the server returned. The wire is in fact the standard single-layer GraphQL envelope (`{data, errors?, warnings?}`); the SDK now returns it verbatim.
+- **GraphQL queries no longer carry `X-Idempotency-Key`.** Queries are read-only; the gateway was caching them for 24h and serving stale snapshots on subsequent identical requests. Side-effect-free queries now hit the live DB on every call.
+- **REST `warnings` are no longer dropped.** Every REST action endpoint can return `warnings: Notice[]` (handbook `command-layer.md`); prior `HttpClient.post()` returned only the unwrapped `data` field, throwing away migration `aiHint` notices like `update-store`'s `webhookSettings field ignored → Switch to client.webhooks.add/update/remove`.
+
+### Changed
+
+- **Resource method return types widened** from `Promise<X>` to `Promise<X & { warnings?: Notice[] }>` for every REST action method (`stores`, `storeMerchants`, `onetimeProducts`, `subscriptionProducts`, `subscriptionProductGroups`, `orders`, `checkout.*`, `webhooks.add/update/remove`, `auth.issueSessionToken`, `buyer.cancelSubscription / cancelOnetimeOrder / reactivateSubscription / createRefundTicket / resubmitRefundTicket`). Existing destructuring (`const { store } = await client.stores.create(...)`) keeps working; add `warnings` to the destructure to read advisories.
+- **Transport refactored**: `HttpClient.post<T>()` now returns the parsed envelope plus HTTP status (`PostResult<T> = { status, data, errors?, warnings? }`) without throwing on `errors[]`. Throw / unwrap / warnings handling moved to the resource layer via the internal `unwrapAction` helper. GraphQL resources return the envelope verbatim.
+- **`GraphQLResource.query` and `BuyerGraphQL.query` pass `noIdempotency: true`** to the transport (suppresses `X-Idempotency-Key`).
+
+### Added
+
+- **`Notice` type** (`{ message, layer, aiHint? }`) — unified shape used by both REST and GraphQL `errors[]` / `warnings[]`. Exported from `index.ts`.
+- **`Envelope<T>` / `PostResult<T>` types** — transport-level envelope (and `PostResult` adds HTTP `status`). Exported for advanced callers.
+- **`GraphQLResponse.errors[].layer?`** — optional field carrying which service stage produced the error (`"graphql"`, `"gateway"`).
+- **`PostOptions.noIdempotency`** — boolean to suppress the `X-Idempotency-Key` header on a per-call basis.
+- **README "Warnings (Migration Notices)" section** with REST + GraphQL examples and explicit guidance for LLM/agent consumers to act on `aiHint`.
+
+### Deprecated
+
+- **`ApiError`, `ApiResponse`, `ApiSuccessResponse`, `ApiErrorResponse`** — kept as type aliases for backwards compatibility; prefer `Notice` and the new `Envelope<T>` / `PostResult<T>`.
+
+### Migration
+
+- **Most callers need no changes.** Destructuring (`const { store } = ...`) still works; the new `warnings` field is optional and untouched code ignores it.
+- **GraphQL callers**: if you have hacks that read `(result as any).stores` directly (bypassing the broken `result.data`), revert to `result.data.stores` — the bug that motivated the hack is gone.
+- **LLM/agent consumers**: read `result.warnings?.[].aiHint` on every action — that's where the platform team puts canonical migration instructions when an API evolves (e.g. `update-store`'s deprecated `webhookSettings` field).
+- **Direct `HttpClient.post` consumers** (rare; `HttpClient` is internal but reachable): return type changed from `T` to `PostResult<T>`; access `.data` to get the unwrapped payload, inspect `.errors` / `.warnings` directly. The transport no longer throws on `errors[]`.
+
 ## [0.7.0] - 2026-05-11
 
 ### Changed

package/README.md

@@ -107,6 +107,7 @@ const result = await client.checkout.authenticated.create({
   buyerEmail: "customer@example.com",
   withTrial: true, // force enable trial (false = skip, omit = default rules)
   billingDetail: { country: "US", isBusiness: false },
+  orderMerchantExternalId: "ORDER-2026-00891", // optional, see Business-Side Identifiers below
 });
 
 // result.checkoutUrl = "https://pancake.waffo.ai/store/{slug}/checkout/{sessionId}#token={JWT}"
@@ -125,12 +126,13 @@ const result = await client.checkout.anonymous.create({
   currency: "USD",
 });
 
-// Also supports priceSnapshot and withTrial
+// Also supports priceSnapshot, withTrial, and orderMerchantExternalId
 const result = await client.checkout.anonymous.create({
   productId: "PROD_xxx",
   currency: "USD",
   priceSnapshot: { amount: "4.99", taxCategory: "saas" },
   withTrial: false, // skip trial for this session
+  orderMerchantExternalId: "ORDER-2026-00891", // optional, API Key auth only
 });
 
 window.open(result.checkoutUrl, "_blank", "noopener,noreferrer");
@@ -186,6 +188,8 @@ app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
         break;
       case WebhookEventType.RefundSucceeded:
         console.log(`Refund succeeded: ${event.data.refundReason}`);
+        // refund.* events carry both business identifiers (see Business-Side Identifiers section)
+        await ledger.closeRefundTicket(event.data.refundTicketMerchantExternalId, event.data.orderMerchantExternalId);
         break;
     }
   } catch {
@@ -253,6 +257,7 @@ const { ticket } = await buyer.createRefundTicket({
   paymentId: "PAY_xxx",
   reason: "Product not as described",
   requestedAmount: { amount: "29.00", currency: "USD" },
+  refundTicketMerchantExternalId: "REF-2026-00012", // optional, see Business-Side Identifiers below
 });
 
 // Resubmit a rejected refund ticket
@@ -273,6 +278,17 @@ The token is scoped to the specified store and buyer identity — buyers can onl
 
 > **Note**: This uses the same `buyerIdentity` as `checkout.authenticated.create()`. Orders placed via authenticated checkout are automatically tied to this identity, so the buyer can manage them later with a token issued here.
 
+## Business-Side Identifiers
+
+Attach your own internal references to a checkout or a refund ticket so cross-system reconciliation does not require Waffo IDs. Two flat keys, both optional (max 128 chars):
+
+| Field                            | Attach at                                   | Inherited by                                               |
+| -------------------------------- | ------------------------------------------- | ---------------------------------------------------------- |
+| `orderMerchantExternalId`        | `checkout.{authenticated,anonymous}.create` | `Order`, `Payment` (incl. subscription renewals), `Refund` |
+| `refundTicketMerchantExternalId` | `buyer.createRefundTicket`                  | `RefundTicket`, `Refund`                                   |
+
+The same field name appears at every layer it surfaces: request body, response entity, webhook payload (`data.orderMerchantExternalId` / `data.refundTicketMerchantExternalId`), and every GraphQL type that carries the value. A `refund.*` webhook event carries **both** keys (order key inherited from the originating order). Query by either key via GraphQL filters — see [GraphQL Guide](docs/graphql-guide.md).
+
 ## GraphQL — Typed Queries
 
 ```typescript
@@ -301,10 +317,46 @@ const detail = await client.graphql.query({
   }`,
   variables: { id: "STO_xxx" },
 });
+
+// Look up by your business-side identifier (see Business-Side Identifiers above)
+const byRef = await client.graphql.query({
+  query: `query ($ref: String!) {
+    payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
+      id orderId status orderMerchantExternalId
+    }
+  }`,
+  variables: { ref: "ORDER-2026-00891" },
+});
 ```
 
 See [GraphQL Guide](docs/graphql-guide.md) for filters, analytics queries, delivery logs, and more.
 
+## Warnings (Migration Notices)
+
+Every successful REST action and GraphQL query may carry a `warnings` array alongside the data. Warnings describe non-fatal advisories the server wants you to act on — typically deprecated parameters, fields scheduled for removal, or new APIs you should switch to. Each `Notice` has `message` (human-readable), `layer` (which service produced it), and `aiHint` (a structured migration instruction aimed at LLM consumers).
+
+```typescript
+// REST action — warnings spread onto the result alongside the typed payload
+const { store, warnings } = await client.stores.update({
+  id: "STO_xxx",
+  webhookSettings: { ... },  // deprecated input
+});
+if (warnings) {
+  for (const w of warnings) {
+    console.warn(`[${w.layer}] ${w.message}`, w.aiHint);
+    // e.g. layer=store, aiHint="Switch to client.webhooks.add / update / remove"
+  }
+}
+
+// GraphQL — warnings sit on the envelope alongside data and errors
+const result = await client.graphql.query<StoresQuery>({
+  query: `query { stores { id } }`,
+});
+result.warnings?.forEach(w => console.warn(w.message, w.aiHint));
+```
+
+**LLM/agent consumers**: always check `aiHint` on every warning — it is the canonical migration instruction (npm package, version, method name, endpoint path) the platform team intends for you to follow when the underlying API evolves.
+
 ## Programmatic Store & Product Management
 
 > Most merchants manage stores and products in the [Dashboard](https://pancake.waffo.ai/dashboard). The following APIs are for merchants who need programmatic automation.

package/dist/index.cjs

@@ -65,12 +65,10 @@ var BuyerHttpClient = class {
     this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
   }
   /**
-   * Send a Bearer-authenticated POST request and return the parsed `data` field.
+   * Send a Bearer-authenticated POST and return the full envelope plus HTTP status.
    *
-   * @param path - API path
-   * @param body - Request body object
-   * @returns Parsed `data` field from the response
-   * @throws {WaffoPancakeError} When the API returns errors
+   * Does NOT throw on `errors[]` or non-2xx status — caller inspects the result.
+   * Throws {@link WaffoPancakeError} only when the response body is not valid JSON.
    */
   async post(path, body) {
     const response = await this._fetch(`${this.baseUrl}${path}`, {
@@ -81,11 +79,13 @@ var BuyerHttpClient = class {
       },
       body: JSON.stringify(body)
     });
-    const result = await response.json();
-    if ("errors" in result && result.errors) {
-      throw new WaffoPancakeError(response.status, result.errors);
+    let envelope;
+    try {
+      envelope = await response.json();
+    } catch {
+      throw new WaffoPancakeError(response.status, [{ message: `Non-JSON response from ${path}`, layer: "sdk" }]);
     }
-    return result.data;
+    return { status: response.status, ...envelope };
   }
 };
 
@@ -201,48 +201,64 @@ var HttpClient = class {
     this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
   }
   /**
-   * Send a signed POST request and return the parsed `data` field.
+   * Send a signed POST and return the full envelope plus HTTP status.
    *
    * Behavior:
-   * - Generates a deterministic `X-Idempotency-Key` from `merchantId + path + body` (same request produces same key)
-   * - When `idempotencyWindow` is set, a floored timestamp is mixed into the key so identical params produce
-   *   a new key after the window elapses (useful for checkout where repeated creation is intentional)
-   * - Auto-builds RSA-SHA256 signature (`X-Merchant-Id` / `X-Timestamp` / `X-Signature`)
-   * - Unwraps the response envelope: returns `data` on success, throws `WaffoPancakeError` on failure
-   *
-   * @param path - API path (e.g. `/v1/actions/store/create-store`)
+   * - Builds RSA-SHA256 signature (`X-Merchant-Id` / `X-Timestamp` / `X-Signature`)
+   * - Attaches `X-Idempotency-Key` (deterministic `sha256(merchantId + path + body)`)
+   *   unless `options.noIdempotency` is set
+   * - When `options.idempotencyWindow` is set, a floored timestamp is mixed into the
+   *   key so identical params produce a new key after the window elapses
+   * - Does NOT throw on `errors[]` or non-2xx status — caller inspects the result
+   * - Throws {@link WaffoPancakeError} only on transport failures (non-JSON body)
+   *
+   * @param path - API path (e.g. `/v1/actions/store/create-store`, `/v1/graphql`)
    * @param body - Request body object
    * @param options - Optional settings
-   * @param options.idempotencyWindow - Time window in seconds for idempotency key rotation (e.g. 60 = per-minute dedup)
-   * @returns Parsed `data` field from the response
-   * @throws {WaffoPancakeError} When the API returns errors
+   * @returns Parsed envelope with HTTP status
+   * @throws {WaffoPancakeError} When the response body is not valid JSON
    */
   async post(path, body, options) {
     const bodyStr = JSON.stringify(body);
-    const now = Date.now();
-    const timestampSec = Math.floor(now / 1e3);
+    const timestampSec = Math.floor(Date.now() / 1e3);
     const timestamp = timestampSec.toString();
     const signature = signRequest("POST", path, timestamp, bodyStr, this.privateKey);
-    const idempotencyBase = `${this.merchantId}:${path}:${bodyStr}`;
-    const idempotencyInput = options?.idempotencyWindow ? `${idempotencyBase}:${Math.floor(timestampSec / options.idempotencyWindow)}` : idempotencyBase;
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Merchant-Id": this.merchantId,
+      "X-Timestamp": timestamp,
+      "X-Signature": signature
+    };
+    if (!options?.noIdempotency) {
+      headers["X-Idempotency-Key"] = computeIdempotencyKey(this.merchantId, path, bodyStr, timestampSec, options);
+    }
     const response = await this._fetch(`${this.baseUrl}${path}`, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-Merchant-Id": this.merchantId,
-        "X-Timestamp": timestamp,
-        "X-Signature": signature,
-        "X-Idempotency-Key": (0, import_node_crypto2.createHash)("sha256").update(idempotencyInput).digest("hex")
-      },
+      headers,
       body: bodyStr
     });
-    const result = await response.json();
-    if ("errors" in result && result.errors) {
-      throw new WaffoPancakeError(response.status, result.errors);
+    let envelope;
+    try {
+      envelope = await response.json();
+    } catch {
+      throw new WaffoPancakeError(response.status, [{ message: `Non-JSON response from ${path}`, layer: "sdk" }]);
     }
-    return result.data;
+    return { status: response.status, ...envelope };
   }
 };
+function computeIdempotencyKey(merchantId, path, bodyStr, timestampSec, options) {
+  const base = `${merchantId}:${path}:${bodyStr}`;
+  const input = options?.idempotencyWindow ? `${base}:${Math.floor(timestampSec / options.idempotencyWindow)}` : base;
+  return (0, import_node_crypto2.createHash)("sha256").update(input).digest("hex");
+}
+
+// src/resources/internal.ts
+function unwrapAction(r) {
+  if (r.errors?.length) {
+    throw new WaffoPancakeError(r.status, r.errors);
+  }
+  return { ...r.data, ...r.warnings ? { warnings: r.warnings } : {} };
+}
 
 // src/validation.ts
 var SHORT_ID_REGEX = /^[A-Z]{2,5}_[0-9A-Za-z]{22}$/;
@@ -297,6 +313,11 @@ function validateEnum(field, value, allowed) {
     fail(`Invalid ${field}: expected one of [${allowed.join(", ")}], got "${value}"`);
   }
 }
+function validateMaxLength(field, value, max) {
+  if (value !== void 0 && value.length > max) {
+    fail(`${field} must be at most ${max} characters, got ${value.length}`);
+  }
+}
 function validatePositiveInteger(field, value) {
   if (!Number.isInteger(value) || value <= 0) {
     fail(`Invalid ${field}: expected positive integer, got ${value}`);
@@ -339,6 +360,7 @@ function validateCheckoutCommon(params) {
   if (params.expiresInSeconds !== void 0) {
     validatePositiveInteger("expiresInSeconds", params.expiresInSeconds);
   }
+  validateMaxLength("orderMerchantExternalId", params.orderMerchantExternalId, 128);
 }
 
 // src/resources/auth.ts
@@ -377,7 +399,7 @@ var AuthResource = class {
       validateShortId("productId", params.productId, "PROD");
     }
     validateRequired("buyerIdentity", params.buyerIdentity);
-    return this.http.post("/v1/actions/auth/issue-session-token", params);
+    return unwrapAction(await this.http.post("/v1/actions/auth/issue-session-token", params));
   }
 };
 
@@ -401,7 +423,7 @@ var BuyerSession = class {
    */
   async cancelSubscription(params) {
     validateShortId("orderId", params.orderId, "ORD");
-    return this.http.post("/v1/actions/subscription-order/cancel-order", params);
+    return unwrapAction(await this.http.post("/v1/actions/subscription-order/cancel-order", params));
   }
   /**
    * Cancel a one-time order (only while payment is still pending).
@@ -414,7 +436,7 @@ var BuyerSession = class {
    */
   async cancelOnetimeOrder(params) {
     validateShortId("orderId", params.orderId, "ORD");
-    return this.http.post("/v1/actions/onetime-order/cancel-order", params);
+    return unwrapAction(await this.http.post("/v1/actions/onetime-order/cancel-order", params));
   }
   /**
    * Reactivate a subscription that is in `canceling` status.
@@ -428,7 +450,7 @@ var BuyerSession = class {
    */
   async reactivateSubscription(params) {
     validateShortId("orderId", params.orderId, "ORD");
-    return this.http.post("/v1/actions/subscription-order/reactivate-order", params);
+    return unwrapAction(await this.http.post("/v1/actions/subscription-order/reactivate-order", params));
   }
   /**
    * Submit a refund request for a payment.
@@ -441,6 +463,7 @@ var BuyerSession = class {
    *   paymentId: "PAY_xxx",
    *   reason: "Product not as described",
    *   requestedAmount: { amount: "29.00", currency: "USD" },
+   *   refundTicketMerchantExternalId: "REF-2026-00891",
    * });
    */
   async createRefundTicket(params) {
@@ -448,7 +471,8 @@ var BuyerSession = class {
     validateRequired("reason", params.reason);
     validateAmountString("requestedAmount.amount", params.requestedAmount.amount);
     validateCurrencyCode("requestedAmount.currency", params.requestedAmount.currency);
-    return this.http.post("/v1/actions/refund-ticket/create-ticket", params);
+    validateMaxLength("refundTicketMerchantExternalId", params.refundTicketMerchantExternalId, 128);
+    return unwrapAction(await this.http.post("/v1/actions/refund-ticket/create-ticket", params));
   }
   /**
    * Resubmit a previously rejected refund ticket with updated details.
@@ -470,7 +494,7 @@ var BuyerSession = class {
     validateRequired("reason", params.reason);
     validateAmountString("requestedAmount.amount", params.requestedAmount.amount);
     validateCurrencyCode("requestedAmount.currency", params.requestedAmount.currency);
-    return this.http.post("/v1/actions/refund-ticket/resubmit-ticket", params);
+    return unwrapAction(await this.http.post("/v1/actions/refund-ticket/resubmit-ticket", params));
   }
 };
 var BuyerGraphQL = class {
@@ -490,7 +514,8 @@ var BuyerGraphQL = class {
    */
   async query(params) {
     validateRequired("query", params.query);
-    return this.http.post("/v1/graphql", params);
+    const result = await this.http.post("/v1/graphql", params);
+    return { data: result.data, errors: result.errors, warnings: result.warnings };
   }
 };
 
@@ -513,17 +538,20 @@ var CheckoutAnonymousResource = class {
    * });
    *
    * @example
-   * // Pre-fill email and billing without issuing a session token
+   * // Pre-fill email + billing + attach business-side order reference
    * const result = await client.checkout.anonymous.create({
    *   productId: "PROD_xxx",
    *   currency: "USD",
    *   buyerEmail: "customer@example.com",
    *   billingDetail: { country: "US", isBusiness: false, postcode: "10001" },
+   *   orderMerchantExternalId: "ORDER-2026-00891",
    * });
    */
   async create(params) {
     validateCheckoutCommon(params);
-    return this.http.post("/v1/actions/checkout/create-session", params, { idempotencyWindow: 60 });
+    return unwrapAction(
+      await this.http.post("/v1/actions/checkout/create-session", params, { idempotencyWindow: 60 })
+    );
   }
 };
 
@@ -552,6 +580,7 @@ var CheckoutAuthenticatedResource = class {
    *   currency: "USD",
    *   buyerIdentity: "user-123",
    *   buyerEmail: "customer@example.com",
+   *   orderMerchantExternalId: "ORDER-2026-00891",
    * });
    * // Redirect to result.checkoutUrl (includes #token=...)
    */
@@ -570,12 +599,16 @@ var CheckoutAuthenticatedResource = class {
       ),
       this.http.post("/v1/actions/checkout/create-session", sessionParams, { idempotencyWindow: 60 })
     ]);
+    const token = unwrapAction(tokenResult);
+    const session = unwrapAction(sessionResult);
+    const warnings = [...token.warnings ?? [], ...session.warnings ?? []];
     return {
-      sessionId: sessionResult.sessionId,
-      checkoutUrl: `${sessionResult.checkoutUrl}#token=${tokenResult.token}`,
-      expiresAt: sessionResult.expiresAt,
-      token: tokenResult.token,
-      tokenExpiresAt: tokenResult.expiresAt
+      sessionId: session.sessionId,
+      checkoutUrl: `${session.checkoutUrl}#token=${token.token}`,
+      expiresAt: session.expiresAt,
+      token: token.token,
+      tokenExpiresAt: token.expiresAt,
+      ...warnings.length > 0 ? { warnings } : {}
     };
   }
 };
@@ -609,7 +642,9 @@ var CheckoutResource = class {
    * // Redirect to session.checkoutUrl
    */
   async createSession(params) {
-    return this.http.post("/v1/actions/checkout/create-session", params, { idempotencyWindow: 60 });
+    return unwrapAction(
+      await this.http.post("/v1/actions/checkout/create-session", params, { idempotencyWindow: 60 })
+    );
   }
 };
 
@@ -638,7 +673,8 @@ var GraphQLResource = class {
    */
   async query(params) {
     validateRequired("query", params.query);
-    return this.http.post("/v1/graphql", params);
+    const result = await this.http.post("/v1/graphql", params, { noIdempotency: true });
+    return { data: result.data, errors: result.errors, warnings: result.warnings };
   }
 };
 
@@ -664,7 +700,7 @@ var OnetimeProductsResource = class {
     validateShortId("storeId", params.storeId, "STO");
     validateRequired("name", params.name);
     validatePrices("prices", params.prices);
-    return this.http.post("/v1/actions/onetime-product/create-product", params);
+    return unwrapAction(await this.http.post("/v1/actions/onetime-product/create-product", params));
   }
   /**
    * Update a one-time product. Creates a new version; skips if unchanged.
@@ -690,7 +726,7 @@ var OnetimeProductsResource = class {
     validateShortId("id", params.id, "PROD");
     if (params.name !== void 0) validateRequired("name", params.name);
     if (params.prices) validatePrices("prices", params.prices);
-    return this.http.post("/v1/actions/onetime-product/update-product", params);
+    return unwrapAction(await this.http.post("/v1/actions/onetime-product/update-product", params));
   }
   /**
    * Publish a one-time product's test version to production.
@@ -703,7 +739,7 @@ var OnetimeProductsResource = class {
    */
   async publish(params) {
     validateShortId("id", params.id, "PROD");
-    return this.http.post("/v1/actions/onetime-product/publish-product", params);
+    return unwrapAction(await this.http.post("/v1/actions/onetime-product/publish-product", params));
   }
   /**
    * Update a one-time product's status (active/inactive).
@@ -720,7 +756,7 @@ var OnetimeProductsResource = class {
   async updateStatus(params) {
     validateShortId("id", params.id, "PROD");
     validateEnum("status", params.status, ["active", "inactive"]);
-    return this.http.post("/v1/actions/onetime-product/update-status", params);
+    return unwrapAction(await this.http.post("/v1/actions/onetime-product/update-status", params));
   }
 };
 
@@ -746,7 +782,7 @@ var OrdersResource = class {
    */
   async cancelSubscription(params) {
     validateShortId("orderId", params.orderId, "ORD");
-    return this.http.post("/v1/actions/subscription-order/cancel-order", params);
+    return unwrapAction(await this.http.post("/v1/actions/subscription-order/cancel-order", params));
   }
 };
 
@@ -772,7 +808,7 @@ var StoreMerchantsResource = class {
     validateShortId("storeId", params.storeId, "STO");
     validateRequired("email", params.email);
     validateEnum("role", params.role, ["admin", "member"]);
-    return this.http.post("/v1/actions/store-merchant/add-merchant", params);
+    return unwrapAction(await this.http.post("/v1/actions/store-merchant/add-merchant", params));
   }
   /**
    * Remove a merchant from a store.
@@ -789,7 +825,7 @@ var StoreMerchantsResource = class {
   async remove(params) {
     validateShortId("storeId", params.storeId, "STO");
     validateShortId("merchantId", params.merchantId, "MER");
-    return this.http.post("/v1/actions/store-merchant/remove-merchant", params);
+    return unwrapAction(await this.http.post("/v1/actions/store-merchant/remove-merchant", params));
   }
   /**
    * Update a merchant's role in a store.
@@ -808,7 +844,7 @@ var StoreMerchantsResource = class {
     validateShortId("storeId", params.storeId, "STO");
     validateShortId("merchantId", params.merchantId, "MER");
     validateEnum("role", params.role, ["admin", "member"]);
-    return this.http.post("/v1/actions/store-merchant/update-role", params);
+    return unwrapAction(await this.http.post("/v1/actions/store-merchant/update-role", params));
   }
 };
 
@@ -828,7 +864,7 @@ var StoresResource = class {
    */
   async create(params) {
     validateRequired("name", params.name);
-    return this.http.post("/v1/actions/store/create-store", params);
+    return unwrapAction(await this.http.post("/v1/actions/store/create-store", params));
   }
   /**
    * Update an existing store's settings.
@@ -860,7 +896,7 @@ var StoresResource = class {
    */
   async update(params) {
     validateShortId("id", params.id, "STO");
-    return this.http.post("/v1/actions/store/update-store", params);
+    return unwrapAction(await this.http.post("/v1/actions/store/update-store", params));
   }
   /**
    * Soft-delete a store. Only the owner can delete.
@@ -873,7 +909,7 @@ var StoresResource = class {
    */
   async delete(params) {
     validateShortId("id", params.id, "STO");
-    return this.http.post("/v1/actions/store/delete-store", params);
+    return unwrapAction(await this.http.post("/v1/actions/store/delete-store", params));
   }
 };
 
@@ -899,7 +935,9 @@ var SubscriptionProductGroupsResource = class {
   async create(params) {
     validateShortId("storeId", params.storeId, "STO");
     validateRequired("name", params.name);
-    return this.http.post("/v1/actions/subscription-product-group/create-group", params);
+    return unwrapAction(
+      await this.http.post("/v1/actions/subscription-product-group/create-group", params)
+    );
   }
   /**
    * Update a subscription product group. `productIds` is a full replacement.
@@ -915,7 +953,9 @@ var SubscriptionProductGroupsResource = class {
    */
   async update(params) {
     validateRequired("id", params.id);
-    return this.http.post("/v1/actions/subscription-product-group/update-group", params);
+    return unwrapAction(
+      await this.http.post("/v1/actions/subscription-product-group/update-group", params)
+    );
   }
   /**
    * Hard-delete a subscription product group.
@@ -928,7 +968,9 @@ var SubscriptionProductGroupsResource = class {
    */
   async delete(params) {
     validateRequired("id", params.id);
-    return this.http.post("/v1/actions/subscription-product-group/delete-group", params);
+    return unwrapAction(
+      await this.http.post("/v1/actions/subscription-product-group/delete-group", params)
+    );
   }
   /**
    * Publish a test-environment group to production (upsert).
@@ -941,7 +983,9 @@ var SubscriptionProductGroupsResource = class {
    */
   async publish(params) {
     validateRequired("id", params.id);
-    return this.http.post("/v1/actions/subscription-product-group/publish-group", params);
+    return unwrapAction(
+      await this.http.post("/v1/actions/subscription-product-group/publish-group", params)
+    );
   }
 };
 
@@ -969,7 +1013,9 @@ var SubscriptionProductsResource = class {
     validateRequired("name", params.name);
     validateEnum("billingPeriod", params.billingPeriod, ["weekly", "monthly", "quarterly", "yearly"]);
     validatePrices("prices", params.prices);
-    return this.http.post("/v1/actions/subscription-product/create-product", params);
+    return unwrapAction(
+      await this.http.post("/v1/actions/subscription-product/create-product", params)
+    );
   }
   /**
    * Update a subscription product. Creates a new version; skips if unchanged.
@@ -998,7 +1044,9 @@ var SubscriptionProductsResource = class {
     if (params.billingPeriod !== void 0)
       validateEnum("billingPeriod", params.billingPeriod, ["weekly", "monthly", "quarterly", "yearly"]);
     if (params.prices) validatePrices("prices", params.prices);
-    return this.http.post("/v1/actions/subscription-product/update-product", params);
+    return unwrapAction(
+      await this.http.post("/v1/actions/subscription-product/update-product", params)
+    );
   }
   /**
    * Publish a subscription product's test version to production.
@@ -1011,7 +1059,9 @@ var SubscriptionProductsResource = class {
    */
   async publish(params) {
     validateShortId("id", params.id, "PROD");
-    return this.http.post("/v1/actions/subscription-product/publish-product", params);
+    return unwrapAction(
+      await this.http.post("/v1/actions/subscription-product/publish-product", params)
+    );
   }
   /**
    * Update a subscription product's status (active/inactive).
@@ -1028,7 +1078,9 @@ var SubscriptionProductsResource = class {
   async updateStatus(params) {
     validateShortId("id", params.id, "PROD");
     validateEnum("status", params.status, ["active", "inactive"]);
-    return this.http.post("/v1/actions/subscription-product/update-status", params);
+    return unwrapAction(
+      await this.http.post("/v1/actions/subscription-product/update-status", params)
+    );
   }
 };
 
@@ -1185,7 +1237,7 @@ var WebhooksResource = class {
     validateShortId("storeId", params.storeId, "STO");
     validateRequired("channel", params.channel);
     validateRequired("url", params.url);
-    return this.http.post("/v1/actions/store/add-webhook", params);
+    return unwrapAction(await this.http.post("/v1/actions/store/add-webhook", params));
   }
   /**
    * Update an existing webhook (only `url`, `events`, and `secret` are mutable).
@@ -1205,7 +1257,7 @@ var WebhooksResource = class {
    */
   async update(params) {
     validateRequired("id", params.id);
-    return this.http.post("/v1/actions/store/update-webhook", params);
+    return unwrapAction(await this.http.post("/v1/actions/store/update-webhook", params));
   }
   /**
    * Hard-delete a webhook. Historical `webhook_deliveries` rows are retained
@@ -1219,7 +1271,7 @@ var WebhooksResource = class {
    */
   async remove(params) {
     validateRequired("id", params.id);
-    return this.http.post("/v1/actions/store/remove-webhook", params);
+    return unwrapAction(await this.http.post("/v1/actions/store/remove-webhook", params));
   }
   /**
    * Verify and parse an incoming webhook event.