@copilotz/admin 0.9.33 → 0.9.34

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import React, { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
 
 type RequestHeadersProvider = () => Record<string, string> | Promise<Record<string, string>>;
 type AdminDatePreset = "24h" | "7d" | "30d";
@@ -7,12 +8,7 @@ type AdminUsageInterval = "minute" | "hour" | "day" | "week" | "month";
 type AdminUsageMetricKind = "tokens" | "cost" | "calls";
 type AdminUsageGroupBy = "thread" | "participant" | "namespace" | "provider" | "model";
 type AdminUsageAttribution = "generatedBy" | "initiatedBy";
-type AdminPage = "dashboard" | "threads" | "thread-detail" | "participants" | "participant-detail" | "agents" | "agent-detail" | "collection-items" | "collection-item-detail" | "events";
-interface AdminRoute {
-    page: AdminPage;
-    resourceId?: string;
-    collection?: string;
-}
+type AdminUsageDimension = "total" | "input" | "output" | "reasoning" | "cacheRead" | "cacheWrite";
 interface AdminUsageBreakdown {
     inputTokens: number;
     outputTokens: number;
@@ -85,6 +81,18 @@ interface AdminParticipantSummary {
     threadCount: number;
     lastActivityAt: string | null;
 }
+interface AdminAgentSummary extends AdminUsageTotals {
+    agentId: string;
+    displayName: string;
+    description: string | null;
+    isConfigured: boolean;
+    namespace: string;
+    isGlobal: boolean;
+    messageCount: number;
+    llmCallCount: number;
+    toolCallMessageCount: number;
+    lastActivityAt: string | null;
+}
 interface AdminUsagePoint extends AdminUsageTotals {
     bucket: string;
     groupKey: string;
@@ -109,30 +117,6 @@ interface AdminUsageFilters {
     provider?: string;
     model?: string;
 }
-interface AdminAgentSummary {
-    agentId: string;
-    displayName: string;
-    description: string | null;
-    isConfigured: boolean;
-    namespace: string;
-    isGlobal: boolean;
-    messageCount: number;
-    llmCallCount: number;
-    toolCallMessageCount: number;
-    inputTokens: AdminUsageBreakdown["inputTokens"];
-    outputTokens: AdminUsageBreakdown["outputTokens"];
-    reasoningTokens: AdminUsageBreakdown["reasoningTokens"];
-    cacheReadInputTokens: AdminUsageBreakdown["cacheReadInputTokens"];
-    cacheCreationInputTokens: AdminUsageBreakdown["cacheCreationInputTokens"];
-    totalTokens: AdminUsageBreakdown["totalTokens"];
-    inputCostUsd: AdminUsageBreakdown["inputCostUsd"];
-    outputCostUsd: AdminUsageBreakdown["outputCostUsd"];
-    reasoningCostUsd: AdminUsageBreakdown["reasoningCostUsd"];
-    cacheReadInputCostUsd: AdminUsageBreakdown["cacheReadInputCostUsd"];
-    cacheCreationInputCostUsd: AdminUsageBreakdown["cacheCreationInputCostUsd"];
-    totalCostUsd: AdminUsageBreakdown["totalCostUsd"];
-    lastActivityAt: string | null;
-}
 interface AdminThreadDetail {
     id: string;
     name: string;
@@ -173,7 +157,17 @@ interface AdminMessagePage {
 type AdminParticipantDetail = Record<string, unknown>;
 type AdminCollectionItem = Record<string, unknown> & {
     id?: string;
+    _id?: string;
 };
+interface AdminCollectionPage {
+    data: AdminCollectionItem[];
+    pageInfo?: {
+        hasNextPage?: boolean;
+        hasPreviousPage?: boolean;
+        startCursor?: string | null;
+        endCursor?: string | null;
+    };
+}
 interface AdminQueueEvent {
     id: string;
     threadId: string;
@@ -188,164 +182,277 @@ interface AdminQueueEvent {
     createdAt: string | null;
     updatedAt: string | null;
 }
-interface AdminFilters {
-    namespace?: string;
-    range?: AdminDatePreset;
-    interval?: AdminActivityInterval;
-    threadSearch?: string;
-    participantSearch?: string;
-    agentSearch?: string;
+
+interface AdminClientPaths {
+    adminBase: string;
+    collectionsBase: string;
+    threadsBase: string;
 }
-interface AdminConfig {
-    branding?: {
-        title?: string;
-        subtitle?: string;
-        logo?: ReactNode;
-        actions?: ReactNode;
-    };
-    labels?: {
-        overviewTitle?: string;
-        activityTitle?: string;
-        threadsTitle?: string;
-        participantsTitle?: string;
-        agentsTitle?: string;
-        range24h?: string;
-        range7d?: string;
-        range30d?: string;
-        intervalHour?: string;
-        intervalDay?: string;
-        refresh?: string;
-        retry?: string;
-        loading?: string;
-        emptyTitle?: string;
-        emptyDescription?: string;
-        threadSearchPlaceholder?: string;
-        participantSearchPlaceholder?: string;
-        agentSearchPlaceholder?: string;
-        messagesCard?: string;
-        activeThreadsCard?: string;
-        participantsCard?: string;
-        tokensCard?: string;
-        costCard?: string;
-        queueCard?: string;
-        llmUsageTitle?: string;
-        usageMetricLabel?: string;
-        usageDimensionLabel?: string;
-        usageMetricTokens?: string;
-        usageMetricCost?: string;
-        usageTotal?: string;
-        usageInput?: string;
-        usageOutput?: string;
-        usageReasoning?: string;
-        usageCacheRead?: string;
-        usageCacheWrite?: string;
-        usageCallsDetail?: string;
-        usageUnavailableDetail?: string;
-        statusActive?: string;
-        statusArchived?: string;
-        scopeGlobal?: string;
-        scopeScoped?: string;
-        configured?: string;
-        unconfigured?: string;
-        noResults?: string;
-        eventsTitle?: string;
-        dashboardTitle?: string;
-        collectionsTitle?: string;
-        collectionsEndpoint?: string;
-    };
-    features?: {
-        showOverview?: boolean;
-        showActivity?: boolean;
-        showThreads?: boolean;
-        showParticipants?: boolean;
-        showAgents?: boolean;
-        showEvents?: boolean;
-        showCollections?: boolean;
-    };
-    ui?: {
-        compact?: boolean;
-        maxActivityBars?: number;
-    };
-    sidebar?: {
-        defaultOpen?: boolean;
-        collapsible?: "icon" | "offcanvas" | "none";
-    };
+interface AdminClientOptions {
     baseUrl?: string;
+    paths?: Partial<AdminClientPaths>;
     getRequestHeaders?: RequestHeadersProvider;
+}
+interface AdminListOptions {
     namespace?: string;
-    initialRange?: AdminDatePreset;
-    initialInterval?: AdminActivityInterval;
-    defaultPage?: AdminPage;
-    onNavigate?: (route: AdminRoute) => void;
-}
-interface ResolvedAdminConfig {
-    branding: Required<NonNullable<AdminConfig["branding"]>>;
-    labels: Required<NonNullable<AdminConfig["labels"]>>;
-    features: Required<NonNullable<AdminConfig["features"]>>;
-    ui: Required<NonNullable<AdminConfig["ui"]>>;
-    sidebar: Required<NonNullable<AdminConfig["sidebar"]>>;
-    baseUrl: string;
-    getRequestHeaders: RequestHeadersProvider;
-    namespace: string;
-    initialRange: AdminDatePreset;
-    initialInterval: AdminActivityInterval;
-    defaultPage: AdminPage;
-    onNavigate: ((route: AdminRoute) => void) | null;
+    search?: string;
+    limit?: number;
+    offset?: number;
+    before?: string;
+    after?: string;
+    filter?: Record<string, unknown>;
+    sort?: Record<string, "asc" | "desc">;
+    populate?: string[];
 }
-interface AdminSectionState {
-    overview: AdminOverview | null;
-    activity: AdminActivityPoint[];
-    threads: AdminThreadSummary[];
-    participants: AdminParticipantSummary[];
-    agents: AdminAgentSummary[];
+interface CopilotzAdminClient {
+    paths: AdminClientPaths;
+    getOverview(options?: {
+        range?: AdminDatePreset;
+        namespace?: string;
+    }): Promise<AdminOverview>;
+    getActivity(options?: {
+        range?: AdminDatePreset;
+        interval?: AdminActivityInterval;
+        namespace?: string;
+    }): Promise<AdminActivityPoint[]>;
+    getUsage(filters?: AdminUsageFilters): Promise<AdminUsageResponse>;
+    listThreads(options?: AdminListOptions): Promise<AdminThreadSummary[]>;
+    listParticipants(options?: AdminListOptions): Promise<AdminParticipantSummary[]>;
+    listAgents(options?: AdminListOptions & {
+        range?: AdminDatePreset;
+    }): Promise<AdminAgentSummary[]>;
+    getThread(threadId: string): Promise<AdminThreadDetail>;
+    getThreadMessages(threadId: string, options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<AdminMessagePage>;
+    getThreadEvent(threadId: string): Promise<AdminQueueEvent | undefined>;
+    listCollections(): Promise<string[]>;
+    listCollectionItems(collection: string, options?: AdminListOptions): Promise<AdminCollectionItem[]>;
+    getCollectionItem(collection: string, itemId: string, options?: {
+        namespace?: string;
+        populate?: string[];
+    }): Promise<AdminCollectionItem>;
+    createCollectionItem(collection: string, data: Record<string, unknown>, options?: {
+        namespace?: string;
+    }): Promise<AdminCollectionItem>;
+    updateCollectionItem(collection: string, itemId: string, data: Record<string, unknown>, options?: {
+        namespace?: string;
+    }): Promise<AdminCollectionItem>;
+    deleteCollectionItem(collection: string, itemId: string, options?: {
+        namespace?: string;
+    }): Promise<void>;
+}
+declare function createAdminClient(options?: AdminClientOptions): CopilotzAdminClient;
+
+type AdminModuleGroup = "operate" | "configure" | "data" | "extensions";
+interface AdminScope {
+    namespace?: string;
+    schema?: string;
+    availableNamespaces?: Array<{
+        id: string;
+        label?: string;
+    }>;
+}
+interface AdminBranding {
+    title?: string;
+    subtitle?: string;
+    logo?: ReactNode;
+    actions?: ReactNode;
+}
+interface AdminPermissions {
+    roles?: string[];
+    canAccess?: (permission: string, action?: string) => boolean;
+}
+interface AdminRouteState {
+    routeId: string;
+    params?: Record<string, string | undefined>;
+}
+interface AdminRouteDefinition {
+    id: string;
+    title: string;
+    permission?: string;
+    render: (context: AdminRuntimeContext) => ReactNode;
+}
+interface AdminNavItem {
+    id: string;
+    label: string;
+    routeId: string;
+    group?: AdminModuleGroup;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    description?: string;
+    order?: number;
+    permission?: string;
+}
+interface CollectionEditorProps {
+    collection: string;
+    itemId: string | null;
+    value: AdminCollectionItem | null;
+    isNew: boolean;
+    context: AdminRuntimeContext;
+    onSaved?: (item: AdminCollectionItem) => void;
+    onDeleted?: () => void;
+}
+type CollectionEditor = ComponentType<CollectionEditorProps>;
+interface AdminDetailPanel {
+    id: string;
+    label: string;
+    routeIds?: string[];
+    render: (context: AdminRuntimeContext) => ReactNode;
 }
-interface UseCopilotzAdminOptions extends AdminFilters {
+interface AdminModule {
+    id: string;
+    label: string;
+    group?: AdminModuleGroup;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    routes: AdminRouteDefinition[];
+    navItems?: AdminNavItem[];
+    collectionEditors?: Record<string, CollectionEditor>;
+    detailPanels?: AdminDetailPanel[];
+}
+interface AdminRuntimeContext {
+    client: CopilotzAdminClient;
+    modules: AdminModule[];
+    route: AdminRouteState;
+    scope: AdminScope;
+    branding: Required<AdminBranding>;
+    permissions: AdminPermissions;
+    refreshKey: number;
+    collectionEditors: Record<string, CollectionEditor>;
+    navigate: (routeId: string, params?: Record<string, string | undefined>) => void;
+    setNamespace: (namespace: string) => void;
+    requestRefresh: () => void;
+    canAccess: (permission?: string, action?: string) => boolean;
+}
+interface AdminClientConfig {
     baseUrl?: string;
+    paths?: Partial<AdminClientPaths>;
     getRequestHeaders?: RequestHeadersProvider;
 }
-interface UseCopilotzAdminResult extends AdminSectionState {
-    filters: Required<Pick<AdminFilters, "range" | "interval">> & Omit<AdminFilters, "range" | "interval">;
-    isLoading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-    setRange: (range: AdminDatePreset) => void;
-    setInterval: (interval: AdminActivityInterval) => void;
+interface LegacyAdminConfig {
+    baseUrl?: string;
+    getRequestHeaders?: RequestHeadersProvider;
+    namespace?: string;
+    branding?: AdminBranding;
+    defaultPage?: string;
 }
-
 interface CopilotzAdminProps {
-    config?: Partial<AdminConfig>;
+    client?: CopilotzAdminClient;
+    clientConfig?: AdminClientConfig;
+    config?: LegacyAdminConfig;
+    scope?: AdminScope;
+    modules?: AdminModule[];
+    branding?: AdminBranding;
+    permissions?: AdminPermissions;
     className?: string;
+    onNavigate?: (route: AdminRouteState) => void;
 }
-declare const CopilotzAdmin: React.FC<CopilotzAdminProps>;
 
-declare function useCopilotzAdmin(options?: UseCopilotzAdminOptions): UseCopilotzAdminResult;
+declare function CopilotzAdmin({ branding: brandingProp, className, client, clientConfig, config, modules: modulesProp, onNavigate, permissions, scope: scopeProp, }: CopilotzAdminProps): react_jsx_runtime.JSX.Element;
+
+declare function useAdmin(): AdminRuntimeContext;
+
+declare const ADMIN_GROUP_LABELS: Record<AdminModuleGroup, string>;
+declare const ADMIN_GROUP_ORDER: AdminModuleGroup[];
+declare function canAccessAdminPermission(permissions: AdminPermissions | undefined, permission?: string, action?: string): boolean;
+declare function collectAdminRoutes(modules: AdminModule[], permissions?: AdminPermissions): Map<string, AdminRouteDefinition>;
+declare function collectAdminNavItems(modules: AdminModule[], permissions?: AdminPermissions): AdminNavItem[];
+declare function collectCollectionEditors(modules: AdminModule[]): Record<string, CollectionEditor>;
+declare function firstAccessibleRoute(modules: AdminModule[], permissions?: AdminPermissions): string;
 
-interface FetchOptions {
+declare function agentsModule(): AdminModule;
+
+declare function collectionsModule(): AdminModule;
+
+declare function eventsModule(): AdminModule;
+
+declare function overviewModule(): AdminModule;
+
+declare function participantsModule(): AdminModule;
+
+declare function threadsModule(): AdminModule;
+
+declare function usageModule(): AdminModule;
+
+interface UsageChartSeries {
+    color: string;
+    id: string;
+    key: string;
+    label: string;
+}
+interface UsageChartState {
+    config: Record<string, {
+        color: string;
+        label: string;
+    }>;
+    data: Array<Record<string, number | string>>;
+    series: UsageChartSeries[];
+}
+interface AggregatedUsageRow extends AdminUsageTotals {
+    groupKey: string;
+    groupLabel: string;
+    value: number;
+}
+interface UsageCalculationOptions {
+    dimension: AdminUsageDimension;
+    interval: AdminUsageInterval;
+    metricKind: AdminUsageMetricKind;
+    points: AdminUsagePoint[];
+}
+
+declare const EMPTY_USAGE_TOTALS: AdminUsageTotals;
+declare function addUsageTotals(target: AdminUsageTotals, source: AdminUsageTotals): void;
+declare function getUsageTotalValue(totals: AdminUsageTotals, metricKind: AdminUsageMetricKind, dimension: AdminUsageDimension): number;
+declare function aggregateUsageRows(points: AdminUsagePoint[], metricKind: AdminUsageMetricKind, dimension: AdminUsageDimension): AggregatedUsageRow[];
+declare function buildUsageChartState(points: AdminUsagePoint[], metricKind: AdminUsageMetricKind, dimension: AdminUsageDimension, interval: AdminUsageInterval): UsageChartState;
+declare function getUsageRange(period: "24h" | "7d" | "30d" | "custom", customFrom: string, customTo: string): {
+    from: string | undefined;
+    to: string | undefined;
+};
+declare function getUsageDimensionLabel(dimension: AdminUsageDimension): "Input" | "Output" | "Reasoning" | "Cache read" | "Cache write" | "Total";
+declare function getUsageGroupLabel(groupBy: string): "Thread" | "Namespace" | "Provider" | "Model" | "Participant";
+declare function formatUsageBucket(bucket: string, interval: AdminUsageInterval): string;
+declare function formatNumber(value: number): string;
+declare function formatPercent(value: number): string;
+declare function formatMetricValue(value: number, metricKind: AdminUsageMetricKind): string;
+declare function formatCompactMetric(value: number, metricKind: AdminUsageMetricKind): string;
+
+declare function defaultCopilotzModules(): AdminModule[];
+
+declare const defaultAdminConfig: LegacyAdminConfig;
+declare function mergeAdminConfig(baseConfig?: LegacyAdminConfig, userConfig?: LegacyAdminConfig): LegacyAdminConfig;
+
+interface UseCopilotzAdminOptions {
+    agentSearch?: string;
     baseUrl?: string;
     getRequestHeaders?: RequestHeadersProvider;
-}
-declare function fetchAdminOverview(range: AdminDatePreset, namespace?: string, options?: FetchOptions): Promise<AdminOverview>;
-declare function fetchAdminActivity(range: AdminDatePreset, interval: AdminActivityInterval, namespace?: string, options?: FetchOptions): Promise<AdminActivityPoint[]>;
-declare function fetchAdminThreads(search?: string, namespace?: string, options?: FetchOptions): Promise<AdminThreadSummary[]>;
-declare function fetchAdminParticipants(search?: string, namespace?: string, options?: FetchOptions): Promise<AdminParticipantSummary[]>;
-declare function fetchAdminAgents(search?: string, namespace?: string, options?: FetchOptions): Promise<AdminAgentSummary[]>;
-declare function fetchAdminUsage(filters: AdminUsageFilters, options?: FetchOptions): Promise<AdminUsageResponse>;
-declare function fetchParticipantDetail(participantId: string, options?: FetchOptions): Promise<AdminParticipantDetail | null>;
-declare function updateParticipant(participantId: string, data: Record<string, unknown>, options?: FetchOptions): Promise<AdminParticipantDetail>;
-declare function fetchCollectionNames(options?: FetchOptions): Promise<string[]>;
-declare function fetchCollectionItems(collection: string, queryOptions?: {
-    search?: string;
+    interval?: AdminActivityInterval;
     namespace?: string;
-    limit?: number;
-    offset?: number;
-}, options?: FetchOptions): Promise<AdminCollectionItem[]>;
-declare function fetchCollectionItem(collection: string, itemId: string, _namespace?: string, options?: FetchOptions): Promise<AdminCollectionItem>;
-declare function createCollectionItem(collection: string, data: Record<string, unknown>, _namespace?: string, options?: FetchOptions): Promise<AdminCollectionItem>;
-declare function updateCollectionItem(collection: string, itemId: string, data: Record<string, unknown>, _namespace?: string, options?: FetchOptions): Promise<AdminCollectionItem>;
-declare function deleteCollectionItem(collection: string, itemId: string, _namespace?: string, options?: FetchOptions): Promise<void>;
-declare function fetchThreadEvents(threadId: string, options?: FetchOptions): Promise<AdminQueueEvent | undefined>;
-
-declare const defaultAdminConfig: ResolvedAdminConfig;
-declare function mergeAdminConfig(_baseConfig: ResolvedAdminConfig, userConfig?: Partial<AdminConfig>): ResolvedAdminConfig;
+    participantSearch?: string;
+    range?: AdminDatePreset;
+    threadSearch?: string;
+}
+interface UseCopilotzAdminResult {
+    activity: AdminActivityPoint[];
+    agents: AdminAgentSummary[];
+    error: Error | null;
+    filters: UseCopilotzAdminOptions & {
+        interval: AdminActivityInterval;
+        range: AdminDatePreset;
+    };
+    isLoading: boolean;
+    overview: AdminOverview | null;
+    participants: AdminParticipantSummary[];
+    refresh: () => Promise<void>;
+    setInterval: (interval: AdminActivityInterval) => void;
+    setRange: (range: AdminDatePreset) => void;
+    threads: AdminThreadSummary[];
+}
+/** @deprecated Prefer the module-based CopilotzAdmin shell and createAdminClient. */
+declare function useCopilotzAdmin(options?: UseCopilotzAdminOptions): UseCopilotzAdminResult;
 
-export { type AdminActivityInterval, type AdminActivityPoint, type AdminAgentSummary, type AdminCollectionItem, type AdminConfig, type AdminDatePreset, type AdminFilters, type AdminMessage, type AdminMessagePage, type AdminMessagePageInfo, type AdminOverview, type AdminPage, type AdminParticipantDetail, type AdminParticipantSummary, type AdminQueueEvent, type AdminRoute, type AdminSectionState, type AdminThreadDetail, type AdminThreadSummary, type AdminUsageAttribution, type AdminUsageFilters, type AdminUsageGroupBy, type AdminUsageInterval, type AdminUsagePoint, type AdminUsageResponse, CopilotzAdmin, type RequestHeadersProvider, type UseCopilotzAdminOptions, type UseCopilotzAdminResult, createCollectionItem, defaultAdminConfig, deleteCollectionItem, fetchAdminActivity, fetchAdminAgents, fetchAdminOverview, fetchAdminParticipants, fetchAdminThreads, fetchAdminUsage, fetchCollectionItem, fetchCollectionItems, fetchCollectionNames, fetchParticipantDetail, fetchThreadEvents, mergeAdminConfig, updateCollectionItem, updateParticipant, useCopilotzAdmin };
+export { ADMIN_GROUP_LABELS, ADMIN_GROUP_ORDER, type AdminActivityInterval, type AdminActivityPoint, type AdminAgentSummary, type AdminBranding, type AdminClientConfig, type AdminClientOptions, type AdminClientPaths, type AdminCollectionItem, type AdminCollectionPage, type AdminDatePreset, type AdminDetailPanel, type AdminMessage, type AdminMessagePage, type AdminMessagePageInfo, type AdminModule, type AdminModuleGroup, type AdminNavItem, type AdminOverview, type AdminParticipantDetail, type AdminParticipantSummary, type AdminPermissions, type AdminQueueEvent, type AdminRouteDefinition, type AdminRouteState, type AdminRuntimeContext, type AdminScope, type AdminThreadDetail, type AdminThreadSummary, type AdminUsageAttribution, type AdminUsageBreakdown, type AdminUsageDimension, type AdminUsageFilters, type AdminUsageGroupBy, type AdminUsageInterval, type AdminUsageMetricKind, type AdminUsagePoint, type AdminUsageResponse, type AdminUsageTotals, type AggregatedUsageRow, type CollectionEditor, type CollectionEditorProps, CopilotzAdmin, type CopilotzAdminClient, type CopilotzAdminProps, EMPTY_USAGE_TOTALS, type LegacyAdminConfig, type RequestHeadersProvider, type UsageCalculationOptions, type UsageChartSeries, type UsageChartState, type UseCopilotzAdminOptions, type UseCopilotzAdminResult, addUsageTotals, agentsModule, aggregateUsageRows, buildUsageChartState, canAccessAdminPermission, collectAdminNavItems, collectAdminRoutes, collectCollectionEditors, collectionsModule, createAdminClient, defaultAdminConfig, defaultCopilotzModules, eventsModule, firstAccessibleRoute, formatCompactMetric, formatMetricValue, formatNumber, formatPercent, formatUsageBucket, getUsageDimensionLabel, getUsageGroupLabel, getUsageRange, getUsageTotalValue, mergeAdminConfig, overviewModule, participantsModule, threadsModule, usageModule, useAdmin, useCopilotzAdmin };