'use client'; import { PageShell } from '@/components/layout/PageShell'; import { useVconRole } from '@/components/layout/VconShell'; import { Button } from '@/components/ui/Button'; import { Card } from '@/components/ui/Card'; import { CodeBlock } from '@/components/ui/CodeBlock'; import { Select } from '@/components/ui/Input'; import { Panel } from '@/components/ui/Panel'; import { StatStrip } from '@/components/ui/StatStrip'; import { useToast } from '@/components/ui/Toast'; import { getCached, setCached } from '@/lib/vconCache'; import { getVconRoleCapabilities, resolvePublicEndpoints, } from '@/lib/vconUiHelpers'; import { useEffect, useState } from 'react'; interface SdkClientItem { clientId: string; name: string; status?: 'active' | 'revoked'; tokenPreview?: string; token?: string; } type SdkLanguageTab = 'python' | 'node' | 'curl'; export default function SdkGuidePage() { const { success, error } = useToast(); const shellRole = useVconRole(); const { canOperate } = getVconRoleCapabilities(shellRole); const [activeTab, setActiveTab] = useState('python'); const [clients, setClients] = useState(() => getCached('vcon:clients', []) ); const [selectedClientId, setSelectedClientId] = useState(() => { const cached = getCached('vcon:clients', []); return cached.find((c) => c.status !== 'revoked')?.clientId ?? cached[0]?.clientId ?? ''; }); const [selectedClientToken, setSelectedClientToken] = useState(''); const [loadingToken, setLoadingToken] = useState(false); const [serverUrl, setServerUrl] = useState('http://localhost:4000'); const [apiUrl, setApiUrl] = useState('http://localhost:3000'); useEffect(() => { const initialPort = getCached('vcon:server-port', 4000); const initialEndpoints = resolvePublicEndpoints(window.location, initialPort); setServerUrl(initialEndpoints.serverUrl); setApiUrl(initialEndpoints.apiUrl); async function loadSdkContext() { try { const [clientsRes, metricsRes] = await Promise.all([ fetch('/api/clients', { cache: 'no-store' }), fetch('/api/metrics', { cache: 'no-store' }).catch(() => null), ]); if (clientsRes.status === 401 || metricsRes?.status === 401) { window.location.assign('/vcon/login'); return; } if (clientsRes.ok) { const data = await clientsRes.json(); const list = setCached('vcon:clients', data.clients || []); setClients(list); if (list.length > 0) { setSelectedClientId((prev) => list.some((c) => c.clientId === prev) ? prev : list.find((c) => c.status !== 'revoked')?.clientId ?? list[0].clientId ); } } if (metricsRes && metricsRes.ok) { const metricsData = await metricsRes.json().catch(() => null); const runtimePort = Number(metricsData?.runtime?.serverPort); if (Number.isFinite(runtimePort) && runtimePort > 0) { setCached('vcon:server-port', runtimePort); const resolved = resolvePublicEndpoints(window.location, runtimePort); setServerUrl(resolved.serverUrl); setApiUrl(resolved.apiUrl); } } } catch { // Retain cached list on transient network error } } void loadSdkContext(); }, []); useEffect(() => { if (!selectedClientId || !canOperate) { setSelectedClientToken(''); setLoadingToken(false); return; } let cancelled = false; setSelectedClientToken(''); setLoadingToken(true); async function fetchToken() { try { const res = await fetch( `/api/clients/${encodeURIComponent(selectedClientId)}?includeToken=true`, { cache: 'no-store' } ); if (res.status === 401) { window.location.assign('/vcon/login'); return; } if (res.ok) { const data = await res.json(); if (!cancelled) { setSelectedClientToken(String(data?.client?.token || '')); } } else if (!cancelled) { setSelectedClientToken(''); } } catch { if (!cancelled) setSelectedClientToken(''); } finally { if (!cancelled) setLoadingToken(false); } } void fetchToken(); return () => { cancelled = true; }; }, [selectedClientId, canOperate]); const activeClient = clients.find((c) => c.clientId === selectedClientId) || clients[0]; const resolvedToken = loadingToken ? '' : selectedClientToken || activeClient?.token || ''; const sampleToken = loadingToken ? 'LOADING_CLIENT_JWT_TOKEN...' : resolvedToken || 'YOUR_SIGNED_CLIENT_JWT_TOKEN'; const clientIdValue = activeClient?.clientId || ''; const pythonConfigSnippet = `# config.datastack.py — Place in your Python project root DATASTACK_CONFIG = { "SERVER_URL": "${serverUrl}", "API_URL": "${apiUrl}", "CLIENT_TOKEN": "${sampleToken}", "CLIENT_ID": "${clientIdValue}", "AUTO_CONNECT": True, "ENABLE_HTTP_FALLBACK": True, "HEARTBEAT_INTERVAL_SEC": 5.0, "MAX_RETRIES": 3, "BATCH_CHUNK_SIZE": 250, "OFFLINE_SPOOL_ENABLED": True, "OFFLINE_SPOOL_DIR": ".datastack_spool", }`; const pythonSnippet = `from datastack import DataStack # Automatically discovers config.datastack.py and connects client = DataStack() # 1. Single Event (WebSocket + Auto HTTP Fallback + Offline Spool) res = client.send({ "event_type": "page_view", "url": "/products/wireless-headphones", "user_id": "usr_9942" }) print("Event response:", res) # 2. Batch Events batch_res = client.send_batch([ {"sensor": "temp", "value": 24.5, "unit": "C"}, {"sensor": "humidity", "value": 61.2, "unit": "%"} ]) print("Batch response:", batch_res) # 3. Direct File Ingestion (.csv, .json, .jsonl) file_res = client.send_file("events_dataset.csv", chunk_size=250) print("File ingestion:", file_res) # 4. Inspect Connection & Heartbeat IDLE Status print("SDK Status:", client.status()) client.disconnect()`; const nodeConfigSnippet = `// datastack.config.json — Place in your Node.js / TypeScript project root { "serverUrl": "${serverUrl}", "apiUrl": "${apiUrl}", "clientToken": "${sampleToken}", "clientId": "${clientIdValue}", "autoConnect": true, "enableHttpFallback": true, "heartbeatIntervalMs": 5000, "maxRetries": 3, "batchChunkSize": 250, "offlineSpoolEnabled": true, "offlineSpoolDir": ".datastack_spool" }`; const nodeSnippet = `import { DataStack } from '@datastack/sdk'; // Loads datastack.config.json or explicit constructor options const client = new DataStack({ serverUrl: '${serverUrl}', apiUrl: '${apiUrl}', token: '${sampleToken}', clientId: '${clientIdValue}', autoConnect: true, }); // 1. Single Event (Socket.IO Primary + Auto HTTP Fallback + Offline Spool) const res = await client.send({ event_type: 'checkout_completed', order_id: 'ord_9942', amount_usd: 149.5, }); console.log('Event response:', res); // 2. Batch Events (Auto-chunked & 413/429 resilient) const batchRes = await client.sendBatch([ { sensor: 'temp', value: 24.5, unit: 'C' }, { sensor: 'humidity', value: 61.2, unit: '%' }, ]); console.log('Batch response:', batchRes); // 3. Direct File Ingestion (.csv, .json, .jsonl, .ndjson with SHA-256 deterministic eventId) const fileRes = await client.sendFile('./events_dataset.csv', { chunkSize: 250 }); console.log('File ingestion:', fileRes); // 4. Graceful Shutdown Drain (awaits in-flight + drains offline spool) await client.shutdown(5000);`; const curlConfigSnippet = `# Environment exports for HTTP / cURL ingestion export DATASTACK_API_URL="${apiUrl}" export DATASTACK_CLIENT_ID="${clientIdValue}" export DATASTACK_CLIENT_TOKEN="${sampleToken}"`; const curlSnippet = `# 1. Single Event Ingestion via HTTP POST /api/events curl -X POST "${apiUrl}/api/events" \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer ${sampleToken}" \\ -d '{ "clientId": "${clientIdValue}", "data": { "event_type": "deployment_finished", "service": "billing-api", "status": "healthy" } }' # 2. Batch Event Ingestion via HTTP POST /api/events curl -X POST "${apiUrl}/api/events" \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer ${sampleToken}" \\ -d '{ "clientId": "${clientIdValue}", "batch": [ { "data": { "metric": "cpu_pct", "value": 31.4 } }, { "data": { "metric": "mem_pct", "value": 58.2 } } ] }'`; const activeConfigSnippet = activeTab === 'node' ? nodeConfigSnippet : activeTab === 'curl' ? curlConfigSnippet : pythonConfigSnippet; const activeCodeSnippet = activeTab === 'node' ? nodeSnippet : activeTab === 'curl' ? curlSnippet : pythonSnippet; const activeConfigLabel = activeTab === 'node' ? 'datastack.config.json' : activeTab === 'curl' ? 'Environment Variables' : 'config.datastack.py'; const activeCodeLabel = activeTab === 'node' ? 'Node.js / TypeScript SDK snippet' : activeTab === 'curl' ? 'cURL REST snippet' : 'Python SDK snippet'; const copySnippet = async (text: string, label: string) => { try { if (!navigator?.clipboard?.writeText) { throw new Error('Clipboard API unavailable in this browser context'); } await navigator.clipboard.writeText(text); success('Copied', `${label} copied`); } catch (copyErr) { error( 'Copy failed', copyErr instanceof Error ? copyErr.message : 'Unable to copy to clipboard. Copy manually from the code block.' ); } }; return ( {resolvedToken && ( )} } >
{activeTab === 'node' ? 'sdk/node/datastack' : activeTab === 'curl' ? 'POST /api/events' : 'sdk/python/datastack'}
{activeTab === 'python' && (
pip install /path/to/datastack/sdk/python/datastack

Self-hosted package bundled in sdk/python/datastack. From inside the repo run{' '} pip install ./sdk/python/datastack, or build a portable wheel with{' '} pip wheel ./sdk/python/datastack -w dist/ for external projects.

)} {activeTab === 'node' && (
npm install /path/to/datastack/sdk/node/datastack

Official Node.js & TypeScript package bundled in{' '} sdk/node/datastack (Node >= 20). Supports Socket.IO primary streaming, automatic{' '} POST /api/events fallback, deterministic{' '} sendFile() SHA-256 deduplication, offline disk spooling, and graceful{' '} await client.shutdown().

)} {!canOperate && (
Read-only {shellRole} session: Operator or Owner role required to reveal live client JWT tokens. Snippets below safely use placeholder{' '} YOUR_SIGNED_CLIENT_JWT_TOKEN .
)} {clients.length > 0 && (
)}