@waffo/pancake-ts 0.3.3 → 0.4.0

package/dist/index.d.cts

@@ -211,7 +211,12 @@ declare enum ErrorLayer {
  * @see waffo-pancake-user-service/app/lib/utils/jwt.ts IssueSessionTokenRequest
  */
 interface IssueSessionTokenParams {
-    /** Buyer identity (email or any merchant-provided identifier string) */
+    /**
+     * Buyer identity — encoded into the JWT payload for merchant-side buyer
+     * identification. Accepts an email or any merchant-provided identifier string.
+     * To pre-fill the checkout page's email field, use `buyerEmail` on
+     * `checkout.authenticated.create`.
+     */
     buyerIdentity: string;
     /** Store ID (optional when `productId` is provided) */
     storeId?: string;
@@ -304,7 +309,13 @@ interface CreateStoreParams {
     /** Store name (slug is auto-generated) */
     name: string;
 }
-/** Parameters for updating a store. */
+/**
+ * Parameters for updating a store.
+ *
+ * Settings objects support partial updates — omitted sub-fields keep their
+ * existing values, `null` clears a field, and a concrete value sets it.
+ * Pass the entire settings object as `null` to clear all fields in the group.
+ */
 interface UpdateStoreParams {
     /** Store ID */
     id: string;
@@ -318,12 +329,12 @@ interface UpdateStoreParams {
     supportEmail?: string | null;
     /** Store website URL (set to `null` to remove) */
     website?: string | null;
-    /** Webhook configuration for test and production environments (set to `null` to remove) */
-    webhookSettings?: WebhookSettings | null;
-    /** Notification preferences (set to `null` to remove) */
-    notificationSettings?: NotificationSettings | null;
-    /** Checkout page theme configuration (set to `null` to remove) */
-    checkoutSettings?: CheckoutSettings | null;
+    /** Webhook configuration (partial update — omitted fields keep existing values, set to `null` to clear all) */
+    webhookSettings?: Partial<WebhookSettings> | null;
+    /** Notification preferences (partial update — omitted fields keep existing values, set to `null` to clear all) */
+    notificationSettings?: Partial<NotificationSettings> | null;
+    /** Checkout page theme configuration (partial update — omitted fields keep existing values, set to `null` to clear all) */
+    checkoutSettings?: Partial<CheckoutSettings> | null;
 }
 /** Parameters for deleting (soft-delete) a store. */
 interface DeleteStoreParams {
@@ -746,8 +757,11 @@ interface RefundTicket {
 /**
  * Parameters for anonymous checkout.
  *
- * The buyer enters the checkout page without a session token and fills in
- * billing details manually. No identity is provided upfront.
+ * The buyer reaches the checkout page without a session token. Merchants may still
+ * pre-fill `buyerEmail` and `billingDetail`; omitting them leaves the form blank.
+ *
+ * Accepts every field of {@link CreateCheckoutSessionParams} — this wrapper simply
+ * forwards the params unchanged to `/v1/actions/checkout/create-session`.
  *
  * @example
  * const result = await client.checkout.anonymous.create({
@@ -756,61 +770,32 @@ interface RefundTicket {
  * });
  * // Redirect to result.checkoutUrl
  */
-interface AnonymousCheckoutParams {
-    /** Product ID */
-    productId: string;
-    /** Currency code (ISO 4217) */
-    currency: string;
-    /** Optional price snapshot override (reads from DB if omitted) */
-    priceSnapshot?: PriceInfo;
-    /** Trial toggle override (subscription only) */
-    withTrial?: boolean;
-    /** Redirect URL after successful payment */
-    successUrl?: string;
-    /** Session expiration in seconds (default: 45 minutes) */
-    expiresInSeconds?: number;
-    /** Dark mode override (true=dark, false=light, omit=use store default) */
-    darkMode?: boolean;
-    /** Custom metadata */
-    metadata?: Record<string, string>;
-}
+type AnonymousCheckoutParams = CreateCheckoutSessionParams;
 /**
  * Parameters for authenticated checkout.
  *
- * The merchant provides a buyer identity; the SDK issues a session token
- * and appends it to the checkout URL as a URL fragment.
+ * Merges the checkout-session fields ({@link CreateCheckoutSessionParams}) with the
+ * extra `buyerIdentity` required by `issue-session-token`. The wrapper splits the
+ * input: `buyerIdentity` goes to the token call; everything else (including
+ * `buyerEmail`) goes to the create-session call. The two fields are independent.
  *
  * @example
  * const result = await client.checkout.authenticated.create({
  *   productId: "PROD_xxx",
  *   currency: "USD",
- *   buyerIdentity: "customer@example.com",
+ *   buyerIdentity: "user-123",            // merchant-side buyer id (goes into JWT)
+ *   buyerEmail: "customer@example.com",   // pre-filled on the checkout page
  * });
  * // Redirect to result.checkoutUrl (includes #token=...)
  */
-interface AuthenticatedCheckoutParams {
-    /** Product ID */
-    productId: string;
-    /** Currency code (ISO 4217) */
-    currency: string;
-    /** Buyer identity (email or merchant-provided identifier) */
+interface AuthenticatedCheckoutParams extends CreateCheckoutSessionParams {
+    /**
+     * Buyer identity — sent to `issue-session-token` and encoded into the JWT
+     * payload for merchant-side buyer identification. Accepts an email or any
+     * merchant-provided identifier string. Use `buyerEmail` to pre-fill the
+     * checkout page's email input.
+     */
     buyerIdentity: string;
-    /** Pre-filled buyer email (defaults to `buyerIdentity` when omitted) */
-    buyerEmail?: string;
-    /** Pre-filled billing details */
-    billingDetail?: BillingDetail;
-    /** Optional price snapshot override (reads from DB if omitted) */
-    priceSnapshot?: PriceInfo;
-    /** Trial toggle override (subscription only) */
-    withTrial?: boolean;
-    /** Redirect URL after successful payment */
-    successUrl?: string;
-    /** Session expiration in seconds (default: 45 minutes) */
-    expiresInSeconds?: number;
-    /** Dark mode override (true=dark, false=light, omit=use store default) */
-    darkMode?: boolean;
-    /** Custom metadata */
-    metadata?: Record<string, string>;
 }
 /**
  * Result of an authenticated checkout creation.
@@ -1157,7 +1142,8 @@ declare class BuyerGraphQL {
 /**
  * Anonymous checkout — no buyer identity provided.
  *
- * The buyer fills in billing details manually on the checkout page.
+ * The buyer reaches the checkout page without a session token. Merchants may still
+ * pre-fill `buyerEmail` and `billingDetail` on the page by passing them here.
  * Internally creates a checkout session and returns the redirect URL.
  */
 declare class CheckoutAnonymousResource {
@@ -1170,11 +1156,20 @@ declare class CheckoutAnonymousResource {
      * @returns Session ID, checkout URL, and expiration
      *
      * @example
+     * // Minimal — buyer fills everything on the page
      * const result = await client.checkout.anonymous.create({
      *   productId: "PROD_xxx",
      *   currency: "USD",
      * });
-     * // Redirect to result.checkoutUrl
+     *
+     * @example
+     * // Pre-fill email and billing without issuing a session token
+     * const result = await client.checkout.anonymous.create({
+     *   productId: "PROD_xxx",
+     *   currency: "USD",
+     *   buyerEmail: "customer@example.com",
+     *   billingDetail: { country: "US", isBusiness: false, postcode: "10001" },
+     * });
      */
     create(params: AnonymousCheckoutParams): Promise<CheckoutSessionResult>;
 }
@@ -1193,10 +1188,12 @@ declare class CheckoutAuthenticatedResource {
      * Create an authenticated checkout session.
      *
      * Behavior:
-     * - Issues a session token via `issue-session-token`
-     * - Creates a checkout session via `create-session`
-     * - Appends the token to the checkout URL as a URL fragment
-     * - Defaults `buyerEmail` to `buyerIdentity` when omitted
+     * - Issues a session token via `issue-session-token` (receives `buyerIdentity` + `productId` only)
+     * - Creates a checkout session via `create-session` (receives every other field unchanged)
+     * - Appends the token to the checkout URL as a URL fragment (`#token=...`)
+     *
+     * `buyerIdentity` and `buyerEmail` are independent inputs: identity is for the JWT,
+     * email is for pre-filling the checkout page. The SDK forwards each to its own endpoint.
      *
      * @param params - Checkout parameters including buyer identity
      * @returns Session details with token-appended checkout URL
@@ -1205,7 +1202,8 @@ declare class CheckoutAuthenticatedResource {
      * const result = await client.checkout.authenticated.create({
      *   productId: "PROD_xxx",
      *   currency: "USD",
-     *   buyerIdentity: "customer@example.com",
+     *   buyerIdentity: "user-123",
+     *   buyerEmail: "customer@example.com",
      * });
      * // Redirect to result.checkoutUrl (includes #token=...)
      */
@@ -1233,7 +1231,8 @@ declare class CheckoutAuthenticatedResource {
  * const result = await client.checkout.authenticated.create({
  *   productId: "PROD_xxx",
  *   currency: "USD",
- *   buyerIdentity: "customer@example.com",
+ *   buyerIdentity: "userIdInYourSystem",
+ *   buyerEmail: "customer@example.com",
  * });
  * // result.checkoutUrl includes #token=...
  */
@@ -1449,14 +1448,26 @@ declare class StoresResource {
     /**
      * 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.
+     *
      * @param params - Fields to update (only provided fields are changed)
      * @returns Updated store entity
      *
      * @example
+     * // Update name
      * const { store } = await client.stores.update({
      *   id: "STO_xxx",
      *   name: "Updated Name",
      * });
+     *
+     * @example
+     * // Clear test webhook URL while keeping other webhook settings
+     * const { store } = await client.stores.update({
+     *   id: "STO_xxx",
+     *   webhookSettings: { testWebhookUrl: null },
+     * });
      */
     update(params: UpdateStoreParams): Promise<{
         store: Store;

package/dist/index.d.ts

@@ -211,7 +211,12 @@ declare enum ErrorLayer {
  * @see waffo-pancake-user-service/app/lib/utils/jwt.ts IssueSessionTokenRequest
  */
 interface IssueSessionTokenParams {
-    /** Buyer identity (email or any merchant-provided identifier string) */
+    /**
+     * Buyer identity — encoded into the JWT payload for merchant-side buyer
+     * identification. Accepts an email or any merchant-provided identifier string.
+     * To pre-fill the checkout page's email field, use `buyerEmail` on
+     * `checkout.authenticated.create`.
+     */
     buyerIdentity: string;
     /** Store ID (optional when `productId` is provided) */
     storeId?: string;
@@ -304,7 +309,13 @@ interface CreateStoreParams {
     /** Store name (slug is auto-generated) */
     name: string;
 }
-/** Parameters for updating a store. */
+/**
+ * Parameters for updating a store.
+ *
+ * Settings objects support partial updates — omitted sub-fields keep their
+ * existing values, `null` clears a field, and a concrete value sets it.
+ * Pass the entire settings object as `null` to clear all fields in the group.
+ */
 interface UpdateStoreParams {
     /** Store ID */
     id: string;
@@ -318,12 +329,12 @@ interface UpdateStoreParams {
     supportEmail?: string | null;
     /** Store website URL (set to `null` to remove) */
     website?: string | null;
-    /** Webhook configuration for test and production environments (set to `null` to remove) */
-    webhookSettings?: WebhookSettings | null;
-    /** Notification preferences (set to `null` to remove) */
-    notificationSettings?: NotificationSettings | null;
-    /** Checkout page theme configuration (set to `null` to remove) */
-    checkoutSettings?: CheckoutSettings | null;
+    /** Webhook configuration (partial update — omitted fields keep existing values, set to `null` to clear all) */
+    webhookSettings?: Partial<WebhookSettings> | null;
+    /** Notification preferences (partial update — omitted fields keep existing values, set to `null` to clear all) */
+    notificationSettings?: Partial<NotificationSettings> | null;
+    /** Checkout page theme configuration (partial update — omitted fields keep existing values, set to `null` to clear all) */
+    checkoutSettings?: Partial<CheckoutSettings> | null;
 }
 /** Parameters for deleting (soft-delete) a store. */
 interface DeleteStoreParams {
@@ -746,8 +757,11 @@ interface RefundTicket {
 /**
  * Parameters for anonymous checkout.
  *
- * The buyer enters the checkout page without a session token and fills in
- * billing details manually. No identity is provided upfront.
+ * The buyer reaches the checkout page without a session token. Merchants may still
+ * pre-fill `buyerEmail` and `billingDetail`; omitting them leaves the form blank.
+ *
+ * Accepts every field of {@link CreateCheckoutSessionParams} — this wrapper simply
+ * forwards the params unchanged to `/v1/actions/checkout/create-session`.
  *
  * @example
  * const result = await client.checkout.anonymous.create({
@@ -756,61 +770,32 @@ interface RefundTicket {
  * });
  * // Redirect to result.checkoutUrl
  */
-interface AnonymousCheckoutParams {
-    /** Product ID */
-    productId: string;
-    /** Currency code (ISO 4217) */
-    currency: string;
-    /** Optional price snapshot override (reads from DB if omitted) */
-    priceSnapshot?: PriceInfo;
-    /** Trial toggle override (subscription only) */
-    withTrial?: boolean;
-    /** Redirect URL after successful payment */
-    successUrl?: string;
-    /** Session expiration in seconds (default: 45 minutes) */
-    expiresInSeconds?: number;
-    /** Dark mode override (true=dark, false=light, omit=use store default) */
-    darkMode?: boolean;
-    /** Custom metadata */
-    metadata?: Record<string, string>;
-}
+type AnonymousCheckoutParams = CreateCheckoutSessionParams;
 /**
  * Parameters for authenticated checkout.
  *
- * The merchant provides a buyer identity; the SDK issues a session token
- * and appends it to the checkout URL as a URL fragment.
+ * Merges the checkout-session fields ({@link CreateCheckoutSessionParams}) with the
+ * extra `buyerIdentity` required by `issue-session-token`. The wrapper splits the
+ * input: `buyerIdentity` goes to the token call; everything else (including
+ * `buyerEmail`) goes to the create-session call. The two fields are independent.
  *
  * @example
  * const result = await client.checkout.authenticated.create({
  *   productId: "PROD_xxx",
  *   currency: "USD",
- *   buyerIdentity: "customer@example.com",
+ *   buyerIdentity: "user-123",            // merchant-side buyer id (goes into JWT)
+ *   buyerEmail: "customer@example.com",   // pre-filled on the checkout page
  * });
  * // Redirect to result.checkoutUrl (includes #token=...)
  */
-interface AuthenticatedCheckoutParams {
-    /** Product ID */
-    productId: string;
-    /** Currency code (ISO 4217) */
-    currency: string;
-    /** Buyer identity (email or merchant-provided identifier) */
+interface AuthenticatedCheckoutParams extends CreateCheckoutSessionParams {
+    /**
+     * Buyer identity — sent to `issue-session-token` and encoded into the JWT
+     * payload for merchant-side buyer identification. Accepts an email or any
+     * merchant-provided identifier string. Use `buyerEmail` to pre-fill the
+     * checkout page's email input.
+     */
     buyerIdentity: string;
-    /** Pre-filled buyer email (defaults to `buyerIdentity` when omitted) */
-    buyerEmail?: string;
-    /** Pre-filled billing details */
-    billingDetail?: BillingDetail;
-    /** Optional price snapshot override (reads from DB if omitted) */
-    priceSnapshot?: PriceInfo;
-    /** Trial toggle override (subscription only) */
-    withTrial?: boolean;
-    /** Redirect URL after successful payment */
-    successUrl?: string;
-    /** Session expiration in seconds (default: 45 minutes) */
-    expiresInSeconds?: number;
-    /** Dark mode override (true=dark, false=light, omit=use store default) */
-    darkMode?: boolean;
-    /** Custom metadata */
-    metadata?: Record<string, string>;
 }
 /**
  * Result of an authenticated checkout creation.
@@ -1157,7 +1142,8 @@ declare class BuyerGraphQL {
 /**
  * Anonymous checkout — no buyer identity provided.
  *
- * The buyer fills in billing details manually on the checkout page.
+ * The buyer reaches the checkout page without a session token. Merchants may still
+ * pre-fill `buyerEmail` and `billingDetail` on the page by passing them here.
  * Internally creates a checkout session and returns the redirect URL.
  */
 declare class CheckoutAnonymousResource {
@@ -1170,11 +1156,20 @@ declare class CheckoutAnonymousResource {
      * @returns Session ID, checkout URL, and expiration
      *
      * @example
+     * // Minimal — buyer fills everything on the page
      * const result = await client.checkout.anonymous.create({
      *   productId: "PROD_xxx",
      *   currency: "USD",
      * });
-     * // Redirect to result.checkoutUrl
+     *
+     * @example
+     * // Pre-fill email and billing without issuing a session token
+     * const result = await client.checkout.anonymous.create({
+     *   productId: "PROD_xxx",
+     *   currency: "USD",
+     *   buyerEmail: "customer@example.com",
+     *   billingDetail: { country: "US", isBusiness: false, postcode: "10001" },
+     * });
      */
     create(params: AnonymousCheckoutParams): Promise<CheckoutSessionResult>;
 }
@@ -1193,10 +1188,12 @@ declare class CheckoutAuthenticatedResource {
      * Create an authenticated checkout session.
      *
      * Behavior:
-     * - Issues a session token via `issue-session-token`
-     * - Creates a checkout session via `create-session`
-     * - Appends the token to the checkout URL as a URL fragment
-     * - Defaults `buyerEmail` to `buyerIdentity` when omitted
+     * - Issues a session token via `issue-session-token` (receives `buyerIdentity` + `productId` only)
+     * - Creates a checkout session via `create-session` (receives every other field unchanged)
+     * - Appends the token to the checkout URL as a URL fragment (`#token=...`)
+     *
+     * `buyerIdentity` and `buyerEmail` are independent inputs: identity is for the JWT,
+     * email is for pre-filling the checkout page. The SDK forwards each to its own endpoint.
      *
      * @param params - Checkout parameters including buyer identity
      * @returns Session details with token-appended checkout URL
@@ -1205,7 +1202,8 @@ declare class CheckoutAuthenticatedResource {
      * const result = await client.checkout.authenticated.create({
      *   productId: "PROD_xxx",
      *   currency: "USD",
-     *   buyerIdentity: "customer@example.com",
+     *   buyerIdentity: "user-123",
+     *   buyerEmail: "customer@example.com",
      * });
      * // Redirect to result.checkoutUrl (includes #token=...)
      */
@@ -1233,7 +1231,8 @@ declare class CheckoutAuthenticatedResource {
  * const result = await client.checkout.authenticated.create({
  *   productId: "PROD_xxx",
  *   currency: "USD",
- *   buyerIdentity: "customer@example.com",
+ *   buyerIdentity: "userIdInYourSystem",
+ *   buyerEmail: "customer@example.com",
  * });
  * // result.checkoutUrl includes #token=...
  */
@@ -1449,14 +1448,26 @@ declare class StoresResource {
     /**
      * 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.
+     *
      * @param params - Fields to update (only provided fields are changed)
      * @returns Updated store entity
      *
      * @example
+     * // Update name
      * const { store } = await client.stores.update({
      *   id: "STO_xxx",
      *   name: "Updated Name",
      * });
+     *
+     * @example
+     * // Clear test webhook URL while keeping other webhook settings
+     * const { store } = await client.stores.update({
+     *   id: "STO_xxx",
+     *   webhookSettings: { testWebhookUrl: null },
+     * });
      */
     update(params: UpdateStoreParams): Promise<{
         store: Store;

package/dist/index.js

@@ -464,11 +464,20 @@ var CheckoutAnonymousResource = class {
    * @returns Session ID, checkout URL, and expiration
    *
    * @example
+   * // Minimal — buyer fills everything on the page
    * const result = await client.checkout.anonymous.create({
    *   productId: "PROD_xxx",
    *   currency: "USD",
    * });
-   * // Redirect to result.checkoutUrl
+   *
+   * @example
+   * // Pre-fill email and billing without issuing a session token
+   * const result = await client.checkout.anonymous.create({
+   *   productId: "PROD_xxx",
+   *   currency: "USD",
+   *   buyerEmail: "customer@example.com",
+   *   billingDetail: { country: "US", isBusiness: false, postcode: "10001" },
+   * });
    */
   async create(params) {
     validateCheckoutCommon(params);
@@ -485,10 +494,12 @@ var CheckoutAuthenticatedResource = class {
    * Create an authenticated checkout session.
    *
    * Behavior:
-   * - Issues a session token via `issue-session-token`
-   * - Creates a checkout session via `create-session`
-   * - Appends the token to the checkout URL as a URL fragment
-   * - Defaults `buyerEmail` to `buyerIdentity` when omitted
+   * - Issues a session token via `issue-session-token` (receives `buyerIdentity` + `productId` only)
+   * - Creates a checkout session via `create-session` (receives every other field unchanged)
+   * - Appends the token to the checkout URL as a URL fragment (`#token=...`)
+   *
+   * `buyerIdentity` and `buyerEmail` are independent inputs: identity is for the JWT,
+   * email is for pre-filling the checkout page. The SDK forwards each to its own endpoint.
    *
    * @param params - Checkout parameters including buyer identity
    * @returns Session details with token-appended checkout URL
@@ -497,14 +508,15 @@ var CheckoutAuthenticatedResource = class {
    * const result = await client.checkout.authenticated.create({
    *   productId: "PROD_xxx",
    *   currency: "USD",
-   *   buyerIdentity: "customer@example.com",
+   *   buyerIdentity: "user-123",
+   *   buyerEmail: "customer@example.com",
    * });
    * // Redirect to result.checkoutUrl (includes #token=...)
    */
   async create(params) {
     validateCheckoutCommon(params);
     validateRequired("buyerIdentity", params.buyerIdentity);
-    const { buyerIdentity, buyerEmail, ...sessionFields } = params;
+    const { buyerIdentity, ...sessionParams } = params;
     const [tokenResult, sessionResult] = await Promise.all([
       this.http.post(
         "/v1/actions/auth/issue-session-token",
@@ -514,14 +526,7 @@ var CheckoutAuthenticatedResource = class {
         },
         { idempotencyWindow: 60 }
       ),
-      this.http.post(
-        "/v1/actions/checkout/create-session",
-        {
-          ...sessionFields,
-          buyerEmail: buyerEmail ?? buyerIdentity
-        },
-        { idempotencyWindow: 60 }
-      )
+      this.http.post("/v1/actions/checkout/create-session", sessionParams, { idempotencyWindow: 60 })
     ]);
     return {
       sessionId: sessionResult.sessionId,
@@ -786,14 +791,26 @@ 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.
+   *
    * @param params - Fields to update (only provided fields are changed)
    * @returns Updated store entity
    *
    * @example
+   * // Update name
    * const { store } = await client.stores.update({
    *   id: "STO_xxx",
    *   name: "Updated Name",
    * });
+   *
+   * @example
+   * // Clear test webhook URL while keeping other webhook settings
+   * const { store } = await client.stores.update({
+   *   id: "STO_xxx",
+   *   webhookSettings: { testWebhookUrl: null },
+   * });
    */
   async update(params) {
     validateShortId("id", params.id, "STO");