Skip to content

Latest commit

 

History

History
152 lines (108 loc) · 5.97 KB

README.md

File metadata and controls

152 lines (108 loc) · 5.97 KB

OURA_API

Interact with v2 of the Oura API using Personal Access Tokens, OAuth2, or the Sandbox environment.

Available as:

  • ESM module: JSR
  • CommonJS module: NPM

⚡️ Quickstart

Installation

# Deno
deno add @pinta365/oura-api

# Bun
bunx jsr add @pinta365/oura-api

# Node.js
npx jsr add @pinta365/oura-api

# NPM (CommonJS)
npm install oura_api --save

Basic Usage (ESM)

import { Oura } from "@pinta365/oura-api";

const accessToken = "YOUR_PERSONAL_ACCESS_TOKEN";
const oura = new Oura(accessToken);

const personalInfo = await oura.getPersonalInfo();
console.log(personalInfo);

Basic Usage (CommonJS)

const { Oura } = require("oura_api");
// ... (same as above)

See the examples folder for more detailed implementations.

🧪 Sandbox Environment (Testing)

The Oura API's sandbox environment (Docs) is perfect for development. It provides sample data so you don't need a real Oura account to test your application.

const ouraSandboxClient = new Oura({ useSandbox: true });
// ...Make API calls with `ouraSandboxClient`

🔑 OAuth2 Support

Our library simplifies OAuth2 authentication with these functions:

  • generateAuthUrl(scopes: string[], state?: string): string

    • Generates the authorization URL for the user.
  • async exchangeCodeForToken(code: string): Promise<OAuth2TokenResponse>

    • Exchanges the received authorization code for access and refresh tokens.
  • async refreshAccessToken(suppliedRefreshToken: string): Promise<OAuth2TokenResponse>

    • Refreshes an expired access token.
  • async revokeAccessToken(accessToken: string): Promise<boolean>

    • Revokes the specified access token.

Example Usage (Simplified) See the examples folder for a basic implementation using Hono.

import { OuraOAuth } from "@pinta365/oura-api";

const oura = new OuraOAuth({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    redirectUri: "http://localhost:8000/callback",
});

// 1. Generate the authorization URL
const authUrl = oura.generateAuthUrl(["personal"]);

// 2. Redirect the user to `authUrl`
// ... (Implementation in your web application)

// 3. In your callback route, exchange the code for tokens
app.get("/callback", async (c) => {
    const code = c.req.query("code");
    const tokens = await oura.exchangeCodeForToken(code);

    // ... Store tokens securely and use the access_token for API calls
});

📑 Documentation

Included data scopes for v2 of the API.

Endpoint/Scope Status
Oura Base docs
Daily Activity Implemented
Daily Cardiovascular Age Implemented
Daily Readiness Implemented
Daily Resilience Implemented
Daily Sleep Implemented
Daily Spo2 Implemented
Daily Stress Implemented
Enhanced Tag Implemented
Heart Rate Implemented
Personal Info Implemented
Rest Mode Period Implemented
Ring Configuration Implemented
Session Implemented
Sleep Implemented
Sleep Time Implemented
Tag DEPRECATED
Vo2 Max Implemented
Workout Implemented
Webhook Subscription docs
List subscription Implemented
Create subscription Implemented
Update subscription Implemented
Delete subscription Implemented
Renew subscription Implemented

Additional info concerning the webhook API

Webhooks enable near real-time Oura data updates and are recommended for getting the latest information. The subscription workflow is implemented in this library – see the Webhook docs for details.

⚠️ I have not been able to fully verify this yet but the subscription workflow has been implemented.

🐞 Issues

Please report any issues or questions on the GitHub repository.

📄 License

MIT License - see the LICENSE file.