Skip to content

A free open source IT asset/license management system

51.1 KB
Raw Blame
<?php

namespace App\SyncAdapters\AppleBusinessManager;

use App\Models\AssetModel;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\SyncAdapter;
use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;

/**
 * Apple Business Manager (ABM) / Apple School Manager (ASM) adapter.
 * Pulls the master device roster from Apple's org-devices API using
 * JWT client-assertion auth (ES256, signed with an EC P-256 private
 * key downloaded from Apple's admin console).
 *
 * ABM is a purchase-registration portal, not a runtime inventory.
 * Devices show up here as soon as they're bought via an
 * Apple-integrated reseller, before enrollment, before OS install.
 * That means hostname, OS version, last-seen, and MAC address are
 * null in every record: those become populated later once the device
 * enrolls in an MDM (Jamf, Kandji, Mosyle, Intune, etc). The point of
 * the ABM adapter is to pre-populate Snipe-IT with the authoritative
 * "we own this serial" list before an MDM enrolls it, or to pick up
 * devices the MDM never sees (spares, decommissioned, in-transit).
 *
 * Groups: ABM has Organizations/Sites concepts, but the device record
 * doesn't expose an org-scoped foreign key today. Group scoping is
 * off. If admins want per-Snipe-IT-company routing, they run one
 * adapter instance per company for now.
 *
 * Push: not implemented. Apple's write endpoints (device metadata,
 * MDM server assignment) are outside Snipe-IT's authoritative scope.
 */
class AppleBusinessManagerAdapter extends SyncAdapter
{
    use UsesAppleDbEnrichment;

    /**
     * Apple's fixed productFamily enum -> friendly display name.
     * Drives the product-family filter's option list.
     *
     * @var array<string, string>
     */
    private const PRODUCT_FAMILIES = [
        'Mac' => 'Mac',
        'iPhone' => 'iPhone',
        'iPad' => 'iPad',
        'AppleTV' => 'Apple TV',
        'Watch' => 'Apple Watch',
        'Vision' => 'Apple Vision',
    ];

    /**
     * Per-category-selector config keys -> friendly display name.
     * Distinct from PRODUCT_FAMILIES because Mac's productFamily
     * collapses laptops and desktops into one bucket, but admins
     * usually want to route them to different Snipe-IT categories
     * ("Laptops" vs "Desktops"), so the "Mac" family gets split
     * into two selectors driven by deviceModel prefix.
     * categoryConfigKeyForFamily() encodes the mapping in the other
     * direction.
     *
     * @var array<string, string>
     */
    private const CATEGORY_SELECTORS = [
        'category_id_mac_laptop' => 'Mac Laptop',
        'category_id_mac_desktop' => 'Mac Desktop',
        'category_id_iphone' => 'iPhone',
        'category_id_ipad' => 'iPad',
        'category_id_appletv' => 'Apple TV',
        'category_id_watch' => 'Apple Watch',
        'category_id_vision' => 'Apple Vision',
    ];

    public static function typeLabel(): string
    {
        return 'Apple Business Manager';
    }

    public static function typeSlug(): string
    {
        return 'abm';
    }

    public static function docsUrl(): ?string
    {
        return 'https://developer.apple.com/documentation/apple-school-and-business-manager-api';
    }

    /**
     * ABM/ASM base URLs are host-fixed per mode (business or school),
     * so the admin never types a URL. Mode selection in the
     * credential schema controls host + scope inside
     * AppleBusinessManagerClient::apiBaseUrl.
     */
    public function usesConfigurableUrl(): bool
    {
        return false;
    }

    public function settingsSchema(): array
    {
        $schema = [
            [
                'key' => 'mode',
                'label' => trans('admin/settings/sync_adapters.abm_label_portal'),
                'type' => 'select',
                'options' => [
                    'business' => trans('admin/settings/sync_adapters.abm_option_mode_business'),
                    'school' => trans('admin/settings/sync_adapters.abm_option_mode_school'),
                ],
                'help' => trans('admin/settings/sync_adapters.abm_mode_help'),
            ],
            [
                'key' => 'client_id',
                'label' => trans('admin/settings/sync_adapters.label_client_id'),
                'help' => trans('admin/settings/sync_adapters.abm_client_id_help'),
            ],
            [
                'key' => 'key_id',
                'label' => trans('admin/settings/sync_adapters.abm_label_key_id'),
                'help' => trans('admin/settings/sync_adapters.abm_key_id_help'),
            ],
            [
                'key' => 'private_key',
                'label' => trans('admin/settings/sync_adapters.abm_label_private_key'),
                'type' => 'textarea',
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.abm_private_key_help'),
                'placeholder' => "-----BEGIN PRIVATE KEY-----\n1234567890\n-----END PRIVATE KEY-----",
            ],
            [
                'key' => 'product_family_filter',
                'label' => trans('admin/settings/sync_adapters.abm_label_product_families'),
                'type' => 'multiselect',
                'options' => self::PRODUCT_FAMILIES,
                'default' => array_keys(self::PRODUCT_FAMILIES),
                'required' => false,
                'help' => trans('admin/settings/sync_adapters.abm_product_family_filter_help'),
            ],
            $this->appleDbSettingsField(),
        ];

        // Per-family category overrides. Apple's productFamily is a
        // fixed enum, so admins can route iPads to "Tablets", Watches
        // to "Wearables", etc. Mac is split into laptop + desktop
        // because Apple lumps them together and admins usually want
        // them in separate Snipe-IT categories. Empty selection falls
        // back to default_category_id. Label + help share one
        // :family-templated translation each so localizers translate
        // the strings once rather than seven times.
        foreach (self::CATEGORY_SELECTORS as $key => $displayName) {
            $schema[] = [
                'key' => $key,
                'label' => trans('admin/settings/sync_adapters.abm_category_family_label', ['family' => $displayName]),
                'type' => 'category',
                'required' => false,
                'section' => 'categories',
                'help' => trans('admin/settings/sync_adapters.abm_category_family_help', ['family' => $displayName]),
            ];
        }

        return $schema;
    }

    /**
     * Section titles for the credential schema. The category
     * selectors are the only grouped block here. Everything else
     * (auth + toggles) stays flat above them because there are only
     * a handful of top-level fields.
     */
    public function settingsSections(): array
    {
        return [
            'categories' => [
                'title' => trans('admin/settings/sync_adapters.abm_section_categories_title'),
            ],
        ];
    }

    /**
     * Parse the private key at save time so a malformed paste
     * (stripped dash, wrong key type, etc) fails now instead
     * of at the next pull with an OpenSSL error.
     */
    public function validationRules(): array
    {
        $rules = parent::validationRules();
        $slug = $this->instance->slug;
        $key = $slug.'_private_key';

        $rules[$key] = array_merge($rules[$key] ?? ['required', 'string'], [
            function (string $attribute, mixed $value, \Closure $fail): void {
                if (! is_string($value) || $value === '') {
                    return;
                }

                $parsed = @openssl_pkey_get_private($value);
                if ($parsed === false) {
                    $fail(trans('admin/settings/sync_adapters.abm_private_key_invalid'));

                    return;
                }

                $details = openssl_pkey_get_details($parsed);
                $type = $details['type'] ?? null;
                // OpenSSL and NIST spell the P-256 curve differently.
                $curve = $details['ec']['curve_name'] ?? null;
                $isP256Ec = $type === OPENSSL_KEYTYPE_EC && in_array($curve, ['prime256v1', 'secp256r1'], true);
                if (! is_array($details) || ! $isP256Ec) {
                    $fail(trans('admin/settings/sync_adapters.abm_private_key_unsupported'));
                }
            },
        ]);

        return $rules;
    }

    public function extraFields(): array
    {
        return [
            ...$this->appleDbExtraFieldsDeclaration(),
            'abm_product_family' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_product_family'],
            'abm_model_marketing_name' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_model_marketing_name'],
            'abm_product_type' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_product_type'],
            'abm_part_number' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_part_number'],
            'abm_color' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_color'],
            'abm_order_number' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_order_number'],
            'abm_order_date' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_order_date', 'type' => 'date'],
            'abm_purchase_source_type' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_purchase_source_type'],
            'abm_purchase_source_id' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_purchase_source_id'],
            'abm_mdm_server' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_mdm_server'],
            'abm_applecare_agreement_number' => ['label_key' => 'admin/settings/sync_adapters.extra_applecare_agreement_number'],
            'abm_applecare_status' => ['label_key' => 'admin/settings/sync_adapters.extra_applecare_status'],
            'abm_applecare_payment_type' => ['label_key' => 'admin/settings/sync_adapters.extra_applecare_payment_type'],
            'abm_applecare_start_date' => ['label_key' => 'admin/settings/sync_adapters.extra_applecare_start_date', 'type' => 'date'],
            'abm_applecare_end_date' => ['label_key' => 'admin/settings/sync_adapters.extra_applecare_end_date', 'type' => 'date'],
            'abm_applecare_description' => ['label_key' => 'admin/settings/sync_adapters.extra_applecare_description'],
            'abm_applecare_is_canceled' => ['label_key' => 'admin/settings/sync_adapters.extra_applecare_is_canceled', 'type' => 'boolean'],
            'abm_applecare_is_renewable' => ['label_key' => 'admin/settings/sync_adapters.extra_applecare_is_renewable', 'type' => 'boolean'],
            'abm_device_capacity' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_device_capacity'],
            'abm_wifi_mac' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_wifi_mac'],
            'abm_bluetooth_mac' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_bluetooth_mac'],
            // Desktop Macs with two Ethernet NICs (Mac Pro, iMac Pro)
            // return ethernetMacAddress as a two-element array. Split
            // positionally so admins can map each physical port to its
            // own Snipe-IT custom field. #19877.
            'abm_ethernet_mac_1' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_ethernet_mac_1'],
            'abm_ethernet_mac_2' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_ethernet_mac_2'],
            // Apple returns IMEIs as an array (dual-SIM iPhones carry
            // two, older devices one). Positional split so admins can
            // map each to its own custom field. #19754.
            'abm_imei_1' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_imei_1'],
            'abm_imei_2' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_imei_2'],
            'abm_meid' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_meid'],
            'abm_eid' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_eid'],
            'abm_added_to_org' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_added_to_org', 'type' => 'date'],
            'abm_released_from_org' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_released_from_org', 'type' => 'date'],
            'abm_org_status' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_org_status'],
            'abm_activation_lock_enabled' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_activation_lock_enabled', 'type' => 'boolean'],
            // Apple Business Manager's built-in MDM (formerly Apple
            // Business Essentials). Native slots (hostname, os,
            // osVersion, lastSeen, primaryMac, imei, meid) are
            // overridden from the MDM detail endpoint when we have it
            // since MDM is runtime truth. The extras below are the
            // MDM-only fields that don't correspond to native slots.
            'abm_mdm_file_vault_enabled' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_mdm_file_vault_enabled', 'type' => 'boolean'],
            'abm_mdm_firewall_enabled' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_mdm_firewall_enabled', 'type' => 'boolean'],
            'abm_mdm_device_lock_status' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_mdm_device_lock_status'],
            'abm_mdm_lost_mode_status' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_mdm_lost_mode_status'],
            'abm_mdm_device_erase_status' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_mdm_device_erase_status'],
            'abm_mdm_storage_total_gb' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_mdm_storage_total_gb'],
            'abm_mdm_storage_free_gb' => ['label_key' => 'admin/settings/sync_adapters.abm_extra_mdm_storage_free_gb'],
        ];
    }

    /**
     * Route each record to a per-productFamily category when the
     * admin configured one. Apple's productFamily is a fixed
     * six-value enum (Mac, iPhone, iPad, AppleTV, Watch, Vision), so
     * the mapping is exhaustive by design. Any family the admin
     * hasn't overridden falls through to defaultCategoryId() via
     * the framework's null-return convention.
     */
    public function categoryIdForRecord(HostInventoryRecord $record): ?int
    {
        $configKey = self::categoryConfigKeyForRecord($record);
        if ($configKey === null) {
            return null;
        }

        try {
            $stored = $this->credential($configKey);
        } catch (\Throwable) {
            return null;
        }

        return $stored === '' ? null : (int) $stored;
    }

    /**
     * Which per-family credential key applies to this record. Mac is
     * split into laptop / desktop based on the marketing name prefix:
     * "MacBook*" is a laptop, anything starting with iMac, Mac mini,
     * Mac Studio, or Mac Pro is a desktop. Marketing name is used
     * because productType lost its form-factor tag on Apple Silicon
     * (M-series desktops all report bare "Mac14,x"/"Mac15,x" with no
     * iMac/Macmini/MacPro prefix).
     *
     * Returns null when the family is unrecognized OR for Macs with
     * an unparseable marketing name, so the framework falls back to
     * defaultCategoryId() rather than saving under an arbitrary
     * bucket.
     */
    private static function categoryConfigKeyForRecord(HostInventoryRecord $record): ?string
    {
        $family = $record->extra['abm_product_family'] ?? null;
        if (! is_string($family)) {
            return null;
        }

        if ($family === 'Mac') {
            $deviceModel = $record->extra['abm_model_marketing_name'] ?? '';
            if (! is_string($deviceModel) || $deviceModel === '') {
                return null;
            }
            if (str_starts_with($deviceModel, 'MacBook')) {
                return 'category_id_mac_laptop';
            }
            foreach (['iMac', 'Mac mini', 'Mac Studio', 'Mac Pro'] as $desktopPrefix) {
                if (str_starts_with($deviceModel, $desktopPrefix)) {
                    return 'category_id_mac_desktop';
                }
            }

            return null;
        }

        return match ($family) {
            'iPhone' => 'category_id_iphone',
            'iPad' => 'category_id_ipad',
            'AppleTV' => 'category_id_appletv',
            'Watch' => 'category_id_watch',
            'Vision' => 'category_id_vision',
            default => null,
        };
    }

    public function pull(): iterable
    {
        $client = new AppleBusinessManagerClient(
            clientId: $this->credential('client_id'),
            keyId: $this->credential('key_id'),
            privateKeyPem: $this->credential('private_key'),
            mode: $this->resolvedMode(),
        );

        // Build the device-to-MDM-server map up front so normalize()
        // can attach each device's assigned server name without a
        // per-device API call. Best-effort: failures leave the map
        // empty and every asset just gets a null abm_mdm_server.
        $deviceToServer = [];
        try {
            $deviceToServer = $client->deviceToMdmServerMap();
        } catch (\Throwable $e) {
            Log::channel('sync-adapters')->warning(sprintf(
                '%s mdm-server map fetch failed: %s',
                $this->name(),
                $e->getMessage(),
            ));
        }

        // Only fetch AppleCare coverage per device when at least one
        // applecare extra field is mapped. Fetching AppleCare adds an
        // API call per device, so admins who don't care about
        // warranty tracking skip the cost entirely.
        $enrichWithAppleCare = $this->hasMappedAppleCareFields();

        // Same opt-in gate for Activation Lock. Same N+1 shape as
        // AppleCare (one extra API call per device), so we skip it
        // unless the admin has mapped the extra.
        $enrichWithActivationLock = $this->hasMappedActivationLockField();

        // Apple Business Manager's built-in MDM (formerly Apple
        // Business Essentials). The list endpoint is one call per sync
        // run and gives us hostname + os, so we always fetch it.
        // Build a serial -> mdmDevice basic-info map for the join.
        // Best-effort: failures leave the map empty and records stay
        // un-enriched.
        $serialToMdmDevice = [];
        try {
            foreach ($client->mdmDevices() as $mdmDevice) {
                $serial = (string) ($mdmDevice['id'] ?? '');
                if ($serial !== '') {
                    $serialToMdmDevice[$serial] = $mdmDevice;
                }
            }
        } catch (\Throwable $e) {
            Log::channel('sync-adapters')->warning(sprintf(
                '%s mdmDevices list fetch failed: %s',
                $this->name(),
                $e->getMessage(),
            ));
        }

        // Detail endpoint is one call per MDM-enrolled device, so it's
        // gated behind at least one MDM-detail extra being mapped.
        $enrichWithMdmDetail = $this->hasMappedMdmDeviceDetailFields();

        // Allowed product families (lower-cased for comparison).
        // Empty means "all families".
        $allowedFamilies = $this->allowedProductFamilies();

        // Model-image enrichment fetches from appledb.dev, so it's
        // opt-in and off by default. Per-pull cache keyed by
        // hardwareModel avoids re-fetching the same image when a
        // tenant has many devices of the same model.
        $pullImages = $this->appleDbEnrichmentEnabled();
        $imagesHandled = [];

        foreach ($client->devices() as $device) {
            $family = strtolower((string) ($device['attributes']['productFamily'] ?? ''));
            if ($allowedFamilies !== [] && ! in_array($family, $allowedFamilies, true)) {
                continue;
            }
            $record = $this->normalize($device, $deviceToServer);
            if ($enrichWithAppleCare) {
                $record = $this->enrichRecordWithAppleCare($record, $client);
            }
            if ($enrichWithActivationLock) {
                $record = $this->enrichRecordWithActivationLock($record, $client);
            }
            $mdmDevice = $serialToMdmDevice[$record->hardwareSerial] ?? null;
            if ($mdmDevice !== null) {
                $record = $this->enrichRecordWithMdmDeviceBasics($record, $mdmDevice);
                if ($enrichWithMdmDetail) {
                    $record = $this->enrichRecordWithMdmDeviceDetail($record, $client);
                }
            }
            if ($pullImages) {
                $imagesHandled = $this->ensureModelImage($record, $imagesHandled);
            }
            yield $record;
        }
    }

    /**
     * Resolve the ABM-side model name + productType and delegate to
     * the shared enrichModelFromAppleDb helper. ABM's native:model
     * mapping routes `abm_model_marketing_name` into AssetModel::name
     * when the admin opts in, so the image lookup has to mirror that
     * so it targets the row the framework will actually create.
     *
     * @param  array<string, bool>  $imagesHandled
     * @return array<string, bool>
     */
    private function ensureModelImage(HostInventoryRecord $record, array $imagesHandled): array
    {
        $modelName = $this->mappingFor('abm_model_marketing_name') === 'native:model'
            ? ($record->extra['abm_model_marketing_name'] ?? $record->hardwareModel)
            : $record->hardwareModel;

        if ($modelName === null || $modelName === '') {
            Log::channel('sync-adapters')->info("{$this->name()} enrichment skip for device {$record->sourceId}: no model name resolvable (hardwareModel and abm_model_marketing_name both blank)");

            return $imagesHandled;
        }

        $productType = $record->extra['abm_product_type'] ?? null;
        if (! is_string($productType) || $productType === '') {
            Log::channel('sync-adapters')->info("{$this->name()} enrichment skip for model \"{$modelName}\": ABM did not return a productType, nothing to look up on appledb.dev");

            return $imagesHandled;
        }

        $color = $record->extra['abm_color'] ?? null;

        return $this->enrichModelFromAppleDb(
            $modelName,
            $productType,
            is_string($color) ? $color : null,
            $imagesHandled,
        );
    }

    /**
     * Parse the admin-configured product-family multiselect into a
     * lower-cased array. Empty / unset returns an empty array, which
     * pull() reads as "allow every family." Persisted as JSON by
     * the base class's multiselect handler.
     *
     * @return array<int, string>
     */
    private function allowedProductFamilies(): array
    {
        try {
            $raw = $this->credential('product_family_filter');
        } catch (\Throwable) {
            return [];
        }

        if ($raw === '') {
            return [];
        }

        $decoded = json_decode($raw, true);
        if (! is_array($decoded)) {
            return [];
        }

        return array_values(array_map('strtolower', array_filter($decoded, 'is_string')));
    }

    /**
     * Whether at least one AppleCare-shaped extra has a non-skip
     * mapping stored. Gates the per-device AppleCare fetch in pull()
     * so admins who don't map any AppleCare field don't pay for the
     * enrichment.
     */
    private function hasMappedAppleCareFields(): bool
    {
        foreach (array_keys($this->extraFields()) as $key) {
            if (! str_starts_with($key, 'abm_applecare_')) {
                continue;
            }
            $target = $this->mappingFor($key);
            if ($target !== '' && $target !== 'skip') {
                return true;
            }
        }

        return false;
    }

    /**
     * Gate for the Activation Lock enrichment. True when the admin has
     * routed the single abm_activation_lock_enabled extra to a real
     * target. Same shape as hasMappedAppleCareFields but scoped to one
     * key.
     */
    private function hasMappedActivationLockField(): bool
    {
        $target = $this->mappingFor('abm_activation_lock_enabled');

        return $target !== '' && $target !== 'skip';
    }

    /**
     * Gate for the MDM device-detail enrichment. True when the admin
     * has mapped any of the detail-endpoint-only extras (FileVault,
     * firewall, lock/lost/erase status, storage). The list-endpoint
     * enrichment (hostname + os) always runs regardless since the list
     * fetch is one call total.
     */
    private function hasMappedMdmDeviceDetailFields(): bool
    {
        foreach (array_keys($this->extraFields()) as $key) {
            if (! str_starts_with($key, 'abm_mdm_')) {
                continue;
            }
            $target = $this->mappingFor($key);
            if ($target !== '' && $target !== 'skip') {
                return true;
            }
        }

        return false;
    }

    /**
     * Fetch AppleCare coverage for one asset, pick the most relevant
     * plan, and merge its fields into the record's extras. On empty
     * or failed responses we just return the un-enriched record so
     * the sync doesn't stall on transient AppleCare-endpoint issues.
     */
    private function enrichRecordWithAppleCare(HostInventoryRecord $record, AppleBusinessManagerClient $client): HostInventoryRecord
    {
        try {
            $coverages = $client->deviceAppleCareCoverage($record->sourceId);
        } catch (\Throwable $e) {
            Log::channel('sync-adapters')->warning(sprintf(
                '%s applecare fetch failed for device %s: %s',
                $this->name(),
                $record->sourceId,
                $e->getMessage(),
            ));

            return $record;
        }

        $best = self::pickBestCoverage($coverages);
        if ($best === null) {
            return $record;
        }

        $extra = $record->extra;
        $extra['abm_applecare_agreement_number'] = $best['agreementNumber'] ?? null;
        $extra['abm_applecare_status'] = self::titleCase($best['status'] ?? null);
        $extra['abm_applecare_payment_type'] = self::titleCase($best['paymentType'] ?? null);
        $extra['abm_applecare_start_date'] = self::parseOrderDate($best['startDateTime'] ?? null);
        $extra['abm_applecare_end_date'] = self::parseOrderDate($best['endDateTime'] ?? null);
        $extra['abm_applecare_description'] = $best['description'] ?? null;
        $extra['abm_applecare_is_canceled'] = $best['isCanceled'] ?? null;
        $extra['abm_applecare_is_renewable'] = $best['isRenewable'] ?? null;

        return new HostInventoryRecord(
            sourceKey: $record->sourceKey,
            sourceId: $record->sourceId,
            hostname: $record->hostname,
            hardwareSerial: $record->hardwareSerial,
            hardwareModel: $record->hardwareModel,
            manufacturer: $record->manufacturer,
            primaryMac: $record->primaryMac,
            primaryIp: $record->primaryIp,
            os: $record->os,
            osVersion: $record->osVersion,
            lastSeen: $record->lastSeen,
            assetTag: $record->assetTag,
            assignedUserEmail: $record->assignedUserEmail,
            assignedUserName: $record->assignedUserName,
            vendorGroupId: $record->vendorGroupId,
            extra: $extra,
        );
    }

    /**
     * Fetch Activation Lock status for one asset and merge into the
     * record's extras. Handy for asset checkin flows because AL has
     * to be cleared before a device can be redeployed to a new user.
     * On empty or failed responses just return the un-enriched record
     * so the sync doesn't stall on a transient AL endpoint issue.
     */
    private function enrichRecordWithActivationLock(HostInventoryRecord $record, AppleBusinessManagerClient $client): HostInventoryRecord
    {
        try {
            $status = $client->deviceActivationLockStatus($record->sourceId);
        } catch (\Throwable $e) {
            Log::channel('sync-adapters')->warning(sprintf(
                '%s activation lock fetch failed for device %s: %s',
                $this->name(),
                $record->sourceId,
                $e->getMessage(),
            ));

            return $record;
        }

        $enabled = Arr::get($status, 'attributes.activationLockEnabled');
        if (! is_bool($enabled)) {
            return $record;
        }

        $extra = $record->extra;
        $extra['abm_activation_lock_enabled'] = $enabled;

        return new HostInventoryRecord(
            sourceKey: $record->sourceKey,
            sourceId: $record->sourceId,
            hostname: $record->hostname,
            hardwareSerial: $record->hardwareSerial,
            hardwareModel: $record->hardwareModel,
            manufacturer: $record->manufacturer,
            primaryMac: $record->primaryMac,
            primaryIp: $record->primaryIp,
            os: $record->os,
            osVersion: $record->osVersion,
            lastSeen: $record->lastSeen,
            assetTag: $record->assetTag,
            assignedUserEmail: $record->assignedUserEmail,
            assignedUserName: $record->assignedUserName,
            vendorGroupId: $record->vendorGroupId,
            extra: $extra,
        );
    }

    /**
     * Merge the cheap MDM-list-endpoint fields onto the record.
     * Populates hostname (deviceName) and os (derived from
     * productFamily). Called only when we have a matching mdmDevice
     * for this record's serial.
     *
     * @param  array<string, mixed>  $mdmDevice
     */
    private function enrichRecordWithMdmDeviceBasics(HostInventoryRecord $record, array $mdmDevice): HostInventoryRecord
    {
        $attrs = $mdmDevice['attributes'] ?? [];
        $deviceName = Arr::get($attrs, 'deviceName');
        $family = (string) Arr::get($attrs, 'productFamily', '');

        return new HostInventoryRecord(
            sourceKey: $record->sourceKey,
            sourceId: $record->sourceId,
            hostname: is_string($deviceName) && $deviceName !== '' ? $deviceName : $record->hostname,
            hardwareSerial: $record->hardwareSerial,
            hardwareModel: $record->hardwareModel,
            manufacturer: $record->manufacturer,
            primaryMac: $record->primaryMac,
            primaryIp: $record->primaryIp,
            os: self::osFromProductFamily($family) ?? $record->os,
            osVersion: $record->osVersion,
            lastSeen: $record->lastSeen,
            assetTag: $record->assetTag,
            assignedUserEmail: $record->assignedUserEmail,
            assignedUserName: $record->assignedUserName,
            vendorGroupId: $record->vendorGroupId,
            extra: $record->extra,
        );
    }

    /**
     * Fetch and merge the per-device MDM detail endpoint fields.
     * Runtime data wins: MDM's osVersion, lastCheckInDateTime, MAC
     * addresses, imei, meid override whatever the orgDevices path
     * populated. FileVault, firewall, lock/lost/erase statuses, and
     * storage go into extras. On empty or failed responses return
     * the un-enriched record so a transient MDM detail-endpoint issue
     * doesn't stall the sync.
     */
    private function enrichRecordWithMdmDeviceDetail(HostInventoryRecord $record, AppleBusinessManagerClient $client): HostInventoryRecord
    {
        try {
            $detail = $client->mdmDeviceDetails($record->hardwareSerial);
        } catch (\Throwable $e) {
            Log::channel('sync-adapters')->warning(sprintf(
                '%s mdmDevice detail fetch failed for device %s: %s',
                $this->name(),
                $record->sourceId,
                $e->getMessage(),
            ));

            return $record;
        }

        $attrs = $detail['attributes'] ?? [];
        if (! is_array($attrs) || $attrs === []) {
            return $record;
        }

        return new HostInventoryRecord(
            sourceKey: $record->sourceKey,
            sourceId: $record->sourceId,
            hostname: $record->hostname,
            hardwareSerial: $record->hardwareSerial,
            hardwareModel: $record->hardwareModel,
            manufacturer: $record->manufacturer,
            primaryMac: self::pickMdmPrimaryMac($attrs, $record->primaryMac),
            primaryIp: $record->primaryIp,
            os: $record->os,
            osVersion: self::firstNonEmptyString(Arr::get($attrs, 'osVersion'), $record->osVersion),
            lastSeen: self::parseMdmTimestamp(Arr::get($attrs, 'lastCheckInDateTime'), $record->lastSeen),
            assetTag: $record->assetTag,
            assignedUserEmail: $record->assignedUserEmail,
            assignedUserName: $record->assignedUserName,
            vendorGroupId: $record->vendorGroupId,
            extra: self::mergeMdmDetailExtras($record->extra, $attrs),
        );
    }

    /**
     * Return $preferred if it is a non-empty string, else $fallback.
     * Extracted so enrichRecordWithMdmDeviceDetail doesn't blow its
     * NPath budget on inline ternaries.
     */
    private static function firstNonEmptyString(mixed $preferred, mixed $fallback): mixed
    {
        if (is_string($preferred) && $preferred !== '') {
            return $preferred;
        }

        return $fallback;
    }

    /**
     * Normalize MDM-reported bytes (storageTotalCapacity /
     * storageFreeCapacity) to GB for cross-adapter consistency with
     * the other storage extras across sync adapters. Divides by 10^9
     * (decimal GB, same convention Apple uses in marketed capacity).
     * Null or non-numeric input returns null so an unpopulated field
     * stays unpopulated rather than becoming a bogus 0 GB that an
     * admin filter could misread.
     */
    private static function bytesToGb(mixed $bytes): int|float|null
    {
        if (! is_numeric($bytes)) {
            return null;
        }
        $gb = $bytes / 1_000_000_000;

        return $gb == (int) $gb ? (int) $gb : round($gb, 2);
    }

    /**
     * Pick the primary MAC from the MDM detail attributes. Prefers
     * Wi-Fi, falls back to Ethernet (desktops without Wi-Fi), then
     * whatever the orgDevices path already set.
     *
     * @param  array<string, mixed>  $attrs
     */
    private static function pickMdmPrimaryMac(array $attrs, ?string $fallback): ?string
    {
        $wifi = self::normalizeMacAddress(Arr::get($attrs, 'wifiMacAddress'));
        if ($wifi !== null) {
            return $wifi;
        }

        // ethernetMacAddress can be a two-element array on Macs with two
        // physical ports. Prefer the first slot so the primaryMac field
        // on a non-wifi Mac still populates something sensible.
        $ethernet = self::extractMacAtIndex(Arr::get($attrs, 'ethernetMacAddress'), 0);
        if ($ethernet !== null) {
            return $ethernet;
        }

        return $fallback;
    }

    /**
     * Parse an MDM timestamp string to Carbon, falling back to the
     * caller-supplied $fallback when the value is missing or Carbon
     * can't parse it.
     */
    private static function parseMdmTimestamp(mixed $value, ?Carbon $fallback): ?Carbon
    {
        if (! is_string($value) || $value === '') {
            return $fallback;
        }

        try {
            return Carbon::parse($value);
        } catch (\Throwable) {
            return $fallback;
        }
    }

    /**
     * Merge MDM detail attributes into the record's existing extras.
     * The seven detail-only fields (FileVault, firewall, statuses,
     * storage) always overwrite. The shared extras (MACs, imei, meid)
     * only overwrite when MDM has a non-empty value, so the orgDevices
     * value stays as the fallback.
     *
     * @param  array<string, mixed>  $extra
     * @param  array<string, mixed>  $attrs
     * @return array<string, mixed>
     */
    private static function mergeMdmDetailExtras(array $extra, array $attrs): array
    {
        $extra['abm_mdm_file_vault_enabled'] = Arr::get($attrs, 'isFileVaultEnabled');
        $extra['abm_mdm_firewall_enabled'] = Arr::get($attrs, 'isFirewallEnabled');
        $extra['abm_mdm_device_lock_status'] = Arr::get($attrs, 'deviceLockStatus');
        $extra['abm_mdm_lost_mode_status'] = Arr::get($attrs, 'lostModeStatus');
        $extra['abm_mdm_device_erase_status'] = Arr::get($attrs, 'deviceEraseStatus');
        $extra['abm_mdm_storage_total_gb'] = self::bytesToGb(Arr::get($attrs, 'storageTotalCapacity'));
        $extra['abm_mdm_storage_free_gb'] = self::bytesToGb(Arr::get($attrs, 'storageFreeCapacity'));

        // Wi-Fi and Bluetooth are single-radio on every current Apple
        // SKU so they stay scalar. Ethernet can be a two-element array
        // on dual-NIC Macs, so split positionally like IMEI.
        $singleMacMap = [
            'wifiMacAddress' => 'abm_wifi_mac',
            'bluetoothMacAddress' => 'abm_bluetooth_mac',
        ];
        foreach ($singleMacMap as $mdmKey => $extraKey) {
            $val = self::normalizeMacAddress(Arr::get($attrs, $mdmKey));
            if ($val !== null) {
                $extra[$extraKey] = $val;
            }
        }

        $mdmEthernet = Arr::get($attrs, 'ethernetMacAddress');
        $ethernet1 = self::extractMacAtIndex($mdmEthernet, 0);
        if ($ethernet1 !== null) {
            $extra['abm_ethernet_mac_1'] = $ethernet1;
        }
        $ethernet2 = self::extractMacAtIndex($mdmEthernet, 1);
        if ($ethernet2 !== null) {
            $extra['abm_ethernet_mac_2'] = $ethernet2;
        }

        // IMEI is an array in both orgDevices and MDM-detail shapes.
        // Overwrite each positional slot only when MDM has a value so
        // the orgDevices value stays as the fallback.
        $mdmImei = Arr::get($attrs, 'imei');
        $first = self::extractImeiAtIndex($mdmImei, 0);
        if ($first !== null) {
            $extra['abm_imei_1'] = $first;
        }
        $second = self::extractImeiAtIndex($mdmImei, 1);
        if ($second !== null) {
            $extra['abm_imei_2'] = $second;
        }

        $meid = Arr::get($attrs, 'meid');
        if ($meid !== null && $meid !== '') {
            $extra['abm_meid'] = $meid;
        }

        return $extra;
    }

    /**
     * Insert the colons Snipe-IT's MAC custom-field validator
     * requires. Apple's APIs return bare 12-hex-char strings
     * (`0123456789AB`) and occasionally the 16-char EUI-64 shape for
     * Bluetooth. Both get normalized to colon-separated uppercase
     * pairs. Non-hex characters are stripped so an already-formatted
     * value round-trips cleanly. Returns null for null, empty, or
     * non-string input, or when the stripped hex isn't a valid length.
     */
    private static function normalizeMacAddress(mixed $raw): ?string
    {
        if (! is_string($raw) || $raw === '') {
            return null;
        }

        $hex = strtoupper((string) preg_replace('/[^0-9A-Fa-f]/', '', $raw));
        $length = strlen($hex);
        if ($length !== 12 && $length !== 16) {
            return null;
        }

        return rtrim(chunk_split($hex, 2, ':'), ':');
    }

    /**
     * Pick a single IMEI out of Apple's `imei` field, which is
     * typically an array (dual-SIM carries two, single-SIM carries a
     * one-element array). A bare-scalar shape is tolerated as a
     * fallback so vendor-side drift doesn't drop a valid IMEI into
     * nothing - a scalar fills slot 0 and leaves slot 1 null.
     * Returns null when the slot is absent, when the value isn't a
     * non-empty string, or when a scalar is requested for slot 1.
     */
    /**
     * Pick a single MAC out of Apple's `ethernetMacAddress` field,
     * which is a two-element array on Macs with two physical NICs and
     * a bare string on everything else. Shape semantics mirror
     * extractImeiAtIndex: scalar fills slot 0 only, array indexes
     * positionally, anything else returns null. The returned value
     * passes through normalizeMacAddress so the colon-separated upper-
     * case shape custom-field validators expect round-trips cleanly.
     */
    private static function extractMacAtIndex(mixed $value, int $index): ?string
    {
        if (is_string($value)) {
            return $index === 0 ? self::normalizeMacAddress($value) : null;
        }
        if (! is_array($value)) {
            return null;
        }

        return self::normalizeMacAddress($value[$index] ?? null);
    }

    private static function extractImeiAtIndex(mixed $value, int $index): ?string
    {
        if (is_string($value)) {
            return $index === 0 && $value !== '' ? $value : null;
        }
        if (! is_array($value)) {
            return null;
        }
        $imei = $value[$index] ?? null;
        if (! is_string($imei) || $imei === '') {
            return null;
        }

        return $imei;
    }

    /**
     * Apple's productFamily enum to the runtime OS name customers
     * expect to see in the assets table. Returns null for families
     * without a well-known OS name so callers can leave the field
     * alone rather than blanking it.
     */
    private static function osFromProductFamily(string $family): ?string
    {
        return match ($family) {
            'Mac' => 'macOS',
            'iPhone' => 'iOS',
            'iPad' => 'iPadOS',
            'AppleTV' => 'tvOS',
            'Watch' => 'watchOS',
            'Vision' => 'visionOS',
            default => null,
        };
    }

    /**
     * Pick the most relevant AppleCare coverage plan for a device.
     * A device can carry multiple overlapping plans (renewals,
     * add-ons, prior canceled ones). Ranking mirrors axm2snipe's
     * approach so an org migrating from that tool sees the same
     * coverage on each asset:
     *   1. ACTIVE status beats INACTIVE
     *   2. PAID_UP_FRONT payment type beats subscription / none
     *   3. Later endDateTime wins the final tiebreaker
     *
     * Returns the winning attributes array, or null when the list is
     * empty / every entry lacks attributes.
     *
     * @param  array<int, array<string, mixed>>  $coverages
     * @return array<string, mixed>|null
     */
    private static function pickBestCoverage(array $coverages): ?array
    {
        $best = null;
        foreach ($coverages as $coverage) {
            $attrs = $coverage['attributes'] ?? null;
            if (! is_array($attrs)) {
                continue;
            }
            if ($best === null) {
                $best = $attrs;

                continue;
            }
            if (self::coverageIsBetter($attrs, $best)) {
                $best = $attrs;
            }
        }

        return $best;
    }

    /**
     * Ordering predicate for two AppleCare coverage attribute maps.
     * See pickBestCoverage() for the ranking rules.
     *
     * @param  array<string, mixed>  $candidate
     * @param  array<string, mixed>  $current
     */
    private static function coverageIsBetter(array $candidate, array $current): bool
    {
        $candidateActive = ($candidate['status'] ?? '') === 'ACTIVE';
        $currentActive = ($current['status'] ?? '') === 'ACTIVE';
        if ($candidateActive !== $currentActive) {
            return $candidateActive;
        }

        $candidatePaid = ($candidate['paymentType'] ?? '') === 'PAID_UP_FRONT';
        $currentPaid = ($current['paymentType'] ?? '') === 'PAID_UP_FRONT';
        if ($candidatePaid !== $currentPaid) {
            return $candidatePaid;
        }

        $candidateEnd = $candidate['endDateTime'] ?? null;
        $currentEnd = $current['endDateTime'] ?? null;
        if (! is_string($candidateEnd) || ! is_string($currentEnd)) {
            return false;
        }

        return Carbon::parse($candidateEnd)->greaterThan(Carbon::parse($currentEnd));
    }

    /**
     * Convert an ABM device row into the normalized record shape.
     * ABM's device `id` is a stable GUID and is what we key
     * asset_external_sources on. Manufacturer is hard-coded to
     * "Apple" since every ABM device is by definition Apple hardware
     * and the payload doesn't carry the string.
     *
     * @param  array<string, mixed>  $device
     * @param  array<string, string>  $deviceToServer
     */
    private function normalize(array $device, array $deviceToServer): HostInventoryRecord
    {
        $attrs = $device['attributes'] ?? [];
        $id = (string) ($device['id'] ?? '');

        // Pass the AssetModel name the framework will use (mirrors
        // ensureModelImage's resolution) so the trait can
        // short-circuit the AppleDB info call when an existing row
        // already has every enrichable field set.
        $modelName = $this->mappingFor('abm_model_marketing_name') === 'native:model'
            ? (Arr::get($attrs, 'deviceModel') ?? Arr::get($attrs, 'partNumber'))
            : Arr::get($attrs, 'partNumber');
        $productType = Arr::get($attrs, 'productType');
        $canonical = $this->canonicalIdentityFor($productType, $modelName);
        $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);

        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: $id,
            // ABM is pre-provisioning, so hostname doesn't exist here.
            // Downstream shell-asset creation names the row after the
            // synthetic sourceKey + sourceId until admins rename it
            // or an MDM adapter joins in and provides a real hostname.
            hostname: null,
            hardwareSerial: Arr::get($attrs, 'serialNumber'),
            // ABM provides three model-adjacent strings, exposed as
            // extras below so admins can pick which one flows to
            // native:model via the mapping UI:
            //   - deviceModel: marketing name ("MacBook Pro
            //     (14-inch, M1 Pro/Max, 2021)"), which matches Fleet's
            //     hardware_marketing_name for cross-adapter
            //     convergence
            //   - productType: hardware identifier ("MacBookPro18,3")
            //   - partNumber: Apple's SKU ("MK1E3LL/A")
            // Default hardwareModel is partNumber because it's
            // always populated and unique per SKU. Admins mapping
            // abm_marketing_name to native:model gets the friendly
            // Fleet-compatible shape instead.
            hardwareModel: Arr::get($attrs, 'partNumber'),
            manufacturer: 'Apple',
            // ABM returns three MAC-shaped strings per device. Wi-Fi
            // is the one every enrolled device has, so it fills the
            // normalized primaryMac field. Ethernet and Bluetooth
            // stay in extras for admins who want to route them to
            // custom fields. normalizeMacAddress() inserts the colons
            // Snipe-IT's MAC custom-field validator requires.
            primaryMac: self::normalizeMacAddress(Arr::get($attrs, 'wifiMacAddress')),
            primaryIp: null,
            os: null,
            osVersion: null,
            lastSeen: null,
            assignedUserEmail: null,
            assignedUserName: null,
            vendorGroupId: null,
            extra: [
                ...$appleDbExtras,
                'abm_product_family' => Arr::get($attrs, 'productFamily'),
                'abm_model_marketing_name' => Arr::get($attrs, 'deviceModel'),
                'abm_product_type' => Arr::get($attrs, 'productType'),
                'abm_part_number' => Arr::get($attrs, 'partNumber'),
                'abm_color' => self::titleCase(Arr::get($attrs, 'color')),
                'abm_order_number' => Arr::get($attrs, 'orderNumber'),
                'abm_order_date' => self::parseOrderDate(Arr::get($attrs, 'orderDateTime')),
                'abm_purchase_source_type' => Arr::get($attrs, 'purchaseSourceType'),
                'abm_purchase_source_id' => Arr::get($attrs, 'purchaseSourceId'),
                'abm_mdm_server' => $deviceToServer[$id] ?? null,
                'abm_device_capacity' => Arr::get($attrs, 'deviceCapacity'),
                'abm_wifi_mac' => self::normalizeMacAddress(Arr::get($attrs, 'wifiMacAddress')),
                'abm_bluetooth_mac' => self::normalizeMacAddress(Arr::get($attrs, 'bluetoothMacAddress')),
                // ethernetMacAddress is a two-element array on dual-NIC
                // Macs. Positional split so admins can map each port to
                // its own custom field. See #19877.
                'abm_ethernet_mac_1' => self::extractMacAtIndex(Arr::get($attrs, 'ethernetMacAddress'), 0),
                'abm_ethernet_mac_2' => self::extractMacAtIndex(Arr::get($attrs, 'ethernetMacAddress'), 1),
                // Cellular-only identifiers. Populated for iPhones and
                // cellular iPads, null on Macs / non-cellular devices.
                // IMEI is an array in Apple's shape, _1/_2 split by
                // index so admins can map each to its own custom field.
                'abm_imei_1' => self::extractImeiAtIndex(Arr::get($attrs, 'imei'), 0),
                'abm_imei_2' => self::extractImeiAtIndex(Arr::get($attrs, 'imei'), 1),
                'abm_meid' => Arr::get($attrs, 'meid'),
                'abm_eid' => Arr::get($attrs, 'eid'),
                'abm_added_to_org' => self::parseOrderDate(Arr::get($attrs, 'addedToOrgDateTime')),
                'abm_released_from_org' => self::parseOrderDate(Arr::get($attrs, 'releasedFromOrgDateTime')),
                'abm_org_status' => Arr::get($attrs, 'status'),
                // Populated by enrichRecordWithActivationLock() when
                // the admin has mapped the extra. Kept as a nullable
                // slot so the mapping-target list surfaces the key
                // even before the first sync run fills it in.
                'abm_activation_lock_enabled' => null,
            ],
            canonicalMarketingName: $canonical['canonicalMarketingName'],
            canonicalModelNumber: $canonical['canonicalModelNumber'],
        );
    }

    /**
     * Which mode we're operating in: 'business' or 'school'. Stored
     * plain-text as a credential value so settingsSchema() renders
     * a normal text input. Anything other than 'school' resolves to
     * 'business' (the safer default that keeps admins from typoing
     * their way into the wrong host).
     */
    private function resolvedMode(): string
    {
        try {
            $stored = strtolower(trim($this->credential('mode')));
        } catch (\Throwable) {
            return 'business';
        }

        return $stored === 'school' ? 'school' : 'business';
    }

    /**
     * Title-case a color string ("SPACEBLACK" -> "Spaceblack") so
     * downstream custom fields aren't stuck with the vendor's
     * upper-case constants. Passes through null unchanged so
     * empty-guards on custom-field writes still fire.
     */
    private static function titleCase(?string $value): ?string
    {
        if ($value === null || $value === '') {
            return $value;
        }

        return ucwords(strtolower($value));
    }

    /**
     * ABM emits orderDateTime as ISO 8601 with fractional seconds and
     * a trailing Z. Format to YYYY-MM-DD for admins who route this
     * to a date-typed custom field.
     */
    private static function parseOrderDate(mixed $value): ?string
    {
        if ($value === null || $value === '') {
            return null;
        }

        try {
            // Rotate to app.timezone before extracting the date part so a
            // vendor datetime at the UTC day boundary records the date
            // the user would recognize. Same reason the last_seen path
            // converts to app timezone before producing its naive string.
            // #19765.
            return Carbon::parse($value)->timezone(config('app.timezone'))->toDateString();
        } catch (\Throwable) {
            return null;
        }
    }
}