@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/templates/full/dashboard/src/lib/usage/providers.ts

@@ -0,0 +1,331 @@
+/**
+ * Third-Party Provider Stubs
+ *
+ * Interface definitions and fetcher stubs for third-party service usage tracking.
+ * These will be implemented incrementally as integrations are built.
+ *
+ * Supported providers (planned):
+ * - GitHub (Actions minutes, Advanced Security seats, storage)
+ * - OpenAI (API usage, tokens)
+ * - Apify (Actor runs, compute units)
+ * - Anthropic (API usage, tokens)
+ * - Resend (emails sent)
+ */
+
+/**
+ * Provider identifier
+ */
+export type ProviderId = 'github' | 'openai' | 'apify' | 'anthropic' | 'resend';
+
+/**
+ * Usage record from a third-party provider
+ */
+export interface ThirdPartyUsageRecord {
+  /** Provider identifier */
+  provider: ProviderId;
+  /** Type of resource (e.g., 'actions_minutes', 'api_tokens') */
+  resourceType: string;
+  /** Optional specific resource name */
+  resourceName?: string;
+  /** Numeric usage value */
+  usageValue: number;
+  /** Unit of measurement */
+  usageUnit: string;
+  /** Estimated cost in USD */
+  costUsd: number;
+  /** When this data was collected */
+  collectedAt: Date;
+  /** Period this usage covers */
+  periodStart: Date;
+  periodEnd: Date;
+}
+
+/**
+ * Provider configuration
+ */
+export interface ProviderConfig {
+  /** Provider identifier */
+  id: ProviderId;
+  /** Human-readable name */
+  name: string;
+  /** Whether the provider is currently enabled */
+  enabled: boolean;
+  /** API key environment variable name */
+  apiKeyEnvVar: string;
+  /** Pricing model description */
+  pricingModel: string;
+  /** Documentation URL */
+  docsUrl: string;
+}
+
+/**
+ * Provider interface for fetching usage data
+ */
+export interface Provider {
+  /** Provider configuration */
+  config: ProviderConfig;
+
+  /**
+   * Fetch current usage data from the provider
+   * @param apiKey - API key for authentication
+   * @param options - Additional fetch options
+   * @returns Array of usage records
+   */
+  fetchUsage(
+    apiKey: string,
+    options?: {
+      startDate?: Date;
+      endDate?: Date;
+      includeBreakdown?: boolean;
+    }
+  ): Promise<ThirdPartyUsageRecord[]>;
+
+  /**
+   * Check if the provider credentials are valid
+   * @param apiKey - API key to validate
+   */
+  validateCredentials(apiKey: string): Promise<boolean>;
+}
+
+/**
+ * Provider configurations
+ */
+export const PROVIDER_CONFIGS: Record<ProviderId, ProviderConfig> = {
+  github: {
+    id: 'github',
+    name: 'GitHub',
+    enabled: true,
+    apiKeyEnvVar: 'GITHUB_TOKEN',
+    pricingModel: 'Actions minutes, Advanced Security seats, storage',
+    docsUrl: 'https://docs.github.com/en/billing',
+  },
+  openai: {
+    id: 'openai',
+    name: 'OpenAI',
+    enabled: false,
+    apiKeyEnvVar: 'OPENAI_ADMIN_API_KEY',
+    pricingModel: 'Per-token pricing for API usage',
+    docsUrl: 'https://platform.openai.com/docs/api-reference/usage',
+  },
+  apify: {
+    id: 'apify',
+    name: 'Apify',
+    enabled: false,
+    apiKeyEnvVar: 'APIFY_API_KEY',
+    pricingModel: 'Compute units for actor runs',
+    docsUrl: 'https://docs.apify.com/platform/billing',
+  },
+  anthropic: {
+    id: 'anthropic',
+    name: 'Anthropic',
+    enabled: false,
+    apiKeyEnvVar: 'ANTHROPIC_ADMIN_API_KEY',
+    pricingModel: 'Per-token pricing for Claude API',
+    docsUrl: 'https://docs.anthropic.com/en/api/admin-api',
+  },
+  resend: {
+    id: 'resend',
+    name: 'Resend',
+    enabled: false,
+    apiKeyEnvVar: 'RESEND_API_KEY',
+    pricingModel: 'Per-email pricing',
+    docsUrl: 'https://resend.com/docs/api-reference',
+  },
+};
+
+// =============================================================================
+// PROVIDER FETCHER STUBS
+// =============================================================================
+// Each stub returns an empty array with a TODO comment.
+// Implement these as integrations are built.
+// =============================================================================
+
+/**
+ * GitHub Usage Fetcher
+ *
+ * TODO: Implement GitHub billing API integration
+ * - GET /orgs/{org}/settings/billing/actions
+ * - GET /orgs/{org}/settings/billing/advanced-security
+ * - GET /orgs/{org}/settings/billing/shared-storage
+ *
+ * @see https://docs.github.com/en/rest/billing
+ */
+export async function fetchGitHubUsage(
+  _apiKey: string,
+  _options?: {
+    organization?: string;
+    startDate?: Date;
+    endDate?: Date;
+  }
+): Promise<ThirdPartyUsageRecord[]> {
+  // TODO: Implement GitHub billing API calls
+  // 1. Fetch Actions minutes usage
+  // 2. Fetch Advanced Security seats
+  // 3. Fetch shared storage usage
+  // 4. Calculate costs based on GitHub pricing
+  console.log('[providers] GitHub usage fetcher not yet implemented');
+  return [];
+}
+
+/**
+ * OpenAI Usage Fetcher
+ *
+ * TODO: Implement OpenAI Usage API integration
+ * - GET /v1/usage (requires admin API key: sk-admin-...)
+ *
+ * @see https://platform.openai.com/docs/api-reference/usage
+ */
+export async function fetchOpenAIUsage(
+  _apiKey: string,
+  _options?: {
+    startDate?: Date;
+    endDate?: Date;
+  }
+): Promise<ThirdPartyUsageRecord[]> {
+  // TODO: Implement OpenAI Usage API calls
+  // 1. Fetch token usage by model
+  // 2. Calculate costs based on model pricing
+  // 3. Group by date for time-series data
+  console.log('[providers] OpenAI usage fetcher not yet implemented');
+  return [];
+}
+
+/**
+ * Apify Usage Fetcher
+ *
+ * TODO: Implement Apify billing API integration
+ * - GET /v2/users/{userId}/usage
+ *
+ * @see https://docs.apify.com/api/v2#/reference/users/account-usage
+ */
+export async function fetchApifyUsage(
+  _apiKey: string,
+  _options?: {
+    startDate?: Date;
+    endDate?: Date;
+  }
+): Promise<ThirdPartyUsageRecord[]> {
+  // TODO: Implement Apify usage API calls
+  // 1. Fetch compute unit usage
+  // 2. Fetch actor run counts
+  // 3. Calculate costs based on Apify pricing
+  console.log('[providers] Apify usage fetcher not yet implemented');
+  return [];
+}
+
+/**
+ * Anthropic Usage Fetcher
+ *
+ * TODO: Implement Anthropic Admin API integration
+ * - GET /v1/organizations/{organization_id}/usage (Admin API)
+ *
+ * @see https://docs.anthropic.com/en/api/admin-api
+ */
+export async function fetchAnthropicUsage(
+  _apiKey: string,
+  _options?: {
+    organizationId?: string;
+    startDate?: Date;
+    endDate?: Date;
+  }
+): Promise<ThirdPartyUsageRecord[]> {
+  // TODO: Implement Anthropic Admin API calls
+  // 1. Fetch token usage by model
+  // 2. Calculate costs based on Claude pricing
+  // 3. Group by date for time-series data
+  console.log('[providers] Anthropic usage fetcher not yet implemented');
+  return [];
+}
+
+/**
+ * Resend Usage Fetcher
+ *
+ * TODO: Implement Resend API integration
+ * - No direct usage endpoint; track via webhook or count emails
+ *
+ * @see https://resend.com/docs/api-reference
+ */
+export async function fetchResendUsage(
+  _apiKey: string,
+  _options?: {
+    startDate?: Date;
+    endDate?: Date;
+  }
+): Promise<ThirdPartyUsageRecord[]> {
+  // TODO: Implement Resend usage tracking
+  // 1. Query sent emails count (if available)
+  // 2. Or track via our own email logs
+  // 3. Calculate costs based on Resend pricing
+  console.log('[providers] Resend usage fetcher not yet implemented');
+  return [];
+}
+
+// =============================================================================
+// AGGREGATION UTILITIES
+// =============================================================================
+
+/**
+ * Fetch usage from all enabled providers
+ */
+export async function fetchAllProviderUsage(
+  apiKeys: Partial<Record<ProviderId, string>>,
+  options?: {
+    startDate?: Date;
+    endDate?: Date;
+  }
+): Promise<ThirdPartyUsageRecord[]> {
+  const results: ThirdPartyUsageRecord[] = [];
+
+  // Only fetch from providers that have API keys configured
+  const fetchPromises: Promise<ThirdPartyUsageRecord[]>[] = [];
+
+  if (apiKeys.github) {
+    fetchPromises.push(fetchGitHubUsage(apiKeys.github, options));
+  }
+  if (apiKeys.openai) {
+    fetchPromises.push(fetchOpenAIUsage(apiKeys.openai, options));
+  }
+  if (apiKeys.apify) {
+    fetchPromises.push(fetchApifyUsage(apiKeys.apify, options));
+  }
+  if (apiKeys.anthropic) {
+    fetchPromises.push(fetchAnthropicUsage(apiKeys.anthropic, options));
+  }
+  if (apiKeys.resend) {
+    fetchPromises.push(fetchResendUsage(apiKeys.resend, options));
+  }
+
+  // Fetch all in parallel, handle individual failures gracefully
+  const settledResults = await Promise.allSettled(fetchPromises);
+
+  for (const result of settledResults) {
+    if (result.status === 'fulfilled') {
+      results.push(...result.value);
+    } else {
+      console.error('[providers] Failed to fetch from provider:', result.reason);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Calculate total third-party costs from usage records
+ */
+export function calculateThirdPartyCosts(records: ThirdPartyUsageRecord[]): {
+  byProvider: Record<ProviderId, number>;
+  total: number;
+} {
+  const byProvider: Partial<Record<ProviderId, number>> = {};
+  let total = 0;
+
+  for (const record of records) {
+    byProvider[record.provider] = (byProvider[record.provider] ?? 0) + record.costUsd;
+    total += record.costUsd;
+  }
+
+  return {
+    byProvider: byProvider as Record<ProviderId, number>,
+    total,
+  };
+}

package/templates/shared/dashboard/src/components/reports/ReportInfoButton.tsx

@@ -0,0 +1,98 @@
+/**
+ * ReportInfoButton Component
+ * Reusable info icon button that toggles a floating panel with report explanation.
+ * Based on PatternInfoButton pattern.
+ */
+import { useState, useRef, useEffect, type ReactNode } from 'react';
+
+interface ReportInfoButtonProps {
+  title: string;
+  children: ReactNode;
+  /** Colour theme: matches the original info panel colours per report */
+  theme?: 'blue' | 'yellow' | 'orange' | 'red' | 'purple' | 'green' | 'teal';
+}
+
+const themeClasses: Record<string, { button: string; panel: string; heading: string }> = {
+  blue: {
+    button: 'bg-blue-100 hover:bg-blue-200 dark:bg-blue-900/40 dark:hover:bg-blue-900/60 text-blue-600 dark:text-blue-400',
+    panel: 'bg-blue-50 dark:bg-blue-900/30 border-blue-200 dark:border-blue-800',
+    heading: 'text-blue-800 dark:text-blue-300',
+  },
+  yellow: {
+    button: 'bg-yellow-100 hover:bg-yellow-200 dark:bg-yellow-900/40 dark:hover:bg-yellow-900/60 text-yellow-600 dark:text-yellow-400',
+    panel: 'bg-yellow-50 dark:bg-yellow-900/30 border-yellow-200 dark:border-yellow-800',
+    heading: 'text-yellow-800 dark:text-yellow-300',
+  },
+  orange: {
+    button: 'bg-orange-100 hover:bg-orange-200 dark:bg-orange-900/40 dark:hover:bg-orange-900/60 text-orange-600 dark:text-orange-400',
+    panel: 'bg-orange-50 dark:bg-orange-900/30 border-orange-200 dark:border-orange-800',
+    heading: 'text-orange-800 dark:text-orange-300',
+  },
+  red: {
+    button: 'bg-red-100 hover:bg-red-200 dark:bg-red-900/40 dark:hover:bg-red-900/60 text-red-600 dark:text-red-400',
+    panel: 'bg-red-50 dark:bg-red-900/30 border-red-200 dark:border-red-800',
+    heading: 'text-red-800 dark:text-red-300',
+  },
+  purple: {
+    button: 'bg-purple-100 hover:bg-purple-200 dark:bg-purple-900/40 dark:hover:bg-purple-900/60 text-purple-600 dark:text-purple-400',
+    panel: 'bg-purple-50 dark:bg-purple-900/30 border-purple-200 dark:border-purple-800',
+    heading: 'text-purple-800 dark:text-purple-300',
+  },
+  green: {
+    button: 'bg-green-100 hover:bg-green-200 dark:bg-green-900/40 dark:hover:bg-green-900/60 text-green-600 dark:text-green-400',
+    panel: 'bg-green-50 dark:bg-green-900/30 border-green-200 dark:border-green-800',
+    heading: 'text-green-800 dark:text-green-300',
+  },
+  teal: {
+    button: 'bg-teal-100 hover:bg-teal-200 dark:bg-teal-900/40 dark:hover:bg-teal-900/60 text-teal-600 dark:text-teal-400',
+    panel: 'bg-teal-50 dark:bg-teal-900/30 border-teal-200 dark:border-teal-800',
+    heading: 'text-teal-800 dark:text-teal-300',
+  },
+};
+
+export function ReportInfoButton({ title, children, theme = 'blue' }: ReportInfoButtonProps) {
+  const [open, setOpen] = useState(false);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const colours = themeClasses[theme];
+
+  useEffect(() => {
+    if (!open) return;
+
+    function handleClickOutside(event: MouseEvent) {
+      if (panelRef.current && !panelRef.current.contains(event.target as Node)) {
+        setOpen(false);
+      }
+    }
+
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, [open]);
+
+  return (
+    <div className="relative" ref={panelRef}>
+      <button
+        onClick={() => setOpen(!open)}
+        className={`inline-flex items-center justify-center w-9 h-9 rounded-full ${colours.button} transition-colors`}
+        title={title}
+        aria-label={title}
+      >
+        <svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+        </svg>
+      </button>
+
+      {open && (
+        <div className={`absolute right-0 top-12 z-50 w-96 border rounded-lg p-4 shadow-lg ${colours.panel}`}>
+          <h3 className={`font-semibold ${colours.heading} mb-2`}>{title}</h3>
+          {children}
+          <button
+            onClick={() => setOpen(false)}
+            className={`mt-3 text-xs ${colours.heading} hover:underline`}
+          >
+            Close
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/shared/dashboard/src/components/usage/react/DashboardShell.tsx

@@ -0,0 +1,263 @@
+/**
+ * DashboardShell Component
+ * Industrial Command Center orchestrator - data fetching, state, auto-refresh
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { Activity, RefreshCw, AlertTriangle } from 'lucide-react';
+import { clsx } from 'clsx';
+import {
+  type Period,
+  type UsageRow,
+  type ProjectStatus,
+  type StatusResponse,
+  type QueryResponse,
+} from './types';
+import { UsageChart } from './UsageChart';
+import { UsageTable } from './UsageTable';
+
+interface DashboardShellProps {
+  initialPeriod?: Period;
+}
+
+const REFRESH_INTERVAL = 60_000; // 60 seconds
+
+/**
+ * Period button component
+ */
+function PeriodButton({
+  period,
+  currentPeriod,
+  onClick,
+}: {
+  period: Period;
+  currentPeriod: Period;
+  onClick: (p: Period) => void;
+}) {
+  const isActive = period === currentPeriod;
+  return (
+    <button
+      type="button"
+      onClick={() => onClick(period)}
+      className={clsx(
+        'px-3 py-1.5 text-xs font-mono font-semibold uppercase tracking-wider rounded-sm transition-all',
+        isActive
+          ? 'bg-gray-200 dark:bg-slate-700 text-gray-900 dark:text-slate-100 shadow-inner'
+          : 'bg-gray-100 dark:bg-slate-800 text-gray-600 dark:text-slate-400 hover:bg-gray-200 dark:hover:bg-slate-700 hover:text-gray-800 dark:hover:text-slate-300'
+      )}
+    >
+      {period}
+    </button>
+  );
+}
+
+/**
+ * Live indicator with pulse
+ */
+function LiveIndicator({ isRefreshing }: { isRefreshing: boolean }) {
+  return (
+    <div className="flex items-center gap-2">
+      {isRefreshing ? (
+        <RefreshCw className="w-3.5 h-3.5 text-gray-500 dark:text-slate-400 animate-spin" />
+      ) : (
+        <span className="relative flex h-2.5 w-2.5">
+          <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-emerald-400 opacity-75" />
+          <span className="relative inline-flex rounded-full h-2.5 w-2.5 bg-emerald-500" />
+        </span>
+      )}
+      <span className="text-xs font-mono text-gray-500 dark:text-slate-500 uppercase tracking-wider">
+        {isRefreshing ? 'Updating' : 'Live'}
+      </span>
+    </div>
+  );
+}
+
+/**
+ * Error state component
+ */
+function ErrorState({ message, onRetry }: { message: string; onRetry: () => void }) {
+  return (
+    <div className="bg-rose-500/10 border border-rose-500/30 rounded-sm p-6 flex items-start gap-4">
+      <AlertTriangle className="w-5 h-5 text-rose-400 flex-shrink-0 mt-0.5" />
+      <div className="flex-1">
+        <h3 className="text-rose-200 font-semibold text-sm">Failed to load data</h3>
+        <p className="text-rose-300/80 text-xs mt-1 font-mono">{message}</p>
+        <button
+          type="button"
+          onClick={onRetry}
+          className="mt-3 px-3 py-1.5 bg-rose-500/20 hover:bg-rose-500/30 text-rose-200 text-xs font-mono rounded-sm transition-colors"
+        >
+          Retry
+        </button>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Loading skeleton
+ */
+function LoadingSkeleton() {
+  return (
+    <div className="space-y-6 animate-pulse">
+      {/* Header skeleton */}
+      <div className="flex justify-between items-center">
+        <div className="h-8 bg-gray-200 dark:bg-slate-800 rounded w-48" />
+        <div className="h-8 bg-gray-200 dark:bg-slate-800 rounded w-32" />
+      </div>
+
+      {/* Chart skeleton */}
+      <div className="space-y-3">
+        <div className="h-5 bg-gray-200 dark:bg-slate-800 rounded w-36" />
+        <div className="h-64 bg-gray-100 dark:bg-slate-900 rounded-sm border border-gray-200 dark:border-slate-800" />
+      </div>
+
+      {/* Table skeleton */}
+      <div className="space-y-3">
+        <div className="h-5 bg-gray-200 dark:bg-slate-800 rounded w-24" />
+        <div className="h-48 bg-gray-100 dark:bg-slate-900 rounded-sm border border-gray-200 dark:border-slate-800" />
+      </div>
+    </div>
+  );
+}
+
+export function DashboardShell({ initialPeriod = '24h' }: DashboardShellProps) {
+  const [period, setPeriod] = useState<Period>(initialPeriod);
+  const [loading, setLoading] = useState(true);
+  const [isRefreshing, setIsRefreshing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [usageData, setUsageData] = useState<UsageRow[]>([]);
+  const [statusMap, setStatusMap] = useState<Record<string, ProjectStatus>>({});
+
+  /**
+   * Fetch data from both endpoints
+   */
+  const fetchData = useCallback(
+    async (isBackground = false) => {
+      if (isBackground) {
+        setIsRefreshing(true);
+      } else {
+        setLoading(true);
+        setError(null);
+      }
+
+      try {
+        const [statusRes, queryRes] = await Promise.all([
+          fetch(`/api/usage/status?period=${period}`),
+          fetch(`/api/usage/query?period=${period}`),
+        ]);
+
+        if (!statusRes.ok) {
+          throw new Error(`Status endpoint failed: ${statusRes.status}`);
+        }
+        if (!queryRes.ok) {
+          throw new Error(`Query endpoint failed: ${queryRes.status}`);
+        }
+
+        const statusData: StatusResponse = await statusRes.json();
+        const queryData: QueryResponse = await queryRes.json();
+
+        if (!statusData.success || !queryData.success) {
+          throw new Error('API returned unsuccessful response');
+        }
+
+        setStatusMap(statusData.projects);
+        setUsageData(queryData.data);
+        setError(null);
+      } catch (err) {
+        if (!isBackground) {
+          setError(err instanceof Error ? err.message : 'Unknown error occurred');
+        }
+        console.error('[DashboardShell] Fetch error:', err);
+      } finally {
+        setLoading(false);
+        setIsRefreshing(false);
+      }
+    },
+    [period]
+  );
+
+  /**
+   * Handle period change - update URL and refetch
+   */
+  const handlePeriodChange = useCallback((newPeriod: Period) => {
+    setPeriod(newPeriod);
+
+    // Update URL without reload
+    const url = new URL(window.location.href);
+    url.searchParams.set('period', newPeriod);
+    history.replaceState(null, '', url.toString());
+  }, []);
+
+  // Initial fetch and period change
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+
+  // Auto-refresh interval
+  useEffect(() => {
+    const interval = setInterval(() => {
+      fetchData(true);
+    }, REFRESH_INTERVAL);
+
+    return () => clearInterval(interval);
+  }, [fetchData]);
+
+  if (loading) {
+    return (
+      <div className="p-6 bg-gray-50 dark:bg-slate-950 min-h-screen">
+        <LoadingSkeleton />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="p-6 bg-gray-50 dark:bg-slate-950 min-h-screen">
+        <ErrorState message={error} onRetry={() => fetchData()} />
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-6 bg-gray-50 dark:bg-slate-950 min-h-screen space-y-6">
+      {/* Header */}
+      <header className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
+        <div className="flex items-center gap-3">
+          <Activity className="w-5 h-5 text-gray-600 dark:text-slate-400" />
+          <h1 className="text-xl font-semibold text-gray-900 dark:text-slate-100 tracking-tight">
+            Usage Monitor
+          </h1>
+          <LiveIndicator isRefreshing={isRefreshing} />
+        </div>
+
+        <div className="flex items-center gap-2">
+          <PeriodButton period="24h" currentPeriod={period} onClick={handlePeriodChange} />
+          <PeriodButton period="7d" currentPeriod={period} onClick={handlePeriodChange} />
+        </div>
+      </header>
+
+      {/* Chart section */}
+      <section>
+        <h2 className="text-sm font-semibold text-gray-600 dark:text-slate-400 uppercase tracking-wider mb-3">
+          Activity Timeline
+        </h2>
+        <UsageChart data={usageData} loading={isRefreshing && usageData.length === 0} />
+      </section>
+
+      {/* Table section */}
+      <section>
+        <h2 className="text-sm font-semibold text-gray-600 dark:text-slate-400 uppercase tracking-wider mb-3">
+          Projects
+        </h2>
+        <UsageTable
+          data={usageData}
+          statusMap={statusMap}
+          loading={isRefreshing && Object.keys(statusMap).length === 0}
+        />
+      </section>
+    </div>
+  );
+}
+
+export default DashboardShell;