@camstack/types 1.2.63 → 1.2.64

package/dist/interfaces/addon.d.ts

@@ -1141,6 +1141,27 @@ export interface AddonExecution {
      * former hard-coded addon-name list in `process-service.ts`.
      */
     readonly heapProfile?: AddonHeapProfile;
+    /**
+     * `@camstack/system` builtin ONLY: run this builtin in its OWN forked runner
+     * instead of in-process on the hub root.
+     *
+     * The hub drops `@camstack/system` builtins from the runner plan because the
+     * infrastructure ones (storage, settings, logging, device-manager) must be
+     * resident in the process every runner depends on. That is a reason to keep
+     * THOSE in-process — not a property of the package. A builtin that owns
+     * capture, transcode and byte caches (`snapshot`) charges all of it to the
+     * event loop that also answers the tRPC API.
+     *
+     * Declaring `isolate: true` opts a single builtin out of that blanket rule:
+     * it is planned, spawned, restarted and route-mounted exactly like any other
+     * forked addon, and `resolveRunnerId` still owns its runner id (D2 — one
+     * addon, one process). Nothing else changes: the manifest entry keeps its
+     * `entry` path inside the `@camstack/system` closure, and the runner loads it
+     * from there.
+     *
+     * Ignored for non-system packages — they already fork.
+     */
+    readonly isolate?: boolean;
 }
 export type AddonHeapProfile = 'light' | 'heavy';
 export declare const DEFAULT_ADDON_PLACEMENT: AddonPlacement;
@@ -1184,6 +1205,17 @@ export declare function resolveAddonGroup(decl: Pick<AddonDeclaration, 'executio
 export declare function resolveRunnerId(decl: Pick<AddonDeclaration, 'execution'>, addonId: string): string;
 /** Convenience accessor — the resolved placement (defaults to `hub-only`). */
 export declare function resolveAddonPlacement(decl: Pick<AddonDeclaration, 'execution'>): AddonPlacement;
+/**
+ * True when a `@camstack/system` builtin opted out of the in-process rule and
+ * must be planned as a forked runner (`execution.isolate`).
+ *
+ * ONE predicate, because the hub asks this question in three places that must
+ * agree: the runner plan (`buildAddonGroupPlan`), the "does this boot
+ * in-process" filter, and `isForkedAddonEntry` (which decides route mounts,
+ * data-plane mounts, restart and uninstall). They diverged once before for
+ * `auth-oidc` and the addon's routes were mounted against an async UDS proxy.
+ */
+export declare function isIsolatedBuiltin(decl: Pick<AddonDeclaration, 'execution'>): boolean;
 /**
  * One entry of a `RunnerPlan` — an addon assigned to a runner, paired
  * with the on-disk directory the runner subprocess loads it from.

package/dist/interfaces/event-bus.d.ts

@@ -526,6 +526,29 @@ export interface TopologyNode {
         readonly version: string;
     } | null;
 }
+/**
+ * Why a broker's stream health flipped — the discriminator that separates an
+ * OUTAGE from an intentional state change.
+ *
+ * A `stream.offline` on its own says nothing about whether anything is wrong:
+ * the same event is fired when a camera stops sending video AND when the last
+ * consumer left and the broker suspended its dial on purpose. A consumer that
+ * reads only the category cannot tell them apart, and the Notification Center
+ * shipped exactly that bug — an operator notified that a stream went down
+ * every time nobody was watching it.
+ *
+ *  - `stale-timeout`    — no video packet for the broker's stale window
+ *    (120 s). The ONLY outage. This is what a notification may act on.
+ *  - `recovered`        — packets resumed after a `stale-timeout`. The
+ *    matching end of an outage.
+ *  - `first-packet`     — a broker's first ever packet. A stream coming up, not
+ *    a recovery: there was no outage before it.
+ *  - `suspended`        — the lazy-dial idle suspend (no demand). Deliberate.
+ *  - `resumed`          — demand returned and the dial came back. The matching
+ *    end of a `suspended`, and equally deliberate.
+ *  - `broker-destroyed` — the stream was unpublished/released. Deliberate.
+ */
+export type StreamHealthReason = 'stale-timeout' | 'recovered' | 'first-packet' | 'suspended' | 'resumed' | 'broker-destroyed';
 /** All known event categories with their typed payloads */
 export interface EventCatalog {
     'system.boot': {
@@ -1011,7 +1034,7 @@ export interface EventCatalog {
             readonly engine: PipelineEngineChoice;
             readonly modelsLoaded: readonly string[];
             readonly inUseByCameras: readonly number[];
-            readonly kind: 'runtime' | 'warm-override';
+            readonly kind: 'runtime' | 'warm-override' | 'device-pool';
             readonly poolPid: number | null;
             readonly idleMs: number | null;
             readonly idleTtlMs: number | null;
@@ -1159,6 +1182,9 @@ export interface EventCatalog {
      * (every broker is keyed by its cam stream now); `profile` is the
      * profile slot currently bound to it (or `null` if the broker is
      * only kept alive by a manual activation).
+     *
+     * `reason` is the discriminator a consumer MUST read before treating a flip
+     * as an outage — see {@link StreamHealthReason}.
      */
     'stream.online': {
         readonly deviceId: number;
@@ -1167,7 +1193,7 @@ export interface EventCatalog {
         readonly brokerId: string;
         readonly sourceType: string;
         readonly lastPacketAt: number;
-        readonly reason?: string;
+        readonly reason?: StreamHealthReason;
     };
     'stream.offline': {
         readonly deviceId: number;
@@ -1176,7 +1202,7 @@ export interface EventCatalog {
         readonly brokerId: string;
         readonly sourceType: string;
         readonly lastPacketAt: number;
-        readonly reason?: string;
+        readonly reason?: StreamHealthReason;
     };
     'retention.cleanup': {
         readonly deletedEvents?: number;

package/dist/interfaces/relocate.d.ts

@@ -8,7 +8,15 @@ import { z } from 'zod';
  * Each completed/failed run also lands one durable ops-log row on its owning
  * addon surface.
  */
+/**
+ * `queued` exists because the recorder mover is SINGLE-FLIGHT and an operator
+ * rebalance enqueues one job per (camera, profile). Refusing the second job —
+ * what the engine did before — turned a fifteen-camera rebalance into fifteen
+ * manual retries. Queued jobs run FIFO; a queued job that is cancelled never
+ * runs at all.
+ */
 export declare const RelocateJobStateSchema: z.ZodEnum<{
+    queued: "queued";
     done: "done";
     failed: "failed";
     running: "running";
@@ -18,6 +26,7 @@ export type RelocateJobState = z.infer<typeof RelocateJobStateSchema>;
 export declare const RelocateJobSchema: z.ZodObject<{
     jobId: z.ZodString;
     state: z.ZodEnum<{
+        queued: "queued";
         done: "done";
         failed: "failed";
         running: "running";
@@ -52,6 +61,8 @@ export declare const RelocateFootageInputSchema: z.ZodObject<{
         recordings: "recordings";
         recordingsLow: "recordingsLow";
     }>>;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    profiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     throttleMbps: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type RelocateFootageInput = z.infer<typeof RelocateFootageInputSchema>;
@@ -72,6 +83,8 @@ export declare const StorageMigrationFootageMoveInputSchema: z.ZodObject<{
         recordings: "recordings";
         recordingsLow: "recordingsLow";
     }>>;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    profiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     throttleMbps: z.ZodOptional<z.ZodNumber>;
     leaseId: z.ZodString;
 }, z.core.$strip>;
@@ -147,6 +160,7 @@ export declare const StorageMigrationMoveSchema: z.ZodObject<{
     toLocationId: z.ZodString;
     moverJobId: z.ZodNullable<z.ZodString>;
     state: z.ZodNullable<z.ZodEnum<{
+        queued: "queued";
         done: "done";
         failed: "failed";
         running: "running";
@@ -185,6 +199,7 @@ export declare const StorageMigrationJobSchema: z.ZodObject<{
         toLocationId: z.ZodString;
         moverJobId: z.ZodNullable<z.ZodString>;
         state: z.ZodNullable<z.ZodEnum<{
+            queued: "queued";
             done: "done";
             failed: "failed";
             running: "running";

package/dist/interfaces/stream-broker.d.ts

@@ -265,6 +265,20 @@ export interface IStreamBroker {
      * `H265Repacketizer` once the camera's first RTP+SDP arrive.
      */
     onSdpParameterSets(callback: (ps: ReadonlyArray<Buffer>) => void): Unsubscribe;
+    /**
+     * Subscribe to SOURCE RESTARTS — every dial after the first, carrying a
+     * short reason (`dial#2`, …). The WebRTC server subscribes for EVERY
+     * session shape (RTP passthrough, AnnexB, transcode): each holds parameter
+     * sets and a bootstrap latch belonging to the connection that ended, so a
+     * re-dial must re-sync them rather than leave the session decoding against
+     * a dead mapping.
+     *
+     * Fires on the DIAL, not on the first packet: a restart that never delivers
+     * must still be observable rather than silently indistinguishable from a
+     * healthy stream. The returned function detaches ONE subscriber (a broker
+     * fans out to many live sessions).
+     */
+    onSourceRestart(observer: (reason: string) => void): Unsubscribe;
     /**
      * Source type as configured at `start()` — see `StreamSourceType`
      * for the supported values. `null` before `start()` resolves.

package/dist/notification/timelapse-rule.d.ts

@@ -28,6 +28,35 @@ export declare const TimelapseTemplateSchema: z.ZodObject<{
     body: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type TimelapseTemplate = z.infer<typeof TimelapseTemplateSchema>;
+/**
+ * Floor on any dense cadence, seconds — the recording's own frame interval.
+ *
+ * Declared here because it bounds BOTH the rule field and the renderer's
+ * derivation, and two copies of a floor are two floors that can drift.
+ */
+export declare const TIMELAPSE_DENSE_FLOOR_SEC = 0.1;
+/**
+ * Whether the notification's preview is a STILL or a short animation.
+ *
+ * The operator's ask, verbatim: *"inviato come gif o video (come per le altre
+ * rule)"* — his Scrypted advanced-notifier has a `gifRule`, and a ten-hour
+ * night reads better as three seconds of motion than as one frame of it. Both
+ * modes get the SAME treatment (blurred frame, large centred title); `'gif'`
+ * simply applies it to a dozen frames sampled across the render and assembles
+ * them.
+ *
+ * `'image'` is the default and stays the default: a GIF costs a dozen ffmpeg
+ * seeks and a palette pass, and no rule that never asked for one should start
+ * paying that on the deploy that shipped it.
+ *
+ * A GIF that cannot be assembled DEGRADES to the still — never to nothing.
+ */
+declare const PreviewModeField: z.ZodEnum<{
+    image: "image";
+    gif: "gif";
+}>;
+/** Still or animation — the rule field, as a type the renderer can take. */
+export type TimelapsePreviewMode = z.infer<typeof PreviewModeField>;
 /**
  * Client-supplied timelapse-rule fields. The server stamps id / createdBy /
  * createdAt / updatedAt / ownerUserId / lastGeneratedAt — none of them appear
@@ -48,6 +77,8 @@ export declare const TimelapseRuleInputSchema: z.ZodObject<{
     }, z.core.$strip>;
     cadenceSec: z.ZodDefault<z.ZodNumber>;
     framerate: z.ZodDefault<z.ZodNumber>;
+    denseCadenceSec: z.ZodOptional<z.ZodNumber>;
+    minDwellSec: z.ZodOptional<z.ZodNumber>;
     targets: z.ZodArray<z.ZodObject<{
         targetId: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -56,9 +87,23 @@ export declare const TimelapseRuleInputSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         body: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    previewText: z.ZodOptional<z.ZodString>;
+    previewMode: z.ZodDefault<z.ZodEnum<{
+        image: "image";
+        gif: "gif";
+    }>>;
+    reportClasses: z.ZodOptional<z.ZodArray<z.ZodString>>;
     priority: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type TimelapseRuleInput = z.infer<typeof TimelapseRuleInputSchema>;
+/**
+ * The caption a rule that never set one gets.
+ *
+ * Rendered through the ordinary `{{var}}` pass at delivery, so a rule created
+ * before this field existed still reads "Timelapse Videocamera ingresso" and
+ * not the literal braces.
+ */
+export declare const DEFAULT_TIMELAPSE_PREVIEW_TEXT = "Timelapse {{camera}}";
 /**
  * Partial patch for an update — any subset of the INPUT fields, with NO
  * defaults (an absent key means "leave unchanged", never "reset to default").
@@ -90,6 +135,8 @@ export declare const TimelapseRulePatchSchema: z.ZodObject<{
     }, z.core.$strip>>;
     cadenceSec: z.ZodOptional<z.ZodNumber>;
     framerate: z.ZodOptional<z.ZodNumber>;
+    denseCadenceSec: z.ZodOptional<z.ZodNumber>;
+    minDwellSec: z.ZodOptional<z.ZodNumber>;
     targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
         targetId: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -98,6 +145,12 @@ export declare const TimelapseRulePatchSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         body: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    previewText: z.ZodOptional<z.ZodString>;
+    previewMode: z.ZodOptional<z.ZodEnum<{
+        image: "image";
+        gif: "gif";
+    }>>;
+    reportClasses: z.ZodOptional<z.ZodArray<z.ZodString>>;
     priority: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type TimelapseRulePatch = z.infer<typeof TimelapseRulePatchSchema>;
@@ -117,6 +170,8 @@ export declare const TimelapseRuleSchema: z.ZodObject<{
     }, z.core.$strip>;
     cadenceSec: z.ZodDefault<z.ZodNumber>;
     framerate: z.ZodDefault<z.ZodNumber>;
+    denseCadenceSec: z.ZodOptional<z.ZodNumber>;
+    minDwellSec: z.ZodOptional<z.ZodNumber>;
     targets: z.ZodArray<z.ZodObject<{
         targetId: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -125,6 +180,12 @@ export declare const TimelapseRuleSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         body: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    previewText: z.ZodOptional<z.ZodString>;
+    previewMode: z.ZodDefault<z.ZodEnum<{
+        image: "image";
+        gif: "gif";
+    }>>;
+    reportClasses: z.ZodOptional<z.ZodArray<z.ZodString>>;
     priority: z.ZodDefault<z.ZodNumber>;
     id: z.ZodString;
     ownerUserId: z.ZodOptional<z.ZodString>;
@@ -135,6 +196,27 @@ export declare const TimelapseRuleSchema: z.ZodObject<{
     updatedAt: z.ZodNumber;
 }, z.core.$strip>;
 export type TimelapseRule = z.infer<typeof TimelapseRuleSchema>;
+/** The cadence pair a rule must satisfy — the guard's whole input. */
+export interface TimelapseCadencePair {
+    readonly cadenceSec: number;
+    readonly denseCadenceSec?: number;
+}
+/**
+ * Refuse a dense cadence that is not denser than the base.
+ *
+ * Called at UPSERT, on the MERGED rule — a patch that lowers `cadenceSec`
+ * alone can invalidate a `denseCadenceSec` set months earlier, so checking the
+ * patch in isolation would let the bad pair through.
+ *
+ * Refusing here and not at render time is the whole point: `ExportTimelapseSchema`
+ * also rejects the pair, but it does so when the window has already closed and
+ * the footage is being cut — the operator learns at 06:05 that last night was
+ * never going to render, and a closed window does not come back. This turns
+ * that into a failed edit he can see and correct.
+ *
+ * @throws Error naming both numbers, so the message is actionable in a toast.
+ */
+export declare function assertTimelapseCadences(pair: TimelapseCadencePair): void;
 /**
  * The last successful generation for ONE camera of a rule, epoch-ms.
  *
@@ -148,3 +230,4 @@ export type TimelapseRule = z.infer<typeof TimelapseRuleSchema>;
  * entire rule set once.
  */
 export declare function readTimelapseGeneratedAt(rule: Pick<TimelapseRule, 'lastGeneratedAt' | 'generatedByDevice'>, deviceId: number): number;
+export {};

package/package.json

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