@dcimorra/authhub-sdk 1.1.0

package/README.md

@@ -0,0 +1,225 @@
+# authhub-sdk
+
+Official TypeScript SDK for [Auth Hub](https://github.com/dcimorra/auth-hub) — self-hosted authentication, database, and storage as a service.
+
+## Install
+
+```bash
+npm install authhub-sdk
+```
+
+Or copy the `sdk/` directory into your project and import from it directly.
+
+## Quick Start
+
+```typescript
+import { AuthHubClient } from "authhub-sdk";
+
+const hub = new AuthHubClient({
+  baseUrl: "https://auth.example.com",
+  projectId: "your-project-uuid",
+  apiKey: "sk_your_api_key",
+});
+```
+
+## Authentication
+
+```typescript
+// Register
+await hub.auth.register("user@example.com", "securePassword123");
+
+// Login — tokens are stored automatically
+const { user } = await hub.auth.login("user@example.com", "securePassword123");
+
+// Get current user (auto-refreshes token if expired)
+const me = await hub.auth.getUser();
+
+// Change password
+await hub.auth.changePassword("oldPassword", "newPassword");
+
+// Password recovery flow
+await hub.auth.recover("user@example.com");
+// User receives email with token...
+await hub.auth.resetPassword(tokenFromEmail, "newPassword");
+
+// Logout — clears tokens locally and revokes on server
+await hub.auth.logout();
+
+// Check auth state
+const isLoggedIn = await hub.auth.isAuthenticated();
+```
+
+### Token Management
+
+Tokens are automatically stored and refreshed. You can customize the storage:
+
+```typescript
+// Browser (default): localStorage
+const hub = new AuthHubClient({ ..., tokenStore: "localStorage" });
+
+// Node.js (default): in-memory
+const hub = new AuthHubClient({ ..., tokenStore: "memory" });
+
+// Custom store (e.g. React Native AsyncStorage)
+const hub = new AuthHubClient({
+  ...,
+  tokenStore: {
+    get: (key) => AsyncStorage.getItem(key),
+    set: (key, value) => AsyncStorage.setItem(key, value),
+    remove: (key) => AsyncStorage.removeItem(key),
+  },
+});
+
+// Handle session expiry (refresh token expired/revoked)
+const hub = new AuthHubClient({
+  ...,
+  onSessionExpired: () => {
+    window.location.href = "/login";
+  },
+});
+```
+
+## Database
+
+Full CRUD with advanced query operators.
+
+```typescript
+// Insert
+const { rows } = await hub.db.create({
+  table: "products",
+  data: { name: "Widget", price: 29.99, active: true },
+});
+
+// Query with operators
+const { rows, count } = await hub.db.read({
+  table: "products",
+  select: ["id", "name", "price"],
+  where: {
+    price: { $gte: 10, $lte: 100 },
+    status: { $in: ["active", "sale"] },
+    deleted_at: { $is: null },
+  },
+  orderBy: [
+    { column: "price", order: "ASC" },
+    { column: "name", order: "DESC" },
+  ],
+  limit: 50,
+  offset: 0,
+});
+
+// Update
+await hub.db.update({
+  table: "products",
+  data: { price: 24.99 },
+  where: { id: 1 },
+});
+
+// Delete
+await hub.db.delete({
+  table: "products",
+  where: { active: false },
+});
+
+// Convenience methods
+const product = await hub.db.findById("products", 1);
+const user = await hub.db.findOne("users", { email: "alice@example.com" });
+const total = await hub.db.count("products", { active: true });
+```
+
+### Query Operators
+
+| Operator | SQL | Example |
+|----------|-----|---------|
+| `$eq` | `=` | `{ status: { $eq: "active" } }` |
+| `$neq` | `!=` | `{ role: { $neq: "admin" } }` |
+| `$gt` | `>` | `{ price: { $gt: 10 } }` |
+| `$gte` | `>=` | `{ age: { $gte: 18 } }` |
+| `$lt` | `<` | `{ stock: { $lt: 5 } }` |
+| `$lte` | `<=` | `{ priority: { $lte: 3 } }` |
+| `$in` | `IN (...)` | `{ status: { $in: ["a", "b"] } }` |
+| `$nin` | `NOT IN (...)` | `{ id: { $nin: [1, 2, 3] } }` |
+| `$like` | `LIKE` | `{ name: { $like: "%widget%" } }` |
+| `$ilike` | `ILIKE` | `{ name: { $ilike: "%Widget%" } }` |
+| `$is` | `IS` | `{ deleted_at: { $is: null } }` |
+| `$not` | `IS NOT` | `{ email: { $not: null } }` |
+
+## Storage
+
+File upload, download, and bucket management.
+
+```typescript
+// Create a bucket
+await hub.storage.createBucket({
+  name: "avatars",
+  isPublic: true,
+  maxFileSize: 5 * 1024 * 1024, // 5MB
+});
+
+// Upload a file (browser)
+const fileInput = document.querySelector<HTMLInputElement>("#file");
+await hub.storage.upload({
+  bucket: "avatars",
+  key: "users/user1.jpg",
+  file: fileInput.files[0],
+});
+
+// Upload from Node.js
+import { readFileSync } from "fs";
+await hub.storage.upload({
+  bucket: "avatars",
+  key: "users/user1.jpg",
+  file: readFileSync("photo.jpg"),
+  contentType: "image/jpeg",
+});
+
+// Download
+const response = await hub.storage.download("avatars", "users/user1.jpg");
+const blob = await response.blob(); // browser
+// or
+const buffer = await hub.storage.downloadBuffer("avatars", "users/user1.jpg");
+
+// Public URL (for <img src=...> etc.)
+const url = hub.storage.getPublicUrl("avatars", "users/user1.jpg");
+
+// List files
+const { objects, count } = await hub.storage.list({
+  bucket: "avatars",
+  prefix: "users/",
+  limit: 50,
+});
+
+// Delete
+await hub.storage.deleteObject("avatars", "users/user1.jpg");
+
+// Bucket management
+const buckets = await hub.storage.listBuckets();
+await hub.storage.deleteBucket("old-bucket");
+```
+
+## Error Handling
+
+All methods throw `AuthHubError` on failure:
+
+```typescript
+import { AuthHubError } from "authhub-sdk";
+
+try {
+  await hub.auth.login("user@example.com", "wrong-password");
+} catch (err) {
+  if (err instanceof AuthHubError) {
+    console.log(err.message); // "Invalid credentials"
+    console.log(err.status);  // 401
+    console.log(err.code);    // optional error code
+  }
+}
+```
+
+## Build from Source
+
+```bash
+cd sdk
+npm install
+npm run build
+```
+
+This produces `dist/` with CJS, ESM, and type declarations.

package/dist/index.d.mts

@@ -0,0 +1,458 @@
+interface AuthHubConfig {
+    /** Base URL of the Auth Hub instance (e.g. "https://auth.example.com") */
+    baseUrl: string;
+    /** Project UUID */
+    projectId: string;
+    /** Project API key (sk_...) */
+    apiKey: string;
+    /**
+     * Token storage strategy.
+     * - "localStorage" (default in browser) — persists across tabs/refreshes
+     * - "memory" (default in Node) — tokens lost on process exit
+     * - Custom object implementing TokenStore interface
+     */
+    tokenStore?: "localStorage" | "memory" | TokenStore;
+    /** Auto-refresh access token when expired. Default: true */
+    autoRefresh?: boolean;
+    /** Called when the session is lost (refresh token expired/revoked) */
+    onSessionExpired?: () => void;
+}
+interface TokenStore {
+    get(key: string): string | null | Promise<string | null>;
+    set(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+}
+interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+interface User {
+    id: string;
+    email: string;
+    confirmed_at: string | null;
+    created_at: string;
+    last_sign_in_at: string | null;
+    app_metadata: {
+        provider: string;
+    };
+    user_metadata: Record<string, unknown>;
+}
+interface AuthResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: "bearer";
+    expires_in: number;
+    user: User;
+}
+interface RegisterResponse {
+    message: string;
+    user: {
+        id: string;
+        email: string;
+    };
+}
+interface MessageResponse {
+    message: string;
+}
+interface SessionResponse {
+    user: User;
+}
+/** Comparison operators for where clauses */
+type WhereOperator = {
+    $eq: unknown;
+} | {
+    $neq: unknown;
+} | {
+    $gt: unknown;
+} | {
+    $gte: unknown;
+} | {
+    $lt: unknown;
+} | {
+    $lte: unknown;
+} | {
+    $in: unknown[];
+} | {
+    $nin: unknown[];
+} | {
+    $like: string;
+} | {
+    $ilike: string;
+} | {
+    $is: null | boolean;
+} | {
+    $not: null | boolean;
+};
+type WhereClause = Record<string, unknown | WhereOperator>;
+interface OrderBy {
+    column: string;
+    order?: "ASC" | "DESC";
+}
+interface DbReadOptions {
+    table: string;
+    select?: string[];
+    where?: WhereClause;
+    limit?: number;
+    offset?: number;
+    orderBy?: OrderBy | OrderBy[];
+}
+interface DbCreateOptions {
+    table: string;
+    data: Record<string, unknown>;
+}
+interface DbUpdateOptions {
+    table: string;
+    data: Record<string, unknown>;
+    where: WhereClause;
+}
+interface DbDeleteOptions {
+    table: string;
+    where: WhereClause;
+}
+interface DbReadResult<T = Record<string, unknown>> {
+    rows: T[];
+    count: number;
+}
+interface DbMutationResult<T = Record<string, unknown>> {
+    rows: T[];
+    [key: string]: unknown;
+}
+interface Bucket {
+    id: string;
+    name: string;
+    isPublic: boolean;
+    maxFileSize: number;
+    allowedMimeTypes: string | null;
+    createdAt: string;
+    _count?: {
+        objects: number;
+    };
+}
+interface StorageObject {
+    id: string;
+    key: string;
+    size: number;
+    mimeType: string;
+    bucketId: string;
+    createdAt: string;
+    updatedAt?: string;
+}
+interface StorageListResult {
+    objects: StorageObject[];
+    count: number;
+}
+interface CreateBucketOptions {
+    name: string;
+    isPublic?: boolean;
+    maxFileSize?: number;
+    allowedMimeTypes?: string;
+}
+interface UploadOptions {
+    bucket: string;
+    key: string;
+    file: Blob | File | Buffer;
+    contentType?: string;
+}
+interface ListObjectsOptions {
+    bucket: string;
+    prefix?: string;
+    limit?: number;
+    offset?: number;
+}
+type OAuthProvider = "google" | "github";
+interface OAuthHashParams {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_in: number;
+    provider: string;
+}
+interface RealtimeConfig {
+    /** WebSocket server URL (e.g. "ws://localhost:4000") */
+    url: string;
+    /** Project UUID */
+    projectId: string;
+}
+interface RealtimeMessage {
+    type: string;
+    channel?: string;
+    event?: string;
+    status?: string;
+    data?: Record<string, unknown>;
+    message?: string;
+}
+type RealtimeMutationHandler = (event: string, data: Record<string, unknown>) => void;
+interface SessionLoginResult$1 {
+    user: User;
+    /** Set-Cookie headers from Auth Hub — forward these to the browser response */
+    setCookieHeaders: string[];
+}
+interface AuthHubErrorData {
+    message: string;
+    code?: string;
+    status: number;
+}
+
+declare class MemoryTokenStore implements TokenStore {
+    private store;
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+declare class LocalStorageTokenStore implements TokenStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+declare class TokenManager {
+    private store;
+    constructor(store: TokenStore);
+    getTokens(): Promise<TokenPair | null>;
+    setTokens(tokens: TokenPair): Promise<void>;
+    clear(): Promise<void>;
+    isExpired(): Promise<boolean>;
+}
+
+declare class AuthHubClient {
+    private baseUrl;
+    private projectId;
+    private apiKey;
+    private tokens;
+    private autoRefresh;
+    private onSessionExpired?;
+    private refreshPromise;
+    /** Auth operations (register, login, logout, etc.) */
+    readonly auth: AuthModule;
+    /** Cookie-based session operations (for server-side Next.js / SSR apps) */
+    readonly session: SessionModule;
+    /** Database CRUD operations */
+    readonly db: DbModule;
+    /** File storage operations */
+    readonly storage: StorageModule;
+    /** OAuth social login helpers */
+    readonly oauth: OAuthModule;
+    constructor(config: AuthHubConfig);
+    /**
+     * Create a Realtime client for subscribing to database changes via WebSocket.
+     *
+     * ```ts
+     * const realtime = hub.realtime("ws://localhost:4000");
+     * await realtime.connect(accessToken);
+     * realtime.on("table:users", (event, data) => console.log(event, data));
+     * ```
+     */
+    realtime(wsUrl: string): RealtimeClient;
+    /** @internal */
+    _url(path: string): string;
+    /** @internal — API key auth request */
+    _apiRequest<T>(path: string, options?: RequestInit): Promise<T>;
+    /** @internal — Bearer JWT auth request (auto-refreshes if needed) */
+    _authRequest<T>(path: string, options?: RequestInit): Promise<T>;
+    /** @internal */
+    _handleResponse<T>(res: Response): Promise<T>;
+    /** @internal — Save tokens from an auth response */
+    _saveAuthTokens(response: AuthResponse): Promise<void>;
+    /** @internal — Get valid access token, refreshing if necessary */
+    private _getValidAccessToken;
+    /** @internal — Refresh with dedup (prevents concurrent refresh calls) */
+    private _refreshTokens;
+    /** Get the token manager (for advanced usage) */
+    getTokenManager(): TokenManager;
+}
+declare class AuthModule {
+    private client;
+    constructor(client: AuthHubClient);
+    /** Register a new user account */
+    register(email: string, password: string, redirectTo?: string): Promise<RegisterResponse>;
+    /** Login with email and password. Stores tokens automatically. */
+    login(email: string, password: string): Promise<AuthResponse>;
+    /** Logout — revokes tokens on server and clears local storage */
+    logout(): Promise<void>;
+    /** Get current authenticated user profile */
+    getUser(): Promise<User>;
+    /** Change password for the authenticated user */
+    changePassword(currentPassword: string, newPassword: string): Promise<MessageResponse>;
+    /** Request password recovery email */
+    recover(email: string): Promise<MessageResponse>;
+    /** Reset password using token from recovery email */
+    resetPassword(token: string, newPassword: string): Promise<MessageResponse>;
+    /**
+     * Refresh tokens using a refresh token.
+     * Normally called automatically — use this for manual refresh.
+     */
+    refreshToken(refreshToken: string): Promise<AuthResponse>;
+    /** Check if the user has a stored session (tokens exist and access token not expired) */
+    isAuthenticated(): Promise<boolean>;
+    /** Get the current access token (or null if not authenticated) */
+    getAccessToken(): Promise<string | null>;
+}
+declare class SessionModule {
+    private client;
+    constructor(client: AuthHubClient);
+    /**
+     * Create a cookie-based session (login).
+     * Returns the user and Set-Cookie headers that must be forwarded to the browser.
+     *
+     * Usage in Next.js API route:
+     * ```ts
+     * const { user, setCookieHeaders } = await hub.session.login(email, password);
+     * const response = NextResponse.json({ success: true });
+     * for (const h of setCookieHeaders) response.headers.append("Set-Cookie", h);
+     * ```
+     */
+    login(email: string, password: string): Promise<SessionLoginResult>;
+    /**
+     * Validate an existing session by forwarding browser cookies.
+     * Returns the user if valid, null if session is expired/invalid.
+     *
+     * Usage in Next.js:
+     * ```ts
+     * const cookieHeader = request.headers.get("cookie") || "";
+     * const user = await hub.session.validate(cookieHeader);
+     * ```
+     */
+    validate(cookieHeader: string): Promise<User | null>;
+    /**
+     * Destroy a cookie-based session (logout).
+     * Returns Set-Cookie headers that clear the session cookies in the browser.
+     *
+     * Usage in Next.js API route:
+     * ```ts
+     * const cookieHeader = request.headers.get("cookie") || "";
+     * const setCookieHeaders = await hub.session.logout(cookieHeader);
+     * const response = NextResponse.json({ success: true });
+     * for (const h of setCookieHeaders) response.headers.append("Set-Cookie", h);
+     * ```
+     */
+    logout(cookieHeader: string): Promise<string[]>;
+    /**
+     * Change password for a user identified by their session cookies.
+     * Extracts the access token from the cookie header and uses it for JWT auth.
+     */
+    changePassword(cookieHeader: string, currentPassword: string, newPassword: string): Promise<MessageResponse>;
+}
+interface SessionLoginResult {
+    user: User;
+    setCookieHeaders: string[];
+}
+declare class DbModule {
+    private client;
+    constructor(client: AuthHubClient);
+    /** Insert a row into a table */
+    create<T = Record<string, unknown>>(options: DbCreateOptions): Promise<DbMutationResult<T>>;
+    /** Query rows from a table with filtering, selection, ordering, pagination */
+    read<T = Record<string, unknown>>(options: DbReadOptions): Promise<DbReadResult<T>>;
+    /** Update rows matching a where clause */
+    update<T = Record<string, unknown>>(options: DbUpdateOptions): Promise<DbMutationResult<T>>;
+    /** Delete rows matching a where clause */
+    delete<T = Record<string, unknown>>(options: DbDeleteOptions): Promise<DbMutationResult<T>>;
+    /** Find one row by column value */
+    findOne<T = Record<string, unknown>>(table: string, where: Record<string, unknown>): Promise<T | null>;
+    /** Find one row by id */
+    findById<T = Record<string, unknown>>(table: string, id: unknown): Promise<T | null>;
+    /** Count rows matching a where clause */
+    count(table: string, where?: Record<string, unknown>): Promise<number>;
+}
+declare class StorageModule {
+    private client;
+    constructor(client: AuthHubClient);
+    /** Create a storage bucket */
+    createBucket(options: CreateBucketOptions): Promise<Bucket>;
+    /** List all buckets */
+    listBuckets(): Promise<Bucket[]>;
+    /** Delete a bucket and all its contents */
+    deleteBucket(name: string): Promise<void>;
+    /** Upload a file to a bucket */
+    upload(options: UploadOptions): Promise<StorageObject>;
+    /** Download a file. Returns the raw Response for streaming support. */
+    download(bucket: string, key: string): Promise<Response>;
+    /** Download a file and return it as a Buffer (Node) or ArrayBuffer (browser) */
+    downloadBuffer(bucket: string, key: string): Promise<ArrayBuffer>;
+    /** Get the public URL for a file (only works for public buckets) */
+    getPublicUrl(bucket: string, key: string): string;
+    /** Delete a file from a bucket */
+    deleteObject(bucket: string, key: string): Promise<void>;
+    /** List objects in a bucket */
+    list(options: ListObjectsOptions): Promise<StorageListResult>;
+}
+declare class OAuthModule {
+    private client;
+    constructor(client: AuthHubClient);
+    /**
+     * Get the URL to redirect the user to for OAuth login.
+     *
+     * ```ts
+     * const url = hub.oauth.getAuthUrl("google", "/dashboard");
+     * window.location.href = url;
+     * ```
+     */
+    getAuthUrl(provider: OAuthProvider, redirectTo?: string): string;
+    /**
+     * Parse OAuth tokens from the URL hash fragment after a redirect callback.
+     * Returns null if no tokens are found in the hash.
+     *
+     * ```ts
+     * const result = hub.oauth.handleCallback();
+     * if (result) {
+     *   console.log("Logged in via", result.provider, result.access_token);
+     *   // Tokens are automatically stored
+     * }
+     * ```
+     */
+    handleCallback(hash?: string): Promise<OAuthHashParams | null>;
+    /**
+     * Convenience: redirect to OAuth provider login page.
+     * Only works in browser environments.
+     */
+    signInWithProvider(provider: OAuthProvider, redirectTo?: string): void;
+}
+declare class RealtimeClient {
+    private config;
+    private ws;
+    private listeners;
+    private connected;
+    private authenticated;
+    constructor(config: RealtimeConfig);
+    /**
+     * Connect to the realtime server and authenticate.
+     *
+     * ```ts
+     * const realtime = hub.realtime("ws://localhost:4000");
+     * await realtime.connect(accessToken);
+     * ```
+     */
+    connect(accessToken: string): Promise<void>;
+    /**
+     * Subscribe to changes on a table.
+     *
+     * ```ts
+     * realtime.on("table:users", (event, data) => {
+     *   console.log(event); // "INSERT", "UPDATE", "DELETE"
+     *   console.log(data);  // { table, operation, id, timestamp }
+     * });
+     * ```
+     */
+    on(channel: string, handler: RealtimeMutationHandler): this;
+    /** Remove a specific handler from a channel */
+    off(channel: string, handler: RealtimeMutationHandler): this;
+    /**
+     * Subscribe to a table and send the subscribe message.
+     * Alias for `on()` that returns a Promise resolving when the server confirms.
+     */
+    subscribe(channel: string, handler: RealtimeMutationHandler): Promise<void>;
+    /** Unsubscribe from a channel (removes all handlers) */
+    unsubscribe(channel: string): void;
+    /** Close the WebSocket connection */
+    close(): void;
+    /** Check if connected and authenticated */
+    isConnected(): boolean;
+}
+
+declare class AuthHubError extends Error {
+    status: number;
+    code?: string;
+    constructor(data: AuthHubErrorData);
+}
+
+export { AuthHubClient, type AuthHubConfig, AuthHubError, type AuthHubErrorData, type AuthResponse, type Bucket, type CreateBucketOptions, type DbCreateOptions, type DbDeleteOptions, type DbMutationResult, type DbReadOptions, type DbReadResult, type DbUpdateOptions, type ListObjectsOptions, LocalStorageTokenStore, MemoryTokenStore, type MessageResponse, type OAuthHashParams, type OAuthProvider, type OrderBy, RealtimeClient, type RealtimeConfig, type RealtimeMessage, type RealtimeMutationHandler, type RegisterResponse, type SessionLoginResult$1 as SessionLoginResult, type SessionResponse, type StorageListResult, type StorageObject, TokenManager, type TokenPair, type TokenStore, type UploadOptions, type User, type WhereClause, type WhereOperator };