Skip to main content

Getting Started

The Dataworks Data SDK (@dataworks-technology/data) lets you authenticate with the Dataworks platform, ingest live athlete metrics, subscribe to real-time data streams, and report errors — all from a single DataClient class.

Installation​

npm install @dataworks-technology/data

Or with your preferred package manager:

yarn add @dataworks-technology/data
# or
pnpm add @dataworks-technology/data
# or
bun add @dataworks-technology/data

The package has zero dependencies — everything is bundled and self-contained.

Quick Start​

import { DataClient } from "@dataworks-technology/data";

// 1. Create a client with your Dataworks credentials
const dataworks = new DataClient({
  cognitoEndpoint: "https://cognito-idp.eu-west-1.amazonaws.com/",
  clientId: "your-client-id",
  ingestUrl: "https://realtime.dataworks.live",
  errorUrl: "https://realtime-error.dataworks.live",
  realtimeUrl: "https://event-api.dataworks.live",
  apiKey: "optional-appsync-events-api-key", // subscription-only fallback
});

// 2. Authenticate
await dataworks.login("your-username", "your-password");

// 3. Ingest metrics
await dataworks.ingest(
  [
    {
      athleteId: "athlete-1",
      metric: "heartrate_calculated",
      value: 172,
      timestamp: Math.floor(Date.now() / 1000),
    },
  ],
  "event-123",
  "dataset-456",
);

// 4. Subscribe to real-time updates
// Channel format: dataworks/{datasetDatasourceId}/{eventId}/{metric}
// Use * to subscribe to all metrics first, then narrow to a specific metric channel
const sub = dataworks.subscribe("dataworks/1/1/*", (event) => {
  console.log("Received:", event);
});

// Later: close the subscription
sub.close();

What You'll Need​

Before using the SDK, you'll need credentials from the Dataworks team:

ItemDescription
UsernameYour Dataworks developer account username
PasswordYour Dataworks developer account password
Client IDCognito app client ID for authentication
Ingest URLAPI Gateway endpoint for metric ingestion
Error URLAPI Gateway endpoint for error reporting
Realtime URLAppSync Events API endpoint for subscriptions
apiKey (optional)AppSync Events API key for subscription-only access

Contact the Dataworks team to get your developer credentials.

If you provide both Cognito credentials (login() + clientId) and apiKey, subscriptions always use Cognito auth. apiKey is only used when Cognito login credentials are not provided.

ESM and CommonJS​

The SDK ships as a dual ESM/CJS package. Both import and require work out of the box:

// ESM
import { DataClient } from "@dataworks-technology/data";

// CJS
const { DataClient } = require("@dataworks-technology/data");

TypeScript​

Full TypeScript type definitions are included. All types are exported from the package root:

import type {
  DataClientConfig,
  Metric,
  LoginResult,
  ErrorReport,
  Subscription,
} from "@dataworks-technology/data";

Next Steps​