auth101

TypeScript client for auth101 — simple email/password authentication for Python backends (FastAPI, Flask, Django).

Installation

npm install auth101
# or
pnpm add auth101
# or
yarn add auth101

Quick Start

import { createAuth101Client } from "auth101"

const auth = createAuth101Client({
  baseURL: "http://localhost:8000/auth", // where auth101 is mounted on your backend
})

Usage

All methods return { data, error }. Exactly one of them will be non-null.

Sign Up

const { data, error } = await auth.signUp({
  email: "[email protected]",
  password: "hunter2",
})

if (error) {
  console.error(error.message, error.code)
} else {
  console.log(data.user)   // { id, email, is_active }
  console.log(data.token)  // JWT — stored automatically
}

Sign In

const { data, error } = await auth.signIn({
  email: "[email protected]",
  password: "hunter2",
})

if (data) {
  console.log("Welcome back,", data.user.email)
}

Get Session

Reads the stored token and asks the backend to return the current user.

const { data, error } = await auth.getSession()

if (data) {
  console.log("Logged in as", data.user.email)
} else {
  console.log("Not authenticated:", error?.code)
}

Sign Out

Notifies the backend (best-effort) and clears the local token.

const { data, error } = await auth.signOut()
// data.success === true

Token Helpers

auth.getToken()        // → string | null
auth.setToken(jwt)     // store a token manually
auth.clearToken()      // remove the stored token

Configuration

const auth = createAuth101Client({
  // Required: base URL where auth101 is mounted
  baseURL: "https://api.myapp.com/auth",

  // Optional: custom storage (defaults to localStorage in browsers)
  storage: sessionStorage,

  // Pass null to keep the token in memory only (useful for SSR)
  // storage: null,

  // Optional: key used in storage (default: "auth101_token")
  storageKey: "myapp_token",

  // Optional: default fetch options merged into every request
  fetchOptions: {
    credentials: "include",
  },
})

Custom Storage

Any object with getItem, setItem, and removeItem works:

const auth = createAuth101Client({
  baseURL: "...",
  storage: {
    getItem: (key) => cookies.get(key) ?? null,
    setItem: (key, value) => cookies.set(key, value),
    removeItem: (key) => cookies.delete(key),
  },
})

TypeScript

All types are exported:

import type {
  User,
  AuthResult,
  BackendError,
  SignUpInput,
  SignInInput,
  SignUpResponse,
  SignInResponse,
  SignOutResponse,
  SessionResponse,
  Auth101ClientOptions,
  StorageLike,
} from "auth101"

Backend Endpoints

The client maps to these endpoints exposed by the Python auth101 package:

| Method | Path | Description | |--------|------|-------------| | POST | /sign-up/email | Register a new user | | POST | /sign-in/email | Sign in an existing user | | POST | /sign-out | Acknowledge sign-out | | GET | /session | Get current user from token |

Error Codes

| Code | Meaning | |------|---------| | VALIDATION_ERROR | Missing or invalid input | | USER_EXISTS | Email is already registered | | INVALID_CREDENTIALS | Wrong email or password | | INVALID_TOKEN | JWT is malformed or expired | | UNAUTHORIZED | No valid token provided | | USER_NOT_FOUND | Token valid but user deleted | | NETWORK_ERROR | Could not reach the server | | PARSE_ERROR | Server returned non-JSON | | HTTP_ERROR | Non-2xx response with no error body |

License

MIT