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

``bash
npm install dexcom-share-client
`

Quick Start

$3

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.

$3

`typescript
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

$3

`typescript
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
});
`

$3

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

// Email
const dexcom2 = new DexcomShare({
username: "user@email.com",
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"
});
`

$3

`typescript
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);
}
}
`

$3

`typescript
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
}
`

$3

| 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

$3

#### Constructor

`typescript
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

##### getLatestGlucoseReading()
Get the most recent glucose reading within the last 24 hours.

Returns: Promise

##### getCurrentGlucoseReading()
Get the current glucose reading within the last 10 minutes.

Returns: Promise

#### Properties

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

$3

#### 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

$3


Authentication and account-related errors:
- FAILED_AUTHENTICATION - Invalid credentials
- MAX_ATTEMPTS - Too many login attempts

$3

Session-related errors (automatically retried):
- NOT_FOUND - Session ID not found
- INVALID - Session expired or timed out

$3

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

$3

Server and response errors:
- INVALID_JSON - Malformed JSON response
- UNKNOWN_CODE - Unknown error code from API
- UNEXPECTED - Unexpected server response

Constants

`typescript
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

`bash
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
// 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.