@dataworks-technology/data 0.2.0 → 0.3.0

package/README.md

@@ -9,12 +9,14 @@ Official SDK for the Dataworks Data Engine — authenticate, ingest live athlete
 
 ## Features
 
-- **Zero dependencies** — fully self-contained, no transitive installs
+- **Self-contained bundle** — Apollo Client and AppSync subscription link are bundled in; consumers install nothing extra
 - **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
+- **Real-time subscriptions** — WebSocket-based live data streaming via AppSync Events API
+- **Typed GraphQL API client** — execute any query, mutation, or subscription against the Data Engine schema
+- **Schema type exports** — full codegen types available via `@dataworks-technology/data/schema`
+- **Cognito authentication** — secure login with automatic token refresh
 
 ## Prerequisites
 
@@ -27,6 +29,7 @@ You need a Dataworks developer account. Contact your Dataworks administrator to
 | `ingestUrl` | API Gateway endpoint for metric ingestion |
 | `errorUrl` | API Gateway endpoint for error reporting |
 | `realtimeUrl` | AppSync Events API endpoint for subscriptions |
+| `graphqlUrl` (optional) | AppSync GraphQL HTTP endpoint |
 | Username + password | Your developer login credentials |
 | `apiKey` (optional) | AppSync Events API key for subscription-only access |
 
@@ -93,6 +96,7 @@ const dataworks = new DataClient({
   ingestUrl: "https://ingest.dataworks.live",
   errorUrl: "https://errors.dataworks.live",
   realtimeUrl: "https://realtime.dataworks.live",
+  graphqlUrl: "https://api-id.appsync-api.eu-west-1.amazonaws.com/graphql",
 });
 ```
 
@@ -239,6 +243,87 @@ interface SubscriptionError {
 | `RECONNECT_FAILED` | Token refresh failed after auth expiry |
 | `UNKNOWN` | Unexpected error |
 
+### `dataworks.query(query, variables?, options?)`
+
+Execute a typed GraphQL query against the Data AppSync schema.
+
+```typescript
+const result = await dataworks.query<{
+  listEvents: { items: Array<{ id: number; name: string }> };
+}>(
+  `query ListEvents($tenant: String!) {
+    listEvents(tenant: $tenant) {
+      items { id name }
+    }
+  }`,
+  { tenant: "demo-tenant" },
+);
+
+console.log(result.listEvents.items);
+```
+
+### `dataworks.mutate(mutation, variables?, options?)`
+
+Execute a typed GraphQL mutation.
+
+```typescript
+const result = await dataworks.mutate<{
+  startEvent: { id: number; name: string };
+}>(
+  `mutation StartEvent($id: Int!, $tenant: String!) {
+    startEvent(id: $id, tenant: $tenant) { id name }
+  }`,
+  { id: 42, tenant: "demo-tenant" },
+);
+```
+
+### `dataworks.subscribeGraphQL(subscription, onEvent, onError?, variables?)`
+
+Subscribe to schema-level GraphQL subscriptions. Backed by Apollo Client + `aws-appsync-subscription-link` internally — AppSync Cognito auth and WebSocket protocol are handled automatically.
+
+The Apollo client is lazily created on the first `subscribeGraphQL()` call and reused for all subsequent subscriptions on the same `DataClient` instance.
+
+```typescript
+import type { Dataset, Maybe } from "@dataworks-technology/data/schema";
+
+const sub = dataworks.subscribeGraphQL<{ onUpdateDataset: Maybe<Dataset> }>(
+  `subscription OnUpdateDataset {
+    onUpdateDataset {
+      id publicId clientId name
+      eventId eventName eventLocation eventType eventStartsAt
+      createdAt updatedAt
+    }
+  }`,
+  (payload) => {
+    console.log(payload.onUpdateDataset);
+  },
+  (error) => {
+    console.error(error.message);
+  },
+);
+
+sub.close();
+```
+
+### Schema Types
+
+All Data Engine GraphQL types are exported from the `schema` subpath. Use these instead of hand-rolling your own:
+
+```typescript
+import type {
+  Dataset,
+  DatasetConnection,
+  Maybe,
+  CreateDatasetInput,
+  UpdateDatasetInput,
+  DatasetConditionInput,
+  Athlete,
+  Participant,
+  Datasource,
+  // ... all entity, connection, filter, and input types
+} from "@dataworks-technology/data/schema";
+```
+
 ### `dataworks.reportError(error)`
 
 Report an error to the Data Engine for monitoring and alerting.