@camstack/types 0.1.40 → 0.1.41

package/dist/types/detection.d.ts

@@ -200,9 +200,9 @@ export interface AudioDetection extends DetectionBase {
  *
  * Named `DetectionEntry` rather than `Detection` because the
  * device-capabilities namespace already exports a different `Detection`
- * interface for Scrypted-style object detectors. The two live in
- * separate files but both are re-exported at the package root, so
- * keeping names distinct avoids an import-level collision.
+ * interface for object detectors. The two live in separate files but
+ * both are re-exported at the package root, so keeping names distinct
+ * avoids an import-level collision.
  */
 export type DetectionEntry = ObjectDetection | AudioDetection;
 /**

package/dist/types/io.d.ts

@@ -46,7 +46,7 @@ export interface FrameInput {
  */
 export interface AudioChunkInput {
     readonly [key: string]: unknown;
-    readonly data: Uint8Array;
+    readonly data: Uint8Array<ArrayBuffer>;
     readonly sampleRate: number;
     readonly channels: number;
     readonly timestamp: number;

package/dist/types/io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/types/io.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpE,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAA;AAEpE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;QACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KACtB,CAAA;IACD,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAA;QACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAC7B,CAAA;IACD,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAClC"}
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/types/io.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpE,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAA;AAEpE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;QACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KACtB,CAAA;IACD,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAA;QACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAC7B,CAAA;IACD,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAClC"}

package/dist/util/location-match.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure fuzzy matcher for adoption location import. Normalized
+ * case-insensitive Levenshtein similarity, used to reuse an existing
+ * CamStack location when an imported source location (e.g. an HA area) is
+ * close enough — otherwise the caller creates a new location.
+ */
+/** Similarity in [0,1]; 1 = identical (after trim + lowercase). */
+export declare function locationSimilarity(a: string, b: string): number;
+/**
+ * Returns the existing name with the highest similarity to `externalName`,
+ * provided it is at least `threshold`; otherwise `null` (caller should create
+ * a new location named `externalName`).
+ */
+export declare function bestLocationMatch(externalName: string, existing: readonly string[], threshold?: number): string | null;
+//# sourceMappingURL=location-match.d.ts.map

package/dist/util/location-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location-match.d.ts","sourceRoot":"","sources":["../../src/util/location-match.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6BH,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,SAAS,SAAM,GACd,MAAM,GAAG,IAAI,CAWf"}

package/dist/utils/canonical-hash.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Deterministic SHA-256 hash of an arbitrary serialisable value. The
+ * canonical form sorts object keys alphabetically at every depth so two
+ * structurally-equal inputs with different key insertion orders produce
+ * the same hash. Returns a 64-char lowercase hex digest.
+ *
+ * Used by export adapters (Alexa, HAP) to short-circuit re-discovery /
+ * accessory-rebuild work when the upstream shape is byte-identical to
+ * the last applied state — preventing user-visible "re-discovery"
+ * notifications on every addon-runner respawn. Each respawn re-fires
+ * `DeviceBindingsChanged` for every cap registration, which without
+ * this guard would propagate redundant pushes.
+ *
+ * Note: this is a SYMPTOMATIC fix layered on top of the binding-change
+ * subscription. The proper fix is a single "device ready" lifecycle
+ * barrier so exports react only when the full cap set has landed —
+ * tracked separately for post-HA-integration work.
+ */
+export declare function canonicalHash(value: unknown): string;
+//# sourceMappingURL=canonical-hash.d.ts.map

package/dist/utils/canonical-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-hash.d.ts","sourceRoot":"","sources":["../../src/utils/canonical-hash.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGpD"}

package/dist/utils/export-reconciler.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure, stateless primitives shared by the camera export addons (Alexa, HAP)
+ * to advertise devices to external ecosystems without re-discovery storms.
+ *
+ * Spec: docs/superpowers/specs/2026-06-01-alexa-hap-export-reconciler-design.md
+ *
+ * Two functions, both pure (no I/O, no clock, no randomness, no event
+ * subscriptions) so they are exhaustively unit-testable in isolation:
+ *
+ *   1) `canonicalDeviceFingerprint(shape)` — a stable hash of the
+ *      EXPORT-RELEVANT device shape (coarse type + the persisted
+ *      `DeviceFeature` set). Order-independent and de-duplicated, so an
+ *      unchanged device produces an identical fingerprint across restarts.
+ *      Identity (`deviceId`) and volatile runtime values (online, battery%,
+ *      name, location) are deliberately excluded.
+ *
+ *   2) `diffExportTargets(desired, lastAdvertised)` — a 3-way set diff keyed
+ *      by `deviceId`: what to add, what to update (fingerprint changed), what
+ *      to remove (no longer desired). Each exporter feeds its own persisted
+ *      per-target sync state in and applies the resulting delta to its
+ *      platform.
+ *
+ * The wiring — event subscription, boot scan, platform apply, persistence —
+ * stays in each exporter; only the fingerprint + diff are shared.
+ */
+/** The export-relevant projection of a device, fed into the fingerprint. */
+export interface DeviceExportShape {
+    /** Numeric device id. Identity only — NOT part of the fingerprint. */
+    readonly deviceId: number;
+    /**
+     * Coarse driver classification (e.g. `'camera' | 'battery-camera' | 'nvr'`),
+     * sourced from the `feature-probe` slice's `deviceType`. Part of the shape:
+     * the same feature set on a different device class can map to a different
+     * export surface.
+     */
+    readonly deviceType: string;
+    /**
+     * Export-relevant `DeviceFeature` values (e.g. `'pan-tilt-zoom'`,
+     * `'two-way-audio'`, `'doorbell-button'`, `'motion-trigger'`,
+     * `'battery-operated'`, `'ptz-autotrack'`). Sourced from the PERSISTED
+     * `PersistedDeviceMeta.features`, so it survives restart and is stable
+     * without a re-probe. Hashed order-independently + de-duplicated.
+     */
+    readonly features: readonly string[];
+}
+/**
+ * Compute the stable 64-char lowercase-hex fingerprint of a device's
+ * export-relevant shape. Two structurally-equal shapes (any feature order,
+ * any duplicates, any deviceId) hash identically.
+ */
+export declare function canonicalDeviceFingerprint(shape: DeviceExportShape): string;
+/** Per-export-target sync state for one device, persisted addon-side. */
+export interface ExportTargetEntry {
+    /** Fingerprint last advertised to this target for this device. */
+    readonly fingerprint: string;
+    /**
+     * Platform-specific external ids (Alexa endpoint ids, HAP accessory UUIDs).
+     * Opaque to the diff — carried so the exporter can address what to update or
+     * delete on its platform.
+     */
+    readonly externalIds: readonly string[];
+}
+/** The 3-way delta produced by `diffExportTargets`. */
+export interface ExportDelta<T> {
+    /** Desired devices with no last-advertised entry — publish fresh. */
+    readonly toAdd: readonly T[];
+    /** Desired devices whose fingerprint differs from last-advertised — re-advertise. */
+    readonly toUpdate: readonly T[];
+    /** `deviceId`s present in last-advertised but absent from desired — retract. */
+    readonly toRemove: readonly number[];
+}
+/**
+ * Pure 3-way diff of desired export state against the persisted
+ * last-advertised state, keyed by `deviceId`.
+ *
+ * - `desired` — one entry per device to advertise this cycle, each carrying
+ *   the freshly-computed `fingerprint`.
+ * - `lastAdvertised` — the exporter's persisted per-target sync state.
+ *
+ * Neither input is mutated.
+ */
+export declare function diffExportTargets<T extends {
+    deviceId: number;
+    fingerprint: string;
+}>(desired: readonly T[], lastAdvertised: ReadonlyMap<number, ExportTargetEntry>): ExportDelta<T>;
+/**
+ * Resolve the fingerprint an exporter should feed into `diffExportTargets`
+ * for one device this cycle.
+ *
+ * When a device is NOT yet probe-ready, carry forward its last-advertised
+ * (persisted) fingerprint so it nets to NO CHANGE in `diffExportTargets`
+ * (neither update nor remove) — never advertise a partial mid-probe shape. A
+ * brand-new un-probed device with no persisted entry falls back to `fresh` so
+ * it can advertise once.
+ */
+export declare function resolveExportFingerprint(input: {
+    ready: boolean;
+    fresh: string;
+    persisted: string | undefined;
+}): string;
+//# sourceMappingURL=export-reconciler.d.ts.map

package/dist/utils/export-reconciler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-reconciler.d.ts","sourceRoot":"","sources":["../../src/utils/export-reconciler.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAG3E;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CACxC;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAA;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAA;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EACnF,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACrD,WAAW,CAAC,CAAC,CAAC,CAsBhB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;CAC9B,GAAG,MAAM,CAGT"}

package/dist/utils/sleep.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Promise-based timer helpers — used everywhere the codebase needs to
+ * wait, back off, or schedule a retry. Before these helpers landed, each
+ * call site re-implemented `new Promise(r => setTimeout(r, ms))` inline,
+ * with subtle variations (some swallowing cancellation, some not). Two
+ * shapes cover every observed use case:
+ *
+ *  - {@link sleep} for a plain, uncancellable wait — the default choice.
+ *  - {@link sleepCancellable} for a wait that wakes early when an
+ *    abort signal trips, used by long-running pollers whose teardown
+ *    must stop a pending backoff promptly.
+ */
+/**
+ * Resolve after `ms` milliseconds. Never rejects, never cancels. The
+ * sleep cannot be interrupted; for a wakeable variant use
+ * {@link sleepCancellable}.
+ *
+ * `ms <= 0` resolves on the next microtask via `setTimeout(0)`, which
+ * still gives the event loop a chance to drain — useful for breaking
+ * up tight async loops without changing call-site semantics.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Resolve after `ms` milliseconds OR when `signal.aborted` flips,
+ * whichever fires first. The returned promise never rejects — aborted
+ * sleeps resolve normally so callers can model "wait or wake" without
+ * try/catch noise.
+ *
+ *   await sleepCancellable(backoffMs, lifecycle.abortSignal)
+ *   if (lifecycle.aborted) return
+ *
+ * If `signal` is already aborted at call time the helper resolves on
+ * the next microtask.
+ */
+export declare function sleepCancellable(ms: number, signal: AbortSignal): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/utils/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../src/utils/sleep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAc/E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",