@withvlibe/base-sdk 1.0.0

package/dist/VlibeBaseAuth-ChuzgzDl.d.ts

@@ -0,0 +1,562 @@
+/**
+ * Type definitions for @withvlibe/base-sdk
+ */
+/**
+ * App category for Vlibe Base apps
+ */
+type AppCategory = 'website' | 'saas' | 'ecommerce';
+/**
+ * Vlibe Base plan type
+ */
+type BasePlan = 'free' | 'premium';
+/**
+ * Main configuration for Vlibe Base SDK
+ */
+interface VlibeBaseConfig {
+    appId: string;
+    appSecret: string;
+    baseUrl?: string;
+    category?: AppCategory;
+}
+/**
+ * Database client configuration
+ */
+interface DatabaseConfig {
+    projectId: string;
+    databaseToken: string;
+    baseUrl?: string;
+    supabaseUrl?: string;
+}
+/**
+ * Authentication configuration
+ */
+interface AuthConfig {
+    appId: string;
+    appSecret: string;
+    baseUrl?: string;
+}
+/**
+ * Payments configuration
+ */
+interface PaymentsConfig {
+    appId: string;
+    appSecret: string;
+    baseUrl?: string;
+}
+/**
+ * Supported column types for table schemas
+ */
+type ColumnType = 'string' | 'number' | 'boolean' | 'json' | 'datetime';
+/**
+ * Column definition for table creation
+ */
+interface TableColumn {
+    name: string;
+    type: ColumnType;
+    required?: boolean;
+    unique?: boolean;
+    default?: unknown;
+}
+/**
+ * Table schema for creation
+ */
+interface TableSchema {
+    columns: TableColumn[];
+}
+/**
+ * Table information from the database
+ */
+interface TableInfo {
+    name: string;
+    columns: TableColumn[];
+    rowCount: number;
+    createdAt: string;
+}
+/**
+ * Query options for database operations
+ */
+interface QueryOptions {
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+    where?: Record<string, unknown>;
+}
+/**
+ * Base record type with common fields
+ */
+interface BaseRecord {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    [key: string]: unknown;
+}
+/**
+ * Real-time subscription payload
+ */
+interface RealtimePayload<T = BaseRecord> {
+    eventType: 'INSERT' | 'UPDATE' | 'DELETE';
+    new: T | null;
+    old: T | null;
+    table: string;
+}
+/**
+ * Subscription handle for cleanup
+ */
+interface Subscription {
+    unsubscribe: () => void;
+}
+/**
+ * Vlibe user object returned from authentication
+ */
+interface VlibeUser {
+    id: string;
+    email: string;
+    name: string | null;
+    avatarUrl: string | null;
+    subscriptionType: 'platform' | 'individual' | null;
+    appAccess?: {
+        tier: string | null;
+        features: string[];
+    } | null;
+}
+/**
+ * Response from session verification
+ */
+interface VerifyResponse {
+    valid: boolean;
+    user?: VlibeUser;
+    error?: string;
+}
+/**
+ * Authentication session
+ */
+interface AuthSession {
+    user: VlibeUser;
+    token: string;
+    expiresAt: string;
+}
+/**
+ * Options for creating a checkout session
+ */
+interface CheckoutOptions {
+    /** Amount in cents (e.g., 1999 for $19.99) */
+    amount: number;
+    /** Currency code (default: 'usd') */
+    currency?: string;
+    /** User ID to associate with the payment */
+    userId?: string;
+    /** User email for receipt */
+    userEmail?: string;
+    /** Description of the payment */
+    description?: string;
+    /** Metadata to attach to the payment */
+    metadata?: Record<string, string>;
+    /** URL to redirect on success */
+    successUrl: string;
+    /** URL to redirect on cancel */
+    cancelUrl: string;
+}
+/**
+ * Checkout session response
+ */
+interface CheckoutSession {
+    id: string;
+    url: string;
+    amount: number;
+    currency: string;
+    status: string;
+}
+/**
+ * Transaction record
+ */
+interface Transaction {
+    id: string;
+    amount: number;
+    vlibeFee: number;
+    netAmount: number;
+    currency: string;
+    status: 'pending' | 'succeeded' | 'failed' | 'refunded';
+    stripeId?: string;
+    userId?: string;
+    metadata?: Record<string, string>;
+    createdAt: string;
+}
+/**
+ * Refund options
+ */
+interface RefundOptions {
+    transactionId: string;
+    amount?: number;
+    reason?: string;
+}
+/**
+ * Stripe Connect status
+ */
+interface ConnectStatus {
+    connected: boolean;
+    accountId?: string;
+    chargesEnabled?: boolean;
+    payoutsEnabled?: boolean;
+}
+interface Page {
+    id: string;
+    title: string;
+    slug: string;
+    content: string;
+    metaTitle?: string;
+    metaDescription?: string;
+    isPublished: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Media {
+    id: string;
+    filename: string;
+    url: string;
+    mimeType: string;
+    size: number;
+    alt?: string;
+    createdAt: string;
+}
+interface FeatureFlag {
+    id: string;
+    key: string;
+    name: string;
+    description?: string;
+    isEnabled: boolean;
+    tier?: string;
+    createdAt: string;
+}
+interface UsageMetric {
+    id: string;
+    userId: string;
+    metricType: string;
+    value: number;
+    period: string;
+    createdAt: string;
+}
+interface Product {
+    id: string;
+    name: string;
+    description?: string;
+    sku?: string;
+    price: number;
+    currency: string;
+    images: string[];
+    stock: number;
+    isActive: boolean;
+    category?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Order {
+    id: string;
+    userId: string;
+    status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
+    items: OrderItem[];
+    subtotal: number;
+    tax: number;
+    total: number;
+    shippingAddress?: Address;
+    createdAt: string;
+}
+interface OrderItem {
+    productId: string;
+    name: string;
+    quantity: number;
+    price: number;
+}
+interface Address {
+    line1: string;
+    line2?: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country: string;
+}
+interface CartItem {
+    productId: string;
+    quantity: number;
+}
+/**
+ * Standard API response
+ */
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+}
+/**
+ * Paginated API response
+ */
+interface PaginatedResponse<T = unknown> {
+    success: boolean;
+    data: T[];
+    total: number;
+    page: number;
+    limit: number;
+    hasMore: boolean;
+}
+/**
+ * Options for useCollection hook
+ */
+interface UseCollectionOptions {
+    limit?: number;
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+    where?: Record<string, unknown>;
+    realtime?: boolean;
+}
+/**
+ * Return type for useCollection hook
+ */
+interface UseCollectionReturn<T = BaseRecord> {
+    data: T[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    insert: (doc: Partial<T>) => Promise<T | null>;
+    update: (id: string, updates: Partial<T>) => Promise<T | null>;
+    remove: (id: string) => Promise<boolean>;
+}
+/**
+ * Return type for useKV hook
+ */
+interface UseKVReturn<T = unknown> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    set: (value: T) => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Return type for useAuth hook
+ */
+interface UseAuthReturn {
+    user: VlibeUser | null;
+    loading: boolean;
+    error: Error | null;
+    login: (redirectPath?: string) => void;
+    logout: (redirectPath?: string) => void;
+    hasFeature: (feature: string) => boolean;
+    hasSubscription: () => boolean;
+}
+/**
+ * Return type for usePayments hook
+ */
+interface UsePaymentsReturn {
+    loading: boolean;
+    error: Error | null;
+    createCheckout: (options: CheckoutOptions) => Promise<string | null>;
+    transactions: Transaction[];
+    loadTransactions: () => Promise<void>;
+}
+
+/**
+ * VlibeBaseDatabase - Database client for Vlibe Base Apps
+ *
+ * Provides access to the Vlibe managed database for Base apps.
+ * Supports CRUD operations, real-time subscriptions, and key-value storage.
+ *
+ * @example
+ * ```typescript
+ * import { VlibeBaseDatabase } from '@withvlibe/base-sdk';
+ *
+ * const db = new VlibeBaseDatabase({
+ *   projectId: process.env.VLIBE_PROJECT_ID!,
+ *   databaseToken: process.env.VLIBE_DB_TOKEN!,
+ * });
+ *
+ * // CRUD operations
+ * const doc = await db.insert('documents', { title: 'Hello', content: 'World' });
+ * const docs = await db.query('documents');
+ * await db.update('documents', doc.id, { title: 'Updated' });
+ * await db.delete('documents', doc.id);
+ *
+ * // Key-value store
+ * await db.setKV('settings', { theme: 'dark' });
+ * const settings = await db.getKV('settings');
+ * ```
+ */
+
+declare class VlibeBaseDatabase {
+    private projectId;
+    private databaseToken;
+    private baseUrl;
+    private supabaseUrl;
+    private supabase;
+    private subscriptions;
+    /**
+     * Create a new VlibeBaseDatabase instance
+     *
+     * @param config - Database configuration
+     * @throws Error if projectId or databaseToken is missing
+     */
+    constructor(config: DatabaseConfig);
+    /**
+     * Initialize Supabase client for real-time subscriptions
+     */
+    private initSupabase;
+    /**
+     * Make an authenticated API request
+     */
+    private apiRequest;
+    /**
+     * Create a new table
+     */
+    createTable(name: string, schema: TableSchema): Promise<TableInfo>;
+    /**
+     * Get table information
+     */
+    getTable(name: string): Promise<TableInfo | null>;
+    /**
+     * List all tables
+     */
+    listTables(): Promise<TableInfo[]>;
+    /**
+     * Delete a table
+     */
+    deleteTable(name: string): Promise<boolean>;
+    /**
+     * Insert a document into a collection
+     */
+    insert<T extends BaseRecord>(collection: string, data: Partial<T>): Promise<T>;
+    /**
+     * Query documents from a collection
+     */
+    query<T extends BaseRecord>(collection: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Get a single document by ID
+     */
+    get<T extends BaseRecord>(collection: string, id: string): Promise<T | null>;
+    /**
+     * Update a document
+     */
+    update<T extends BaseRecord>(collection: string, id: string, data: Partial<T>): Promise<T>;
+    /**
+     * Delete a document
+     */
+    delete(collection: string, id: string): Promise<boolean>;
+    /**
+     * Count documents in a collection
+     */
+    count(collection: string, where?: Record<string, unknown>): Promise<number>;
+    /**
+     * Set a key-value pair
+     */
+    setKV<T = unknown>(key: string, value: T): Promise<void>;
+    /**
+     * Get a value by key
+     */
+    getKV<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Delete a key-value pair
+     */
+    deleteKV(key: string): Promise<boolean>;
+    /**
+     * Subscribe to real-time changes on a collection
+     */
+    subscribe<T extends BaseRecord>(collection: string, callback: (payload: RealtimePayload<T>) => void): Subscription;
+    /**
+     * Unsubscribe from all subscriptions
+     */
+    unsubscribeAll(): void;
+    /**
+     * Get the project ID
+     */
+    getProjectId(): string;
+    /**
+     * Get the base URL
+     */
+    getBaseUrl(): string;
+}
+
+/**
+ * VlibeBaseAuth - SSO Authentication for Vlibe Base Apps
+ *
+ * Provides single sign-on authentication for users logged into Vlibe.
+ *
+ * @example
+ * ```typescript
+ * import { VlibeBaseAuth } from '@withvlibe/base-sdk';
+ *
+ * const auth = new VlibeBaseAuth({
+ *   appId: process.env.VLIBE_BASE_APP_ID!,
+ *   appSecret: process.env.VLIBE_BASE_APP_SECRET!,
+ * });
+ *
+ * // Verify a session token
+ * const user = await auth.verifySession(token);
+ *
+ * // Get login URL for unauthenticated users
+ * const loginUrl = auth.getLoginUrl('/dashboard');
+ * ```
+ */
+
+declare class VlibeBaseAuth {
+    private appId;
+    private appSecret;
+    private baseUrl;
+    /**
+     * Create a new VlibeBaseAuth instance
+     *
+     * @param config - Authentication configuration
+     * @throws Error if appId or appSecret is missing
+     */
+    constructor(config: AuthConfig);
+    /**
+     * Verify a session token and get user information
+     *
+     * @param token - The session token from the SSO callback
+     * @returns The user object if valid, null otherwise
+     */
+    verifySession(token: string): Promise<VlibeUser | null>;
+    /**
+     * Generate the SSO login URL to redirect unauthenticated users
+     *
+     * @param redirectPath - The path to redirect to after login
+     * @returns The full Vlibe SSO URL
+     */
+    getLoginUrl(redirectPath?: string): string;
+    /**
+     * Generate the logout URL
+     *
+     * @param redirectPath - The path to redirect to after logout
+     * @returns The logout URL
+     */
+    getLogoutUrl(redirectPath?: string): string;
+    /**
+     * Check if user has access to a specific feature
+     *
+     * @param user - The Vlibe user object
+     * @param feature - The feature name to check
+     * @returns True if user has access to the feature
+     */
+    hasFeature(user: VlibeUser | null, feature: string): boolean;
+    /**
+     * Check if user has an active subscription
+     *
+     * @param user - The Vlibe user object
+     * @returns True if user has any active subscription
+     */
+    hasSubscription(user: VlibeUser | null): boolean;
+    /**
+     * Get the subscription tier for a user
+     *
+     * @param user - The Vlibe user object
+     * @returns The tier name or null
+     */
+    getTier(user: VlibeUser | null): string | null;
+    /**
+     * Get the app ID
+     */
+    getAppId(): string;
+    /**
+     * Get the base URL
+     */
+    getBaseUrl(): string;
+}
+
+export { type AppCategory as A, type BasePlan as B, type ConnectStatus as C, type DatabaseConfig as D, type FeatureFlag as F, type Media as M, type Order as O, type PaymentsConfig as P, type QueryOptions as Q, type RefundOptions as R, type Subscription as S, type Transaction as T, type UsageMetric as U, VlibeBaseDatabase as V, type CheckoutOptions as a, type CheckoutSession as b, VlibeBaseAuth as c, type VlibeBaseConfig as d, type AuthConfig as e, type ColumnType as f, type TableColumn as g, type TableSchema as h, type TableInfo as i, type BaseRecord as j, type RealtimePayload as k, type VlibeUser as l, type VerifyResponse as m, type AuthSession as n, type Page as o, type Product as p, type OrderItem as q, type Address as r, type CartItem as s, type ApiResponse as t, type PaginatedResponse as u, type UseCollectionReturn as v, type UseCollectionOptions as w, type UseKVReturn as x, type UseAuthReturn as y, type UsePaymentsReturn as z };

package/dist/index.d.mts

@@ -0,0 +1,158 @@
+import { P as PaymentsConfig, C as ConnectStatus, a as CheckoutOptions, b as CheckoutSession, T as Transaction, R as RefundOptions } from './VlibeBaseAuth-ChuzgzDl.mjs';
+export { r as Address, t as ApiResponse, A as AppCategory, e as AuthConfig, n as AuthSession, B as BasePlan, j as BaseRecord, s as CartItem, f as ColumnType, D as DatabaseConfig, F as FeatureFlag, M as Media, O as Order, q as OrderItem, o as Page, u as PaginatedResponse, p as Product, Q as QueryOptions, k as RealtimePayload, S as Subscription, g as TableColumn, i as TableInfo, h as TableSchema, U as UsageMetric, y as UseAuthReturn, w as UseCollectionOptions, v as UseCollectionReturn, x as UseKVReturn, z as UsePaymentsReturn, m as VerifyResponse, c as VlibeBaseAuth, d as VlibeBaseConfig, V as VlibeBaseDatabase, l as VlibeUser } from './VlibeBaseAuth-ChuzgzDl.mjs';
+
+/**
+ * VlibeBasePayments - Payment processing for Vlibe Base Apps
+ *
+ * Provides Stripe Connect payment processing with transaction fees.
+ * Unlike Vlibe Official (50/50 revenue split), Base apps pay a small
+ * transaction fee (0.5-2% depending on plan).
+ *
+ * @example
+ * ```typescript
+ * import { VlibeBasePayments } from '@withvlibe/base-sdk';
+ *
+ * const payments = new VlibeBasePayments({
+ *   appId: process.env.VLIBE_BASE_APP_ID!,
+ *   appSecret: process.env.VLIBE_BASE_APP_SECRET!,
+ * });
+ *
+ * // Create a checkout session
+ * const session = await payments.createCheckout({
+ *   amount: 1999, // $19.99 in cents
+ *   successUrl: '/success',
+ *   cancelUrl: '/cancel',
+ * });
+ *
+ * // Redirect user to session.url
+ *
+ * // Get transaction history
+ * const transactions = await payments.getTransactions();
+ * ```
+ */
+
+declare class VlibeBasePayments {
+    private appId;
+    private appSecret;
+    private baseUrl;
+    /**
+     * Create a new VlibeBasePayments instance
+     *
+     * @param config - Payments configuration
+     * @throws Error if appId or appSecret is missing
+     *
+     * @remarks
+     * This class should only be used server-side. Never expose your
+     * appSecret to the client.
+     */
+    constructor(config: PaymentsConfig);
+    /**
+     * Make an authenticated API request
+     */
+    private apiRequest;
+    /**
+     * Get Stripe Connect onboarding URL
+     *
+     * Redirect users to this URL to connect their Stripe account.
+     *
+     * @param returnUrl - URL to return to after onboarding
+     * @returns The Stripe Connect onboarding URL
+     */
+    getConnectOnboardingUrl(returnUrl: string): Promise<string>;
+    /**
+     * Check Stripe Connect status
+     *
+     * @returns The current Stripe Connect status
+     */
+    getConnectStatus(): Promise<ConnectStatus>;
+    /**
+     * Create a checkout session for one-time payments
+     *
+     * @param options - Checkout options
+     * @returns The checkout session with URL to redirect user
+     *
+     * @remarks
+     * Transaction fees are automatically calculated based on your plan:
+     * - Free plan: 2% of transaction
+     * - Premium plan: 0.5% of transaction
+     */
+    createCheckout(options: CheckoutOptions): Promise<CheckoutSession>;
+    /**
+     * Get checkout session by ID
+     *
+     * @param sessionId - The checkout session ID
+     * @returns The checkout session details
+     */
+    getCheckoutSession(sessionId: string): Promise<CheckoutSession | null>;
+    /**
+     * Get all transactions
+     *
+     * @param options - Query options
+     * @returns List of transactions
+     */
+    getTransactions(options?: {
+        limit?: number;
+        offset?: number;
+        status?: 'pending' | 'succeeded' | 'failed' | 'refunded';
+    }): Promise<Transaction[]>;
+    /**
+     * Get a single transaction
+     *
+     * @param transactionId - The transaction ID
+     * @returns The transaction details
+     */
+    getTransaction(transactionId: string): Promise<Transaction | null>;
+    /**
+     * Get transaction summary/stats
+     *
+     * @returns Transaction statistics
+     */
+    getTransactionStats(): Promise<{
+        totalRevenue: number;
+        totalFees: number;
+        netRevenue: number;
+        transactionCount: number;
+        thisMonth: {
+            revenue: number;
+            fees: number;
+            net: number;
+            count: number;
+        };
+    }>;
+    /**
+     * Create a refund
+     *
+     * @param options - Refund options
+     * @returns The updated transaction
+     *
+     * @remarks
+     * Note: Transaction fees are not refunded when you issue a refund.
+     */
+    createRefund(options: RefundOptions): Promise<Transaction>;
+    /**
+     * Calculate the Vlibe fee for an amount
+     *
+     * @param amount - Amount in cents
+     * @param plan - The Base plan ('free' or 'premium')
+     * @returns The fee amount in cents
+     */
+    calculateFee(amount: number, plan?: 'free' | 'premium'): number;
+    /**
+     * Calculate net amount after fees
+     *
+     * @param amount - Gross amount in cents
+     * @param plan - The Base plan ('free' or 'premium')
+     * @returns The net amount in cents
+     */
+    calculateNetAmount(amount: number, plan?: 'free' | 'premium'): number;
+    /**
+     * Get the app ID
+     */
+    getAppId(): string;
+    /**
+     * Get the base URL
+     */
+    getBaseUrl(): string;
+}
+
+export { CheckoutOptions, CheckoutSession, ConnectStatus, PaymentsConfig, RefundOptions, Transaction, VlibeBasePayments };