@wowsql/sdk 3.4.0

package/dist/auth.d.ts

@@ -0,0 +1,160 @@
+export interface ProjectAuthClientConfig {
+    /** Project slug or full URL (e.g., `myproject` or `https://myproject.wowsql.com`) */
+    projectUrl: string;
+    /** Override for wowsql.com when using custom domains */
+    baseDomain?: string;
+    /** Use HTTPS (default true) */
+    secure?: boolean;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Optional public API key for analytics/future enforcement */
+    publicApiKey?: string;
+    /** Custom token storage implementation (defaults to in-memory) */
+    storage?: AuthTokenStorage;
+}
+export interface AuthTokenStorage {
+    getAccessToken(): string | null;
+    setAccessToken(token: string | null): void;
+    getRefreshToken(): string | null;
+    setRefreshToken(token: string | null): void;
+}
+export interface AuthUser {
+    id: string;
+    email: string;
+    fullName?: string | null;
+    avatarUrl?: string | null;
+    emailVerified: boolean;
+    userMetadata: Record<string, any>;
+    appMetadata: Record<string, any>;
+    createdAt?: string | null;
+}
+export interface SignUpParams {
+    email: string;
+    password: string;
+    full_name?: string;
+    fullName?: string;
+    user_metadata?: Record<string, any>;
+    userMetadata?: Record<string, any>;
+}
+export interface SignInParams {
+    email: string;
+    password: string;
+}
+export interface AuthSession {
+    accessToken: string;
+    refreshToken: string;
+    tokenType: string;
+    expiresIn: number;
+}
+export interface AuthResponse {
+    user?: AuthUser;
+    session: AuthSession;
+}
+export interface OAuthAuthorizeResponse {
+    authorizationUrl: string;
+    provider: string;
+    redirectUri: string;
+    backendCallbackUrl?: string;
+    frontendRedirectUri?: string;
+}
+export declare class ProjectAuthClient {
+    private readonly config;
+    private readonly client;
+    private readonly storage;
+    private accessToken;
+    private refreshToken;
+    constructor(config: ProjectAuthClientConfig);
+    /**
+     * Register a new end user for the project.
+     */
+    signUp(payload: SignUpParams): Promise<AuthResponse>;
+    /**
+     * Authenticate an existing user.
+     */
+    signIn(payload: SignInParams): Promise<AuthResponse>;
+    /**
+     * Retrieve the current authenticated user.
+     */
+    getUser(accessToken?: string): Promise<AuthUser>;
+    /**
+     * Fetch the OAuth authorization URL for a configured provider.
+     */
+    /**
+     * Get OAuth authorization URL for the specified provider.
+     *
+     * @param provider OAuth provider name (e.g., 'github', 'google', 'facebook', 'microsoft')
+     * @param redirectUri The redirect URI where the OAuth provider will send the user after authorization.
+     *                    Must match the redirect URI configured in the OAuth provider settings.
+     * @returns Promise resolving to OAuth authorization URL and metadata
+     * @throws {WOWSQLError} If the request fails or the provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const auth = new ProjectAuthClient({ projectUrl: 'myproject' });
+     * const result = await auth.getOAuthAuthorizationUrl(
+     *   'github',
+     *   'http://localhost:5000/auth/github/callback'
+     * );
+     * console.log(result.authorizationUrl);
+     * ```
+     */
+    getOAuthAuthorizationUrl(provider: string, redirectUri: string): Promise<OAuthAuthorizeResponse>;
+    /**
+     * Exchange OAuth callback code for access tokens.
+     *
+     * After the user authorizes with the OAuth provider, the provider redirects
+     * back with a code. Call this method to exchange that code for JWT tokens.
+     *
+     * @param provider - OAuth provider name (e.g., 'github', 'google')
+     * @param code - Authorization code from OAuth provider callback
+     * @param redirectUri - Optional redirect URI (uses configured one if not provided)
+     * @returns AuthResponse with session tokens and user info
+     */
+    exchangeOAuthCallback(provider: string, code: string, redirectUri?: string): Promise<AuthResponse>;
+    /**
+     * Request password reset.
+     *
+     * Sends a password reset email to the user if they exist.
+     * Always returns success to prevent email enumeration.
+     *
+     * @param email - User's email address
+     * @returns Object with success status and message
+     */
+    forgotPassword(email: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Reset password with token.
+     *
+     * Validates the reset token and updates the user's password.
+     *
+     * @param token - Password reset token from email
+     * @param newPassword - New password (minimum 8 characters)
+     * @returns Object with success status and message
+     */
+    resetPassword(token: string, newPassword: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Get the current session tokens.
+     */
+    getSession(): {
+        accessToken: string | null;
+        refreshToken: string | null;
+    };
+    /**
+     * Override stored session tokens (useful for SSR or persisted sessions).
+     */
+    setSession(session: {
+        accessToken: string;
+        refreshToken?: string | null;
+    }): void;
+    /**
+     * Clear all stored tokens.
+     */
+    clearSession(): void;
+    private persistSession;
+    private toWowError;
+}

package/dist/auth.js

@@ -0,0 +1,320 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectAuthClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const errors_1 = require("./errors");
+class MemoryAuthTokenStorage {
+    constructor() {
+        this.accessToken = null;
+        this.refreshToken = null;
+    }
+    getAccessToken() {
+        return this.accessToken;
+    }
+    setAccessToken(token) {
+        this.accessToken = token;
+    }
+    getRefreshToken() {
+        return this.refreshToken;
+    }
+    setRefreshToken(token) {
+        this.refreshToken = token;
+    }
+}
+class ProjectAuthClient {
+    constructor(config) {
+        this.config = config;
+        const baseUrl = buildAuthBaseUrl(config.projectUrl, config.baseDomain, config.secure);
+        this.storage = config.storage || new MemoryAuthTokenStorage();
+        this.accessToken = this.storage.getAccessToken();
+        this.refreshToken = this.storage.getRefreshToken();
+        this.client = axios_1.default.create({
+            baseURL: baseUrl,
+            timeout: config.timeout ?? 30000,
+            headers: {
+                'Content-Type': 'application/json',
+                ...(config.publicApiKey ? { 'X-Wow-Public-Key': config.publicApiKey } : {}),
+            },
+        });
+    }
+    /**
+     * Register a new end user for the project.
+     */
+    async signUp(payload) {
+        try {
+            const response = await this.client.post('/signup', normalizeSignUpPayload(payload));
+            const session = this.persistSession(response.data);
+            const user = response.data.user ? mapUser(response.data.user) : undefined;
+            return { user, session };
+        }
+        catch (error) {
+            throw this.toWowError(error);
+        }
+    }
+    /**
+     * Authenticate an existing user.
+     */
+    async signIn(payload) {
+        try {
+            const response = await this.client.post('/login', payload);
+            const session = this.persistSession(response.data);
+            return { session };
+        }
+        catch (error) {
+            throw this.toWowError(error);
+        }
+    }
+    /**
+     * Retrieve the current authenticated user.
+     */
+    async getUser(accessToken) {
+        const token = accessToken || this.accessToken || this.storage.getAccessToken();
+        if (!token) {
+            throw new errors_1.WOWSQLError('Access token is required. Please sign in first.');
+        }
+        try {
+            const response = await this.client.get('/me', {
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                },
+            });
+            return mapUser(response.data);
+        }
+        catch (error) {
+            throw this.toWowError(error);
+        }
+    }
+    /**
+     * Fetch the OAuth authorization URL for a configured provider.
+     */
+    /**
+     * Get OAuth authorization URL for the specified provider.
+     *
+     * @param provider OAuth provider name (e.g., 'github', 'google', 'facebook', 'microsoft')
+     * @param redirectUri The redirect URI where the OAuth provider will send the user after authorization.
+     *                    Must match the redirect URI configured in the OAuth provider settings.
+     * @returns Promise resolving to OAuth authorization URL and metadata
+     * @throws {WOWSQLError} If the request fails or the provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const auth = new ProjectAuthClient({ projectUrl: 'myproject' });
+     * const result = await auth.getOAuthAuthorizationUrl(
+     *   'github',
+     *   'http://localhost:5000/auth/github/callback'
+     * );
+     * console.log(result.authorizationUrl);
+     * ```
+     */
+    async getOAuthAuthorizationUrl(provider, redirectUri) {
+        if (!redirectUri || !redirectUri.trim()) {
+            throw new errors_1.WOWSQLError('redirectUri is required and cannot be empty');
+        }
+        if (!provider || !provider.trim()) {
+            throw new errors_1.WOWSQLError('provider is required and cannot be empty');
+        }
+        // Ensure redirectUri is properly formatted
+        redirectUri = redirectUri.trim();
+        try {
+            const response = await this.client.get(`/oauth/${provider}`, {
+                params: { frontend_redirect_uri: redirectUri },
+            });
+            return {
+                authorizationUrl: response.data.authorization_url,
+                provider: response.data.provider,
+                redirectUri: response.data.redirect_uri || response.data.backend_callback_url || '',
+                backendCallbackUrl: response.data.backend_callback_url,
+                frontendRedirectUri: response.data.frontend_redirect_uri,
+            };
+        }
+        catch (error) {
+            const axiosError = error;
+            if (axiosError.response?.status === 502) {
+                throw new errors_1.WOWSQLError(`Bad Gateway (502): The backend server may be down or unreachable. ` +
+                    `Check if the backend is running and accessible at ${this.client.defaults.baseURL}`, 502, axiosError.response?.data);
+            }
+            else if (axiosError.response?.status === 400) {
+                throw new errors_1.WOWSQLError(`Bad Request (400): ${axiosError.message}. ` +
+                    `Ensure OAuth provider '${provider}' is configured and enabled for this project.`, 400, axiosError.response?.data);
+            }
+            throw this.toWowError(error);
+        }
+    }
+    /**
+     * Exchange OAuth callback code for access tokens.
+     *
+     * After the user authorizes with the OAuth provider, the provider redirects
+     * back with a code. Call this method to exchange that code for JWT tokens.
+     *
+     * @param provider - OAuth provider name (e.g., 'github', 'google')
+     * @param code - Authorization code from OAuth provider callback
+     * @param redirectUri - Optional redirect URI (uses configured one if not provided)
+     * @returns AuthResponse with session tokens and user info
+     */
+    async exchangeOAuthCallback(provider, code, redirectUri) {
+        try {
+            const response = await this.client.post(`/oauth/${provider}/callback`, {
+                code,
+                redirect_uri: redirectUri,
+            });
+            const session = this.persistSession(response.data);
+            const user = response.data.user ? mapUser(response.data.user) : undefined;
+            return { user, session };
+        }
+        catch (error) {
+            throw this.toWowError(error);
+        }
+    }
+    /**
+     * Request password reset.
+     *
+     * Sends a password reset email to the user if they exist.
+     * Always returns success to prevent email enumeration.
+     *
+     * @param email - User's email address
+     * @returns Object with success status and message
+     */
+    async forgotPassword(email) {
+        try {
+            const response = await this.client.post('/forgot-password', { email });
+            return {
+                success: response.data.success ?? true,
+                message: response.data.message ?? 'If that email exists, a password reset link has been sent'
+            };
+        }
+        catch (error) {
+            throw this.toWowError(error);
+        }
+    }
+    /**
+     * Reset password with token.
+     *
+     * Validates the reset token and updates the user's password.
+     *
+     * @param token - Password reset token from email
+     * @param newPassword - New password (minimum 8 characters)
+     * @returns Object with success status and message
+     */
+    async resetPassword(token, newPassword) {
+        try {
+            const response = await this.client.post('/reset-password', {
+                token,
+                new_password: newPassword
+            });
+            return {
+                success: response.data.success ?? true,
+                message: response.data.message ?? 'Password reset successfully! You can now login with your new password'
+            };
+        }
+        catch (error) {
+            throw this.toWowError(error);
+        }
+    }
+    /**
+     * Get the current session tokens.
+     */
+    getSession() {
+        return {
+            accessToken: this.accessToken || this.storage.getAccessToken(),
+            refreshToken: this.refreshToken || this.storage.getRefreshToken(),
+        };
+    }
+    /**
+     * Override stored session tokens (useful for SSR or persisted sessions).
+     */
+    setSession(session) {
+        this.accessToken = session.accessToken;
+        this.refreshToken = session.refreshToken ?? null;
+        this.storage.setAccessToken(this.accessToken);
+        this.storage.setRefreshToken(this.refreshToken);
+    }
+    /**
+     * Clear all stored tokens.
+     */
+    clearSession() {
+        this.accessToken = null;
+        this.refreshToken = null;
+        this.storage.setAccessToken(null);
+        this.storage.setRefreshToken(null);
+    }
+    persistSession(raw) {
+        const session = mapSession(raw);
+        this.accessToken = session.accessToken;
+        this.refreshToken = session.refreshToken;
+        this.storage.setAccessToken(session.accessToken);
+        this.storage.setRefreshToken(session.refreshToken);
+        return session;
+    }
+    toWowError(error) {
+        if (error instanceof errors_1.WOWSQLError) {
+            return error;
+        }
+        if (axios_1.default.isAxiosError(error)) {
+            const axiosError = error;
+            const status = axiosError.response?.status;
+            const detail = axiosError.response?.data?.detail ||
+                axiosError.response?.data?.message ||
+                axiosError.message;
+            return new errors_1.WOWSQLError(detail || 'Request failed', status, axiosError.response?.data);
+        }
+        return new errors_1.WOWSQLError(error?.message || 'Unknown error');
+    }
+}
+exports.ProjectAuthClient = ProjectAuthClient;
+function buildAuthBaseUrl(projectUrl, baseDomain = 'wowsql.com', secure = true) {
+    let normalized = projectUrl.trim();
+    // If it's already a full URL, use it as-is
+    if (normalized.startsWith('http://') || normalized.startsWith('https://')) {
+        normalized = normalized.replace(/\/+$/, '');
+        if (normalized.endsWith('/api')) {
+            normalized = normalized.slice(0, -4);
+        }
+        return `${normalized}/api/auth`;
+    }
+    // If it already contains the base domain, don't append it again
+    if (normalized.includes(`.${baseDomain}`) || normalized.endsWith(baseDomain)) {
+        const protocol = secure ? 'https' : 'http';
+        normalized = `${protocol}://${normalized}`;
+    }
+    else {
+        // Just a project slug, append domain
+        const protocol = secure ? 'https' : 'http';
+        normalized = `${protocol}://${normalized}.${baseDomain}`;
+    }
+    normalized = normalized.replace(/\/+$/, '');
+    if (normalized.endsWith('/api')) {
+        normalized = normalized.slice(0, -4);
+    }
+    return `${normalized}/api/auth`;
+}
+function normalizeSignUpPayload(payload) {
+    return {
+        email: payload.email,
+        password: payload.password,
+        full_name: payload.full_name ?? payload.fullName,
+        user_metadata: payload.user_metadata ?? payload.userMetadata,
+    };
+}
+function mapSession(data) {
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        tokenType: data.token_type ?? 'bearer',
+        expiresIn: data.expires_in ?? 0,
+    };
+}
+function mapUser(data) {
+    return {
+        id: data.id,
+        email: data.email,
+        fullName: data.full_name ?? data.fullName ?? null,
+        avatarUrl: data.avatar_url ?? data.avatarUrl ?? null,
+        emailVerified: Boolean(data.email_verified ?? data.emailVerified),
+        userMetadata: data.user_metadata ?? data.userMetadata ?? {},
+        appMetadata: data.app_metadata ?? data.appMetadata ?? {},
+        createdAt: data.created_at ?? data.createdAt ?? null,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class WOWSQLError extends Error {
+    statusCode?: number | undefined;
+    response?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WOWSQLError = void 0;
+class WOWSQLError extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.statusCode = statusCode;
+        this.response = response;
+        this.name = 'WOWSQLError';
+    }
+}
+exports.WOWSQLError = WOWSQLError;

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+/**
+ * WowSQL TypeScript SDK
+ * Official client library for WowSQL REST API v2
+ *
+ * @version 2.0.0
+ * @license MIT
+ * @see https://github.com/wowsql/wowsql
+ */
+import { AxiosInstance } from 'axios';
+export interface WowSQLConfig {
+    /** Project subdomain or full URL (e.g., 'myproject' or 'https://myproject.wowsql.com') */
+    projectUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Base domain (default: wowsql.com) */
+    baseDomain?: string;
+    /** Use HTTPS (default: true) */
+    secure?: boolean;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+export interface QueryOptions {
+    /** Columns to select (comma-separated or array) */
+    select?: string | string[];
+    /** Filter expressions */
+    filter?: FilterExpression | FilterExpression[];
+    /** Column to sort by */
+    order?: string;
+    /** Sort direction */
+    orderDirection?: 'asc' | 'desc';
+    /** Maximum records to return */
+    limit?: number;
+    /** Number of records to skip */
+    offset?: number;
+}
+export interface FilterExpression {
+    column: string;
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'is';
+    value: string | number | boolean | null;
+}
+export interface QueryResponse<T = any> {
+    data: T[];
+    count: number;
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface CreateResponse {
+    id: number | string;
+    message: string;
+}
+export interface UpdateResponse {
+    message: string;
+    affected_rows: number;
+}
+export interface DeleteResponse {
+    message: string;
+    affected_rows: number;
+}
+export interface TableSchema {
+    table: string;
+    columns: ColumnInfo[];
+    primary_key: string | null;
+}
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    nullable: boolean;
+    key: string;
+    default: any;
+    extra: string;
+}
+export declare class WowSQLClient {
+    private client;
+    private baseUrl;
+    constructor(config: WowSQLConfig);
+    /**
+     * Get a table interface for fluent API
+     */
+    table<T = any>(tableName: string): Table<T>;
+    /**
+     * List all tables in the database
+     */
+    listTables(): Promise<string[]>;
+    /**
+     * Get table schema
+     */
+    getTableSchema(tableName: string): Promise<TableSchema>;
+    /**
+     * Execute raw SQL query (read-only for safety)
+     */
+    query<T = any>(sql: string): Promise<T[]>;
+    /**
+     * Health check
+     */
+    health(): Promise<{
+        status: string;
+        timestamp: string;
+    }>;
+}
+export declare class Table<T = any> {
+    private client;
+    private tableName;
+    constructor(client: AxiosInstance, tableName: string);
+    /**
+     * Query records with filters and pagination
+     *
+     * @example
+     * const users = await client.table('users')
+     *   .select(['id', 'name', 'email'])
+     *   .filter({ column: 'age', operator: 'gt', value: 18 })
+     *   .order('created_at', 'desc')
+     *   .limit(10)
+     *   .get();
+     */
+    select(columns: string | string[]): QueryBuilder<T>;
+    /**
+     * Query with filter
+     */
+    filter(filter: FilterExpression): QueryBuilder<T>;
+    /**
+     * Get all records (with optional limit)
+     */
+    get(options?: QueryOptions): Promise<QueryResponse<T>>;
+    /**
+     * Get a single record by ID
+     */
+    getById(id: string | number): Promise<T>;
+    /**
+     * Create a new record
+     */
+    create(data: Partial<T>): Promise<CreateResponse>;
+    /**
+     * Update a record by ID
+     */
+    update(id: string | number, data: Partial<T>): Promise<UpdateResponse>;
+    /**
+     * Delete a record by ID
+     */
+    delete(id: string | number): Promise<DeleteResponse>;
+}
+export declare class QueryBuilder<T = any> {
+    private client;
+    private tableName;
+    private options;
+    constructor(client: AxiosInstance, tableName: string);
+    /**
+     * Select specific columns
+     */
+    select(columns: string | string[]): this;
+    /**
+     * Add filter condition
+     */
+    filter(filter: FilterExpression): this;
+    /**
+     * Order by column
+     */
+    order(column: string, direction?: 'asc' | 'desc'): this;
+    /**
+     * Limit number of results
+     */
+    limit(limit: number): this;
+    /**
+     * Skip records (pagination)
+     */
+    offset(offset: number): this;
+    /**
+     * Execute query
+     */
+    get(additionalOptions?: QueryOptions): Promise<QueryResponse<T>>;
+    /**
+     * Get first record
+     */
+    first(): Promise<T | null>;
+}
+export * from './storage';
+export * from './auth';
+export * from './schema';
+export * from './errors';
+export default WowSQLClient;