@doswiftly/storefront-sdk 20.1.0 → 21.0.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 21.0.0
+
+### Major Changes
+
+- a539021: Product attribute fields renamed and split by purpose (breaking)
+
+  `Product.attributes` now returns the product's **stored custom-field values** — merchant-managed metadata such as manufacturer, licence or material — as `[EntityAttributeField!]!`. Only values marked visible are returned; pass the optional `namespace` argument to fetch a single group.
+
+  The configurator field **definitions** that previously lived under `Product.attributes` have moved to **`Product.configuratorFields(filter: { filledBy: ... })`**, returning `[ConfiguratorField!]!`.
+
+  Renames:
+  - Type `ProductAttributeDefinition` → `ConfiguratorField`, with field renames `fillingMode` → `filledBy`, `billingMode` → `pricingMode`, `isRequired` → `required`, `displayOrder` → `sortOrder`.
+  - Type `ProductAttributeOption` → `ConfiguratorOption`.
+  - Input `ProductAttributeFilterInput` → `ConfiguratorFieldFilterInput` (its `fillingMode` argument → `filledBy`).
+
+  Removed from the public contract: `Product.attributeSetId`; the internal `scopeProductId` and `taxClassId` on configurator fields; and the raw `linkedVariantId` on a configurator option (read `linkedVariant.id` instead).
+
+  Migration: rename `attributes(filter: { fillingMode })` selections to `configuratorFields(filter: { filledBy })` and spread `...ConfiguratorField`; use the new `attributes` field (optional `namespace`) to read product metadata values.
+
+## 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

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

@@ -569,6 +569,8 @@ export type CartAddLinesPayload = {
     warnings: Array<CartWarning>;
 };
 export type 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?: InputMaybe<Scalars['String']['input']>;
     /** City */
     city: Scalars['String']['input'];
     /** Company name */
@@ -577,6 +579,8 @@ export type CartAddressInput = {
     country: CountryCode;
     /** First name */
     firstName?: InputMaybe<Scalars['String']['input']>;
+    /** Flat / apartment number as a discrete field — optional companion to `buildingNumber`. */
+    flatNumber?: InputMaybe<Scalars['String']['input']>;
     /** Last name */
     lastName?: InputMaybe<Scalars['String']['input']>;
     /** Phone number */
@@ -1134,6 +1138,54 @@ export declare const CompensationType: {
     readonly StoreCredit: "STORE_CREDIT";
 };
 export type CompensationType = typeof CompensationType[keyof typeof CompensationType];
+export type ConfiguratorField = {
+    /** Optional help text shown beneath the field. */
+    description?: Maybe<Scalars['String']['output']>;
+    /** Who provides the value — CUSTOMER (the shopper fills it in) or BOTH (seller sets a default the shopper can change). Seller-only metadata fields are not returned here. */
+    filledBy: AttributeFillingMode;
+    /** URL-friendly key for the field. */
+    handle: Scalars['String']['output'];
+    /** Stable identifier of this field. */
+    id: Scalars['ID']['output'];
+    /** Whether this field should be shown on the storefront. */
+    isVisible: Scalars['Boolean']['output'];
+    /** Upper bound — maximum value (NUMBER) or maximum length (TEXT). */
+    maxValue?: Maybe<Scalars['Float']['output']>;
+    /** Lower bound — minimum value (NUMBER) or minimum length (TEXT). */
+    minValue?: Maybe<Scalars['Float']['output']>;
+    /** Field label shown to the shopper (e.g. "Finish"). */
+    name: Scalars['String']['output'];
+    /** Selectable choices for SELECT / RADIO / CHECKBOX fields; empty for free-input types (TEXT, NUMBER, …). */
+    options: Array<ConfiguratorOption>;
+    /** If a choice adds cost, how it is billed — BUNDLED (folded into the product price) or SEPARATE_LINE (its own order line). Null when the field has no price impact. */
+    pricingMode?: Maybe<AttributeBillingMode>;
+    /** Whether the shopper must provide a value before adding the product to the cart. */
+    required: Scalars['Boolean']['output'];
+    /** Order in which to render this field. */
+    sortOrder: Scalars['Int']['output'];
+    /** Input type — controls how to render the field (TEXT, TEXTAREA, SELECT, RADIO, CHECKBOX, NUMBER, COLOR, …). */
+    type: AttributeType;
+};
+export type ConfiguratorOption = {
+    /** Hex colour for swatch rendering (COLOR fields). */
+    colorHex?: Maybe<Scalars['String']['output']>;
+    /** Stable identifier of this choice. */
+    id: Scalars['ID']['output'];
+    /** Whether this choice is pre-selected by default. */
+    isDefault: Scalars['Boolean']['output'];
+    /** Human-readable label shown to the shopper. */
+    label: Scalars['String']['output'];
+    /** The stocked variant this choice maps to (used for inventory-backed components). Null when the choice maps to no variant or the variant no longer exists. */
+    linkedVariant?: Maybe<LinkedVariantSummary>;
+    /** Order in which to render this choice. */
+    sortOrder: Scalars['Int']['output'];
+    /** Extra charge applied when this choice is selected. With surchargeType FIXED it is an amount in minor currency units (e.g. 500 = 5.00). With PERCENT it is thousandths of a percent (e.g. 1500 = 1.5%). */
+    surchargeAmount?: Maybe<Scalars['Int']['output']>;
+    /** How to interpret surchargeAmount — FIXED (a money amount) or PERCENT. */
+    surchargeType?: Maybe<AttributeOptionSurchargeType>;
+    /** Machine value (slug-style) — use it for form state and when submitting the choice to the cart. */
+    value: Scalars['String']['output'];
+};
 export declare const ContentFormat: {
     readonly Html: "HTML";
     readonly Markdown: "MARKDOWN";
@@ -2161,6 +2213,8 @@ export declare const LoyaltyTransactionType: {
 };
 export type LoyaltyTransactionType = typeof LoyaltyTransactionType[keyof typeof LoyaltyTransactionType];
 export type MailingAddress = 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?: Maybe<Scalars['String']['output']>;
     /** City / town. */
     city?: Maybe<Scalars['String']['output']>;
     /** Company name (relevant for B2B addresses). */
@@ -2171,6 +2225,8 @@ export type MailingAddress = Node & {
     countryCode?: Maybe<CountryCode>;
     /** Buyer first name. */
     firstName?: Maybe<Scalars['String']['output']>;
+    /** Flat / apartment number as a discrete field — optional companion to `buildingNumber`. */
+    flatNumber?: Maybe<Scalars['String']['output']>;
     /** 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). */
     formatted: Array<Scalars['String']['output']>;
     /** Single-line summary of the area, e.g. "Warszawa, MZ, Poland". Useful for compact display in lists. */
@@ -2743,10 +2799,8 @@ export type PricingTier = {
     unitPrice: Money;
 };
 export type Product = Node & {
-    /** Assigned AttributeSet ID (shared template fields) */
-    attributeSetId?: Maybe<Scalars['ID']['output']>;
-    /** Customer-facing product attributes (configurator) — set definitions + per-product scoped */
-    attributes: Array<ProductAttributeDefinition>;
+    /** This product's stored custom-field values — merchant-managed metadata such as manufacturer, licence, material or EAN. Only fields the merchant marked visible are returned. Pass `namespace` to fetch a single group. */
+    attributes: Array<EntityAttributeField>;
     /** Average rating (1-5) */
     averageRating?: Maybe<Scalars['Float']['output']>;
     /** Canonical brand entity. Resolved via DataLoader (N+1 safe for list queries). Null when the product has no assigned brand. */
@@ -2757,6 +2811,8 @@ export type Product = Node & {
     compareAtPriceRange?: Maybe<ProductPriceRange>;
     /** Opt-in: compare-at price range with conversion transparency. */
     compareAtPriceRangeWithConversion?: Maybe<ConvertedPriceRange>;
+    /** Configurable fields shown on the product page for the shopper to fill in or choose (combines shared template fields and product-specific ones). Pass `{ filledBy: CUSTOMER }` to return only the fields a shopper can edit. */
+    configuratorFields: Array<ConfiguratorField>;
     /** Creation timestamp */
     createdAt: Scalars['DateTime']['output'];
     /** Plain text description */
@@ -2806,60 +2862,6 @@ export type Product = Node & {
     /** Catalog visibility — PUBLIC | HIDDEN | BUNDLE_ONLY */
     visibility: ProductVisibility;
 };
-export type ProductAttributeDefinition = {
-    /** Billing mode — BUNDLED | SEPARATE_LINE; null = informational only */
-    billingMode?: Maybe<AttributeBillingMode>;
-    /** Customer-facing description */
-    description?: Maybe<Scalars['String']['output']>;
-    /** Display order */
-    displayOrder: Scalars['Int']['output'];
-    /** Filling mode — MERCHANT | CUSTOMER | BOTH */
-    fillingMode: AttributeFillingMode;
-    /** URL-friendly handle */
-    handle: Scalars['String']['output'];
-    /** Definition ID */
-    id: Scalars['ID']['output'];
-    /** Required validation flag */
-    isRequired: Scalars['Boolean']['output'];
-    /** Visibility flag */
-    isVisible: Scalars['Boolean']['output'];
-    /** Max value (NUMBER) / max length (TEXT) */
-    maxValue?: Maybe<Scalars['Float']['output']>;
-    /** Min value (NUMBER) / min length (TEXT) */
-    minValue?: Maybe<Scalars['Float']['output']>;
-    /** Field name (e.g. "Finiszer") */
-    name: Scalars['String']['output'];
-    /** Options for SELECT/RADIO/CHECKBOX types */
-    options: Array<ProductAttributeOption>;
-    /** Per-product scope — set to product ID for unique configurator fields, null for shared (in AttributeSet) */
-    scopeProductId?: Maybe<Scalars['ID']['output']>;
-    /** Tax class ID; null = inherit from variant */
-    taxClassId?: Maybe<Scalars['ID']['output']>;
-    /** Field type — TEXT/SELECT/RADIO/CHECKBOX/etc. */
-    type: AttributeType;
-};
-export type ProductAttributeOption = {
-    /** Hex color (for COLOR/SWATCH types) */
-    colorHex?: Maybe<Scalars['String']['output']>;
-    /** Option ID */
-    id: Scalars['ID']['output'];
-    /** Default option marker */
-    isDefault: Scalars['Boolean']['output'];
-    /** Display label shown to customer */
-    label: Scalars['String']['output'];
-    /** Summary of the linked ProductVariant. Null when the option has no linkedVariantId or the variant was deleted. */
-    linkedVariant?: Maybe<LinkedVariantSummary>;
-    /** Linked ProductVariant ID for component stock decrement (hidden-products pattern). */
-    linkedVariantId?: Maybe<Scalars['ID']['output']>;
-    /** Sort order */
-    sortOrder: Scalars['Int']['output'];
-    /** Surcharge amount when selected (FIXED = minor currency units; PERCENT = thousandths of percent). */
-    surchargeAmount?: Maybe<Scalars['Int']['output']>;
-    /** Surcharge type — FIXED | PERCENT. */
-    surchargeType?: Maybe<AttributeOptionSurchargeType>;
-    /** Internal value (slug-style) */
-    value: Scalars['String']['output'];
-};
 export type ProductConnection = {
     /** Product edges with cursors */
     edges: Array<ProductEdge>;