@molecule/api-wearable-fitbit 1.0.0

package/dist/secrets.js

@@ -0,0 +1,30 @@
+/**
+ * Fitbit wearable bond secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import { registerSecrets } from '@molecule/api-secrets';
+/** Secret definitions required by the Fitbit wearable bond. */
+export const wearableFitbitSecretDefinitions = [
+    {
+        key: 'OAUTH_FITBIT_CLIENT_ID',
+        description: 'Fitbit OAuth client ID — Register an application at dev.fitbit.com and copy the OAuth 2.0 Client ID.',
+        helpUrl: 'https://dev.fitbit.com/apps',
+        required: true,
+    },
+    {
+        key: 'OAUTH_FITBIT_CLIENT_SECRET',
+        description: 'Fitbit client secret — Shown on your registered Fitbit application page.',
+        helpUrl: 'https://dev.fitbit.com/apps',
+        required: false,
+    },
+];
+registerSecrets(wearableFitbitSecretDefinitions);
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,+BAA+B,GAAuB;IACjE;QACE,GAAG,EAAE,wBAAwB;QAC7B,WAAW,EACT,sGAAsG;QACxG,OAAO,EAAE,6BAA6B;QACtC,QAAQ,EAAE,IAAI;KACf;IACD;QACE,GAAG,EAAE,4BAA4B;QACjC,WAAW,EAAE,0EAA0E;QACvF,OAAO,EAAE,6BAA6B;QACtC,QAAQ,EAAE,KAAK;KAChB;CACF,CAAA;AAED,eAAe,CAAC,+BAA+B,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Fitbit wearable bond types for molecule.dev.
+ *
+ * @module
+ */
+import type { UserConnection as WearableUserConnection, WearableCredentialsStore, WearableProvider as WearableProviderType } from '@molecule/api-wearable';
+export type { DailyActivity, HeartRateSummary, HeartRateZone, SleepSession, SleepStage, SleepStageSegment, SleepStageSummary, UserConnection, WearableCredentialsStore, WearableDate, WearableDateRange, WearableProvider, WeightEntry, } from '@molecule/api-wearable';
+declare global {
+    namespace NodeJS {
+        /**
+         * Process Env interface.
+         */
+        interface ProcessEnv {
+            /**
+             * The Fitbit OAuth client ID. Required to mint and refresh access
+             * tokens. Treated as a public identifier — sent in `client_id`
+             * during PKCE — but still configured as a secret for symmetry.
+             *
+             * @see https://dev.fitbit.com/build/reference/web-api/authorization/
+             */
+            OAUTH_FITBIT_CLIENT_ID?: string;
+            /**
+             * The Fitbit OAuth client secret. Required for confidential-client
+             * apps to refresh tokens via Basic auth. PKCE-only public clients
+             * may omit it (the bond falls back to the PKCE-only token call when
+             * absent).
+             *
+             * @see https://dev.fitbit.com/build/reference/web-api/authorization/
+             */
+            OAUTH_FITBIT_CLIENT_SECRET?: string;
+        }
+    }
+}
+/**
+ * Cache of `code_verifier` strings keyed by the in-flight authorization
+ * `code` string they were paired with.
+ *
+ * The Fitbit OAuth callback hands the bond an authorization `code` but
+ * not the `code_verifier` it was created with — the bond needs to store
+ * the verifier between {@link FitbitProvider.startAuthorize} and
+ * {@link FitbitProvider.connect}. The store contract leaves the choice
+ * of backing storage (Redis, Postgres, in-memory for tests) to the host.
+ */
+export interface FitbitCodeVerifierStore {
+    /**
+     * Persists the verifier indexed by the `state` value the bond will
+     * round-trip through Fitbit's authorize redirect.
+     *
+     * @param state - Opaque CSRF-protection token returned in the redirect.
+     * @param verifier - The PKCE `code_verifier` to retrieve later.
+     */
+    put(state: string, verifier: string): Promise<void>;
+    /**
+     * Retrieves and deletes the verifier associated with `state`.
+     * Implementations MUST delete on read so a verifier is never reused.
+     *
+     * @param state - The `state` value extracted from the OAuth callback.
+     * @returns The verifier, or `null` if no entry exists.
+     */
+    take(state: string): Promise<string | null>;
+}
+/**
+ * Configuration options for {@link createProvider}.
+ */
+export interface FitbitProviderOptions {
+    /**
+     * OAuth client id. Defaults to `process.env.OAUTH_FITBIT_CLIENT_ID`.
+     */
+    clientId?: string;
+    /**
+     * OAuth client secret. Defaults to
+     * `process.env.OAUTH_FITBIT_CLIENT_SECRET`. Optional — PKCE-only public
+     * clients omit it.
+     */
+    clientSecret?: string;
+    /**
+     * OAuth redirect URI registered with the Fitbit application. Required
+     * to complete the authorization-code exchange.
+     */
+    redirectUri: string;
+    /**
+     * Persists user connections (access + refresh tokens). Required.
+     */
+    credentialsStore: WearableCredentialsStore;
+    /**
+     * Optional store for PKCE `code_verifier` strings keyed by `state`.
+     * Required if the bond's `startAuthorize` / `connect` helpers are used
+     * to drive the OAuth flow; the host may omit it when wiring the OAuth
+     * exchange themselves.
+     */
+    codeVerifierStore?: FitbitCodeVerifierStore;
+    /**
+     * OAuth scopes to request when starting authorization. Defaults to the
+     * union needed for activity, sleep, heart-rate, and weight reads.
+     */
+    scopes?: readonly string[];
+    /**
+     * Override the Fitbit Web API base URL. Defaults to
+     * `https://api.fitbit.com/1`.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Override the Fitbit OAuth authorize endpoint. Defaults to
+     * `https://www.fitbit.com/oauth2/authorize`.
+     */
+    authorizeUrl?: string;
+    /**
+     * Override the Fitbit OAuth token endpoint. Defaults to
+     * `https://api.fitbit.com/oauth2/token`.
+     */
+    tokenUrl?: string;
+    /**
+     * Override the Fitbit OAuth token-revoke endpoint. Defaults to
+     * `https://api.fitbit.com/oauth2/revoke`.
+     */
+    revokeUrl?: string;
+    /**
+     * Request timeout in milliseconds. Defaults to `15_000`.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional override for the random-bytes generator used by PKCE / CSRF.
+     * Tests inject a deterministic generator.
+     */
+    randomBytes?: (size: number) => Uint8Array;
+    /**
+     * Optional clock override, primarily for tests. Defaults to `Date.now`.
+     */
+    now?: () => number;
+}
+/**
+ * Result of {@link FitbitProvider.startAuthorize} — the URL the host
+ * should redirect the user to plus the `state` value to round-trip.
+ */
+export interface FitbitAuthorizeStart {
+    /** Fitbit OAuth authorize URL. */
+    url: string;
+    /** Opaque `state` value the host MUST verify on the callback. */
+    state: string;
+}
+/**
+ * Public surface returned by {@link createProvider}. Extends the
+ * stack-neutral {@link import('@molecule/api-wearable').WearableProvider}
+ * with Fitbit-specific OAuth-flow helpers.
+ */
+export interface FitbitProvider extends WearableProviderType {
+    /**
+     * Builds the Fitbit authorize URL and persists a fresh PKCE verifier.
+     *
+     * @returns The URL to redirect to and the round-trip `state` value.
+     */
+    startAuthorize(): Promise<FitbitAuthorizeStart>;
+    /**
+     * Performs the authorization-code → token exchange with an explicit
+     * PKCE `code_verifier`. Use this when the host wires the OAuth flow
+     * itself (no `codeVerifierStore` configured).
+     *
+     * @param userId - Host-app user identifier.
+     * @param code - OAuth authorization `code` from the redirect callback.
+     * @param verifier - The PKCE `code_verifier` used to derive the challenge.
+     * @returns The freshly-minted user connection (already persisted).
+     */
+    connectWithVerifier(userId: string, code: string, verifier: string): Promise<WearableUserConnection>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,IAAI,sBAAsB,EACxC,wBAAwB,EACxB,gBAAgB,IAAI,oBAAoB,EACzC,MAAM,wBAAwB,CAAA;AAE/B,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,GACZ,MAAM,wBAAwB,CAAA;AAE/B,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,MAAM,CAAC;QACf;;WAEG;QACH,UAAiB,UAAU;YACzB;;;;;;eAMG;YACH,sBAAsB,CAAC,EAAE,MAAM,CAAA;YAE/B;;;;;;;eAOG;YACH,0BAA0B,CAAC,EAAE,MAAM,CAAA;SACpC;KACF;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,gBAAgB,EAAE,wBAAwB,CAAA;IAC1C;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,uBAAuB,CAAA;IAC3C;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU,CAAA;IAC1C;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,oBAAoB;IAC1D;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAC/C;;;;;;;;;OASG;IACH,mBAAmB,CACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,sBAAsB,CAAC,CAAA;CACnC"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Fitbit wearable bond types for molecule.dev.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@molecule/api-wearable-fitbit",
+  "version": "1.0.0",
+  "description": "Fitbit Web API bond for molecule.dev — daily activity, sleep, heart-rate, and weight ingestion via OAuth 2.0 PKCE",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "wearable",
+    "fitbit",
+    "fitness",
+    "sleep",
+    "heart-rate",
+    "oauth"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.0",
+    "@molecule/api-http": "^1.0.0",
+    "@molecule/api-secrets": "^1.0.0",
+    "@molecule/api-wearable": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.0",
+    "@molecule/api-http": "1.0.0",
+    "@molecule/api-wearable": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/wearable/fitbit"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/wearable/fitbit",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}