@waffo/pancake-ts 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -29,34 +29,56 @@ interface PostOptions {
      * produce a new key after the window elapses (e.g. 60 = per-minute dedup).
      */
     idempotencyWindow?: number;
+    /**
+     * Skip the X-Idempotency-Key header entirely. Set for read-only queries
+     * (e.g. GraphQL) so the gateway's 24h idempotency cache does not serve
+     * stale data on identical repeat queries.
+     */
+    noIdempotency?: boolean;
 }
 /**
- * Single error object within the `errors` array.
+ * Single Notice entry within `errors` or `warnings` arrays.
+ *
+ * Both REST and GraphQL envelopes use the same Notice shape. `aiHint` is the
+ * structured migration instruction for LLM consumers (see handbook
+ * `command-layer.md` aiHint four-line template).
  *
  * @example
  * { message: "Store slug already exists", layer: "store" }
+ * @example
+ * { message: "webhookSettings field ignored", layer: "store",
+ *   aiHint: "Switch to client.webhooks.add / update / remove" }
  */
-interface ApiError {
-    /** Error message */
+interface Notice {
+    /** Human-readable message */
     message: string;
-    /** Layer where the error originated */
+    /** Layer that produced this notice */
     layer: `${ErrorLayer}`;
+    /** Structured migration / remediation instruction for LLM consumers */
+    aiHint?: string;
 }
-/** Successful API response envelope. */
-interface ApiSuccessResponse<T> {
-    data: T;
-}
+/** @deprecated Use {@link Notice}. Kept for backwards compatibility with existing imports. */
+type ApiError = Notice;
 /**
- * Error API response envelope.
+ * API response envelope. Both REST writes and GraphQL queries return this shape:
+ * - Success: `{ data: T }` (optionally with `warnings`)
+ * - Failure: `{ data: null, errors: Notice[] }`
+ * - Partial success (GraphQL only): `{ data: T, errors: Notice[] }`
  *
  * `errors` are ordered by call stack: `[0]` is the deepest layer, `[n]` is the outermost.
+ *
+ * See handbook `coding-standards/code-style-guide/command-layer.md` for the wire contract.
  */
-interface ApiErrorResponse {
-    data: null;
-    errors: ApiError[];
+interface Envelope<T> {
+    data: T | null;
+    errors?: Notice[];
+    warnings?: Notice[];
+}
+/** Transport-layer result: HTTP status plus the parsed envelope. */
+interface PostResult<T> extends Envelope<T> {
+    /** HTTP status code from the response */
+    status: number;
 }
-/** Union type of success and error API responses. */
-type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
 /**
  * Environment type.
  * @see waffo-pancake-order-service/app/lib/types.ts
@@ -253,8 +275,8 @@ interface StoreWebhook {
     channel: WebhookChannel;
     /** Target webhook URL */
     url: string;
-    /** Subscribed event types (e.g. `order.completed`) */
-    events: string[];
+    /** Subscribed event types (use `WebhookEventType` enum or its string literal) */
+    events: `${WebhookEventType}`[];
     /** Whether this webhook fires in test or prod environment */
     testMode: boolean;
     /** Channel-specific credential (e.g. Telegram chat_id) */
@@ -269,8 +291,8 @@ interface AddWebhookParams {
     channel: WebhookChannel;
     /** Target webhook URL */
     url: string;
-    /** Subscribed event types */
-    events: string[];
+    /** Subscribed event types (use `WebhookEventType` enum or its string literal) */
+    events: `${WebhookEventType}`[];
     /** Whether this webhook fires in test (true) or prod (false) */
     testMode: boolean;
     /** Channel-specific credential (e.g. Telegram chat_id) */
@@ -282,8 +304,8 @@ interface UpdateWebhookParams {
     id: string;
     /** Replace target URL (must remain on the same channel host) */
     url?: string;
-    /** Replace subscribed event types */
-    events?: string[];
+    /** Replace subscribed event types (use `WebhookEventType` enum or its string literal) */
+    events?: `${WebhookEventType}`[];
     /** Replace channel-specific credential */
     secret?: string | null;
 }
@@ -875,7 +897,11 @@ interface GraphQLParams {
     /** Query variables */
     variables?: Record<string, unknown>;
 }
-/** GraphQL response envelope. */
+/**
+ * GraphQL response envelope. Same shape as {@link Envelope}, but `errors` entries
+ * may additionally carry `locations` and `path` (graphql-js fields). The `layer`
+ * field is optional on GraphQL because resolver errors don't carry one.
+ */
 interface GraphQLResponse<T = Record<string, unknown>> {
     data: T | null;
     errors?: Array<{
@@ -885,7 +911,11 @@ interface GraphQLResponse<T = Record<string, unknown>> {
             column: number;
         }>;
         path?: string[];
+        aiHint?: string;
+        /** Service stage that produced the error ("graphql", "gateway"). Resolver errors omit it. */
+        layer?: string;
     }>;
+    warnings?: Notice[];
 }
 /**
  * Webhook event types.
@@ -1053,10 +1083,16 @@ interface VerifyWebhookOptions {
 }
 
 /**
- * Internal HTTP client that auto-signs requests and attaches idempotency keys.
+ * Internal HTTP client that auto-signs requests.
+ *
+ * The transport is intentionally thin: one {@link post} method that signs,
+ * sends, and parses the {data, errors?, warnings?} envelope. It does NOT
+ * unwrap `data`, throw on `errors[]`, or hide `warnings` — those are policy
+ * choices that belong to the resource layer. See handbook
+ * `coding-standards/code-style-guide/command-layer.md`.
  *
- * The `X-Merchant-Id` header is sent in `MER_{base62}` format as provided by the user.
- * The gateway decodes it to a raw UUID before forwarding to downstream services.
+ * The `X-Merchant-Id` header is sent in `MER_{base62}` format as provided
+ * by the user. The gateway decodes it to a raw UUID before forwarding.
  *
  * Not exported publicly — used by resource classes via {@link WaffoPancake}.
  */
@@ -1067,23 +1103,24 @@ declare class HttpClient {
     private readonly _fetch;
     constructor(config: WaffoPancakeConfig);
     /**
-     * Send a signed POST request and return the parsed `data` field.
+     * Send a signed POST and return the full envelope plus HTTP status.
      *
      * Behavior:
-     * - Generates a deterministic `X-Idempotency-Key` from `merchantId + path + body` (same request produces same key)
-     * - When `idempotencyWindow` is set, a floored timestamp is mixed into the key so identical params produce
-     *   a new key after the window elapses (useful for checkout where repeated creation is intentional)
-     * - Auto-builds RSA-SHA256 signature (`X-Merchant-Id` / `X-Timestamp` / `X-Signature`)
-     * - Unwraps the response envelope: returns `data` on success, throws `WaffoPancakeError` on failure
-     *
-     * @param path - API path (e.g. `/v1/actions/store/create-store`)
+     * - Builds RSA-SHA256 signature (`X-Merchant-Id` / `X-Timestamp` / `X-Signature`)
+     * - Attaches `X-Idempotency-Key` (deterministic `sha256(merchantId + path + body)`)
+     *   unless `options.noIdempotency` is set
+     * - When `options.idempotencyWindow` is set, a floored timestamp is mixed into the
+     *   key so identical params produce a new key after the window elapses
+     * - Does NOT throw on `errors[]` or non-2xx status — caller inspects the result
+     * - Throws {@link WaffoPancakeError} only on transport failures (non-JSON body)
+     *
+     * @param path - API path (e.g. `/v1/actions/store/create-store`, `/v1/graphql`)
      * @param body - Request body object
      * @param options - Optional settings
-     * @param options.idempotencyWindow - Time window in seconds for idempotency key rotation (e.g. 60 = per-minute dedup)
-     * @returns Parsed `data` field from the response
-     * @throws {WaffoPancakeError} When the API returns errors
+     * @returns Parsed envelope with HTTP status
+     * @throws {WaffoPancakeError} When the response body is not valid JSON
      */
-    post<T>(path: string, body: object, options?: PostOptions): Promise<T>;
+    post<T>(path: string, body: object, options?: PostOptions): Promise<PostResult<T>>;
 }
 
 /** Authentication resource — issue session tokens for buyers. */
@@ -1110,14 +1147,18 @@ declare class AuthResource {
      *   buyerIdentity: "customer@example.com",
      * });
      */
-    issueSessionToken(params: IssueSessionTokenParams): Promise<SessionToken>;
+    issueSessionToken(params: IssueSessionTokenParams): Promise<SessionToken & {
+        warnings?: Notice[];
+    }>;
 }
 
 /**
  * Internal HTTP client for buyer-side requests using Bearer token authentication.
  *
  * Unlike {@link HttpClient} which signs requests with RSA-SHA256 (API Key auth),
- * this client attaches a session token as `Authorization: Bearer <token>`.
+ * this client attaches a session token as `Authorization: Bearer <token>` and
+ * never sends an idempotency key (buyer session actions are not protected by
+ * gateway idempotency in the current architecture).
  *
  * Not exported publicly — used internally by {@link BuyerSession}.
  */
@@ -1127,14 +1168,12 @@ declare class BuyerHttpClient {
     private readonly _fetch;
     constructor(token: string, config: Pick<WaffoPancakeConfig, "baseUrl" | "fetch">);
     /**
-     * Send a Bearer-authenticated POST request and return the parsed `data` field.
+     * Send a Bearer-authenticated POST and return the full envelope plus HTTP status.
      *
-     * @param path - API path
-     * @param body - Request body object
-     * @returns Parsed `data` field from the response
-     * @throws {WaffoPancakeError} When the API returns errors
+     * Does NOT throw on `errors[]` or non-2xx status — caller inspects the result.
+     * Throws {@link WaffoPancakeError} only when the response body is not valid JSON.
      */
-    post<T>(path: string, body: object): Promise<T>;
+    post<T>(path: string, body: object): Promise<PostResult<T>>;
 }
 
 /**
@@ -1166,7 +1205,9 @@ declare class BuyerSession {
      * const { orderId, status } = await buyer.cancelSubscription({ orderId: "ORD_xxx" });
      * // status: "canceled" (was pending) or "canceling" (was active)
      */
-    cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult>;
+    cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult & {
+        warnings?: Notice[];
+    }>;
     /**
      * Cancel a one-time order (only while payment is still pending).
      *
@@ -1176,7 +1217,9 @@ declare class BuyerSession {
      * @example
      * const { orderId, status } = await buyer.cancelOnetimeOrder({ orderId: "ORD_xxx" });
      */
-    cancelOnetimeOrder(params: CancelOnetimeOrderParams): Promise<CancelOnetimeOrderResult>;
+    cancelOnetimeOrder(params: CancelOnetimeOrderParams): Promise<CancelOnetimeOrderResult & {
+        warnings?: Notice[];
+    }>;
     /**
      * Reactivate a subscription that is in `canceling` status.
      *
@@ -1187,7 +1230,9 @@ declare class BuyerSession {
      * const { orderId, status } = await buyer.reactivateSubscription({ orderId: "ORD_xxx" });
      * // status: "active"
      */
-    reactivateSubscription(params: ReactivateSubscriptionParams): Promise<ReactivateSubscriptionResult>;
+    reactivateSubscription(params: ReactivateSubscriptionParams): Promise<ReactivateSubscriptionResult & {
+        warnings?: Notice[];
+    }>;
     /**
      * Submit a refund request for a payment.
      *
@@ -1203,6 +1248,7 @@ declare class BuyerSession {
      */
     createRefundTicket(params: CreateRefundTicketParams): Promise<{
         ticket: RefundTicket;
+        warnings?: Notice[];
     }>;
     /**
      * Resubmit a previously rejected refund ticket with updated details.
@@ -1220,6 +1266,7 @@ declare class BuyerSession {
      */
     resubmitRefundTicket(params: ResubmitRefundTicketParams): Promise<{
         ticket: RefundTicket;
+        warnings?: Notice[];
     }>;
 }
 /**
@@ -1274,7 +1321,9 @@ declare class CheckoutAnonymousResource {
      *   billingDetail: { country: "US", isBusiness: false, postcode: "10001" },
      * });
      */
-    create(params: AnonymousCheckoutParams): Promise<CheckoutSessionResult>;
+    create(params: AnonymousCheckoutParams): Promise<CheckoutSessionResult & {
+        warnings?: Notice[];
+    }>;
 }
 
 /**
@@ -1310,7 +1359,9 @@ declare class CheckoutAuthenticatedResource {
      * });
      * // Redirect to result.checkoutUrl (includes #token=...)
      */
-    create(params: AuthenticatedCheckoutParams): Promise<AuthenticatedCheckoutResult>;
+    create(params: AuthenticatedCheckoutParams): Promise<AuthenticatedCheckoutResult & {
+        warnings?: Notice[];
+    }>;
 }
 
 /**
@@ -1363,7 +1414,9 @@ declare class CheckoutResource {
      * });
      * // Redirect to session.checkoutUrl
      */
-    createSession(params: CreateCheckoutSessionParams): Promise<CheckoutSessionResult>;
+    createSession(params: CreateCheckoutSessionParams): Promise<CheckoutSessionResult & {
+        warnings?: Notice[];
+    }>;
 }
 
 /** GraphQL query resource (Query only, no Mutations). */
@@ -1410,6 +1463,7 @@ declare class OnetimeProductsResource {
      */
     create(params: CreateOnetimeProductParams): Promise<{
         product: OnetimeProductDetail;
+        warnings?: Notice[];
     }>;
     /**
      * Update a one-time product. Creates a new version; skips if unchanged.
@@ -1433,6 +1487,7 @@ declare class OnetimeProductsResource {
      */
     update(params: UpdateOnetimeProductParams): Promise<{
         product: OnetimeProductDetail;
+        warnings?: Notice[];
     }>;
     /**
      * Publish a one-time product's test version to production.
@@ -1445,6 +1500,7 @@ declare class OnetimeProductsResource {
      */
     publish(params: PublishOnetimeProductParams): Promise<{
         product: OnetimeProductDetail;
+        warnings?: Notice[];
     }>;
     /**
      * Update a one-time product's status (active/inactive).
@@ -1460,6 +1516,7 @@ declare class OnetimeProductsResource {
      */
     updateStatus(params: UpdateOnetimeStatusParams): Promise<{
         product: OnetimeProductDetail;
+        warnings?: Notice[];
     }>;
 }
 
@@ -1482,7 +1539,9 @@ declare class OrdersResource {
      * });
      * // status: "canceled" or "canceling"
      */
-    cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult>;
+    cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult & {
+        warnings?: Notice[];
+    }>;
 }
 
 /** Store merchant management resource (coming soon — endpoints return 501). */
@@ -1502,7 +1561,9 @@ declare class StoreMerchantsResource {
      *   role: "admin",
      * });
      */
-    add(params: AddMerchantParams): Promise<AddMerchantResult>;
+    add(params: AddMerchantParams): Promise<AddMerchantResult & {
+        warnings?: Notice[];
+    }>;
     /**
      * Remove a merchant from a store.
      *
@@ -1515,7 +1576,9 @@ declare class StoreMerchantsResource {
      *   merchantId: "MER_xxx",
      * });
      */
-    remove(params: RemoveMerchantParams): Promise<RemoveMerchantResult>;
+    remove(params: RemoveMerchantParams): Promise<RemoveMerchantResult & {
+        warnings?: Notice[];
+    }>;
     /**
      * Update a merchant's role in a store.
      *
@@ -1529,7 +1592,9 @@ declare class StoreMerchantsResource {
      *   role: "member",
      * });
      */
-    updateRole(params: UpdateRoleParams): Promise<UpdateRoleResult>;
+    updateRole(params: UpdateRoleParams): Promise<UpdateRoleResult & {
+        warnings?: Notice[];
+    }>;
 }
 
 /** Store management resource — create, update, and delete stores. */
@@ -1547,6 +1612,7 @@ declare class StoresResource {
      */
     create(params: CreateStoreParams): Promise<{
         store: Store;
+        warnings?: Notice[];
     }>;
     /**
      * Update an existing store's settings.
@@ -1578,6 +1644,7 @@ declare class StoresResource {
      */
     update(params: UpdateStoreParams): Promise<{
         store: Store;
+        warnings?: Notice[];
     }>;
     /**
      * Soft-delete a store. Only the owner can delete.
@@ -1590,6 +1657,7 @@ declare class StoresResource {
      */
     delete(params: DeleteStoreParams): Promise<{
         store: Store;
+        warnings?: Notice[];
     }>;
 }
 
@@ -1613,6 +1681,7 @@ declare class SubscriptionProductGroupsResource {
      */
     create(params: CreateSubscriptionProductGroupParams): Promise<{
         group: SubscriptionProductGroup;
+        warnings?: Notice[];
     }>;
     /**
      * Update a subscription product group. `productIds` is a full replacement.
@@ -1628,6 +1697,7 @@ declare class SubscriptionProductGroupsResource {
      */
     update(params: UpdateSubscriptionProductGroupParams): Promise<{
         group: SubscriptionProductGroup;
+        warnings?: Notice[];
     }>;
     /**
      * Hard-delete a subscription product group.
@@ -1640,6 +1710,7 @@ declare class SubscriptionProductGroupsResource {
      */
     delete(params: DeleteSubscriptionProductGroupParams): Promise<{
         group: SubscriptionProductGroup;
+        warnings?: Notice[];
     }>;
     /**
      * Publish a test-environment group to production (upsert).
@@ -1652,6 +1723,7 @@ declare class SubscriptionProductGroupsResource {
      */
     publish(params: PublishSubscriptionProductGroupParams): Promise<{
         group: SubscriptionProductGroup;
+        warnings?: Notice[];
     }>;
 }
 
@@ -1675,6 +1747,7 @@ declare class SubscriptionProductsResource {
      */
     create(params: CreateSubscriptionProductParams): Promise<{
         product: SubscriptionProductDetail;
+        warnings?: Notice[];
     }>;
     /**
      * Update a subscription product. Creates a new version; skips if unchanged.
@@ -1699,6 +1772,7 @@ declare class SubscriptionProductsResource {
      */
     update(params: UpdateSubscriptionProductParams): Promise<{
         product: SubscriptionProductDetail;
+        warnings?: Notice[];
     }>;
     /**
      * Publish a subscription product's test version to production.
@@ -1711,6 +1785,7 @@ declare class SubscriptionProductsResource {
      */
     publish(params: PublishSubscriptionProductParams): Promise<{
         product: SubscriptionProductDetail;
+        warnings?: Notice[];
     }>;
     /**
      * Update a subscription product's status (active/inactive).
@@ -1726,6 +1801,7 @@ declare class SubscriptionProductsResource {
      */
     updateStatus(params: UpdateSubscriptionStatusParams): Promise<{
         product: SubscriptionProductDetail;
+        warnings?: Notice[];
     }>;
 }
 
@@ -1787,6 +1863,7 @@ declare class WebhooksResource {
      */
     add(params: AddWebhookParams): Promise<{
         webhook: StoreWebhook;
+        warnings?: Notice[];
     }>;
     /**
      * Update an existing webhook (only `url`, `events`, and `secret` are mutable).
@@ -1806,6 +1883,7 @@ declare class WebhooksResource {
      */
     update(params: UpdateWebhookParams): Promise<{
         webhook: StoreWebhook;
+        warnings?: Notice[];
     }>;
     /**
      * Hard-delete a webhook. Historical `webhook_deliveries` rows are retained
@@ -1819,6 +1897,7 @@ declare class WebhooksResource {
      */
     remove(params: RemoveWebhookParams): Promise<{
         webhook: StoreWebhook;
+        warnings?: Notice[];
     }>;
     /**
      * Verify and parse an incoming webhook event.
@@ -2011,4 +2090,4 @@ declare class WaffoPancakeError extends Error {
  */
 declare function verifyWebhook<T = Record<string, unknown>>(payload: string, signatureHeader: string | undefined | null, options?: VerifyWebhookOptions): WebhookEvent<T>;
 
-export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, PaymentStatus, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };
+export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, type Envelope, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type Notice, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, PaymentStatus, type PostResult, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };