@fleetbase/fleetops-engine 0.6.71 → 0.6.72

package/server/src/Support/TrackingPage/TrackingPageConfig.php

@@ -0,0 +1,264 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\TrackingPage;
+
+use Illuminate\Support\Str;
+
+/**
+ * The shape, defaults and sanitizing of a company's customer tracking page settings.
+ *
+ * A company keeps its config in the company setting `tracking-page`. Instance-wide
+ * defaults for the generic page live in the system setting `fleet-ops.tracking-page`.
+ * Everything here is pure, so the controller and the public tracking API read one shape.
+ *
+ * Privacy rules are not settings: the map and driver hide after delivery, and the driver
+ * shows only while en route to the viewer's stops, whatever is saved here.
+ */
+class TrackingPageConfig
+{
+    public const SETTING_KEY       = 'tracking-page';
+    public const ADMIN_SETTING_KEY = 'fleet-ops.tracking-page';
+    public const SLUG_INDEX_PREFIX = 'fleet-ops.tracking-page-slugs.';
+    public const DEFAULT_ACCENT    = '#1F5FA8';
+    public const DARK_INK          = '#14191A';
+    public const LIGHT_INK         = '#FFFFFF';
+
+    /**
+     * The FleetOps locales a tracking page can be shown in.
+     */
+    public const LOCALES = ['en-us', 'ar-ae', 'bg-bg', 'es-pa', 'fr-fr', 'mn-mn', 'pt-br', 'ru-ru', 'uk-ua', 'vi-vn'];
+
+    /**
+     * Slugs a company can't take: they would read as part of the page's own URLs.
+     */
+    public const RESERVED_SLUGS = [
+        'admin', 'api', 'auth', 'console', 'customer-access', 'customer-portal', 'fleetbase', 'help',
+        'int', 'login', 'new', 'portal', 'public', 'settings', 'support', 'track', 'tracking', 'www',
+    ];
+
+    /**
+     * Instance-wide defaults for the generic page, as an administrator saved them.
+     */
+    public static function sanitizeAdmin(array $input): array
+    {
+        return [
+            'generic_page' => [
+                'enabled' => static::bool(data_get($input, 'generic_page.enabled'), true),
+            ],
+            'branding'     => [
+                'display_name'  => static::text(data_get($input, 'branding.display_name'), 80),
+                'accent'        => static::color(data_get($input, 'branding.accent')) ?? static::DEFAULT_ACCENT,
+                'support_phone' => static::text(data_get($input, 'branding.support_phone'), 32),
+                'support_email' => static::email(data_get($input, 'branding.support_email')),
+                'website'       => static::url(data_get($input, 'branding.website')),
+                'powered_by'    => static::bool(data_get($input, 'branding.powered_by'), true),
+            ],
+        ];
+    }
+
+    /**
+     * A company's config, with every key present and every value valid.
+     *
+     * @param array       $admin       the sanitized instance defaults
+     * @param string|null $companyName used for the default slug
+     */
+    public static function sanitize(array $input, array $admin = [], ?string $companyName = null): array
+    {
+        $admin  = static::sanitizeAdmin($admin);
+        $locale = static::oneOf(data_get($input, 'branding.default_locale'), static::LOCALES, 'en-us');
+
+        return [
+            'org_page'     => [
+                'enabled' => static::bool(data_get($input, 'org_page.enabled'), false),
+                'slug'    => static::normalizeSlug(data_get($input, 'org_page.slug')) ?: static::slugify((string) $companyName),
+            ],
+            'generic_page' => [
+                'allowed' => static::bool(data_get($input, 'generic_page.allowed'), true),
+            ],
+            'links'        => [
+                'target' => static::oneOf(data_get($input, 'links.target'), ['auto', 'org', 'generic'], 'auto'),
+            ],
+            'branding'     => [
+                'display_name'  => static::text(data_get($input, 'branding.display_name'), 80),
+                'logo_uuid'     => static::text(data_get($input, 'branding.logo_uuid'), 64),
+                'accent'        => static::color(data_get($input, 'branding.accent')) ?? $admin['branding']['accent'],
+                'accent_dark'   => static::color(data_get($input, 'branding.accent_dark')),
+                'support_phone' => static::text(data_get($input, 'branding.support_phone'), 32),
+                'support_email' => static::email(data_get($input, 'branding.support_email')),
+                'website'       => static::url(data_get($input, 'branding.website')),
+                'powered_by'    => static::bool(data_get($input, 'branding.powered_by'), $admin['branding']['powered_by']),
+                'theme'         => static::oneOf(data_get($input, 'branding.theme'), ['system', 'light'], 'system'),
+                'default_locale' => $locale,
+                'locales'       => static::locales(data_get($input, 'branding.locales'), $locale),
+            ],
+            'access'       => [
+                'public_status'   => static::bool(data_get($input, 'access.public_status'), true),
+                'channels'        => [
+                    'sms'   => static::bool(data_get($input, 'access.channels.sms'), true),
+                    'email' => static::bool(data_get($input, 'access.channels.email'), true),
+                ],
+                'session_hours'   => static::clampInt(data_get($input, 'access.session_hours'), 1, 168, 24),
+                'account_sign_in' => static::bool(data_get($input, 'access.account_sign_in'), true),
+                'account_upsell'  => static::bool(data_get($input, 'access.account_upsell'), true),
+            ],
+            'visibility'   => [
+                'map'               => static::bool(data_get($input, 'visibility.map'), true),
+                'driver_name'       => static::bool(data_get($input, 'visibility.driver_name'), true),
+                'vehicle'           => static::bool(data_get($input, 'visibility.vehicle'), true),
+                'driver_contact'    => static::oneOf(data_get($input, 'visibility.driver_contact'), ['company', 'driver'], 'company'),
+                'items'             => static::bool(data_get($input, 'visibility.items'), true),
+                'item_prices'       => static::bool(data_get($input, 'visibility.item_prices'), false),
+                'pod_photo'         => static::bool(data_get($input, 'visibility.pod_photo'), true),
+                'pod_signature'     => static::bool(data_get($input, 'visibility.pod_signature'), true),
+                'instructions_edit' => static::bool(data_get($input, 'visibility.instructions_edit'), false),
+                'report_problem'    => static::bool(data_get($input, 'visibility.report_problem'), true),
+            ],
+        ];
+    }
+
+    /**
+     * Why a slug can't be used, or null when its shape is fine. Availability is the caller's check.
+     *
+     * @return string|null `invalid` or `reserved`
+     */
+    public static function slugError(?string $slug): ?string
+    {
+        if (!is_string($slug) || preg_match('/^[a-z0-9](?:[a-z0-9-]{1,38})[a-z0-9]$/', $slug) !== 1 || str_contains($slug, '--')) {
+            return 'invalid';
+        }
+
+        return in_array($slug, static::RESERVED_SLUGS, true) ? 'reserved' : null;
+    }
+
+    /**
+     * A slug made from a company name: lowercase, hyphenated, 3 to 40 characters.
+     */
+    public static function slugify(string $name): string
+    {
+        $slug = trim(Str::limit(Str::slug($name), 40, ''), '-');
+
+        if (strlen($slug) >= 3) {
+            return $slug;
+        }
+
+        return $slug === '' ? 'company-tracking' : $slug . '-tracking';
+    }
+
+    /**
+     * The text colour readable on an accent: white when it reaches 4.5:1, otherwise dark.
+     */
+    public static function inkFor(string $accent): string
+    {
+        return static::contrastRatio($accent, static::LIGHT_INK) >= 4.5 ? static::LIGHT_INK : static::DARK_INK;
+    }
+
+    /**
+     * The WCAG contrast ratio of two `#RRGGBB` colours.
+     */
+    public static function contrastRatio(string $a, string $b): float
+    {
+        $lighter = max(static::luminance($a), static::luminance($b));
+        $darker  = min(static::luminance($a), static::luminance($b));
+
+        return round(($lighter + 0.05) / ($darker + 0.05), 2);
+    }
+
+    protected static function luminance(string $hex): float
+    {
+        $channels = array_map(function (string $pair) {
+            $value = hexdec($pair) / 255;
+
+            return $value <= 0.03928 ? $value / 12.92 : (($value + 0.055) / 1.055) ** 2.4;
+        }, str_split(ltrim($hex, '#'), 2));
+
+        return 0.2126 * $channels[0] + 0.7152 * $channels[1] + 0.0722 * $channels[2];
+    }
+
+    protected static function normalizeSlug(mixed $value): string
+    {
+        return is_string($value) ? strtolower(trim($value)) : '';
+    }
+
+    protected static function bool(mixed $value, bool $default): bool
+    {
+        if (is_bool($value)) {
+            return $value;
+        }
+
+        // filter_var() reads null as false, so a missing value must fall back explicitly.
+        if ($value === null || $value === '') {
+            return $default;
+        }
+
+        return filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? $default;
+    }
+
+    protected static function text(mixed $value, int $max): ?string
+    {
+        if (!is_string($value) && !is_numeric($value)) {
+            return null;
+        }
+
+        $value = trim((string) $value);
+
+        return $value === '' ? null : mb_substr($value, 0, $max);
+    }
+
+    protected static function email(mixed $value): ?string
+    {
+        $value = static::text($value, 191);
+
+        return $value !== null && filter_var($value, FILTER_VALIDATE_EMAIL) ? $value : null;
+    }
+
+    protected static function url(mixed $value): ?string
+    {
+        $value = static::text($value, 255);
+
+        return $value !== null && preg_match('#^https?://#i', $value) === 1 && filter_var($value, FILTER_VALIDATE_URL) ? $value : null;
+    }
+
+    /**
+     * `#RGB` or `#RRGGBB` as uppercase `#RRGGBB`, or null.
+     */
+    protected static function color(mixed $value): ?string
+    {
+        if (!is_string($value) || preg_match('/^#?([0-9a-f]{3}|[0-9a-f]{6})$/i', trim($value), $match) !== 1) {
+            return null;
+        }
+
+        $hex = $match[1];
+        if (strlen($hex) === 3) {
+            $hex = $hex[0] . $hex[0] . $hex[1] . $hex[1] . $hex[2] . $hex[2];
+        }
+
+        return '#' . strtoupper($hex);
+    }
+
+    protected static function oneOf(mixed $value, array $allowed, string $default): string
+    {
+        return is_string($value) && in_array($value, $allowed, true) ? $value : $default;
+    }
+
+    protected static function clampInt(mixed $value, int $min, int $max, int $default): int
+    {
+        if (!is_numeric($value)) {
+            return $default;
+        }
+
+        return max($min, min($max, (int) $value));
+    }
+
+    /**
+     * The enabled locales, always including the default one; every locale when none are valid.
+     */
+    protected static function locales(mixed $value, string $default): array
+    {
+        $locales = array_values(array_intersect(static::LOCALES, is_array($value) ? $value : []));
+        if ($locales === []) {
+            return static::LOCALES;
+        }
+
+        return in_array($default, $locales, true) ? $locales : array_merge([$default], $locales);
+    }
+}

package/server/src/Support/TrackingPage/TrackingRecipient.php

@@ -0,0 +1,111 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\TrackingPage;
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\FleetOps\Models\Vendor;
+use Fleetbase\FleetOps\Support\TrackingScope;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Who a one-time code goes to for a tracking scope, and how their contact details are
+ * shown on the page: masked, and never editable, so a code can only reach details the
+ * company already holds.
+ */
+class TrackingRecipient
+{
+    public const CHANNEL_SMS   = 'sms';
+    public const CHANNEL_EMAIL = 'email';
+
+    public function __construct(
+        public readonly ?Model $customer,
+        public readonly ?string $email,
+        public readonly ?string $phone,
+    ) {
+    }
+
+    /**
+     * The scope's customer (a Contact or a Vendor) and the contact details a code can use.
+     *
+     * @param string|null $fallbackPhone the stop place's phone, used when the customer has none
+     */
+    public static function for(?TrackingScope $scope, ?string $fallbackPhone = null, ?Model $customer = null): self
+    {
+        $customer ??= $scope ? static::loadCustomer($scope) : null;
+
+        $email = static::validEmail(data_get($customer, 'email'));
+        $phone = static::validPhone(data_get($customer, 'phone')) ?? static::validPhone($fallbackPhone);
+
+        return new self($customer, $email, $phone);
+    }
+
+    protected static function loadCustomer(TrackingScope $scope): ?Model
+    {
+        $class = match (true) {
+            is_a($scope->customer_type, Contact::class, true) => Contact::class,
+            is_a($scope->customer_type, Vendor::class, true)  => Vendor::class,
+            default                                          => null,
+        };
+
+        return $class ? $class::withoutGlobalScopes()->where('uuid', $scope->customer_uuid)->first() : null;
+    }
+
+    /**
+     * The channels a code can go out on, given the company's settings and the instance.
+     *
+     * @return array<int, array{type: string, masked: string}>
+     */
+    public function channels(array $config, bool $smsAvailable): array
+    {
+        $channels = [];
+        if ($this->phone && $smsAvailable && data_get($config, 'access.channels.sms', true)) {
+            $channels[] = ['type' => self::CHANNEL_SMS, 'masked' => static::maskPhone($this->phone)];
+        }
+
+        if ($this->email && data_get($config, 'access.channels.email', true)) {
+            $channels[] = ['type' => self::CHANNEL_EMAIL, 'masked' => static::maskEmail($this->email)];
+        }
+
+        return $channels;
+    }
+
+    public function destination(string $channel): ?string
+    {
+        return $channel === self::CHANNEL_SMS ? $this->phone : ($channel === self::CHANNEL_EMAIL ? $this->email : null);
+    }
+
+    /**
+     * `•••• •• 4821`: only the last four digits.
+     */
+    public static function maskPhone(string $phone): string
+    {
+        $digits = preg_replace('/\D/', '', $phone);
+
+        return '•••• •• ' . substr($digits, -4);
+    }
+
+    /**
+     * `m•••@g•••.com`: the first letter of each part and the top-level domain.
+     */
+    public static function maskEmail(string $email): string
+    {
+        [$local, $domain] = explode('@', $email, 2);
+        $tld              = str_contains($domain, '.') ? substr($domain, strrpos($domain, '.')) : '';
+
+        return mb_substr($local, 0, 1) . '•••@' . mb_substr($domain, 0, 1) . '•••' . $tld;
+    }
+
+    protected static function validEmail(mixed $value): ?string
+    {
+        $value = is_string($value) ? trim($value) : '';
+
+        return $value !== '' && filter_var($value, FILTER_VALIDATE_EMAIL) ? $value : null;
+    }
+
+    protected static function validPhone(mixed $value): ?string
+    {
+        $value = is_string($value) ? trim($value) : '';
+
+        return strlen(preg_replace('/\D/', '', $value)) >= 6 ? $value : null;
+    }
+}

package/server/src/Support/TrackingPage/TrackingResolver.php

@@ -0,0 +1,201 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\TrackingPage;
+
+use Fleetbase\FleetOps\Models\Entity;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\FleetOps\Models\TrackingNumber;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\TrackingScope;
+use Fleetbase\Models\Setting;
+
+/**
+ * Turns what a visitor typed into the order and customer it may open, or null.
+ *
+ * Null covers everything a visitor must not be able to tell apart: a malformed number, an
+ * unknown one, one from a company that opted out of the shared page, and, on a company's
+ * own page, one belonging to another company. The caller answers all of them the same way.
+ *
+ * Only the `tracking_number` column is matched, never a uuid or public id.
+ */
+class TrackingResolver
+{
+    public const NUMBER_PATTERN = '/^[A-Za-z0-9][A-Za-z0-9._\-]{0,99}$/';
+
+    /**
+     * The tracking number as typed, trimmed, or null when it can't be one.
+     */
+    public static function normalize(mixed $input): ?string
+    {
+        if (!is_string($input)) {
+            return null;
+        }
+
+        $input = trim($input);
+
+        return preg_match(static::NUMBER_PATTERN, $input) === 1 ? $input : null;
+    }
+
+    /**
+     * @param string|null $slug a company page's slug; null for the shared page
+     */
+    public function resolve(mixed $input, ?string $slug = null): ?TrackingTarget
+    {
+        $number = static::normalize($input);
+        if ($number === null) {
+            return null;
+        }
+
+        $companyUuid = null;
+        if ($slug !== null) {
+            $companyUuid = $this->companyForSlug($slug);
+            if ($companyUuid === null) {
+                return null;
+            }
+        }
+
+        $trackingNumber = $this->findTrackingNumber($number, $companyUuid);
+        $target         = $trackingNumber ? $this->targetFor($trackingNumber) : null;
+        if ($target === null) {
+            return null;
+        }
+
+        $config = $this->config($target->companyUuid());
+        if ($slug === null && (!$config['generic_page']['allowed'] || !$this->adminConfig()['generic_page']['enabled'])) {
+            return null;
+        }
+
+        if ($companyUuid !== null && $target->companyUuid() !== $companyUuid) {
+            return null;
+        }
+
+        return $target->withConfig($config);
+    }
+
+    /**
+     * The company whose enabled page lives at this slug.
+     */
+    public function companyForSlug(?string $slug): ?string
+    {
+        $slug = strtolower(trim((string) $slug));
+        if (TrackingPageConfig::slugError($slug) !== null) {
+            return null;
+        }
+
+        $companyUuid = $this->lookupSetting(TrackingPageConfig::SLUG_INDEX_PREFIX . $slug);
+        if (!is_string($companyUuid) || $companyUuid === '') {
+            return null;
+        }
+
+        $config = $this->config($companyUuid);
+
+        return $config['org_page']['enabled'] && $config['org_page']['slug'] === $slug ? $companyUuid : null;
+    }
+
+    /**
+     * The order and customer a tracking number opens, from whatever owns it.
+     */
+    public function targetFor(TrackingNumber $trackingNumber): ?TrackingTarget
+    {
+        $owner = $this->ownerOf($trackingNumber);
+
+        if ($owner instanceof Order) {
+            return new TrackingTarget($owner, TrackingScope::forOrder($owner), $trackingNumber);
+        }
+
+        if ($owner instanceof Waypoint) {
+            $order = $this->orderForPayload($owner->payload_uuid);
+
+            return $order ? new TrackingTarget($order, TrackingScope::forStop($order, $owner), $trackingNumber, TrackingTarget::KIND_STOP, $owner) : null;
+        }
+
+        if ($owner instanceof Entity) {
+            $order = $this->orderForPayload($owner->payload_uuid);
+            if (!$order) {
+                return null;
+            }
+
+            $waypoint = $this->waypointForEntity($owner);
+
+            return new TrackingTarget($order, TrackingScope::forStop($order, $waypoint), $trackingNumber, TrackingTarget::KIND_ITEM, $waypoint);
+        }
+
+        if ($owner instanceof Place) {
+            // A service stop's pickup or dropoff number: the stop belongs to the order's customer.
+            $order = $this->orderForPlaceTrackingNumber($trackingNumber->uuid);
+
+            return $order ? new TrackingTarget($order, TrackingScope::forOrder($order), $trackingNumber, TrackingTarget::KIND_STOP) : null;
+        }
+
+        return null;
+    }
+
+    /**
+     * The slug to put in a company's tracking links, or null to link the shared page.
+     */
+    public function linkSlugFor(string $companyUuid): ?string
+    {
+        $config = $this->config($companyUuid);
+
+        return $config['links']['target'] !== 'generic' && $config['org_page']['enabled'] ? $config['org_page']['slug'] : null;
+    }
+
+    public function config(?string $companyUuid): array
+    {
+        return TrackingPageConfig::sanitize(
+            (array) $this->lookupSetting('company.' . $companyUuid . '.' . TrackingPageConfig::SETTING_KEY, []),
+            $this->adminConfig()
+        );
+    }
+
+    public function adminConfig(): array
+    {
+        return TrackingPageConfig::sanitizeAdmin((array) $this->lookupSetting(TrackingPageConfig::ADMIN_SETTING_KEY, []));
+    }
+
+    protected function findTrackingNumber(string $number, ?string $companyUuid): ?TrackingNumber
+    {
+        $query = TrackingNumber::withoutGlobalScopes()->where('tracking_number', $number);
+        if ($companyUuid !== null) {
+            $query->where('company_uuid', $companyUuid);
+        }
+
+        return $query->first();
+    }
+
+    protected function ownerOf(TrackingNumber $trackingNumber): mixed
+    {
+        return $trackingNumber->owner;
+    }
+
+    protected function orderForPayload(?string $payloadUuid): ?Order
+    {
+        return $payloadUuid ? Order::withoutGlobalScopes()->where('payload_uuid', $payloadUuid)->first() : null;
+    }
+
+    protected function waypointForEntity(Entity $entity): ?Waypoint
+    {
+        if (!$entity->payload_uuid || !$entity->destination_uuid) {
+            return null;
+        }
+
+        return Waypoint::withoutGlobalScopes()->where('payload_uuid', $entity->payload_uuid)->where('place_uuid', $entity->destination_uuid)->first();
+    }
+
+    protected function orderForPlaceTrackingNumber(string $trackingNumberUuid): ?Order
+    {
+        $payloadUuid = Payload::withoutGlobalScopes()
+            ->where('pickup_tracking_number_uuid', $trackingNumberUuid)
+            ->orWhere('dropoff_tracking_number_uuid', $trackingNumberUuid)
+            ->value('uuid');
+
+        return $this->orderForPayload($payloadUuid);
+    }
+
+    protected function lookupSetting(string $key, mixed $default = null): mixed
+    {
+        return Setting::lookup($key, $default);
+    }
+}

package/server/src/Support/TrackingPage/TrackingTarget.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\TrackingPage;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\TrackingNumber;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\TrackingScope;
+
+/**
+ * What a tracking number opened on the public page: the order, the customer within it
+ * whose stops the visitor may see (null when the order names nobody), the stop the number
+ * belongs to when it is a stop's or an item's, and the owning company's page config.
+ */
+final class TrackingTarget
+{
+    public const KIND_ORDER = 'order';
+    public const KIND_STOP  = 'stop';
+    public const KIND_ITEM  = 'item';
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly ?TrackingScope $scope,
+        public readonly TrackingNumber $trackingNumber,
+        public readonly string $kind = self::KIND_ORDER,
+        public readonly ?Waypoint $waypoint = null,
+        public readonly array $config = [],
+    ) {
+    }
+
+    public function withConfig(array $config): self
+    {
+        return new self($this->order, $this->scope, $this->trackingNumber, $this->kind, $this->waypoint, $config);
+    }
+
+    public function companyUuid(): ?string
+    {
+        return $this->order->company_uuid;
+    }
+}