@dataworks-technology/data 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 /**
- * Public types for @dataworks/data.
+ * Public types for @dataworks-technology/data.
  *
  * @module @dataworks-technology/data
  */
@@ -9,6 +9,8 @@ interface DataClientConfig {
     cognitoEndpoint: string;
     /** Cognito app client ID */
     clientId: string;
+    /** Optional Cognito app client secret (if configured on the app client) */
+    clientSecret?: string;
     /** Data Engine ingest URL (API Gateway endpoint) */
     ingestUrl: string;
     /** Data Engine error reporting URL (API Gateway endpoint) */
@@ -70,6 +72,8 @@ interface ErrorReport {
 }
 /** Callback for subscription events. */
 type SubscriptionHandler = (event: unknown) => void;
+/** Callback for subscription errors (WebSocket errors, AppSync errors, reconnect failures). */
+type ErrorHandler = (error: Error) => void;
 /** Active subscription that can be closed. */
 interface Subscription {
     /** Close the subscription and disconnect. */
@@ -79,6 +83,8 @@ interface Subscription {
 declare class DataClient {
     private readonly config;
     private credentials;
+    private lastLoginUsername;
+    private refreshInFlight;
     constructor(config: DataClientConfig);
     /**
      * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.
@@ -87,6 +93,7 @@ declare class DataClient {
      * @param username - Cognito username
      * @param password - Cognito password
      * @returns Login result containing tokens and tenant
+     * @see https://data-sdk-docs.dataworks.live/authentication
      */
     login(username: string, password: string): Promise<LoginResult>;
     /**
@@ -97,6 +104,7 @@ declare class DataClient {
      * @param eventId - Event identifier
      * @param datasetDatasourceId - Dataset-datasource identifier
      * @throws Error if not authenticated or if the request fails
+     * @see https://data-sdk-docs.dataworks.live/ingesting-data
      */
     ingest(metrics: Metric[], eventId: string, datasetDatasourceId: string): Promise<void>;
     /**
@@ -104,20 +112,24 @@ declare class DataClient {
      *
      * @param error - Error report details
      * @throws Error if not authenticated or if the request fails
+     * @see https://data-sdk-docs.dataworks.live/error-reporting
      */
     reportError(error: ErrorReport): Promise<void>;
     /**
      * Subscribe to a real-time data channel on the AppSync Events API.
      * Uses the Cognito JWT for authentication.
      *
-     * The channel name maps to the AppSync Events API namespace (e.g. "dataworks/metrics").
+     * Channel format: dataworks/{datasetDatasourceId}/{eventId}/{metric}
+     * Use "*" for metric to receive all metrics for a dataset-datasource/event pair.
+     * Examples: "dataworks/1/1/heartrate", "dataworks/1/1/*".
      *
      * @param channel - Channel path to subscribe to
      * @param onEvent - Callback invoked for each received event
      * @returns Subscription handle with a close() method
      * @throws Error if not authenticated
+     * @see https://data-sdk-docs.dataworks.live/real-time-subscriptions
      */
-    subscribe(channel: string, onEvent: SubscriptionHandler): Subscription;
+    subscribe(channel: string, onEvent: SubscriptionHandler, onError?: ErrorHandler): Subscription;
     /**
      * Check whether a metric is valid before ingesting.
      * Returns null if valid, or a human-readable reason string if invalid.
@@ -134,6 +146,8 @@ declare class DataClient {
     get tenant(): string | null;
     /** @internal Throws if not authenticated. */
     private requireAuth;
+    private fetchWithAutoRefresh;
+    private refreshSession;
 }
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Public types for @dataworks/data.
+ * Public types for @dataworks-technology/data.
  *
  * @module @dataworks-technology/data
  */
@@ -9,6 +9,8 @@ interface DataClientConfig {
     cognitoEndpoint: string;
     /** Cognito app client ID */
     clientId: string;
+    /** Optional Cognito app client secret (if configured on the app client) */
+    clientSecret?: string;
     /** Data Engine ingest URL (API Gateway endpoint) */
     ingestUrl: string;
     /** Data Engine error reporting URL (API Gateway endpoint) */
@@ -70,6 +72,8 @@ interface ErrorReport {
 }
 /** Callback for subscription events. */
 type SubscriptionHandler = (event: unknown) => void;
+/** Callback for subscription errors (WebSocket errors, AppSync errors, reconnect failures). */
+type ErrorHandler = (error: Error) => void;
 /** Active subscription that can be closed. */
 interface Subscription {
     /** Close the subscription and disconnect. */
@@ -79,6 +83,8 @@ interface Subscription {
 declare class DataClient {
     private readonly config;
     private credentials;
+    private lastLoginUsername;
+    private refreshInFlight;
     constructor(config: DataClientConfig);
     /**
      * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.
@@ -87,6 +93,7 @@ declare class DataClient {
      * @param username - Cognito username
      * @param password - Cognito password
      * @returns Login result containing tokens and tenant
+     * @see https://data-sdk-docs.dataworks.live/authentication
      */
     login(username: string, password: string): Promise<LoginResult>;
     /**
@@ -97,6 +104,7 @@ declare class DataClient {
      * @param eventId - Event identifier
      * @param datasetDatasourceId - Dataset-datasource identifier
      * @throws Error if not authenticated or if the request fails
+     * @see https://data-sdk-docs.dataworks.live/ingesting-data
      */
     ingest(metrics: Metric[], eventId: string, datasetDatasourceId: string): Promise<void>;
     /**
@@ -104,20 +112,24 @@ declare class DataClient {
      *
      * @param error - Error report details
      * @throws Error if not authenticated or if the request fails
+     * @see https://data-sdk-docs.dataworks.live/error-reporting
      */
     reportError(error: ErrorReport): Promise<void>;
     /**
      * Subscribe to a real-time data channel on the AppSync Events API.
      * Uses the Cognito JWT for authentication.
      *
-     * The channel name maps to the AppSync Events API namespace (e.g. "dataworks/metrics").
+     * Channel format: dataworks/{datasetDatasourceId}/{eventId}/{metric}
+     * Use "*" for metric to receive all metrics for a dataset-datasource/event pair.
+     * Examples: "dataworks/1/1/heartrate", "dataworks/1/1/*".
      *
      * @param channel - Channel path to subscribe to
      * @param onEvent - Callback invoked for each received event
      * @returns Subscription handle with a close() method
      * @throws Error if not authenticated
+     * @see https://data-sdk-docs.dataworks.live/real-time-subscriptions
      */
-    subscribe(channel: string, onEvent: SubscriptionHandler): Subscription;
+    subscribe(channel: string, onEvent: SubscriptionHandler, onError?: ErrorHandler): Subscription;
     /**
      * Check whether a metric is valid before ingesting.
      * Returns null if valid, or a human-readable reason string if invalid.
@@ -134,6 +146,8 @@ declare class DataClient {
     get tenant(): string | null;
     /** @internal Throws if not authenticated. */
     private requireAuth;
+    private fetchWithAutoRefresh;
+    private refreshSession;
 }
 
 /**

package/dist/index.js

@@ -1,4 +1,46 @@
-// ../../node_modules/@dataworks/sdk/dist/client/validation.js
+// node_modules/@dataworks/sdk/dist/client/subscription-manager.js
+function createAutoRefreshingSubscription(options) {
+  const maxReconnectAttempts = options.maxReconnectAttempts ?? 1;
+  let reconnectAttempts = 0;
+  let reconnectInFlight = false;
+  let closedByUser = false;
+  let activeConnection = null;
+  const hooks = {
+    onUnexpectedClose: () => {
+      if (closedByUser || reconnectInFlight) {
+        return;
+      }
+      if (reconnectAttempts >= maxReconnectAttempts) {
+        return;
+      }
+      reconnectInFlight = true;
+      reconnectAttempts += 1;
+      void (async () => {
+        try {
+          await options.refreshAuth();
+          if (closedByUser) {
+            return;
+          }
+          activeConnection = options.connect(hooks);
+        } catch {
+          options.onReconnectError?.(new Error("Subscription reconnect failed. Please retry or reauthenticate."));
+        } finally {
+          reconnectInFlight = false;
+        }
+      })();
+    }
+  };
+  activeConnection = options.connect(hooks);
+  return {
+    close() {
+      closedByUser = true;
+      activeConnection?.close();
+      activeConnection = null;
+    }
+  };
+}
+
+// node_modules/@dataworks/sdk/dist/client/validation.js
 function validateMetric(m) {
   if (typeof m.metric !== "string" || m.metric.trim() === "")
     return "metric must be a non-empty string";
@@ -17,28 +59,59 @@ function validateMetric(m) {
   return null;
 }
 function filterValidMetrics(metrics, warn) {
+  const { valid, dropped } = getMetricValidationResult(metrics);
+  for (const item of dropped) {
+    let valueStr;
+    try {
+      valueStr = JSON.stringify(item.metric.value);
+    } catch {
+      valueStr = String(item.metric.value);
+    }
+    warn(`Dropping invalid metric [${String(item.metric.metric)}=${valueStr}]: ${item.reason}`);
+  }
+  return valid;
+}
+function getMetricValidationResult(metrics) {
   const valid = [];
-  for (const m of metrics) {
+  const dropped = [];
+  for (const [index, m] of metrics.entries()) {
     const reason = validateMetric(m);
     if (reason) {
-      warn(`Dropping invalid metric [${String(m.metric)}=${JSON.stringify(m.value)}]: ${reason}`);
+      dropped.push({
+        index,
+        reason,
+        metric: m
+      });
     } else {
       valid.push(m);
     }
   }
-  return valid;
+  return { valid, dropped };
 }
 
-// ../../node_modules/@dataworks/sdk/dist/client/auth.js
+// node_modules/@dataworks/sdk/dist/client/base64url.js
+var toBase64Url = (input) => {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input).toString("base64url");
+  }
+  return btoa(input).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+var fromBase64Url = (b64url) => {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(b64url, "base64url").toString("utf-8");
+  }
+  const padded = b64url.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((-b64url.length % 4 + 4) % 4);
+  return atob(padded);
+};
+
+// node_modules/@dataworks/sdk/dist/client/auth.js
 async function loginWithCredentials(username, password, config) {
   const authParams = {
     USERNAME: username,
     PASSWORD: password
   };
   if (config.clientSecret) {
-    const crypto2 = await import("crypto");
-    const hash = crypto2.createHmac("sha256", config.clientSecret).update(username + config.clientId).digest("base64");
-    authParams.SECRET_HASH = hash;
+    authParams.SECRET_HASH = await computeSecretHashAsync(username, config.clientId, config.clientSecret);
   }
   const resp = await fetch(config.cognitoEndpoint, {
     method: "POST",
@@ -69,15 +142,60 @@ async function loginWithCredentials(username, password, config) {
     tenant
   };
 }
+async function refreshWithToken(refreshToken, config) {
+  const authParams = {
+    REFRESH_TOKEN: refreshToken
+  };
+  if (config.clientSecret) {
+    if (!config.username) {
+      throw new Error("refreshWithToken: username is required when clientSecret is configured");
+    }
+    authParams.SECRET_HASH = await computeSecretHashAsync(config.username, config.clientId, config.clientSecret);
+  }
+  const resp = await fetch(config.cognitoEndpoint, {
+    method: "POST",
+    headers: {
+      "X-Amz-Target": "AWSCognitoIdentityProviderService.InitiateAuth",
+      "Content-Type": "application/x-amz-json-1.1"
+    },
+    body: JSON.stringify({
+      AuthFlow: "REFRESH_TOKEN_AUTH",
+      ClientId: config.clientId,
+      AuthParameters: authParams
+    })
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(`refreshWithToken: Cognito refresh failed: ${resp.status} \u2014 ${body}`);
+  }
+  const data = await resp.json();
+  const result = data.AuthenticationResult;
+  if (!result?.AccessToken) {
+    throw new Error("refreshWithToken: response missing AccessToken");
+  }
+  const idToken = result.IdToken ?? config.previousIdToken ?? "";
+  const extractedTenant = idToken ? extractTenantFromJwt(idToken) : "";
+  const tenant = extractedTenant || config.previousTenant || "";
+  return {
+    accessToken: result.AccessToken,
+    idToken,
+    refreshToken: result.RefreshToken ?? refreshToken,
+    tenant
+  };
+}
 function extractTenantFromJwt(idToken) {
   try {
     const payload = idToken.split(".")[1];
-    const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
-    return decoded["custom:tenant"] ?? decoded.tenant ?? decoded["cognito:groups"]?.[0] ?? "";
+    const decoded = JSON.parse(fromBase64Url(payload));
+    return decoded["custom:tenants"] ?? decoded["custom:tenant"] ?? decoded.tenant ?? decoded["cognito:groups"]?.[0] ?? "";
   } catch {
     return "";
   }
 }
+async function computeSecretHashAsync(username, clientId, clientSecret) {
+  const crypto2 = await import("crypto");
+  return crypto2.createHmac("sha256", clientSecret).update(username + clientId).digest("base64");
+}
 
 // src/validation.ts
 var validateMetric2 = validateMetric;
@@ -87,6 +205,8 @@ var filterValidMetrics2 = filterValidMetrics;
 var DataClient = class {
   constructor(config) {
     this.credentials = null;
+    this.lastLoginUsername = null;
+    this.refreshInFlight = null;
     this.config = config;
   }
   /**
@@ -96,11 +216,14 @@ var DataClient = class {
    * @param username - Cognito username
    * @param password - Cognito password
    * @returns Login result containing tokens and tenant
+   * @see https://data-sdk-docs.dataworks.live/authentication
    */
   async login(username, password) {
+    this.lastLoginUsername = username;
     this.credentials = await loginWithCredentials(username, password, {
       cognitoEndpoint: this.config.cognitoEndpoint,
-      clientId: this.config.clientId
+      clientId: this.config.clientId,
+      clientSecret: this.config.clientSecret
     });
     return this.credentials;
   }
@@ -112,6 +235,7 @@ var DataClient = class {
    * @param eventId - Event identifier
    * @param datasetDatasourceId - Dataset-datasource identifier
    * @throws Error if not authenticated or if the request fails
+   * @see https://data-sdk-docs.dataworks.live/ingesting-data
    */
   async ingest(metrics, eventId, datasetDatasourceId) {
     this.requireAuth();
@@ -125,14 +249,16 @@ var DataClient = class {
       datasetDatasourceId,
       metrics: valid
     };
-    const resp = await fetch(this.config.ingestUrl, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.credentials.accessToken}`
-      },
-      body: JSON.stringify(payload)
-    });
+    const resp = await this.fetchWithAutoRefresh(
+      (accessToken) => fetch(this.config.ingestUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${accessToken}`
+        },
+        body: JSON.stringify(payload)
+      })
+    );
     if (!resp.ok) {
       const body = await resp.text().catch(() => "");
       throw new Error(
@@ -145,23 +271,26 @@ var DataClient = class {
    *
    * @param error - Error report details
    * @throws Error if not authenticated or if the request fails
+   * @see https://data-sdk-docs.dataworks.live/error-reporting
    */
   async reportError(error) {
     this.requireAuth();
-    const resp = await fetch(this.config.errorUrl, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.credentials.accessToken}`
-      },
-      body: JSON.stringify({
-        client_id: String(error.clientId),
-        dataset_datasource_id: error.datasetDatasourceId,
-        athlete_id: error.athleteId,
-        error_title: error.errorTitle,
-        error_description: error.errorDescription
+    const resp = await this.fetchWithAutoRefresh(
+      (accessToken) => fetch(this.config.errorUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${accessToken}`
+        },
+        body: JSON.stringify({
+          client_id: String(error.clientId),
+          dataset_datasource_id: error.datasetDatasourceId,
+          athlete_id: error.athleteId,
+          error_title: error.errorTitle,
+          error_description: error.errorDescription
+        })
       })
-    });
+    );
     if (!resp.ok) {
       const body = await resp.text().catch(() => "");
       throw new Error(
@@ -173,56 +302,107 @@ var DataClient = class {
    * Subscribe to a real-time data channel on the AppSync Events API.
    * Uses the Cognito JWT for authentication.
    *
-   * The channel name maps to the AppSync Events API namespace (e.g. "dataworks/metrics").
+   * Channel format: dataworks/{datasetDatasourceId}/{eventId}/{metric}
+   * Use "*" for metric to receive all metrics for a dataset-datasource/event pair.
+   * Examples: "dataworks/1/1/heartrate", "dataworks/1/1/*".
    *
    * @param channel - Channel path to subscribe to
    * @param onEvent - Callback invoked for each received event
    * @returns Subscription handle with a close() method
    * @throws Error if not authenticated
+   * @see https://data-sdk-docs.dataworks.live/real-time-subscriptions
    */
-  subscribe(channel, onEvent) {
+  subscribe(channel, onEvent, onError) {
     this.requireAuth();
-    const url = new URL(this.config.realtimeUrl);
-    url.pathname = "/event/realtime";
-    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-    const authPayload = JSON.stringify({
-      Authorization: this.credentials.accessToken,
-      host: new URL(this.config.realtimeUrl).host
-    });
-    const authHeader = btoa(authPayload).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-    const ws = new WebSocket(url.toString(), [
-      "aws-appsync-event-ws",
-      `header-${authHeader}`
-    ]);
-    ws.addEventListener("open", () => {
-      ws.send(JSON.stringify({ type: "connection_init" }));
-    });
-    ws.addEventListener("message", (event) => {
-      try {
-        const msg = JSON.parse(String(event.data));
-        if (msg.type === "connection_ack") {
-          ws.send(
-            JSON.stringify({
-              type: "subscribe",
-              id: crypto.randomUUID(),
-              channel: `/${channel}`,
-              authorization: {
-                Authorization: this.credentials.accessToken,
-                host: new URL(this.config.realtimeUrl).host
+    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."
+      );
+    }
+    if (typeof crypto?.randomUUID !== "function") {
+      throw new Error(
+        "[@dataworks-technology/data] crypto.randomUUID() is not available. Use Node >= 19, Bun, or a browser with Crypto API support."
+      );
+    }
+    const channelPath = channel.startsWith("/") ? channel : `/${channel}`;
+    return createAutoRefreshingSubscription({
+      refreshAuth: async () => {
+        await this.refreshSession();
+      },
+      onReconnectError: (error) => {
+        onError?.(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 authHeader = toBase64Url(authPayload);
+        const ws = new WebSocket(url.toString(), [
+          "aws-appsync-event-ws",
+          `header-${authHeader}`
+        ]);
+        let closedByUser = false;
+        let unexpectedCloseHandled = false;
+        const handleUnexpectedCloseOnce = () => {
+          if (unexpectedCloseHandled) return;
+          unexpectedCloseHandled = true;
+          onUnexpectedClose();
+        };
+        ws.addEventListener("open", () => {
+          ws.send(JSON.stringify({ type: "connection_init" }));
+        });
+        ws.addEventListener("error", () => {
+          onError?.(new Error("[@dataworks-technology/data] WebSocket connection error"));
+        });
+        ws.addEventListener("message", (event) => {
+          try {
+            const msg = JSON.parse(String(event.data));
+            if (msg.type === "connection_ack") {
+              ws.send(
+                JSON.stringify({
+                  type: "subscribe",
+                  id: crypto.randomUUID(),
+                  channel: channelPath,
+                  authorization: {
+                    Authorization: this.credentials.accessToken,
+                    host
+                  }
+                })
+              );
+            } else if (msg.type === "data") {
+              onEvent(JSON.parse(msg.event));
+            } else if (msg.type === "error") {
+              const msgStr = JSON.stringify(msg);
+              if (msgStr.toLowerCase().includes("unauthor")) {
+                handleUnexpectedCloseOnce();
+              } else {
+                const errorMessage = msg.message ?? msg.errors?.[0]?.message ?? "AppSync subscription error";
+                onError?.(
+                  new Error(`[@dataworks-technology/data] ${errorMessage}`)
+                );
               }
-            })
-          );
-        } else if (msg.type === "data") {
-          onEvent(JSON.parse(msg.event));
-        }
-      } catch {
+            }
+          } catch {
+          }
+        });
+        ws.addEventListener("close", () => {
+          if (!closedByUser) {
+            handleUnexpectedCloseOnce();
+          }
+        });
+        return {
+          close() {
+            closedByUser = true;
+            ws.close();
+          }
+        };
       }
     });
-    return {
-      close() {
-        ws.close();
-      }
-    };
   }
   /** Returns true if the client has been authenticated via login(). */
   get isAuthenticated() {
@@ -240,6 +420,42 @@ var DataClient = class {
       );
     }
   }
+  async fetchWithAutoRefresh(makeRequest) {
+    this.requireAuth();
+    let response = await makeRequest(this.credentials.accessToken);
+    if (response.status !== 401) {
+      return response;
+    }
+    await this.refreshSession();
+    response = await makeRequest(this.credentials.accessToken);
+    return response;
+  }
+  async refreshSession() {
+    this.requireAuth();
+    if (!this.credentials.refreshToken) {
+      throw new Error(
+        "[@dataworks-technology/data] Session expired and no refresh token is available \u2014 call login() again"
+      );
+    }
+    if (!this.refreshInFlight) {
+      this.refreshInFlight = (async () => {
+        this.credentials = await refreshWithToken(
+          this.credentials.refreshToken,
+          {
+            cognitoEndpoint: this.config.cognitoEndpoint,
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            username: this.lastLoginUsername ?? void 0,
+            previousTenant: this.credentials.tenant,
+            previousIdToken: this.credentials.idToken
+          }
+        );
+      })().finally(() => {
+        this.refreshInFlight = null;
+      });
+    }
+    await this.refreshInFlight;
+  }
 };
 /**
  * Check whether a metric is valid before ingesting.