doover-js 0.8.0 → 0.8.1

package/dist/apis/agents-api.d.ts

@@ -19,6 +19,65 @@ export interface MultiAgentMessagesParams {
     agent_message_limit?: number;
     field_name?: string[];
 }
+/**
+ * One token-posture knob across all three layers, so a UI can show
+ * "inherited from organisation" vs "overridden on this device" and offer a reset
+ * without duplicating the precedence rule client-side.
+ */
+export interface TokenPolicyField<T> {
+    /** What is actually enforced: `agent_override` if set, else `org_default`. */
+    effective: T | null;
+    /** This device's override. `null` means it inherits. */
+    agent_override: T | null;
+    /** The organisation-wide default inherited when not overridden. */
+    org_default: T | null;
+}
+export interface AgentTokenState {
+    /**
+     * Unix-ms revocation floor: every long-lived credential issued before this is
+     * rejected. `null` means nothing has ever been revoked for this agent.
+     */
+    tokens_valid_from: number | null;
+    /** Auth kill-switch — while true, every auth attempt is rejected. */
+    auth_locked: boolean;
+    self_rotation: TokenPolicyField<boolean>;
+    max_age_ms: TokenPolicyField<number>;
+    reuse_grace_ms: TokenPolicyField<number>;
+}
+/**
+ * A token-posture override. `null` on any field means "inherit the organisation
+ * default"; there is no way to express "explicitly off, ignoring the default",
+ * because every knob here is off when absent.
+ */
+export interface AgentTokenPolicy {
+    /** Allow the device to trade its own credential for a fresh one. */
+    self_rotation?: boolean | null;
+    /**
+     * Hard maximum credential age. Only valid alongside `self_rotation` — without
+     * it the device cannot rotate before the deadline and will be locked out.
+     */
+    max_age_ms?: number | null;
+    /**
+     * Grace window after a rotation before a stale credential counts as reuse.
+     * Setting this opts the device into *automatic* lockout on reuse detection.
+     */
+    reuse_grace_ms?: number | null;
+}
+export interface ResourcePermission {
+    permission_id: string;
+    permission: string;
+}
+export interface AdhocTokenResponse {
+    /** Shown once. Not retrievable afterwards. */
+    token: string;
+    token_id: string | null;
+}
+export interface DeviceTokenResponse {
+    /** Shown once. Not stored anywhere and not retrievable afterwards. */
+    token: string;
+    /** Unix-ms issuance time, which is what the revocation floor compares against. */
+    issued_at_ms: number | null;
+}
 export interface MultiAgentAggregatesParams {
     agent_id: string[];
     /**
@@ -56,4 +115,82 @@ export declare class AgentsApi {
         results: AgentAggregate[];
         count: number;
     }>;
+    /**
+     * Read an agent's credential state: the revocation floor, the auth
+     * kill-switch, and the token posture resolved across the per-agent override
+     * and the organisation default.
+     *
+     * Requires `AgentTokenRead`, which is read-only — a caller can display
+     * credential state (including an auth-lock banner, often the only explanation
+     * for why a device is offline) without being able to change any of it.
+     */
+    getTokenState(agentId: string): Promise<AgentTokenState>;
+    /**
+     * Replace an agent's token-posture override. Omitted or null fields mean
+     * "inherit the organisation default" — a full replacement rather than a
+     * merge, so clearing an override back to inherited is expressible.
+     *
+     * Rejected server-side if the resolved posture sets `max_age_ms` without
+     * `self_rotation`: a device that can't self-rotate has no way to trade its
+     * token in before the max age elapses, making that combination a scheduled
+     * outage.
+     */
+    setTokenPolicy(agentId: string, policy: AgentTokenPolicy): Promise<{
+        effective: AgentTokenPolicy;
+    }>;
+    /**
+     * Set or clear the auth kill-switch. While locked, every auth attempt for the
+     * agent is rejected regardless of token validity.
+     *
+     * doover-data sets this automatically on suspected token reuse, so clearing it
+     * is a routine incident-response action rather than an exotic one.
+     */
+    setAuthLock(agentId: string, locked: boolean): Promise<void>;
+    /**
+     * Revoke every outstanding long-lived credential for an agent by advancing the
+     * revocation floor. Mints nothing.
+     *
+     * This takes the device offline until it is re-provisioned. Break-glass:
+     * confirm before calling.
+     */
+    revokeAllTokens(agentId: string): Promise<{
+        tokens_valid_from: number;
+    }>;
+    /**
+     * Set the revocation floor to an explicit point, in either direction. `0` or
+     * `null` clears it.
+     *
+     * `revokeAllTokens` is the normal way to revoke. Lowering the floor reverses a
+     * revocation, so it is for undoing one made by mistake — not for recovering
+     * from a leak, where you should issue fresh credentials instead.
+     */
+    setRevocationFloor(agentId: string, tokensValidFrom: number | null): Promise<{
+        tokens_valid_from: number | null;
+    }>;
+    /**
+     * Mint a short-lived scoped JWT for ad-hoc access to an agent — debugging, a
+     * one-off script, an integration.
+     *
+     * This is the way to give a *person* access to a device. The device's own
+     * long-lived credential is deliberately not obtainable through the API: it is
+     * minted into an installer bundle and never shown. Expiry stands in for
+     * revocation here, so keep `timeout` as short as the task allows.
+     */
+    createAdhocToken(agentId: string, options?: {
+        permissions?: ResourcePermission[];
+        timeout?: number;
+    }): Promise<AdhocTokenResponse>;
+    /**
+     * Mint the device's long-lived credential and return it once, for manual
+     * provisioning — pasting into a device's config by hand. The installer download
+     * mints one into the bundle for you; this is the equivalent for a device you're
+     * configuring yourself.
+     *
+     * Always additive: the revocation floor is left alone, so minting can never
+     * knock a running device offline. `revoke_existing` is intentionally not
+     * exposed here — revoking is `revokeAllTokens`, a separate deliberate act.
+     *
+     * Returned once and stored nowhere. If it's lost, mint another.
+     */
+    createDeviceToken(agentId: string): Promise<DeviceTokenResponse>;
 }

package/dist/apis/agents-api.js

@@ -232,6 +232,96 @@ class AgentsApi {
             count: responses.reduce((acc, r) => acc + r.count, 0),
         };
     }
+    /**
+     * Read an agent's credential state: the revocation floor, the auth
+     * kill-switch, and the token posture resolved across the per-agent override
+     * and the organisation default.
+     *
+     * Requires `AgentTokenRead`, which is read-only — a caller can display
+     * credential state (including an auth-lock banner, often the only explanation
+     * for why a device is offline) without being able to change any of it.
+     */
+    getTokenState(agentId) {
+        return this.rest.get(`/agents/${agentId}/token_state`);
+    }
+    /**
+     * Replace an agent's token-posture override. Omitted or null fields mean
+     * "inherit the organisation default" — a full replacement rather than a
+     * merge, so clearing an override back to inherited is expressible.
+     *
+     * Rejected server-side if the resolved posture sets `max_age_ms` without
+     * `self_rotation`: a device that can't self-rotate has no way to trade its
+     * token in before the max age elapses, making that combination a scheduled
+     * outage.
+     */
+    setTokenPolicy(agentId, policy) {
+        return this.rest.put(`/agents/${agentId}/token_policy`, policy);
+    }
+    /**
+     * Set or clear the auth kill-switch. While locked, every auth attempt for the
+     * agent is rejected regardless of token validity.
+     *
+     * doover-data sets this automatically on suspected token reuse, so clearing it
+     * is a routine incident-response action rather than an exotic one.
+     */
+    setAuthLock(agentId, locked) {
+        return this.rest.post(`/agents/${agentId}/auth_lock`, { locked });
+    }
+    /**
+     * Revoke every outstanding long-lived credential for an agent by advancing the
+     * revocation floor. Mints nothing.
+     *
+     * This takes the device offline until it is re-provisioned. Break-glass:
+     * confirm before calling.
+     */
+    revokeAllTokens(agentId) {
+        return this.rest.post(`/agents/${agentId}/token/revoke_all`, {});
+    }
+    /**
+     * Set the revocation floor to an explicit point, in either direction. `0` or
+     * `null` clears it.
+     *
+     * `revokeAllTokens` is the normal way to revoke. Lowering the floor reverses a
+     * revocation, so it is for undoing one made by mistake — not for recovering
+     * from a leak, where you should issue fresh credentials instead.
+     */
+    setRevocationFloor(agentId, tokensValidFrom) {
+        return this.rest.post(`/agents/${agentId}/token/floor`, { tokens_valid_from: tokensValidFrom });
+    }
+    /**
+     * Mint a short-lived scoped JWT for ad-hoc access to an agent — debugging, a
+     * one-off script, an integration.
+     *
+     * This is the way to give a *person* access to a device. The device's own
+     * long-lived credential is deliberately not obtainable through the API: it is
+     * minted into an installer bundle and never shown. Expiry stands in for
+     * revocation here, so keep `timeout` as short as the task allows.
+     */
+    createAdhocToken(agentId, options = {}) {
+        return this.rest.post(`/agents/${agentId}/token`, {
+            format: "jwt",
+            permissions: options.permissions ?? [],
+            timeout: options.timeout,
+        });
+    }
+    /**
+     * Mint the device's long-lived credential and return it once, for manual
+     * provisioning — pasting into a device's config by hand. The installer download
+     * mints one into the bundle for you; this is the equivalent for a device you're
+     * configuring yourself.
+     *
+     * Always additive: the revocation floor is left alone, so minting can never
+     * knock a running device offline. `revoke_existing` is intentionally not
+     * exposed here — revoking is `revokeAllTokens`, a separate deliberate act.
+     *
+     * Returned once and stored nowhere. If it's lost, mint another.
+     */
+    createDeviceToken(agentId) {
+        return this.rest.post(`/agents/${agentId}/token`, {
+            format: "mini_v1",
+            revoke_existing: false,
+        });
+    }
 }
 exports.AgentsApi = AgentsApi;
 // CloudFront fronts the channels-rest API with a hard 8,192-byte URL quota.

package/dist/client/capabilities.d.ts

@@ -6,5 +6,5 @@
  * String-literal union (not a TS enum) so values serialise cleanly and can
  * appear in error messages / debug UIs verbatim.
  */
-export type Capability = "agents.list" | "agents.multiAgentMessages" | "agents.multiAgentAggregates" | "channels.list" | "channels.get" | "channels.create" | "channels.archive" | "channels.dataSeries" | "aggregates.get" | "aggregates.put" | "aggregates.patch" | "aggregates.attachment" | "messages.list" | "messages.listHistorical" | "messages.get" | "messages.post" | "messages.put" | "messages.delete" | "messages.attachment" | "messages.timeseries" | "messages.invocationLogs" | "gateway.subscribe" | "gateway.realtime" | "gateway.oneShot" | "rpc.send" | "alarms.read" | "alarms.write" | "connections.read" | "connections.write" | "notifications.read" | "notifications.write" | "permissions.read" | "permissions.write" | "processors.read" | "processors.write" | "turn.credentials" | "users.me";
+export type Capability = "agents.list" | "agents.multiAgentMessages" | "agents.multiAgentAggregates" | "agents.tokenRead" | "agents.tokenManage" | "channels.list" | "channels.get" | "channels.create" | "channels.archive" | "channels.dataSeries" | "aggregates.get" | "aggregates.put" | "aggregates.patch" | "aggregates.attachment" | "messages.list" | "messages.listHistorical" | "messages.get" | "messages.post" | "messages.put" | "messages.delete" | "messages.attachment" | "messages.timeseries" | "messages.invocationLogs" | "gateway.subscribe" | "gateway.realtime" | "gateway.oneShot" | "rpc.send" | "alarms.read" | "alarms.write" | "connections.read" | "connections.write" | "notifications.read" | "notifications.write" | "permissions.read" | "permissions.write" | "processors.read" | "processors.write" | "turn.credentials" | "users.me";
 export declare const ALL_CAPABILITIES: readonly Capability[];

package/dist/client/capabilities.js

@@ -5,6 +5,8 @@ exports.ALL_CAPABILITIES = [
     "agents.list",
     "agents.multiAgentMessages",
     "agents.multiAgentAggregates",
+    "agents.tokenRead",
+    "agents.tokenManage",
     "channels.list",
     "channels.get",
     "channels.create",

package/dist/client/local-agent-client.js

@@ -183,6 +183,13 @@ const METHOD_TO_CAPABILITY = {
     "agents.listAgents": "agents.list",
     "agents.getMultiAgentMessages": "agents.multiAgentMessages",
     "agents.getMultiAgentAggregates": "agents.multiAgentAggregates",
+    "agents.getTokenState": "agents.tokenRead",
+    "agents.setTokenPolicy": "agents.tokenManage",
+    "agents.setAuthLock": "agents.tokenManage",
+    "agents.revokeAllTokens": "agents.tokenManage",
+    "agents.setRevocationFloor": "agents.tokenManage",
+    "agents.createAdhocToken": "agents.tokenManage",
+    "agents.createDeviceToken": "agents.tokenManage",
     "channels.listChannels": "channels.list",
     "channels.getChannel": "channels.get",
     "channels.createChannel": "channels.create",

package/dist/client/multiplex-client.js

@@ -660,6 +660,13 @@ class MultiplexClient {
                 const merged = (0, multiplex_merge_1.dedupeBy)([].concat(...responses.map((r) => r.results)), (a) => a.agent_id);
                 return { results: merged, count: merged.length };
             },
+            getTokenState: self.makeFanoutFirst("agents.getTokenState", "agents.tokenRead"),
+            setTokenPolicy: self.routedWrite("agents.setTokenPolicy", "agents.tokenManage"),
+            setAuthLock: self.routedWrite("agents.setAuthLock", "agents.tokenManage"),
+            revokeAllTokens: self.routedWrite("agents.revokeAllTokens", "agents.tokenManage"),
+            setRevocationFloor: self.routedWrite("agents.setRevocationFloor", "agents.tokenManage"),
+            createAdhocToken: self.routedWrite("agents.createAdhocToken", "agents.tokenManage"),
+            createDeviceToken: self.routedWrite("agents.createDeviceToken", "agents.tokenManage"),
         };
     }
     // ===== non-core generic facade =====

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { getDooverClient, peekDooverClient, resetDooverClient, } from "./client/
 export { DooverStatsCollector } from "./client/stats";
 export type { DooverStatsSnapshot, RestStatsSnapshot, GatewayStatsSnapshot, } from "./client/stats";
 export { AgentsApi } from "./apis/agents-api";
+export type { AgentTokenState, AgentTokenPolicy, TokenPolicyField, AdhocTokenResponse, DeviceTokenResponse, ResourcePermission, } from "./apis/agents-api";
 export { AggregatesApi } from "./apis/aggregates-api";
 export { AlarmsApi } from "./apis/alarms-api";
 export { ChannelsApi } from "./apis/channels-api";

package/dist/react/index.d.ts

@@ -33,4 +33,6 @@ export type { UseMultiAgentChannelMessagesOptions, UseMultiAgentChannelMessagesR
 export { useDeviceMap } from "./useDeviceMap";
 export type { DeviceMapEntry, UseDeviceMapOptions, UseDeviceMapResult, } from "./useDeviceMap";
 export { useTurnCredentials } from "./useTurnCredentials";
+export { useAgentTokenState, useSetAgentTokenPolicy, useSetAgentAuthLock, useRevokeAgentTokens, useSetRevocationFloor, useCreateAdhocToken, useCreateDeviceToken, agentTokenStateQueryKey, } from "./useAgentTokenState";
+export type { UseAgentTokenStateOptions } from "./useAgentTokenState";
 export { getSharedQueryClient, resetSharedQueryClient, } from "./sharedQueryClient";

package/dist/react/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.hasOfflineStatus = exports.useOfflineStatus = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
+exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.agentTokenStateQueryKey = exports.useCreateDeviceToken = exports.useCreateAdhocToken = exports.useSetRevocationFloor = exports.useRevokeAgentTokens = exports.useSetAgentAuthLock = exports.useSetAgentTokenPolicy = exports.useAgentTokenState = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.hasOfflineStatus = exports.useOfflineStatus = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "DooverProvider", { enumerable: true, get: function () { return context_1.DooverProvider; } });
 Object.defineProperty(exports, "useDooverClient", { enumerable: true, get: function () { return context_1.useDooverClient; } });
@@ -48,6 +48,15 @@ var useDeviceMap_1 = require("./useDeviceMap");
 Object.defineProperty(exports, "useDeviceMap", { enumerable: true, get: function () { return useDeviceMap_1.useDeviceMap; } });
 var useTurnCredentials_1 = require("./useTurnCredentials");
 Object.defineProperty(exports, "useTurnCredentials", { enumerable: true, get: function () { return useTurnCredentials_1.useTurnCredentials; } });
+var useAgentTokenState_1 = require("./useAgentTokenState");
+Object.defineProperty(exports, "useAgentTokenState", { enumerable: true, get: function () { return useAgentTokenState_1.useAgentTokenState; } });
+Object.defineProperty(exports, "useSetAgentTokenPolicy", { enumerable: true, get: function () { return useAgentTokenState_1.useSetAgentTokenPolicy; } });
+Object.defineProperty(exports, "useSetAgentAuthLock", { enumerable: true, get: function () { return useAgentTokenState_1.useSetAgentAuthLock; } });
+Object.defineProperty(exports, "useRevokeAgentTokens", { enumerable: true, get: function () { return useAgentTokenState_1.useRevokeAgentTokens; } });
+Object.defineProperty(exports, "useSetRevocationFloor", { enumerable: true, get: function () { return useAgentTokenState_1.useSetRevocationFloor; } });
+Object.defineProperty(exports, "useCreateAdhocToken", { enumerable: true, get: function () { return useAgentTokenState_1.useCreateAdhocToken; } });
+Object.defineProperty(exports, "useCreateDeviceToken", { enumerable: true, get: function () { return useAgentTokenState_1.useCreateDeviceToken; } });
+Object.defineProperty(exports, "agentTokenStateQueryKey", { enumerable: true, get: function () { return useAgentTokenState_1.agentTokenStateQueryKey; } });
 var sharedQueryClient_1 = require("./sharedQueryClient");
 Object.defineProperty(exports, "getSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_1.getSharedQueryClient; } });
 Object.defineProperty(exports, "resetSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_1.resetSharedQueryClient; } });

package/dist/react/useAgentTokenState.d.ts

@@ -0,0 +1,70 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { AgentTokenPolicy, AgentTokenState, ResourcePermission } from "../apis/agents-api";
+export declare function agentTokenStateQueryKey(agentId: string | undefined): readonly ["doover", "agent", string | null, "tokenState"];
+export interface UseAgentTokenStateOptions {
+    enabled?: boolean;
+    staleTime?: number;
+}
+/**
+ * Read an agent's credential state — revocation floor, auth kill-switch, and the
+ * token posture resolved across the per-agent override and organisation default.
+ *
+ * Deliberately short `staleTime`: `auth_locked` can be flipped by doover-data
+ * itself (automatic lockout on suspected token reuse), so this value changes
+ * without any action from this client. Showing a stale "not locked" on the one
+ * screen someone opens *because* their device went offline would be worse than
+ * an extra fetch.
+ */
+export declare function useAgentTokenState(agentId: string | undefined, options?: UseAgentTokenStateOptions): UseQueryResult<AgentTokenState>;
+/**
+ * Write an agent's token-posture override. Full replacement — a null field means
+ * "inherit the organisation default".
+ *
+ * Invalidates the token-state query on success so the inherited-vs-overridden
+ * display reflects the write without the caller wiring that up.
+ */
+export declare function useSetAgentTokenPolicy(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    effective: AgentTokenPolicy;
+}, Error, AgentTokenPolicy, unknown>;
+/** Set or clear the auth kill-switch. */
+export declare function useSetAgentAuthLock(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<void, Error, boolean, unknown>;
+/**
+ * Mint a short-lived scoped token for ad-hoc access to an agent.
+ *
+ * Does not invalidate the token-state query: an ad-hoc token is a JWT with its
+ * own expiry and doesn't touch the revocation floor or the agent's posture, so
+ * there is nothing in that query for it to change.
+ *
+ * The resulting token is returned once and is not retrievable afterwards — hand
+ * it straight to the user and don't cache it.
+ */
+export declare function useCreateAdhocToken(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<import("../apis/agents-api").AdhocTokenResponse, Error, {
+    permissions?: ResourcePermission[];
+    timeout?: number;
+}, unknown>;
+/**
+ * Set the revocation floor to an explicit point; pass `0` or `null` to clear it.
+ *
+ * Lowering it reverses a revocation, so this is for undoing one made by mistake
+ * rather than for recovering a device whose credentials leaked.
+ */
+export declare function useSetRevocationFloor(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    tokens_valid_from: number | null;
+}, Error, number | null, unknown>;
+/**
+ * Mint the device's long-lived credential for manual provisioning, returned once.
+ *
+ * Invalidates the token-state query so the revocation floor display stays honest
+ * — the mint itself is additive and doesn't move the floor, but refetching keeps
+ * this in step with anything else that has changed since the panel loaded.
+ */
+export declare function useCreateDeviceToken(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<import("../apis/agents-api").DeviceTokenResponse, Error, void, unknown>;
+/**
+ * Revoke every outstanding long-lived credential for an agent.
+ *
+ * Break-glass: the device stays offline until it is re-provisioned. Confirm with
+ * the user before calling.
+ */
+export declare function useRevokeAgentTokens(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    tokens_valid_from: number;
+}, Error, void, unknown>;

package/dist/react/useAgentTokenState.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentTokenStateQueryKey = agentTokenStateQueryKey;
+exports.useAgentTokenState = useAgentTokenState;
+exports.useSetAgentTokenPolicy = useSetAgentTokenPolicy;
+exports.useSetAgentAuthLock = useSetAgentAuthLock;
+exports.useCreateAdhocToken = useCreateAdhocToken;
+exports.useSetRevocationFloor = useSetRevocationFloor;
+exports.useCreateDeviceToken = useCreateDeviceToken;
+exports.useRevokeAgentTokens = useRevokeAgentTokens;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+function agentTokenStateQueryKey(agentId) {
+    return ["doover", "agent", agentId ?? null, "tokenState"];
+}
+/**
+ * Read an agent's credential state — revocation floor, auth kill-switch, and the
+ * token posture resolved across the per-agent override and organisation default.
+ *
+ * Deliberately short `staleTime`: `auth_locked` can be flipped by doover-data
+ * itself (automatic lockout on suspected token reuse), so this value changes
+ * without any action from this client. Showing a stale "not locked" on the one
+ * screen someone opens *because* their device went offline would be worse than
+ * an extra fetch.
+ */
+function useAgentTokenState(agentId, options) {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_query_1.useQuery)({
+        queryKey: agentTokenStateQueryKey(agentId),
+        enabled: (options?.enabled ?? true) && Boolean(agentId),
+        staleTime: options?.staleTime ?? 15 * 1000,
+        queryFn: () => client.agents.getTokenState(agentId),
+    });
+}
+/**
+ * Write an agent's token-posture override. Full replacement — a null field means
+ * "inherit the organisation default".
+ *
+ * Invalidates the token-state query on success so the inherited-vs-overridden
+ * display reflects the write without the caller wiring that up.
+ */
+function useSetAgentTokenPolicy(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (policy) => client.agents.setTokenPolicy(agentId, policy),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/** Set or clear the auth kill-switch. */
+function useSetAgentAuthLock(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (locked) => client.agents.setAuthLock(agentId, locked),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Mint a short-lived scoped token for ad-hoc access to an agent.
+ *
+ * Does not invalidate the token-state query: an ad-hoc token is a JWT with its
+ * own expiry and doesn't touch the revocation floor or the agent's posture, so
+ * there is nothing in that query for it to change.
+ *
+ * The resulting token is returned once and is not retrievable afterwards — hand
+ * it straight to the user and don't cache it.
+ */
+function useCreateAdhocToken(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (options) => client.agents.createAdhocToken(agentId, options),
+    });
+}
+/**
+ * Set the revocation floor to an explicit point; pass `0` or `null` to clear it.
+ *
+ * Lowering it reverses a revocation, so this is for undoing one made by mistake
+ * rather than for recovering a device whose credentials leaked.
+ */
+function useSetRevocationFloor(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (tokensValidFrom) => client.agents.setRevocationFloor(agentId, tokensValidFrom),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Mint the device's long-lived credential for manual provisioning, returned once.
+ *
+ * Invalidates the token-state query so the revocation floor display stays honest
+ * — the mint itself is additive and doesn't move the floor, but refetching keeps
+ * this in step with anything else that has changed since the panel loaded.
+ */
+function useCreateDeviceToken(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: () => client.agents.createDeviceToken(agentId),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Revoke every outstanding long-lived credential for an agent.
+ *
+ * Break-glass: the device stays offline until it is re-provisioned. Confirm with
+ * the user before calling.
+ */
+function useRevokeAgentTokens(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: () => client.agents.revokeAllTokens(agentId),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",