npm package: @neuroflow/sdk
Description: NeuroFlow TypeScript SDK — Build brain-computer interfaces with real-time EEG processing
Latest version: 0.1.0

# NeuroFlow SDK for TypeScript

[![Version](https://img.shields.io/badge/version-0.1.0-blue)](https://www.npmjs.com/package/@neuroflow/sdk)
[![TypeScript](https://img.shields.io/badge/typescript-5.0%2B-blue)](https://typescriptlang.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**Build brain-computer interfaces in TypeScript.** Connect to 20+ EEG/BCI devices, stream real-time neural data, and process signals directly in the browser with WASM.

```typescript
import { NeuroFlowClient } from '@neuroflow/sdk';

const client = new NeuroFlowClient({
  baseUrl: 'http://localhost:8000',
  apiKey: 'your-key',
});

// Discover and connect
const devices = await client.discoverDevices();
const device = await client.connectDevice(devices[0].id);

// Start session and stream
const session = await client.startSession({ deviceId: device.id });
const stream = client.createStream({ sessionId: session.id });

stream.on('features', (features) => {
  console.log(`Focus: ${features.focusScore}`);
  console.log(`Alpha: ${features.bandPowers.alpha}`);
});

await stream.connect();
```

## Installation

```bash
npm install @neuroflow/sdk
```

For in-browser WASM processing (optional):

```bash
npm install @neuroflow/sdk neuroflow-wasm
```

## Quick Start

### REST API Client

```typescript
import { NeuroFlowClient } from '@neuroflow/sdk';

const client = new NeuroFlowClient({
  baseUrl: 'http://localhost:8000',
  apiKey: 'your-key',
});

// Health check
const healthy = await client.isHealthy();

// Device management
const devices = await client.discoverDevices();
const connected = await client.connectDevice(devices[0].id);

// Session lifecycle
const session = await client.startSession({ deviceId: connected.id });
const features = await client.getFeatures(session.id);
console.log(features);
await client.stopSession(session.id);
```

### Real-Time Streaming

```typescript
import { NeuroFlowClient } from '@neuroflow/sdk';

const client = new NeuroFlowClient({ baseUrl, apiKey });
const session = await client.startSession({ deviceId });

const stream = client.createStream({
  sessionId: session.id,
  includeFeatures: true,
});

stream.on('data', (packet) => {
  console.log(`Sample ${packet.sampleIndex}:`, packet.channels);
});

stream.on('features', (features) => {
  console.log(`Focus: ${features.focusScore}`);
  console.log(`Alpha power: ${features.bandPowers.alpha}`);
});

stream.on('error', (err) => console.error(err));

await stream.connect();
```

### WASM Processing (Browser-Side DSP)

Process EEG data directly in the browser using the Rust DSP engine compiled to WebAssembly:

```typescript
import { NeuroFlowDSP, extractBandPowers } from '@neuroflow/sdk';

// Create pipeline: 4 channels, 256 Hz
const dsp = await NeuroFlowDSP.create(4, 256, {
  bandpass: [1, 45, 4],    // 1-45 Hz, order 4
  notch: [50, 30],         // 50 Hz powerline removal
});

// Process raw EEG chunk (flat Float64Array, row-major)
const rawData = new Float64Array(4 * 256); // 4 channels x 256 samples
const features = dsp.process(rawData);

// Extract structured band powers
const bands = extractBandPowers(features);
console.log(`Alpha: ${bands.alpha}, Beta: ${bands.beta}`);

// Cleanup
dsp.dispose();
```

### React Hooks

```tsx
import { NeuroFlowProvider, useSession, useFocusMetrics, useWasmPipeline } from '@neuroflow/sdk';

function App() {
  return (
    <NeuroFlowProvider config={{ baseUrl: 'http://localhost:8000', apiKey: 'key' }}>
      <Dashboard />
    </NeuroFlowProvider>
  );
}

function Dashboard() {
  const { session, start, stop, features } = useSession({
    client, deviceId: 'device-1',
  });

  const { focus, relaxation, averageFocus } = useFocusMetrics({
    client, sessionId: session?.id,
  });

  return (
    <div>
      <p>Focus: {(focus * 100).toFixed(0)}%</p>
      <p>Relaxation: {(relaxation * 100).toFixed(0)}%</p>
      <button onClick={start}>Start</button>
      <button onClick={stop}>Stop</button>
    </div>
  );
}
```

## Features

- **20+ Device Support** - Muse, OpenBCI, Emotiv, BrainBit, and more
- **Real-Time Streaming** - WebSocket with automatic reconnection and exponential backoff
- **WASM DSP** - Rust signal processing at 0.18ms P95 in the browser
- **React Hooks** - `useSession`, `useFocusMetrics`, `useDeviceConnection`, `useWasmPipeline`
- **Context Provider** - `NeuroFlowProvider` for shared client state
- **Type-Safe** - Full TypeScript with strict mode
- **Tree-Shakeable** - ESM + CJS dual output

## Documentation

- [Quickstart Guide](https://docs.neuroflow.dev/docs/quickstart)
- [TypeScript SDK Reference](https://docs.neuroflow.dev/docs/sdk-javascript)
- [API Reference](https://docs.neuroflow.dev/docs/api-reference)

## License

MIT