@aerostack/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,577 @@
+/**
+ * Client-side error handling for Aerostack SDK
+ */
+declare enum ClientErrorCode {
+    AUTH_INVALID_CREDENTIALS = "AUTH_INVALID_CREDENTIALS",
+    AUTH_USER_EXISTS = "AUTH_USER_EXISTS",
+    AUTH_EMAIL_NOT_VERIFIED = "AUTH_EMAIL_NOT_VERIFIED",
+    AUTH_TOKEN_EXPIRED = "AUTH_TOKEN_EXPIRED",
+    AUTH_TOKEN_INVALID = "AUTH_TOKEN_INVALID",
+    AUTH_OTP_EXPIRED = "AUTH_OTP_EXPIRED",
+    AUTH_OTP_INVALID = "AUTH_OTP_INVALID",
+    AUTH_PASSWORD_WEAK = "AUTH_PASSWORD_WEAK",
+    AUTH_RESET_TOKEN_INVALID = "AUTH_RESET_TOKEN_INVALID",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    NETWORK_TIMEOUT = "NETWORK_TIMEOUT",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    REQUEST_FAILED = "REQUEST_FAILED",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+interface ClientErrorDetails {
+    suggestion?: string;
+    field?: string;
+    recoveryAction?: string;
+}
+/**
+ * Base error class for client-side SDK
+ */
+declare class ClientError extends Error {
+    code: ClientErrorCode;
+    details?: ClientErrorDetails | undefined;
+    statusCode?: number | undefined;
+    constructor(code: ClientErrorCode, message: string, details?: ClientErrorDetails | undefined, statusCode?: number | undefined);
+    /**
+     * Check if this is an authentication error
+     */
+    isAuthError(): boolean;
+    /**
+     * Check if this is a network error
+     */
+    isNetworkError(): boolean;
+    /**
+     * Check if this is a validation error
+     */
+    isValidationError(): boolean;
+    toJSON(): {
+        name: string;
+        code: ClientErrorCode;
+        message: string;
+        details: ClientErrorDetails | undefined;
+        statusCode: number | undefined;
+    };
+}
+/**
+ * Authentication-specific errors
+ */
+declare class AuthenticationError extends ClientError {
+    constructor(code: ClientErrorCode, message: string, details?: ClientErrorDetails, statusCode?: number);
+}
+/**
+ * Validation-specific errors
+ */
+declare class ValidationError extends ClientError {
+    constructor(message: string, field?: string, suggestion?: string);
+}
+/**
+ * Network-specific errors
+ */
+declare class NetworkError extends ClientError {
+    constructor(message: string, suggestion?: string);
+}
+
+interface SDKConfig {
+    projectSlug: string;
+    baseUrl?: string;
+}
+interface AuthResponse {
+    success: boolean;
+    user?: User;
+    token?: string;
+    refreshToken?: string;
+    expiresAt?: string;
+    error?: string;
+    requiresVerification?: boolean;
+}
+interface User {
+    id: string;
+    email: string;
+    name?: string;
+    emailVerified: boolean;
+    createdAt: string;
+    customFields?: Record<string, any>;
+}
+interface RegisterData {
+    email: string;
+    password: string;
+    name?: string;
+    customFields?: Record<string, any>;
+}
+interface OTPResponse {
+    success: boolean;
+    message?: string;
+    error?: string;
+}
+interface VerifyResponse {
+    success: boolean;
+    message?: string;
+    error?: string;
+}
+interface ResetResponse {
+    success: boolean;
+    message?: string;
+    error?: string;
+}
+interface LogoutResponse {
+    success: boolean;
+}
+interface ProfileUpdate {
+    name?: string;
+    customFields?: Record<string, any>;
+}
+/**
+ * Aerostack Client SDK
+ *
+ * Provides client-side authentication and (future) ecommerce features
+ * Focused on:
+ * - Complete authentication flows
+ * - Password reset
+ * - Session management
+ * - User profile management
+ */
+declare class AerostackClient {
+    private projectSlug;
+    private baseUrl;
+    constructor(config: SDKConfig);
+    /**
+     * Authentication operations
+     */
+    get auth(): {
+        /**
+         * Register a new user
+         */
+        register: (data: RegisterData) => Promise<AuthResponse>;
+        /**
+         * Login with email and password
+         */
+        login: (email: string, password: string) => Promise<AuthResponse>;
+        /**
+         * Send OTP code to email
+         */
+        sendOTP: (email: string) => Promise<OTPResponse>;
+        /**
+         * Verify OTP code and login
+         */
+        verifyOTP: (email: string, code: string) => Promise<AuthResponse>;
+        /**
+         * Verify email with token
+         */
+        verifyEmail: (token: string) => Promise<VerifyResponse>;
+        /**
+         * Request password reset email
+         */
+        requestPasswordReset: (email: string) => Promise<ResetResponse>;
+        /**
+         * Reset password with token
+         */
+        resetPassword: (token: string, newPassword: string) => Promise<AuthResponse>;
+        /**
+         * Refresh access token using refresh token
+         */
+        refreshToken: (refreshToken: string) => Promise<AuthResponse>;
+        /**
+         * Logout and invalidate tokens
+         */
+        logout: (token: string) => Promise<LogoutResponse>;
+        /**
+         * Get current user profile
+         */
+        getCurrentUser: (token: string) => Promise<User>;
+        /**
+         * Update user profile
+         */
+        updateProfile: (token: string, updates: ProfileUpdate) => Promise<User>;
+    };
+    /**
+     * Make HTTP request with comprehensive error handling
+     */
+    private request;
+    /**
+     * Map API error codes to client error codes
+     */
+    private mapErrorCode;
+    /**
+     * Get helpful suggestion based on error code
+     */
+    private getSuggestion;
+}
+
+/**
+ * Type definitions for Aerostack Server SDK
+ */
+interface DatabaseResponse<T = any> {
+    results: T[];
+    success: boolean;
+    meta: {
+        target: 'd1' | 'postgres';
+        rowCount?: number;
+        duration?: number;
+    };
+}
+interface RoutingRules {
+    tables: Record<string, 'd1' | 'postgres'>;
+}
+interface SchemaColumn {
+    name: string;
+    type: string;
+    nullable: boolean;
+    defaultValue?: any;
+    isPrimaryKey?: boolean;
+}
+interface SchemaTable {
+    name: string;
+    columns: SchemaColumn[];
+    database: 'd1' | 'postgres';
+}
+interface SchemaInfo {
+    tables: SchemaTable[];
+    database: 'd1' | 'postgres';
+}
+interface Transaction {
+    query<T = any>(sql: string, params?: any[]): Promise<DatabaseResponse<T>>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}
+interface BatchQuery {
+    sql: string;
+    params?: any[];
+}
+interface BatchResult {
+    results: DatabaseResponse[];
+    success: boolean;
+    errors?: Array<{
+        index: number;
+        error: Error;
+    }>;
+}
+interface CacheOptions {
+    ttl?: number;
+    expirationTtl?: number;
+}
+interface CacheGetOptions {
+    type?: 'text' | 'json' | 'arrayBuffer' | 'stream';
+}
+interface Job {
+    type: string;
+    data: any;
+    delay?: number;
+    retries?: number;
+}
+interface JobResult {
+    jobId: string;
+    status: 'queued' | 'processing' | 'completed' | 'failed';
+    queuedAt: Date;
+}
+interface JobStatus {
+    id: string;
+    type: string;
+    status: 'queued' | 'processing' | 'completed' | 'failed';
+    attempts: number;
+    createdAt: Date;
+    completedAt?: Date;
+    error?: string;
+}
+interface UploadOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+    cacheControl?: string;
+}
+interface UploadResult {
+    key: string;
+    url: string;
+    size: number;
+    contentType: string;
+}
+interface UrlOptions {
+    expiresIn?: number;
+    download?: boolean;
+}
+interface StorageObject {
+    key: string;
+    size: number;
+    uploaded: Date;
+    contentType?: string;
+}
+interface Message {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface ChatOptions {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+}
+interface ChatResponse {
+    response: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface EmbedOptions {
+    model?: string;
+}
+interface Embedding {
+    embedding: number[];
+    model: string;
+}
+interface GenerateOptions {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+interface GenerationResult {
+    text: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+}
+interface InvokeOptions {
+    timeout?: number;
+}
+interface AuthContext {
+    user?: any;
+    request: Request;
+}
+interface AuthHookResult {
+    allow: boolean;
+    user?: any;
+    error?: string;
+}
+interface AerostackEnv {
+    DB?: D1Database;
+    CACHE?: KVNamespace;
+    QUEUE?: Queue;
+    STORAGE?: R2Bucket;
+    AI?: Ai;
+    DISPATCHER?: DurableObjectNamespace;
+    [key: string]: any;
+}
+
+/**
+ * Server-side error handling for Aerostack SDK
+ * Provides structured errors with actionable suggestions
+ */
+declare enum ErrorCode {
+    DB_CONNECTION_FAILED = "DB_CONNECTION_FAILED",
+    DB_QUERY_FAILED = "DB_QUERY_FAILED",
+    DB_TABLE_NOT_FOUND = "DB_TABLE_NOT_FOUND",
+    DB_COLUMN_NOT_FOUND = "DB_COLUMN_NOT_FOUND",
+    DB_AUTH_FAILED = "DB_AUTH_FAILED",
+    DB_MIGRATION_FAILED = "DB_MIGRATION_FAILED",
+    DB_TRANSACTION_FAILED = "DB_TRANSACTION_FAILED",
+    CACHE_GET_FAILED = "CACHE_GET_FAILED",
+    CACHE_SET_FAILED = "CACHE_SET_FAILED",
+    CACHE_DELETE_FAILED = "CACHE_DELETE_FAILED",
+    CACHE_NOT_CONFIGURED = "CACHE_NOT_CONFIGURED",
+    QUEUE_ENQUEUE_FAILED = "QUEUE_ENQUEUE_FAILED",
+    QUEUE_NOT_CONFIGURED = "QUEUE_NOT_CONFIGURED",
+    QUEUE_JOB_NOT_FOUND = "QUEUE_JOB_NOT_FOUND",
+    STORAGE_UPLOAD_FAILED = "STORAGE_UPLOAD_FAILED",
+    STORAGE_DELETE_FAILED = "STORAGE_DELETE_FAILED",
+    STORAGE_NOT_CONFIGURED = "STORAGE_NOT_CONFIGURED",
+    STORAGE_FILE_TOO_LARGE = "STORAGE_FILE_TOO_LARGE",
+    AI_REQUEST_FAILED = "AI_REQUEST_FAILED",
+    AI_NOT_CONFIGURED = "AI_NOT_CONFIGURED",
+    AI_RATE_LIMIT = "AI_RATE_LIMIT",
+    SERVICE_INVOKE_FAILED = "SERVICE_INVOKE_FAILED",
+    SERVICE_NOT_FOUND = "SERVICE_NOT_FOUND",
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+interface ErrorDetails {
+    suggestion?: string;
+    recoveryAction?: string;
+    field?: string;
+    cause?: string;
+}
+/**
+ * Base error class for all server-side errors
+ */
+declare class ServerError extends Error {
+    code: ErrorCode;
+    details?: ErrorDetails | undefined;
+    context?: Record<string, any> | undefined;
+    constructor(code: ErrorCode, message: string, details?: ErrorDetails | undefined, context?: Record<string, any> | undefined);
+    toJSON(): {
+        name: string;
+        code: ErrorCode;
+        message: string;
+        details: ErrorDetails | undefined;
+        context: Record<string, any> | undefined;
+    };
+}
+/**
+ * Database-related errors
+ */
+declare class DatabaseError extends ServerError {
+    constructor(code: ErrorCode, message: string, details?: ErrorDetails, context?: Record<string, any>);
+    /**
+     * Create error from Postgres error
+     */
+    static fromPostgresError(err: any, context?: Record<string, any>): DatabaseError;
+    /**
+     * Create error from D1 error
+     */
+    static fromD1Error(err: any, context?: Record<string, any>): DatabaseError;
+}
+/**
+ * Cache-related errors
+ */
+declare class CacheError extends ServerError {
+    constructor(code: ErrorCode, message: string, details?: ErrorDetails, context?: Record<string, any>);
+}
+/**
+ * Queue-related errors
+ */
+declare class QueueError extends ServerError {
+    constructor(code: ErrorCode, message: string, details?: ErrorDetails, context?: Record<string, any>);
+}
+/**
+ * Storage-related errors
+ */
+declare class StorageError extends ServerError {
+    constructor(code: ErrorCode, message: string, details?: ErrorDetails, context?: Record<string, any>);
+}
+/**
+ * AI-related errors
+ */
+declare class AIError extends ServerError {
+    constructor(code: ErrorCode, message: string, details?: ErrorDetails, context?: Record<string, any>);
+}
+/**
+ * Service invocation errors
+ */
+declare class ServiceError extends ServerError {
+    constructor(code: ErrorCode, message: string, details?: ErrorDetails, context?: Record<string, any>);
+}
+
+/**
+ * AerostackServer provides comprehensive server-side SDK for Cloudflare Workers
+ *
+ * Features:
+ * - Multi-database operations (D1 + Postgres with intelligent routing)
+ * - KV cache operations
+ * - Queue operations for background jobs
+ * - R2 storage operations
+ * - AI operations (chat, embeddings, generation)
+ * - Service invocation via Workers Dispatch
+ */
+declare class AerostackServer {
+    private pgPool?;
+    private _d1?;
+    private _kv?;
+    private _queue?;
+    private _storage?;
+    private _ai?;
+    private _dispatcher?;
+    private routingRules;
+    private env;
+    constructor(env: AerostackEnv, options?: {
+        routing?: RoutingRules;
+    });
+    /**
+     * Database operations with intelligent routing between D1 and Postgres
+     */
+    get db(): {
+        /**
+         * Execute a SQL query with automatic routing
+         */
+        query: <T = any>(sql: string, params?: any[]) => Promise<DatabaseResponse<T>>;
+        /**
+         * Get database schema information
+         */
+        getSchema: (binding?: string) => Promise<SchemaInfo>;
+        /**
+         * Execute multiple queries in a batch
+         */
+        batch: (queries: BatchQuery[]) => Promise<BatchResult>;
+    };
+    /**
+     * KV Cache operations
+     */
+    get cache(): {
+        /**
+         * Get value from cache
+         */
+        get: <T = any>(key: string, options?: CacheGetOptions) => Promise<T | null>;
+        /**
+         * Set value in cache
+         */
+        set: (key: string, value: any, options?: CacheOptions) => Promise<void>;
+        /**
+         * Delete value from cache
+         */
+        delete: (key: string) => Promise<void>;
+        /**
+         * Check if key exists in cache
+         */
+        exists: (key: string) => Promise<boolean>;
+    };
+    /**
+     * Queue operations for background jobs
+     */
+    get queue(): {
+        /**
+         * Add job to queue
+         */
+        enqueue: (job: Job) => Promise<JobResult>;
+    };
+    /**
+     * R2 Storage operations
+     */
+    get storage(): {
+        /**
+         * Upload file to R2 storage
+         */
+        upload: (file: ReadableStream | ArrayBuffer | string, key: string, options?: UploadOptions) => Promise<UploadResult>;
+        /**
+         * Get presigned URL for object
+         */
+        getUrl: (key: string, options?: UrlOptions) => Promise<string>;
+        /**
+         * Delete object from storage
+         */
+        delete: (key: string) => Promise<void>;
+        /**
+         * List objects in storage
+         */
+        list: (prefix?: string) => Promise<StorageObject[]>;
+    };
+    /**
+     * AI operations using Cloudflare AI
+     */
+    get ai(): {
+        /**
+         * Generate chat completion
+         */
+        chat: (messages: Message[], options?: ChatOptions) => Promise<ChatResponse>;
+        /**
+         * Generate text embeddings
+         */
+        embed: (text: string, options?: EmbedOptions) => Promise<Embedding>;
+        /**
+         * Generate text from prompt
+         */
+        generate: (prompt: string, options?: GenerateOptions) => Promise<GenerationResult>;
+    };
+    /**
+     * Service invocation via Workers Dispatch
+     */
+    get services(): {
+        /**
+         * Invoke another service via RPC
+         */
+        invoke: (serviceName: string, data: any, options?: InvokeOptions) => Promise<any>;
+    };
+    private routeQuery;
+    private determineTarget;
+    private introspectD1;
+    private introspectPostgres;
+    private findPostgresConnStr;
+}
+
+export { AIError, AerostackClient, type AerostackEnv, AerostackServer, type AuthContext, type AuthHookResult, type AuthResponse, AuthenticationError, type BatchQuery, type BatchResult, CacheError, type CacheGetOptions, type CacheOptions, type ChatOptions, type ChatResponse, ClientError, ClientErrorCode, type ClientErrorDetails, DatabaseError, type DatabaseResponse, type EmbedOptions, type Embedding, ErrorCode, type ErrorDetails, type GenerateOptions, type GenerationResult, type InvokeOptions, type Job, type JobResult, type JobStatus, type LogoutResponse, type Message, NetworkError, type OTPResponse, type ProfileUpdate, QueueError, type RegisterData, type ResetResponse, type RoutingRules, type SDKConfig, type SchemaColumn, type SchemaInfo, type SchemaTable, ServerError, ServiceError, StorageError, type StorageObject, type Transaction, type UploadOptions, type UploadResult, type UrlOptions, type User, ValidationError, type VerifyResponse };