@camera.ui/sdk 0.0.2 → 0.0.4

package/dist/plugin/contract.js

@@ -1,120 +1,107 @@
-import { SensorType } from '../sensor/types.js';
 /**
- * Validate a plugin contract
- *
- * @param contract - The contract to validate
- *
- * @returns Whether the contract is valid
+ * Role a plugin plays in the system. The role decides which lifecycle hooks
+ * the host invokes and which contract validations apply (see helper.ts).
  */
-export function validateContract(contract) {
-    if (!contract || typeof contract !== 'object') {
-        return false;
-    }
-    const c = contract;
-    // Required fields
-    if (!Array.isArray(c.provides))
-        return false;
-    if (!Array.isArray(c.consumes))
-        return false;
-    if (typeof c.name !== 'string' || c.name.length === 0)
-        return false;
-    // Validate sensor types
-    const validSensorTypes = Object.values(SensorType);
-    for (const type of c.provides) {
-        if (!validSensorTypes.includes(type)) {
-            return false;
-        }
-    }
-    for (const type of c.consumes) {
-        if (!validSensorTypes.includes(type)) {
-            return false;
-        }
-    }
-    // Optional fields validation
-    if (c.pythonVersion !== undefined) {
-        if (!['3.10', '3.11', '3.12'].includes(c.pythonVersion)) {
-            return false;
-        }
-    }
-    if (c.dependencies !== undefined && !Array.isArray(c.dependencies)) {
-        return false;
-    }
-    if (c.cameraController !== undefined && typeof c.cameraController !== 'boolean') {
-        return false;
-    }
-    return true;
-}
+export var PluginRole;
+(function (PluginRole) {
+    /**
+     * Cloud-service integration that manages its own cameras end-to-end via a
+     * vendor account (e.g. a vendor SDK / cloud API). The hub owns camera
+     * creation, streaming and sensors; it cannot expose sensors for cameras
+     * owned by other plugins.
+     */
+    PluginRole["Hub"] = "hub";
+    /**
+     * Adds sensors to existing cameras without owning the camera itself.
+     * Typical use: a detection plugin that consumes another plugin's video
+     * frames and emits motion / object / face detections back into the system.
+     */
+    PluginRole["SensorProvider"] = "sensorProvider";
+    /**
+     * Manages cameras and their media streams (ONVIF, RTSP, generic IP, ...).
+     * The plugin is responsible for stream URLs, PTZ, snapshots, and the
+     * lifecycle hooks in BasePlugin. It does not produce sensors for foreign
+     * cameras.
+     */
+    PluginRole["CameraController"] = "cameraController";
+    /**
+     * Combined role: plugin both manages cameras and exposes sensors (its own
+     * cameras and, when consumes is set, also foreign cameras). Used by
+     * integrations that ship a complete camera + detection stack.
+     */
+    PluginRole["CameraAndSensorProvider"] = "cameraAndSensorProvider";
+})(PluginRole || (PluginRole = {}));
 /**
- * Check if a plugin is a provider (provides any sensors)
- *
- * @param contract - The plugin contract to check
- *
- * @returns Whether the plugin is a provider
+ * Capability flags a plugin advertises in its contract. The host uses these
+ *  to decide which RPC handlers to wire up and which UI affordances to show.
  */
-export function isProvider(contract) {
-    return contract.provides.length > 0;
-}
+export var PluginInterface;
+(function (PluginInterface) {
+    /** Implements MotionDetectionInterface (video-based motion detection). */
+    PluginInterface["MotionDetection"] = "MotionDetection";
+    /** Implements ObjectDetectionInterface (e.g. person, vehicle, animal). */
+    PluginInterface["ObjectDetection"] = "ObjectDetection";
+    /** Implements AudioDetectionInterface (event/keyword audio detection). */
+    PluginInterface["AudioDetection"] = "AudioDetection";
+    /**
+     * Implements FaceDetectionInterface (face localisation + embeddings). The
+     *  NVR owns matching against enrolled faces; the plugin only emits
+     *  detections + embeddings.
+     */
+    PluginInterface["FaceDetection"] = "FaceDetection";
+    /** Implements LicensePlateDetectionInterface (plate localisation + OCR). */
+    PluginInterface["LicensePlateDetection"] = "LicensePlateDetection";
+    /**
+     * Implements ClassifierDetectionInterface (generic image classification
+     *  emitting attribute/label pairs).
+     */
+    PluginInterface["ClassifierDetection"] = "ClassifierDetection";
+    /**
+     * Implements ClipDetectionInterface (CLIP image and text embeddings used
+     *  for semantic search).
+     */
+    PluginInterface["ClipDetection"] = "ClipDetection";
+    /**
+     * Implements DiscoveryProvider — plugin can scan the network for new
+     *  cameras and adopt them. Only valid for camera-controlling roles.
+     */
+    PluginInterface["DiscoveryProvider"] = "DiscoveryProvider";
+    /**
+     * Implements NVRInterface — persists events and recordings, and serves
+     *  them back to the UI / mobile clients. Exactly one plugin per host
+     *  fills this role at runtime.
+     */
+    PluginInterface["NVR"] = "NVR";
+    /**
+     * Implements NotifierInterface (getDevices, sendNotification, ...). Lets
+     * the central NotificationManager dispatch notifications to this plugin
+     * regardless of role — see notifier.ts.
+     */
+    PluginInterface["Notifier"] = "Notifier";
+    /**
+     * Implements the OAuthCapable base interface (getOAuthMetadata,
+     * getOAuthState, disconnect) plus at least one flow sub-interface below —
+     * see oauth.ts.
+     */
+    PluginInterface["OAuthCapable"] = "OAuthCapable";
+    /** Implements OAuthDeviceFlowCapable (RFC 8628 Device Authorization Grant). */
+    PluginInterface["OAuthDeviceFlow"] = "OAuthDeviceFlow";
+    /** Implements OAuthAuthCodeFlowCapable (Authorization Code Flow + PKCE). */
+    PluginInterface["OAuthAuthCodeFlow"] = "OAuthAuthCodeFlow";
+    /** Implements OAuthClientCredentialsCapable (user-supplied client_id + client_secret). */
+    PluginInterface["OAuthClientCredentials"] = "OAuthClientCredentials";
+})(PluginInterface || (PluginInterface = {}));
 /**
- * Check if a plugin is a consumer (consumes any sensors)
- *
- * @param contract - The plugin contract to check
- *
- * @returns Whether the plugin is a consumer
+ * Permission a plugin requests so it can call a host-provided system feature.
+ * Each capability gates one outgoing SDK call — calls without the matching
+ * capability are rejected by the host.
  */
-export function isConsumer(contract) {
-    return contract.consumes.length > 0;
-}
-/**
- * Check if a plugin is a pure hub (only consumes, doesn't provide)
- *
- * @param contract - The plugin contract to check
- *
- * @returns Whether the plugin is a pure hub
- */
-export function isHub(contract) {
-    return contract.provides.length === 0 && contract.consumes.length > 0;
-}
-/**
- * Check if a plugin provides a specific sensor type
- *
- * @param contract - The plugin contract to check
- *
- * @param type - The sensor type to check
- *
- * @returns Whether the plugin provides the sensor type
- */
-export function providesSensor(contract, type) {
-    return contract.provides.includes(type);
-}
-/**
- * Check if a plugin consumes a specific sensor type
- *
- * @param contract - The plugin contract to check
- *
- * @param type - The sensor type to check
- *
- * @returns Whether the plugin consumes the sensor type
- */
-export function consumesSensor(contract, type) {
-    return contract.consumes.includes(type);
-}
-/**
- * Check if a plugin is a camera controller (can create/manage cameras)
- *
- * @param contract - The plugin contract to check
- *
- * @returns Whether the plugin is a camera controller
- */
-export function isCameraController(contract) {
-    return contract.cameraController === true;
-}
-/**
- * Check if a plugin is qualified (provides, consumes, or is camera controller)
- *
- * @param contract - The plugin contract to check
- *
- * @returns Whether the plugin is qualified
- */
-export function isQualifiedContract(contract) {
-    return contract.provides.length > 0 || contract.consumes.length > 0 || contract.cameraController === true;
-}
+export var PluginCapability;
+(function (PluginCapability) {
+    /**
+     * Grants the plugin permission to call `api.notificationManager.publish`.
+     * Without this capability the host silently drops published notifications
+     * and logs an error.
+     */
+    PluginCapability["PublishNotifications"] = "publishNotifications";
+})(PluginCapability || (PluginCapability = {}));

package/dist/plugin/helper.js

@@ -0,0 +1,277 @@
+import { PluginCapability, PluginInterface, PluginRole } from './contract.js';
+/**
+ * Check the structural validity of an unknown contract object — required
+ * fields present, enum values inside the accepted sets — and return one
+ * human-readable error per problem found. Returns an empty array when the
+ * contract is valid.
+ *
+ * @param contract - Untrusted candidate contract (e.g. from manifest JSON).
+ *
+ * @returns Error messages, empty if the contract is valid.
+ *
+ * @example
+ * ```ts
+ * import { getContractValidationErrors } from '@camera.ui/sdk';
+ *
+ * const errors = getContractValidationErrors(rawManifest);
+ * if (errors.length) throw new Error(errors.join('\n'));
+ * ```
+ */
+export function getContractValidationErrors(contract) {
+    const errors = [];
+    if (!contract || typeof contract !== 'object') {
+        errors.push('Contract must be an object. Got: ' + (contract === null ? 'null' : typeof contract));
+        return errors;
+    }
+    const c = contract;
+    const validRoles = Object.values(PluginRole);
+    // Import SensorType values dynamically to avoid circular dependency
+    const validSensorTypes = [
+        'motion',
+        'object',
+        'audio',
+        'face',
+        'licensePlate',
+        'classifier',
+        'contact',
+        'temperature',
+        'humidity',
+        'occupancy',
+        'smoke',
+        'leak',
+        'light',
+        'siren',
+        'switch',
+        'lock',
+        'garage',
+        'ptz',
+        'securitySystem',
+        'doorbell',
+        'battery',
+        'clip',
+    ];
+    // Check role
+    if (c.role === undefined) {
+        errors.push('Missing required field: "role"');
+    }
+    else if (typeof c.role !== 'string') {
+        errors.push(`Field "role" must be a string. Got: ${typeof c.role}`);
+    }
+    else if (!validRoles.includes(c.role)) {
+        errors.push(`Invalid role "${c.role}". Valid roles: ${validRoles.join(', ')}`);
+    }
+    // Check name
+    if (c.name === undefined) {
+        errors.push('Missing required field: "name"');
+    }
+    else if (typeof c.name !== 'string') {
+        errors.push(`Field "name" must be a string. Got: ${typeof c.name}`);
+    }
+    else if (c.name.length === 0) {
+        errors.push('Field "name" cannot be empty');
+    }
+    // Check provides
+    if (c.provides === undefined) {
+        errors.push('Missing required field: "provides"');
+    }
+    else if (!Array.isArray(c.provides)) {
+        errors.push(`Field "provides" must be an array. Got: ${typeof c.provides}`);
+    }
+    else {
+        for (const type of c.provides) {
+            if (!validSensorTypes.includes(type)) {
+                errors.push(`Invalid sensor type in "provides": "${type}". Valid types: ${validSensorTypes.join(', ')}`);
+            }
+        }
+    }
+    // Check consumes
+    if (c.consumes === undefined) {
+        errors.push('Missing required field: "consumes"');
+    }
+    else if (!Array.isArray(c.consumes)) {
+        errors.push(`Field "consumes" must be an array. Got: ${typeof c.consumes}`);
+    }
+    else {
+        for (const type of c.consumes) {
+            if (!validSensorTypes.includes(type)) {
+                errors.push(`Invalid sensor type in "consumes": "${type}". Valid types: ${validSensorTypes.join(', ')}`);
+            }
+        }
+    }
+    // Check interfaces
+    const validInterfaces = Object.values(PluginInterface);
+    if (c.interfaces === undefined) {
+        errors.push('Missing required field: "interfaces"');
+    }
+    else if (!Array.isArray(c.interfaces)) {
+        errors.push(`Field "interfaces" must be an array. Got: ${typeof c.interfaces}`);
+    }
+    else {
+        for (const iface of c.interfaces) {
+            if (!validInterfaces.includes(iface)) {
+                errors.push(`Invalid interface in "interfaces": "${iface}". Valid interfaces: ${validInterfaces.join(', ')}`);
+            }
+        }
+    }
+    // Check optional capabilities
+    const validCapabilities = Object.values(PluginCapability);
+    if (c.capabilities !== undefined) {
+        if (!Array.isArray(c.capabilities)) {
+            errors.push(`Field "capabilities" must be an array. Got: ${typeof c.capabilities}`);
+        }
+        else {
+            for (const cap of c.capabilities) {
+                if (!validCapabilities.includes(cap)) {
+                    errors.push(`Invalid capability in "capabilities": "${cap}". Valid capabilities: ${validCapabilities.join(', ')}`);
+                }
+            }
+        }
+    }
+    // Check optional pythonVersion
+    if (c.pythonVersion !== undefined) {
+        if (!['3.11', '3.12'].includes(c.pythonVersion)) {
+            errors.push(`Invalid pythonVersion "${c.pythonVersion}". Valid versions: 3.11, 3.12`);
+        }
+    }
+    // Check optional dependencies
+    if (c.dependencies !== undefined && !Array.isArray(c.dependencies)) {
+        errors.push(`Field "dependencies" must be an array. Got: ${typeof c.dependencies}`);
+    }
+    return errors;
+}
+/**
+ * Enforce role-specific consistency rules on top of the structural check
+ * (e.g. SensorProvider plugins must declare at least one provided sensor;
+ * Hub plugins cannot expose sensors). Throws on the first violation.
+ *
+ * @param contract - Already-structurally-valid contract.
+ *
+ * @param pluginName - Optional plugin name; used to prefix error messages.
+ *
+ * @throws {Error} When the contract violates a role-specific rule.
+ *
+ * @example
+ * ```ts
+ * import { validateContractConsistency } from '@camera.ui/sdk';
+ *
+ * validateContractConsistency(contract, 'my-plugin');
+ * ```
+ */
+export function validateContractConsistency(contract, pluginName) {
+    const prefix = pluginName ? `Plugin "${pluginName}": ` : '';
+    switch (contract.role) {
+        case PluginRole.Hub:
+            if (contract.provides.length > 0) {
+                throw new Error(`${prefix}Hub plugins cannot provide sensors.`);
+            }
+            break;
+        case PluginRole.SensorProvider:
+            if (contract.provides.length === 0) {
+                throw new Error(`${prefix}SensorProvider plugins must provide at least one sensor type.`);
+            }
+            break;
+        case PluginRole.CameraAndSensorProvider:
+            if (contract.provides.length === 0) {
+                throw new Error(`${prefix}CameraAndSensorProvider plugins must provide at least one sensor type.`);
+            }
+            break;
+        case PluginRole.CameraController:
+            // CameraController can have empty or filled provides array
+            // (sensors are only for its own cameras)
+            break;
+    }
+}
+/**
+ * Reports whether the plugin's role is Hub (vendor cloud integration that
+ * manages its own cameras end-to-end).
+ *
+ * @param contract - Plugin contract to inspect.
+ *
+ * @returns `true` if the role is {@link PluginRole.Hub}.
+ *
+ * @example
+ * ```ts
+ * import { isHub } from '@camera.ui/sdk';
+ *
+ * if (isHub(contract)) skipLocalDiscovery();
+ * ```
+ */
+export function isHub(contract) {
+    return contract.role === PluginRole.Hub;
+}
+/**
+ * Reports whether the plugin is allowed to add sensors to cameras owned by
+ * other plugins (true for SensorProvider and CameraAndSensorProvider).
+ * Hub and pure CameraController plugins only see their own cameras.
+ *
+ * @param contract - Plugin contract to inspect.
+ *
+ * @returns `true` if the plugin may attach sensors to any camera.
+ *
+ * @example
+ * ```ts
+ * import { canProvideSensorsToAnyCameras } from '@camera.ui/sdk';
+ *
+ * if (canProvideSensorsToAnyCameras(contract)) listAllCameras();
+ * ```
+ */
+export function canProvideSensorsToAnyCameras(contract) {
+    return contract.role === PluginRole.SensorProvider || contract.role === PluginRole.CameraAndSensorProvider;
+}
+/**
+ * Reports whether the plugin can create cameras (role is CameraController
+ * or CameraAndSensorProvider). Used to gate camera-creating operations such
+ * as DiscoveryProvider adoption.
+ *
+ * @param contract - Plugin contract to inspect.
+ *
+ * @returns `true` if the plugin may create cameras.
+ *
+ * @example
+ * ```ts
+ * import { canCreateCameras } from '@camera.ui/sdk';
+ *
+ * if (canCreateCameras(contract)) enableAdoption();
+ * ```
+ */
+export function canCreateCameras(contract) {
+    return contract.role === PluginRole.CameraController || contract.role === PluginRole.CameraAndSensorProvider;
+}
+/**
+ * Reports whether the plugin implements the given capability.
+ *
+ * @param contract - Plugin contract to inspect.
+ *
+ * @param iface - Interface to check (e.g. `PluginInterface.DiscoveryProvider`).
+ *
+ * @returns `true` if `iface` is listed in the contract's `interfaces`.
+ *
+ * @example
+ * ```ts
+ * import { hasInterface, PluginInterface } from '@camera.ui/sdk';
+ *
+ * if (hasInterface(contract, PluginInterface.DiscoveryProvider)) startScan();
+ * ```
+ */
+export function hasInterface(contract, iface) {
+    return contract.interfaces.includes(iface);
+}
+/**
+ * Reports whether the plugin requested the given capability.
+ *
+ * @param contract - Plugin contract to inspect.
+ *
+ * @param cap - Capability to check (e.g. `PluginCapability.PublishNotifications`).
+ *
+ * @returns `true` if `cap` is listed in the contract's `capabilities`.
+ *
+ * @example
+ * ```ts
+ * import { hasCapability, PluginCapability } from '@camera.ui/sdk';
+ *
+ * if (hasCapability(contract, PluginCapability.PublishNotifications)) allowPublish();
+ * ```
+ */
+export function hasCapability(contract, cap) {
+    return contract.capabilities?.includes(cap) ?? false;
+}

package/dist/plugin/index.js

@@ -1,3 +1,6 @@
+export * from './api.js';
 export * from './contract.js';
+export * from './helper.js';
 export * from './interfaces.js';
-export * from './types.js';
+export * from './notifier.js';
+export * from './oauth.js';

package/dist/plugin/interfaces.js

@@ -1 +1,51 @@
-export {};
+/**
+ * Base class every plugin extends. It wires up the three dependencies the
+ * host injects (logger, PluginAPI, DeviceStorage) and declares the lifecycle
+ * methods the host calls on the plugin.
+ *
+ * Lifecycle order: the host calls `configureCameras()` once at startup with
+ * every camera already assigned to this plugin, then calls `onCameraAdded()`
+ * / `onCameraReleased()` as the user adds or removes cameras at runtime.
+ *
+ * The generic `T` types `storage.values` so plugin code gets autocompletion
+ * for its own settings shape.
+ *
+ * @example
+ * ```typescript
+ * export default class MyPlugin extends BasePlugin<MyStorage> {
+ *   private state = new Map<string, MyState>();
+ *
+ *   async configureCameras(cameras: CameraDevice[]): Promise<void> {
+ *     for (const camera of cameras) await this.onCameraAdded(camera);
+ *   }
+ *
+ *   async onCameraAdded(camera: CameraDevice): Promise<void> {
+ *     this.state.set(camera.id, await this.attach(camera));
+ *   }
+ *
+ *   async onCameraReleased(cameraId: string): Promise<void> {
+ *     this.state.get(cameraId)?.dispose();
+ *     this.state.delete(cameraId);
+ *   }
+ * }
+ * ```
+ *
+ * @see /examples/getting-started — end-to-end walkthrough.
+ */
+export class BasePlugin {
+    logger;
+    api;
+    storage;
+    constructor(logger, api, storage) {
+        this.logger = logger;
+        this.api = api;
+        this.storage = storage;
+    }
+    /**
+     * Override to register a JSON schema for the plugin-level settings form
+     *  rendered in the UI. Default: no schema.
+     */
+    get storageSchema() {
+        return [];
+    }
+}

package/dist/plugin/notifier.js

@@ -0,0 +1,23 @@
+/**
+ * Generic notification types — domain-agnostic. The NotificationManager and
+ * notifier plugins talk over RPC and JSON-encode these types directly.
+ */
+/**
+ * Severity classifies how urgent a Notification is. Notifiers map this to
+ * platform-specific delivery characteristics; the host bypasses user-configured
+ * Quiet Hours for `critical`.
+ */
+export var Severity;
+(function (Severity) {
+    /** Standard notification — default delivery (sound + banner). */
+    Severity["Info"] = "info";
+    /** Heightened attention; notifiers may use a different sound/colour. */
+    Severity["Warn"] = "warn";
+    /** Failure or action-required notification. */
+    Severity["Error"] = "error";
+    /**
+     * Highest-priority delivery on supporting notifiers; bypasses user-configured
+     * Quiet Hours on the host.
+     */
+    Severity["Critical"] = "critical";
+})(Severity || (Severity = {}));

package/dist/plugin/oauth.js

@@ -0,0 +1 @@
+export {};