@aglyn/plugins-commerce 1.0.0-beta.285 → 1.0.0-beta.288

package/src/lib/model/plugin-permissions.js

@@ -13,6 +13,18 @@
  * 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 { _ as _extends } from "@swc/helpers/_/_extends";
+/** The tier defaults `managePos` has, which every finer key mirrors. */ const POS_TIER_DEFAULTS = {
+    admin: true,
+    editor: true,
+    viewer: false
+};
+/*
+ * The register is a site's own (AGL-4047): `managePos` and its five finer
+ * keys are `narrowsPerSite`, so an editor of the whole workspace given Viewer
+ * or Author access to one site does not work that site's register unless the
+ * site grants it to them. `posBuyHardware` is not: the hardware shop spends
+ * the workspace's money, and its verdict is the workspace's on every site.
  */ /**
  * Commerce's plugin-declared permissions (AGL-435) — the reference
  * adopter. Pure data: the client barrel and /server entry both register
@@ -22,14 +34,219 @@
         key: 'managePos',
         pluginId: 'commerce',
         label: 'Use the point of sale',
-        description: 'Open the POS page and record in-person sales.',
-        defaults: {
-            admin: true,
-            editor: true,
-            viewer: false
-        },
-        groupLabel: 'Commerce'
+        description: 'Open the point of sale. Each point of sale permission below follows this one unless a role or member sets it.',
+        defaults: _extends({}, POS_TIER_DEFAULTS),
+        groupLabel: 'Commerce',
+        narrowsPerSite: true
+    },
+    {
+        key: 'posSell',
+        pluginId: 'commerce',
+        label: 'Sell at the register',
+        description: 'Ring up sales and take payment at the register, the kiosk and the point of sale apps.',
+        defaults: _extends({}, POS_TIER_DEFAULTS),
+        groupLabel: 'Commerce',
+        narrowsPerSite: true,
+        refines: 'managePos'
+    },
+    {
+        key: 'posRefund',
+        pluginId: 'commerce',
+        label: 'Refunds and returns',
+        description: 'Refund point of sale orders at the register, up to its refund limit, and take returns and exchanges.',
+        defaults: _extends({}, POS_TIER_DEFAULTS),
+        groupLabel: 'Commerce',
+        narrowsPerSite: true,
+        refines: 'managePos'
+    },
+    {
+        key: 'posDiscount',
+        pluginId: 'commerce',
+        label: 'Give discounts at the register',
+        description: 'Take a discount off a sale at the register. A shopper’s discount code and the store’s own promotions apply without it.',
+        defaults: _extends({}, POS_TIER_DEFAULTS),
+        groupLabel: 'Commerce',
+        narrowsPerSite: true,
+        refines: 'managePos'
+    },
+    {
+        key: 'posCashDrawer',
+        pluginId: 'commerce',
+        label: 'Cash drawer and shifts',
+        description: 'Open and close shifts, record cash in and out, print shift reports and open the drawer without a sale.',
+        defaults: _extends({}, POS_TIER_DEFAULTS),
+        groupLabel: 'Commerce',
+        narrowsPerSite: true,
+        refines: 'managePos'
+    },
+    {
+        key: 'posDevices',
+        pluginId: 'commerce',
+        label: 'Registers and devices',
+        description: 'Add, change and remove card readers, receipt printers and customer displays, and set the reader screen.',
+        defaults: _extends({}, POS_TIER_DEFAULTS),
+        groupLabel: 'Commerce',
+        narrowsPerSite: true,
+        refines: 'managePos'
+    },
+    {
+        key: 'posBuyHardware',
+        pluginId: 'commerce',
+        label: 'Buy point of sale hardware',
+        description: 'Order card readers and other hardware from the hardware shop. Follows "Use the point of sale" unless a role or member sets it, and may be allowed without it.',
+        defaults: _extends({}, POS_TIER_DEFAULTS),
+        groupLabel: 'Commerce',
+        follows: 'managePos'
+    }
+];
+/** One finer register key's label, for a refusal or a disabled control's reason. */ export function posPermissionLabel(permission) {
+    var _ref;
+    var _COMMERCE_PERMISSIONS_find;
+    return (_ref = (_COMMERCE_PERMISSIONS_find = COMMERCE_PERMISSIONS.find((entry)=>entry.key === permission)) == null ? void 0 : _COMMERCE_PERMISSIONS_find.label) != null ? _ref : permission;
+}
+/**
+ * Whether a resolved permission map allows one of the register's finer
+ * actions (AGL-4047): `managePos`, and the finer key not refused. A map
+ * that does not carry the finer key at all follows `managePos` — the
+ * resolvers always carry it once commerce has registered, so an absent key
+ * is a map built before that, which keeps the register it had.
+ *
+ * `posBuyHardware` stands on its own: its own verdict when the map carries
+ * one, granted with or without `managePos`, and `managePos`'s when it does
+ * not.
+ */ export function holdsPosPermission(permissions, permission) {
+    if (permission === 'posBuyHardware') {
+        const own = permissions == null ? void 0 : permissions[permission];
+        return typeof own === 'boolean' ? own : (permissions == null ? void 0 : permissions['managePos']) === true;
+    }
+    return (permissions == null ? void 0 : permissions['managePos']) === true && (permissions == null ? void 0 : permissions[permission]) !== false;
+}
+/**
+ * Whether a member may open the hardware shop at all (AGL-4047): see what
+ * it offers and what the store ordered. Whoever works the register, and
+ * whoever may buy hardware without working it.
+ */ export function mayVisitPosHardwareShop(permissions) {
+    return (permissions == null ? void 0 : permissions['managePos']) === true || holdsPosPermission(permissions, 'posBuyHardware');
+}
+/** The refusal a register route answers when a finer key is not held. */ export function posPermissionRefusal(permission) {
+    return `Your role does not include "${posPermissionLabel(permission)}" — ask an organization admin`;
+}
+/** Who held reservations on a site before they were keys: Admin, Editor and Author. */ export const RESERVATION_SITE_ROLE_PRESET = {
+    admin: true,
+    editor: true,
+    author: true,
+    viewer: false
+};
+/** The same, per workspace role: the answer with no site named. */ const RESERVATION_ORG_ROLE_PRESET = {
+    owner: true,
+    admin: true,
+    editor: true,
+    viewer: false
+};
+/**
+ * Who worked a site's orders and gift cards before they were keys: the site's
+ * Admin and Editor (an Author edits the catalog and never touched an order).
+ */ export const ORDERS_SITE_ROLE_PRESET = {
+    admin: true,
+    editor: true,
+    author: false,
+    viewer: false
+};
+/**
+ * Who changed a site's payment methods and its shipping app connections
+ * before they were keys: the site's Admin alone (an Editor could see them, as
+ * whoever works the orders still can).
+ */ export const STORE_SETTINGS_SITE_ROLE_PRESET = {
+    admin: true,
+    editor: false,
+    author: false,
+    viewer: false
+};
+/** The same, per workspace role: the answer with no site named. */ export const STORE_SETTINGS_ORG_ROLE_PRESET = {
+    owner: true,
+    admin: true,
+    editor: false,
+    viewer: false
+};
+/**
+ * The reservation keys as commerce declares them into the org permission
+ * catalog (AGL-4047), registered beside `COMMERCE_PERMISSIONS`.
+ */ export const COMMERCE_SITE_PERMISSIONS = [
+    {
+        key: 'commerce.reservations',
+        label: 'Manage reservations',
+        description: 'Edit, cancel and check out stays, and add, change and remove what can be booked. Follows the site role unless a role or member sets it.',
+        roleDefaults: _extends({}, RESERVATION_ORG_ROLE_PRESET),
+        hostRoleDefaults: _extends({}, RESERVATION_SITE_ROLE_PRESET),
+        group: 'commerce',
+        groupLabel: 'Commerce',
+        presetFromSiteRole: true
+    },
+    {
+        key: 'commerce.walkIns',
+        label: 'Book walk-ins and change guests',
+        description: 'Book a walk-in stay and change how many guests a stay is for. Follows "Manage reservations" unless a role or member sets it, and may be allowed without it.',
+        roleDefaults: _extends({}, RESERVATION_ORG_ROLE_PRESET),
+        hostRoleDefaults: _extends({}, RESERVATION_SITE_ROLE_PRESET),
+        group: 'commerce',
+        groupLabel: 'Commerce',
+        presetFromSiteRole: true,
+        follows: 'commerce.reservations'
+    },
+    {
+        key: 'commerce.orders',
+        label: 'Manage orders',
+        description: 'Fulfill, cancel and print orders, resend receipts, build draft orders, take returns and record shipments. Follows the site role unless a role or member sets it.',
+        roleDefaults: _extends({}, RESERVATION_ORG_ROLE_PRESET),
+        hostRoleDefaults: _extends({}, ORDERS_SITE_ROLE_PRESET),
+        group: 'commerce',
+        groupLabel: 'Commerce',
+        presetFromSiteRole: true
+    },
+    {
+        key: 'commerce.giftCards',
+        label: 'Issue gift cards',
+        description: 'Issue, adjust and void the store’s gift cards. Follows the site role unless a role or member sets it.',
+        roleDefaults: _extends({}, RESERVATION_ORG_ROLE_PRESET),
+        hostRoleDefaults: _extends({}, ORDERS_SITE_ROLE_PRESET),
+        group: 'commerce',
+        groupLabel: 'Commerce',
+        presetFromSiteRole: true
+    },
+    {
+        key: 'commerce.paymentMethods',
+        label: 'Manage payment methods',
+        description: 'Turn the store’s payment methods on and off. Anyone with "Manage orders" sees them. Follows the site role unless a role or member sets it.',
+        roleDefaults: _extends({}, STORE_SETTINGS_ORG_ROLE_PRESET),
+        hostRoleDefaults: _extends({}, STORE_SETTINGS_SITE_ROLE_PRESET),
+        group: 'commerce',
+        groupLabel: 'Commerce',
+        presetFromSiteRole: true
+    },
+    {
+        key: 'commerce.shippingConnections',
+        label: 'Connect shipping apps',
+        description: 'Connect, sync and disconnect ShipStation and ShippingEasy, and show or replace their credentials. Anyone with "Manage orders" sees whether they are connected. Follows the site role unless a role or member sets it.',
+        roleDefaults: _extends({}, STORE_SETTINGS_ORG_ROLE_PRESET),
+        hostRoleDefaults: _extends({}, STORE_SETTINGS_SITE_ROLE_PRESET),
+        group: 'commerce',
+        groupLabel: 'Commerce',
+        presetFromSiteRole: true
     }
 ];
+/** The refusal a door answers when a commerce site key is not held: names the permission. */ export function commerceSitePermissionRefusal(key) {
+    var _ref;
+    var _COMMERCE_SITE_PERMISSIONS_find;
+    const label = (_ref = (_COMMERCE_SITE_PERMISSIONS_find = COMMERCE_SITE_PERMISSIONS.find((entry)=>entry.key === key)) == null ? void 0 : _COMMERCE_SITE_PERMISSIONS_find.label) != null ? _ref : key;
+    return `Your role does not include "${label}" — ask an organization admin`;
+}
+/** One reservation key's label, for a refusal. */ export function reservationPermissionLabel(permission) {
+    var _ref;
+    var _COMMERCE_SITE_PERMISSIONS_find;
+    return (_ref = (_COMMERCE_SITE_PERMISSIONS_find = COMMERCE_SITE_PERMISSIONS.find((entry)=>entry.key === permission)) == null ? void 0 : _COMMERCE_SITE_PERMISSIONS_find.label) != null ? _ref : permission;
+}
+/** The refusal a reservation route answers when its key is not held; names the permission, never a role. */ export function reservationPermissionRefusal(permission) {
+    return commerceSitePermissionRefusal(permission);
+}
 
 //# sourceMappingURL=plugin-permissions.js.map

package/src/lib/model/plugin-permissions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/plugin-permissions.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 type { PluginPermission } from '@aglyn/aglyn/plugin-manager/plugin-permissions'\n\n/**\n * Commerce's plugin-declared permissions (AGL-435) — the reference\n * adopter. Pure data: the client barrel and /server entry both register\n * it, so console gating and API-side resolution agree.\n */\nexport const COMMERCE_PERMISSIONS: readonly PluginPermission[] = [\n  {\n    key: 'managePos',\n    pluginId: 'commerce',\n    label: 'Use the point of sale',\n    description: 'Open the POS page and record in-person sales.',\n    defaults: { admin: true, editor: true, viewer: false },\n    groupLabel: 'Commerce',\n  },\n]\n"],"names":["COMMERCE_PERMISSIONS","key","pluginId","label","description","defaults","admin","editor","viewer","groupLabel"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID;;;;CAIC,GACD,OAAO,MAAMA,uBAAoD;IAC/D;QACEC,KAAK;QACLC,UAAU;QACVC,OAAO;QACPC,aAAa;QACbC,UAAU;YAAEC,OAAO;YAAMC,QAAQ;YAAMC,QAAQ;QAAM;QACrDC,YAAY;IACd;CACD,CAAA"}
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/plugin-permissions.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 type { HostAccessRole } from '@aglyn/aglyn/foundation/definitions/organization.types'\nimport type { PluginOrgPermissionDeclaration } from '@aglyn/aglyn/plugin-manager/plugin-entitlements'\nimport type { PluginPermission } from '@aglyn/aglyn/plugin-manager/plugin-permissions'\n\n/**\n * The register's finer permissions (AGL-4047), each a part of `managePos`\n * (Use the point of sale). Each REFINES it: never held without it, and,\n * where no custom role or override sets one, it follows `managePos` — so a\n * member keeps exactly the register they had until somebody narrows it.\n */\nexport type PosRegisterPermission =\n  | 'posSell'\n  | 'posRefund'\n  | 'posDiscount'\n  | 'posCashDrawer'\n  | 'posDevices'\n\n/**\n * The register's keys and `posBuyHardware`, which stands on its own\n * (AGL-4047): it FOLLOWS `managePos` where no custom role or override sets\n * it, so every member keeps the hardware shop they had, but it may be\n * granted without the register — a bookkeeper who orders the store's readers\n * and never rings a sale.\n */\nexport type PosPermission = PosRegisterPermission | 'posBuyHardware'\n\n/** The tier defaults `managePos` has, which every finer key mirrors. */\nconst POS_TIER_DEFAULTS = { admin: true, editor: true, viewer: false } as const\n\n/*\n * The register is a site's own (AGL-4047): `managePos` and its five finer\n * keys are `narrowsPerSite`, so an editor of the whole workspace given Viewer\n * or Author access to one site does not work that site's register unless the\n * site grants it to them. `posBuyHardware` is not: the hardware shop spends\n * the workspace's money, and its verdict is the workspace's on every site.\n */\n\n/**\n * Commerce's plugin-declared permissions (AGL-435) — the reference\n * adopter. Pure data: the client barrel and /server entry both register\n * it, so console gating and API-side resolution agree.\n */\nexport const COMMERCE_PERMISSIONS: readonly PluginPermission[] = [\n  {\n    key: 'managePos',\n    pluginId: 'commerce',\n    label: 'Use the point of sale',\n    description:\n      'Open the point of sale. Each point of sale permission below follows this one unless a role or member sets it.',\n    defaults: { ...POS_TIER_DEFAULTS },\n    groupLabel: 'Commerce',\n    narrowsPerSite: true,\n  },\n  {\n    key: 'posSell',\n    pluginId: 'commerce',\n    label: 'Sell at the register',\n    description: 'Ring up sales and take payment at the register, the kiosk and the point of sale apps.',\n    defaults: { ...POS_TIER_DEFAULTS },\n    groupLabel: 'Commerce',\n    narrowsPerSite: true,\n    refines: 'managePos',\n  },\n  {\n    key: 'posRefund',\n    pluginId: 'commerce',\n    label: 'Refunds and returns',\n    description: 'Refund point of sale orders at the register, up to its refund limit, and take returns and exchanges.',\n    defaults: { ...POS_TIER_DEFAULTS },\n    groupLabel: 'Commerce',\n    narrowsPerSite: true,\n    refines: 'managePos',\n  },\n  {\n    key: 'posDiscount',\n    pluginId: 'commerce',\n    label: 'Give discounts at the register',\n    description:\n      'Take a discount off a sale at the register. A shopper’s discount code and the store’s own promotions apply without it.',\n    defaults: { ...POS_TIER_DEFAULTS },\n    groupLabel: 'Commerce',\n    narrowsPerSite: true,\n    refines: 'managePos',\n  },\n  {\n    key: 'posCashDrawer',\n    pluginId: 'commerce',\n    label: 'Cash drawer and shifts',\n    description: 'Open and close shifts, record cash in and out, print shift reports and open the drawer without a sale.',\n    defaults: { ...POS_TIER_DEFAULTS },\n    groupLabel: 'Commerce',\n    narrowsPerSite: true,\n    refines: 'managePos',\n  },\n  {\n    key: 'posDevices',\n    pluginId: 'commerce',\n    label: 'Registers and devices',\n    description: 'Add, change and remove card readers, receipt printers and customer displays, and set the reader screen.',\n    defaults: { ...POS_TIER_DEFAULTS },\n    groupLabel: 'Commerce',\n    narrowsPerSite: true,\n    refines: 'managePos',\n  },\n  {\n    key: 'posBuyHardware',\n    pluginId: 'commerce',\n    label: 'Buy point of sale hardware',\n    description:\n      'Order card readers and other hardware from the hardware shop. Follows \"Use the point of sale\" unless a role or member sets it, and may be allowed without it.',\n    defaults: { ...POS_TIER_DEFAULTS },\n    groupLabel: 'Commerce',\n    follows: 'managePos',\n  },\n]\n\n/** One finer register key's label, for a refusal or a disabled control's reason. */\nexport function posPermissionLabel(permission: PosPermission): string {\n  return COMMERCE_PERMISSIONS.find((entry) => entry.key === permission)?.label ?? permission\n}\n\n/**\n * Whether a resolved permission map allows one of the register's finer\n * actions (AGL-4047): `managePos`, and the finer key not refused. A map\n * that does not carry the finer key at all follows `managePos` — the\n * resolvers always carry it once commerce has registered, so an absent key\n * is a map built before that, which keeps the register it had.\n *\n * `posBuyHardware` stands on its own: its own verdict when the map carries\n * one, granted with or without `managePos`, and `managePos`'s when it does\n * not.\n */\nexport function holdsPosPermission(\n  permissions: Readonly<Record<string, boolean | undefined>> | null | undefined,\n  permission: PosPermission,\n): boolean {\n  if (permission === 'posBuyHardware') {\n    const own = permissions?.[permission]\n    return typeof own === 'boolean' ? own : permissions?.['managePos'] === true\n  }\n  return permissions?.['managePos'] === true && permissions?.[permission] !== false\n}\n\n/**\n * Whether a member may open the hardware shop at all (AGL-4047): see what\n * it offers and what the store ordered. Whoever works the register, and\n * whoever may buy hardware without working it.\n */\nexport function mayVisitPosHardwareShop(\n  permissions: Readonly<Record<string, boolean | undefined>> | null | undefined,\n): boolean {\n  return permissions?.['managePos'] === true || holdsPosPermission(permissions, 'posBuyHardware')\n}\n\n/** The refusal a register route answers when a finer key is not held. */\nexport function posPermissionRefusal(permission: PosPermission): string {\n  return `Your role does not include \"${posPermissionLabel(permission)}\" — ask an organization admin`\n}\n\n/*\n * RESERVATIONS (AGL-4047).\n *\n * A site's stays and what they book were decided by the member's role ON THE\n * SITE: Admin, Editor and Author could book a walk-in, change a stay's guests\n * and edit or cancel stays, and a Viewer could not (`canWriteHostContent` in\n * the rules, the same three roles at the routes). Those are now keys whose\n * preset is that site role (`presetFromSiteRole`), so every member keeps\n * exactly the access they had, and a custom role, a member's own permissions\n * or a site's toggle can grant or refuse either one: the window's staff can\n * be allowed walk-ins without editing anyone's booking.\n */\n\n/** The reservation keys. */\nexport type ReservationPermission = 'commerce.reservations' | 'commerce.walkIns'\n\n/** Commerce's keys whose preset is the site role (AGL-4047). */\nexport type CommerceSitePermission =\n  | ReservationPermission\n  | 'commerce.orders'\n  | 'commerce.giftCards'\n  | 'commerce.paymentMethods'\n  | 'commerce.shippingConnections'\n\n/** Who held reservations on a site before they were keys: Admin, Editor and Author. */\nexport const RESERVATION_SITE_ROLE_PRESET: Readonly<Record<HostAccessRole, boolean>> = {\n  admin: true,\n  editor: true,\n  author: true,\n  viewer: false,\n}\n\n/** The same, per workspace role: the answer with no site named. */\nconst RESERVATION_ORG_ROLE_PRESET = { owner: true, admin: true, editor: true, viewer: false } as const\n\n/**\n * Who worked a site's orders and gift cards before they were keys: the site's\n * Admin and Editor (an Author edits the catalog and never touched an order).\n */\nexport const ORDERS_SITE_ROLE_PRESET: Readonly<Record<HostAccessRole, boolean>> = {\n  admin: true,\n  editor: true,\n  author: false,\n  viewer: false,\n}\n\n/**\n * Who changed a site's payment methods and its shipping app connections\n * before they were keys: the site's Admin alone (an Editor could see them, as\n * whoever works the orders still can).\n */\nexport const STORE_SETTINGS_SITE_ROLE_PRESET: Readonly<Record<HostAccessRole, boolean>> = {\n  admin: true,\n  editor: false,\n  author: false,\n  viewer: false,\n}\n\n/** The same, per workspace role: the answer with no site named. */\nexport const STORE_SETTINGS_ORG_ROLE_PRESET = { owner: true, admin: true, editor: false, viewer: false } as const\n\n/**\n * The reservation keys as commerce declares them into the org permission\n * catalog (AGL-4047), registered beside `COMMERCE_PERMISSIONS`.\n */\nexport const COMMERCE_SITE_PERMISSIONS: readonly PluginOrgPermissionDeclaration[] = [\n  {\n    key: 'commerce.reservations',\n    label: 'Manage reservations',\n    description:\n      'Edit, cancel and check out stays, and add, change and remove what can be booked. Follows the site role unless a role or member sets it.',\n    roleDefaults: { ...RESERVATION_ORG_ROLE_PRESET },\n    hostRoleDefaults: { ...RESERVATION_SITE_ROLE_PRESET },\n    group: 'commerce',\n    groupLabel: 'Commerce',\n    presetFromSiteRole: true,\n  },\n  {\n    key: 'commerce.walkIns',\n    label: 'Book walk-ins and change guests',\n    description:\n      'Book a walk-in stay and change how many guests a stay is for. Follows \"Manage reservations\" unless a role or member sets it, and may be allowed without it.',\n    roleDefaults: { ...RESERVATION_ORG_ROLE_PRESET },\n    hostRoleDefaults: { ...RESERVATION_SITE_ROLE_PRESET },\n    group: 'commerce',\n    groupLabel: 'Commerce',\n    presetFromSiteRole: true,\n    follows: 'commerce.reservations',\n  },\n  {\n    key: 'commerce.orders',\n    label: 'Manage orders',\n    description:\n      'Fulfill, cancel and print orders, resend receipts, build draft orders, take returns and record shipments. Follows the site role unless a role or member sets it.',\n    roleDefaults: { ...RESERVATION_ORG_ROLE_PRESET },\n    hostRoleDefaults: { ...ORDERS_SITE_ROLE_PRESET },\n    group: 'commerce',\n    groupLabel: 'Commerce',\n    presetFromSiteRole: true,\n  },\n  {\n    key: 'commerce.giftCards',\n    label: 'Issue gift cards',\n    description: 'Issue, adjust and void the store’s gift cards. Follows the site role unless a role or member sets it.',\n    roleDefaults: { ...RESERVATION_ORG_ROLE_PRESET },\n    hostRoleDefaults: { ...ORDERS_SITE_ROLE_PRESET },\n    group: 'commerce',\n    groupLabel: 'Commerce',\n    presetFromSiteRole: true,\n  },\n  {\n    key: 'commerce.paymentMethods',\n    label: 'Manage payment methods',\n    description:\n      'Turn the store’s payment methods on and off. Anyone with \"Manage orders\" sees them. Follows the site role unless a role or member sets it.',\n    roleDefaults: { ...STORE_SETTINGS_ORG_ROLE_PRESET },\n    hostRoleDefaults: { ...STORE_SETTINGS_SITE_ROLE_PRESET },\n    group: 'commerce',\n    groupLabel: 'Commerce',\n    presetFromSiteRole: true,\n  },\n  {\n    key: 'commerce.shippingConnections',\n    label: 'Connect shipping apps',\n    description:\n      'Connect, sync and disconnect ShipStation and ShippingEasy, and show or replace their credentials. Anyone with \"Manage orders\" sees whether they are connected. Follows the site role unless a role or member sets it.',\n    roleDefaults: { ...STORE_SETTINGS_ORG_ROLE_PRESET },\n    hostRoleDefaults: { ...STORE_SETTINGS_SITE_ROLE_PRESET },\n    group: 'commerce',\n    groupLabel: 'Commerce',\n    presetFromSiteRole: true,\n  },\n]\n\n/** The refusal a door answers when a commerce site key is not held: names the permission. */\nexport function commerceSitePermissionRefusal(key: CommerceSitePermission): string {\n  const label = COMMERCE_SITE_PERMISSIONS.find((entry) => entry.key === key)?.label ?? key\n  return `Your role does not include \"${label}\" — ask an organization admin`\n}\n\n/** One reservation key's label, for a refusal. */\nexport function reservationPermissionLabel(permission: ReservationPermission): string {\n  return COMMERCE_SITE_PERMISSIONS.find((entry) => entry.key === permission)?.label ?? permission\n}\n\n/** The refusal a reservation route answers when its key is not held; names the permission, never a role. */\nexport function reservationPermissionRefusal(permission: ReservationPermission): string {\n  return commerceSitePermissionRefusal(permission)\n}\n"],"names":["POS_TIER_DEFAULTS","admin","editor","viewer","COMMERCE_PERMISSIONS","key","pluginId","label","description","defaults","groupLabel","narrowsPerSite","refines","follows","posPermissionLabel","permission","find","entry","holdsPosPermission","permissions","own","mayVisitPosHardwareShop","posPermissionRefusal","RESERVATION_SITE_ROLE_PRESET","author","RESERVATION_ORG_ROLE_PRESET","owner","ORDERS_SITE_ROLE_PRESET","STORE_SETTINGS_SITE_ROLE_PRESET","STORE_SETTINGS_ORG_ROLE_PRESET","COMMERCE_SITE_PERMISSIONS","roleDefaults","hostRoleDefaults","group","presetFromSiteRole","commerceSitePermissionRefusal","reservationPermissionLabel","reservationPermissionRefusal"],"mappings":"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"}

package/src/lib/model/pos-cellular.d.ts

@@ -0,0 +1,223 @@
+/**
+ * @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.
+ */
+export declare const POS_CELLULAR_ENV: {
+    readonly monthlyCostCents: "POS_CELLULAR_MONTHLY_COST_CENTS";
+    readonly billingCostBps: "POS_CELLULAR_BILLING_COST_BPS";
+    readonly billingCostFixedCents: "POS_CELLULAR_BILLING_COST_FIXED_CENTS";
+    readonly productId: "STRIPE_PRODUCT_POS_CELLULAR";
+    readonly graceDays: "POS_CELLULAR_GRACE_DAYS";
+};
+/** How long a month's charge may stay unpaid before 4G is turned off, unless configured. */
+export declare const POS_CELLULAR_DEFAULT_GRACE_DAYS = 14;
+/** A day, in milliseconds. */
+export declare const POS_CELLULAR_DAY_MS: number;
+/** The platform's card processing rate, in basis points: the default billing cost. */
+export declare const POS_CELLULAR_DEFAULT_BILLING_COST_BPS: number;
+/** The platform's card processing fixed fee, in cents: the default billing cost. */
+export declare const POS_CELLULAR_DEFAULT_BILLING_COST_FIXED_CENTS: number;
+/** The Stripe device types that take cellular service: the S710, and its simulator. */
+export declare const POS_CELLULAR_DEVICE_TYPES: readonly string[];
+/** The top-level, server-only record of each reader's 4G months. */
+export declare const POS_CELLULAR_READERS_COLLECTION = "posCellularReaders";
+/** The top-level, server-only record of each workspace's monthly 4G charge. */
+export declare const POS_CELLULAR_CHARGES_COLLECTION = "posCellularCharges";
+/** The metadata `kind` the charge's invoice carries. */
+export declare const POS_CELLULAR_CHARGE_KIND = "pos-cellular";
+/** How many 4G periods a reader's record keeps: two years of on and off. */
+export declare const POS_CELLULAR_MAX_PERIODS = 24;
+export interface PosCellularConfig {
+    monthlyCostCents: number;
+    billingCostBps: number;
+    billingCostFixedCents: number;
+    productId: string;
+    /** Days a charge may stay unpaid before 4G is turned off for the workspace. */
+    graceDays: number;
+}
+/**
+ * The deployment's 4G pricing, or null when 4G is not offered: no monthly
+ * cost, no product, or a value that is not a whole number in range. A bad
+ * value hides the feature rather than billing a guess.
+ */
+export declare function parsePosCellularConfig(env?: Record<string, string | undefined>): PosCellularConfig | null;
+/**
+ * One workspace's 4G charge for a month, in whole cents: Stripe's price for
+ * each reader, grossed up so that what the charge's own processing takes
+ * leaves the platform exactly that:
+ *
+ *     ceil((readers × cost + fixed) / (1 − rate))
+ *
+ * Rounded up, the one direction that never bills below cost.
+ * Zero readers is no charge.
+ */
+export declare function posCellularChargeCents(readers: number, config: PosCellularConfig): number;
+/**
+ * What one reader costs a month, as the console shows it: a store's charge
+ * for a single reader. More readers on one charge share its fixed fee, so
+ * this is never less than any reader's share of a larger charge.
+ */
+export declare function posCellularReaderMonthlyCents(config: PosCellularConfig): number;
+/** Whether a reader of this Stripe device type can have 4G. */
+export declare function isPosCellularDeviceType(deviceType: unknown): boolean;
+/** `2026-10` for a time in October 2026, in UTC. */
+export declare function posCellularMonthKey(ms: number): string;
+/** The calendar month before the one `ms` falls in. */
+export declare function posCellularPreviousMonthKey(ms: number): string;
+/** A month's first instant, and the next month's, in UTC; null for a key that is not one. */
+export declare function posCellularMonthBounds(month: string): {
+    startMs: number;
+    endMs: number;
+} | null;
+/** `October 2026`, for the invoice line. */
+export declare function posCellularMonthLabel(month: string): string;
+/** One stretch of time a reader had 4G: from when it was turned on, to when it was turned off (open while it is on). */
+export interface PosCellularPeriod {
+    fromMs: number;
+    toMs: number | null;
+}
+/**
+ * `posCellularReaders/{hostId}_{readerId}`: one S710's 4G months, written
+ * only by the server. No person is named on it: a workspace, a store, a
+ * Stripe reader and its serial, and when it had 4G.
+ */
+export interface PosCellularReaderRecord {
+    orgId: string;
+    hostId: string;
+    readerId: string;
+    serialNumber: string | null;
+    /** The store's Terminal Configuration that carries `cellular[enabled]`. */
+    stripeConfigurationId: string | null;
+    enabled: boolean;
+    periods: PosCellularPeriod[];
+    /** The last time a period was closed, which the month's charge queries by. */
+    disabledAtMs: number | null;
+    updatedAtMs: number;
+}
+/** The record's document id. */
+export declare function posCellularReaderId(hostId: string, readerId: string): string;
+/** The record with a period open from `now`, unless one already is. */
+export declare function openPosCellularPeriod(base: Omit<PosCellularReaderRecord, 'enabled' | 'periods' | 'disabledAtMs' | 'updatedAtMs'>, existing: PosCellularReaderRecord | null, now: number): PosCellularReaderRecord;
+/** The record with its open period closed at `now`; unchanged when none is open. */
+export declare function closePosCellularPeriod(existing: PosCellularReaderRecord, now: number): PosCellularReaderRecord;
+/** Whether a reader had 4G at any time in the month. */
+export declare function posCellularBilledInMonth(record: Pick<PosCellularReaderRecord, 'periods'>, bounds: {
+    startMs: number;
+    endMs: number;
+}): boolean;
+/** Each workspace's readers that had 4G in the month, by workspace. */
+export declare function posCellularReadersByWorkspace(records: ReadonlyArray<PosCellularReaderRecord>, month: string): Map<string, {
+    readers: number;
+    hostIds: string[];
+}>;
+/**
+ * The outcome of a workspace's month: charged and paid; charged and left
+ * open on their Billing page because the card failed; still unpaid after the
+ * grace period, so 4G was turned off for the workspace (`suspended`); its
+ * invoice voided by staff (`voided`); not charged because there is no one to
+ * bill (no workspace, no customer) or nothing to bill (under Stripe's
+ * minimum); or `charging`, claimed by a run in progress.
+ */
+export type PosCellularChargeState = 'charging' | 'paid' | 'open' | 'suspended' | 'voided' | 'failed' | 'no-workspace' | 'no-customer' | 'below-minimum';
+/** States a later run never charges again. */
+export declare const POS_CELLULAR_SETTLED_STATES: readonly PosCellularChargeState[];
+/** `posCellularCharges/{orgId}_{month}`: one workspace's 4G charge for one month. */
+export interface PosCellularCharge {
+    orgId: string;
+    month: string;
+    readers: number;
+    amountCents: number;
+    state: PosCellularChargeState;
+    invoiceId: string | null;
+    paidCents: number;
+    attempts: number;
+    createdAtMs: number;
+    updatedAtMs: number;
+    /** When the charge was left open, which the grace period counts from. */
+    openedAtMs?: number | null;
+    /** When 4G was turned off for the workspace because it stayed unpaid. */
+    suspendedAtMs?: number | null;
+    /** The stores 4G was turned off for, whose notice clears once it is paid. */
+    suspendedHostIds?: string[];
+    /**
+     * When the people who manage the workspace's billing were warned, as the
+     * charge was left open, of the day 4G turns off unless it is paid.
+     */
+    warnedAtMs?: number | null;
+    /** When the people who manage the workspace's billing were told 4G was turned off. */
+    noticeSentAtMs?: number | null;
+    /** Charged as the workspace was erased, for the month it was deleted in (or the one before). */
+    final?: boolean;
+}
+/**
+ * When a charge left open runs out of grace: the grace period after it was
+ * left open (or, for a charge from before that was recorded, after it last
+ * changed).
+ */
+export declare function posCellularGraceEndsAtMs(charge: Pick<PosCellularCharge, 'openedAtMs' | 'updatedAtMs'>, graceDays: number): number;
+/** Whether an open charge is past its grace period. */
+export declare function posCellularOverdue(charge: Pick<PosCellularCharge, 'state' | 'openedAtMs' | 'updatedAtMs'>, graceDays: number, now: number): boolean;
+/**
+ * Whether the people who manage a workspace's billing are still owed the
+ * warning that 4G turns off unless the charge is paid: an open charge not yet
+ * warned of. Never a charge made as the workspace was erased, whose 4G is
+ * already off and whose members are gone.
+ */
+export declare function posCellularWarningDue(charge: Pick<PosCellularCharge, 'state' | 'warnedAtMs' | 'final'>): boolean;
+/**
+ * A day as the workspace reads it, `November 16, 2026`, in its time zone
+ * (UTC for a zone the runtime cannot format in).
+ */
+export declare function posCellularDayLabel(ms: number, timeZone?: string): string;
+/**
+ * On a store's terminal settings (`cellularSuspended`) while 4G is off because
+ * a month's charge was not paid: which month, its invoice, and when.
+ */
+export interface PosCellularSuspension {
+    month: string;
+    invoiceId: string | null;
+    atMs: number;
+}
+/** What the POS devices card is told about 4G for a store; null hides it. */
+export interface PosCellularView {
+    /** What one reader costs a month, in cents, before any sales tax. */
+    readerMonthlyCents: number;
+    enabled: boolean;
+    /** The store's readers that take 4G. */
+    readers: number;
+    /** Turned off because a month's charge was not paid: that month, as `October 2026`, and when. */
+    suspended?: {
+        month: string;
+        atMs: number;
+    } | null;
+    /**
+     * Why the viewer may not turn 4G ON (it is charged to the workspace, so it
+     * also takes "Manage billing"), or null. Turning it off needs only the
+     * card's own key.
+     */
+    turnOnBlocked?: string | null;
+}
+/**
+ * The 4G row of a store's POS devices card: shown only where 4G is offered
+ * and the store has an S710, or already has 4G on (so it can be turned off).
+ */
+export declare function posCellularView(config: PosCellularConfig | null, terminal: {
+    cellularEnabled?: unknown;
+    cellularSuspended?: unknown;
+} | null | undefined, readers: ReadonlyArray<{
+    deviceType?: unknown;
+}>, options?: {
+    turnOnBlocked?: string | null;
+}): PosCellularView | null;