Skip to content

A free open source IT asset/license management system

Added trait

snipe3023a0da7267
diff --git a/app/SyncAdapters/Fleet/FleetAdapter.php b/app/SyncAdapters/Fleet/FleetAdapter.php
index fd9e100e4f..9e96882ce3 100644
--- a/app/SyncAdapters/Fleet/FleetAdapter.php
+++ b/app/SyncAdapters/Fleet/FleetAdapter.php
@@ -4,6 +4,7 @@ namespace App\SyncAdapters\Fleet;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\SyncAdapter;
+use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
@@ -21,6 +22,16 @@ use Illuminate\Support\Arr;
*/
class FleetAdapter extends SyncAdapter
{
+ use UsesAppleDbEnrichment;
+
+ /**
+ * Fleet platform values treated as Apple hardware. Non-Apple
+ * hosts have hardware_model strings that will never match an
+ * appledb.dev entry, so gating here saves a wasted network call
+ * per non-Apple host on every sync.
+ */
+ private const APPLE_PLATFORMS = ['darwin', 'ios', 'ipados'];
+
public static function typeLabel(): string
{
return 'Fleet';
@@ -45,12 +56,14 @@ class FleetAdapter extends SyncAdapter
'secret' => true,
'help' => trans('admin/settings/sync_adapters.fleet_token_help'),
],
+ $this->appleDbSettingsField(),
];
}
public function extraFields(): array
{
return [
+ ...$this->appleDbExtraFieldsDeclaration(),
'fleet_team' => ['label_key' => 'admin/settings/sync_adapters.extra_team'],
'fleet_labels' => ['label_key' => 'admin/settings/sync_adapters.extra_labels'],
'fleet_uuid' => ['label_key' => 'admin/settings/sync_adapters.extra_uuid'],
@@ -150,6 +163,9 @@ class FleetAdapter extends SyncAdapter
// work with. Pays an N+1 API cost per sync, only when needed.
$needsDetail = $this->userMatchStrategy() !== 'none';
+ $enrichmentEnabled = $this->appleDbEnrichmentEnabled();
+ $enrichmentHandled = [];
+
foreach ($client->hosts() as $host) {
if ($needsDetail && isset($host['id'])) {
$detail = $client->hostDetail((int) $host['id']);
@@ -158,8 +174,55 @@ class FleetAdapter extends SyncAdapter
}
}
- yield $this->normalize($host);
+ $record = $this->normalize($host);
+
+ if ($enrichmentEnabled && $this->isAppleHost($host)) {
+ $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
+ }
+
+ yield $record;
+ }
+ }
+
+ /**
+ * Resolve the Fleet record's AssetModel name + AppleDB-shape
+ * productType and delegate to the shared enrichment helper.
+ *
+ * Fleet's hardware_model is osquery's raw sysctl value which is
+ * already the AppleDB identifier shape ("MacBookPro18,3") on
+ * Apple devices. hardware_marketing_name is the human-readable
+ * name, used as the AssetModel name when the admin routes
+ * fleet_model_marketing_name to native:model.
+ *
+ * @param array<string, bool> $handled
+ * @return array<string, bool>
+ */
+ private function enrichFromAppleDb(HostInventoryRecord $record, array $handled): array
+ {
+ $modelName = $this->mappingFor('fleet_model_marketing_name') === 'native:model'
+ ? ($record->extra['fleet_model_marketing_name'] ?? $record->hardwareModel)
+ : $record->hardwareModel;
+
+ if (! is_string($modelName) || $modelName === '') {
+ return $handled;
}
+
+ $productType = $record->hardwareModel;
+ if (! is_string($productType) || $productType === '') {
+ return $handled;
+ }
+
+ return $this->enrichModelFromAppleDb($modelName, $productType, null, $handled);
+ }
+
+ /**
+ * @param array<string, mixed> $host
+ */
+ private function isAppleHost(array $host): bool
+ {
+ $platform = Arr::get($host, 'platform');
+
+ return is_string($platform) && in_array($platform, self::APPLE_PLATFORMS, true);
}
/**
@@ -172,6 +235,25 @@ class FleetAdapter extends SyncAdapter
*/
private function normalize(array $host): HostInventoryRecord
{
+ // Only Apple hosts have hardware_model values that resolve on
+ // AppleDB. Non-Apple hosts carry strings like "ThinkPad X1
+ // Carbon" that the service would always return null for.
+ //
+ // Pass the AssetModel name the framework will use (mirrors
+ // the mapping ensureModelImage uses later in pull) so the
+ // trait can short-circuit the AppleDB info call when an
+ // existing row already has every enrichable field set.
+ $modelName = $this->mappingFor('fleet_model_marketing_name') === 'native:model'
+ ? (Arr::get($host, 'hardware_marketing_name') ?? Arr::get($host, 'hardware_model'))
+ : Arr::get($host, 'hardware_model');
+ $isAppleHost = $this->isAppleHost($host);
+ $canonical = $isAppleHost
+ ? $this->canonicalIdentityFor(Arr::get($host, 'hardware_model'), $modelName)
+ : ['canonicalMarketingName' => null, 'canonicalModelNumber' => null];
+ $appleDbExtras = $isAppleHost
+ ? $this->appleDbExtrasFor(Arr::get($host, 'hardware_model'), $modelName)
+ : ['appledb_marketing_name' => null, 'appledb_model_number' => null, 'appledb_release_date' => null, 'appledb_discontinued_date' => null];
+
return new HostInventoryRecord(
sourceKey: $this->name(),
sourceId: (string) Arr::get($host, 'id'),
@@ -188,6 +270,7 @@ class FleetAdapter extends SyncAdapter
assignedUserName: $this->extractUserName($host),
vendorGroupId: Arr::has($host, 'team_id') ? (string) Arr::get($host, 'team_id') : null,
extra: [
+ ...$appleDbExtras,
'fleet_team' => Arr::get($host, 'team_name'),
'fleet_labels' => Arr::get($host, 'labels'),
'fleet_uuid' => Arr::get($host, 'uuid'),
@@ -199,6 +282,8 @@ class FleetAdapter extends SyncAdapter
// non-MDM hosts) is treated as not-BYOD.
'fleet_byod' => Arr::get($host, 'mdm.enrollment_status') === 'On (personal)',
],
+ canonicalMarketingName: $canonical['canonicalMarketingName'],
+ canonicalModelNumber: $canonical['canonicalModelNumber'],
);
}
diff --git a/app/SyncAdapters/Jamf/JamfAdapter.php b/app/SyncAdapters/Jamf/JamfAdapter.php
index e695ae2364..fd23c85dd2 100644
--- a/app/SyncAdapters/Jamf/JamfAdapter.php
+++ b/app/SyncAdapters/Jamf/JamfAdapter.php
@@ -5,7 +5,7 @@ namespace App\SyncAdapters\Jamf;
use App\Models\Asset;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\PushableSyncAdapter;
-use App\SyncAdapters\SyncAdapter;
+use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
@@ -21,6 +21,8 @@ use Illuminate\Support\Arr;
*/
class JamfAdapter extends PushableSyncAdapter
{
+ use UsesAppleDbEnrichment;
+
public static function typeLabel(): string
{
return 'Jamf Pro';
@@ -62,12 +64,14 @@ class JamfAdapter extends PushableSyncAdapter
'required' => false,
'help' => trans('admin/settings/sync_adapters.jamf_include_mobile_devices_help'),
],
+ $this->appleDbSettingsField(),
];
}
public function extraFields(): array
{
return [
+ ...$this->appleDbExtraFieldsDeclaration(),
'jamf_udid' => ['label_key' => 'admin/settings/sync_adapters.extra_udid'],
'jamf_last_enrolled' => ['label_key' => 'admin/settings/sync_adapters.extra_last_enrolled', 'type' => 'date'],
'jamf_model_identifier' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
@@ -115,17 +119,54 @@ class JamfAdapter extends PushableSyncAdapter
clientSecret: $this->credential('client_secret'),
);
+ $enrichmentEnabled = $this->appleDbEnrichmentEnabled();
+ $enrichmentHandled = [];
+
foreach ($client->computers() as $computer) {
- yield $this->normalizeComputer($computer);
+ $record = $this->normalizeComputer($computer);
+ if ($enrichmentEnabled) {
+ $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
+ }
+ yield $record;
}
if ($this->shouldPullMobileDevices()) {
foreach ($client->mobileDevices() as $device) {
- yield $this->normalizeMobileDevice($device);
+ $record = $this->normalizeMobileDevice($device);
+ if ($enrichmentEnabled) {
+ $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
+ }
+ yield $record;
}
}
}
+ /**
+ * Pass the Jamf record to the shared enrichment flow. Both the
+ * computer and mobile normalize paths put the AppleDB-shape
+ * hardware identifier into jamf_model_identifier, so the lookup
+ * is unified here. hardwareModel ends up as the AssetModel name
+ * (Jamf's model string is already the marketing-ish shape
+ * admins see in Snipe-IT today).
+ *
+ * @param array<string, bool> $handled
+ * @return array<string, bool>
+ */
+ private function enrichFromAppleDb(HostInventoryRecord $record, array $handled): array
+ {
+ $modelName = $record->hardwareModel;
+ if (! is_string($modelName) || $modelName === '') {
+ return $handled;
+ }
+
+ $productType = $record->extra['jamf_model_identifier'] ?? null;
+ if (! is_string($productType) || $productType === '') {
+ return $handled;
+ }
+
+ return $this->enrichModelFromAppleDb($modelName, $productType, null, $handled);
+ }
+
/**
* Opt-in toggle for syncing iOS / iPadOS / tvOS devices alongside
* computers. Off by default so adding the mobile pull doesn't
@@ -159,6 +200,11 @@ class JamfAdapter extends PushableSyncAdapter
*/
private function normalizeComputer(array $computer): HostInventoryRecord
{
+ $productType = Arr::get($computer, 'hardware.modelIdentifier');
+ $modelName = Arr::get($computer, 'hardware.model');
+ $canonical = $this->canonicalIdentityFor($productType, $modelName);
+ $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);
+
return new HostInventoryRecord(
sourceKey: $this->name(),
sourceId: (string) Arr::get($computer, 'id'),
@@ -176,10 +222,13 @@ class JamfAdapter extends PushableSyncAdapter
assignedUserName: Arr::get($computer, 'userAndLocation.username'),
vendorGroupId: Arr::has($computer, 'general.site.id') ? (string) Arr::get($computer, 'general.site.id') : null,
extra: [
+ ...$appleDbExtras,
'jamf_udid' => Arr::get($computer, 'udid'),
'jamf_last_enrolled' => Arr::get($computer, 'general.lastEnrolledDate'),
'jamf_model_identifier' => Arr::get($computer, 'hardware.modelIdentifier'),
],
+ canonicalMarketingName: $canonical['canonicalMarketingName'],
+ canonicalModelNumber: $canonical['canonicalModelNumber'],
);
}
@@ -197,6 +246,10 @@ class JamfAdapter extends PushableSyncAdapter
private function normalizeMobileDevice(array $device): HostInventoryRecord
{
$sourceId = 'mobile:'.(string) Arr::get($device, 'id');
+ $productType = Arr::get($device, 'modelIdentifier');
+ $modelName = Arr::get($device, 'model');
+ $canonical = $this->canonicalIdentityFor($productType, $modelName);
+ $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);
return new HostInventoryRecord(
sourceKey: $this->name(),
@@ -215,12 +268,15 @@ class JamfAdapter extends PushableSyncAdapter
assignedUserName: Arr::get($device, 'location.username'),
vendorGroupId: Arr::has($device, 'site.id') ? (string) Arr::get($device, 'site.id') : null,
extra: [
+ ...$appleDbExtras,
'jamf_udid' => Arr::get($device, 'udid'),
'jamf_model_identifier' => Arr::get($device, 'modelIdentifier'),
'jamf_mobile_device_type' => Arr::get($device, 'deviceType'),
'jamf_mobile_managed' => Arr::get($device, 'managed'),
'jamf_mobile_supervised' => Arr::get($device, 'supervised'),
],
+ canonicalMarketingName: $canonical['canonicalMarketingName'],
+ canonicalModelNumber: $canonical['canonicalModelNumber'],
);
}
diff --git a/app/SyncAdapters/JamfPlatform/JamfPlatformAdapter.php b/app/SyncAdapters/JamfPlatform/JamfPlatformAdapter.php
index 5b010b0841..2b50c06458 100644
--- a/app/SyncAdapters/JamfPlatform/JamfPlatformAdapter.php
+++ b/app/SyncAdapters/JamfPlatform/JamfPlatformAdapter.php
@@ -4,6 +4,7 @@ namespace App\SyncAdapters\JamfPlatform;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\SyncAdapter;
+use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
@@ -24,6 +25,8 @@ use Illuminate\Support\Arr;
*/
class JamfPlatformAdapter extends SyncAdapter
{
+ use UsesAppleDbEnrichment;
+
public static function typeLabel(): string
{
return 'Jamf Platform';
@@ -63,16 +66,19 @@ class JamfPlatformAdapter extends SyncAdapter
'label' => trans('admin/settings/sync_adapters.label_environment_id'),
'help' => trans('admin/settings/sync_adapters.jamf_platform_environment_id_help'),
],
+ $this->appleDbSettingsField(),
];
}
public function extraFields(): array
{
return [
+ ...$this->appleDbExtraFieldsDeclaration(),
'jamf_platform_udid' => ['label_key' => 'admin/settings/sync_adapters.extra_udid'],
'jamf_platform_device_type' => ['label_key' => 'admin/settings/sync_adapters.extra_device_type'],
'jamf_platform_supervised' => ['label_key' => 'admin/settings/sync_adapters.extra_supervised', 'type' => 'boolean'],
'jamf_platform_blueprint_id' => ['label_key' => 'admin/settings/sync_adapters.extra_blueprint_id'],
+ 'jamf_platform_model_identifier' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
];
}
@@ -103,11 +109,42 @@ class JamfPlatformAdapter extends SyncAdapter
{
$client = $this->buildClient();
+ $enrichmentEnabled = $this->appleDbEnrichmentEnabled();
+ $enrichmentHandled = [];
+
foreach ($client->devices() as $device) {
- yield $this->normalize($device);
+ $record = $this->normalize($device);
+ if ($enrichmentEnabled) {
+ $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
+ }
+ yield $record;
}
}
+ /**
+ * Pass the Platform device record to the shared enrichment flow.
+ * modelIdentifier is on the top-level device payload (no detail
+ * fetch needed), already captured as jamf_platform_model_identifier
+ * in extras during normalize.
+ *
+ * @param array<string, bool> $handled
+ * @return array<string, bool>
+ */
+ private function enrichFromAppleDb(HostInventoryRecord $record, array $handled): array
+ {
+ $modelName = $record->hardwareModel;
+ if (! is_string($modelName) || $modelName === '') {
+ return $handled;
+ }
+
+ $productType = $record->extra['jamf_platform_model_identifier'] ?? null;
+ if (! is_string($productType) || $productType === '') {
+ return $handled;
+ }
+
+ return $this->enrichModelFromAppleDb($modelName, $productType, null, $handled);
+ }
+
private function buildClient(): JamfPlatformClient
{
return new JamfPlatformClient(
@@ -131,12 +168,17 @@ class JamfPlatformAdapter extends SyncAdapter
*/
private function normalize(array $device): HostInventoryRecord
{
+ $productType = Arr::get($device, 'modelIdentifier');
+ $modelName = Arr::get($device, 'model');
+ $canonical = $this->canonicalIdentityFor($productType, $modelName);
+ $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);
+
return new HostInventoryRecord(
sourceKey: $this->name(),
sourceId: (string) Arr::get($device, 'udid'),
hostname: Arr::get($device, 'name'),
hardwareSerial: Arr::get($device, 'serialNumber'),
- hardwareModel: Arr::get($device, 'model'),
+ hardwareModel: $modelName,
manufacturer: 'Apple',
primaryMac: Arr::get($device, 'wifiMacAddress'),
primaryIp: null,
@@ -146,11 +188,15 @@ class JamfPlatformAdapter extends SyncAdapter
assetTag: Arr::get($device, 'assetTag'),
vendorGroupId: Arr::has($device, 'blueprintId') ? (string) Arr::get($device, 'blueprintId') : null,
extra: [
+ ...$appleDbExtras,
'jamf_platform_udid' => Arr::get($device, 'udid'),
'jamf_platform_device_type' => Arr::get($device, 'deviceType'),
'jamf_platform_supervised' => Arr::get($device, 'isSupervised'),
'jamf_platform_blueprint_id' => Arr::get($device, 'blueprintId'),
+ 'jamf_platform_model_identifier' => $productType,
],
+ canonicalMarketingName: $canonical['canonicalMarketingName'],
+ canonicalModelNumber: $canonical['canonicalModelNumber'],
);
}
diff --git a/app/SyncAdapters/JamfSchool/JamfSchoolAdapter.php b/app/SyncAdapters/JamfSchool/JamfSchoolAdapter.php
index 32bb1eec22..d22df95241 100644
--- a/app/SyncAdapters/JamfSchool/JamfSchoolAdapter.php
+++ b/app/SyncAdapters/JamfSchool/JamfSchoolAdapter.php
@@ -4,6 +4,7 @@ namespace App\SyncAdapters\JamfSchool;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\SyncAdapter;
+use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
@@ -16,6 +17,8 @@ use Illuminate\Support\Arr;
*/
class JamfSchoolAdapter extends SyncAdapter
{
+ use UsesAppleDbEnrichment;
+
public static function typeLabel(): string
{
return 'Jamf School';
@@ -50,12 +53,14 @@ class JamfSchoolAdapter extends SyncAdapter
'secret' => true,
'help' => trans('admin/settings/sync_adapters.jamf_school_api_key_help'),
],
+ $this->appleDbSettingsField(),
];
}
public function extraFields(): array
{
return [
+ ...$this->appleDbExtraFieldsDeclaration(),
'jamf_school_model_identifier' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
'jamf_school_supervised' => ['label_key' => 'admin/settings/sync_adapters.extra_supervised', 'type' => 'boolean'],
'jamf_school_location_id' => ['label_key' => 'admin/settings/sync_adapters.extra_location_id'],
@@ -98,11 +103,42 @@ class JamfSchoolAdapter extends SyncAdapter
apiKey: $this->credential('api_key'),
);
+ $enrichmentEnabled = $this->appleDbEnrichmentEnabled();
+ $enrichmentHandled = [];
+
foreach ($client->devices() as $device) {
- yield $this->normalize($device);
+ $record = $this->normalize($device);
+ if ($enrichmentEnabled) {
+ $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
+ }
+ yield $record;
}
}
+ /**
+ * Pass the Jamf School record to the shared enrichment flow.
+ * Jamf School exposes the AppleDB-shape identifier at
+ * `model.identifier`; `model.name` is the marketing-ish string
+ * admins see as the AssetModel name.
+ *
+ * @param array<string, bool> $handled
+ * @return array<string, bool>
+ */
+ private function enrichFromAppleDb(HostInventoryRecord $record, array $handled): array
+ {
+ $modelName = $record->hardwareModel;
+ if (! is_string($modelName) || $modelName === '') {
+ return $handled;
+ }
+
+ $productType = $record->extra['jamf_school_model_identifier'] ?? null;
+ if (! is_string($productType) || $productType === '') {
+ return $handled;
+ }
+
+ return $this->enrichModelFromAppleDb($modelName, $productType, null, $handled);
+ }
+
/**
* Convert a Jamf School device payload into the normalized record
* shape. Jamf School's UDID is stable per enrolled device and is
@@ -112,6 +148,11 @@ class JamfSchoolAdapter extends SyncAdapter
*/
private function normalize(array $device): HostInventoryRecord
{
+ $productType = Arr::get($device, 'model.identifier');
+ $modelName = Arr::get($device, 'model.name');
+ $canonical = $this->canonicalIdentityFor($productType, $modelName);
+ $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);
+
return new HostInventoryRecord(
sourceKey: $this->name(),
sourceId: (string) Arr::get($device, 'UDID'),
@@ -139,11 +180,14 @@ class JamfSchoolAdapter extends SyncAdapter
assignedUserName: Arr::get($device, 'owner.username'),
vendorGroupId: Arr::has($device, 'locationId') ? (string) Arr::get($device, 'locationId') : null,
extra: [
+ ...$appleDbExtras,
'jamf_school_model_identifier' => Arr::get($device, 'model.identifier'),
'jamf_school_supervised' => Arr::get($device, 'isSupervised'),
'jamf_school_location_id' => Arr::get($device, 'locationId'),
'jamf_school_device_type' => Arr::get($device, 'deviceType'),
],
+ canonicalMarketingName: $canonical['canonicalMarketingName'],
+ canonicalModelNumber: $canonical['canonicalModelNumber'],
);
}
diff --git a/app/SyncAdapters/Kandji/KandjiAdapter.php b/app/SyncAdapters/Kandji/KandjiAdapter.php
index 58f14444b4..d8cd853583 100644
--- a/app/SyncAdapters/Kandji/KandjiAdapter.php
+++ b/app/SyncAdapters/Kandji/KandjiAdapter.php
@@ -5,7 +5,7 @@ namespace App\SyncAdapters\Kandji;
use App\Models\Asset;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\PushableSyncAdapter;
-use App\SyncAdapters\SyncAdapter;
+use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;
@@ -18,6 +18,8 @@ use Illuminate\Support\Facades\Log;
*/
class KandjiAdapter extends PushableSyncAdapter
{
+ use UsesAppleDbEnrichment;
+
public static function typeLabel(): string
{
return 'Iru (Kandji)';
@@ -52,15 +54,18 @@ class KandjiAdapter extends PushableSyncAdapter
'secret' => true,
'help' => trans('admin/settings/sync_adapters.kandji_token_help'),
],
+ $this->appleDbSettingsField(),
];
}
public function extraFields(): array
{
return [
+ ...$this->appleDbExtraFieldsDeclaration(),
'kandji_blueprint_id' => ['label_key' => 'admin/settings/sync_adapters.extra_blueprint_id'],
'kandji_mdm_enabled' => ['label_key' => 'admin/settings/sync_adapters.extra_mdm_enabled', 'type' => 'boolean'],
'kandji_is_missing' => ['label_key' => 'admin/settings/sync_adapters.extra_marked_missing', 'type' => 'boolean'],
+ 'kandji_model_identifier' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
];
}
@@ -91,11 +96,71 @@ class KandjiAdapter extends PushableSyncAdapter
{
$client = new KandjiClient(baseUrl: $this->url(), token: $this->credential('token'));
+ $enrichmentEnabled = $this->appleDbEnrichmentEnabled();
+ $enrichmentHandled = [];
+
foreach ($client->devices() as $device) {
- yield $this->normalize($device);
+ // Kandji's list endpoint omits the AppleDB-shape hardware
+ // identifier so an enrichment-enabled pull hits
+ // /devices/{id}/details per record. Pays N+1 API cost for
+ // the enrichment, which is why the toggle is opt-in.
+ $identifier = null;
+ if ($enrichmentEnabled && Arr::get($device, 'platform') !== null) {
+ $details = $client->deviceDetails((string) Arr::get($device, 'device_id'));
+ $identifier = $details !== null ? $this->extractKandjiIdentifier($details) : null;
+ }
+
+ $record = $this->normalize($device, $identifier);
+ if ($enrichmentEnabled) {
+ $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
+ }
+ yield $record;
}
}
+ /**
+ * Kandji's /devices/{id}/details response nests the AppleDB-
+ * shape identifier under hardware_overview on Macs. iPads /
+ * iPhones place the equivalent under a different key depending
+ * on the model class, so walk the two most common locations and
+ * accept whichever responds. Non-Apple devices (if Kandji ever
+ * adds them) are already filtered out before this is called via
+ * the enrichment toggle gate.
+ *
+ * @param array<string, mixed> $details
+ */
+ private function extractKandjiIdentifier(array $details): ?string
+ {
+ $identifier = Arr::get($details, 'hardware_overview.model_identifier')
+ ?? Arr::get($details, 'general.model_identifier');
+
+ return is_string($identifier) && $identifier !== '' ? $identifier : null;
+ }
+
+ /**
+ * Pass the Kandji record to the shared enrichment flow. Uses
+ * the normalized hardwareModel as the AssetModel name, same as
+ * the list-endpoint behavior before enrichment landed. The
+ * details-fetched identifier flows through the record extras.
+ *
+ * @param array<string, bool> $handled
+ * @return array<string, bool>
+ */
+ private function enrichFromAppleDb(HostInventoryRecord $record, array $handled): array
+ {
+ $modelName = $record->hardwareModel;
+ if (! is_string($modelName) || $modelName === '') {
+ return $handled;
+ }
+
+ $productType = $record->extra['kandji_model_identifier'] ?? null;
+ if (! is_string($productType) || $productType === '') {
+ return $handled;
+ }
+
+ return $this->enrichModelFromAppleDb($modelName, $productType, null, $handled);
+ }
+
/**
* Convert a Kandji device payload into the normalized record shape.
* Kandji's `device_id` is stable per enrolled device and is what we
@@ -108,14 +173,18 @@ class KandjiAdapter extends PushableSyncAdapter
*
* @param array<string, mixed> $device
*/
- private function normalize(array $device): HostInventoryRecord
+ private function normalize(array $device, ?string $modelIdentifier = null): HostInventoryRecord
{
+ $modelName = Arr::get($device, 'model');
+ $canonical = $this->canonicalIdentityFor($modelIdentifier, $modelName);
+ $appleDbExtras = $this->appleDbExtrasFor($modelIdentifier, $modelName);
+
return new HostInventoryRecord(
sourceKey: $this->name(),
sourceId: (string) Arr::get($device, 'device_id'),
hostname: Arr::get($device, 'device_name'),
hardwareSerial: Arr::get($device, 'serial_number'),
- hardwareModel: Arr::get($device, 'model'),
+ hardwareModel: $modelName,
manufacturer: Arr::get($device, 'platform') === 'Mac' ? 'Apple' : null,
primaryMac: null,
primaryIp: null,
@@ -127,10 +196,14 @@ class KandjiAdapter extends PushableSyncAdapter
assignedUserName: Arr::get($device, 'user.name'),
vendorGroupId: Arr::has($device, 'assigned_blueprint_id') ? (string) Arr::get($device, 'assigned_blueprint_id') : null,
extra: [
+ ...$appleDbExtras,
'kandji_blueprint_id' => Arr::get($device, 'assigned_blueprint_id'),
'kandji_mdm_enabled' => Arr::get($device, 'mdm_enabled'),
'kandji_is_missing' => Arr::get($device, 'is_missing'),
+ 'kandji_model_identifier' => $modelIdentifier,
],
+ canonicalMarketingName: $canonical['canonicalMarketingName'],
+ canonicalModelNumber: $canonical['canonicalModelNumber'],
);
}
diff --git a/app/SyncAdapters/Kandji/KandjiClient.php b/app/SyncAdapters/Kandji/KandjiClient.php
index ea69216d91..c20ec8f86b 100644
--- a/app/SyncAdapters/Kandji/KandjiClient.php
+++ b/app/SyncAdapters/Kandji/KandjiClient.php
@@ -61,6 +61,34 @@ class KandjiClient
} while (! $done);
}
+ /**
+ * Fetch the rich per-device detail payload. Only called when the
+ * admin has enabled AppleDB enrichment, which needs the
+ * AppleDB-shape hardware identifier (e.g. "MacBookPro18,3")
+ * from `hardware_overview.model_identifier`. The list endpoint
+ * stops short at marketing name only.
+ *
+ * Returns null when Kandji does not know the device-id or any
+ * HTTP error is raised, so a single bad device does not abort
+ * the entire pull. Caller treats null as "no enrichment target
+ * resolvable for this device."
+ *
+ * @return array<string, mixed>|null
+ */
+ public function deviceDetails(string $deviceId): ?array
+ {
+ try {
+ $response = $this->request()
+ ->get('/api/v1/devices/'.rawurlencode($deviceId).'/details')
+ ->throwIfNotJson()
+ ->json();
+ } catch (\Throwable) {
+ return null;
+ }
+
+ return is_array($response) ? $response : null;
+ }
+
/**
* List every Blueprint in the Kandji tenant. Used by the
* adapter's fetchGroups() so admins can map Blueprints to
diff --git a/app/SyncAdapters/Mosyle/MosyleAdapter.php b/app/SyncAdapters/Mosyle/MosyleAdapter.php
index 14ce5e4da1..90d484374c 100644
--- a/app/SyncAdapters/Mosyle/MosyleAdapter.php
+++ b/app/SyncAdapters/Mosyle/MosyleAdapter.php
@@ -5,7 +5,7 @@ namespace App\SyncAdapters\Mosyle;
use App\Models\Asset;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\PushableSyncAdapter;
-use App\SyncAdapters\SyncAdapter;
+use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;
@@ -24,6 +24,8 @@ use Illuminate\Support\Facades\Log;
*/
class MosyleAdapter extends PushableSyncAdapter
{
+ use UsesAppleDbEnrichment;
+
/**
* Per-category-selector config keys -> friendly display name. Same
* split pattern as ABM: Mosyle's device_type is a four-value enum
@@ -89,6 +91,7 @@ class MosyleAdapter extends PushableSyncAdapter
'secret' => true,
'help' => trans('admin/settings/sync_adapters.mosyle_password_help'),
],
+ $this->appleDbSettingsField(),
];
// Per-family category overrides. Mirrors the ABM pattern (which
@@ -203,6 +206,7 @@ class MosyleAdapter extends PushableSyncAdapter
public function extraFields(): array
{
return [
+ ...$this->appleDbExtraFieldsDeclaration(),
// Hardware / inventory
'mosyle_battery' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_battery'],
'mosyle_total_disk' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_total_disk'],
@@ -246,6 +250,7 @@ class MosyleAdapter extends PushableSyncAdapter
'mosyle_latitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_latitude'],
'mosyle_longitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_longitude'],
'mosyle_altitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_altitude'],
+ 'mosyle_device_model' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
];
}
@@ -253,9 +258,42 @@ class MosyleAdapter extends PushableSyncAdapter
{
$client = $this->makeClient();
+ $enrichmentEnabled = $this->appleDbEnrichmentEnabled();
+ $enrichmentHandled = [];
+
foreach ($client->devices() as $device) {
- yield $this->normalize($device);
+ $record = $this->normalize($device);
+ if ($enrichmentEnabled) {
+ $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
+ }
+ yield $record;
+ }
+ }
+
+ /**
+ * Pass the Mosyle record to the shared enrichment flow. Mosyle's
+ * `device_model` field holds the AppleDB-shape hardware
+ * identifier (sample "iPad12,1" per the Mosyle Business API
+ * reference) while `device_model_name` is the marketing-shape
+ * string used as the AssetModel name. Both Mosyle Manager and
+ * Mosyle Business follow this split.
+ *
+ * @param array<string, bool> $handled
+ * @return array<string, bool>
+ */
+ private function enrichFromAppleDb(HostInventoryRecord $record, array $handled): array
+ {
+ $modelName = $record->hardwareModel;
+ if (! is_string($modelName) || $modelName === '') {
+ return $handled;
}
+
+ $productType = $record->extra['mosyle_device_model'] ?? null;
+ if (! is_string($productType) || $productType === '') {
+ return $handled;
+ }
+
+ return $this->enrichModelFromAppleDb($modelName, $productType, null, $handled);
}
/**
@@ -271,12 +309,17 @@ class MosyleAdapter extends PushableSyncAdapter
*/
private function normalize(array $device): HostInventoryRecord
{
+ $productType = Arr::get($device, 'device_model');
+ $modelName = Arr::get($device, 'device_model_name');
+ $canonical = $this->canonicalIdentityFor($productType, $modelName);
+ $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);
+
return new HostInventoryRecord(
sourceKey: $this->name(),
sourceId: (string) Arr::get($device, 'deviceudid'),
hostname: Arr::get($device, 'device_name'),
hardwareSerial: Arr::get($device, 'serial_number'),
- hardwareModel: Arr::get($device, 'device_model_name'),
+ hardwareModel: $modelName,
manufacturer: 'Apple',
primaryMac: Arr::get($device, 'wifi_mac_address'),
primaryIp: Arr::get($device, 'last_lan_ip'),
@@ -287,6 +330,7 @@ class MosyleAdapter extends PushableSyncAdapter
assignedUserEmail: Arr::get($device, 'useremail'),
assignedUserName: Arr::get($device, 'username'),
extra: [
+ ...$appleDbExtras,
// Hardware / inventory
'mosyle_battery' => Arr::get($device, 'battery'),
'mosyle_total_disk' => Arr::get($device, 'total_disk'),
@@ -326,7 +370,10 @@ class MosyleAdapter extends PushableSyncAdapter
'mosyle_latitude' => Arr::get($device, 'latitude'),
'mosyle_longitude' => Arr::get($device, 'longitude'),
'mosyle_altitude' => Arr::get($device, 'altitude'),
+ 'mosyle_device_model' => $productType,
],
+ canonicalMarketingName: $canonical['canonicalMarketingName'],
+ canonicalModelNumber: $canonical['canonicalModelNumber'],
);
}
diff --git a/app/SyncAdapters/MosyleBusiness/MosyleBusinessAdapter.php b/app/SyncAdapters/MosyleBusiness/MosyleBusinessAdapter.php
index 29252b61ea..ba95b6c223 100644
--- a/app/SyncAdapters/MosyleBusiness/MosyleBusinessAdapter.php
+++ b/app/SyncAdapters/MosyleBusiness/MosyleBusinessAdapter.php
@@ -5,7 +5,7 @@ namespace App\SyncAdapters\MosyleBusiness;
use App\Models\Asset;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\PushableSyncAdapter;
-use App\SyncAdapters\SyncAdapter;
+use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;
@@ -29,6 +29,8 @@ use Illuminate\Support\Facades\Log;
*/
class MosyleBusinessAdapter extends PushableSyncAdapter
{
+ use UsesAppleDbEnrichment;
+
public static function typeLabel(): string
{
return 'Mosyle Business';
@@ -69,6 +71,7 @@ class MosyleBusinessAdapter extends PushableSyncAdapter
'secret' => true,
'help' => trans('admin/settings/sync_adapters.mosyle_business_password_help'),
],
+ $this->appleDbSettingsField(),
];
}
@@ -81,6 +84,7 @@ class MosyleBusinessAdapter extends PushableSyncAdapter
public function extraFields(): array
{
return [
+ ...$this->appleDbExtraFieldsDeclaration(),
// Hardware / inventory
'mosyle_battery' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_battery'],
'mosyle_total_disk' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_total_disk'],
@@ -120,6 +124,7 @@ class MosyleBusinessAdapter extends PushableSyncAdapter
'mosyle_latitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_latitude'],
'mosyle_longitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_longitude'],
'mosyle_altitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_altitude'],
+ 'mosyle_device_model' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
];
}
@@ -127,9 +132,40 @@ class MosyleBusinessAdapter extends PushableSyncAdapter
{
$client = $this->makeClient();
+ $enrichmentEnabled = $this->appleDbEnrichmentEnabled();
+ $enrichmentHandled = [];
+
foreach ($client->devices() as $device) {
- yield $this->normalize($device);
+ $record = $this->normalize($device);
+ if ($enrichmentEnabled) {
+ $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
+ }
+ yield $record;
+ }
+ }
+
+ /**
+ * Pass the Mosyle Business record to the shared enrichment flow.
+ * Business and Manager share field semantics: `device_model` is
+ * the AppleDB identifier shape ("iPad12,1" per the Business API
+ * reference), `device_model_name` is the marketing shape.
+ *
+ * @param array<string, bool> $handled
+ * @return array<string, bool>
+ */
+ private function enrichFromAppleDb(HostInventoryRecord $record, array $handled): array
+ {
+ $modelName = $record->hardwareModel;
+ if (! is_string($modelName) || $modelName === '') {
+ return $handled;
}
+
+ $productType = $record->extra['mosyle_device_model'] ?? null;
+ if (! is_string($productType) || $productType === '') {
+ return $handled;
+ }
+
+ return $this->enrichModelFromAppleDb($modelName, $productType, null, $handled);
}
/**
@@ -142,12 +178,17 @@ class MosyleBusinessAdapter extends PushableSyncAdapter
*/
private function normalize(array $device): HostInventoryRecord
{
+ $productType = Arr::get($device, 'device_model');
+ $modelName = Arr::get($device, 'device_model_name') ?? $productType;
+ $canonical = $this->canonicalIdentityFor($productType, $modelName);
+ $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);
+
return new HostInventoryRecord(
sourceKey: $this->name(),
sourceId: (string) Arr::get($device, 'deviceudid'),
hostname: Arr::get($device, 'device_name'),
hardwareSerial: Arr::get($device, 'serial_number'),
- hardwareModel: Arr::get($device, 'device_model_name') ?? Arr::get($device, 'device_model'),
+ hardwareModel: $modelName,
manufacturer: 'Apple',
primaryMac: Arr::get($device, 'wifi_mac_address'),
primaryIp: Arr::get($device, 'last_lan_ip'),
@@ -158,6 +199,7 @@ class MosyleBusinessAdapter extends PushableSyncAdapter
assignedUserEmail: Arr::get($device, 'useremail'),
assignedUserName: Arr::get($device, 'username'),
extra: [
+ ...$appleDbExtras,
// Hardware / inventory
'mosyle_battery' => Arr::get($device, 'battery'),
'mosyle_total_disk' => Arr::get($device, 'total_disk'),
@@ -197,7 +239,10 @@ class MosyleBusinessAdapter extends PushableSyncAdapter
'mosyle_latitude' => Arr::get($device, 'latitude'),
'mosyle_longitude' => Arr::get($device, 'longitude'),
'mosyle_altitude' => Arr::get($device, 'altitude'),
+ 'mosyle_device_model' => $productType,
],
+ canonicalMarketingName: $canonical['canonicalMarketingName'],
+ canonicalModelNumber: $canonical['canonicalModelNumber'],
);
}
diff --git a/app/SyncAdapters/Traits/UsesAppleDbEnrichment.php b/app/SyncAdapters/Traits/UsesAppleDbEnrichment.php
new file mode 100644
index 0000000000..d53ef0b143
--- /dev/null
+++ b/app/SyncAdapters/Traits/UsesAppleDbEnrichment.php
@@ -0,0 +1,323 @@
+<?php
+
+namespace App\SyncAdapters\Traits;
+
+use App\Enums\FileStorage;
+use App\Models\AssetModel;
+use App\Models\SyncAdapterConfig;
+use App\Services\AppleDb\AppleDbEnrichment;
+use App\Services\AppleDb\AppleDbRecord;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Storage;
+
+/**
+ * Shared AppleDB enrichment surface for Apple-capable sync adapters.
+ * Provides the settings-schema entry for the per-instance opt-in
+ * checkbox, the credential-read helper, and the common "find model,
+ * look up appledb.dev, soft-write every empty field" flow that would
+ * otherwise be duplicated across nine adapters.
+ *
+ * Adapters are responsible for extracting the AppleDB-shape hardware
+ * identifier (e.g. "MacBookPro18,3") from their vendor payload. That
+ * part cannot be shared because each vendor stores it differently.
+ */
+trait UsesAppleDbEnrichment
+{
+ /**
+ * Settings-schema entry each adapter injects into its own
+ * settingsSchema() output. One checkbox per adapter so admins
+ * can enable the lookup per instance.
+ *
+ * @return array<string, mixed>
+ */
+ protected function appleDbSettingsField(): array
+ {
+ return [
+ 'key' => 'use_appledb_enrichment',
+ 'label' => trans('admin/settings/sync_adapters.label_use_appledb_enrichment'),
+ 'type' => 'checkbox',
+ 'required' => false,
+ 'help' => trans('admin/settings/sync_adapters.use_appledb_enrichment_help'),
+ ];
+ }
+
+ /**
+ * True when the admin has turned the enrichment toggle on for
+ * this instance. Also honors ABM's legacy pull_model_images key
+ * as a backward-compat read so existing installs keep enriching
+ * without the admin re-visiting the settings page.
+ */
+ protected function appleDbEnrichmentEnabled(): bool
+ {
+ if ($this->credentialOrEmpty('use_appledb_enrichment') === '1') {
+ return true;
+ }
+
+ return SyncAdapterConfig::get($this->instance->id, 'pull_model_images') === '1';
+ }
+
+ private function credentialOrEmpty(string $key): string
+ {
+ try {
+ return $this->credential($key);
+ } catch (\Throwable) {
+ return '';
+ }
+ }
+
+ /**
+ * Shared extra-field declarations each Apple-capable adapter
+ * merges into its own extraFields() output. Exposing the AppleDB
+ * values as extras lets admins map them to custom fields on the
+ * asset (so a release-date column can sort assets in a report,
+ * not just display on the model row). The underlying mfg_*
+ * columns on `models` are still written by enrichment either
+ * way, these mappings are additive.
+ *
+ * @return array<string, array<string, string>>
+ */
+ protected function appleDbExtraFieldsDeclaration(): array
+ {
+ if (! $this->appleDbEnrichmentEnabled()) {
+ return [];
+ }
+
+ return [
+ 'appledb_marketing_name' => ['label_key' => 'admin/settings/sync_adapters.extra_appledb_marketing_name'],
+ 'appledb_model_number' => ['label_key' => 'admin/settings/sync_adapters.extra_appledb_model_number'],
+ 'appledb_release_date' => ['label_key' => 'admin/settings/sync_adapters.extra_appledb_release_date', 'type' => 'date'],
+ 'appledb_discontinued_date' => ['label_key' => 'admin/settings/sync_adapters.extra_appledb_discontinued_date', 'type' => 'date'],
+ ];
+ }
+
+ /**
+ * Values the matching extras-mapping path consumes. Each adapter
+ * calls this in normalize() and merges the result into the
+ * record's extra array, so the framework can route the values to
+ * whatever custom field (or native target) the admin picked.
+ *
+ * Reuses the per-process AppleDB device info cache that
+ * canonicalIdentityFor also hits, so there is no additional
+ * network call per device.
+ *
+ * The $modelName shortcut behaves the same as canonicalIdentityFor's: when a
+ * fully-populated AssetModel row matches the name, no network
+ * fetch is worth making. An admin adding a new AppleDB-to-custom-
+ * field mapping later would need to clear one of the model's
+ * mfg_* columns to trigger a refresh on the next sync.
+ *
+ * @return array<string, string|null>
+ */
+ protected function appleDbExtrasFor(?string $productType, ?string $modelName = null): array
+ {
+ $blank = [
+ 'appledb_marketing_name' => null,
+ 'appledb_model_number' => null,
+ 'appledb_release_date' => null,
+ 'appledb_discontinued_date' => null,
+ ];
+
+ if (! is_string($productType) || $productType === '' || ! $this->appleDbEnrichmentEnabled()) {
+ return $blank;
+ }
+
+ if (is_string($modelName) && $modelName !== '') {
+ $existing = AssetModel::query()->where('name', $modelName)->first();
+ if ($existing !== null && $this->allAppleDbEnrichableFieldsSet($existing)) {
+ return $blank;
+ }
+ }
+
+ $record = AppleDbEnrichment::canonicalIdentity($productType);
+ if ($record === null) {
+ return $blank;
+ }
+
+ return [
+ 'appledb_marketing_name' => $record->marketingName,
+ 'appledb_model_number' => $record->modelNumber,
+ 'appledb_release_date' => $record->releaseDate?->toDateString(),
+ 'appledb_discontinued_date' => $record->discontinuedDate?->toDateString(),
+ ];
+ }
+
+ /**
+ * Resolve the AppleDB canonical marketing name + model number for
+ * a hardware identifier. Called from each adapter's normalize()
+ * so the shared HostInventoryRecord carries identity hints into
+ * resolveModelIdByName. Returns null-null when the toggle is off,
+ * the identifier is blank, or AppleDB has no catalog entry.
+ *
+ * Keyed on the AppleDB-shape identifier string
+ * ("MacBookPro18,3", "iPhone16,2", etc). Each adapter is
+ * responsible for finding that string in its own vendor payload
+ * before calling here.
+ *
+ * When $modelName is supplied and an existing fully-populated
+ * AssetModel row matches it, the appledb.dev info call is
+ * skipped: the current adapter's name match will hit that row
+ * directly, and the row's own mfg_marketing_name + model_number
+ * already serve any future cross-adapter OR match.
+ *
+ * @return array{canonicalMarketingName: ?string, canonicalModelNumber: ?string}
+ */
+ protected function canonicalIdentityFor(?string $productType, ?string $modelName = null): array
+ {
+ $blank = [
+ 'canonicalMarketingName' => null,
+ 'canonicalModelNumber' => null,
+ ];
+
+ if (! is_string($productType) || $productType === '') {
+ return $blank;
+ }
+
+ if (! $this->appleDbEnrichmentEnabled()) {
+ return $blank;
+ }
+
+ if (is_string($modelName) && $modelName !== '') {
+ $existing = AssetModel::query()->where('name', $modelName)->first();
+ if ($existing !== null && $this->allAppleDbEnrichableFieldsSet($existing)) {
+ return $blank;
+ }
+ }
+
+ $record = AppleDbEnrichment::canonicalIdentity($productType);
+ if ($record === null) {
+ return $blank;
+ }
+
+ return [
+ 'canonicalMarketingName' => $record->marketingName,
+ 'canonicalModelNumber' => $record->modelNumber,
+ ];
+ }
+
+ /**
+ * Look up $productType on appledb.dev and soft-write every value
+ * it returns to the AssetModel row named $modelName. $handled is
+ * a per-pull dedupe map (modelName => true) so a 500-device pull
+ * sharing one model only hits the network once.
+ *
+ * Soft-write semantics: a column is populated only if it is
+ * currently empty. Admin edits and prior-sync values are never
+ * clobbered. If the model row doesn't exist yet (first-pass sync
+ * before the framework builds it), the image still downloads to
+ * the cache so the next sync picks it up without a re-fetch.
+ *
+ * @param array<string, bool> $handled
+ * @return array<string, bool>
+ */
+ protected function enrichModelFromAppleDb(
+ string $modelName,
+ string $productType,
+ ?string $colorHint,
+ array $handled,
+ ): array {
+ if ($modelName === '' || $productType === '') {
+ return $handled;
+ }
+
+ if (array_key_exists($modelName, $handled)) {
+ return $handled;
+ }
+ $handled[$modelName] = true;
+
+ $existing = AssetModel::query()
+ ->where('name', $modelName)
+ ->first();
+
+ if ($existing !== null && $this->allAppleDbEnrichableFieldsSet($existing)) {
+ Log::channel('sync-adapters')->info("{$this->name()} enrichment skip for model \"{$modelName}\": image and all mfg_* fields are already populated");
+
+ return $handled;
+ }
+
+ $enrichment = AppleDbEnrichment::lookup($productType, $colorHint);
+ if ($enrichment === null) {
+ Log::channel('sync-adapters')->info("{$this->name()} enrichment skip for model \"{$modelName}\" (productType={$productType}): appledb.dev returned no usable record");
+
+ return $handled;
+ }
+
+ if ($existing === null) {
+ Log::channel('sync-adapters')->info("{$this->name()} enrichment staged for model \"{$modelName}\" (productType={$productType}): AssetModel row not yet created, fields will be assigned on the next sync");
+
+ return $handled;
+ }
+
+ $this->softWriteAppleDbEnrichment($existing, $enrichment, $modelName, $productType);
+
+ return $handled;
+ }
+
+ private function allAppleDbEnrichableFieldsSet(AssetModel $model): bool
+ {
+ return $this->modelImagePresentOnDisk($model)
+ && ! empty($model->mfg_marketing_name)
+ && ! empty($model->model_number)
+ && ! empty($model->mfg_release_date)
+ && ! empty($model->mfg_discontinued_date);
+ }
+
+ /**
+ * True when model.image is set AND the referenced file actually
+ * exists on the public disk. Catches stale references left behind
+ * by a prior tenant migration or an older release that wrote to a
+ * disk the install no longer uses, so enrichment can repair the
+ * model.image column instead of leaving a 404 image forever.
+ */
+ private function modelImagePresentOnDisk(AssetModel $model): bool
+ {
+ if (empty($model->image)) {
+ return false;
+ }
+
+ return Storage::disk('public')->exists(FileStorage::Models->publicPath().$model->image);
+ }
+
+ private function softWriteAppleDbEnrichment(AssetModel $model, AppleDbRecord $enrichment, string $modelName, string $productType): void
+ {
+ $applied = [];
+
+ if (! $this->modelImagePresentOnDisk($model) && $enrichment->imageFilename !== null) {
+ $previous = $model->image;
+ $model->image = $enrichment->imageFilename;
+ $applied[] = $previous
+ ? "image={$enrichment->imageFilename} (replaced stale {$previous})"
+ : "image={$enrichment->imageFilename}";
+ }
+
+ if (empty($model->mfg_marketing_name) && $enrichment->marketingName !== null) {
+ $model->mfg_marketing_name = $enrichment->marketingName;
+ $applied[] = "mfg_marketing_name={$enrichment->marketingName}";
+ }
+
+ if (empty($model->model_number) && $enrichment->modelNumber !== null) {
+ $model->model_number = $enrichment->modelNumber;
+ $applied[] = "model_number={$enrichment->modelNumber}";
+ }
+
+ if (empty($model->mfg_release_date) && $enrichment->releaseDate !== null) {
+ $model->mfg_release_date = $enrichment->releaseDate;
+ $applied[] = 'mfg_release_date='.$enrichment->releaseDate->toDateString();
+ }
+
+ if (empty($model->mfg_discontinued_date) && $enrichment->discontinuedDate !== null) {
+ $model->mfg_discontinued_date = $enrichment->discontinuedDate;
+ $applied[] = 'mfg_discontinued_date='.$enrichment->discontinuedDate->toDateString();
+ }
+
+ if ($applied === []) {
+ Log::channel('sync-adapters')->info("{$this->name()} enrichment noop for model \"{$modelName}\" (productType={$productType}): appledb.dev returned data but every target field already has a value");
+
+ return;
+ }
+
+ $model->save();
+
+ $summary = implode(', ', $applied);
+ Log::channel('sync-adapters')->info("{$this->name()} enrichment applied to model \"{$modelName}\" (productType={$productType}): {$summary}");
+ }
+}