@doswiftly/storefront-operations 20.0.0 → 20.2.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**: 20.0.0
+- **Schema version**: 20.2.0
 - **Queries**: 52
 - **Mutations**: 44
 - **Fragments**: 104

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 20.2.0
+
+### Minor Changes
+
+- 17fedcf: Addresses now carry a structured building / flat number alongside the free-form street line.
+
+  **Why**: Polish addresses — and carriers like InPost as well as VAT invoicing — need the building number as a discrete field rather than mixed into a single street line (e.g. `"ul. Piękna 5/3"` must split into building `5`, flat `3`). The `MailingAddress` type and the cart / mailing address inputs now expose `buildingNumber` and `flatNumber` so storefronts can collect and display them precisely.
+
+  **Additive (backward-compatible)**:
+  1. `MailingAddress` (read) gains `buildingNumber` and `flatNumber` — populated on cart, order and saved customer addresses; `null` when only the free-form line was provided.
+  2. The address inputs (`CartAddressInput`, `MailingAddressInput`) accept optional `buildingNumber` and `flatNumber`. For a Polish street delivery without a pickup point the building number is now required server-side — omitting it returns a `BUILDING_NUMBER_REQUIRED` user error instead of silently guessing it from the street text.
+
+  **Usage example**:
+
+  ```ts
+  await cartSetShippingAddress({
+    cartId,
+    address: {
+      streetLine1: "ul. Piękna 5/3",
+      buildingNumber: "5",
+      flatNumber: "3",
+      city: "Warszawa",
+      postalCode: "00-001",
+      country: "PL",
+    },
+  });
+
+  // reading it back
+  const { buildingNumber, flatNumber } = order.shippingAddress;
+  ```
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Add a `buildingNumber` (and optional `flatNumber`) field to your address forms.
+  - [ ] For Polish street addresses, send `buildingNumber`, or handle the `BUILDING_NUMBER_REQUIRED` user error returned by the cart address mutations.
+  - [ ] Optionally render `buildingNumber` / `flatNumber` when displaying saved or order addresses.
+
+## 20.1.0
+
+### Minor Changes
+
+- e1bda76: Cart addresses now carry full B2B invoice identity end to end. `cartSetShippingAddress` and `cartSetBillingAddress` accept an EU VAT number (`vatNumber`, e.g. `PL1234567890`) alongside the existing tax ID and business registry number, and the cart address now returns all three (`taxId`, `vatNumber`, `regon`) — so a storefront can display and re-confirm exactly what the buyer entered. These values are carried onto the resulting order at checkout, ready for reverse-charge and cross-border B2B invoices.
+
+  Signed-in shoppers also get their saved default shipping and billing address — including those B2B fields — prefilled into the cart automatically when they create a cart or log in. Anything the shopper has already typed is never overwritten.
+
 ## 20.0.0
 
 ### Major Changes

package/README.md

@@ -472,7 +472,7 @@ full executable body of each operation.
 | Fragment | On Type | Description |
 | --- | --- | --- |
 | `PickupPoint` | `PickupPoint` | Selected pickup point (parcel locker or collection point) attached to a delivery address. Returned on `MailingAddress.pickupPoint` when the buyer chose a non-home delivery method (`deliveryType` other than `HOME`). Null for home delivery. |
-| `MailingAddress` | `MailingAddress` | Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries. |
+| `MailingAddress` | `MailingAddress` | Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`, `regon`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries. |
 | `CustomerAccessToken` | `CustomerAccessToken` | Customer access token returned by `customerLogin` / `customerSignup` / `customerActivate` / `customerResetPassword` / `customerRefreshToken`. The token's JWT TTL is 24h; cookie max-age is 30d. |
 | `Customer` | `Customer` | Customer profile — basic info plus B2B fields (`taxId`, `vatNumber`, `regon`, `companyName`), default address, lifetime stats (`orderCount`, `totalSpent`), marketing preferences. Use on profile / settings pages. |
 | `Order` | `Order` | Order summary — number, totals (cost / tax / shipping), payment + fulfillment status, shipping address, item count, lifecycle timestamps, plus payment capability signal (`canCreatePayment` + `paymentMethodType`) the storefront uses to decide post-completion payment flow without hard-coded provider checks. Spread on the order list, order detail, and the `cartComplete` mutation result. Line items are not included here. |

package/fragments.graphql

@@ -252,11 +252,13 @@ fragment PickupPoint on PickupPoint {
   address
 }
 
-# Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries.
+# Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`, `regon`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries.
 fragment MailingAddress on MailingAddress {
   id
   streetLine1
   streetLine2
+  buildingNumber
+  flatNumber
   city
   company
   country
@@ -271,6 +273,7 @@ fragment MailingAddress on MailingAddress {
   isDefault
   taxId
   vatNumber
+  regon
   pickupPoint {
     ...PickupPoint
   }

package/llms-full.txt

@@ -1,6 +1,6 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **20.0.0**
+> Schema version: **20.2.0**
 > 52 queries · 44 mutations · 104 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
@@ -2927,7 +2927,7 @@ fragment PickupPoint on PickupPoint {
 
 **Section**: Customer
 
-**Description**: Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries.
+**Description**: Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`, `regon`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries.
 
 **Uses fragments**: `PickupPoint`
 
@@ -2937,6 +2937,8 @@ fragment MailingAddress on MailingAddress {
   id
   streetLine1
   streetLine2
+  buildingNumber
+  flatNumber
   city
   company
   country
@@ -2951,6 +2953,7 @@ fragment MailingAddress on MailingAddress {
   isDefault
   taxId
   vatNumber
+  regon
   pickupPoint {
     ...PickupPoint
   }

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "20.0.0",
+  "schemaVersion": "20.2.0",
   "queries": [
     {
       "name": "Shop",
@@ -2112,12 +2112,12 @@
       "name": "MailingAddress",
       "kind": "fragment",
       "section": "Customer",
-      "description": "Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries.",
+      "description": "Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`, `regon`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries.",
       "variables": [],
       "fragmentRefs": [
         "PickupPoint"
       ],
-      "body": "fragment MailingAddress on MailingAddress {\n  id\n  streetLine1\n  streetLine2\n  city\n  company\n  country\n  countryCode\n  firstName\n  lastName\n  name\n  phone\n  state\n  stateCode\n  postalCode\n  isDefault\n  taxId\n  vatNumber\n  pickupPoint {\n    ...PickupPoint\n  }\n}",
+      "body": "fragment MailingAddress on MailingAddress {\n  id\n  streetLine1\n  streetLine2\n  buildingNumber\n  flatNumber\n  city\n  company\n  country\n  countryCode\n  firstName\n  lastName\n  name\n  phone\n  state\n  stateCode\n  postalCode\n  isDefault\n  taxId\n  vatNumber\n  regon\n  pickupPoint {\n    ...PickupPoint\n  }\n}",
       "onType": "MailingAddress"
     },
     {

package/package.json

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

package/schema.graphql

@@ -1046,9 +1046,14 @@ type CartAddLinesPayload {
 }
 
 """
-Mailing address used as the shipping or billing address on a cart. Carries an optional pickup point (for parcel locker / collection-point delivery) and optional B2B fields (`taxId`, `regon`).
+Mailing address used as the shipping or billing address on a cart. Carries an optional pickup point (for parcel locker / collection-point delivery) and optional B2B fields (`taxId`, `vatNumber`, `regon`).
 """
 input CartAddressInput {
+  """
+  Building / house number as a discrete field, overlaid on `streetLine1`. Required for delivery and billing addresses in Poland (`country: PL`) without a `pickupPoint` — carriers (e.g. InPost) and invoicing need the building number split out from the street name.
+  """
+  buildingNumber: String
+
   """City"""
   city: String!
 
@@ -1061,6 +1066,11 @@ input CartAddressInput {
   """First name"""
   firstName: String
 
+  """
+  Flat / apartment number as a discrete field — optional companion to `buildingNumber`.
+  """
+  flatNumber: String
+
   """Last name"""
   lastName: String
 
@@ -1093,6 +1103,11 @@ input CartAddressInput {
   Buyer tax ID for B2B invoicing (Polish NIP). Persisted on the resulting order at checkout completion.
   """
   taxId: String
+
+  """
+  Buyer EU VAT number for cross-border B2B invoicing (e.g. PL1234567890). Persisted on the resulting order at checkout completion.
+  """
+  vatNumber: String
 }
 
 """
@@ -3828,9 +3843,14 @@ enum LoyaltyTransactionType {
 }
 
 """
-A mailing address — shipping or billing — used on a cart, on the resulting order, or saved in a customer address book. Carries optional B2B fields (`taxId`, `vatNumber`) and an optional `pickupPoint` for parcel locker / collection-point delivery.
+A mailing address — shipping or billing — used on a cart, on the resulting order, or saved in a customer address book. Carries optional B2B fields (`taxId`, `vatNumber`, `regon`) and an optional `pickupPoint` for parcel locker / collection-point delivery.
 """
 type MailingAddress implements Node {
+  """
+  Building / house number as a discrete field, overlaid on `streetLine1`. Populated for structured addresses (required for PL delivery / billing without a pickup point); null when only the free-form `streetLine1` was provided.
+  """
+  buildingNumber: String
+
   """City / town."""
   city: String
 
@@ -3848,6 +3868,11 @@ type MailingAddress implements Node {
   """Buyer first name."""
   firstName: String
 
+  """
+  Flat / apartment number as a discrete field — optional companion to `buildingNumber`.
+  """
+  flatNumber: String
+
   """
   Country-aware ordered address lines, ready to render line by line in UI without manual formatting. The exact line layout depends on country (e.g. PL puts postal code before city, US after state).
   """
@@ -3881,6 +3906,11 @@ type MailingAddress implements Node {
   """Postal / ZIP code."""
   postalCode: String
 
+  """
+  Buyer business registry number (Polish REGON) carried on a cart address for B2B invoicing. Populated on cart shipping/billing addresses; null on customer address-book entries (REGON is customer-level).
+  """
+  regon: String
+
   """State / province / region name."""
   state: String
 
@@ -3934,6 +3964,11 @@ type MailingAddressEdge {
 
 """Input for mailing address"""
 input MailingAddressInput {
+  """
+  Building / house number as a discrete field, overlaid on `streetLine1`. Required for saved Polish addresses (`country: PL`) — used for carrier delivery and invoicing.
+  """
+  buildingNumber: String
+
   """City"""
   city: String
 
@@ -3946,6 +3981,11 @@ input MailingAddressInput {
   """First name"""
   firstName: String
 
+  """
+  Flat / apartment number as a discrete field — optional companion to `buildingNumber`.
+  """
+  flatNumber: String
+
   """Last name"""
   lastName: String