sahab-utils 1.10.0 → 2.0.0

package/dist/constants/types.d.ts

@@ -25,6 +25,16 @@ export type Car = {
     plateLetters: string;
     plateNumber: string;
     imageUrl?: string;
+    /** 'customer' when the customer chose the size of a model Sahab does not know yet; set only by the server. */
+    sizeSource?: 'catalogue' | 'customer';
+    /** The make/model key (`carModelKey`), stored so staff can find every car of one model. */
+    modelKey?: string;
+    verifiedBySahab?: boolean;
+    verifiedSize?: CarSize;
+    verifiedModelKey?: string;
+    verifiedAt?: TimestampType;
+    verifiedBy?: string;
+    sizeBeforeFix?: CarSize;
 };
 export type ClientLocation = {
     locationId: string;
@@ -835,6 +845,8 @@ export type AppSettings = {
     pushTransport?: PushTransport;
     /** Kill switch for staff push broadcasts. Off unless true; test sends to the dev team still work. */
     broadcastEnabled?: boolean;
+    /** Staff push for an order that used a car Sahab has not verified. Off unless true, so deploying does not send one per model already in use. */
+    carReviewAlertsEnabled?: boolean;
 };
 export type OrderReview = {
     ratingId: string;

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './ts/staffAccess';
 export * from './ts/broadcast';
 export * from './ts/capacity';
 export * from './ts/calcs';
+export * from './ts/carCatalogue';
 export * from './ts/cash';
 export * from './ts/cashback';
 export * from './ts/gifts';

package/dist/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./ts/staffAccess"), exports);
 __exportStar(require("./ts/broadcast"), exports);
 __exportStar(require("./ts/capacity"), exports);
 __exportStar(require("./ts/calcs"), exports);
+__exportStar(require("./ts/carCatalogue"), exports);
 __exportStar(require("./ts/cash"), exports);
 __exportStar(require("./ts/cashback"), exports);
 __exportStar(require("./ts/gifts"), exports);

package/dist/ts/carCatalogue.d.ts

@@ -0,0 +1,156 @@
+import { Car, CarSize, TimestampType } from '../constants/types';
+/** Longest model a customer may type under "Other". */
+export declare const CAR_MODEL_MAX_LENGTH = 40;
+/** Longest make, colour or other free text a car request may carry. */
+export declare const CAR_NAME_MAX_LENGTH = 60;
+export declare const CAR_MODEL_STATUSES: readonly ["active", "pending", "declined", "alias"];
+export type CarModelStatus = (typeof CAR_MODEL_STATUSES)[number];
+/** The staff review queues: models awaiting a decision, declined ones, and active ones whose cars are still unverified on orders. */
+export declare const CAR_REVIEW_QUEUES: readonly ["pending", "declined", "needs_fix"];
+export type CarReviewQueue = (typeof CAR_REVIEW_QUEUES)[number];
+/** An alias document counts toward this many per model, so a fix can find every key with one `in` query (Firestore allows 30). */
+export declare const MAX_ALIASES = 29;
+export type CarPickerEntry = {
+    id: string;
+    name: string;
+    size: CarSize;
+};
+/** `car_makes/{makeKey}`. `T` is the timestamp type of whichever Firestore SDK reads or writes it. */
+export type CarMakeDoc<T = TimestampType> = {
+    en: string;
+    ar?: string;
+    picker: CarPickerEntry[];
+    source: 'seed' | 'approved';
+    createdAt?: T;
+    updatedAt?: T;
+    updatedBy?: string;
+};
+/** `car_makes/{makeKey}/car_models/{modelKey}`: a model of any status, or an alias pointing at the active model it stands for. */
+export type CarModelDoc<T = TimestampType> = {
+    makeKey: string;
+    makeEn: string;
+    status: CarModelStatus;
+    name: string;
+    size: CarSize;
+    aliasKeys?: string[];
+    aliases?: string[];
+    aliasOf?: string;
+    source: 'seed' | 'other' | 'order';
+    count: number;
+    ordersCount: number;
+    sizesSeen: Record<string, number>;
+    unverifiedOrdersCount: number;
+    createdAt: T;
+    decidedAt?: T;
+    decidedBy?: string;
+    updatedAt?: T;
+    updatedBy?: string;
+    sizeUpdatedAt?: T;
+};
+export type CarModelSource = CarModelDoc['source'];
+export type CarModelDecision = 'approve' | 'decline' | 'reopen';
+export declare const CAR_QUEUE_SORTS: readonly ["count", "orders", "recent"];
+export type CarQueueSort = (typeof CAR_QUEUE_SORTS)[number];
+/** A model as the staff catalogue lists it; `modelId` is its document id. */
+export type CarCatalogueEntry = {
+    modelId: string;
+    name: string;
+    aliases: string[];
+    size: CarSize;
+    source: CarModelSource;
+};
+/** One row of a staff queue. For `needs_fix`, `requestedSize` is the model's current catalogue size and `typedModel` its name. */
+export type CarQueueRow = {
+    modelKey: string;
+    makeEn: string;
+    typedModel: string;
+    requestedSize: CarSize;
+    count: number;
+    ordersCount: number;
+    unverifiedOrdersCount: number;
+    sizesSeen: Record<string, number>;
+    source: CarModelSource;
+    status: CarReviewQueue;
+    createdAt: string | null;
+    decidedAt: string | null;
+    decidedBy?: string;
+};
+/** What the customer app sends to save a car; the server decides the size of a known model. */
+export type SaveCarRequest = {
+    carId?: string;
+    manufacturer: string;
+    year: string;
+    color: string;
+    plateLetters: string;
+    plateNumber: string;
+    imageUrl?: string;
+    /** A model picked from the list. */
+    modelId?: string;
+    /** A model typed under "Other", with the size the customer chose for it. */
+    model?: string;
+    size?: number;
+};
+/** The size names and what each covers, as the back office shows them (the customer app reads the same wording from its dictionary). */
+export declare const CAR_SIZE_INFO: Record<CarSize, {
+    label: {
+        en: string;
+        ar: string;
+    };
+    description: {
+        en: string;
+        ar: string;
+    };
+}>;
+export declare const isCarSize: (value: unknown) => value is CarSize;
+/** One spelling for a car name: case, accents, Arabic letter variants, Arabic digits, spaces and punctuation all gone. Empty when nothing usable is left. */
+export declare function normalizeCarText(text: unknown): string;
+/** `makeKey__modelKey`: the one place that shape is written. */
+export declare const joinModelKey: (makeKey: string, modelKey: string) => string;
+/** The key a make and model share across cars, review items and fixes; empty when either part is empty. */
+export declare function carModelKey(make: unknown, model: unknown): string;
+export type TypedCarModel = {
+    ok: true;
+    text: string;
+    key: string;
+} | {
+    ok: false;
+    error: 'empty' | 'too_long';
+};
+/** A model typed under "Other", ready to use: trimmed, within the length cap and with a non-empty key. */
+export declare function parseTypedCarModel(make: unknown, text: unknown): TypedCarModel;
+/** Verified only while the car still has the size and model Sahab checked; any edit by the customer makes it unverified again. */
+export declare function isCarVerified(car: Partial<Car> | undefined): boolean;
+/** The active models of a make as the customer picker lists them: sorted by name, never an alias, pending or declined model. */
+export declare function buildPicker(models: ({
+    id: string;
+} & Pick<CarModelDoc, 'status' | 'name' | 'size'>)[]): CarPickerEntry[];
+/** The picker with one active model added, or replaced if it is already there. */
+export declare function withPickerEntry(picker: CarPickerEntry[] | undefined, entry: CarPickerEntry): CarPickerEntry[];
+/** Every key a model's cars may carry: its own and those of the aliases merged into it. */
+export declare function modelKeysOf(model: {
+    id: string;
+    aliasKeys?: string[];
+}): string[];
+/** `makeKey__modelKey` as its two parts, or undefined when it is not that shape. */
+export declare function splitModelKey(key: unknown): {
+    makeKey: string;
+    modelKey: string;
+} | undefined;
+/** The makes list a customer picks from: one small document, so showing it costs a single read. */
+export declare const CAR_CATALOGUE_INDEX_ID = "_index";
+export type CarMakeIndexEntry = {
+    makeKey: string;
+    en: string;
+    ar?: string;
+};
+export type CarMakeIndex = {
+    makes: CarMakeIndexEntry[];
+};
+/** The key of the make a customer typed: the catalogue's own key when the text is a known make's English or Arabic name, else the typed text's key. Empty when nothing usable was typed. */
+export declare function resolveMakeKey(index: CarMakeIndexEntry[] | undefined, typedMake: unknown): string;
+export declare const PLATE_LETTERS_MAX = 3;
+export declare const PLATE_NUMBER_MAX = 4;
+/** Plate letters as stored: English capitals only, at most three; Arabic letters become their plate equivalents. */
+export declare function normalizePlateLetters(text: unknown): string;
+/** Plate digits as stored: Western digits only, at most four. */
+export declare function normalizePlateNumber(text: unknown): string;

package/dist/ts/carCatalogue.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLATE_NUMBER_MAX = exports.PLATE_LETTERS_MAX = exports.CAR_CATALOGUE_INDEX_ID = exports.joinModelKey = exports.isCarSize = exports.CAR_SIZE_INFO = exports.CAR_QUEUE_SORTS = exports.MAX_ALIASES = exports.CAR_REVIEW_QUEUES = exports.CAR_MODEL_STATUSES = exports.CAR_NAME_MAX_LENGTH = exports.CAR_MODEL_MAX_LENGTH = void 0;
+exports.normalizeCarText = normalizeCarText;
+exports.carModelKey = carModelKey;
+exports.parseTypedCarModel = parseTypedCarModel;
+exports.isCarVerified = isCarVerified;
+exports.buildPicker = buildPicker;
+exports.withPickerEntry = withPickerEntry;
+exports.modelKeysOf = modelKeysOf;
+exports.splitModelKey = splitModelKey;
+exports.resolveMakeKey = resolveMakeKey;
+exports.normalizePlateLetters = normalizePlateLetters;
+exports.normalizePlateNumber = normalizePlateNumber;
+const types_1 = require("../constants/types");
+/** Longest model a customer may type under "Other". */
+exports.CAR_MODEL_MAX_LENGTH = 40;
+/** Longest make, colour or other free text a car request may carry. */
+exports.CAR_NAME_MAX_LENGTH = 60;
+exports.CAR_MODEL_STATUSES = ['active', 'pending', 'declined', 'alias'];
+/** The staff review queues: models awaiting a decision, declined ones, and active ones whose cars are still unverified on orders. */
+exports.CAR_REVIEW_QUEUES = ['pending', 'declined', 'needs_fix'];
+/** An alias document counts toward this many per model, so a fix can find every key with one `in` query (Firestore allows 30). */
+exports.MAX_ALIASES = 29;
+exports.CAR_QUEUE_SORTS = ['count', 'orders', 'recent'];
+/** The size names and what each covers, as the back office shows them (the customer app reads the same wording from its dictionary). */
+exports.CAR_SIZE_INFO = {
+    [types_1.CarSize.X_SMALL]: { label: { en: 'Extra Small', ar: 'صغير جداً' }, description: { en: 'Bikes and similar sizes', ar: 'الدراجات النارية، الدبابات، ومايعادلها' } },
+    [types_1.CarSize.SMALL]: { label: { en: 'Small', ar: 'صغير' }, description: { en: 'Sedan, mini, coupe, sport and similar sizes', ar: 'سيارات السيدان، ميني، الكوبيه، السبورت، ومايعادلها' } },
+    [types_1.CarSize.MEDIUM]: { label: { en: 'Medium', ar: 'متوسط' }, description: { en: '5 passengers car, small pickup or similar sizes', ar: 'سيارات بسعة 5 ركاب، وانيت صغير، ومايعادلها' } },
+    [types_1.CarSize.LARGE]: { label: { en: 'Large', ar: 'كبير' }, description: { en: '7 passengers car, large pickup or similar sizes', ar: 'سيارات بسعة 7 ركاب، وانيت كبير، ومايعادلها' } },
+    [types_1.CarSize.X_LARGE]: { label: { en: 'Extra Large', ar: 'كبير جداً' }, description: { en: 'Food trucks, travel trailers and similar sizes', ar: 'الفود ترك، مقطورات السفر، ومايعادلها' } },
+};
+const isCarSize = (value) => Number.isInteger(value) && value >= types_1.CarSize.X_SMALL && value <= types_1.CarSize.X_LARGE;
+exports.isCarSize = isCarSize;
+const ARABIC_DIACRITICS = /[ً-ٰٟـ]/g;
+const LATIN_ACCENTS = /[̀-ͯ]/g;
+const NOT_A_LETTER_OR_DIGIT = /[^a-z0-9ء-ي]/g;
+const westernDigits = (text) => text.replace(/[٠-٩۰-۹]/g, (digit) => String(digit.charCodeAt(0) >= 0x06f0 ? digit.charCodeAt(0) - 0x06f0 : digit.charCodeAt(0) - 0x0660));
+/** One spelling for a car name: case, accents, Arabic letter variants, Arabic digits, spaces and punctuation all gone. Empty when nothing usable is left. */
+function normalizeCarText(text) {
+    if (typeof text !== 'string')
+        return '';
+    const lower = text.normalize('NFD').replace(LATIN_ACCENTS, '').toLowerCase();
+    return westernDigits(lower.replace(ARABIC_DIACRITICS, ''))
+        .replace(/[أإآٱ]/g, 'ا')
+        .replace(/ى/g, 'ي')
+        .replace(/ة/g, 'ه')
+        .replace(NOT_A_LETTER_OR_DIGIT, '');
+}
+/** `makeKey__modelKey`: the one place that shape is written. */
+const joinModelKey = (makeKey, modelKey) => `${makeKey}__${modelKey}`;
+exports.joinModelKey = joinModelKey;
+/** The key a make and model share across cars, review items and fixes; empty when either part is empty. */
+function carModelKey(make, model) {
+    const makeKey = normalizeCarText(make);
+    const modelKey = normalizeCarText(model);
+    return makeKey && modelKey ? (0, exports.joinModelKey)(makeKey, modelKey) : '';
+}
+/** A model typed under "Other", ready to use: trimmed, within the length cap and with a non-empty key. */
+function parseTypedCarModel(make, text) {
+    const trimmed = typeof text === 'string' ? text.trim() : '';
+    if (trimmed.length > exports.CAR_MODEL_MAX_LENGTH)
+        return { ok: false, error: 'too_long' };
+    const key = carModelKey(make, trimmed);
+    if (!key)
+        return { ok: false, error: 'empty' };
+    return { ok: true, text: trimmed, key };
+}
+/** Verified only while the car still has the size and model Sahab checked; any edit by the customer makes it unverified again. */
+function isCarVerified(car) {
+    if (!car || car.verifiedBySahab !== true)
+        return false;
+    if (!(0, exports.isCarSize)(car.verifiedSize) || car.size !== car.verifiedSize)
+        return false;
+    const key = carModelKey(car.manufacturer, car.model);
+    return !!key && key === car.verifiedModelKey;
+}
+/** The active models of a make as the customer picker lists them: sorted by name, never an alias, pending or declined model. */
+function buildPicker(models) {
+    return models
+        .filter((model) => model.status === 'active')
+        .map(({ id, name, size }) => ({ id, name, size }))
+        .sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+}
+/** The picker with one active model added, or replaced if it is already there. */
+function withPickerEntry(picker, entry) {
+    return buildPicker([...(picker !== null && picker !== void 0 ? picker : []).filter((existing) => existing.id !== entry.id), entry].map((item) => (Object.assign(Object.assign({}, item), { status: 'active' }))));
+}
+/** Every key a model's cars may carry: its own and those of the aliases merged into it. */
+function modelKeysOf(model) {
+    var _a;
+    return [model.id, ...((_a = model.aliasKeys) !== null && _a !== void 0 ? _a : []).filter((key) => key !== model.id)].filter((key, index, all) => all.indexOf(key) === index);
+}
+/** `makeKey__modelKey` as its two parts, or undefined when it is not that shape. */
+function splitModelKey(key) {
+    if (typeof key !== 'string')
+        return undefined;
+    const parts = key.split('__');
+    return parts.length === 2 && parts[0] && parts[1] ? { makeKey: parts[0], modelKey: parts[1] } : undefined;
+}
+/** The makes list a customer picks from: one small document, so showing it costs a single read. */
+exports.CAR_CATALOGUE_INDEX_ID = '_index';
+/** The key of the make a customer typed: the catalogue's own key when the text is a known make's English or Arabic name, else the typed text's key. Empty when nothing usable was typed. */
+function resolveMakeKey(index, typedMake) {
+    const typedKey = normalizeCarText(typedMake);
+    if (!typedKey)
+        return '';
+    const match = (index !== null && index !== void 0 ? index : []).find((entry) => normalizeCarText(entry.en) === typedKey || (!!entry.ar && normalizeCarText(entry.ar) === typedKey));
+    return match ? match.makeKey : typedKey;
+}
+exports.PLATE_LETTERS_MAX = 3;
+exports.PLATE_NUMBER_MAX = 4;
+// The Latin letters Saudi plates carry for each Arabic letter, so a customer can type the plate as it reads.
+const ARABIC_PLATE_LETTERS = {
+    'ا': 'A', 'أ': 'A', 'إ': 'A', 'آ': 'A',
+    'ب': 'B', 'ح': 'J', 'د': 'D', 'ر': 'R', 'س': 'S', 'ص': 'X', 'ط': 'T', 'ع': 'E',
+    'ق': 'G', 'ك': 'K', 'ل': 'L', 'م': 'Z', 'ن': 'N', 'ه': 'H', 'و': 'U', 'ى': 'V', 'ي': 'V',
+};
+/** Plate letters as stored: English capitals only, at most three; Arabic letters become their plate equivalents. */
+function normalizePlateLetters(text) {
+    if (typeof text !== 'string')
+        return '';
+    return text
+        .normalize('NFD')
+        .replace(/[̀-ًͯ-ٟـ]/g, '')
+        .split('')
+        .map((char) => { var _a; return (_a = ARABIC_PLATE_LETTERS[char]) !== null && _a !== void 0 ? _a : char.toUpperCase(); })
+        .join('')
+        .replace(/[^A-Z]/g, '')
+        .slice(0, exports.PLATE_LETTERS_MAX);
+}
+/** Plate digits as stored: Western digits only, at most four. */
+function normalizePlateNumber(text) {
+    if (typeof text !== 'string')
+        return '';
+    return westernDigits(text).replace(/[^0-9]/g, '').slice(0, exports.PLATE_NUMBER_MAX);
+}

package/dist/ts/staffAccess.d.ts

@@ -10,7 +10,8 @@ export declare enum Permissions {
     VIEW_MAP = 6,// 6
     VIEW_PROMO = 7,// 7
     VIEW_BANNERS = 8,// 8
-    VIEW_INVESTOR_NUMBERS = 9
+    VIEW_INVESTOR_NUMBERS = 9,// 9
+    VIEW_CAR_MODELS = 10
 }
 export declare const ALL_PERMISSIONS: Permissions[];
 export declare const PERMISSION_LABELS: Record<Permissions, {

package/dist/ts/staffAccess.js

@@ -16,6 +16,7 @@ var Permissions;
     Permissions[Permissions["VIEW_PROMO"] = 7] = "VIEW_PROMO";
     Permissions[Permissions["VIEW_BANNERS"] = 8] = "VIEW_BANNERS";
     Permissions[Permissions["VIEW_INVESTOR_NUMBERS"] = 9] = "VIEW_INVESTOR_NUMBERS";
+    Permissions[Permissions["VIEW_CAR_MODELS"] = 10] = "VIEW_CAR_MODELS";
 })(Permissions || (exports.Permissions = Permissions = {}));
 exports.ALL_PERMISSIONS = [
     Permissions.VIEW_KPI,
@@ -28,6 +29,7 @@ exports.ALL_PERMISSIONS = [
     Permissions.VIEW_PROMO,
     Permissions.VIEW_BANNERS,
     Permissions.VIEW_INVESTOR_NUMBERS,
+    Permissions.VIEW_CAR_MODELS,
 ];
 exports.PERMISSION_LABELS = {
     [Permissions.VIEW_KPI]: { label: 'KPIs', description: 'Business KPIs for a chosen period.' },
@@ -40,6 +42,7 @@ exports.PERMISSION_LABELS = {
     [Permissions.VIEW_PROMO]: { label: 'Promo and offers', description: 'Promo codes, offers, gifts and the wheel.' },
     [Permissions.VIEW_BANNERS]: { label: 'Banners', description: 'The app banners.' },
     [Permissions.VIEW_INVESTOR_NUMBERS]: { label: 'Investor numbers', description: 'Financial and unit-economics figures.' },
+    [Permissions.VIEW_CAR_MODELS]: { label: 'Car models', description: 'Review car models customers entered, and fix the size of unverified cars.' },
 };
 /** ADMIN opens every page; STAFF opens only the pages in their list. */
 exports.STAFF_ROLES = ['ADMIN', 'STAFF'];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sahab-utils",
-	"version": "1.10.0",
+	"version": "2.0.0",
 	"description": "This package contains types and utils functions",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -8,7 +8,7 @@
 		"build": "tsc",
 		"prepublishOnly": "npm run build",
 		"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 && node tests/push.test.js && node tests/broadcast.test.js && node tests/iban.test.js && node tests/cash.test.js && node tests/workingHours.test.js && node tests/payLink.test.js && node tests/offerings.test.js && node tests/capacity.test.js && node tests/tap.test.js && node tests/orderAdjustment.test.js && node tests/adminNotifications.test.js && node tests/staffAccess.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 && node tests/iban.test.js && node tests/cash.test.js && node tests/workingHours.test.js && node tests/payLink.test.js && node tests/offerings.test.js && node tests/capacity.test.js && node tests/tap.test.js && node tests/orderAdjustment.test.js && node tests/adminNotifications.test.js && node tests/staffAccess.test.js && node tests/carCatalogue.test.js"
 	},
 	"repository": {
 		"type": "git",