@doswiftly/storefront-operations 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 6.1.0
+
+### Minor Changes
+
+- fbc6a94: Rozszerzono `CustomerUpdateInput` w GraphQL Storefront API o pełen kontrakt B2B — storefront developer może teraz zaktualizować dane firmowe klienta (nazwa firmy, NIP, VAT UE, REGON) oraz typ klienta (osoba fizyczna / firma) bezpośrednio przez mutację `customerUpdate`. Wcześniej te pola były dostępne wyłącznie z poziomu panelu administratora.
+
+  **Nowe pola Input**:
+  - `customerType: CustomerType` — `INDIVIDUAL` (B2C) lub `COMPANY` (B2B). Opcjonalne — gdy pominięte, backend dokona inteligentnej inferencji (patrz „Strict hybrid" niżej).
+  - `companyName: String` — nazwa firmy (wymagana dla `COMPANY`).
+  - `taxId: String` — polski NIP (10 cyfr z sumą kontrolną).
+  - `vatNumber: String` — numer VAT UE (np. `PL5260250274`, `DE123456789`).
+  - `regon: String` — polski REGON (9 lub 14 cyfr z sumą kontrolną).
+
+  **Nowe pola czytelne na typie `Customer`** (dostępne automatycznie przez fragment `Customer`):
+  - `customerType`, `companyName`, `taxId`, `vatNumber`, `regon`.
+
+  **Strict hybrid — kontrakt aktualizacji typu klienta**:
+  1. Jeśli `customerType` jest w payloadzie, wygrywa explicit (nawet jeśli inne pola sugerowałyby co innego).
+  2. Jeśli `customerType` jest pominięty, backend dokonuje implicit upgrade `INDIVIDUAL → COMPANY` tylko gdy podano niepuste pole firmowe. Implicit downgrade nigdy się nie zdarza — wymaga jawnego `customerType: INDIVIDUAL`.
+  3. Każde efektywne `COMPANY` (jawne lub przez inferencję) wymaga niepustej `companyName` — w przeciwnym razie mutacja zwraca `userErrors` z kodem `CUSTOMER_UPDATE_FAILED`.
+  4. `undefined` w payloadzie = brak zmiany pola; `null` = świadome czyszczenie wartości.
+
+  **Walidacja format**: NIP, VAT UE i REGON walidowane przez wspólny dekorator (regex + algorytm sumy kontrolnej). Niepoprawny format → błąd walidacji input'u GraphQL.
+
+  **Concurrency safety**: `customerUpdate` używa optimistic locking — równoczesne aktualizacje tego samego klienta (np. profil w wielu zakładkach) zwracają `userErrors` z message o konflikcie wersji zamiast cichego nadpisania.
+
+  **Use cases dla storefront-developera**:
+  - Strona „moje dane" w sklepie — pełen formularz B2C/B2B z radio pickerem typu klienta.
+  - Checkout pre-fill — możliwość uzupełnienia danych do faktury bez wchodzenia do panelu sklepu.
+  - Rejestracja firm / sole-trader scenarios — implicit upgrade gdy klient wpisze NIP w polu opcjonalnym.
+
+  **Test coverage**: 8 service-level scenariuszy (każda z 4 reguł strict hybrid + concurrency conflict + audit trail + EventEmitter) + 3 GraphQL surface scenariusze (full B2B payload, error mapping, format validation).
+
+- c91b700: Rozszerzono storefront GraphQL API o pełną obsługę zgód marketingowych — storefront-developer może teraz zbudować checkbox marketingu przy rejestracji, toggle preferencji w panelu klienta, oraz widget „zapisz się do newslettera" w stopce sklepu. Wszystkie 3 use case'y działają end-to-end (z double opt-in dla anonimowego widget'u i audit trail dla zgodności z RODO).
+
+  **Nowe pola Input (signup)** — `CustomerCreateInput`:
+  - `acceptsMarketing: Boolean` — checkbox marketingu przy `customerSignup`. `true` → state SUBSCRIBED bezpośrednio (signup = adres potwierdzony). `false`/`null` → bez zmian (NOT_SUBSCRIBED).
+  - `marketingOptInLevel: MarketingOptInLevel` (`SINGLE_OPT_IN | CONFIRMED_OPT_IN | UNKNOWN`) — opcjonalny override. Ustaw `CONFIRMED_OPT_IN` aby wymusić double opt-in (state PENDING + automatyczny email z linkiem potwierdzającym).
+
+  **Nowe pole Input (panel klienta)** — `CustomerUpdateInput`:
+  - `acceptsMarketing: Boolean` — toggle dla zalogowanego klienta. `true` → SUBSCRIBED, `false` → UNSUBSCRIBED. Działa tylko z access tokenem (auth-required mutation).
+
+  **Nowe mutacje (newsletter widget — guest, bez auth)**:
+  - `customerSubscribeToMarketing(input: { email, marketingOptInLevel? }): SubscribeToMarketingPayload` — anonimowy opt-in. Backend zawsze stosuje double opt-in (state PENDING → email z linkiem → klik → SUBSCRIBED) niezależnie od `marketingOptInLevel` w input — bez tego ktoś mógłby zapisywać cudze adresy.
+  - `customerUnsubscribeFromMarketing(input: { email }): UnsubscribeFromMarketingPayload` — anonimowy opt-out, idempotent.
+
+  **Payloady — `accepted: Boolean!` semantyka (anti-enumeration)**: obie mutacje guest zwracają `accepted: true` niezależnie od stanu emaila (registered / nieistniejący / już SUBSCRIBED). Storefront-developer dostaje deterministyczny shape response — atakujący nie może przez to API enumerate'ować adresów ani odróżnić invalid email format od valid (orzeczenie: też swallowed jako `accepted: true`). Stan końcowy zawsze widoczny przez `Customer.emailMarketing` (gdy klient autoryzowany).
+
+  **Mutacje C są throttlowane per IP** (limit 10/min) i pod botprotection guardem — storefront powinien zintegrować odpowiedni captcha provider. Email-bombing przez wpisywanie cudzego adresu w widget'cie blokowany dodatkowo na poziomie backendu (max 1 email potwierdzenia na adres na dobę).
+
+  **Strict-hybrid kontrakt update'u**:
+  - Brak pola w Input = no-op dla tego pola (zachowanie back-compat dla istniejących storefrontów bez nowych pól).
+  - `acceptsMarketing: null` na auth'd customer = explicit no-change (nie unsubscribe — do unsubscribe użyj `false`).
+
+  **Double opt-in dla widget'u — co dzieje się po kliknięciu „Zapisz"**:
+  1. Mutation `customerSubscribeToMarketing` → backend zapisuje stan PENDING + uruchamia wysłanie maila potwierdzającego.
+  2. Email idzie z domeny sklepu (per-shop branding — `From: "Sklep <noreply@shop-domain>"`) z CTA buttonem prowadzącym pod URL potwierdzający (token JWT 24h).
+  3. Klient klika link → backend transitionuje stan z PENDING na SUBSCRIBED.
+  4. Po SUBSCRIBED storefront może wysyłać maile marketingowe (gate consent jest egzekwowane przez backend pre-send).
+
+  **Read surface — `Customer.emailMarketing: EmailMarketingState!`** (pole już istniejące, dla auth'd customer): storefront odczytuje `NOT_SUBSCRIBED | PENDING | SUBSCRIBED | UNSUBSCRIBED | INVALID | REDACTED` aby zdecydować jak renderować checkbox/toggle w UI (np. PENDING = pokaż „sprawdź email", SUBSCRIBED = checkbox zaznaczony).
+
+  **Use cases**:
+  - Strona `/auth/register` — checkbox „Chcę otrzymywać newsletter" zapisany razem z signupem.
+  - Strona `/account/preferences` — toggle marketing on/off dla zalogowanego klienta.
+  - Stopka layoutu sklepu — input email + button „Zapisz się" → mutation guest subscribe → automatyczny email z linkiem potwierdzającym.
+
+  **Suppression list awareness**: jeśli adres trafił wcześniej na suppression list (hard bounce / complaint feedback), kolejna subskrypcja zwraca `accepted: true` ale email potwierdzający nie wychodzi. Klient pozostanie w stanie PENDING — admin sklepu musi ręcznie odblokować adres przez panel administracyjny.
+
 ## 6.0.0
 
 ### Major Changes

package/fragments.graphql

@@ -285,6 +285,11 @@ fragment Customer on Customer {
   isEmailVerified
   emailMarketing
   tags
+  customerType
+  companyName
+  taxId
+  vatNumber
+  regon
   defaultAddress {
     ...MailingAddress
   }

package/package.json

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

package/schema.graphql

@@ -2010,9 +2010,15 @@ type Customer implements Node {
   """Saved addresses (Relay Connection)"""
   addresses(after: String, before: String, first: Int, last: Int): MailingAddressConnection!
 
+  """Company name (populated for COMPANY type)"""
+  companyName: String
+
   """Account creation date"""
   createdAt: DateTime!
 
+  """Business type discriminator (INDIVIDUAL/COMPANY)"""
+  customerType: CustomerType!
+
   """Default address"""
   defaultAddress: MailingAddress
 
@@ -2046,14 +2052,23 @@ type Customer implements Node {
   """Phone number"""
   phone: String
 
+  """Polish business registry number — REGON"""
+  regon: String
+
   """Customer tags for segmentation (e.g. vip, wholesale, b2b)"""
   tags: [String!]!
 
+  """Polish tax ID — NIP"""
+  taxId: String
+
   """Total amount spent"""
   totalSpent: Money!
 
   """Last update date"""
   updatedAt: DateTime!
+
+  """EU VAT number"""
+  vatNumber: String
 }
 
 """Customer access token"""
@@ -2103,6 +2118,11 @@ type CustomerAddAddressPayload {
 
 """Input for customer registration"""
 input CustomerCreateInput {
+  """
+  Opt-in to email marketing checkbox. true → state SUBSCRIBED (single opt-in) unless `marketingOptInLevel: CONFIRMED_OPT_IN` is also set (then PENDING + double opt-in confirmation email). false/null → no consent change.
+  """
+  acceptsMarketing: Boolean
+
   """Email address"""
   email: String!
 
@@ -2112,6 +2132,11 @@ input CustomerCreateInput {
   """Last name"""
   lastName: String
 
+  """
+  Opt-in level. Default SINGLE_OPT_IN (signup = email proven implicitly). Set CONFIRMED_OPT_IN to force double opt-in via confirmation email.
+  """
+  marketingOptInLevel: MarketingOptInLevel
+
   """Password"""
   password: String!
 
@@ -2234,6 +2259,29 @@ type CustomerSignupPayload {
   userErrors: [UserError!]!
 }
 
+"""Input for newsletter subscribe (guest-friendly)."""
+input CustomerSubscribeToMarketingInput {
+  """Email address to subscribe to newsletter"""
+  email: String!
+
+  """
+  Opt-in level. Guest mutation always enforces CONFIRMED_OPT_IN regardless of value.
+  """
+  marketingOptInLevel: MarketingOptInLevel
+}
+
+"""Customer business type — INDIVIDUAL (B2C) or COMPANY (B2B)."""
+enum CustomerType {
+  COMPANY
+  INDIVIDUAL
+}
+
+"""Input for newsletter unsubscribe (guest-friendly)."""
+input CustomerUnsubscribeFromMarketingInput {
+  """Email address to unsubscribe"""
+  email: String!
+}
+
 """Result of address update"""
 type CustomerUpdateAddressPayload {
   """Updated address"""
@@ -2247,6 +2295,17 @@ type CustomerUpdateAddressPayload {
 
 """Input for customer update"""
 input CustomerUpdateInput {
+  """
+  Email marketing toggle. true → state SUBSCRIBED bezpośrednio (auth'd customer = email proven). false → UNSUBSCRIBED. null/undefined → no change.
+  """
+  acceptsMarketing: Boolean
+
+  """Company name (required when customerType is COMPANY)"""
+  companyName: String
+
+  """Business type discriminator (INDIVIDUAL/COMPANY)"""
+  customerType: CustomerType
+
   """First name"""
   firstName: String
 
@@ -2255,6 +2314,15 @@ input CustomerUpdateInput {
 
   """Phone number"""
   phone: String
+
+  """Polish business registry number — REGON (9 or 14 digits with checksum)"""
+  regon: String
+
+  """Polish tax ID — NIP (10 digits with checksum)"""
+  taxId: String
+
+  """EU VAT number (e.g. PL1234567890)"""
+  vatNumber: String
 }
 
 """Result of customer update"""
@@ -3274,6 +3342,15 @@ input MailingAddressInput {
   streetLine2: String
 }
 
+"""
+Email marketing opt-in level — SINGLE_OPT_IN, CONFIRMED_OPT_IN, UNKNOWN.
+"""
+enum MarketingOptInLevel {
+  CONFIRMED_OPT_IN
+  SINGLE_OPT_IN
+  UNKNOWN
+}
+
 """Navigation menu"""
 type Menu {
   """URL handle (e.g., main-menu, footer)"""
@@ -3455,6 +3532,12 @@ type Mutation {
   """Register new customer"""
   customerSignup(input: CustomerCreateInput!): CustomerSignupPayload!
 
+  """Subscribe an email to the newsletter (guest-friendly, double opt-in)."""
+  customerSubscribeToMarketing(input: CustomerSubscribeToMarketingInput!): SubscribeToMarketingPayload!
+
+  """Unsubscribe an email from the newsletter (guest-friendly, idempotent)."""
+  customerUnsubscribeFromMarketing(input: CustomerUnsubscribeFromMarketingInput!): UnsubscribeFromMarketingPayload!
+
   """Update customer profile"""
   customerUpdate(customer: CustomerUpdateInput!): CustomerUpdatePayload!
 
@@ -5662,6 +5745,17 @@ enum StorefrontOrderStatus {
   PROCESSING
 }
 
+"""Payload for customerSubscribeToMarketing mutation"""
+type SubscribeToMarketingPayload {
+  """
+  Always true (anti-enumeration). Backend may silently skip enqueue if rate-limited or already SUBSCRIBED.
+  """
+  accepted: Boolean!
+
+  """User-facing errors"""
+  userErrors: [UserError!]!
+}
+
 """Tax line item"""
 type TaxLine {
   """Tax amount"""
@@ -5756,6 +5850,15 @@ Unsigned 64-bit integer, JSON-serialized as String (BigInt-safe). Format: "{inte
 """
 scalar UnsignedInt64
 
+"""Payload for customerUnsubscribeFromMarketing mutation"""
+type UnsubscribeFromMarketingPayload {
+  """Always true (anti-enumeration)."""
+  accepted: Boolean!
+
+  """User-facing errors"""
+  userErrors: [UserError!]!
+}
+
 """URL redirect (SEO, store migration)"""
 type UrlRedirect {
   """Source path"""