@dataworks-technology/data 0.1.4 → 0.1.6

package/README.md

@@ -3,6 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@dataworks-technology/data)](https://www.npmjs.com/package/@dataworks-technology/data)
 [![license](https://img.shields.io/npm/l/@dataworks-technology/data)](./LICENSE)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@dataworks-technology/data)](https://bundlephobia.com/package/@dataworks-technology/data)
+[![docs](https://img.shields.io/badge/docs-data--sdk--docs.dataworks.live-blue)](https://data-sdk-docs.dataworks.live)
 
 Official SDK for the Dataworks Data Engine — authenticate, ingest live athlete metrics, subscribe to real-time data streams, and report errors.
 
@@ -51,7 +52,7 @@ bun add @dataworks-technology/data
 ```typescript
 import { DataClient } from "@dataworks-technology/data";
 
-const client = new DataClient({
+const dataworks = new DataClient({
   cognitoEndpoint: "https://cognito-idp.eu-west-1.amazonaws.com/",
   clientId: "your-client-id",
   ingestUrl: "https://your-ingest-endpoint.dataworks.live",
@@ -60,14 +61,14 @@ const client = new DataClient({
 });
 
 // Authenticate
-await client.login("username", "password");
+await dataworks.login("username", "password");
 
 // Ingest metrics
-await client.ingest(
+await dataworks.ingest(
   [
     {
       athleteId: "athlete-1",
-      metric: "heartrate",
+      metric: "heartrate_calculated",
       value: 172,
       timestamp: Math.floor(Date.now() / 1000),
     },
@@ -84,7 +85,7 @@ await client.ingest(
 Create a new client instance.
 
 ```typescript
-const client = new DataClient({
+const dataworks = new DataClient({
   cognitoEndpoint: "https://cognito-idp.eu-west-1.amazonaws.com/",
   clientId: "abc123",
   ingestUrl: "https://ingest.dataworks.live",
@@ -93,52 +94,62 @@ const client = new DataClient({
 });
 ```
 
-### `client.login(username, password)`
+### `dataworks.login(username, password)`
 
 Authenticate with Cognito. Must be called before any other operation.
 
 ```typescript
-const result = await client.login("username", "password");
+const result = await dataworks.login("username", "password");
 // result: { accessToken, idToken, refreshToken, tenant }
 ```
 
-### `client.ingest(metrics, eventId, datasetDatasourceId)`
+### `dataworks.ingest(metrics, eventId, datasetDatasourceId)`
 
 Send metric data points to the Data Engine. Invalid metrics are automatically filtered out.
 
 ```typescript
-await client.ingest(
+await dataworks.ingest(
   [
-    { athleteId: "1", metric: "heartrate", value: 172, timestamp: 1700000000 },
-    { athleteId: "1", metric: "speed", value: 4.2, timestamp: 1700000000 },
+    { athleteId: "1", metric: "heartrate_calculated", value: 172, timestamp: 1700000000 },
+    { athleteId: "1", metric: "speed_calculated", value: 4.2, timestamp: 1700000000 },
   ],
   "event-123",
   "ds-456",
 );
 ```
 
-### `client.subscribe(channel, onEvent)`
+### `dataworks.subscribe(channel, onEvent, onError?)`
 
 Subscribe to real-time data events via WebSocket.
 
+Tip: start with `dataworks/1/1/*` to inspect all metrics for a dataset-datasource/event pair, then narrow to a specific metric channel such as `dataworks/1/1/heartrate`.
+
 ```typescript
-const subscription = client.subscribe(
-  "/default/events/event-123",
+const subscription = dataworks.subscribe(
+  "dataworks/1/1/heartrate",
   (event) => {
     console.log("Received:", event);
   },
+  (error) => {
+    console.error("Subscription error:", error.message);
+  },
 );
 
 // Later: close the subscription
 subscription.close();
 ```
 
-### `client.reportError(error)`
+The optional `onError` callback receives an `Error` for:
+- **WebSocket connection errors** (network failures, TLS errors)
+- **AppSync subscription errors** (invalid channel, server-side errors)
+- **Reconnect failures** (token refresh failed after an auth expiry)
+
+### `dataworks.reportError(error)`
 
 Report an error to the Data Engine for monitoring and alerting.
 
 ```typescript
-await client.reportError({
+await dataworks.reportError({
   datasetDatasourceId: "ds-456",
   athleteId: "athlete-123",
   clientId: 1,
@@ -147,22 +158,22 @@ await client.reportError({
 });
 ```
 
-### `client.isAuthenticated`
+### `dataworks.isAuthenticated`
 
 Check if the client has valid credentials.
 
 ```typescript
-if (client.isAuthenticated) {
-  await client.ingest(metrics, eventId, dsId);
+if (dataworks.isAuthenticated) {
+  await dataworks.ingest(metrics, eventId, dsId);
 }
 ```
 
-### `client.tenant`
+### `dataworks.tenant`
 
 Get the tenant from the authenticated session (or `null`).
 
 ```typescript
-console.log(`Logged in as tenant: ${client.tenant}`);
+console.log(`Logged in as tenant: ${dataworks.tenant}`);
 ```
 
 ## Validation Utilities
@@ -221,6 +232,7 @@ import type {
   MetricsPayload,
   ErrorReport,
   SubscriptionHandler,
+  ErrorHandler,
   Subscription,
 } from "@dataworks-technology/data";
 ```
@@ -257,13 +269,13 @@ All async methods throw on failure. Wrap calls in try/catch:
 
 ```typescript
 try {
-  await client.login("user", "pass");
+  await dataworks.login("user", "pass");
 } catch (err) {
   // Authentication failed (invalid credentials, network error, etc.)
 }
 
 try {
-  await client.ingest(metrics, eventId, dsId);
+  await dataworks.ingest(metrics, eventId, dsId);
 } catch (err) {
   // Ingestion failed (401 expired token, 5xx server error, etc.)
 }
@@ -285,7 +297,7 @@ A core use case: subscribe to live metrics, apply your own calculations external
 ### Concept
 
 ```
-Data Engine → subscribe("heartrate") → Your App → calculate rolling avg → ingest("heartrate_rolling_avg") → Data Engine
+Data Engine → subscribe("dataworks/{datasetDatasourceId}/{eventId}/heartrate") → Your App → calculate rolling avg → ingest("heartrate_rolling_avg_calculated") → Data Engine
 ```
 
 Any metric you ingest is treated the same as raw sensor data — it flows through the enrichment pipeline (avg/min/max/zones), gets stored, and is available via subscriptions and the GraphQL API.
@@ -295,7 +307,7 @@ Any metric you ingest is treated the same as raw sensor data — it flows throug
 ```typescript
 import { DataClient } from "@dataworks-technology/data";
 
-const client = new DataClient({
+const dataworks = new DataClient({
   cognitoEndpoint: "https://cognito-idp.eu-west-1.amazonaws.com/",
   clientId: "your-client-id",
   ingestUrl: "https://your-ingest-endpoint.dataworks.live",
@@ -303,13 +315,16 @@ const client = new DataClient({
   realtimeUrl: "https://your-realtime-endpoint.dataworks.live",
 });
 
-await client.login("developer", "password");
+await dataworks.login("developer", "password");
 
 // 1. Subscribe to raw heart rate data
 const buffer: number[] = [];
+const datasetDatasourceId = "1";
+const eventId = "1";
+const heartrateChannel = `dataworks/${datasetDatasourceId}/${eventId}/heartrate`;
 
-client.subscribe("dataworks/metrics", (event) => {
-  if (event.metric !== "heartrate") return;
+dataworks.subscribe(heartrateChannel, (event) => {
+  // No metric guard needed here: the channel already filters to heartrate.
 
   // 2. Calculate a rolling 3-point average
   buffer.push(event.value);
@@ -317,11 +332,11 @@ client.subscribe("dataworks/metrics", (event) => {
   const avg = buffer.reduce((a, b) => a + b, 0) / buffer.length;
 
   // 3. Push the derived metric back into the engine
-  client.ingest(
+  dataworks.ingest(
     [
       {
         athleteId: event.athleteId,
-        metric: "heartrate_rolling_avg",
+        metric: "heartrate_rolling_avg_calculated",
         value: Math.round(avg * 10) / 10,
         timestamp: event.timestamp,
       },
@@ -338,12 +353,12 @@ The same flow works from any language. A full working Python demo is included at
 
 | Phase | What it does | SDK equivalent |
 |-------|-------------|----------------|
-| 1. Authenticate | Cognito USER_PASSWORD_AUTH | `client.login()` |
-| 2. Subscribe | WebSocket → AppSync Events API | `client.subscribe()` |
+| 1. Authenticate | Cognito USER_PASSWORD_AUTH | `dataworks.login()` |
+| 2. Subscribe | WebSocket → AppSync Events API | `dataworks.subscribe()` |
 | 3. Receive | Catch events on the subscriber | `onEvent` callback |
 | 4. Calculate | Write to CSV/Google Sheets, compute rolling avg + HR zones | Your business logic |
-| 5. Re-ingest | POST enriched metrics back to the Data Engine | `client.ingest()` |
-| 6. Report Error | Send error through the error pipeline | `client.reportError()` |
+| 5. Re-ingest | POST enriched metrics back to the Data Engine | `dataworks.ingest()` |
+| 6. Report Error | Send error through the error pipeline | `dataworks.reportError()` |
 
 #### Run the demo
 
@@ -375,7 +390,7 @@ PHASE 5: RE-INGEST ENRICHED METRICS
   ✓ Ingested (200)
 ```
 
-The raw `heartrate` values (130–170 bpm) are transformed into `heartrate_rolling_avg` derived metrics and pushed back into the platform. These derived metrics are then available to all consumers (Console, Visual, Moments triggers) just like any other metric.
+The raw `heartrate` values (130–170 bpm) are transformed into `heartrate_rolling_avg_calculated` derived metrics and pushed back into the platform. These derived metrics are then available to all consumers (Console, Visual, Moments triggers) just like any other metric.
 
 #### Google Sheets (optional)
 
@@ -385,7 +400,7 @@ The demo can write to Google Sheets instead of CSV — formulas compute rolling
 
 | Derived metric | Calculation | Use case |
 |---|---|---|
-| `heartrate_rolling_avg` | 3-point moving average | Smooth noisy sensor data |
+| `heartrate_rolling_avg_calculated` | 3-point moving average | Smooth noisy sensor data |
 | `heartrate_zone` | Zone classification (1–5) | Training load analysis |
 | `speed_efficiency` | Speed / heart rate ratio | Fatigue detection |
 | `power_to_weight` | Power / athlete weight | Normalised performance |
@@ -396,7 +411,7 @@ The demo can write to Google Sheets instead of CSV — formulas compute rolling
 
 Full documentation with guides, examples, and detailed API reference:
 
-**[https://data-docs.dataworks.live](https://data-docs.dataworks.live)**
+**[https://data-sdk-docs.dataworks.live](https://data-sdk-docs.dataworks.live)**
 
 ## Development
 
@@ -408,9 +423,49 @@ This package publishes to **public npm** (`registry.npmjs.org`), not to the inte
 
 ```bash
 bun run build    # tsup → dist/ (ESM + CJS + DTS)
+bun run dev      # tsup --watch (rebuild on save)
 bun run test     # vitest unit tests (mocked — no infra needed)
 ```
 
+### Local Development
+
+To test SDK changes locally before publishing:
+
+**Option A — `npm pack` (recommended, simulates real install):**
+
+```bash
+# In packages/sdk/
+bun run build
+npm pack                    # creates dataworks-technology-data-0.1.4.tgz
+
+# In your consumer project (e.g. test/demo/)
+npm install ../../packages/sdk/dataworks-technology-data-0.1.4.tgz
+```
+
+**Option B — `bun link` (faster iteration):**
+
+```bash
+# In packages/sdk/
+bun run build
+bun link
+
+# In your consumer project
+bun link @dataworks-technology/data
+```
+
+**Option C — watch mode + link (live reload):**
+
+```bash
+# Terminal 1: packages/sdk/
+bun run dev                 # rebuilds dist/ on every save
+
+# Terminal 2: consumer project
+bun link @dataworks-technology/data
+npx tsx demo.ts             # picks up latest build automatically
+```
+
+> **Tip:** After local testing, remember to `bun unlink` or reinstall from npm before committing.
+
 ### Publish
 
 Login to npm first (one-time):
@@ -456,7 +511,7 @@ bun x vitest run test/e2e-public-sdk.test.ts
 | 1 | **Login** | `should authenticate testdeveloper` | USER_PASSWORD_AUTH works with frontend client | AWS Console → Cognito → User Pool → Users → `testdeveloper` exists in `developer` group |
 | 2 | **Login** | `should extract tenant from JWT` | `custom:tenant` claim is present in ID token | Decode the JWT at [jwt.io](https://jwt.io) — look for `custom:tenant` |
 | 3 | **Login** | `should include resource server scopes` | Pre-token Lambda injects `dataworks.live/read` and `/write` | AWS Console → Cognito → User Pool → Lambda triggers → Pre token generation V2 is set |
-| 4 | **Login** | `should reject invalid credentials` | Bad password returns error, not a token | Try `client.login("testdeveloper", "wrong")` — should throw |
+| 4 | **Login** | `should reject invalid credentials` | Bad password returns error, not a token | Try `dataworks.login("testdeveloper", "wrong")` — should throw |
 | 5 | **Ingest** | `should ingest valid metrics` | JWT passes API Gateway authoriser, Lambda processes payload | AWS Console → CloudWatch → Log group for the ingest Lambda — look for the metric |
 | 6 | **Ingest** | `should filter invalid metrics` | Client-side validation drops bad metrics before sending | The `stderr` output shows `Dropping invalid metric` — local validation, no server call for bad data |
 | 7 | **Ingest** | `should throw when not authenticated` | `ingest()` before `login()` throws immediately | Client-side guard — no network call made |