Withings (#304)

Co-authored-by: pilcrowOnPaper <[email protected]>

Author: benmccann

docs/malta.config.json

@@ -76,6 +76,7 @@
 				["Twitch", "/providers/twitch"],
 				["Twitter", "/providers/twitter"],
 				["VK", "/providers/vk"],
+				["Withings", "/providers/withings"],
 				["WorkOS", "/providers/workos"],
 				["Yahoo", "/providers/yahoo"],
 				["Yandex", "/providers/yandex"],

docs/pages/providers/withings.md

@@ -0,0 +1,76 @@
+---
+title: "Withings"
+---
+
+# Withings
+
+OAuth 2.0 provider for Withings.
+
+Also see the [OAuth 2.0](/guides/oauth2) guide.
+
+## Initialization
+
+```ts
+import * as arctic from "arctic";
+
+const withings = new arctic.Withings(clientId, clientSecret, redirectURI);
+```
+
+## Create authorization URL
+
+```ts
+import * as arctic from "arctic";
+
+const state = arctic.generateState();
+const scopes = ["user.info", "user.metrics", "user.activity"];
+const url = withings.createAuthorizationURL(state, scopes);
+```
+
+## Validate authorization code
+
+`validateAuthorizationCode()` will either return an [`OAuth2Tokens`](/reference/main/OAuth2Tokens), or throw one of [`OAuth2RequestError`](/reference/main/OAuth2RequestError), [`ArcticFetchError`](/reference/main/ArcticFetchError), [`UnexpectedResponseError`](/reference/main/UnexpectedResponseError), or [`UnexpectedErrorResponseBodyError`](/reference/main/UnexpectedErrorResponseBodyError). Withings will return an access token with an expiration.
+
+Withings deviates from the RFC and the value of `OAuth2RequestError.code` will not be a registered OAuth 2.0 error code.
+
+```ts
+import * as arctic from "arctic";
+
+try {
+	const tokens = await withings.validateAuthorizationCode(code);
+	const accessToken = tokens.accessToken();
+	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
+} catch (e) {
+	if (e instanceof arctic.OAuth2RequestError) {
+		// Invalid authorization code, credentials, or redirect URI
+		const responseBody = e.code;
+		// ...
+	}
+	if (e instanceof arctic.ArcticFetchError) {
+		// Failed to call `fetch()`
+		const cause = e.cause;
+		// ...
+	}
+	// Parse error
+}
+```
+
+## Get measures
+
+Use the `/measure` endpoint. See [the API docs](https://developer.withings.com/api-reference/#tag/measure).
+
+```ts
+const response = await fetch("https://wbsapi.withings.net/measure", {
+	method: "POST",
+	headers: {
+		Authorization: `Bearer ${tokens.accessToken()}`,
+		"Content-Type": "application/json"
+	},
+	body: JSON.stringify({
+		action: "getmeas",
+		meastypes: "1,5,6,8,76",
+		category: 1,
+		lastupdate: 1746082800
+	})
+});
+const measures = await response.json();
+```

src/index.ts

@@ -56,6 +56,7 @@ export { Tumblr } from "./providers/tumblr.js";
 export { Twitch } from "./providers/twitch.js";
 export { Twitter } from "./providers/twitter.js";
 export { VK } from "./providers/vk.js";
+export { Withings } from "./providers/withings.js";
 export { WorkOS } from "./providers/workos.js";
 export { Yahoo } from "./providers/yahoo.js";
 export { Yandex } from "./providers/yandex.js";

src/providers/withings.ts

@@ -0,0 +1,97 @@
+import {
+	ArcticFetchError,
+	createOAuth2Request,
+	createOAuth2RequestError,
+	UnexpectedErrorResponseBodyError,
+	UnexpectedResponseError
+} from "../request.js";
+import { OAuth2Tokens } from "../oauth2.js";
+
+const authorizationEndpoint = "https://account.withings.com/oauth2_user/authorize2";
+const tokenEndpoint = "https://wbsapi.withings.net/v2/oauth2";
+
+export class Withings {
+	private clientId: string;
+	private clientSecret: string;
+	private redirectURI: string;
+
+	constructor(clientId: string, clientSecret: string, redirectURI: string) {
+		this.clientId = clientId;
+		this.clientSecret = clientSecret;
+		this.redirectURI = redirectURI;
+	}
+
+	public createAuthorizationURL(state: string, scopes: string[]): URL {
+		const url = new URL(authorizationEndpoint);
+		url.searchParams.set("response_type", "code");
+		url.searchParams.set("client_id", this.clientId);
+		url.searchParams.set("state", state);
+		// Withings deviates from the RFC and uses a comma-delimitated string instead of spaces.
+		if (scopes.length > 0) {
+			url.searchParams.set("scope", scopes.join(","));
+		}
+		url.searchParams.set("redirect_uri", this.redirectURI);
+		return url;
+	}
+
+	public async validateAuthorizationCode(code: string): Promise<OAuth2Tokens> {
+		const body = new URLSearchParams();
+		// Withings requires an `action` parameter.
+		body.set("action", "requesttoken");
+		body.set("grant_type", "authorization_code");
+		body.set("code", code);
+		body.set("redirect_uri", this.redirectURI);
+		body.set("client_id", this.clientId);
+		body.set("client_secret", this.clientSecret);
+		const request = createOAuth2Request(tokenEndpoint, body);
+		const tokens = await sendTokenRequest(request);
+		return tokens;
+	}
+}
+
+async function sendTokenRequest(request: Request): Promise<OAuth2Tokens> {
+	let response: Response;
+	try {
+		response = await fetch(request);
+	} catch (e) {
+		throw new ArcticFetchError(e);
+	}
+
+	// Withings returns a 200 even for error responses.
+	if (response.status !== 200) {
+		if (response.body !== null) {
+			await response.body.cancel();
+		}
+		throw new UnexpectedResponseError(response.status);
+	}
+
+	let data: unknown;
+	try {
+		data = await response.json();
+	} catch {
+		throw new UnexpectedResponseError(response.status);
+	}
+	if (typeof data !== "object" || data === null) {
+		throw new UnexpectedErrorResponseBodyError(response.status, data);
+	}
+
+	// Withings returns an `error` field but the value deviates from the RFC.
+	// Probably better to throw `UnexpectedErrorResponseBodyError`
+	// but we're keeping `OAuth2RequestError` for now to be consistent with the other providers.
+	if ("error" in data && typeof data.error === "string") {
+		let error: Error;
+		try {
+			error = createOAuth2RequestError(data);
+		} catch {
+			throw new UnexpectedErrorResponseBodyError(response.status, data);
+		}
+		throw error;
+	}
+
+	// Withings returns `{"status": 0, "body": {...}}`.
+	if (!("body" in data) || typeof data.body !== "object" || data.body === null) {
+		throw new Error("Missing or invalid 'body' field");
+	}
+	const tokens = new OAuth2Tokens(data.body);
+	return tokens;
+}