@waffo/pancake-ts 0.2.2 → 0.3.1

package/docs/api-reference.md

@@ -5,7 +5,7 @@ Complete reference for all `@waffo/pancake-ts` resources, parameters, and return
 > **Conventions**:
 > - All amounts are in the **smallest currency unit** (e.g. 999 = $9.99 USD, 4500 = ¥4500 JPY)
 > - All timestamps are **ISO 8601 UTC** strings
-> - Product updates follow **immutable versioning** — each update creates a new version, skipped if content is unchanged
+> - Product updates follow **immutable versioning** — only provided fields are updated (omitted fields are preserved), each update creates a new version, skipped if content is unchanged
 > - The **publish** flow promotes a test version to production
 
 ---
@@ -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`**:
@@ -270,10 +278,18 @@ const { product } = await client.onetimeProducts.create({
 
 Update a one-time product. Creates a new immutable version; skips if content is unchanged.
 
+> Only `id` is required. Omitted fields keep their current values.
+
 ```typescript
+// Update only the name
 const { product } = await client.onetimeProducts.update({
   id: "PROD_xxx",
   name: "E-Book: TypeScript Handbook v2",
+});
+
+// Update only the prices
+const { product: p2 } = await client.onetimeProducts.update({
+  id: "PROD_xxx",
   prices: { USD: { amount: "39.00", taxCategory: "digital_goods" } },
 });
 ```
@@ -283,8 +299,8 @@ const { product } = await client.onetimeProducts.update({
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `id` | `string` | Yes | Product ID |
-| `name` | `string` | Yes | Product name |
-| `prices` | `Prices` | Yes | Multi-currency prices |
+| `name` | `string` | No | Product name |
+| `prices` | `Prices` | No | Multi-currency prices |
 | `description` | `string` | No | Product description |
 | `media` | `MediaItem[]` | No | Media assets |
 | `successUrl` | `string` | No | Redirect URL after successful payment |
@@ -369,16 +385,35 @@ const { product } = await client.subscriptionProducts.create({
 
 Update a subscription product. Creates a new immutable version; skips if unchanged.
 
+> Only `id` is required. Omitted fields keep their current values.
+
 ```typescript
+// Update only the name
 const { product } = await client.subscriptionProducts.update({
   id: "PROD_xxx",
   name: "Pro Plan v2",
-  billingPeriod: BillingPeriod.Monthly,
-  prices: { USD: { amount: "14.99", taxCategory: "saas" } },
+});
+
+// Update billing period and prices
+const { product: p2 } = await client.subscriptionProducts.update({
+  id: "PROD_xxx",
+  billingPeriod: BillingPeriod.Yearly,
+  prices: { USD: { amount: "99.00", taxCategory: "saas" } },
 });
 ```
 
-**Parameters `UpdateSubscriptionProductParams`**: Same as create, but `id` replaces `storeId`.
+**Parameters `UpdateSubscriptionProductParams`**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Product ID |
+| `name` | `string` | No | Product name |
+| `billingPeriod` | `BillingPeriod` | No | Billing period |
+| `prices` | `Prices` | No | Multi-currency prices |
+| `description` | `string` | No | Product description |
+| `media` | `MediaItem[]` | No | Media assets |
+| `successUrl` | `string` | No | Redirect URL after successful payment |
+| `metadata` | `Record<string, unknown>` | No | Custom metadata |
 
 **Returns `{ product: SubscriptionProductDetail }`**
 
@@ -607,9 +642,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 +651,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 +663,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 +693,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 +710,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 +733,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 +743,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 +781,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.1",
   "description": "TypeScript SDK for Waffo Pancake API (Merchant API Key authentication)",
   "type": "module",
   "main": "./dist/index.cjs",