@nativesquare/soma 0.12.0 → 0.13.0

package/src/client/types.ts

@@ -1,215 +1,303 @@
-import type {
-    GenericActionCtx,
-    GenericMutationCtx,
-    GenericQueryCtx,
-    GenericDataModel,
-} from "convex/server";
-
-// ─── Context Types ──────────────────────────────────────────────────────────
-// Narrowed Convex context types that only expose the runner methods each
-// operation actually needs.
-
-export type QueryCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
-
-export type MutationCtx = Pick<
-    GenericMutationCtx<GenericDataModel>,
-    "runQuery" | "runMutation"
->;
-
-export type ActionCtx = Pick<
-    GenericActionCtx<GenericDataModel>,
-    "runQuery" | "runMutation" | "runAction"
->;
-
-// ─── Provider Configuration ─────────────────────────────────────────────────
-
-/**
- * Configuration for the Strava integration.
- *
- * If not provided to the Soma constructor, the class will attempt to
- * read `STRAVA_CLIENT_ID` and `STRAVA_CLIENT_SECRET`
- * from environment variables automatically.
- */
-export interface SomaStravaConfig {
-  /** Your Strava application's Client ID. */
-  clientId: string;
-  /** Your Strava application's Client Secret. */
-  clientSecret: string;
-}
-
-/**
- * Configuration for the Garmin integration.
- *
- * If not provided to the Soma constructor, the class will attempt to
- * read `GARMIN_CLIENT_ID` and `GARMIN_CLIENT_SECRET` from
- * environment variables automatically.
- */
-export interface SomaGarminConfig {
-  /** Your Garmin application's Client ID. */
-  clientId: string;
-  /** Your Garmin application's Client Secret. */
-  clientSecret: string;
-}
-
-// ─── Data Query & Ingestion Args ────────────────────────────────────────────
-
-/**
- * Common args shape for all ingestion methods.
- *
- * Requires `connectionId` and `userId` at minimum — additional fields
- * come from the transformer output (e.g., `metadata`, `calories_data`, etc.)
- * and are validated server-side by Convex validators.
- */
-export type IngestArgs = {
-  connectionId: string;
-  userId: string;
-} & Record<string, unknown>;
-
-/**
- * Base args for time-range filtered queries.
- *
- * - `userId` is required for all health data queries.
- * - `startTime` / `endTime` are optional ISO-8601 bounds on `metadata.start_time`.
- */
-export type TimeRangeArgs = {
-  userId: string;
-  startTime?: string;
-  endTime?: string;
-};
-
-/**
- * Args for list (collect-all) queries with optional ordering and limit.
- */
-export type ListTimeRangeArgs = TimeRangeArgs & {
-  order?: "asc" | "desc";
-  limit?: number;
-};
-
-/**
- * Args for paginated queries with Convex pagination options.
- */
-export type PaginateTimeRangeArgs = TimeRangeArgs & {
-  paginationOpts: { numItems: number; cursor: string | null };
-};
-
-// ─── OAuth Callback Events ──────────────────────────────────────────────────
-
-/** Data passed to `onComplete` after Strava OAuth completes. */
-export interface StravaConnectEvent {
-  provider: "STRAVA";
-  userId: string;
-  connectionId: string;
-}
-
-/** Data passed to `oauth.onComplete` after Garmin OAuth completes. */
-export interface GarminConnectEvent {
-  provider: "GARMIN";
-  userId: string;
-  connectionId: string;
-}
-
-// ─── Garmin Webhook Types ───────────────────────────────────────────────────
-
-/** Data passed to webhook `events` handlers and `onEvent` after data ingestion. */
-export interface GarminWebhookEvent {
-  dataType: string;
-  processed: number;
-  errors: Array<{ type: string; id: string; error: string }>;
-  /** Users whose data was affected by this webhook. */
-  affectedUsers: Array<{ userId: string; connectionId: string }>;
-}
-
-/** Webhook endpoint names matching the Garmin API data types. */
-export type GarminWebhookEventName =
-  | "activities" | "activity-details" | "manually-updated-activities" | "move-iq"
-  | "blood-pressures" | "body-compositions" | "dailies" | "epochs"
-  | "health-snapshot" | "sleeps" | "hrv" | "stress" | "pulse-ox"
-  | "respiration" | "skin-temp" | "user-metrics" | "menstrual-cycle-tracking";
-
-/** Handler for a specific webhook event or the catch-all `onEvent`. */
-export type GarminWebhookHandler = (
-  ctx: GenericActionCtx<GenericDataModel>,
-  event: GarminWebhookEvent,
-) => Promise<void>;
-
-// ─── Route Registration Options ─────────────────────────────────────────────
-
-/**
- * Per-provider options for `registerRoutes`.
- */
-export interface StravaOAuthOptions {
-  /** HTTP path for the OAuth callback. @default "/api/strava/callback" */
-  path?: string;
-  /** Override STRAVA_CLIENT_ID env var. */
-  clientId?: string;
-  /** Override STRAVA_CLIENT_SECRET env var. */
-  clientSecret?: string;
-  /** URL to redirect the user to after a successful connection. */
-  redirectTo?: string;
-  /** Called after Strava OAuth completes and the connection is established. */
-  onComplete?: (
-    ctx: GenericActionCtx<GenericDataModel>,
-    event: StravaConnectEvent,
-  ) => Promise<void>;
-}
-
-export interface GarminOAuthOptions {
-  /** HTTP path for the OAuth callback. @default "/api/garmin/callback" */
-  path?: string;
-  /** Override GARMIN_CLIENT_ID env var. */
-  clientId?: string;
-  /** Override GARMIN_CLIENT_SECRET env var. */
-  clientSecret?: string;
-  /** URL to redirect the user to after a successful connection. */
-  redirectTo?: string;
-  /** Called after Garmin OAuth completes and the connection is established. */
-  onComplete?: (
-    ctx: GenericActionCtx<GenericDataModel>,
-    event: GarminConnectEvent,
-  ) => Promise<void>;
-}
-
-export interface GarminWebhookOptions {
-  /** Base path prefix for all webhook routes. @default "/api/garmin/webhook" */
-  basePath?: string;
-  /** Called after every webhook payload is processed, regardless of data type. */
-  onEvent?: GarminWebhookHandler;
-  /**
-   * Per-data-type webhook registration.
-   *
-   * **Only data types listed here get an HTTP route registered.**
-   * Unlisted types are ignored — Garmin receives a 404 if it POSTs to them.
-   *
-   * Pass a handler function to run custom logic after ingestion,
-   * or `true` to register the route with default processing only.
-   *
-   * @example
-   * ```ts
-   * events: {
-   *   "activities": async (ctx, event) => { // custom side-effect },
-   *   "sleeps": true,   // register route, default processing only
-   *   "dailies": true,
-   * }
-   * ```
-   */
-  events?: Partial<Record<GarminWebhookEventName, GarminWebhookHandler | true>>;
-}
-
-export interface RegisterRoutesOptions {
-  strava?: {
-    /** OAuth callback configuration. */
-    oauth?: StravaOAuthOptions;
-  };
-  garmin?: {
-    /** OAuth callback configuration. */
-    oauth?: GarminOAuthOptions;
-    /**
-     * Webhook route configuration.
-     *
-     * Routes are **disabled by default**. Only data types listed in `events`
-     * get an HTTP endpoint registered. Omit entirely or set to `false` to
-     * skip all webhook routes.
-     */
-    webhook?: GarminWebhookOptions | false;
-  };
-}
+import type {
+    GenericActionCtx,
+    GenericMutationCtx,
+    GenericQueryCtx,
+    GenericDataModel,
+} from "convex/server";
+
+// ─── Context Types ──────────────────────────────────────────────────────────
+// Narrowed Convex context types that only expose the runner methods each
+// operation actually needs.
+
+export type QueryCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+
+export type MutationCtx = Pick<
+    GenericMutationCtx<GenericDataModel>,
+    "runQuery" | "runMutation"
+>;
+
+export type ActionCtx = Pick<
+    GenericActionCtx<GenericDataModel>,
+    "runQuery" | "runMutation" | "runAction"
+>;
+
+// ─── Provider Configuration ─────────────────────────────────────────────────
+
+/**
+ * Configuration for the Strava integration.
+ *
+ * If not provided to the Soma constructor, the class will attempt to
+ * read `STRAVA_CLIENT_ID` and `STRAVA_CLIENT_SECRET`
+ * from environment variables automatically.
+ */
+export interface SomaStravaConfig {
+  /** Your Strava application's Client ID. */
+  clientId: string;
+  /** Your Strava application's Client Secret. */
+  clientSecret: string;
+}
+
+/**
+ * Configuration for the Garmin integration.
+ *
+ * If not provided to the Soma constructor, the class will attempt to
+ * read `GARMIN_CLIENT_ID` and `GARMIN_CLIENT_SECRET` from
+ * environment variables automatically.
+ */
+export interface SomaGarminConfig {
+  /** Your Garmin application's Client ID. */
+  clientId: string;
+  /** Your Garmin application's Client Secret. */
+  clientSecret: string;
+}
+
+// ─── Shared Error & Result Types ───────────────────────────────────────────
+
+/**
+ * A structured error from a Soma operation.
+ *
+ * Operational errors (API failures, transform errors, ingestion failures)
+ * are returned in the result — not thrown. Only configuration errors
+ * (missing connection, nonexistent document) are thrown as exceptions.
+ */
+export interface SomaError {
+  /** Category of the failed item (e.g. `"activity"`, `"pushWorkout"`, `"ingest"`). */
+  type: string;
+  /** Identifier of the failed item, or `"fetch"` for API-level failures. */
+  id: string;
+  /** Human-readable error description. */
+  message: string;
+}
+
+/**
+ * Standard result wrapper for all Soma data operations.
+ *
+ * - `data` contains the operation's success payload.
+ * - `errors` contains any operational failures that occurred.
+ *
+ * For **batch operations** (pull, sync), partial success is possible:
+ * `data` contains the counts of successfully processed items, while
+ * `errors` lists the individual failures.
+ *
+ * For **atomic operations** (push, delete), `data` is `null` when the
+ * operation fails, with a single entry in `errors` describing the cause.
+ */
+export type SomaResult<T> = {
+  data: T;
+  errors: SomaError[];
+};
+
+// ─── Data Query & Ingestion Args ────────────────────────────────────────────
+
+/**
+ * Common args shape for all ingestion methods.
+ *
+ * Requires `connectionId` and `userId` at minimum — additional fields
+ * come from the transformer output (e.g., `metadata`, `calories_data`, etc.)
+ * and are validated server-side by Convex validators.
+ */
+export type IngestArgs = {
+  connectionId: string;
+  userId: string;
+} & Record<string, unknown>;
+
+/**
+ * Base args for time-range filtered queries.
+ *
+ * - `userId` is required for all health data queries.
+ * - `startTime` / `endTime` are optional ISO-8601 bounds on `metadata.start_time`.
+ */
+export type TimeRangeArgs = {
+  userId: string;
+  startTime?: string;
+  endTime?: string;
+};
+
+/**
+ * Args for list (collect-all) queries with optional ordering and limit.
+ */
+export type ListTimeRangeArgs = TimeRangeArgs & {
+  order?: "asc" | "desc";
+  limit?: number;
+};
+
+/**
+ * Args for paginated queries with Convex pagination options.
+ */
+export type PaginateTimeRangeArgs = TimeRangeArgs & {
+  paginationOpts: { numItems: number; cursor: string | null };
+};
+
+// ─── OAuth Callback Events ──────────────────────────────────────────────────
+
+/** Data passed to `onComplete` after Strava OAuth completes. */
+export interface StravaConnectEvent {
+  provider: "STRAVA";
+  userId: string;
+  connectionId: string;
+}
+
+/** Data passed to `oauth.onComplete` after Garmin OAuth completes. */
+export interface GarminConnectEvent {
+  provider: "GARMIN";
+  userId: string;
+  connectionId: string;
+}
+
+// ─── Garmin Webhook Types ───────────────────────────────────────────────────
+
+/** Args accepted by all Garmin webhook handler actions inside the component. */
+export type GarminWebhookActionArgs = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  payload: any;
+  autoIngest?: boolean;
+};
+
+/** Result returned by all Garmin webhook handler actions inside the component. */
+export interface GarminWebhookActionResult {
+  errors: SomaError[];
+  items: GarminWebhookItem[];
+}
+
+/** A single transformed item with its user/connection mapping. */
+export interface GarminWebhookItem {
+  /** The Soma connection ID that this data belongs to. */
+  connectionId: string;
+  /** The host app's user ID. */
+  userId: string;
+  /** The transformed data in Soma's normalized format. */
+  data: Record<string, unknown>;
+}
+
+/**
+ * Data passed to webhook `events` handlers and `onEvent` after processing.
+ *
+ * The host app receives the full set of transformed items plus the raw Garmin
+ * payload, regardless of the `autoIngest` setting.
+ */
+export interface GarminWebhookEvent {
+  /** The Garmin data type that triggered this webhook (e.g. `"activities"`, `"sleeps"`). */
+  dataType: string;
+  /** Errors encountered during connection resolution, transformation, or ingestion. */
+  errors: SomaError[];
+  /** The raw JSON payload received from Garmin, before any transformation. */
+  rawPayload: unknown;
+  /**
+   * Transformed items in Soma's normalized format.
+   *
+   * Always contains the full set of successfully transformed items, regardless
+   * of the `autoIngest` setting. When `autoIngest` is `true`, these are the
+   * same items that were written to the database. When `autoIngest` is `false`,
+   * the host app can use them for custom ingestion or processing.
+   *
+   * Empty for ping-mode webhooks (which contain no data).
+   */
+  items: GarminWebhookItem[];
+}
+
+/** Webhook endpoint names matching the Garmin API data types. */
+export type GarminWebhookEventName =
+  | "activities" | "activity-details" | "manually-updated-activities" | "move-iq"
+  | "blood-pressures" | "body-compositions" | "dailies" | "epochs"
+  | "health-snapshot" | "sleeps" | "hrv" | "stress" | "pulse-ox"
+  | "respiration" | "skin-temp" | "user-metrics" | "menstrual-cycle-tracking";
+
+/** Handler for a specific webhook event or the catch-all `onEvent`. */
+export type GarminWebhookHandler = (
+  ctx: GenericActionCtx<GenericDataModel>,
+  event: GarminWebhookEvent,
+) => Promise<void>;
+
+// ─── Route Registration Options ─────────────────────────────────────────────
+
+/**
+ * Per-provider options for `registerRoutes`.
+ */
+export interface StravaOAuthOptions {
+  /** HTTP path for the OAuth callback. @default "/api/strava/callback" */
+  path?: string;
+  /** URL to redirect the user to after a successful connection. */
+  redirectTo?: string;
+  /** Called after Strava OAuth completes and the connection is established. */
+  onComplete?: (
+    ctx: GenericActionCtx<GenericDataModel>,
+    event: StravaConnectEvent,
+  ) => Promise<void>;
+}
+
+export interface GarminOAuthOptions {
+  /** HTTP path for the OAuth callback. @default "/api/garmin/callback" */
+  path?: string;
+  /** URL to redirect the user to after a successful connection. */
+  redirectTo?: string;
+  /** Called after Garmin OAuth completes and the connection is established. */
+  onComplete?: (
+    ctx: GenericActionCtx<GenericDataModel>,
+    event: GarminConnectEvent,
+  ) => Promise<void>;
+}
+
+export interface GarminWebhookOptions {
+  /** Base path prefix for all webhook routes. @default "/api/garmin/webhook" */
+  basePath?: string;
+  /**
+   * Whether to automatically ingest (upsert) transformed data into the Soma
+   * database when a webhook payload is received.
+   *
+   * When `true` (default), incoming data is validated, transformed, and written
+   * to the database automatically. When `false`, the webhook still receives and
+   * validates the payload, but skips the database write — useful when you want
+   * to handle ingestion yourself via the `onEvent` / per-type callbacks.
+   *
+   * @default true
+   */
+  autoIngest?: boolean;
+  /** Called after every webhook payload is processed, regardless of data type. */
+  onEvent?: GarminWebhookHandler;
+  /**
+   * Per-data-type webhook registration.
+   *
+   * **Only data types listed here get an HTTP route registered.**
+   * Unlisted types are ignored — Garmin receives a 404 if it POSTs to them.
+   *
+   * Pass a handler function to run custom logic after ingestion,
+   * or `true` to register the route with default processing only.
+   *
+   * @example
+   * ```ts
+   * events: {
+   *   "activities": async (ctx, event) => { // custom side-effect },
+   *   "sleeps": true,   // register route, default processing only
+   *   "dailies": true,
+   * }
+   * ```
+   */
+  events?: Partial<Record<GarminWebhookEventName, GarminWebhookHandler | true>>;
+}
+
+export interface RegisterRoutesOptions {
+  strava?: {
+    /** Override STRAVA_CLIENT_ID env var. */
+    clientId?: string;
+    /** Override STRAVA_CLIENT_SECRET env var. */
+    clientSecret?: string;
+    /** OAuth callback configuration. */
+    oauth?: StravaOAuthOptions;
+  };
+  garmin?: {
+    /** Override GARMIN_CLIENT_ID env var. */
+    clientId?: string;
+    /** Override GARMIN_CLIENT_SECRET env var. */
+    clientSecret?: string;
+    /** OAuth callback configuration. */
+    oauth?: GarminOAuthOptions;
+    /**
+     * Webhook route configuration.
+     *
+     * Routes are **disabled by default**. Only data types listed in `events`
+     * get an HTTP endpoint registered. Omit entirely or set to `false` to
+     * skip all webhook routes.
+     */
+    webhook?: GarminWebhookOptions | false;
+  };
+}