2026-10-23 11:43:49 -05:00
|
|
|
'use client';
|
|
|
|
|
|
2026-11-17 00:24:33 +06:00
|
|
|
import { PageShell } from '@/components/layout/PageShell';
|
2026-10-23 11:43:49 -05:00
|
|
|
import { Button } from '@/components/ui/Button';
|
2026-11-16 21:58:18 +06:00
|
|
|
import { Card } from '@/components/ui/Card';
|
|
|
|
|
import { CodeBlock } from '@/components/ui/CodeBlock';
|
2026-10-23 11:43:49 -05:00
|
|
|
import { Select } from '@/components/ui/Input';
|
2026-11-16 21:58:18 +06:00
|
|
|
import { Panel } from '@/components/ui/Panel';
|
2026-11-17 00:24:33 +06:00
|
|
|
import { StatStrip } from '@/components/ui/StatStrip';
|
2026-10-23 11:43:49 -05:00
|
|
|
import { useToast } from '@/components/ui/Toast';
|
2026-11-16 23:10:44 +06:00
|
|
|
import { getCached, setCached } from '@/lib/vconCache';
|
2026-10-23 19:56:38 -07:00
|
|
|
import { useEffect, useState } from 'react';
|
2026-10-23 11:43:49 -05:00
|
|
|
|
2026-11-18 05:18:55 +06:00
|
|
|
interface SdkClientItem {
|
|
|
|
|
clientId: string;
|
|
|
|
|
name: string;
|
|
|
|
|
status?: 'active' | 'revoked';
|
|
|
|
|
tokenPreview?: string;
|
|
|
|
|
token?: string;
|
|
|
|
|
}
|
|
|
|
|
|
2026-10-23 11:43:49 -05:00
|
|
|
export default function SdkGuidePage() {
|
2026-11-18 05:18:55 +06:00
|
|
|
const { success, error } = useToast();
|
|
|
|
|
const [clients, setClients] = useState<SdkClientItem[]>(() =>
|
|
|
|
|
getCached<SdkClientItem[]>('vcon:clients', [])
|
2026-11-17 00:24:33 +06:00
|
|
|
);
|
2026-11-16 23:10:44 +06:00
|
|
|
const [selectedClientId, setSelectedClientId] = useState<string>(() => {
|
2026-11-18 05:18:55 +06:00
|
|
|
const cached = getCached<SdkClientItem[]>('vcon:clients', []);
|
|
|
|
|
return cached.find((c) => c.status !== 'revoked')?.clientId ?? cached[0]?.clientId ?? '';
|
2026-11-16 23:10:44 +06:00
|
|
|
});
|
2026-11-18 05:18:55 +06:00
|
|
|
const [selectedClientToken, setSelectedClientToken] = useState<string>('');
|
|
|
|
|
const [loadingToken, setLoadingToken] = useState<boolean>(false);
|
2026-11-17 00:24:33 +06:00
|
|
|
const [serverUrl, setServerUrl] = useState<string>('http://localhost:4000');
|
2026-11-18 02:23:01 +06:00
|
|
|
const [apiUrl, setApiUrl] = useState<string>('http://localhost:3000');
|
2026-10-23 11:43:49 -05:00
|
|
|
|
|
|
|
|
useEffect(() => {
|
2026-11-17 00:24:33 +06:00
|
|
|
const isLocalDev = window.location.port === '3000';
|
|
|
|
|
setServerUrl(
|
|
|
|
|
isLocalDev
|
|
|
|
|
? `${window.location.protocol}//${window.location.hostname}:4000`
|
|
|
|
|
: window.location.origin
|
|
|
|
|
);
|
2026-11-18 02:23:01 +06:00
|
|
|
setApiUrl(window.location.origin);
|
2026-11-17 00:24:33 +06:00
|
|
|
|
2026-10-23 11:43:49 -05:00
|
|
|
async function loadClients() {
|
|
|
|
|
try {
|
2026-11-18 05:18:55 +06:00
|
|
|
const res = await fetch('/api/clients', { cache: 'no-store' });
|
|
|
|
|
if (res.status === 401) {
|
|
|
|
|
window.location.assign('/vcon/login');
|
|
|
|
|
return;
|
|
|
|
|
}
|
2026-10-23 11:43:49 -05:00
|
|
|
if (res.ok) {
|
|
|
|
|
const data = await res.json();
|
2026-11-18 05:18:55 +06:00
|
|
|
const list = setCached<SdkClientItem[]>('vcon:clients', data.clients || []);
|
2026-10-23 11:43:49 -05:00
|
|
|
setClients(list);
|
|
|
|
|
if (list.length > 0) {
|
2026-11-17 20:05:00 +06:00
|
|
|
setSelectedClientId((prev) =>
|
2026-11-18 05:18:55 +06:00
|
|
|
list.some((c) => c.clientId === prev)
|
|
|
|
|
? prev
|
|
|
|
|
: list.find((c) => c.status !== 'revoked')?.clientId ?? list[0].clientId
|
2026-11-17 20:05:00 +06:00
|
|
|
);
|
2026-10-23 11:43:49 -05:00
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
} catch {
|
2026-11-18 05:18:55 +06:00
|
|
|
// Retain cached list on transient network error
|
2026-10-23 11:43:49 -05:00
|
|
|
}
|
|
|
|
|
}
|
2026-11-18 05:18:55 +06:00
|
|
|
void loadClients();
|
2026-10-23 11:43:49 -05:00
|
|
|
}, []);
|
|
|
|
|
|
2026-11-18 05:18:55 +06:00
|
|
|
useEffect(() => {
|
|
|
|
|
if (!selectedClientId) {
|
|
|
|
|
setSelectedClientToken('');
|
|
|
|
|
return;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
let cancelled = false;
|
|
|
|
|
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]);
|
|
|
|
|
|
2026-11-17 00:24:33 +06:00
|
|
|
const activeClient =
|
|
|
|
|
clients.find((c) => c.clientId === selectedClientId) || clients[0];
|
2026-11-18 05:18:55 +06:00
|
|
|
const resolvedToken = selectedClientToken || activeClient?.token || '';
|
|
|
|
|
const sampleToken = resolvedToken || 'YOUR_SIGNED_CLIENT_JWT_TOKEN';
|
2026-10-23 11:43:49 -05:00
|
|
|
|
2026-11-18 02:23:01 +06:00
|
|
|
const configSnippet = `# config.datastack.py — Place in your Python project root
|
|
|
|
|
DATASTACK_CONFIG = {
|
|
|
|
|
"SERVER_URL": "${serverUrl}",
|
|
|
|
|
"API_URL": "${apiUrl}",
|
|
|
|
|
"CLIENT_TOKEN": "${sampleToken}",
|
2026-11-18 05:18:55 +06:00
|
|
|
"CLIENT_ID": "${activeClient?.clientId || ''}",
|
2026-11-18 02:23:01 +06:00
|
|
|
"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",
|
|
|
|
|
}`;
|
2026-10-23 11:43:49 -05:00
|
|
|
|
2026-11-18 02:23:01 +06:00
|
|
|
const pythonSnippet = `from datastack import DataStack
|
2026-10-23 11:43:49 -05:00
|
|
|
|
2026-11-18 02:23:01 +06:00
|
|
|
# Automatically discovers config.datastack.py and connects
|
|
|
|
|
client = DataStack()
|
2026-10-23 11:43:49 -05:00
|
|
|
|
2026-11-18 02:23:01 +06:00
|
|
|
# 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)
|
2026-10-23 11:43:49 -05:00
|
|
|
|
2026-11-18 02:23:01 +06:00
|
|
|
# 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()`;
|
2026-10-23 11:43:49 -05:00
|
|
|
|
2026-11-18 05:18:55 +06:00
|
|
|
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.'
|
|
|
|
|
);
|
|
|
|
|
}
|
2026-10-23 11:43:49 -05:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
return (
|
2026-11-17 00:24:33 +06:00
|
|
|
<PageShell
|
|
|
|
|
title="Python SDK"
|
|
|
|
|
actions={
|
2026-11-17 20:05:00 +06:00
|
|
|
<>
|
2026-11-18 05:18:55 +06:00
|
|
|
{resolvedToken && (
|
2026-11-17 20:05:00 +06:00
|
|
|
<Button
|
|
|
|
|
size="xs"
|
|
|
|
|
variant="secondary"
|
|
|
|
|
icon="Key"
|
2026-11-18 05:18:55 +06:00
|
|
|
disabled={loadingToken}
|
|
|
|
|
onClick={() => void copySnippet(resolvedToken, 'Client JWT token')}
|
2026-11-17 20:05:00 +06:00
|
|
|
>
|
|
|
|
|
Copy Token
|
|
|
|
|
</Button>
|
|
|
|
|
)}
|
2026-11-18 02:23:01 +06:00
|
|
|
<Button
|
|
|
|
|
size="xs"
|
|
|
|
|
variant="secondary"
|
|
|
|
|
icon="FileCode"
|
2026-11-18 05:18:55 +06:00
|
|
|
onClick={() => void copySnippet(configSnippet, 'config.datastack.py')}
|
2026-11-18 02:23:01 +06:00
|
|
|
>
|
|
|
|
|
Copy Config
|
|
|
|
|
</Button>
|
2026-11-17 20:05:00 +06:00
|
|
|
<Button
|
|
|
|
|
size="xs"
|
|
|
|
|
variant="secondary"
|
|
|
|
|
icon="Copy"
|
2026-11-18 05:18:55 +06:00
|
|
|
onClick={() => void copySnippet(pythonSnippet, 'Python SDK snippet')}
|
2026-11-17 20:05:00 +06:00
|
|
|
>
|
|
|
|
|
Copy Code
|
|
|
|
|
</Button>
|
|
|
|
|
</>
|
2026-11-17 00:24:33 +06:00
|
|
|
}
|
|
|
|
|
>
|
|
|
|
|
<StatStrip
|
|
|
|
|
items={[
|
2026-11-18 02:23:01 +06:00
|
|
|
{ label: 'SDK package', value: 'datastack (v2.2.0)', dot: 'ok' },
|
|
|
|
|
{ label: 'Transport', value: 'WS + HTTP Fallback + Offline Spool' },
|
2026-11-17 00:24:33 +06:00
|
|
|
{ label: 'Server endpoint', value: serverUrl },
|
|
|
|
|
{
|
|
|
|
|
label: 'Active client',
|
|
|
|
|
value: activeClient?.clientId || 'None selected',
|
|
|
|
|
},
|
|
|
|
|
]}
|
2026-11-16 21:58:18 +06:00
|
|
|
/>
|
|
|
|
|
|
2026-11-17 00:24:33 +06:00
|
|
|
<Card
|
|
|
|
|
compact
|
|
|
|
|
className="flex w-full items-center justify-between bg-[var(--surface)] px-3 py-2 font-mono text-[11.5px]"
|
|
|
|
|
>
|
2026-11-18 02:23:01 +06:00
|
|
|
<span className="text-[var(--accent)]">
|
|
|
|
|
pip install ./sdk/python/datastack
|
|
|
|
|
</span>
|
2026-11-17 00:24:33 +06:00
|
|
|
<Button
|
|
|
|
|
size="xs"
|
|
|
|
|
variant="ghost"
|
|
|
|
|
icon="Copy"
|
2026-11-18 05:18:55 +06:00
|
|
|
aria-label="Copy pip install command"
|
2026-11-18 02:23:01 +06:00
|
|
|
onClick={() =>
|
2026-11-18 05:18:55 +06:00
|
|
|
void copySnippet('pip install ./sdk/python/datastack', 'Pip command')
|
2026-11-18 02:23:01 +06:00
|
|
|
}
|
2026-11-17 00:24:33 +06:00
|
|
|
/>
|
|
|
|
|
</Card>
|
2026-10-23 11:43:49 -05:00
|
|
|
|
2026-11-17 00:24:33 +06:00
|
|
|
<Panel
|
2026-11-18 02:23:01 +06:00
|
|
|
title="Step 1 — config.datastack.py"
|
2026-11-17 00:24:33 +06:00
|
|
|
className="w-full"
|
|
|
|
|
action={
|
2026-11-18 02:23:01 +06:00
|
|
|
<div className="flex items-center gap-2">
|
|
|
|
|
{clients.length > 0 && (
|
|
|
|
|
<div className="w-[190px]">
|
|
|
|
|
<Select
|
|
|
|
|
compact
|
2026-11-18 05:18:55 +06:00
|
|
|
aria-label="Select SDK client"
|
2026-11-18 02:23:01 +06:00
|
|
|
value={selectedClientId}
|
|
|
|
|
onChange={(e) => setSelectedClientId(e.target.value)}
|
|
|
|
|
>
|
|
|
|
|
{clients.map((c) => (
|
|
|
|
|
<option key={c.clientId} value={c.clientId}>
|
|
|
|
|
{c.clientId}
|
|
|
|
|
</option>
|
|
|
|
|
))}
|
|
|
|
|
</Select>
|
|
|
|
|
</div>
|
|
|
|
|
)}
|
|
|
|
|
<Button
|
|
|
|
|
size="xs"
|
|
|
|
|
variant="ghost"
|
|
|
|
|
icon="Copy"
|
2026-11-18 05:18:55 +06:00
|
|
|
aria-label="Copy config.datastack.py"
|
|
|
|
|
onClick={() => void copySnippet(configSnippet, 'config.datastack.py')}
|
2026-11-18 02:23:01 +06:00
|
|
|
/>
|
|
|
|
|
</div>
|
|
|
|
|
}
|
|
|
|
|
>
|
|
|
|
|
<CodeBlock>{configSnippet}</CodeBlock>
|
|
|
|
|
</Panel>
|
|
|
|
|
|
|
|
|
|
<Panel
|
|
|
|
|
title="Step 2 — Application Usage (Events, Batches & Direct CSV/JSON Files)"
|
|
|
|
|
className="w-full"
|
|
|
|
|
action={
|
|
|
|
|
<Button
|
|
|
|
|
size="xs"
|
|
|
|
|
variant="ghost"
|
|
|
|
|
icon="Copy"
|
2026-11-18 05:18:55 +06:00
|
|
|
aria-label="Copy Python SDK snippet"
|
|
|
|
|
onClick={() => void copySnippet(pythonSnippet, 'Python SDK snippet')}
|
2026-11-18 02:23:01 +06:00
|
|
|
/>
|
2026-11-17 00:24:33 +06:00
|
|
|
}
|
|
|
|
|
>
|
|
|
|
|
<CodeBlock>{pythonSnippet}</CodeBlock>
|
|
|
|
|
</Panel>
|
|
|
|
|
</PageShell>
|
2026-10-23 11:43:49 -05:00
|
|
|
);
|
|
|
|
|
}
|