@waffo/pancake-ts 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CHANGELOG.md +50 -0
  2. package/README.md +32 -8
  3. package/dist/index.cjs +11 -1
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +35 -3
  6. package/dist/index.d.ts +35 -3
  7. package/dist/index.js +11 -1
  8. package/dist/index.js.map +1 -1
  9. package/docs/api-reference.md +45 -41
  10. package/docs/graphql-guide.md +26 -0
  11. package/docs/webhook-guide.md +11 -9
  12. package/package.json +1 -1
package/docs/api-reference.md CHANGED
@@ -583,12 +583,13 @@ const buyer = client.buyer(token);
583
583
 
584
584
  ### `buyer.createRefundTicket(params)`
585
585
 
586
- | Field | Type | Required | Description |
587
- | ----------------- | ------------------------- | -------- | -------------------------------------- |
588
- | `paymentId` | `string` | Yes | Payment ID to refund |
589
- | `reason` | `string` | Yes | Reason for the refund request |
590
- | `requestedAmount` | `RequestedAmount` | Yes | Refund amount (`{ amount, currency }`) |
591
- | `metadata` | `Record<string, unknown>` | No | Custom metadata |
586
+ | Field | Type | Required | Description |
587
+ | -------------------------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
588
+ | `paymentId` | `string` | Yes | Payment ID to refund |
589
+ | `reason` | `string` | Yes | Reason for the refund request |
590
+ | `requestedAmount` | `RequestedAmount` | Yes | Refund amount (`{ amount, currency }`) |
591
+ | `metadata` | `Record<string, unknown>` | No | Custom metadata |
592
+ | `refundTicketMerchantExternalId` | `string` | No | Your business-side refund-ticket identifier (max 128 chars). Surfaces under the same name in webhook payload (`data.refundTicketMerchantExternalId`) and GraphQL `RefundTicket` / `Refund` types. |
592
593
 
593
594
  **`RequestedAmount`**:
594
595
 
@@ -665,19 +666,20 @@ const subResult = await client.checkout.authenticated.create({
665
666
 
666
667
  **Parameters `AuthenticatedCheckoutParams`**:
667
668
 
668
- | Field | Type | Required | Description |
669
- | ------------------ | ------------------------ | -------- | --------------------------------------------------------------------- |
670
- | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
671
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
672
- | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
673
- | `buyerEmail` | `string` | No | Pre-fill checkout page email field (independent from `buyerIdentity`) |
674
- | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
675
- | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
676
- | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
677
- | `successUrl` | `string` | No | Redirect URL after successful payment |
678
- | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
679
- | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
680
- | `metadata` | `Record<string, string>` | No | Custom metadata |
669
+ | Field | Type | Required | Description |
670
+ | ------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
671
+ | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
672
+ | `currency` | `string` | Yes | Currency code (ISO 4217) |
673
+ | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
674
+ | `buyerEmail` | `string` | No | Pre-fill checkout page email field (independent from `buyerIdentity`) |
675
+ | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
676
+ | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
677
+ | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
678
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
679
+ | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
680
+ | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
681
+ | `metadata` | `Record<string, string>` | No | Custom metadata |
682
+ | `orderMerchantExternalId` | `string` | No | Your business-side order identifier (max 128 chars). Surfaces under the same name on `Order` / `Payment` / `Refund` GraphQL types and in webhook payload (`data.orderMerchantExternalId`). |
681
683
 
682
684
  **Returns `AuthenticatedCheckoutResult`**:
683
685
 
@@ -712,16 +714,17 @@ const snapshotResult = await client.checkout.anonymous.create({
712
714
 
713
715
  **Parameters `AnonymousCheckoutParams`**:
714
716
 
715
- | Field | Type | Required | Description |
716
- | ------------------ | ------------------------ | -------- | --------------------------------------------------------------- |
717
- | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
718
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
719
- | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
720
- | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
721
- | `successUrl` | `string` | No | Redirect URL after successful payment |
722
- | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
723
- | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
724
- | `metadata` | `Record<string, string>` | No | Custom metadata |
717
+ | Field | Type | Required | Description |
718
+ | ------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
719
+ | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
720
+ | `currency` | `string` | Yes | Currency code (ISO 4217) |
721
+ | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
722
+ | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
723
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
724
+ | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
725
+ | `darkMode` | `boolean` | No | Dark mode override (true=dark, false=light, omit=store default) |
726
+ | `metadata` | `Record<string, string>` | No | Custom metadata |
727
+ | `orderMerchantExternalId` | `string` | No | Your business-side order identifier (max 128 chars). Honored on the API Key path; visitor / store-slug flows silently drop it. Same field name in webhook payload and GraphQL `Order` / `Payment` / `Refund`. |
725
728
 
726
729
  **Returns `CheckoutSessionResult`**:
727
730
 
@@ -745,18 +748,19 @@ const session = await client.checkout.createSession({
745
748
 
746
749
  **Parameters `CreateCheckoutSessionParams`**:
747
750
 
748
- | Field | Type | Required | Description |
749
- | ------------------ | ------------------------ | -------- | ------------------------------------------------------ |
750
- | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
751
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
752
- | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
753
- | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
754
- | `buyerEmail` | `string` | No | Pre-filled buyer email |
755
- | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
756
- | `successUrl` | `string` | No | Redirect URL after successful payment |
757
- | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
758
- | `darkMode` | `boolean` | No | Dark mode override |
759
- | `metadata` | `Record<string, string>` | No | Custom metadata |
751
+ | Field | Type | Required | Description |
752
+ | ------------------------- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
753
+ | `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
754
+ | `currency` | `string` | Yes | Currency code (ISO 4217) |
755
+ | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
756
+ | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
757
+ | `buyerEmail` | `string` | No | Pre-filled buyer email |
758
+ | `billingDetail` | `BillingDetail` | No | Pre-filled billing details (country, tax ID, etc.) |
759
+ | `successUrl` | `string` | No | Redirect URL after successful payment |
760
+ | `expiresInSeconds` | `number` | No | Session expiry in seconds (default: 45 minutes) |
761
+ | `darkMode` | `boolean` | No | Dark mode override |
762
+ | `metadata` | `Record<string, string>` | No | Custom metadata |
763
+ | `orderMerchantExternalId` | `string` | No | Your business-side order identifier (max 128 chars). Honored on the API Key (merchant) path; visitor / store-slug flows silently drop it. Same field name in webhook payload and GraphQL. |
760
764
 
761
765
  **`BillingDetail` fields**:
762
766
 
package/docs/graphql-guide.md CHANGED
@@ -251,8 +251,34 @@ const tickets = await client.graphql.query({
251
251
  refundTicketsCount(filter: { status: { eq: "pending" } })
252
252
  }`,
253
253
  });
254
+
255
+ // Look up by merchant business numbers — flat dual-key naming, same field name
256
+ // appears on Order / Payment / Refund types and in webhook payload.
257
+ const byOrderRef = await client.graphql.query({
258
+ query: `query ($ref: String!) {
259
+ payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
260
+ id orderId status orderMerchantExternalId
261
+ }
262
+ }`,
263
+ variables: { ref: "ORDER-2026-00891" },
264
+ });
265
+
266
+ const byRefundTicketRef = await client.graphql.query({
267
+ query: `query ($ref: String!) {
268
+ refundTickets(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
269
+ id status refundTicketMerchantExternalId
270
+ }
271
+ refunds(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
272
+ id status orderMerchantExternalId refundTicketMerchantExternalId
273
+ pspAmountDetails { amount currency }
274
+ }
275
+ }`,
276
+ variables: { ref: "REF-2026-00012" },
277
+ });
254
278
  ```
255
279
 
280
+ > The `Refund` type exposes **both** keys as flat fields (`orderMerchantExternalId` from the originating order, `refundTicketMerchantExternalId` from the originating refund ticket). `Order` / `Payment` / `RefundTicket` carry only the key relevant to their entity. The field name on the wire matches the webhook payload (`data.orderMerchantExternalId` / `data.refundTicketMerchantExternalId`).
281
+
256
282
  ### 6. Merchant Info and Store Associations
257
283
 
258
284
  ```typescript
package/docs/webhook-guide.md CHANGED
@@ -371,15 +371,17 @@ All events include the **Order**, **Amount**, and **Product** sections. Addition
371
371
 
372
372
  **Order fields** (always present):
373
373
 
374
- | Field | Type | Required | Description |
375
- | ------------------------------- | -------- | -------- | ----------------------------------------------------------------- |
376
- | `orderId` | `string` | Yes | Associated order ID |
377
- | `orderStatus` | `string` | No | Order status (e.g., `"completed"`, `"active"`, `"canceling"`) |
378
- | `buyerEmail` | `string` | Yes | Buyer email address |
379
- | `merchantProvidedBuyerIdentity` | `string` | No | Merchant-provided buyer identity from checkout session |
380
- | `currency` | `string` | Yes | Currency code (ISO 4217) |
381
- | `billingDetail` | `object` | No | Billing/shipping address (structured object) |
382
- | `orderMetadata` | `object` | No | Order-level metadata from checkout session (flat key-value pairs) |
374
+ | Field | Type | Required | Description |
375
+ | -------------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
376
+ | `orderId` | `string` | Yes | Associated order ID |
377
+ | `orderStatus` | `string` | No | Order status (e.g., `"completed"`, `"active"`, `"canceling"`) |
378
+ | `buyerEmail` | `string` | Yes | Buyer email address |
379
+ | `merchantProvidedBuyerIdentity` | `string` | No | Merchant-provided buyer identity from checkout session |
380
+ | `orderMerchantExternalId` | `string` | No | Order business-side identifier set at checkout creation (max 128 chars). Present on order / payment / subscription events and on refund events (inherited from the originating order). |
381
+ | `refundTicketMerchantExternalId` | `string` | No | Refund-ticket business-side identifier set at refund-ticket creation. **Only present on `refund.*` events**; coexists with `orderMerchantExternalId` on the same refund payload. |
382
+ | `currency` | `string` | Yes | Currency code (ISO 4217) |
383
+ | `billingDetail` | `object` | No | Billing/shipping address (structured object) |
384
+ | `orderMetadata` | `object` | No | Order-level metadata from checkout session (flat key-value pairs) |
383
385
 
384
386
  **Amount fields** (always present):
385
387
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@waffo/pancake-ts",
3
- "version": "0.8.0",
3
+ "version": "0.10.0",
4
4
  "description": "TypeScript SDK for Waffo Pancake MoR platform — RSA-SHA256 signing, zero runtime dependencies",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",