@ttoss/oauth-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024, Terezinha Tech Operations (ttoss)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @ttoss/oauth-client
+
+Reusable client for connecting a ttoss app to third-party OAuth 2.0 providers
+(TikTok, Instagram, YouTube, Google, …). It covers building the authorization
+URL, exchanging the callback code, and keeping access tokens fresh through lazy
+and scheduled refresh. The client is **ORM- and storage-agnostic**: it operates
+on plain token objects and delegates persistence to you, so it works with
+Sequelize, Prisma, or anything else.
+
+See the [OAuth Client guideline](https://ttoss.dev/docs/engineering/guidelines/oauth-third-party-client)
+for the full end-to-end pattern (endpoints, scheduled jobs, internal token access).
+
+## Install
+
+```bash
+pnpm add @ttoss/oauth-client
+```
+
+## Generic core
+
+`createOAuthClient` builds a client for any provider. Parameter-name overrides
+absorb providers that deviate from RFC 6749.
+
+```typescript
+import { createOAuthClient } from '@ttoss/oauth-client';
+
+const client = createOAuthClient({
+  authorizationUrl: 'https://provider.example/authorize',
+  tokenUrl: 'https://provider.example/token',
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+});
+
+// 1. Redirect the user to the provider
+const url = client.buildAuthUrl({
+  redirectUri: 'https://app.example/callback',
+  scope: ['read', 'write'],
+  state: crypto.randomBytes(16).toString('hex'), // persist & verify on callback
+});
+
+// 2. Exchange the callback code for tokens
+const tokens = await client.exchangeCode({
+  code,
+  redirectUri: 'https://app.example/callback',
+});
+```
+
+## Provider presets
+
+Presets pre-configure a provider's quirks. TikTok, for example, names the client
+id `client_key` and uses comma-separated scopes — the preset encodes both.
+
+```typescript
+import { createTikTokClient } from '@ttoss/oauth-client';
+
+const tiktok = createTikTokClient({
+  clientKey: process.env.TIKTOK_CLIENT_KEY!,
+  clientSecret: process.env.TIKTOK_CLIENT_SECRET!,
+});
+```
+
+Adding a provider is one new preset over the same core; nothing else changes.
+
+## Keeping tokens fresh
+
+`getValidToken` returns a usable access token, refreshing first if it expires
+within `refreshWindowMs` (default 2h). `onRefresh` receives the new tokens so you
+can persist them.
+
+```typescript
+const accessToken = await client.getValidToken(record, {
+  onRefresh: async (updated) => {
+    await saveToken(record.id, updated);
+  },
+});
+```
+
+`findExpiringTokens` powers a scheduled job that proactively refreshes tokens
+expiring within a wider window (default 6h), keeping connections alive for
+inactive users.
+
+```typescript
+import { findExpiringTokens } from '@ttoss/oauth-client';
+
+const expiring = findExpiringTokens(await loadAllTokens());
+await Promise.all(expiring.map(refreshOne));
+```
+
+## Encryption at rest
+
+Access and refresh tokens are credentials — **encrypt them at rest**. The package
+stays encryption-agnostic and works with plaintext records; encrypt at the
+storage boundary with [`@ttoss/auth-core`](https://ttoss.dev/docs/modules/packages/auth-core):
+
+```typescript
+import { decryptValue, encryptValue } from '@ttoss/auth-core';
+
+const KEY = process.env.TOKEN_ENCRYPTION_KEY!; // from generateEncryptionKey()
+
+const accessToken = await client.getValidToken(
+  {
+    accessToken: decryptValue({ ciphertext: row.accessToken, key: KEY }),
+    refreshToken: decryptValue({ ciphertext: row.refreshToken, key: KEY }),
+    accessTokenExpiresAt: row.accessTokenExpiresAt,
+  },
+  {
+    onRefresh: async (updated) => {
+      await row.update({
+        accessToken: encryptValue({ plaintext: updated.accessToken, key: KEY }),
+        refreshToken: encryptValue({
+          plaintext: updated.refreshToken,
+          key: KEY,
+        }),
+        accessTokenExpiresAt: new Date(Date.now() + updated.expiresIn * 1000),
+      });
+    },
+  }
+);
+```
+
+## API
+
+| Export                      | Purpose                                                          |
+| --------------------------- | ---------------------------------------------------------------- |
+| `createOAuthClient`         | Build a client for a generic `OAuthProvider`.                    |
+| `createTikTokClient`        | Preset for TikTok Login Kit.                                     |
+| `client.buildAuthUrl`       | Build the provider's authorization URL.                          |
+| `client.exchangeCode`       | Exchange an authorization code for tokens.                       |
+| `client.refreshAccessToken` | Refresh an access token from a stored refresh token.             |
+| `client.getValidToken`      | Return a valid token, refreshing lazily within a safety window.  |
+| `findExpiringTokens`        | Filter records expiring within a window (for scheduled refresh). |

package/dist/index-BgPLLjdP.d.cts

@@ -0,0 +1,141 @@
+
+//#region src/types.d.ts
+/**
+ * Overrides for providers that deviate from the RFC 6749 parameter names and
+ * conventions. Every field is optional; unset fields fall back to the standard
+ * OAuth 2.0 defaults.
+ */
+interface ProviderParamOverrides {
+  /** Parameter name carrying the client identifier. Default: `client_id`. */
+  clientId?: string;
+  /** Parameter name carrying the client secret. Default: `client_secret`. */
+  clientSecret?: string;
+  /** Separator used to join multiple scopes into one string. Default: `' '`. */
+  scopeSeparator?: string;
+  /** `grant_type` value sent when refreshing a token. Default: `refresh_token`. */
+  refreshGrantType?: string;
+}
+/**
+ * Normalized token response returned by every client method that talks to the
+ * provider's token endpoint. `raw` preserves provider-specific fields (e.g.
+ * TikTok's `open_id`) that the generic shape does not model.
+ */
+interface TokenResponse {
+  /** Short-lived access token used to call the provider's API. */
+  accessToken: string;
+  /** Long-lived token used to obtain new access tokens. */
+  refreshToken: string;
+  /** Lifetime of the access token, in seconds. */
+  expiresIn: number;
+  /** Untouched JSON body from the provider, for provider-specific fields. */
+  raw: Record<string, unknown>;
+}
+/**
+ * Maps a raw token endpoint JSON body to a {@link TokenResponse}. Supply this on
+ * {@link OAuthProvider} when a provider names its token fields differently from
+ * the OAuth 2.0 defaults (`access_token`, `refresh_token`, `expires_in`).
+ */
+type TokenResponseParser = (raw: Record<string, unknown>) => TokenResponse;
+/**
+ * Configuration for a third-party OAuth 2.0 provider. This is the generic,
+ * provider-agnostic shape consumed by {@link createOAuthClient}. Pre-built
+ * presets (e.g. `createTikTokClient`) assemble this for you.
+ */
+interface OAuthProvider {
+  /** Authorization endpoint the user is redirected to in order to log in. */
+  authorizationUrl: string;
+  /** Token endpoint used for both code exchange and refresh. */
+  tokenUrl: string;
+  /** OAuth client identifier issued by the provider. */
+  clientId: string;
+  /** OAuth client secret issued by the provider. */
+  clientSecret: string;
+  /** Overrides for providers that deviate from RFC 6749 parameter names. */
+  params?: ProviderParamOverrides;
+  /** Custom parser for non-standard token endpoint responses. */
+  parseTokenResponse?: TokenResponseParser;
+}
+/**
+ * Plain, ORM-agnostic snapshot of a stored token. The package never persists
+ * these records itself — the caller loads them (decrypting if stored encrypted)
+ * and persists updates via the `onRefresh` callback.
+ */
+interface TokenRecord {
+  /** Current access token (plaintext). */
+  accessToken: string;
+  /** Current refresh token (plaintext). */
+  refreshToken: string;
+  /** Absolute time at which the access token expires. */
+  accessTokenExpiresAt: Date;
+}
+//#endregion
+//#region src/client.d.ts
+/** Default safety window for lazy refresh: 2 hours. */
+declare const DEFAULT_REFRESH_WINDOW_MS: number;
+/** Options for {@link OAuthClient.buildAuthUrl}. */
+interface BuildAuthUrlOptions {
+  /** Where the provider redirects the user back to after consent. */
+  redirectUri: string;
+  /** Requested scope(s). An array is joined with the provider's separator. */
+  scope: string | string[];
+  /** Opaque CSRF value; persist it and verify it on callback. */
+  state: string;
+  /** Extra provider-specific query parameters to append. */
+  extraParams?: Record<string, string>;
+}
+/** Options for {@link OAuthClient.exchangeCode}. */
+interface ExchangeCodeOptions {
+  /** Authorization code received on the callback. */
+  code: string;
+  /** Must match the `redirectUri` used to build the authorization URL. */
+  redirectUri: string;
+}
+/** Options for {@link OAuthClient.getValidToken}. */
+interface GetValidTokenOptions {
+  /** Refresh if the access token expires within this window. Default: 2h. */
+  refreshWindowMs?: number;
+  /** Called with the refreshed tokens so the caller can persist them. */
+  onRefresh: (updated: TokenResponse) => Promise<void> | void;
+}
+/**
+ * A configured OAuth 2.0 client bound to a single provider. Obtain one via
+ * {@link createOAuthClient} or a provider preset (e.g. `createTikTokClient`).
+ */
+interface OAuthClient {
+  /** Build the provider's authorization URL to redirect the user to. */
+  buildAuthUrl: (options: BuildAuthUrlOptions) => string;
+  /** Exchange an authorization code for tokens at the token endpoint. */
+  exchangeCode: (options: ExchangeCodeOptions) => Promise<TokenResponse>;
+  /** Refresh an access token using a stored refresh token. */
+  refreshAccessToken: (refreshToken: string) => Promise<TokenResponse>;
+  /**
+   * Return a valid access token, refreshing first if it expires within
+   * `refreshWindowMs`. On refresh, `onRefresh` is awaited before returning so
+   * the caller can persist the new tokens.
+   */
+  getValidToken: (record: TokenRecord, options: GetValidTokenOptions) => Promise<string>;
+}
+/**
+ * Create an OAuth client for a generic {@link OAuthProvider}. The returned
+ * client is stateless and delegates all persistence to its caller, making it
+ * ORM- and storage-agnostic.
+ */
+declare const createOAuthClient: (provider: OAuthProvider) => OAuthClient;
+//#endregion
+//#region src/providers/tiktok.d.ts
+/** Options for {@link createTikTokClient}. */
+interface TikTokClientOptions {
+  /** TikTok app `client_key` (TikTok's name for the client id). */
+  clientKey: string;
+  /** TikTok app `client_secret`. */
+  clientSecret: string;
+}
+/**
+ * Build an {@link OAuthClient} preconfigured for TikTok's Login Kit. Encodes
+ * TikTok's deviations from RFC 6749: the client id is sent as `client_key` and
+ * scopes are comma-separated. The token endpoint returns `open_id` alongside
+ * the tokens, available on `TokenResponse.raw`.
+ */
+declare const createTikTokClient: (options: TikTokClientOptions) => OAuthClient;
+//#endregion
+export { ExchangeCodeOptions as a, createOAuthClient as c, TokenRecord as d, TokenResponse as f, DEFAULT_REFRESH_WINDOW_MS as i, OAuthProvider as l, createTikTokClient as n, GetValidTokenOptions as o, TokenResponseParser as p, BuildAuthUrlOptions as r, OAuthClient as s, TikTokClientOptions as t, ProviderParamOverrides as u };

package/dist/index-BgPLLjdP.d.mts

@@ -0,0 +1,141 @@
+
+//#region src/types.d.ts
+/**
+ * Overrides for providers that deviate from the RFC 6749 parameter names and
+ * conventions. Every field is optional; unset fields fall back to the standard
+ * OAuth 2.0 defaults.
+ */
+interface ProviderParamOverrides {
+  /** Parameter name carrying the client identifier. Default: `client_id`. */
+  clientId?: string;
+  /** Parameter name carrying the client secret. Default: `client_secret`. */
+  clientSecret?: string;
+  /** Separator used to join multiple scopes into one string. Default: `' '`. */
+  scopeSeparator?: string;
+  /** `grant_type` value sent when refreshing a token. Default: `refresh_token`. */
+  refreshGrantType?: string;
+}
+/**
+ * Normalized token response returned by every client method that talks to the
+ * provider's token endpoint. `raw` preserves provider-specific fields (e.g.
+ * TikTok's `open_id`) that the generic shape does not model.
+ */
+interface TokenResponse {
+  /** Short-lived access token used to call the provider's API. */
+  accessToken: string;
+  /** Long-lived token used to obtain new access tokens. */
+  refreshToken: string;
+  /** Lifetime of the access token, in seconds. */
+  expiresIn: number;
+  /** Untouched JSON body from the provider, for provider-specific fields. */
+  raw: Record<string, unknown>;
+}
+/**
+ * Maps a raw token endpoint JSON body to a {@link TokenResponse}. Supply this on
+ * {@link OAuthProvider} when a provider names its token fields differently from
+ * the OAuth 2.0 defaults (`access_token`, `refresh_token`, `expires_in`).
+ */
+type TokenResponseParser = (raw: Record<string, unknown>) => TokenResponse;
+/**
+ * Configuration for a third-party OAuth 2.0 provider. This is the generic,
+ * provider-agnostic shape consumed by {@link createOAuthClient}. Pre-built
+ * presets (e.g. `createTikTokClient`) assemble this for you.
+ */
+interface OAuthProvider {
+  /** Authorization endpoint the user is redirected to in order to log in. */
+  authorizationUrl: string;
+  /** Token endpoint used for both code exchange and refresh. */
+  tokenUrl: string;
+  /** OAuth client identifier issued by the provider. */
+  clientId: string;
+  /** OAuth client secret issued by the provider. */
+  clientSecret: string;
+  /** Overrides for providers that deviate from RFC 6749 parameter names. */
+  params?: ProviderParamOverrides;
+  /** Custom parser for non-standard token endpoint responses. */
+  parseTokenResponse?: TokenResponseParser;
+}
+/**
+ * Plain, ORM-agnostic snapshot of a stored token. The package never persists
+ * these records itself — the caller loads them (decrypting if stored encrypted)
+ * and persists updates via the `onRefresh` callback.
+ */
+interface TokenRecord {
+  /** Current access token (plaintext). */
+  accessToken: string;
+  /** Current refresh token (plaintext). */
+  refreshToken: string;
+  /** Absolute time at which the access token expires. */
+  accessTokenExpiresAt: Date;
+}
+//#endregion
+//#region src/client.d.ts
+/** Default safety window for lazy refresh: 2 hours. */
+declare const DEFAULT_REFRESH_WINDOW_MS: number;
+/** Options for {@link OAuthClient.buildAuthUrl}. */
+interface BuildAuthUrlOptions {
+  /** Where the provider redirects the user back to after consent. */
+  redirectUri: string;
+  /** Requested scope(s). An array is joined with the provider's separator. */
+  scope: string | string[];
+  /** Opaque CSRF value; persist it and verify it on callback. */
+  state: string;
+  /** Extra provider-specific query parameters to append. */
+  extraParams?: Record<string, string>;
+}
+/** Options for {@link OAuthClient.exchangeCode}. */
+interface ExchangeCodeOptions {
+  /** Authorization code received on the callback. */
+  code: string;
+  /** Must match the `redirectUri` used to build the authorization URL. */
+  redirectUri: string;
+}
+/** Options for {@link OAuthClient.getValidToken}. */
+interface GetValidTokenOptions {
+  /** Refresh if the access token expires within this window. Default: 2h. */
+  refreshWindowMs?: number;
+  /** Called with the refreshed tokens so the caller can persist them. */
+  onRefresh: (updated: TokenResponse) => Promise<void> | void;
+}
+/**
+ * A configured OAuth 2.0 client bound to a single provider. Obtain one via
+ * {@link createOAuthClient} or a provider preset (e.g. `createTikTokClient`).
+ */
+interface OAuthClient {
+  /** Build the provider's authorization URL to redirect the user to. */
+  buildAuthUrl: (options: BuildAuthUrlOptions) => string;
+  /** Exchange an authorization code for tokens at the token endpoint. */
+  exchangeCode: (options: ExchangeCodeOptions) => Promise<TokenResponse>;
+  /** Refresh an access token using a stored refresh token. */
+  refreshAccessToken: (refreshToken: string) => Promise<TokenResponse>;
+  /**
+   * Return a valid access token, refreshing first if it expires within
+   * `refreshWindowMs`. On refresh, `onRefresh` is awaited before returning so
+   * the caller can persist the new tokens.
+   */
+  getValidToken: (record: TokenRecord, options: GetValidTokenOptions) => Promise<string>;
+}
+/**
+ * Create an OAuth client for a generic {@link OAuthProvider}. The returned
+ * client is stateless and delegates all persistence to its caller, making it
+ * ORM- and storage-agnostic.
+ */
+declare const createOAuthClient: (provider: OAuthProvider) => OAuthClient;
+//#endregion
+//#region src/providers/tiktok.d.ts
+/** Options for {@link createTikTokClient}. */
+interface TikTokClientOptions {
+  /** TikTok app `client_key` (TikTok's name for the client id). */
+  clientKey: string;
+  /** TikTok app `client_secret`. */
+  clientSecret: string;
+}
+/**
+ * Build an {@link OAuthClient} preconfigured for TikTok's Login Kit. Encodes
+ * TikTok's deviations from RFC 6749: the client id is sent as `client_key` and
+ * scopes are comma-separated. The token endpoint returns `open_id` alongside
+ * the tokens, available on `TokenResponse.raw`.
+ */
+declare const createTikTokClient: (options: TikTokClientOptions) => OAuthClient;
+//#endregion
+export { ExchangeCodeOptions as a, createOAuthClient as c, TokenRecord as d, TokenResponse as f, DEFAULT_REFRESH_WINDOW_MS as i, OAuthProvider as l, createTikTokClient as n, GetValidTokenOptions as o, TokenResponseParser as p, BuildAuthUrlOptions as r, OAuthClient as s, TikTokClientOptions as t, ProviderParamOverrides as u };

package/dist/index.cjs

@@ -0,0 +1,29 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+Object.defineProperty(exports, Symbol.toStringTag, {
+  value: 'Module'
+});
+const require_providers = require('./providers-FHRUbQH_.cjs');
+
+//#region src/tokens.ts
+/** Default scheduled-refresh window: 6 hours. */
+var DEFAULT_EXPIRING_WINDOW_MS = 360 * 60 * 1e3;
+/**
+* Filter a list of token records down to those that expire within `windowMs`
+* from now (default 6 hours). Intended for a scheduled job that proactively
+* refreshes tokens before they lapse, keeping connections alive for inactive
+* users. Pure and provider-agnostic — it inspects only `accessTokenExpiresAt`.
+*/
+var findExpiringTokens = (records, options) => {
+  const windowMs = options?.windowMs ?? 216e5;
+  const threshold = Date.now() + windowMs;
+  return records.filter(record => {
+    return record.accessTokenExpiresAt.getTime() <= threshold;
+  });
+};
+
+//#endregion
+exports.DEFAULT_EXPIRING_WINDOW_MS = DEFAULT_EXPIRING_WINDOW_MS;
+exports.DEFAULT_REFRESH_WINDOW_MS = require_providers.DEFAULT_REFRESH_WINDOW_MS;
+exports.createOAuthClient = require_providers.createOAuthClient;
+exports.createTikTokClient = require_providers.createTikTokClient;
+exports.findExpiringTokens = findExpiringTokens;

package/dist/index.d.cts

@@ -0,0 +1,20 @@
+
+import { a as ExchangeCodeOptions, c as createOAuthClient, d as TokenRecord, f as TokenResponse, i as DEFAULT_REFRESH_WINDOW_MS, l as OAuthProvider, n as createTikTokClient, o as GetValidTokenOptions, p as TokenResponseParser, r as BuildAuthUrlOptions, s as OAuthClient, t as TikTokClientOptions, u as ProviderParamOverrides } from "./index-BgPLLjdP.cjs";
+
+//#region src/tokens.d.ts
+/** Default scheduled-refresh window: 6 hours. */
+declare const DEFAULT_EXPIRING_WINDOW_MS: number;
+/** Options for {@link findExpiringTokens}. */
+interface FindExpiringTokensOptions {
+  /** Include records expiring within this window from now. Default: 6h. */
+  windowMs?: number;
+}
+/**
+ * Filter a list of token records down to those that expire within `windowMs`
+ * from now (default 6 hours). Intended for a scheduled job that proactively
+ * refreshes tokens before they lapse, keeping connections alive for inactive
+ * users. Pure and provider-agnostic — it inspects only `accessTokenExpiresAt`.
+ */
+declare const findExpiringTokens: <T extends TokenRecord>(records: T[], options?: FindExpiringTokensOptions) => T[];
+//#endregion
+export { type BuildAuthUrlOptions, DEFAULT_EXPIRING_WINDOW_MS, DEFAULT_REFRESH_WINDOW_MS, type ExchangeCodeOptions, type FindExpiringTokensOptions, type GetValidTokenOptions, type OAuthClient, type OAuthProvider, type ProviderParamOverrides, type TikTokClientOptions, type TokenRecord, type TokenResponse, type TokenResponseParser, createOAuthClient, createTikTokClient, findExpiringTokens };

package/dist/index.d.mts

@@ -0,0 +1,20 @@
+
+import { a as ExchangeCodeOptions, c as createOAuthClient, d as TokenRecord, f as TokenResponse, i as DEFAULT_REFRESH_WINDOW_MS, l as OAuthProvider, n as createTikTokClient, o as GetValidTokenOptions, p as TokenResponseParser, r as BuildAuthUrlOptions, s as OAuthClient, t as TikTokClientOptions, u as ProviderParamOverrides } from "./index-BgPLLjdP.mjs";
+
+//#region src/tokens.d.ts
+/** Default scheduled-refresh window: 6 hours. */
+declare const DEFAULT_EXPIRING_WINDOW_MS: number;
+/** Options for {@link findExpiringTokens}. */
+interface FindExpiringTokensOptions {
+  /** Include records expiring within this window from now. Default: 6h. */
+  windowMs?: number;
+}
+/**
+ * Filter a list of token records down to those that expire within `windowMs`
+ * from now (default 6 hours). Intended for a scheduled job that proactively
+ * refreshes tokens before they lapse, keeping connections alive for inactive
+ * users. Pure and provider-agnostic — it inspects only `accessTokenExpiresAt`.
+ */
+declare const findExpiringTokens: <T extends TokenRecord>(records: T[], options?: FindExpiringTokensOptions) => T[];
+//#endregion
+export { type BuildAuthUrlOptions, DEFAULT_EXPIRING_WINDOW_MS, DEFAULT_REFRESH_WINDOW_MS, type ExchangeCodeOptions, type FindExpiringTokensOptions, type GetValidTokenOptions, type OAuthClient, type OAuthProvider, type ProviderParamOverrides, type TikTokClientOptions, type TokenRecord, type TokenResponse, type TokenResponseParser, createOAuthClient, createTikTokClient, findExpiringTokens };

package/dist/index.mjs

@@ -0,0 +1,22 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { n as DEFAULT_REFRESH_WINDOW_MS, r as createOAuthClient, t as createTikTokClient } from "./providers-Cxs2-TSE.mjs";
+
+//#region src/tokens.ts
+/** Default scheduled-refresh window: 6 hours. */
+var DEFAULT_EXPIRING_WINDOW_MS = 360 * 60 * 1e3;
+/**
+* Filter a list of token records down to those that expire within `windowMs`
+* from now (default 6 hours). Intended for a scheduled job that proactively
+* refreshes tokens before they lapse, keeping connections alive for inactive
+* users. Pure and provider-agnostic — it inspects only `accessTokenExpiresAt`.
+*/
+var findExpiringTokens = (records, options) => {
+  const windowMs = options?.windowMs ?? 216e5;
+  const threshold = Date.now() + windowMs;
+  return records.filter(record => {
+    return record.accessTokenExpiresAt.getTime() <= threshold;
+  });
+};
+
+//#endregion
+export { DEFAULT_EXPIRING_WINDOW_MS, DEFAULT_REFRESH_WINDOW_MS, createOAuthClient, createTikTokClient, findExpiringTokens };

package/dist/providers/index.cjs

@@ -0,0 +1,6 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+Object.defineProperty(exports, Symbol.toStringTag, {
+  value: 'Module'
+});
+const require_providers = require('../providers-FHRUbQH_.cjs');
+exports.createTikTokClient = require_providers.createTikTokClient;

package/dist/providers/index.d.cts

@@ -0,0 +1,3 @@
+
+import { n as createTikTokClient, t as TikTokClientOptions } from "../index-BgPLLjdP.cjs";
+export { type TikTokClientOptions, createTikTokClient };

package/dist/providers/index.d.mts

@@ -0,0 +1,3 @@
+
+import { n as createTikTokClient, t as TikTokClientOptions } from "../index-BgPLLjdP.mjs";
+export { type TikTokClientOptions, createTikTokClient };

package/dist/providers/index.mjs

@@ -0,0 +1,3 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { t as createTikTokClient } from "../providers-Cxs2-TSE.mjs";
+export { createTikTokClient };

package/dist/providers-Cxs2-TSE.mjs

@@ -0,0 +1,107 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+//#region src/client.ts
+/** Default safety window for lazy refresh: 2 hours. */
+var DEFAULT_REFRESH_WINDOW_MS = 7200 * 1e3;
+var defaultParseTokenResponse = raw => {
+  return {
+    accessToken: String(raw.access_token),
+    refreshToken: String(raw.refresh_token),
+    expiresIn: Number(raw.expires_in),
+    raw
+  };
+};
+/**
+* Create an OAuth client for a generic {@link OAuthProvider}. The returned
+* client is stateless and delegates all persistence to its caller, making it
+* ORM- and storage-agnostic.
+*/
+var createOAuthClient = provider => {
+  const clientIdParam = provider.params?.clientId ?? "client_id";
+  const clientSecretParam = provider.params?.clientSecret ?? "client_secret";
+  const scopeSeparator = provider.params?.scopeSeparator ?? " ";
+  const refreshGrantType = provider.params?.refreshGrantType ?? "refresh_token";
+  const parse = provider.parseTokenResponse ?? defaultParseTokenResponse;
+  const requestToken = async body => {
+    const response = await fetch(provider.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`OAuth token request failed: ${response.status} ${response.statusText} ${text}`);
+    }
+    return parse(await response.json());
+  };
+  const refreshAccessToken = refreshToken => {
+    return requestToken(new URLSearchParams({
+      [clientIdParam]: provider.clientId,
+      [clientSecretParam]: provider.clientSecret,
+      grant_type: refreshGrantType,
+      refresh_token: refreshToken
+    }));
+  };
+  return {
+    buildAuthUrl: ({
+      redirectUri,
+      scope,
+      state,
+      extraParams
+    }) => {
+      const url = new URL(provider.authorizationUrl);
+      url.searchParams.set(clientIdParam, provider.clientId);
+      url.searchParams.set("response_type", "code");
+      url.searchParams.set("redirect_uri", redirectUri);
+      url.searchParams.set("scope", Array.isArray(scope) ? scope.join(scopeSeparator) : scope);
+      url.searchParams.set("state", state);
+      for (const [key, value] of Object.entries(extraParams ?? {})) url.searchParams.set(key, value);
+      return url.toString();
+    },
+    exchangeCode: ({
+      code,
+      redirectUri
+    }) => {
+      return requestToken(new URLSearchParams({
+        [clientIdParam]: provider.clientId,
+        [clientSecretParam]: provider.clientSecret,
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri
+      }));
+    },
+    refreshAccessToken,
+    getValidToken: async (record, options) => {
+      const refreshWindowMs = options.refreshWindowMs ?? 72e5;
+      if (record.accessTokenExpiresAt.getTime() - Date.now() > refreshWindowMs) return record.accessToken;
+      const updated = await refreshAccessToken(record.refreshToken);
+      await options.onRefresh(updated);
+      return updated.accessToken;
+    }
+  };
+};
+
+//#endregion
+//#region src/providers/tiktok.ts
+/**
+* Build an {@link OAuthClient} preconfigured for TikTok's Login Kit. Encodes
+* TikTok's deviations from RFC 6749: the client id is sent as `client_key` and
+* scopes are comma-separated. The token endpoint returns `open_id` alongside
+* the tokens, available on `TokenResponse.raw`.
+*/
+var createTikTokClient = options => {
+  return createOAuthClient({
+    authorizationUrl: "https://www.tiktok.com/v2/auth/authorize/",
+    tokenUrl: "https://open.tiktokapis.com/v2/oauth/token/",
+    clientId: options.clientKey,
+    clientSecret: options.clientSecret,
+    params: {
+      clientId: "client_key",
+      scopeSeparator: ","
+    }
+  });
+};
+
+//#endregion
+export { DEFAULT_REFRESH_WINDOW_MS as n, createOAuthClient as r, createTikTokClient as t };

package/dist/providers-FHRUbQH_.cjs

@@ -0,0 +1,124 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+//#region src/client.ts
+/** Default safety window for lazy refresh: 2 hours. */
+var DEFAULT_REFRESH_WINDOW_MS = 7200 * 1e3;
+var defaultParseTokenResponse = raw => {
+  return {
+    accessToken: String(raw.access_token),
+    refreshToken: String(raw.refresh_token),
+    expiresIn: Number(raw.expires_in),
+    raw
+  };
+};
+/**
+* Create an OAuth client for a generic {@link OAuthProvider}. The returned
+* client is stateless and delegates all persistence to its caller, making it
+* ORM- and storage-agnostic.
+*/
+var createOAuthClient = provider => {
+  const clientIdParam = provider.params?.clientId ?? "client_id";
+  const clientSecretParam = provider.params?.clientSecret ?? "client_secret";
+  const scopeSeparator = provider.params?.scopeSeparator ?? " ";
+  const refreshGrantType = provider.params?.refreshGrantType ?? "refresh_token";
+  const parse = provider.parseTokenResponse ?? defaultParseTokenResponse;
+  const requestToken = async body => {
+    const response = await fetch(provider.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`OAuth token request failed: ${response.status} ${response.statusText} ${text}`);
+    }
+    return parse(await response.json());
+  };
+  const refreshAccessToken = refreshToken => {
+    return requestToken(new URLSearchParams({
+      [clientIdParam]: provider.clientId,
+      [clientSecretParam]: provider.clientSecret,
+      grant_type: refreshGrantType,
+      refresh_token: refreshToken
+    }));
+  };
+  return {
+    buildAuthUrl: ({
+      redirectUri,
+      scope,
+      state,
+      extraParams
+    }) => {
+      const url = new URL(provider.authorizationUrl);
+      url.searchParams.set(clientIdParam, provider.clientId);
+      url.searchParams.set("response_type", "code");
+      url.searchParams.set("redirect_uri", redirectUri);
+      url.searchParams.set("scope", Array.isArray(scope) ? scope.join(scopeSeparator) : scope);
+      url.searchParams.set("state", state);
+      for (const [key, value] of Object.entries(extraParams ?? {})) url.searchParams.set(key, value);
+      return url.toString();
+    },
+    exchangeCode: ({
+      code,
+      redirectUri
+    }) => {
+      return requestToken(new URLSearchParams({
+        [clientIdParam]: provider.clientId,
+        [clientSecretParam]: provider.clientSecret,
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri
+      }));
+    },
+    refreshAccessToken,
+    getValidToken: async (record, options) => {
+      const refreshWindowMs = options.refreshWindowMs ?? 72e5;
+      if (record.accessTokenExpiresAt.getTime() - Date.now() > refreshWindowMs) return record.accessToken;
+      const updated = await refreshAccessToken(record.refreshToken);
+      await options.onRefresh(updated);
+      return updated.accessToken;
+    }
+  };
+};
+
+//#endregion
+//#region src/providers/tiktok.ts
+/**
+* Build an {@link OAuthClient} preconfigured for TikTok's Login Kit. Encodes
+* TikTok's deviations from RFC 6749: the client id is sent as `client_key` and
+* scopes are comma-separated. The token endpoint returns `open_id` alongside
+* the tokens, available on `TokenResponse.raw`.
+*/
+var createTikTokClient = options => {
+  return createOAuthClient({
+    authorizationUrl: "https://www.tiktok.com/v2/auth/authorize/",
+    tokenUrl: "https://open.tiktokapis.com/v2/oauth/token/",
+    clientId: options.clientKey,
+    clientSecret: options.clientSecret,
+    params: {
+      clientId: "client_key",
+      scopeSeparator: ","
+    }
+  });
+};
+
+//#endregion
+Object.defineProperty(exports, 'DEFAULT_REFRESH_WINDOW_MS', {
+  enumerable: true,
+  get: function () {
+    return DEFAULT_REFRESH_WINDOW_MS;
+  }
+});
+Object.defineProperty(exports, 'createOAuthClient', {
+  enumerable: true,
+  get: function () {
+    return createOAuthClient;
+  }
+});
+Object.defineProperty(exports, 'createTikTokClient', {
+  enumerable: true,
+  get: function () {
+    return createTikTokClient;
+  }
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ttoss/oauth-client",
+  "version": "0.1.0",
+  "description": "Reusable third-party OAuth 2.0 client for ttoss — authorization, code exchange, lazy and scheduled token refresh",
+  "keywords": [
+    "auth",
+    "oauth",
+    "oauth2",
+    "tiktok",
+    "ttoss"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ttoss/ttoss.git",
+    "directory": "packages/oauth-client"
+  },
+  "license": "MIT",
+  "author": "ttoss",
+  "contributors": [
+    "Pedro Arantes <pedro@arantespp.com> (https://arantespp.com)"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./providers": {
+      "import": "./dist/providers/index.mjs",
+      "require": "./dist/providers/index.cjs",
+      "types": "./dist/providers/index.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "jest": "^30.4.2",
+    "tsdown": "^0.22.2",
+    "@ttoss/auth-core": "^0.7.0",
+    "@ttoss/config": "^1.37.17"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "jest --projects tests/unit"
+  }
+}