@urbackend/sdk 0.2.0 → 0.2.2

package/README.md

@@ -1,9 +1,11 @@
 # urbackend-sdk
 
-Official TypeScript SDK for [urBackend](https://urbackend.bitbros.in) — the instant Backend-as-a-Service for frontend developers.
+Official TypeScript SDK for [urBackend](https://urbackend.bitbros.in) — the instant Backend-as-a-Service for MongoDB.
 
 ## Installation
+```bash
 npm install @urbackend/sdk
+```
 
 ## Quick Start
 ```javascript
@@ -12,49 +14,80 @@ 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();
+const { accessToken } = await client.auth.login({ email, password });
+const user = 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);
+// Database — collections are managed via the urBackend Dashboard
+await client.db.insert('posts', { title: 'Hello World' }, client.auth.getToken());
+await client.db.getAll('posts', { sort: 'createdAt:desc', limit: 10 });
 
 // Storage
-await client.storage.upload(file);
-await client.storage.deleteFile(path);
+const { url } = await client.storage.upload(file);
+
+// Mail (Requires Secret Key)
+await client.mail.send({ 
+  to: 'user@example.com', 
+  subject: 'Welcome!', 
+  text: 'Glad to have you.' 
+});
 ```
 
 ## API Reference
 
-### Client initialization
+### Client Initialization
 `urBackend({ apiKey: string, baseUrl?: string })`
 
-### Auth
+---
+
+### Auth (`client.auth`)
 | Method | Params | Returns |
 |--------|--------|---------|
-| signUp | { email, password, name? } | AuthUser |
-| login  | { email, password } | { token, user } |
-| me     | token? | AuthUser |
-| logout | — | void |
+| `signUp` | `{ email, password, username?, name?, ... }` | `AuthUser` |
+| `login` | `{ email, password }` | `AuthResponse` |
+| `me` | `token?` | `AuthUser` |
+| `logout` | `token?` | `{ success: boolean }` |
+| `refreshToken` | `refreshToken?` | `AuthResponse` |
+| `updateProfile`| `payload, token?` | `{ message: string }` |
+| `changePassword`| `payload, token?` | `{ message: string }` |
+| `verifyEmail` | `{ email, otp }` | `{ message: string }` |
+| `publicProfile`| `username` | `AuthUser` |
+| `socialStart` | `provider ('github'\|'google')` | `string` (Redirect URL) |
+| `socialExchange`| `{ token, rtCode }` | `SocialExchangeResponse` |
+
+---
+
+### Database (`client.db`)
+Support for **Row-Level Security (RLS)** is built-in. Pass the user's `accessToken` as the final parameter to write routes if RLS is enabled for the collection.
 
-### 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
+| `getAll<T>` | `collection, params?` | `T[]` |
+| `getOne<T>` | `collection, id, options?` | `T` |
+| `insert<T>` | `collection, data, token?` | `T` |
+| `update<T>` | `collection, id, data, token?` | `T` (Full Replace) |
+| `patch<T>` | `collection, id, data, token?` | `T` (Partial Update) |
+| `delete` | `collection, id, token?` | `{ deleted: boolean }` |
+
+**Query Parameters (`params`):**
+- `filter`: `{ price_gt: 100 }`
+- `sort`: `"createdAt:desc"`
+- `limit`: `50`
+- `page`: `1`
+- `populate`: `"author"` (Expand Reference fields)
+
+---
+
+### Storage (`client.storage`)
 | Method | Params | Returns |
 |--------|--------|---------|
-| upload | file, filename? | { url, path } |
-| deleteFile | path | { deleted: boolean } |
+| `upload` | `file (Buffer\|Blob), filename?` | `{ url, path, provider }` |
+| `deleteFile` | `path` | `{ deleted: boolean }` |
+
+---
+
+### New Modules
+- **`client.schema`**: Use `getSchema(collection)` to fetch visual field definitions.
+- **`client.mail`**: Use `send(payload)` to send emails via Resend (Requires Secret Key).
 
 ## Error Handling
 ```javascript
@@ -63,23 +96,13 @@ 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');
+  if (e instanceof AuthError) console.error('Invalid token or insufficient RLS permissions');
+  if (e instanceof NotFoundError) console.error('Resource not found');
+  if (e instanceof RateLimitError) console.error('Too many requests');
 }
 ```
 
-## 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`
+- **Never expose your Secret Key (`sk_live_...`)** in frontend/browser code.
+- Use **Publishable Keys (`pk_live_...`)** for client-side applications.
+- Enable **RLS** in the urBackend Dashboard to allow secure writes from the frontend using the user's access token.

package/dist/index.cjs

@@ -0,0 +1,560 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthError: () => AuthError,
+  AuthModule: () => AuthModule,
+  DatabaseModule: () => DatabaseModule,
+  MailModule: () => MailModule,
+  NotFoundError: () => NotFoundError,
+  RateLimitError: () => RateLimitError,
+  SchemaModule: () => SchemaModule,
+  StorageError: () => StorageError,
+  StorageModule: () => StorageModule,
+  UrBackendClient: () => UrBackendClient,
+  UrBackendError: () => UrBackendError,
+  ValidationError: () => ValidationError,
+  default: () => urBackend,
+  parseApiError: () => parseApiError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var UrBackendError = class extends Error {
+  constructor(message, statusCode, endpoint) {
+    super(message);
+    this.message = message;
+    this.statusCode = statusCode;
+    this.endpoint = endpoint;
+    this.name = "UrBackendError";
+  }
+};
+var AuthError = class extends UrBackendError {
+  constructor(message, statusCode, endpoint) {
+    super(message, statusCode, endpoint);
+    this.name = "AuthError";
+  }
+};
+var NotFoundError = class extends UrBackendError {
+  constructor(message, endpoint) {
+    super(message, 404, endpoint);
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends UrBackendError {
+  constructor(message, endpoint, retryAfter) {
+    super(message, 429, endpoint);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var StorageError = class extends UrBackendError {
+  constructor(message, statusCode, endpoint) {
+    super(message, statusCode, endpoint);
+    this.name = "StorageError";
+  }
+};
+var ValidationError = class extends UrBackendError {
+  constructor(message, endpoint) {
+    super(message, 400, endpoint);
+    this.name = "ValidationError";
+  }
+};
+async function parseApiError(response) {
+  const endpoint = new URL(response.url).pathname;
+  let message = "An unexpected error occurred";
+  let data;
+  try {
+    data = await response.json();
+    if (typeof data === "object" && data !== null && "message" in data) {
+      message = data.message || message;
+    }
+  } catch {
+    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) : void 0);
+  }
+  if (status === 400) {
+    return new ValidationError(message, endpoint);
+  }
+  if (endpoint.includes("/api/storage")) {
+    return new StorageError(message, status, endpoint);
+  }
+  return new UrBackendError(message, status, endpoint);
+}
+
+// src/modules/auth.ts
+var AuthModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new user account
+   */
+  async signUp(payload) {
+    return this.client.request("POST", "/api/userAuth/signup", { body: payload });
+  }
+  /**
+   * Log in an existing user and store the session token
+   */
+  async login(payload) {
+    const response = await this.client.request("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
+   */
+  async me(token) {
+    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("GET", "/api/userAuth/me", { token: activeToken });
+  }
+  /**
+   * Update the current authenticated user's profile
+   */
+  async updateProfile(payload, token) {
+    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("PUT", "/api/userAuth/update-profile", {
+      body: payload,
+      token: activeToken
+    });
+  }
+  /**
+   * Change the current authenticated user's password
+   */
+  async changePassword(payload, token) {
+    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("PUT", "/api/userAuth/change-password", {
+      body: payload,
+      token: activeToken
+    });
+  }
+  /**
+   * Verify user email with OTP
+   */
+  async verifyEmail(payload) {
+    return this.client.request("POST", "/api/userAuth/verify-email", {
+      body: payload
+    });
+  }
+  /**
+   * Resend verification OTP
+   */
+  async resendVerificationOtp(payload) {
+    return this.client.request("POST", "/api/userAuth/resend-verification-otp", {
+      body: payload
+    });
+  }
+  /**
+   * Request password reset OTP
+   */
+  async requestPasswordReset(payload) {
+    return this.client.request("POST", "/api/userAuth/request-password-reset", {
+      body: payload
+    });
+  }
+  /**
+   * Reset user password with OTP
+   */
+  async resetPassword(payload) {
+    return this.client.request("POST", "/api/userAuth/reset-password", {
+      body: payload
+    });
+  }
+  /**
+   * Get public-safe profile by username
+   */
+  async publicProfile(username) {
+    return this.client.request("GET", `/api/userAuth/public/${username}`);
+  }
+  /**
+   * Refresh the access token
+   * @param refreshToken Optional refresh token for header mode. If omitted, uses cookie mode.
+   */
+  async refreshToken(refreshToken) {
+    const options = {};
+    if (refreshToken) {
+      options.headers = { "x-refresh-token": refreshToken, "x-refresh-token-mode": "header" };
+    } else {
+      options.credentials = "include";
+    }
+    const response = await this.client.request("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.
+   */
+  socialStart(provider) {
+    return `${this.client.getBaseUrl()}/api/userAuth/social/${provider}/start?key=${this.client.getApiKey()}`;
+  }
+  /**
+   * Exchange social auth rtCode for a refresh token
+   */
+  async socialExchange(payload) {
+    return this.client.request("POST", "/api/userAuth/social/exchange", {
+      body: payload
+    });
+  }
+  /**
+   * Revoke the current session and clear local state
+   */
+  async logout(token) {
+    const activeToken = token || this.sessionToken;
+    let result = { success: true, message: "Logged out locally" };
+    if (activeToken) {
+      try {
+        result = await this.client.request(
+          "POST",
+          "/api/userAuth/logout",
+          { token: activeToken, credentials: "include" }
+        );
+      } catch (e) {
+        console.warn("urbackend-sdk: Server logout failed", e);
+      }
+    }
+    this.sessionToken = void 0;
+    return result;
+  }
+  /**
+   * Manually set the session token (e.g. after social auth exchange)
+   */
+  setToken(token) {
+    this.sessionToken = token;
+  }
+  /**
+   * Get the current stored session token
+   */
+  getToken() {
+    return this.sessionToken;
+  }
+};
+
+// src/modules/database.ts
+var DatabaseModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Fetch all documents from a collection with optional query parameters
+   */
+  async getAll(collection, params = {}) {
+    const queryString = this.buildQueryString(params);
+    const path = `/api/data/${collection}${queryString}`;
+    try {
+      return await this.client.request("GET", path);
+    } catch (e) {
+      if (e instanceof NotFoundError) {
+        return [];
+      }
+      throw e;
+    }
+  }
+  /**
+   * Fetch a single document by its ID
+   */
+  async getOne(collection, id, options = {}) {
+    const queryString = this.buildQueryString(options);
+    return this.client.request("GET", `/api/data/${collection}/${id}${queryString}`);
+  }
+  /**
+   * Insert a new document into a collection
+   */
+  async insert(collection, data, token) {
+    return this.client.request("POST", `/api/data/${collection}`, {
+      body: data,
+      token
+    });
+  }
+  /**
+   * Update an existing document by its ID (Full replacement)
+   */
+  async update(collection, id, data, token) {
+    return this.client.request("PUT", `/api/data/${collection}/${id}`, {
+      body: data,
+      token
+    });
+  }
+  /**
+   * Partially update an existing document by its ID
+   */
+  async patch(collection, id, data, token) {
+    return this.client.request("PATCH", `/api/data/${collection}/${id}`, {
+      body: data,
+      token
+    });
+  }
+  /**
+   * Delete a document by its ID
+   */
+  async delete(collection, id, token) {
+    const result = await this.client.request(
+      "DELETE",
+      `/api/data/${collection}/${id}`,
+      { token }
+    );
+    const deleted = typeof result === "object" && result !== null && (result.id === id || result.message === "Document deleted");
+    return { deleted };
+  }
+  /**
+   * Internal helper to build query string from QueryParams
+   */
+  buildQueryString(params) {
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (value === void 0 || value === null) return;
+      if (key === "filter" && typeof value === "object") {
+        Object.entries(value).forEach(([fKey, fValue]) => {
+          if (fValue !== void 0 && fValue !== null) {
+            searchParams.append(fKey, String(fValue));
+          }
+        });
+      } else if ((key === "populate" || key === "expand") && Array.isArray(value)) {
+        searchParams.append(key, value.join(","));
+      } else {
+        searchParams.append(key, String(value));
+      }
+    });
+    const str = searchParams.toString();
+    return str ? `?${str}` : "";
+  }
+};
+
+// src/modules/storage.ts
+var StorageModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Upload a file to storage
+   */
+  async upload(file, filename) {
+    const formData = new FormData();
+    if (typeof window === "undefined" && typeof Buffer !== "undefined" && Buffer.isBuffer(file)) {
+      const blob = new Blob([file]);
+      formData.append("file", blob, filename || "file");
+    } else {
+      formData.append("file", file, filename);
+    }
+    return this.client.request("POST", "/api/storage/upload", {
+      body: formData,
+      isMultipart: true
+    });
+  }
+  /**
+   * Delete a file from storage by its path
+   */
+  async deleteFile(path) {
+    return this.client.request("DELETE", "/api/storage/file", {
+      body: { path }
+    });
+  }
+};
+
+// src/modules/schema.ts
+var SchemaModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Fetch the schema definition for a collection
+   */
+  async getSchema(collection) {
+    const trimmedCollection = collection.trim();
+    if (trimmedCollection === "") {
+      throw new Error("Collection name cannot be empty or whitespace-only");
+    }
+    const encodedCollection = encodeURIComponent(trimmedCollection);
+    const response = await this.client.request("GET", `/api/schemas/${encodedCollection}`);
+    return response.collection;
+  }
+};
+
+// src/modules/mail.ts
+var MailModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Send an email using the urBackend mail service.
+   * Note: This requires a Secret Key (sk_live_...) and should be called from a server environment.
+   */
+  async send(payload) {
+    return this.client.request("POST", "/api/mail/send", {
+      body: payload
+    });
+  }
+};
+
+// src/client.ts
+var UrBackendClient = class {
+  constructor(config) {
+    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(
+        "\u26A0\uFE0F 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() {
+    if (!this._auth) {
+      this._auth = new AuthModule(this);
+    }
+    return this._auth;
+  }
+  get db() {
+    if (!this._db) {
+      this._db = new DatabaseModule(this);
+    }
+    return this._db;
+  }
+  get storage() {
+    if (!this._storage) {
+      this._storage = new StorageModule(this);
+    }
+    return this._storage;
+  }
+  get schema() {
+    if (!this._schema) {
+      this._schema = new SchemaModule(this);
+    }
+    return this._schema;
+  }
+  get mail() {
+    if (!this._mail) {
+      this._mail = new MailModule(this);
+    }
+    return this._mail;
+  }
+  getBaseUrl() {
+    return this.baseUrl;
+  }
+  getApiKey() {
+    return this.apiKey;
+  }
+  /**
+   * Internal request handler
+   */
+  async request(method, path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "x-api-key": this.apiKey,
+      "User-Agent": `urbackend-sdk-js/0.2.0`,
+      ...this.headers
+    };
+    if (options.token) {
+      headers["Authorization"] = `Bearer ${options.token}`;
+    }
+    if (options.headers) {
+      Object.assign(headers, options.headers);
+    }
+    let requestBody;
+    if (options.isMultipart) {
+      requestBody = options.body;
+    } 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();
+        if (json.data !== void 0) {
+          return json.data;
+        }
+        return json;
+      }
+      return await response.text();
+    } catch (error) {
+      if (error instanceof UrBackendError) {
+        throw error;
+      }
+      throw new UrBackendError(
+        error instanceof Error ? error.message : "Network request failed",
+        0,
+        path
+      );
+    }
+  }
+};
+
+// src/index.ts
+function urBackend(config) {
+  return new UrBackendClient(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthError,
+  AuthModule,
+  DatabaseModule,
+  MailModule,
+  NotFoundError,
+  RateLimitError,
+  SchemaModule,
+  StorageError,
+  StorageModule,
+  UrBackendClient,
+  UrBackendError,
+  ValidationError,
+  parseApiError
+});
+//# sourceMappingURL=index.cjs.map