@urbackend/sdk 0.2.1 → 0.2.3

package/dist/index.d.mts

@@ -0,0 +1,343 @@
+interface UrBackendConfig {
+    apiKey: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+}
+interface RequestOptions {
+    body?: unknown;
+    token?: string;
+    isMultipart?: boolean;
+    credentials?: RequestCredentials;
+    headers?: Record<string, string>;
+}
+interface QueryParams {
+    page?: number;
+    limit?: number;
+    sort?: string;
+    populate?: string | string[];
+    expand?: string | string[];
+    filter?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface SignUpPayload {
+    email: string;
+    password: string;
+    username?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface LoginPayload {
+    email: string;
+    password: string;
+}
+interface UpdateProfilePayload {
+    username?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface ChangePasswordPayload {
+    currentPassword: string;
+    newPassword: string;
+}
+interface VerifyEmailPayload {
+    email: string;
+    otp: string;
+}
+interface ResendOtpPayload {
+    email: string;
+}
+interface RequestPasswordResetPayload {
+    email: string;
+}
+interface ResetPasswordPayload {
+    email: string;
+    otp: string;
+    newPassword: string;
+}
+interface SocialExchangePayload {
+    token: string;
+    rtCode: string;
+}
+interface SocialExchangeResponse {
+    refreshToken: string;
+}
+interface AuthUser {
+    _id: string;
+    email: string;
+    username?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface AuthResponse {
+    accessToken?: string;
+    /** @deprecated use accessToken instead */
+    token?: string;
+    expiresIn?: string;
+    userId?: string;
+    user?: AuthUser;
+}
+interface DocumentData {
+    _id: string;
+    [key: string]: unknown;
+}
+interface InsertPayload {
+    [key: string]: unknown;
+}
+interface UpdatePayload {
+    [key: string]: unknown;
+}
+interface PatchPayload {
+    [key: string]: unknown;
+}
+interface SchemaField {
+    key: string;
+    type: string;
+    required: boolean;
+    unique?: boolean;
+    ref?: string;
+    items?: {
+        type: string;
+        fields?: SchemaField[];
+    };
+    fields?: SchemaField[];
+}
+interface CollectionSchema {
+    name: string;
+    model: SchemaField[];
+}
+interface SendMailPayload {
+    to: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+}
+interface SendMailResponse {
+    id: string | null;
+    provider: 'byok' | 'default';
+    monthlyUsage: number;
+    monthlyLimit: number;
+}
+interface UploadResponse {
+    url: string;
+    path: string;
+    provider: 'internal' | 'external';
+    message?: string;
+}
+interface ApiResponse<T> {
+    data: T;
+    success: boolean;
+    message?: string;
+}
+
+declare class AuthModule {
+    private client;
+    private sessionToken?;
+    constructor(client: UrBackendClient);
+    /**
+     * Create a new user account
+     */
+    signUp(payload: SignUpPayload): Promise<AuthUser>;
+    /**
+     * Log in an existing user and store the session token
+     */
+    login(payload: LoginPayload): Promise<AuthResponse>;
+    /**
+     * Get the current authenticated user's profile
+     */
+    me(token?: string): Promise<AuthUser>;
+    /**
+     * Update the current authenticated user's profile
+     */
+    updateProfile(payload: UpdateProfilePayload, token?: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Change the current authenticated user's password
+     */
+    changePassword(payload: ChangePasswordPayload, token?: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Verify user email with OTP
+     */
+    verifyEmail(payload: VerifyEmailPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Resend verification OTP
+     */
+    resendVerificationOtp(payload: ResendOtpPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Request password reset OTP
+     */
+    requestPasswordReset(payload: RequestPasswordResetPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Reset user password with OTP
+     */
+    resetPassword(payload: ResetPasswordPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Get public-safe profile by username
+     */
+    publicProfile(username: string): Promise<AuthUser>;
+    /**
+     * Refresh the access token
+     * @param refreshToken Optional refresh token for header mode. If omitted, uses cookie mode.
+     */
+    refreshToken(refreshToken?: string): Promise<AuthResponse>;
+    /**
+     * Returns the start URL for social authentication.
+     * Redirect the user's browser to this URL to begin the flow.
+     */
+    socialStart(provider: 'github' | 'google'): string;
+    /**
+     * Exchange social auth rtCode for a refresh token
+     */
+    socialExchange(payload: SocialExchangePayload): Promise<SocialExchangeResponse>;
+    /**
+     * Revoke the current session and clear local state
+     */
+    logout(token?: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Manually set the session token (e.g. after social auth exchange)
+     */
+    setToken(token: string): void;
+    /**
+     * Get the current stored session token
+     */
+    getToken(): string | undefined;
+}
+
+declare class DatabaseModule {
+    private client;
+    constructor(client: UrBackendClient);
+    /**
+     * Fetch all documents from a collection with optional query parameters
+     */
+    getAll<T extends DocumentData>(collection: string, params?: QueryParams): Promise<T[]>;
+    /**
+     * Fetch a single document by its ID
+     */
+    getOne<T extends DocumentData>(collection: string, id: string, options?: {
+        populate?: string | string[];
+        expand?: string | string[];
+    }): Promise<T>;
+    /**
+     * Insert a new document into a collection
+     */
+    insert<T extends DocumentData>(collection: string, data: InsertPayload, token?: string): Promise<T>;
+    /**
+     * Update an existing document by its ID (Full replacement)
+     */
+    update<T extends DocumentData>(collection: string, id: string, data: UpdatePayload, token?: string): Promise<T>;
+    /**
+     * Partially update an existing document by its ID
+     */
+    patch<T extends DocumentData>(collection: string, id: string, data: PatchPayload, token?: string): Promise<T>;
+    /**
+     * Delete a document by its ID
+     */
+    delete(collection: string, id: string, token?: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Internal helper to build query string from QueryParams
+     */
+    private buildQueryString;
+}
+
+declare class StorageModule {
+    private client;
+    constructor(client: UrBackendClient);
+    /**
+     * Upload a file to storage
+     */
+    upload(file: unknown, filename?: string): Promise<UploadResponse>;
+    /**
+     * Delete a file from storage by its path
+     */
+    deleteFile(path: string): Promise<{
+        deleted: boolean;
+    }>;
+}
+
+declare class SchemaModule {
+    private client;
+    constructor(client: UrBackendClient);
+    /**
+     * Fetch the schema definition for a collection
+     */
+    getSchema(collection: string): Promise<CollectionSchema>;
+}
+
+declare class MailModule {
+    private client;
+    constructor(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.
+     */
+    send(payload: SendMailPayload): Promise<SendMailResponse>;
+}
+
+declare class UrBackendClient {
+    private apiKey;
+    private baseUrl;
+    private _auth?;
+    private _db?;
+    private _storage?;
+    private _schema?;
+    private _mail?;
+    private headers;
+    constructor(config: UrBackendConfig);
+    get auth(): AuthModule;
+    get db(): DatabaseModule;
+    get storage(): StorageModule;
+    get schema(): SchemaModule;
+    get mail(): MailModule;
+    getBaseUrl(): string;
+    getApiKey(): string;
+    /**
+     * Internal request handler
+     */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+
+declare class UrBackendError extends Error {
+    message: string;
+    statusCode: number;
+    endpoint: string;
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+declare class AuthError extends UrBackendError {
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+declare class NotFoundError extends UrBackendError {
+    constructor(message: string, endpoint: string);
+}
+declare class RateLimitError extends UrBackendError {
+    retryAfter?: number;
+    constructor(message: string, endpoint: string, retryAfter?: number);
+}
+declare class StorageError extends UrBackendError {
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+declare class ValidationError extends UrBackendError {
+    constructor(message: string, endpoint: string);
+}
+declare function parseApiError(response: Response): Promise<UrBackendError>;
+
+/**
+ * Factory function to create a new urBackend client
+ */
+declare function urBackend(config: UrBackendConfig): UrBackendClient;
+
+export { type ApiResponse, AuthError, AuthModule, type AuthResponse, type AuthUser, type ChangePasswordPayload, type CollectionSchema, DatabaseModule, type DocumentData, type InsertPayload, type LoginPayload, MailModule, NotFoundError, type PatchPayload, type QueryParams, RateLimitError, type RequestOptions, type RequestPasswordResetPayload, type ResendOtpPayload, type ResetPasswordPayload, type SchemaField, SchemaModule, type SendMailPayload, type SendMailResponse, type SignUpPayload, type SocialExchangePayload, type SocialExchangeResponse, StorageError, StorageModule, type UpdatePayload, type UpdateProfilePayload, type UploadResponse, UrBackendClient, type UrBackendConfig, UrBackendError, ValidationError, type VerifyEmailPayload, urBackend as default, parseApiError };

package/dist/index.d.ts

@@ -0,0 +1,343 @@
+interface UrBackendConfig {
+    apiKey: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+}
+interface RequestOptions {
+    body?: unknown;
+    token?: string;
+    isMultipart?: boolean;
+    credentials?: RequestCredentials;
+    headers?: Record<string, string>;
+}
+interface QueryParams {
+    page?: number;
+    limit?: number;
+    sort?: string;
+    populate?: string | string[];
+    expand?: string | string[];
+    filter?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface SignUpPayload {
+    email: string;
+    password: string;
+    username?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface LoginPayload {
+    email: string;
+    password: string;
+}
+interface UpdateProfilePayload {
+    username?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface ChangePasswordPayload {
+    currentPassword: string;
+    newPassword: string;
+}
+interface VerifyEmailPayload {
+    email: string;
+    otp: string;
+}
+interface ResendOtpPayload {
+    email: string;
+}
+interface RequestPasswordResetPayload {
+    email: string;
+}
+interface ResetPasswordPayload {
+    email: string;
+    otp: string;
+    newPassword: string;
+}
+interface SocialExchangePayload {
+    token: string;
+    rtCode: string;
+}
+interface SocialExchangeResponse {
+    refreshToken: string;
+}
+interface AuthUser {
+    _id: string;
+    email: string;
+    username?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface AuthResponse {
+    accessToken?: string;
+    /** @deprecated use accessToken instead */
+    token?: string;
+    expiresIn?: string;
+    userId?: string;
+    user?: AuthUser;
+}
+interface DocumentData {
+    _id: string;
+    [key: string]: unknown;
+}
+interface InsertPayload {
+    [key: string]: unknown;
+}
+interface UpdatePayload {
+    [key: string]: unknown;
+}
+interface PatchPayload {
+    [key: string]: unknown;
+}
+interface SchemaField {
+    key: string;
+    type: string;
+    required: boolean;
+    unique?: boolean;
+    ref?: string;
+    items?: {
+        type: string;
+        fields?: SchemaField[];
+    };
+    fields?: SchemaField[];
+}
+interface CollectionSchema {
+    name: string;
+    model: SchemaField[];
+}
+interface SendMailPayload {
+    to: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+}
+interface SendMailResponse {
+    id: string | null;
+    provider: 'byok' | 'default';
+    monthlyUsage: number;
+    monthlyLimit: number;
+}
+interface UploadResponse {
+    url: string;
+    path: string;
+    provider: 'internal' | 'external';
+    message?: string;
+}
+interface ApiResponse<T> {
+    data: T;
+    success: boolean;
+    message?: string;
+}
+
+declare class AuthModule {
+    private client;
+    private sessionToken?;
+    constructor(client: UrBackendClient);
+    /**
+     * Create a new user account
+     */
+    signUp(payload: SignUpPayload): Promise<AuthUser>;
+    /**
+     * Log in an existing user and store the session token
+     */
+    login(payload: LoginPayload): Promise<AuthResponse>;
+    /**
+     * Get the current authenticated user's profile
+     */
+    me(token?: string): Promise<AuthUser>;
+    /**
+     * Update the current authenticated user's profile
+     */
+    updateProfile(payload: UpdateProfilePayload, token?: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Change the current authenticated user's password
+     */
+    changePassword(payload: ChangePasswordPayload, token?: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Verify user email with OTP
+     */
+    verifyEmail(payload: VerifyEmailPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Resend verification OTP
+     */
+    resendVerificationOtp(payload: ResendOtpPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Request password reset OTP
+     */
+    requestPasswordReset(payload: RequestPasswordResetPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Reset user password with OTP
+     */
+    resetPassword(payload: ResetPasswordPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Get public-safe profile by username
+     */
+    publicProfile(username: string): Promise<AuthUser>;
+    /**
+     * Refresh the access token
+     * @param refreshToken Optional refresh token for header mode. If omitted, uses cookie mode.
+     */
+    refreshToken(refreshToken?: string): Promise<AuthResponse>;
+    /**
+     * Returns the start URL for social authentication.
+     * Redirect the user's browser to this URL to begin the flow.
+     */
+    socialStart(provider: 'github' | 'google'): string;
+    /**
+     * Exchange social auth rtCode for a refresh token
+     */
+    socialExchange(payload: SocialExchangePayload): Promise<SocialExchangeResponse>;
+    /**
+     * Revoke the current session and clear local state
+     */
+    logout(token?: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Manually set the session token (e.g. after social auth exchange)
+     */
+    setToken(token: string): void;
+    /**
+     * Get the current stored session token
+     */
+    getToken(): string | undefined;
+}
+
+declare class DatabaseModule {
+    private client;
+    constructor(client: UrBackendClient);
+    /**
+     * Fetch all documents from a collection with optional query parameters
+     */
+    getAll<T extends DocumentData>(collection: string, params?: QueryParams): Promise<T[]>;
+    /**
+     * Fetch a single document by its ID
+     */
+    getOne<T extends DocumentData>(collection: string, id: string, options?: {
+        populate?: string | string[];
+        expand?: string | string[];
+    }): Promise<T>;
+    /**
+     * Insert a new document into a collection
+     */
+    insert<T extends DocumentData>(collection: string, data: InsertPayload, token?: string): Promise<T>;
+    /**
+     * Update an existing document by its ID (Full replacement)
+     */
+    update<T extends DocumentData>(collection: string, id: string, data: UpdatePayload, token?: string): Promise<T>;
+    /**
+     * Partially update an existing document by its ID
+     */
+    patch<T extends DocumentData>(collection: string, id: string, data: PatchPayload, token?: string): Promise<T>;
+    /**
+     * Delete a document by its ID
+     */
+    delete(collection: string, id: string, token?: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Internal helper to build query string from QueryParams
+     */
+    private buildQueryString;
+}
+
+declare class StorageModule {
+    private client;
+    constructor(client: UrBackendClient);
+    /**
+     * Upload a file to storage
+     */
+    upload(file: unknown, filename?: string): Promise<UploadResponse>;
+    /**
+     * Delete a file from storage by its path
+     */
+    deleteFile(path: string): Promise<{
+        deleted: boolean;
+    }>;
+}
+
+declare class SchemaModule {
+    private client;
+    constructor(client: UrBackendClient);
+    /**
+     * Fetch the schema definition for a collection
+     */
+    getSchema(collection: string): Promise<CollectionSchema>;
+}
+
+declare class MailModule {
+    private client;
+    constructor(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.
+     */
+    send(payload: SendMailPayload): Promise<SendMailResponse>;
+}
+
+declare class UrBackendClient {
+    private apiKey;
+    private baseUrl;
+    private _auth?;
+    private _db?;
+    private _storage?;
+    private _schema?;
+    private _mail?;
+    private headers;
+    constructor(config: UrBackendConfig);
+    get auth(): AuthModule;
+    get db(): DatabaseModule;
+    get storage(): StorageModule;
+    get schema(): SchemaModule;
+    get mail(): MailModule;
+    getBaseUrl(): string;
+    getApiKey(): string;
+    /**
+     * Internal request handler
+     */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+
+declare class UrBackendError extends Error {
+    message: string;
+    statusCode: number;
+    endpoint: string;
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+declare class AuthError extends UrBackendError {
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+declare class NotFoundError extends UrBackendError {
+    constructor(message: string, endpoint: string);
+}
+declare class RateLimitError extends UrBackendError {
+    retryAfter?: number;
+    constructor(message: string, endpoint: string, retryAfter?: number);
+}
+declare class StorageError extends UrBackendError {
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+declare class ValidationError extends UrBackendError {
+    constructor(message: string, endpoint: string);
+}
+declare function parseApiError(response: Response): Promise<UrBackendError>;
+
+/**
+ * Factory function to create a new urBackend client
+ */
+declare function urBackend(config: UrBackendConfig): UrBackendClient;
+
+export { type ApiResponse, AuthError, AuthModule, type AuthResponse, type AuthUser, type ChangePasswordPayload, type CollectionSchema, DatabaseModule, type DocumentData, type InsertPayload, type LoginPayload, MailModule, NotFoundError, type PatchPayload, type QueryParams, RateLimitError, type RequestOptions, type RequestPasswordResetPayload, type ResendOtpPayload, type ResetPasswordPayload, type SchemaField, SchemaModule, type SendMailPayload, type SendMailResponse, type SignUpPayload, type SocialExchangePayload, type SocialExchangeResponse, StorageError, StorageModule, type UpdatePayload, type UpdateProfilePayload, type UploadResponse, UrBackendClient, type UrBackendConfig, UrBackendError, ValidationError, type VerifyEmailPayload, urBackend as default, parseApiError };