@dataworks-technology/data 0.2.2 → 0.3.0

package/dist/index.d.cts

@@ -1,3 +1,6 @@
+import { validateMetric, filterValidMetrics } from '@dataworks/sdk/client';
+export { filterValidMetrics, validateMetric } from '@dataworks/sdk/client';
+
 /**
  * Public types for @dataworks-technology/data.
  *
@@ -19,7 +22,34 @@ interface DataClientConfig {
     errorUrl: string;
     /** AppSync Events API endpoint for real-time subscriptions */
     realtimeUrl: string;
+    /** AppSync GraphQL HTTP endpoint for query/mutate/subscribeGraphQL (e.g. https://{id}.appsync-api.{region}.amazonaws.com/graphql) */
+    graphqlUrl?: string;
+}
+/** GraphQL authentication strategy for API calls. */
+type GraphQLAuthMode = "auto" | "cognito" | "apiKey";
+/** Optional per-operation controls for GraphQL query/mutation/subscription calls. */
+interface GraphQLOperationOptions {
+    /** Auth mode selection. auto prefers Cognito token, then apiKey if configured. */
+    authMode?: GraphQLAuthMode;
+    /** Additional request headers merged into auth headers. */
+    headers?: Record<string, string>;
+}
+/** GraphQL error shape returned by AppSync-compliant APIs. */
+interface GraphQLError {
+    message: string;
+    path?: ReadonlyArray<string | number>;
+    extensions?: Record<string, unknown>;
 }
+/** Data SDK error for GraphQL operation failures. */
+interface GraphQLClientError {
+    message: string;
+    errors?: GraphQLError[];
+    cause?: Error;
+}
+/** Callback for GraphQL subscription payloads. */
+type GraphQLSubscriptionHandler<T = unknown> = (payload: T) => void;
+/** Callback for GraphQL subscription errors. */
+type GraphQLSubscriptionErrorHandler = (error: GraphQLClientError) => void;
 /** Credentials returned from a successful login. */
 interface LoginResult {
     accessToken: string;
@@ -30,8 +60,8 @@ interface LoginResult {
 }
 /** A single metric data point to ingest. */
 interface Metric {
-    /** Unique athlete identifier */
-    athleteId: string;
+    /** Unique athlete public identifier */
+    athletePublicId: string;
     /** Metric name (e.g. "heartrate", "speed", "power") */
     metric: string;
     /** Metric value — number or string */
@@ -41,7 +71,7 @@ interface Metric {
 }
 /** Validated metric item (all fields confirmed present and correct). */
 interface MetricItem {
-    athleteId: string;
+    athletePublicId: string;
     metric: string;
     value: unknown;
     timestamp: number;
@@ -49,22 +79,22 @@ interface MetricItem {
 /** Loosely-typed input for validation — all fields are unknown. */
 interface RawMetricItem {
     metric: unknown;
-    athleteId: unknown;
+    athletePublicId: unknown;
     value: unknown;
     timestamp: unknown;
 }
 /** Payload shape for metric ingestion. */
 interface MetricsPayload {
-    eventId: string;
-    datasetDatasourceId: string;
+    eventPublicId: string;
+    datasetDatasourcePublicId: string;
     metrics: MetricItem[];
 }
 /** Error report to send to the Data Engine. */
 interface ErrorReport {
-    /** Dataset-datasource identifier */
-    datasetDatasourceId: string;
-    /** Athlete identifier */
-    athleteId: string;
+    /** Dataset-datasource public identifier */
+    datasetDatasourcePublicId: string;
+    /** Athlete public identifier */
+    athletePublicId: string;
     /** Client identifier */
     clientId: number;
     /** Short error title */
@@ -175,11 +205,38 @@ declare class MetricValidationError extends Error {
     constructor(message: string, dropped: DroppedMetric[]);
 }
 
+/**
+ * DataClient — the public entry point for external developers using the Dataworks Data Engine.
+ *
+ * Handles authentication, metric ingestion, error reporting, and real-time subscriptions.
+ * All SDK foundation code (@dataworks/sdk) is bundled at build time — consumers install
+ * only @dataworks-technology/data with zero transitive dependencies.
+ *
+ * @example
+ * ```ts
+ * import { DataClient } from "@dataworks-technology/data";
+ *
+ * const dataworks = new DataClient({
+ *   cognitoEndpoint: "https://cognito-idp.eu-west-1.amazonaws.com/",
+ *   clientId: "abc123",
+ *   ingestUrl: "https://dev-realtime.dataworks.live",
+ *   errorUrl: "https://dev-realtime-errors.dataworks.live",
+ *   realtimeUrl: "https://dev-event-api.dataworks.live",
+ * });
+ *
+ * await dataworks.login("graeme", "password123");
+ * await dataworks.ingest([{ athletePublicId: "1", metric: "heartrate_calculated", value: 172, timestamp: Date.now() / 1000 }], "evt1", "ds1");
+ * ```
+ *
+ * @module @dataworks-technology/data
+ */
+
 declare class DataClient {
     private readonly config;
     private credentials;
     private lastLoginUsername;
     private refreshInFlight;
+    private apolloClient;
     constructor(config: DataClientConfig);
     /**
      * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.
@@ -196,12 +253,12 @@ declare class DataClient {
      * Validates each metric before sending — invalid metrics are dropped with warnings.
      *
      * @param metrics - Array of metric data points
-     * @param eventId - Event identifier
-     * @param datasetDatasourceId - Dataset-datasource identifier
+     * @param eventPublicId - Event public identifier
+     * @param datasetDatasourcePublicId - Dataset-datasource public 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>;
+    ingest(metrics: Metric[], eventPublicId: string, datasetDatasourcePublicId: string): Promise<void>;
     /**
      * Ingest metrics with structured validation diagnostics.
      *
@@ -211,7 +268,7 @@ declare class DataClient {
      *
      * @returns IngestResult with accepted/dropped counts and dropped reasons.
      */
-    ingestWithResult(metrics: Metric[], eventId: string, datasetDatasourceId: string, options?: IngestOptions): Promise<IngestResult>;
+    ingestWithResult(metrics: Metric[], eventPublicId: string, datasetDatasourcePublicId: string, options?: IngestOptions): Promise<IngestResult>;
     /**
      * Report an error to the Dataworks Data Engine.
      *
@@ -220,16 +277,30 @@ declare class DataClient {
      * @see https://data-sdk-docs.dataworks.live/error-reporting
      */
     reportError(error: ErrorReport): Promise<void>;
+    /**
+     * Execute a typed GraphQL query against the Data AppSync API.
+     */
+    query<TData = unknown, TVariables extends Record<string, unknown> = Record<string, unknown>>(query: string, variables?: TVariables, options?: GraphQLOperationOptions): Promise<TData>;
+    /**
+     * Execute a typed GraphQL mutation against the Data AppSync API.
+     */
+    mutate<TData = unknown, TVariables extends Record<string, unknown> = Record<string, unknown>>(mutation: string, variables?: TVariables, options?: GraphQLOperationOptions): Promise<TData>;
+    /**
+     * Subscribe to a typed GraphQL subscription from the Data AppSync API.
+     */
+    subscribeGraphQL<TData = unknown, TVariables extends Record<string, unknown> = Record<string, unknown>>(subscription: string, onEvent: GraphQLSubscriptionHandler<TData>, onError?: GraphQLSubscriptionErrorHandler, variables?: TVariables): Subscription;
+    private getApolloClient;
     /**
      * Subscribe to a real-time data channel on the AppSync Events API.
      * Uses the Cognito JWT for authentication.
      *
-     * Channel format: dataworks/{datasetDatasourceId}/{eventId}/{metric}
+     * Channel format: dataworks/{datasetDatasourcePublicId}/{eventPublicId}/{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
+     * @param onError - Optional callback invoked on connection or protocol errors
      * @returns Subscription handle with a close() method
      * @throws Error if not authenticated
      * @see https://data-sdk-docs.dataworks.live/real-time-subscriptions
@@ -239,12 +310,12 @@ declare class DataClient {
      * 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;
+    static validateMetric: typeof validateMetric;
     /**
      * 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[];
+    static filterValidMetrics: typeof filterValidMetrics;
     /** Returns true if the client has been authenticated via login(). */
     get isAuthenticated(): boolean;
     /** Returns the tenant from the last successful login, or null. */
@@ -259,24 +330,9 @@ declare class DataClient {
     private requireIngestAuth;
     private fetchWithAutoRefresh;
     private refreshSession;
+    private getGraphQLHttpUrl;
+    private buildGraphQLHeaders;
+    private executeGraphQLOperation;
 }
 
-/**
- * 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 DroppedMetric, type ErrorHandler, type ErrorReport, type IngestOptions, type IngestResult, type LoginResult, type Metric, type MetricItem, MetricValidationError, type MetricsPayload, type RawMetricItem, type Subscription, type SubscriptionError, type SubscriptionEvent, type SubscriptionHandler, type SubscriptionMetric, type ValidationMode, filterValidMetrics, validateMetric };
+export { DataClient, type DataClientConfig, type DroppedMetric, type ErrorHandler, type ErrorReport, type GraphQLAuthMode, type GraphQLClientError, type GraphQLError, type GraphQLOperationOptions, type GraphQLSubscriptionErrorHandler, type GraphQLSubscriptionHandler, type IngestOptions, type IngestResult, type LoginResult, type Metric, type MetricItem, MetricValidationError, type MetricsPayload, type RawMetricItem, type Subscription, type SubscriptionError, type SubscriptionEvent, type SubscriptionHandler, type SubscriptionMetric, type ValidationMode };

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { validateMetric, filterValidMetrics } from '@dataworks/sdk/client';
+export { filterValidMetrics, validateMetric } from '@dataworks/sdk/client';
+
 /**
  * Public types for @dataworks-technology/data.
  *
@@ -19,7 +22,34 @@ interface DataClientConfig {
     errorUrl: string;
     /** AppSync Events API endpoint for real-time subscriptions */
     realtimeUrl: string;
+    /** AppSync GraphQL HTTP endpoint for query/mutate/subscribeGraphQL (e.g. https://{id}.appsync-api.{region}.amazonaws.com/graphql) */
+    graphqlUrl?: string;
+}
+/** GraphQL authentication strategy for API calls. */
+type GraphQLAuthMode = "auto" | "cognito" | "apiKey";
+/** Optional per-operation controls for GraphQL query/mutation/subscription calls. */
+interface GraphQLOperationOptions {
+    /** Auth mode selection. auto prefers Cognito token, then apiKey if configured. */
+    authMode?: GraphQLAuthMode;
+    /** Additional request headers merged into auth headers. */
+    headers?: Record<string, string>;
+}
+/** GraphQL error shape returned by AppSync-compliant APIs. */
+interface GraphQLError {
+    message: string;
+    path?: ReadonlyArray<string | number>;
+    extensions?: Record<string, unknown>;
 }
+/** Data SDK error for GraphQL operation failures. */
+interface GraphQLClientError {
+    message: string;
+    errors?: GraphQLError[];
+    cause?: Error;
+}
+/** Callback for GraphQL subscription payloads. */
+type GraphQLSubscriptionHandler<T = unknown> = (payload: T) => void;
+/** Callback for GraphQL subscription errors. */
+type GraphQLSubscriptionErrorHandler = (error: GraphQLClientError) => void;
 /** Credentials returned from a successful login. */
 interface LoginResult {
     accessToken: string;
@@ -30,8 +60,8 @@ interface LoginResult {
 }
 /** A single metric data point to ingest. */
 interface Metric {
-    /** Unique athlete identifier */
-    athleteId: string;
+    /** Unique athlete public identifier */
+    athletePublicId: string;
     /** Metric name (e.g. "heartrate", "speed", "power") */
     metric: string;
     /** Metric value — number or string */
@@ -41,7 +71,7 @@ interface Metric {
 }
 /** Validated metric item (all fields confirmed present and correct). */
 interface MetricItem {
-    athleteId: string;
+    athletePublicId: string;
     metric: string;
     value: unknown;
     timestamp: number;
@@ -49,22 +79,22 @@ interface MetricItem {
 /** Loosely-typed input for validation — all fields are unknown. */
 interface RawMetricItem {
     metric: unknown;
-    athleteId: unknown;
+    athletePublicId: unknown;
     value: unknown;
     timestamp: unknown;
 }
 /** Payload shape for metric ingestion. */
 interface MetricsPayload {
-    eventId: string;
-    datasetDatasourceId: string;
+    eventPublicId: string;
+    datasetDatasourcePublicId: string;
     metrics: MetricItem[];
 }
 /** Error report to send to the Data Engine. */
 interface ErrorReport {
-    /** Dataset-datasource identifier */
-    datasetDatasourceId: string;
-    /** Athlete identifier */
-    athleteId: string;
+    /** Dataset-datasource public identifier */
+    datasetDatasourcePublicId: string;
+    /** Athlete public identifier */
+    athletePublicId: string;
     /** Client identifier */
     clientId: number;
     /** Short error title */
@@ -175,11 +205,38 @@ declare class MetricValidationError extends Error {
     constructor(message: string, dropped: DroppedMetric[]);
 }
 
+/**
+ * DataClient — the public entry point for external developers using the Dataworks Data Engine.
+ *
+ * Handles authentication, metric ingestion, error reporting, and real-time subscriptions.
+ * All SDK foundation code (@dataworks/sdk) is bundled at build time — consumers install
+ * only @dataworks-technology/data with zero transitive dependencies.
+ *
+ * @example
+ * ```ts
+ * import { DataClient } from "@dataworks-technology/data";
+ *
+ * const dataworks = new DataClient({
+ *   cognitoEndpoint: "https://cognito-idp.eu-west-1.amazonaws.com/",
+ *   clientId: "abc123",
+ *   ingestUrl: "https://dev-realtime.dataworks.live",
+ *   errorUrl: "https://dev-realtime-errors.dataworks.live",
+ *   realtimeUrl: "https://dev-event-api.dataworks.live",
+ * });
+ *
+ * await dataworks.login("graeme", "password123");
+ * await dataworks.ingest([{ athletePublicId: "1", metric: "heartrate_calculated", value: 172, timestamp: Date.now() / 1000 }], "evt1", "ds1");
+ * ```
+ *
+ * @module @dataworks-technology/data
+ */
+
 declare class DataClient {
     private readonly config;
     private credentials;
     private lastLoginUsername;
     private refreshInFlight;
+    private apolloClient;
     constructor(config: DataClientConfig);
     /**
      * Authenticate with the Dataworks platform using Cognito USER_PASSWORD_AUTH.
@@ -196,12 +253,12 @@ declare class DataClient {
      * Validates each metric before sending — invalid metrics are dropped with warnings.
      *
      * @param metrics - Array of metric data points
-     * @param eventId - Event identifier
-     * @param datasetDatasourceId - Dataset-datasource identifier
+     * @param eventPublicId - Event public identifier
+     * @param datasetDatasourcePublicId - Dataset-datasource public 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>;
+    ingest(metrics: Metric[], eventPublicId: string, datasetDatasourcePublicId: string): Promise<void>;
     /**
      * Ingest metrics with structured validation diagnostics.
      *
@@ -211,7 +268,7 @@ declare class DataClient {
      *
      * @returns IngestResult with accepted/dropped counts and dropped reasons.
      */
-    ingestWithResult(metrics: Metric[], eventId: string, datasetDatasourceId: string, options?: IngestOptions): Promise<IngestResult>;
+    ingestWithResult(metrics: Metric[], eventPublicId: string, datasetDatasourcePublicId: string, options?: IngestOptions): Promise<IngestResult>;
     /**
      * Report an error to the Dataworks Data Engine.
      *
@@ -220,16 +277,30 @@ declare class DataClient {
      * @see https://data-sdk-docs.dataworks.live/error-reporting
      */
     reportError(error: ErrorReport): Promise<void>;
+    /**
+     * Execute a typed GraphQL query against the Data AppSync API.
+     */
+    query<TData = unknown, TVariables extends Record<string, unknown> = Record<string, unknown>>(query: string, variables?: TVariables, options?: GraphQLOperationOptions): Promise<TData>;
+    /**
+     * Execute a typed GraphQL mutation against the Data AppSync API.
+     */
+    mutate<TData = unknown, TVariables extends Record<string, unknown> = Record<string, unknown>>(mutation: string, variables?: TVariables, options?: GraphQLOperationOptions): Promise<TData>;
+    /**
+     * Subscribe to a typed GraphQL subscription from the Data AppSync API.
+     */
+    subscribeGraphQL<TData = unknown, TVariables extends Record<string, unknown> = Record<string, unknown>>(subscription: string, onEvent: GraphQLSubscriptionHandler<TData>, onError?: GraphQLSubscriptionErrorHandler, variables?: TVariables): Subscription;
+    private getApolloClient;
     /**
      * Subscribe to a real-time data channel on the AppSync Events API.
      * Uses the Cognito JWT for authentication.
      *
-     * Channel format: dataworks/{datasetDatasourceId}/{eventId}/{metric}
+     * Channel format: dataworks/{datasetDatasourcePublicId}/{eventPublicId}/{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
+     * @param onError - Optional callback invoked on connection or protocol errors
      * @returns Subscription handle with a close() method
      * @throws Error if not authenticated
      * @see https://data-sdk-docs.dataworks.live/real-time-subscriptions
@@ -239,12 +310,12 @@ declare class DataClient {
      * 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;
+    static validateMetric: typeof validateMetric;
     /**
      * 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[];
+    static filterValidMetrics: typeof filterValidMetrics;
     /** Returns true if the client has been authenticated via login(). */
     get isAuthenticated(): boolean;
     /** Returns the tenant from the last successful login, or null. */
@@ -259,24 +330,9 @@ declare class DataClient {
     private requireIngestAuth;
     private fetchWithAutoRefresh;
     private refreshSession;
+    private getGraphQLHttpUrl;
+    private buildGraphQLHeaders;
+    private executeGraphQLOperation;
 }
 
-/**
- * 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 DroppedMetric, type ErrorHandler, type ErrorReport, type IngestOptions, type IngestResult, type LoginResult, type Metric, type MetricItem, MetricValidationError, type MetricsPayload, type RawMetricItem, type Subscription, type SubscriptionError, type SubscriptionEvent, type SubscriptionHandler, type SubscriptionMetric, type ValidationMode, filterValidMetrics, validateMetric };
+export { DataClient, type DataClientConfig, type DroppedMetric, type ErrorHandler, type ErrorReport, type GraphQLAuthMode, type GraphQLClientError, type GraphQLError, type GraphQLOperationOptions, type GraphQLSubscriptionErrorHandler, type GraphQLSubscriptionHandler, type IngestOptions, type IngestResult, type LoginResult, type Metric, type MetricItem, MetricValidationError, type MetricsPayload, type RawMetricItem, type Subscription, type SubscriptionError, type SubscriptionEvent, type SubscriptionHandler, type SubscriptionMetric, type ValidationMode };