sahab-utils 1.9.2 → 1.9.4

package/dist/constants/types.d.ts

@@ -1,5 +1,6 @@
 import { DocumentReference, GeoPoint, Timestamp } from 'firebase/firestore';
 import type { PushTransport } from '../ts/push';
+import type { TapLicenseType } from '../ts/tap';
 export type GeoPointType = GeoPoint;
 export type TimestampType = Timestamp;
 export type DistenceDueration = {
@@ -493,7 +494,6 @@ export declare const INTEGRATION_KEYS: {
 export type IntegrationKey = (typeof INTEGRATION_KEYS)[keyof typeof INTEGRATION_KEYS];
 export type TapKycStatus = 'draft' | 'documents_uploaded' | 'lead_created' | 'account_created' | 'payout_enabled' | 'rejected';
 export type TapDocumentPurpose = 'commercial_registration' | 'national_id' | 'bank_statement' | 'iban_certificate';
-export type TapLicenseType = 'LLC' | 'SOLE_PROPRIETORSHIP' | 'JOINT_STOCK' | 'PARTNERSHIP' | 'OTHER';
 export type TapApplicationFile = {
     purpose: TapDocumentPurpose;
     fileId: string;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './constants/types';
+export * from './ts/adminNotifications';
+export * from './ts/staffAccess';
 export * from './ts/broadcast';
 export * from './ts/capacity';
 export * from './ts/calcs';
@@ -10,6 +12,7 @@ export * from './ts/loyalty';
 export * from './ts/offerings';
 export * from './ts/orderActivity';
 export * from './ts/payLink';
+export * from './ts/tap';
 export * from './ts/push';
 export * from './ts/utils';
 export * from './ts/wheel';

package/dist/index.js

@@ -15,6 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./constants/types"), exports);
+__exportStar(require("./ts/adminNotifications"), exports);
+__exportStar(require("./ts/staffAccess"), exports);
 __exportStar(require("./ts/broadcast"), exports);
 __exportStar(require("./ts/capacity"), exports);
 __exportStar(require("./ts/calcs"), exports);
@@ -26,6 +28,7 @@ __exportStar(require("./ts/loyalty"), exports);
 __exportStar(require("./ts/offerings"), exports);
 __exportStar(require("./ts/orderActivity"), exports);
 __exportStar(require("./ts/payLink"), exports);
+__exportStar(require("./ts/tap"), exports);
 __exportStar(require("./ts/push"), exports);
 __exportStar(require("./ts/utils"), exports);
 __exportStar(require("./ts/wheel"), exports);

package/dist/ts/adminNotifications.d.ts

@@ -0,0 +1,67 @@
+import type { Permissions, StaffRole } from './staffAccess';
+/** Which alerts a back-office admin gets. The shared contract between sahab-website (the Admin notifications page) and cloudFun. */
+/** App (push) alerts, each sent to the admin's customer-app account. */
+export declare const ADMIN_PUSH_KINDS: readonly ["newOrder", "newCarwash", "newGift", "newClient", "needsAttention", "statements"];
+export type AdminPushKind = (typeof ADMIN_PUSH_KINDS)[number];
+/** Every switch on the page: the app alerts plus the lead e-mail. */
+export declare const ADMIN_NOTIFICATION_KEYS: readonly ["newOrder", "newCarwash", "newGift", "newClient", "needsAttention", "statements", "leadEmails"];
+export type AdminNotificationKey = (typeof ADMIN_NOTIFICATION_KEYS)[number];
+export type AdminNotificationPrefs = Record<AdminNotificationKey, boolean>;
+export declare const ADMIN_NOTIFICATION_LABELS: Record<AdminNotificationKey, {
+    label: string;
+    description: string;
+}>;
+/** Nothing is switched on until an admin is set up. */
+export declare const defaultAdminNotificationPrefs: () => AdminNotificationPrefs;
+/** A stored `notifications` map as a full set of switches; anything missing or not a boolean is off. */
+export declare function normalizeAdminNotificationPrefs(raw: unknown): AdminNotificationPrefs;
+export type AdminListItem = {
+    email: string;
+    name?: string;
+    /** The back-office role, e.g. ADMIN. */
+    type?: string;
+    role: StaffRole;
+    /** The pages a STAFF member may open; empty for an ADMIN, who opens all of them. */
+    permissions: Permissions[];
+    /** True once their access to the dashboard has been removed. */
+    disabled: boolean;
+    /** Why this person's role or access cannot be taken away right now (the list shows it instead of the button); absent when it can. */
+    accessLocked?: string;
+    /** The admin's app user ID (the Firebase user, the same in the customer and provider apps), where app alerts are delivered. */
+    appUid?: string;
+    notifications: AdminNotificationPrefs;
+};
+export type ListAdminsResponse = {
+    /** Whether the caller may change anything on the page. */
+    canEdit: boolean;
+    admins: AdminListItem[];
+};
+export type UpdateAdminRequest = {
+    email: string;
+    /** Changes what they may open. Left out, it is unchanged. */
+    role?: StaffRole;
+    permissions?: Permissions[];
+    /** An empty string clears it. Left out, it is unchanged. */
+    appUid?: string;
+    /** Only the switches listed here change. */
+    notifications?: Partial<AdminNotificationPrefs>;
+};
+export type AddAdminRequest = {
+    email: string;
+    name: string;
+    /** Defaults to ADMIN. */
+    role?: StaffRole;
+    permissions?: Permissions[];
+    appUid?: string;
+    notifications?: Partial<AdminNotificationPrefs>;
+};
+export type AddAdminResponse = {
+    admin: AdminListItem;
+    /** Whether the set-password e-mail went out. */
+    inviteSent: boolean;
+};
+/** An e-mail as it is stored: trimmed and lower case, since `support_users` documents are keyed by it. */
+export declare const normalizeAdminEmail: (value: unknown) => string;
+export declare const isValidAdminEmail: (value: unknown) => boolean;
+/** A Firebase user ID: letters and digits only, never a path. */
+export declare const isValidAppUid: (value: unknown) => boolean;

package/dist/ts/adminNotifications.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidAppUid = exports.isValidAdminEmail = exports.normalizeAdminEmail = exports.defaultAdminNotificationPrefs = exports.ADMIN_NOTIFICATION_LABELS = exports.ADMIN_NOTIFICATION_KEYS = exports.ADMIN_PUSH_KINDS = void 0;
+exports.normalizeAdminNotificationPrefs = normalizeAdminNotificationPrefs;
+/** Which alerts a back-office admin gets. The shared contract between sahab-website (the Admin notifications page) and cloudFun. */
+/** App (push) alerts, each sent to the admin's customer-app account. */
+exports.ADMIN_PUSH_KINDS = ['newOrder', 'newCarwash', 'newGift', 'newClient', 'needsAttention', 'statements'];
+/** Every switch on the page: the app alerts plus the lead e-mail. */
+exports.ADMIN_NOTIFICATION_KEYS = [...exports.ADMIN_PUSH_KINDS, 'leadEmails'];
+exports.ADMIN_NOTIFICATION_LABELS = {
+    newOrder: { label: 'New order', description: 'A customer places an order.' },
+    newCarwash: { label: 'New carwash', description: 'A carwash registers or finishes its registration.' },
+    newGift: { label: 'New gift', description: 'A customer buys a gift.' },
+    newClient: { label: 'New customer', description: 'A customer joins the app.' },
+    needsAttention: { label: 'Carwash needs attention', description: 'A carwash changed something that needs a look.' },
+    statements: { label: 'Statements', description: 'The daily and weekly statements are ready.' },
+    leadEmails: { label: 'Lead e-mails', description: 'A visitor sends an enquiry or a carwash request on the website.' },
+};
+/** Nothing is switched on until an admin is set up. */
+const defaultAdminNotificationPrefs = () => {
+    const prefs = {};
+    exports.ADMIN_NOTIFICATION_KEYS.forEach((key) => {
+        prefs[key] = false;
+    });
+    return prefs;
+};
+exports.defaultAdminNotificationPrefs = defaultAdminNotificationPrefs;
+/** A stored `notifications` map as a full set of switches; anything missing or not a boolean is off. */
+function normalizeAdminNotificationPrefs(raw) {
+    const stored = raw && typeof raw === 'object' ? raw : {};
+    const prefs = (0, exports.defaultAdminNotificationPrefs)();
+    exports.ADMIN_NOTIFICATION_KEYS.forEach((key) => {
+        prefs[key] = stored[key] === true;
+    });
+    return prefs;
+}
+/** An e-mail as it is stored: trimmed and lower case, since `support_users` documents are keyed by it. */
+const normalizeAdminEmail = (value) => (typeof value === 'string' ? value.trim().toLowerCase() : '');
+exports.normalizeAdminEmail = normalizeAdminEmail;
+const isValidAdminEmail = (value) => {
+    const email = (0, exports.normalizeAdminEmail)(value);
+    return email.length <= 254 && /^[^\s@/]+@[^\s@/]+\.[^\s@/]{2,}$/.test(email);
+};
+exports.isValidAdminEmail = isValidAdminEmail;
+/** A Firebase user ID: letters and digits only, never a path. */
+const isValidAppUid = (value) => typeof value === 'string' && /^[A-Za-z0-9_-]{6,128}$/.test(value);
+exports.isValidAppUid = isValidAppUid;

package/dist/ts/staffAccess.d.ts

@@ -0,0 +1,39 @@
+/** Who may open which back-office page. The shared contract between sahab-website and cloudFun. */
+/** A dashboard page a non-admin may open. The numbers are stored in `support_users.permissions`, so never renumber. */
+export declare enum Permissions {
+    VIEW_KPI = 0,// 0
+    VIEW_REQUESTS = 1,// 1
+    VIEW_COMPLAINTS = 2,// 2
+    VIEW_BUGS = 3,// 3
+    VIEW_ORDERS = 4,// 4
+    VIEW_PROVIDERS = 5,// 5
+    VIEW_MAP = 6,// 6
+    VIEW_PROMO = 7,// 7
+    VIEW_BANNERS = 8,// 8
+    VIEW_INVESTOR_NUMBERS = 9
+}
+export declare const ALL_PERMISSIONS: Permissions[];
+export declare const PERMISSION_LABELS: Record<Permissions, {
+    label: string;
+    description: string;
+}>;
+/** ADMIN opens every page; STAFF opens only the pages in their list. */
+export declare const STAFF_ROLES: readonly ["ADMIN", "STAFF"];
+export type StaffRole = (typeof STAFF_ROLES)[number];
+export declare const isStaffRole: (value: unknown) => value is StaffRole;
+/** A stored `type` as a role: ADMIN stays ADMIN, anything else is STAFF. */
+export declare const roleOfType: (type: unknown) => StaffRole;
+/** The permissions that exist, once each, in page order; anything else in the input is dropped. */
+export declare function normalizePermissions(raw: unknown): Permissions[];
+/** Whether every entry of a request's list is a real permission, so a typo is refused rather than quietly dropped. */
+export declare const areAllPermissions: (raw: unknown) => raw is Permissions[];
+export type SetAdminAccessRequest = {
+    email: string;
+    /** True removes their access to the dashboard; false restores it. */
+    disabled: boolean;
+};
+export type SetAdminAccessResponse = {
+    admin: import('./adminNotifications').AdminListItem;
+    /** False when the person has no sign-in account to switch, which does not stop the dashboard from refusing them. */
+    authUpdated: boolean;
+};

package/dist/ts/staffAccess.js

@@ -0,0 +1,58 @@
+"use strict";
+/** Who may open which back-office page. The shared contract between sahab-website and cloudFun. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.areAllPermissions = exports.roleOfType = exports.isStaffRole = exports.STAFF_ROLES = exports.PERMISSION_LABELS = exports.ALL_PERMISSIONS = exports.Permissions = void 0;
+exports.normalizePermissions = normalizePermissions;
+/** A dashboard page a non-admin may open. The numbers are stored in `support_users.permissions`, so never renumber. */
+var Permissions;
+(function (Permissions) {
+    Permissions[Permissions["VIEW_KPI"] = 0] = "VIEW_KPI";
+    Permissions[Permissions["VIEW_REQUESTS"] = 1] = "VIEW_REQUESTS";
+    Permissions[Permissions["VIEW_COMPLAINTS"] = 2] = "VIEW_COMPLAINTS";
+    Permissions[Permissions["VIEW_BUGS"] = 3] = "VIEW_BUGS";
+    Permissions[Permissions["VIEW_ORDERS"] = 4] = "VIEW_ORDERS";
+    Permissions[Permissions["VIEW_PROVIDERS"] = 5] = "VIEW_PROVIDERS";
+    Permissions[Permissions["VIEW_MAP"] = 6] = "VIEW_MAP";
+    Permissions[Permissions["VIEW_PROMO"] = 7] = "VIEW_PROMO";
+    Permissions[Permissions["VIEW_BANNERS"] = 8] = "VIEW_BANNERS";
+    Permissions[Permissions["VIEW_INVESTOR_NUMBERS"] = 9] = "VIEW_INVESTOR_NUMBERS";
+})(Permissions || (exports.Permissions = Permissions = {}));
+exports.ALL_PERMISSIONS = [
+    Permissions.VIEW_KPI,
+    Permissions.VIEW_REQUESTS,
+    Permissions.VIEW_COMPLAINTS,
+    Permissions.VIEW_BUGS,
+    Permissions.VIEW_ORDERS,
+    Permissions.VIEW_PROVIDERS,
+    Permissions.VIEW_MAP,
+    Permissions.VIEW_PROMO,
+    Permissions.VIEW_BANNERS,
+    Permissions.VIEW_INVESTOR_NUMBERS,
+];
+exports.PERMISSION_LABELS = {
+    [Permissions.VIEW_KPI]: { label: 'KPIs', description: 'Business KPIs for a chosen period.' },
+    [Permissions.VIEW_REQUESTS]: { label: 'Requests', description: 'Carwash applications waiting for review.' },
+    [Permissions.VIEW_COMPLAINTS]: { label: 'Complaints', description: 'Customer complaints.' },
+    [Permissions.VIEW_BUGS]: { label: 'Bugs', description: 'Bug reports from the apps.' },
+    [Permissions.VIEW_ORDERS]: { label: 'Orders', description: 'Live orders, with the option to edit them.' },
+    [Permissions.VIEW_PROVIDERS]: { label: 'Providers', description: 'Accepted carwashes and their Tap onboarding.' },
+    [Permissions.VIEW_MAP]: { label: 'Map', description: 'Orders and drivers on the map.' },
+    [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.' },
+};
+/** ADMIN opens every page; STAFF opens only the pages in their list. */
+exports.STAFF_ROLES = ['ADMIN', 'STAFF'];
+const isStaffRole = (value) => exports.STAFF_ROLES.includes(value);
+exports.isStaffRole = isStaffRole;
+/** A stored `type` as a role: ADMIN stays ADMIN, anything else is STAFF. */
+const roleOfType = (type) => (type === 'ADMIN' ? 'ADMIN' : 'STAFF');
+exports.roleOfType = roleOfType;
+/** The permissions that exist, once each, in page order; anything else in the input is dropped. */
+function normalizePermissions(raw) {
+    const wanted = Array.isArray(raw) ? raw : [];
+    return exports.ALL_PERMISSIONS.filter((permission) => wanted.includes(permission));
+}
+/** Whether every entry of a request's list is a real permission, so a typo is refused rather than quietly dropped. */
+const areAllPermissions = (raw) => Array.isArray(raw) && raw.every((p) => exports.ALL_PERMISSIONS.includes(p));
+exports.areAllPermissions = areAllPermissions;

package/dist/ts/tap.d.ts

@@ -0,0 +1,6 @@
+/** The only `entity.license.type` values Tap's Create Lead API accepts, spelled exactly as Tap lists them. */
+export declare const TAP_LICENSE_TYPES: readonly ["Establishment", "Trust", "Partnership", "LLC", "JSC", "Foreign JSC Branch", "Mix LLC", "Foreign LLC", "GCC Partnership", "GCC LLC", "GCC JSC", "Foreign LLC Branch", "Profession LLC", "Freelancer"];
+export type TapLicenseType = (typeof TAP_LICENSE_TYPES)[number];
+export declare const isTapLicenseType: (value: unknown) => value is TapLicenseType;
+/** A stored or submitted license type as one Tap accepts, or undefined when it maps to none. */
+export declare function normalizeTapLicenseType(value: unknown): TapLicenseType | undefined;

package/dist/ts/tap.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTapLicenseType = exports.TAP_LICENSE_TYPES = void 0;
+exports.normalizeTapLicenseType = normalizeTapLicenseType;
+/** The only `entity.license.type` values Tap's Create Lead API accepts, spelled exactly as Tap lists them. */
+exports.TAP_LICENSE_TYPES = [
+    'Establishment',
+    'Trust',
+    'Partnership',
+    'LLC',
+    'JSC',
+    'Foreign JSC Branch',
+    'Mix LLC',
+    'Foreign LLC',
+    'GCC Partnership',
+    'GCC LLC',
+    'GCC JSC',
+    'Foreign LLC Branch',
+    'Profession LLC',
+    'Freelancer',
+];
+const isTapLicenseType = (value) => exports.TAP_LICENSE_TYPES.includes(value);
+exports.isTapLicenseType = isTapLicenseType;
+// Applications saved before the list was corrected hold the dashboard's old names. There is no Tap value for
+// "other", so that one stays unresolved and the form must ask again.
+const LEGACY_LICENSE_TYPES = {
+    SOLE_PROPRIETORSHIP: 'Establishment',
+    JOINT_STOCK: 'JSC',
+    PARTNERSHIP: 'Partnership',
+};
+/** A stored or submitted license type as one Tap accepts, or undefined when it maps to none. */
+function normalizeTapLicenseType(value) {
+    if ((0, exports.isTapLicenseType)(value))
+        return value;
+    return typeof value === 'string' ? LEGACY_LICENSE_TYPES[value] : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sahab-utils",
-	"version": "1.9.2",
+	"version": "1.9.4",
 	"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"
+		"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/adminNotifications.test.js && node tests/staffAccess.test.js"
 	},
 	"repository": {
 		"type": "git",