@urbackend/sdk 0.1.0 → 0.2.0

package/src/modules/database.ts

@@ -0,0 +1,124 @@
+import { UrBackendClient } from '../client';
+import { DocumentData, InsertPayload, UpdatePayload, PatchPayload, QueryParams } from '../types';
+import { NotFoundError } from '../errors';
+
+export class DatabaseModule {
+  constructor(private client: UrBackendClient) {}
+
+  /**
+   * Fetch all documents from a collection with optional query parameters
+   */
+  public async getAll<T extends DocumentData>(collection: string, params: QueryParams = {}): Promise<T[]> {
+    const queryString = this.buildQueryString(params);
+    const path = `/api/data/${collection}${queryString}`;
+    
+    try {
+      return await this.client.request<T[]>('GET', path);
+    } catch (e) {
+      if (e instanceof NotFoundError) {
+        return [] as T[];
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Fetch a single document by its ID
+   */
+  public async getOne<T extends DocumentData>(
+    collection: string, 
+    id: string, 
+    options: { populate?: string | string[]; expand?: string | string[] } = {}
+  ): Promise<T> {
+    const queryString = this.buildQueryString(options);
+    return this.client.request<T>('GET', `/api/data/${collection}/${id}${queryString}`);
+  }
+
+  /**
+   * Insert a new document into a collection
+   */
+  public async insert<T extends DocumentData>(
+    collection: string, 
+    data: InsertPayload, 
+    token?: string
+  ): Promise<T> {
+    return this.client.request<T>('POST', `/api/data/${collection}`, { 
+      body: data,
+      token 
+    });
+  }
+
+  /**
+   * Update an existing document by its ID (Full replacement)
+   */
+  public async update<T extends DocumentData>(
+    collection: string,
+    id: string,
+    data: UpdatePayload,
+    token?: string
+  ): Promise<T> {
+    return this.client.request<T>('PUT', `/api/data/${collection}/${id}`, { 
+      body: data,
+      token
+    });
+  }
+
+  /**
+   * Partially update an existing document by its ID
+   */
+  public async patch<T extends DocumentData>(
+    collection: string,
+    id: string,
+    data: PatchPayload,
+    token?: string
+  ): Promise<T> {
+    return this.client.request<T>('PATCH', `/api/data/${collection}/${id}`, { 
+      body: data,
+      token
+    });
+  }
+
+  /**
+   * Delete a document by its ID
+   */
+  public async delete(collection: string, id: string, token?: string): Promise<{ deleted: boolean }> {
+    const result = await this.client.request<{ message?: string; id?: string } | null>(
+      '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
+   */
+  private buildQueryString(params: QueryParams): string {
+    const searchParams = new URLSearchParams();
+
+    Object.entries(params).forEach(([key, value]) => {
+      if (value === undefined || value === null) return;
+
+      if (key === 'filter' && typeof value === 'object') {
+        Object.entries(value as Record<string, unknown>).forEach(([fKey, fValue]) => {
+          if (fValue !== undefined && 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}` : '';
+  }
+}

package/src/modules/mail.ts

@@ -0,0 +1,16 @@
+import { UrBackendClient } from '../client';
+import { SendMailPayload, SendMailResponse } from '../types';
+
+export class MailModule {
+  constructor(private client: UrBackendClient) {}
+
+  /**
+   * Send an email using the urBackend mail service.
+   * Note: This requires a Secret Key (sk_live_...) and should be called from a server environment.
+   */
+  public async send(payload: SendMailPayload): Promise<SendMailResponse> {
+    return this.client.request<SendMailResponse>('POST', '/api/mail/send', {
+      body: payload,
+    });
+  }
+}

package/src/modules/schema.ts

@@ -0,0 +1,24 @@
+import { UrBackendClient } from '../client';
+import { CollectionSchema } from '../types';
+
+export class SchemaModule {
+  constructor(private client: UrBackendClient) {}
+
+  /**
+   * Fetch the schema definition for a collection
+   */
+  public async getSchema(collection: string): Promise<CollectionSchema> {
+    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<{
+      message: string;
+      collection: CollectionSchema;
+    }>('GET', `/api/schemas/${encodedCollection}`);
+
+    return response.collection;
+  }
+}

package/src/modules/storage.ts

@@ -0,0 +1,41 @@
+/// <reference lib="dom" />
+import { UrBackendClient } from '../client';
+import { UploadResponse } from '../types';
+
+export class StorageModule {
+  constructor(private client: UrBackendClient) {}
+
+  /**
+   * Upload a file to storage
+   */
+  public async upload(file: unknown, filename?: string): Promise<UploadResponse> {
+    const formData = new FormData();
+
+    if (
+      typeof window === 'undefined' &&
+      typeof Buffer !== 'undefined' &&
+      Buffer.isBuffer(file)
+    ) {
+      // In Node.js environment, convert Buffer to Blob for standard FormData
+      const blob = new Blob([file as unknown as BlobPart]);
+      formData.append('file', blob, filename || 'file');
+    } else {
+      // Browser File/Blob or Node.js Blob/File
+      formData.append('file', file as unknown as Blob, filename);
+    }
+
+    return this.client.request<UploadResponse>('POST', '/api/storage/upload', {
+      body: formData,
+      isMultipart: true,
+    });
+  }
+
+  /**
+   * Delete a file from storage by its path
+   */
+  public async deleteFile(path: string): Promise<{ deleted: boolean }> {
+    return this.client.request<{ deleted: boolean }>('DELETE', '/api/storage/file', {
+      body: { path },
+    });
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,154 @@
+export interface UrBackendConfig {
+  apiKey: string;
+  baseUrl?: string;
+  headers?: Record<string, string>;
+}
+
+export interface RequestOptions {
+  body?: unknown;
+  token?: string;
+  isMultipart?: boolean;
+  credentials?: RequestCredentials;
+  headers?: Record<string, string>;
+}
+
+export interface QueryParams {
+  page?: number;
+  limit?: number;
+  sort?: string;
+  populate?: string | string[];
+  expand?: string | string[];
+  filter?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface SignUpPayload {
+  email: string;
+  password: string;
+  username?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+export interface LoginPayload {
+  email: string;
+  password: string;
+}
+
+export interface UpdateProfilePayload {
+  username?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+export interface ChangePasswordPayload {
+  currentPassword: string;
+  newPassword: string;
+}
+
+export interface VerifyEmailPayload {
+  email: string;
+  otp: string;
+}
+
+export interface ResendOtpPayload {
+  email: string;
+}
+
+export interface RequestPasswordResetPayload {
+  email: string;
+}
+
+export interface ResetPasswordPayload {
+  email: string;
+  otp: string;
+  newPassword: string;
+}
+
+export interface SocialExchangePayload {
+  token: string;
+  rtCode: string;
+}
+
+export interface SocialExchangeResponse {
+  refreshToken: string;
+}
+
+export interface AuthUser {
+  _id: string;
+  email: string;
+  username?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+export interface AuthResponse {
+  accessToken?: string;
+  /** @deprecated use accessToken instead */
+  token?: string;
+  expiresIn?: string;
+  userId?: string;
+  user?: AuthUser;
+}
+
+export interface DocumentData {
+  _id: string;
+  [key: string]: unknown;
+}
+
+export interface InsertPayload {
+  [key: string]: unknown;
+}
+
+export interface UpdatePayload {
+  [key: string]: unknown;
+}
+
+export interface PatchPayload {
+  [key: string]: unknown;
+}
+
+export interface SchemaField {
+  key: string;
+  type: string;
+  required: boolean;
+  unique?: boolean;
+  ref?: string;
+  items?: {
+    type: string;
+    fields?: SchemaField[];
+  };
+  fields?: SchemaField[];
+}
+
+export interface CollectionSchema {
+  name: string;
+  model: SchemaField[];
+}
+
+export interface SendMailPayload {
+  to: string | string[];
+  subject: string;
+  text?: string;
+  html?: string;
+}
+
+export interface SendMailResponse {
+  id: string | null;
+  provider: 'byok' | 'default';
+  monthlyUsage: number;
+  monthlyLimit: number;
+}
+
+export interface UploadResponse {
+  url: string;
+  path: string;
+  provider: 'internal' | 'external';
+  message?: string;
+}
+
+export interface ApiResponse<T> {
+  data: T;
+  success: boolean;
+  message?: string;
+}

package/tests/auth.test.ts

@@ -0,0 +1,169 @@
+import { expect, test, vi, beforeEach } from 'vitest';
+import urBackend from '../src/index';
+
+const mockApiKey = 'pk_live_test';
+let client: ReturnType<typeof urBackend>;
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  client = urBackend({ apiKey: mockApiKey });
+});
+
+test('signUp returns user object on success', async () => {
+  const mockUser = { _id: '123', email: 'test@example.com' };
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue({
+      ok: true,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      json: () => Promise.resolve({ success: true, data: mockUser }),
+    }),
+  );
+
+  const user = await client.auth.signUp({ email: 'test@example.com', password: 'password' });
+  expect(user).toEqual(mockUser);
+});
+
+test('login stores accessToken', async () => {
+  const mockAccessToken = 'mock-access-token';
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue({
+      ok: true,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      json: () =>
+        Promise.resolve({
+          success: true,
+          data: { accessToken: mockAccessToken, user: { _id: '123', email: 'test@example.com' } },
+        }),
+    }),
+  );
+
+  const response = await client.auth.login({ email: 'test@example.com', password: 'password' });
+  expect(response.accessToken).toBe(mockAccessToken);
+  expect(client.auth.getToken()).toBe(mockAccessToken);
+});
+
+test('me() uses stored token from login', async () => {
+  const mockToken = 'mock-token';
+  const mockUser = { _id: '123', email: 'test@example.com' };
+
+  // First mock login
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue({
+      ok: true,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      json: () =>
+        Promise.resolve({
+          success: true,
+          data: { accessToken: mockToken, user: mockUser },
+        }),
+    }),
+  );
+  await client.auth.login({ email: 'test@example.com', password: 'password' });
+
+  // Then mock me call
+  const meFetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: mockUser }),
+  });
+  vi.stubGlobal('fetch', meFetchMock);
+
+  await client.auth.me();
+
+  expect(meFetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/userAuth/me'),
+    expect.objectContaining({
+      headers: expect.objectContaining({
+        Authorization: `Bearer ${mockToken}`,
+      }),
+    }),
+  );
+});
+
+test('logout() calls server and clears local token', async () => {
+  client.auth.setToken('test-token');
+  const logoutFetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, message: 'Logged out' }),
+  });
+  vi.stubGlobal('fetch', logoutFetchMock);
+
+  await client.auth.logout();
+
+  expect(logoutFetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/userAuth/logout'),
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer test-token',
+      }),
+    }),
+  );
+  expect(client.auth.getToken()).toBeUndefined();
+});
+
+test('refreshToken() uses credentials: include by default', async () => {
+  const refreshFetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { accessToken: 'new-token' } }),
+  });
+  vi.stubGlobal('fetch', refreshFetchMock);
+
+  await client.auth.refreshToken();
+
+  expect(refreshFetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/userAuth/refresh-token'),
+    expect.objectContaining({
+      method: 'POST',
+      credentials: 'include',
+    }),
+  );
+});
+
+test('refreshToken(token) uses header mode', async () => {
+  const refreshFetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { accessToken: 'new-token' } }),
+  });
+  vi.stubGlobal('fetch', refreshFetchMock);
+
+  await client.auth.refreshToken('manual-refresh-token');
+
+  expect(refreshFetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/userAuth/refresh-token'),
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({
+        'x-refresh-token': 'manual-refresh-token',
+        'x-refresh-token-mode': 'header',
+      }),
+    }),
+  );
+});
+
+test('socialStart returns correct URL', () => {
+  const url = client.auth.socialStart('github');
+  expect(url).toBe('https://api.ub.bitbros.in/api/userAuth/social/github/start?key=pk_live_test');
+});
+
+test('publicProfile calls correct endpoint', async () => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { username: 'yash' } }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  await client.auth.publicProfile('yash');
+
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/userAuth/public/yash'),
+    expect.any(Object),
+  );
+});

package/tests/database.test.ts

@@ -0,0 +1,134 @@
+import { expect, test, vi, beforeEach } from 'vitest';
+import urBackend from '../src/index';
+
+const mockApiKey = 'pk_live_test';
+const client = urBackend({ apiKey: mockApiKey });
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+test('getAll returns array of typed documents', async () => {
+  const mockData = [
+    { _id: '1', name: 'Product 1' },
+    { _id: '2', name: 'Product 2' },
+  ];
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue({
+      ok: true,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      json: () => Promise.resolve({ success: true, data: mockData }),
+    }),
+  );
+
+  const items = await client.db.getAll<{ _id: string; name: string }>('products');
+  expect(items).toEqual(mockData);
+});
+
+test('getAll with query params builds correct query string', async () => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: [] }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  await client.db.getAll('products', {
+    page: 2,
+    limit: 10,
+    sort: 'price:asc',
+    populate: 'category',
+    filter: { price_gt: 100 }
+  });
+
+  const url = fetchMock.mock.calls[0][0] as string;
+  const searchParams = new URL(url).searchParams;
+  
+  expect(searchParams.get('page')).toBe('2');
+  expect(searchParams.get('limit')).toBe('10');
+  expect(searchParams.get('sort')).toBe('price:asc');
+  expect(searchParams.get('populate')).toBe('category');
+  expect(searchParams.get('price_gt')).toBe('100');
+});
+
+test('insert returns created document and handles optional token', async () => {
+  const payload = { name: 'New Item' };
+  const mockCreated = { _id: 'new-id', ...payload };
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: mockCreated }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  const result = await client.db.insert<{ _id: string; name: string }>('products', payload, 'user-token');
+  
+  expect(result._id).toBe('new-id');
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/data/products'),
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer user-token',
+      }),
+    }),
+  );
+});
+
+test('patch sends PATCH request', async () => {
+  const payload = { price: 50 };
+  const mockUpdated = { _id: '1', name: 'Original', price: 50 };
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: mockUpdated }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  await client.db.patch('products', '1', payload);
+
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/data/products/1'),
+    expect.objectContaining({
+      method: 'PATCH',
+      body: JSON.stringify(payload),
+    }),
+  );
+});
+
+test('getOne with populate builds correct query string', async () => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { _id: '1' } }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  await client.db.getOne('products', '1', { populate: 'category' });
+
+  const url = fetchMock.mock.calls[0][0] as string;
+  expect(url).toContain('?populate=category');
+});
+
+test('delete returns { deleted: true } and handles token', async () => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { message: 'Document deleted', id: 'id-1' } }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  const result = await client.db.delete('products', 'id-1', 'admin-token');
+  
+  expect(result.deleted).toBe(true);
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/data/products/id-1'),
+    expect.objectContaining({
+      method: 'DELETE',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer admin-token',
+      }),
+    }),
+  );
+});

package/tests/mail.test.ts

@@ -0,0 +1,41 @@
+import { expect, test, vi, beforeEach } from 'vitest';
+import urBackend from '../src/index';
+
+const mockApiKey = 'sk_live_test';
+const client = urBackend({ apiKey: mockApiKey });
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+test('send() sends POST request to mail endpoint', async () => {
+  const payload = {
+    to: 'user@example.com',
+    subject: 'Hello',
+    text: 'Test mail'
+  };
+  
+  const mockResponse = {
+    success: true,
+    data: { id: 'msg_1', provider: 'default', monthlyUsage: 1, monthlyLimit: 100 },
+    message: 'Sent'
+  };
+
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve(mockResponse),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  const result = await client.mail.send(payload);
+  
+  expect(result).toEqual(mockResponse.data);
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/mail/send'),
+    expect.objectContaining({
+      method: 'POST',
+      body: JSON.stringify(payload),
+    }),
+  );
+});