@urbackend/sdk 0.1.0 → 0.2.0

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/README.md

@@ -1,82 +1,85 @@
-# urbackend-sdk
-
-Official TypeScript SDK for [urBackend](https://urbackend.bitbros.in) — the instant Backend-as-a-Service for frontend developers.
-
-## Installation
-npm install @urbackend/sdk
-
-## Quick Start
-```javascript
-import urBackend from '@urbackend/sdk';
-
-const client = urBackend({ apiKey: 'YOUR_API_KEY' });
-
-// Auth
-await client.auth.signUp({ email, password, name });
-const { token } = await client.auth.login({ email, password });
-
-// Database (collections auto-created on first insert)
-await client.db.insert('products', { name: 'Chair', price: 99 });
-await client.db.getAll('products');
-await client.db.update('products', id, { price: 79 });
-await client.db.delete('products', id);
-
-// Storage
-const { url } = await client.storage.upload(file);
-```
-
-## API Reference
-
-### Client initialization
-`urBackend({ apiKey: string, baseUrl?: string })`
-
-### Auth
-| Method | Params | Returns |
-|--------|--------|---------|
-| signUp | { email, password, name? } | AuthUser |
-| login  | { email, password } | { token, user } |
-| me     | token? | AuthUser |
-| logout | — | void |
-
-### Database
-| Method | Params | Returns |
-|--------|--------|---------|
-| getAll<T> | collection | T[] |
-| getOne<T> | collection, id | T |
-| insert<T> | collection, data | T |
-| update<T> | collection, id, data | T |
-| delete | collection, id | { deleted: boolean } |
-
-### Storage
-| Method | Params | Returns |
-|--------|--------|---------|
-| upload | file, filename? | { url, path } |
-| deleteFile | path | { deleted: boolean } |
-
-## Error Handling
-```javascript
-import { AuthError, NotFoundError, RateLimitError } from '@urbackend/sdk';
-
-try {
-  await client.db.getOne('products', id);
-} catch (e) {
-  if (e instanceof NotFoundError) console.log('Not found');
-  if (e instanceof RateLimitError) console.log('Slow down');
-}
-```
-
-## TypeScript Support
-```typescript
-interface Product { _id: string; name: string; price: number; }
-const products = await client.db.getAll<Product>('products');
-```
-
-## Limits
-- Rate limit: 100 requests / 15 mins per IP
-- Database: 50 MB per project
-- Storage: 100 MB per project
-- File upload: 5 MB per file
-
-## Security
-⚠️ Never expose your API key in client-side/browser code.
-Use environment variables: `process.env.URBACKEND_API_KEY`
+# urbackend-sdk
+
+Official TypeScript SDK for [urBackend](https://urbackend.bitbros.in) — the instant Backend-as-a-Service for frontend developers.
+
+## Installation
+npm install @urbackend/sdk
+
+## Quick Start
+```javascript
+import urBackend from '@urbackend/sdk';
+
+const client = urBackend({ apiKey: 'YOUR_API_KEY' });
+
+// Auth
+await client.auth.signUp({ email, password, name });
+await client.auth.login({ email, password });
+await client.auth.me();
+
+// Database — collections are auto-created on first insert
+await client.db.insert('products', { name: 'Chair', price: 99 });
+await client.db.getAll('products');
+await client.db.getOne('products', id);
+await client.db.update('products', id, { price: 79 });
+await client.db.delete('products', id);
+
+// Storage
+await client.storage.upload(file);
+await client.storage.deleteFile(path);
+```
+
+## API Reference
+
+### Client initialization
+`urBackend({ apiKey: string, baseUrl?: string })`
+
+### Auth
+| Method | Params | Returns |
+|--------|--------|---------|
+| signUp | { email, password, name? } | AuthUser |
+| login  | { email, password } | { token, user } |
+| me     | token? | AuthUser |
+| logout | — | void |
+
+### Database
+| Method | Params | Returns |
+|--------|--------|---------|
+| getAll<T> | collection | T[] |
+| getOne<T> | collection, id | T |
+| insert<T> | collection, data | T |
+| update<T> | collection, id, data | T |
+| delete | collection, id | { deleted: boolean } |
+
+### Storage
+| Method | Params | Returns |
+|--------|--------|---------|
+| upload | file, filename? | { url, path } |
+| deleteFile | path | { deleted: boolean } |
+
+## Error Handling
+```javascript
+import { AuthError, NotFoundError, RateLimitError } from '@urbackend/sdk';
+
+try {
+  await client.db.getOne('products', id);
+} catch (e) {
+  if (e instanceof NotFoundError) console.log('Not found');
+  if (e instanceof RateLimitError) console.log('Slow down');
+}
+```
+
+## TypeScript Support
+```typescript
+interface Product { _id: string; name: string; price: number; }
+const products = await client.db.getAll<Product>('products');
+```
+
+## Limits
+- Rate limit: 100 requests / 15 mins per IP
+- Database: 50 MB per project
+- Storage: 100 MB per project
+- File upload: 5 MB per file
+
+## Security
+⚠️ Never expose your API key in client-side/browser code.
+Use environment variables: `process.env.URBACKEND_API_KEY`

package/eslint.config.js

@@ -0,0 +1,15 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+    },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**', 'tests/**'],
+  },
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbackend/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official TypeScript SDK for urBackend BaaS",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -12,16 +12,11 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run --coverage",
     "lint": "eslint src",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "prepublishOnly": "npm run build && npm test"
+    "format": "prettier --write \"src/**/*.ts\""
   },
   "keywords": [
     "urbackend",
@@ -53,8 +48,5 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.2",
     "vitest": "^4.1.2"
-  },
-  "dependencies": {
-    "@urbackend/sdk": "^1.0.0"
   }
-}
+}

package/src/client.ts

@@ -0,0 +1,143 @@
+import { UrBackendConfig, RequestOptions } from './types';
+import { UrBackendError, parseApiError } from './errors';
+import { AuthModule } from './modules/auth';
+import { DatabaseModule } from './modules/database';
+import { StorageModule } from './modules/storage';
+import { SchemaModule } from './modules/schema';
+import { MailModule } from './modules/mail';
+
+export class UrBackendClient {
+  private apiKey: string;
+  private baseUrl: string;
+  private _auth?: AuthModule;
+  private _db?: DatabaseModule;
+  private _storage?: StorageModule;
+  private _schema?: SchemaModule;
+  private _mail?: MailModule;
+  private headers: Record<string, string>;
+
+  constructor(config: UrBackendConfig) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || 'https://api.ub.bitbros.in';
+    this.headers = config.headers || {};
+
+    if (typeof window !== 'undefined' && this.apiKey.startsWith('sk_live_')) {
+      console.warn(
+        '⚠️ urbackend-sdk: Avoid exposing your Secret Key (sk_live_...) in client-side code. This can lead to unauthorized access to your account and data. Use your Publishable Key (pk_live_...) instead.',
+      );
+    }
+  }
+
+  get auth(): AuthModule {
+    if (!this._auth) {
+      this._auth = new AuthModule(this);
+    }
+    return this._auth;
+  }
+
+  get db(): DatabaseModule {
+    if (!this._db) {
+      this._db = new DatabaseModule(this);
+    }
+    return this._db;
+  }
+
+  get storage(): StorageModule {
+    if (!this._storage) {
+      this._storage = new StorageModule(this);
+    }
+    return this._storage;
+  }
+
+  get schema(): SchemaModule {
+    if (!this._schema) {
+      this._schema = new SchemaModule(this);
+    }
+    return this._schema;
+  }
+
+  get mail(): MailModule {
+    if (!this._mail) {
+      this._mail = new MailModule(this);
+    }
+    return this._mail;
+  }
+
+  public getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  public getApiKey(): string {
+    return this.apiKey;
+  }
+
+  /**
+   * Internal request handler
+   */
+  public async request<T>(
+    method: string,
+    path: string,
+    options: RequestOptions = {},
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      'x-api-key': this.apiKey,
+      'User-Agent': `urbackend-sdk-js/0.2.0`,
+      ...this.headers,
+    };
+
+    if (options.token) {
+      headers['Authorization'] = `Bearer ${options.token}`;
+    }
+
+    // Merge custom headers from options if provided
+    if (options.headers) {
+      Object.assign(headers, options.headers);
+    }
+
+    let requestBody: BodyInit | undefined;
+
+    if (options.isMultipart) {
+      // Fetch handles FormData content type and boundary
+      requestBody = options.body as FormData;
+    } else if (options.body) {
+      headers['Content-Type'] = 'application/json';
+      requestBody = JSON.stringify(options.body);
+    }
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: requestBody,
+        credentials: options.credentials,
+      });
+
+      if (!response.ok) {
+        throw await parseApiError(response);
+      }
+
+      const contentType = response.headers.get('content-type');
+      if (contentType && contentType.includes('application/json')) {
+        const json = await response.json();
+        // The API returns { data, success, message }
+        // If data is present, return it. If success/message are present but no data, return the whole object (for exchange/logout etc)
+        if (json.data !== undefined) {
+          return json.data;
+        }
+        return json;
+      }
+
+      return (await response.text()) as unknown as T;
+    } catch (error) {
+      if (error instanceof UrBackendError) {
+        throw error;
+      }
+      throw new UrBackendError(
+        error instanceof Error ? error.message : 'Network request failed',
+        0,
+        path,
+      );
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,90 @@
+export class UrBackendError extends Error {
+  constructor(
+    public message: string,
+    public statusCode: number,
+    public endpoint: string,
+  ) {
+    super(message);
+    this.name = 'UrBackendError';
+  }
+}
+
+export class AuthError extends UrBackendError {
+  constructor(message: string, statusCode: number, endpoint: string) {
+    super(message, statusCode, endpoint);
+    this.name = 'AuthError';
+  }
+}
+
+export class NotFoundError extends UrBackendError {
+  constructor(message: string, endpoint: string) {
+    super(message, 404, endpoint);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class RateLimitError extends UrBackendError {
+  public retryAfter?: number;
+
+  constructor(message: string, endpoint: string, retryAfter?: number) {
+    super(message, 429, endpoint);
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class StorageError extends UrBackendError {
+  constructor(message: string, statusCode: number, endpoint: string) {
+    super(message, statusCode, endpoint);
+    this.name = 'StorageError';
+  }
+}
+
+export class ValidationError extends UrBackendError {
+  constructor(message: string, endpoint: string) {
+    super(message, 400, endpoint);
+    this.name = 'ValidationError';
+  }
+}
+
+export async function parseApiError(response: Response): Promise<UrBackendError> {
+  const endpoint = new URL(response.url).pathname;
+  let message = 'An unexpected error occurred';
+  let data: unknown;
+
+  try {
+    data = await response.json();
+    if (typeof data === 'object' && data !== null && 'message' in data) {
+      message = (data as { message: string }).message || message;
+    }
+  } catch {
+    // If not JSON, use status text
+    message = response.statusText || message;
+  }
+
+  const status = response.status;
+
+  if (status === 401 || status === 403) {
+    return new AuthError(message, status, endpoint);
+  }
+
+  if (status === 404) {
+    return new NotFoundError(message, endpoint);
+  }
+
+  if (status === 429) {
+    const retryAfter = response.headers.get('Retry-After');
+    return new RateLimitError(message, endpoint, retryAfter ? parseInt(retryAfter, 10) : undefined);
+  }
+
+  if (status === 400) {
+    return new ValidationError(message, endpoint);
+  }
+
+  // Default for 5xx or other 4xx
+  if (endpoint.includes('/api/storage')) {
+    return new StorageError(message, status, endpoint);
+  }
+
+  return new UrBackendError(message, status, endpoint);
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+import { UrBackendClient } from './client';
+import { UrBackendConfig } from './types';
+import { AuthModule } from './modules/auth';
+import { DatabaseModule } from './modules/database';
+import { StorageModule } from './modules/storage';
+import { SchemaModule } from './modules/schema';
+import { MailModule } from './modules/mail';
+
+export * from './types';
+export * from './errors';
+export { UrBackendClient, AuthModule, DatabaseModule, StorageModule, SchemaModule, MailModule };
+
+/**
+ * Factory function to create a new urBackend client
+ */
+export default function urBackend(config: UrBackendConfig): UrBackendClient {
+  return new UrBackendClient(config);
+}

package/src/modules/auth.ts

@@ -0,0 +1,209 @@
+import { UrBackendClient } from '../client';
+import {
+  AuthUser,
+  AuthResponse,
+  SignUpPayload,
+  LoginPayload,
+  UpdateProfilePayload,
+  ChangePasswordPayload,
+  VerifyEmailPayload,
+  ResendOtpPayload,
+  RequestPasswordResetPayload,
+  ResetPasswordPayload,
+  SocialExchangePayload,
+  SocialExchangeResponse,
+  RequestOptions,
+} from '../types';
+import { AuthError } from '../errors';
+
+export class AuthModule {
+  private sessionToken?: string;
+
+  constructor(private client: UrBackendClient) {}
+
+  /**
+   * Create a new user account
+   */
+  public async signUp(payload: SignUpPayload): Promise<AuthUser> {
+    return this.client.request<AuthUser>('POST', '/api/userAuth/signup', { body: payload });
+  }
+
+  /**
+   * Log in an existing user and store the session token
+   */
+  public async login(payload: LoginPayload): Promise<AuthResponse> {
+    const response = await this.client.request<AuthResponse>('POST', '/api/userAuth/login', {
+      body: payload,
+    });
+
+    this.sessionToken = response.accessToken || response.token;
+
+    if (!response.accessToken && response.token) {
+      console.warn(
+        'urbackend-sdk: The server returned "token" which is deprecated. Please update your backend to return "accessToken".',
+      );
+    }
+
+    return response;
+  }
+
+  /**
+   * Get the current authenticated user's profile
+   */
+  public async me(token?: string): Promise<AuthUser> {
+    const activeToken = token || this.sessionToken;
+
+    if (!activeToken) {
+      throw new AuthError(
+        'Authentication token is required for /me endpoint',
+        401,
+        '/api/userAuth/me',
+      );
+    }
+
+    return this.client.request<AuthUser>('GET', '/api/userAuth/me', { token: activeToken });
+  }
+
+  /**
+   * Update the current authenticated user's profile
+   */
+  public async updateProfile(payload: UpdateProfilePayload, token?: string): Promise<{ message: string }> {
+    const activeToken = token || this.sessionToken;
+    if (!activeToken) {
+      throw new AuthError('Authentication token is required to update profile', 401, '/api/userAuth/update-profile');
+    }
+    return this.client.request<{ message: string }>('PUT', '/api/userAuth/update-profile', {
+      body: payload,
+      token: activeToken,
+    });
+  }
+
+  /**
+   * Change the current authenticated user's password
+   */
+  public async changePassword(payload: ChangePasswordPayload, token?: string): Promise<{ message: string }> {
+    const activeToken = token || this.sessionToken;
+    if (!activeToken) {
+      throw new AuthError('Authentication token is required to change password', 401, '/api/userAuth/change-password');
+    }
+    return this.client.request<{ message: string }>('PUT', '/api/userAuth/change-password', {
+      body: payload,
+      token: activeToken,
+    });
+  }
+
+  /**
+   * Verify user email with OTP
+   */
+  public async verifyEmail(payload: VerifyEmailPayload): Promise<{ message: string }> {
+    return this.client.request<{ message: string }>('POST', '/api/userAuth/verify-email', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Resend verification OTP
+   */
+  public async resendVerificationOtp(payload: ResendOtpPayload): Promise<{ message: string }> {
+    return this.client.request<{ message: string }>('POST', '/api/userAuth/resend-verification-otp', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Request password reset OTP
+   */
+  public async requestPasswordReset(payload: RequestPasswordResetPayload): Promise<{ message: string }> {
+    return this.client.request<{ message: string }>('POST', '/api/userAuth/request-password-reset', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Reset user password with OTP
+   */
+  public async resetPassword(payload: ResetPasswordPayload): Promise<{ message: string }> {
+    return this.client.request<{ message: string }>('POST', '/api/userAuth/reset-password', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Get public-safe profile by username
+   */
+  public async publicProfile(username: string): Promise<AuthUser> {
+    return this.client.request<AuthUser>('GET', `/api/userAuth/public/${username}`);
+  }
+
+  /**
+   * Refresh the access token
+   * @param refreshToken Optional refresh token for header mode. If omitted, uses cookie mode.
+   */
+  public async refreshToken(refreshToken?: string): Promise<AuthResponse> {
+    const options: RequestOptions = {};
+    if (refreshToken) {
+      options.headers = { 'x-refresh-token': refreshToken, 'x-refresh-token-mode': 'header' };
+    } else {
+      options.credentials = 'include';
+    }
+
+    const response = await this.client.request<AuthResponse>('POST', '/api/userAuth/refresh-token', options);
+    this.sessionToken = response.accessToken || response.token;
+    return response;
+  }
+
+  /**
+   * Returns the start URL for social authentication.
+   * Redirect the user's browser to this URL to begin the flow.
+   */
+  public socialStart(provider: 'github' | 'google'): string {
+    return `${this.client.getBaseUrl()}/api/userAuth/social/${provider}/start?key=${this.client.getApiKey()}`;
+  }
+
+  /**
+   * Exchange social auth rtCode for a refresh token
+   */
+  public async socialExchange(payload: SocialExchangePayload): Promise<SocialExchangeResponse> {
+    return this.client.request<SocialExchangeResponse>('POST', '/api/userAuth/social/exchange', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Revoke the current session and clear local state
+   */
+  public async logout(token?: string): Promise<{ success: boolean; message: string }> {
+    const activeToken = token || this.sessionToken;
+    let result = { success: true, message: 'Logged out locally' };
+
+    if (activeToken) {
+      try {
+        result = await this.client.request<{ success: boolean; message: string }>(
+          'POST',
+          '/api/userAuth/logout',
+          { token: activeToken, credentials: 'include' },
+        );
+      } catch (e) {
+        // Silently fail if server logout fails, we still want to clear local state
+        console.warn('urbackend-sdk: Server logout failed', e);
+      }
+    }
+
+    this.sessionToken = undefined;
+    return result;
+  }
+
+  /**
+   * Manually set the session token (e.g. after social auth exchange)
+   */
+  public setToken(token: string): void {
+    this.sessionToken = token;
+  }
+
+  /**
+   * Get the current stored session token
+   */
+  public getToken(): string | undefined {
+    return this.sessionToken;
+  }
+}