@aglyn/plugins-commerce 1.0.0-beta.199 → 1.0.0-beta.201

package/src/lib/model/order-list-fields.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type OrderDisputeTone } from './commerce-dispute';
+import { type HostOrder, type OrderChannel, type OrderDispute, type OrderStatus } from './commerce-orders';
+/** Tokens past this many are dropped from the quick search's array. */
+export declare const ORDER_SEARCH_TOKEN_LIMIT = 200;
+/** The fields the orders list's query reads, as every writer stamps them. */
+export interface OrderListFields {
+    /**
+     * Always present. A Commerce Starter order (AGL-90) carried none and was
+     * read as `paid` (`liftLegacyOrder`); the lift is written down so the
+     * Status filter finds it.
+     */
+    status: OrderStatus;
+    /** Always present; absent was always read as `online`. */
+    channel: OrderChannel;
+    /**
+     * Every product the order holds, line items first and the legacy flat
+     * `productId` after — the Product filter's `array-contains-any`.
+     */
+    productIds: string[];
+    /**
+     * The dispute badge's tone (`describeOrderDispute`), or null with no
+     * dispute. `open` is a case with a deadline; `lost` a chargeback; `won` and
+     * `settled` closed with no money reversed. What the Disputes filter and the
+     * open-dispute banner ask.
+     */
+    disputeKey: OrderDisputeTone | null;
+    /** The buyer's address, lower-cased — the Customer filter's `equals`. */
+    customerEmailLower: string | null;
+    /** The address's search prefixes (`emailSearchTokens`) — its `contains`. */
+    customerEmailTokens: string[];
+    /** The order number's prefixes, with and without its `#` — Order `contains`. */
+    orderLabelTokens: string[];
+    /**
+     * The quick search: the order number's, the buyer's address's and every
+     * line item name's word prefixes, capped at {@link ORDER_SEARCH_TOKEN_LIMIT}
+     * with the item names cut first.
+     */
+    searchTokens: string[];
+}
+/** The dispute badge's tone, stored — see {@link OrderListFields.disputeKey}. */
+export declare function orderDisputeKey(dispute: OrderDispute | null | undefined): OrderDisputeTone | null;
+/**
+ * The order number's prefixes, as `#1042` and as `1042`, so a reader who
+ * types either finds it. An order with no number is labelled by its document
+ * id (`formatOrderNumber`), and is found by that label the same way.
+ */
+export declare function orderLabelTokens(order: Pick<Partial<HostOrder>, 'number'>, docId: string): string[];
+/**
+ * The fields the orders list's query reads, from an order as it will be
+ * stored — see {@link OrderListFields}. Pure: the same answer on the server,
+ * in a spec and (restated) in the backfill.
+ *
+ * `legacyProductName` names the product of a Commerce Starter order, which
+ * stored an id and no line items; only the backfill has it to give.
+ */
+export declare function orderListFields(order: object, docId: string, options?: {
+    legacyProductName?: string;
+}): OrderListFields;
+/**
+ * An order document with its list fields spread over it — what a creator
+ * writes. The document's own `status` and `channel` win where it names them,
+ * which every creator does; the rest is derived from it.
+ */
+export declare function withOrderListFields<T extends object>(docId: string, doc: T): T & OrderListFields;

package/src/lib/model/order-list-fields.js

@@ -0,0 +1,112 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { emailSearchTokens } from "@aglyn/aglyn/app-utils/email-search";
+import { nameSearchKey, nameSearchTokens } from "@aglyn/aglyn/app-utils/name-search";
+import { describeOrderDispute } from "./commerce-dispute.js";
+import { formatOrderNumber } from "./commerce-orders.js";
+/*
+ * WHAT THE ORDERS LIST ASKS ITS QUERY, WRITTEN ON THE ORDER (AGL-3321).
+ *
+ * The orders list puts every filter and its search on the Firestore query,
+ * and a query can only ask about a field a document stores. The list used to
+ * derive five of its columns in the browser — a legacy order's status and
+ * channel, the products in a cart, the dispute badge, the order number — and
+ * match them over the two hundred rows it had read, which answered "none"
+ * for an order on the next page.
+ *
+ * So every writer of `hosts/{hostId}/orders` spreads `orderListFields` over
+ * the document it writes, computed from the whole document as it will stand:
+ * the creators (cart, buy-now, subscription renewal, POS, draft) and every
+ * write that moves an input — the dispute record, the address a paid draft
+ * learns. A write that moves none of them (a status flip, a fulfillment, a
+ * refund, a timeline note) moves none of these either: `status` is its own
+ * field and is what the Status filter reads.
+ *
+ * `tools/scripts/backfill-orders-list-fields.mjs` restates this for the
+ * orders written before it; the two answer the same worked examples,
+ * `tools/scripts/lib/order-list-fields.fixtures.json`.
+ */ /** Tokens past this many are dropped from the quick search's array. */ export const ORDER_SEARCH_TOKEN_LIMIT = 200;
+/** The dispute badge's tone, stored — see {@link OrderListFields.disputeKey}. */ export function orderDisputeKey(dispute) {
+    var _ref;
+    var _describeOrderDispute;
+    if (!dispute || typeof dispute !== 'object') return null;
+    return (_ref = (_describeOrderDispute = describeOrderDispute({
+        dispute
+    })) == null ? void 0 : _describeOrderDispute.tone) != null ? _ref : null;
+}
+/**
+ * The order number's prefixes, as `#1042` and as `1042`, so a reader who
+ * types either finds it. An order with no number is labelled by its document
+ * id (`formatOrderNumber`), and is found by that label the same way.
+ */ export function orderLabelTokens(order, docId) {
+    const label = nameSearchKey(formatOrderNumber({
+        number: order.number
+    }, docId));
+    const bare = label.replace(/^#+/, '');
+    return nameSearchTokens(bare && bare !== label ? `${label} ${bare}` : label);
+}
+const text = (value)=>typeof value === 'string' ? value : '';
+/**
+ * The fields the orders list's query reads, from an order as it will be
+ * stored — see {@link OrderListFields}. Pure: the same answer on the server,
+ * in a spec and (restated) in the backfill.
+ *
+ * `legacyProductName` names the product of a Commerce Starter order, which
+ * stored an id and no line items; only the backfill has it to give.
+ */ export function orderListFields(order, docId, options = {}) {
+    const source = order;
+    const lineItems = Array.isArray(source.lineItems) ? source.lineItems : [];
+    const productIds = [
+        ...new Set([
+            ...lineItems.map((line)=>line == null ? void 0 : line.productId),
+            source.productId
+        ].filter((id)=>typeof id === 'string' && id !== ''))
+    ];
+    const email = text(source.customerEmail);
+    const emailTokens = emailSearchTokens(email);
+    const labelTokens = orderLabelTokens(source, docId);
+    const names = lineItems.map((line)=>text(line == null ? void 0 : line.name)).filter(Boolean);
+    if (!names.length && options.legacyProductName) {
+        names.push(options.legacyProductName);
+    }
+    const searchTokens = [
+        ...new Set([
+            ...labelTokens,
+            ...emailTokens,
+            ...names.flatMap((name)=>nameSearchTokens(name))
+        ])
+    ].slice(0, ORDER_SEARCH_TOKEN_LIMIT);
+    return {
+        status: text(source.status) || 'paid',
+        channel: text(source.channel) || 'online',
+        productIds,
+        disputeKey: orderDisputeKey(source.dispute),
+        customerEmailLower: nameSearchKey(email) || null,
+        customerEmailTokens: emailTokens,
+        orderLabelTokens: labelTokens,
+        searchTokens
+    };
+}
+/**
+ * An order document with its list fields spread over it — what a creator
+ * writes. The document's own `status` and `channel` win where it names them,
+ * which every creator does; the rest is derived from it.
+ */ export function withOrderListFields(docId, doc) {
+    return _extends({}, doc, orderListFields(doc, docId));
+}
+
+//# sourceMappingURL=order-list-fields.js.map

package/src/lib/model/order-list-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/order-list-fields.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { emailSearchTokens } from '@aglyn/aglyn/app-utils/email-search'\nimport {\n  nameSearchKey,\n  nameSearchTokens,\n} from '@aglyn/aglyn/app-utils/name-search'\nimport { describeOrderDispute, type OrderDisputeTone } from './commerce-dispute'\nimport {\n  formatOrderNumber,\n  type HostOrder,\n  type OrderChannel,\n  type OrderDispute,\n  type OrderStatus,\n} from './commerce-orders'\n\n/*\n * WHAT THE ORDERS LIST ASKS ITS QUERY, WRITTEN ON THE ORDER (AGL-3321).\n *\n * The orders list puts every filter and its search on the Firestore query,\n * and a query can only ask about a field a document stores. The list used to\n * derive five of its columns in the browser — a legacy order's status and\n * channel, the products in a cart, the dispute badge, the order number — and\n * match them over the two hundred rows it had read, which answered \"none\"\n * for an order on the next page.\n *\n * So every writer of `hosts/{hostId}/orders` spreads `orderListFields` over\n * the document it writes, computed from the whole document as it will stand:\n * the creators (cart, buy-now, subscription renewal, POS, draft) and every\n * write that moves an input — the dispute record, the address a paid draft\n * learns. A write that moves none of them (a status flip, a fulfillment, a\n * refund, a timeline note) moves none of these either: `status` is its own\n * field and is what the Status filter reads.\n *\n * `tools/scripts/backfill-orders-list-fields.mjs` restates this for the\n * orders written before it; the two answer the same worked examples,\n * `tools/scripts/lib/order-list-fields.fixtures.json`.\n */\n\n/** Tokens past this many are dropped from the quick search's array. */\nexport const ORDER_SEARCH_TOKEN_LIMIT = 200\n\n/** The fields the orders list's query reads, as every writer stamps them. */\nexport interface OrderListFields {\n  /**\n   * Always present. A Commerce Starter order (AGL-90) carried none and was\n   * read as `paid` (`liftLegacyOrder`); the lift is written down so the\n   * Status filter finds it.\n   */\n  status: OrderStatus\n  /** Always present; absent was always read as `online`. */\n  channel: OrderChannel\n  /**\n   * Every product the order holds, line items first and the legacy flat\n   * `productId` after — the Product filter's `array-contains-any`.\n   */\n  productIds: string[]\n  /**\n   * The dispute badge's tone (`describeOrderDispute`), or null with no\n   * dispute. `open` is a case with a deadline; `lost` a chargeback; `won` and\n   * `settled` closed with no money reversed. What the Disputes filter and the\n   * open-dispute banner ask.\n   */\n  disputeKey: OrderDisputeTone | null\n  /** The buyer's address, lower-cased — the Customer filter's `equals`. */\n  customerEmailLower: string | null\n  /** The address's search prefixes (`emailSearchTokens`) — its `contains`. */\n  customerEmailTokens: string[]\n  /** The order number's prefixes, with and without its `#` — Order `contains`. */\n  orderLabelTokens: string[]\n  /**\n   * The quick search: the order number's, the buyer's address's and every\n   * line item name's word prefixes, capped at {@link ORDER_SEARCH_TOKEN_LIMIT}\n   * with the item names cut first.\n   */\n  searchTokens: string[]\n}\n\n/** The dispute badge's tone, stored — see {@link OrderListFields.disputeKey}. */\nexport function orderDisputeKey(\n  dispute: OrderDispute | null | undefined,\n): OrderDisputeTone | null {\n  if (!dispute || typeof dispute !== 'object') return null\n  return describeOrderDispute({ dispute })?.tone ?? null\n}\n\n/**\n * The order number's prefixes, as `#1042` and as `1042`, so a reader who\n * types either finds it. An order with no number is labelled by its document\n * id (`formatOrderNumber`), and is found by that label the same way.\n */\nexport function orderLabelTokens(\n  order: Pick<Partial<HostOrder>, 'number'>,\n  docId: string,\n): string[] {\n  const label = nameSearchKey(formatOrderNumber({ number: order.number }, docId))\n  const bare = label.replace(/^#+/, '')\n  return nameSearchTokens(bare && bare !== label ? `${label} ${bare}` : label)\n}\n\nconst text = (value: unknown): string =>\n  typeof value === 'string' ? value : ''\n\n/**\n * The fields the orders list's query reads, from an order as it will be\n * stored — see {@link OrderListFields}. Pure: the same answer on the server,\n * in a spec and (restated) in the backfill.\n *\n * `legacyProductName` names the product of a Commerce Starter order, which\n * stored an id and no line items; only the backfill has it to give.\n */\nexport function orderListFields(\n  order: object,\n  docId: string,\n  options: { legacyProductName?: string } = {},\n): OrderListFields {\n  const source = order as Partial<HostOrder> & Record<string, unknown>\n  const lineItems = Array.isArray(source.lineItems) ? source.lineItems : []\n  const productIds = [\n    ...new Set(\n      [...lineItems.map((line) => line?.productId), source.productId].filter(\n        (id): id is string => typeof id === 'string' && id !== '',\n      ),\n    ),\n  ]\n  const email = text(source.customerEmail)\n  const emailTokens = emailSearchTokens(email)\n  const labelTokens = orderLabelTokens(source, docId)\n  const names = lineItems.map((line) => text(line?.name)).filter(Boolean)\n  if (!names.length && options.legacyProductName) {\n    names.push(options.legacyProductName)\n  }\n  const searchTokens = [\n    ...new Set([\n      ...labelTokens,\n      ...emailTokens,\n      ...names.flatMap((name) => nameSearchTokens(name)),\n    ]),\n  ].slice(0, ORDER_SEARCH_TOKEN_LIMIT)\n  return {\n    status: (text(source.status) || 'paid') as OrderStatus,\n    channel: (text(source.channel) || 'online') as OrderChannel,\n    productIds,\n    disputeKey: orderDisputeKey(source.dispute),\n    customerEmailLower: nameSearchKey(email) || null,\n    customerEmailTokens: emailTokens,\n    orderLabelTokens: labelTokens,\n    searchTokens,\n  }\n}\n\n/**\n * An order document with its list fields spread over it — what a creator\n * writes. The document's own `status` and `channel` win where it names them,\n * which every creator does; the rest is derived from it.\n */\nexport function withOrderListFields<T extends object>(\n  docId: string,\n  doc: T,\n): T & OrderListFields {\n  return { ...doc, ...orderListFields(doc, docId) }\n}\n"],"names":["emailSearchTokens","nameSearchKey","nameSearchTokens","describeOrderDispute","formatOrderNumber","ORDER_SEARCH_TOKEN_LIMIT","orderDisputeKey","dispute","tone","orderLabelTokens","order","docId","label","number","bare","replace","text","value","orderListFields","options","source","lineItems","Array","isArray","productIds","Set","map","line","productId","filter","id","email","customerEmail","emailTokens","labelTokens","names","name","Boolean","length","legacyProductName","push","searchTokens","flatMap","slice","status","channel","disputeKey","customerEmailLower","customerEmailTokens","withOrderListFields","doc"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,iBAAiB,QAAQ,sCAAqC;AACvE,SACEC,aAAa,EACbC,gBAAgB,QACX,qCAAoC;AAC3C,SAASC,oBAAoB,QAA+B,wBAAoB;AAChF,SACEC,iBAAiB,QAKZ,uBAAmB;AAE1B;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED,qEAAqE,GACrE,OAAO,MAAMC,2BAA2B,IAAG;AAsC3C,+EAA+E,GAC/E,OAAO,SAASC,gBACdC,OAAwC;;QAGjCJ;IADP,IAAI,CAACI,WAAW,OAAOA,YAAY,UAAU,OAAO;IACpD,gBAAOJ,wBAAAA,qBAAqB;QAAEI;IAAQ,uBAA/BJ,sBAAmCK,IAAI,mBAAI;AACpD;AAEA;;;;CAIC,GACD,OAAO,SAASC,iBACdC,KAAyC,EACzCC,KAAa;IAEb,MAAMC,QAAQX,cAAcG,kBAAkB;QAAES,QAAQH,MAAMG,MAAM;IAAC,GAAGF;IACxE,MAAMG,OAAOF,MAAMG,OAAO,CAAC,OAAO;IAClC,OAAOb,iBAAiBY,QAAQA,SAASF,QAAQ,GAAGA,MAAM,CAAC,EAAEE,MAAM,GAAGF;AACxE;AAEA,MAAMI,OAAO,CAACC,QACZ,OAAOA,UAAU,WAAWA,QAAQ;AAEtC;;;;;;;CAOC,GACD,OAAO,SAASC,gBACdR,KAAa,EACbC,KAAa,EACbQ,UAA0C,CAAC,CAAC;IAE5C,MAAMC,SAASV;IACf,MAAMW,YAAYC,MAAMC,OAAO,CAACH,OAAOC,SAAS,IAAID,OAAOC,SAAS,GAAG,EAAE;IACzE,MAAMG,aAAa;WACd,IAAIC,IACL;eAAIJ,UAAUK,GAAG,CAAC,CAACC,OAASA,wBAAAA,KAAMC,SAAS;YAAGR,OAAOQ,SAAS;SAAC,CAACC,MAAM,CACpE,CAACC,KAAqB,OAAOA,OAAO,YAAYA,OAAO;KAG5D;IACD,MAAMC,QAAQf,KAAKI,OAAOY,aAAa;IACvC,MAAMC,cAAcjC,kBAAkB+B;IACtC,MAAMG,cAAczB,iBAAiBW,QAAQT;IAC7C,MAAMwB,QAAQd,UAAUK,GAAG,CAAC,CAACC,OAASX,KAAKW,wBAAAA,KAAMS,IAAI,GAAGP,MAAM,CAACQ;IAC/D,IAAI,CAACF,MAAMG,MAAM,IAAInB,QAAQoB,iBAAiB,EAAE;QAC9CJ,MAAMK,IAAI,CAACrB,QAAQoB,iBAAiB;IACtC;IACA,MAAME,eAAe;WAChB,IAAIhB,IAAI;eACNS;eACAD;eACAE,MAAMO,OAAO,CAAC,CAACN,OAASlC,iBAAiBkC;SAC7C;KACF,CAACO,KAAK,CAAC,GAAGtC;IACX,OAAO;QACLuC,QAAS5B,KAAKI,OAAOwB,MAAM,KAAK;QAChCC,SAAU7B,KAAKI,OAAOyB,OAAO,KAAK;QAClCrB;QACAsB,YAAYxC,gBAAgBc,OAAOb,OAAO;QAC1CwC,oBAAoB9C,cAAc8B,UAAU;QAC5CiB,qBAAqBf;QACrBxB,kBAAkByB;QAClBO;IACF;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASQ,oBACdtC,KAAa,EACbuC,GAAM;IAEN,OAAO,aAAKA,KAAQhC,gBAAgBgC,KAAKvC;AAC3C"}