@camstack/types 1.2.236 → 1.2.238

package/dist/capabilities/videoclips.cap.d.ts

@@ -6,13 +6,14 @@ import { type InferProvider } from './capability-definition.js';
  *
  * A device-scoped wrapper COLLECTION (D549 decision 2, D554): every provider a
  * camera has is a SOURCE, and they are listed beside each other — never one
- * substituted for another. The DEFAULT provider (`analytics`, registered by
- * the RECORDER — the addon that owns the footage, D560 — `defaultActive: true`)
- * composes the analytics event log (markers + thumbnails, read over `ctx.api`)
- * with the recorder's own `getPlaybackManifest` — a clip is a time-WINDOW over
- * existing footage, never a separate file. A camera that exposes NATIVE onboard
- * clips (Reolink SD card, a hub's storage, HKSV) adds its own catalog
- * ALONGSIDE that one.
+ * substituted for another, and none of them privileged by name. One source,
+ * `analytics`, is registered by the RECORDER — the addon that owns the
+ * footage, D560 — and composes the analytics event log (markers + thumbnails,
+ * read over `ctx.api`) with the recorder's own `getPlaybackManifest`: a clip
+ * is a time-WINDOW over existing footage, never a separate file. A camera that
+ * exposes NATIVE onboard clips (Reolink SD card, a hub's storage, HKSV) adds
+ * its own catalog ALONGSIDE that one. (`defaultActive` above is the CAP's
+ * auto-bind to cameras, not a ranking among these sources — there is none.)
  *
  * The mount stays per-device (`resolveCapMount` → `device-scoped`), and a
  * device's SOURCES are its BINDINGS: `deviceManager.getBindings(deviceId)` is
@@ -22,10 +23,17 @@ import { type InferProvider } from './capability-definition.js';
  * native provider, as the hub-local registration and as an
  * `<addonId>@<nodeId>` one (D554 amended 2026-09-20).
  *
- * `listClips` is asked of ONE provider at a time
- * ({@link videoclipsCapability.methods.listClips} `provider`), defaulting to
- * the bound one, which is CamStack on every camera today. It is NOT a union
- * over everything a camera has: *"l'utilizzatore è uno solo"*.
+ * `listClips` is asked of ONE provider at a time, and NAMING it is REQUIRED
+ * ({@link videoclipsCapability.methods.listClips} `provider`, D554 amended). It is not
+ * a union over everything a camera has: *"l'utilizzatore è uno solo"*. There
+ * is no default, because a collection cap's binding set is DERIVED and PLURAL
+ * (D554 amended, `getBindings` step 0) — "the bound one" does not exist to
+ * resolve to, and the one thing that could take its place is a second
+ * authority naming a provider per camera, which D554 decision 3 rejected.
+ * The pick is a SURFACE's to make, from the {@link ClipSourceSchema} rows it
+ * already holds, and it says which one it made (D569 § 1–3).
+ * {@link videoclipsCapability.methods.listSources} is the method that fans out
+ * — one row per source, by construction.
  * {@link videoclipsCapability.methods.getClipPlayback} dispatches by the
  * source namespace inside the clip id, which is why ids are self-contained.
  *
@@ -169,6 +177,68 @@ export type ClipPlayback = z.infer<typeof ClipPlaybackSchema>;
  * which days it asked for and got nothing — "no clips" would be a lie about a
  * card that is full of them.
  */
+/**
+ * The operator's authorisation to WAKE a sleeping camera for one clip read.
+ *
+ * ONE value, absent by default, and it is a `force`-shaped operator signal in
+ * exactly the sense `snapshot-wake-gate.ts` uses the word: *"`snapshot.getSnapshot`'s
+ * `force` flag, and nothing else… a background caller must never set it…
+ * Stale but honest beats woken"*. A scheduler, a retry, a reconcile and a
+ * prefetch never set it; a surface sets it only behind the same confirm the
+ * "Wake and refresh" gesture uses, and it is refused below 15 % battery
+ * exactly as that gesture is.
+ *
+ * The gate is decided BEFORE `getApi()`, because on UDP the login IS the wake
+ * (D549) — a read that opened a session and then checked would have woken the
+ * camera to find out it was not allowed to.
+ *
+ * **One authorised yes is one wake.** `next-natural` — take the clip the next
+ * time the camera is awake for its own reasons — is deliberately not a member:
+ * it was proposed, it is free on the battery, and the operator declined it on
+ * 2026-09-20 (*"Quando un export viene richiesto si sveglia la camera."*,
+ * D558 "Considered and not taken").
+ */
+export declare const ClipWakeSchema: z.ZodEnum<{
+    authorised: "authorised";
+}>;
+export type ClipWake = z.infer<typeof ClipWakeSchema>;
+/**
+ * Hard ceiling on ONE {@link videoclipsCapability.methods.readClipBytes} — the
+ * same 50 MiB `RECORDING_EXPORT_MAX_READ_BYTES` uses, and for the same second
+ * reason: the envelope is unary, so a base64 payload is held whole (~1.33× its
+ * size) in the provider AND in the caller, on a hub this repo has already
+ * OOM'd once (D9/D18).
+ *
+ * Measured clips sit far below it — 92 KB–2.29 MB for a sub twin, 455 KB for a
+ * 16 s main clip — so the bound bites rarely. "Rarely" is not "never": a long
+ * 4K main twin can exceed it, and above the bound the provider REFUSES with
+ * the size in the message, never truncates. Half a video is worse than an
+ * honest refusal.
+ *
+ * The clean follow-on is a CHUNKED read so a `high` twin of a long clip stops
+ * being refusable at all. That is a later slice, named here so the bound is
+ * not mistaken for a design ceiling.
+ */
+export declare const VIDEOCLIPS_MAX_READ_BYTES: number;
+/**
+ * A clip's finished bytes, inline — the twin of `recordingExport.readExportBytes`.
+ *
+ * `bytes` is the DECODED length, so nobody infers it from the base64 length,
+ * and `served` says which twin the caller actually got.
+ */
+export declare const ClipBytesSchema: z.ZodObject<{
+    base64: z.ZodString;
+    contentType: z.ZodString;
+    name: z.ZodString;
+    bytes: z.ZodNumber;
+    served: z.ZodEnum<{
+        high: "high";
+        mid: "mid";
+        low: "low";
+    }>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ClipBytes = z.infer<typeof ClipBytesSchema>;
 export declare const ClipSourceAvailabilitySchema: z.ZodObject<{
     state: z.ZodEnum<{
         ok: "ok";
@@ -259,7 +329,7 @@ export declare const videoclipsCapability: {
             since: z.ZodNumber;
             until: z.ZodNumber;
             limit: z.ZodOptional<z.ZodNumber>;
-            provider: z.ZodOptional<z.ZodString>;
+            provider: z.ZodString;
         }, z.core.$strip>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             source: z.ZodString;
@@ -358,6 +428,66 @@ export declare const videoclipsCapability: {
             playbackEndpoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
             token: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, "query">;
+        /**
+         * This clip's BYTES, base64, bounded — the by-handle read a clip EXPORT
+         * pulls once (D558).
+         *
+         * `getClipPlayback` is the right answer for a player: it hands back a URL
+         * on a plane the hub serves `access:'authenticated'`, which a browser and a
+         * viewer session satisfy. It is the wrong answer for another ADDON. There
+         * is no addon→addon byte transport in this framework — `AddonDataPlane`
+         * only lets an addon SERVE, on `127.0.0.1` behind a per-listener secret
+         * only the hub may present — so a recorder that wants a camera's clip
+         * cannot fetch that URL. This method is the one seam that exists for it,
+         * and it is deliberately the same shape (and the same bound) as
+         * `recordingExport.readExportBytes`, which exists for the mirror-image
+         * reason.
+         *
+         * Routing needs no `provider` pin: the id is source-prefixed and
+         * self-contained, so `device-collection-dispatch.ts` rule 3 hands the call
+         * to the source that claims it — and an id nobody claims is REFUSED rather
+         * than answered by another source.
+         *
+         * The producer reuses the fetch path it already has, completion rules
+         * included: a clip is taken by cmd 5 and finished on a short idle window
+         * whose result is PROVED against the catalog row's own span, retried once
+         * when it comes up materially short, and served-and-named when it is still
+         * short (D568). A second fetch with different completion rules is exactly
+         * the second authority D558 refuses to create.
+         *
+         * Every refusal THROWS with its reason and none of them is silent — the
+         * sleep gate (decided before `getApi()`, liftable only by
+         * {@link ClipWakeSchema}), a catalog row nobody claims, a clip with no
+         * bytes behind it, a mux that failed, and the size bound. The caller turns
+         * that reason into an operator-facing one; a truncated file is never an
+         * answer.
+         */
+        readonly readClipBytes: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            clipId: z.ZodString;
+            profile: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                mid: "mid";
+                low: "low";
+            }>>;
+            maxBytes: z.ZodOptional<z.ZodNumber>;
+            wake: z.ZodOptional<z.ZodEnum<{
+                authorised: "authorised";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            base64: z.ZodString;
+            contentType: z.ZodString;
+            name: z.ZodString;
+            bytes: z.ZodNumber;
+            served: z.ZodEnum<{
+                high: "high";
+                mid: "mid";
+                low: "low";
+            }>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, "query"> & {
+            readonly providerOptional: true;
+        };
     };
 };
 export type IVideoclipsProvider = InferProvider<typeof videoclipsCapability>;

package/dist/generated/addon-api.d.ts

@@ -9080,6 +9080,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof videoclipsCapability.methods.getClipPlayback.output>;
             meta: object;
         }>;
+        readClipBytes: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof videoclipsCapability.methods.readClipBytes.input>;
+            output: z.infer<typeof videoclipsCapability.methods.readClipBytes.output>;
+            meta: object;
+        }>;
     }>>;
     viewerUi: TRPCBuiltRouter<{
         ctx: TrpcContext;

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 1058 method paths across 131 capabilities.
+ * Coverage: 1059 method paths across 131 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {

package/dist/generated/method-device-selectors.d.ts

@@ -6,7 +6,7 @@
  * system-scope cap that takes a deviceId was previously never device-filtered
  * — see the generator header).
  *
- * Coverage: 390 methods carry a device reference, of which
+ * Coverage: 391 methods carry a device reference, of which
  * 141 are on SYSTEM-scope caps.
  *
  * Top-level fields, number arrays, and one-level arrays of objects carrying