Intro

Avanta is a super-lightweight (sub 100kB) TypeScript-first OAuth library for teams who want prebuilt providers with full type safety and zero framework lock-in.

If you like the convenience of NextAuth or Lucia, but want something that:

• gives you full control over the OAuth flow (no magic, no sessions, no database)
• returns scope-aware typed data (request email and guilds? the return type includes exactly those fields)
• uses only the Fetch API (works in Bun, Node 18+, Deno, Cloudflare Workers)
• has zero dependencies

Avanta is a good fit.

It gives you:

• 5 prebuilt providers: Discord, GitHub, Google, Microsoft, Twitch, and more to come
• Scope-level typing: the data you get back is typed to the exact scopes you requested
• Token management: TokenStore with built-in refresh, serialization, and expiry tracking
• Scope-dependent actions: Discord's guilds.join and guilds.members.read are only available when you request those scopes

Table of contents

• Quickstart
• Providers
  • Discord
  • GitHub
  • Google
  • Microsoft
  • Twitch
• TokenStore
• Common API
• Scope-dependent actions (Discord)
• Framework examples
• API reference
• Contributor docs
• License

Quickstart

Install:

bun add avanta

Other package managers:

pnpm add avanta
npm i avanta

1) Create a provider

Every provider takes the same shape: clientId, clientSecret, redirectUri, and scopes. The scopes you pass in determine the return type of getData().

import Avanta from "avanta";

const discord = new Avanta.DiscordProvider({
    clientId: process.env.DISCORD_CLIENT_ID!,
    clientSecret: process.env.DISCORD_CLIENT_SECRET!,
    redirectUri: "http://localhost:3000/auth/discord/callback",
    scopes: ["identify", "email", "guilds"],
});

2) Redirect the user to the OAuth page

Generate the authorization URL and redirect the user to it. You can optionally pass a state parameter for CSRF protection.

const url = discord.getOAuthUrl("random-state-string");
// Redirect the user to `url`

3) Exchange the code for tokens

When the user is redirected back, exchange the authorization code for a TokenStore:

const tokenStore = await discord.getTokenStore(code);

The TokenStore holds the access token, refresh token, and expiry timestamp. You can serialize it to JSON for storage:

const serialized = tokenStore.compress(); // JSON string

And restore it later:

import { TokenStore } from "avanta"; // or from the util path
const restored = TokenStore.extract(serialized);

4) Fetch user data

Call getData() with the token store. The return type is automatically narrowed to the scopes you configured:

const data = await discord.getData(tokenStore);

// Because we requested ["identify", "email", "guilds"]:
data.username; // string     (from "identify")
data.email; // string     (from "email")
data.guilds; // Array<...> (from "guilds")
data.tokenStore; // TokenStore (always present, may be refreshed)

If a scope wasn't requested, the field doesn't exist on the type — no runtime checks needed.

Providers

All providers share the same constructor shape and public API. The only differences are the available scopes and the shape of the returned data.

Discord

const discord = new Avanta.DiscordProvider({
    clientId: "...",
    clientSecret: "...",
    redirectUri: "...",
    scopes: ["identify", "email", "guilds", "connections"],
});

Available scopes:

| Scope | Data returned | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | identify | id, username, avatar, discriminator, global_name, banner, accent_color, locale, mfa_enabled, premium_type, public_flags | | email | email, verified | | guilds | guilds (array of partial guild objects) | | connections | connections (array of connection objects) | | guilds.join | Enables actions.guilds.join(...) | | guilds.members.read | Enables actions.guilds.members.read(...) | | gdm.join | Group DM join capability | | role_connections.write | Role connection metadata write | | dm_channels.read | DM channel read access |

GitHub

const github = new Avanta.GitHubProvider({
    clientId: "...",
    clientSecret: "...",
    redirectUri: "...",
    scopes: ["read:user", "user:email", "read:org"],
});

Available scopes:

| Scope | Data returned | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | read:user | login, id, node_id, avatar_url, html_url, name, company, blog, location, bio, twitter_username, public_repos, public_gists, followers, following, created_at, updated_at | | user:email | emails (array with email, primary, verified, visibility) | | read:org | orgs (array with login, id, node_id, avatar_url, description) |

Note: GitHub only issues refresh tokens when token expiration is enabled on the GitHub App. If your app doesn't have token expiration, refreshTokens() will throw.

Google

const google = new Avanta.GoogleProvider({
    clientId: "...",
    clientSecret: "...",
    redirectUri: "...",
    scopes: ["openid", "profile", "email"],
});

Available scopes:

| Scope | Data returned | | --------- | -------------------------------------------------------- | | openid | sub (stable Google account ID) | | profile | name, given_name, family_name, picture, locale | | email | email, email_verified |

Google's OAuth URL automatically requests offline access and consent prompt for refresh token support.

Microsoft

const microsoft = new Avanta.MicrosoftProvider({
    clientId: "...",
    clientSecret: "...",
    redirectUri: "...",
    scopes: ["User.Read", "Organization.Read.All", "offline_access"],
});

Available scopes:

| Scope | Data returned | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User.Read | id, displayName, givenName, surname, mail, userPrincipalName, jobTitle, officeLocation, businessPhones, mobilePhone, preferredLanguage, avatarUrl | | Organization.Read.All | organization (object with id, displayName, address fields, verifiedDomains, or null for personal accounts) | | offline_access | Enables refresh tokens (no data fields) |

Note: The avatarUrl field requires the access token to fetch the actual image bytes. Personal Microsoft accounts may have mail as null — use userPrincipalName as a fallback.

Twitch

const twitch = new Avanta.TwitchProvider({
    clientId: "...",
    clientSecret: "...",
    redirectUri: "...",
    scopes: ["user:read:email"],
});

Twitch always returns base profile data regardless of scopes:

| Field | Description | | ------------------- | --------------------------------------------------------- | | id | Unique Twitch numeric ID (as string) | | login | Lowercase login name | | display_name | Case-preserved display name | | type | Account type ("", "admin", "staff", "global_mod") | | broadcaster_type | "", "affiliate", or "partner" | | description | Channel bio | | profile_image_url | Profile image URL | | offline_image_url | Offline stream image URL | | created_at | ISO 8601 account creation date |

Additional scopes:

| Scope | Data returned | | ----------------- | ------------- | | user:read:email | email |

TokenStore

TokenStore is a small utility class that holds OAuth tokens and manages serialization.

import Avanta from "avanta";

// Created automatically by getTokenStore()
const tokenStore = await provider.getTokenStore(code);

// Properties
tokenStore.access_token; // string
tokenStore.refresh_token; // string
tokenStore.access_token_expires_at; // number (ms since epoch)

// Serialize to JSON string (for database storage, cookies, etc.)
const json = tokenStore.compress();

// Restore from JSON string
const restored = TokenStore.extract(json);

When you call getData(), Avanta automatically refreshes the access token if it has expired. The returned data.tokenStore may be a new instance with fresh tokens — always persist the returned token store.

const data = await discord.getData(tokenStore);

// IMPORTANT: persist the (possibly refreshed) token store
await db.user.update({
    where: { id: userId },
    data: { tokens: data.tokenStore.compress() },
});

Common API

Every provider exposes the same methods:

| Method | Description | | ------------------------------- | ---------------------------------------------------------------------------------------- | | getOAuthUrl(state?) | Returns the full authorization URL. Pass an optional state string for CSRF protection. | | getTokens(code) | Exchanges an authorization code for raw token data (provider-specific shape). | | getTokenStore(code) | Exchanges a code for a TokenStore (recommended over getTokens). | | refreshTokens(tokenStore) | Refreshes the access token using the refresh token. Returns raw token data. | | refreshTokenStore(tokenStore) | Refreshes and returns a new TokenStore. | | getData(tokenStore) | Fetches all user data for the configured scopes. Auto-refreshes expired tokens. |

Scope-dependent actions (Discord)

Discord's provider exposes an actions object whose methods are typed based on the scopes you requested.

guilds.join — Join a user to a guild

Requires the guilds.join scope and a bot token with CREATE_INSTANT_INVITE permission in the target guild.

const discord = new Avanta.DiscordProvider({
    clientId: "...",
    clientSecret: "...",
    redirectUri: "...",
    scopes: ["identify", "guilds.join"],
});

const result = await discord.actions.guilds.join({
    guildId: "123456789",
    tokenStore,
    botToken: process.env.DISCORD_BOT_TOKEN!,
    options: {
        nick: "New Member",
        roles: ["role-id-1"],
        mute: false,
        deaf: false,
    },
});
// result.data is the guild member object (or null if already a member)
// result.tokenStore is the (possibly refreshed) token store

guilds.members.read — Read guild member data

Requires the guilds.members.read scope.

const discord = new Avanta.DiscordProvider({
    clientId: "...",
    clientSecret: "...",
    redirectUri: "...",
    scopes: ["identify", "guilds.members.read"],
});

const result = await discord.actions.guilds.members.read({
    guildId: "123456789",
    tokenStore,
});
// result.data is the guild member object

If you don't request these scopes, discord.actions won't have these methods at the type level — TypeScript prevents you from calling them.

Framework examples

Next.js (App Router)

// app/auth/discord/route.ts
import Avanta from "avanta";

const discord = new Avanta.DiscordProvider({
    clientId: process.env.DISCORD_CLIENT_ID!,
    clientSecret: process.env.DISCORD_CLIENT_SECRET!,
    redirectUri: "http://localhost:3000/auth/discord/callback",
    scopes: ["identify", "email"],
});

export async function GET() {
    const url = discord.getOAuthUrl();
    return Response.redirect(url);
}

// app/auth/discord/callback/route.ts
export async function GET(req: Request) {
    const url = new URL(req.url);
    const code = url.searchParams.get("code")!;

    const tokenStore = await discord.getTokenStore(code);
    const data = await discord.getData(tokenStore);

    // data.username, data.email, data.tokenStore
    // Store in your database, set a session cookie, etc.

    return Response.redirect("/dashboard");
}

Express / Bun / any Request-based server

import Avanta from "avanta";

const github = new Avanta.GitHubProvider({
    clientId: process.env.GITHUB_CLIENT_ID!,
    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    redirectUri: "http://localhost:3000/auth/github/callback",
    scopes: ["read:user", "user:email"],
});

// Redirect route
app.get("/auth/github", (req, res) => {
    res.redirect(github.getOAuthUrl());
});

// Callback route
app.get("/auth/github/callback", async (req, res) => {
    const code = req.query.code as string;
    const tokenStore = await github.getTokenStore(code);
    const data = await github.getData(tokenStore);

    // data.login, data.emails, data.tokenStore
    res.json({ user: data.login, emails: data.emails });
});

API reference

Exports

The default export is an object containing all providers:

import {
    DiscordProvider,
    GitHubProvider,
    GoogleProvider,
    MicrosoftProvider,
    TwitchProvider,
} from "avanta";

Provider constructor

All providers accept the same options:

{
    clientId: string;
    clientSecret: string;
    redirectUri: string;
    scopes: [...Scope[]]; // const tuple — drives return type inference
}

TokenStore

| Property / Method | Type | Description | | -------------------------- | --------------------- | ----------------------------------------------- | | access_token | string | The current access token | | refresh_token | string | The refresh token (empty string if unavailable) | | access_token_expires_at | number | Expiry as ms since epoch | | compress() | string | JSON-serialized token data | | compressed | string (getter) | Alias for compress() | | TokenStore.extract(json) | TokenStore (static) | Deserialize from JSON string |

Contributor docs

• Implementation + extension guide: FOR_AGENTS.md

License

MIT