zdata-client/dist/types.d.ts

TypeScript client library for zdata backend API with authentication and full CRUD operations

/**
 * @fileoverview Type definitions for the zdata-client library
 */
/**
 * Base entity metadata that gets added by the database
 */
export interface BaseEntity {
    /** Unique identifier */
    readonly id: string;
    /** Creation timestamp */
    readonly created_at: string;
    /** Last update timestamp */
    readonly updated_at: string;
}
/**
 * Entity for creation (without database-generated fields)
 * @template T - The entity type without base fields
 */
export type CreateEntity<T> = Omit<T, keyof BaseEntity>;
/**
 * Entity returned from database (with all metadata)
 * @template T - The entity type
 */
export type EntityWithBase<T> = T & BaseEntity;
/**
 * Metadata for paginated responses
 */
export interface PaginationMeta {
    /** Current active page number (1-based) */
    readonly activePageNumber: number;
    /** Number of records per page */
    readonly limit: number;
    /** Total number of records available */
    readonly totalRecords: number;
    /** Total number of pages available */
    readonly totalPages: number;
    /** Whether there is a next page available */
    readonly hasNext: boolean;
    /** Whether there is a previous page available */
    readonly hasPrev: boolean;
}
/**
 * Generic paginated response structure
 * @template T - Type of the records in the response
 */
export interface PaginatedResponse<T = unknown> {
    /** Array of records for the current page */
    readonly records: readonly T[];
    /** Pagination metadata */
    readonly meta: PaginationMeta;
}
/**
 * Login request payload
 */
export interface LoginRequest {
    /** User's email address */
    readonly email: string;
    /** User's password */
    readonly password: string;
}
/**
 * User registration request payload
 */
export interface RegisterRequest {
    /** User's full name */
    readonly name: string;
    /** User's email address */
    readonly email: string;
    /** User's password */
    readonly password: string;
}
/**
 * User information returned from authentication
 */
export interface User {
    /** Unique user identifier */
    readonly id: string;
    /** User's email address */
    readonly email: string;
    /** User's full name */
    readonly name: string;
}
/**
 * Authentication response from login/register operations
 */
export interface AuthResponse {
    /** JWT access token for API authentication */
    readonly access_token: string;
    /** Token expiration time in seconds */
    readonly expires_in: number;
    /** Type of token (typically "Bearer") */
    readonly token_type: string;
    /** Authenticated user information */
    readonly user: User;
}
/**
 * Detailed validation error information
 */
export interface ValidationErrorDetail {
    /** Error code identifier */
    readonly code: string;
    /** JSON path to the field that caused the error */
    readonly path: readonly string[];
    /** Human-readable error message */
    readonly message: string;
}
/**
 * API error response structure
 */
export interface ApiError {
    /** Main error message */
    readonly message: string;
    /** Detailed validation errors (if applicable) */
    readonly errors?: readonly ValidationErrorDetail[];
}
/**
 * Configuration options for the API client
 */
export interface ApiConfig {
    /** Base URL of the API server */
    readonly baseUrl: string;
    /** Workspace identifier for API requests */
    readonly workspaceId: string;
    /** Request timeout in milliseconds (default: 10000) */
    readonly timeout?: number;
    /** Additional HTTP headers to include in requests */
    readonly headers?: Readonly<Record<string, string>>;
}
/**
 * Parameters for finding records with pagination and search
 */
export interface FindRecordsParams {
    /** Name of the resource to query */
    readonly resourceName: string;
    /** Search query string (optional) */
    readonly search?: string;
    /** Page number (1-based, default: 1) */
    readonly page?: number;
    /** Number of records per page (default: 10) */
    readonly limit?: number;
}
/**
 * Interface defining the contract for the API client
 * Provides authentication and CRUD operations for the zdata backend
 */
export interface IApiClient {
    /**
     * Authenticate user with email and password
     * @param credentials - User login credentials
     * @returns Promise resolving to authentication response
     * @throws {InvalidCredentialsError} When credentials are invalid
     * @throws {ApiClientError} When API request fails
     */
    login(credentials: LoginRequest): Promise<AuthResponse>;
    /**
     * Register a new user account
     * @param userData - User registration data
     * @returns Promise resolving to authentication response
     * @throws {ValidationError} When registration data is invalid
     * @throws {ApiClientError} When API request fails
     */
    register(userData: RegisterRequest): Promise<AuthResponse>;
    /**
     * Clear authentication token and log out user
     */
    logout(): void;
    /**
     * Check if user is currently authenticated
     * @returns True if user has a valid access token
     */
    isAuthenticated(): boolean;
    /**
     * Create a new record in the specified resource
     * @template T - The entity type to create
     * @param resourceName - Name of the resource
     * @param data - Record data to create
     * @returns Promise resolving to the created record with base entity fields
     * @throws {ValidationError} When record data is invalid
     * @throws {ApiClientError} When API request fails
     */
    createRecord<T = unknown>(resourceName: string, data: CreateEntity<T>): Promise<EntityWithBase<T>>;
    /**
     * Update an existing record
     * @template T - The entity type to update
     * @param resourceName - Name of the resource
     * @param id - Record identifier
     * @param data - Updated record data
     * @returns Promise resolving to the updated record with base entity fields
     * @throws {ValidationError} When record data is invalid
     * @throws {ApiClientError} When API request fails
     */
    updateRecord<T = unknown>(resourceName: string, id: string, data: Partial<CreateEntity<T>>): Promise<EntityWithBase<T>>;
    /**
     * Delete a record by ID
     * @param resourceName - Name of the resource
     * @param id - Record identifier
     * @returns Promise that resolves when deletion is complete
     * @throws {ApiClientError} When API request fails
     */
    deleteRecord(resourceName: string, id: string): Promise<void>;
    /**
     * Find a specific record by ID
     * @template T - The entity type to return
     * @param resourceName - Name of the resource
     * @param id - Record identifier
     * @returns Promise resolving to the found record with base entity fields
     * @throws {ApiClientError} When record is not found or API request fails
     */
    findRecordById<T = unknown>(resourceName: string, id: string): Promise<EntityWithBase<T>>;
    /**
     * Find records with pagination and optional search
     * @template T - The entity type to return
     * @param params - Query parameters including resource name, pagination, and search
     * @returns Promise resolving to paginated response with entities containing base fields
     * @throws {ApiClientError} When API request fails
     */
    findRecords<T = unknown>(params: FindRecordsParams): Promise<PaginatedResponse<EntityWithBase<T>>>;
    /**
     * Set the access token for authentication
     * @param token - JWT access token
     * @throws {Error} When token is invalid
     */
    setAccessToken(token: string): void;
    /**
     * Get the current access token
     * @returns Current access token or null if not authenticated
     */
    getAccessToken(): string | null;
}
/**
 * Error thrown when authentication credentials are invalid
 */
export declare class InvalidCredentialsError extends Error {
    readonly name = "InvalidCredentialsError";
    constructor(message?: string);
}
/**
 * Error thrown when request data fails validation
 */
export declare class ValidationError extends Error {
    readonly name = "ValidationError";
    readonly errors: readonly ValidationErrorDetail[];
    constructor(message?: string, errors?: readonly ValidationErrorDetail[]);
}
/**
 * General API client error for HTTP and network issues
 */
export declare class ApiClientError extends Error {
    readonly name = "ApiClientError";
    readonly statusCode?: number;
    constructor(message: string, statusCode?: number);
}
/**
 * Type guard to check if an error is an InvalidCredentialsError
 */
export declare function isInvalidCredentialsError(error: unknown): error is InvalidCredentialsError;
/**
 * Type guard to check if an error is a ValidationError
 */
export declare function isValidationError(error: unknown): error is ValidationError;
/**
 * Type guard to check if an error is an ApiClientError
 */
export declare function isApiClientError(error: unknown): error is ApiClientError;
//# sourceMappingURL=types.d.ts.map