doover-js 0.11.0 → 0.13.0

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

@@ -0,0 +1,72 @@
+import type { RestClient } from "../http/rest-client.js";
+export type RefineRecord = Record<string, unknown> & {
+    id?: string | number;
+};
+export type RefineMeta = Record<string, unknown> | undefined;
+export interface RefinePagination {
+    currentPage?: number;
+    pageSize?: number;
+}
+export interface RefineSorter {
+    field: string;
+    order?: "asc" | "desc";
+}
+export interface RefineCrudFilter {
+    field: string;
+    operator: string;
+    value: unknown;
+}
+export interface RefineGetListParams {
+    resource: string;
+    pagination?: RefinePagination;
+    sorters?: RefineSorter[];
+    filters?: RefineCrudFilter[];
+    meta?: RefineMeta;
+}
+export interface RefineOneParams {
+    resource: string;
+    id: string | number;
+    meta?: RefineMeta;
+}
+export interface RefineMutationParams {
+    resource: string;
+    id?: string | number;
+    variables?: unknown;
+    meta?: RefineMeta;
+}
+export interface RefineCustomParams {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    payload?: unknown;
+    meta?: RefineMeta;
+}
+export interface RefineDataProviderLike {
+    getOne: (params: RefineOneParams) => Promise<{
+        data: unknown;
+    }>;
+    getList: <TData extends RefineRecord = RefineRecord>(params: RefineGetListParams) => Promise<{
+        data: TData[];
+        total: number;
+    }>;
+    create: (params: RefineMutationParams) => Promise<{
+        data: unknown;
+    }>;
+    update: (params: RefineMutationParams & {
+        id: string | number;
+    }) => Promise<{
+        data: unknown;
+    }>;
+    deleteOne: (params: RefineOneParams) => Promise<{
+        data: unknown;
+    }>;
+    custom: (params: RefineCustomParams) => Promise<{
+        data: unknown;
+    }>;
+    getApiUrl: () => string;
+}
+export interface CreateRefineDataProviderOptions {
+    baseUrl?: string;
+}
+export declare function createRefineDataProvider(rest: RestClient, options?: CreateRefineDataProviderOptions): RefineDataProviderLike;
+export declare function getApiPath(resource: string, meta?: RefineMeta): string;

package/dist/esm/refine/index.js

@@ -0,0 +1,215 @@
+export function createRefineDataProvider(rest, options = {}) {
+    const baseUrl = options.baseUrl ?? rest.config.controlApiUrl;
+    return {
+        getOne: async ({ resource, id, meta }) => {
+            const data = await rest.request({
+                path: `/${getApiPath(resource, meta)}/${id}/`,
+                headers: getMetaHeaders(meta),
+                baseUrl,
+            });
+            return { data };
+        },
+        getList: async ({ resource, pagination, sorters, filters, meta, }) => {
+            const data = await rest.request({
+                path: `/${getApiPath(resource, meta)}/`,
+                query: buildListQuery({ pagination, sorters, filters, meta }),
+                headers: getMetaHeaders(meta),
+                baseUrl,
+            });
+            return {
+                data: data.results,
+                total: data.count,
+            };
+        },
+        create: async ({ resource, variables, meta }) => {
+            const mergedMeta = isRecord(variables) ? { ...meta, ...variables } : meta;
+            const data = await rest.request({
+                path: `/${getApiPath(resource, mergedMeta)}/`,
+                method: "POST",
+                body: prepareVariables(variables, meta),
+                headers: getMetaHeaders(meta),
+                baseUrl,
+            });
+            return { data };
+        },
+        update: async ({ resource, id, variables, meta }) => {
+            const data = await rest.request({
+                path: `/${getApiPath(resource, meta)}/${id}/`,
+                method: "PATCH",
+                body: prepareVariables(variables, meta),
+                headers: getMetaHeaders(meta),
+                baseUrl,
+            });
+            return { data };
+        },
+        deleteOne: async ({ resource, id, meta }) => {
+            const data = await rest.request({
+                path: `/${getApiPath(resource, meta)}/${id}/`,
+                method: "DELETE",
+                headers: getMetaHeaders(meta),
+                baseUrl,
+            });
+            return { data: data ?? null };
+        },
+        custom: async ({ url, method, headers, payload, meta }) => {
+            const { path, query } = splitCustomUrl(url);
+            const data = await rest.request({
+                path,
+                method,
+                headers: { ...headers, ...getMetaHeaders(meta) },
+                body: payload == null ? undefined : payload,
+                query,
+                baseUrl,
+            });
+            return { data };
+        },
+        getApiUrl: () => baseUrl,
+    };
+}
+function getMetaHeaders(meta) {
+    if (!meta?.organisation)
+        return undefined;
+    return { "X-Doover-Organisation": String(idValue(meta.organisation)) };
+}
+export function getApiPath(resource, meta) {
+    const apiPath = meta?.api_path;
+    if (apiPath !== undefined) {
+        const paths = typeof apiPath === "string" ? [apiPath] : apiPath;
+        if (Array.isArray(paths)) {
+            for (const path of paths) {
+                if (typeof path !== "string")
+                    continue;
+                try {
+                    return fillApiPath(path, meta);
+                }
+                catch (err) {
+                    if (paths.length === 1)
+                        throw err;
+                }
+            }
+        }
+    }
+    return resource;
+}
+function fillApiPath(path, meta) {
+    let apiPath = path;
+    const matches = [...apiPath.matchAll(/:([^/]+)/g)].map((m) => m[1]);
+    for (const match of matches) {
+        const value = lookupPathParam(match, meta);
+        if (value === undefined) {
+            throw new Error(`Missing value for ${match} in meta`);
+        }
+        apiPath = apiPath.replace(`:${match}`, String(value));
+    }
+    return apiPath;
+}
+function lookupPathParam(match, meta) {
+    if (!meta)
+        return undefined;
+    if (match in meta && meta[match] !== undefined)
+        return idValue(meta[match]);
+    const withoutId = match.replace(/id$/i, "");
+    if (withoutId in meta && meta[withoutId] !== undefined) {
+        return idValue(meta[withoutId]);
+    }
+    return undefined;
+}
+function idValue(value) {
+    return isRecord(value) && "id" in value ? value.id : value;
+}
+function buildListQuery({ pagination, sorters, filters, meta, }) {
+    const query = {};
+    if (pagination) {
+        query.page = pagination.currentPage ?? 1;
+        if (pagination.pageSize)
+            query.per_page = pagination.pageSize;
+    }
+    if (sorters && sorters.length > 0) {
+        query.ordering = `${sorters[0].order === "desc" ? "-" : ""}${sorters[0].field}`;
+    }
+    let hasArchivedFilter = false;
+    for (const filter of filters ?? []) {
+        if (!filter.field || !filter.operator)
+            continue;
+        if (filter.operator === "contains" && filter.field === "search") {
+            query.search = String(filter.value ?? "");
+            continue;
+        }
+        if (filter.field === "archived" || filter.field === "device_archived") {
+            hasArchivedFilter = hasArchivedFilter || filter.field === "archived";
+            if (filter.operator === "eq" || filter.operator === "in") {
+                query[filter.field] =
+                    filter.value === "__all__" ? "" : String(filter.value ?? "");
+            }
+            continue;
+        }
+        if (filter.operator === "contains") {
+            query[`${filter.field}__icontains`] = String(filter.value ?? "");
+        }
+        else if (filter.operator === "containss") {
+            query[`${filter.field}__contains`] = String(filter.value ?? "");
+        }
+        else if (filter.operator === "eq" || filter.operator === "in") {
+            query[filter.field] = String(filter.value ?? "");
+        }
+    }
+    if (meta?.canArchive === true && !hasArchivedFilter) {
+        query.archived = "false";
+    }
+    return query;
+}
+function prepareVariables(variables, meta) {
+    if (!isRecord(variables))
+        return variables;
+    const next = { ...variables };
+    const renameFields = isRecord(meta?.renameFields) ? meta.renameFields : null;
+    if (renameFields) {
+        for (const [from, to] of Object.entries(renameFields)) {
+            if (typeof to !== "string")
+                continue;
+            const value = next[from];
+            const mapped = Array.isArray(value)
+                ? value.map((item) => idValue(item))
+                : idValue(value);
+            next[from] = mapped;
+            next[to] = mapped;
+        }
+    }
+    if (Object.values(next).some(isFileLike)) {
+        const formData = new FormData();
+        for (const [key, value] of Object.entries(next)) {
+            if (value == null)
+                continue;
+            if (isFileLike(value)) {
+                formData.append(key, value);
+            }
+            else if (typeof value === "object") {
+                formData.append(key, JSON.stringify(value));
+            }
+            else {
+                formData.append(key, String(value));
+            }
+        }
+        return formData;
+    }
+    return next;
+}
+function splitCustomUrl(url) {
+    const [rawPath, rawQuery] = url.replace(/^\//, "").split("?", 2);
+    const path = `/${rawPath.replace(/\/?$/, "/")}`;
+    if (!rawQuery)
+        return { path, query: undefined };
+    const params = new URLSearchParams(rawQuery);
+    const query = {};
+    for (const key of new Set(params.keys())) {
+        const values = params.getAll(key);
+        query[key] = values.length > 1 ? values : values[0] ?? "";
+    }
+    return { path, query };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFileLike(value) {
+    return typeof File !== "undefined" && value instanceof File;
+}

package/dist/esm/rpc/errors.d.ts

@@ -0,0 +1,10 @@
+import type { RpcRequest, RpcStatus } from "../types/common.js";
+export declare class DooverRpcError extends Error {
+    readonly status: RpcStatus<unknown> & {
+        code: "error";
+    };
+    readonly request: RpcRequest;
+    constructor(status: RpcStatus<unknown> & {
+        code: "error";
+    }, request: RpcRequest);
+}

package/dist/esm/rpc/errors.js

@@ -0,0 +1,19 @@
+export class DooverRpcError extends Error {
+    constructor(status, request) {
+        const text = typeof status.message === "string"
+            ? status.message
+            : (() => {
+                try {
+                    return JSON.stringify(status.message);
+                }
+                catch {
+                    return "Unknown RPC error";
+                }
+            })();
+        super(text);
+        this.name = "DooverRpcError";
+        this.status = status;
+        this.request = request;
+        Object.setPrototypeOf(this, DooverRpcError.prototype);
+    }
+}

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

@@ -0,0 +1,3 @@
+export { RpcDispatcher } from "./rpc-dispatcher.js";
+export type { SendRpcOptions } from "./rpc-dispatcher.js";
+export { DooverRpcError } from "./errors.js";

package/dist/esm/rpc/index.js

@@ -0,0 +1,2 @@
+export { RpcDispatcher } from "./rpc-dispatcher.js";
+export { DooverRpcError } from "./errors.js";

package/dist/esm/rpc/rpc-dispatcher.d.ts

@@ -0,0 +1,41 @@
+import type { MessagesApi } from "../apis/messages-api.js";
+import type { DooverStatsCollector } from "../client/stats.js";
+import type { GatewayClient } from "../gateway/gateway-client.js";
+import type { RpcRequest, RpcStatus } from "../types/common.js";
+export interface SendRpcOptions<TPending = undefined> {
+    onStatus?: (status: RpcStatus<TPending>) => void;
+    signal?: AbortSignal;
+    /**
+     * How long to wait to hear from the device at all. A healthy device answers
+     * within seconds however long the work then takes, so keep this short and
+     * use `pendingTimeoutMs` for the work itself.
+     */
+    timeoutMs?: number;
+    /**
+     * How long the command may then stay in flight once the device has answered
+     * it — acknowledged it, or reported progress. Re-armed on every subsequent
+     * status update, so a device that keeps reporting keeps its command alive,
+     * while one that answers and then dies still fails. Without this, a handler
+     * that legitimately runs longer than `timeoutMs` is killed mid-flight.
+     */
+    pendingTimeoutMs?: number;
+}
+interface ChannelIdentifierLike {
+    agentId: string;
+    channelName: string;
+}
+export declare class RpcDispatcher {
+    private readonly gateway;
+    private readonly messages;
+    private pending;
+    private channelRefs;
+    private stats;
+    constructor(gateway: GatewayClient, messages: MessagesApi);
+    setStats(collector: DooverStatsCollector | null): void;
+    send<TReq = object, TRes = object, TPending = undefined>(channel: ChannelIdentifierLike, request: RpcRequest<TReq>, options?: SendRpcOptions<TPending>): Promise<TRes>;
+    private acquireChannel;
+    private releaseChannel;
+    private route;
+    private settle;
+}
+export {};

package/dist/esm/rpc/rpc-dispatcher.js

@@ -0,0 +1,141 @@
+import { DooverRpcError } from "./errors.js";
+/** Whether the device has answered this command, rather than only received it. */
+function hasDeviceAnswered(status) {
+    return status.code === "acknowledged" || status.code === "pending";
+}
+function isRpcMessageData(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        "status" in data &&
+        "method" in data &&
+        "request" in data);
+}
+export class RpcDispatcher {
+    constructor(gateway, messages) {
+        this.gateway = gateway;
+        this.messages = messages;
+        this.pending = new Map();
+        this.channelRefs = new Map();
+        this.stats = null;
+    }
+    setStats(collector) {
+        this.stats = collector;
+    }
+    send(channel, request, options) {
+        return new Promise((resolve, reject) => {
+            const channelRef = {
+                agent_id: channel.agentId,
+                name: channel.channelName,
+            };
+            const channelKey = `${channelRef.agent_id}/${channelRef.name}`;
+            this.acquireChannel(channelKey, channelRef);
+            const startedAt = this.stats?.recordRpcStart() ?? null;
+            this.messages
+                .postMessage(channel.agentId, channel.channelName, {
+                data: {
+                    type: "rpc",
+                    ...request,
+                },
+            })
+                .then((message) => {
+                const pending = {
+                    resolve: resolve,
+                    reject,
+                    onStatus: options?.onStatus,
+                    request: request,
+                    channelKey,
+                    channel: channelRef,
+                    startedAt,
+                    pendingTimeoutMs: options?.pendingTimeoutMs,
+                };
+                if (options?.signal) {
+                    const onAbort = () => this.settle(message.id, "abort", undefined, options.signal?.reason);
+                    if (options.signal.aborted) {
+                        this.releaseChannel(channelKey);
+                        this.stats?.recordRpcEnd(startedAt, "abort");
+                        reject(options.signal.reason ?? new Error("Aborted"));
+                        return;
+                    }
+                    options.signal.addEventListener("abort", onAbort);
+                    pending.signal = options.signal;
+                    pending.abortListener = onAbort;
+                }
+                if (options?.timeoutMs !== undefined) {
+                    pending.timer = setTimeout(() => {
+                        this.settle(message.id, "timeout", undefined, new Error("RPC timed out"));
+                    }, options.timeoutMs);
+                }
+                this.pending.set(message.id, pending);
+            })
+                .catch((err) => {
+                // postMessage failed before we registered pending — release and reject.
+                this.releaseChannel(channelKey);
+                this.stats?.recordRpcEnd(startedAt, "error");
+                reject(err);
+            });
+        });
+    }
+    acquireChannel(channelKey, channelRef) {
+        const existing = this.channelRefs.get(channelKey);
+        if (existing) {
+            existing.refCount += 1;
+            return;
+        }
+        const handlers = {
+            onMessageUpdate: (msg, requestData) => this.route(msg, requestData),
+        };
+        const unsubscribe = this.gateway.subscribeToChannel(channelRef, handlers);
+        this.channelRefs.set(channelKey, { unsubscribe, refCount: 1 });
+    }
+    releaseChannel(channelKey) {
+        const entry = this.channelRefs.get(channelKey);
+        if (!entry)
+            return;
+        entry.refCount -= 1;
+        if (entry.refCount <= 0) {
+            entry.unsubscribe();
+            this.channelRefs.delete(channelKey);
+        }
+    }
+    route(msg, _requestData) {
+        const pending = this.pending.get(msg.id);
+        if (!pending)
+            return;
+        if (!isRpcMessageData(msg.data))
+            return;
+        const status = msg.data.status;
+        pending.onStatus?.(status);
+        if (status.code === "success") {
+            this.settle(msg.id, "success", msg.data.response);
+        }
+        else if (status.code === "error") {
+            this.settle(msg.id, "error", undefined, new DooverRpcError(status, pending.request));
+        }
+        else if (hasDeviceAnswered(status) && pending.pendingTimeoutMs !== undefined) {
+            // The device is alive and working: swap the "no response" deadline for
+            // the pending budget, and re-arm it on every report that follows.
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.timer = setTimeout(() => {
+                this.settle(msg.id, "timeout", undefined, new Error("Device stopped reporting progress"));
+            }, pending.pendingTimeoutMs);
+        }
+    }
+    settle(messageId, outcome, response, rejection) {
+        const pending = this.pending.get(messageId);
+        if (!pending)
+            return;
+        this.pending.delete(messageId);
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        if (pending.signal && pending.abortListener) {
+            pending.signal.removeEventListener("abort", pending.abortListener);
+        }
+        this.releaseChannel(pending.channelKey);
+        this.stats?.recordRpcEnd(pending.startedAt, outcome);
+        if (outcome === "success")
+            pending.resolve(response);
+        else
+            pending.reject(rejection);
+    }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Audit event types — mirror of the records doover-control writes to the
+ * `dv-audit` channel (see ``doover-control/doover_control/events/audit.py``
+ * for the source of truth).
+ *
+ * Each record is read back via the standard channel-messages APIs: it lands
+ * inside a ``MessageStructure<AuditEvent>`` envelope (with ``id``, ``timestamp``,
+ * ``channel``, etc.), and the record itself is on ``message.data``.
+ */
+/** Channel name on which audit records live in doover-data. */
+export declare const DV_AUDIT_CHANNEL = "dv-audit";
+/** The role this party plays in the record. */
+export type AuditEntityType = "device" | "user" | "organisation" | "Tunnel" | "ApplicationInstallation" | "SolutionInstallation" | "ApplicationDeployment" | "ObjectGroup" | "PendingUser" | "User" | "fusionauth" | "system";
+export interface AuditEntity {
+    type: AuditEntityType;
+    /** Stringified id (User pk, Device pk, FA UUID, etc.). May be absent for `system`. */
+    id?: string;
+    /** Display name. May be an email for users / pending invites. */
+    name?: string;
+}
+export interface AuditOrganisation {
+    id: string;
+    name: string;
+}
+export interface AuditRequestContext {
+    ip_address?: string;
+    user_agent?: string;
+}
+/** Origin system for the event. */
+export type AuditSource = "control" | "auth" | "data" | "tunnels";
+/**
+ * String-literal union of every wired audit action — kept in lock-step with
+ * ``doover_control/events/types.py``'s ``EventType`` enum. Future event types
+ * declared in Python but not yet emitted are intentionally included so the
+ * frontend mapping (icons, labels) can be filled in ahead of the wire-up.
+ */
+export type AuditAction = "user.logged_in" | "user.login.failed" | "user.signed_up" | "user.created" | "user.updated" | "user.deleted" | "user.deactivated" | "user.reactivated" | "user.password_changed" | "user.password_reset" | "user.password_breached" | "user.mfa_changed" | "user.email_verified" | "user.email_changed" | "user.idp_linked" | "user.idp_unlinked" | "user.token_revoked" | "user.invited" | "user.removed" | "user.role_changed" | "app.installed" | "app.deployed" | "app.config_changed" | "app.uninstalled" | "solution.config_changed" | "group.created" | "group.edited" | "group.deleted" | "device.created" | "device.updated" | "device.config_changed" | "device.archived" | "device.unarchived" | "device.deleted" | "device.opened" | "tunnel.created" | "tunnel.deleted" | "tunnel.opened" | "tunnel.closed" | "tunnel.accessed" | "notification.sent" | "report.created" | "command.received";
+/**
+ * The audit record payload as written by ``publish_audit`` — i.e. what you
+ * find on ``MessageStructure<AuditEvent>.data`` after reading the channel.
+ *
+ * The doover-data ``MessageStructure`` envelope provides ``id`` (snowflake)
+ * and ``timestamp`` (epoch ms) for ordering; this struct is the body only.
+ */
+export interface AuditEvent {
+    action: AuditAction;
+    actor: AuditEntity | null;
+    subject: AuditEntity | null;
+    organisation: AuditOrganisation | null;
+    source: AuditSource;
+    metadata: Record<string, unknown>;
+    request_context: AuditRequestContext | null;
+}

package/dist/esm/types/audit.js

@@ -0,0 +1,11 @@
+/**
+ * Audit event types — mirror of the records doover-control writes to the
+ * `dv-audit` channel (see ``doover-control/doover_control/events/audit.py``
+ * for the source of truth).
+ *
+ * Each record is read back via the standard channel-messages APIs: it lands
+ * inside a ``MessageStructure<AuditEvent>`` envelope (with ``id``, ``timestamp``,
+ * ``channel``, etc.), and the record itself is on ``message.data``.
+ */
+/** Channel name on which audit records live in doover-data. */
+export const DV_AUDIT_CHANNEL = "dv-audit";

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

@@ -0,0 +1,85 @@
+/**
+ * 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 declare const MAX_BATCH_ITEMS = 50;
+/** A single merge-patch against one agent's channel aggregate. */
+export interface BatchAggregateUpdateItem {
+    agent_id: string;
+    channel_name: string;
+    /** Merge patch. `null` at a leaf clears that key. */
+    data: Record<string, unknown>;
+    /**
+     * Dot-paths to replace outright rather than merge into. Mirrors the
+     * `replace` query parameter on the single-aggregate PATCH.
+     */
+    replace?: string[];
+    /** Skip aggregate hooks (alarms, SNS fan-out, websocket publish). */
+    suppress_hooks?: boolean;
+}
+export interface BatchCreateMessageItem {
+    agent_id: string;
+    channel_name: string;
+    /**
+     * Supplying a stable ID makes create retries idempotent. Without one the
+     * server generates an ID and a lost response can duplicate the message.
+     */
+    message_id?: string;
+    data: unknown;
+    /** Message timestamp, ms since epoch. Defaults to server receipt time. */
+    ts?: number;
+    /** Time-to-live in seconds. */
+    ttl?: number;
+}
+export interface BatchUpdateMessageItem {
+    agent_id: string;
+    channel_name: string;
+    message_id: string;
+    data: unknown;
+}
+export interface BatchDeleteMessageItem {
+    agent_id: string;
+    channel_name: string;
+    message_id: string;
+}
+/** Per-item outcome. `error` is present only when `success` is false. */
+export interface BatchResultItem {
+    agent_id: string;
+    channel_name: string;
+    success: boolean;
+    error?: string;
+}
+export interface BatchMessageResultItem extends BatchResultItem {
+    /** Present for creates — the server-generated ID when none was supplied. */
+    message_id?: string;
+}
+export interface BatchResponse<TItem extends BatchResultItem = BatchResultItem> {
+    /** Results in request order, one per submitted item. */
+    items: TItem[];
+    count: number;
+    succeeded: number;
+    failed: number;
+}
+export type BatchAggregateResponse = BatchResponse<BatchResultItem>;
+export type BatchMessageResponse = BatchResponse<BatchMessageResultItem>;
+/**
+ * Split `items` into server-acceptable chunks. Returns `[]` for an empty
+ * input, since an empty batch is a 400 rather than a no-op.
+ */
+export declare function chunkBatchItems<T>(items: T[], size?: number): T[][];
+/**
+ * Merge several batch responses into one, as if the whole set had been sent
+ * in a single request. Useful after chunking.
+ */
+export declare function mergeBatchResponses<TItem extends BatchResultItem>(responses: BatchResponse<TItem>[]): BatchResponse<TItem>;