@waffo/pancake-ts 0.1.9 → 0.2.0

package/CHANGELOG.md

@@ -4,22 +4,23 @@ 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.1.9] - 2026-04-02
+## [0.2.0] - 2026-04-02
 
 ### Added
 
 - **Checkout convenience methods** — `client.checkout.authenticated.create()` and `client.checkout.anonymous.create()` wrap the full checkout flow into a single call. Authenticated mode issues a session token, creates a checkout session, and returns a URL with the token appended as a URL fragment. Anonymous mode creates a session directly.
-- **Types** — `AuthenticatedCheckoutParams`, `AuthenticatedCheckoutResult`, `AnonymousCheckoutParams`
-- **Resources** — `CheckoutAnonymousResource`, `CheckoutAuthenticatedResource` (accessed via `client.checkout.anonymous` / `client.checkout.authenticated`)
+- **Buyer self-service** — `client.buyer(token)` creates a session-token-authenticated buyer session with methods: `cancelSubscription()`, `cancelOnetimeOrder()`, `reactivateSubscription()`, `createRefundTicket()`, `resubmitRefundTicket()`, and `graphql.query()`.
+- **Types** — `AuthenticatedCheckoutParams`, `AuthenticatedCheckoutResult`, `AnonymousCheckoutParams`, `CancelOnetimeOrderParams`, `CancelOnetimeOrderResult`, `ReactivateSubscriptionParams`, `ReactivateSubscriptionResult`, `CreateRefundTicketParams`, `ResubmitRefundTicketParams`, `RefundTicket`, `RequestedAmount`
+- **Resources** — `CheckoutAnonymousResource`, `CheckoutAuthenticatedResource`, `BuyerSession`, `BuyerHttpClient`
 
 ### Changed
 
 - **Base URL** — Default API endpoint changed from `waffo-pancake-auth-service.vercel.app` to `api.waffo.ai`
 - **Package** — `docs/` directory now included in npm package (`files` field)
-- **Docs** — `docs/api-reference.md` synced with endpoint docs: fixed `storeId` required status, added `BillingDetail` conditional field rules, fixed price amount format (display string, not integer), added subscription product group UUID note
+- **Docs** — `docs/api-reference.md` synced with endpoint docs: fixed `storeId` required status, added `BillingDetail` conditional field rules, fixed price amount format (display string, not integer), added subscription product group UUID note, added Buyer Self-Service section
 - **Docs** — `docs/graphql-guide.md` rewritten: corrected query names (`onetimeOrders` / `subscriptionOrders`), added product version queries, exchange rate query, webhook/email delivery log queries, 9 analytics queries (`orderStatistics`, `paymentStatistics`, `productStatistics`, `trendAnalysis`, `distributionAnalysis`, `customerAnalysis`, `taxAnalysis`, `subscriptionAnalysis`, `refundTicketAnalysis`), updated count query list and filter examples
 - **Docs** — `docs/webhook-guide.md` fixed `amount` / `taxAmount` type from `number` to `string` (display format), added retry mechanism section with delivery status table
-- **README** — Reorganized by use-case priority (checkout → webhooks → GraphQL → programmatic management), added checkout mode comparison and recommendation rationale
+- **README** — Reorganized by use-case priority (checkout → webhooks → buyer self-service → GraphQL → programmatic management), added checkout mode comparison and recommendation rationale
 
 ## [0.1.8] - 2026-03-20
 

package/README.md

@@ -66,32 +66,54 @@ Waffo supports two checkout modes based on whether the merchant knows the buyer'
 
 > **We recommend authenticated checkout whenever possible.** The most important reason: authenticated checkout binds the order to the `buyerIdentity` you provide, which is a **merchant-controlled stable identifier**. Even if the buyer changes the email on the checkout form, the order is still tied to the identity you specified. In anonymous mode, the buyer self-reports their email on the form — if they enter a different address, the system treats them as a new user, which means **previous orders become unlinked** and **subscription trial periods can be exploited** (a new email = a new user = a fresh trial).
 >
-> Anonymous checkout also uses the `shopper` role, which can **only create orders** (no cancellation, subscription management, or refund tickets) with a **1-minute single-use session**.
->
-> | | Authenticated (`customer`) | Anonymous (`shopper`) |
+> | | Authenticated | Anonymous |
 > |---|---|---|
 > | **Identity** | Merchant-provided, stable across orders | Self-reported email, may vary |
-> | **Permissions** | Create orders, cancel orders, manage subscriptions, submit refund tickets | Create orders **only** |
-> | **Session** | 5-minute TTL, auto-refreshes on each API call | 1-minute TTL, **single-use** (consumed on first API call) |
-> | **Subscriptions** | Fully supported — buyers can manage, cancel, or reactivate | Not practical — buyer has no session to manage the subscription afterward |
+> | **Form** | Pre-filled from merchant-provided identity | Empty, buyer fills manually |
+> | **Post-purchase** | Full self-service (see [Buyer Self-Service](#buyer-self-service)) | Create orders only — no post-purchase self-service |
+> | **Session** | 5-minute TTL, auto-refreshes | 1-minute, single-use |
+
+Both modes support **dynamic pricing** and **trial control** at checkout time:
+
+- `priceSnapshot` — override the product's stored price with a custom amount (e.g., coupon, volume discount)
+- `withTrial` — explicitly enable or disable the trial period for subscriptions (`true` = force trial, `false` = skip trial, omit = use default rules)
 
 ### Authenticated Checkout (Recommended)
 
 The merchant provides buyer identity — the SDK issues a session token, creates a checkout session, and returns a checkout URL with the token appended as a URL fragment. One call does everything.
 
 ```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",
-  // Optional: pre-fill billing details
+  priceSnapshot: { amount: "19.99", taxCategory: "digital_goods" },
+});
+
+// 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)
   billingDetail: { country: "US", isBusiness: false },
 });
-// result.checkoutUrl = "https://pancake.waffo.ai/store/{slug}/checkout/{sessionId}#token={JWT}"
 
-// Frontend — open in a new tab (recommended)
+// result.checkoutUrl = "https://pancake.waffo.ai/store/{slug}/checkout/{sessionId}#token={JWT}"
 window.open(result.checkoutUrl, "_blank", "noopener,noreferrer");
 ```
 
@@ -108,7 +130,16 @@ const result = await client.checkout.anonymous.create({
   productType: "onetime",
   currency: "USD",
 });
-// result.checkoutUrl = "https://pancake.waffo.ai/store/{slug}/checkout/{sessionId}"
+
+// 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
+});
 
 window.open(result.checkoutUrl, "_blank", "noopener,noreferrer");
 ```
@@ -195,6 +226,57 @@ const event = client.webhooks.verify(rawBody, sig, { environment: "prod" });
 
 See [Webhook Guide](docs/webhook-guide.md) for event types, dual-environment key architecture, key resolution chain, retry mechanism, and best practices.
 
+## Buyer Self-Service
+
+Beyond checkout, you can let buyers manage their own orders and subscriptions — for example, embedding a "Cancel Subscription" or "Request Refund" button in your site.
+
+Issue a session token, then use `client.buyer(token)` to get a session with self-service methods:
+
+```typescript
+// Your backend — issue a session token for the buyer
+const { token } = await client.auth.issueSessionToken({
+  storeId: "STO_xxx",
+  buyerIdentity: req.user.email,
+});
+
+// Create a buyer session
+const buyer = client.buyer(token);
+
+// Cancel a subscription
+const { orderId, status } = await buyer.cancelSubscription({ orderId: "ORD_xxx" });
+// status: "canceling" (active) or "canceled" (pending)
+
+// Reactivate a canceled subscription
+await buyer.reactivateSubscription({ orderId: "ORD_xxx" });
+
+// Cancel a one-time order (while payment is pending)
+await buyer.cancelOnetimeOrder({ orderId: "ORD_yyy" });
+
+// Submit a refund request
+const { ticket } = await buyer.createRefundTicket({
+  paymentId: "PAY_xxx",
+  reason: "Product not as described",
+  requestedAmount: { amount: "29.00", currency: "USD" },
+});
+
+// Resubmit a rejected refund ticket
+await buyer.resubmitRefundTicket({
+  ticketId: "TKT_xxx",
+  paymentId: "PAY_xxx",
+  reason: "Updated reason with more detail",
+  requestedAmount: { amount: "29.00", currency: "USD" },
+});
+
+// Query the buyer's own orders via GraphQL
+const result = await buyer.graphql.query({
+  query: `query { orders { id status createdAt } }`,
+});
+```
+
+The token is scoped to the specified store and buyer identity — buyers can only access their own data. Token TTL is 5 minutes and auto-refreshes on each API call.
+
+> **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.
+
 ## GraphQL — Typed Queries
 
 ```typescript
@@ -361,8 +443,10 @@ try {
 | `client.checkout.authenticated` | `create()` | Authenticated checkout (recommended) |
 | `client.checkout.anonymous` | `create()` | Anonymous checkout |
 | `client.checkout` | `createSession()` | Low-level checkout session |
+| `client.buyer(token)` | `cancelSubscription()` `cancelOnetimeOrder()` `reactivateSubscription()` `createRefundTicket()` `resubmitRefundTicket()` | Buyer self-service |
+| `client.buyer(token).graphql` | `query<T>()` | Buyer-scoped GraphQL queries |
 | `client.webhooks` | `verify<T>()` | Webhook signature verification |
-| `client.graphql` | `query<T>()` | Typed GraphQL queries |
+| `client.graphql` | `query<T>()` | Merchant GraphQL queries |
 | `client.auth` | `issueSessionToken()` | Issue a buyer session token (JWT) |
 | `client.stores` | `create()` `update()` `delete()` | Store management |
 | `client.storeMerchants` | `add()` `remove()` `updateRole()` | Store members (coming soon) |
@@ -430,7 +514,8 @@ npm run build           # tsup → ESM + CJS + DTS
 src/
 ├── index.ts               # Unified export entry
 ├── client.ts              # WaffoPancake main class
-├── http-client.ts         # HTTP client (auto-signing + idempotency)
+├── http-client.ts         # HTTP client (API Key, auto-signing + idempotency)
+├── buyer-http-client.ts   # HTTP client (Bearer token, buyer self-service)
 ├── signing.ts             # RSA-SHA256 request signing
 ├── errors.ts              # WaffoPancakeError
 ├── webhooks.ts            # Webhook verification (embedded keys)
@@ -443,6 +528,7 @@ src/
     ├── onetime-products.ts
     ├── subscription-products.ts
     ├── subscription-product-groups.ts
+    ├── buyer.ts
     ├── orders.ts
     ├── checkout.ts
     ├── checkout-anonymous.ts

package/dist/index.cjs

@@ -41,9 +41,6 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/http-client.ts
-var import_node_crypto2 = require("crypto");
-
 // src/errors.ts
 var WaffoPancakeError = class extends Error {
   status;
@@ -57,6 +54,45 @@ var WaffoPancakeError = class extends Error {
   }
 };
 
+// src/buyer-http-client.ts
+var DEFAULT_BASE_URL = "https://api.waffo.ai";
+var BuyerHttpClient = class {
+  token;
+  baseUrl;
+  _fetch;
+  constructor(token, config) {
+    this.token = token;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this._fetch = config.fetch ?? fetch;
+  }
+  /**
+   * Send a Bearer-authenticated POST request and return the parsed `data` field.
+   *
+   * @param path - API path
+   * @param body - Request body object
+   * @returns Parsed `data` field from the response
+   * @throws {WaffoPancakeError} When the API returns errors
+   */
+  async post(path, body) {
+    const response = await this._fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.token}`
+      },
+      body: JSON.stringify(body)
+    });
+    const result = await response.json();
+    if ("errors" in result && result.errors) {
+      throw new WaffoPancakeError(response.status, result.errors);
+    }
+    return result.data;
+  }
+};
+
+// src/http-client.ts
+var import_node_crypto2 = require("crypto");
+
 // src/signing.ts
 var import_node_crypto = require("crypto");
 var PKCS8_HEADER = "-----BEGIN PRIVATE KEY-----";
@@ -169,7 +205,7 @@ ${bodyHash}`;
 }
 
 // src/http-client.ts
-var DEFAULT_BASE_URL = "https://api.waffo.ai";
+var DEFAULT_BASE_URL2 = "https://api.waffo.ai";
 var HttpClient = class {
   merchantId;
   privateKey;
@@ -178,7 +214,7 @@ var HttpClient = class {
   constructor(config) {
     this.merchantId = config.merchantId;
     this.privateKey = normalizePrivateKey(config.privateKey);
-    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL2).replace(/\/+$/, "");
     this._fetch = config.fetch ?? fetch;
   }
   /**
@@ -239,6 +275,121 @@ var AuthResource = class {
   }
 };
 
+// src/resources/buyer.ts
+var BuyerSession = class {
+  constructor(http) {
+    this.http = http;
+    this.graphql = new BuyerGraphQL(http);
+  }
+  /** GraphQL query access scoped to the buyer's data. */
+  graphql;
+  /**
+   * Cancel a subscription order.
+   *
+   * @param params - Order to cancel
+   * @returns Order ID and resulting status
+   *
+   * @example
+   * const { orderId, status } = await buyer.cancelSubscription({ orderId: "ORD_xxx" });
+   * // status: "canceled" (was pending) or "canceling" (was active)
+   */
+  async cancelSubscription(params) {
+    return this.http.post(
+      "/v1/actions/subscription-order/cancel-order",
+      params
+    );
+  }
+  /**
+   * Cancel a one-time order (only while payment is still pending).
+   *
+   * @param params - Order to cancel
+   * @returns Order ID and resulting status
+   *
+   * @example
+   * const { orderId, status } = await buyer.cancelOnetimeOrder({ orderId: "ORD_xxx" });
+   */
+  async cancelOnetimeOrder(params) {
+    return this.http.post(
+      "/v1/actions/onetime-order/cancel-order",
+      params
+    );
+  }
+  /**
+   * Reactivate a subscription that is in `canceling` status.
+   *
+   * @param params - Order to reactivate
+   * @returns Order ID and resulting status
+   *
+   * @example
+   * const { orderId, status } = await buyer.reactivateSubscription({ orderId: "ORD_xxx" });
+   * // status: "active"
+   */
+  async reactivateSubscription(params) {
+    return this.http.post(
+      "/v1/actions/subscription-order/reactivate-order",
+      params
+    );
+  }
+  /**
+   * Submit a refund request for a payment.
+   *
+   * @param params - Refund ticket details
+   * @returns Created refund ticket
+   *
+   * @example
+   * const { ticket } = await buyer.createRefundTicket({
+   *   paymentId: "PAY_xxx",
+   *   reason: "Product not as described",
+   *   requestedAmount: { amount: "29.00", currency: "USD" },
+   * });
+   */
+  async createRefundTicket(params) {
+    return this.http.post(
+      "/v1/actions/refund-ticket/create-ticket",
+      params
+    );
+  }
+  /**
+   * Resubmit a previously rejected refund ticket with updated details.
+   *
+   * @param params - Updated ticket details
+   * @returns Updated refund ticket
+   *
+   * @example
+   * const { ticket } = await buyer.resubmitRefundTicket({
+   *   ticketId: "TKT_xxx",
+   *   paymentId: "PAY_xxx",
+   *   reason: "Updated reason with more detail",
+   *   requestedAmount: { amount: "29.00", currency: "USD" },
+   * });
+   */
+  async resubmitRefundTicket(params) {
+    return this.http.post(
+      "/v1/actions/refund-ticket/resubmit-ticket",
+      params
+    );
+  }
+};
+var BuyerGraphQL = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Execute a GraphQL query scoped to the buyer's data.
+   *
+   * @param params - GraphQL query and variables
+   * @returns GraphQL response
+   *
+   * @example
+   * const result = await buyer.graphql.query({
+   *   query: `query { orders { id status } }`,
+   * });
+   */
+  async query(params) {
+    return this.http.post("/v1/graphql", params);
+  }
+};
+
 // src/resources/checkout-anonymous.ts
 var CheckoutAnonymousResource = class {
   constructor(http) {
@@ -323,7 +474,7 @@ var CheckoutResource = class {
     this.anonymous = new CheckoutAnonymousResource(http);
     this.authenticated = new CheckoutAuthenticatedResource(http);
   }
-  /** Anonymous checkout — visitor enters without a session token. */
+  /** Anonymous checkout — no buyer identity, empty form. */
   anonymous;
   /** Authenticated checkout — merchant provides buyer identity. */
   authenticated;
@@ -848,6 +999,7 @@ var WebhooksResource = class {
 // src/client.ts
 var WaffoPancake = class {
   http;
+  config;
   auth;
   stores;
   storeMerchants;
@@ -859,6 +1011,7 @@ var WaffoPancake = class {
   graphql;
   webhooks;
   constructor(config) {
+    this.config = config;
     this.http = new HttpClient(config);
     this.auth = new AuthResource(this.http);
     this.stores = new StoresResource(this.http);
@@ -871,6 +1024,31 @@ var WaffoPancake = class {
     this.graphql = new GraphQLResource(this.http);
     this.webhooks = new WebhooksResource(config.webhookPublicKey);
   }
+  /**
+   * Create a buyer session for self-service operations.
+   *
+   * The returned session uses Bearer token authentication and provides
+   * methods for order cancellation, subscription management, refund tickets,
+   * and scoped GraphQL queries.
+   *
+   * @param token - Session token from `client.auth.issueSessionToken()`
+   * @returns A buyer session with self-service methods
+   *
+   * @example
+   * const { token } = await client.auth.issueSessionToken({
+   *   storeId: "STO_xxx",
+   *   buyerIdentity: "customer@example.com",
+   * });
+   * const buyer = client.buyer(token);
+   * await buyer.cancelSubscription({ orderId: "ORD_xxx" });
+   */
+  buyer(token) {
+    const buyerHttp = new BuyerHttpClient(token, {
+      baseUrl: this.config.baseUrl,
+      fetch: this.config.fetch
+    });
+    return new BuyerSession(buyerHttp);
+  }
 };
 
 // src/types.ts