sahab-utils 1.7.6 → 1.7.7

package/dist/constants/types.d.ts

@@ -811,6 +811,8 @@ export type AppSettings = {
     minimumBalanceToUse?: number;
     /** The one live cashback campaign, if any — nested here rather than its own collection. */
     cashback?: CashbackOffer;
+    /** Kill switch for the order Live Activity / Android Live Update pushes. Off unless true. */
+    liveActivitiesEnabled?: boolean;
 };
 export type OrderReview = {
     ratingId: string;

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export * from './ts/calcs';
 export * from './ts/cashback';
 export * from './ts/gifts';
 export * from './ts/loyalty';
+export * from './ts/orderActivity';
 export * from './ts/utils';
 export * from './ts/wheel';

package/dist/index.js

@@ -19,5 +19,6 @@ __exportStar(require("./ts/calcs"), exports);
 __exportStar(require("./ts/cashback"), exports);
 __exportStar(require("./ts/gifts"), exports);
 __exportStar(require("./ts/loyalty"), exports);
+__exportStar(require("./ts/orderActivity"), exports);
 __exportStar(require("./ts/utils"), exports);
 __exportStar(require("./ts/wheel"), exports);

package/dist/ts/orderActivity.d.ts

@@ -0,0 +1,74 @@
+import { Order, OrderStatus } from '../constants/types';
+export declare const ORDER_ACTIVITY_TYPE = "LiveActivityAttributes";
+export declare const ORDER_ACTIVITY_NAME = "orderStatus";
+export declare const ORDER_ACTIVITY_STEP_COUNT = 4;
+/** The activity (and the widget's live state) starts this long before the booked time. */
+export declare const ORDER_LIVE_WINDOW_MS: number;
+/** How long the widget keeps saying the car is clean after the order finishes. */
+export declare const ORDER_DONE_VISIBLE_MS: number;
+export declare const ORDER_ACTIVITY_STALE_MS: number;
+/** How long the widget trusts a status it was last told while the app was closed; after that it asks the customer to open the app. */
+export declare const ORDER_WIDGET_FRESH_MS: number;
+/** The id both OneSignal (server) and the app's token registration use for one order's activity. */
+export declare const orderActivityId: (orderId: string) => string;
+/** The deep link a push-started activity carries in its static attributes; the app reads the order id back out of it. */
+export declare const orderDeepLink: (orderId: string) => string;
+export declare const orderIdFromDeepLink: (url?: string) => string | undefined;
+export type OrderActivityStep = 'SCHEDULED' | 'ON_THE_WAY' | 'IN_PROGRESS' | 'DONE' | 'CANCELLED';
+export type OrderActivityLang = 'ar' | 'en';
+export type OrderActivityContent = {
+    orderId: string;
+    step: OrderActivityStep;
+    stepIndex: number;
+    progress: number;
+    isTerminal: boolean;
+    isRtl: boolean;
+    providerName: string;
+    orderTimeMs: number;
+    orderTimeText: string;
+    title: string;
+    subtitle: string;
+    a11yLabel: string;
+    updatedAtMs: number;
+};
+export declare const ORDER_ACTIVITY_TEXT: {
+    titles: Record<OrderActivityLang, Record<OrderActivityStep, string>>;
+    stepPhrase: {
+        en: (n: number, label: string) => string;
+        ar: (n: number, label: string) => string;
+    };
+};
+export declare const ACTIVE_ORDER_STATUSES: OrderStatus[];
+export declare function orderActivityLang(language?: string): OrderActivityLang;
+export declare function isOrderActive(status?: OrderStatus): boolean;
+export declare function orderActivityStep(status?: OrderStatus): OrderActivityStep | null;
+/** Whether an order deserves a Live Activity right now: on the way / washing, or accepted and due within the live window. */
+export declare function isOrderLive(status: OrderStatus | undefined, orderDateMs: number, nowMs: number): boolean;
+/** What every surface (Live Activity, widget, Android notification) shows for an order. Never includes the driver's name. */
+export declare function buildOrderActivityContent(order: Pick<Order, 'orderId' | 'orderStatus' | 'providerName'>, orderDateMs: number, lang: OrderActivityLang, nowMs?: number): OrderActivityContent | null;
+export type OrderWidgetState = 'NONE' | 'UPCOMING' | 'LIVE' | 'DONE' | 'STALE';
+/** An order as the widget sees it: dates already converted to epoch milliseconds by the caller. */
+export type OrderWidgetInput = Pick<Order, 'orderId' | 'orderStatus' | 'providerName'> & {
+    orderDateMs: number;
+    finishMs?: number;
+};
+export type OrderWidgetContent = {
+    state: OrderWidgetState;
+    orderId: string;
+    title: string;
+    subtitle: string;
+    /** "+2 more" when the customer has other active orders, otherwise empty. */
+    moreText: string;
+    stepIndex: number;
+    progress: number;
+    a11yLabel: string;
+};
+/** The one order the widget (and a single-slot surface) should talk about: live orders first, most advanced first, then the soonest booking. */
+export declare function pickPrimaryOrder<T extends Pick<OrderWidgetInput, 'orderStatus' | 'orderDateMs'>>(orders: T[], nowMs: number): T | null;
+/**
+ * What the home-screen widget says at `nowMs`: the primary active order (upcoming until it is live), "your car is clean"
+ * for a while after the last finished order, otherwise an invitation to book.
+ */
+export declare function buildOrderWidgetContent(active: OrderWidgetInput[], lastFinished: OrderWidgetInput | null, lang: OrderActivityLang, nowMs?: number, syncedAtMs?: number): OrderWidgetContent;
+/** Future moments at which the widget's text changes on its own (a booking turning live, "clean" expiring, a status going stale), soonest first. */
+export declare function orderWidgetChangeTimes(active: OrderWidgetInput[], lastFinished: OrderWidgetInput | null, nowMs?: number): number[];

package/dist/ts/orderActivity.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVE_ORDER_STATUSES = exports.ORDER_ACTIVITY_TEXT = exports.orderIdFromDeepLink = exports.orderDeepLink = exports.orderActivityId = exports.ORDER_WIDGET_FRESH_MS = exports.ORDER_ACTIVITY_STALE_MS = exports.ORDER_DONE_VISIBLE_MS = exports.ORDER_LIVE_WINDOW_MS = exports.ORDER_ACTIVITY_STEP_COUNT = exports.ORDER_ACTIVITY_NAME = exports.ORDER_ACTIVITY_TYPE = void 0;
+exports.orderActivityLang = orderActivityLang;
+exports.isOrderActive = isOrderActive;
+exports.orderActivityStep = orderActivityStep;
+exports.isOrderLive = isOrderLive;
+exports.buildOrderActivityContent = buildOrderActivityContent;
+exports.pickPrimaryOrder = pickPrimaryOrder;
+exports.buildOrderWidgetContent = buildOrderWidgetContent;
+exports.orderWidgetChangeTimes = orderWidgetChangeTimes;
+const types_1 = require("../constants/types");
+exports.ORDER_ACTIVITY_TYPE = 'LiveActivityAttributes';
+exports.ORDER_ACTIVITY_NAME = 'orderStatus';
+exports.ORDER_ACTIVITY_STEP_COUNT = 4;
+/** The activity (and the widget's live state) starts this long before the booked time. */
+exports.ORDER_LIVE_WINDOW_MS = 15 * 60 * 1000;
+/** How long the widget keeps saying the car is clean after the order finishes. */
+exports.ORDER_DONE_VISIBLE_MS = 2 * 60 * 60 * 1000;
+exports.ORDER_ACTIVITY_STALE_MS = 3 * 60 * 60 * 1000;
+/** How long the widget trusts a status it was last told while the app was closed; after that it asks the customer to open the app. */
+exports.ORDER_WIDGET_FRESH_MS = 45 * 60 * 1000;
+/** The id both OneSignal (server) and the app's token registration use for one order's activity. */
+const orderActivityId = (orderId) => `order-${orderId}`;
+exports.orderActivityId = orderActivityId;
+/** The deep link a push-started activity carries in its static attributes; the app reads the order id back out of it. */
+const orderDeepLink = (orderId) => `sahab://orders/${orderId}`;
+exports.orderDeepLink = orderDeepLink;
+const orderIdFromDeepLink = (url) => { var _a; return (_a = /^sahab:\/\/orders\/([^/?#]+)/.exec(url !== null && url !== void 0 ? url : '')) === null || _a === void 0 ? void 0 : _a[1]; };
+exports.orderIdFromDeepLink = orderIdFromDeepLink;
+const STEP_INDEX = { SCHEDULED: 0, ON_THE_WAY: 1, IN_PROGRESS: 2, DONE: 3, CANCELLED: 0 };
+// Titles only: the subtitle is built from the provider name (and the time while still scheduled).
+const TITLES = {
+    en: {
+        SCHEDULED: 'Wash booked',
+        ON_THE_WAY: 'On the way',
+        IN_PROGRESS: 'Washing your car',
+        DONE: 'Wash complete',
+        CANCELLED: 'Order cancelled',
+    },
+    ar: {
+        SCHEDULED: 'تم حجز الغسيل',
+        ON_THE_WAY: 'في الطريق إليك',
+        IN_PROGRESS: 'جاري غسل سيارتك',
+        DONE: 'اكتمل الغسيل',
+        CANCELLED: 'تم إلغاء الطلب',
+    },
+};
+const SOON_TITLE = { en: 'Wash starting soon', ar: 'غسيلك على وشك البدء' };
+exports.ORDER_ACTIVITY_TEXT = {
+    titles: TITLES,
+    stepPhrase: {
+        en: (n, label) => `Step ${n} of ${exports.ORDER_ACTIVITY_STEP_COUNT}: ${label}`,
+        ar: (n, label) => `الخطوة ${n} من ${exports.ORDER_ACTIVITY_STEP_COUNT}: ${label}`,
+    },
+};
+exports.ACTIVE_ORDER_STATUSES = [types_1.OrderStatus.PENDING, types_1.OrderStatus.CONFIRMED, types_1.OrderStatus.STARTED, types_1.OrderStatus.IN_PROGRESS];
+// First-strong isolate / pop-directional-isolate: keeps a Latin provider name from reordering Arabic text.
+const FSI = '⁨';
+const PDI = '⁩';
+function orderActivityLang(language) {
+    return language === 'ar' ? 'ar' : 'en';
+}
+function isOrderActive(status) {
+    return status !== undefined && exports.ACTIVE_ORDER_STATUSES.includes(status);
+}
+function orderActivityStep(status) {
+    switch (status) {
+        case types_1.OrderStatus.PENDING:
+        case types_1.OrderStatus.CONFIRMED:
+            return 'SCHEDULED';
+        case types_1.OrderStatus.STARTED:
+            return 'ON_THE_WAY';
+        case types_1.OrderStatus.IN_PROGRESS:
+            return 'IN_PROGRESS';
+        case types_1.OrderStatus.COMPLETED:
+        case types_1.OrderStatus.RATED:
+            return 'DONE';
+        case types_1.OrderStatus.CANCELLED:
+        case types_1.OrderStatus.REJECTED:
+        case types_1.OrderStatus.EXPIRED:
+            return 'CANCELLED';
+        default:
+            return null;
+    }
+}
+const isWithinLiveWindow = (orderDateMs, nowMs) => orderDateMs - nowMs <= exports.ORDER_LIVE_WINDOW_MS;
+/** Whether an order deserves a Live Activity right now: on the way / washing, or accepted and due within the live window. */
+function isOrderLive(status, orderDateMs, nowMs) {
+    const step = orderActivityStep(status);
+    if (step === 'ON_THE_WAY' || step === 'IN_PROGRESS')
+        return true;
+    // The lower bound matches the activity's stale date: a no-show booking stops claiming "starting soon" after 3 h.
+    return (status === types_1.OrderStatus.CONFIRMED &&
+        hasDate(orderDateMs) &&
+        isWithinLiveWindow(orderDateMs, nowMs) &&
+        nowMs - orderDateMs <= exports.ORDER_ACTIVITY_STALE_MS);
+}
+// Gregorian and Latin digits pinned: ar-SA otherwise defaults to Hijri on some devices, and every surface must agree.
+const localeOf = (lang) => (lang === 'ar' ? 'ar-SA-u-ca-gregory-nu-latn' : 'en-US');
+const hasDate = (ms) => Number.isFinite(ms) && ms > 0;
+function formatOrderTime(orderTimeMs, lang) {
+    if (!hasDate(orderTimeMs))
+        return '';
+    return new Intl.DateTimeFormat(localeOf(lang), { timeZone: 'Asia/Riyadh', hour: 'numeric', minute: '2-digit' }).format(new Date(orderTimeMs));
+}
+/** What every surface (Live Activity, widget, Android notification) shows for an order. Never includes the driver's name. */
+function buildOrderActivityContent(order, orderDateMs, lang, nowMs = Date.now()) {
+    var _a, _b, _c;
+    const step = orderActivityStep(order.orderStatus);
+    if (!step || !order.orderId)
+        return null;
+    const stepIndex = STEP_INDEX[step];
+    const isCancelled = step === 'CANCELLED';
+    const providerName = ((_a = order.providerName) === null || _a === void 0 ? void 0 : _a[lang]) || ((_b = order.providerName) === null || _b === void 0 ? void 0 : _b.en) || ((_c = order.providerName) === null || _c === void 0 ? void 0 : _c.ar) || '';
+    const orderTimeText = formatOrderTime(orderDateMs, lang);
+    const title = step === 'SCHEDULED' && isWithinLiveWindow(orderDateMs, nowMs) ? SOON_TITLE[lang] : TITLES[lang][step];
+    const shownProvider = providerName && lang === 'ar' ? `${FSI}${providerName}${PDI}` : providerName;
+    const subtitle = step === 'SCHEDULED' && shownProvider ? `${shownProvider} · ${orderTimeText}` : shownProvider;
+    return {
+        orderId: order.orderId,
+        step,
+        stepIndex,
+        progress: stepIndex / (exports.ORDER_ACTIVITY_STEP_COUNT - 1),
+        isTerminal: step === 'DONE' || isCancelled,
+        isRtl: lang === 'ar',
+        providerName,
+        orderTimeMs: orderDateMs,
+        orderTimeText,
+        title,
+        subtitle,
+        a11yLabel: [isCancelled ? title : exports.ORDER_ACTIVITY_TEXT.stepPhrase[lang](stepIndex + 1, title), subtitle].filter(Boolean).join('. '),
+        updatedAtMs: nowMs,
+    };
+}
+// "and N more bookings", with the Arabic dual / few / many forms.
+const ARABIC_MORE = {
+    one: () => 'وحجز آخر',
+    two: () => 'وحجزان آخران',
+    few: (n) => `و${n} حجوزات أخرى`,
+    many: (n) => `و${n} حجزًا آخر`,
+    other: (n) => `و${n} حجز آخر`,
+};
+const arabicPlural = (n) => {
+    const mod100 = n % 100;
+    if (n === 1)
+        return 'one';
+    if (n === 2)
+        return 'two';
+    if (mod100 >= 3 && mod100 <= 10)
+        return 'few';
+    return mod100 >= 11 ? 'many' : 'other';
+};
+const arabicMore = (n) => ARABIC_MORE[arabicPlural(n)](n);
+const WIDGET_TEXT = {
+    en: {
+        none: 'No active booking',
+        book: 'Book a wash',
+        upcoming: 'Your next wash',
+        done: 'Your car is now clean',
+        stale: 'Check your booking',
+        staleHint: 'Open Sahab for the latest status',
+        more: (n) => `+${n} more`,
+    },
+    ar: {
+        none: 'لا يوجد حجز نشط',
+        book: 'احجز غسلة',
+        upcoming: 'غسلتك القادمة',
+        done: 'سيارتك الآن نظيفة',
+        stale: 'تحقق من حجزك',
+        staleHint: 'افتح سحاب لمعرفة آخر حالة',
+        more: arabicMore,
+    },
+};
+const providerOf = (order, lang) => {
+    var _a, _b, _c;
+    const name = ((_a = order.providerName) === null || _a === void 0 ? void 0 : _a[lang]) || ((_b = order.providerName) === null || _b === void 0 ? void 0 : _b.en) || ((_c = order.providerName) === null || _c === void 0 ? void 0 : _c.ar) || '';
+    return name && lang === 'ar' ? `${FSI}${name}${PDI}` : name;
+};
+// Today shows just the time; any other day adds the weekday and date so "5:30 PM" is never ambiguous.
+function formatOrderWhen(orderTimeMs, lang, nowMs) {
+    if (!hasDate(orderTimeMs))
+        return '';
+    const day = (ms) => new Intl.DateTimeFormat('en-CA', { timeZone: 'Asia/Riyadh' }).format(new Date(ms));
+    if (day(orderTimeMs) === day(nowMs))
+        return formatOrderTime(orderTimeMs, lang);
+    return new Intl.DateTimeFormat(localeOf(lang), {
+        timeZone: 'Asia/Riyadh',
+        weekday: 'short',
+        day: 'numeric',
+        month: 'short',
+        hour: 'numeric',
+        minute: '2-digit',
+    }).format(new Date(orderTimeMs));
+}
+const LIVE_RANK = { IN_PROGRESS: 2, ON_THE_WAY: 1, SCHEDULED: 0 };
+/** The one order the widget (and a single-slot surface) should talk about: live orders first, most advanced first, then the soonest booking. */
+function pickPrimaryOrder(orders, nowMs) {
+    const live = orders.filter((o) => isOrderLive(o.orderStatus, o.orderDateMs, nowMs));
+    const stepRank = (o) => { var _a, _b; return (_b = LIVE_RANK[(_a = orderActivityStep(o.orderStatus)) !== null && _a !== void 0 ? _a : 'SCHEDULED']) !== null && _b !== void 0 ? _b : 0; };
+    const pool = live.length ? live : orders;
+    return pool.reduce((best, o) => {
+        if (!best)
+            return o;
+        if (live.length)
+            return stepRank(o) > stepRank(best) || (stepRank(o) === stepRank(best) && o.orderDateMs < best.orderDateMs) ? o : best;
+        return o.orderDateMs < best.orderDateMs ? o : best;
+    }, null);
+}
+// A status the app saw at `syncedAtMs` can move on without the widget hearing about it (only pushes reach the closed app),
+// so on the way / washing is trusted for a while after the sync and a booking for a while after its time.
+const widgetFreshUntil = (o, syncedAtMs) => {
+    const step = orderActivityStep(o.orderStatus);
+    const from = step === 'ON_THE_WAY' || step === 'IN_PROGRESS' ? syncedAtMs : Math.max(syncedAtMs, hasDate(o.orderDateMs) ? o.orderDateMs : 0);
+    return from + exports.ORDER_WIDGET_FRESH_MS;
+};
+/**
+ * What the home-screen widget says at `nowMs`: the primary active order (upcoming until it is live), "your car is clean"
+ * for a while after the last finished order, otherwise an invitation to book.
+ */
+function buildOrderWidgetContent(active, lastFinished, lang, nowMs = Date.now(), syncedAtMs = nowMs) {
+    var _a, _b, _c, _d;
+    const text = WIDGET_TEXT[lang];
+    const primary = pickPrimaryOrder(active, nowMs);
+    const finish = (state, orderId, title, subtitle, stepIndex, moreText = '') => ({
+        state,
+        orderId,
+        title,
+        subtitle,
+        moreText,
+        stepIndex,
+        progress: stepIndex / (exports.ORDER_ACTIVITY_STEP_COUNT - 1),
+        a11yLabel: [title, subtitle, moreText].filter(Boolean).join('. '),
+    });
+    if (primary) {
+        const moreText = active.length > 1 ? text.more(active.length - 1) : '';
+        if (nowMs > widgetFreshUntil(primary, syncedAtMs)) {
+            const provider = providerOf(primary, lang);
+            return finish('STALE', (_a = primary.orderId) !== null && _a !== void 0 ? _a : '', text.stale, provider ? `${provider} · ${text.staleHint}` : text.staleHint, 0, moreText);
+        }
+        if (isOrderLive(primary.orderStatus, primary.orderDateMs, nowMs)) {
+            const c = buildOrderActivityContent({ orderId: primary.orderId, orderStatus: primary.orderStatus, providerName: primary.providerName }, primary.orderDateMs, lang, nowMs);
+            if (c)
+                return finish('LIVE', c.orderId, c.title, c.subtitle, c.stepIndex, moreText);
+        }
+        const provider = providerOf(primary, lang);
+        const when = formatOrderWhen(primary.orderDateMs, lang, nowMs);
+        return finish('UPCOMING', (_b = primary.orderId) !== null && _b !== void 0 ? _b : '', text.upcoming, provider ? `${provider} · ${when}` : when, 0, moreText);
+    }
+    if (lastFinished && nowMs - ((_c = lastFinished.finishMs) !== null && _c !== void 0 ? _c : lastFinished.orderDateMs) <= exports.ORDER_DONE_VISIBLE_MS) {
+        return finish('DONE', (_d = lastFinished.orderId) !== null && _d !== void 0 ? _d : '', text.done, providerOf(lastFinished, lang), exports.ORDER_ACTIVITY_STEP_COUNT - 1);
+    }
+    return finish('NONE', '', text.none, text.book, 0);
+}
+const RIYADH_OFFSET_MS = 3 * 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const nextRiyadhMidnight = (nowMs) => Math.floor((nowMs + RIYADH_OFFSET_MS) / DAY_MS) * DAY_MS + DAY_MS - RIYADH_OFFSET_MS;
+/** Future moments at which the widget's text changes on its own (a booking turning live, "clean" expiring, a status going stale), soonest first. */
+function orderWidgetChangeTimes(active, lastFinished, nowMs = Date.now()) {
+    var _a;
+    const times = active.filter((o) => orderActivityStep(o.orderStatus) === 'SCHEDULED').map((o) => o.orderDateMs - exports.ORDER_LIVE_WINDOW_MS);
+    if (lastFinished)
+        times.push(((_a = lastFinished.finishMs) !== null && _a !== void 0 ? _a : lastFinished.orderDateMs) + exports.ORDER_DONE_VISIBLE_MS + 1);
+    // "Sat 9:00 AM" becomes just "9:00 AM" once the booked day arrives, so the next Riyadh midnight is a change too.
+    if (active.length)
+        times.push(nextRiyadhMidnight(nowMs));
+    active.forEach((o) => times.push(widgetFreshUntil(o, nowMs) + 1));
+    return [...new Set(times)].filter((t) => t > nowMs).sort((a, b) => a - b);
+}

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "sahab-utils",
-	"version": "1.7.6",
+	"version": "1.7.7",
 	"description": "This package contains types and utils functions",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"scripts": {
 		"build": "tsc",
 		"deploy": "npm run build && npm publish",
-		"test": "npm run build && node tests/loyalty.test.js && node tests/gifts.test.js && node tests/cashback.test.js && node tests/utils.test.js && node tests/wheel.test.js && node tests/calcs.test.js"
+		"test": "npm run build && node tests/loyalty.test.js && node tests/gifts.test.js && node tests/cashback.test.js && node tests/utils.test.js && node tests/wheel.test.js && node tests/calcs.test.js && node tests/orderActivity.test.js"
 	},
 	"repository": {
 		"type": "git",