Skip to content

A free open source IT asset/license management system

61.8 KB
Raw Blame
<?php

namespace App\SyncAdapters;

use App\Models\Asset;
use App\Models\SyncAdapterConfig;
use App\Models\SyncAdapterInstance;
use App\Rules\ExternalUrl;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Crypt;
use Illuminate\Support\Facades\Log;

/**
 * The single base class every host-inventory adapter extends. Owns
 * every piece of behavior that's the same across adapters regardless
 * of auth shape: URL storage with SSRF-guarded validation, encrypted
 * secret storage, blank-preserves-existing save semantics, active +
 * heartbeat toggles, per-field target mapping, isEnabled().
 *
 * The one thing subclasses declare is their settingsSchema(): a
 * list of the auth fields the vendor requires and whether each is a
 * secret (masked with a show/hide toggle) or plain text. That's
 * enough for the shared blade partial to render the form, for
 * saveConfig() to persist correctly, for isEnabled() to enforce
 * required-cred presence, and for the sync path to read decrypted
 * values via credential().
 *
 * Auth shapes currently modeled by schema alone:
 *   - single API token (Fleet, Kandji, Jamf Pro, osctrl, Zentral, JumpCloud)
 *   - dual key pair (Addigy, Datto RMM)
 *   - OAuth 2.0 client credentials (Intune, Google Workspace, Azure AD)
 *
 * Auth shapes we can add later without touching the base. Schema
 * gains a `type` value beyond text/password (file upload for JSON
 * key files and certs, oauth_button for browser-redirect flows,
 * textarea for pasted private keys):
 *   - Google service account (file upload)
 *   - Apple ABM/ASM (certificate + private key)
 *   - Slack / any browser-redirect OAuth (oauth_button + callback)
 *   - AWS SigV4 (still three text/password fields plus a region)
 *   - Basic auth (still two fields, no new type)
 */
abstract class SyncAdapter
{
    // Asset-side upsert path. Exposes SyncAdapter::syncFromRecord($record) as
    // the public entry point every caller hits. Kept in its own trait
    // rather than inlined so this file stays focused on the adapter
    // contract (settings, credentials, mapping, direction, group
    // scoping, push helpers).
    use SyncsHostFromRecord;

    public function __construct(protected readonly SyncAdapterInstance $instance) {}

    /** Display label for the adapter TYPE (not the instance). Shown in the "Add adapter" dropdown. */
    abstract public static function typeLabel(): string;

    /**
     * Stable identifier stored in sync_adapter_instances.adapter_type.
     * Distinct from typeLabel() (localized display string) and name()
     * (per-instance slug). Adapters declare their own so the discovery
     * loop below can key the class map without a central registry.
     */
    abstract public static function typeSlug(): string;

    /**
     * Link to the vendor's public API documentation. Rendered as an
     * external link in the adapter catalog so admins can jump to the
     * vendor's own reference for the endpoints this adapter hits.
     * Return null when the vendor has no stable public docs URL or
     * gates its docs behind a login.
     */
    public static function docsUrl(): ?string
    {
        return null;
    }

    /** Vendor-specific inventory fetch. Yield HostInventoryRecord objects. */
    abstract public function pull(): iterable;

    /**
     * Discover every adapter subclass under app/SyncAdapters/*Adapter.php
     * and return a slug-keyed map of the concrete classes. Cached in a
     * static so repeat calls within a request don't re-scan the tree.
     *
     * @return array<string, class-string<self>>
     */
    public static function allTypes(): array
    {
        static $cache = null;
        if ($cache !== null) {
            return $cache;
        }

        $out = [];
        $base = app_path('SyncAdapters').DIRECTORY_SEPARATOR;
        foreach (glob($base.'*'.DIRECTORY_SEPARATOR.'*Adapter.php') as $file) {
            $relative = substr($file, strlen($base), -4);
            $class = 'App\\SyncAdapters\\'.str_replace(DIRECTORY_SEPARATOR, '\\', $relative);
            if (! class_exists($class) || ! is_subclass_of($class, self::class)) {
                continue;
            }
            $reflection = new \ReflectionClass($class);
            if ($reflection->isAbstract()) {
                continue;
            }
            $out[$class::typeSlug()] = $class;
        }
        ksort($out);

        return $cache = $out;
    }

    /**
     * Instantiate the adapter class for a given SyncAdapterInstance row.
     * Returns null when the instance's adapter_type doesn't match any
     * discovered class (e.g. an old row for a removed adapter).
     */
    public static function factory(SyncAdapterInstance $instance): ?self
    {
        $types = self::allTypes();
        $class = $types[$instance->adapter_type] ?? null;
        if ($class === null) {
            return null;
        }

        return new $class($instance);
    }

    /**
     * List of registered type slugs, in the same order as allTypes().
     *
     * @return array<int, string>
     */
    public static function typeNames(): array
    {
        return array_keys(self::allTypes());
    }

    /**
     * Type slug -> display label. Powers the "Add adapter" dropdown.
     *
     * @return array<string, string>
     */
    public static function typeLabels(): array
    {
        $out = [];
        foreach (self::allTypes() as $slug => $class) {
            $out[$slug] = $class::typeLabel();
        }

        return $out;
    }

    /**
     * Type slug -> {label, docs_url, direction} catalog. Powers the
     * help pane's list of supported adapters so admins can jump into
     * either the "Add adapter" modal with the type pre-selected or
     * the docs page (vendor's own for named adapters, Snipe-IT's own
     * for Custom HTTP). docs_url is null for adapters whose vendor
     * has no stable public reference URL or gates its docs behind a
     * login. direction is derived from whether the class extends
     * PushableSyncAdapter so the catalog UI reflects reality without
     * a separate list for admins or docs to drift from.
     *
     * @return array<string, array{label: string, docs_url: ?string, direction: 'pull'|'both'}>
     */
    public static function typeCatalog(): array
    {
        $out = [];
        foreach (self::allTypes() as $slug => $class) {
            $out[$slug] = [
                'label' => $class::typeLabel(),
                'docs_url' => $class::docsUrl(),
                'direction' => is_subclass_of($class, PushableSyncAdapter::class) ? 'both' : 'pull',
            ];
        }

        return $out;
    }

    /**
     * Hydrate every configured instance from the database as a live
     * adapter, skipping rows whose adapter_type is no longer registered.
     *
     * @return array<int, self>
     */
    public static function allInstances(): array
    {
        return SyncAdapterInstance::query()
            ->orderBy('label')
            ->get()
            ->map(fn (SyncAdapterInstance $i) => self::factory($i))
            ->filter()
            ->values()
            ->all();
    }

    /**
     * Declare this adapter's authentication field schema. The base
     * class drives every settings-page, storage, validation, and
     * enable-check decision off this list. Adapters typically have
     * only this and pull() to think about.
     *
     * Field entry keys:
     *   - key      (required) storage key AND form-field-name suffix
     *   - label    (required) display label rendered next to the input
     *   - type     (optional, default 'text') one of 'text', 'password',
     *              'textarea', 'checkbox', 'select'. 'password' also
     *              implied when secret => true.
     *   - options  (optional) for type='select', a map of
     *              value => display-label pairs.
     *   - secret   (optional, default false) render as password with
     *              show/hide toggle AND encrypt the value at rest
     *   - required (optional, default true) treat as required for the
     *              isEnabled() gate. UI hint is up to the label copy
     *   - help     (optional, default null) inline help text under the
     *              field, passed straight to `<x-form.row help_text=...>`
     *   - placeholder (optional) placeholder text shown inside an
     *              empty text / textarea input. Ignored for other
     *              types.
     *   - default  (optional) initial-render fallback used when
     *              nothing is stored yet. For type='multiselect' pass
     *              an array of option keys to pre-select on first
     *              render.
     *
     * @return array<int, array{key: string, label: string, type?: string, options?: array<string, string>, secret?: bool, required?: bool, help?: string|null, placeholder?: string|null, default?: array<int, string>|string|null}>
     */
    abstract public function settingsSchema(): array;

    /**
     * Adapter-specific extra fields the vendor emits, keyed by the
     * extra-array key from HostInventoryRecord. Values are either a
     * plain string label (defaults to text type) or an array shaped
     * ['label' => 'Human Label', 'type' => 'text' | 'boolean',
     * 'admin_defined' => bool] OR ['label_key' => 'lang.key.path',
     * 'type' => 'text' | 'boolean', 'admin_defined' => bool]. The
     * label_key variant is resolved at render time via trans() with
     * ':vendor' bound to the adapter's typeLabel so translators
     * localize each shape once for every adapter that emits it.
     *
     * Type filters the target pool via MappingTargets::optionsForExtra:
     * 'text' offers text/textarea/markdown-textarea custom fields
     * plus native asset_tag/model/notes. 'boolean' offers checkbox
     * fields only. admin_defined (used by adapters that expose
     * tenant-labeled vendor custom fields) further narrows to
     * custom-only.
     *
     * Adapters that don't emit extras leave this empty.
     *
     * @return array<string, string|array{label?: string, label_key?: string, type?: string, admin_defined?: bool}>
     */
    public function extraFields(): array
    {
        return $this->presetExtraFields() + $this->adminDefinedExtraFields();
    }

    /**
     * Vendor-specific extras the adapter extracts in its own normalize()
     * from well-known API fields. Default empty - adapters that emit
     * extras override this with their preset keys (e.g. Intune's
     * compliance_state, Jamf's building, Kandji's blueprint).
     *
     * This replaced the old extraFields() hook when admin-defined extras
     * were added. extraFields() now composes presets with admin extras
     * so Blade / mapping-targets consumers see the union.
     *
     * @return array<string, string|array{label?: string, label_key?: string, type?: string, admin_defined?: bool}>
     */
    public function presetExtraFields(): array
    {
        return [];
    }

    /**
     * Admin-defined extras surfaced as mapping targets. Every adapter
     * gets a Custom Extras widget below its mapping table where admins
     * can pair a Snipe-IT destination (custom:X or native:X) with a
     * vendor-record dot-path. extraFields() includes these alongside
     * the adapter's own presetExtraFields() so the mapping picker
     * shows both groups.
     *
     * @return array<string, array{label: string, admin_defined: true}>
     */
    public function adminDefinedExtraFields(): array
    {
        $out = [];
        foreach (array_keys($this->adminDefinedExtras()) as $key) {
            $out[$key] = ['label' => $key, 'admin_defined' => true];
        }

        return $out;
    }

    /**
     * Admin-configured extras rows for this instance: destination key
     * (`custom:X` / `native:X`) mapped to a dot-path into the vendor
     * record. Shared with CustomHttpAdapter's existing Vendor Response
     * Paths widget via the same `field_paths` config key. Entries whose
     * destination is a HostInventoryRecord slot (hostname / serial /
     * etc.) are filtered out here - those are CustomHttp-specific and
     * driven by its own normalize path, not the admin-extras overlay.
     *
     * @return array<string, string>
     */
    public function adminDefinedExtras(): array
    {
        $raw = SyncAdapterConfig::get($this->instance->id, 'field_paths');
        if (! is_string($raw) || trim($raw) === '') {
            return [];
        }

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

        $out = [];
        foreach ($decoded as $key => $path) {
            if (! is_string($key) || ! is_string($path) || $path === '') {
                continue;
            }
            if (! str_starts_with($key, 'custom:') && ! str_starts_with($key, 'native:')) {
                continue;
            }
            $out[$key] = $path;
        }

        return $out;
    }

    /**
     * Overlay admin-defined extras onto an adapter's preset extras.
     * Called from each adapter's normalize() after assembling the
     * preset extras, right before yielding the HostInventoryRecord.
     * Walks every configured dot-path against the raw vendor record
     * and populates the corresponding extras key.
     *
     * @param  array<string, mixed>  $extra
     * @param  array<string, mixed>  $vendorRecord
     * @return array<string, mixed>
     */
    protected function applyAdminExtras(array $extra, array $vendorRecord): array
    {
        foreach ($this->adminDefinedExtras() as $key => $path) {
            $extra[$key] = self::dotPathGet($vendorRecord, $path);
        }

        return $extra;
    }

    /**
     * Which destination options to expose in this adapter's Custom
     * Extras widget. Named adapters only let admins add new custom:X
     * / native:X mappings so they can't accidentally remap an identity
     * field (serial, hostname, etc.) that the adapter's normalize()
     * owns. CustomHttp overrides this to include HostInventoryRecord
     * slots because for that adapter, admins ARE the ones defining
     * where every field comes from.
     *
     * @return array<string, string>
     */
    public function customExtrasDestinationOptions(): array
    {
        $options = [
            // native:asset_tag lets admins route a vendor field (Intune's
            // deviceName, Jamf's name, etc.) to the asset_tag column.
            // writeNative() prevents blank vendor values overwriting an
            // admin-curated asset_tag.
            'native:asset_tag' => MappingTargets::labelFor('native:asset_tag'),
            'native:notes' => trans('admin/settings/sync_adapters.target_native_notes'),
            'native:purchase_date' => MappingTargets::labelFor('native:purchase_date'),
            'native:order_number' => MappingTargets::labelFor('native:order_number'),
        ];

        foreach (\App\Models\CustomField::whereIn('element', ['text', 'textarea', 'markdown-textarea', 'checkbox'])->orderBy('name')->get() as $cf) {
            $options['custom:'.$cf->id] = trans('admin/settings/sync_adapters.target_custom_prefix').': '.$cf->name;
        }

        return $options;
    }

    /**
     * CustomHttp drives its field_paths widget via its own schema
     * entry (type: field_map) because that widget predates admin-
     * extras and also exposes HostInventoryRecord slots. Named
     * adapters opt into the shared Custom Extras widget by leaving
     * this at its default of false.
     */
    public function rendersFieldPathsInSchema(): bool
    {
        return false;
    }

    /**
     * Whether the shared "Custom Extras" fieldset renders on this
     * adapter's settings page. Default off so adapters that haven't
     * been wired up (no applyAdminExtras() call in their normalize())
     * don't advertise a widget that then does nothing at sync time.
     * Adapters opt in once their normalize() is calling
     * applyAdminExtras() by overriding this to true.
     */
    public function supportsAdminDefinedExtras(): bool
    {
        return false;
    }

    /**
     * Hook for an adapter-specific "fetch extra details per device"
     * toggle in the shared settings UI. When this returns a label +
     * help string, the base saveConfig persists the posted
     * `{slug}_fetch_per_device_details` boolean and the shared Blade
     * renders a checkbox row. Adapters that don't need the toggle
     * (every adapter whose LIST endpoint already returns everything)
     * leave this at the default null.
     *
     * @return array{label: string, help: string}|null
     */
    public function perDeviceDetailsToggle(): ?array
    {
        return null;
    }

    /**
     * Walk a dot-separated path into a nested array structure. Empty
     * path returns the input unchanged. Numeric segments (like
     * "data.0.serial") index into sequential arrays. Returns null for
     * any miss so downstream null-guards do the right thing.
     */
    public static function dotPathGet(mixed $data, string $path): mixed
    {
        if ($path === '') {
            return $data;
        }

        $current = $data;
        foreach (explode('.', $path) as $segment) {
            if (! is_array($current)) {
                return null;
            }
            if (array_key_exists($segment, $current)) {
                $current = $current[$segment];

                continue;
            }
            if (ctype_digit($segment) && array_key_exists((int) $segment, $current)) {
                $current = $current[(int) $segment];

                continue;
            }

            return null;
        }

        return $current;
    }

    /**
     * Section titles + help copy for the settings schema. Adapters
     * that group their credential fields via a `section` key on
     * schema entries override this to give each section a labeled
     * <fieldset> in the settings UI. Default is empty, in which case
     * the credentials partial renders the schema entries flat.
     *
     * Expected shape:
     *   ['section_key' => ['title' => string, 'help' => ?string], ...]
     *
     * @return array<string, array{title: string, help?: string}>
     */
    public function settingsSections(): array
    {
        return [];
    }

    /**
     * Optional: name a settingsSections() key that should include
     * the Base URL row. The shell opens the fieldset around Base URL
     * and the credentials partial's schema loop continues rendering
     * into the same fieldset for that section's entries. Returns null
     * to keep Base URL rendered above the fieldsets (default).
     */
    public function baseUrlSection(): ?string
    {
        return null;
    }

    public function name(): string
    {
        return $this->instance->slug;
    }

    public function label(): string
    {
        return $this->instance->label;
    }

    /**
     * Public accessor for the backing instance. Blade views that need to
     * reason about per-instance state (lock keys, mapping tables, etc)
     * use through this vs relying on the protected constructor property.
     */
    public function instance(): SyncAdapterInstance
    {
        return $this->instance;
    }

    public function companyId(): ?int
    {
        return $this->instance->company_id;
    }

    public function isActive(): bool
    {
        return $this->instance->active;
    }

    public function isEnabled(): bool
    {
        if (! $this->instance->active) {
            return false;
        }

        if ($this->usesConfigurableUrl() && empty(SyncAdapterConfig::get($this->instance->id, 'url'))) {
            return false;
        }

        foreach ($this->settingsSchema() as $field) {
            if (($field['required'] ?? true) && ! SyncAdapterConfig::has($this->instance->id, $field['key'])) {
                return false;
            }
        }

        return true;
    }

    /**
     * Whether the admin needs to configure a base URL for this
     * adapter. Defaults to true because most vendors expose a
     * tenant-specific host. Adapters whose host is fixed (Apple ABM
     * derives the host from the Portal enum, so there's nothing for
     * the admin to type) override to false, and the shared form,
     * validation, and isEnabled() gate all skip the URL field.
     */
    public function usesConfigurableUrl(): bool
    {
        return true;
    }

    /**
     * Three-state readiness for the settings-page tab indicator:
     *
     * - 'active'   = will sync (Active toggle on AND URL + required credentials all present)
     * - 'partial'  = Active toggle on but the config is incomplete (admin turned it on before finishing setup)
     * - 'inactive' = Active toggle off (regardless of whether config exists, this is the "off" state)
     *
     * Kept separate from isEnabled() so the tab indicator can distinguish
     * "not turned on yet" from "turned on but not working yet", which
     * needs different admin attention.
     */
    public function readinessStatus(): string
    {
        if ($this->isEnabled()) {
            return 'active';
        }

        return $this->instance->active ? 'partial' : 'inactive';
    }

    /**
     * Rules the controller enforces before saveConfig() runs.
     * ExternalUrl blocks loopback / RFC-1918 / cloud-metadata targets
     * so an admin can't turn Snipe-IT into an SSRF primitive by
     * pointing at 127.0.0.1 or 169.254.169.254. Credential fields
     * stay nullable at rules-time so admins can save a URL-only
     * draft while they go fetch credentials from the vendor console.
     */
    public function validationRules(): array
    {
        $slug = $this->instance->slug;

        $rules = [
            $slug.'_asset_tag_pattern' => ['nullable', 'string', 'max:191', new \App\Rules\AssetTagPatternRule],
            $slug.'_default_category_id' => ['nullable', 'integer', 'exists:categories,id'],
            $slug.'_default_status_id' => ['required', 'integer', 'exists:status_labels,id'],
            $slug.'_default_fieldset_id' => ['nullable', 'integer', 'exists:custom_fieldsets,id'],
            $slug.'_user_match_strategy' => ['nullable', 'string', 'in:none,email,username,username_then_email'],
            $slug.'_adopt_by_serial' => ['nullable', 'boolean'],
            $slug.'_create_snipeit_assets_on_pull' => ['nullable', 'boolean'],
        ];

        // Admin-defined extras widget. Posts as an associative array
        // of {destination: vendor_path}. Only rendered for adapters
        // that opt in via supportsAdminDefinedExtras(), but the rule
        // itself is cheap and harmless when absent.
        if ($this->supportsAdminDefinedExtras()) {
            $rules[$slug.'_field_paths'] = ['nullable', 'array'];
            $rules[$slug.'_field_paths.*'] = ['nullable', 'string', 'max:191'];
        }

        if ($this->perDeviceDetailsToggle() !== null) {
            $rules[$slug.'_fetch_per_device_details'] = ['nullable', 'boolean'];
        }

        if ($this->usesConfigurableUrl()) {
            $rules[$slug.'_url'] = ['required', new ExternalUrl('app.sync_adapter_allow_internal_targets')];
        }

        foreach ($this->settingsSchema() as $field) {
            // Auth fields default to required so admins can't save a
            // half-configured adapter that then silently refuses to
            // sync because isEnabled() returns false. Secret fields
            // are pre-populated with the decrypted value on the
            // settings page, so submission always carries a value
            // unless the admin explicitly cleared it (which is an
            // error worth surfacing). Adapters declaring a truly
            // optional credential set `required => false`.
            $required = $field['required'] ?? true;
            $fieldName = $slug.'_'.$field['key'];
            $type = $field['type'] ?? 'text';

            // Multiselect fields post as `name[]`, so they arrive as
            // an array (or absent when nothing is selected). Validate
            // as an array with string members, not as a string.
            if ($type === 'multiselect') {
                $rules[$fieldName] = [$required ? 'required' : 'nullable', 'array'];
                $rules[$fieldName.'.*'] = ['string'];

                continue;
            }

            // Category selectors post the chosen category id (or an
            // empty string to fall back to default_category_id).
            if ($type === 'category') {
                $rules[$fieldName] = [$required ? 'required' : 'nullable', 'integer', 'exists:categories,id'];

                continue;
            }

            // Field-map repeater posts as an associative array of
            // {snipe_field: vendor_path}. Values are trimmed strings
            // (dot-paths). Empty submissions produce an empty array,
            // which persists as "{}" and reads back as no mappings.
            if ($type === 'field_map') {
                $rules[$fieldName] = [$required ? 'required' : 'nullable', 'array'];
                $rules[$fieldName.'.*'] = ['nullable', 'string'];

                continue;
            }

            $rules[$fieldName] = [
                $required ? 'required' : 'nullable',
                'string',
            ];
        }

        return $rules;
    }

    public function saveConfig(Request $request): void
    {
        $slug = $this->instance->slug;

        if ($this->usesConfigurableUrl()) {
            $this->persistUrl($request, $slug);
        }
        $this->persistCredentialsFromSchema($request, $slug);
        $this->persistOperationalSettings($request, $slug);

        if ($this->supportsGroupScoping()) {
            $this->persistGroupMappings($request, $slug);
        }

        if ($this->supportsAdminDefinedExtras()) {
            $this->persistAdminDefinedExtras($request, $slug);
        }

        $validFields = $this->validMappingFields();
        $this->persistFieldMappings($request, $slug, $validFields);
        $this->persistFieldDirections($request, $slug, $validFields);

        $this->afterSaveConfig();
    }

    /**
     * Persist the Custom Extras widget's rows. Posted shape is an
     * associative array mapping destination (`custom:X` or `native:X`)
     * to a vendor-record dot-path. Stored as a JSON blob in
     * `field_paths` and also written as self-routing mapping entries
     * (mapping.<key> = <key>) so the framework's extras loop writes
     * each extracted value to its target at sync time.
     */
    private function persistAdminDefinedExtras(Request $request, string $slug): void
    {
        $posted = (array) $request->input($slug.'_field_paths', []);
        $cleaned = [];
        foreach ($posted as $key => $path) {
            if (! is_string($key) || ! is_string($path)) {
                continue;
            }
            $path = trim($path);
            if ($path === '') {
                continue;
            }
            if (! str_starts_with($key, 'custom:') && ! str_starts_with($key, 'native:')) {
                continue;
            }
            $cleaned[$key] = $path;
            SyncAdapterConfig::put($this->instance->id, 'mapping.'.$key, $key);
        }

        SyncAdapterConfig::put(
            $this->instance->id,
            'field_paths',
            $cleaned === [] ? '' : json_encode($cleaned, JSON_UNESCAPED_SLASHES),
        );
    }

    /**
     * URL is always overwritten from the form. Blank means "no URL
     * configured yet" which the isEnabled() gate then treats as
     * "instance not usable."
     */
    private function persistUrl(Request $request, string $slug): void
    {
        SyncAdapterConfig::put($this->instance->id, 'url', $request->input($slug.'_url'));
    }

    /**
     * Blank input preserves the existing value so admins can update the
     * URL without re-entering every credential every time. Secrets get
     * encrypted at rest. Plain-text fields (like OAuth tenant / client
     * IDs) get stored as-is.
     */
    private function persistCredentialsFromSchema(Request $request, string $slug): void
    {
        foreach ($this->settingsSchema() as $field) {
            $fieldName = $slug.'_'.$field['key'];
            $type = $field['type'] ?? 'text';

            // Checkbox fields always overwrite: an unchecked box is
            // a real value ("off") and needs to overwrite a
            // previously-saved "on". Text and password fields
            // preserve blank input so admins can update the URL
            // without re-entering every secret.
            if ($type === 'checkbox') {
                SyncAdapterConfig::put(
                    $this->instance->id,
                    $field['key'],
                    $request->boolean($fieldName) ? '1' : '0',
                );

                continue;
            }

            // Multiselect also always overwrites. Empty selection
            // is a real value (means "sync all"). Store as JSON so
            // values with commas / special chars round-trip cleanly.
            if ($type === 'multiselect') {
                $values = (array) $request->input($fieldName, []);
                $values = array_values(array_filter($values, fn ($v) => $v !== null && $v !== ''));
                SyncAdapterConfig::put(
                    $this->instance->id,
                    $field['key'],
                    json_encode($values),
                );

                continue;
            }

            // Category selector: empty means "fall back to the
            // instance-wide default_category_id". Store as-is so a
            // deliberate clear overwrites a previous pick.
            if ($type === 'category') {
                $value = $request->input($fieldName, '');
                SyncAdapterConfig::put(
                    $this->instance->id,
                    $field['key'],
                    $value === null ? '' : (string) $value,
                );

                continue;
            }

            // Field-map repeater: assoc array of {field_key: path}.
            // Empty submissions overwrite as {} so a deliberate
            // "clear everything".
            if ($type === 'field_map') {
                $values = (array) $request->input($fieldName, []);
                $pending = (array) $request->input($fieldName.'_pending', []);
                $pendingKey = is_string($pending['key'] ?? null) ? trim($pending['key']) : '';
                $pendingValue = is_string($pending['value'] ?? null) ? trim($pending['value']) : '';
                if ($pendingKey !== '' && $pendingValue !== '') {
                    $values[$pendingKey] = $pendingValue;
                }
                $values = array_filter(
                    $values,
                    fn ($v, $k) => is_string($k) && $k !== '' && is_string($v) && trim($v) !== '',
                    ARRAY_FILTER_USE_BOTH,
                );
                SyncAdapterConfig::put(
                    $this->instance->id,
                    $field['key'],
                    json_encode($values),
                );

                continue;
            }

            if (! $request->filled($fieldName)) {
                continue;
            }

            $value = $request->input($fieldName);
            if ($field['secret'] ?? false) {
                $value = Crypt::encrypt($value);
            }
            SyncAdapterConfig::put($this->instance->id, $field['key'], $value);
        }
    }

    /**
     * Non-credential operational toggles + defaults + push settings.
     * Grouped here so saveConfig() reads as a list of intent rather
     * than a wall of SyncAdapterConfig::put() calls.
     */
    protected function persistOperationalSettings(Request $request, string $slug): void
    {
        SyncAdapterConfig::put(
            $this->instance->id,
            'log_heartbeats',
            $request->boolean($slug.'_log_heartbeats') ? '1' : '0',
        );

        // Asset-tag pattern for auto-created assets. Empty input clears
        // the setting so we fall back to Asset::autoincrement_asset().
        SyncAdapterConfig::put(
            $this->instance->id,
            'asset_tag_pattern',
            (string) $request->input($slug.'_asset_tag_pattern', ''),
        );

        // Default category for auto-created AssetModels. Empty falls
        // back to the get-or-create "Discovered Hardware" category.
        SyncAdapterConfig::put(
            $this->instance->id,
            'default_category_id',
            (string) $request->input($slug.'_default_category_id', ''),
        );

        // Default status label for auto-created assets. Empty falls
        // back to the first deployable label (or any label if none
        // are marked deployable).
        SyncAdapterConfig::put(
            $this->instance->id,
            'default_status_id',
            (string) $request->input($slug.'_default_status_id', ''),
        );

        // Default fieldset for AssetModels auto-created from this
        // adapter. Empty leaves fieldset_id null on new models (today's
        // behavior). Admins pick a fieldset here so custom fields show
        // on devices discovered by the adapter without having to
        // revisit each new model by hand.
        SyncAdapterConfig::put(
            $this->instance->id,
            'default_fieldset_id',
            (string) $request->input($slug.'_default_fieldset_id', ''),
        );

        // User match strategy for sync-driven assignments. 'none'
        // disables the lookup entirely. Anything else the accessor
        // doesn't recognize also degrades to 'none'.
        SyncAdapterConfig::put(
            $this->instance->id,
            'user_match_strategy',
            (string) $request->input($slug.'_user_match_strategy', 'none'),
        );

        // Suppress notifications checkbox. Stored as '0' when the
        // admin opted OUT of suppression (i.e., wants events to fire).
        // Any other value means suppress. Matches the accessor.
        SyncAdapterConfig::put(
            $this->instance->id,
            'suppress_notifications',
            $request->boolean($slug.'_suppress_notifications') ? '1' : '0',
        );

        // Opt-in: check the asset in when the vendor stops reporting
        // an assigned user (a previously-assigned device that now
        // returns null / empty on the user field). Default off because
        // any single missing sync cycle would flap the assignment.
        // Admins turn it on when they trust their vendor's user
        // reporting to be consistent.
        SyncAdapterConfig::put(
            $this->instance->id,
            'checkin_on_null_user',
            $request->boolean($slug.'_checkin_on_null_user') ? '1' : '0',
        );

        // Migration aid for customers moving from a homegrown sync
        // script that already populated the assets table. When on,
        // provisionAsset() looks up an existing asset by serial
        // before creating a new shell asset, and inserts an
        // asset_external_sources row so subsequent syncs match by
        // external_id. Default off, keeps the safe "vendor host with
        // no known link creates a fresh asset" behavior.
        SyncAdapterConfig::put(
            $this->instance->id,
            'adopt_by_serial',
            $request->boolean($slug.'_adopt_by_serial') ? '1' : '0',
        );

        // Opt-out: skip asset creation on pull when the vendor record
        // has no existing Snipe-IT counterpart.
        SyncAdapterConfig::put(
            $this->instance->id,
            'create_snipeit_assets_on_pull',
            $request->boolean($slug.'_create_snipeit_assets_on_pull') ? '1' : '0',
        );

        // Per-device enrichment opt-in. Only persisted for adapters
        // that declare a perDeviceDetailsToggle(). Default off so
        // large-fleet installs don't eat an extra Graph call per
        // device unless the admin explicitly opts in.
        if ($this->perDeviceDetailsToggle() !== null) {
            SyncAdapterConfig::put(
                $this->instance->id,
                'fetch_per_device_details',
                $request->boolean($slug.'_fetch_per_device_details') ? '1' : '0',
            );
        }

        // Pull dry-run flag. When on, Sync Now still calls pull() so
        // vendor-side fetch, mapping, and normalization all run - but
        // the consumer logs each HostInventoryRecord instead of handing
        // it to syncFromRecord, so no asset is created, updated, or
        // linked. Mirror of push_dry_run on the other direction.
        SyncAdapterConfig::put(
            $this->instance->id,
            'pull_dry_run',
            $request->boolean($slug.'_pull_dry_run') ? '1' : '0',
        );
    }

    /**
     * Per-vendor-group Snipe-IT company mappings. Form emits one input
     * per group (name = {slug}_group_mapping[{vendor_group_id}]).
     * Blank / "unassigned" values clear that group's mapping so it
     * falls back to the instance company_id at sync time.
     */
    private function persistGroupMappings(Request $request, string $slug): void
    {
        foreach ((array) $request->input($slug.'_group_mapping', []) as $vendorGroupId => $companyId) {
            $key = 'group_mapping.'.$vendorGroupId;

            if ($companyId === null || $companyId === '') {
                SyncAdapterConfig::forget($this->instance->id, $key);

                continue;
            }

            SyncAdapterConfig::put($this->instance->id, $key, (string) (int) $companyId);
        }
    }

    /**
     * Standard fields have shipped defaults from MappingTargets. Extras
     * default to skip. Both share the same mapping.{key} storage prefix
     * because the two key namespaces don't collide (standard =
     * hostname/serial/etc, extras = adapter-prefixed).
     *
     * @return array<int, string>
     */
    private function validMappingFields(): array
    {
        return array_merge(
            MappingTargets::FIELDS,
            array_keys($this->extraFields()),
        );
    }

    /**
     * @param  array<int, string>  $validFields
     */
    private function persistFieldMappings(Request $request, string $slug, array $validFields): void
    {
        $posted = (array) $request->input($slug.'_mapping', []);

        // The mapping-picker widget's picker row submits its unfinished
        // pair under <slug>_mapping_pending[key|value] so admins can
        // save without clicking the + button first. Fold it into the
        // posted array before save.
        $pending = (array) $request->input($slug.'_mapping_pending', []);
        $pendingKey = is_string($pending['key'] ?? null) ? trim($pending['key']) : '';
        $pendingValue = is_string($pending['value'] ?? null) ? trim($pending['value']) : '';
        if ($pendingKey !== '' && $pendingValue !== '' && ! array_key_exists($pendingKey, $posted)) {
            $posted[$pendingKey] = $pendingValue;
        }

        foreach ($posted as $field => $target) {
            if (! in_array($field, $validFields, true)) {
                continue;
            }
            SyncAdapterConfig::put($this->instance->id, 'mapping.'.$field, (string) $target);
        }

        // Extras use the mapping-picker widget, which submits only for
        // rows the admin left mapped. Removing a row = the row's key
        // is absent from POST.
        foreach (array_keys($this->extraFields()) as $extraKey) {
            if (! array_key_exists($extraKey, $posted)) {
                SyncAdapterConfig::forget($this->instance->id, 'mapping.'.$extraKey);
            }
        }
    }

    /**
     * Per-field direction (pull / push / skip). Orthogonal to the
     * target column stored above so admins can flip direction without
     * re-picking the target. Only meaningful for adapters that
     * implement PushableSyncAdapter. For pull-only adapters the form
     * doesn't render the direction column, and the default is always pull, and
     * this method is a no-op.
     *
     * @param  array<int, string>  $validFields
     */
    protected function persistFieldDirections(Request $request, string $slug, array $validFields): void
    {
        \Log::debug("This should never be called - there's no such thing as 'direction' for pull-only SyncAdapters");
        // Though, maybe, there is? 'skip' is a direction, and you might use that?
        // TODO - this is copypasta from PushableSyncAdapter, but without it, tests won't pass
        $posted = (array) $request->input($slug.'_direction', []);

        // Widgets' picker rows submit their unfinished pair under
        // <slug>_<map_key>_pending[key|value] so admins can save
        // without clicking + to commit the row first.
        $pairedMapKeys = [$slug.'_mapping_pending'];
        foreach ($this->settingsSchema() as $field) {
            if (($field['type'] ?? '') === 'field_map') {
                $pairedMapKeys[] = $slug.'_'.$field['key'].'_pending';
            }
        }
        $directionPending = (array) $request->input($slug.'_direction_pending', []);
        $pendingDir = is_string($directionPending['value'] ?? null) ? trim($directionPending['value']) : '';
        foreach ($pairedMapKeys as $pendingField) {
            $pairedPending = (array) $request->input($pendingField, []);
            $pendingKey = is_string($pairedPending['key'] ?? null) ? trim($pairedPending['key']) : '';
            $pendingValue = is_string($pairedPending['value'] ?? null) ? trim($pairedPending['value']) : '';
            if ($pendingKey !== '' && $pendingValue !== '' && $pendingDir !== '' && ! array_key_exists($pendingKey, $posted)) {
                $posted[$pendingKey] = $pendingDir;
            }
        }

        // Standard-field pushability gate. Adapters that only know
        // how to push a subset of fields (CustomHttp) coerce
        // push/both on non-pushable standard fields down to pull so
        // we don't persist an unenforceable direction. Extras are
        // defined by the adapter and assumed pushable.
        $pushable = MappingTargets::FIELDS;

        foreach ($posted as $field => $direction) {
            if (! in_array($field, $validFields, true)) {
                continue;
            }
            if (! in_array($direction, ['pull', 'push', 'skip', 'both'], true)) {
                continue;
            }
            if (
                in_array($field, MappingTargets::FIELDS, true)
                && ! in_array($field, $pushable, true)
                && in_array($direction, ['push', 'both'], true)
            ) {
                $direction = 'pull';
            }
            SyncAdapterConfig::put($this->instance->id, 'direction.'.$field, (string) $direction);
        }

        // Same forget-on-omit rule as persistFieldMappings for extras:
        // rows removed via the mapping-picker widget are absent from
        // POST, and their direction needs clearing so it doesn't
        // linger on the next sync if the extra gets re-added.
        foreach (array_keys($this->extraFields()) as $extraKey) {
            if (! array_key_exists($extraKey, $posted)) {
                SyncAdapterConfig::forget($this->instance->id, 'direction.'.$extraKey);
            }
        }
    }

    /**
     * Hook that runs after saveConfig() finishes persisting the form.
     * Empty on the base class. Adapters override to do things like
     * probe the vendor for tier / feature-flag info now that credentials
     * are in place (FleetAdapter caches its license tier here so the
     * group-mapping UI can be hidden on Fleet Free).
     */
    protected function afterSaveConfig(): void
    {
        // no-op by default
    }

    /**
     * Dry-run mode for pull: when true, Sync Now still fetches from
     * the vendor and runs the adapter's normalization, but the pull
     * consumers (PullInventory CLI + SyncAdapterController UI) log
     * each HostInventoryRecord instead of handing it to
     * SyncFromRecord. No asset is created, updated, or linked.
     * Mirror of isPushDryRun() on the other direction. Off by default.
     */
    public function isPullDryRun(): bool
    {
        if ($this->pullDryRunOverride !== null) {
            return $this->pullDryRunOverride;
        }

        return SyncAdapterConfig::get($this->instance->id, 'pull_dry_run') === '1';
    }

    /**
     * Per-request override for the dry-run flags. Set by callers that
     * want to force a dry run without flipping the persisted config
     * (CLI --dry-run flag on snipeit:pull-inventory, UI toggle inside a
     * single click, etc.).
     * Null means "fall back to the persisted config value". Lives on
     * the adapter instance so it's scoped to one adapter object for
     * the current request.
     */
    protected ?bool $pullDryRunOverride = null;

    public function withPullDryRunOverride(?bool $override): static
    {
        $this->pullDryRunOverride = $override;

        return $this;
    }

    // FIXME - do we want to do this differently here versus elsewhere?
    public function directionFor(string $field): string
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'direction.'.$field);

        return in_array($stored, ['pull', 'push', 'skip', 'both'], true) ? $stored : 'pull';
    }

    /**
     * Whether this adapter's settings form should render the
     * "<Adapter>-specific fields" mapping-picker section. True by
     * default - the picker lets admins route adapter-declared extras
     * to Snipe-IT slots. CustomHttp returns false because its extras
     * are admin-defined via the field_paths widget rather than
     * declared statically by the adapter: the picker there would just
     * duplicate what Vendor Response Paths already captures.
     */
    public function rendersExtrasPicker(): bool
    {
        return true;
    }

    /**
     * Currently-selected target for a field, or the shipped default
     * when no per-instance override exists. Standard fields fall back
     * to MappingTargets::defaultTarget(). extras fall back to skip.
     */
    public function mappingFor(string $field): string
    {
        $default = in_array($field, MappingTargets::FIELDS, true)
            ? MappingTargets::defaultTarget($field)
            : 'skip';

        return SyncAdapterConfig::get(
            $this->instance->id,
            'mapping.'.$field,
            $default,
        );
    }

    public function getUrl(): ?string
    {
        return SyncAdapterConfig::get($this->instance->id, 'url');
    }

    public function logsHeartbeats(): bool
    {
        return SyncAdapterConfig::get($this->instance->id, 'log_heartbeats') === '1';
    }

    /**
     * Custom asset-tag pattern the admin configured for auto-created
     * assets. Null when unset (SyncAdapter falls back to
     * Asset::autoincrement_asset() in that case). Placeholders like
     * `{serial}` / `{external_id}` / `{hostname}` get substituted at
     * create time from HostInventoryRecord fields.
     */
    public function assetTagPattern(): ?string
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'asset_tag_pattern');

        return $stored === null || $stored === '' ? null : $stored;
    }

    /**
     * Default category id for auto-created AssetModels from this
     * adapter. Vendors don't send Snipe-IT's category concept, but
     * every AssetModel needs one. When null, SyncAdapter
     * falls back to a get-or-create "Discovered Hardware" category.
     */
    public function defaultCategoryId(): ?int
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'default_category_id');

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

    /**
     * Per-record category override. Adapters that can classify a
     * record's device type (Apple's productFamily, Intune's
     * deviceCategory, etc.) override this to route each record to a
     * more specific category than the instance-wide default.
     *
     * Return null to fall through to defaultCategoryId(). The
     * framework calls this from SyncAdapter when creating a
     * new AssetModel row, so a null return is equivalent to today's
     * one-category-per-instance behavior.
     *
     * @SuppressWarnings("PHPMD.UnusedFormalParameter")
     */
    public function categoryIdForRecord(\App\SyncAdapters\HostInventoryRecord $record): ?int
    {
        return null;
    }

    /**
     * Default status label id for auto-created assets from this
     * adapter. When null, SyncAdapter falls back to the
     * first deployable status label (or, absent that, any status
     * label). Admins pick a specific status to route synced devices
     * into a curated workflow bucket ("Awaiting Assignment", "In
     * Production", etc.) rather than lumping them into whatever
     * happens to be the first deployable row.
     */
    public function defaultStatusId(): ?int
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'default_status_id');

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

    /**
     * Default fieldset for AssetModels auto-created from this adapter.
     * When set, resolveModelIdByName stamps this id on the new model's
     * fieldset_id so custom fields show on synced devices without the
     * admin revisiting each new model after a pull. Null leaves
     * fieldset_id unset (today's behavior for installs that haven't
     * configured this).
     */
    public function defaultFieldsetId(): ?int
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'default_fieldset_id');

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

    /**
     * How the sync path resolves a Snipe-IT user from the vendor's
     * assigned-user data. Returns one of:
     * - 'none'                 no assignment attempted (default)
     * - 'username'             match against users.username only
     * - 'email'                match against users.email only
     * - 'username_then_email'  try username first, fall back to email
     *
     * Anything unrecognized (or absent) degrades to 'none' so a
     * corrupt row or a future rename can't leak into an unexpected
     * match strategy.
     */
    public function userMatchStrategy(): string
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'user_match_strategy');

        return in_array($stored, ['email', 'username', 'username_then_email'], true) ? $stored : 'none';
    }

    /**
     * Whether sync-driven user assignments skip the checkout
     * notification path entirely. When true, the sync goes through
     * silentAssignToUser() which bypasses the CheckoutableCheckedOut
     * event and every listener on it (email, Slack, webhook, etc.).
     * Default true so scheduled syncs don't blast users every time
     * their device phones home.
     */
    public function suppressesNotifications(): bool
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'suppress_notifications');

        // Absent = suppress (safe default). Only an explicit '0'
        // opts back into the standard checkout-event flow.
        return $stored !== '0';
    }

    /**
     * Whether sync should check the asset in when the vendor stops
     * reporting an assigned user. Default false. Turning it on means
     * a device that reported alice@ yesterday and reports null today
     * gets checked in from Alice. Admins opt in when their vendor's
     * user reporting is consistent enough that a null value truly
     * means "unassigned" rather than "field wasn't populated this
     * sync cycle".
     */
    public function checksInOnNullUser(): bool
    {
        return SyncAdapterConfig::get($this->instance->id, 'checkin_on_null_user') === '1';
    }

    /**
     * Migration aid: when on, the sync loop looks for an existing
     * Snipe-IT asset with a matching serial before creating a new
     * shell asset for a first-time sync vendor host.
     */
    public function adoptsBySerial(): bool
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'adopt_by_serial');
        if ($stored !== null) {
            return $stored === '1';
        }

        return $this->instance->last_synced_at === null;
    }

    /**
     * When off, pull-side vendor records with no `asset_external_sources`
     * link are logged and skipped rather than creating a new Snipe-IT
     * asset. Default on so existing installs behave unchanged. Admins
     * flip it off when their vendor data contains rows that shouldn't
     * become Snipe-IT assets (e.g. Intune devices with generic serials
     * that would duplicate manually-entered rows).
     */
    public function createsSnipeitAssetsOnPull(): bool
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'create_snipeit_assets_on_pull');

        return $stored === null ? true : $stored === '1';
    }

    /**
     * Whether this adapter's vendor exposes a groups concept
     * (Fleet Teams, Jamf Sites, Kandji Blueprints, etc.) that
     * admins can map to Snipe-IT companies. Default false so
     * adapters without group support don't render the mapping
     * section on the settings page. Adapters override to true and
     * implement fetchGroups() + populate vendorGroupId in normalize.
     */
    public function supportsGroupScoping(): bool
    {
        return false;
    }

    /**
     * Vendor's own terminology for their groups concept. Used in the
     * mapping section header (e.g. "Fleet Team", "Kandji Blueprint",
     * "Jamf Site") so admins see wording they recognize.
     */
    public function vendorGroupLabel(): string
    {
        return 'Group';
    }

    /**
     * Placeholder shown in the base-URL input on the settings page.
     * Overridden by adapters whose vendor uses a well-known URL
     * (SaaS APIs with fixed hostnames or a well-defined subdomain
     * pattern). Adapters targeting self-hosted vendors return null.
     */
    public function baseUrlPlaceholder(): ?string
    {
        return null;
    }

    /**
     * Adapter-specific help copy rendered under the base-URL input.
     * Overridden by adapters whose vendor requires the admin to look
     * up the API URL in a non-obvious place (e.g. Kandji hides the
     * API URL behind the Access page's API Token section). Returning
     * null falls back to the generic base_url_help lang key.
     */
    public function baseUrlHelp(): ?string
    {
        return null;
    }

    /**
     * Live-fetch the current list of groups from the vendor.
     * Returns an array of ['id' => '...', 'label' => '...']. Called
     * when the admin clicks the "refresh groups" button on the
     * settings page. Default throws so adapters that opt into
     * supportsGroupScoping have to implement it. Adapters without
     * group support never have this called.
     *
     * @return array<int, array{id: string, label: string}>
     */
    public function fetchGroups(): array
    {
        throw new \RuntimeException(static::class.' declared group scoping support but did not implement fetchGroups().');
    }

    /**
     * Per-instance vendor-group to Snipe-IT-company mappings, keyed
     * by vendor group id. Empty when the admin has not configured any
     * mappings.
     *
     * @return array<string, int>
     */
    public function groupMappings(): array
    {
        $mappings = [];
        foreach (SyncAdapterConfig::listForInstance($this->instance->id) as $key => $value) {
            if (! str_starts_with($key, 'group_mapping.')) {
                continue;
            }
            $vendorGroupId = substr($key, strlen('group_mapping.'));
            if ($value !== null && $value !== '') {
                $mappings[$vendorGroupId] = (int) $value;
            }
        }

        return $mappings;
    }

    /**
     * Snipe-IT company id for a vendor group id, or null when the
     * group has no mapping. Callers (SyncAdapter) fall back
     * to the instance's own company_id in that case.
     */
    public function companyForVendorGroup(string $vendorGroupId): ?int
    {
        $mappings = $this->groupMappings();

        return $mappings[$vendorGroupId] ?? null;
    }

    /**
     * Cached copy of the last fetchGroups() result, so the settings
     * page renders the mapping table without hitting the vendor on
     * every page load. Refreshed when the admin clicks the button.
     *
     * @return array<int, array{id: string, label: string}>
     */
    public function cachedGroups(): array
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'cached_groups');
        if ($stored === null || $stored === '') {
            return [];
        }
        $decoded = json_decode($stored, true);

        return is_array($decoded) ? $decoded : [];
    }

    /**
     * Whether the adapter's vendor exposes a tenant / site / workspace
     * concept that scopes the pull to one chosen entry. UniFi
     * Network's Site, Jamf School's Location, Microsoft Entra Tenant,
     * etc. Different from supportsGroupScoping(): sites choose ONE
     * entry to pull from, groups map many vendor groups to Snipe-IT
     * companies. Adapters that opt in render Site ID as a select
     * backed by cachedSites() and implement fetchSites().
     */
    public function supportsSiteScoping(): bool
    {
        return false;
    }

    /**
     * Vendor's own terminology for the site concept. Mirrors
     * vendorGroupLabel() so admins see wording they recognize in the
     * refresh button and empty-state copy.
     */
    public function vendorSiteLabel(): string
    {
        return 'Site';
    }

    /**
     * Live-fetch the current list of sites from the vendor. Returns
     * an array of ['id' => '...', 'label' => '...']. Called from the
     * settings page's "refresh sites" button. $overrides lets the
     * caller supply the base URL and credentials from the pending
     * form so a brand-new adapter can discover its sites before the
     * admin saves anything. Keys match the schema field keys the
     * adapter declares (e.g. 'url', 'api_key'). Default throws so
     * adapters that opt into supportsSiteScoping have to implement it.
     *
     * @param  array<string, string|null>  $overrides
     * @return array<int, array{id: string, label: string}>
     */
    public function fetchSites(array $overrides = []): array
    {
        throw new \RuntimeException(static::class.' declared site scoping support but did not implement fetchSites().');
    }

    /**
     * Cached copy of the last fetchSites() result, so the settings
     * page renders the Site ID select without hitting the vendor on
     * every page load.
     *
     * @return array<int, array{id: string, label: string}>
     */
    public function cachedSites(): array
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'cached_sites');
        if ($stored === null || $stored === '') {
            return [];
        }
        $decoded = json_decode($stored, true);

        return is_array($decoded) ? $decoded : [];
    }

    /**
     * Whether the adapter supports fetching a list of vendor-defined
     * custom fields at settings-refresh time. Vendors like Kaseya VSA
     * 10 expose per-tenant custom fields whose names admins can only
     * discover at the tenant level, so extraFields() alone cannot
     * declare them statically. Adapters that opt in override this and
     * implement fetchVendorCustomFields() plus enrichment in pull().
     */
    public function supportsVendorCustomFields(): bool
    {
        return false;
    }

    /**
     * Fetch the current list of custom-field definitions from the
     * vendor. Default is empty. Adapters that opt into
     * supportsVendorCustomFields() must override this to hit the
     * vendor's custom-fields listing endpoint.
     *
     * @return array<int, array{id: string, name: string, type: string}>
     */
    public function fetchVendorCustomFields(): array
    {
        return [];
    }

    /**
     * Return the cached vendor custom fields from the last refresh.
     * Same storage pattern as cachedGroups(): a JSON blob under the
     * `vendor_custom_fields` config key, refreshed when the admin
     * clicks the button. extraFields() reads this back to merge
     * vendor-specific fields into the mapping UI.
     *
     * @return array<int, array{id: string, name: string, type: string}>
     */
    public function cachedVendorCustomFields(): array
    {
        $stored = SyncAdapterConfig::get($this->instance->id, 'vendor_custom_fields');
        if ($stored === null || $stored === '') {
            return [];
        }
        $decoded = json_decode($stored, true);

        return is_array($decoded) ? $decoded : [];
    }

    public function lastSyncedAt(): ?\Carbon\CarbonInterface
    {
        return $this->instance->last_synced_at;
    }

    public function lastSyncResult(): ?string
    {
        return $this->instance->last_sync_result;
    }

    /**
     * Value of a credential for form pre-fill. Returns '' on any
     * failure (missing row, rotated app key, corrupt ciphertext) so
     * blade always has a string to drop into `value=""`. Failed
     * decryption becomes an empty field the admin can re-enter.
     * Loud failures during sync go through credential() instead.
     */
    public function credentialForDisplay(string $key): string
    {
        try {
            return $this->credential($key);
        } catch (\Throwable) {
            return '';
        }
    }

    /**
     * Decrypted (or plain, per schema) value of a credential, for
     * pull() implementations building their vendor API client.
     * Throws loudly on any failure so admins see a real error message
     * instead of a silent auth failure on the vendor's side.
     */
    public function credential(string $key): string
    {
        $stored = SyncAdapterConfig::get($this->instance->id, $key);
        if ($stored === null) {
            throw new \RuntimeException(
                'No '.$key.' stored for '.$this->instance->label.'. Save one on the adapters settings page.',
            );
        }

        foreach ($this->settingsSchema() as $field) {
            if ($field['key'] !== $key) {
                continue;
            }

            if (! ($field['secret'] ?? false)) {
                return $stored;
            }

            try {
                return Crypt::decrypt($stored);
            } catch (\Throwable $e) {
                throw new \RuntimeException(
                    'Unable to decrypt '.$key.' for '.$this->instance->label.'. Re-enter it on the adapters settings page.',
                    previous: $e,
                );
            }
        }

        throw new \RuntimeException(
            $key.' is not a declared credential for '.$this->instance->label,
        );
    }

    protected function url(): string
    {
        return SyncAdapterConfig::get($this->instance->id, 'url') ?? '';
    }
}