@dataworks-technology/data 0.1.8 → 0.2.0

package/README.md

@@ -28,6 +28,7 @@ You need a Dataworks developer account. Contact your Dataworks administrator to
 | `errorUrl` | API Gateway endpoint for error reporting |
 | `realtimeUrl` | AppSync Events API endpoint for subscriptions |
 | Username + password | Your developer login credentials |
+| `apiKey` (optional) | AppSync Events API key for subscription-only access |
 
 ## Installation
 
@@ -58,6 +59,7 @@ const dataworks = new DataClient({
   ingestUrl: "https://your-ingest-endpoint.dataworks.live",
   errorUrl: "https://your-error-endpoint.dataworks.live",
   realtimeUrl: "https://your-realtime-endpoint.dataworks.live",
+  apiKey: "your-appsync-events-api-key", // optional
 });
 
 // Authenticate
@@ -94,9 +96,33 @@ const dataworks = new DataClient({
 });
 ```
 
+#### API Key Authentication (Subscription-Only)
+
+For read-only access to real-time subscriptions without Cognito credentials:
+
+```typescript
+import { DataClient, SubscriptionEvent } from "@dataworks-technology/data";
+
+const dataworks = new DataClient({
+  cognitoEndpoint: "https://cognito-idp.eu-west-1.amazonaws.com/",
+  clientId: "unused",
+  ingestUrl: "https://unused.dataworks.live",
+  errorUrl: "https://unused.dataworks.live",
+  realtimeUrl: "https://realtime.dataworks.live",
+  apiKey: "da2-xxxxxxxxxx", // AppSync Events API key
+});
+
+// No login required — subscribe directly
+const sub = dataworks.subscribe("dataworks/*", (event: SubscriptionEvent) => {
+  console.log(event.athleteId, event.metrics);
+});
+```
+
+> **Note:** API key authentication only supports subscriptions. Ingest and error reporting require Cognito credentials. If both `apiKey` and Cognito credentials are provided, Cognito takes precedence.
+
 ### `dataworks.login(username, password)`
 
-Authenticate with Cognito. Must be called before any other operation.
+Authenticate with Cognito. Must be called before any other operation (unless using API key for subscriptions).
 
 ```typescript
 const result = await dataworks.login("username", "password");
@@ -105,7 +131,7 @@ const result = await dataworks.login("username", "password");
 
 ### `dataworks.ingest(metrics, eventId, datasetDatasourceId)`
 
-Send metric data points to the Data Engine. Invalid metrics are automatically filtered out.
+Send metric data points to the Data Engine. Invalid metrics are dropped with warnings.
 
 ```typescript
 await dataworks.ingest(
@@ -118,6 +144,21 @@ await dataworks.ingest(
 );
 ```
 
+### `dataworks.ingestWithResult(metrics, eventId, datasetDatasourceId, options?)`
+
+Ingest with structured validation diagnostics.
+
+- Default mode (`best-effort`): invalid metrics are dropped and valid metrics continue.
+- Strict mode (`strict`): throws `MetricValidationError` if any metric is invalid.
+
+```typescript
+const result = await dataworks.ingestWithResult(metrics, "event-123", "ds-456", {
+  validationMode: "best-effort",
+});
+
+console.log(result.acceptedCount, result.droppedCount, result.requestSent);
+```
+
 ### `dataworks.subscribe(channel, onEvent, onError?)`
 
 Subscribe to real-time data events via WebSocket.
@@ -125,13 +166,16 @@ 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
+import { SubscriptionEvent, SubscriptionError } from "@dataworks-technology/data";
+
 const subscription = dataworks.subscribe(
   "dataworks/1/1/heartrate",
-  (event) => {
-    console.log("Received:", event);
+  (event: SubscriptionEvent) => {
+    console.log("Athlete:", event.athleteId);
+    console.log("Metrics:", event.metrics);
   },
-  (error) => {
-    console.error("Subscription error:", error.message);
+  (error: SubscriptionError) => {
+    console.error("Error:", error.message, "Code:", error.code);
   },
 );
 
@@ -139,10 +183,61 @@ const subscription = dataworks.subscribe(
 subscription.close();
 ```
 
-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)
+#### Event Type: `SubscriptionEvent`
+
+The standard Data Engine event shape:
+
+```typescript
+interface SubscriptionEvent {
+  name: string;              // e.g. "heartrateingested"
+  timestamp: number;         // Unix timestamp (milliseconds)
+  timestampSec: number;      // Unix timestamp (seconds)
+  eventId: string;
+  datasetDatasourceId: string;
+  athleteId: string;
+  metrics: SubscriptionMetric[];
+}
+
+interface SubscriptionMetric {
+  metric: string;            // e.g. "current", "heartrate"
+  value: number | string;
+}
+```
+
+#### Custom Event Types
+
+If your channel publishes a different format, use the generic type parameter:
+
+```typescript
+interface MyCustomEvent {
+  athleteId: string;
+  customField: number;
+}
+
+dataworks.subscribe<MyCustomEvent>("custom/*", (event) => {
+  console.log(event.customField); // TypeScript knows this exists
+});
+```
+
+#### Error Type: `SubscriptionError`
+
+```typescript
+interface SubscriptionError {
+  message: string;
+  code: "CONNECTION_ERROR" | "UNAUTHORIZED" | "SUBSCRIPTION_ERROR" 
+      | "PARSE_ERROR" | "RECONNECT_FAILED" | "UNKNOWN";
+  cause?: Error;
+}
+```
+
+| Code | Description |
+|------|-------------|
+| `CONNECTION_ERROR` | WebSocket connection failed (network, TLS) |
+| `UNAUTHORIZED` | Auth token expired or invalid |
+| `SUBSCRIPTION_ERROR` | AppSync subscription error (invalid channel, server error) |
+| `PARSE_ERROR` | Malformed message or event payload |
+| `RECONNECT_FAILED` | Token refresh failed after auth expiry |
+| `UNKNOWN` | Unexpected error |
 
 ### `dataworks.reportError(error)`
 
@@ -234,6 +329,10 @@ import type {
   SubscriptionHandler,
   ErrorHandler,
   Subscription,
+  ValidationMode,
+  DroppedMetric,
+  IngestOptions,
+  IngestResult,
 } from "@dataworks-technology/data";
 ```
 
@@ -283,6 +382,10 @@ try {
 
 Calling `ingest()`, `reportError()`, or `subscribe()` before `login()` throws immediately.
 
+Exception: `subscribe()` can run without `login()` when `apiKey` is configured. This mode is subscription-only — `ingest()` and `reportError()` still require `login()`.
+
+When both Cognito credentials (`login(username, password)` + `clientId`) and `apiKey` are available, the SDK always uses Cognito auth for subscriptions.
+
 ## Requirements
 
 - **Node.js** ≥ 18 (uses native `fetch`)

package/dist/index.cjs

@@ -31,11 +31,32 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   DataClient: () => DataClient,
+  MetricValidationError: () => MetricValidationError,
   filterValidMetrics: () => filterValidMetrics2,
   validateMetric: () => validateMetric2
 });
 module.exports = __toCommonJS(index_exports);
 
+// node_modules/@dataworks/sdk/dist/client/events-auth.js
+var INGEST_AUTH_ERROR = "Authentication failed: username, password, and clientId are required for ingest.";
+function resolveEventsAuth(input) {
+  const userToken = input.userToken?.trim();
+  if (userToken) {
+    return { mode: "userCredentials", token: userToken };
+  }
+  const apiKey = input.apiKey?.trim();
+  if (apiKey) {
+    return { mode: "apiKey", apiKey };
+  }
+  throw new Error(INGEST_AUTH_ERROR);
+}
+function buildEventsAuthHeader(resolved, host) {
+  if (resolved.mode === "userCredentials") {
+    return { Authorization: resolved.token, host };
+  }
+  return { "x-api-key": resolved.apiKey, host };
+}
+
 // node_modules/@dataworks/sdk/dist/client/subscription-manager.js
 function createAutoRefreshingSubscription(options) {
   const maxReconnectAttempts = options.maxReconnectAttempts ?? 1;
@@ -238,8 +259,22 @@ async function computeSecretHashAsync(username, clientId, clientSecret) {
 // src/validation.ts
 var validateMetric2 = validateMetric;
 var filterValidMetrics2 = filterValidMetrics;
+var getMetricValidationResult2 = getMetricValidationResult;
+
+// src/types.ts
+var MetricValidationError = class extends Error {
+  constructor(message, dropped) {
+    super(message);
+    this.code = "METRIC_VALIDATION_FAILED";
+    this.name = "MetricValidationError";
+    this.dropped = dropped;
+  }
+};
 
 // src/data-client.ts
+function createSubscriptionError(message, code, cause) {
+  return { message, code, cause };
+}
 var DataClient = class {
   constructor(config) {
     this.credentials = null;
@@ -267,7 +302,7 @@ var DataClient = class {
   }
   /**
    * Ingest metric data points into the Dataworks Data Engine.
-   * Validates each metric before sending — invalid metrics are silently dropped.
+   * Validates each metric before sending — invalid metrics are dropped with warnings.
    *
    * @param metrics - Array of metric data points
    * @param eventId - Event identifier
@@ -276,12 +311,53 @@ var DataClient = class {
    * @see https://data-sdk-docs.dataworks.live/ingesting-data
    */
   async ingest(metrics, eventId, datasetDatasourceId) {
-    this.requireAuth();
-    const valid = filterValidMetrics2(
-      metrics,
-      (msg) => console.warn(`[@dataworks-technology/data] ${msg}`)
-    );
-    if (valid.length === 0) return;
+    await this.ingestWithResult(metrics, eventId, datasetDatasourceId);
+  }
+  /**
+   * Ingest metrics with structured validation diagnostics.
+   *
+   * By default (`validationMode: "best-effort"`), invalid metrics are dropped and
+   * valid metrics continue. In strict mode, invalid metrics cause a
+   * MetricValidationError before any network request is sent.
+   *
+   * @returns IngestResult with accepted/dropped counts and dropped reasons.
+   */
+  async ingestWithResult(metrics, eventId, datasetDatasourceId, options = {}) {
+    this.requireIngestAuth();
+    const validationMode = options.validationMode ?? "best-effort";
+    const validation = getMetricValidationResult2(metrics);
+    const valid = validation.valid;
+    const dropped = validation.dropped.map((item) => ({
+      index: item.index,
+      reason: item.reason,
+      metric: item.metric
+    }));
+    dropped.forEach((item) => {
+      options.onDroppedMetric?.(item);
+      console.warn(
+        `[@dataworks-technology/data] Dropping invalid metric [${String(item.metric.metric)}=${String(item.metric.value)}]: ${item.reason}`
+      );
+    });
+    if (validationMode === "strict" && dropped.length > 0) {
+      throw new MetricValidationError(
+        "[@dataworks-technology/data] validation failed: one or more metrics are invalid",
+        dropped
+      );
+    }
+    if (valid.length === 0) {
+      if (options.requireAtLeastOneValidMetric) {
+        throw new MetricValidationError(
+          "[@dataworks-technology/data] validation failed: no valid metrics to ingest",
+          dropped
+        );
+      }
+      return {
+        acceptedCount: 0,
+        droppedCount: dropped.length,
+        dropped,
+        requestSent: false
+      };
+    }
     const payload = {
       eventId,
       datasetDatasourceId,
@@ -303,6 +379,12 @@ var DataClient = class {
         `[@dataworks-technology/data] ingest failed: ${resp.status} \u2014 ${body}`
       );
     }
+    return {
+      acceptedCount: valid.length,
+      droppedCount: dropped.length,
+      dropped,
+      requestSent: true
+    };
   }
   /**
    * Report an error to the Dataworks Data Engine.
@@ -312,7 +394,7 @@ var DataClient = class {
    * @see https://data-sdk-docs.dataworks.live/error-reporting
    */
   async reportError(error) {
-    this.requireAuth();
+    this.requireIngestAuth();
     const resp = await this.fetchWithAutoRefresh(
       (accessToken) => fetch(this.config.errorUrl, {
         method: "POST",
@@ -351,7 +433,10 @@ var DataClient = class {
    * @see https://data-sdk-docs.dataworks.live/real-time-subscriptions
    */
   subscribe(channel, onEvent, onError) {
-    this.requireAuth();
+    const apiKey = this.config.apiKey?.trim();
+    if (!this.credentials && !apiKey) {
+      this.requireAuth();
+    }
     if (typeof WebSocket === "undefined") {
       throw new Error(
         "[@dataworks-technology/data] WebSocket is not available. Use Node >= 22, Bun, or a browser environment. For older Node versions, install a WebSocket polyfill (e.g. ws) and assign it to globalThis.WebSocket."
@@ -365,20 +450,26 @@ var DataClient = class {
     const channelPath = channel.startsWith("/") ? channel : `/${channel}`;
     return createAutoRefreshingSubscription({
       refreshAuth: async () => {
-        await this.refreshSession();
+        if (this.credentials) {
+          await this.refreshSession();
+        }
       },
       onReconnectError: (error) => {
-        onError?.(error);
+        onError?.(
+          createSubscriptionError(error.message, "RECONNECT_FAILED", error)
+        );
       },
       connect: ({ onUnexpectedClose }) => {
         const url = new URL(this.config.realtimeUrl);
         url.pathname = "/event/realtime";
         url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
         const host = new URL(this.config.realtimeUrl).host;
-        const authPayload = JSON.stringify({
-          Authorization: this.credentials.accessToken,
-          host
+        const resolvedAuth = resolveEventsAuth({
+          userToken: this.credentials?.accessToken,
+          apiKey: this.config.apiKey?.trim()
         });
+        const realtimeAuthHeader = buildEventsAuthHeader(resolvedAuth, host);
+        const authPayload = JSON.stringify(realtimeAuthHeader);
         const authHeader = toBase64Url(authPayload);
         const ws = new WebSocket(url.toString(), [
           "aws-appsync-event-ws",
@@ -396,8 +487,9 @@ var DataClient = class {
         });
         ws.addEventListener("error", () => {
           onError?.(
-            new Error(
-              "[@dataworks-technology/data] WebSocket connection error"
+            createSubscriptionError(
+              "[@dataworks-technology/data] WebSocket connection error",
+              "CONNECTION_ERROR"
             )
           );
         });
@@ -407,8 +499,9 @@ var DataClient = class {
             msg = JSON.parse(String(event.data));
           } catch {
             onError?.(
-              new Error(
-                "[@dataworks-technology/data] Received malformed message from AppSync"
+              createSubscriptionError(
+                "[@dataworks-technology/data] Received malformed message from AppSync",
+                "PARSE_ERROR"
               )
             );
             return;
@@ -419,10 +512,7 @@ var DataClient = class {
                 type: "subscribe",
                 id: crypto.randomUUID(),
                 channel: channelPath,
-                authorization: {
-                  Authorization: this.credentials.accessToken,
-                  host
-                }
+                authorization: realtimeAuthHeader
               })
             );
           } else if (msg.type === "data") {
@@ -432,21 +522,31 @@ var DataClient = class {
                 onEvent(JSON.parse(String(raw)));
               } catch {
                 onError?.(
-                  new Error(
-                    "[@dataworks-technology/data] Received malformed event payload from AppSync"
+                  createSubscriptionError(
+                    "[@dataworks-technology/data] Received malformed event payload from AppSync",
+                    "PARSE_ERROR"
                   )
                 );
               }
             }
           } else if (msg.type === "error" || msg.type === "connection_error" || msg.type === "subscribe_error" || msg.type === "broadcast_error" || msg.type === "unsubscribe_error") {
             const msgStr = JSON.stringify(msg);
-            if (msgStr.toLowerCase().includes("unauthor")) {
+            if (msgStr.toLowerCase().includes("unauthor") && !unexpectedCloseHandled) {
+              onError?.(
+                createSubscriptionError(
+                  "[@dataworks-technology/data] Unauthorized \u2014 session may have expired, attempting to reconnect",
+                  "UNAUTHORIZED"
+                )
+              );
               handleUnexpectedCloseOnce();
             } else {
               const errors = msg.errors;
               const errorMessage = msg.message ?? errors?.[0]?.message ?? errors?.[0]?.errorType ?? "AppSync subscription error";
               onError?.(
-                new Error(`[@dataworks-technology/data] ${errorMessage}`)
+                createSubscriptionError(
+                  `[@dataworks-technology/data] ${errorMessage}`,
+                  "SUBSCRIPTION_ERROR"
+                )
               );
             }
           }
@@ -481,6 +581,16 @@ var DataClient = class {
       );
     }
   }
+  /**
+   * @internal Guard for ingest-only operations (ingest, reportError). Throws the
+   * canonical SDK ingest auth error so the message is consistent with the lower-level
+   * `@dataworks/sdk/client` HttpClient guard.
+   */
+  requireIngestAuth() {
+    if (!this.credentials) {
+      throw new Error(`[@dataworks-technology/data] ${INGEST_AUTH_ERROR}`);
+    }
+  }
   async fetchWithAutoRefresh(makeRequest) {
     this.requireAuth();
     let response = await makeRequest(this.credentials.accessToken);
@@ -531,6 +641,7 @@ DataClient.filterValidMetrics = filterValidMetrics2;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DataClient,
+  MetricValidationError,
   filterValidMetrics,
   validateMetric
 });