@doswiftly/storefront-sdk 9.1.0 → 11.0.0

package/dist/core/operations/cart.js

@@ -2,14 +2,16 @@
  * Cart GraphQL operations — manual query strings (no codegen).
  *
  * SSOT: packages/backend/src/commerce/storefront-graphql/operations/
- *   - fragments.graphql (CartCost, CartLineCost, CartLine, Cart, etc.)
+ *   - fragments.graphql (CartCost, CartLineCost, CartLine, Cart, Order, CartWarning, etc.)
  *   - queries.graphql   (Cart query)
- *   - mutations.graphql  (cartCreate, cartLinesAdd, etc.)
+ *   - mutations.graphql  (cartCreate, cartAddLines, etc.)
  *
  * Validate drift: pnpm test:contract (cart-operations-drift test)
  *
- * Cart mutations always return full Cart + userErrors.
+ * Cart mutations always return full Cart + userErrors + warnings (non-fatal hints).
+ * Drift detection: PreToolUse hook validuje strings przeciwko storefront-operations/schema.graphql.
  */
+import { composeOperation } from './compose';
 // ---------------------------------------------------------------------------
 // Shared fragments (matching SSOT fragments.graphql)
 // ---------------------------------------------------------------------------
@@ -135,6 +137,53 @@ const CART_DISCOUNT_ALLOCATION_FRAGMENT = `
     amount { ...Money }
   }
 `;
+const MAILING_ADDRESS_FRAGMENT = `
+  fragment MailingAddress on MailingAddress {
+    id
+    firstName
+    lastName
+    name
+    company
+    streetLine1
+    streetLine2
+    city
+    state
+    stateCode
+    country
+    countryCode
+    postalCode
+    phone
+    isDefault
+  }
+`;
+const CART_SHIPPING_METHOD_FRAGMENT = `
+  fragment CartShippingMethod on CartShippingMethod {
+    handle
+    title
+    price { ...Money }
+  }
+`;
+const CART_APPLIED_GIFT_CARD_FRAGMENT = `
+  fragment CartAppliedGiftCard on CartAppliedGiftCard {
+    maskedCode
+    lastCharacters
+    appliedAmount { ...Money }
+    remainingBalance { ...Money }
+  }
+`;
+const CART_SELECTED_PAYMENT_METHOD_FRAGMENT = `
+  fragment CartSelectedPaymentMethod on PaymentMethod {
+    id
+    name
+    provider
+    type
+    icon
+    description
+    isDefault
+    supportedCurrencies
+    position
+  }
+`;
 const CART_FRAGMENT = `
   fragment Cart on Cart {
     id
@@ -155,6 +204,13 @@ const CART_FRAGMENT = `
     discountAllocations { ...CartDiscountAllocation }
     note
     attributes { key value }
+    email
+    phone
+    shippingAddress { ...MailingAddress }
+    billingAddress { ...MailingAddress }
+    selectedShippingMethod { ...CartShippingMethod }
+    selectedPaymentMethod { ...CartSelectedPaymentMethod }
+    appliedGiftCards { ...CartAppliedGiftCard }
     createdAt
     updatedAt
   }
@@ -163,8 +219,37 @@ const CART_FRAGMENT = `
   ${CART_BUYER_IDENTITY_FRAGMENT}
   ${CART_DISCOUNT_CODE_FRAGMENT}
   ${CART_DISCOUNT_ALLOCATION_FRAGMENT}
+  ${MAILING_ADDRESS_FRAGMENT}
+  ${CART_SHIPPING_METHOD_FRAGMENT}
+  ${CART_APPLIED_GIFT_CARD_FRAGMENT}
+  ${CART_SELECTED_PAYMENT_METHOD_FRAGMENT}
   ${PAGE_INFO_FRAGMENT}
 `;
+const ORDER_FRAGMENT = `
+  fragment Order on Order {
+    id
+    orderNumber
+    totals {
+      total { ...Money }
+      subtotal { ...Money }
+      totalTax { ...Money }
+      totalShipping { ...Money }
+    }
+    status
+    paymentStatus
+    fulfillmentStatus
+    processedAt
+    confirmedAt
+    cancelledAt
+    expiredAt
+    shippingAddress { ...MailingAddress }
+    itemCount
+    canCreatePayment
+    paymentMethodType
+  }
+  ${MONEY_FRAGMENT}
+  ${MAILING_ADDRESS_FRAGMENT}
+`;
 const USER_ERROR_FRAGMENT = `
   fragment UserError on UserError {
     message
@@ -172,87 +257,245 @@ const USER_ERROR_FRAGMENT = `
     field
   }
 `;
+const CART_WARNING_FRAGMENT = `
+  fragment CartWarning on CartWarning {
+    message
+    code
+    target
+  }
+`;
 // ---------------------------------------------------------------------------
 // Queries
 // ---------------------------------------------------------------------------
-export const CART_QUERY = `
+export const CART_QUERY = composeOperation(`
   query Cart($id: ID!) {
     cart(id: $id) {
       ...Cart
     }
   }
   ${CART_FRAGMENT}
-`;
+`);
 // ---------------------------------------------------------------------------
 // Mutations
 // ---------------------------------------------------------------------------
-export const CART_CREATE = `
+export const CART_CREATE = composeOperation(`
   mutation CartCreate($input: CartCreateInput) {
     cartCreate(input: $input) {
       cart { ...Cart }
       userErrors { ...UserError }
+      warnings { ...CartWarning }
     }
   }
   ${CART_FRAGMENT}
   ${USER_ERROR_FRAGMENT}
-`;
-export const CART_LINES_ADD = `
-  mutation CartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
-    cartLinesAdd(cartId: $cartId, lines: $lines) {
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_ADD_LINES = composeOperation(`
+  mutation CartAddLines($id: ID!, $lines: [CartLineInput!]!) {
+    cartAddLines(id: $id, lines: $lines) {
       cart { ...Cart }
       userErrors { ...UserError }
+      warnings { ...CartWarning }
     }
   }
   ${CART_FRAGMENT}
   ${USER_ERROR_FRAGMENT}
-`;
-export const CART_LINES_UPDATE = `
-  mutation CartLinesUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
-    cartLinesUpdate(cartId: $cartId, lines: $lines) {
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_UPDATE_LINES = composeOperation(`
+  mutation CartUpdateLines($id: ID!, $lines: [CartLineUpdateInput!]!) {
+    cartUpdateLines(id: $id, lines: $lines) {
       cart { ...Cart }
       userErrors { ...UserError }
+      warnings { ...CartWarning }
     }
   }
   ${CART_FRAGMENT}
   ${USER_ERROR_FRAGMENT}
-`;
-export const CART_LINES_REMOVE = `
-  mutation CartLinesRemove($cartId: ID!, $lineIds: [ID!]!) {
-    cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_REMOVE_LINES = composeOperation(`
+  mutation CartRemoveLines($id: ID!, $lineIds: [ID!]!) {
+    cartRemoveLines(id: $id, lineIds: $lineIds) {
       cart { ...Cart }
       userErrors { ...UserError }
+      warnings { ...CartWarning }
     }
   }
   ${CART_FRAGMENT}
   ${USER_ERROR_FRAGMENT}
-`;
-export const CART_DISCOUNT_CODES_UPDATE = `
-  mutation CartDiscountCodesUpdate($cartId: ID!, $discountCodes: [String!]!) {
-    cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) {
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_DISCOUNT_CODES_UPDATE = composeOperation(`
+  mutation CartDiscountCodesUpdate($id: ID!, $discountCodes: [String!]!) {
+    cartDiscountCodesUpdate(id: $id, discountCodes: $discountCodes) {
       cart { ...Cart }
       userErrors { ...UserError }
+      warnings { ...CartWarning }
     }
   }
   ${CART_FRAGMENT}
   ${USER_ERROR_FRAGMENT}
-`;
-export const CART_NOTE_UPDATE = `
-  mutation CartNoteUpdate($cartId: ID!, $note: String!) {
-    cartNoteUpdate(cartId: $cartId, note: $note) {
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_UPDATE_NOTE = composeOperation(`
+  mutation CartUpdateNote($id: ID!, $note: String!) {
+    cartUpdateNote(id: $id, note: $note) {
       cart { ...Cart }
       userErrors { ...UserError }
+      warnings { ...CartWarning }
     }
   }
   ${CART_FRAGMENT}
   ${USER_ERROR_FRAGMENT}
-`;
-export const CART_BUYER_IDENTITY_UPDATE = `
-  mutation CartBuyerIdentityUpdate($cartId: ID!, $buyerIdentity: CartBuyerIdentityInput!) {
-    cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentity) {
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_UPDATE_BUYER_IDENTITY = composeOperation(`
+  mutation CartUpdateBuyerIdentity($id: ID!, $buyerIdentity: CartBuyerIdentityInput!) {
+    cartUpdateBuyerIdentity(id: $id, buyerIdentity: $buyerIdentity) {
       cart { ...Cart }
       userErrors { ...UserError }
+      warnings { ...CartWarning }
     }
   }
   ${CART_FRAGMENT}
   ${USER_ERROR_FRAGMENT}
-`;
+  ${CART_WARNING_FRAGMENT}
+`);
+// ---------------------------------------------------------------------------
+// Phase 3 — Cart completion lifecycle mutations
+// ---------------------------------------------------------------------------
+export const CART_SET_SHIPPING_ADDRESS = composeOperation(`
+  mutation CartSetShippingAddress($input: CartSetShippingAddressInput!) {
+    cartSetShippingAddress(input: $input) {
+      cart { ...Cart }
+      userErrors { ...UserError }
+      warnings { ...CartWarning }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_SET_BILLING_ADDRESS = composeOperation(`
+  mutation CartSetBillingAddress($input: CartSetBillingAddressInput!) {
+    cartSetBillingAddress(input: $input) {
+      cart { ...Cart }
+      userErrors { ...UserError }
+      warnings { ...CartWarning }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_SELECT_SHIPPING_METHOD = composeOperation(`
+  mutation CartSelectShippingMethod($input: CartSelectShippingMethodInput!) {
+    cartSelectShippingMethod(input: $input) {
+      cart { ...Cart }
+      userErrors { ...UserError }
+      warnings { ...CartWarning }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_SELECT_PAYMENT_METHOD = composeOperation(`
+  mutation CartSelectPaymentMethod($input: CartSelectPaymentMethodInput!) {
+    cartSelectPaymentMethod(input: $input) {
+      cart { ...Cart }
+      userErrors { ...UserError }
+      warnings { ...CartWarning }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_APPLY_GIFT_CARD = composeOperation(`
+  mutation CartApplyGiftCard($input: CartApplyGiftCardInput!) {
+    cartApplyGiftCard(input: $input) {
+      cart { ...Cart }
+      userErrors { ...UserError }
+      warnings { ...CartWarning }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_REMOVE_GIFT_CARD = composeOperation(`
+  mutation CartRemoveGiftCard($input: CartRemoveGiftCardInput!) {
+    cartRemoveGiftCard(input: $input) {
+      cart { ...Cart }
+      userErrors { ...UserError }
+      warnings { ...CartWarning }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+  ${CART_WARNING_FRAGMENT}
+`);
+export const CART_UPDATE_GIFT_CARD_RECIPIENT = composeOperation(`
+  mutation CartUpdateGiftCardRecipient($input: CartUpdateGiftCardRecipientInput!) {
+    cartUpdateGiftCardRecipient(input: $input) {
+      cart { ...Cart }
+      userErrors { ...UserError }
+      warnings { ...CartWarning }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+  ${CART_WARNING_FRAGMENT}
+`);
+/**
+ * cartComplete — returns the Order created from the cart (carrying
+ * `canCreatePayment` + `paymentMethodType` signals for post-completion payment
+ * flow decisions). The cart itself is NOT returned — after completion it is
+ * CONVERTED/locked, so the storefront drops its local cart and works with the
+ * Order. `order` is non-null on success. `paymentUrl` is intentionally NOT in
+ * the payload (Decision D4) — the storefront calls a separate `paymentCreate`
+ * mutation after checking `order.canCreatePayment`.
+ */
+export const CART_COMPLETE = composeOperation(`
+  mutation CartComplete($input: CartCompleteInput!) {
+    cartComplete(input: $input) {
+      order { ...Order }
+      userErrors { ...UserError }
+      warnings { ...CartWarning }
+    }
+  }
+  ${ORDER_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+  ${CART_WARNING_FRAGMENT}
+`);
+/**
+ * cartValidateDiscountCode Query — read-only preview discount applicability
+ * (Decision D3). No cart side effects; storefront UI używa do inline feedback
+ * gdy klient wpisuje kod (przed wywołaniem cartDiscountCodesUpdate).
+ *
+ * Caching guidance: `fetchPolicy: 'network-only'` lub key zawierający
+ * `cart.subtotal` (discount eligibility może zależeć od minimum order amount).
+ */
+export const CART_VALIDATE_DISCOUNT_CODE = composeOperation(`
+  query CartValidateDiscountCode($cartId: ID!, $discountCode: String!) {
+    cartValidateDiscountCode(cartId: $cartId, discountCode: $discountCode) {
+      isValid
+      discount {
+        code
+        title
+        type
+        value
+        discountAmount {
+          amount
+          currencyCode
+        }
+      }
+      error {
+        code
+        message
+      }
+    }
+  }
+`);

package/dist/core/operations/compose.d.ts

@@ -0,0 +1,24 @@
+/**
+ * composeOperation — assemble a GraphQL operation string from an operation body
+ * plus its fragment definitions, deduplicating fragments by name.
+ *
+ * The SDK hand-maintains operation strings (no codegen) by concatenating fragment
+ * constants. Each constant carries its own transitive dependency closure — e.g.
+ * the Cart fragment tree pulls in `Money`, and the Order fragment tree pulls in
+ * `Money` too. When one operation selects two fields whose fragment trees overlap
+ * (the only case today: `cartComplete` returns both `cart` and `order`), the naive
+ * concatenation emits the shared fragment twice → GraphQL `UniqueFragmentNames`
+ * violation → the server rejects the whole request (HTTP 400).
+ *
+ * `composeOperation` scans the concatenated string, extracts every
+ * `fragment Name on Type { ... }` block (brace-matched), keeps the first
+ * occurrence of each name, and reassembles: operation body first, then each
+ * unique fragment. Every exported operation is wrapped in it, so a future
+ * operation combining two fragment trees can never reintroduce the collision.
+ *
+ * Pure string processing — no `graphql` dependency, so `core/` stays 0-deps.
+ * Inputs are our own controlled operation constants (no GraphQL string literals
+ * or comments), so the brace-matcher does not need a full lexer.
+ */
+export declare function composeOperation(raw: string): string;
+//# sourceMappingURL=compose.d.ts.map

package/dist/core/operations/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/core/operations/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuCpD"}

package/dist/core/operations/compose.js

@@ -0,0 +1,58 @@
+/**
+ * composeOperation — assemble a GraphQL operation string from an operation body
+ * plus its fragment definitions, deduplicating fragments by name.
+ *
+ * The SDK hand-maintains operation strings (no codegen) by concatenating fragment
+ * constants. Each constant carries its own transitive dependency closure — e.g.
+ * the Cart fragment tree pulls in `Money`, and the Order fragment tree pulls in
+ * `Money` too. When one operation selects two fields whose fragment trees overlap
+ * (the only case today: `cartComplete` returns both `cart` and `order`), the naive
+ * concatenation emits the shared fragment twice → GraphQL `UniqueFragmentNames`
+ * violation → the server rejects the whole request (HTTP 400).
+ *
+ * `composeOperation` scans the concatenated string, extracts every
+ * `fragment Name on Type { ... }` block (brace-matched), keeps the first
+ * occurrence of each name, and reassembles: operation body first, then each
+ * unique fragment. Every exported operation is wrapped in it, so a future
+ * operation combining two fragment trees can never reintroduce the collision.
+ *
+ * Pure string processing — no `graphql` dependency, so `core/` stays 0-deps.
+ * Inputs are our own controlled operation constants (no GraphQL string literals
+ * or comments), so the brace-matcher does not need a full lexer.
+ */
+export function composeOperation(raw) {
+    const fragmentStart = /fragment\s+(\w+)\s+on\s+\w+\s*\{/g;
+    const fragments = new Map();
+    const bodyParts = [];
+    let cursor = 0;
+    let match;
+    while ((match = fragmentStart.exec(raw)) !== null) {
+        const blockStart = match.index;
+        // Text before this fragment — the operation body on the first iteration,
+        // inter-fragment whitespace afterwards.
+        bodyParts.push(raw.slice(cursor, blockStart));
+        // Brace-match from the fragment's opening `{` to its closing `}`. Nested
+        // braces (field arguments like `url(transform: { maxWidth: 300 })`) net out.
+        let depth = 1;
+        let i = blockStart + match[0].length;
+        while (i < raw.length && depth > 0) {
+            const ch = raw[i];
+            if (ch === '{')
+                depth++;
+            else if (ch === '}')
+                depth--;
+            i++;
+        }
+        const name = match[1];
+        if (!fragments.has(name)) {
+            fragments.set(name, raw.slice(blockStart, i).trim());
+        }
+        cursor = i;
+        fragmentStart.lastIndex = i;
+    }
+    bodyParts.push(raw.slice(cursor));
+    const body = bodyParts.join('').trim();
+    return fragments.size > 0
+        ? [body, ...fragments.values()].join('\n\n')
+        : body;
+}

package/dist/react/hooks/use-cart-manager.d.ts

@@ -13,15 +13,16 @@
  * ```
  */
 import type { Cart, CartLineInput, CartLineUpdateInput } from '../../core/cart/types';
+import type { CartMutationOutcome } from '../../core/cart/cart-client';
 export declare function useCartManager(): {
     getCart: () => Promise<Cart | null>;
     addItem: (lines: CartLineInput[], options?: {
         forceNewCart?: boolean;
-    }) => Promise<Cart>;
-    updateItem: (lines: CartLineUpdateInput[]) => Promise<Cart>;
-    removeItem: (lineIds: string[]) => Promise<Cart>;
-    updateDiscountCodes: (codes: string[]) => Promise<Cart>;
-    updateNote: (note: string) => Promise<Cart>;
+    }) => Promise<CartMutationOutcome>;
+    updateItem: (lines: CartLineUpdateInput[]) => Promise<CartMutationOutcome>;
+    removeItem: (lineIds: string[]) => Promise<CartMutationOutcome>;
+    updateDiscountCodes: (codes: string[]) => Promise<CartMutationOutcome>;
+    updateNote: (note: string) => Promise<CartMutationOutcome>;
     clearCart: () => void;
     getCartId: () => string | null;
     isLoading: boolean;

package/dist/react/hooks/use-cart-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-cart-manager.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cart-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,mBAAmB,EAA2C,MAAM,uBAAuB,CAAC;AAwB/H,wBAAgB,cAAc;mBAiCU,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;qBAoBjD,aAAa,EAAE,YACZ;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC;wBA0BP,mBAAmB,EAAE,KAC3B,OAAO,CAAC,IAAI,CAAC;0BAuB+B,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAAC;iCAuBjB,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAAC;uBAoBlC,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;;qBA2BhC,MAAM,GAAG,IAAI;;;EAiBhD"}
+{"version":3,"file":"use-cart-manager.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cart-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAwBvE,wBAAgB,cAAc;mBAiCU,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;qBAoBjD,aAAa,EAAE,YACZ;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KACnC,OAAO,CAAC,mBAAmB,CAAC;wBAyBtB,mBAAmB,EAAE,KAC3B,OAAO,CAAC,mBAAmB,CAAC;0BAuBgB,MAAM,EAAE,KAAG,OAAO,CAAC,mBAAmB,CAAC;iCAuBhC,MAAM,EAAE,KAAG,OAAO,CAAC,mBAAmB,CAAC;uBAoBjD,MAAM,KAAG,OAAO,CAAC,mBAAmB,CAAC;;qBA2B/C,MAAM,GAAG,IAAI;;;EAiBhD"}

package/dist/react/hooks/use-cart-manager.js

@@ -49,7 +49,7 @@ export function useCartManager() {
             if (existing)
                 return existing;
         }
-        const cart = await cartClient.create();
+        const { cart } = await cartClient.create();
         setCartIdCookie(cart.id);
         return cart.id;
     }, [cartClient]);
@@ -90,8 +90,7 @@ export function useCartManager() {
         setIsLoading(true);
         try {
             const cartId = await getOrCreateCartId(options?.forceNewCart);
-            const cart = await cartClient.addItems(cartId, lines);
-            return cart;
+            return await cartClient.addItems(cartId, lines);
         }
         catch (err) {
             if (isCartExpired(err) && !options?.forceNewCart) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "9.1.0",
+  "version": "11.0.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "files": [