Dexcom Share Client (TypeScript)

A complete TypeScript port of pydexcom - A simple API to interact with Dexcom Share service.

Features

✅ Complete pydexcom port with all features:

• Multi-region support (US, Outside US, Japan)
• Comprehensive error handling
• Session management with automatic retry
• Full glucose reading data (mg/dL, mmol/L, trends, arrows)
• Input validation
• TypeScript types

Installation

npm install dexcom-share-client

Quick Start

1. Enable Dexcom Share

Download the Dexcom G7 / G6 / G5 / G4 mobile app and enable the Share service.

Note: The Dexcom Share service requires setup of at least one follower, but this library uses your (or the dependent's) credentials, not the follower's.

2. Basic Usage

import DexcomShare, { Region } from "dexcom-share-client";

// Create client (US region by default)
const dexcom = new DexcomShare({
  username: "your_username",  // or email or phone number
  password: "your_password"
});

// Get current glucose reading (within last 10 minutes)
const current = await dexcom.getCurrentGlucoseReading();
if (current) {
  console.log(current.value);              // 85
  console.log(current.mmolL);              // 4.7
  console.log(current.trend);              // 4
  console.log(current.trendDirection);     // "Flat"
  console.log(current.trendDescription);   // "steady"
  console.log(current.trendArrow);         // "→"
  console.log(current.datetime);           // Date object
}

// Get latest reading (within last 24 hours)
const latest = await dexcom.getLatestGlucoseReading();

// Get multiple readings
const readings = await dexcom.getGlucoseReadings(
  60,   // minutes (1-1440)
  12    // max count (1-288)
);

Advanced Usage

Region Support

import DexcomShare, { Region } from "dexcom-share-client";

// US (default)
const dexcomUS = new DexcomShare({
  username: "username",
  password: "password",
  region: Region.US
});

// Outside US
const dexcomOUS = new DexcomShare({
  username: "username",
  password: "password",
  region: Region.OUS
});

// Japan
const dexcomJP = new DexcomShare({
  username: "username",
  password: "password",
  region: Region.JP
});

Username Formats

// Username
const dexcom1 = new DexcomShare({
  username: "myusername",
  password: "password"
});

// Email
const dexcom2 = new DexcomShare({
  username: "[email protected]",
  password: "password"
});

// Phone number
const dexcom3 = new DexcomShare({
  username: "+11234567890",
  password: "password"
});

// Account ID (advanced - if you already have the UUID)
const dexcom4 = new DexcomShare({
  accountId: "12345678-90ab-cdef-1234-567890abcdef",
  password: "password"
});

Error Handling

import DexcomShare, {
  AccountError,
  SessionError,
  ArgumentError,
  ServerError
} from "dexcom-share-client";

try {
  const dexcom = new DexcomShare({
    username: "username",
    password: "password"
  });
  
  const reading = await dexcom.getCurrentGlucoseReading();
  console.log(reading);
} catch (error) {
  if (error instanceof AccountError) {
    console.error("Authentication failed:", error.message);
  } else if (error instanceof SessionError) {
    console.error("Session error:", error.message);
    // Session errors are automatically retried once
  } else if (error instanceof ArgumentError) {
    console.error("Invalid argument:", error.message);
  } else if (error instanceof ServerError) {
    console.error("Server error:", error.message);
  }
}

Glucose Reading Properties

const reading = await dexcom.getCurrentGlucoseReading();

if (reading) {
  // Glucose values
  reading.value;              // number - glucose in mg/dL
  reading.mgDl;               // number - same as value
  reading.mmolL;              // number - glucose in mmol/L (converted)
  
  // Trend information
  reading.trend;              // number - trend value (0-9)
  reading.trendDirection;     // string - "Flat", "SingleUp", "DoubleDown", etc.
  reading.trendDescription;   // string - "steady", "rising", "falling quickly", etc.
  reading.trendArrow;         // string - "→", "↑", "↓↓", etc.
  
  // Timestamp
  reading.datetime;           // Date - when reading was taken
  
  // Raw data
  reading.json;               // RawGlucoseReading - original API response
  
  // String representation
  reading.toString();         // string - glucose value as string
}

Trend Values

| Value | Direction | Description | Arrow | |-------|-----------|-------------|-------| | 0 | None | - | - | | 1 | DoubleUp | rising quickly | ↑↑ | | 2 | SingleUp | rising | ↑ | | 3 | FortyFiveUp | rising slightly | ↗ | | 4 | Flat | steady | → | | 5 | FortyFiveDown | falling slightly | ↘ | | 6 | SingleDown | falling | ↓ | | 7 | DoubleDown | falling quickly | ↓↓ | | 8 | NotComputable | unable to determine trend | ? | | 9 | RateOutOfRange | trend unavailable | - |

API Reference

DexcomShare Class

Constructor

new DexcomShare(options: DexcomOptions)

Options:

• password (required): Password for Dexcom Share account
• username (optional): Username, email, or phone number
• accountId (optional): Account UUID (advanced)
• region (optional): Region.US (default), Region.OUS, or Region.JP

Note: Must provide either username or accountId, but not both.

Methods

getGlucoseReadings(minutes?, maxCount?)

Get glucose readings within specified time window.

Parameters:

• minutes (optional): Number of minutes (1-1440, default: 1440)
• maxCount (optional): Maximum readings to return (1-288, default: 288)

Returns: Promise<GlucoseReading[]>

getLatestGlucoseReading()

Get the most recent glucose reading within the last 24 hours.

Returns: Promise<GlucoseReading | null>

getCurrentGlucoseReading()

Get the current glucose reading within the last 10 minutes.

Returns: Promise<GlucoseReading | null>

Properties

• username: string | null - The username (read-only)
• accountId: string | null - The account ID (read-only)
• region: Region - The region (read-only)

GlucoseReading Class

Properties

• value: number - Glucose in mg/dL
• mgDl: number - Glucose in mg/dL (alias)
• mmolL: number - Glucose in mmol/L
• trend: number - Trend value (0-9)
• trendDirection: string - Trend direction name
• trendDescription: string - Human-readable trend
• trendArrow: string - Unicode arrow
• datetime: Date - Reading timestamp
• json: RawGlucoseReading - Raw API response

Methods

• toString(): string - Returns glucose value as string

Error Types

AccountError

Authentication and account-related errors:

• FAILED_AUTHENTICATION - Invalid credentials
• MAX_ATTEMPTS - Too many login attempts

SessionError

Session-related errors (automatically retried):

• NOT_FOUND - Session ID not found
• INVALID - Session expired or timed out

ArgumentError

Invalid argument errors:

• MINUTES_INVALID - Minutes out of range
• MAX_COUNT_INVALID - Max count out of range
• USERNAME_INVALID - Invalid username
• PASSWORD_INVALID - Invalid password
• ACCOUNT_ID_INVALID - Invalid account ID format
• SESSION_ID_INVALID - Invalid session ID
• REGION_INVALID - Invalid region
• USER_ID_REQUIRED - Must provide username or accountId
• USER_ID_MULTIPLE - Cannot provide both username and accountId
• GLUCOSE_READING_INVALID - Malformed glucose reading data

ServerError

Server and response errors:

• INVALID_JSON - Malformed JSON response
• UNKNOWN_CODE - Unknown error code from API
• UNEXPECTED - Unexpected server response

Constants

import {
  Region,
  MAX_MINUTES,              // 1440 (24 hours)
  MAX_MAX_COUNT,            // 288 (one reading per 5 minutes)
  MMOL_L_CONVERSION_FACTOR, // 0.0555
  DEXCOM_TREND_DIRECTIONS,  // Trend name to number mapping
  TREND_DESCRIPTIONS,       // Trend descriptions array
  TREND_ARROWS              // Trend arrows array
} from "dexcom-share-client";

Build

npm run build

Differences from pydexcom

This is a complete port of pydexcom with the following adaptations for TypeScript/JavaScript:

1. Naming conventions: camelCase instead of snake_case

   • get_current_glucose_reading() → getCurrentGlucoseReading()
   • mmol_l → mmolL
   • trend_direction → trendDirection

2. Constructor: Uses options object instead of keyword arguments

   // TypeScript
   new DexcomShare({ username: "user", password: "pass", region: Region.US })
      
   // Python
   Dexcom(username="user", password="pass", region="us")

3. Async/await: All API methods return Promises

4. TypeScript types: Full type definitions included

5. ES modules: Uses ES module syntax

All functionality from pydexcom is preserved!

License

MIT

Credits

This is a TypeScript port of pydexcom by Gage Benne.

Disclaimer

This project is not affiliated with or endorsed by Dexcom, Inc. Use at your own risk.