doover-js 0.6.5 → 0.6.6

package/dist/apis/_args.js

@@ -2,25 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveChannelArgs = resolveChannelArgs;
 exports.resolveAgentArgs = resolveAgentArgs;
+const request_options_1 = require("../client/request-options");
 function resolveChannelArgs(args) {
     if (typeof args[0] === "string") {
+        const options = (0, request_options_1.isDooverRequestOptions)(args[2]) ? undefined : args[2];
         return {
             agentId: args[0],
             channelName: args[1],
-            options: args[2],
+            options: options,
         };
     }
     const id = args[0];
+    const options = (0, request_options_1.isDooverRequestOptions)(args[1]) ? undefined : args[1];
     return {
         agentId: id.agentId,
         channelName: id.channelName,
-        options: args[1],
+        options: options,
     };
 }
 function resolveAgentArgs(args) {
     if (typeof args[0] === "string") {
-        return { agentId: args[0], options: args[1] };
+        const options = (0, request_options_1.isDooverRequestOptions)(args[1]) ? undefined : args[1];
+        return { agentId: args[0], options: options };
     }
     const id = args[0];
-    return { agentId: id.agentId, options: args[1] };
+    const options = (0, request_options_1.isDooverRequestOptions)(args[1]) ? undefined : args[1];
+    return { agentId: id.agentId, options: options };
 }

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

@@ -1,6 +1,7 @@
 import type { AgentAggregate, BatchMessagesResponse } from "../types/openapi";
 import type { AgentsResponse, GetAgentsOptions } from "../types/viewer";
 import type { RestClient } from "../http/rest-client";
+import type { DooverRequestOptions } from "../client/request-options";
 export interface MultiAgentMessagesParams {
     agent_id: string[];
     /**
@@ -32,6 +33,8 @@ export declare class AgentsApi {
     private readonly controlApiUrl?;
     constructor(rest: RestClient, controlApiUrl?: string | undefined);
     listAgents(options?: GetAgentsOptions): Promise<AgentsResponse>;
+    listAgents(requestOptions?: DooverRequestOptions): Promise<AgentsResponse>;
+    listAgents(options?: GetAgentsOptions, requestOptions?: DooverRequestOptions): Promise<AgentsResponse>;
     /**
      * Batch-fetch recent messages for many agents. Auto-chunks `agent_id`
      * (and the parallel `agent_before` cursors, if given) at MULTI_AGENT_CHUNK_SIZE

package/dist/apis/agents-api.js

@@ -110,13 +110,14 @@ class AgentsApi {
         this.rest = rest;
         this.controlApiUrl = controlApiUrl;
     }
-    async listAgents(options) {
+    async listAgents(options, _requestOptions) {
+        const agentOptions = options;
         const query = {};
-        if (options?.includeArchived)
+        if (agentOptions?.includeArchived)
             query["include-archived"] = true;
-        if (options?.includeOrganisations)
+        if (agentOptions?.includeOrganisations)
             query["include-organisations"] = true;
-        if (options?.includeUsers)
+        if (agentOptions?.includeUsers)
             query["include-users"] = true;
         const raw = await this.rest.request({
             path: "/agents/",
@@ -126,18 +127,18 @@ class AgentsApi {
         });
         const rawAgents = Array.isArray(raw.agents) ? raw.agents : [];
         const normalizedAgents = rawAgents.map(normalizeAgentEntry);
-        if (!options?.mergeIncludedAsAgents) {
+        if (!agentOptions?.mergeIncludedAsAgents) {
             return { ...raw, agents: normalizedAgents };
         }
         const merged = [...normalizedAgents];
-        if (options.includeOrganisations) {
+        if (agentOptions.includeOrganisations) {
             const rawOrgs = Array.isArray(raw.organisations)
                 ? raw.organisations
                 : [];
             for (const org of rawOrgs)
                 merged.push(normalizeOrganisationEntry(org));
         }
-        if (options.includeUsers) {
+        if (agentOptions.includeUsers) {
             const rawUsers = Array.isArray(raw.users) ? raw.users : [];
             for (const user of rawUsers)
                 merged.push(normalizeUserEntry(user));

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

@@ -1,5 +1,6 @@
 import type { RestClient } from "../http/rest-client";
 import type { Aggregate } from "../types/openapi";
+import type { DooverRequestOptions } from "../client/request-options";
 export interface AggregateMutationParams {
     suppress_response?: boolean;
     clear_attachments?: boolean;
@@ -9,10 +10,15 @@ export declare class AggregatesApi {
     private readonly rest;
     constructor(rest: RestClient);
     getAggregate(agentId: string, channelName: string): Promise<Aggregate>;
+    getAggregate(agentId: string, channelName: string, requestOptions: DooverRequestOptions): Promise<Aggregate>;
     getAggregate(identifier: {
         agentId: string;
         channelName: string;
     }): Promise<Aggregate>;
+    getAggregate(identifier: {
+        agentId: string;
+        channelName: string;
+    }, requestOptions: DooverRequestOptions): Promise<Aggregate>;
     private _getAggregate;
     putAggregate(agentId: string, channelName: string, body: Record<string, unknown> | FormData, params?: AggregateMutationParams): Promise<Aggregate>;
     putAggregate(identifier: {
@@ -27,9 +33,14 @@ export declare class AggregatesApi {
     }, body: Record<string, unknown> | FormData, params?: AggregateMutationParams): Promise<Aggregate>;
     private _patchAggregate;
     getAggregateAttachment(agentId: string, channelName: string, attachmentId: string): Promise<Blob>;
+    getAggregateAttachment(agentId: string, channelName: string, attachmentId: string, requestOptions: DooverRequestOptions): Promise<Blob>;
     getAggregateAttachment(identifier: {
         agentId: string;
         channelName: string;
     }, attachmentId: string): Promise<Blob>;
+    getAggregateAttachment(identifier: {
+        agentId: string;
+        channelName: string;
+    }, attachmentId: string, requestOptions: DooverRequestOptions): Promise<Blob>;
     private _getAggregateAttachment;
 }

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

@@ -1,5 +1,6 @@
 import type { RestClient } from "../http/rest-client";
 import type { Channel, CreateChannelRequest, DataSeries, PutChannelRequest } from "../types/openapi";
+import type { DooverRequestOptions } from "../client/request-options";
 export interface ListChannelsOptions {
     include_aggregate?: boolean;
     include_daily_summaries?: boolean;
@@ -18,15 +19,33 @@ export declare class ChannelsApi {
     private readonly rest;
     constructor(rest: RestClient);
     listChannels(agentId: string, options?: ListChannelsOptions): Promise<Channel[]>;
+    listChannels(agentId: string, requestOptions: DooverRequestOptions): Promise<Channel[]>;
+    listChannels(agentId: string, options: ListChannelsOptions, requestOptions: DooverRequestOptions): Promise<Channel[]>;
     listChannels(identifier: {
         agentId: string;
     }, options?: ListChannelsOptions): Promise<Channel[]>;
+    listChannels(identifier: {
+        agentId: string;
+    }, requestOptions: DooverRequestOptions): Promise<Channel[]>;
+    listChannels(identifier: {
+        agentId: string;
+    }, options: ListChannelsOptions, requestOptions: DooverRequestOptions): Promise<Channel[]>;
     private _listChannels;
     getChannel(agentId: string, channelName: string, options?: GetChannelOptions): Promise<Channel>;
+    getChannel(agentId: string, channelName: string, requestOptions: DooverRequestOptions): Promise<Channel>;
+    getChannel(agentId: string, channelName: string, options: GetChannelOptions, requestOptions: DooverRequestOptions): Promise<Channel>;
     getChannel(identifier: {
         agentId: string;
         channelName: string;
     }, options?: GetChannelOptions): Promise<Channel>;
+    getChannel(identifier: {
+        agentId: string;
+        channelName: string;
+    }, requestOptions: DooverRequestOptions): Promise<Channel>;
+    getChannel(identifier: {
+        agentId: string;
+        channelName: string;
+    }, options: GetChannelOptions, requestOptions: DooverRequestOptions): Promise<Channel>;
     private _getChannel;
     createChannel(agentId: string, channelName: string, body: CreateChannelRequest): Promise<{
         id: string;

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

@@ -1,5 +1,6 @@
 import type { RestClient } from "../http/rest-client";
 import type { CreateMessageRequest, DataSeries, MessageStructure, UpdateMessageRequest } from "../types/openapi";
+import type { DooverRequestOptions } from "../client/request-options";
 export interface ListMessagesParams {
     before?: string;
     after?: string;
@@ -27,10 +28,15 @@ export declare class MessagesApi {
     private readonly rest;
     constructor(rest: RestClient);
     listMessages(agentId: string, channelName: string, params?: ListMessagesParams): Promise<MessageStructure[]>;
+    listMessages(agentId: string, channelName: string, params: ListMessagesParams, requestOptions: DooverRequestOptions): Promise<MessageStructure[]>;
     listMessages(identifier: {
         agentId: string;
         channelName: string;
     }, params?: ListMessagesParams): Promise<MessageStructure[]>;
+    listMessages(identifier: {
+        agentId: string;
+        channelName: string;
+    }, params: ListMessagesParams, requestOptions: DooverRequestOptions): Promise<MessageStructure[]>;
     private _listMessages;
     postMessage(agentId: string, channelName: string, body: MessageBody): Promise<MessageStructure>;
     postMessage(identifier: {

package/dist/client/errors.d.ts

@@ -21,3 +21,12 @@ export declare class AmbiguousWriteError extends DooverApiError {
     readonly candidateSourceIds: string[];
     constructor(capability: Capability, candidateSourceIds: string[]);
 }
+/**
+ * Thrown by offline-aware clients when a network-only operation is attempted
+ * while offline, or when an offline read has no usable cached value.
+ */
+export declare class DooverOfflineError extends DooverApiError {
+    readonly operation: string;
+    readonly cacheKey?: string;
+    constructor(operation: string, message?: string, cacheKey?: string);
+}

package/dist/client/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = void 0;
+exports.DooverOfflineError = exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = void 0;
 const errors_1 = require("../http/errors");
 /**
  * Thrown when a `DataClient` method is called whose backing capability the
@@ -48,3 +48,23 @@ class AmbiguousWriteError extends errors_1.DooverApiError {
     }
 }
 exports.AmbiguousWriteError = AmbiguousWriteError;
+/**
+ * Thrown by offline-aware clients when a network-only operation is attempted
+ * while offline, or when an offline read has no usable cached value.
+ */
+class DooverOfflineError extends errors_1.DooverApiError {
+    constructor(operation, message, cacheKey) {
+        super({
+            status: 0,
+            body: { operation, cacheKey },
+            url: "",
+            method: "",
+            message: message ?? `Operation "${operation}" is unavailable while offline.`,
+        });
+        this.name = "DooverOfflineError";
+        this.operation = operation;
+        this.cacheKey = cacheKey;
+        Object.setPrototypeOf(this, DooverOfflineError.prototype);
+    }
+}
+exports.DooverOfflineError = DooverOfflineError;

package/dist/client/offline-cache.d.ts

@@ -0,0 +1,162 @@
+import type { AgentScope, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client";
+import type { Capability } from "./capabilities";
+export declare const DEFAULT_OFFLINE_RETENTION_MS: number;
+export type OfflineCacheMode = "read-through" | "network-first" | "cache-first" | "cache-only";
+export interface OfflineReadCacheOptions {
+    enabled?: boolean;
+    mode?: OfflineCacheMode;
+    policy?: string;
+    retentionMs?: number;
+    allowExpired?: boolean;
+}
+export interface OfflineChannelPolicy {
+    id?: string;
+    channel: {
+        agentId?: string;
+        channelName: string;
+    };
+    cache?: boolean;
+    retentionMs?: number;
+    messages?: {
+        mode?: "latest";
+        count?: number;
+    };
+    messageAttachments?: {
+        include?: "none" | "metadata-only" | "metadata-and-selected-blobs";
+    };
+    aggregateAttachments?: {
+        include?: "none" | "metadata-only" | "metadata-and-selected-blobs";
+    };
+}
+export interface OfflineCacheScope {
+    userId: string;
+    organisationId?: string | null;
+    sourceId?: string;
+    sharing?: string;
+    assumeUserId?: string | null;
+}
+export interface OfflineCacheRecord<T = unknown> {
+    key: string;
+    scope: OfflineCacheScope;
+    kind: string;
+    value: T;
+    cachedAt: number;
+    lastAccessedAt: number;
+    expiresAt: number | null;
+    serverUpdatedAt?: number | null;
+    schemaVersion: number;
+    policyId?: string;
+}
+export type OfflineReadState = "online" | "cache-fallback" | "cache-hit" | "cache-miss" | "expired";
+export interface OfflineStatusSnapshot {
+    online: boolean;
+    state: OfflineReadState;
+    operation?: string;
+    cacheKey?: string;
+    cachedAt?: number;
+    expiresAt?: number | null;
+    serverUpdatedAt?: number | null;
+    isOfflineFallback: boolean;
+    isExpired: boolean;
+    at: number;
+}
+export interface OfflineStorageAdapter {
+    getJson<T>(key: string): Promise<OfflineCacheRecord<T> | undefined>;
+    setJson<T>(key: string, record: OfflineCacheRecord<T>): Promise<void>;
+    deleteJson?(key: string): Promise<void>;
+    listJsonKeys?(prefix?: string): Promise<string[]>;
+    clearScope?(scope: OfflineCacheScope): Promise<void>;
+    getBlob?(key: string): Promise<Blob | undefined>;
+    setBlob?(key: string, blob: Blob, metadata: OfflineCacheRecord): Promise<void>;
+    deleteBlob?(key: string): Promise<void>;
+}
+export declare class MemoryOfflineStorageAdapter implements OfflineStorageAdapter {
+    private readonly json;
+    private readonly blobs;
+    getJson<T>(key: string): Promise<OfflineCacheRecord<T> | undefined>;
+    setJson<T>(key: string, record: OfflineCacheRecord<T>): Promise<void>;
+    deleteJson(key: string): Promise<void>;
+    listJsonKeys(prefix?: string): Promise<string[]>;
+    clearScope(scope: OfflineCacheScope): Promise<void>;
+    getBlob(key: string): Promise<Blob | undefined>;
+    setBlob(key: string, blob: Blob, metadata: OfflineCacheRecord): Promise<void>;
+    deleteBlob(key: string): Promise<void>;
+}
+export interface OfflineDataClientOptions {
+    client: DataClient;
+    storage: OfflineStorageAdapter;
+    scope: OfflineCacheScope;
+    policies?: OfflineChannelPolicy[];
+    defaultRetentionMs?: number;
+    /**
+     * Apps may provide their own reachability signal. When omitted, the wrapper
+     * uses `navigator.onLine` when present and otherwise assumes online.
+     */
+    isOnline?: () => boolean;
+}
+export declare class OfflineDataClient implements DataClient {
+    readonly agents: AgentsApiLike;
+    readonly channels: ChannelsApiLike;
+    readonly messages: MessagesApiLike;
+    readonly aggregates: AggregatesApiLike;
+    readonly alarms: AlarmsApiLike;
+    readonly connections: ConnectionsApiLike;
+    readonly notifications: NotificationsApiLike;
+    readonly permissions: PermissionsApiLike;
+    readonly processors: ProcessorsApiLike;
+    readonly turn: TurnApiLike;
+    readonly users: UsersApiLike;
+    readonly gateway: GatewayClientLike;
+    readonly rpc: RpcDispatcherLike;
+    private readonly client;
+    private readonly storage;
+    private readonly scope;
+    private readonly defaultRetentionMs;
+    private readonly isOnlineFn?;
+    private readonly offlineStatusListeners;
+    private policies;
+    private offlineStatus;
+    private persistQueue;
+    constructor(options: OfflineDataClientOptions);
+    setChannelPolicy(policy: OfflineChannelPolicy): void;
+    setChannelPolicies(policies: OfflineChannelPolicy[]): void;
+    getChannelPolicies(): readonly OfflineChannelPolicy[];
+    getOfflineStatus(): OfflineStatusSnapshot;
+    onOfflineStatusChange(listener: (status: OfflineStatusSnapshot) => void): () => void;
+    clearScope(scope?: OfflineCacheScope): Promise<void>;
+    getCapabilities(): ReadonlySet<Capability>;
+    supports(cap: Capability): boolean;
+    isConnected(): boolean;
+    getStatus(): DataClientStatus;
+    onStatusChange(listener: (status: DataClientStatus) => void): () => void;
+    getAgentScope(): Promise<AgentScope>;
+    getKnownAgentScope(): AgentScope | "unknown";
+    private makeAgentsFacade;
+    private makeChannelsFacade;
+    private makeAggregatesFacade;
+    private makeMessagesFacade;
+    private makeGatewayFacade;
+    private makeRpcFacade;
+    private passThroughSubclient;
+    private offlineGuard;
+    private readCached;
+    private readBlobCached;
+    private readRecord;
+    private tryReadRecord;
+    private writeRecord;
+    private writePolicyDerivedRecords;
+    private writeLatestMessagesRecord;
+    private mergeLatestMessage;
+    private persistGatewayMessage;
+    private persistGatewayAggregate;
+    private effectivePolicy;
+    private matchPolicy;
+    private shouldCacheAttachmentBlob;
+    private withDelegateOptions;
+    private cacheKey;
+    private latestMessagesKeyParts;
+    private scopePrefix;
+    private isOnline;
+    private setOfflineStatus;
+    private enqueuePersist;
+}