@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/core/cart/actions.mjs

@@ -9,18 +9,20 @@ var CartActionError = class extends Error {
 	}
 };
 /**
-* Parses an incoming cart mutation request into a typed {@link CartAction}.
+* Reads the cart change from a cart request body. Use the function in a custom cart route.
 *
-* Accepts `application/json` and `application/x-www-form-urlencoded` /
-* `multipart/form-data` content types. JSON and FormData each support a
-* different subset of intents — JSON produces `discount-update` while
-* FormData produces `discount-apply` / `discount-remove`.
+* The function accepts `application/json`, `application/x-www-form-urlencoded`, and
+* `multipart/form-data` requests. A JSON request can replace every discount code, and a form submission applies or removes one code.
 *
-* FormData requests always return `cartId: null` — the server handler
-* should fall back to the cart cookie.
+* A form submission always returns a `null` cart ID. Read the cart ID for a form submission with `getCartId`.
 *
-* @throws If the content-type is unsupported, the intent is unrecognized,
-* or required fields are missing.
+* The function reads the request body, and you can't read the body again afterward. The function throws when the request has an unsupported content type, an unknown intent, or a missing required field, and when a JSON body combines more than one of `lines`, `discountCodes`, `attributes`, and `note`.
+*
+* @param request The incoming cart request.
+* @returns The cart change and, for a JSON body, the cart ID.
+* @throws If the request has an unsupported content type, an unrecognized intent,
+* or missing required fields, or if a JSON body combines more than one of
+* `lines`, `discountCodes`, `attributes`, and `note`.
 *
 * @example
 * ```ts
@@ -34,6 +36,7 @@ var CartActionError = class extends Error {
 *   // ...
 * }
 * ```
+* @publicDocs
 */
 async function parseCartRequest(request) {
 	const contentType = request.headers.get("content-type") ?? "";
@@ -44,9 +47,17 @@ async function parseCartRequest(request) {
 	};
 	throw new CartActionError(`Unsupported content-type: "${contentType}". Expected application/json or form data.`);
 }
+const JSON_MUTATION_FIELDS = [
+	"lines",
+	"discountCodes",
+	"attributes",
+	"note"
+];
 function parseJsonBody(body) {
 	assertObject(body);
 	const cartId = typeof body.cartId === "string" ? normalizeCartId(body.cartId) : null;
+	const fields = JSON_MUTATION_FIELDS.filter((field) => body[field] !== void 0);
+	if (fields.length > 1) throw new CartActionError(`Request body must contain only one of "lines", "discountCodes", "attributes", or "note", got ${fields.join(", ")}.`);
 	if ("note" in body && typeof body.note === "string") return {
 		action: {
 			intent: "note-update",
@@ -101,6 +112,7 @@ function partitionLines(rawLines) {
 		else if (hasId && quantity === 0) removeIds.push(line.id);
 		else if (hasId) updates.push({
 			id: line.id,
+			...hasMerchandiseId && { merchandiseId: line.merchandiseId },
 			quantity,
 			...optionalFields
 		});

package/dist/core/cart/actions.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"actions.mjs","names":[],"sources":["../../../src/core/cart/actions.ts"],"sourcesContent":["import { normalizeCartId } from \"./cookie\";\nimport { getCartAttributeFormEntries } from \"./form\";\n\n/** A key-value pair attached to the cart or an individual cart line. */\nexport type CartAttributeInput = { key: string; value: string };\n\nexport type CartLineAddInput = {\n  /** Storefront API GID of the product variant to add. */\n  merchandiseId: string;\n  quantity: number;\n  attributes?: CartAttributeInput[];\n  /** Selling plan GID for subscription line items. */\n  sellingPlanId?: string;\n};\n\n/** Input for updating an existing cart line. Setting `quantity` to `0` removes the line. */\nexport type CartLineUpdateInput = {\n  /** The `CartLine.id` of the line to update. */\n  id: string;\n  quantity: number;\n  attributes?: CartAttributeInput[];\n  sellingPlanId?: string;\n};\n\n/**\n * Discriminated union of all cart mutation intents.\n *\n * {@link parseCartRequest} normalizes both JSON and FormData requests into one\n * of these variants. The `intent` field determines the Storefront API mutation:\n *\n * - `\"add\"` — add new lines (cartLinesAdd, or cartCreate when no cart exists)\n * - `\"update\"` — change quantity or attributes on existing lines (cartLinesUpdate)\n * - `\"remove\"` — remove lines by ID (cartLinesRemove)\n * - `\"discount-update\"` — replace all discount codes (cartDiscountCodesUpdate)\n * - `\"discount-apply\"` — add a single discount code (read-then-write via cartDiscountCodesUpdate)\n * - `\"discount-remove\"` — remove a single discount code (read-then-write via cartDiscountCodesUpdate)\n * - `\"attributes-update\"` — set cart-level attributes (cartAttributesUpdate)\n * - `\"note-update\"` — set the cart note (cartNoteUpdate)\n */\nexport type CartAction =\n  | { intent: \"add\"; lines: CartLineAddInput[] }\n  | { intent: \"update\"; lines: CartLineUpdateInput[] }\n  | { intent: \"remove\"; lineIds: string[] }\n  | { intent: \"discount-update\"; discountCodes: string[] }\n  | { intent: \"discount-apply\"; code: string }\n  | { intent: \"discount-remove\"; code: string }\n  | { intent: \"attributes-update\"; attributes: CartAttributeInput[] }\n  | { intent: \"note-update\"; note: string };\n\ntype ParsedCartRequest = {\n  action: CartAction;\n  cartId: string | null;\n};\n\nclass CartActionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"CartActionError\";\n  }\n}\n\n/**\n * Parses an incoming cart mutation request into a typed {@link CartAction}.\n *\n * Accepts `application/json` and `application/x-www-form-urlencoded` /\n * `multipart/form-data` content types. JSON and FormData each support a\n * different subset of intents — JSON produces `discount-update` while\n * FormData produces `discount-apply` / `discount-remove`.\n *\n * FormData requests always return `cartId: null` — the server handler\n * should fall back to the cart cookie.\n *\n * @throws If the content-type is unsupported, the intent is unrecognized,\n * or required fields are missing.\n *\n * @example\n * ```ts\n * const { action, cartId } = await parseCartRequest(request);\n *\n * switch (action.intent) {\n *   case \"add\":\n *     return cartLinesAdd(cartId ?? getCartId(request), action.lines);\n *   case \"remove\":\n *     return cartLinesRemove(cartId ?? getCartId(request), action.lineIds);\n *   // ...\n * }\n * ```\n */\nexport async function parseCartRequest(request: Request): Promise<ParsedCartRequest> {\n  const contentType = request.headers.get(\"content-type\") ?? \"\";\n\n  if (contentType.includes(\"application/json\")) {\n    return parseJsonBody(await request.json());\n  }\n\n  if (\n    contentType.includes(\"application/x-www-form-urlencoded\") ||\n    contentType.includes(\"multipart/form-data\")\n  ) {\n    return { action: parseFormData(await request.formData()), cartId: null };\n  }\n\n  throw new CartActionError(\n    `Unsupported content-type: \"${contentType}\". Expected application/json or form data.`,\n  );\n}\n\n// --- JSON parsing ---\n\nfunction parseJsonBody(body: unknown): ParsedCartRequest {\n  assertObject(body);\n  const cartId = typeof body.cartId === \"string\" ? normalizeCartId(body.cartId) : null;\n\n  if (\"note\" in body && typeof body.note === \"string\") {\n    return { action: { intent: \"note-update\", note: body.note }, cartId };\n  }\n\n  if (\"discountCodes\" in body && Array.isArray(body.discountCodes)) {\n    for (const code of body.discountCodes) {\n      assertString(code, \"discountCodes entries\");\n    }\n    return {\n      action: { intent: \"discount-update\", discountCodes: body.discountCodes as string[] },\n      cartId,\n    };\n  }\n\n  if (\"attributes\" in body && Array.isArray(body.attributes)) {\n    return {\n      action: { intent: \"attributes-update\", attributes: parseAttributes(body.attributes) },\n      cartId,\n    };\n  }\n\n  if (!(\"lines\" in body) || !Array.isArray(body.lines)) {\n    throw new CartActionError(\n      'Request body must contain \"lines\", \"discountCodes\", \"attributes\", or \"note\".',\n    );\n  }\n\n  const lines = body.lines as unknown[];\n  if (lines.length === 0) {\n    throw new CartActionError(\"Lines array must not be empty.\");\n  }\n\n  return { action: partitionLines(lines), cartId };\n}\n\nfunction partitionLines(rawLines: unknown[]): CartAction {\n  const adds: CartLineAddInput[] = [];\n  const updates: CartLineUpdateInput[] = [];\n  const removeIds: string[] = [];\n\n  for (const raw of rawLines) {\n    assertObject(raw);\n    const line = raw as Record<string, unknown>;\n    const hasId = \"id\" in line && typeof line.id === \"string\" && line.id !== \"\";\n    const hasMerchandiseId =\n      \"merchandiseId\" in line &&\n      typeof line.merchandiseId === \"string\" &&\n      line.merchandiseId !== \"\";\n\n    assertNonNegativeInteger(line.quantity, \"quantity\");\n    const quantity = line.quantity as number;\n\n    if (!hasId && !hasMerchandiseId) {\n      throw new CartActionError(\n        'Each line must have either \"id\" (for update/remove) or \"merchandiseId\" (for add).',\n      );\n    }\n\n    if (hasId && (line.id as string) === \"\") {\n      throw new CartActionError('Line \"id\" must not be empty.');\n    }\n\n    const optionalFields = extractOptionalLineFields(line);\n\n    if (!hasId && hasMerchandiseId) {\n      adds.push({\n        merchandiseId: line.merchandiseId as string,\n        quantity,\n        ...optionalFields,\n      });\n    } else if (hasId && quantity === 0) {\n      removeIds.push(line.id as string);\n    } else if (hasId) {\n      updates.push({\n        id: line.id as string,\n        quantity,\n        ...optionalFields,\n      });\n    }\n  }\n\n  const populatedBuckets = [adds.length, updates.length, removeIds.length].filter(\n    (n) => n > 0,\n  ).length;\n\n  if (populatedBuckets > 1) {\n    throw new CartActionError(\n      \"Mixed line operations are not allowed. Separate add, update, and remove into distinct requests.\",\n    );\n  }\n\n  if (adds.length > 0) return { intent: \"add\", lines: adds };\n  if (updates.length > 0) return { intent: \"update\", lines: updates };\n  return { intent: \"remove\", lineIds: removeIds };\n}\n\nfunction extractOptionalLineFields(\n  line: Record<string, unknown>,\n): Pick<CartLineAddInput, \"attributes\" | \"sellingPlanId\"> {\n  const result: Pick<CartLineAddInput, \"attributes\" | \"sellingPlanId\"> = {};\n\n  if (\"attributes\" in line && Array.isArray(line.attributes)) {\n    result.attributes = line.attributes as CartAttributeInput[];\n  }\n\n  if (\"sellingPlanId\" in line && typeof line.sellingPlanId === \"string\") {\n    result.sellingPlanId = line.sellingPlanId;\n  }\n\n  return result;\n}\n\n// --- FormData parsing ---\n//\n// HTML forms can't express the same structures as JSON. Key compromises:\n//\n//   Add line:       single item per submission (forms can't batch multiple adds)\n//   Update qty:     server does the math — form sends current qty, server increments/decrements\n//   Remove line:    explicit intent field (can't express \"quantity=0 means remove\" implicitly)\n//   Discount bulk:  no FormData equivalent — forms handle one code at a time\n//   Cart attributes: attributes.<key> fields preserve each key/value relationship\n//   Selling plan:   add only — no way to change selling plan on existing line via form\n//\n// Design decisions:\n//   - `intent` field disambiguates operations (forms need explicit routing; JSON infers from structure)\n//   - Field names match where possible: merchandiseId, quantity, lineId, discountCode, note\n//   - Form submissions get 303 redirect to referer; JSON gets JSON response\n//   - `increase`/`decrease` intents exist because forms can't atomically read-modify-write quantity\n\nconst LINE_INTENTS = new Set([\"increase\", \"decrease\", \"remove\", \"set\"]);\nconst DISCOUNT_INTENTS = new Set([\"discount-apply\", \"discount-remove\"]);\n\nfunction parseFormData(form: FormData): CartAction {\n  const intent = formString(form, \"intent\");\n  const merchandiseId = formString(form, \"merchandiseId\");\n\n  if (!intent && merchandiseId) {\n    return parseAddIntent(form, merchandiseId);\n  }\n\n  if (intent === \"add\") {\n    if (!merchandiseId) {\n      throw new CartActionError('Intent \"add\" requires a \"merchandiseId\" field.');\n    }\n    return parseAddIntent(form, merchandiseId);\n  }\n\n  if (!intent) {\n    throw new CartActionError(\n      'FormData must include an \"intent\" field or a \"merchandiseId\" field.',\n    );\n  }\n\n  if (LINE_INTENTS.has(intent)) {\n    return parseLineIntent(intent, form);\n  }\n\n  if (DISCOUNT_INTENTS.has(intent)) {\n    return parseDiscountIntent(intent as \"discount-apply\" | \"discount-remove\", form);\n  }\n\n  if (intent === \"note-update\") {\n    return parseNoteIntent(form);\n  }\n\n  if (intent === \"attributes-update\") {\n    return parseAttributesIntent(form);\n  }\n\n  throw new CartActionError(\n    `Unknown intent \"${intent}\". Expected one of: add, increase, decrease, remove, set, discount-apply, discount-remove, attributes-update, note-update.`,\n  );\n}\n\nfunction parseLineIntent(intent: string, form: FormData): CartAction {\n  const lineId = formString(form, \"lineId\");\n  if (!lineId) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"lineId\" field.`);\n  }\n\n  if (intent === \"remove\") {\n    return { intent: \"remove\", lineIds: [lineId] };\n  }\n\n  const quantity = formInt(form, \"quantity\");\n  if (quantity === null) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"quantity\" field.`);\n  }\n\n  if (intent === \"set\") {\n    if (quantity <= 0) {\n      return { intent: \"remove\", lineIds: [lineId] };\n    }\n    return { intent: \"update\", lines: [{ id: lineId, quantity }] };\n  }\n\n  if (intent === \"increase\") {\n    return { intent: \"update\", lines: [{ id: lineId, quantity: quantity + 1 }] };\n  }\n\n  const decremented = quantity - 1;\n  if (decremented <= 0) {\n    return { intent: \"remove\", lineIds: [lineId] };\n  }\n  return { intent: \"update\", lines: [{ id: lineId, quantity: decremented }] };\n}\n\nfunction parseDiscountIntent(\n  intent: \"discount-apply\" | \"discount-remove\",\n  form: FormData,\n): CartAction {\n  const code = formString(form, \"discountCode\");\n  if (!code) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"discountCode\" field.`);\n  }\n  return { intent, code };\n}\n\nfunction parseAddIntent(form: FormData, merchandiseId: string): CartAction {\n  const quantity = formInt(form, \"quantity\") ?? 1;\n  const sellingPlanId = formString(form, \"sellingPlanId\");\n\n  const line: CartLineAddInput = { merchandiseId, quantity };\n  if (sellingPlanId) line.sellingPlanId = sellingPlanId;\n\n  const rawAttributes = getCartAttributeFormEntries(form);\n  if (rawAttributes.length > 0) {\n    line.attributes = parseAttributes(rawAttributes);\n  }\n\n  return { intent: \"add\", lines: [line] };\n}\n\nfunction parseNoteIntent(form: FormData): CartAction {\n  const noteValue = form.get(\"note\");\n  if (noteValue === null) {\n    throw new CartActionError('Intent \"note-update\" requires a \"note\" field.');\n  }\n  return { intent: \"note-update\", note: String(noteValue) };\n}\n\nfunction parseAttributesIntent(form: FormData): CartAction {\n  return {\n    intent: \"attributes-update\",\n    attributes: parseAttributes(getCartAttributeFormEntries(form)),\n  };\n}\n\nfunction parseAttributes(values: unknown[]): CartAttributeInput[] {\n  return values.map((value, index) => {\n    assertObject(value);\n    assertString(value.key, `attributes[${index}].key`);\n    assertString(value.value, `attributes[${index}].value`);\n    if (!value.key) {\n      throw new CartActionError(`Expected \"attributes[${index}].key\" not to be empty.`);\n    }\n    return { key: value.key, value: value.value };\n  });\n}\n\n// --- Assertion helpers ---\n\nfunction assertObject(value: unknown): asserts value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new CartActionError(\"Expected an object.\");\n  }\n}\n\nfunction assertString(value: unknown, label: string): asserts value is string {\n  if (typeof value !== \"string\") {\n    throw new CartActionError(`Expected \"${label}\" to be a string.`);\n  }\n}\n\nfunction assertNonNegativeInteger(value: unknown, label: string): asserts value is number {\n  if (typeof value !== \"number\" || !Number.isInteger(value) || value < 0) {\n    throw new CartActionError(\n      `Expected \"${label}\" to be a non-negative integer, got ${JSON.stringify(value)}.`,\n    );\n  }\n}\n\n// --- FormData field helpers ---\n\nfunction formString(form: FormData, key: string): string | null {\n  const value = form.get(key);\n  if (value === null || typeof value !== \"string\") return null;\n  return value || null;\n}\n\nfunction formInt(form: FormData, key: string): number | null {\n  const raw = form.get(key);\n  if (raw === null || typeof raw !== \"string\") return null;\n  const parsed = parseInt(raw, 10);\n  if (Number.isNaN(parsed)) return null;\n  return parsed;\n}\n"],"mappings":"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"}
+{"version":3,"file":"actions.mjs","names":[],"sources":["../../../src/core/cart/actions.ts"],"sourcesContent":["import { normalizeCartId } from \"./cookie\";\nimport { getCartAttributeFormEntries } from \"./form\";\n\n/** A custom key-value pair for the cart or a cart line. */\nexport type CartAttributeInput = {\n  /** The attribute name. parseCartRequest throws for an empty name in cart attributes and in form submissions. */\n  key: string;\n  /** The attribute value. */\n  value: string;\n};\n\n/** Input for adding a line to the cart. */\nexport type CartLineAddInput = {\n  /** The Storefront API GID of the product variant to add. */\n  merchandiseId: string;\n  /** Number of units to add. A form submission without a quantity adds `1`. */\n  quantity: number;\n  /** Custom key-value attributes to set on the new line. */\n  attributes?: CartAttributeInput[];\n  /** The selling plan GID for a subscription line. */\n  sellingPlanId?: string;\n};\n\n/** Input for updating an existing cart line. A quantity of `0` removes the line. */\nexport type CartLineUpdateInput = {\n  /** The ID of the cart line to update. */\n  id: string;\n  /** The GID of a product variant to swap the line to. */\n  merchandiseId?: string;\n  /** The line's new quantity. */\n  quantity: number;\n  /** Custom key-value attributes to set on the line. */\n  attributes?: CartAttributeInput[];\n  /** The selling plan GID to assign to the line for a subscription. */\n  sellingPlanId?: string;\n};\n\n/**\n * A cart change that `parseCartRequest` reads from a JSON or form request.\n *\n * The `intent` field names the change and the Storefront API mutation that applies the change:\n *\n * - `add` adds new lines with `cartLinesAdd`, or creates a cart with `cartCreate` when none exists.\n * - `update` changes quantity, merchandise, or attributes on existing lines with `cartLinesUpdate`.\n * - `remove` removes lines by ID with `cartLinesRemove`.\n * - `discount-update` replaces all discount codes with `cartDiscountCodesUpdate`.\n * - `discount-apply` adds one discount code. The handler reads the current codes, then writes the new list with `cartDiscountCodesUpdate`.\n * - `discount-remove` removes one discount code with the same read-then-write approach.\n * - `attributes-update` sets cart-level attributes with `cartAttributesUpdate`.\n * - `note-update` sets the cart note with `cartNoteUpdate`.\n *\n * @publicDocs\n */\nexport type CartAction =\n  | { intent: \"add\"; lines: CartLineAddInput[] }\n  | { intent: \"update\"; lines: CartLineUpdateInput[] }\n  | { intent: \"remove\"; lineIds: string[] }\n  | { intent: \"discount-update\"; discountCodes: string[] }\n  | { intent: \"discount-apply\"; code: string }\n  | { intent: \"discount-remove\"; code: string }\n  | { intent: \"attributes-update\"; attributes: CartAttributeInput[] }\n  | { intent: \"note-update\"; note: string };\n\n/** The cart change and the cart ID that `parseCartRequest` reads from the request body. */\ntype ParsedCartRequest = {\n  action: CartAction;\n  /** The cart GID from a JSON body, or `null` for a form submission or a JSON body without a cart ID. The function adds the `gid://shopify/Cart/` prefix to a bare cart token. */\n  cartId: string | null;\n};\n\nclass CartActionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"CartActionError\";\n  }\n}\n\n/**\n * Reads the cart change from a cart request body. Use the function in a custom cart route.\n *\n * The function accepts `application/json`, `application/x-www-form-urlencoded`, and\n * `multipart/form-data` requests. A JSON request can replace every discount code, and a form submission applies or removes one code.\n *\n * A form submission always returns a `null` cart ID. Read the cart ID for a form submission with `getCartId`.\n *\n * The function reads the request body, and you can't read the body again afterward. The function throws when the request has an unsupported content type, an unknown intent, or a missing required field, and when a JSON body combines more than one of `lines`, `discountCodes`, `attributes`, and `note`.\n *\n * @param request The incoming cart request.\n * @returns The cart change and, for a JSON body, the cart ID.\n * @throws If the request has an unsupported content type, an unrecognized intent,\n * or missing required fields, or if a JSON body combines more than one of\n * `lines`, `discountCodes`, `attributes`, and `note`.\n *\n * @example\n * ```ts\n * const { action, cartId } = await parseCartRequest(request);\n *\n * switch (action.intent) {\n *   case \"add\":\n *     return cartLinesAdd(cartId ?? getCartId(request), action.lines);\n *   case \"remove\":\n *     return cartLinesRemove(cartId ?? getCartId(request), action.lineIds);\n *   // ...\n * }\n * ```\n * @publicDocs\n */\nexport async function parseCartRequest(request: Request): Promise<ParsedCartRequest> {\n  const contentType = request.headers.get(\"content-type\") ?? \"\";\n\n  if (contentType.includes(\"application/json\")) {\n    return parseJsonBody(await request.json());\n  }\n\n  if (\n    contentType.includes(\"application/x-www-form-urlencoded\") ||\n    contentType.includes(\"multipart/form-data\")\n  ) {\n    return { action: parseFormData(await request.formData()), cartId: null };\n  }\n\n  throw new CartActionError(\n    `Unsupported content-type: \"${contentType}\". Expected application/json or form data.`,\n  );\n}\n\n// --- JSON parsing ---\n\nconst JSON_MUTATION_FIELDS = [\"lines\", \"discountCodes\", \"attributes\", \"note\"] as const;\n\nfunction parseJsonBody(body: unknown): ParsedCartRequest {\n  assertObject(body);\n  const cartId = typeof body.cartId === \"string\" ? normalizeCartId(body.cartId) : null;\n\n  // Each request runs one Storefront API mutation, so any other field would be silently dropped.\n  const fields = JSON_MUTATION_FIELDS.filter((field) => body[field] !== undefined);\n  if (fields.length > 1) {\n    throw new CartActionError(\n      `Request body must contain only one of \"lines\", \"discountCodes\", \"attributes\", or \"note\", got ${fields.join(\", \")}.`,\n    );\n  }\n\n  if (\"note\" in body && typeof body.note === \"string\") {\n    return { action: { intent: \"note-update\", note: body.note }, cartId };\n  }\n\n  if (\"discountCodes\" in body && Array.isArray(body.discountCodes)) {\n    for (const code of body.discountCodes) {\n      assertString(code, \"discountCodes entries\");\n    }\n    return {\n      action: { intent: \"discount-update\", discountCodes: body.discountCodes as string[] },\n      cartId,\n    };\n  }\n\n  if (\"attributes\" in body && Array.isArray(body.attributes)) {\n    return {\n      action: { intent: \"attributes-update\", attributes: parseAttributes(body.attributes) },\n      cartId,\n    };\n  }\n\n  if (!(\"lines\" in body) || !Array.isArray(body.lines)) {\n    throw new CartActionError(\n      'Request body must contain \"lines\", \"discountCodes\", \"attributes\", or \"note\".',\n    );\n  }\n\n  const lines = body.lines as unknown[];\n  if (lines.length === 0) {\n    throw new CartActionError(\"Lines array must not be empty.\");\n  }\n\n  return { action: partitionLines(lines), cartId };\n}\n\nfunction partitionLines(rawLines: unknown[]): CartAction {\n  const adds: CartLineAddInput[] = [];\n  const updates: CartLineUpdateInput[] = [];\n  const removeIds: string[] = [];\n\n  for (const raw of rawLines) {\n    assertObject(raw);\n    const line = raw as Record<string, unknown>;\n    const hasId = \"id\" in line && typeof line.id === \"string\" && line.id !== \"\";\n    const hasMerchandiseId =\n      \"merchandiseId\" in line &&\n      typeof line.merchandiseId === \"string\" &&\n      line.merchandiseId !== \"\";\n\n    assertNonNegativeInteger(line.quantity, \"quantity\");\n    const quantity = line.quantity as number;\n\n    if (!hasId && !hasMerchandiseId) {\n      throw new CartActionError(\n        'Each line must have either \"id\" (for update/remove) or \"merchandiseId\" (for add).',\n      );\n    }\n\n    if (hasId && (line.id as string) === \"\") {\n      throw new CartActionError('Line \"id\" must not be empty.');\n    }\n\n    const optionalFields = extractOptionalLineFields(line);\n\n    if (!hasId && hasMerchandiseId) {\n      adds.push({\n        merchandiseId: line.merchandiseId as string,\n        quantity,\n        ...optionalFields,\n      });\n    } else if (hasId && quantity === 0) {\n      removeIds.push(line.id as string);\n    } else if (hasId) {\n      updates.push({\n        id: line.id as string,\n        ...(hasMerchandiseId && { merchandiseId: line.merchandiseId as string }),\n        quantity,\n        ...optionalFields,\n      });\n    }\n  }\n\n  const populatedBuckets = [adds.length, updates.length, removeIds.length].filter(\n    (n) => n > 0,\n  ).length;\n\n  if (populatedBuckets > 1) {\n    throw new CartActionError(\n      \"Mixed line operations are not allowed. Separate add, update, and remove into distinct requests.\",\n    );\n  }\n\n  if (adds.length > 0) return { intent: \"add\", lines: adds };\n  if (updates.length > 0) return { intent: \"update\", lines: updates };\n  return { intent: \"remove\", lineIds: removeIds };\n}\n\nfunction extractOptionalLineFields(\n  line: Record<string, unknown>,\n): Pick<CartLineAddInput, \"attributes\" | \"sellingPlanId\"> {\n  const result: Pick<CartLineAddInput, \"attributes\" | \"sellingPlanId\"> = {};\n\n  if (\"attributes\" in line && Array.isArray(line.attributes)) {\n    result.attributes = line.attributes as CartAttributeInput[];\n  }\n\n  if (\"sellingPlanId\" in line && typeof line.sellingPlanId === \"string\") {\n    result.sellingPlanId = line.sellingPlanId;\n  }\n\n  return result;\n}\n\n// --- FormData parsing ---\n//\n// HTML forms can't express the same structures as JSON. Key compromises:\n//\n//   Add line:       single item per submission (forms can't batch multiple adds)\n//   Update qty:     server does the math — form sends current qty, server increments/decrements\n//   Remove line:    explicit intent field (can't express \"quantity=0 means remove\" implicitly)\n//   Discount bulk:  no FormData equivalent — forms handle one code at a time\n//   Cart attributes: attributes.<key> fields preserve each key/value relationship\n//   Selling plan:   add only — no way to change selling plan on existing line via form\n//\n// Design decisions:\n//   - `intent` field disambiguates operations (forms need explicit routing; JSON infers from structure)\n//   - Field names match where possible: merchandiseId, quantity, lineId, discountCode, note\n//   - Form submissions get 303 redirect to referer; JSON gets JSON response\n//   - `increase`/`decrease` intents exist because forms can't atomically read-modify-write quantity\n\nconst LINE_INTENTS = new Set([\"increase\", \"decrease\", \"remove\", \"set\"]);\nconst DISCOUNT_INTENTS = new Set([\"discount-apply\", \"discount-remove\"]);\n\nfunction parseFormData(form: FormData): CartAction {\n  const intent = formString(form, \"intent\");\n  const merchandiseId = formString(form, \"merchandiseId\");\n\n  if (!intent && merchandiseId) {\n    return parseAddIntent(form, merchandiseId);\n  }\n\n  if (intent === \"add\") {\n    if (!merchandiseId) {\n      throw new CartActionError('Intent \"add\" requires a \"merchandiseId\" field.');\n    }\n    return parseAddIntent(form, merchandiseId);\n  }\n\n  if (!intent) {\n    throw new CartActionError(\n      'FormData must include an \"intent\" field or a \"merchandiseId\" field.',\n    );\n  }\n\n  if (LINE_INTENTS.has(intent)) {\n    return parseLineIntent(intent, form);\n  }\n\n  if (DISCOUNT_INTENTS.has(intent)) {\n    return parseDiscountIntent(intent as \"discount-apply\" | \"discount-remove\", form);\n  }\n\n  if (intent === \"note-update\") {\n    return parseNoteIntent(form);\n  }\n\n  if (intent === \"attributes-update\") {\n    return parseAttributesIntent(form);\n  }\n\n  throw new CartActionError(\n    `Unknown intent \"${intent}\". Expected one of: add, increase, decrease, remove, set, discount-apply, discount-remove, attributes-update, note-update.`,\n  );\n}\n\nfunction parseLineIntent(intent: string, form: FormData): CartAction {\n  const lineId = formString(form, \"lineId\");\n  if (!lineId) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"lineId\" field.`);\n  }\n\n  if (intent === \"remove\") {\n    return { intent: \"remove\", lineIds: [lineId] };\n  }\n\n  const quantity = formInt(form, \"quantity\");\n  if (quantity === null) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"quantity\" field.`);\n  }\n\n  if (intent === \"set\") {\n    if (quantity <= 0) {\n      return { intent: \"remove\", lineIds: [lineId] };\n    }\n    return { intent: \"update\", lines: [{ id: lineId, quantity }] };\n  }\n\n  if (intent === \"increase\") {\n    return { intent: \"update\", lines: [{ id: lineId, quantity: quantity + 1 }] };\n  }\n\n  const decremented = quantity - 1;\n  if (decremented <= 0) {\n    return { intent: \"remove\", lineIds: [lineId] };\n  }\n  return { intent: \"update\", lines: [{ id: lineId, quantity: decremented }] };\n}\n\nfunction parseDiscountIntent(\n  intent: \"discount-apply\" | \"discount-remove\",\n  form: FormData,\n): CartAction {\n  const code = formString(form, \"discountCode\");\n  if (!code) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"discountCode\" field.`);\n  }\n  return { intent, code };\n}\n\nfunction parseAddIntent(form: FormData, merchandiseId: string): CartAction {\n  const quantity = formInt(form, \"quantity\") ?? 1;\n  const sellingPlanId = formString(form, \"sellingPlanId\");\n\n  const line: CartLineAddInput = { merchandiseId, quantity };\n  if (sellingPlanId) line.sellingPlanId = sellingPlanId;\n\n  const rawAttributes = getCartAttributeFormEntries(form);\n  if (rawAttributes.length > 0) {\n    line.attributes = parseAttributes(rawAttributes);\n  }\n\n  return { intent: \"add\", lines: [line] };\n}\n\nfunction parseNoteIntent(form: FormData): CartAction {\n  const noteValue = form.get(\"note\");\n  if (noteValue === null) {\n    throw new CartActionError('Intent \"note-update\" requires a \"note\" field.');\n  }\n  return { intent: \"note-update\", note: String(noteValue) };\n}\n\nfunction parseAttributesIntent(form: FormData): CartAction {\n  return {\n    intent: \"attributes-update\",\n    attributes: parseAttributes(getCartAttributeFormEntries(form)),\n  };\n}\n\nfunction parseAttributes(values: unknown[]): CartAttributeInput[] {\n  return values.map((value, index) => {\n    assertObject(value);\n    assertString(value.key, `attributes[${index}].key`);\n    assertString(value.value, `attributes[${index}].value`);\n    if (!value.key) {\n      throw new CartActionError(`Expected \"attributes[${index}].key\" not to be empty.`);\n    }\n    return { key: value.key, value: value.value };\n  });\n}\n\n// --- Assertion helpers ---\n\nfunction assertObject(value: unknown): asserts value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new CartActionError(\"Expected an object.\");\n  }\n}\n\nfunction assertString(value: unknown, label: string): asserts value is string {\n  if (typeof value !== \"string\") {\n    throw new CartActionError(`Expected \"${label}\" to be a string.`);\n  }\n}\n\nfunction assertNonNegativeInteger(value: unknown, label: string): asserts value is number {\n  if (typeof value !== \"number\" || !Number.isInteger(value) || value < 0) {\n    throw new CartActionError(\n      `Expected \"${label}\" to be a non-negative integer, got ${JSON.stringify(value)}.`,\n    );\n  }\n}\n\n// --- FormData field helpers ---\n\nfunction formString(form: FormData, key: string): string | null {\n  const value = form.get(key);\n  if (value === null || typeof value !== \"string\") return null;\n  return value || null;\n}\n\nfunction formInt(form: FormData, key: string): number | null {\n  const raw = form.get(key);\n  if (raw === null || typeof raw !== \"string\") return null;\n  const parsed = parseInt(raw, 10);\n  if (Number.isNaN(parsed)) return null;\n  return parsed;\n}\n"],"mappings":"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"}

package/dist/core/cart/attach-quantity-input.d.mts

@@ -1,15 +1,15 @@
 //#region src/core/cart/attach-quantity-input.d.ts
 /**
- * Attaches interactive quantity behavior to a DOM `<input>` inside a cart form.
+ * Submits a cart form when the customer changes the form's quantity input.
  *
- * When the input's value changes, the form is automatically submitted via the
- * first submit button (which must carry `name="intent" value="set"`). Returns
- * a cleanup function that removes the event listener.
+ * Make the form's first submit button the set button from `register("set")`. The function throws when the first submit button is any other button.
  *
- * The form must contain a `"set"` button as its first submit element — use
- * `register("set")` from `createCartFormRegister` to produce it.
+ * In React, register the quantity field with `interactive: true` in `useCartForm`, which calls the function for you. Call the function yourself in Vue and in frameworks without a binding.
  *
- * @throws If the form's first submit button is not a `name="intent" value="set"` button.
+ * @param inputEl The quantity input that submits the form on change.
+ * @param formEl The cart form that holds the input and the set button.
+ * @returns A function that stops the automatic submits. Call the function when you remove the input.
+ * @throws If the form's first submit button isn't the set button, which has `name="intent"` and `value="set"`.
  *
  * @example
  * ```ts
@@ -24,6 +24,7 @@
  *   detach();
  * }
  * ```
+ * @publicDocs
  */
 declare function attachQuantityInput(inputEl: HTMLInputElement, formEl: HTMLFormElement): () => void;
 //#endregion

package/dist/core/cart/attach-quantity-input.mjs

@@ -1,16 +1,16 @@
 //#region src/core/cart/attach-quantity-input.ts
 const FIRST_SUBMIT_BUTTON_SELECTOR = "button:not([type=button])";
 /**
-* Attaches interactive quantity behavior to a DOM `<input>` inside a cart form.
+* Submits a cart form when the customer changes the form's quantity input.
 *
-* When the input's value changes, the form is automatically submitted via the
-* first submit button (which must carry `name="intent" value="set"`). Returns
-* a cleanup function that removes the event listener.
+* Make the form's first submit button the set button from `register("set")`. The function throws when the first submit button is any other button.
 *
-* The form must contain a `"set"` button as its first submit element — use
-* `register("set")` from `createCartFormRegister` to produce it.
+* In React, register the quantity field with `interactive: true` in `useCartForm`, which calls the function for you. Call the function yourself in Vue and in frameworks without a binding.
 *
-* @throws If the form's first submit button is not a `name="intent" value="set"` button.
+* @param inputEl The quantity input that submits the form on change.
+* @param formEl The cart form that holds the input and the set button.
+* @returns A function that stops the automatic submits. Call the function when you remove the input.
+* @throws If the form's first submit button isn't the set button, which has `name="intent"` and `value="set"`.
 *
 * @example
 * ```ts
@@ -25,6 +25,7 @@ const FIRST_SUBMIT_BUTTON_SELECTOR = "button:not([type=button])";
 *   detach();
 * }
 * ```
+* @publicDocs
 */
 function attachQuantityInput(inputEl, formEl) {
 	const firstSubmitButton = formEl.querySelector(FIRST_SUBMIT_BUTTON_SELECTOR);

package/dist/core/cart/attach-quantity-input.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"attach-quantity-input.mjs","names":[],"sources":["../../../src/core/cart/attach-quantity-input.ts"],"sourcesContent":["const FIRST_SUBMIT_BUTTON_SELECTOR = \"button:not([type=button])\";\n\n/**\n * Attaches interactive quantity behavior to a DOM `<input>` inside a cart form.\n *\n * When the input's value changes, the form is automatically submitted via the\n * first submit button (which must carry `name=\"intent\" value=\"set\"`). Returns\n * a cleanup function that removes the event listener.\n *\n * The form must contain a `\"set\"` button as its first submit element — use\n * `register(\"set\")` from `createCartFormRegister` to produce it.\n *\n * @throws If the form's first submit button is not a `name=\"intent\" value=\"set\"` button.\n *\n * @example\n * ```ts\n * const input = document.querySelector<HTMLInputElement>('input[name=\"quantity\"]');\n * const form = input?.closest('form');\n *\n * if (input && form) {\n *   const detach = attachQuantityInput(input, form);\n *   // Input changes now auto-submit the form\n *\n *   // Clean up when unmounting\n *   detach();\n * }\n * ```\n */\nexport function attachQuantityInput(\n  inputEl: HTMLInputElement,\n  formEl: HTMLFormElement,\n): () => void {\n  const firstSubmitButton = formEl.querySelector(\n    FIRST_SUBMIT_BUTTON_SELECTOR,\n  ) as HTMLButtonElement | null;\n\n  if (\n    !firstSubmitButton ||\n    firstSubmitButton.name !== \"intent\" ||\n    firstSubmitButton.value !== \"set\"\n  ) {\n    throw new Error(\n      `The first button in cart form must have a name of \"intent\" and value of \"set\". Your UI will not behave as expected.`,\n      { cause: formEl },\n    );\n  }\n\n  const handleChange = (e: Event) => {\n    if (formEl.isConnected && e.target === inputEl) {\n      formEl.requestSubmit(firstSubmitButton);\n    }\n  };\n\n  inputEl.addEventListener(\"change\", handleChange);\n\n  return () => {\n    inputEl.removeEventListener(\"change\", handleChange);\n  };\n}\n"],"mappings":";AAAA,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BrC,SAAgB,oBACd,SACA,QACY;CACZ,MAAM,oBAAoB,OAAO,cAC/B,6BACD;AAED,KACE,CAAC,qBACD,kBAAkB,SAAS,YAC3B,kBAAkB,UAAU,MAE5B,OAAM,IAAI,MACR,uHACA,EAAE,OAAO,QAAQ,CAClB;CAGH,MAAM,gBAAgB,MAAa;AACjC,MAAI,OAAO,eAAe,EAAE,WAAW,QACrC,QAAO,cAAc,kBAAkB;;AAI3C,SAAQ,iBAAiB,UAAU,aAAa;AAEhD,cAAa;AACX,UAAQ,oBAAoB,UAAU,aAAa"}
+{"version":3,"file":"attach-quantity-input.mjs","names":[],"sources":["../../../src/core/cart/attach-quantity-input.ts"],"sourcesContent":["const FIRST_SUBMIT_BUTTON_SELECTOR = \"button:not([type=button])\";\n\n/**\n * Submits a cart form when the customer changes the form's quantity input.\n *\n * Make the form's first submit button the set button from `register(\"set\")`. The function throws when the first submit button is any other button.\n *\n * In React, register the quantity field with `interactive: true` in `useCartForm`, which calls the function for you. Call the function yourself in Vue and in frameworks without a binding.\n *\n * @param inputEl The quantity input that submits the form on change.\n * @param formEl The cart form that holds the input and the set button.\n * @returns A function that stops the automatic submits. Call the function when you remove the input.\n * @throws If the form's first submit button isn't the set button, which has `name=\"intent\"` and `value=\"set\"`.\n *\n * @example\n * ```ts\n * const input = document.querySelector<HTMLInputElement>('input[name=\"quantity\"]');\n * const form = input?.closest('form');\n *\n * if (input && form) {\n *   const detach = attachQuantityInput(input, form);\n *   // Input changes now auto-submit the form\n *\n *   // Clean up when unmounting\n *   detach();\n * }\n * ```\n * @publicDocs\n */\nexport function attachQuantityInput(\n  inputEl: HTMLInputElement,\n  formEl: HTMLFormElement,\n): () => void {\n  const firstSubmitButton = formEl.querySelector(\n    FIRST_SUBMIT_BUTTON_SELECTOR,\n  ) as HTMLButtonElement | null;\n\n  if (\n    !firstSubmitButton ||\n    firstSubmitButton.name !== \"intent\" ||\n    firstSubmitButton.value !== \"set\"\n  ) {\n    throw new Error(\n      `The first button in cart form must have a name of \"intent\" and value of \"set\". Your UI will not behave as expected.`,\n      { cause: formEl },\n    );\n  }\n\n  const handleChange = (e: Event) => {\n    if (formEl.isConnected && e.target === inputEl) {\n      formEl.requestSubmit(firstSubmitButton);\n    }\n  };\n\n  inputEl.addEventListener(\"change\", handleChange);\n\n  return () => {\n    inputEl.removeEventListener(\"change\", handleChange);\n  };\n}\n"],"mappings":";AAAA,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BrC,SAAgB,oBACd,SACA,QACY;CACZ,MAAM,oBAAoB,OAAO,cAC/B,6BACD;AAED,KACE,CAAC,qBACD,kBAAkB,SAAS,YAC3B,kBAAkB,UAAU,MAE5B,OAAM,IAAI,MACR,uHACA,EAAE,OAAO,QAAQ,CAClB;CAGH,MAAM,gBAAgB,MAAa;AACjC,MAAI,OAAO,eAAe,EAAE,WAAW,QACrC,QAAO,cAAc,kBAAkB;;AAI3C,SAAQ,iBAAiB,UAAU,aAAa;AAEhD,cAAa;AACX,UAAQ,oBAAoB,UAAU,aAAa"}

package/dist/core/cart/buyer-identity-sync.d.mts

@@ -1,20 +1,21 @@
 import { StorefrontClient } from "../../client/types.mjs";
 //#region src/core/cart/buyer-identity-sync.d.ts
 declare const cartBuyerIdentitySync: unique symbol;
+/** The request with the `cart` cookie and the Storefront API client that updates the cart. */
 type CartBuyerIdentitySyncContext = {
-  request: Request;
+  /** The incoming request. The `cart` cookie on the request identifies the cart. */request: Request; /** The Storefront API client that updates the cart's buyer identity. */
   storefrontClient: StorefrontClient;
 };
 /**
- * Capability attached by `createCartServerHandlers({customerSession})` and
- * consumed by `createCustomerAccountServerHandlers({cartServerHandlers})` to
- * keep the browser cart's buyer identity in step with the customer session.
+ * Connects the cart to the customer when the customer logs in, and disconnects the cart when the customer logs out.
+ *
+ * Create the cart server handlers with `customerSession`, then pass the handlers to `createCustomerAccountServerHandlers` through the `cartServerHandlers` option. The customer account handlers then update the cart for you.
  */
 type CartBuyerIdentitySync = {
-  /** Attaches (token) or detaches (null) the customer on the request's cart cookie. */updateBuyerIdentity(context: CartBuyerIdentitySyncContext, customerAccessToken: string | null): Promise<void>; /** Set-Cookie value that expires the cart cookie, for fail-safe logout cleanup. */
+  /** Attaches the customer to the cart in the request's `cart` cookie, or detaches the customer when the token is `null`. */updateBuyerIdentity(context: CartBuyerIdentitySyncContext, customerAccessToken: string | null): Promise<void>; /** A `Set-Cookie` value that clears the `cart` cookie. The customer account handlers send the value when they can't detach the customer from the cart. */
   readonly expiredCartCookie: string;
 };
-/** Cart server handlers capable of buyer identity sync. */
+/** Cart server handlers that you created with `customerSession`. */
 type CartBuyerIdentitySyncSource = {
   readonly [cartBuyerIdentitySync]: CartBuyerIdentitySync;
 };

package/dist/core/cart/buyer-identity-sync.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"buyer-identity-sync.mjs","names":[],"sources":["../../../src/core/cart/buyer-identity-sync.ts"],"sourcesContent":["import type { StorefrontClient } from \"../../client\";\n\n// Deliberately a tiny standalone module: customer-account handlers import it at\n// runtime, so it must not pull the cart handler graph into their bundle.\nexport const cartBuyerIdentitySync: unique symbol = Symbol(\"hydrogen.cartBuyerIdentitySync\");\n\nexport type CartBuyerIdentitySyncContext = {\n  request: Request;\n  storefrontClient: StorefrontClient;\n};\n\n/**\n * Capability attached by `createCartServerHandlers({customerSession})` and\n * consumed by `createCustomerAccountServerHandlers({cartServerHandlers})` to\n * keep the browser cart's buyer identity in step with the customer session.\n */\nexport type CartBuyerIdentitySync = {\n  /** Attaches (token) or detaches (null) the customer on the request's cart cookie. */\n  updateBuyerIdentity(\n    context: CartBuyerIdentitySyncContext,\n    customerAccessToken: string | null,\n  ): Promise<void>;\n  /** Set-Cookie value that expires the cart cookie, for fail-safe logout cleanup. */\n  readonly expiredCartCookie: string;\n};\n\n/** Cart server handlers capable of buyer identity sync. */\nexport type CartBuyerIdentitySyncSource = {\n  readonly [cartBuyerIdentitySync]: CartBuyerIdentitySync;\n};\n\n// Accepts a partial source because JavaScript callers can pass cart handlers\n// created without customerSession; the caller turns undefined into an error.\nexport function getCartBuyerIdentitySync(\n  source: Partial<CartBuyerIdentitySyncSource>,\n): CartBuyerIdentitySync | undefined {\n  return source[cartBuyerIdentitySync];\n}\n"],"mappings":";AAIA,MAAa,wBAAuC,OAAO,iCAAiC;AA6B5F,SAAgB,yBACd,QACmC;AACnC,QAAO,OAAO"}
+{"version":3,"file":"buyer-identity-sync.mjs","names":[],"sources":["../../../src/core/cart/buyer-identity-sync.ts"],"sourcesContent":["import type { StorefrontClient } from \"../../client\";\n\n// Deliberately a tiny standalone module: customer-account handlers import it at\n// runtime, so it must not pull the cart handler graph into their bundle.\nexport const cartBuyerIdentitySync: unique symbol = Symbol(\"hydrogen.cartBuyerIdentitySync\");\n\n/** The request with the `cart` cookie and the Storefront API client that updates the cart. */\nexport type CartBuyerIdentitySyncContext = {\n  /** The incoming request. The `cart` cookie on the request identifies the cart. */\n  request: Request;\n  /** The Storefront API client that updates the cart's buyer identity. */\n  storefrontClient: StorefrontClient;\n};\n\n/**\n * Connects the cart to the customer when the customer logs in, and disconnects the cart when the customer logs out.\n *\n * Create the cart server handlers with `customerSession`, then pass the handlers to `createCustomerAccountServerHandlers` through the `cartServerHandlers` option. The customer account handlers then update the cart for you.\n */\nexport type CartBuyerIdentitySync = {\n  /** Attaches the customer to the cart in the request's `cart` cookie, or detaches the customer when the token is `null`. */\n  updateBuyerIdentity(\n    context: CartBuyerIdentitySyncContext,\n    customerAccessToken: string | null,\n  ): Promise<void>;\n  /** A `Set-Cookie` value that clears the `cart` cookie. The customer account handlers send the value when they can't detach the customer from the cart. */\n  readonly expiredCartCookie: string;\n};\n\n/** Cart server handlers that you created with `customerSession`. */\nexport type CartBuyerIdentitySyncSource = {\n  readonly [cartBuyerIdentitySync]: CartBuyerIdentitySync;\n};\n\n// Accepts a partial source because JavaScript callers can pass cart handlers\n// created without customerSession; the caller turns undefined into an error.\nexport function getCartBuyerIdentitySync(\n  source: Partial<CartBuyerIdentitySyncSource>,\n): CartBuyerIdentitySync | undefined {\n  return source[cartBuyerIdentitySync];\n}\n"],"mappings":";AAIA,MAAa,wBAAuC,OAAO,iCAAiC;AAgC5F,SAAgB,yBACd,QACmC;AACnC,QAAO,OAAO"}

package/dist/core/cart/cart.d.mts

@@ -1,28 +1,32 @@
 import { CartData, CartState } from "./state.mjs";
 
 //#region src/core/cart/cart.d.ts
-/** Timeout (in milliseconds) for cart loads and mutations. */
+/** The timeout in milliseconds for cart loads and mutations. */
 declare const STANDARD_ACTION_TIMEOUT_IN_MS = 30000;
 /**
- * Error thrown when the cart endpoint responds with a non-2xx status.
+ * The error that a cart load or cart change throws when your cart endpoint responds with a non-2xx status. Read `status` to handle specific failures.
  *
- * Carries the HTTP {@link CartNetworkError.status | status} code so callers
- * can distinguish transient failures from permanent ones.
+ * Without a cart endpoint from `configureCartEndpoint`, cart requests fail with other error types.
+ *
+ * @publicDocs
  */
 declare class CartNetworkError extends Error {
+  /** The HTTP status code that the cart endpoint returned. */
   readonly status: number;
+  /** Always `CartNetworkError`. */
+  name: string;
+  /** Always `"Something went wrong updating your cart. Please try again."`, including for a failed cart load. */
+  message: string;
+  /** The stack trace, when the JavaScript runtime records one. */
+  stack?: string;
   constructor(status: number);
 }
 /**
- * A reactive, framework-agnostic cart state machine.
+ * Holds the customer's cart and runs cart changes in any framework. In React, `CartProvider` creates the store for you.
  *
- * The store manages optimistic mutations and server reconciliation — the client's
- * *intent*. Cart-level costs and totals are always server-authoritative, but
- * line-level data (quantity, estimated cost) and discount applicability are
- * projected optimistically until the server response arrives.
+ * The store shows line and discount code changes before the server responds, then updates the cart from each server response. Cart costs change only when the server responds.
  *
- * Mutations are dispatched via {@link CartStore.handleFormSubmit} (from HTML
- * forms) or through Shopify Standard Action `shopify:cart:*` events.
+ * Cart changes start from cart form submissions or from Standard Actions `shopify:cart:*` events. Cart changes need the Standard Actions script, which `ShopifyScripts` adds to the page. Cart loads and changes time out after 30 seconds.
  *
  * @example
  * ```ts
@@ -41,67 +45,71 @@ declare class CartNetworkError extends Error {
  */
 type CartStore = {
   /**
-   * Activates the store — starts listening for Shopify standard action events
-   * and triggers the initial cart load if no `initialData` was provided.
-   * Idempotent; no-op without `document` (SSR-safe).
+   * Starts handling cart events, and loads the cart when you created the store without initial data. Repeated calls have no effect. During server rendering, the method does nothing.
    */
-  connect(): void; /** Tears down the store — cancels in-flight requests, removes event listeners, releases resources. */
-  destroy(): void; /** Replaces the settled cart data with a fresh server response. */
-  hydrate(data: CartData): void; /** Returns the current {@link CartState}, with optimistic projections applied on top of settled data. */
+  connect(): void; /** Stops the store. Cancels in-flight cart requests and stops handling cart events. */
+  destroy(): void; /** Replaces the store's cart with a different cart that the server loaded. The method ignores data for the cart that the store already holds, and ignores data while cart changes are in flight. */
+  hydrate(data: CartData): void; /** Returns the current cart state, including changes that the server hasn't confirmed yet. */
   getState(): CartState;
   /**
-   * Registers a listener invoked on every state change. Returns an unsubscribe function.
-   * Compatible with React's `useSyncExternalStore`.
+   * Calls the listener on every state change and returns a function that removes the listener. The method works with React's `useSyncExternalStore`.
    *
-   * @param listener - Callback receiving the new {@link CartState} snapshot
+   * @param listener - The function that receives each new state.
+   */
+  subscribe(listener: (state: CartState) => void): () => void;
+  /**
+   * Loads the full cart from the server.
+   *
+   * The promise rejects when the load fails, with a `CartNetworkError` when your cart endpoint returns a non-2xx status.
    */
-  subscribe(listener: (state: CartState) => void): () => void; /** Triggers a full cart load from the server endpoint. */
   fetch(): Promise<void>;
   /**
-   * Reconciles the cart after an out-of-band mutation: revalidates the current
-   * cart, or loads one when none is present yet (e.g. just created server-side).
+   * Reloads the cart after a cart change that skipped the store, such as a server action. When the store has no cart yet, the method picks up the cart that the server created.
+   *
+   * A failed reload adds an entry to the network errors in the cart state.
    */
-  refresh(): void; /** Resets the store — aborts in-flight requests, clears data and errors, and re-fetches when connected. */
+  refresh(): void; /** Clears the cart data and errors and cancels in-flight cart requests. After you connect the store, the method also loads the cart again when the store held a cart. */
   reset(): void;
   /**
-   * Intercepts a native `SubmitEvent` from a cart form, parses the intent and
-   * field values, and dispatches the matching transaction.
+   * Runs the cart change that a cart form submission describes. Pass the form's submit event, and call `event.preventDefault()` to stop the browser's own form submission. The method connects the store when you haven't connected it.
    *
-   * The submitter's `value` attribute determines the action — `"add"`,
-   * `"increase"`, `"decrease"`, `"remove"`, `"set"`, `"discount-apply"`,
-   * `"discount-remove"`, `"note-update"`, or `"attributes-update"`. An empty
-   * value with a `merchandiseId` field is treated as `"add"`.
+   * The submit button's value sets the change: `add`, `increase`,
+   * `decrease`, `remove`, `set`, `discount-apply`, `discount-remove`,
+   * `note-update`, or `attributes-update`. A button without a value adds
+   * the line when the form has a `merchandiseId` field. A `set` with an empty or
+   * zero quantity removes the line. When your cart fragment selects the variant's
+   * available quantity, the store caps a `set` quantity at that number.
    *
-   * The returned promise rejects with a `TypeError` if `event.target` is not
-   * a form or `event.submitter` is missing, and with an `Error` if the
-   * submitter's value is not a recognized intent.
+   * The promise rejects with a type error when the event target isn't a form or
+   * the event has no submitter. The promise rejects with an error when the button's
+   * value isn't a recognized change, or when the form lacks a required field
+   * such as the line ID.
    */
   handleFormSubmit(event: SubmitEvent, eventDetail?: Record<string, unknown>): Promise<void>;
 };
-/** Actions for reconciling cart state after updates outside Standard Actions. */
+/** The store action that reloads the cart after a cart change outside the store. */
 type CartActions = Pick<CartStore, "refresh">;
+/** The cart that the server loaded for the first render. */
 type CartInitialData<TData extends CartData = CartData> = {
-  cart: TData | null;
+  /** The loaded cart, or `null` when the server found no cart. */cart: TData | null; /** Load errors from the server. The store ignores the errors. */
   errors?: Array<{
     message: string;
   }>;
 };
-/** Options for {@link createCartStore}. */
+/** Options for creating a cart store. */
 type CreateCartStoreOptions<TData extends CartData = CartData> = {
   /**
-   * Server-loaded cart data to hydrate the store with on creation.
+   * The cart that the server loaded, or a promise of the cart for streamed data.
    *
-   * Accepts a synchronous value or a `PromiseLike` for streamed/deferred data.
-   * When omitted, the store starts empty and loads the cart on {@link CartStore.connect}.
+   * Pass the `data` property of the cart GET handler's result. A `null` cart
+   * tells the store that no cart exists yet. Without initial data, the store starts empty and loads the cart when you call `connect()`.
    */
   initialData?: CartInitialData<TData> | PromiseLike<CartInitialData<TData>>;
 };
 /**
- * Creates a new {@link CartStore} for the given initial data.
+ * Creates a cart store that holds the cart and applies cart changes before the server responds.
  *
- * The store is inert until {@link CartStore.connect} is called — no network
- * requests are made and no event listeners are attached at creation time.
- * Framework adapters call `connect()` on mount and `destroy()` on unmount.
+ * Call `connect()` to start the store and `destroy()` to stop it. The React and Vue cart providers call both for you.
  *
  * @example
  * ```ts
@@ -118,18 +126,23 @@ type CreateCartStoreOptions<TData extends CartData = CartData> = {
  * // Empty — loads the cart on connect()
  * const store = createCartStore();
  * ```
+ * @param options The cart that the server loaded for the first render.
+ * @returns The cart store. Read the cart with `getState()` and listen for changes with `subscribe()`.
+ * @publicDocs
  */
 declare function createCartStore<TData extends CartData = CartData>(options?: CreateCartStoreOptions<TData>): CartStore;
 /**
- * Routes cart loads and mutations to a custom endpoint instead of the
- * Standard Actions default handler.
+ * Sends every cart load and cart change on the page to your cart endpoint. Without an endpoint, Standard Actions handles cart requests with its default handler.
  *
- * Logs a warning if called again with a different endpoint.
+ * Call the function before you connect a cart store. The first cart load then goes to your endpoint. A later call with a different endpoint replaces the first endpoint and logs a warning. In React, `CartProvider` sets the endpoint to `/api/cart` when the provider mounts.
  *
+ * @param endpoint The URL path of your cart route.
+ * @returns Nothing. Later cart loads and changes on the page go to the endpoint.
  * @example
  * ```ts
  * configureCartEndpoint("/storefront/cart");
  * ```
+ * @publicDocs
  */
 declare function configureCartEndpoint(endpoint: string): void;
 //#endregion