@waffo/pancake-ts 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.6.0] - 2026-05-07
+
+### BREAKING
+
+- **`UpdateStoreParams.webhookSettings` removed** — webhook configuration is no longer managed through `client.stores.update()`. The legacy single-URL JSONB shape (`testWebhookUrl` / `prodWebhookUrl` / `testEvents` / `prodEvents`) has been replaced by a multi-row `store.store_webhooks` table supporting multiple webhooks and multiple channels per store.
+- **`WebhookSettings` type removed** from public exports. Replaced by `StoreWebhook`, `WebhookChannel`, and the new `Add/Update/RemoveWebhookParams` types.
+- The server's `update-store` endpoint accepts the legacy `webhookSettings` field for backward compatibility but **ignores it** and returns `200` with a top-level `warnings` array containing `WEBHOOK_SETTINGS_IGNORED` and an `aiHint` describing the migration path. Old SDK calls will silently lose webhook updates — upgrade to use the new methods below.
+
+### Added
+
+- **`client.webhooks.add / update / remove`** — manage webhook endpoints (HTTP / Feishu / Discord / Telegram / Slack) via dedicated mutations.
+  - `channel` field selects the payload format. HTTP keeps the existing RSA-signed envelope (no breakage on the merchant consumption side); IM platforms render their native card / embed / attachment formats.
+  - `secret` field stores channel-specific credentials (e.g. Telegram `chat_id`).
+  - Any valid HTTPS URL accepted; merchant ensures the URL matches the chosen channel.
+  - Hard-delete; historical `webhook_deliveries` rows are retained with `storeWebhookId = null` for audit.
+- **`StoreWebhook`, `WebhookChannel`, `AddWebhookParams`, `UpdateWebhookParams`, `RemoveWebhookParams`** types exported.
+
+### Migration
+
+- **List webhooks**: query GraphQL `Store.storeWebhooks` (filtered automatically by environment via `test_mode`). The SDK does not expose a `list` method — `client.graphql.query` is the only read path, by design.
+- **Create/Update/Delete**: replace `client.stores.update({ id, webhookSettings: {...} })` with `client.webhooks.add({...})` / `update({...})` / `remove({ id })`.
+
 ## [0.5.2] - 2026-04-22
 
 ### Added

package/README.md

@@ -315,16 +315,11 @@ See [GraphQL Guide](docs/graphql-guide.md) for filters, analytics queries, deliv
 // Create a store
 const { store } = await client.stores.create({ name: "My Store" });
 
-// Update settings (webhook, notification, checkout theme)
+// Update settings (notification, checkout theme).
+// NOTE: webhook configuration moved to client.webhooks (see Webhooks section below).
 const { store: updated } = await client.stores.update({
   id: store.id,
   supportEmail: "help@example.com",
-  webhookSettings: {
-    testWebhookUrl: "https://example.com/webhooks",
-    prodWebhookUrl: null,
-    testEvents: ["order.completed", "subscription.activated"],
-    prodEvents: [],
-  },
   notificationSettings: {
     emailOrderConfirmation: true,
     emailSubscriptionConfirmation: true,
@@ -341,6 +336,51 @@ const { store: updated } = await client.stores.update({
 const { store: deleted } = await client.stores.delete({ id: store.id });
 ```
 
+### Webhooks
+
+Manage webhook endpoints across HTTP, Feishu, Discord, Telegram, and Slack. Each store can have up to 20 webhooks across all channels.
+
+```typescript
+// Add a standard HTTPS webhook (RSA-signed envelope)
+const { webhook } = await client.webhooks.add({
+  storeId: store.id,
+  channel: "http",
+  url: "https://example.com/webhooks/pancake",
+  events: ["order.completed", "refund.succeeded"],
+  testMode: false,
+});
+
+// Add a Discord webhook (uses Discord embed format)
+await client.webhooks.add({
+  storeId: store.id,
+  channel: "discord",
+  url: "https://discord.com/api/webhooks/123/abc",
+  events: ["order.completed"],
+  testMode: false,
+});
+
+// Add a Telegram webhook (chat_id stored in `secret`)
+await client.webhooks.add({
+  storeId: store.id,
+  channel: "telegram",
+  url: "https://api.telegram.org/bot123:ABC/sendMessage",
+  events: ["order.completed"],
+  testMode: false,
+  secret: "8737101383",
+});
+
+// Update events
+await client.webhooks.update({
+  id: webhook.id,
+  events: ["order.completed", "refund.succeeded", "subscription.canceled"],
+});
+
+// Hard-delete a webhook (delivery history retained for audit)
+await client.webhooks.remove({ id: webhook.id });
+```
+
+> **Listing**: query the configured webhook list via GraphQL `Store.storeWebhooks` (filtered by environment automatically). The SDK does not expose a `list` method — `client.graphql.query` is the only read path, by design.
+
 ### Products
 
 ```typescript
@@ -434,22 +474,22 @@ try {
 
 ## Resources
 
-| Namespace                          | Methods                                                                                                                  | Description                          |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
-| `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>()`                                                                                                             | 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)          |
-| `client.onetimeProducts`           | `create()` `update()` `publish()` `updateStatus()`                                                                       | One-time products                    |
-| `client.subscriptionProducts`      | `create()` `update()` `publish()` `updateStatus()`                                                                       | Subscription products                |
-| `client.subscriptionProductGroups` | `create()` `update()` `delete()` `publish()`                                                                             | Product groups                       |
-| `client.orders`                    | `cancelSubscription()`                                                                                                   | Order management                     |
+| Namespace                          | Methods                                                                                                                  | Description                             |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
+| `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>()` `add()` `update()` `remove()`                                                                              | Webhook config + signature verification |
+| `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)             |
+| `client.onetimeProducts`           | `create()` `update()` `publish()` `updateStatus()`                                                                       | One-time products                       |
+| `client.subscriptionProducts`      | `create()` `update()` `publish()` `updateStatus()`                                                                       | Subscription products                   |
+| `client.subscriptionProductGroups` | `create()` `update()` `delete()` `publish()`                                                                             | Product groups                          |
+| `client.orders`                    | `cancelSubscription()`                                                                                                   | Order management                        |
 
 ## Documentation
 

package/dist/index.cjs

@@ -833,9 +833,13 @@ var StoresResource = class {
   /**
    * Update an existing store's settings.
    *
-   * Settings objects (`webhookSettings`, `notificationSettings`, `checkoutSettings`)
-   * support partial updates: omitted sub-fields keep existing values, `null` clears
-   * a field. Pass the entire settings object as `null` to clear all fields.
+   * Settings objects (`notificationSettings`, `checkoutSettings`) support
+   * partial updates: omitted sub-fields keep existing values, `null` clears a
+   * field. Pass the entire settings object as `null` to clear all fields.
+   *
+   * **BREAKING (2026-05)**: the legacy `webhookSettings` parameter is removed.
+   * Use `client.webhooks.add / update / remove` to manage webhook endpoints,
+   * and query the configured webhook list via GraphQL `Store.storeWebhooks`.
    *
    * @param params - Fields to update (only provided fields are changed)
    * @returns Updated store entity
@@ -848,10 +852,10 @@ var StoresResource = class {
    * });
    *
    * @example
-   * // Clear test webhook URL while keeping other webhook settings
+   * // Toggle a notification preference
    * const { store } = await client.stores.update({
    *   id: "STO_xxx",
-   *   webhookSettings: { testWebhookUrl: null },
+   *   notificationSettings: { emailOrderConfirmation: false },
    * });
    */
   async update(params) {
@@ -1132,10 +1136,91 @@ function verifyWebhook(payload, signatureHeader, options) {
 
 // src/resources/webhooks.ts
 var WebhooksResource = class {
-  /** @param publicKeys - Optional config-level public key(s) from WaffoPancakeConfig */
-  constructor(publicKeys) {
+  /**
+   * @param http - HTTP client (used for add/update/remove)
+   * @param publicKeys - Optional config-level public key(s) from WaffoPancakeConfig
+   */
+  constructor(http, publicKeys) {
+    this.http = http;
     this.publicKeys = publicKeys;
   }
+  /**
+   * Add a webhook endpoint to a store.
+   *
+   * @param params - Webhook configuration
+   * @returns Created webhook entity
+   *
+   * @example
+   * // HTTP webhook (RSA-signed envelope, default)
+   * const { webhook } = await client.webhooks.add({
+   *   storeId: "STO_xxx",
+   *   channel: "http",
+   *   url: "https://example.com/webhook",
+   *   events: ["order.completed", "refund.succeeded"],
+   *   testMode: false,
+   * });
+   *
+   * @example
+   * // Discord webhook (uses Discord embed format)
+   * await client.webhooks.add({
+   *   storeId: "STO_xxx",
+   *   channel: "discord",
+   *   url: "https://discord.com/api/webhooks/...",
+   *   events: ["order.completed"],
+   *   testMode: false,
+   * });
+   *
+   * @example
+   * // Telegram bot — chat_id goes in `secret`; URL is the bot's sendMessage endpoint
+   * await client.webhooks.add({
+   *   storeId: "STO_xxx",
+   *   channel: "telegram",
+   *   url: "https://api.telegram.org/bot123:ABC/sendMessage",
+   *   events: ["order.completed"],
+   *   testMode: false,
+   *   secret: "8737101383",
+   * });
+   */
+  async add(params) {
+    validateShortId("storeId", params.storeId, "STO");
+    validateRequired("channel", params.channel);
+    validateRequired("url", params.url);
+    return this.http.post("/v1/actions/store/add-webhook", params);
+  }
+  /**
+   * Update an existing webhook (only `url`, `events`, and `secret` are mutable).
+   *
+   * `channel` and `testMode` cannot be changed — remove the webhook and
+   * re-add it instead. URL changes must remain on the same channel host
+   * whitelist.
+   *
+   * @param params - Fields to update
+   * @returns Updated webhook entity
+   *
+   * @example
+   * await client.webhooks.update({
+   *   id: "11111111-2222-3333-4444-555555555555",
+   *   events: ["order.completed", "refund.succeeded", "subscription.canceled"],
+   * });
+   */
+  async update(params) {
+    validateRequired("id", params.id);
+    return this.http.post("/v1/actions/store/update-webhook", params);
+  }
+  /**
+   * Hard-delete a webhook. Historical `webhook_deliveries` rows are retained
+   * (with `storeWebhookId` set to null) for audit purposes.
+   *
+   * @param params - Webhook to remove
+   * @returns The removed webhook entity (snapshot before deletion)
+   *
+   * @example
+   * await client.webhooks.remove({ id: "11111111-..." });
+   */
+  async remove(params) {
+    validateRequired("id", params.id);
+    return this.http.post("/v1/actions/store/remove-webhook", params);
+  }
   /**
    * Verify and parse an incoming webhook event.
    *
@@ -1199,7 +1284,7 @@ var WaffoPancake = class {
     this.orders = new OrdersResource(this.http);
     this.checkout = new CheckoutResource(this.http);
     this.graphql = new GraphQLResource(this.http);
-    this.webhooks = new WebhooksResource(config.webhookPublicKey);
+    this.webhooks = new WebhooksResource(this.http, config.webhookPublicKey);
   }
   /**
    * Create a buyer session for self-service operations.