@asteby/storefront 0.16.1 → 0.18.0

package/dist/index.cjs

@@ -124,9 +124,14 @@ function appendParams(search, params) {
   return search;
 }
 function productListQuery(params = {}) {
-  const { filters, handles, ...rest } = params;
+  const { filters, handles, tags_any, ...rest } = params;
   const search = appendParams(new URLSearchParams(), rest);
   if (handles && handles.length > 0) search.set("handles", handles.join(","));
+  if (tags_any && tags_any.length > 0) {
+    if (tags_any.length > 5) throw new RangeError("tags_any takes at most 5 tags");
+    if (tags_any.some((t) => t.includes(",") || t.length > 120)) throw new TypeError("tags_any: a tag has at most 120 characters and no comma");
+    search.set("tags_any", tags_any.join(","));
+  }
   if (filters) {
     for (const [key, raw] of Object.entries(filters)) {
       const name = key.startsWith("filter.") ? key : `filter.${key}`;
@@ -486,6 +491,43 @@ function createStorefrontClient(config) {
       get: (options) => get("/storefront/customer", void 0, options),
       /** Updates the profile and the saved fiscal data; `fiscal: null` deletes the latter. `422` with `field: 'fiscal.<field>'`. */
       update: (input, options) => write("PATCH", "/storefront/customer", input, options),
+      /**
+       * Active sessions of the buyer («Devices»; contract 1.9). Private, never cached. The list carries no address
+       * and no token: only what the buyer needs to recognize their own devices.
+       */
+      sessions: {
+        list: async (options) => (await get("/storefront/customer/sessions", void 0, { ...options, cache: "no-store" })).nodes,
+        /** Closes one session. Repeating it is fine. `404` for a session that is not the buyer's. Closing the current one is a sign-out. */
+        revoke: (id, options) => write("DELETE", `/storefront/customer/sessions/${enc(id)}`, void 0, options),
+        /** Closes every session except the one making the call. */
+        revokeOthers: (options) => write("DELETE", "/storefront/customer/sessions/others", void 0, options)
+      },
+      /**
+       * Confirms the buyer's identity again with their password or a sign-in code (`requestOtp` first). The
+       * confirmation lasts `valid_for_seconds` (a few minutes) and counts only for the session that made the call;
+       * exporting data and deleting the account need it (`403 reauth_required` otherwise, see `isReauthRequired`).
+       * A wrong credential is always the same `400`; too many tries is `429` (`StorefrontError.retryAfter`).
+       */
+      reauth: (input, options) => write("POST", "/storefront/customer/reauth", input, options),
+      /**
+       * The buyer's data as a JSON file (contract 1.9, `capabilities().data_export`). Needs a recent `reauth`. It is
+       * built on request and is neither stored nor emailed: call it from YOUR server, stream the bytes
+       * (`dataExportBytes`, `safeExportFilename`) with `Cache-Control: no-store`, and keep nothing. Three a day per account.
+       */
+      exportData: async (options) => {
+        const file = await write("POST", "/storefront/customer/data-export", void 0, { ...options, cache: "no-store" });
+        if (!file || typeof file.content_base64 !== "string" || typeof file.filename !== "string" || typeof file.content_type !== "string") {
+          throw new StorefrontError({ status: 502, code: "invalid_response", message: "The data export answer is not a file" });
+        }
+        return { filename: file.filename, content_type: file.content_type, content_base64: file.content_base64 };
+      },
+      /**
+       * Deletes the buyer's account (contract 1.9, `capabilities().account_delete`). Needs a recent `reauth` and the
+       * text the buyer typed in `confirm`. Personal data is erased; orders and invoices are kept by the store.
+       * `409` (see `isAccountDeleteBlocked`) while an order is on its way or a payment is pending. Idempotent: a
+       * repeat after success is also fine. Afterwards the token is dead: drop it.
+       */
+      deleteAccount: (input, options) => write("DELETE", "/storefront/customer", input, options),
       orders: (params, options) => get("/storefront/customer/orders", params, options),
       /** `null` when the order does not exist or belongs to someone else. */
       order: (id, options) => getOrNull(`/storefront/customer/orders/${enc(id)}`, void 0, options),
@@ -536,6 +578,19 @@ function createStorefrontClient(config) {
         /** Physical delete (a profile leaves nothing behind). A saved default passes to another profile. */
         delete: (id, options) => write("DELETE", `/storefront/customer/fiscal-profiles/${enc(id)}`, void 0, options)
       },
+      /**
+       * Saved items of the buyer («My items», «My garage»; contract 1.9, `capabilities().subjects`). Personal data:
+       * private, never cached, never logged. `422` with `field: 'attributes.<field>'` when the kind refuses a value
+       * (it never echoes it); `409` for an item already saved or past the limit; `429` for too many saves; `404` for
+       * an item that is not the buyer's. The server builds `label` and `fit_key`; private fields come back masked.
+       */
+      subjects: {
+        list: async (params, options) => (await get("/storefront/customer/subjects", params, { ...options, cache: "no-store" })).nodes,
+        create: (input, options) => write("POST", "/storefront/customer/subjects", input, options),
+        update: (id, patch, options) => write("PATCH", `/storefront/customer/subjects/${enc(id)}`, patch, options),
+        /** Physical delete (the item leaves nothing behind). The default of its kind passes to another item. */
+        delete: (id, options) => write("DELETE", `/storefront/customer/subjects/${enc(id)}`, void 0, options)
+      },
       addresses: {
         list: (options) => get("/storefront/customer/addresses", void 0, options),
         create: (address, options) => write("POST", "/storefront/customer/addresses", address, options),
@@ -544,6 +599,11 @@ function createStorefrontClient(config) {
       }
     },
     content: {
+      /**
+       * The kinds of buyer item the organization declares («My garage») and their catalogs (contract 1.9; public,
+       * cacheable). `[]` when it declares none or the server predates the route: the store has no such section.
+       */
+      subjectKinds: async (options) => (await getOrNull("/storefront/subject-kinds", void 0, options))?.nodes ?? [],
       theme: (options) => get("/storefront/content/theme", void 0, options),
       /** `null` when the page does not exist. */
       page: (handle, options) => getOrNull(`/storefront/content/pages/${enc(handle)}`, previewQuery(options), options),
@@ -1451,6 +1511,29 @@ function shipmentsStatus(order) {
   return live.length ? live[0].status : null;
 }
 
+// src/account-settings.ts
+function isReauthRequired(error) {
+  const e = error;
+  return !!e && typeof e === "object" && e.status === 403 && e.code === "reauth_required";
+}
+function isAccountDeleteBlocked(error) {
+  const e = error;
+  return !!e && typeof e === "object" && e.status === 409 && (e.field === "orders" || e.field === "pending_payments");
+}
+function dataExportBytes(file) {
+  const raw = typeof file.content_base64 === "string" ? file.content_base64.replace(/\s+/g, "") : "";
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(raw) || raw.length % 4 === 1) throw new TypeError("data export is not valid base64");
+  const bin = atob(raw);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function safeExportFilename(name, fallback = "account-data.json") {
+  const base = typeof name === "string" ? name.split(/[\\/]/).pop() ?? "" : "";
+  const clean = base.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^\.+/, "").slice(0, 80);
+  return clean || fallback;
+}
+
 // src/invoice-docs.ts
 function groupInvoiceDocs(docs) {
   const list = Array.isArray(docs) ? docs.filter((d) => !!d && typeof d === "object") : [];
@@ -1478,6 +1561,199 @@ function safeInvoiceFilename(name, fallback = "factura") {
   return clean || fallback;
 }
 
+// src/subjects.ts
+var MIN_SUBJECT_YEAR = 1900;
+var MAX_SUBJECT_YEAR = 2100;
+var MAX_VALUE_LENGTH = 80;
+var MAX_LABEL_LENGTH = 120;
+var MAX_FIT_KEY_LENGTH = 100;
+var isPresent = (v) => v !== null && v !== void 0 && v !== "";
+var asYear = (v) => {
+  const n = typeof v === "number" ? v : typeof v === "string" && /^\s*\d+\s*$/.test(v) ? Number(v) : NaN;
+  return Number.isInteger(n) && n >= MIN_SUBJECT_YEAR && n <= MAX_SUBJECT_YEAR ? n : null;
+};
+var cleanText = (v, max) => {
+  if (typeof v !== "string") return null;
+  const s = v.split(/\s+/).filter(Boolean).join(" ");
+  return [...s].length > max || /[\u0000-\u001f\u007f-\u009f]/.test(s) ? null : s;
+};
+var slug = (s) => s.toLowerCase().replace(/[^a-z0-9._+-]+/g, "-").replace(/^-+|-+$/g, "");
+function coversYear(node, year) {
+  if (node.ranges && node.ranges.length > 0) return node.ranges.some(([a, b]) => year >= a && year <= b);
+  if (node.from !== void 0 && year < node.from) return false;
+  if (node.to !== void 0 && year > node.to) return false;
+  return true;
+}
+var declaresYears = (n) => n.from !== void 0 || n.to !== void 0 || (n.ranges?.length ?? 0) > 0;
+function subjectLevels(kind) {
+  return kind.fields.filter((f) => f.source === "catalog" && f.type !== "year");
+}
+function subjectFields(kind) {
+  return kind.fields;
+}
+function walk(kind, values) {
+  const path = [];
+  const ids = {};
+  let tree = kind.catalog?.tree;
+  for (const f of subjectLevels(kind)) {
+    const raw = values[f.key];
+    const s = isPresent(raw) ? cleanText(raw, MAX_VALUE_LENGTH) : null;
+    const node = s && tree ? tree[s] ?? tree[s.toLowerCase()] : void 0;
+    if (!s || !node) return { path, ids, next: tree };
+    ids[f.key] = tree && tree[s] ? s : s.toLowerCase();
+    path.push(node);
+    tree = node.children;
+    if (!tree) return { path, ids, next: void 0 };
+  }
+  return { path, ids, next: tree };
+}
+var byLabel = (a, b) => a.label.localeCompare(b.label, void 0, { sensitivity: "base", numeric: true });
+function subjectOptions(kind, fieldKey, values) {
+  const field = kind.fields.find((f) => f.key === fieldKey);
+  if (!field || field.source !== "catalog" || !kind.catalog) return [];
+  if (field.type === "year") {
+    const upto = kind.fields.slice(0, kind.fields.indexOf(field));
+    const { path: path2 } = walk({ ...kind, fields: upto }, values);
+    const declared = path2.filter(declaresYears);
+    if (declared.length === 0) return [];
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const n of declared) {
+      for (const [a, b] of n.ranges?.length ? n.ranges : [[n.from ?? MIN_SUBJECT_YEAR, n.to ?? MAX_SUBJECT_YEAR]]) {
+        lo = Math.min(lo, a);
+        hi = Math.max(hi, b);
+      }
+    }
+    const out = [];
+    for (let y = Math.min(hi, MAX_SUBJECT_YEAR); y >= Math.max(lo, MIN_SUBJECT_YEAR); y--) if (declared.every((n) => coversYear(n, y))) out.push({ value: String(y), label: String(y) });
+    return out;
+  }
+  const levels = subjectLevels(kind);
+  const at = levels.findIndex((f) => f.key === fieldKey);
+  if (at < 0) return [];
+  const before = Object.fromEntries(levels.slice(0, at).map((f) => [f.key, values[f.key]]));
+  const { path, next } = walk({ ...kind, fields: kind.fields.filter((f) => levels.slice(0, at).includes(f) || f.type === "year") }, before);
+  if (path.length < at || !next) return [];
+  const year = asYear(values[kind.fields.find((f) => f.type === "year" && f.source === "catalog")?.key ?? ""]);
+  return Object.entries(next).filter(([, n]) => year === null || coversYear(n, year)).map(([value, n]) => ({ value, label: n.label })).sort(byLabel);
+}
+function reconcileSubjectValues(kind, values) {
+  const out = { ...values };
+  for (const f of kind.fields) {
+    if (f.source !== "catalog" || !isPresent(out[f.key])) continue;
+    const options = subjectOptions(kind, f.key, out);
+    const v = String(out[f.key]);
+    const ok = f.type === "year" ? options.length === 0 || options.some((o) => o.value === v) : options.some((o) => o.value === v || o.value === v.toLowerCase());
+    if (!ok) out[f.key] = "";
+  }
+  return out;
+}
+function resolveSubject(kind, values) {
+  const problems = {};
+  const known = new Set(kind.fields.map((f) => f.key));
+  for (const key2 of Object.keys(values)) if (isPresent(values[key2]) && !known.has(key2)) problems[key2] = "unknown";
+  const attributes = {};
+  const priv = {};
+  const display = {};
+  const ids = {};
+  const path = [];
+  let tree = kind.catalog?.tree;
+  const years = [];
+  const put = (f, v) => {
+    if (f.private) priv[f.key] = String(v);
+    else attributes[f.key] = v;
+  };
+  for (const f of kind.fields) {
+    const raw = values[f.key];
+    if (!isPresent(raw)) {
+      if (f.required) problems[f.key] = "required";
+      if (f.source === "catalog" && f.type !== "year") tree = void 0;
+      continue;
+    }
+    const max = f.max ?? MAX_VALUE_LENGTH;
+    if (f.type === "year") {
+      const y = asYear(raw);
+      if (y === null) {
+        problems[f.key] = "invalid";
+        continue;
+      }
+      put(f, y);
+      display[f.key] = ids[f.key] = String(y);
+      if (f.source === "catalog") years.push(f.key);
+    } else if (f.source === "catalog") {
+      if (!kind.catalog) {
+        problems[f.key] = "catalog_unavailable";
+        continue;
+      }
+      const s = cleanText(raw, max);
+      if (s === null) {
+        problems[f.key] = "invalid";
+        continue;
+      }
+      const node = tree?.[s] ?? tree?.[s.toLowerCase()];
+      if (!node) {
+        problems[f.key] = "not_in_catalog";
+        continue;
+      }
+      const id = tree?.[s] ? s : s.toLowerCase();
+      path.push(node);
+      tree = node.children;
+      put(f, id);
+      display[f.key] = node.label;
+      ids[f.key] = id;
+    } else {
+      const s = cleanText(raw, max);
+      if (s === null) {
+        problems[f.key] = "invalid";
+        continue;
+      }
+      put(f, s);
+      display[f.key] = s;
+      ids[f.key] = slug(s);
+    }
+  }
+  for (const key2 of years) {
+    const y = attributes[key2];
+    if (y !== void 0 && !problems[key2] && !path.every((n) => coversYear(n, y))) problems[key2] = "year_range";
+  }
+  if (Object.keys(problems).length > 0) return { ok: false, problems };
+  const label = [...kind.fields.filter((f) => !f.private).map((f) => display[f.key]).filter(Boolean).join(" ")].slice(0, MAX_LABEL_LENGTH).join("").trim();
+  if (!label) return { ok: false, problems: { _: "required" } };
+  let complete = true;
+  const key = kind.fit_key_template.replace(/\{([a-z][a-z0-9_]*)\}/g, (_m, name) => {
+    const id = ids[name];
+    if (!id) complete = false;
+    return id ?? "";
+  });
+  return { ok: true, subject: { label, fit_key: complete && key.length <= MAX_FIT_KEY_LENGTH ? key.toLowerCase() : "", attributes, private: priv } };
+}
+var PRIVATE_MASK = "\u2022\u2022";
+var isMasked = (v) => typeof v === "string" && v.startsWith(PRIVATE_MASK);
+var DEFAULT_FIT_TAG_PREFIX = "fit:";
+var fitTag = (fitKey, prefix = DEFAULT_FIT_TAG_PREFIX) => `${prefix}${fitKey}`;
+function fitTagsAny(fitKey, opts = {}) {
+  if (!fitKey) return [];
+  const prefix = opts.prefix ?? DEFAULT_FIT_TAG_PREFIX;
+  return opts.universal === false ? [fitTag(fitKey, prefix)] : [fitTag(fitKey, prefix), `${prefix}universal`];
+}
+var SUBJECT_CATALOG_PAGE_BYTES = 28 * 1024;
+var utf8Bytes = (s) => new TextEncoder().encode(s).length;
+function splitSubjectTree(tree, maxBytes = SUBJECT_CATALOG_PAGE_BYTES) {
+  const size = (part) => utf8Bytes(JSON.stringify(JSON.stringify(part)));
+  const parts = [];
+  let current = {};
+  for (const [id, node] of Object.entries(tree)) {
+    if (size({ [id]: node }) > maxBytes) throw new RangeError(`splitSubjectTree: option ${id} alone exceeds ${maxBytes} bytes`);
+    const next = { ...current, [id]: node };
+    if (Object.keys(current).length > 0 && size(next) > maxBytes) {
+      parts.push(current);
+      current = { [id]: node };
+    } else current = next;
+  }
+  if (Object.keys(current).length > 0) parts.push(current);
+  return parts;
+}
+
 // src/delivery.ts
 function parseDelivery(value) {
   const raw = (value ?? "").trim();
@@ -1506,11 +1782,16 @@ function deliveryNotices(delivery) {
 
 exports.CLIENT_IP_HEADER = CLIENT_IP_HEADER;
 exports.COUNTRY_HEADERS = COUNTRY_HEADERS;
+exports.DEFAULT_FIT_TAG_PREFIX = DEFAULT_FIT_TAG_PREFIX;
+exports.MAX_SUBJECT_YEAR = MAX_SUBJECT_YEAR;
+exports.MIN_SUBJECT_YEAR = MIN_SUBJECT_YEAR;
 exports.MISSING_WEIGHT = MISSING_WEIGHT;
 exports.NOTE_MAX_LENGTH = NOTE_MAX_LENGTH;
 exports.PAYMENT_CHOICE_REFUSED_FIELD = PAYMENT_CHOICE_REFUSED_FIELD;
 exports.PICKUP_STEPS = PICKUP_STEPS;
+exports.PRIVATE_MASK = PRIVATE_MASK;
 exports.SHIPPING_STEPS = SHIPPING_STEPS;
+exports.SUBJECT_CATALOG_PAGE_BYTES = SUBJECT_CATALOG_PAGE_BYTES;
 exports.StorefrontError = StorefrontError;
 exports.appendParams = appendParams;
 exports.availabilityLocale = availabilityLocale;
@@ -1519,12 +1800,16 @@ exports.availabilityView = availabilityView;
 exports.cartLineProblemView = cartLineProblemView;
 exports.clampPercent = clampPercent;
 exports.classifyPaymentError = classifyPaymentError;
+exports.coversYear = coversYear;
 exports.createStorefrontClient = createStorefrontClient;
+exports.dataExportBytes = dataExportBytes;
 exports.declineMessage = declineMessage;
 exports.declineMessageKey = declineMessageKey;
 exports.deliveryInput = deliveryInput;
 exports.deliveryNotices = deliveryNotices;
 exports.diagnose = diagnose;
+exports.fitTag = fitTag;
+exports.fitTagsAny = fitTagsAny;
 exports.formatAvailabilityMessage = formatAvailabilityMessage;
 exports.formatMoney = formatMoney;
 exports.formatVoucherExpiry = formatVoucherExpiry;
@@ -1532,6 +1817,9 @@ exports.generateIdempotencyKey = generateIdempotencyKey;
 exports.groupInvoiceDocs = groupInvoiceDocs;
 exports.hreflangLinks = hreflangLinks;
 exports.invoiceFileBytes = invoiceFileBytes;
+exports.isAccountDeleteBlocked = isAccountDeleteBlocked;
+exports.isMasked = isMasked;
+exports.isReauthRequired = isReauthRequired;
 exports.isStorefrontError = isStorefrontError;
 exports.isTestInvoice = isTestInvoice;
 exports.isTestShipment = isTestShipment;
@@ -1556,16 +1844,23 @@ exports.productAvailability = productAvailability;
 exports.productListQuery = productListQuery;
 exports.promoProgressView = promoProgressView;
 exports.promotionMessages = promotionMessages;
+exports.reconcileSubjectValues = reconcileSubjectValues;
 exports.repairPath = repairPath;
 exports.resolveAvailability = resolveAvailability;
+exports.resolveSubject = resolveSubject;
 exports.rewardLabel = rewardLabel;
+exports.safeExportFilename = safeExportFilename;
 exports.safeHttpsUrl = safeHttpsUrl;
 exports.safeInvoiceFilename = safeInvoiceFilename;
 exports.safeTrackingUrl = safeTrackingUrl;
 exports.schemaAvailability = schemaAvailability;
 exports.shipmentsStatus = shipmentsStatus;
 exports.sortTrackingEvents = sortTrackingEvents;
+exports.splitSubjectTree = splitSubjectTree;
 exports.storefrontDomainHeader = storefrontDomainHeader;
+exports.subjectFields = subjectFields;
+exports.subjectLevels = subjectLevels;
+exports.subjectOptions = subjectOptions;
 exports.suggestMarket = suggestMarket;
 exports.toMoney = toMoney;
 exports.visitorCountry = visitorCountry;