@camstack/types 1.2.427 → 1.2.429

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this package are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.2.429] - 2026-10-27
+
+### Added
+
+- pet-feeder reports bowlFood, eating and supportsMarkRefilled
+
+## [1.2.428] - 2026-10-27
+
+### Added
+
+- The published package now includes its README and CHANGELOG.
+- Cloud integrations raise one alert when their session is lost and clear it when it is back
+
+## [1.2.427] - 2026-10-27
+
+### Added
+
+- CamStack Types: Shared types, interfaces, and model catalogs for the CamStack detection ecosystem.

package/README.md

@@ -0,0 +1,19 @@
+# CamStack Types
+
+Shared types, interfaces, and model catalogs for the CamStack detection ecosystem.
+
+<!-- readme:generated:start (derived from the manifest; edit outside this block) -->
+
+Package `@camstack/types` on npm.
+
+## Documentation
+
+- [docs/architecture/notifications.md](https://github.com/camstack/server/blob/main/docs/architecture/notifications.md)
+- [docs/architecture/capabilities.md](https://github.com/camstack/server/blob/main/docs/architecture/capabilities.md)
+- [docs/architecture/detection-execution.md](https://github.com/camstack/server/blob/main/docs/architecture/detection-execution.md)
+- [docs/architecture/ffmpeg.md](https://github.com/camstack/server/blob/main/docs/architecture/ffmpeg.md)
+- [packages/types/AGENTS.md](https://github.com/camstack/server/blob/main/packages/types/AGENTS.md)
+
+See [CHANGELOG.md](./CHANGELOG.md) for what changed in each version.
+
+<!-- readme:generated:end -->

package/dist/addon/session-health.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Session health — the STANDARD "cloud connection lost" alert (D-session-health).
+ *
+ * Every addon that keeps a cloud session for an integration (an account login, a
+ * refresh token, a long-lived socket) reports two facts and nothing else:
+ *
+ *   - `lost(integrationId, …)`  the session was refused / kicked / dropped;
+ *   - `restored(integrationId)` a call went through again.
+ *
+ * The tracker owns everything between: a debounce (a transient reconnect never
+ * alerts), ONE alert per integration instance (never one per device, never one
+ * per failed poll), the wording (provider, integration, reason), an action the
+ * operator can follow, and the automatic resolve when the session is back.
+ *
+ * Alerts are durable state that the next run of the addon cannot see, so the
+ * first `restored()` of a process resolves whatever a previous run left active.
+ */
+import type { Alert, AlertSeverity } from '../capabilities/alerts.cap.js';
+import type { IScopedLogger } from '../interfaces/logging.js';
+/** Why the session ended. `kicked` = the same account signed in elsewhere. */
+export type SessionLossReason = 'kicked' | 'auth-rejected' | 'token-expired' | 'connection-lost';
+/** What an alert's action looks like (the `Alert.action` shape). */
+export interface SessionAlertAction {
+    readonly label: string;
+    readonly href?: string;
+    readonly navigation?: 'app' | 'server';
+}
+/** The slice of `ctx.api.alerts` the tracker needs. Structural, so `ctx.api.alerts` fits. */
+export interface SessionHealthAlertsPort {
+    readonly emit?: {
+        mutate(alert: Alert): Promise<unknown>;
+    };
+    readonly update?: {
+        mutate(input: {
+            readonly alertId: string;
+            readonly patch: Partial<Alert>;
+        }): Promise<unknown>;
+    };
+}
+export declare const SESSION_LOST_ALERT_CATEGORY = "integration.session-lost";
+/** A transient reconnect is quiet for this long before it is worth an alert. */
+export declare const DEFAULT_SESSION_LOST_DEBOUNCE_MS: number;
+export declare function sessionLostAlertId(kind: string, integrationId: string): string;
+export interface BuildSessionLostAlertInput {
+    /** Stable provider key, e.g. `petkit` — part of the alert id and source. */
+    readonly kind: string;
+    /** Display name, e.g. `PetKit`. */
+    readonly providerName: string;
+    readonly integrationId: string;
+    readonly integrationName: string;
+    readonly reason: SessionLossReason;
+    /** Defaults to "Open integration" (the admin integration page). */
+    readonly action?: SessionAlertAction;
+    readonly severity?: AlertSeverity;
+    readonly now?: number;
+}
+/** Pure builder, exported so an addon with its own flow can still emit the standard shape. */
+export declare function buildSessionLostAlert(input: BuildSessionLostAlertInput): Alert;
+export interface SessionHealthTrackerOptions {
+    readonly kind: string;
+    readonly providerName: string;
+    readonly logger: IScopedLogger;
+    /** Read lazily: `ctx.api.alerts` may be absent early in boot. */
+    readonly getAlerts: () => SessionHealthAlertsPort | undefined;
+    readonly debounceMs?: number;
+}
+export interface SessionLostInfo {
+    readonly integrationName: string;
+    readonly reason: SessionLossReason;
+    /** Re-auth route when the addon has one; otherwise "Open integration". */
+    readonly action?: SessionAlertAction;
+}
+export declare class SessionHealthTracker {
+    #private;
+    constructor(opts: SessionHealthTrackerOptions);
+    /** The session is gone. Idempotent: call it on every failed poll. */
+    lost(integrationId: string, info: SessionLostInfo): void;
+    /** A call went through. Idempotent: call it on every successful poll. */
+    restored(integrationId: string): Promise<void>;
+    /** The integration is gone (deleted / disabled): drop its state and its alert. */
+    forget(integrationId: string): Promise<void>;
+    /** Stop every pending timer (addon shutdown). */
+    dispose(): void;
+}
+export interface IntegrationSessionBinding {
+    readonly logger: IScopedLogger;
+    readonly getAlerts: () => SessionHealthAlertsPort | undefined;
+    readonly debounceMs?: number;
+}
+export interface IntegrationSessionReporterOptions {
+    readonly kind: string;
+    readonly providerName: string;
+    /**
+     * Is `err` the cloud ending OUR session (kicked, token refused, sign-in
+     * rejected)? `null` for anything else — a network blip or a per-device error
+     * must never read as a lost session.
+     */
+    readonly classify: (err: unknown) => SessionLossReason | null;
+    /** Re-auth route when the addon has one; otherwise "Open integration". */
+    readonly action?: (integrationId: string) => SessionAlertAction | undefined;
+}
+/**
+ * The addon-facing face of {@link SessionHealthTracker}: a process-wide object an
+ * integration manager AND its device classes can reach (the kernel builds a
+ * device from a `DeviceContext` alone, so neither can be handed a tracker).
+ * The addon `bind()`s it in `onInitialize`, `unbind()`s it on shutdown and
+ * `forget()`s an integration that vanished; everything before `bind` is a no-op.
+ */
+export declare class IntegrationSessionReporter {
+    #private;
+    constructor(opts: IntegrationSessionReporterOptions);
+    bind(binding: IntegrationSessionBinding): void;
+    unbind(): void;
+    /** The manager tells us the display name once, so a device can report by id alone. */
+    register(integrationId: string, integrationName: string): void;
+    /** A call failed. Only a session-ending failure counts; anything else is ignored. */
+    failure(integrationId: string, err: unknown): void;
+    /** A call went through. */
+    ok(integrationId: string): Promise<void>;
+    /** The integration was removed. */
+    forget(integrationId: string): Promise<void>;
+}
+/** What a manager / device depends on to report. */
+export type IntegrationSessionSink = Pick<IntegrationSessionReporter, 'register' | 'failure' | 'ok'>;

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-edKiOXLo.js");
+const require_sleep = require("./sleep-hRhTSDlN.js");
 const require_event_category = require("./event-category-Ave2VSxY.js");
 const require_err_msg = require("./err-msg-U7lLUMNz.js");
 //#region src/generated/cap-input-defaults.ts

package/dist/addon.mjs

@@ -1,4 +1,4 @@
-import { $ as expandCapMethods, $n as REVALIDATE_AFTER_MS, $r as isSecretMarker, $t as RecordFieldPathSchema, A as HF_REPO, An as RecordUniqueViolationError, Ar as buildSecretRef, B as withoutCallerStamp, Bn as RECORD_CLASSES, C as addonSliceHandleApi, Cn as InvalidRecordError, Dn as RecordNotFoundError, En as RECORDS_ERROR_CODES, Fn as UnknownRecordKindError, Fr as parseSecretRef, G as adminUiCapability, Gn as RECORD_MAX_DATA_BYTES, Hn as RECORD_DEFAULT_MAX_DATA_BYTES, I as deviceOpsCapability, In as asRecordsError, Jn as RECORD_QUERY_MAX, Jt as defineEntryKind, Kn as RECORD_MAX_INDEXES, L as viewerUiCapability, Ln as recordsErrorFromMessage, M as CAP_ADVANCE_FIELDS, Mn as RevConflictError, Mr as globalSecretScope, Nn as TransactRefusedError, Nr as isSecretRef, On as RecordSecretUnavailableError, Or as SECRET_REF_SCHEME, P as CAP_STATE_LEAVES, Pn as UnindexedFilterError, Pr as normalizeSecretOwner, Qn as resolveSecretViewsIn, Qr as isSecretFieldView, Qt as EntryDescriptorSchema, R as DEVICE_CHILDREN_BATCH_MAX, Rn as RECORD_BATCH_MAX, Rr as createEvent, Sn as ForeignSecretMarkerError, Tn as PlaintextSecretError, U as describeCustomActions, Un as RECORD_DELETE_BATCH, Vn as RECORD_DATABASES, Wn as RECORD_ID_MAX_LENGTH, Xn as RECORD_SETTINGS_MAX_ROWS, Xr as classifySecretWrite, Xt as createRecordsAccess, Yn as RECORD_SECRET_COLLECTION_PREFIX, Yr as SECRET_CLEAR, Yt as entryBody, Zn as RECORD_SWEEP_INTERVAL_MS, Zr as isSecretClear, Zt as assertTransactScope, _ as readErrorI18n, _n as collectZodSecretPaths, an as assertValidDeclaration, ar as registerKnownSecret, b as isDeviceScopedCap, bn as DeclarationRefusedError, c as asString, cn as REMOVE_LEAF, cr as PEER_BYTES_CHUNK_BYTES, ct as readNodePin, d as parseJsonUnknown, dn as parseSecretPath, dr as PEER_BYTES_TICKET_TTL_MS, dt as ReadinessRegistry, ei as isSecretMarkerLike, en as RecordIndexSchema, er as createSecretsAccess, f as hfModelUrl, fn as recordArrayItemPath, ft as ReadinessTimeoutError, g as ErrorI18nPayloadSchema, gr as BaseAddon, hn as secretArrayPrefixes, hr as DisposerChain, ht as scopeKey, in as StoredRecordKindDeclarationSchema, ir as knownSecretCount, jn as RecordsError, jr as formatSecretScope, kn as RecordTooLargeError, kr as arrayItemFieldPath, ln as collectSecretLeaves, lr as PEER_BYTES_MAX_OUTSTANDING, mn as recordSecretRef, ni as toSecretFieldView, nn as RecordKindNameSchema, nr as clearKnownSecrets, o as asJsonObject, on as declarationsOf, or as scrubKnownSecrets, p as BOOT_RECOVERY_BACKOFF_MS, pn as recordSecretCollection, pr as DATAPLANE_SECRET_HEADER, qn as RECORD_MAX_INDEX_FIELDS, qt as makeInMemoryRecords, r as maskUrlCredentials, rn as RecordRetentionSchema, rr as forgetKnownSecret, sn as defineRecordKinds, sr as shortSecretRefHash, st as nodePin, t as sleep, ti as makeSecretMarker, tn as RecordKindDeclarationSchema, tr as MIN_SCRUBBED_LENGTH, un as mapSecretLeaves, ur as PEER_BYTES_STALL_MS, ut as MODEL_FORMATS, vn as isZodSecret, vr as normalizeAddonInitResult, w as createEventBusSliceSource, wn as NoCallerError, x as createDeviceProxy, xn as FilterRequiredError, y as DEVICE_SCOPED_CAPS, yn as BatchTooLargeError, z as CALLER_STAMPED_CAPABILITIES, zn as RECORD_BATCH_MAX_BYTES, zr as emitReadiness } from "./sleep--jXS9hWo.mjs";
+import { $ as expandCapMethods, $n as REVALIDATE_AFTER_MS, $r as isSecretMarker, $t as RecordFieldPathSchema, A as HF_REPO, An as RecordUniqueViolationError, Ar as buildSecretRef, B as withoutCallerStamp, Bn as RECORD_CLASSES, C as addonSliceHandleApi, Cn as InvalidRecordError, Dn as RecordNotFoundError, En as RECORDS_ERROR_CODES, Fn as UnknownRecordKindError, Fr as parseSecretRef, G as adminUiCapability, Gn as RECORD_MAX_DATA_BYTES, Hn as RECORD_DEFAULT_MAX_DATA_BYTES, I as deviceOpsCapability, In as asRecordsError, Jn as RECORD_QUERY_MAX, Jt as defineEntryKind, Kn as RECORD_MAX_INDEXES, L as viewerUiCapability, Ln as recordsErrorFromMessage, M as CAP_ADVANCE_FIELDS, Mn as RevConflictError, Mr as globalSecretScope, Nn as TransactRefusedError, Nr as isSecretRef, On as RecordSecretUnavailableError, Or as SECRET_REF_SCHEME, P as CAP_STATE_LEAVES, Pn as UnindexedFilterError, Pr as normalizeSecretOwner, Qn as resolveSecretViewsIn, Qr as isSecretFieldView, Qt as EntryDescriptorSchema, R as DEVICE_CHILDREN_BATCH_MAX, Rn as RECORD_BATCH_MAX, Rr as createEvent, Sn as ForeignSecretMarkerError, Tn as PlaintextSecretError, U as describeCustomActions, Un as RECORD_DELETE_BATCH, Vn as RECORD_DATABASES, Wn as RECORD_ID_MAX_LENGTH, Xn as RECORD_SETTINGS_MAX_ROWS, Xr as classifySecretWrite, Xt as createRecordsAccess, Yn as RECORD_SECRET_COLLECTION_PREFIX, Yr as SECRET_CLEAR, Yt as entryBody, Zn as RECORD_SWEEP_INTERVAL_MS, Zr as isSecretClear, Zt as assertTransactScope, _ as readErrorI18n, _n as collectZodSecretPaths, an as assertValidDeclaration, ar as registerKnownSecret, b as isDeviceScopedCap, bn as DeclarationRefusedError, c as asString, cn as REMOVE_LEAF, cr as PEER_BYTES_CHUNK_BYTES, ct as readNodePin, d as parseJsonUnknown, dn as parseSecretPath, dr as PEER_BYTES_TICKET_TTL_MS, dt as ReadinessRegistry, ei as isSecretMarkerLike, en as RecordIndexSchema, er as createSecretsAccess, f as hfModelUrl, fn as recordArrayItemPath, ft as ReadinessTimeoutError, g as ErrorI18nPayloadSchema, gr as BaseAddon, hn as secretArrayPrefixes, hr as DisposerChain, ht as scopeKey, in as StoredRecordKindDeclarationSchema, ir as knownSecretCount, jn as RecordsError, jr as formatSecretScope, kn as RecordTooLargeError, kr as arrayItemFieldPath, ln as collectSecretLeaves, lr as PEER_BYTES_MAX_OUTSTANDING, mn as recordSecretRef, ni as toSecretFieldView, nn as RecordKindNameSchema, nr as clearKnownSecrets, o as asJsonObject, on as declarationsOf, or as scrubKnownSecrets, p as BOOT_RECOVERY_BACKOFF_MS, pn as recordSecretCollection, pr as DATAPLANE_SECRET_HEADER, qn as RECORD_MAX_INDEX_FIELDS, qt as makeInMemoryRecords, r as maskUrlCredentials, rn as RecordRetentionSchema, rr as forgetKnownSecret, sn as defineRecordKinds, sr as shortSecretRefHash, st as nodePin, t as sleep, ti as makeSecretMarker, tn as RecordKindDeclarationSchema, tr as MIN_SCRUBBED_LENGTH, un as mapSecretLeaves, ur as PEER_BYTES_STALL_MS, ut as MODEL_FORMATS, vn as isZodSecret, vr as normalizeAddonInitResult, w as createEventBusSliceSource, wn as NoCallerError, x as createDeviceProxy, xn as FilterRequiredError, y as DEVICE_SCOPED_CAPS, yn as BatchTooLargeError, z as CALLER_STAMPED_CAPABILITIES, zn as RECORD_BATCH_MAX_BYTES, zr as emitReadiness } from "./sleep-BE7IAR2p.mjs";
 import { t as EventCategory } from "./event-category-CT-hz5Rb.mjs";
 import { a as DeviceType, t as errMsg } from "./err-msg-DIorGYeC.mjs";
 //#region src/generated/cap-input-defaults.ts

package/dist/capabilities/network-access.cap.d.ts

@@ -38,7 +38,7 @@ export type NetworkEndpoint = z.infer<typeof NetworkEndpointSchema>;
 export type NetworkTunnelStartedData = z.infer<typeof NetworkTunnelStartedDataSchema>;
 /**
  * Optional, richer endpoint shape returned by providers that expose
- * MORE than one ingress concurrently (Tailscale Ingress with mixed
+ * MORE than one ingress concurrently (Tailscale Funnel with mixed
  * serve+funnel rules, future ngrok multi-tunnel, …). Each entry carries
  * the originating provider config (mode + sourcePort) so the
  * orchestrator UI can label rows distinctly. Providers that expose only

package/dist/capabilities/pet-feeder.cap.d.ts

@@ -46,6 +46,9 @@ export declare const PetFeederDeviceStatusSchema: z.ZodEnum<{
 export type PetFeederDeviceStatus = z.infer<typeof PetFeederDeviceStatusSchema>;
 export declare const PetFeederStatusSchema: z.ZodObject<{
     foodLevel: z.ZodNullable<z.ZodNumber>;
+    bowlFood: z.ZodNullable<z.ZodNumber>;
+    eating: z.ZodBoolean;
+    supportsMarkRefilled: z.ZodBoolean;
     food1: z.ZodNullable<z.ZodNumber>;
     food2: z.ZodNullable<z.ZodNumber>;
     lowFood: z.ZodBoolean;
@@ -95,7 +98,9 @@ export declare const petFeederCapability: {
         readonly resetDesiccant: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
-        /** Mark a hopper as refilled (D4H/D4S/D4SH). */
+        /** Tell the PetKit cloud a hopper was refilled so it stops its low-food
+         *  reminders (D4H/D4S/D4SH only — see `supportsMarkRefilled`). It does not
+         *  change any sensor reading. */
         readonly markFoodReplenished: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
@@ -132,6 +137,9 @@ export declare const petFeederCapability: {
     readonly status: {
         readonly schema: z.ZodObject<{
             foodLevel: z.ZodNullable<z.ZodNumber>;
+            bowlFood: z.ZodNullable<z.ZodNumber>;
+            eating: z.ZodBoolean;
+            supportsMarkRefilled: z.ZodBoolean;
             food1: z.ZodNullable<z.ZodNumber>;
             food2: z.ZodNullable<z.ZodNumber>;
             lowFood: z.ZodBoolean;
@@ -161,6 +169,9 @@ export declare const petFeederCapability: {
      */
     readonly runtimeState: z.ZodObject<{
         foodLevel: z.ZodNullable<z.ZodNumber>;
+        bowlFood: z.ZodNullable<z.ZodNumber>;
+        eating: z.ZodBoolean;
+        supportsMarkRefilled: z.ZodBoolean;
         food1: z.ZodNullable<z.ZodNumber>;
         food2: z.ZodNullable<z.ZodNumber>;
         lowFood: z.ZodBoolean;
@@ -196,6 +207,9 @@ export declare const petFeederCapability: {
             readonly foodLevel: {
                 readonly kind: 'gauge';
             };
+            readonly bowlFood: {
+                readonly kind: 'gauge';
+            };
             readonly food1: {
                 readonly kind: 'gauge';
             };

package/dist/generated/addon-cap-facts.d.ts

@@ -5,7 +5,7 @@
  * `ALL_CAPABILITY_DEFINITIONS` (the whole Zod schema graph, ~+100 MB heap per
  * runner). See docs/decisions/adr-0028.md.
  *
- * Coverage: 1 advance-derived caps, 77 caps with 353 state leaves.
+ * Coverage: 1 advance-derived caps, 77 caps with 356 state leaves.
  */
 /** A bindable scalar in a capability's runtime state. */
 export interface CapStateLeaf {

package/dist/generated/history-catalog.d.ts

@@ -1,7 +1,7 @@
 import type { CapabilityHistoryField, CapabilityHistoryItems } from '../capabilities/capability-definition.js';
 /**
  * Cap history catalog, projected from every `*.cap.ts` `history` block.
- * 42 caps with series (76 series), 33 caps answered `'none'`.
+ * 42 caps with series (77 series), 33 caps answered `'none'`.
  * Field keys are `runtimeState` paths (`a.b` into fixed objects only).
  */
 export declare const HISTORY_CATALOG: Readonly<Record<string, Readonly<Record<string, CapabilityHistoryField>>>>;

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { BaseAddon, classifyStoreError, normalizeAddonInitResult } from './addon
 export { normalizeNodeId } from './addon/per-node-store.js';
 export type { AddonRouteInvokeRequest, AddonRouteReplyEnvelope, } from './addon/build-addon-route-provider.js';
 export { buildAddonRouteProvider } from './addon/build-addon-route-provider.js';
+export type { BuildSessionLostAlertInput, IntegrationSessionBinding, IntegrationSessionReporterOptions, IntegrationSessionSink, SessionAlertAction, SessionHealthAlertsPort, SessionHealthTrackerOptions, SessionLossReason, SessionLostInfo, } from './addon/session-health.js';
+export { buildSessionLostAlert, DEFAULT_SESSION_LOST_DEBOUNCE_MS, IntegrationSessionReporter, SESSION_LOST_ALERT_CATEGORY, SessionHealthTracker, sessionLostAlertId, } from './addon/session-health.js';
 export type { DurableState, DurableStateDeps } from './addon/durable-state.js';
 export { createDurableState } from './addon/durable-state.js';
 export type { IAuthProvider } from './capabilities/auth-provider.cap.js';