From 96faa383d111f14bc74a9a01f8cd4ad8ba242dc1 Mon Sep 17 00:00:00 2001 From: Pinta365 Date: Sun, 3 Sep 2023 20:57:39 +0200 Subject: [PATCH] documentation --- README.md | 5 +- src/Oura.ts | 217 ++++++++++++++++++++++++------------------- src/Webhook.ts | 109 ++++++++++++---------- src/types/oura.ts | 7 ++ src/types/webhook.ts | 8 ++ 5 files changed, 200 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index 7811628..8d9ef9e 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,7 @@ Read the [Webhook docs](https://cloud.ouraring.com/v2/docs#tag/Webhook-Subscript Issues or questions concerning the library can be raised at the [github repository](https://github.com/Pinta365/oura_api/issues) page. -### License +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. -MIT diff --git a/src/Oura.ts b/src/Oura.ts index a323643..17a9d8b 100644 --- a/src/Oura.ts +++ b/src/Oura.ts @@ -1,8 +1,7 @@ /** - * oura_api - * - * @file Class containing all the methods to access the Oura API with a access token. + * Class containing all the methods to access the Oura API with an access token. * + * @class Oura * @author Pinta * @license MIT */ @@ -40,8 +39,11 @@ class Oura { #baseUrlv2: string; /** - * Takes the accessToken as a string parameter and stores it for use with the requests made by this class. - * @param accessToken - A personal access token generated at the Oura Cloud website. + * Creates a new Oura API client. + * + * @constructor + * @param {string} accessToken - A personal access token generated at the Oura Cloud website. + * @throws {Error} Throws an error if the access token is missing. */ constructor(accessToken: string) { if (!accessToken) { @@ -52,11 +54,13 @@ class Oura { } /** - * Private class method for doing the fetch requests to the API endpoints. Throws an error - * if the response is not ok. - * @param url - API endpoint url. - * @param qs - optional parameter for including a querystring parameter to the endpoint. - * @returns A JSON parsed fetch response. + * Private method to make GET requests to the API endpoints. + * + * @private + * @param {string} url - The API endpoint URL. + * @param {Object} [qs] - Optional querystring parameters. + * @returns {Promise} A JSON parsed fetch response. + * @throws {Error} Throws an error if the response status is not OK. */ #get = async (url: string, qs?: Record) => { const params = new URLSearchParams(qs); @@ -76,10 +80,11 @@ class Oura { }; /** - * Retrieves daily activity documents for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A DailyActivityDocuments typed object. + * Retrieves daily activity documents for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A DailyActivityDocuments typed object. */ getDailyActivityDocuments( startDate: DateFormat, @@ -90,19 +95,21 @@ class Oura { } /** - * Retrieves a single activity document. - * @param documentId - The document id in string format. - * @returns A DailyActivity typed object. + * Retrieves a single activity document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A DailyActivity typed object. */ getDailyActivity(documentId: string): Promise { return this.#get("daily_activity/" + documentId) as Promise; } /** - * Retrieves daily readiness documents for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A DailyReadinessDocuments typed object. + * Retrieves daily readiness documents for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A DailyReadinessDocuments typed object. */ getDailyReadinessDocuments( startDate: DateFormat, @@ -113,39 +120,43 @@ class Oura { } /** - * Retrieves a single readiness document. - * @param documentId - The document id in string format. - * @returns A DailyReadiness typed object. + * Retrieves a single readiness document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A DailyReadiness typed object. */ getDailyReadiness(documentId: string): Promise { return this.#get("daily_readiness/" + documentId) as Promise; } /** - * Retrieves daily sleep documents for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A DailySleepDocuments typed object. + * Retrieves daily sleep documents for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A DailySleepDocuments typed object. */ getDailySleepDocuments(startDate: DateFormat, endDate: DateFormat): Promise { const params = { start_date: startDate, end_date: endDate }; return this.#get("daily_sleep", params) as Promise; } - + /** - * Retrieves a single daily sleep document. - * @param documentId - The document id in string format. - * @returns A DailySleep typed object. + * Retrieves a single daily sleep document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A DailySleep typed object. */ getDailySleep(documentId: string): Promise { return this.#get("daily_sleep/" + documentId) as Promise; } /** - * Retrieves daily spO2 (blood oxygenation) average for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A DailySpo2Documents typed object. + * Retrieves daily spO2 (blood oxygenation) averages for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A DailySpo2Documents typed object. */ getDailySpo2Documents(startDate: DateFormat, endDate: DateFormat): Promise { const params = { start_date: startDate, end_date: endDate }; @@ -153,20 +164,21 @@ class Oura { } /** - * Retrieves a single daily spO2 (blood oxygenation) average document. - * @param documentId - The document id in string format. - * @returns A DailySpo2 typed object. + * Retrieves a single daily spO2 (blood oxygenation) average document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A DailySpo2 typed object. */ getDailySpo2(documentId: string): Promise { return this.#get("daily_spo2/" + documentId) as Promise; } /** - * Retrieves heartrate data for a startDateTime - endDateTime period. Includes day time - * and night time heartrate in 5 minute increments. - * @param startDateTime - Start date and time of the period in string format. - * @param endDateTime - End date and time of the period in string format. - * @returns A Heartrate typed object. + * Retrieves heart rate data for a specified date and time period. + * + * @param {string} startDateTime - Start date and time of the period in string format (e.g., 'YYYY-MM-DDTHH:mm:ss'). + * @param {string} endDateTime - End date and time of the period in string format (e.g., 'YYYY-MM-DDTHH:mm:ss'). + * @returns {Promise} A Heartrate typed object. */ getHeartrate(startDateTime: string, endDateTime: string): Promise { const params = { start_datetime: startDateTime, end_datetime: endDateTime }; @@ -174,18 +186,20 @@ class Oura { } /** - * Retrieves the personal information about the user. - * @returns A PersonalInfo typed object. + * Retrieves personal information about the user. + * + * @returns {Promise} A PersonalInfo typed object. */ getPersonalInfo(): Promise { return this.#get("personal_info") as Promise; } /** - * Retrieves rest mode periods for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A RestModePeriodDocuments typed object. + * Retrieves rest mode periods for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A RestModePeriodDocuments typed object. */ getRestModePeriodDocuments( startDate: DateFormat, @@ -196,19 +210,21 @@ class Oura { } /** - * Retrieves a single rest mode period document. - * @param documentId - The document id in string format. - * @returns A RestModePeriod typed object. + * Retrieves a single rest mode period document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A RestModePeriod typed object. */ getRestModePeriod(documentId: string): Promise { return this.#get("rest_mode_period/" + documentId) as Promise; } /** - * Retrieves ring configuration information for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A RingConfigurationDocuments typed object. + * Retrieves ring configuration information for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A RingConfigurationDocuments typed object. */ getRingConfigurationDocuments( startDate: DateFormat, @@ -219,19 +235,21 @@ class Oura { } /** - * Retrieves a single ring configuration document. - * @param documentId - The document id in string format. - * @returns A RingConfiguration typed object. + * Retrieves a single ring configuration document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A RingConfiguration typed object. */ getRingConfiguration(documentId: string): Promise { return this.#get("ring_configuration/" + documentId) as Promise; } /** - * Retrieves daily session documents for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A DailySessionDocuments typed object. + * Retrieves daily session documents for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A DailySessionDocuments typed object. */ getDailySessionDocuments( startDate: DateFormat, @@ -242,19 +260,21 @@ class Oura { } /** - * Retrieves a single daily session document. - * @param documentId - The document id in string format. - * @returns A DailySession typed object. + * Retrieves a single daily session document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A DailySession typed object. */ getDailySession(documentId: string): Promise { return this.#get("session/" + documentId) as Promise; } /** - * Retrieves sleep documents for a startDate - endDate period. Can be multiple sleep periods per day. - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A SleepDocuments typed object. + * Retrieves sleep documents for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A SleepDocuments typed object. */ getSleepDocuments(startDate: DateFormat, endDate: DateFormat): Promise { const params = { start_date: startDate, end_date: endDate }; @@ -262,19 +282,21 @@ class Oura { } /** - * Retrieves a single sleep session document. - * @param documentId - The document id in string format. - * @returns A Sleep typed object. + * Retrieves a single sleep session document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A Sleep typed object. */ getSleep(documentId: string): Promise { return this.#get("sleep/" + documentId) as Promise; } /** - * Retrieves recommendated bedtime window for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A SleepTimeDocuments typed object. + * Retrieves recommended bedtime windows for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A SleepTimeDocuments typed object. */ getSleepTimeDocuments(startDate: DateFormat, endDate: DateFormat): Promise { const params = { start_date: startDate, end_date: endDate }; @@ -282,19 +304,21 @@ class Oura { } /** - * Retrieves a single recommendated bedtime window document. - * @param documentId - The document id in string format. - * @returns A SleepTime typed object. + * Retrieves a single recommended bedtime window document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A SleepTime typed object. */ getSleepTime(documentId: string): Promise { return this.#get("sleep_time/" + documentId) as Promise; } /** - * Retrieves daily tags for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A TagDocuments typed object. + * Retrieves daily tags for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A TagDocuments typed object. */ getTagDocuments(startDate: DateFormat, endDate: DateFormat): Promise { const params = { start_date: startDate, end_date: endDate }; @@ -302,19 +326,21 @@ class Oura { } /** - * Retrieves a single tag document. - * @param documentId - The document id in string format. - * @returns A Tag typed object. + * Retrieves a single tag document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A Tag typed object. */ getTag(documentId: string): Promise { return this.#get("tag/" + documentId) as Promise; } /** - * Retrieves workout documents for a startDate - endDate period - * @param startDate - Start date of the period in string format. - * @param endDate - End date of the period in string format. - * @returns A WorkoutDocuments typed object. + * Retrieves workout documents for a specified date range. + * + * @param {string} startDate - Start date of the period in string format (e.g., 'YYYY-MM-DD'). + * @param {string} endDate - End date of the period in string format (e.g., 'YYYY-MM-DD'). + * @returns {Promise} A WorkoutDocuments typed object. */ getWorkoutDocuments(startDate: DateFormat, endDate: DateFormat): Promise { const params = { start_date: startDate, end_date: endDate }; @@ -322,9 +348,10 @@ class Oura { } /** - * Retrieves a single workout document. - * @param documentId - The document id in string format. - * @returns A Workout typed object. + * Retrieves a single workout document by its ID. + * + * @param {string} documentId - The document ID in string format. + * @returns {Promise} A Workout typed object. */ getWorkout(documentId: string): Promise { return this.#get("workout/" + documentId) as Promise; diff --git a/src/Webhook.ts b/src/Webhook.ts index c236b6b..9f78f8b 100644 --- a/src/Webhook.ts +++ b/src/Webhook.ts @@ -1,12 +1,11 @@ /** - * oura_api - * - * @file Class containing all the methods to access the Oura Webhook Subscription API with a client id and client secret. + * Class containing all the methods to access the Oura Webhook Subscription API with a client id and client secret. * + * @class Webhook * @author Pinta * @license MIT */ -import * as types from "./types/webhook.ts"; +import { DataType, DeletedSubscription, EventType, Subscription } from "./types/webhook.ts"; class Webhook { #clientId: string; @@ -14,9 +13,12 @@ class Webhook { #baseUrlv2: string; /** - * Takes the cliend id and secret as string parameters and stores it for use with the requests made by this class. - * @param clientId - A client id generated at the Oura Cloud website. - * @param clientSecret - A client secret generated at the Oura Cloud website. + * Creates a new Webhook API client. + * + * @constructor + * @param {string} clientId - A client id generated at the Oura Cloud website. + * @param {string} clientSecret - A client secret generated at the Oura Cloud website. + * @throws {Error} Throws an error if the client id or client secret is missing. */ constructor(clientId: string, clientSecret: string) { if (!clientId) { @@ -32,12 +34,15 @@ class Webhook { } /** - * Private class method for doing the fetch requests to the API endpoints. Throws an error - * if the response is not ok. - * @param method - Fetch method - * @param url - API endpoint url. - * @param body - optional parameter for supplying a POST/PUT body. - * @returns A JSON or Text parsed fetch response. + * Private class method for making fetch requests to the API endpoints. Throws an error + * if the response is not OK. + * + * @private + * @param {string} method - Fetch method (e.g., GET, POST, PUT, DELETE). + * @param {string} url - API endpoint URL. + * @param {Object} [body] - Optional parameter for supplying a POST/PUT body. + * @returns {Promise} A JSON or Text parsed fetch response. + * @throws {Error} Throws an error if the request encounters a problem (e.g., non-OK response status). */ #request = async (method: string, url: string, body?: Record) => { let options = {}; @@ -78,61 +83,65 @@ class Webhook { /** * Retrieves a list of current active webhook subscriptions. - * @returns an array of Subscription typed objects. + * + * @returns {Promise} An array of Subscription typed objects. */ - listSubscriptions(): Promise { - return this.#request("GET", "subscription") as Promise; + listSubscriptions(): Promise { + return this.#request("GET", "subscription") as Promise; } /** * Retrieves a specific webhook subscription by id. - * @param id - Subscription id in string format. - * @returns A Subscription typed object. + * + * @param {string} id - Subscription id in string format. + * @returns {Promise} A Subscription typed object. */ - getSubscription(id: string): Promise { - return this.#request("GET", "subscription/" + id) as Promise; + getSubscription(id: string): Promise { + return this.#request("GET", "subscription/" + id) as Promise; } /** * Creates a new webhook subscription. See setup documentation on the Oura Developer website - * for detailed description of the creation workflow. - * @param callbackUrl - Your callback url used buy Oura to post subscriptions events to. - * @param verificationToken - Your verification token, use to verify Ouras calls to your api. - * @param eventType - One of the EventTypes. - * @param dataType - One of the DataTypes. - * @returns A Subscription typed object of the created sub. + * for a detailed description of the creation workflow. + * + * @param {string} callbackUrl - Your callback URL used by Oura to post subscription events to. + * @param {string} verificationToken - Your verification token used to verify Oura's calls to your API. + * @param {EventType} eventType - One of the EventTypes. + * @param {DataType} dataType - One of the DataTypes. + * @returns {Promise} A Subscription typed object of the created subscription. */ createSubscription( callbackUrl: string, verificationToken: string, - eventType: types.EventType, - dataType: types.DataType, - ): Promise { + eventType: EventType, + dataType: DataType, + ): Promise { const data = { callback_url: callbackUrl, verification_token: verificationToken, event_type: eventType, data_type: dataType, }; - return this.#request("POST", "subscription", data) as Promise; + return this.#request("POST", "subscription", data) as Promise; } /** * Updates a webhook subscription. - * @param id - Subscription id in string format. - * @param verificationToken - Your verification token, use to verify Ouras calls to your api. - * @param callbackUrl - Callback url used buy Oura to post subscriptions to. - * @param eventType - One of the EventTypes. - * @param dataType - One of the DataTypes. - * @returns A Subscription typed object of the updated sub. + * + * @param {string} id - Subscription id in string format. + * @param {string} verificationToken - Your verification token used to verify Oura's calls to your API. + * @param {string} [callbackUrl] - Callback URL used by Oura to post subscriptions to. + * @param {EventType} [eventType] - One of the EventTypes. + * @param {DataType} [dataType] - One of the DataTypes. + * @returns {Promise} A Subscription typed object of the updated subscription. */ updateSubscription( id: string, verificationToken: string, callbackUrl?: string, - eventType?: types.EventType, - dataType?: types.DataType, - ): Promise { + eventType?: EventType, + dataType?: DataType, + ): Promise { const data = { callback_url: callbackUrl, verification_token: verificationToken, @@ -150,25 +159,27 @@ class Webhook { delete data.data_type; } - return this.#request("PUT", "subscription/" + id, data) as Promise; + return this.#request("PUT", "subscription/" + id, data) as Promise; } /** * Deletes a webhook subscription. - * @param id - Subscription id in string format. - * @returns A DeletedSubscription typed object. + * + * @param {string} id - Subscription id in string format. + * @returns {Promise} A DeletedSubscription typed object. */ - deleteSubscription(id: string): Promise { - return this.#request("DELETE", "subscription/" + id) as Promise; + deleteSubscription(id: string): Promise { + return this.#request("DELETE", "subscription/" + id) as Promise; } /** - * Renew the expiration time of a webhook subscription. - * @param id -Subscription id in string format. - * @returns A Subscription typed object of the renewed sub. + * Renews the expiration time of a webhook subscription. + * + * @param {string} id - Subscription id in string format. + * @returns {Promise} A Subscription typed object of the renewed subscription. */ - renewSubscription(id: string): Promise { - return this.#request("PUT", "subscription/renew/" + id) as Promise; + renewSubscription(id: string): Promise { + return this.#request("PUT", "subscription/renew/" + id) as Promise; } } diff --git a/src/types/oura.ts b/src/types/oura.ts index 1bb6def..e9f1fd1 100644 --- a/src/types/oura.ts +++ b/src/types/oura.ts @@ -1,3 +1,10 @@ +/** + * oura_api + * + * @file Contains type definitions and interfaces for the Oura API responses and data structures. + * @author Pinta + * @license MIT + */ type oneToNine = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9; type zeroToNine = 0 | oneToNine; type YYYY = `19${zeroToNine}${zeroToNine}` | `20${zeroToNine}${zeroToNine}`; diff --git a/src/types/webhook.ts b/src/types/webhook.ts index bb021d4..b64786f 100644 --- a/src/types/webhook.ts +++ b/src/types/webhook.ts @@ -1,3 +1,11 @@ +/** + * oura_api + * + * @file Contains type definitions and interfaces for the Oura Webhook Subscription API. + * Defines event types, data types, and subscription related interfaces. + * @author Pinta + * @license MIT + */ export type EventType = | "create" | "update"