@kadoa/node-sdk 0.7.0 → 0.10.0

package/README.md

@@ -46,12 +46,30 @@ const client = new KadoaClient({
 });
 ```
 
+### Realtime Configuration
+
+To enable WebSocket connections for realtime events, use a team API key (starting with `tk-`):
+
+```typescript
+const client = new KadoaClient({
+  apiKey: 'tk-your-team-api-key',  // Must be a team API key
+  enableRealtime: true,
+  realtimeConfig: {
+    autoConnect: true,      // optional, default: true
+    reconnectDelay: 5000,   // optional, default: 5000ms
+    heartbeatInterval: 10000 // optional, default: 10000ms
+  }
+});
+```
+
 ### Using Environment Variables
 
 ```env
 KADOA_API_KEY=your-api-key
-KADOA_API_URL=https://api.kadoa.com
+KADOA_TEAM_API_KEY=tk-your-team-api-key  # For realtime features (optional)
+KADOA_PUBLIC_API_URI=https://api.kadoa.com
 KADOA_TIMEOUT=30000
+DEBUG=kadoa:*  # Enable all SDK debug logs (optional)
 ```
 
 ```typescript
@@ -62,7 +80,7 @@ config();
 
 const client = new KadoaClient({
   apiKey: process.env.KADOA_API_KEY!,
-  baseUrl: process.env.KADOA_API_URL,
+  baseUrl: process.env.KADOA_PUBLIC_API_URI,
   timeout: parseInt(process.env.KADOA_TIMEOUT || '30000')
 });
 ```
@@ -83,42 +101,209 @@ client.onEvent((event) => {
 // - extraction:status_changed
 // - extraction:data_available
 // - extraction:completed
+// - realtime:connected (when WebSocket enabled)
+// - realtime:disconnected
+// - realtime:event
+// - realtime:heartbeat
+// - realtime:error
+```
+
+### Realtime Events
+
+When realtime is enabled with a team API key:
+
+```typescript
+const client = new KadoaClient({
+  apiKey: 'tk-your-team-api-key',
+  enableRealtime: true
+});
+
+// Listen to realtime events
+client.onEvent((event) => {
+  if (event.type === 'realtime:event') {
+    console.log('Received realtime data:', event.payload.data);
+  }
+});
+
+// Manual connection control
+const realtime = client.connectRealtime();
+
+// Check connection status
+if (client.isRealtimeConnected()) {
+  console.log('Connected to realtime server');
+}
+
+// Disconnect when done
+client.disconnectRealtime();
 ```
 
-## API Reference
-
-### new KadoaClient(config)
-- `apiKey` (required): Your Kadoa API key
-- `baseUrl` (optional): API base URL (default: 'https://api.kadoa.com')
-- `timeout` (optional): Request timeout in milliseconds (default: 30000)
-
-Returns a client instance with:
-- `extraction`: Extraction module with `run()`, `submit()`, `fetchData()` methods
-- `workflow`: Workflow module with `get()`, `submit()`, `cancel()`, `wait()` methods
-- `onEvent()`: Subscribe to events
-- `offEvent()`: Unsubscribe from events
-- `dispose()`: Releases resources and removes all event listeners
-
-### client.extraction.run(options)
-Runs extraction and waits for completion.
-- `urls`: Array of URLs to extract from
-- `name`: Workflow name
-- Additional options available in API documentation
-
-### client.extraction.submit(options)
-Submits extraction without waiting for completion.
-- `urls`: Array of URLs to extract from
-- `name`: Workflow name
-- Returns: `{ workflowId: string }`
-
-### client.workflow.get(workflowId)
-Gets the current status of a workflow.
-- `workflowId`: The workflow ID to query
-- Returns: Workflow status object
+## Debug Logging
+
+The SDK uses the [debug](https://www.npmjs.com/package/debug) package for logging, which is disabled by default. Enable debug logs using the `DEBUG` environment variable:
+
+```bash
+# Enable all Kadoa SDK logs
+DEBUG=kadoa:* node app.js
+
+# Enable specific modules
+DEBUG=kadoa:client node app.js          # Client operations only
+DEBUG=kadoa:wss node app.js             # WebSocket logs only
+DEBUG=kadoa:extraction node app.js      # Extraction module logs
+DEBUG=kadoa:http node app.js            # HTTP request/response logs
+DEBUG=kadoa:workflow node app.js        # Workflow operations
+
+# Enable multiple modules
+DEBUG=kadoa:client,kadoa:extraction node app.js
+```
 
 ## Examples
 
-See [examples directory](https://github.com/kadoa-org/kadoa-sdks/tree/main/examples/node-examples) for more usage examples.
+### Basic Extraction
+
+```typescript
+import { KadoaClient } from '@kadoa/node-sdk';
+
+const client = new KadoaClient({
+  apiKey: 'your-api-key'
+});
+
+// Run an extraction
+const result = await client.extraction.run({
+  urls: ['https://sandbox.kadoa.com/ecommerce'],
+  name: 'My Extraction Workflow'
+});
+
+// Fetch paginated data
+if (result.workflowId) {
+  const page1 = await client.extraction.fetchData({
+    workflowId: result.workflowId,
+    page: 1
+  });
+
+  console.log('Data:', page1.data?.slice(0, 5));
+  console.log('Pagination:', page1.pagination);
+}
+```
+
+### WebSocket Events with Notifications
+
+```typescript
+// Initialize client with team API key for realtime features
+const client = new KadoaClient({
+  apiKey: 'tk-your-team-api-key',
+  enableRealtime: true,
+});
+
+// Listen to realtime events
+client.realtime?.onEvent((event) => {
+  console.log('Event received:', event);
+});
+
+// List available notification events
+const availableEvents = await client.notification.settings.listAllEvents();
+
+// Run extraction with notifications
+const result = await client.extraction.run({
+  urls: ['https://sandbox.kadoa.com/ecommerce'],
+  notifications: {
+    events: 'all', // or subset of availableEvents
+    channels: {
+      WEBSOCKET: true,
+    },
+  },
+});
+```
+
+### Data Validation with Rules
+
+```typescript
+import { KadoaClient, pollUntil } from '@kadoa/node-sdk';
+
+const client = new KadoaClient({ apiKey: 'your-api-key' });
+
+// 1. Run an extraction
+const result = await client.extraction.run({
+  urls: ['https://sandbox.kadoa.com/ecommerce'],
+});
+
+// 2. Wait for automatic rule suggestions
+const rulesResult = await pollUntil(
+  async () => await client.validation.listRules({
+    workflowId: result.workflowId,
+  }),
+  (result) => result.data.length > 0,
+  { pollIntervalMs: 1000, timeoutMs: 30000 }
+);
+
+// 3. Approve suggested rules
+const approvedRules = await client.validation.bulkApproveRules({
+  workflowId: result.workflowId,
+  ruleIds: rulesResult.result.data.map(rule => rule.id),
+});
+
+// 4. Run validation check
+const validation = await client.validation.scheduleValidation(
+  result.workflowId,
+  result.workflow?.jobId || ''
+);
+
+// 5. Wait for completion and check anomalies
+const completed = await client.validation.waitUntilCompleted(
+  validation.validationId
+);
+
+const anomalies = await client.validation.getValidationAnomalies(
+  validation.validationId
+);
+
+console.log('Validation anomalies:', anomalies);
+```
+
+### Complete Example
+
+```typescript
+import assert from 'node:assert';
+import { KadoaClient } from '@kadoa/node-sdk';
+
+async function main() {
+  const apiKey = process.env.KADOA_API_KEY;
+  assert(apiKey, 'KADOA_API_KEY is not set');
+
+  const client = new KadoaClient({ apiKey });
+
+  // Run extraction
+  const result = await client.extraction.run({
+    urls: ['https://sandbox.kadoa.com/ecommerce'],
+  });
+
+  // Fetch and display data
+  if (result.workflowId) {
+    const page1 = await client.extraction.fetchData({
+      workflowId: result.workflowId,
+      page: 1,
+    });
+
+    console.log('Page 1 Data:');
+    console.log('--------------------------------');
+    console.log(page1.data?.slice(0, 5));
+    console.log(page1.pagination);
+    console.log('--------------------------------');
+  }
+
+  console.log('Initial result:', result.data?.slice(0, 5));
+}
+
+main().catch(console.error);
+```
+
+### More Examples
+
+See the [examples directory](https://github.com/kadoa-org/kadoa-sdks/tree/main/examples/node-examples) for additional usage examples including:
+- Advanced extraction configurations
+- Custom validation rules
+- Error handling patterns
+- Batch processing
+- Integration patterns
 
 ## Requirements