@camstack/system 1.2.330 → 1.2.331

package/dist/builtins/doorbell/virtual-doorbell.addon.d.ts

@@ -1,218 +0,0 @@
-import { ProviderRegistration, BaseAddon } from '@camstack/types';
-interface VirtualDoorbellAddonConfig {
-    /** Per-camera debounce window (ms) against sensor chatter. */
-    readonly debounceMs: number;
-    /**
-     * Reload the camera→source assignment map (and the binding mirror) at
-     * most this often — lazily, on trigger traffic. Covers devices/settings
-     * appearing after boot without a save, and is the cadence on
-     * which an unbind gets corroborated.
-     */
-    readonly assignmentsTtlMs: number;
-}
-/**
- * VirtualDoorbellAddon — WRAPPER over the `doorbell` capability.
- *
- * Turns any binary sensor or switch (contact, motion, flood/gas/CO/smoke,
- * vibration, tamper, generic binary, or a switch) into a doorbell for a
- * camera:
- *
- *   1. The operator binds the wrapper to a camera in the bindings UI
- *      (`defaultActive: false` — never auto-bound).
- *   2. In the camera's Extensions section (the `doorbell-source` slot,
- *      D648/D655) the operator picks one or more SOURCE devices — that is
- *      the ONLY choice. The reaction is derived automatically per
- *      device type: a binary sensor rings when it goes active, a switch
- *      rings when it turns on (see `trigger-engine.ts`). The persisted
- *      shape (`doorbellSources: [{deviceId}]`) stays extensible for a
- *      future custom-trigger override.
- *   3. At runtime the addon watches `EventCategory.DeviceStateChanged`
- *      (binary/switch slice transitions — false→true edge detected). On a
- *      matching, debounced rise it emits `EventCategory.DoorbellOnPressed`
- *      with the CAMERA as source (`{deviceId: cameraId, timestamp}` — the
- *      same shape Reolink's native `emitDoorbellPressed` produces) and
- *      bumps the camera's `doorbell` runtime-state counters via the
- *      standard `deviceState.setCapSlice` plumbing.
- *
- * Fires ONLY for cameras with at least one configured source device that
- * this wrapper is BOUND to. The binding is NOT re-derived on the ring path:
- * it is mirrored in memory (`binding-mirror.ts`) and refreshed on the
- * assignment-reload cadence, because a fallible read must never be able to
- * destroy a one-shot press.
- */
-export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddonConfig> {
-    private engine;
-    private compositionMigration;
-    private providerRegisteredUnsubscribe;
-    /** Monotonic guard: assignments are reloaded lazily on trigger traffic. */
-    private assignmentsLoadedAt;
-    private assignmentsLoading;
-    /**
-     * Per-camera mirror of "is this wrapper still the active doorbell
-     * binding". Written ONLY off the ring path; read on it. See
-     * `binding-mirror.ts` for why a single negative read is not believed.
-     */
-    private readonly bindingMirror;
-    /**
-     * Per camera, the last NEGATIVE refresh this addon reported — its state,
-     * the authority's verdict and who else serves the doorbell. A refresh runs
-     * every reload cycle (about once a minute); the same answer repeated is not
-     * news, so it is reported once per change and forgotten on a positive read.
-     * Camera 615 logged the same WARN 607 times in 14 h after D671.
-     */
-    private readonly reportedNegative;
-    /** Cameras whose last durable-authority read THREW — reported once per outage. */
-    private readonly durableReadFailing;
-    /**
-     * Per camera, the OTHER providers of `doorbell` the last successful derived
-     * read named (the composer after D671). Written off the ring path with the
-     * mirror; read on it, to decide whether erring open would double a ring.
-     */
-    private readonly servedElsewhere;
-    /** Cameras whose store-over-derived disagreement has been reported, until a derived read agrees. */
-    private readonly reportedStoreOverride;
-    constructor();
-    protected onInitialize(): Promise<ProviderRegistration[]>;
-    protected onShutdown(): Promise<void>;
-    /**
-     * The `device-extension` provider: the only editor of a camera's trigger
-     * devices since D655 (see `doorbell-extension-slot.ts`).
-     */
-    private buildExtensionProvider;
-    private handleStateChanged;
-    /**
-     * Say out loud every case where a rise did NOT become a ring. Silence
-     * reads as "never happened": three real presses on camera 615 produced
-     * zero operator-visible lines because the drop logged at `debug`.
-     */
-    private logSuppressions;
-    /**
-     * Ring the camera's virtual doorbell: bump the `doorbell` runtime-state
-     * counters through the canonical `deviceState.setCapSlice` write, and
-     * emit the typed `DoorbellOnPressed` event with the CAMERA as source —
-     * byte-shaped like a native firmware ring so every downstream consumer
-     * (UI toast, notifier rules, exporters) is agnostic to the origin.
-     *
-     * The binding gate here is a pure in-memory read on the path that RINGS:
-     * a `bound` mirror, or an open one on a camera nobody else serves, performs
-     * NO I/O and cannot fail. Every other case asks the durable authority once
-     * before deciding — see `needsDurableRead` and `ringsAfterDurableRead`.
-     *
-     * `sourceDeviceId`/`capName` are the source that produced this rise —
-     * carried through purely so the terminal `pressed` line can name it. Every
-     * suppression branch beside it already reports its source
-     * (`logSuppressions`); the successful path was the one place that did not,
-     * which meant answering "what rang it" required hand-correlating a
-     * timestamp against provider logs (proven live 2026-08-25, camera 615).
-     */
-    private fireDoorbell;
-    /**
-     * The addon id as the REGISTRY and the bindings store spell it.
-     *
-     * `ctx.id` does NOT: hub-main prefixes it (`addon:virtual-doorbell`) while
-     * a forked runner does not, and this builtin runs in hub-main. Comparing
-     * the raw `ctx.id` to a `providerAddonId` was false for every entry for
-     * twelve hours on 2026-08-07 (D72).
-     */
-    private get ownAddonId();
-    /**
-     * One read of the DERIVED binding view. `null` when the read could not be
-     * answered at all — which carries no information and must leave the mirror
-     * untouched.
-     */
-    private readDerivedBinding;
-    /**
-     * One read of the DURABLE authority: the wrapper activation device-manager
-     * STORED for this camera (`deviceManager.getWrapperActivation`, D675) — the
-     * row the operator's bindings toggle writes. `deviceManager.getBindings` is
-     * a VIEW derived from it plus the capability registry.
-     *
-     * This is deliberately NOT `getBindings`. The derived view folds the store
-     * together with the capability registry, `defaultActive` auto-binding and
-     * the cluster native-cap feeds — any of which can make it disagree with
-     * what the operator actually persisted, and one of which (an addon-id
-     * spelling mismatch) made it disagree *systematically* while looking
-     * exactly like a genuine unbind. The raw row cannot: it is what the
-     * bindings toggle wrote, and it grades its own trustworthiness (D44).
-     *
-     * A read that throws is reported when the outage STARTS and when it ends —
-     * never per read: this runs on every reload cycle.
-     */
-    private readDurableAuthority;
-    /**
-     * Reconcile `cameraId`'s mirror against the authority. Runs on the
-     * assignment-reload cadence, never while firing — and it runs on EVERY
-     * cycle regardless of the current verdict, so a camera sitting in
-     * `unbound` returns to `bound` on its own the moment the authority says
-     * so. There is no latch here that an operator has to clear.
-     *
-     * A positive derived read is believed immediately. A NEGATIVE one never
-     * is: the durable authority is asked, and it outranks the derived view in
-     * the direction that destroys work. Only when the authority agrees does
-     * the negative get folded, and even then `nextBindingState` still wants a
-     * second consecutive one (D49).
-     */
-    private refreshBindingMirror;
-    /** The ring gate's in-memory input for one camera — no I/O. */
-    private mirrorRead;
-    /**
-     * Report a negative refresh ONCE per change of what it says (D391: a
-     * repeated identical line is noise that buries the next real one).
-     *
-     * The level follows what the answer MEANS:
-     *   - the durable store could not grade it (`unreadable`) — WARN: the
-     *     camera's ring now depends on erring open, and nobody can say whether
-     *     that is right;
-     *   - the store CONFIRMS the wrapper is not bound — an operator's unbind or
-     *     the D671 cutover to a composition. That is a state, not an anomaly:
-     *     INFO when it is believed (`unbound`), DEBUG for the first,
-     *     not-yet-believed read.
-     */
-    private reportNegativeRefresh;
-    /**
-     * A real press arrived on a camera the in-memory gate cannot clear on its
-     * own: the mirror is `unbound`, or it is short of `bound` while another
-     * provider serves the doorbell. Decide, with ONE read of the durable
-     * authority, whether this wrapper rings.
-     *
-     * D49 forbade I/O on the ring path because the read it would have made was
-     * the same fallible derived read that caused the problem. This read is
-     * different in both directions: it is the authority rather than a view of
-     * it, and it is paid ONLY where erring open could be wrong — a dropped ring
-     * (an `unbound` mirror) or a DOUBLED one (another provider rings this
-     * camera). A ring is rare and one query is cheap. An unreadable store still
-     * rings: it carries no information.
-     *
-     * Returns `true` when the ring must proceed.
-     */
-    private ringsAfterDurableRead;
-    /**
-     * Lazily (re)build the camera→source assignment set from every
-     * camera's device store. TTL-bounded so devices/settings appearing
-     * after boot are picked up without a save; invalidated eagerly by
-     * `persistDoorbellSources`.
-     */
-    private ensureAssignments;
-    private loadAssignments;
-    private invalidateAssignments;
-    /**
-     * Status from the kernel-managed `doorbell` runtime-state slice —
-     * the wrapper keeps NO parallel counter fields (the slice is the
-     * single source of truth, persisted across restarts).
-     */
-    private getStatus;
-    /**
-     * The camera's configured doorbell sources, parsed tolerantly (new
-     * `doorbellSources` shape + legacy single-source migration).
-     */
-    private readDeviceSources;
-    /**
-     * THE write path for a camera's trigger sources — the `doorbell-source`
-     * extension slot lands here (D648; its only caller since D655): normalise
-     * to `doorbellSources: [{deviceId}]`, strip the legacy keys, and invalidate
-     * the assignment cache so the next rise (and the binding mirror's next
-     * refresh, off the ring path) sees the new wiring.
-     */
-    private persistDoorbellSources;
-}
-export default VirtualDoorbellAddon;