fitbit-endpoints

A simple JavaScript wrapper for the Fitbit API designed to work in both Node.js CommonJS and ES Module environments.

Installation

npm install fitbit-endpoints

Features

• Dual Module Support: Works with both CommonJS (require) and ES Modules (import)
• Comprehensive Endpoint Coverage: Supports various Fitbit API endpoints including:
  • Activity metrics (steps, calories, distance, elevation, floors)
  • Heart rate and heart rate variability (HRV)
  • Sleep data and sleep logs
  • Breathing rate
  • Blood oxygen (SpO2)
  • Temperature (core and skin)
  • ECG data
  • Active Zone Minutes (AZM)
  • And more health/fitness related measurements

Usage

ES Modules (ESM)

import {
  downloadSensors,
  generateSensorSettings,
  cronJobSensors,
  generateCronSensorSettings,
  defaultRangeDownloadSettings
} from 'fitbit-endpoints';

// Access available sensors
console.log('Download Sensors:', downloadSensors);
console.log('Cron Job Sensors:', cronJobSensors);

// Generate sensor settings
const sensor = downloadSensors[0];
const settings = generateSensorSettings(sensor);
console.log('Sensor Settings:', settings);

CommonJS (CJS)

const {
  downloadSensors,
  generateSensorSettings,
  cronJobSensors,
  generateCronSensorSettings,
  defaultRangeDownloadSettings
} = require('fitbit-endpoints');

// Access available sensors
console.log('Download Sensors:', downloadSensors);
console.log('Cron Job Sensors:', cronJobSensors);

// Generate sensor settings
const sensor = downloadSensors[0];
const settings = generateSensorSettings(sensor);
console.log('Sensor Settings:', settings);

API Reference

Exported Functions

• downloadSensors: Array of sensor configurations for downloading historical data
• generateSensorSettings(sensor): Generates settings object from a sensor configuration
• cronJobSensors: Array of sensor configurations for cron job scheduling
• generateCronSensorSettings(sensor): Generates cron settings from a sensor configuration
• defaultRangeDownloadSettings: Default configuration for date range downloads

Development

Project Structure

fitbit-endpoints/
├── src/
│   ├── index.cjs              # CommonJS entry point
│   ├── index.mjs              # ES Module entry point
│   ├── sensorsDownload.cjs    # Sensor download configurations (CJS)
│   ├── sensorsDownload.mjs    # Sensor download configurations (ESM)
│   ├── sensorsCronJob.cjs     # Cron job configurations (CJS)
│   ├── sensorsCronJob.mjs     # Cron job configurations (ESM)
│   ├── utils.cjs              # Utility functions (CJS)
│   ├── utils.mjs              # Utility functions (ESM)
│   ├── timezones.cjs          # Timezone data (CJS)
│   └── timezones.mjs          # Timezone data (ESM)
├── types/
│   └── index.d.ts             # TypeScript type definitions
├── fitbit-endpoints-demo/     # ESM demo project
├── fitbit-endpoints-demo-classic/ # CJS demo project
├── package.json
├── LICENSE
└── README.md

Running Tests

To test the module with ES Modules:

cd fitbit-endpoints-demo
npm install
npm test

To test the module with CommonJS:

cd fitbit-endpoints-demo-classic
npm install
npm test

Publishing to npm

Prerequisites

1. Create an npm account: Sign up at npmjs.com
2. Login to npm: Run npm login in your terminal and enter your credentials

Build and Publish Steps

1. Update version number in package.json:

   {
     "version": "1.0.8"
   }

2. Verify package contents:

   # Preview what will be published
   npm pack --dry-run

3. Test the package locally (optional but recommended):

   # Create a tarball
   npm pack
   
   # Install in a test project
   cd ../test-project
   npm install ../fitbit-endpoints/fitbit-endpoints-1.0.8.tgz

4. Publish to npm:

   # For public packages
   npm publish
   
   # For scoped packages (e.g., @cutsocial/fitbit-endpoints)
   npm publish --access public

5. Publish to GitHub Packages (optional):

   # Set GitHub token in environment
   export GITHUB_TOKEN=your_github_token
   
   # Use the GitHub npmrc configuration
   cp .npmrc.github .npmrc
   
   # Publish to GitHub Packages
   npm publish
   
   # Restore original npmrc
   git checkout .npmrc

Automated Publishing with GitHub Actions

The workflow automatically publishes to both npm and GitHub Packages when you push changes to package.json:

name: Publish to npm

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Version Management

Use semantic versioning (semver):

# Patch release (1.0.7 -> 1.0.8)
npm version patch

# Minor release (1.0.7 -> 1.1.0)
npm version minor

# Major release (1.0.7 -> 2.0.0)
npm version major

# Then publish
npm publish

Publishing Checklist

• [ ] All tests pass
• [ ] Version number updated in package.json
• [ ] README.md is up to date
• [ ] CHANGELOG.md is updated (if applicable)
• [ ] All files are committed to git
• [ ] Git tags are created for the version
• [ ] No sensitive data in the package
• [ ] .npmignore or files field in package.json is configured correctly

License

This project is licensed under the MIT License - see the LICENSE file for details.

Repository

https://github.com/cutsocial/fitbit-endpoints

Issues

Report bugs and feature requests at: https://github.com/cutsocial/fitbit-endpoints/issues

Author

[email protected]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.