@doswiftly/storefront-sdk 22.1.0 → 22.3.0

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/README.md

@@ -1078,34 +1078,32 @@ middleware: [
 ### Forwarding the buyer IP for rate limiting
 
 When a storefront fetches on the server, the API sees the storefront server's IP for
-every buyer, so per-IP rate limits collapse onto a single address. The server client
-forwards the buyer's real IP so rate limiting applies per buyer again.
+every buyer, so per-IP rate limits collapse onto a single address. Forwarding the
+buyer's real IP restores per-buyer limits.
 
-**Automatic on the server — nothing to wire.** Call `getStorefrontClient` as usual:
+**Opt-in — supply `getBuyerIp`.** Reading the buyer IP requires a request-scoped
+dynamic API (e.g. `next/headers` `headers()`), which is **illegal in
+statically-generated / ISR routes** and would crash them ("static to dynamic at
+runtime"). So enable it **only on routes that are already dynamic** (per-request
+rendered):
 
 ```typescript
+import { headers } from 'next/headers';
+
+// In a DYNAMIC route/segment only — headers() forces dynamic rendering:
 const client = getStorefrontClient({
   apiUrl: process.env.DOSWIFTLY_API_URL!,
   shopSlug: process.env.DOSWIFTLY_SHOP_SLUG!,
+  getBuyerIp: async () => (await headers()).get('cf-connecting-ip'),
 });
 ```
 
-It applies only inside a server request with forwarding configured by your
-deployment, and is otherwise an inert pass-through — existing setups are unaffected.
+Without `getBuyerIp` the client never reads the IP and never signs — a fully
+static-safe, inert pass-through (static / ISR routes are unaffected). Signing also
+requires the secret `process.env.DOSWIFTLY_FORWARDED_IP_SECRET` (set by your
+deployment; override via `getForwardedIpSecret` for runtimes without `process.env`).
 **Server-only**: nothing IP-related reaches the browser.
 
-**Non-Next server runtimes** — supply the buyer IP yourself (e.g. from
-`cf-connecting-ip`), plus the signing secret if your runtime has no `process.env`:
-
-```typescript
-const client = getStorefrontClient({
-  apiUrl,
-  shopSlug,
-  getBuyerIp: () => incomingRequest.headers.get('cf-connecting-ip'),
-  // getForwardedIpSecret: () => ...
-});
-```
-
 The lower-level `forwardedIpMiddleware({ getBuyerIp, getSecret })` is also exported
 for fully custom clients.
 

package/dist/core/generated/operation-types.d.ts

@@ -2569,7 +2569,44 @@ export type PageInfo = {
     /** Cursor of the first item on the current page — opaque, base64-encoded. Echo as the `before` argument to paginate backwards. */
     startCursor?: Maybe<Scalars['String']['output']>;
 };
+export type PaymentAcknowledgement = {
+    /** Stable machine code identifying the acknowledgement (e.g. "PRZELEWY24_REGULATION"). Echo it back in `PaymentAcknowledgementInput.code` when the buyer accepts. */
+    code: Scalars['String']['output'];
+    /** Documents linked from `statement`, bound by `token`. Empty when the statement carries no links. */
+    documents: Array<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: Scalars['String']['output'];
+};
+export 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: Scalars['String']['output'];
+    /** Absolute URL of the document to link to. */
+    url: Scalars['URL']['output'];
+};
+export declare const PaymentAcknowledgementDocumentKind: {
+    readonly InformationObligation: "INFORMATION_OBLIGATION";
+    readonly PrivacyPolicy: "PRIVACY_POLICY";
+    readonly Terms: "TERMS";
+};
+export type PaymentAcknowledgementDocumentKind = typeof PaymentAcknowledgementDocumentKind[keyof typeof PaymentAcknowledgementDocumentKind];
+export declare const PaymentAcknowledgementEnforcement: {
+    readonly GatewayFallback: "GATEWAY_FALLBACK";
+    readonly StorefrontRequired: "STOREFRONT_REQUIRED";
+};
+export type PaymentAcknowledgementEnforcement = typeof PaymentAcknowledgementEnforcement[keyof typeof PaymentAcknowledgementEnforcement];
+export type PaymentAcknowledgementInput = {
+    /** True when the buyer checked the acknowledgement. */
+    accepted: Scalars['Boolean']['input'];
+    /** Code of the acknowledgement the buyer affirmed (e.g. "PRZELEWY24_REGULATION"). */
+    code: Scalars['String']['input'];
+};
 export type 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?: InputMaybe<Array<PaymentAcknowledgementInput>>;
     /** URL the gateway returns the buyer to after they cancel the payment. Must point to a verified domain of the shop. */
     cancelUrl?: InputMaybe<Scalars['URL']['input']>;
     /** ID of the order to pay for — `cartComplete.order.id`. */
@@ -2624,6 +2661,8 @@ export declare const PaymentInstrumentType: {
 };
 export type PaymentInstrumentType = typeof PaymentInstrumentType[keyof typeof PaymentInstrumentType];
 export 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: Array<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. */
     available: Scalars['Boolean']['output'];
     /** Optional buyer-facing description shown under the name (e.g. "Pay with your bank app"). */