doover-js 0.11.0 → 0.13.0

package/dist/esm/types/batch.js

@@ -0,0 +1,42 @@
+/**
+ * Shared types for the bounded batch mutation endpoints.
+ *
+ * The data API exposes cross-agent batch mutations at `/agents/aggregates`
+ * and `/agents/messages`. Every item carries its own `agent_id` and
+ * `channel_name`, each is authorised independently, and the batch can
+ * partially succeed — results come back in request order and callers should
+ * retry only the failed entries.
+ *
+ * See `docs/batch-aggregate-updates.md` in channels-rest for the contract.
+ */
+/**
+ * Server-enforced ceiling on items per batch request. Exceeding it is a 400,
+ * so callers must chunk. `chunkBatchItems` does this for you.
+ */
+export const MAX_BATCH_ITEMS = 50;
+/**
+ * Split `items` into server-acceptable chunks. Returns `[]` for an empty
+ * input, since an empty batch is a 400 rather than a no-op.
+ */
+export function chunkBatchItems(items, size = MAX_BATCH_ITEMS) {
+    if (size < 1)
+        throw new RangeError("chunk size must be at least 1");
+    const out = [];
+    for (let i = 0; i < items.length; i += size) {
+        out.push(items.slice(i, i + size));
+    }
+    return out;
+}
+/**
+ * Merge several batch responses into one, as if the whole set had been sent
+ * in a single request. Useful after chunking.
+ */
+export function mergeBatchResponses(responses) {
+    const items = responses.flatMap((r) => r.items);
+    return {
+        items,
+        count: items.length,
+        succeeded: items.filter((i) => i.success).length,
+        failed: items.filter((i) => !i.success).length,
+    };
+}

package/dist/esm/types/common.d.ts

@@ -0,0 +1,250 @@
+import type { SourceProvenance } from "./provenance.js";
+export type JSONPrimitive = null | boolean | number | string;
+export type JSONValue = JSONPrimitive | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+export interface Attachment {
+    url: string;
+    content_type: string | null;
+    filename: string;
+    size: number;
+}
+export interface ChannelRef {
+    agent_id: string;
+    name: string;
+}
+export interface Aggregate<TData = Record<string, JSONValue>> {
+    data: TData;
+    attachments: Attachment[];
+    last_updated?: number | null;
+    __source?: SourceProvenance;
+}
+export interface MessageAttachment extends Attachment {
+}
+export interface MessageStructure<TData = JSONValue> {
+    data: TData;
+    attachments: MessageAttachment[];
+    id: string;
+    author_id: string;
+    channel: ChannelRef;
+    timestamp: number;
+    record_log?: boolean;
+    __source?: SourceProvenance;
+}
+export interface Channel<TAgg = Record<string, JSONValue>> {
+    aggregate?: Aggregate<TAgg>;
+    is_private: boolean;
+    id?: string;
+    name: string;
+    owner_id: string;
+    alarms_enabled?: boolean;
+    aggregate_schema?: Record<string, JSONValue> | null;
+    message_schema?: Record<string, JSONValue> | null;
+    daily_message_summaries?: unknown[];
+    alarms?: Alarm[];
+    __source?: SourceProvenance;
+}
+export interface Alarm {
+    id: string;
+    name: string;
+    description: string;
+    /** Channel the alarm lives on — set on every alarm the REST API returns. */
+    channel_name?: string;
+    topic_name?: string;
+    notification_policy?: "default" | "opt-in";
+    enabled: boolean;
+    key: string;
+    operator: AlarmOperator;
+    value: JSONValue;
+    state: AlarmState;
+    expiry_mins: number | null;
+    entered_state_ts: number;
+    alarm_pending_ms: number | null;
+    rate_threshold?: number | null;
+    rate_window_ms?: number | null;
+    rate_baseline_value?: number | null;
+    rate_baseline_ts?: number | null;
+    messages?: AlarmMessages | null;
+    __source?: SourceProvenance;
+}
+/**
+ * Per-transition notification override. `notify` and `text` are independent:
+ * turning notifications off keeps whatever wording was set, and `text: null`
+ * means "use the auto-generated message".
+ */
+export interface AlarmStateMessage {
+    notify?: boolean;
+    text?: string | null;
+}
+/** Notification overrides keyed by the state being entered. */
+export interface AlarmMessages {
+    alarm?: AlarmStateMessage;
+    ok?: AlarmStateMessage;
+    pending?: AlarmStateMessage;
+    no_data?: AlarmStateMessage;
+}
+export type AlarmOperator = "eq" | "ge" | "gt" | "le" | "lt";
+export type AlarmState = "NoData" | "OK" | "Alarm" | "AlarmPending";
+export interface ConnectionSubscription {
+    channel: ChannelRef;
+    subscribed_at: number;
+    connection_id: string;
+    __source?: SourceProvenance;
+}
+export interface ConnectionSubscriptionLog {
+    channel: ChannelRef;
+    subscribed_at?: number | null;
+    unsubscribed_at?: number | null;
+    connection_id: string;
+    __source?: SourceProvenance;
+}
+export interface ConnectionDetails {
+    address: string;
+    agent_id: string;
+    default_session: boolean;
+    session_id: string;
+    last_ping?: number | null;
+    latency?: number | null;
+    status: number;
+    subscriptions: ConnectionSubscription[];
+    __source?: SourceProvenance;
+}
+/**
+ * How a subscription's `topic_filter` entries are matched. `exact` is literal
+ * (and the server's default when the field is absent); `regex` matches each
+ * expression against the whole canonical topic. Entries are ORed either way.
+ */
+export type NotificationTopicFilterMode = "exact" | "regex";
+export interface NotificationSubscriptionEndpoint {
+    id: string;
+    name: string;
+    default: boolean;
+}
+export interface NotificationSubscription {
+    id: string;
+    subscriber: string;
+    subscribed_to: string;
+    severity: number;
+    topic_filter: string[];
+    topic_filter_mode: NotificationTopicFilterMode;
+    endpoints: NotificationSubscriptionEndpoint[];
+    __source?: SourceProvenance;
+}
+export interface NotificationEndpoint {
+    id: string;
+    agent_id: string;
+    type: number;
+    priority: number | null;
+    extra_data: Record<string, JSONValue>;
+    name: string;
+    default: boolean;
+    __source?: SourceProvenance;
+}
+/**
+ * Delivery readiness for an endpoint, without its destination address or
+ * `extra_data` — the one endpoint listing a delegated subscription manager is
+ * allowed to see.
+ */
+export interface NotificationEndpointSummary {
+    id: string;
+    type: number;
+    priority: number | null;
+    name: string;
+    display_name: string | null;
+    default: boolean;
+    ready: boolean;
+    __source?: SourceProvenance;
+}
+export interface ResourcePermission {
+    permission_id: string;
+    permission: string;
+}
+export interface AgentPermission {
+    agent_id: string;
+    is_superuser: boolean;
+    resources: ResourcePermission[];
+    last_updated?: number | null;
+    __source?: SourceProvenance;
+}
+export interface TurnCredential {
+    username: string;
+    credential: string;
+    ttl: number;
+    expires_at: number;
+    uris: string[];
+    __source?: SourceProvenance;
+}
+export interface AgentAggregate<TData = Record<string, JSONValue>> {
+    agent_id: string;
+    data: TData;
+    attachments: Attachment[];
+    last_updated?: number | null;
+    __source?: SourceProvenance;
+}
+export interface DataSeriesResult {
+    value: JSONValue;
+    message_id: string;
+    __source?: SourceProvenance;
+}
+export interface DataSeries {
+    count: number;
+    results: DataSeriesResult[];
+    next?: string | null;
+    __source?: SourceProvenance;
+}
+/**
+ * Lifecycle status for an RPC.
+ *
+ * `sent` is written by the sender; the other non-terminal codes come from the
+ * device handling the request. `acknowledged` means it has picked the request
+ * up, and `pending` carries arbitrary intermediate payloads (progress updates)
+ * it emits while still working — by convention a `{ text }` summary, plus
+ * whatever structured fields the handler wants alongside it. Both prove the
+ * device is alive, so consumers should treat either as a reason to extend how
+ * long they are willing to wait (see `SendRpcOptions.pendingTimeoutMs`), never
+ * as a completion.
+ *
+ * `success` and `error` are the only terminal codes.
+ */
+export type RpcStatus<TPending = undefined> = {
+    code: "awaiting_confirmation";
+} | {
+    code: "sent";
+} | {
+    code: "acknowledged";
+    message: {
+        timestamp: number;
+    };
+} | {
+    code: "error";
+    message: string | object;
+} | {
+    code: "deferred";
+    message: {
+        until: number;
+        at: number;
+    };
+} | {
+    code: "pending";
+    message: TPending;
+} | {
+    code: "success";
+};
+export interface RpcActor {
+    id: string;
+    name: string;
+    email: string;
+}
+/** Shape a consumer posts to initiate an RPC. */
+export interface RpcRequest<TRequest = object> {
+    app_key?: string;
+    method: string;
+    request: TRequest;
+    actor?: RpcActor;
+}
+/** Shape of the message the server maintains as the RPC progresses. */
+export interface RpcMessageData<TRequest = object, TResponse = object, TPending = undefined> extends RpcRequest<TRequest> {
+    status: RpcStatus<TPending>;
+    response: TResponse;
+    __source?: SourceProvenance;
+}

package/dist/esm/types/connection.d.ts

@@ -0,0 +1,72 @@
+/** Platform's binary "is this device currently online?" verdict. */
+export type ConnectionDetermination = "Online" | "Offline";
+/**
+ * Transport mode the device negotiates.
+ *  - `Continuous` keeps a long-lived websocket.
+ *  - `Periodic` checks in on a schedule and disconnects between.
+ *  - `PeriodicContinuous` holds a websocket while awake but lets it drop
+ *    during scheduled sleep windows.
+ */
+export type ConnectionType = "Continuous" | "Periodic" | "PeriodicContinuous";
+/**
+ * Fine-grained transport status code. `…Online…` and `…Pending…` mean the
+ * device is up; `…Offline` means down; `…Unknown` / `PeriodicUnknown` means
+ * the platform hasn't determined either way yet (e.g. a Periodic device
+ * outside its expected check-in window).
+ */
+export type ConnectionStatusCode = "ContinuousOnline" | "ContinuousOnlineNoPing" | "ContinuousOffline" | "ContinuousPending" | "PeriodicUnknown" | "Unknown";
+/**
+ * Per-app preference for how this device's connection state should surface in
+ * user-facing UIs. The platform stores it but doesn't act on it itself — apps
+ * render accordingly.
+ */
+export type ConnectionDisplay = "Always" | "OnlineOnly" | "OfflineOnly" | "Never";
+/**
+ * The connection config block on a `doover_connection` aggregate. Mirrors
+ * pydoover's `ConnectionConfig`. All durations are in seconds (the project's
+ * convention only switches to ms for absolute timestamps); `next_wake_time`
+ * is an absolute timestamp and is therefore epoch ms.
+ */
+export interface ConnectionConfig {
+    connection_type?: ConnectionType | null;
+    /** Expected interval between pings, in seconds (set by the device agent). */
+    expected_interval?: number | null;
+    /**
+     * Seconds of silence after which the platform marks the device offline.
+     * When unset the platform applies its defaults (120 s for `Continuous`,
+     * `expected_interval × 2` otherwise, 1 h fallback) — the resolved value
+     * may also be populated server-side.
+     */
+    offline_after?: number | null;
+    /** For `PeriodicContinuous` devices: how long the device sleeps between connections, in seconds. */
+    sleep_time?: number | null;
+    /** Epoch ms of the device's next scheduled wake (Periodic / PeriodicContinuous). */
+    next_wake_time?: number | null;
+    display?: ConnectionDisplay | null;
+}
+/**
+ * The status block on a `doover_connection` aggregate — the device's most
+ * recent transport observation. Timestamps are epoch ms.
+ */
+export interface ConnectionStatusBlock {
+    status?: ConnectionStatusCode | null;
+    last_online?: number | null;
+    last_ping?: number | null;
+    user_agent?: string | null;
+    ip?: string | null;
+    /** Round-trip latency to the platform in ms (`Continuous` transports). */
+    latency_ms?: number | null;
+}
+/**
+ * Data shape of a device's `doover_connection` aggregate. Use as the generic
+ * to `useAgentChannel` for a typed read:
+ *
+ * ```ts
+ * const { data } = useAgentChannel<ConnectionAggregate>(agentId, "doover_connection");
+ * ```
+ */
+export interface ConnectionAggregate {
+    status?: ConnectionStatusBlock | null;
+    determination?: ConnectionDetermination | null;
+    config?: ConnectionConfig | null;
+}

package/dist/esm/types/connection.js

@@ -0,0 +1,7 @@
+// Types for the `doover_connection` channel — the platform-maintained
+// per-device aggregate that summarises each device agent's transport status,
+// keepalive timing, and connection config. Populated server-side from the
+// device agent's pings (see channels-rest `connection_sync.rs`) and mirrored
+// in pydoover's `ConnectionStatus` / `ConnectionDetermination` /
+// `ConnectionType` / `ConnectionDisplay` / `ConnectionConfig`.
+export {};

package/dist/esm/types/index.d.ts

@@ -0,0 +1,9 @@
+export type * from "./common.js";
+export type * from "./connection.js";
+export type * from "./openapi.js";
+export type * from "./viewer.js";
+export type * from "./audit.js";
+export type * from "./provenance.js";
+export type * from "./batch.js";
+export type * from "../client/data-client.js";
+export type * from "../gateway/types.js";

package/dist/esm/types/openapi.d.ts

@@ -0,0 +1,195 @@
+import type { AgentAggregate, AgentPermission, Alarm, AlarmMessages, AlarmStateMessage, Aggregate, Channel, ConnectionDetails, ConnectionSubscription, ConnectionSubscriptionLog, DataSeries, MessageStructure, NotificationEndpoint, NotificationEndpointSummary, NotificationSubscription, NotificationTopicFilterMode, ResourcePermission, TurnCredential } from "./common.js";
+export type { AgentAggregate, AgentPermission, Alarm, AlarmMessages, AlarmStateMessage, Aggregate, Channel, ConnectionDetails, ConnectionSubscription, ConnectionSubscriptionLog, DataSeries, MessageStructure, NotificationEndpoint, NotificationEndpointSummary, NotificationSubscription, NotificationTopicFilterMode, ResourcePermission, TurnCredential, };
+export interface BatchMessagesResponse {
+    results: MessageStructure[];
+    count: number;
+    /**
+     * Per-agent resume cursors. Any agent whose fetch hit the per-agent
+     * limit before draining the window maps to the oldest snowflake we
+     * did return for it. Pass these back as `agent_before` (parallel to
+     * `agent_id`) on the next call to continue paginating each agent
+     * independently. Empty (or missing, on older servers) when the
+     * window is fully drained.
+     *
+     * This is the canonical pagination signal — `next` and
+     * `at_limit_agent_ids` are kept populated for back-compat with
+     * pre-`next_cursors` clients.
+     */
+    next_cursors?: Record<string, string>;
+    /**
+     * Legacy single-cursor pagination signal — the most-recent (highest
+     * snowflake id) oldest-cursor across at-limit agents. Clients
+     * paginating with a single global `before` should pass this back;
+     * prefer `next_cursors` + `agent_before` for new code.
+     */
+    next?: string | null;
+    /**
+     * Legacy: agent ids with possibly-more older messages — equivalent to
+     * `Object.keys(next_cursors)`. Prefer `next_cursors` for new code.
+     */
+    at_limit_agent_ids?: string[];
+}
+export interface BatchAggregatesResponse {
+    results: AgentAggregate[];
+    count: number;
+}
+export interface NotificationDataResponse {
+    subscriptions: NotificationSubscription[];
+    subscribers: NotificationSubscription[];
+    endpoints: NotificationEndpoint[];
+}
+export interface NotificationEndpointsResponse {
+    endpoints: NotificationEndpoint[];
+}
+export interface NotificationEndpointSummariesResponse {
+    endpoints: NotificationEndpointSummary[];
+}
+export interface NotificationSubscriptionsResponse {
+    subscriptions: NotificationSubscription[];
+}
+export interface NotificationSubscribersResponse {
+    subscribers: NotificationSubscription[];
+}
+export interface NotificationSubscriptionCreateResponse {
+    subscriptions: Array<{
+        id: string;
+        endpoint_id: string;
+    }>;
+}
+export interface PermissionDebugResponse {
+    cache?: AgentPermission | null;
+    db: AgentPermission;
+}
+export interface ScheduleInfo {
+    [key: string]: unknown;
+}
+export interface ProcessorSubscriptionInfo {
+    [key: string]: unknown;
+}
+export interface IngestionEndpointInfo {
+    [key: string]: unknown;
+}
+export interface SubscriptionInfo {
+    agent_id: string;
+    organisation_id: string;
+    app_key: string;
+    deployment_config: Record<string, unknown>;
+    ui_state: Record<string, unknown>;
+    ui_cmds: Record<string, unknown>;
+    tag_values: Record<string, unknown>;
+    connection_data: Record<string, unknown>;
+    token: string;
+}
+export interface SuccessListResponse<T = string> {
+    success: T[];
+}
+export interface CreateChannelRequest {
+    is_private?: boolean;
+    message_schema?: Record<string, unknown> | null;
+    aggregate_schema?: Record<string, unknown> | null;
+}
+export interface PutChannelRequest extends CreateChannelRequest {
+    is_private: boolean;
+}
+export interface CreateMessageRequest {
+    data: Record<string, unknown>;
+    ts?: number;
+}
+export interface UpdateMessageRequest {
+    data: Record<string, unknown>;
+}
+export interface CreateAlarmRequest {
+    name: string;
+    description?: string;
+    enabled?: boolean;
+    key: string;
+    operator: Alarm["operator"];
+    /**
+     * The threshold to compare against. Required for a threshold alarm, and
+     * must be left out entirely for a rate alarm — which states its condition
+     * with `rate_threshold` instead.
+     */
+    value?: unknown;
+    expiry_mins?: number | null;
+    alarm_pending_ms?: number | null;
+    /** Stable slug used in notification topics. Derived from `name` if absent. */
+    topic_name?: string;
+    notification_policy?: Alarm["notification_policy"];
+    /**
+     * Units per second, judged over at least `rate_window_ms`. Setting the pair
+     * makes this a rate-of-change alarm; they must be set together.
+     */
+    rate_threshold?: number | null;
+    rate_window_ms?: number | null;
+    messages?: AlarmMessages | null;
+}
+/**
+ * Every field is optional; each is merged rather than replaced. `messages` is
+ * merged state by state and field by field, so `{messages: {ok: {notify:
+ * false}}}` leaves the stored text alone, and an explicit `null` clears.
+ */
+export interface PatchAlarmRequest extends Partial<CreateAlarmRequest> {
+}
+export interface CreateEndpointRequest {
+    name: string;
+    priority?: number | null;
+    type: number;
+    extra_data: Record<string, unknown>;
+    default: boolean;
+}
+export interface UpdateEndpointRequest {
+    extra_data?: Record<string, unknown> | null;
+    priority?: number | null;
+    name?: string;
+}
+export interface CreateNotificationSubscriptionRequest {
+    subscribe_to: string;
+    endpoint_id?: string | null;
+    severity: number;
+    topic_filter: string[];
+    /** Defaults to `exact` server-side when absent. */
+    topic_filter_mode?: NotificationTopicFilterMode;
+}
+export interface UpdateNotificationSubscriptionRequest {
+    severity?: number;
+    topic_filter?: string[];
+    topic_filter_mode?: NotificationTopicFilterMode;
+}
+export interface UpdateMeWebPushEndpointRequest {
+    old_endpoint: string;
+    endpoint: string;
+    key_p256dh: string;
+    key_auth: string;
+    expires_at: number;
+}
+export interface SyncPermissionRequest {
+    agent_permissions: AgentPermission[];
+}
+export interface PutScheduleRequest {
+    app_key: string;
+    is_org?: boolean | null;
+    permissions: ResourcePermission[];
+}
+export interface PutSubscriptionRequest {
+    subscription_arn: string;
+    app_key: string;
+    is_org?: boolean | null;
+    permissions: ResourcePermission[];
+}
+export interface CreateIngestionRequest {
+    lambda_arn: string;
+    cidr_ranges: string[];
+    signing_key?: string | null;
+    signing_key_hash_header?: string | null;
+    throttle_limit: number;
+    never_replace_token?: boolean;
+    mini_token?: boolean;
+    is_org?: boolean | null;
+    app_key: string;
+    permissions: ResourcePermission[];
+}
+export interface TurnTokenRequest {
+    role: "client" | "device";
+    device_id?: string;
+    camera_name: string;
+}

package/dist/esm/types/provenance.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Provenance envelope stamped on every datum a `DataClient` returns —
+ * describing which client produced it, when, and how (REST request with
+ * params/timing, or gateway event with name/receipt time).
+ *
+ * Purely additive: every data shape gains `__source?: SourceProvenance`.
+ * Nothing existing is removed/renamed/modified.
+ */
+export interface SourceProvenance {
+    /** Which DataClient produced this datum. For a stand-alone client this is
+     *  its own id; for an item via a MultiplexClient it is the originating
+     *  member's id. */
+    client: {
+        id: string;
+        /** "cloud" | "local" | … */
+        kind: string;
+        label?: string;
+        /** Arbitrary client/source metadata (base URL, org id, device id, …). */
+        meta?: Record<string, unknown>;
+    };
+    /** When the client obtained this datum (epoch ms). */
+    retrievedAt: number;
+    via: SourceProvenanceViaRest | SourceProvenanceViaGateway;
+}
+export interface SourceProvenanceViaRest {
+    transport: "rest";
+    /** The DataClient method that produced it, e.g. "messages.listMessages". */
+    method: string;
+    /** The input the caller passed (agentId, channelName, params, body summary). */
+    request: Record<string, unknown>;
+    /** When the request was dispatched (epoch ms). */
+    startedAt: number;
+    /** Time from dispatch to response completion (ms). */
+    durationMs: number;
+    /** HTTP status, when known. */
+    status?: number;
+}
+export interface SourceProvenanceViaGateway {
+    transport: "gateway";
+    /** The gateway event that carried it, e.g. "messageCreate", "aggregateUpdate". */
+    event: string;
+    sessionId?: string;
+    /** When the event was received (epoch ms). */
+    receivedAt: number;
+}