@waffo/pancake-ts 0.7.0 → 0.9.0

package/dist/index.js

@@ -23,12 +23,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}`, {
@@ -39,11 +37,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 };
   }
 };
 
@@ -159,48 +159,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": createHash2("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 createHash2("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}$/;
@@ -255,6 +271,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}`);
@@ -297,6 +318,7 @@ function validateCheckoutCommon(params) {
   if (params.expiresInSeconds !== void 0) {
     validatePositiveInteger("expiresInSeconds", params.expiresInSeconds);
   }
+  validateMaxLength("orderMerchantExternalId", params.orderMerchantExternalId, 128);
 }
 
 // src/resources/auth.ts
@@ -335,7 +357,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));
   }
 };
 
@@ -359,7 +381,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).
@@ -372,7 +394,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.
@@ -386,7 +408,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.
@@ -399,6 +421,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) {
@@ -406,7 +429,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.
@@ -428,7 +452,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 {
@@ -448,7 +472,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 };
   }
 };
 
@@ -471,17 +496,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 })
+    );
   }
 };
 
@@ -510,6 +538,7 @@ var CheckoutAuthenticatedResource = class {
    *   currency: "USD",
    *   buyerIdentity: "user-123",
    *   buyerEmail: "customer@example.com",
+   *   orderMerchantExternalId: "ORDER-2026-00891",
    * });
    * // Redirect to result.checkoutUrl (includes #token=...)
    */
@@ -528,12 +557,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 } : {}
     };
   }
 };
@@ -567,7 +600,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 })
+    );
   }
 };
 
@@ -596,7 +631,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 };
   }
 };
 
@@ -622,7 +658,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.
@@ -648,7 +684,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.
@@ -661,7 +697,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).
@@ -678,7 +714,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));
   }
 };
 
@@ -704,7 +740,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));
   }
 };
 
@@ -730,7 +766,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.
@@ -747,7 +783,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.
@@ -766,7 +802,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));
   }
 };
 
@@ -786,7 +822,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.
@@ -818,7 +854,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.
@@ -831,7 +867,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));
   }
 };
 
@@ -857,7 +893,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.
@@ -873,7 +911,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.
@@ -886,7 +926,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).
@@ -899,7 +941,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)
+    );
   }
 };
 
@@ -927,7 +971,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.
@@ -956,7 +1002,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.
@@ -969,7 +1017,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).
@@ -986,7 +1036,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)
+    );
   }
 };
 
@@ -1143,7 +1195,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).
@@ -1163,7 +1215,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
@@ -1177,7 +1229,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.