@teincfood/core 0.9.5 → 0.9.8

package/dist/reference/entitlement-guard.js

@@ -0,0 +1,83 @@
+/**
+ * Offline entitlement auto-guard — evaluates the cached signed
+ * `subscription:entitlements` envelope and enforces gated commands locally,
+ * before any transport is attempted. The backend remains the final authority
+ * (HTTP 402 SUBSCRIPTION_REQUIRED); this guard gives immediate feedback and
+ * keeps disallowed work out of the outbox.
+ *
+ * Fail-closed: missing envelope, missing secret, bad signature, expired, or
+ * stale (> max_offline_days) => gated commands throw SUBSCRIPTION_REQUIRED.
+ * The host app provisions the HMAC secret at boot via setEntitlementSecret
+ * and refreshes the envelope via reference sync; useEntitlements surfaces
+ * mustReconnect/paywall state for UI gates.
+ */
+import { openSyncDatabase } from "../db/connection";
+import { getReferenceData } from "../reference/operations";
+import { evaluateEntitlements, getEntitledFeature, } from "./entitlements";
+import { assertEntitledFor } from "../sync/online-gates";
+let entitlementSecret = null;
+/** Provisioned once at app boot from the host app's env. */
+export function setEntitlementSecret(secret) {
+    entitlementSecret = secret;
+}
+export function getEntitlementSecret() {
+    return entitlementSecret;
+}
+/** Evaluate the cached signed envelope for a business (no network). */
+export async function evaluateBusinessEntitlements(businessId) {
+    const db = await openSyncDatabase();
+    const rec = await getReferenceData(db, businessId, "subscription:entitlements");
+    const payload = (rec?.payload ?? null);
+    const evaluation = await evaluateEntitlements({
+        businessId,
+        envelope: payload?.envelope,
+        features: payload?.data,
+        secret: entitlementSecret ?? "",
+    });
+    return { evaluation, features: payload?.data ?? null };
+}
+/**
+ * Per-command feature keys. Commands without an entry require overall
+ * `entitled` only (counts/quotas stay backend-enforced). delivery:assign is
+ * intentionally overall-only: merchants assigning their own riders are not
+ * subject to the fleet feature (backend scopes fleet.dispatch to
+ * delivery_provider businesses the same way).
+ */
+const FEATURE_BY_COMMAND = {
+    "promo:create": "seller.promo",
+};
+/** Real engine command types subject to the entitlement guard. */
+const GATED_COMMANDS = new Set([
+    "order:create",
+    "menu:create_item",
+    "menu:update_item",
+    "menu:delete_item",
+    "menu:create_category",
+    "promo:create",
+    "member:invite",
+    "member:manage",
+    "terminal:link",
+    "delivery:assign",
+]);
+export function isEntitlementGated(commandType) {
+    return GATED_COMMANDS.has(commandType);
+}
+/**
+ * Throw SUBSCRIPTION_REQUIRED unless the cached entitlement proof covers
+ * this command. No-ops for non-gated commands — and when no envelope was
+ * ever cached (fresh terminal that never synced): the backend remains the
+ * authority there. Once proof exists, invalid/expired/stale proof denies.
+ */
+export async function assertEntitledForCommand(businessId, commandType) {
+    if (!isEntitlementGated(commandType))
+        return;
+    const db = await openSyncDatabase();
+    const rec = await getReferenceData(db, businessId, "subscription:entitlements");
+    if (!rec?.payload)
+        return;
+    const { evaluation, features } = await evaluateBusinessEntitlements(businessId);
+    const feature = FEATURE_BY_COMMAND[commandType];
+    const entitled = evaluation.entitled &&
+        (!feature || getEntitledFeature(evaluation, features, feature));
+    assertEntitledFor(commandType, entitled, evaluation.reason);
+}

package/dist/reference/menu-record.d.ts

@@ -22,7 +22,7 @@ export interface MenuItemRecordInput {
     variants?: Array<{
         id?: string;
         name: string;
-        price_adjustment?: number;
+        price?: number;
     }>;
     extras?: Array<{
         id?: string;
@@ -51,8 +51,7 @@ export interface MenuItemEnvelopeInput extends MenuItemRecordInput {
 }
 /**
  * Build the { wire, cacheRecord } pair for a menu item write. Callers pass
- * backend adjustment-shaped variants; absolute form prices are converted by
- * the caller (form layer owns both fields).
+ * absolute variant prices (backend model) — the form layer owns the field.
  *
  * Variant/extra ids are preserved when they are backend UUIDs. The backend
  * update path deletes existing rows absent from the incoming list, so

package/dist/reference/menu-record.js

@@ -29,8 +29,8 @@ export function buildMenuItemRecord(input) {
         variants: (input.variants ?? []).map((v) => ({
             id: v.id ?? generateUUID(),
             name: v.name,
-            // Matches backend serializer: variant price = base + adjustment.
-            price: { amountMinor: input.priceMinor + (v.price_adjustment ?? 0), currencyCode },
+            // Absolute variant price (backend model) — no size defaults to base.
+            price: { amountMinor: v.price ?? input.priceMinor, currencyCode },
         })),
         extras: (input.extras ?? []).map((e) => ({
             id: e.id ?? generateUUID(),
@@ -123,8 +123,7 @@ function wireId(id) {
 }
 /**
  * Build the { wire, cacheRecord } pair for a menu item write. Callers pass
- * backend adjustment-shaped variants; absolute form prices are converted by
- * the caller (form layer owns both fields).
+ * absolute variant prices (backend model) — the form layer owns the field.
  *
  * Variant/extra ids are preserved when they are backend UUIDs. The backend
  * update path deletes existing rows absent from the incoming list, so
@@ -145,8 +144,8 @@ export function buildMenuItemEnvelope(input) {
         variants: (input.variants ?? []).map((v) => {
             const vid = wireId(v.id);
             return vid
-                ? { id: vid, name: v.name, price_adjustment: v.price_adjustment ?? 0 }
-                : { name: v.name, price_adjustment: v.price_adjustment ?? 0 };
+                ? { id: vid, name: v.name, price: v.price ?? input.priceMinor }
+                : { name: v.name, price: v.price ?? input.priceMinor };
         }),
         extras: (input.extras ?? []).map((e) => {
             const eid = wireId(e.id);

package/dist/sync/command-queue.service.js

@@ -210,7 +210,7 @@ class CommandQueueService {
         // types (transitions, payments, delivery) are unaffected so in-progress
         // orders can still be completed while closed.
         if (command.command_type === "order:create") {
-            await assertBusinessOpenForCreate(command.business_id);
+            await assertBusinessOpenForCreate(command.business_id, new Date(), "pos");
         }
         const db = getSyncDatabase();
         const preparedCommand = injectLocalOrderNumber(command);

package/dist/sync/engine.js

@@ -24,6 +24,7 @@ import { getReferenceData } from "../reference/operations";
 import { openSyncDatabase } from "../db/connection";
 import { canBusinessSync } from "./sync-guard";
 import { TRANSITION_ERROR_CODES, TransitionError } from "./transition-errors";
+import { assertEntitledForCommand } from "../reference/entitlement-guard";
 function withTimeout(promise, ms) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
@@ -79,6 +80,22 @@ export class SyncEngine {
                 // otherwise fail open
             }
         }
+        // Entitlement guard (fail-closed, offline-first): subscription-gated
+        // commands need cached proof before routing. Backend 402 backstops.
+        try {
+            await assertEntitledForCommand(command.business_id, command.command_type);
+        }
+        catch (e) {
+            if (e instanceof TransitionError &&
+                e.code === TRANSITION_ERROR_CODES.SUBSCRIPTION_REQUIRED) {
+                throw e;
+            }
+            // Guard infra failure (no DB yet, corrupt cache) must not brick the
+            // terminal — backend remains the authority. Log and continue.
+            syncLogger.warn("SyncEngine", "entitlement guard skipped", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
         let strategy = this.resolveStrategy(command);
         const { isCloudReachable, isOnline } = getConnectivityState();
         syncLogger.info("SyncEngine", "Command strategy resolved", {

package/dist/sync/online-gates.js

@@ -69,7 +69,7 @@ export function assertOnlineFor(commandType, payload) {
  */
 export function assertEntitledFor(commandType, entitled, evaluationReason) {
     const gated = new Set([
-        "order:create_online",
+        "order:create",
         "menu:create_item",
         "menu:update_item",
         "menu:delete_item",
@@ -78,7 +78,7 @@ export function assertEntitledFor(commandType, entitled, evaluationReason) {
         "member:invite",
         "member:manage",
         "terminal:link",
-        "fleet:dispatch_create",
+        "delivery:assign",
     ]);
     if (!gated.has(commandType))
         return;

package/dist/types/api/menu.api.d.ts

@@ -52,7 +52,8 @@ export interface MenuItemListResponse {
 export interface MenuItemVariant {
     id: string;
     name: string;
-    price_adjustment: number;
+    /** Absolute variant price in minor units (replaces the base price). */
+    price: number;
 }
 export interface MenuItemAddon {
     id: string;
@@ -80,7 +81,8 @@ export interface CatalogItemRequest {
     variants: {
         id?: string;
         name: string;
-        price_adjustment: number;
+        /** Absolute variant price in minor units (replaces the base price). */
+        price: number;
     }[];
     extras: {
         id?: string;

package/dist/types/api/seller.api.d.ts

@@ -20,6 +20,12 @@ export interface OrderMenuItem {
 export interface OrderItemAddon {
     id: string;
     price: number;
+    /** Minor-unit price (backend order_item_addons carry price_minor). */
+    price_minor?: number;
+    name?: string;
+    addon?: {
+        name?: string;
+    } | null;
 }
 export interface OrderItem {
     id: string;
@@ -28,11 +34,20 @@ export interface OrderItem {
     unit_price: number;
     subtotal: number;
     addons?: OrderItemAddon[];
+    /** Backend order_items preload :variant (absolute size, has name). */
+    variant?: {
+        id?: string;
+        name?: string;
+    } | null;
+    /** Backend shape for addon lines. */
+    order_item_addons?: OrderItemAddon[];
 }
 export interface OrderBusiness {
     id: string;
     name: string;
     phone?: string;
+    /** Base64 `GS v 0` raster block for the thermal header (synced via business:profile). */
+    logo_escpos?: string | null;
     latitude?: number;
     longitude?: number;
     estimated_delivery_time?: number;

package/dist/utils/business-hours.d.ts

@@ -1,8 +1,10 @@
 /**
  * Business open/closed evaluation — single source for the lib.
  *
- * Mirrors backend `TeincFoodBackend.Businesses.is_open?/1` exactly:
- *   - `manually_closed` → closed
+ * Mirrors backend `TeincFoodBackend.Businesses.is_open?/1` for the `online`
+ * channel and `open_for_pos?/1` for the `pos` channel:
+ *   - `manually_closed` → closed for online; IGNORED for pos (temporary
+ *     online shutdown must not stop the POS terminal)
  *   - else UTC clock: day = Elixir `Date.day_of_week - 1` (Monday=0 … Sunday=6),
  *     a row matches when `day_of_week` equals today, `is_closed` is false and
  *     `open_time <= now < close_time` (open inclusive, close exclusive).
@@ -13,6 +15,8 @@
  * fixed here): overnight ranges (close <= open) never match.
  */
 export type BusinessClosedReason = "manually_closed" | "outside_hours" | "no_hours_configured";
+/** Order channel: online buyer orders vs in-store POS orders. */
+export type OrderChannel = "online" | "pos";
 export interface BusinessOpenState {
     open: boolean;
     reason?: BusinessClosedReason;
@@ -27,11 +31,11 @@ export declare class BusinessHoursError extends Error {
     reason?: BusinessClosedReason;
     constructor(code: "BUSINESS_CLOSED" | "HOURS_NOT_SYNCED", message: string, reason?: BusinessClosedReason);
 }
-export declare function isBusinessOpenNow(businessId: string, now?: Date): Promise<BusinessOpenState>;
+export declare function isBusinessOpenNow(businessId: string, now?: Date, channel?: OrderChannel): Promise<BusinessOpenState>;
 /**
  * Guard for order creation — fail-closed. Throws `BusinessHoursError` with
  * code `HOURS_NOT_SYNCED` when no hours are cached (configure in Settings,
  * works offline) or `BUSINESS_CLOSED` when the business is closed.
  * Backend remains the final gate for clock-skew edge cases.
  */
-export declare function assertBusinessOpenForCreate(businessId: string, now?: Date): Promise<BusinessOpenState>;
+export declare function assertBusinessOpenForCreate(businessId: string, now?: Date, channel?: OrderChannel): Promise<BusinessOpenState>;

package/dist/utils/business-hours.js

@@ -1,8 +1,10 @@
 /**
  * Business open/closed evaluation — single source for the lib.
  *
- * Mirrors backend `TeincFoodBackend.Businesses.is_open?/1` exactly:
- *   - `manually_closed` → closed
+ * Mirrors backend `TeincFoodBackend.Businesses.is_open?/1` for the `online`
+ * channel and `open_for_pos?/1` for the `pos` channel:
+ *   - `manually_closed` → closed for online; IGNORED for pos (temporary
+ *     online shutdown must not stop the POS terminal)
  *   - else UTC clock: day = Elixir `Date.day_of_week - 1` (Monday=0 … Sunday=6),
  *     a row matches when `day_of_week` equals today, `is_closed` is false and
  *     `open_time <= now < close_time` (open inclusive, close exclusive).
@@ -41,7 +43,7 @@ function normalizeEntries(payload) {
         return data;
     return [];
 }
-export async function isBusinessOpenNow(businessId, now = new Date()) {
+export async function isBusinessOpenNow(businessId, now = new Date(), channel = "online") {
     const evaluatedAt = new Date().toISOString();
     // Backend: Date.day_of_week (Mon=1..Sun=7) minus 1 → Mon=0..Sun=6 (UTC).
     const dayOfWeek = (now.getUTCDay() + 6) % 7;
@@ -56,7 +58,7 @@ export async function isBusinessOpenNow(businessId, now = new Date()) {
     const profileData = profile && typeof profile === "object" && "data" in profile && profile.data !== undefined
         ? profile.data
         : (profile ?? {});
-    if (profileData.manually_closed === true) {
+    if (profileData.manually_closed === true && channel !== "pos") {
         return { open: false, reason: "manually_closed", dayOfWeek, timeUtc, evaluatedAt };
     }
     const entries = normalizeEntries(hoursRec?.payload);
@@ -82,8 +84,8 @@ export async function isBusinessOpenNow(businessId, now = new Date()) {
  * works offline) or `BUSINESS_CLOSED` when the business is closed.
  * Backend remains the final gate for clock-skew edge cases.
  */
-export async function assertBusinessOpenForCreate(businessId, now = new Date()) {
-    const state = await isBusinessOpenNow(businessId, now);
+export async function assertBusinessOpenForCreate(businessId, now = new Date(), channel = "online") {
+    const state = await isBusinessOpenNow(businessId, now, channel);
     if (state.reason === "no_hours_configured") {
         throw new BusinessHoursError("HOURS_NOT_SYNCED", "Operating hours are not available offline — configure them in Settings (works offline) or sync once before taking orders", state.reason);
     }

package/dist/utils/order-transitions.d.ts

@@ -12,6 +12,19 @@ export declare const ORDER_STATUSES: readonly ["pending", "awaiting_payment", "a
 export type OrderStatus = (typeof ORDER_STATUSES)[number];
 export declare const CANCELLABLE_STATUSES: readonly ["pending", "awaiting_payment", "accepted", "preparing", "ready"];
 export declare const PIPELINE: readonly ["pending", "accepted", "preparing", "ready", "delivered"];
+export type StageState = "done" | "current" | "upcoming";
+export interface PipelineStage {
+    status: string;
+    state: StageState;
+}
+/**
+ * Derives hierarchical stage states for `current` over `steps`
+ * (defaults to PIPELINE). Stages before the current index are `done`,
+ * the current index is `current`, later stages are `upcoming`.
+ * Unknown statuses (e.g. cancelled, awaiting_payment) yield all `upcoming`
+ * so callers can apply their own mapping first.
+ */
+export declare function stageStatuses(current: string, steps?: readonly string[]): PipelineStage[];
 export type OrderAction = "accept" | "reject" | "start_preparing" | "mark_ready" | "complete_pickup" | "cancel" | "assign_rider" | "confirm_handover" | "confirm_cash" | "pay";
 export declare function isUnpaid(order: SellerOrder): boolean;
 export declare function isCancellable(status: string): boolean;

package/dist/utils/order-transitions.js

@@ -19,6 +19,20 @@ export const CANCELLABLE_STATUSES = [
     "ready",
 ];
 export const PIPELINE = ["pending", "accepted", "preparing", "ready", "delivered"];
+/**
+ * Derives hierarchical stage states for `current` over `steps`
+ * (defaults to PIPELINE). Stages before the current index are `done`,
+ * the current index is `current`, later stages are `upcoming`.
+ * Unknown statuses (e.g. cancelled, awaiting_payment) yield all `upcoming`
+ * so callers can apply their own mapping first.
+ */
+export function stageStatuses(current, steps = PIPELINE) {
+    const idx = steps.indexOf(current);
+    return steps.map((status, i) => ({
+        status,
+        state: idx < 0 || i > idx ? "upcoming" : i === idx ? "current" : "done",
+    }));
+}
 // ── Helpers ───────────────────────────────────────────────────────────────
 export function isUnpaid(order) {
     const o = order;

package/dist/validation/offline.d.ts

@@ -19,6 +19,8 @@ export declare function validateMenuItemInput(input: {
     categoryId?: unknown;
     variants?: Array<{
         name?: unknown;
+        price?: unknown;
+        price_minor?: unknown;
     }>;
     extras?: Array<{
         name?: unknown;

package/dist/validation/offline.js

@@ -41,6 +41,12 @@ export function validateMenuItemInput(input) {
     for (const v of input.variants ?? []) {
         if (!v || typeof v.name !== "string" || !v.name.trim())
             fail("variants", "Variant name is required", details);
+        // Absolute variant price mirrors backend (must be 0 or more when given).
+        // Accepts both envelope shape (price) and form shape (price_minor).
+        const vp = v.price ?? v.price_minor;
+        if (vp !== undefined && (typeof vp !== "number" || !Number.isFinite(vp) || vp < 0)) {
+            fail("variants", "Variant price must be 0 or more", details);
+        }
     }
     for (const e of input.extras ?? []) {
         if (!e || typeof e.name !== "string" || !e.name.trim())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teincfood/core",
-  "version": "0.9.5",
+  "version": "0.9.8",
   "description": "TeincFood shared offline-first core — types, sync engine, local DB, reference data, and repositories for mobile + desktop",
   "type": "module",
   "main": "dist/index.js",