@waffo/pancake-ts 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,56 @@ 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.10.0] - 2026-06-01
+
+Expands `NotificationSettings` to the full 19-field schema (8 consumer-email + 11 merchant-notify toggles) and narrows `UpdateStoreParams.notificationSettings` to the merchant-writable subset.
+
+### Added
+
+- **`NotificationSettings`** gains 11 fields aligning with the platform schema:
+  - Consumer email (platform-managed): `emailTrialStarted`, `emailTrialEnding`
+  - Merchant notify (merchant-writable): `notifySubscriptionCanceled`, `notifySubscriptionEnded`, `notifySubscriptionPastDue`, `notifySubscriptionRenewed`, `notifySubscriptionUncanceled`, `notifySubscriptionUpdated`, `notifyChargeback`, `notifyPayoutCompleted`, `notifyPayoutFailed`
+- **`MerchantWritableNotificationSettings`** — new type exposing only the 11 `notify*` toggles. Use this for any merchant-side `update-store` call. `email*` toggles are managed by the PANCAKE platform (admin via DB) and silently dropped if passed to the merchant API.
+
+### Changed
+
+- **`UpdateStoreParams.notificationSettings` narrowed** from `Partial<NotificationSettings>` to `Partial<MerchantWritableNotificationSettings>`. Passing `email*` keys now fails TypeScript compilation rather than being silently dropped at the server.
+- README "Update store" example pruned to only show writable `notify*` fields with an explicit comment on the platform-managed `email*` subset.
+
+### Migration
+
+If your `client.stores.update` calls passed any `emailOrderConfirmation` / `emailSubscription*` / `emailTrial*` keys in `notificationSettings`, remove them — these were already being dropped server-side as of v2026.5 (returned as a `warnings[].aiHint`). Only `notify*` keys are merchant-writable.
+
+```diff
+ await client.stores.update({
+   id: storeId,
+   notificationSettings: {
+-    emailOrderConfirmation: true,
+-    emailSubscriptionCycled: true,
+     notifyNewOrders: true,
+     notifyNewSubscriptions: false,
++    notifyChargeback: true,
++    notifyPayoutFailed: true,
+   },
+ });
+```
+
+## [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

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,6 +317,16 @@ 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.
@@ -343,18 +369,16 @@ const { store } = await client.stores.create({ name: "My Store" });
 
 // Update settings (notification, checkout theme).
 // NOTE: webhook configuration moved to client.webhooks (see Webhooks section below).
+// NOTE: only merchant-facing `notify*` toggles (notifyNewOrders / notifyNewSubscriptions /
+//       notifySubscription* / notifyChargeback / notifyPayout*) are writable here;
+//       consumer email toggles (emailOrderConfirmation, emailSubscription*, emailTrial*) are
+//       managed by the PANCAKE platform and silently dropped if passed.
 const { store: updated } = await client.stores.update({
   id: store.id,
   supportEmail: "help@example.com",
   notificationSettings: {
-    emailOrderConfirmation: true,
-    emailSubscriptionConfirmation: true,
-    emailSubscriptionCycled: true,
-    emailSubscriptionCanceled: true,
-    emailSubscriptionRevoked: true,
-    emailSubscriptionPastDue: true,
     notifyNewOrders: true,
-    notifyNewSubscriptions: true,
+    notifyNewSubscriptions: false,
   },
 });
 

package/dist/index.cjs

@@ -313,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}`);
@@ -355,6 +360,7 @@ function validateCheckoutCommon(params) {
   if (params.expiresInSeconds !== void 0) {
     validatePositiveInteger("expiresInSeconds", params.expiresInSeconds);
   }
+  validateMaxLength("orderMerchantExternalId", params.orderMerchantExternalId, 128);
 }
 
 // src/resources/auth.ts
@@ -457,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) {
@@ -464,6 +471,7 @@ var BuyerSession = class {
     validateRequired("reason", params.reason);
     validateAmountString("requestedAmount.amount", params.requestedAmount.amount);
     validateCurrencyCode("requestedAmount.currency", params.requestedAmount.currency);
+    validateMaxLength("refundTicketMerchantExternalId", params.refundTicketMerchantExternalId, 128);
     return unwrapAction(await this.http.post("/v1/actions/refund-ticket/create-ticket", params));
   }
   /**
@@ -530,12 +538,13 @@ 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) {
@@ -571,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=...)
    */