doover-js 0.5.3 → 0.6.0

package/dist/types/common.d.ts

@@ -1,3 +1,4 @@
+import type { SourceProvenance } from "./provenance";
 export type JSONPrimitive = null | boolean | number | string;
 export type JSONValue = JSONPrimitive | JSONValue[] | {
     [key: string]: JSONValue;
@@ -16,6 +17,7 @@ export interface Aggregate<TData = Record<string, JSONValue>> {
     data: TData;
     attachments: Attachment[];
     last_updated?: number | null;
+    __source?: SourceProvenance;
 }
 export interface MessageAttachment extends Attachment {
 }
@@ -27,6 +29,7 @@ export interface MessageStructure<TData = JSONValue> {
     channel: ChannelRef;
     timestamp: number;
     record_log?: boolean;
+    __source?: SourceProvenance;
 }
 export interface Channel<TAgg = Record<string, JSONValue>> {
     aggregate?: Aggregate<TAgg>;
@@ -39,6 +42,7 @@ export interface Channel<TAgg = Record<string, JSONValue>> {
     message_schema?: Record<string, JSONValue> | null;
     daily_message_summaries?: unknown[];
     alarms?: Alarm[];
+    __source?: SourceProvenance;
 }
 export interface Alarm {
     id: string;
@@ -51,19 +55,23 @@ export interface Alarm {
     state: AlarmState;
     expiry_mins: number | null;
     entered_state_ts: number;
+    alarm_pending_ms: number | null;
+    __source?: SourceProvenance;
 }
 export type AlarmOperator = "eq" | "ge" | "gt" | "le" | "lt";
-export type AlarmState = "NoData" | "OK" | "Alarm";
+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;
@@ -74,6 +82,7 @@ export interface ConnectionDetails {
     latency?: number | null;
     status: number;
     subscriptions: ConnectionSubscription[];
+    __source?: SourceProvenance;
 }
 export interface NotificationSubscriptionEndpoint {
     id: string;
@@ -87,6 +96,7 @@ export interface NotificationSubscription {
     severity: number;
     topic_filter: string[];
     endpoints: NotificationSubscriptionEndpoint[];
+    __source?: SourceProvenance;
 }
 export interface NotificationEndpoint {
     id: string;
@@ -96,6 +106,7 @@ export interface NotificationEndpoint {
     extra_data: Record<string, JSONValue>;
     name: string;
     default: boolean;
+    __source?: SourceProvenance;
 }
 export interface ResourcePermission {
     permission_id: string;
@@ -106,6 +117,7 @@ export interface AgentPermission {
     is_superuser: boolean;
     resources: ResourcePermission[];
     last_updated?: number | null;
+    __source?: SourceProvenance;
 }
 export interface TurnCredential {
     username: string;
@@ -113,20 +125,24 @@ export interface TurnCredential {
     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[];
+    __source?: SourceProvenance;
 }
 /**
  * Lifecycle status for an RPC. `pending` carries arbitrary intermediate
@@ -167,4 +183,5 @@ export interface RpcRequest<TRequest = object> {
 export interface RpcMessageData<TRequest = object, TResponse = object, TPending = undefined> extends RpcRequest<TRequest> {
     status: RpcStatus<TPending>;
     response: TResponse;
+    __source?: SourceProvenance;
 }

package/dist/types/openapi.d.ts

@@ -103,6 +103,7 @@ export interface CreateAlarmRequest {
     operator: Alarm["operator"];
     value: unknown;
     expiry_mins?: number | null;
+    alarm_pending_ms?: number | null;
 }
 export interface PatchAlarmRequest extends Partial<CreateAlarmRequest> {
 }

package/dist/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;
+}

package/dist/types/provenance.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/viewer.d.ts

@@ -1,3 +1,4 @@
+import type { SourceProvenance } from "./provenance";
 import type { Aggregate, Channel, ConnectionDetails, MessageStructure } from "./common";
 export interface ChannelIdentifier {
     agentId?: string;
@@ -19,11 +20,13 @@ export interface Agent {
     };
     extra_config: Record<string, unknown>;
     connection_determination?: "Online" | "Offline";
+    __source?: SourceProvenance;
 }
 export interface User {
     id: string;
     email?: string;
     name?: string;
+    __source?: SourceProvenance;
     [key: string]: unknown;
 }
 export interface GetAgentsOptions {

package/dist/viewer/doover-data-provider.d.ts

@@ -18,8 +18,8 @@ interface SubscriptionEntry {
      */
     messageUpdateCallback?: (identifier: ChannelIdentifier, message: MessageStructure, request_data?: JSONValue) => void;
 }
+/** @deprecated Use DooverClient subclients directly. Removed in 0.6.0. */
 export declare class DooverDataProvider implements ChannelsDataProvider<ChannelIdentifier> {
-    private readonly config;
     readonly rest: RestClient;
     readonly gateway: GatewayClient;
     readonly agentsApi: AgentsApi;
@@ -27,68 +27,64 @@ export declare class DooverDataProvider implements ChannelsDataProvider<ChannelI
     readonly messagesApi: MessagesApi;
     readonly aggregatesApi: AggregatesApi;
     readonly connectionsApi: ConnectionsApi;
-    private readonly subscriptions;
+    private readonly controlApiUrl?;
+    private bridges;
+    private dispatcher?;
     constructor(config: DooverClientConfig, auth?: DooverAuth);
+    constructor(injected: {
+        rest: RestClient;
+        gateway: GatewayClient;
+        controlApiUrl?: string;
+    });
+    /** @deprecated Use `client.users.getMe()` instead. Removed in 0.6.0. */
     getMe(): Promise<User>;
+    /** @deprecated Use `client.agents.listAgents(opts)` instead. Removed in 0.6.0. */
     getAgents(options?: GetAgentsOptions): Promise<AgentsResponse>;
+    /** @deprecated Use `client.channels.listChannels(id, opts)` instead. Removed in 0.6.0. */
     getChannels(identifier: ChannelIdentifier, options?: {
         includeArchived?: boolean;
     }): Promise<Channel[] | undefined>;
+    /** @deprecated Use `client.channels.putChannel(id, name, body)` instead. Removed in 0.6.0. */
     createChannel(identifier: ChannelIdentifier, channelName: string, options?: {
         is_private?: boolean;
     }): Promise<unknown>;
+    /** @deprecated Use `client.channels.archiveChannel(id)` instead. Removed in 0.6.0. */
     archiveChannel(identifier: ChannelIdentifier): Promise<unknown>;
+    /** @deprecated Use `client.channels.unarchiveChannel(id)` instead. Removed in 0.6.0. */
     unarchiveChannel(identifier: ChannelIdentifier): Promise<unknown>;
+    /** @deprecated Use `client.channels.getChannel(id)` instead. Removed in 0.6.0. */
     getChannel(identifier: ChannelIdentifier): Promise<Channel | undefined>;
+    /** @deprecated Use `client.gateway.subscribeToChannel(channel, handlers)` instead. Removed in 0.6.0. */
     subscribeToChannel(identifier: ChannelIdentifier, callback: SubscriptionEntry["messageCallback"], aggregateCallback: SubscriptionEntry["aggregateCallback"], messageUpdateCallback?: SubscriptionEntry["messageUpdateCallback"]): Promise<void>;
-    unsubscribeFromChannel(identifier: ChannelIdentifier, callback: SubscriptionEntry["messageCallback"]): Promise<void>;
+    /** @deprecated Call the unsubscribe fn returned by `client.gateway.subscribeToChannel`. Removed in 0.6.0. */
+    unsubscribeFromChannel(_identifier: ChannelIdentifier, callback: SubscriptionEntry["messageCallback"]): Promise<void>;
+    /** @deprecated Compose `client.channels.getChannel(id).then(c => c.aggregate ?? client.aggregates.getAggregate(id))` instead. Removed in 0.6.0. */
     getAggregate(identifier: ChannelIdentifier): Promise<Aggregate | undefined>;
-    /**
-     * Fetch a page of messages for a channel.
-     *
-     * Accepts either a cursor string (legacy — shorthand for `{ before }`)
-     * or a `ListMessagesParams` options object.
-     *
-     * Default limit is 10 for backwards compatibility; pass `limit` explicitly
-     * for larger pages.
-     */
+    /** @deprecated Use `client.messages.listMessages(id, { ...opts, order: "asc" })` instead. Removed in 0.6.0. */
     getMessages(identifier: ChannelIdentifier, optionsOrBefore?: string | ListMessagesParams): Promise<MessageStructure[] | undefined>;
+    /** @deprecated Use `client.messages.deleteMessage(id, msgId)` instead. Removed in 0.6.0. */
     deleteMessage(identifier: ChannelIdentifier, messageId: string): Promise<unknown>;
+    /** @deprecated Use `client.messages.postMessage(id, { data })` instead. Removed in 0.6.0. */
     sendMessage(identifier: ChannelIdentifier, message: object): Promise<MessageStructure>;
-    /**
-     * Send a message-based RPC to a channel and await a settled response.
-     *
-     * Wire protocol: POST a message with `{ type: "rpc", ...rpcRequest }`; the
-     * server echoes progress via `MessageUpdate` events keyed by the message id,
-     * carrying a `status` envelope. Resolves on `success` with the `response`
-     * payload, rejects on `error` with the status message.
-     *
-     * For low-latency ephemeral commands (camera PTZ etc.), use
-     * `gateway.sendOneShotMessage` directly instead — that path is not persisted
-     * to the database.
-     *
-     * `onStatus` fires on every intermediate status (`sent`, `acknowledged`,
-     * `deferred`, `pending`) and once more on terminal states.
-     */
+    /** @deprecated Use `client.rpc.send(id, req, opts)` instead. Removed in 0.6.0. */
     sendRPC<TRequest = object, TResponse = object, TPending = undefined>(identifier: ChannelIdentifier, rpcRequest: RpcRequest<TRequest>, options?: {
         onStatus?: (status: RpcStatus<TPending>) => void;
     }): Promise<TResponse>;
+    /** @deprecated Use `client.aggregates.patchAggregate(id, data, params)` instead. Removed in 0.6.0. */
     updateAggregate(identifier: ChannelIdentifier, message: object, params?: AggregateMutationParams): Promise<Aggregate>;
+    /** @deprecated Use `client.aggregates.putAggregate(id, data, params)` instead. Removed in 0.6.0. */
     putAggregate(identifier: ChannelIdentifier, message: object, params?: AggregateMutationParams): Promise<Aggregate>;
+    /** @deprecated Use `client.connections.getChannelSubscriptions(id)` instead. Removed in 0.6.0. */
     getChannelSubscriptions(identifier: ChannelIdentifier): Promise<SubscriptionDetails[]>;
+    /** @deprecated Use `client.connections.getAgentConnections(id)` instead. Removed in 0.6.0. */
     getAgentConnections(identifier: ChannelIdentifier): Promise<ConnectionDetails[]>;
+    /** @deprecated Use the free function `getIdentifierFromPath(path, search)` instead. Removed in 0.6.0. */
     getIdentifierFromPath(path: string, searchParams: URLSearchParams): {
         identifier: ChannelIdentifier;
         aggregatePath?: string;
     };
+    /** @deprecated No replacement — this was a synthesized stub. Removed in 0.6.0. */
     getAgentInfo(agentId: string): Promise<Agent | undefined>;
-    private normalizeAgentEntry;
-    private normalizeOrganisationEntry;
-    private normalizeUserEntry;
-    private buildUserDisplayName;
-    private coerceExtraConfig;
     private requireChannel;
-    private channelKey;
-    private toIdentifier;
 }
 export {};