Skip to content

A free open source IT asset/license management system

31.4 KB
Raw Blame
<?php

namespace App\SyncAdapters;

use App\Models\Asset;
use App\Models\CustomField;
use App\Models\SyncAdapterConfig;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

/**
 * Marker + contract for adapters that support pushing Snipe-IT-owned
 * field values back to the vendor (Snipe-IT asset_tag -> vendor
 * asset_tag, Snipe-IT notes -> vendor notes, etc.). Kept separate
 * from SyncAdapter so pull-only vendors (osctrl, Zentral,
 * UniFi) don't have to stub anything.
 *
 * Adapters that implement this ALSO implement SyncAdapter
 * in practice — the two directions share credentials, base URL, and
 * asset identity (asset_external_sources.external_id). The interfaces
 * stay separate so an adapter can be pull-only, push-only, or both.
 */
abstract class PushableSyncAdapter extends SyncAdapter
{
    /**
     * Runtime check: is push actually available for this instance
     * right now? Adapters return false when a vendor-side gate is
     * in effect (Fleet manual labels are Premium-only, Jamf writes
     * need extra role scopes, etc.) so the settings-page UI hides
     * the push controls instead of letting admins configure a path
     * that will 403 at execution time.
     *
     * Default implementations may return true unconditionally. The
     * check is opt-in per adapter.
     */
    abstract public function canPush(): bool;

    /**
     * Name (or dotted path) of the vendor's single freeform notes
     * field that admins can compose from a template. Return null
     * when the vendor has no such field (or when routing composed
     * notes would be a semantic stretch, e.g. hostname).
     *
     * Push implementations call SyncAdapter::composeNotesForPush()
     * and set the returned ['value'] on the returned ['target']
     * position in the outgoing payload.
     */
    abstract public function notesFieldTarget(): ?string;

    /**
     * Push the currently-configured `push`-direction fields for one
     * asset to the vendor. Implementations are responsible for:
     * - Resolving the vendor-side external_id from the asset's
     *   asset_external_sources row scoped to this adapter's instance
     * - Filtering the field set to those directed 'push' via
     *   SyncAdapter::directionFor()
     * - Serializing each field into the vendor's expected shape
     * - Sending the write call
     *
     * Silent no-op is acceptable when the asset has no external_source
     * row for this instance (never synced from here, so we have no
     * vendor-side id to write against).
     *
     * Return true when the adapter actually reached out to the vendor
     * (or logged a dry-run payload). Return false when the call was
     * skipped for any reason (nothing to push for this asset, no
     * external-source row, empty payload, etc.). The controller's
     * batch runner uses the return value to distinguish "successfully
     * pushed" from "skipped" so the flash message reflects reality
     * instead of counting every silent no-op as a success.
     *
     * @param  array<int, string>  $changedFields
     *                                             Optional list of source-field names (hostname, asset_tag,
     *                                             etc.) that changed and prompted this push. Implementations
     *                                             may use this to skip an API call when no push-direction field
     *                                             is in the changed set. When empty, treat as "push everything
     *                                             marked push-direction".
     */
    abstract public function push(Asset $asset, array $changedFields = []): bool;

    // default implementations for 'push', can be overridden


    public function pushableFields(): array
    {
        return MappingTargets::FIELDS;
    }

    protected function persistOperationalSettings(Request $request, string $slug): void
    {
        parent::persistOperationalSettings($request, $slug);
        // Push dry-run flag. When on, adapters log the push payload
        // instead of sending it, so admins can verify mapping +
        // direction config against real assets without any vendor
        // side effect.
        SyncAdapterConfig::put(
            $this->instance->id,
            'push_dry_run',
            $request->boolean($slug . '_push_dry_run') ? '1' : '0',
        );

        // Push notes template. Blade-ish {placeholder} string that
        // adapters with a notes-shape vendor field (Intune, Kandji,
        // Jamf, etc.) render + push to that field. Blank = don't push
        // a notes field. Empty-string save clears the template.
        SyncAdapterConfig::put(
            $this->instance->id,
            'push_notes_template',
            (string) $request->input($slug . '_push_notes_template', ''),
        );

        // Optional override for which vendor field the composed
        // notes get pushed to. Blank = use the adapter's default
        // (Kandji: notes, Jamf: general.notes, Intune: notes, etc.).
        // Admin sets this when their vendor has multiple candidate
        // fields (Kandji's `notes` vs a specific custom field, WS1's
        // Custom Attribute name, Ninja's Custom Field name).
        SyncAdapterConfig::put(
            $this->instance->id,
            'push_notes_target',
            (string) $request->input($slug . '_push_notes_target', ''),
        );
    }

    /**
     * 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.
     *
     * @param  array<int, string>  $validFields
     */
    protected function persistFieldDirections(Request $request, string $slug, array $validFields): void
    {
        $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 = $this->pushableFields();

        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);
            }
        }
    }


    /**
     * Dry-run mode for push: when true, PushableSyncAdapter::push()
     * implementations should build the payload and log it via the
     * sync-adapters channel but skip the actual vendor API call.
     * Lets admins verify their mapping + direction configuration
     * end-to-end without touching the vendor. Off by default.
     */
    public function isPushDryRun(): bool
    {
        if ($this->pushDryRunOverride !== null) {
            return $this->pushDryRunOverride;
        }

        return SyncAdapterConfig::get($this->instance->id, 'push_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:push-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 $pushDryRunOverride = null;

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

        return $this;
    }

    /**
     * Valid placeholder keys for the composed-notes push template.
     * Admins wrap these tokens in {curly-braces} inside their
     * push_notes_template to build a single-field notes blob from
     * many Snipe-IT fields. `{custom.Field Name}` accesses any
     * CustomField by its exact display name (case-sensitive).
     * Unknown placeholders and null values render as empty so a
     * template referencing missing fields degrades gracefully.
     *
     * Admin-facing descriptions of each placeholder live in the
     * `push_notes_template_help` translation, not here, so the
     * catalog stays translator-friendly.
     *
     * @var array<int, string>
     */
    public const NOTES_TEMPLATE_PLACEHOLDERS = [
        'asset_tag',
        'name',
        'serial',
        'model',
        'model_number',
        'manufacturer',
        'category',
        'status',
        'status_type',
        'assigned_to',
        'assigned_to_email',
        'assigned_to_username',
        'location',
        'company',
        'supplier',
        'last_checkout',
        'last_checkin',
        'expected_checkin',
        'notes',
        'order_number',
        'purchase_date',
        'purchase_cost',
        'warranty_months',
        'warranty_expires',
    ];

    public function pushDirectedFields(): array
    {
        $out = [];
        $candidates = array_merge(MappingTargets::FIELDS, array_keys($this->extraFields()));
        foreach ($candidates as $field) {
            // Standard-field target "Skip (do not sync)" wins over
            // whatever the paired direction dropdown says - the field
            // is explicitly opted out of syncing in either direction.
            // The direction value may still be 'push' in the stored
            // config from before the target was flipped to skip, but
            // we treat the field as excluded from the push set
            // regardless. Also protects against stale state on
            // direction=push + mapping=skip combos the UI used to be
            // able to produce.
            //
            // Extras skip this gate because their mapping default is
            // 'skip' (no stored row = "not configured, not synced")
            // and their direction toggle is the only control the
            // admin has to pick push on them.
            if (in_array($field, MappingTargets::FIELDS, true) && $this->mappingFor($field) === 'skip') {
                continue;
            }
            if (in_array($this->directionFor($field), ['push', 'both'], true)) {
                $out[] = $field;
            }
        }

        return $out;
    }


    /**
     * Resolve one of the standard source-field names (hostname,
     * asset_tag, serial, model, notes, etc.) to the matching value
     * on the asset. Push implementations call this when building
     * their outgoing payload so every adapter reads Snipe-IT values
     * the same way. Returns null for unknown source-field names,
     * for extras (vendor-specific keys the base class can't map),
     * or when the asset has no value for that field.
     *
     * Adapters with a vendor-specific extra that needs pushing
     * override in the subclass, call parent for the standard fields,
     * and handle the vendor-specific keys in the child branch.
     */
    protected function assetValueForSourceField(Asset $asset, string $field): mixed
    {
        // Native fast-path: the four fields every adapter can push
        // without consulting a mapping target. Pre-dates the mapping-
        // target resolver below so adapters that call this with
        // non-mapped fields (test harnesses, future callers) still get
        // a sensible answer.
        $native = match ($field) {
            'hostname', 'name' => $asset->name,
            'serial' => $asset->serial,
            'asset_tag' => $asset->asset_tag,
            'model' => $asset->model?->name,
            'notes' => $asset->notes,
            default => null,
        };
        if ($native !== null) {
            return $native;
        }

        // For other source fields (os, os_version, last_seen, mac,
        // custom:X, etc.) consult the per-field mapping target so the
        // middleman push scenario (pull from vendor A, push to vendor
        // B) can actually surface the stored value. The mapping is
        // the admin's choice of "where in Snipe-IT does this field
        // live" - we read from that slot.
        $target = $this->mappingFor($field);
        if ($target === '' || $target === 'skip') {
            return null;
        }

        if (str_starts_with($target, 'custom:')) {
            $customFieldId = (int) substr($target, 7);
            $customField = CustomField::find($customFieldId);
            if ($customField === null || $customField->db_column === null) {
                return null;
            }

            return $asset->getAttribute($customField->db_column);
        }

        if (str_starts_with($target, 'external:')) {
            $column = substr($target, 9);
            $row = \Illuminate\Support\Facades\DB::table('asset_external_sources')
                ->where('asset_id', $asset->id)
                ->where('source', $this->name())
                ->first();

            return $row->{$column} ?? null;
        }

        if (str_starts_with($target, 'native:')) {
            // Direct read from the asset column named after the
            // target. The sync writers use the same convention, so
            // native:foo stored by pull is readable as $asset->foo.
            $column = substr($target, 7);

            return $asset->getAttribute($column);
        }

        return null;
    }

    /**
     * Standard push() implementation for single-endpoint adapters. An
     * adapter whose push() writes one payload to one endpoint (Kandji,
     * Jamf, NinjaOne) overrides two hooks (buildPushPayload,
     * dispatchPush) and delegates push() to this template.
     *
     * Adapters with split-endpoint pushes (Mosyle posts asset_tag and
     * notes to separate operations, Workspace ONE splits device fields
     * from Custom Attributes) implement push() directly and don't call
     * this. CustomHttp also implements push() directly because its
     * dry-run log and dispatch depend on admin-configured HTTP method
     * and endpoint that the template can't parameterize.
     *
     * Success and dry-run log lines use typeLabel() plus the flat
     * $touched list (falling back to array_keys($payload) when the
     * adapter builds a flat-keyed payload and doesn't populate
     * $touched). Adapters wanting vendor-specific log wording override
     * push() directly instead of using the template.
     *
     * @param  array<int, string>  $changedFields
     */
    protected function pushViaSinglePayload(Asset $asset, array $changedFields): bool
    {
        $externalSource = $this->pushPrologue($asset, $changedFields);
        if ($externalSource === null) {
            return false;
        }

        [$payload, $touched] = $this->buildPushPayload($asset);
        $this->applyComposedNotesToPayload($asset, $payload, $touched);

        if ($payload === []) {
            return false;
        }

        $written = $touched !== [] ? $touched : array_keys($payload);

        if ($this->isPushDryRun()) {
            Log::channel('sync-adapters')->info(sprintf(
                '%s push [dry-run]: would send %s to %s device %s',
                $this->name(),
                json_encode($payload, JSON_UNESCAPED_SLASHES),
                static::typeLabel(),
                $externalSource->external_id,
            ));

            return true;
        }

        $this->dispatchPush($externalSource, $payload);

        Log::channel('sync-adapters')->info(sprintf(
            '%s push: updated %s device %s [%s]',
            $this->name(),
            static::typeLabel(),
            $externalSource->external_id,
            implode(', ', $written),
        ));

        return true;
    }

    /**
     * Build the outgoing vendor payload for pushViaSinglePayload().
     * Adapters that call pushViaSinglePayload() override this to
     * return their payload and the flat list of dot-paths / keys that
     * were written (for the post-push audit log). Empty payload signals
     * "nothing to send" and the template short-circuits.
     *
     * @return array{0: array<string, mixed>, 1: array<int, string>}
     */
    protected function buildPushPayload(Asset $asset): array
    {
        throw new \LogicException(static::class . ' calls pushViaSinglePayload() but does not override buildPushPayload().');
    }

    /**
     * Fire the vendor HTTP call for pushViaSinglePayload(). Adapters
     * that call pushViaSinglePayload() override this. Failures throw
     * (the outer controller catches and renders a red-flash summary,
     * matching the pull path). No return value: presence of the call
     * is enough, the template logs success on its own.
     *
     * @param  array<string, mixed>  $payload
     */
    protected function dispatchPush(\App\Models\AssetExternalSource $externalSource, array $payload): void
    {
        throw new \LogicException(static::class . ' calls pushViaSinglePayload() but does not override dispatchPush().');
    }

    /**
     * Shared prologue for every PushableSyncAdapter::push() implementation.
     * Runs the three identical guards each adapter's push() started with
     * and returns the AssetExternalSource row when the push should
     * proceed, or null when any guard rejects it. Callers early-return
     * on null.
     *
     * The three guards, in order:
     *  1. pushDirectedFields is empty AND no composed-notes template is
     *     configured (nothing to send, skip).
     *  2. Caller-provided $changedFields is non-empty but doesn't
     *     intersect pushDirectedFields (the caller told us which
     *     fields changed and none of them are push-directed on this
     *     instance, so skip the vendor call).
     *  3. asset_external_sources row missing (the asset was never
     *     synced from this instance, so we have no vendor device id
     *     to write against).
     *
     * @param  array<int, string>  $changedFields
     */
    public function pushPrologue(Asset $asset, array $changedFields): ?\App\Models\AssetExternalSource
    {
        $pushFields = $this->pushDirectedFields();
        $notesConfigured = $this->hasComposedNotesConfigured();

        if ($pushFields === [] && !$notesConfigured) {
            // Nothing directed push and no composed-notes template.
            // Logged at info because this is a config-shape issue
            // the admin should see in the per-run log + file log
            // instead of just "0 pushed, N skipped" with no reason.
            Log::channel('sync-adapters')->info(sprintf(
                '%s push: skipped asset %d (asset_tag=%s) - no push-directed fields and no composed-notes template configured',
                $this->name(),
                $asset->id,
                $asset->asset_tag ?? '(none)',
            ));

            return null;
        }

        if ($pushFields !== [] && $changedFields !== []
            && array_intersect($changedFields, $pushFields) === []) {
            Log::channel('sync-adapters')->info(sprintf(
                '%s push: skipped asset %d (asset_tag=%s) - changed fields [%s] do not intersect push-directed fields [%s]',
                $this->name(),
                $asset->id,
                $asset->asset_tag ?? '(none)',
                implode(', ', $changedFields),
                implode(', ', $pushFields),
            ));

            return null;
        }

        $externalSource = \App\Models\AssetExternalSource::query()
            ->where('asset_id', $asset->id)
            ->where('source', $this->name())
            ->first();

        if ($externalSource === null) {
            Log::channel('sync-adapters')->info(sprintf(
                '%s push: skipped asset %d (asset_tag=%s) - no asset_external_sources row for this adapter instance',
                $this->name(),
                $asset->id,
                $asset->asset_tag ?? '(none)',
            ));
        }

        return $externalSource;
    }

    /**
     * Composed notes payload for a push, or null when nothing to
     * push. Reads the admin's push_notes_template from config,
     * resolves the target vendor field (admin override or
     * PushableSyncAdapter::notesFieldTarget() default), then substitutes
     * every {placeholder} against the given asset.
     *
     * Placeholders are enumerated in NOTES_TEMPLATE_PLACEHOLDERS.
     * `{custom.Field Name}` resolves any CustomField by exact
     * display name. Unknown keys and null values render as empty,
     * so a template referencing missing fields degrades gracefully
     * instead of throwing.
     *
     * Adapter push() implementations call this and check for null:
     * non-null returns give both the vendor field name (`target`)
     * and the rendered string (`value`), so the caller can splice
     * both into its payload in one hit.
     *
     * @return array{target: string, value: string}|null
     */
    public function composeNotesForPush(Asset $asset): ?array
    {
        $template = (string) SyncAdapterConfig::get($this->instance->id, 'push_notes_template');
        if (trim($template) === '') {
            // Blank template is the common "feature not in use" case,
            // so log at debug - skipping it on every asset push would
            // just noise up the file log on fleets that haven't set
            // up composed notes.
            Log::channel('sync-adapters')->debug(sprintf(
                '%s push: asset %d (asset_tag=%s) - composed notes not applied: push_notes_template is blank',
                $this->name(),
                $asset->id,
                $asset->asset_tag ?? '(none)',
            ));

            return null;
        }

        $target = $this->resolveComposedNotesTarget();
        if ($target === null) {
            // Template is set but target field path is not. This IS
            // worth surfacing at info - the admin wrote a template
            // expecting it to be pushed somewhere and the destination
            // config is missing.
            Log::channel('sync-adapters')->info(sprintf(
                '%s push: asset %d (asset_tag=%s) - composed notes not applied: push_notes_template is set but no target field is configured (push_notes_target)',
                $this->name(),
                $asset->id,
                $asset->asset_tag ?? '(none)',
            ));

            return null;
        }

        // Match anything between braces that isn't itself a brace.
        // Permissive so custom-field names with spaces or punctuation
        // ({custom.Cost Center}, {custom.Warranty (extended)}) match
        // cleanly. The inner match block below decides validity.
        $value = preg_replace_callback(
            '/\{([^{}]+)\}/',
            function (array $m) use ($asset): string {
                $key = $m[1];

                if (str_starts_with($key, 'custom.')) {
                    $field = CustomField::query()->where('name', substr($key, 7))->first();
                    if ($field === null || $field->db_column === null) {
                        return '';
                    }
                    $stored = $asset->getAttribute($field->db_column);

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

                return match ($key) {
                    'asset_tag' => (string) ($asset->asset_tag ?? ''),
                    'name' => (string) ($asset->name ?? ''),
                    'serial' => (string) ($asset->serial ?? ''),
                    'model' => (string) ($asset->model->name ?? ''),
                    'model_number' => (string) ($asset->model->model_number ?? ''),
                    'manufacturer' => (string) ($asset->model->manufacturer->name ?? ''),
                    'category' => (string) ($asset->model->category->name ?? ''),
                    'status' => (string) ($asset->status->name ?? ''),
                    'status_type' => (string) ($asset->status?->getStatuslabelType() ?? ''),
                    'assigned_to' => (string) ($asset->assignedTo?->present()?->name() ?? ''),
                    'assigned_to_email' => (string) ($asset->assignedTo->email ?? ''),
                    'assigned_to_username' => (string) ($asset->assignedTo->username ?? ''),
                    'location' => (string) ($asset->location->name ?? ''),
                    'company' => (string) ($asset->company->name ?? ''),
                    'supplier' => (string) ($asset->supplier->name ?? ''),
                    'last_checkout' => (string) ($asset->last_checkout ?? ''),
                    'last_checkin' => (string) ($asset->last_checkin ?? ''),
                    'expected_checkin' => (string) ($asset->expected_checkin ?? ''),
                    'notes' => (string) ($asset->notes ?? ''),
                    'order_number' => (string) ($asset->order_number ?? ''),
                    'purchase_date' => (string) ($asset->purchase_date ?? ''),
                    'purchase_cost' => (string) ($asset->purchase_cost ?? ''),
                    'warranty_months' => (string) ($asset->warranty_months ?? ''),
                    'warranty_expires' => (string) ($asset->warranty_expires ?? ''),
                    default => '',
                };
            },
            $template,
        ) ?? '';

        return ['target' => $target, 'value' => $value];
    }

    /**
     * Splice the composed-notes payload (from composeNotesForPush)
     * into an outgoing vendor payload. Returns true when composed
     * notes were configured and spliced, false when there was
     * nothing to send. Callers that track which fields they pushed
     * (for post-push logging or event dispatch) pass their $touched
     * array by reference. The target field name gets appended to
     * it on success.
     *
     * Uses Arr::set so dotted target paths (Jamf's "general.notes"
     * shape) branch into nested payload structures rather than
     * writing a literal key with a dot in it.
     *
     * @param  array<mixed>  $payload
     * @param  array<int, string>  $touched
     */
    public function applyComposedNotesToPayload(Asset $asset, array &$payload, array &$touched = []): bool
    {
        $composedNotes = $this->composeNotesForPush($asset);
        if ($composedNotes === null) {
            return false;
        }

        \Illuminate\Support\Arr::set($payload, $composedNotes['target'], $composedNotes['value']);
        $touched[] = $composedNotes['target'];

        return true;
    }

    /**
     * Stored composed-notes template + target-override, exposed for
     * the settings-page form so it can pre-fill the two inputs.
     * Runtime callers use composeNotesForPush() instead, which
     * resolves the effective target (falling back to
     * PushableSyncAdapter::notesFieldTarget()) and does the substitution
     * in one hit.
     *
     * @return array{template: string, target_override: ?string}
     */
    public function storedPushNotesConfig(): array
    {
        $template = (string) SyncAdapterConfig::get($this->instance->id, 'push_notes_template');
        $target = (string) SyncAdapterConfig::get($this->instance->id, 'push_notes_target');

        return [
            'template' => $template,
            'target_override' => $target === '' ? null : $target,
        ];
    }

    /**
     * True when this instance has ANY push configuration in place
     * (at least one field directed 'push' OR a composed-notes
     * template + target). Used by the controller's Push Now handler
     * to abort with a clear error before iterating asset rows when
     * the admin hit the button on a fresh or incorrectly-configured
     * adapter, instead of iterating N rows that each silent-no-op
     * and reporting an inaccurate success.
     */
    public function hasPushConfiguration(): bool
    {
        return $this->pushDirectedFields() !== [] || $this->hasComposedNotesConfigured();
    }

    /**
     * Cheap "should we bother trying to push composed notes?" check
     * used by pushPrologue to gate the vendor call without paying
     * the cost of rendering the template. True when the admin has a
     * non-blank push_notes_template AND a resolvable target field.
     */
    private function hasComposedNotesConfigured(): bool
    {
        $template = (string) SyncAdapterConfig::get($this->instance->id, 'push_notes_template');

        return trim($template) !== '' && $this->resolveComposedNotesTarget() !== null;
    }

    /**
     * Vendor field name for the composed-notes push. Admin's
     * override (push_notes_target config key) wins if set. Falls
     * back to the adapter's suggested default via
     * PushableSyncAdapter::notesFieldTarget(). Null when neither is
     * set (adapter has no notes concept AND admin didn't name a
     * target field).
     */
    private function resolveComposedNotesTarget(): ?string
    {
        $stored = (string) SyncAdapterConfig::get($this->instance->id, 'push_notes_target');
        if ($stored !== '') {
            return $stored;
        }

        return $this->notesFieldTarget();
    }

    /**
     * Whether the composed-notes push UI should appear on this
     * adapter's settings page. Default is "yes if the adapter is
     * pushable at all" so existing adapters stay unchanged. Adapters
     * targeting APIs that have no notes-like field anywhere in their
     * push payload (Mosyle Manager v2's push elements, for example)
     * override this to false so admins don't fill in a template that
     * can never land. notesFieldTarget() returning null doesn't carry
     * this meaning (Workspace ONE / NinjaOne return null legitimately
     * because the admin picks the target).
     */
    public function supportsComposedNotesPush(): bool
    {
        return $this->canPush();
    }

}