@camstack/types 1.2.88 → 1.2.89

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

@@ -0,0 +1,348 @@
+/**
+ * rule-kinds — WHICH KIND OF RULE THIS IS, WHICH FIELDS IT ACTUALLY HAS, AND
+ * WHICH LIST SECTION IT LIVES IN. Pure, UI-framework-free, RN-safe.
+ *
+ * WHY IT LIVES HERE
+ * ─────────────────
+ * Two editors author the same rules — the admin UI (React DOM, shipped with
+ * `camstack deploy`) and the viewer (React Native / Hermes, shipped by EAS OTA)
+ * — and the layer they were NOT sharing is this one: not the schema (already
+ * shared) and not the widgets (they cannot be), but the model in between.
+ * The divergence it caused is on the record: the viewer filtered conditions on
+ * the served `appliesTo` alone, so a viewer-authored occupancy rule was still
+ * offered `sensorKinds`, `eventTypeTokens` and `source` — the exact "in
+ * occupancy alcuni campi non hanno senso" failure the admin UI fixed on
+ * 2026-08-14 and the viewer never got. Beside it, the viewer's rule list had no
+ * sections and no seeded creates, so the two features that have no delivery of
+ * their own (sound, occupancy) were unauthorable from the phone.
+ *
+ * The CONTENT is what makes a second copy expensive: a dozen exclusions, each
+ * traced to a subject field the engine reads and finds absent, each carrying
+ * the sentence shown to the operator. Two tables disagreeing about which fields
+ * an occupancy rule has is the same failure as two knobs writing a store nobody
+ * read.
+ *
+ * THE MISSING DIMENSION
+ * ─────────────────────
+ * The editor had exactly ONE dimension of applicability, the rule's `delivery`,
+ * which the served catalog answers through `appliesTo`. Two features have no
+ * delivery of their own:
+ *
+ *   - an OCCUPANCY rule is a `device-event` rule carrying `conditions.occupancy`
+ *   - a SOUND rule is an `immediate` rule carrying `conditions.audio`
+ *
+ * and the engine discriminates them by that CONDITION (`rule-engine.ts`: an
+ * occupancy edge fires only for a rule declaring `occupancy`, a confirmed audio
+ * window only for one declaring `audio`). So an occupancy rule was offered the
+ * whole `device-event` surface — sensor kinds, raw event tokens, a detection
+ * source — every one of which the engine FAILS CLOSED on an occupancy subject,
+ * because the subject carries no `sensorKind`, no `eventType` and always the
+ * `pipeline` source.
+ *
+ * This module adds that dimension: `delivery` × `kind`. Visibility is the
+ * COMPOSITION of the two — `appliesTo` still answers the trigger question (it is
+ * the server's answer and stays authoritative), and the kind subtracts what the
+ * sub-type cannot use. Every subtraction is declared WITH ITS REASON and the
+ * reason is shown to the operator rather than kept in a comment.
+ *
+ * LABELS ARE ENGLISH FALLBACKS, NOT TRANSLATIONS. The stable thing here is the
+ * ID (`kind`, section `key`, editor-section `key`); the admin UI renders these
+ * strings verbatim, the viewer maps the ids onto its `v2.nc.rules.*` i18n keys
+ * and falls back to them.
+ *
+ * The admin UI keeps a pinned local copy for now — `@camstack/types` reaches it
+ * as a Module-Federation singleton provided by the HOST, so a newly-added export
+ * reads `undefined` there until a server closure carrying it is installed. See
+ * `docs/design/2026-08-19-viewer-notification-rule-parity.md` §3 and Phase 3.
+ */
+import { type NcAudioCondition, type NcConditions, type NcDelivery, type NcOccupancyCondition } from '../capabilities/notification-rules.cap.js';
+/**
+ * The kind of rule an operator is authoring.
+ *
+ * Coarser than `delivery` in one direction and finer in another, deliberately:
+ * `immediate` / `track-end` / `package-event` are ONE kind here (their
+ * differences are already the catalog's `appliesTo` job), while `device-event`
+ * and `immediate` each split in two on their discriminating condition.
+ */
+export type NcRuleKind = 'detection' | 'sensor' | 'occupancy' | 'sound' | 'system';
+export interface NcRuleKindSpec {
+    readonly kind: NcRuleKind;
+    /** What the conditions section is CALLED for this kind (English fallback). */
+    readonly label: string;
+    /**
+     * The condition that MAKES a rule this kind. Always visible, and never
+     * excluded — burying it would hide the whole feature (which is how an
+     * operator with a working audio engine reported there was no way to create an
+     * audio rule).
+     */
+    readonly discriminator?: keyof NcConditions;
+    /**
+     * Conditions the catalog offers for this kind's DELIVERY that a rule of this
+     * kind cannot use, each with the engine reason — shown to the operator when a
+     * save is about to drop one.
+     */
+    readonly excluded: Readonly<Record<string, string>>;
+    /**
+     * Can a notification of this kind carry a picture AT ALL?
+     *
+     * `false` is not a UI preference, it is the delivery path: the attachment
+     * ladder resolves media by OWNER, and only a subject that freezes one has any
+     * (`triggerCanCarryStill` in the addon's `test-event.ts` is the same list).
+     *
+     * Only `system` is left. An infrastructure event is about no camera at all —
+     * there is nothing to photograph, so every media control on it is a knob that
+     * does nothing. A SOUND rule was here until 2026-08-15 and was right to be:
+     * its subject is a sampling window that owns no frame. It now photographs the
+     * camera at the match instead (`still-shelf.ts`), which is a picture nothing
+     * else could give it.
+     */
+    readonly carriesMedia: boolean;
+    /**
+     * Does anything about this kind's subject describe a REGION of the frame?
+     *
+     * `false` removes the two controls that cut one — the zone crop and the image
+     * frame — because neither has an input. A sound was not boxed and carries no
+     * zone condition to crop to, so `frame: 'cropped'` resolves nothing and
+     * `zoneCrop` has no ids to use. Same argument as `excluded`, applied to the
+     * media policy instead of the conditions: a knob that decides nothing is
+     * worse than a missing one, because the operator sets it and believes they
+     * have asked for something.
+     */
+    readonly carriesSubjectCrop: boolean;
+    /** One line under the section title — what this kind of rule IS. */
+    readonly blurb?: string;
+    /** One line above the media controls, when the picture needs explaining. */
+    readonly mediaBlurb?: string;
+}
+export declare const NC_RULE_KIND_SPECS: readonly NcRuleKindSpec[];
+/** The spec for a kind. Total by construction — every member has an entry. */
+export declare function ruleKindSpec(kind: NcRuleKind): NcRuleKindSpec;
+/** The delivery a system rule rides — named once, compared everywhere. */
+export declare const NC_SYSTEM_DELIVERY = "system-event";
+/**
+ * Is this a SYSTEM rule — one about the installation rather than about anything
+ * a camera saw? Takes a plain `string` so a rule carrying a delivery this build
+ * has never heard of still gets an answer instead of a type error.
+ */
+export declare function isSystemDelivery(delivery: string): boolean;
+/**
+ * The conditions of a rule, as much of them as classification needs.
+ *
+ * DELIBERATELY STRUCTURAL, and this is load-bearing. The viewer keeps its OWN
+ * Zod mirror of the rule schema on purpose (older/newer hub tolerance —
+ * `camstack/src/data/notification-center.ts`), so a parameter typed as THIS
+ * package's `NcConditions` would be unusable from the surface this module was
+ * hoisted for without a cast, and this repo does not take casts. Two optional
+ * `unknown`s is the whole question the classifier asks.
+ */
+export interface NcRuleConditionsSubject {
+    readonly occupancy?: unknown;
+    readonly audio?: unknown;
+}
+/** Every authored condition, keyed by descriptor id — same reasoning as above. */
+export type NcAuthoredConditions = Readonly<Record<string, unknown>>;
+/** What both the kind and the section ask a rule about. */
+export interface NcRuleSectionSubject {
+    readonly delivery: string;
+    readonly conditions: NcRuleConditionsSubject;
+}
+/**
+ * Which kind of rule is this?
+ *
+ * The CONDITION wins over the delivery wherever the engine says it does, and
+ * the order below is the engine's own: `evaluateRule` checks the system branch
+ * first, then the occupancy and audio gates. Takes a plain `delivery` string so
+ * a trigger this build does not know still classifies (as `detection`, which is
+ * the read-only path's own fallback).
+ */
+export declare function ruleKindOf(rule: NcRuleSectionSubject): NcRuleKind;
+/**
+ * The shape {@link conditionVisibleForKind} reads off a catalog descriptor.
+ *
+ * `appliesTo` is `readonly string[]`, not `readonly NcDelivery[]`: the catalog
+ * arrives at RUNTIME from a server that may be newer than this build, and each
+ * editor parses it through its own mirror. Narrowing the parameter to this
+ * package's union would reject the viewer's descriptor for a nominal reason
+ * while the value is identical.
+ */
+export interface NcKindVisibilitySubject {
+    readonly id: string;
+    readonly appliesTo: readonly string[];
+}
+/**
+ * Is this condition visible — and authorable — for a rule of this kind?
+ *
+ * The COMPOSITION, and the only function that decides it: `appliesTo` is the
+ * server's answer about the trigger, the kind's `excluded` map is this build's
+ * answer about the sub-type, and the discriminator overrides both (a sound rule
+ * must be able to edit its sound even though `audio` is excluded for every
+ * OTHER kind that rides `immediate`).
+ */
+export declare function conditionVisibleForKind(descriptor: NcKindVisibilitySubject, delivery: string, kind: NcRuleKind): boolean;
+/** Why a condition is not offered for this kind, or `null` when it IS. */
+export declare function conditionExclusionReason(descriptorId: string, kind: NcRuleKind): string | null;
+/**
+ * Conditions the rule CARRIES that this kind cannot use — the save will drop
+ * them, and the operator is told which and why BEFORE pressing Save.
+ *
+ * Dropping is the right action and not a compromise: every entry here is a
+ * condition the engine fails closed on for this subject, so the rule is
+ * currently enabled, in the list, and permanently silent. Keeping it would keep
+ * it silent; dropping it is what makes the rule fire again. Saying nothing
+ * about the drop would be the third option, and it is the one this repo has
+ * paid for before.
+ */
+export interface NcDroppedCondition {
+    readonly conditionId: string;
+    readonly reason: string;
+}
+export declare function droppedConditionsForKind(conditions: NcAuthoredConditions, kind: NcRuleKind): readonly NcDroppedCondition[];
+/**
+ * The sections a rule LIST is split into.
+ *
+ * Operator request, 2026-08-13: "vorrei che le system rules fossero in una
+ * sezione a parte, più facile da utilizzare, affianco alle detection rules". A
+ * system rule and a detection rule share a store and nothing else — different
+ * triggers, different conditions, no media, a different question ("is my
+ * installation healthy?" vs "what did the camera see?").
+ *
+ * `all` is kept and is the DEFAULT: a section that hides rules is how an
+ * operator concludes a rule was deleted. Which sections a given SURFACE offers
+ * for authoring is that surface's decision — the viewer omits `system` from its
+ * create flow and still renders system rules under `all`.
+ */
+export type NcRuleSectionKey = 'all' | 'detection' | 'audio' | 'occupancy' | 'system';
+export interface NcRuleSection {
+    readonly key: NcRuleSectionKey;
+    /** English fallback; the viewer maps `key` onto an i18n key. */
+    readonly label: string;
+    /** Shown under the section strip — what this section is for. */
+    readonly blurb: string;
+    /** The create button's words in this section — it authors a DIFFERENT rule. */
+    readonly newRuleLabel: string;
+    /** What the section says when it holds nothing yet. */
+    readonly emptyHint: string;
+}
+export declare const NC_RULE_SECTIONS: readonly NcRuleSection[];
+/** The section for a key, or `undefined` — the lookup behind every label. */
+export declare function ruleSection(key: NcRuleSectionKey): NcRuleSection;
+/** Narrow a raw section string back to a known key (no cast). */
+export declare function parseRuleSection(value: string): NcRuleSectionKey | undefined;
+/** True for a rule whose sound condition makes it a SOUND rule. */
+export declare function isAudioRule(subject: NcRuleSectionSubject): boolean;
+/** True for a rule whose occupancy condition makes it an OCCUPANCY rule. */
+export declare function isOccupancyRule(subject: NcRuleSectionSubject): boolean;
+/**
+ * Does a rule belong in this section?
+ *
+ * `all` always matches — a section that hides a rule is how an operator
+ * concludes it was deleted. The other four PARTITION the list: sound and
+ * occupancy are claimed by their condition, system by its trigger, and
+ * everything left over — including a trigger this build has never heard of —
+ * counts as a detection rule so it stays visible somewhere.
+ *
+ * Keyed on the CONDITION for two of them, because the trigger alone cannot
+ * answer: a sound rule is `immediate` and an occupancy rule is `device-event`,
+ * and in each case the condition is the discriminator the engine itself uses.
+ * A section keyed on delivery would put both back in the pile they are
+ * invisible in.
+ */
+export declare function ruleMatchesSection(subject: NcRuleSectionSubject, section: NcRuleSectionKey): boolean;
+/** The ONE real section a rule lives in — `all` holds everything and is not it. */
+export type NcRuleOwningSectionKey = Exclude<NcRuleSectionKey, 'all'>;
+/**
+ * Which section OWNS this rule — the counter behind a section strip.
+ *
+ * Derived from {@link ruleMatchesSection} rather than restated, so the strip's
+ * counts and the strip's contents can never disagree.
+ */
+export declare function ruleSectionOf(subject: NcRuleSectionSubject): NcRuleOwningSectionKey;
+/**
+ * The occupancy schema's own defaults, in one place.
+ *
+ * Both the WIDGET (what an untouched sub-field shows) and the CREATION PRESET
+ * (what "New occupancy rule" seeds) have to author exactly these numbers, and
+ * two copies of a default is how a preset starts writing a rule that does not
+ * match what the editor then displays. Mirrors `NcOccupancyConditionSchema`'s
+ * `.default(...)` clauses, and the spec asserts the mirror.
+ */
+export declare const NC_OCCUPANCY_DEFAULTS: NcOccupancyCondition;
+/**
+ * The seeded sound condition.
+ *
+ * Carries a level floor rather than the bare defaults: with neither a level nor
+ * a label the engine returns false for every window (`matchesAudio`), so a
+ * preset without one would hand the operator a rule that can never fire. The
+ * offered level is the same one the widget writes, so switching to SOUNDS
+ * (label mode — the one that fires on the first labelled frame, D157) is one
+ * tap on the mode picker.
+ *
+ * The seed cannot be a label rule instead: a labels-only condition with no
+ * labels chosen yet is fail-closed too, and it would hand the operator the same
+ * dead rule from the other side.
+ */
+export declare const NC_AUDIO_SEED: NcAudioCondition;
+/**
+ * What a "New rule" started from a section opens on.
+ *
+ * A trigger alone was enough while every section WAS a trigger. It is not for
+ * sound and occupancy: the condition is what makes the rule that kind of rule,
+ * so the preset seeds it — otherwise the operator lands on a form identical to
+ * a detection rule's and has to know that the feature lives behind an expander
+ * on a trigger they must pick first. That is exactly the gap reported on
+ * 2026-08-13 ("non vedo un modo per creare le nuove rules audio e occupancy")
+ * for two features whose engines had already shipped.
+ */
+export interface NcRuleSeed extends NcRuleSectionSubject {
+    readonly delivery: NcDelivery;
+    /** Pre-authored conditions — the ones that DEFINE the kind, nothing else. */
+    readonly conditions: NcConditions;
+}
+export declare function ruleSeedForSection(section: NcRuleSectionKey): NcRuleSeed;
+/** The trigger a "New rule" in this section should open on. */
+export declare function defaultDeliveryForSection(section: NcRuleSectionKey): NcDelivery;
+/**
+ * The rule editor's sections, in the order an operator meets them.
+ *
+ * Operator request, 2026-08-04 (admin) and 2026-08-18 (viewer): the editor was
+ * ONE scrolling form holding every setting a rule has, so authoring a simple
+ * rule meant scrolling past everything a simple rule does not need. Ordered by
+ * how often a setting is touched — not by how the schema is shaped.
+ *
+ * The admin renders them as dialog TABS and the viewer as one scroll of
+ * headings (a phone scrolls; dialog tabs are a desktop idiom), and the viewer
+ * renders a SUBSET — but the ORDER is shared, because two surfaces that put the
+ * same five things in two different orders are two features to learn.
+ *
+ * The `fields` claim map stays per-surface: each editor's form state is its own
+ * type, and each side's spec asserts every field of ITS form is claimed exactly
+ * once. What is shared is which sections exist, in what order, and which ones a
+ * kind shows at all.
+ */
+export type NcRuleEditorSectionKey = 'rule' | 'devices' | 'conditions' | 'notification' | 'actions' | 'advanced';
+export declare const NC_RULE_EDITOR_SECTION_ORDER: readonly NcRuleEditorSectionKey[];
+export interface NcRuleEditorSection {
+    readonly key: NcRuleEditorSectionKey;
+    /** English fallback; the viewer maps `key` onto an i18n key. */
+    readonly label: string;
+}
+/**
+ * The sections a rule of THIS kind actually shows.
+ *
+ * Two rules, both of them about a control that would decide nothing:
+ *
+ *  - a `system-event` rule has no device scope — `conditions.devices` is not
+ *    evaluated for it and the input builder refuses to write it — so the
+ *    Cameras section is DROPPED rather than shown and ignored;
+ *  - a sound or occupancy rule is NAMED on its conditions section. Neither has
+ *    a trigger of its own, so that section is the only place either feature
+ *    exists, and a heading that never mentions sound is exactly why an operator
+ *    with a working audio engine reported there was no way to create an audio
+ *    rule.
+ *
+ * The NOTIFICATION section always survives: priority and the template still
+ * matter even for a kind that carries no picture, and dropping the section to
+ * hide the media controls would take the template with it. Whether the media
+ * half renders is `carriesMedia` / `carriesSubjectCrop`, asked separately.
+ */
+export declare function ruleEditorSectionsForKind(kind: NcRuleKind): readonly NcRuleEditorSection[];

package/package.json

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