@waffo/pancake-ts 0.2.2 → 0.3.0

package/docs/api-reference.md

@@ -17,17 +17,25 @@ Complete reference for all `@waffo/pancake-ts` resources, parameters, and return
 Issue a buyer session token (JWT) for storefront authentication.
 
 ```typescript
+// With storeId
 const { token, expiresAt } = await client.auth.issueSessionToken({
   storeId: "STO_xxx",
   buyerIdentity: "customer@example.com",
 });
+
+// With productId (server derives storeId from the product)
+const { token, expiresAt } = await client.auth.issueSessionToken({
+  productId: "PROD_xxx",
+  buyerIdentity: "customer@example.com",
+});
 ```
 
 **Parameters `IssueSessionTokenParams`**:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `storeId` | `string` | Yes | Store ID |
+| `storeId` | `string` | No | Store ID (at least one of `storeId` / `productId` required) |
+| `productId` | `string` | No | Product ID (at least one of `storeId` / `productId` required; server derives store from product) |
 | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
 
 **Returns `SessionToken`**:
@@ -607,9 +615,7 @@ Internally calls `POST /v1/actions/auth/issue-session-token` and `POST /v1/actio
 ```typescript
 // One-time product with buyer identity
 const result = await client.checkout.authenticated.create({
-  storeId: "STO_xxx",
   productId: "PROD_xxx",
-  productType: "onetime",
   currency: "USD",
   buyerIdentity: "customer@example.com",
   successUrl: "https://example.com/thank-you",
@@ -618,9 +624,7 @@ const result = await client.checkout.authenticated.create({
 
 // Subscription with trial and billing detail
 const subResult = await client.checkout.authenticated.create({
-  storeId: "STO_xxx",
   productId: "PROD_yyy",
-  productType: "subscription",
   currency: "USD",
   buyerIdentity: "customer@example.com",
   withTrial: true,
@@ -632,9 +636,7 @@ const subResult = await client.checkout.authenticated.create({
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `storeId` | `string` | Yes | Store ID |
-| `productId` | `string` | Yes | Product ID |
-| `productType` | `CheckoutSessionProductType` | Yes | `"onetime"` or `"subscription"` |
+| `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
 | `currency` | `string` | Yes | Currency code (ISO 4217) |
 | `buyerIdentity` | `string` | Yes | Buyer identity (email or merchant-defined identifier) |
 | `buyerEmail` | `string` | No | Pre-filled buyer email (defaults to `buyerIdentity`) |
@@ -664,18 +666,14 @@ Internally calls `POST /v1/actions/checkout/create-session`.
 
 ```typescript
 const result = await client.checkout.anonymous.create({
-  storeId: "STO_xxx",
   productId: "PROD_xxx",
-  productType: "onetime",
   currency: "USD",
 });
 // => redirect buyer to result.checkoutUrl (buyer fills form manually)
 
 // With price snapshot override
 const snapshotResult = await client.checkout.anonymous.create({
-  storeId: "STO_xxx",
   productId: "PROD_xxx",
-  productType: "onetime",
   currency: "USD",
   priceSnapshot: { amount: "19.99", taxCategory: "digital_goods" },
 });
@@ -685,9 +683,7 @@ const snapshotResult = await client.checkout.anonymous.create({
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `storeId` | `string` | Yes | Store ID |
-| `productId` | `string` | Yes | Product ID |
-| `productType` | `CheckoutSessionProductType` | Yes | `"onetime"` or `"subscription"` |
+| `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
 | `currency` | `string` | Yes | Currency code (ISO 4217) |
 | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
 | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
@@ -710,9 +706,7 @@ Create a checkout session directly. For most use cases, prefer `checkout.authent
 
 ```typescript
 const session = await client.checkout.createSession({
-  storeId: "STO_xxx",
   productId: "PROD_xxx",
-  productType: "onetime",
   currency: "USD",
   buyerEmail: "customer@example.com",
 });
@@ -722,9 +716,7 @@ const session = await client.checkout.createSession({
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `storeId` | `string` | Yes | Store ID |
-| `productId` | `string` | Yes | Product ID |
-| `productType` | `CheckoutSessionProductType` | Yes | `"onetime"` or `"subscription"` |
+| `productId` | `string` | Yes | Product ID (product type is auto-detected server-side) |
 | `currency` | `string` | Yes | Currency code (ISO 4217) |
 | `priceSnapshot` | `PriceInfo` | No | Price snapshot override (reads from DB if omitted) |
 | `withTrial` | `boolean` | No | Enable trial period (subscription only) |
@@ -762,6 +754,8 @@ const session = await client.checkout.createSession({
 
 Execute a typed GraphQL query. Only Query operations are supported — Mutations return a 403 error.
 
+> **Note**: GraphQL field names may differ from SDK TypeScript types. For example, `prices` is `Record<string, PriceInfo>` in REST but `[CurrencyPrice!]!` in GraphQL. Use introspection (`__schema` / `__type` queries) to discover the exact schema. See [GraphQL Guide](./graphql-guide.md) for details.
+
 ```typescript
 interface StoresQuery {
   stores: Array<{ id: string; name: string; status: string }>;

package/docs/graphql-guide.md

@@ -7,6 +7,8 @@ The Waffo Pancake GraphQL API is **query-only** — Mutations are not supported
 Introspection is **enabled by default**. Use it during development to explore the full schema, discover available types, fields, and filter conditions.
 
 > **Recommended**: Always use introspection to stay in sync with the server — this guide covers common queries, but the schema is the source of truth.
+>
+> **Important**: The SDK's TypeScript types (e.g. `Prices`, `MediaItem`) reflect the **REST API** shape. The GraphQL schema may represent the same data differently — for example, `prices` is a `Record<string, PriceInfo>` in REST but `[CurrencyPrice!]!` (array of `{currency, priceInfo}`) in GraphQL. Always use introspection or the examples below for GraphQL field names, not the SDK type definitions.
 
 ### Discover All Query Fields
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waffo/pancake-ts",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "TypeScript SDK for Waffo Pancake API (Merchant API Key authentication)",
   "type": "module",
   "main": "./dist/index.cjs",