@drawbridge/drawbridge-utils 0.0.106 → 0.0.107

package/dist/connections/oauth.cjs

@@ -0,0 +1,123 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// lib/connections/oauth.js
+var oauth_exports = {};
+__export(oauth_exports, {
+  consentUrl: () => consentUrl,
+  exchange: () => exchange,
+  pkcePair: () => pkcePair,
+  refresh: () => refresh
+});
+module.exports = __toCommonJS(oauth_exports);
+var import_node_crypto = require("crypto");
+var credentials = ({ clientId, clientSecret, descriptor }) => (descriptor == null ? void 0 : descriptor.clientAuth) === "basic" ? {
+  headers: { authorization: "Basic " + Buffer.from(clientId + ":" + clientSecret).toString("base64") },
+  body: {}
+} : {
+  headers: {},
+  body: { client_id: clientId, client_secret: clientSecret }
+};
+var pkcePair = () => {
+  const verifier = (0, import_node_crypto.randomBytes)(32).toString("base64url");
+  return {
+    challenge: (0, import_node_crypto.createHash)("sha256").update(verifier).digest("base64url"),
+    method: "S256",
+    verifier
+  };
+};
+var consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) => {
+  if (!clientId) throw new Error("This deployment has no OAuth client configured, so there is nothing to consent through");
+  if (!(descriptor == null ? void 0 : descriptor.authorize)) throw new Error("This connection declares no authorize url");
+  if (descriptor.pkce && !challenge) throw new Error("This connection requires PKCE, so a code challenge is not optional");
+  return descriptor.authorize + "?" + new URLSearchParams({
+    // The descriptor's own params go FIRST, so a vendor quirk cannot quietly
+    // overwrite one of the fields below that every consent carries.
+    ...descriptor.params || {},
+    client_id: clientId,
+    redirect_uri: redirect,
+    response_type: "code",
+    ...descriptor.scopes && { scope: descriptor.scopes },
+    ...descriptor.pkce && {
+      code_challenge: challenge,
+      code_challenge_method: "S256"
+    },
+    state
+  });
+};
+var exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fetch, redirect, verifier } = {}) => {
+  if (!(descriptor == null ? void 0 : descriptor.token)) throw new Error("This connection declares no token url");
+  if (descriptor.pkce && !verifier) throw new Error("This connection requires PKCE, so the code verifier is not optional");
+  const client = credentials({ clientId, clientSecret, descriptor });
+  const response = await fetcher(descriptor.token, {
+    body: new URLSearchParams({
+      ...client.body,
+      code: decodeURIComponent(String(code || "").trim()),
+      grant_type: "authorization_code",
+      redirect_uri: redirect,
+      ...descriptor.pkce && { code_verifier: verifier }
+    }),
+    headers: { "content-type": "application/x-www-form-urlencoded", ...client.headers },
+    method: "POST",
+    signal: AbortSignal.timeout(15e3)
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error("The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : ""));
+  }
+  if (!body.access_token) throw new Error("The vendor returned no access token");
+  return {
+    accessToken: body.access_token,
+    expiresIn: body.expires_in || null,
+    refreshToken: body.refresh_token || null,
+    scope: body.scope || null
+  };
+};
+var refresh = async ({ clientId, clientSecret, descriptor, fetcher = fetch, refreshToken } = {}) => {
+  if (!clientId || !clientSecret) throw new Error("This deployment has no OAuth client configured, so no token can be minted");
+  if (!refreshToken) throw new Error("Nothing has been consented to yet, so there is no refresh token to spend");
+  if (!(descriptor == null ? void 0 : descriptor.token)) throw new Error("This connection declares no token url");
+  const client = credentials({ clientId, clientSecret, descriptor });
+  const response = await fetcher(descriptor.token, {
+    body: new URLSearchParams({
+      ...client.body,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken
+    }),
+    headers: { "content-type": "application/x-www-form-urlencoded", ...client.headers },
+    method: "POST",
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!response.ok) throw new Error("The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection");
+  const body = await response.json();
+  return {
+    accessToken: body.access_token,
+    expiresIn: body.expires_in || null,
+    // A vendor that rotates its refresh token returns a new one, and dropping
+    // it silently invalidates the stored grant on the NEXT refresh rather
+    // than this one — a failure a day late and nowhere near its cause.
+    refreshToken: body.refresh_token || null
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  consentUrl,
+  exchange,
+  pkcePair,
+  refresh
+});

package/dist/connections/oauth.d.cts

@@ -0,0 +1,189 @@
+import { randomBytes, createHash } from 'node:crypto';
+
+// HOW A VENDOR WANTS TO BE TOLD WHO WE ARE. Two conventions, both standard, and
+// vendors genuinely differ: Google takes client_id and client_secret as form
+// fields; Klaviyo requires HTTP Basic and rejects the body form. Declared per
+// vendor rather than branched on a slug, because the second Basic vendor would
+// otherwise add a second branch.
+const credentials = ({ clientId, clientSecret, descriptor }) => (
+
+	descriptor?.clientAuth === 'basic'
+		? {
+			headers : { authorization : 'Basic ' + Buffer.from( clientId + ':' + clientSecret ).toString( 'base64' ) },
+			body : {}
+		}
+		: {
+			headers : {},
+			body : { client_id : clientId, client_secret : clientSecret }
+		}
+
+);
+
+// The OAuth flow, once, for every vendor that uses one.
+//
+// A connection declares what it needs and this runs it. Adding an OAuth vendor
+// is a manifest, not a module — which is the whole point: the alternative is
+// what Shopify already is, a vendor whose consent, exchange and callback are
+// hand-written, so a second one copies every line.
+//
+//   auth : {
+//       type  : 'oauth',
+//       oauth : {
+//           authorize : 'https://login.mailchimp.com/oauth2/authorize',
+//           client    : { id : 'MAILCHIMP_OAUTH_CLIENT_ID', secret : 'MAILCHIMP_OAUTH_CLIENT_SECRET' },
+//           redirect  : '/api/connection/mailchimp/callback',
+//           token     : 'https://login.mailchimp.com/oauth2/token',
+//           params    : { ... },   optional vendor quirks
+//           pkce      : true,      Klaviyo's OAuth 2.1 requires it
+//           scopes    : '...'      optional; Mailchimp has none
+//       }
+//   }
+//
+// NO CREDENTIAL LIVES HERE OR IN A MANIFEST. `client` NAMES the environment
+// variables holding OUR application's client — one identity, every merchant,
+// which is what an OAuth client is. The token belongs to the merchant and
+// arrives from their own consent, and that distinction is what stops one
+// organization reading another's data.
+//
+// `fetcher` is injected on every call so tests never open a socket. Production
+// passes nothing and gets global fetch.
+
+// PKCE, for the vendors that demand it. Klaviyo's OAuth 2.1 refuses an exchange
+// without it: a random verifier is held by us, its SHA-256 challenge travels
+// with the consent, and the vendor checks they match — which is what stops an
+// intercepted code being redeemed by somebody else.
+//
+// 43-128 characters of unreserved alphabet, per RFC 7636. base64url of 32 bytes
+// lands at 43 and needs no padding stripped beyond the two substitutions.
+const pkcePair = () => {
+
+	const verifier = randomBytes( 32 ).toString( 'base64url' );
+
+	return {
+		challenge : createHash( 'sha256' ).update( verifier ).digest( 'base64url' ),
+		method : 'S256',
+		verifier
+	};
+
+};
+
+// The url a merchant follows. Side-effect free by construction — building it
+// writes nothing, which is what lets a card render it as a link rather than a
+// button that mints a consent on click.
+const consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) => {
+
+	// A url naming no application is not a consent, and it reports a deployment
+	// fault nobody can fix from a connection page.
+	if( ! clientId ) throw new Error( 'This deployment has no OAuth client configured, so there is nothing to consent through' );
+
+	if( ! descriptor?.authorize ) throw new Error( 'This connection declares no authorize url' );
+
+	if( descriptor.pkce && ! challenge ) throw new Error( 'This connection requires PKCE, so a code challenge is not optional' );
+
+	return descriptor.authorize + '?' + new URLSearchParams({
+		// The descriptor's own params go FIRST, so a vendor quirk cannot quietly
+		// overwrite one of the fields below that every consent carries.
+		...( descriptor.params || {} ),
+		client_id : clientId,
+		redirect_uri : redirect,
+		response_type : 'code',
+		...( descriptor.scopes && { scope : descriptor.scopes }),
+		...( descriptor.pkce && {
+			code_challenge : challenge,
+			code_challenge_method : 'S256'
+		}),
+		state
+	});
+
+};
+
+// The code-for-token trade.
+//
+// The redirect must byte-match what the consent carried — it is registered in
+// the vendor's console — so the caller passes the declared callback and it is
+// used verbatim, never rebuilt from a slug.
+const exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fetch, redirect, verifier } = {}) => {
+
+	if( ! descriptor?.token ) throw new Error( 'This connection declares no token url' );
+
+	if( descriptor.pkce && ! verifier ) throw new Error( 'This connection requires PKCE, so the code verifier is not optional' );
+
+	const client = credentials({ clientId, clientSecret, descriptor });
+
+	const response = await fetcher( descriptor.token, {
+		body : new URLSearchParams({
+			...client.body,
+			code : decodeURIComponent( String( code || '' ).trim() ),
+			grant_type : 'authorization_code',
+			redirect_uri : redirect,
+			...( descriptor.pkce && { code_verifier : verifier })
+		}),
+		headers : { 'content-type' : 'application/x-www-form-urlencoded', ...client.headers },
+		method : 'POST',
+		signal : AbortSignal.timeout( 15000 )
+	});
+
+	const body = await response.json().catch( () => ({}) );
+
+	if( ! response.ok ){
+
+		throw new Error( 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' ) );
+
+	}
+
+	if( ! body.access_token ) throw new Error( 'The vendor returned no access token' );
+
+	// A REFRESH TOKEN IS NOT UNIVERSAL. Google returns one only with
+	// access_type=offline; Mailchimp's tokens do not expire and it returns none
+	// at all. So its absence cannot be an error here the way it is in a
+	// refresh-only world — the manifest says whether the vendor issues one by
+	// whether it declares the params that ask for it.
+	return {
+		accessToken : body.access_token,
+		expiresIn : body.expires_in || null,
+		refreshToken : body.refresh_token || null,
+		scope : body.scope || null
+	};
+
+};
+
+// Short-lived access, minted from a stored refresh token.
+//
+// THE MINT IS THE PROBE. A revoked, rotated or wrong-account grant fails here in
+// the vendor's own words, rather than as an empty result three steps later that
+// reads like "this account has no data".
+const refresh = async ({ clientId, clientSecret, descriptor, fetcher = fetch, refreshToken } = {}) => {
+
+	if( ! clientId || ! clientSecret ) throw new Error( 'This deployment has no OAuth client configured, so no token can be minted' );
+	if( ! refreshToken ) throw new Error( 'Nothing has been consented to yet, so there is no refresh token to spend' );
+	if( ! descriptor?.token ) throw new Error( 'This connection declares no token url' );
+
+	const client = credentials({ clientId, clientSecret, descriptor });
+
+	const response = await fetcher( descriptor.token, {
+		body : new URLSearchParams({
+			...client.body,
+			grant_type : 'refresh_token',
+			refresh_token : refreshToken
+		}),
+		headers : { 'content-type' : 'application/x-www-form-urlencoded', ...client.headers },
+		method : 'POST',
+		signal : AbortSignal.timeout( 15000 )
+	});
+
+	if( ! response.ok ) throw new Error( 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection' );
+
+	const body = await response.json();
+
+	return {
+		accessToken : body.access_token,
+		expiresIn : body.expires_in || null,
+		// A vendor that rotates its refresh token returns a new one, and dropping
+		// it silently invalidates the stored grant on the NEXT refresh rather
+		// than this one — a failure a day late and nowhere near its cause.
+		refreshToken : body.refresh_token || null
+	};
+
+};
+
+export { consentUrl, exchange, pkcePair, refresh };

package/dist/connections/oauth.d.ts

@@ -0,0 +1,189 @@
+import { randomBytes, createHash } from 'node:crypto';
+
+// HOW A VENDOR WANTS TO BE TOLD WHO WE ARE. Two conventions, both standard, and
+// vendors genuinely differ: Google takes client_id and client_secret as form
+// fields; Klaviyo requires HTTP Basic and rejects the body form. Declared per
+// vendor rather than branched on a slug, because the second Basic vendor would
+// otherwise add a second branch.
+const credentials = ({ clientId, clientSecret, descriptor }) => (
+
+	descriptor?.clientAuth === 'basic'
+		? {
+			headers : { authorization : 'Basic ' + Buffer.from( clientId + ':' + clientSecret ).toString( 'base64' ) },
+			body : {}
+		}
+		: {
+			headers : {},
+			body : { client_id : clientId, client_secret : clientSecret }
+		}
+
+);
+
+// The OAuth flow, once, for every vendor that uses one.
+//
+// A connection declares what it needs and this runs it. Adding an OAuth vendor
+// is a manifest, not a module — which is the whole point: the alternative is
+// what Shopify already is, a vendor whose consent, exchange and callback are
+// hand-written, so a second one copies every line.
+//
+//   auth : {
+//       type  : 'oauth',
+//       oauth : {
+//           authorize : 'https://login.mailchimp.com/oauth2/authorize',
+//           client    : { id : 'MAILCHIMP_OAUTH_CLIENT_ID', secret : 'MAILCHIMP_OAUTH_CLIENT_SECRET' },
+//           redirect  : '/api/connection/mailchimp/callback',
+//           token     : 'https://login.mailchimp.com/oauth2/token',
+//           params    : { ... },   optional vendor quirks
+//           pkce      : true,      Klaviyo's OAuth 2.1 requires it
+//           scopes    : '...'      optional; Mailchimp has none
+//       }
+//   }
+//
+// NO CREDENTIAL LIVES HERE OR IN A MANIFEST. `client` NAMES the environment
+// variables holding OUR application's client — one identity, every merchant,
+// which is what an OAuth client is. The token belongs to the merchant and
+// arrives from their own consent, and that distinction is what stops one
+// organization reading another's data.
+//
+// `fetcher` is injected on every call so tests never open a socket. Production
+// passes nothing and gets global fetch.
+
+// PKCE, for the vendors that demand it. Klaviyo's OAuth 2.1 refuses an exchange
+// without it: a random verifier is held by us, its SHA-256 challenge travels
+// with the consent, and the vendor checks they match — which is what stops an
+// intercepted code being redeemed by somebody else.
+//
+// 43-128 characters of unreserved alphabet, per RFC 7636. base64url of 32 bytes
+// lands at 43 and needs no padding stripped beyond the two substitutions.
+const pkcePair = () => {
+
+	const verifier = randomBytes( 32 ).toString( 'base64url' );
+
+	return {
+		challenge : createHash( 'sha256' ).update( verifier ).digest( 'base64url' ),
+		method : 'S256',
+		verifier
+	};
+
+};
+
+// The url a merchant follows. Side-effect free by construction — building it
+// writes nothing, which is what lets a card render it as a link rather than a
+// button that mints a consent on click.
+const consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) => {
+
+	// A url naming no application is not a consent, and it reports a deployment
+	// fault nobody can fix from a connection page.
+	if( ! clientId ) throw new Error( 'This deployment has no OAuth client configured, so there is nothing to consent through' );
+
+	if( ! descriptor?.authorize ) throw new Error( 'This connection declares no authorize url' );
+
+	if( descriptor.pkce && ! challenge ) throw new Error( 'This connection requires PKCE, so a code challenge is not optional' );
+
+	return descriptor.authorize + '?' + new URLSearchParams({
+		// The descriptor's own params go FIRST, so a vendor quirk cannot quietly
+		// overwrite one of the fields below that every consent carries.
+		...( descriptor.params || {} ),
+		client_id : clientId,
+		redirect_uri : redirect,
+		response_type : 'code',
+		...( descriptor.scopes && { scope : descriptor.scopes }),
+		...( descriptor.pkce && {
+			code_challenge : challenge,
+			code_challenge_method : 'S256'
+		}),
+		state
+	});
+
+};
+
+// The code-for-token trade.
+//
+// The redirect must byte-match what the consent carried — it is registered in
+// the vendor's console — so the caller passes the declared callback and it is
+// used verbatim, never rebuilt from a slug.
+const exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fetch, redirect, verifier } = {}) => {
+
+	if( ! descriptor?.token ) throw new Error( 'This connection declares no token url' );
+
+	if( descriptor.pkce && ! verifier ) throw new Error( 'This connection requires PKCE, so the code verifier is not optional' );
+
+	const client = credentials({ clientId, clientSecret, descriptor });
+
+	const response = await fetcher( descriptor.token, {
+		body : new URLSearchParams({
+			...client.body,
+			code : decodeURIComponent( String( code || '' ).trim() ),
+			grant_type : 'authorization_code',
+			redirect_uri : redirect,
+			...( descriptor.pkce && { code_verifier : verifier })
+		}),
+		headers : { 'content-type' : 'application/x-www-form-urlencoded', ...client.headers },
+		method : 'POST',
+		signal : AbortSignal.timeout( 15000 )
+	});
+
+	const body = await response.json().catch( () => ({}) );
+
+	if( ! response.ok ){
+
+		throw new Error( 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' ) );
+
+	}
+
+	if( ! body.access_token ) throw new Error( 'The vendor returned no access token' );
+
+	// A REFRESH TOKEN IS NOT UNIVERSAL. Google returns one only with
+	// access_type=offline; Mailchimp's tokens do not expire and it returns none
+	// at all. So its absence cannot be an error here the way it is in a
+	// refresh-only world — the manifest says whether the vendor issues one by
+	// whether it declares the params that ask for it.
+	return {
+		accessToken : body.access_token,
+		expiresIn : body.expires_in || null,
+		refreshToken : body.refresh_token || null,
+		scope : body.scope || null
+	};
+
+};
+
+// Short-lived access, minted from a stored refresh token.
+//
+// THE MINT IS THE PROBE. A revoked, rotated or wrong-account grant fails here in
+// the vendor's own words, rather than as an empty result three steps later that
+// reads like "this account has no data".
+const refresh = async ({ clientId, clientSecret, descriptor, fetcher = fetch, refreshToken } = {}) => {
+
+	if( ! clientId || ! clientSecret ) throw new Error( 'This deployment has no OAuth client configured, so no token can be minted' );
+	if( ! refreshToken ) throw new Error( 'Nothing has been consented to yet, so there is no refresh token to spend' );
+	if( ! descriptor?.token ) throw new Error( 'This connection declares no token url' );
+
+	const client = credentials({ clientId, clientSecret, descriptor });
+
+	const response = await fetcher( descriptor.token, {
+		body : new URLSearchParams({
+			...client.body,
+			grant_type : 'refresh_token',
+			refresh_token : refreshToken
+		}),
+		headers : { 'content-type' : 'application/x-www-form-urlencoded', ...client.headers },
+		method : 'POST',
+		signal : AbortSignal.timeout( 15000 )
+	});
+
+	if( ! response.ok ) throw new Error( 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection' );
+
+	const body = await response.json();
+
+	return {
+		accessToken : body.access_token,
+		expiresIn : body.expires_in || null,
+		// A vendor that rotates its refresh token returns a new one, and dropping
+		// it silently invalidates the stored grant on the NEXT refresh rather
+		// than this one — a failure a day late and nowhere near its cause.
+		refreshToken : body.refresh_token || null
+	};
+
+};
+
+export { consentUrl, exchange, pkcePair, refresh };

package/dist/connections/oauth.js

@@ -0,0 +1,96 @@
+// lib/connections/oauth.js
+import { createHash, randomBytes } from "crypto";
+var credentials = ({ clientId, clientSecret, descriptor }) => (descriptor == null ? void 0 : descriptor.clientAuth) === "basic" ? {
+  headers: { authorization: "Basic " + Buffer.from(clientId + ":" + clientSecret).toString("base64") },
+  body: {}
+} : {
+  headers: {},
+  body: { client_id: clientId, client_secret: clientSecret }
+};
+var pkcePair = () => {
+  const verifier = randomBytes(32).toString("base64url");
+  return {
+    challenge: createHash("sha256").update(verifier).digest("base64url"),
+    method: "S256",
+    verifier
+  };
+};
+var consentUrl = ({ challenge, clientId, descriptor, redirect, state } = {}) => {
+  if (!clientId) throw new Error("This deployment has no OAuth client configured, so there is nothing to consent through");
+  if (!(descriptor == null ? void 0 : descriptor.authorize)) throw new Error("This connection declares no authorize url");
+  if (descriptor.pkce && !challenge) throw new Error("This connection requires PKCE, so a code challenge is not optional");
+  return descriptor.authorize + "?" + new URLSearchParams({
+    // The descriptor's own params go FIRST, so a vendor quirk cannot quietly
+    // overwrite one of the fields below that every consent carries.
+    ...descriptor.params || {},
+    client_id: clientId,
+    redirect_uri: redirect,
+    response_type: "code",
+    ...descriptor.scopes && { scope: descriptor.scopes },
+    ...descriptor.pkce && {
+      code_challenge: challenge,
+      code_challenge_method: "S256"
+    },
+    state
+  });
+};
+var exchange = async ({ clientId, clientSecret, code, descriptor, fetcher = fetch, redirect, verifier } = {}) => {
+  if (!(descriptor == null ? void 0 : descriptor.token)) throw new Error("This connection declares no token url");
+  if (descriptor.pkce && !verifier) throw new Error("This connection requires PKCE, so the code verifier is not optional");
+  const client = credentials({ clientId, clientSecret, descriptor });
+  const response = await fetcher(descriptor.token, {
+    body: new URLSearchParams({
+      ...client.body,
+      code: decodeURIComponent(String(code || "").trim()),
+      grant_type: "authorization_code",
+      redirect_uri: redirect,
+      ...descriptor.pkce && { code_verifier: verifier }
+    }),
+    headers: { "content-type": "application/x-www-form-urlencoded", ...client.headers },
+    method: "POST",
+    signal: AbortSignal.timeout(15e3)
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error("The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : ""));
+  }
+  if (!body.access_token) throw new Error("The vendor returned no access token");
+  return {
+    accessToken: body.access_token,
+    expiresIn: body.expires_in || null,
+    refreshToken: body.refresh_token || null,
+    scope: body.scope || null
+  };
+};
+var refresh = async ({ clientId, clientSecret, descriptor, fetcher = fetch, refreshToken } = {}) => {
+  if (!clientId || !clientSecret) throw new Error("This deployment has no OAuth client configured, so no token can be minted");
+  if (!refreshToken) throw new Error("Nothing has been consented to yet, so there is no refresh token to spend");
+  if (!(descriptor == null ? void 0 : descriptor.token)) throw new Error("This connection declares no token url");
+  const client = credentials({ clientId, clientSecret, descriptor });
+  const response = await fetcher(descriptor.token, {
+    body: new URLSearchParams({
+      ...client.body,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken
+    }),
+    headers: { "content-type": "application/x-www-form-urlencoded", ...client.headers },
+    method: "POST",
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!response.ok) throw new Error("The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection");
+  const body = await response.json();
+  return {
+    accessToken: body.access_token,
+    expiresIn: body.expires_in || null,
+    // A vendor that rotates its refresh token returns a new one, and dropping
+    // it silently invalidates the stored grant on the NEXT refresh rather
+    // than this one — a failure a day late and nowhere near its cause.
+    refreshToken: body.refresh_token || null
+  };
+};
+export {
+  consentUrl,
+  exchange,
+  pkcePair,
+  refresh
+};

package/package.json

@@ -172,6 +172,16 @@
       "types": "./dist/fields-validate.d.ts",
       "import": "./dist/fields-validate.js",
       "require": "./dist/fields-validate.cjs"
+    },
+    "./connections": {
+      "types": "./dist/connections/index.d.ts",
+      "import": "./dist/connections/index.js",
+      "require": "./dist/connections/index.cjs"
+    },
+    "./connections/oauth": {
+      "types": "./dist/connections/oauth.d.ts",
+      "import": "./dist/connections/oauth.js",
+      "require": "./dist/connections/oauth.cjs"
     }
   },
   "files": [
@@ -190,5 +200,5 @@
     "test": ". \"$HOME/.nvm/nvm.sh\" && nvm use && node --test"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.106"
+  "version": "0.0.107"
 }