sahab-utils 1.7.7 → 1.7.9

package/dist/constants/types.d.ts

@@ -1,4 +1,5 @@
 import { DocumentReference, GeoPoint, Timestamp } from 'firebase/firestore';
+import type { PushTransport } from '../ts/push';
 export type GeoPointType = GeoPoint;
 export type TimestampType = Timestamp;
 export type DistenceDueration = {
@@ -813,6 +814,10 @@ export type AppSettings = {
     cashback?: CashbackOffer;
     /** Kill switch for the order Live Activity / Android Live Update pushes. Off unless true. */
     liveActivitiesEnabled?: boolean;
+    /** Which transport delivers push: OneSignal (default when unset), FCM/APNs per recipient that has a token, or FCM only. */
+    pushTransport?: PushTransport;
+    /** Kill switch for staff push broadcasts. Off unless true; test sends to the dev team still work. */
+    broadcastEnabled?: boolean;
 };
 export type OrderReview = {
     ratingId: string;

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export * from './constants/types';
+export * from './ts/broadcast';
 export * from './ts/calcs';
 export * from './ts/cashback';
 export * from './ts/gifts';
 export * from './ts/loyalty';
 export * from './ts/orderActivity';
+export * from './ts/push';
 export * from './ts/utils';
 export * from './ts/wheel';

package/dist/index.js

@@ -15,10 +15,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./constants/types"), exports);
+__exportStar(require("./ts/broadcast"), exports);
 __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/push"), exports);
 __exportStar(require("./ts/utils"), exports);
 __exportStar(require("./ts/wheel"), exports);

package/dist/ts/broadcast.d.ts

@@ -0,0 +1,69 @@
+import { AppSettings, TimestampType } from '../constants/types';
+export type BilingualText = {
+    en: string;
+    ar: string;
+};
+export declare const BROADCAST_LIMITS: {
+    readonly titleMax: 50;
+    readonly bodyMax: 180;
+    readonly minLeadMs: number;
+    readonly maxLeadMs: number;
+    readonly hourlyCapPerStaff: 10;
+};
+export type BroadcastProviderRole = 'owner' | 'driver';
+export type BroadcastAudience = {
+    app: 'client';
+    language?: 'ar' | 'en';
+} | {
+    app: 'provider';
+    roles: BroadcastProviderRole[];
+};
+export type BroadcastMessage = {
+    title: BilingualText;
+    body: BilingualText;
+};
+export type BroadcastRequest = {
+    /** A UUID the page makes per send; the server uses it as the record id, so a retry is idempotent. */
+    clientRequestId: string;
+    audience: BroadcastAudience;
+    message: BroadcastMessage;
+    scheduleAtMs?: number;
+    /** Device count from the preview; the server refuses when the audience has moved past the tolerance. */
+    expectedDeviceCount: number;
+};
+/** Counts only, never uids or tokens. */
+export type BroadcastPreview = {
+    deviceCount: number;
+    userCount: number;
+};
+export type BroadcastStatus = 'scheduled' | 'sending' | 'sent' | 'cancelled' | 'failed';
+/** `push_broadcasts/{clientRequestId}` — also the audit log. */
+export type BroadcastRecord = {
+    id: string;
+    audience: BroadcastAudience;
+    message: BroadcastMessage;
+    status: BroadcastStatus;
+    createdBy: string;
+    createdAt: TimestampType;
+    scheduleAt?: TimestampType;
+    startedAt?: TimestampType;
+    finishedAt?: TimestampType;
+    deviceCount: number;
+    userCount: number;
+    /** FCM accepted the message; not proof a device displayed it. */
+    successCount?: number;
+    failureCount?: number;
+    isTest?: boolean;
+    /** Scheduled sends only; never returned to the browser. */
+    runToken?: string;
+    taskName?: string;
+    error?: string;
+};
+/** Returns human-readable errors; an empty array means valid. Never throws on bad input. */
+export declare const validateBroadcastRequest: (req: unknown, nowMs: number) => string[];
+/** A preview that has gone stale is refused: within 2% of the expected count, never tighter than 5 devices. */
+export declare const broadcastCountTolerated: (expected: number, actual: number) => boolean;
+export declare const broadcastConfirmPhrase: (deviceCount: number) => string;
+/** Broadcasts never use the provider new-order channel, which plays the horn. */
+export declare const broadcastAndroidChannel: (app: "client" | "provider") => string;
+export declare const isBroadcastEnabled: (settings?: Pick<AppSettings, "broadcastEnabled"> | null) => boolean;

package/dist/ts/broadcast.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBroadcastEnabled = exports.broadcastAndroidChannel = exports.broadcastConfirmPhrase = exports.broadcastCountTolerated = exports.validateBroadcastRequest = exports.BROADCAST_LIMITS = void 0;
+const push_1 = require("./push");
+// maxLeadMs is Cloud Tasks' 30-day scheduling horizon; title/body sized for lock-screen truncation.
+exports.BROADCAST_LIMITS = { titleMax: 50, bodyMax: 180, minLeadMs: 5 * 60000, maxLeadMs: 30 * 24 * 3600000, hourlyCapPerStaff: 10 };
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// eslint-disable-next-line no-control-regex
+const CONTROL_ANY = /[\u0000-\u001f\u007f]/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_NOT_NEWLINE = /[\u0000-\u0009\u000b-\u001f\u007f]/;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function validateText(label, value, max, allowNewline, errors) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return errors.push(`${label} is required.`);
+    if (value.trim().length > max)
+        errors.push(`${label} is longer than ${max} characters.`);
+    if ((allowNewline ? CONTROL_NOT_NEWLINE : CONTROL_ANY).test(value))
+        errors.push(`${label} contains control characters.`);
+}
+function validateAudience(audience, errors) {
+    if (!isObject(audience))
+        return errors.push('Audience is required.');
+    if (audience.app === 'client') {
+        if (audience.language !== undefined && audience.language !== 'ar' && audience.language !== 'en')
+            errors.push('Language must be ar or en.');
+        return;
+    }
+    if (audience.app === 'provider') {
+        const roles = audience.roles;
+        const valid = Array.isArray(roles) && roles.length >= 1 && roles.length <= 2 && roles.every((r) => r === 'owner' || r === 'driver') && new Set(roles).size === roles.length;
+        if (!valid)
+            errors.push('Choose owners, drivers, or both.');
+        return;
+    }
+    errors.push('Audience must be customers or providers.');
+}
+/** Returns human-readable errors; an empty array means valid. Never throws on bad input. */
+const validateBroadcastRequest = (req, nowMs) => {
+    if (!isObject(req))
+        return ['Request is required.'];
+    const errors = [];
+    if (typeof req.clientRequestId !== 'string' || !UUID.test(req.clientRequestId))
+        errors.push('Request id must be a UUID.');
+    validateAudience(req.audience, errors);
+    const message = isObject(req.message) ? req.message : undefined;
+    const title = message && isObject(message.title) ? message.title : undefined;
+    const body = message && isObject(message.body) ? message.body : undefined;
+    validateText('English title', title === null || title === void 0 ? void 0 : title.en, exports.BROADCAST_LIMITS.titleMax, false, errors);
+    validateText('Arabic title', title === null || title === void 0 ? void 0 : title.ar, exports.BROADCAST_LIMITS.titleMax, false, errors);
+    validateText('English body', body === null || body === void 0 ? void 0 : body.en, exports.BROADCAST_LIMITS.bodyMax, true, errors);
+    validateText('Arabic body', body === null || body === void 0 ? void 0 : body.ar, exports.BROADCAST_LIMITS.bodyMax, true, errors);
+    const count = req.expectedDeviceCount;
+    if (typeof count !== 'number' || !Number.isInteger(count) || count < 1)
+        errors.push('Preview the audience first: it has no devices to reach.');
+    if (req.scheduleAtMs !== undefined) {
+        const at = req.scheduleAtMs;
+        if (typeof at !== 'number' || !Number.isFinite(at))
+            errors.push('Schedule time is invalid.');
+        else if (at < nowMs + exports.BROADCAST_LIMITS.minLeadMs)
+            errors.push('Schedule at least 5 minutes from now.');
+        else if (at > nowMs + exports.BROADCAST_LIMITS.maxLeadMs)
+            errors.push('Schedule at most 30 days ahead.');
+    }
+    return errors;
+};
+exports.validateBroadcastRequest = validateBroadcastRequest;
+/** A preview that has gone stale is refused: within 2% of the expected count, never tighter than 5 devices. */
+const broadcastCountTolerated = (expected, actual) => Math.abs(expected - actual) <= Math.max(5, Math.floor(expected * 0.02));
+exports.broadcastCountTolerated = broadcastCountTolerated;
+const broadcastConfirmPhrase = (deviceCount) => `SEND ${deviceCount}`;
+exports.broadcastConfirmPhrase = broadcastConfirmPhrase;
+/** Broadcasts never use the provider new-order channel, which plays the horn. */
+const broadcastAndroidChannel = (app) => (app === 'client' ? push_1.ANDROID_CHANNEL.client : push_1.ANDROID_CHANNEL.provider);
+exports.broadcastAndroidChannel = broadcastAndroidChannel;
+const isBroadcastEnabled = (settings) => (settings === null || settings === void 0 ? void 0 : settings.broadcastEnabled) === true;
+exports.isBroadcastEnabled = isBroadcastEnabled;

package/dist/ts/orderActivity.d.ts

@@ -9,7 +9,7 @@ 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. */
+/** The id both the 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;

package/dist/ts/orderActivity.js

@@ -20,7 +20,7 @@ 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. */
+/** The id both the 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. */

package/dist/ts/push.d.ts

@@ -0,0 +1,80 @@
+import { AppSettings, TimestampType } from '../constants/types';
+import { OrderActivityContent } from './orderActivity';
+export type PushApp = 'client' | 'provider';
+export type PushRole = 'customer' | 'owner' | 'driver';
+export type PushPlatform = 'ios' | 'android';
+export type PushTransport = 'onesignal' | 'auto' | 'fcm';
+export type ApnsEnvironment = 'sandbox' | 'production';
+export type LiveNotificationKind = 'start' | 'update' | 'end';
+export type PushActivityEntry = {
+    state: 'pending' | 'started' | 'ended';
+    leaseUntil?: TimestampType;
+    pushToken?: string;
+    startedAt?: TimestampType;
+    endedAt?: TimestampType;
+};
+/** `pushTokens/{sha256(token)}`. `uid` is what the server addresses; `authUid` is the verified Firebase uid that registered it. */
+export type PushTokenDoc = {
+    token: string;
+    app: PushApp;
+    role: PushRole;
+    platform: PushPlatform;
+    language: 'ar' | 'en';
+    uid: string;
+    /** Drivers only: the carwash they belong to, so a staff broadcast can check the driver is still active. */
+    providerUid?: string;
+    authUid: string;
+    apnsEnvironment?: ApnsEnvironment;
+    pushToStartToken?: string;
+    appVersion?: string;
+    /** Keyed by `orderActivityId`; entries ended more than 7 days ago are dropped on write. */
+    activities?: Record<string, PushActivityEntry>;
+    createdAt: TimestampType;
+    updatedAt: TimestampType;
+    /** Firestore TTL field: now + 90 days, refreshed on every register. */
+    expireAt: TimestampType;
+};
+export type RegisterPushTokenBody = Pick<PushTokenDoc, 'token' | 'app' | 'uid' | 'role' | 'platform' | 'language' | 'apnsEnvironment' | 'pushToStartToken' | 'appVersion'> & {
+    /** Required when `role` is `driver`: the carwash the driver belongs to, so the server can phone-match them. */
+    providerUid?: string;
+    /** The token this device held before a refresh; the server deletes it when the same caller owns it. */
+    previousToken?: string;
+};
+export type UnregisterPushTokenBody = {
+    token: string;
+    uid: string;
+};
+export type RegisterActivityTokenBody = {
+    token: string;
+    activityId: string;
+    pushToken: string;
+};
+export declare const PUSH_TOKENS_COLLECTION = "pushTokens";
+export declare const ANDROID_CHANNEL: {
+    readonly client: "orders";
+    readonly providerNewOrder: "new-orders";
+    readonly provider: "general";
+};
+export declare const APNS_LIVE_ACTIVITY_TOPIC_SUFFIX = ".push-type.liveactivity";
+export declare const LIVE_NOTIFICATION_DATA_KEY = "live_notification";
+/** An absent or unrecognised value is `onesignal`, so the switch defaults to today's behaviour. */
+export declare const pushTransportOf: (settings?: Pick<AppSettings, "pushTransport"> | null) => PushTransport;
+export declare const choosePushTransport: (mode: PushTransport, hasTokens: boolean) => "onesignal" | "fcm";
+export declare const buildLiveNotification: (kind: LiveNotificationKind, orderId: string, content: OrderActivityContent) => {
+    key: string;
+    event: LiveNotificationKind;
+    event_attributes: {
+        orderId: string;
+        url: string;
+    };
+    event_updates: {
+        stepIndex: number;
+        stepCount: number;
+        progress: number;
+        title: string;
+        subtitle: string;
+    };
+};
+/** FCM data values must be strings, so the notification travels as one JSON string. */
+export declare const buildLiveNotificationData: (kind: LiveNotificationKind, orderId: string, content: OrderActivityContent) => Record<string, string>;
+export declare const sanitizePushUids: (uids: ReadonlyArray<string | null | undefined>) => string[];

package/dist/ts/push.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizePushUids = exports.buildLiveNotificationData = exports.buildLiveNotification = exports.choosePushTransport = exports.pushTransportOf = exports.LIVE_NOTIFICATION_DATA_KEY = exports.APNS_LIVE_ACTIVITY_TOPIC_SUFFIX = exports.ANDROID_CHANNEL = exports.PUSH_TOKENS_COLLECTION = void 0;
+const orderActivity_1 = require("./orderActivity");
+exports.PUSH_TOKENS_COLLECTION = 'pushTokens';
+exports.ANDROID_CHANNEL = { client: 'orders', providerNewOrder: 'new-orders', provider: 'general' };
+exports.APNS_LIVE_ACTIVITY_TOPIC_SUFFIX = '.push-type.liveactivity';
+exports.LIVE_NOTIFICATION_DATA_KEY = 'live_notification';
+const PUSH_TRANSPORTS = ['onesignal', 'auto', 'fcm'];
+/** An absent or unrecognised value is `onesignal`, so the switch defaults to today's behaviour. */
+const pushTransportOf = (settings) => {
+    const mode = settings === null || settings === void 0 ? void 0 : settings.pushTransport;
+    return mode && PUSH_TRANSPORTS.includes(mode) ? mode : 'onesignal';
+};
+exports.pushTransportOf = pushTransportOf;
+const choosePushTransport = (mode, hasTokens) => {
+    if (mode === 'fcm')
+        return 'fcm';
+    if (mode === 'auto' && hasTokens)
+        return 'fcm';
+    return 'onesignal';
+};
+exports.choosePushTransport = choosePushTransport;
+const buildLiveNotification = (kind, orderId, content) => ({
+    key: (0, orderActivity_1.orderActivityId)(orderId),
+    event: kind,
+    event_attributes: { orderId, url: (0, orderActivity_1.orderDeepLink)(orderId) },
+    event_updates: { stepIndex: content.stepIndex, stepCount: orderActivity_1.ORDER_ACTIVITY_STEP_COUNT, progress: content.progress, title: content.title, subtitle: content.subtitle },
+});
+exports.buildLiveNotification = buildLiveNotification;
+/** FCM data values must be strings, so the notification travels as one JSON string. */
+const buildLiveNotificationData = (kind, orderId, content) => ({
+    [exports.LIVE_NOTIFICATION_DATA_KEY]: JSON.stringify((0, exports.buildLiveNotification)(kind, orderId, content)),
+});
+exports.buildLiveNotificationData = buildLiveNotificationData;
+const sanitizePushUids = (uids) => [...new Set(uids.filter((uid) => typeof uid === 'string' && uid.length > 0))];
+exports.sanitizePushUids = sanitizePushUids;

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "sahab-utils",
-	"version": "1.7.7",
+	"version": "1.7.9",
 	"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 && node tests/orderActivity.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 && node tests/push.test.js && node tests/broadcast.test.js"
 	},
 	"repository": {
 		"type": "git",