@waffo/pancake-ts 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.3.0] - 2026-04-09
+
+### Breaking Changes
+
+- **Checkout params simplified** — `storeId` and `productType` removed from `CreateCheckoutSessionParams`, `AnonymousCheckoutParams`, and `AuthenticatedCheckoutParams`. The server now derives both from `productId` automatically. Only `productId` + `currency` are required.
+- **`CheckoutSessionProductType` enum removed** — No longer exported. Product type is determined server-side.
+- **`IssueSessionTokenParams.storeId` now optional** — Provide either `storeId` or `productId` (at least one required). When `productId` is given, the server derives the store from the product.
+
+### Added
+
+- **`IssueSessionTokenParams.productId`** — New optional field. When provided without `storeId`, the server derives the store from the product.
+
+### Changed
+
+- **`checkout.authenticated.create()`** — Now sends `productId` (instead of `storeId`) to `issue-session-token` endpoint for parallel session token + checkout session creation.
+
+### Documentation
+
+- **GraphQL type difference warning** — Added warnings in `graphql-guide.md`, `api-reference.md`, and external docs (EN/ZH/JA) clarifying that SDK TypeScript types reflect the REST API shape and differ from GraphQL schema types (e.g. `prices` is `Record<string, PriceInfo>` in REST but `[CurrencyPrice!]!` in GraphQL). Users should always use introspection for GraphQL queries.
+
+## [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

package/README.md

@@ -28,9 +28,7 @@ const client = new WaffoPancake({
 
 // Create a checkout session — one call handles token + session + URL
 const result = await client.checkout.authenticated.create({
-  storeId: "STO_xxx",      // from Dashboard > Stores
   productId: "PROD_xxx",   // from Dashboard > Products
-  productType: "onetime",
   currency: "USD",
   buyerIdentity: req.user.email,  // your user's identity
 });
@@ -85,18 +83,14 @@ The merchant provides buyer identity — the SDK issues a session token, creates
 ```typescript
 // Basic — buyer identity only
 const result = await client.checkout.authenticated.create({
-  storeId: "STO_xxx",
   productId: "PROD_xxx",
-  productType: "onetime",
   currency: "USD",
   buyerIdentity: "customer@example.com",
 });
 
 // With dynamic pricing — override stored price (e.g., coupon, volume discount)
 const result = await client.checkout.authenticated.create({
-  storeId: "STO_xxx",
   productId: "PROD_xxx",
-  productType: "onetime",
   currency: "USD",
   buyerIdentity: "customer@example.com",
   priceSnapshot: { amount: "19.99", taxCategory: "digital_goods" },
@@ -104,9 +98,7 @@ const result = await client.checkout.authenticated.create({
 
 // Subscription with trial control + billing detail pre-fill
 const result = await client.checkout.authenticated.create({
-  storeId: "STO_xxx",
   productId: "PROD_xxx",
-  productType: "subscription",
   currency: "USD",
   buyerIdentity: "customer@example.com",
   withTrial: true,  // force enable trial (false = skip, omit = default rules)
@@ -125,17 +117,13 @@ No buyer identity required — the buyer fills in billing details manually on th
 
 ```typescript
 const result = await client.checkout.anonymous.create({
-  storeId: "STO_xxx",
   productId: "PROD_xxx",
-  productType: "onetime",
   currency: "USD",
 });
 
 // Also supports priceSnapshot and withTrial
 const result = await client.checkout.anonymous.create({
-  storeId: "STO_xxx",
   productId: "PROD_xxx",
-  productType: "subscription",
   currency: "USD",
   priceSnapshot: { amount: "4.99", taxCategory: "saas" },
   withTrial: false,  // skip trial for this session

package/dist/index.cjs

@@ -21,7 +21,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BillingPeriod: () => BillingPeriod,
-  CheckoutSessionProductType: () => CheckoutSessionProductType,
   EntityStatus: () => EntityStatus,
   Environment: () => Environment,
   ErrorLayer: () => ErrorLayer,
@@ -222,18 +221,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 +248,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
     });
@@ -336,9 +343,7 @@ function validateBillingDetail(detail) {
   }
 }
 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);
@@ -364,13 +369,31 @@ var AuthResource = class {
    * @returns Issued session token with expiration
    *
    * @example
+   * // By store ID
    * const { token, expiresAt } = await client.auth.issueSessionToken({
    *   storeId: "STO_xxx",
    *   buyerIdentity: "customer@example.com",
    * });
+   *
+   * @example
+   * // By product ID (store derived automatically)
+   * const { token, expiresAt } = await client.auth.issueSessionToken({
+   *   productId: "PROD_xxx",
+   *   buyerIdentity: "customer@example.com",
+   * });
    */
   async issueSessionToken(params) {
-    validateShortId("storeId", params.storeId, "STO");
+    if (!params.storeId && !params.productId) {
+      throw new WaffoPancakeError(400, [
+        { message: "Missing required field: provide storeId or productId", layer: "sdk" }
+      ]);
+    }
+    if (params.storeId) {
+      validateShortId("storeId", params.storeId, "STO");
+    }
+    if (params.productId) {
+      validateShortId("productId", params.productId, "PROD");
+    }
     validateRequired("buyerIdentity", params.buyerIdentity);
     return this.http.post("/v1/actions/auth/issue-session-token", params);
   }
@@ -517,9 +540,7 @@ var CheckoutAnonymousResource = class {
    *
    * @example
    * const result = await client.checkout.anonymous.create({
-   *   storeId: "STO_xxx",
    *   productId: "PROD_xxx",
-   *   productType: "onetime",
    *   currency: "USD",
    * });
    * // Redirect to result.checkoutUrl
@@ -528,7 +549,8 @@ var CheckoutAnonymousResource = class {
     validateCheckoutCommon(params);
     return this.http.post(
       "/v1/actions/checkout/create-session",
-      params
+      params,
+      { idempotencyWindow: 60 }
     );
   }
 };
@@ -552,9 +574,7 @@ var CheckoutAuthenticatedResource = class {
    *
    * @example
    * const result = await client.checkout.authenticated.create({
-   *   storeId: "STO_xxx",
    *   productId: "PROD_xxx",
-   *   productType: "onetime",
    *   currency: "USD",
    *   buyerIdentity: "customer@example.com",
    * });
@@ -566,13 +586,13 @@ var CheckoutAuthenticatedResource = class {
     const { buyerIdentity, buyerEmail, ...sessionFields } = params;
     const [tokenResult, sessionResult] = await Promise.all([
       this.http.post("/v1/actions/auth/issue-session-token", {
-        storeId: params.storeId,
+        productId: params.productId,
         buyerIdentity
-      }),
+      }, { idempotencyWindow: 60 }),
       this.http.post("/v1/actions/checkout/create-session", {
         ...sessionFields,
         buyerEmail: buyerEmail ?? buyerIdentity
-      })
+      }, { idempotencyWindow: 60 })
     ]);
     return {
       sessionId: sessionResult.sessionId,
@@ -606,16 +626,14 @@ var CheckoutResource = class {
    *
    * @example
    * const session = await client.checkout.createSession({
-   *   storeId: "STO_xxx",
    *   productId: "PROD_xxx",
-   *   productType: "onetime",
    *   currency: "USD",
    *   buyerEmail: "customer@example.com",
    * });
    * // 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 });
   }
 };
 
@@ -1291,11 +1309,6 @@ var MediaType = /* @__PURE__ */ ((MediaType2) => {
   MediaType2["Video"] = "video";
   return MediaType2;
 })(MediaType || {});
-var CheckoutSessionProductType = /* @__PURE__ */ ((CheckoutSessionProductType2) => {
-  CheckoutSessionProductType2["Onetime"] = "onetime";
-  CheckoutSessionProductType2["Subscription"] = "subscription";
-  return CheckoutSessionProductType2;
-})(CheckoutSessionProductType || {});
 var ErrorLayer = /* @__PURE__ */ ((ErrorLayer2) => {
   ErrorLayer2["Gateway"] = "gateway";
   ErrorLayer2["User"] = "user";
@@ -1325,7 +1338,6 @@ var WebhookEventType = /* @__PURE__ */ ((WebhookEventType2) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BillingPeriod,
-  CheckoutSessionProductType,
   EntityStatus,
   Environment,
   ErrorLayer,