# Core SDK (framework-agnostic)
npm install @huitzo/dashboard-sdk

# React hooks and components
npm install @huitzo/dashboard-sdk @huitzo/dashboard-sdk-react

import { HuitzoClient } from '@huitzo/dashboard-sdk';

const huitzo = new HuitzoClient({
  apiUrl: 'https://huitzo.ai',  // Optional, defaults to current origin
});

// Execute a command
const result = await huitzo.commands.execute('@acme/claims/process-claim', {
  claimId: 'CLM-12345'
});

console.log(result);

# pseudocode — conceptual React usage
import type { HuitzoMountContext } from '@huitzo/dashboard-sdk-react';
import { HuitzoProvider, useCommand } from '@huitzo/dashboard-sdk-react';

// 1. Dashboard entry point receives context from Hub's mount()
export function mount(container: HTMLElement, context: HuitzoMountContext) {
  const root = createRoot(container);
  root.render(
    <HuitzoProvider context={context}>
      <ClaimsList />
    </HuitzoProvider>
  );
}

// 2. Use hooks in your components
function ClaimsList() {
  const { execute, data, loading, error } = useCommand('@acme/claims/list-claims');

  useEffect(() => { execute({ status: 'pending' }) }, []);

  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  return <ul>{data?.claims.map(claim => <li key={claim.id}>{claim.title}</li>)}</ul>;
}

# pseudocode
import { HuitzoClient } from '@huitzo/dashboard-sdk';

// Basic initialization (uses current origin)
const huitzo = new HuitzoClient();

// With options
const huitzo = new HuitzoClient({
  apiUrl: 'https://huitzo.ai',
  timeout: 60000,
  onAuthError: (error) => { /* redirect to login */ },
});

# pseudocode
// Email/password login
await huitzo.auth.login('[email protected]', 'password');

// Register a new account
await huitzo.auth.register('[email protected]', 'password', 'acme', 'access_code');

// API key (for development)
huitzo.auth.setApiKey('sk_...');

// Check auth status
const isAuthenticated = huitzo.auth.isAuthenticated();
const user = await huitzo.auth.getUser();

// Logout
await huitzo.auth.logout();

// Basic execution
const result = await huitzo.commands.execute('@acme/claims/process-claim', {
  claimId: 'CLM-12345',
  priority: 'high'
});

// With options
const result = await huitzo.commands.execute(
  '@acme/claims/process-claim',
  { claimId: 'CLM-12345' },
  {
    timeout: 60000,      // Override timeout
    signal: controller.signal,  // AbortController signal
  }
);

# pseudocode
interface CommandResult<T> {
  result: T;                    // The command's return value
  execution: {
    duration_ms: number;        // Server-side execution time
    status: string;             // e.g. "success"
  };
}

// Type-safe usage
interface ClaimResult {
  id: string;
  status: string;
  processedAt: string;
}

const result = await huitzo.commands.execute<ClaimResult>(
  '@acme/claims/process-claim',
  { claimId: 'CLM-12345' }
);

console.log(result.result.status);       // "pending" | "approved" | ...
console.log(result.execution.duration_ms);

# pseudocode
// List all commands accessible to the current tenant
const all = await huitzo.commands.list();

// Filter by pack namespace (client-side filter over the full list)
const claims = await huitzo.commands.list({ pack: 'claims' });

// Get details for one command
const command = await huitzo.commands.get('@acme/claims/process-claim');
console.log(command.description);
console.log(command.input_schema);

# pseudocode
import { usePacks } from '@huitzo/dashboard-sdk-react';

function ClaimsFeature() {
  const { isInstalled, loading } = usePacks();
  if (loading) return null;
  if (!isInstalled('@acme/claims-processor')) return <UpsellBanner />;
  return <ClaimsPanel />;
}

# pseudocode
const packs = await huitzo.packs.list();
const isInstalled = packs.some(p => p.id === '@acme/claims-processor');

# pseudocode — planned API
const unsubscribe = huitzo.realtime.subscribe('claims:updated', {
  onMessage: (event) => { console.log('Claim updated:', event.data) },
  onError: (error) => { console.error('Subscription error:', error) },
});

unsubscribe();

# pseudocode — planned API
const status = huitzo.realtime.getStatus();  // 'connected' | 'connecting' | 'disconnected'
await huitzo.realtime.connect();
huitzo.realtime.disconnect();
huitzo.realtime.on('connected', () => {});
huitzo.realtime.on('disconnected', () => {});

// Dashboard entry point (src/main.tsx)
import { createRoot } from 'react-dom/client';
import type { HuitzoContext } from '@huitzo/dashboard-sdk';
import { HuitzoProvider } from '@huitzo/dashboard-sdk-react';

export function mount(container: HTMLElement, context: HuitzoContext) {
  const root = createRoot(container);
  root.render(
    <HuitzoProvider context={context}>
      <Dashboard />
    </HuitzoProvider>
  );
}

# pseudocode
import { useHuitzo } from '@huitzo/dashboard-sdk-react';

function UserInfo() {
  const { client, user, isAuthenticated, initError, isPackInstalled } = useHuitzo();

  if (initError) return <ErrorBanner error={initError} />;
  if (!isAuthenticated) return <LoginButton />;

  return (
    <div>
      <p>Welcome, {user.email}</p>
      {isPackInstalled('@huitzo/analytics') && <AnalyticsWidget />}
    </div>
  );
}

import { useCommand } from '@huitzo/dashboard-sdk-react';

interface Claim {
  id: string;
  title: string;
  status: string;
}

interface ListClaimsResult {
  claims: Claim[];
  total: number;
}

function ClaimsList() {
  const {
    execute,
    data,
    loading,
    error,
    reset
  } = useCommand<ListClaimsResult>('@acme/claims/list-claims');

  // Execute on mount
  useEffect(() => {
    execute({ status: 'pending', limit: 20 });
  }, []);

  // Execute with different params
  const handleFilter = (status: string) => {
    execute({ status, limit: 20 });
  };

  if (loading) return <Skeleton count={5} />;
  if (error) return <ErrorMessage error={error} onRetry={() => execute()} />;

  return (
    <div>
      <FilterBar onFilter={handleFilter} />
      <ul>
        {data?.claims.map(claim => (
          <ClaimItem key={claim.id} claim={claim} />
        ))}
      </ul>
      <p>Total: {data?.total}</p>
    </div>
  );
}

# pseudocode
const {
  execute,
  data,
  loading,
  error,
  reset,
  status,     // 'idle' | 'loading' | 'success' | 'error'
  isIdle,
  isSuccess,
  isError
} = useCommand('@acme/claims/process', {
  // Execute immediately with these args
  initialArgs: { claimId: 'CLM-123' },

  // Callbacks
  onSuccess: (data) => { toast.success('Claim processed!') },
  onError: (error) => { toast.error(error.message) },

  // Cache result for 5 seconds (keyed by args)
  cacheTime: 5000,
});

# pseudocode — planned API
useRealtime('claims:updated', (event) => { /* handle event */ });
useRealtime(['claims:created', 'claims:deleted'], (event) => { /* handle */ });

# pseudocode
import { usePacks } from '@huitzo/dashboard-sdk-react';

function PackList() {
  const { packs, loading, error, isInstalled, refetch } = usePacks();

  if (loading) return <p>Loading packs...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {packs.map(pack => (
        <li key={pack.name}>{pack.name} - {pack.version}</li>
      ))}
    </ul>
  );
}

# pseudocode
import { useHubNavigation } from '@huitzo/dashboard-sdk-react';

function DashboardHeader() {
  const {
    navigateToHub,        // Go to Hub home
    navigateToDashboard,  // Go to specific dashboard
    navigateToExplore,    // Go to marketplace
    navigateToSettings,   // Go to settings
    currentDashboard,     // Current dashboard slug
  } = useHubNavigation();

  return (
    <header>
      <button onClick={navigateToHub}>← Hub</button>
      <h1>Claims Dashboard</h1>
      <button onClick={() => navigateToDashboard('analytics')}>Open Analytics</button>
    </header>
  );
}

# pseudocode
import { useHubContext } from '@huitzo/dashboard-sdk-react';

function MyComponent() {
  const {
    apiUrl,         // Huitzo API base URL
    dashboardSlug,  // Current dashboard slug
    user,           // Current user from Hub session
    theme,          // Hub's current theme ('light' | 'dark')
  } = useHubContext();

  return (
    <div className={theme}>
      <span>Dashboard: {dashboardSlug}</span>
      <span>User: {user?.email}</span>
    </div>
  );
}

# pseudocode — planned API
useHubBreadcrumbs([
  { label: 'Claims Dashboard', href: '/d/claims-dashboard' },
  { label: 'Claim #123' },
]);

# pseudocode — conceptual usage
import { DashboardTile } from '@huitzo/dashboard-sdk-react';

<DashboardTile
  name="Claims"
  description="Process and review insurance claims"
  icon="📋"
  isPinned
  color="var(--color-accent)"
  href="/d/claims"
/>

# pseudocode — conceptual usage
import { DashboardInfoBlock } from '@huitzo/dashboard-sdk-react';

<DashboardInfoBlock
  title="Claims Dashboard"
  description="Manage and process insurance claims"
  icon="📋"
  variant="elevated"
  metadata={[
    { label: 'Version', value: '1.2.0' },
    { label: 'Last updated', value: '2 hours ago' },
  ]}
/>

# pseudocode — conceptual usage
<div className="hz-rail">
  <section className="hz-step hz-card hz-card--lg">
    <span className="hz-step__badge" aria-hidden>1</span>
    <h3>Run a pack</h3>
    <div className="hz-terminal">
      <div className="hz-terminal__header">
        <span className="hz-terminal__dots">
          <span className="hz-terminal__dot" />
          <span className="hz-terminal__dot" />
          <span className="hz-terminal__dot" />
        </span>
        <span className="hz-terminal__label">Terminal</span>
        <button className="hz-terminal__copy">Copy</button>
      </div>
      <pre className="hz-terminal__body">
        <span className="hz-terminal__prompt">$</span>
        huitzo run @yc/yc-weather-demo/current-weather --city san-francisco
      </pre>
      <pre className="hz-terminal__output">
        → {`{"city": "san-francisco", "temp_c": 14.2}`}
      </pre>
    </div>
  </section>
</div>

# pseudocode
import {
  HuitzoError,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NetworkError
} from '@huitzo/dashboard-sdk';

try {
  await huitzo.commands.execute('@acme/claims/process', args);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401 — redirect to login
  } else if (error instanceof ValidationError) {
    // 400/422 — field errors in error.details
  } else if (error instanceof RateLimitError) {
    // 429 — retry after error.retryAfter seconds
  } else if (error instanceof NetworkError) {
    // DNS failure, offline, etc.
  } else if (error instanceof HuitzoError) {
    // Catch-all for any SDK error
    console.error(error.code, error.message);
  }
}

# pseudocode
function ClaimProcessor() {
  const { execute, error, isError } = useCommand('@acme/claims/process');

  if (isError) {
    if (error instanceof ValidationError) {
      return <ValidationErrors errors={error.details} />;
    }
    if (error instanceof AuthorizationError) {
      return <PermissionDenied />;
    }
    return <GenericError error={error} />;
  }
}

// Define your command types
interface ProcessClaimArgs {
  claimId: string;
  priority?: 'low' | 'medium' | 'high';
}

interface ProcessClaimResult {
  id: string;
  status: 'approved' | 'denied' | 'pending';
  processedAt: string;
  reviewer?: string;
}

// Use with execute
const result = await huitzo.commands.execute<ProcessClaimResult>(
  '@acme/claims/process',
  { claimId: 'CLM-123', priority: 'high' } satisfies ProcessClaimArgs
);

// result.result is typed as ProcessClaimResult

# pseudocode
// useCommand is generic
const { data } = useCommand<ListClaimsResult>('@acme/claims/list');
// data is ListClaimsResult | null

function ClaimDetails({ id }: { id: string }) {
  const { execute, data, loading, error } = useCommand('@acme/claims/get');

  useEffect(() => {
    execute({ claimId: id });
  }, [id]);

  // Always handle all states
  if (loading) return <Skeleton />;
  if (error) return <ErrorDisplay error={error} />;
  if (!data) return null;

  return <ClaimCard claim={data} />;
}

function ClaimActions({ claim }: { claim: Claim }) {
  const [optimisticStatus, setOptimisticStatus] = useState(claim.status);
  const { execute } = useCommand('@acme/claims/update-status');

  const handleApprove = async () => {
    setOptimisticStatus('approved');  // Optimistic update

    try {
      await execute({ claimId: claim.id, status: 'approved' });
    } catch (error) {
      setOptimisticStatus(claim.status);  // Revert on error
      toast.error('Failed to approve claim');
    }
  };

  return (
    <StatusBadge status={optimisticStatus} />
  );
}

function ClaimSearch() {
  const [query, setQuery] = useState('');
  const { execute, data, loading } = useCommand('@acme/claims/search');

  // Debounce search
  useEffect(() => {
    const timer = setTimeout(() => {
      if (query.length >= 2) {
        execute({ query });
      }
    }, 300);

    return () => clearTimeout(timer);
  }, [query]);

  return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      {loading ? <Spinner /> : <Results data={data} />}
    </div>
  );
}

# pseudocode — planned API
useRealtime('claims:created', (event) => {
  setClaims(prev => [event.data, ...prev]);
});