flit-baas 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,481 @@
+/**
+ * Pluggable Storage Adapter for session persistence.
+ * By default, Flit SDK stores sessions strictly in-memory to prevent XSS localStorage leaks.
+ */
+interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/**
+ * Flit SDK Configuration Options
+ */
+interface FlitClientOptions {
+    /**
+     * Unique Application ID provided by Flit
+     */
+    appId: string;
+    /**
+     * Public Anon Key (flit_pk_...) or Secret Service Key (flit_sk_...)
+     * Note: Secret keys (flit_sk_...) are strictly rejected in browser environments for security.
+     */
+    apiKey?: string;
+    /**
+     * Base API endpoint (defaults to https://api.flit.site)
+     */
+    endpoint?: string;
+    /**
+     * Request timeout in milliseconds (default: 15000ms)
+     */
+    timeout?: number;
+    /**
+     * Custom HTTP headers injected into every request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Custom storage adapter for auth sessions.
+     * Defaults to secure in-memory storage (zero localStorage usage to prevent XSS attacks).
+     */
+    storage?: StorageAdapter;
+    /**
+     * Request credentials mode ('include', 'same-origin', 'omit').
+     * Defaults to 'include' to automatically forward HttpOnly session cookies.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Custom fetch implementation (useful for testing or specific edge environments)
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Enable verbose console logging for development
+     */
+    debug?: boolean;
+}
+
+/**
+ * Flit BaaS Database Types & Interfaces
+ */
+interface BaaSRecord {
+    id: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: any;
+}
+type NewBaaSRecord<T> = Omit<T, 'id' | 'createdAt' | 'updatedAt'>;
+interface QueryOptions<T = any> {
+    /**
+     * Maximum number of documents to return (default: 50, max: 200)
+     */
+    limit?: number;
+    /**
+     * Number of documents to skip for pagination
+     */
+    offset?: number;
+    /**
+     * Field name to sort by
+     */
+    orderBy?: keyof T | string;
+    /**
+     * Sort direction
+     */
+    order?: 'asc' | 'desc';
+}
+type FilterCondition<T = any> = {
+    [K in keyof T]?: T[K] | any;
+} & Record<string, any>;
+interface QueryResponse<T> {
+    success: boolean;
+    collection: string;
+    total: number;
+    records: T[];
+    error?: string;
+}
+interface SingleRecordResponse<T> {
+    success: boolean;
+    record?: T;
+    error?: string;
+}
+
+declare class Collection<T = any> {
+    private readonly client;
+    readonly name: string;
+    constructor(client: FlitClient, name: string);
+    /**
+     * Helper to normalize a record returned from the PostgreSQL JSONB document store.
+     * Flattens { id, createdAt, updatedAt, data: { ... } } into a single intuitive object.
+     */
+    private normalizeRecord;
+    /**
+     * Find documents matching optional filters, with pagination and sorting
+     * @param filter Key-value pairs to match against document properties
+     * @param options Query options (limit, offset, orderBy, order)
+     */
+    find(filter?: FilterCondition<T>, options?: QueryOptions<T>): Promise<T[]>;
+    /**
+     * Find a single document by its unique ID
+     * @param id Document UUID
+     */
+    findById(id: string): Promise<T | null>;
+    /**
+     * Insert a new document into the collection
+     * @param data The document payload (without id, createdAt, updatedAt)
+     */
+    insert(data: NewBaaSRecord<T>): Promise<T>;
+    /**
+     * Insert multiple documents sequentially
+     * @param items Array of document payloads
+     */
+    insertMany(items: Array<NewBaaSRecord<T>>): Promise<T[]>;
+    /**
+     * Update an existing document by ID
+     * @param id Document UUID
+     * @param data Partial update payload
+     */
+    update(id: string, data: Partial<T>): Promise<T>;
+    /**
+     * Delete a document by ID
+     * @param id Document UUID
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Count documents matching an optional filter
+     */
+    count(filter?: FilterCondition<T>): Promise<number>;
+}
+
+/**
+ * Mobile Money & Payment Types
+ */
+type MobileMoneyOperator = 'ORANGE' | 'MTN' | 'WAVE' | 'AIRTEL' | 'MOOV' | 'MPESA';
+type PaymentCurrency = 'XAF' | 'XOF' | 'KES' | 'GHS' | 'USD';
+type PaymentStatus = 'PENDING' | 'SUCCESS' | 'FAILED' | 'EXPIRED' | 'CANCELLED';
+interface PaymentInitiateRequest {
+    /**
+     * Mobile Money Operator (Orange Money, MTN MoMo, Wave, etc.)
+     */
+    operator: MobileMoneyOperator;
+    /**
+     * Recipient / Customer phone number (international or national format)
+     * Examples: "+237690000000", "690000000", "770000000"
+     */
+    phone: string;
+    /**
+     * Amount in specified currency (must be positive integer or decimal)
+     */
+    amount: number;
+    /**
+     * Regional Currency (default: 'XAF')
+     */
+    currency?: PaymentCurrency;
+    /**
+     * Order / Transaction title or memo displayed to customer
+     */
+    title?: string;
+    /**
+     * Customer full name
+     */
+    customerName?: string;
+    /**
+     * Customer email address
+     */
+    customerEmail?: string;
+    /**
+     * Custom metadata payload returned with webhook callbacks
+     */
+    metadata?: Record<string, any>;
+}
+interface PaymentInitiateResponse {
+    success: boolean;
+    transactionId: string;
+    depositId?: string;
+    status: PaymentStatus;
+    operator: MobileMoneyOperator;
+    amount: number;
+    currency: PaymentCurrency;
+    message?: string;
+}
+interface PaymentStatusResponse {
+    success: boolean;
+    transactionId: string;
+    status: PaymentStatus;
+    operator: MobileMoneyOperator;
+    amount: number;
+    currency: PaymentCurrency;
+    createdAt: string;
+    completedAt?: string;
+    errorMessage?: string;
+    metadata?: Record<string, any>;
+}
+
+declare class FlitPayments {
+    private readonly client;
+    constructor(client: FlitClient);
+    /**
+     * Initiate a Mobile Money STK Push deposit (Orange Money, MTN MoMo, Wave, etc.)
+     * @param order Payment order specifications
+     */
+    initiate(order: PaymentInitiateRequest): Promise<PaymentInitiateResponse>;
+    /**
+     * Retrieve current real-time status of a payment transaction
+     * @param transactionId Transaction or deposit reference
+     */
+    getStatus(transactionId: string): Promise<PaymentStatusResponse>;
+    /**
+     * Poll for transaction completion until a final status (SUCCESS, FAILED, EXPIRED) is reached
+     * @param transactionId Transaction reference
+     * @param options Polling configuration (timeoutMs default 60000ms, intervalMs default 3000ms)
+     */
+    waitForStatus(transactionId: string, options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<PaymentStatusResponse>;
+}
+
+/**
+ * Authentication Types & Interfaces
+ */
+interface AuthUser {
+    id: string;
+    email: string;
+    name?: string;
+    phone?: string;
+    role?: string;
+    metadata?: Record<string, any>;
+    createdAt: string;
+    updatedAt?: string;
+}
+interface AuthSession {
+    token: string;
+    refreshToken?: string;
+    expiresAt: number;
+    user: AuthUser;
+}
+interface SignUpCredentials {
+    email: string;
+    password?: string;
+    name?: string;
+    phone?: string;
+    metadata?: Record<string, any>;
+}
+interface SignInCredentials {
+    email: string;
+    password?: string;
+    phone?: string;
+}
+interface AuthResponse {
+    success: boolean;
+    user?: AuthUser;
+    session?: AuthSession;
+    error?: string;
+}
+
+/**
+ * Universal Cookie & Cryptographic Utilities
+ * In strict compliance with Web Security Standards:
+ * - RFC 6265 Cookies with HttpOnly, Secure, and SameSite=Lax flags
+ * - AES-256-GCM authenticated symmetric encryption via standard Web Crypto API (crypto.subtle)
+ * - Zero XSS vulnerability: Tokens never touch document.cookie or localStorage
+ */
+interface CookieOptions {
+    name?: string;
+    path?: string;
+    maxAge?: number;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Lax' | 'Strict' | 'None';
+}
+interface EncryptedSessionPayload {
+    token: string;
+    userId: string;
+    appId: string;
+    expiresAt: number;
+    [key: string]: any;
+}
+/**
+ * Encrypt a session payload into a compact base64-encoded string using AES-256-GCM
+ */
+declare function encryptSession(payload: EncryptedSessionPayload, secretKey: string): Promise<string>;
+/**
+ * Decrypt and verify an AES-256-GCM encrypted session string
+ */
+declare function decryptSession(encryptedText: string, secretKey: string): Promise<EncryptedSessionPayload | null>;
+/**
+ * Build a standard RFC 6265 Set-Cookie header string with HttpOnly and Secure flags
+ */
+declare function buildSetCookieHeader(value: string, options?: CookieOptions): string;
+/**
+ * Build a Set-Cookie header to immediately expire and delete the session cookie
+ */
+declare function buildClearCookieHeader(options?: CookieOptions): string;
+/**
+ * Parse a specific cookie value from an incoming `Cookie` header string
+ */
+declare function parseCookieFromHeader(cookieHeader: string | null | undefined, cookieName?: string): string | null;
+
+declare class FlitAuth {
+    private readonly client;
+    private readonly storage?;
+    private currentSession;
+    private readonly storageKey;
+    constructor(client: FlitClient, storage?: StorageAdapter);
+    /**
+     * Initialize session securely.
+     * If a custom storage adapter was provided (e.g. secure encrypted cookie store),
+     * load the session from it. Otherwise keep in-memory only (zero XSS localStorage exposure).
+     */
+    private initSession;
+    private persistSession;
+    /**
+     * Register a new user
+     */
+    signUp(credentials: SignUpCredentials): Promise<AuthResponse>;
+    /**
+     * Sign in an existing user with email and password
+     */
+    signInWithPassword(credentials: SignInCredentials): Promise<AuthResponse>;
+    /**
+     * Sign out the currently authenticated user
+     */
+    signOut(): Promise<void>;
+    /**
+     * Get current session if available (in-memory)
+     */
+    getSession(): AuthSession | null;
+    /**
+     * Get current user if authenticated
+     */
+    getUser(): AuthUser | null;
+    /**
+     * Server-Side Helper: Generate a cryptographically encrypted (AES-256-GCM) HttpOnly Set-Cookie header.
+     * Immunizes authentication tokens against XSS attacks.
+     *
+     * @param session The authenticated session to encrypt
+     * @param secretKey Encryption key (defaults to client's secret apiKey or appId)
+     * @param options Custom cookie attributes (Path, Domain, Max-Age, etc.)
+     */
+    createSessionCookie(session: AuthSession, secretKey?: string, options?: CookieOptions): Promise<string>;
+    /**
+     * Server-Side Helper: Decrypt and verify an incoming HttpOnly cookie header using AES-256-GCM.
+     *
+     * @param cookieHeader The incoming Cookie request header string
+     * @param secretKey Encryption key (must match the key used in createSessionCookie)
+     */
+    verifySessionCookie(cookieHeader: string | null | undefined, secretKey?: string, cookieName?: string): Promise<EncryptedSessionPayload | null>;
+    /**
+     * Server-Side Helper: Generate a Set-Cookie header that expires and destroys the session cookie.
+     */
+    clearSessionCookie(options?: CookieOptions): string;
+}
+
+interface StorageUploadResponse {
+    success: boolean;
+    url: string;
+    key: string;
+    size?: number;
+    contentType?: string;
+}
+declare class FlitStorage {
+    private readonly client;
+    constructor(client: FlitClient);
+    /**
+     * Upload a file (Blob, File, or Buffer) to Flit Cloud Storage
+     */
+    upload(file: any, fileName: string, options?: {
+        contentType?: string;
+    }): Promise<StorageUploadResponse>;
+    /**
+     * Generate a public URL for a stored asset
+     */
+    getPublicUrl(key: string): string;
+}
+
+declare class FlitClient {
+    readonly appId: string;
+    readonly apiKey?: string;
+    readonly endpoint: string;
+    readonly timeout: number;
+    private readonly customHeaders;
+    private readonly customFetch?;
+    private readonly debug;
+    private readonly credentials;
+    private readonly _storageAdapter?;
+    private _payments?;
+    private _auth?;
+    private _storage?;
+    constructor(options: FlitClientOptions);
+    /**
+     * Access a database collection
+     * @param name Name of the collection (e.g. 'products', 'users', 'orders')
+     */
+    collection<T = any>(name: string): Collection<T>;
+    /**
+     * Access Mobile Money payments service (Orange Money, MTN MoMo, Wave)
+     */
+    get payments(): FlitPayments;
+    /**
+     * Access Authentication service
+     */
+    get auth(): FlitAuth;
+    /**
+     * Access Storage & File upload service
+     */
+    get storage(): FlitStorage;
+    /**
+     * Internal HTTP request transport with timeout and error handling
+     */
+    request<T = any>(path: string, init?: RequestInit): Promise<T>;
+}
+
+/**
+ * Flit SDK Error Hierarchy
+ */
+declare class FlitError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+declare class FlitAPIError extends FlitError {
+    readonly status: number;
+    readonly details?: any;
+    constructor(message: string, status: number, code?: string, details?: any);
+}
+declare class FlitPaymentError extends FlitError {
+    readonly operator?: string;
+    readonly transactionId?: string;
+    constructor(message: string, operator?: string, transactionId?: string);
+}
+declare class FlitAuthError extends FlitError {
+    constructor(message: string, code?: string);
+}
+
+/**
+ * Flit BaaS & Mobile Money SDK
+ * Official TypeScript Client Library
+ */
+
+/**
+ * Creates and initializes a new Flit BaaS Client instance
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@flit/baas';
+ *
+ * export const flit = createClient({
+ *   appId: process.env.NEXT_PUBLIC_FLIT_APP_ID!,
+ *   apiKey: process.env.NEXT_PUBLIC_FLIT_API_KEY!,
+ * });
+ *
+ * // Query documents
+ * const products = await flit.collection('products').find();
+ *
+ * // Initiate Mobile Money payment
+ * const payment = await flit.payments.initiate({
+ *   operator: 'ORANGE',
+ *   phone: '690000000',
+ *   amount: 15000,
+ * });
+ * ```
+ */
+declare function createClient(options: FlitClientOptions): FlitClient;
+
+export { type AuthResponse, type AuthSession, type AuthUser, type BaaSRecord, Collection, type CookieOptions, type EncryptedSessionPayload, type FilterCondition, FlitAPIError, FlitAuth, FlitAuthError, FlitClient, type FlitClientOptions, FlitError, FlitPaymentError, FlitPayments, FlitStorage, type MobileMoneyOperator, type NewBaaSRecord, type PaymentCurrency, type PaymentInitiateRequest, type PaymentInitiateResponse, type PaymentStatus, type PaymentStatusResponse, type QueryOptions, type QueryResponse, type SignInCredentials, type SignUpCredentials, type SingleRecordResponse, type StorageAdapter, buildClearCookieHeader, buildSetCookieHeader, createClient, decryptSession, createClient as default, encryptSession, parseCookieFromHeader };