@dataworks-technology/data 0.1.3

package/README.md

@@ -0,0 +1,289 @@
+# @dataworks-technology/data
+
+[![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)
+
+Official SDK for the Dataworks Data Engine — authenticate, ingest live athlete metrics, subscribe to real-time data streams, and report errors.
+
+## Features
+
+- **Zero dependencies** — fully self-contained, no transitive installs
+- **Dual format** — ESM and CommonJS bundles included
+- **TypeScript-first** — complete type declarations shipped with the package
+- **Built-in validation** — metrics are validated before ingestion
+- **Real-time subscriptions** — WebSocket-based live data streaming
+- **Cognito authentication** — secure login with automatic token management
+
+## Prerequisites
+
+You need a Dataworks developer account. Contact your Dataworks administrator to receive:
+
+| Credential | Description |
+|---|---|
+| `cognitoEndpoint` | Cognito User Pool endpoint URL |
+| `clientId` | Cognito app client ID |
+| `ingestUrl` | API Gateway endpoint for metric ingestion |
+| `errorUrl` | API Gateway endpoint for error reporting |
+| `realtimeUrl` | AppSync Events API endpoint for subscriptions |
+| Username + password | Your developer login credentials |
+
+## Installation
+
+```bash
+npm install @dataworks-technology/data
+```
+
+```bash
+yarn add @dataworks-technology/data
+```
+
+```bash
+pnpm add @dataworks-technology/data
+```
+
+```bash
+bun add @dataworks-technology/data
+```
+
+## Quick Start
+
+```typescript
+import { DataClient } from "@dataworks-technology/data";
+
+const client = new DataClient({
+  cognitoEndpoint: "https://cognito-idp.eu-west-1.amazonaws.com/",
+  clientId: "your-client-id",
+  ingestUrl: "https://your-ingest-endpoint.dataworks.live",
+  errorUrl: "https://your-error-endpoint.dataworks.live",
+  realtimeUrl: "https://your-realtime-endpoint.dataworks.live",
+});
+
+// Authenticate
+await client.login("username", "password");
+
+// Ingest metrics
+await client.ingest(
+  [
+    {
+      athleteId: "athlete-1",
+      metric: "heartrate",
+      value: 172,
+      timestamp: Math.floor(Date.now() / 1000),
+    },
+  ],
+  "event-id",
+  "dataset-datasource-id",
+);
+```
+
+## API
+
+### `new DataClient(config)`
+
+Create a new client instance.
+
+```typescript
+const client = new DataClient({
+  cognitoEndpoint: "https://cognito-idp.eu-west-1.amazonaws.com/",
+  clientId: "abc123",
+  ingestUrl: "https://ingest.dataworks.live",
+  errorUrl: "https://errors.dataworks.live",
+  realtimeUrl: "https://realtime.dataworks.live",
+});
+```
+
+### `client.login(username, password)`
+
+Authenticate with Cognito. Must be called before any other operation.
+
+```typescript
+const result = await client.login("username", "password");
+// result: { accessToken, idToken, refreshToken, tenant }
+```
+
+### `client.ingest(metrics, eventId, datasetDatasourceId)`
+
+Send metric data points to the Data Engine. Invalid metrics are automatically filtered out.
+
+```typescript
+await client.ingest(
+  [
+    { athleteId: "1", metric: "heartrate", value: 172, timestamp: 1700000000 },
+    { athleteId: "1", metric: "speed", value: 4.2, timestamp: 1700000000 },
+  ],
+  "event-123",
+  "ds-456",
+);
+```
+
+### `client.subscribe(channel, onEvent)`
+
+Subscribe to real-time data events via WebSocket.
+
+```typescript
+const subscription = client.subscribe(
+  "/default/events/event-123",
+  (event) => {
+    console.log("Received:", event);
+  },
+);
+
+// Later: close the subscription
+subscription.close();
+```
+
+### `client.reportError(error)`
+
+Report an error to the Data Engine for monitoring and alerting.
+
+```typescript
+await client.reportError({
+  datasetDatasourceId: "ds-456",
+  eventId: "event-123",
+  clientId: 1,
+  errorTitle: "Sensor disconnected",
+  errorDescription: "BLE heart rate sensor lost connection at 00:42:15",
+});
+```
+
+### `client.isAuthenticated`
+
+Check if the client has valid credentials.
+
+```typescript
+if (client.isAuthenticated) {
+  await client.ingest(metrics, eventId, dsId);
+}
+```
+
+### `client.tenant`
+
+Get the tenant from the authenticated session (or `null`).
+
+```typescript
+console.log(`Logged in as tenant: ${client.tenant}`);
+```
+
+## Validation Utilities
+
+Standalone validation functions are exported for pre-checking metrics before ingestion:
+
+### `DataClient.validateMetric(metric)`
+
+Returns `null` if valid, or a string describing the validation failure.
+
+```typescript
+import { validateMetric } from "@dataworks-technology/data";
+
+const error = validateMetric({
+  metric: "heartrate",
+  athleteId: "1",
+  value: 172,
+  timestamp: 1700000000,
+});
+
+if (error) {
+  console.warn("Invalid metric:", error);
+}
+```
+
+### `DataClient.filterValidMetrics(metrics, warnFn)`
+
+Filters an array, keeping only valid metrics. Calls `warnFn` for each invalid item.
+
+```typescript
+import { filterValidMetrics } from "@dataworks-technology/data";
+
+const valid = filterValidMetrics(rawMetrics, (msg) => console.warn(msg));
+```
+
+### Validation Rules
+
+| Field | Rule |
+|---|---|
+| `metric` | Non-empty string |
+| `athleteId` | Non-empty string |
+| `value` | Number (finite, not NaN) or non-empty string |
+| `timestamp` | Positive integer (Unix seconds) |
+
+## Types
+
+All types are exported for use in your application:
+
+```typescript
+import type {
+  DataClientConfig,
+  LoginResult,
+  Metric,
+  MetricItem,
+  RawMetricItem,
+  MetricsPayload,
+  ErrorReport,
+  SubscriptionHandler,
+  Subscription,
+} from "@dataworks-technology/data";
+```
+
+### Key Interfaces
+
+```typescript
+interface Metric {
+  athleteId: string;
+  metric: string;
+  value: number | string;
+  timestamp: number; // Unix seconds
+}
+
+interface ErrorReport {
+  datasetDatasourceId: string;
+  eventId: string;
+  clientId: number;
+  errorTitle: string;
+  errorDescription: string;
+}
+
+interface LoginResult {
+  accessToken: string;
+  idToken: string;
+  refreshToken: string;
+  tenant: string;
+}
+```
+
+## Error Handling
+
+All async methods throw on failure. Wrap calls in try/catch:
+
+```typescript
+try {
+  await client.login("user", "pass");
+} catch (err) {
+  // Authentication failed (invalid credentials, network error, etc.)
+}
+
+try {
+  await client.ingest(metrics, eventId, dsId);
+} catch (err) {
+  // Ingestion failed (401 expired token, 5xx server error, etc.)
+}
+```
+
+Calling `ingest()`, `reportError()`, or `subscribe()` before `login()` throws immediately.
+
+## Requirements
+
+- **Node.js** ≥ 18 (uses native `fetch`)
+- **ESM or CommonJS** — both module formats are included
+- **TypeScript** ≥ 5.0 (optional — works with plain JavaScript too)
+- **Browser** — compatible with any environment that has `fetch` and `WebSocket`
+
+## Documentation
+
+Full documentation with guides, examples, and detailed API reference:
+
+**[https://data-docs.dataworks.live](https://data-docs.dataworks.live)**
+
+## License
+
+MIT © [Dataworks Technology](https://github.com/Dataworks-Technology)

package/dist/index.cjs

@@ -0,0 +1,291 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DataClient: () => DataClient,
+  filterValidMetrics: () => filterValidMetrics2,
+  validateMetric: () => validateMetric2
+});
+module.exports = __toCommonJS(index_exports);
+
+// ../../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";
+  if (typeof m.athleteId !== "string" || m.athleteId.trim() === "")
+    return "athleteId must be a non-empty string";
+  if (!Number.isInteger(m.timestamp) || m.timestamp <= 0)
+    return `timestamp must be a positive integer, got ${m.timestamp}`;
+  if (m.value === null || m.value === void 0)
+    return "value is null/undefined";
+  if (typeof m.value === "number" && !isFinite(m.value))
+    return `value is non-finite number (${m.value})`;
+  if (typeof m.value !== "number" && typeof m.value !== "string")
+    return `value type ${typeof m.value} not allowed (must be number or string)`;
+  if (typeof m.value === "string" && m.value === "")
+    return "value is empty string";
+  return null;
+}
+function filterValidMetrics(metrics, warn) {
+  const valid = [];
+  for (const m of metrics) {
+    const reason = validateMetric(m);
+    if (reason) {
+      warn(`Dropping invalid metric [${String(m.metric)}=${JSON.stringify(m.value)}]: ${reason}`);
+    } else {
+      valid.push(m);
+    }
+  }
+  return valid;
+}
+
+// ../../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;
+  }
+  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: "USER_PASSWORD_AUTH",
+      ClientId: config.clientId,
+      AuthParameters: authParams
+    })
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(`loginWithCredentials: Cognito auth failed: ${resp.status} \u2014 ${body}`);
+  }
+  const data = await resp.json();
+  const result = data.AuthenticationResult;
+  if (!result?.AccessToken || !result?.IdToken) {
+    throw new Error("loginWithCredentials: response missing AccessToken or IdToken");
+  }
+  const tenant = extractTenantFromJwt(result.IdToken);
+  return {
+    accessToken: result.AccessToken,
+    idToken: result.IdToken,
+    refreshToken: result.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] ?? "";
+  } catch {
+    return "";
+  }
+}
+
+// src/validation.ts
+var validateMetric2 = validateMetric;
+var filterValidMetrics2 = filterValidMetrics;
+
+// src/data-client.ts
+var DataClient = class {
+  constructor(config) {
+    this.credentials = null;
+    this.config = config;
+  }
+  /**
+   * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.
+   * Must be called before ingest(), reportError(), or subscribe().
+   *
+   * @param username - Cognito username
+   * @param password - Cognito password
+   * @returns Login result containing tokens and tenant
+   */
+  async login(username, password) {
+    this.credentials = await loginWithCredentials(username, password, {
+      cognitoEndpoint: this.config.cognitoEndpoint,
+      clientId: this.config.clientId
+    });
+    return this.credentials;
+  }
+  /**
+   * Ingest metric data points into the Dataworks Data Engine.
+   * Validates each metric before sending — invalid metrics are silently dropped.
+   *
+   * @param metrics - Array of metric data points
+   * @param eventId - Event identifier
+   * @param datasetDatasourceId - Dataset-datasource identifier
+   * @throws Error if not authenticated or if the request fails
+   */
+  async ingest(metrics, eventId, datasetDatasourceId) {
+    this.requireAuth();
+    const valid = filterValidMetrics2(
+      metrics,
+      (msg) => console.warn(`[@dataworks-technology/data] ${msg}`)
+    );
+    if (valid.length === 0) return;
+    const payload = {
+      eventId,
+      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)
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(
+        `[@dataworks-technology/data] ingest failed: ${resp.status} \u2014 ${body}`
+      );
+    }
+  }
+  /**
+   * Report an error to the Dataworks Data Engine.
+   *
+   * @param error - Error report details
+   * @throws Error if not authenticated or if the request fails
+   */
+  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(error)
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(
+        `[@dataworks-technology/data] reportError failed: ${resp.status} \u2014 ${body}`
+      );
+    }
+  }
+  /**
+   * 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").
+   *
+   * @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
+   */
+  subscribe(channel, onEvent) {
+    this.requireAuth();
+    const url = new URL(this.config.realtimeUrl);
+    url.pathname = "/event/realtime";
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    const ws = new WebSocket(url.toString(), [
+      "aws-appsync-event-ws",
+      // Encode auth as a base64 subprotocol header
+      `header-${btoa(
+        JSON.stringify({
+          Authorization: this.credentials.accessToken,
+          host: new URL(this.config.realtimeUrl).host
+        })
+      )}`
+    ]);
+    ws.addEventListener("open", () => {
+      ws.send(
+        JSON.stringify({
+          type: "subscribe",
+          id: crypto.randomUUID(),
+          channel: `/${channel}`,
+          authorization: {
+            Authorization: this.credentials.accessToken,
+            host: new URL(this.config.realtimeUrl).host
+          }
+        })
+      );
+    });
+    ws.addEventListener("message", (event) => {
+      try {
+        const msg = JSON.parse(String(event.data));
+        if (msg.type === "data") {
+          onEvent(JSON.parse(msg.event));
+        }
+      } catch {
+      }
+    });
+    return {
+      close() {
+        ws.close();
+      }
+    };
+  }
+  /** Returns true if the client has been authenticated via login(). */
+  get isAuthenticated() {
+    return this.credentials !== null;
+  }
+  /** Returns the tenant from the last successful login, or null. */
+  get tenant() {
+    return this.credentials?.tenant ?? null;
+  }
+  /** @internal Throws if not authenticated. */
+  requireAuth() {
+    if (!this.credentials) {
+      throw new Error(
+        "[@dataworks-technology/data] Not authenticated \u2014 call login() first"
+      );
+    }
+  }
+};
+/**
+ * Check whether a metric is valid before ingesting.
+ * Returns null if valid, or a human-readable reason string if invalid.
+ */
+DataClient.validateMetric = validateMetric2;
+/**
+ * Filter an array of metrics, keeping only valid ones.
+ * Logs a warning for each dropped item.
+ */
+DataClient.filterValidMetrics = filterValidMetrics2;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DataClient,
+  filterValidMetrics,
+  validateMetric
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../../../node_modules/@dataworks/sdk/dist/client/validation.js","../../../node_modules/@dataworks/sdk/dist/client/auth.js","../src/validation.ts","../src/data-client.ts"],"sourcesContent":["/**\n * @dataworks-technology/data — Dataworks Data Engine SDK\n *\n * Public npm package for external developers to:\n * - Authenticate via Cognito\n * - Ingest live athlete metrics\n * - Subscribe to real-time data streams\n * - Report errors\n *\n * @example\n * ```ts\n * import { DataClient } from \"@dataworks-technology/data\";\n *\n * const client = new DataClient({ ... });\n * await client.login(\"username\", \"password\");\n * await client.ingest(metrics, eventId, dsId);\n * ```\n *\n * @module @dataworks-technology/data\n */\n\nexport { DataClient } from \"./data-client.js\";\n\nexport type {\n  DataClientConfig,\n  LoginResult,\n  Metric,\n  MetricItem,\n  RawMetricItem,\n  MetricsPayload,\n  ErrorReport,\n  SubscriptionHandler,\n  Subscription,\n} from \"./types.js\";\n\n// Re-export validation utilities for standalone use\nexport { validateMetric, filterValidMetrics } from \"./validation.js\";\n","/**\n * Metric validation for Dataworks payloads.\n *\n * Ported from Dataworks-Data packages/adaptors/shared-ts/src/validation.ts\n * to serve as the single source of truth for all Dataworks engine SDKs.\n *\n * @module @dataworks/sdk/client\n */\n/**\n * Returns null if the metric is valid, or a human-readable reason string if invalid.\n */\nexport function validateMetric(m) {\n    if (typeof m.metric !== \"string\" || m.metric.trim() === \"\")\n        return \"metric must be a non-empty string\";\n    if (typeof m.athleteId !== \"string\" || m.athleteId.trim() === \"\")\n        return \"athleteId must be a non-empty string\";\n    if (!Number.isInteger(m.timestamp) || m.timestamp <= 0)\n        return `timestamp must be a positive integer, got ${m.timestamp}`;\n    if (m.value === null || m.value === undefined)\n        return \"value is null/undefined\";\n    if (typeof m.value === \"number\" && !isFinite(m.value))\n        return `value is non-finite number (${m.value})`;\n    if (typeof m.value !== \"number\" && typeof m.value !== \"string\")\n        return `value type ${typeof m.value} not allowed (must be number or string)`;\n    if (typeof m.value === \"string\" && m.value === \"\")\n        return \"value is empty string\";\n    return null;\n}\n/**\n * Filters an array of metrics, returning only valid ones.\n * Logs a warning for each dropped item via the provided warn function.\n */\nexport function filterValidMetrics(metrics, warn) {\n    const valid = [];\n    for (const m of metrics) {\n        const reason = validateMetric(m);\n        if (reason) {\n            warn(`Dropping invalid metric [${String(m.metric)}=${JSON.stringify(m.value)}]: ${reason}`);\n        }\n        else {\n            valid.push(m);\n        }\n    }\n    return valid;\n}\n","/**\n * Cognito authentication helpers.\n *\n * Provides M2M (client_credentials) and user (USER_PASSWORD_AUTH) flows.\n * Refactored from @dataworks/sdk e2e-utils.ts — uses native fetch instead\n * of axios so the client sub-path has zero heavy dependencies.\n *\n * @module @dataworks/sdk/client\n */\n/**\n * Fetch an M2M access token using the client_credentials grant.\n *\n * @param clientId - Cognito app client ID\n * @param clientSecret - Cognito app client secret\n * @param tokenUrl - Cognito token endpoint (e.g. https://<domain>.auth.<region>.amazoncognito.com/oauth2/token)\n * @returns Access token string\n */\nexport async function getClientToken(clientId, clientSecret, tokenUrl) {\n    const resp = await fetch(tokenUrl, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n        body: new URLSearchParams({\n            grant_type: \"client_credentials\",\n            client_id: clientId,\n            client_secret: clientSecret,\n        }),\n    });\n    if (!resp.ok) {\n        throw new Error(`getClientToken: Cognito token request failed: ${resp.status} ${resp.statusText}`);\n    }\n    const data = (await resp.json());\n    if (!data.access_token) {\n        throw new Error(\"getClientToken: response missing access_token\");\n    }\n    return data.access_token;\n}\n/**\n * Authenticate a user via Cognito USER_PASSWORD_AUTH flow.\n * Returns access token, ID token, refresh token, and tenant (extracted from JWT).\n *\n * Used by external developer clients — no client secret required when the\n * Cognito app client is configured without one.\n *\n * @param username - Cognito username\n * @param password - Cognito password\n * @param config - Cognito endpoint and client configuration\n * @returns Login result with tokens and tenant\n */\nexport async function loginWithCredentials(username, password, config) {\n    const authParams = {\n        USERNAME: username,\n        PASSWORD: password,\n    };\n    // If a client secret is configured, compute SECRET_HASH\n    if (config.clientSecret) {\n        // Dynamic import to keep this module usable in environments without crypto\n        const crypto = await import(\"crypto\");\n        const hash = crypto\n            .createHmac(\"sha256\", config.clientSecret)\n            .update(username + config.clientId)\n            .digest(\"base64\");\n        authParams.SECRET_HASH = hash;\n    }\n    const resp = await fetch(config.cognitoEndpoint, {\n        method: \"POST\",\n        headers: {\n            \"X-Amz-Target\": \"AWSCognitoIdentityProviderService.InitiateAuth\",\n            \"Content-Type\": \"application/x-amz-json-1.1\",\n        },\n        body: JSON.stringify({\n            AuthFlow: \"USER_PASSWORD_AUTH\",\n            ClientId: config.clientId,\n            AuthParameters: authParams,\n        }),\n    });\n    if (!resp.ok) {\n        const body = await resp.text().catch(() => \"\");\n        throw new Error(`loginWithCredentials: Cognito auth failed: ${resp.status} — ${body}`);\n    }\n    const data = (await resp.json());\n    const result = data.AuthenticationResult;\n    if (!result?.AccessToken || !result?.IdToken) {\n        throw new Error(\"loginWithCredentials: response missing AccessToken or IdToken\");\n    }\n    // Extract tenant from JWT claims (ID token payload)\n    const tenant = extractTenantFromJwt(result.IdToken);\n    return {\n        accessToken: result.AccessToken,\n        idToken: result.IdToken,\n        refreshToken: result.RefreshToken ?? \"\",\n        tenant,\n    };\n}\n/**\n * Extracts the tenant claim from a JWT ID token without verifying the signature.\n * The token is validated server-side by AppSync/API Gateway — this is a client-side\n * convenience for reading the tenant value.\n */\nfunction extractTenantFromJwt(idToken) {\n    try {\n        const payload = idToken.split(\".\")[1];\n        const decoded = JSON.parse(Buffer.from(payload, \"base64url\").toString(\"utf-8\"));\n        // Cognito custom attributes use \"custom:tenant\" claim\n        return (decoded[\"custom:tenant\"] ?? decoded.tenant ?? decoded[\"cognito:groups\"]?.[0] ?? \"\");\n    }\n    catch {\n        return \"\";\n    }\n}\n","/**\n * Validation re-exports — thin wrappers around @dataworks/sdk/client validation.\n * Declared locally so the published .d.ts is fully self-contained.\n *\n * @module @dataworks-technology/data\n */\n\nimport {\n  validateMetric as _validateMetric,\n  filterValidMetrics as _filterValidMetrics,\n} from \"@dataworks/sdk/client\";\nimport type { RawMetricItem, MetricItem } from \"./types.js\";\n\n/**\n * Check whether a metric is valid.\n * Returns null if valid, or a human-readable reason string if invalid.\n */\nexport const validateMetric: (m: RawMetricItem) => string | null =\n  _validateMetric;\n\n/**\n * Filter an array of metrics, keeping only valid ones.\n * Logs a warning for each dropped item via the provided warn function.\n */\nexport const filterValidMetrics: (\n  metrics: RawMetricItem[],\n  warn: (msg: string) => void,\n) => MetricItem[] = _filterValidMetrics;\n","/**\n * DataClient — the public entry point for external developers using the Dataworks Data Engine.\n *\n * Handles authentication, metric ingestion, error reporting, and real-time subscriptions.\n * All SDK foundation code (@dataworks/sdk) is bundled at build time — consumers install\n * only @dataworks/data with zero transitive dependencies.\n *\n * @example\n * ```ts\n * import { DataClient } from \"@dataworks-technology/data\";\n *\n * const client = new DataClient({\n *   cognitoEndpoint: \"https://cognito-idp.eu-west-1.amazonaws.com/\",\n *   clientId: \"abc123\",\n *   ingestUrl: \"https://dev-realtime.dataworks.live\",\n *   errorUrl: \"https://dev-realtime-errors.dataworks.live\",\n *   realtimeUrl: \"https://dev-event-api.dataworks.live\",\n * });\n *\n * await client.login(\"graeme\", \"password123\");\n * await client.ingest([{ athleteId: \"1\", metric: \"heartrate\", value: 172, timestamp: Date.now() / 1000 }], \"evt1\", \"ds1\");\n * ```\n *\n * @module @dataworks-technology/data\n */\n\nimport { loginWithCredentials } from \"@dataworks/sdk/client\";\nimport { validateMetric, filterValidMetrics } from \"./validation.js\";\nimport type {\n  DataClientConfig,\n  LoginResult,\n  Metric,\n  ErrorReport,\n  SubscriptionHandler,\n  Subscription,\n} from \"./types.js\";\n\nexport class DataClient {\n  private readonly config: DataClientConfig;\n  private credentials: LoginResult | null = null;\n\n  constructor(config: DataClientConfig) {\n    this.config = config;\n  }\n\n  /**\n   * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.\n   * Must be called before ingest(), reportError(), or subscribe().\n   *\n   * @param username - Cognito username\n   * @param password - Cognito password\n   * @returns Login result containing tokens and tenant\n   */\n  async login(username: string, password: string): Promise<LoginResult> {\n    this.credentials = await loginWithCredentials(username, password, {\n      cognitoEndpoint: this.config.cognitoEndpoint,\n      clientId: this.config.clientId,\n    });\n    return this.credentials;\n  }\n\n  /**\n   * Ingest metric data points into the Dataworks Data Engine.\n   * Validates each metric before sending — invalid metrics are silently dropped.\n   *\n   * @param metrics - Array of metric data points\n   * @param eventId - Event identifier\n   * @param datasetDatasourceId - Dataset-datasource identifier\n   * @throws Error if not authenticated or if the request fails\n   */\n  async ingest(\n    metrics: Metric[],\n    eventId: string,\n    datasetDatasourceId: string,\n  ): Promise<void> {\n    this.requireAuth();\n\n    const valid = filterValidMetrics(metrics, (msg) =>\n      console.warn(`[@dataworks-technology/data] ${msg}`),\n    );\n\n    if (valid.length === 0) return;\n\n    const payload = {\n      eventId,\n      datasetDatasourceId,\n      metrics: valid,\n    };\n\n    const resp = await fetch(this.config.ingestUrl, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Authorization: `Bearer ${this.credentials!.accessToken}`,\n      },\n      body: JSON.stringify(payload),\n    });\n\n    if (!resp.ok) {\n      const body = await resp.text().catch(() => \"\");\n      throw new Error(\n        `[@dataworks-technology/data] ingest failed: ${resp.status} — ${body}`,\n      );\n    }\n  }\n\n  /**\n   * Report an error to the Dataworks Data Engine.\n   *\n   * @param error - Error report details\n   * @throws Error if not authenticated or if the request fails\n   */\n  async reportError(error: ErrorReport): Promise<void> {\n    this.requireAuth();\n\n    const resp = await fetch(this.config.errorUrl, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Authorization: `Bearer ${this.credentials!.accessToken}`,\n      },\n      body: JSON.stringify(error),\n    });\n\n    if (!resp.ok) {\n      const body = await resp.text().catch(() => \"\");\n      throw new Error(\n        `[@dataworks-technology/data] reportError failed: ${resp.status} — ${body}`,\n      );\n    }\n  }\n\n  /**\n   * Subscribe to a real-time data channel on the AppSync Events API.\n   * Uses the Cognito JWT for authentication.\n   *\n   * The channel name maps to the AppSync Events API namespace (e.g. \"dataworks/metrics\").\n   *\n   * @param channel - Channel path to subscribe to\n   * @param onEvent - Callback invoked for each received event\n   * @returns Subscription handle with a close() method\n   * @throws Error if not authenticated\n   */\n  subscribe(channel: string, onEvent: SubscriptionHandler): Subscription {\n    this.requireAuth();\n\n    const url = new URL(this.config.realtimeUrl);\n    // AppSync Events API uses the /event/realtime path for WebSocket connections\n    url.pathname = \"/event/realtime\";\n    url.protocol = url.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n\n    const ws = new WebSocket(url.toString(), [\n      \"aws-appsync-event-ws\",\n      // Encode auth as a base64 subprotocol header\n      `header-${btoa(\n        JSON.stringify({\n          Authorization: this.credentials!.accessToken,\n          host: new URL(this.config.realtimeUrl).host,\n        }),\n      )}`,\n    ]);\n\n    ws.addEventListener(\"open\", () => {\n      // Subscribe to the channel after connection is established\n      ws.send(\n        JSON.stringify({\n          type: \"subscribe\",\n          id: crypto.randomUUID(),\n          channel: `/${channel}`,\n          authorization: {\n            Authorization: this.credentials!.accessToken,\n            host: new URL(this.config.realtimeUrl).host,\n          },\n        }),\n      );\n    });\n\n    ws.addEventListener(\"message\", (event) => {\n      try {\n        const msg = JSON.parse(String(event.data));\n        if (msg.type === \"data\") {\n          onEvent(JSON.parse(msg.event));\n        }\n      } catch {\n        // Ignore non-data messages (connection_ack, subscribe_success, etc.)\n      }\n    });\n\n    return {\n      close() {\n        ws.close();\n      },\n    };\n  }\n\n  /**\n   * Check whether a metric is valid before ingesting.\n   * Returns null if valid, or a human-readable reason string if invalid.\n   */\n  static validateMetric = validateMetric;\n\n  /**\n   * Filter an array of metrics, keeping only valid ones.\n   * Logs a warning for each dropped item.\n   */\n  static filterValidMetrics = filterValidMetrics;\n\n  /** Returns true if the client has been authenticated via login(). */\n  get isAuthenticated(): boolean {\n    return this.credentials !== null;\n  }\n\n  /** Returns the tenant from the last successful login, or null. */\n  get tenant(): string | null {\n    return this.credentials?.tenant ?? null;\n  }\n\n  /** @internal Throws if not authenticated. */\n  private requireAuth(): void {\n    if (!this.credentials) {\n      throw new Error(\n        \"[@dataworks-technology/data] Not authenticated — call login() first\",\n      );\n    }\n  }\n}\n"],"mappings":"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","names":["filterValidMetrics","validateMetric","crypto","validateMetric","filterValidMetrics","filterValidMetrics","validateMetric"]}

package/dist/index.d.cts

@@ -0,0 +1,157 @@
+/**
+ * Public types for @dataworks/data.
+ *
+ * @module @dataworks-technology/data
+ */
+/** Configuration for connecting to the Dataworks Data Engine. */
+interface DataClientConfig {
+    /** Cognito User Pool endpoint (e.g. "https://cognito-idp.eu-west-1.amazonaws.com/") */
+    cognitoEndpoint: string;
+    /** Cognito app client ID */
+    clientId: string;
+    /** Data Engine ingest URL (API Gateway endpoint) */
+    ingestUrl: string;
+    /** Data Engine error reporting URL (API Gateway endpoint) */
+    errorUrl: string;
+    /** AppSync Events API endpoint for real-time subscriptions */
+    realtimeUrl: string;
+}
+/** Credentials returned from a successful login. */
+interface LoginResult {
+    accessToken: string;
+    idToken: string;
+    refreshToken: string;
+    /** Tenant extracted from the JWT claims. */
+    tenant: string;
+}
+/** A single metric data point to ingest. */
+interface Metric {
+    /** Unique athlete identifier */
+    athleteId: string;
+    /** Metric name (e.g. "heartrate", "speed", "power") */
+    metric: string;
+    /** Metric value — number or string */
+    value: number | string;
+    /** Unix timestamp in seconds */
+    timestamp: number;
+}
+/** Validated metric item (all fields confirmed present and correct). */
+interface MetricItem {
+    athleteId: string;
+    metric: string;
+    value: unknown;
+    timestamp: number;
+}
+/** Loosely-typed input for validation — all fields are unknown. */
+interface RawMetricItem {
+    metric: unknown;
+    athleteId: unknown;
+    value: unknown;
+    timestamp: unknown;
+}
+/** Payload shape for metric ingestion. */
+interface MetricsPayload {
+    eventId: string;
+    datasetDatasourceId: string;
+    metrics: MetricItem[];
+}
+/** Error report to send to the Data Engine. */
+interface ErrorReport {
+    /** Dataset-datasource identifier */
+    datasetDatasourceId: string;
+    /** Event identifier */
+    eventId: string;
+    /** Client identifier */
+    clientId: number;
+    /** Short error title */
+    errorTitle: string;
+    /** Detailed error description */
+    errorDescription: string;
+}
+/** Callback for subscription events. */
+type SubscriptionHandler = (event: unknown) => void;
+/** Active subscription that can be closed. */
+interface Subscription {
+    /** Close the subscription and disconnect. */
+    close(): void;
+}
+
+declare class DataClient {
+    private readonly config;
+    private credentials;
+    constructor(config: DataClientConfig);
+    /**
+     * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.
+     * Must be called before ingest(), reportError(), or subscribe().
+     *
+     * @param username - Cognito username
+     * @param password - Cognito password
+     * @returns Login result containing tokens and tenant
+     */
+    login(username: string, password: string): Promise<LoginResult>;
+    /**
+     * Ingest metric data points into the Dataworks Data Engine.
+     * Validates each metric before sending — invalid metrics are silently dropped.
+     *
+     * @param metrics - Array of metric data points
+     * @param eventId - Event identifier
+     * @param datasetDatasourceId - Dataset-datasource identifier
+     * @throws Error if not authenticated or if the request fails
+     */
+    ingest(metrics: Metric[], eventId: string, datasetDatasourceId: string): Promise<void>;
+    /**
+     * Report an error to the Dataworks Data Engine.
+     *
+     * @param error - Error report details
+     * @throws Error if not authenticated or if the request fails
+     */
+    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").
+     *
+     * @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
+     */
+    subscribe(channel: string, onEvent: SubscriptionHandler): Subscription;
+    /**
+     * Check whether a metric is valid before ingesting.
+     * Returns null if valid, or a human-readable reason string if invalid.
+     */
+    static validateMetric: (m: RawMetricItem) => string | null;
+    /**
+     * Filter an array of metrics, keeping only valid ones.
+     * Logs a warning for each dropped item.
+     */
+    static filterValidMetrics: (metrics: RawMetricItem[], warn: (msg: string) => void) => MetricItem[];
+    /** Returns true if the client has been authenticated via login(). */
+    get isAuthenticated(): boolean;
+    /** Returns the tenant from the last successful login, or null. */
+    get tenant(): string | null;
+    /** @internal Throws if not authenticated. */
+    private requireAuth;
+}
+
+/**
+ * Validation re-exports — thin wrappers around @dataworks/sdk/client validation.
+ * Declared locally so the published .d.ts is fully self-contained.
+ *
+ * @module @dataworks-technology/data
+ */
+
+/**
+ * Check whether a metric is valid.
+ * Returns null if valid, or a human-readable reason string if invalid.
+ */
+declare const validateMetric: (m: RawMetricItem) => string | null;
+/**
+ * Filter an array of metrics, keeping only valid ones.
+ * Logs a warning for each dropped item via the provided warn function.
+ */
+declare const filterValidMetrics: (metrics: RawMetricItem[], warn: (msg: string) => void) => MetricItem[];
+
+export { DataClient, type DataClientConfig, type ErrorReport, type LoginResult, type Metric, type MetricItem, type MetricsPayload, type RawMetricItem, type Subscription, type SubscriptionHandler, filterValidMetrics, validateMetric };

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Public types for @dataworks/data.
+ *
+ * @module @dataworks-technology/data
+ */
+/** Configuration for connecting to the Dataworks Data Engine. */
+interface DataClientConfig {
+    /** Cognito User Pool endpoint (e.g. "https://cognito-idp.eu-west-1.amazonaws.com/") */
+    cognitoEndpoint: string;
+    /** Cognito app client ID */
+    clientId: string;
+    /** Data Engine ingest URL (API Gateway endpoint) */
+    ingestUrl: string;
+    /** Data Engine error reporting URL (API Gateway endpoint) */
+    errorUrl: string;
+    /** AppSync Events API endpoint for real-time subscriptions */
+    realtimeUrl: string;
+}
+/** Credentials returned from a successful login. */
+interface LoginResult {
+    accessToken: string;
+    idToken: string;
+    refreshToken: string;
+    /** Tenant extracted from the JWT claims. */
+    tenant: string;
+}
+/** A single metric data point to ingest. */
+interface Metric {
+    /** Unique athlete identifier */
+    athleteId: string;
+    /** Metric name (e.g. "heartrate", "speed", "power") */
+    metric: string;
+    /** Metric value — number or string */
+    value: number | string;
+    /** Unix timestamp in seconds */
+    timestamp: number;
+}
+/** Validated metric item (all fields confirmed present and correct). */
+interface MetricItem {
+    athleteId: string;
+    metric: string;
+    value: unknown;
+    timestamp: number;
+}
+/** Loosely-typed input for validation — all fields are unknown. */
+interface RawMetricItem {
+    metric: unknown;
+    athleteId: unknown;
+    value: unknown;
+    timestamp: unknown;
+}
+/** Payload shape for metric ingestion. */
+interface MetricsPayload {
+    eventId: string;
+    datasetDatasourceId: string;
+    metrics: MetricItem[];
+}
+/** Error report to send to the Data Engine. */
+interface ErrorReport {
+    /** Dataset-datasource identifier */
+    datasetDatasourceId: string;
+    /** Event identifier */
+    eventId: string;
+    /** Client identifier */
+    clientId: number;
+    /** Short error title */
+    errorTitle: string;
+    /** Detailed error description */
+    errorDescription: string;
+}
+/** Callback for subscription events. */
+type SubscriptionHandler = (event: unknown) => void;
+/** Active subscription that can be closed. */
+interface Subscription {
+    /** Close the subscription and disconnect. */
+    close(): void;
+}
+
+declare class DataClient {
+    private readonly config;
+    private credentials;
+    constructor(config: DataClientConfig);
+    /**
+     * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.
+     * Must be called before ingest(), reportError(), or subscribe().
+     *
+     * @param username - Cognito username
+     * @param password - Cognito password
+     * @returns Login result containing tokens and tenant
+     */
+    login(username: string, password: string): Promise<LoginResult>;
+    /**
+     * Ingest metric data points into the Dataworks Data Engine.
+     * Validates each metric before sending — invalid metrics are silently dropped.
+     *
+     * @param metrics - Array of metric data points
+     * @param eventId - Event identifier
+     * @param datasetDatasourceId - Dataset-datasource identifier
+     * @throws Error if not authenticated or if the request fails
+     */
+    ingest(metrics: Metric[], eventId: string, datasetDatasourceId: string): Promise<void>;
+    /**
+     * Report an error to the Dataworks Data Engine.
+     *
+     * @param error - Error report details
+     * @throws Error if not authenticated or if the request fails
+     */
+    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").
+     *
+     * @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
+     */
+    subscribe(channel: string, onEvent: SubscriptionHandler): Subscription;
+    /**
+     * Check whether a metric is valid before ingesting.
+     * Returns null if valid, or a human-readable reason string if invalid.
+     */
+    static validateMetric: (m: RawMetricItem) => string | null;
+    /**
+     * Filter an array of metrics, keeping only valid ones.
+     * Logs a warning for each dropped item.
+     */
+    static filterValidMetrics: (metrics: RawMetricItem[], warn: (msg: string) => void) => MetricItem[];
+    /** Returns true if the client has been authenticated via login(). */
+    get isAuthenticated(): boolean;
+    /** Returns the tenant from the last successful login, or null. */
+    get tenant(): string | null;
+    /** @internal Throws if not authenticated. */
+    private requireAuth;
+}
+
+/**
+ * Validation re-exports — thin wrappers around @dataworks/sdk/client validation.
+ * Declared locally so the published .d.ts is fully self-contained.
+ *
+ * @module @dataworks-technology/data
+ */
+
+/**
+ * Check whether a metric is valid.
+ * Returns null if valid, or a human-readable reason string if invalid.
+ */
+declare const validateMetric: (m: RawMetricItem) => string | null;
+/**
+ * Filter an array of metrics, keeping only valid ones.
+ * Logs a warning for each dropped item via the provided warn function.
+ */
+declare const filterValidMetrics: (metrics: RawMetricItem[], warn: (msg: string) => void) => MetricItem[];
+
+export { DataClient, type DataClientConfig, type ErrorReport, type LoginResult, type Metric, type MetricItem, type MetricsPayload, type RawMetricItem, type Subscription, type SubscriptionHandler, filterValidMetrics, validateMetric };

package/dist/index.js

@@ -0,0 +1,252 @@
+// ../../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";
+  if (typeof m.athleteId !== "string" || m.athleteId.trim() === "")
+    return "athleteId must be a non-empty string";
+  if (!Number.isInteger(m.timestamp) || m.timestamp <= 0)
+    return `timestamp must be a positive integer, got ${m.timestamp}`;
+  if (m.value === null || m.value === void 0)
+    return "value is null/undefined";
+  if (typeof m.value === "number" && !isFinite(m.value))
+    return `value is non-finite number (${m.value})`;
+  if (typeof m.value !== "number" && typeof m.value !== "string")
+    return `value type ${typeof m.value} not allowed (must be number or string)`;
+  if (typeof m.value === "string" && m.value === "")
+    return "value is empty string";
+  return null;
+}
+function filterValidMetrics(metrics, warn) {
+  const valid = [];
+  for (const m of metrics) {
+    const reason = validateMetric(m);
+    if (reason) {
+      warn(`Dropping invalid metric [${String(m.metric)}=${JSON.stringify(m.value)}]: ${reason}`);
+    } else {
+      valid.push(m);
+    }
+  }
+  return valid;
+}
+
+// ../../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;
+  }
+  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: "USER_PASSWORD_AUTH",
+      ClientId: config.clientId,
+      AuthParameters: authParams
+    })
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(`loginWithCredentials: Cognito auth failed: ${resp.status} \u2014 ${body}`);
+  }
+  const data = await resp.json();
+  const result = data.AuthenticationResult;
+  if (!result?.AccessToken || !result?.IdToken) {
+    throw new Error("loginWithCredentials: response missing AccessToken or IdToken");
+  }
+  const tenant = extractTenantFromJwt(result.IdToken);
+  return {
+    accessToken: result.AccessToken,
+    idToken: result.IdToken,
+    refreshToken: result.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] ?? "";
+  } catch {
+    return "";
+  }
+}
+
+// src/validation.ts
+var validateMetric2 = validateMetric;
+var filterValidMetrics2 = filterValidMetrics;
+
+// src/data-client.ts
+var DataClient = class {
+  constructor(config) {
+    this.credentials = null;
+    this.config = config;
+  }
+  /**
+   * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.
+   * Must be called before ingest(), reportError(), or subscribe().
+   *
+   * @param username - Cognito username
+   * @param password - Cognito password
+   * @returns Login result containing tokens and tenant
+   */
+  async login(username, password) {
+    this.credentials = await loginWithCredentials(username, password, {
+      cognitoEndpoint: this.config.cognitoEndpoint,
+      clientId: this.config.clientId
+    });
+    return this.credentials;
+  }
+  /**
+   * Ingest metric data points into the Dataworks Data Engine.
+   * Validates each metric before sending — invalid metrics are silently dropped.
+   *
+   * @param metrics - Array of metric data points
+   * @param eventId - Event identifier
+   * @param datasetDatasourceId - Dataset-datasource identifier
+   * @throws Error if not authenticated or if the request fails
+   */
+  async ingest(metrics, eventId, datasetDatasourceId) {
+    this.requireAuth();
+    const valid = filterValidMetrics2(
+      metrics,
+      (msg) => console.warn(`[@dataworks-technology/data] ${msg}`)
+    );
+    if (valid.length === 0) return;
+    const payload = {
+      eventId,
+      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)
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(
+        `[@dataworks-technology/data] ingest failed: ${resp.status} \u2014 ${body}`
+      );
+    }
+  }
+  /**
+   * Report an error to the Dataworks Data Engine.
+   *
+   * @param error - Error report details
+   * @throws Error if not authenticated or if the request fails
+   */
+  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(error)
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(
+        `[@dataworks-technology/data] reportError failed: ${resp.status} \u2014 ${body}`
+      );
+    }
+  }
+  /**
+   * 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").
+   *
+   * @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
+   */
+  subscribe(channel, onEvent) {
+    this.requireAuth();
+    const url = new URL(this.config.realtimeUrl);
+    url.pathname = "/event/realtime";
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    const ws = new WebSocket(url.toString(), [
+      "aws-appsync-event-ws",
+      // Encode auth as a base64 subprotocol header
+      `header-${btoa(
+        JSON.stringify({
+          Authorization: this.credentials.accessToken,
+          host: new URL(this.config.realtimeUrl).host
+        })
+      )}`
+    ]);
+    ws.addEventListener("open", () => {
+      ws.send(
+        JSON.stringify({
+          type: "subscribe",
+          id: crypto.randomUUID(),
+          channel: `/${channel}`,
+          authorization: {
+            Authorization: this.credentials.accessToken,
+            host: new URL(this.config.realtimeUrl).host
+          }
+        })
+      );
+    });
+    ws.addEventListener("message", (event) => {
+      try {
+        const msg = JSON.parse(String(event.data));
+        if (msg.type === "data") {
+          onEvent(JSON.parse(msg.event));
+        }
+      } catch {
+      }
+    });
+    return {
+      close() {
+        ws.close();
+      }
+    };
+  }
+  /** Returns true if the client has been authenticated via login(). */
+  get isAuthenticated() {
+    return this.credentials !== null;
+  }
+  /** Returns the tenant from the last successful login, or null. */
+  get tenant() {
+    return this.credentials?.tenant ?? null;
+  }
+  /** @internal Throws if not authenticated. */
+  requireAuth() {
+    if (!this.credentials) {
+      throw new Error(
+        "[@dataworks-technology/data] Not authenticated \u2014 call login() first"
+      );
+    }
+  }
+};
+/**
+ * Check whether a metric is valid before ingesting.
+ * Returns null if valid, or a human-readable reason string if invalid.
+ */
+DataClient.validateMetric = validateMetric2;
+/**
+ * Filter an array of metrics, keeping only valid ones.
+ * Logs a warning for each dropped item.
+ */
+DataClient.filterValidMetrics = filterValidMetrics2;
+export {
+  DataClient,
+  filterValidMetrics2 as filterValidMetrics,
+  validateMetric2 as validateMetric
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../node_modules/@dataworks/sdk/dist/client/validation.js","../../../node_modules/@dataworks/sdk/dist/client/auth.js","../src/validation.ts","../src/data-client.ts"],"sourcesContent":["/**\n * Metric validation for Dataworks payloads.\n *\n * Ported from Dataworks-Data packages/adaptors/shared-ts/src/validation.ts\n * to serve as the single source of truth for all Dataworks engine SDKs.\n *\n * @module @dataworks/sdk/client\n */\n/**\n * Returns null if the metric is valid, or a human-readable reason string if invalid.\n */\nexport function validateMetric(m) {\n    if (typeof m.metric !== \"string\" || m.metric.trim() === \"\")\n        return \"metric must be a non-empty string\";\n    if (typeof m.athleteId !== \"string\" || m.athleteId.trim() === \"\")\n        return \"athleteId must be a non-empty string\";\n    if (!Number.isInteger(m.timestamp) || m.timestamp <= 0)\n        return `timestamp must be a positive integer, got ${m.timestamp}`;\n    if (m.value === null || m.value === undefined)\n        return \"value is null/undefined\";\n    if (typeof m.value === \"number\" && !isFinite(m.value))\n        return `value is non-finite number (${m.value})`;\n    if (typeof m.value !== \"number\" && typeof m.value !== \"string\")\n        return `value type ${typeof m.value} not allowed (must be number or string)`;\n    if (typeof m.value === \"string\" && m.value === \"\")\n        return \"value is empty string\";\n    return null;\n}\n/**\n * Filters an array of metrics, returning only valid ones.\n * Logs a warning for each dropped item via the provided warn function.\n */\nexport function filterValidMetrics(metrics, warn) {\n    const valid = [];\n    for (const m of metrics) {\n        const reason = validateMetric(m);\n        if (reason) {\n            warn(`Dropping invalid metric [${String(m.metric)}=${JSON.stringify(m.value)}]: ${reason}`);\n        }\n        else {\n            valid.push(m);\n        }\n    }\n    return valid;\n}\n","/**\n * Cognito authentication helpers.\n *\n * Provides M2M (client_credentials) and user (USER_PASSWORD_AUTH) flows.\n * Refactored from @dataworks/sdk e2e-utils.ts — uses native fetch instead\n * of axios so the client sub-path has zero heavy dependencies.\n *\n * @module @dataworks/sdk/client\n */\n/**\n * Fetch an M2M access token using the client_credentials grant.\n *\n * @param clientId - Cognito app client ID\n * @param clientSecret - Cognito app client secret\n * @param tokenUrl - Cognito token endpoint (e.g. https://<domain>.auth.<region>.amazoncognito.com/oauth2/token)\n * @returns Access token string\n */\nexport async function getClientToken(clientId, clientSecret, tokenUrl) {\n    const resp = await fetch(tokenUrl, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n        body: new URLSearchParams({\n            grant_type: \"client_credentials\",\n            client_id: clientId,\n            client_secret: clientSecret,\n        }),\n    });\n    if (!resp.ok) {\n        throw new Error(`getClientToken: Cognito token request failed: ${resp.status} ${resp.statusText}`);\n    }\n    const data = (await resp.json());\n    if (!data.access_token) {\n        throw new Error(\"getClientToken: response missing access_token\");\n    }\n    return data.access_token;\n}\n/**\n * Authenticate a user via Cognito USER_PASSWORD_AUTH flow.\n * Returns access token, ID token, refresh token, and tenant (extracted from JWT).\n *\n * Used by external developer clients — no client secret required when the\n * Cognito app client is configured without one.\n *\n * @param username - Cognito username\n * @param password - Cognito password\n * @param config - Cognito endpoint and client configuration\n * @returns Login result with tokens and tenant\n */\nexport async function loginWithCredentials(username, password, config) {\n    const authParams = {\n        USERNAME: username,\n        PASSWORD: password,\n    };\n    // If a client secret is configured, compute SECRET_HASH\n    if (config.clientSecret) {\n        // Dynamic import to keep this module usable in environments without crypto\n        const crypto = await import(\"crypto\");\n        const hash = crypto\n            .createHmac(\"sha256\", config.clientSecret)\n            .update(username + config.clientId)\n            .digest(\"base64\");\n        authParams.SECRET_HASH = hash;\n    }\n    const resp = await fetch(config.cognitoEndpoint, {\n        method: \"POST\",\n        headers: {\n            \"X-Amz-Target\": \"AWSCognitoIdentityProviderService.InitiateAuth\",\n            \"Content-Type\": \"application/x-amz-json-1.1\",\n        },\n        body: JSON.stringify({\n            AuthFlow: \"USER_PASSWORD_AUTH\",\n            ClientId: config.clientId,\n            AuthParameters: authParams,\n        }),\n    });\n    if (!resp.ok) {\n        const body = await resp.text().catch(() => \"\");\n        throw new Error(`loginWithCredentials: Cognito auth failed: ${resp.status} — ${body}`);\n    }\n    const data = (await resp.json());\n    const result = data.AuthenticationResult;\n    if (!result?.AccessToken || !result?.IdToken) {\n        throw new Error(\"loginWithCredentials: response missing AccessToken or IdToken\");\n    }\n    // Extract tenant from JWT claims (ID token payload)\n    const tenant = extractTenantFromJwt(result.IdToken);\n    return {\n        accessToken: result.AccessToken,\n        idToken: result.IdToken,\n        refreshToken: result.RefreshToken ?? \"\",\n        tenant,\n    };\n}\n/**\n * Extracts the tenant claim from a JWT ID token without verifying the signature.\n * The token is validated server-side by AppSync/API Gateway — this is a client-side\n * convenience for reading the tenant value.\n */\nfunction extractTenantFromJwt(idToken) {\n    try {\n        const payload = idToken.split(\".\")[1];\n        const decoded = JSON.parse(Buffer.from(payload, \"base64url\").toString(\"utf-8\"));\n        // Cognito custom attributes use \"custom:tenant\" claim\n        return (decoded[\"custom:tenant\"] ?? decoded.tenant ?? decoded[\"cognito:groups\"]?.[0] ?? \"\");\n    }\n    catch {\n        return \"\";\n    }\n}\n","/**\n * Validation re-exports — thin wrappers around @dataworks/sdk/client validation.\n * Declared locally so the published .d.ts is fully self-contained.\n *\n * @module @dataworks-technology/data\n */\n\nimport {\n  validateMetric as _validateMetric,\n  filterValidMetrics as _filterValidMetrics,\n} from \"@dataworks/sdk/client\";\nimport type { RawMetricItem, MetricItem } from \"./types.js\";\n\n/**\n * Check whether a metric is valid.\n * Returns null if valid, or a human-readable reason string if invalid.\n */\nexport const validateMetric: (m: RawMetricItem) => string | null =\n  _validateMetric;\n\n/**\n * Filter an array of metrics, keeping only valid ones.\n * Logs a warning for each dropped item via the provided warn function.\n */\nexport const filterValidMetrics: (\n  metrics: RawMetricItem[],\n  warn: (msg: string) => void,\n) => MetricItem[] = _filterValidMetrics;\n","/**\n * DataClient — the public entry point for external developers using the Dataworks Data Engine.\n *\n * Handles authentication, metric ingestion, error reporting, and real-time subscriptions.\n * All SDK foundation code (@dataworks/sdk) is bundled at build time — consumers install\n * only @dataworks/data with zero transitive dependencies.\n *\n * @example\n * ```ts\n * import { DataClient } from \"@dataworks-technology/data\";\n *\n * const client = new DataClient({\n *   cognitoEndpoint: \"https://cognito-idp.eu-west-1.amazonaws.com/\",\n *   clientId: \"abc123\",\n *   ingestUrl: \"https://dev-realtime.dataworks.live\",\n *   errorUrl: \"https://dev-realtime-errors.dataworks.live\",\n *   realtimeUrl: \"https://dev-event-api.dataworks.live\",\n * });\n *\n * await client.login(\"graeme\", \"password123\");\n * await client.ingest([{ athleteId: \"1\", metric: \"heartrate\", value: 172, timestamp: Date.now() / 1000 }], \"evt1\", \"ds1\");\n * ```\n *\n * @module @dataworks-technology/data\n */\n\nimport { loginWithCredentials } from \"@dataworks/sdk/client\";\nimport { validateMetric, filterValidMetrics } from \"./validation.js\";\nimport type {\n  DataClientConfig,\n  LoginResult,\n  Metric,\n  ErrorReport,\n  SubscriptionHandler,\n  Subscription,\n} from \"./types.js\";\n\nexport class DataClient {\n  private readonly config: DataClientConfig;\n  private credentials: LoginResult | null = null;\n\n  constructor(config: DataClientConfig) {\n    this.config = config;\n  }\n\n  /**\n   * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.\n   * Must be called before ingest(), reportError(), or subscribe().\n   *\n   * @param username - Cognito username\n   * @param password - Cognito password\n   * @returns Login result containing tokens and tenant\n   */\n  async login(username: string, password: string): Promise<LoginResult> {\n    this.credentials = await loginWithCredentials(username, password, {\n      cognitoEndpoint: this.config.cognitoEndpoint,\n      clientId: this.config.clientId,\n    });\n    return this.credentials;\n  }\n\n  /**\n   * Ingest metric data points into the Dataworks Data Engine.\n   * Validates each metric before sending — invalid metrics are silently dropped.\n   *\n   * @param metrics - Array of metric data points\n   * @param eventId - Event identifier\n   * @param datasetDatasourceId - Dataset-datasource identifier\n   * @throws Error if not authenticated or if the request fails\n   */\n  async ingest(\n    metrics: Metric[],\n    eventId: string,\n    datasetDatasourceId: string,\n  ): Promise<void> {\n    this.requireAuth();\n\n    const valid = filterValidMetrics(metrics, (msg) =>\n      console.warn(`[@dataworks-technology/data] ${msg}`),\n    );\n\n    if (valid.length === 0) return;\n\n    const payload = {\n      eventId,\n      datasetDatasourceId,\n      metrics: valid,\n    };\n\n    const resp = await fetch(this.config.ingestUrl, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Authorization: `Bearer ${this.credentials!.accessToken}`,\n      },\n      body: JSON.stringify(payload),\n    });\n\n    if (!resp.ok) {\n      const body = await resp.text().catch(() => \"\");\n      throw new Error(\n        `[@dataworks-technology/data] ingest failed: ${resp.status} — ${body}`,\n      );\n    }\n  }\n\n  /**\n   * Report an error to the Dataworks Data Engine.\n   *\n   * @param error - Error report details\n   * @throws Error if not authenticated or if the request fails\n   */\n  async reportError(error: ErrorReport): Promise<void> {\n    this.requireAuth();\n\n    const resp = await fetch(this.config.errorUrl, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Authorization: `Bearer ${this.credentials!.accessToken}`,\n      },\n      body: JSON.stringify(error),\n    });\n\n    if (!resp.ok) {\n      const body = await resp.text().catch(() => \"\");\n      throw new Error(\n        `[@dataworks-technology/data] reportError failed: ${resp.status} — ${body}`,\n      );\n    }\n  }\n\n  /**\n   * Subscribe to a real-time data channel on the AppSync Events API.\n   * Uses the Cognito JWT for authentication.\n   *\n   * The channel name maps to the AppSync Events API namespace (e.g. \"dataworks/metrics\").\n   *\n   * @param channel - Channel path to subscribe to\n   * @param onEvent - Callback invoked for each received event\n   * @returns Subscription handle with a close() method\n   * @throws Error if not authenticated\n   */\n  subscribe(channel: string, onEvent: SubscriptionHandler): Subscription {\n    this.requireAuth();\n\n    const url = new URL(this.config.realtimeUrl);\n    // AppSync Events API uses the /event/realtime path for WebSocket connections\n    url.pathname = \"/event/realtime\";\n    url.protocol = url.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n\n    const ws = new WebSocket(url.toString(), [\n      \"aws-appsync-event-ws\",\n      // Encode auth as a base64 subprotocol header\n      `header-${btoa(\n        JSON.stringify({\n          Authorization: this.credentials!.accessToken,\n          host: new URL(this.config.realtimeUrl).host,\n        }),\n      )}`,\n    ]);\n\n    ws.addEventListener(\"open\", () => {\n      // Subscribe to the channel after connection is established\n      ws.send(\n        JSON.stringify({\n          type: \"subscribe\",\n          id: crypto.randomUUID(),\n          channel: `/${channel}`,\n          authorization: {\n            Authorization: this.credentials!.accessToken,\n            host: new URL(this.config.realtimeUrl).host,\n          },\n        }),\n      );\n    });\n\n    ws.addEventListener(\"message\", (event) => {\n      try {\n        const msg = JSON.parse(String(event.data));\n        if (msg.type === \"data\") {\n          onEvent(JSON.parse(msg.event));\n        }\n      } catch {\n        // Ignore non-data messages (connection_ack, subscribe_success, etc.)\n      }\n    });\n\n    return {\n      close() {\n        ws.close();\n      },\n    };\n  }\n\n  /**\n   * Check whether a metric is valid before ingesting.\n   * Returns null if valid, or a human-readable reason string if invalid.\n   */\n  static validateMetric = validateMetric;\n\n  /**\n   * Filter an array of metrics, keeping only valid ones.\n   * Logs a warning for each dropped item.\n   */\n  static filterValidMetrics = filterValidMetrics;\n\n  /** Returns true if the client has been authenticated via login(). */\n  get isAuthenticated(): boolean {\n    return this.credentials !== null;\n  }\n\n  /** Returns the tenant from the last successful login, or null. */\n  get tenant(): string | null {\n    return this.credentials?.tenant ?? null;\n  }\n\n  /** @internal Throws if not authenticated. */\n  private requireAuth(): void {\n    if (!this.credentials) {\n      throw new Error(\n        \"[@dataworks-technology/data] Not authenticated — call login() first\",\n      );\n    }\n  }\n}\n"],"mappings":"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","names":["crypto","validateMetric","filterValidMetrics","filterValidMetrics","validateMetric"]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@dataworks-technology/data",
+  "version": "0.1.3",
+  "description": "Dataworks Data Engine SDK — authenticate, ingest metrics, and subscribe to live data",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "prepublishOnly": "bun run build",
+    "publish:patch": "npm version patch && npm publish --@dataworks-technology:registry=https://registry.npmjs.org/",
+    "publish:minor": "npm version minor && npm publish --@dataworks-technology:registry=https://registry.npmjs.org/",
+    "publish:major": "npm version major && npm publish --@dataworks-technology:registry=https://registry.npmjs.org/"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "keywords": [
+    "dataworks",
+    "sports",
+    "data",
+    "metrics",
+    "live",
+    "sdk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Dataworks-Technology/Dataworks-Data"
+  },
+  "devDependencies": {
+    "@dataworks/sdk": "^1.6.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3"
+  },
+  "dependencies": {}
+}