@waffo/pancake-ts 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,33 @@ 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.2.2] - 2026-04-03
+
+### Fixed
+
+- **Checkout idempotency** — Checkout methods (`anonymous.create()`, `authenticated.create()`, `createSession()`) now use time-windowed idempotency keys (60-second window) instead of fully deterministic keys. Previously, identical checkout params always produced the same `X-Idempotency-Key`, causing the gateway to return cached (and potentially expired) sessions. Now, same params within the same minute are still deduped (protects against network retries), but a new key is generated after the window elapses.
+- **Timestamp consistency** — `Date.now()` is now called once per request and shared between signature timestamp and idempotency key calculation, eliminating a theoretical edge case where the two could land in different seconds.
+
+### Internal
+
+- **`PostOptions` interface** — Extracted inline `{ idempotencyWindow?: number }` into a named type in `types.ts` (not publicly exported).
+
+## [0.2.1] - 2026-04-02
+
+### Added
+
+- **Client-side input validation** — All resource methods now validate inputs before sending network requests. Checks include: required field presence, Short ID format (`STO_xxx`, `PROD_xxx`, etc.), ISO 4217 currency codes, ISO 3166-1 country codes, display-format amount strings, enum value ranges, and positive integers. Validation errors throw `WaffoPancakeError` with `status: 400` and `layer: "sdk"`, so developers catch them uniformly with API errors.
+- **`ErrorLayer.Sdk`** — New `"sdk"` value in the `ErrorLayer` enum for client-side validation errors.
+
+### Fixed
+
+- **Types** — `RefundTicketStatus` enum now includes all 9 statuses: added `UnderReview`, `Returned`, `Cancelled` (previously missing 3 values)
+- **Types** — `RefundTicket.currentVersionId` corrected to `string | null` (was `string`)
+- **Types** — `RefundTicket.versionNumber` corrected to `number | null` (was `number`)
+- **Types** — `RefundTicket.versionData` corrected to `Record<string, unknown> | null` (was non-nullable)
+- **Types** — `RefundTicket` now includes `createdAt` and `updatedAt` fields (previously missing)
+- **Types** — `PriceInfo`, `Prices`, `WebhookEvent` JSDoc examples corrected from numeric amounts to display-format strings
+
 ## [0.2.0] - 2026-04-02
 
 ### Added

package/dist/index.cjs

@@ -222,18 +222,26 @@ var HttpClient = class {
    *
    * 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`)
    * @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
    */
-  async post(path, body) {
+  async post(path, body, options) {
     const bodyStr = JSON.stringify(body);
-    const timestamp = Math.floor(Date.now() / 1e3).toString();
+    const now = Date.now();
+    const timestampSec = Math.floor(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 response = await this._fetch(`${this.baseUrl}${path}`, {
       method: "POST",
       headers: {
@@ -241,7 +249,7 @@ var HttpClient = class {
         "X-Merchant-Id": this.merchantId,
         "X-Timestamp": timestamp,
         "X-Signature": signature,
-        "X-Idempotency-Key": (0, import_node_crypto2.createHash)("sha256").update(`${this.merchantId}:${path}:${bodyStr}`).digest("hex")
+        "X-Idempotency-Key": (0, import_node_crypto2.createHash)("sha256").update(idempotencyInput).digest("hex")
       },
       body: bodyStr
     });
@@ -253,6 +261,105 @@ var HttpClient = class {
   }
 };
 
+// src/validation.ts
+var SHORT_ID_REGEX = /^[A-Z]{2,4}_[A-Za-z0-9]+$/;
+var CURRENCY_CODE_REGEX = /^[A-Z]{3}$/;
+var COUNTRY_CODE_REGEX = /^[A-Z]{2}$/;
+var AMOUNT_STRING_REGEX = /^\d+(\.\d+)?$/;
+var SHORT_ID_LABELS = {
+  STO: "Store",
+  PROD: "Product",
+  ORD: "Order",
+  PAY: "Payment",
+  REF: "Refund",
+  TKT: "Ticket",
+  MER: "Merchant"
+};
+function fail(message) {
+  throw new WaffoPancakeError(400, [{ message, layer: "sdk" }]);
+}
+function validateRequired(field, value) {
+  if (value === void 0 || value === null) {
+    fail(`Missing required field: ${field}`);
+  }
+  if (typeof value === "string" && value.trim() === "") {
+    fail(`${field} cannot be empty`);
+  }
+}
+function validateShortId(field, value, prefix) {
+  validateRequired(field, value);
+  const label = SHORT_ID_LABELS[prefix] ?? prefix;
+  if (!SHORT_ID_REGEX.test(value)) {
+    fail(`Invalid ${field}: expected ${label} Short ID format (${prefix}_xxx), got "${value}"`);
+  }
+  if (!value.startsWith(`${prefix}_`)) {
+    fail(`Invalid ${field}: expected ${prefix}_ prefix (${label}), got "${value.split("_")[0]}_"`);
+  }
+}
+function validateCurrencyCode(field, value) {
+  validateRequired(field, value);
+  if (!CURRENCY_CODE_REGEX.test(value)) {
+    fail(`Invalid ${field}: expected 3-letter ISO 4217 currency code (e.g., "USD"), got "${value}"`);
+  }
+}
+function validateAmountString(field, value) {
+  validateRequired(field, value);
+  if (!AMOUNT_STRING_REGEX.test(value)) {
+    fail(`Invalid ${field}: expected numeric string in display format (e.g., "9.99", "1000"), got "${value}"`);
+  }
+}
+function validateEnum(field, value, allowed) {
+  validateRequired(field, value);
+  if (!allowed.includes(value)) {
+    fail(`Invalid ${field}: expected one of [${allowed.join(", ")}], got "${value}"`);
+  }
+}
+function validatePositiveInteger(field, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    fail(`Invalid ${field}: expected positive integer, got ${value}`);
+  }
+}
+function validateCountryCode(field, value) {
+  validateRequired(field, value);
+  if (!COUNTRY_CODE_REGEX.test(value)) {
+    fail(`Invalid ${field}: expected 2-letter ISO 3166-1 country code (e.g., "US"), got "${value}"`);
+  }
+}
+function validatePrices(field, prices) {
+  validateRequired(field, prices);
+  const entries = Object.entries(prices);
+  if (entries.length === 0) {
+    fail(`${field} must contain at least one currency`);
+  }
+  for (const [currency, info] of entries) {
+    validateCurrencyCode(`${field}.${currency} (key)`, currency);
+    validateAmountString(`${field}.${currency}.amount`, info.amount);
+    validateRequired(`${field}.${currency}.taxCategory`, info.taxCategory);
+  }
+}
+function validateBillingDetail(detail) {
+  validateCountryCode("billingDetail.country", detail.country);
+  if (typeof detail.isBusiness !== "boolean") {
+    fail(`Invalid billingDetail.isBusiness: expected boolean, got ${typeof detail.isBusiness}`);
+  }
+}
+function validateCheckoutCommon(params) {
+  validateShortId("storeId", params.storeId, "STO");
+  validateShortId("productId", params.productId, "PROD");
+  validateEnum("productType", params.productType, ["onetime", "subscription"]);
+  validateCurrencyCode("currency", params.currency);
+  if (params.priceSnapshot) {
+    validateAmountString("priceSnapshot.amount", params.priceSnapshot.amount);
+    validateRequired("priceSnapshot.taxCategory", params.priceSnapshot.taxCategory);
+  }
+  if (params.billingDetail) {
+    validateBillingDetail(params.billingDetail);
+  }
+  if (params.expiresInSeconds !== void 0) {
+    validatePositiveInteger("expiresInSeconds", params.expiresInSeconds);
+  }
+}
+
 // src/resources/auth.ts
 var AuthResource = class {
   constructor(http) {
@@ -271,6 +378,8 @@ var AuthResource = class {
    * });
    */
   async issueSessionToken(params) {
+    validateShortId("storeId", params.storeId, "STO");
+    validateRequired("buyerIdentity", params.buyerIdentity);
     return this.http.post("/v1/actions/auth/issue-session-token", params);
   }
 };
@@ -294,6 +403,7 @@ var BuyerSession = class {
    * // status: "canceled" (was pending) or "canceling" (was active)
    */
   async cancelSubscription(params) {
+    validateShortId("orderId", params.orderId, "ORD");
     return this.http.post(
       "/v1/actions/subscription-order/cancel-order",
       params
@@ -309,6 +419,7 @@ var BuyerSession = class {
    * const { orderId, status } = await buyer.cancelOnetimeOrder({ orderId: "ORD_xxx" });
    */
   async cancelOnetimeOrder(params) {
+    validateShortId("orderId", params.orderId, "ORD");
     return this.http.post(
       "/v1/actions/onetime-order/cancel-order",
       params
@@ -325,6 +436,7 @@ var BuyerSession = class {
    * // status: "active"
    */
   async reactivateSubscription(params) {
+    validateShortId("orderId", params.orderId, "ORD");
     return this.http.post(
       "/v1/actions/subscription-order/reactivate-order",
       params
@@ -344,6 +456,10 @@ var BuyerSession = class {
    * });
    */
   async createRefundTicket(params) {
+    validateShortId("paymentId", params.paymentId, "PAY");
+    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
@@ -364,6 +480,11 @@ var BuyerSession = class {
    * });
    */
   async resubmitRefundTicket(params) {
+    validateShortId("ticketId", params.ticketId, "TKT");
+    validateShortId("paymentId", params.paymentId, "PAY");
+    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
@@ -386,6 +507,7 @@ var BuyerGraphQL = class {
    * });
    */
   async query(params) {
+    validateRequired("query", params.query);
     return this.http.post("/v1/graphql", params);
   }
 };
@@ -411,9 +533,11 @@ var CheckoutAnonymousResource = class {
    * // Redirect to result.checkoutUrl
    */
   async create(params) {
+    validateCheckoutCommon(params);
     return this.http.post(
       "/v1/actions/checkout/create-session",
-      params
+      params,
+      { idempotencyWindow: 60 }
     );
   }
 };
@@ -446,16 +570,18 @@ var CheckoutAuthenticatedResource = class {
    * // Redirect to result.checkoutUrl (includes #token=...)
    */
   async create(params) {
+    validateCheckoutCommon(params);
+    validateRequired("buyerIdentity", params.buyerIdentity);
     const { buyerIdentity, buyerEmail, ...sessionFields } = params;
     const [tokenResult, sessionResult] = await Promise.all([
       this.http.post("/v1/actions/auth/issue-session-token", {
         storeId: params.storeId,
         buyerIdentity
-      }),
+      }, { idempotencyWindow: 60 }),
       this.http.post("/v1/actions/checkout/create-session", {
         ...sessionFields,
         buyerEmail: buyerEmail ?? buyerIdentity
-      })
+      }, { idempotencyWindow: 60 })
     ]);
     return {
       sessionId: sessionResult.sessionId,
@@ -498,7 +624,7 @@ var CheckoutResource = class {
    * // Redirect to session.checkoutUrl
    */
   async createSession(params) {
-    return this.http.post("/v1/actions/checkout/create-session", params);
+    return this.http.post("/v1/actions/checkout/create-session", params, { idempotencyWindow: 60 });
   }
 };
 
@@ -526,6 +652,7 @@ var GraphQLResource = class {
    * });
    */
   async query(params) {
+    validateRequired("query", params.query);
     return this.http.post("/v1/graphql", params);
   }
 };
@@ -549,6 +676,9 @@ var OnetimeProductsResource = class {
    * });
    */
   async create(params) {
+    validateShortId("storeId", params.storeId, "STO");
+    validateRequired("name", params.name);
+    validatePrices("prices", params.prices);
     return this.http.post("/v1/actions/onetime-product/create-product", params);
   }
   /**
@@ -565,6 +695,9 @@ var OnetimeProductsResource = class {
    * });
    */
   async update(params) {
+    validateShortId("id", params.id, "PROD");
+    validateRequired("name", params.name);
+    validatePrices("prices", params.prices);
     return this.http.post("/v1/actions/onetime-product/update-product", params);
   }
   /**
@@ -577,6 +710,7 @@ var OnetimeProductsResource = class {
    * const { product } = await client.onetimeProducts.publish({ id: "PROD_xxx" });
    */
   async publish(params) {
+    validateShortId("id", params.id, "PROD");
     return this.http.post("/v1/actions/onetime-product/publish-product", params);
   }
   /**
@@ -592,6 +726,8 @@ 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);
   }
 };
@@ -617,6 +753,7 @@ var OrdersResource = class {
    * // status: "canceled" or "canceling"
    */
   async cancelSubscription(params) {
+    validateShortId("orderId", params.orderId, "ORD");
     return this.http.post("/v1/actions/subscription-order/cancel-order", params);
   }
 };
@@ -640,6 +777,9 @@ var StoreMerchantsResource = class {
    * });
    */
   async add(params) {
+    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);
   }
   /**
@@ -655,6 +795,8 @@ 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);
   }
   /**
@@ -671,6 +813,9 @@ var StoreMerchantsResource = class {
    * });
    */
   async updateRole(params) {
+    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);
   }
 };
@@ -690,6 +835,7 @@ var StoresResource = class {
    * const { store } = await client.stores.create({ name: "My Store" });
    */
   async create(params) {
+    validateRequired("name", params.name);
     return this.http.post("/v1/actions/store/create-store", params);
   }
   /**
@@ -705,6 +851,7 @@ var StoresResource = class {
    * });
    */
   async update(params) {
+    validateShortId("id", params.id, "STO");
     return this.http.post("/v1/actions/store/update-store", params);
   }
   /**
@@ -717,6 +864,7 @@ var StoresResource = class {
    * const { store } = await client.stores.delete({ id: "STO_xxx" });
    */
   async delete(params) {
+    validateShortId("id", params.id, "STO");
     return this.http.post("/v1/actions/store/delete-store", params);
   }
 };
@@ -741,6 +889,8 @@ 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);
   }
   /**
@@ -756,6 +906,7 @@ var SubscriptionProductGroupsResource = class {
    * });
    */
   async update(params) {
+    validateRequired("id", params.id);
     return this.http.post("/v1/actions/subscription-product-group/update-group", params);
   }
   /**
@@ -768,6 +919,7 @@ var SubscriptionProductGroupsResource = class {
    * const { group } = await client.subscriptionProductGroups.delete({ id: "GRP_xxx" });
    */
   async delete(params) {
+    validateRequired("id", params.id);
     return this.http.post("/v1/actions/subscription-product-group/delete-group", params);
   }
   /**
@@ -780,6 +932,7 @@ var SubscriptionProductGroupsResource = class {
    * const { group } = await client.subscriptionProductGroups.publish({ id: "GRP_xxx" });
    */
   async publish(params) {
+    validateRequired("id", params.id);
     return this.http.post("/v1/actions/subscription-product-group/publish-group", params);
   }
 };
@@ -804,6 +957,10 @@ var SubscriptionProductsResource = class {
    * });
    */
   async create(params) {
+    validateShortId("storeId", params.storeId, "STO");
+    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);
   }
   /**
@@ -821,6 +978,10 @@ var SubscriptionProductsResource = class {
    * });
    */
   async update(params) {
+    validateShortId("id", params.id, "PROD");
+    validateRequired("name", params.name);
+    validateEnum("billingPeriod", params.billingPeriod, ["weekly", "monthly", "quarterly", "yearly"]);
+    validatePrices("prices", params.prices);
     return this.http.post("/v1/actions/subscription-product/update-product", params);
   }
   /**
@@ -833,6 +994,7 @@ var SubscriptionProductsResource = class {
    * const { product } = await client.subscriptionProducts.publish({ id: "PROD_xxx" });
    */
   async publish(params) {
+    validateShortId("id", params.id, "PROD");
     return this.http.post("/v1/actions/subscription-product/publish-product", params);
   }
   /**
@@ -848,6 +1010,8 @@ 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);
   }
 };
@@ -1116,11 +1280,14 @@ var PaymentStatus = /* @__PURE__ */ ((PaymentStatus2) => {
 })(PaymentStatus || {});
 var RefundTicketStatus = /* @__PURE__ */ ((RefundTicketStatus2) => {
   RefundTicketStatus2["Pending"] = "pending";
+  RefundTicketStatus2["UnderReview"] = "under_review";
   RefundTicketStatus2["Approved"] = "approved";
   RefundTicketStatus2["Rejected"] = "rejected";
+  RefundTicketStatus2["Returned"] = "returned";
   RefundTicketStatus2["Processing"] = "processing";
   RefundTicketStatus2["Succeeded"] = "succeeded";
   RefundTicketStatus2["Failed"] = "failed";
+  RefundTicketStatus2["Cancelled"] = "cancelled";
   return RefundTicketStatus2;
 })(RefundTicketStatus || {});
 var RefundStatus = /* @__PURE__ */ ((RefundStatus2) => {
@@ -1148,6 +1315,7 @@ var ErrorLayer = /* @__PURE__ */ ((ErrorLayer2) => {
   ErrorLayer2["GraphQL"] = "graphql";
   ErrorLayer2["Resource"] = "resource";
   ErrorLayer2["Email"] = "email";
+  ErrorLayer2["Sdk"] = "sdk";
   return ErrorLayer2;
 })(ErrorLayer || {});
 var WebhookEventType = /* @__PURE__ */ ((WebhookEventType2) => {