@dcimorra/authhub-sdk 1.1.0

package/dist/index.d.ts

@@ -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 };