@doswiftly/storefront-operations 22.1.0 → 22.3.0

package/AGENTS.md

@@ -27,7 +27,7 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 22.1.0
+- **Schema version**: 22.3.0
 - **Queries**: 52
 - **Mutations**: 44
 - **Fragments**: 105

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 22.3.0
+
+### Minor Changes
+
+- 21b0c44: Storefront payments: surface buyer acknowledgements (such as the Przelewy24 regulation consent) on payment methods, and accept them when starting a payment.
+
+  `PaymentMethod` now exposes an `acknowledgements` list — consents the buyer can affirm before paying. Each one carries a localized `statement` (with `<token>…</token>` tags marking the words that link to its `documents`), the linked document URLs, and an `enforcement` flag (optional vs required). Render each as a checkbox (never pre-checked) and link the tagged words to the matching `documents[].url`, then send the accepted ones back through the new optional `PaymentCreateInput.acknowledgements` field (`{ code, accepted }`).
+
+  For Przelewy24 this lets a storefront collect the regulation consent in-store (showing the required statement and links) so the buyer skips the gateway's consent page and goes straight to the bank / BLIK / card form. When you omit it, the gateway shows the consent itself, so it is fully optional.
+
+  Additive and backwards-compatible — existing operations are unaffected.
+
+## 22.2.0
+
+### Minor Changes
+
+- 27934d1: Server `getStorefrontClient`: forwarded-IP signing is now **opt-in** via `getBuyerIp`.
+
+  Previously the server client auto-read the buyer IP through `next/headers` on every
+  request. That is a dynamic API and is illegal in statically-generated / ISR routes —
+  it crashed such pages with "Page changed from static to dynamic at runtime".
+
+  Forwarded-IP is now wired only when you pass `getBuyerIp`, which you should do **only
+  on routes that are already dynamic** (per-request rendered). Without it the client is
+  a fully static-safe, inert pass-through.
+
+  Migration — to keep forwarding the buyer IP, pass `getBuyerIp` on your dynamic routes:
+
+  ```typescript
+  import { headers } from "next/headers";
+
+  getStorefrontClient({
+    apiUrl,
+    shopSlug,
+    getBuyerIp: async () => (await headers()).get("cf-connecting-ip"),
+  });
+  ```
+
 ## 22.1.0
 
 ### Minor Changes

package/fragments.graphql

@@ -752,6 +752,20 @@ fragment PaymentMethod on PaymentMethod {
   instruments {
     ...PaymentInstrument
   }
+  # Consents the buyer can affirm before paying (e.g. the Przelewy24 regulation). Render each
+  # `statement` as a checkbox label (the checkbox MUST NOT be pre-checked) with the `<token>…</token>`
+  # tagged words linked to the matching `documents[].url`; echo accepted `code`s back in
+  # `PaymentCreateInput.acknowledgements`. Empty when the method carries no acknowledgements.
+  acknowledgements {
+    code
+    enforcement
+    statement
+    documents {
+      token
+      kind
+      url
+    }
+  }
 }
 
 # Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query.

package/llms-full.txt

@@ -1,6 +1,6 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **22.1.0**
+> Schema version: **22.3.0**
 > 52 queries · 44 mutations · 105 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
@@ -3655,6 +3655,16 @@ fragment PaymentMethod on PaymentMethod {
   instruments {
     ...PaymentInstrument
   }
+  acknowledgements {
+    code
+    enforcement
+    statement
+    documents {
+      token
+      kind
+      url
+    }
+  }
 }
 ```
 

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "22.1.0",
+  "schemaVersion": "22.3.0",
   "queries": [
     {
       "name": "Shop",
@@ -2431,7 +2431,7 @@
         "ImageThumbnail",
         "PaymentInstrument"
       ],
-      "body": "fragment PaymentMethod on PaymentMethod {\n  id\n  name\n  provider\n  type\n  icon {\n    ...ImageThumbnail\n  }\n  description\n  isDefault\n  supportedCurrencies\n  position\n  providersAvailable\n  preferredProvider\n  available\n  unavailableReason\n  instruments {\n    ...PaymentInstrument\n  }\n}",
+      "body": "fragment PaymentMethod on PaymentMethod {\n  id\n  name\n  provider\n  type\n  icon {\n    ...ImageThumbnail\n  }\n  description\n  isDefault\n  supportedCurrencies\n  position\n  providersAvailable\n  preferredProvider\n  available\n  unavailableReason\n  instruments {\n    ...PaymentInstrument\n  }\n  acknowledgements {\n    code\n    enforcement\n    statement\n    documents {\n      token\n      kind\n      url\n    }\n  }\n}",
       "onType": "PaymentMethod"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "22.1.0",
+  "version": "22.3.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/schema.graphql

@@ -4928,10 +4928,88 @@ enum PageSortKeys {
   UPDATED_AT
 }
 
+"""
+A consent the buyer can affirm before paying with this method (e.g. the Przelewy24 regulation declaration). Render `statement` as a checkbox label — the checkbox MUST NOT be pre-checked — with the `<token>…</token>` tagged words linked to the matching `documents[].url`. On submit, echo the accepted `code`s back via `PaymentCreateInput.acknowledgements`. When `enforcement` is GATEWAY_FALLBACK collecting it is optional (the gateway shows it otherwise); STOREFRONT_REQUIRED must be accepted or `paymentCreate` returns ACKNOWLEDGEMENT_REQUIRED.
+"""
+type PaymentAcknowledgement {
+  """
+  Stable machine code identifying the acknowledgement (e.g. "PRZELEWY24_REGULATION"). Echo it back in `PaymentAcknowledgementInput.code` when the buyer accepts.
+  """
+  code: String!
+
+  """
+  Documents linked from `statement`, bound by `token`. Empty when the statement carries no links.
+  """
+  documents: [PaymentAcknowledgementDocument!]!
+
+  """
+  Whether collecting this in the storefront is optional (GATEWAY_FALLBACK) or mandatory (STOREFRONT_REQUIRED).
+  """
+  enforcement: PaymentAcknowledgementEnforcement!
+
+  """
+  Localized statement to show next to the checkbox. Contains `<token>…</token>` tags marking the words that link to `documents` (e.g. "… <terms>regulaminem</terms> …"). Render the tagged words as anchors; never inject as raw HTML.
+  """
+  statement: String!
+}
+
+"""
+A document linked from a payment acknowledgement statement. Its `token` matches a `<token>…</token>` tag inside `PaymentAcknowledgement.statement` — wrap the tagged words in an anchor to `url` (open in a new tab). Never inject the statement as raw HTML.
+"""
+type PaymentAcknowledgementDocument {
+  """
+  Semantic category of the document (TERMS, INFORMATION_OBLIGATION, PRIVACY_POLICY).
+  """
+  kind: PaymentAcknowledgementDocumentKind!
+
+  """
+  Binding token — equals the tag name wrapping the linked words inside `PaymentAcknowledgement.statement` (e.g. `terms` ↔ `<terms>…</terms>`).
+  """
+  token: String!
+
+  """Absolute URL of the document to link to."""
+  url: URL!
+}
+
+"""
+Category of a document linked from an acknowledgement statement (TERMS, INFORMATION_OBLIGATION, PRIVACY_POLICY). Use for optional iconography; the `token` is what binds the link into the statement text.
+"""
+enum PaymentAcknowledgementDocumentKind {
+  INFORMATION_OBLIGATION
+  PRIVACY_POLICY
+  TERMS
+}
+
+"""
+Whether collecting a payment acknowledgement in the storefront is optional (GATEWAY_FALLBACK — the gateway shows it itself when you omit it) or mandatory (STOREFRONT_REQUIRED — `paymentCreate` rejects with ACKNOWLEDGEMENT_REQUIRED unless the buyer accepted it).
+"""
+enum PaymentAcknowledgementEnforcement {
+  GATEWAY_FALLBACK
+  STOREFRONT_REQUIRED
+}
+
+"""
+A payment acknowledgement the buyer affirmed at pay time — `code` echoes a `PaymentAcknowledgement.code` from `availablePaymentMethods`.
+"""
+input PaymentAcknowledgementInput {
+  """True when the buyer checked the acknowledgement."""
+  accepted: Boolean!
+
+  """
+  Code of the acknowledgement the buyer affirmed (e.g. "PRZELEWY24_REGULATION").
+  """
+  code: String!
+}
+
 """
 Input for `paymentCreate` — initiates a payment for an order created by `cartComplete`. Idempotent on the order: a second call returns the existing still-valid session.
 """
 input PaymentCreateInput {
+  """
+  Payment acknowledgements the buyer affirmed (e.g. accepting the Przelewy24 regulation). Send only the ones the buyer checked. Optional — when omitted, gateways that present their own consent step collect it; a method with a STOREFRONT_REQUIRED acknowledgement returns `ACKNOWLEDGEMENT_REQUIRED` if not accepted.
+  """
+  acknowledgements: [PaymentAcknowledgementInput!]
+
   """
   URL the gateway returns the buyer to after they cancel the payment. Must point to a verified domain of the shop.
   """
@@ -5039,6 +5117,11 @@ enum PaymentInstrumentType {
 A payment method offered to the buyer at checkout — what to render in the payment picker and pass to `cartSelectPaymentMethod`.
 """
 type PaymentMethod {
+  """
+  Consents the buyer can affirm before paying with this method (e.g. the Przelewy24 regulation declaration). Render each as a checkbox using `statement` + `documents`, then echo accepted `code`s back in `PaymentCreateInput.acknowledgements`. Empty when the method carries no acknowledgements.
+  """
+  acknowledgements: [PaymentAcknowledgement!]!
+
   """
   True when the buyer can actually pick this method right now. False when the resolving gateway is temporarily unavailable (incident/maintenance) or reported the method as disabled. Storefront UI should gray-out the tile when false instead of hiding it — gives merchants observability into routing failures.
   """