krisspy-sdk 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -6,8 +6,12 @@ interface KrisspyClientOptions {
     url?: string;
     /** Backend ID for this client */
     backendId: string;
-    /** API key or access token */
-    apiKey?: string;
+    /**
+     * Public API key for the backend (required)
+     * This key can be safely exposed in frontend code.
+     * Get it from your backend settings in the Krisspy dashboard.
+     */
+    anonKey: string;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Enable debug logging */
@@ -346,6 +350,31 @@ interface StorageUrlResponse {
 /**
  * Storage bucket interface for file operations
  */
+interface UploadAndLinkOptions {
+    /** Table to insert/update the record */
+    table: string;
+    /** Column name to store the URL (default: 'url') */
+    column?: string;
+    /** Additional data to insert with the record */
+    data?: Record<string, any>;
+    /** If provided, update existing record instead of insert */
+    recordId?: string;
+    /** Content type of the file */
+    contentType?: string;
+}
+interface UploadAndLinkResponse {
+    data: {
+        file: {
+            path: string;
+            url: string;
+            bucket: string;
+            contentType: string;
+            size: number;
+        };
+        record: Record<string, any>;
+    } | null;
+    error: KrisspyError | null;
+}
 declare class StorageBucket {
     private http;
     private backendId;
@@ -438,6 +467,34 @@ declare class StorageBucket {
      *   .createSignedUrl('document.pdf', 3600)
      */
     createSignedUrl(path: string, expiresIn?: number): Promise<StorageUrlResponse>;
+    /**
+     * Upload a file and link it to a database record in one operation
+     *
+     * @param path - Path/filename for the file
+     * @param file - File data
+     * @param options - Link options (table, column, additional data)
+     *
+     * @example
+     * // Upload image and create new item record
+     * const { data, error } = await krisspy.storage
+     *   .from('media')
+     *   .uploadAndLink('products/phone.jpg', file, {
+     *     table: 'items',
+     *     column: 'image_url',
+     *     data: { name: 'iPhone', price: 999 }
+     *   })
+     *
+     * @example
+     * // Upload avatar and update existing user
+     * const { data, error } = await krisspy.storage
+     *   .from('avatars')
+     *   .uploadAndLink('user123.jpg', file, {
+     *     table: 'users',
+     *     column: 'avatar_url',
+     *     recordId: 'user123'
+     *   })
+     */
+    uploadAndLink(path: string, file: Blob | File | ArrayBuffer | string, options: UploadAndLinkOptions): Promise<UploadAndLinkResponse>;
     private blobToBase64;
     private arrayBufferToBase64;
     private detectMimeType;
@@ -489,6 +546,159 @@ declare class KrisspyStorage {
     }>;
 }
 
+/**
+ * Krisspy Realtime - WebSocket subscriptions for real-time data changes
+ *
+ * Similar to Supabase Realtime, allows subscribing to database changes.
+ *
+ * @example
+ * // Subscribe to all changes on a table
+ * const channel = krisspy.channel('messages-changes')
+ *   .on('postgres_changes', { event: '*', table: 'messages' }, (payload) => {
+ *     console.log('Change:', payload)
+ *   })
+ *   .subscribe()
+ *
+ * // Subscribe to INSERT only
+ * const channel = krisspy.channel('new-messages')
+ *   .on('postgres_changes', { event: 'INSERT', table: 'messages' }, (payload) => {
+ *     console.log('New message:', payload.new)
+ *   })
+ *   .subscribe()
+ *
+ * // Unsubscribe
+ * channel.unsubscribe()
+ */
+type RealtimeEvent = 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+interface PostgresChangesConfig {
+    event: RealtimeEvent;
+    schema?: string;
+    table: string;
+    filter?: string;
+}
+interface RealtimePayload<T = any> {
+    eventType: 'INSERT' | 'UPDATE' | 'DELETE';
+    new: T | null;
+    old: T | null;
+    table: string;
+    schema: string;
+    commitTimestamp: string;
+}
+type RealtimeCallback<T = any> = (payload: RealtimePayload<T>) => void;
+type ChannelState = 'closed' | 'connecting' | 'connected' | 'error';
+/**
+ * Realtime Channel - represents a subscription to database changes
+ */
+declare class RealtimeChannel {
+    private name;
+    private realtime;
+    private subscriptions;
+    private _state;
+    constructor(name: string, realtime: KrisspyRealtime);
+    /**
+     * Get channel state
+     */
+    get state(): ChannelState;
+    /**
+     * Subscribe to postgres changes
+     *
+     * @example
+     * channel.on('postgres_changes', { event: 'INSERT', table: 'messages' }, (payload) => {
+     *   console.log('New message:', payload.new)
+     * })
+     */
+    on<T = any>(type: 'postgres_changes', config: PostgresChangesConfig, callback: RealtimeCallback<T>): RealtimeChannel;
+    /**
+     * Activate the channel and start receiving events
+     */
+    subscribe(callback?: (status: ChannelState, error?: Error) => void): RealtimeChannel;
+    /**
+     * Unsubscribe from the channel
+     */
+    unsubscribe(): Promise<void>;
+    /**
+     * Handle incoming message (called by KrisspyRealtime)
+     */
+    handleMessage(payload: RealtimePayload): void;
+}
+/**
+ * Krisspy Realtime - manages WebSocket connection and channels
+ */
+declare class KrisspyRealtime {
+    private url;
+    private backendId;
+    private ws;
+    private channels;
+    private token;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private pingInterval;
+    private connectionPromise;
+    private debug;
+    constructor(baseUrl: string, backendId: string, debug?: boolean);
+    /**
+     * Set auth token for authenticated subscriptions
+     */
+    setAuth(token: string | null): void;
+    /**
+     * Create a new channel
+     */
+    channel(name: string): RealtimeChannel;
+    /**
+     * Connect to WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Send subscribe message
+     */
+    sendSubscribe(channel: string, config: PostgresChangesConfig): void;
+    /**
+     * Send unsubscribe message
+     */
+    sendUnsubscribe(channel: string): void;
+    /**
+     * Register a channel for receiving messages
+     */
+    registerChannel(name: string, channel: RealtimeChannel): void;
+    /**
+     * Unregister a channel
+     */
+    unregisterChannel(name: string): void;
+    /**
+     * Remove all subscriptions
+     */
+    removeAllChannels(): void;
+    /**
+     * Handle incoming WebSocket message
+     */
+    private handleMessage;
+    /**
+     * Send message to WebSocket server
+     */
+    private send;
+    /**
+     * Start ping interval to keep connection alive
+     */
+    private startPing;
+    /**
+     * Stop ping interval
+     */
+    private stopPing;
+    /**
+     * Attempt to reconnect
+     */
+    private reconnect;
+    /**
+     * Log debug message
+     */
+    private log;
+}
+
 /**
  * Query Builder - Supabase-style fluent API for database queries
  */
@@ -636,9 +846,12 @@ declare class QueryBuilder<T = any> {
 declare class KrisspyClient {
     private http;
     private backendId;
+    private baseUrl;
     private _auth;
     private _storage;
+    private _realtime;
     private useRLS;
+    private debug;
     constructor(options: KrisspyClientOptions);
     /**
      * Auth module for user authentication
@@ -685,6 +898,49 @@ declare class KrisspyClient {
      * const { error } = await krisspy.storage.from('uploads').remove(['old.jpg'])
      */
     get storage(): KrisspyStorage;
+    /**
+     * Create a realtime channel for subscribing to database changes
+     *
+     * @example
+     * // Subscribe to all changes on a table
+     * const channel = krisspy.channel('messages-changes')
+     *   .on('postgres_changes', { event: '*', table: 'messages' }, (payload) => {
+     *     console.log('Change:', payload)
+     *   })
+     *   .subscribe()
+     *
+     * // Subscribe to INSERT only
+     * const channel = krisspy.channel('new-messages')
+     *   .on('postgres_changes', { event: 'INSERT', table: 'messages' }, (payload) => {
+     *     console.log('New message:', payload.new)
+     *   })
+     *   .subscribe()
+     *
+     * // Subscribe with status callback
+     * const channel = krisspy.channel('my-channel')
+     *   .on('postgres_changes', { event: '*', table: 'items' }, (payload) => {
+     *     console.log('Item changed:', payload)
+     *   })
+     *   .subscribe((status, error) => {
+     *     if (status === 'connected') {
+     *       console.log('Connected to realtime!')
+     *     } else if (status === 'error') {
+     *       console.error('Connection error:', error)
+     *     }
+     *   })
+     *
+     * // Unsubscribe
+     * await channel.unsubscribe()
+     */
+    channel(name: string): RealtimeChannel;
+    /**
+     * Remove all realtime subscriptions
+     */
+    removeAllChannels(): void;
+    /**
+     * Get the realtime instance for advanced usage
+     */
+    get realtime(): KrisspyRealtime;
     /**
      * Create a query builder for a table
      *
@@ -769,7 +1025,7 @@ declare class KrisspyClient {
 /**
  * @krisspy/sdk - Krisspy Cloud SDK
  *
- * Database, Auth, Storage, and Functions for your apps.
+ * Database, Auth, Storage, Functions, and Realtime for your apps.
  * A simpler alternative to Supabase.
  *
  * @example
@@ -777,7 +1033,7 @@ declare class KrisspyClient {
  *
  * const krisspy = createClient({
  *   backendId: 'your-backend-id',
- *   apiKey: 'your-api-key', // optional
+ *   anonKey: 'your-anon-key', // from backend settings
  * })
  *
  * // Auth
@@ -801,6 +1057,13 @@ declare class KrisspyClient {
  *
  * // Functions
  * await krisspy.functions.invoke('hello', { body: { name: 'World' } })
+ *
+ * // Realtime
+ * const channel = krisspy.channel('messages')
+ *   .on('postgres_changes', { event: '*', table: 'messages' }, (payload) => {
+ *     console.log('Change:', payload)
+ *   })
+ *   .subscribe()
  */
 
 /**
@@ -812,10 +1075,10 @@ declare class KrisspyClient {
  * @example
  * const krisspy = createClient({
  *   backendId: 'abc123',
- *   apiKey: 'your-api-key',
+ *   anonKey: 'your-anon-key',
  *   url: 'https://api.krisspy.ai', // optional
  * })
  */
 declare function createClient(options: KrisspyClientOptions): KrisspyClient;
 
-export { type AuthChangeEvent, type AuthResponse, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, KrisspyAuth, KrisspyClient, type KrisspyClientOptions, type KrisspyError, KrisspyStorage, type MutationResponse, type OAuthProvider, type OrderBy, QueryBuilder, type QueryOptions, type QueryResponse, type Session, type SignInCredentials, type SignUpCredentials, type SingleResponse, StorageBucket, type User, createClient };
+export { type AuthChangeEvent, type AuthResponse, type ChannelState, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, KrisspyAuth, KrisspyClient, type KrisspyClientOptions, type KrisspyError, KrisspyRealtime, KrisspyStorage, type MutationResponse, type OAuthProvider, type OrderBy, type PostgresChangesConfig, QueryBuilder, type QueryOptions, type QueryResponse, RealtimeChannel, type RealtimeEvent, type RealtimePayload, type Session, type SignInCredentials, type SignUpCredentials, type SingleResponse, StorageBucket, type UploadAndLinkOptions, type UploadAndLinkResponse, type User, createClient };

package/dist/index.d.ts

@@ -6,8 +6,12 @@ interface KrisspyClientOptions {
     url?: string;
     /** Backend ID for this client */
     backendId: string;
-    /** API key or access token */
-    apiKey?: string;
+    /**
+     * Public API key for the backend (required)
+     * This key can be safely exposed in frontend code.
+     * Get it from your backend settings in the Krisspy dashboard.
+     */
+    anonKey: string;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Enable debug logging */
@@ -346,6 +350,31 @@ interface StorageUrlResponse {
 /**
  * Storage bucket interface for file operations
  */
+interface UploadAndLinkOptions {
+    /** Table to insert/update the record */
+    table: string;
+    /** Column name to store the URL (default: 'url') */
+    column?: string;
+    /** Additional data to insert with the record */
+    data?: Record<string, any>;
+    /** If provided, update existing record instead of insert */
+    recordId?: string;
+    /** Content type of the file */
+    contentType?: string;
+}
+interface UploadAndLinkResponse {
+    data: {
+        file: {
+            path: string;
+            url: string;
+            bucket: string;
+            contentType: string;
+            size: number;
+        };
+        record: Record<string, any>;
+    } | null;
+    error: KrisspyError | null;
+}
 declare class StorageBucket {
     private http;
     private backendId;
@@ -438,6 +467,34 @@ declare class StorageBucket {
      *   .createSignedUrl('document.pdf', 3600)
      */
     createSignedUrl(path: string, expiresIn?: number): Promise<StorageUrlResponse>;
+    /**
+     * Upload a file and link it to a database record in one operation
+     *
+     * @param path - Path/filename for the file
+     * @param file - File data
+     * @param options - Link options (table, column, additional data)
+     *
+     * @example
+     * // Upload image and create new item record
+     * const { data, error } = await krisspy.storage
+     *   .from('media')
+     *   .uploadAndLink('products/phone.jpg', file, {
+     *     table: 'items',
+     *     column: 'image_url',
+     *     data: { name: 'iPhone', price: 999 }
+     *   })
+     *
+     * @example
+     * // Upload avatar and update existing user
+     * const { data, error } = await krisspy.storage
+     *   .from('avatars')
+     *   .uploadAndLink('user123.jpg', file, {
+     *     table: 'users',
+     *     column: 'avatar_url',
+     *     recordId: 'user123'
+     *   })
+     */
+    uploadAndLink(path: string, file: Blob | File | ArrayBuffer | string, options: UploadAndLinkOptions): Promise<UploadAndLinkResponse>;
     private blobToBase64;
     private arrayBufferToBase64;
     private detectMimeType;
@@ -489,6 +546,159 @@ declare class KrisspyStorage {
     }>;
 }
 
+/**
+ * Krisspy Realtime - WebSocket subscriptions for real-time data changes
+ *
+ * Similar to Supabase Realtime, allows subscribing to database changes.
+ *
+ * @example
+ * // Subscribe to all changes on a table
+ * const channel = krisspy.channel('messages-changes')
+ *   .on('postgres_changes', { event: '*', table: 'messages' }, (payload) => {
+ *     console.log('Change:', payload)
+ *   })
+ *   .subscribe()
+ *
+ * // Subscribe to INSERT only
+ * const channel = krisspy.channel('new-messages')
+ *   .on('postgres_changes', { event: 'INSERT', table: 'messages' }, (payload) => {
+ *     console.log('New message:', payload.new)
+ *   })
+ *   .subscribe()
+ *
+ * // Unsubscribe
+ * channel.unsubscribe()
+ */
+type RealtimeEvent = 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+interface PostgresChangesConfig {
+    event: RealtimeEvent;
+    schema?: string;
+    table: string;
+    filter?: string;
+}
+interface RealtimePayload<T = any> {
+    eventType: 'INSERT' | 'UPDATE' | 'DELETE';
+    new: T | null;
+    old: T | null;
+    table: string;
+    schema: string;
+    commitTimestamp: string;
+}
+type RealtimeCallback<T = any> = (payload: RealtimePayload<T>) => void;
+type ChannelState = 'closed' | 'connecting' | 'connected' | 'error';
+/**
+ * Realtime Channel - represents a subscription to database changes
+ */
+declare class RealtimeChannel {
+    private name;
+    private realtime;
+    private subscriptions;
+    private _state;
+    constructor(name: string, realtime: KrisspyRealtime);
+    /**
+     * Get channel state
+     */
+    get state(): ChannelState;
+    /**
+     * Subscribe to postgres changes
+     *
+     * @example
+     * channel.on('postgres_changes', { event: 'INSERT', table: 'messages' }, (payload) => {
+     *   console.log('New message:', payload.new)
+     * })
+     */
+    on<T = any>(type: 'postgres_changes', config: PostgresChangesConfig, callback: RealtimeCallback<T>): RealtimeChannel;
+    /**
+     * Activate the channel and start receiving events
+     */
+    subscribe(callback?: (status: ChannelState, error?: Error) => void): RealtimeChannel;
+    /**
+     * Unsubscribe from the channel
+     */
+    unsubscribe(): Promise<void>;
+    /**
+     * Handle incoming message (called by KrisspyRealtime)
+     */
+    handleMessage(payload: RealtimePayload): void;
+}
+/**
+ * Krisspy Realtime - manages WebSocket connection and channels
+ */
+declare class KrisspyRealtime {
+    private url;
+    private backendId;
+    private ws;
+    private channels;
+    private token;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private pingInterval;
+    private connectionPromise;
+    private debug;
+    constructor(baseUrl: string, backendId: string, debug?: boolean);
+    /**
+     * Set auth token for authenticated subscriptions
+     */
+    setAuth(token: string | null): void;
+    /**
+     * Create a new channel
+     */
+    channel(name: string): RealtimeChannel;
+    /**
+     * Connect to WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Send subscribe message
+     */
+    sendSubscribe(channel: string, config: PostgresChangesConfig): void;
+    /**
+     * Send unsubscribe message
+     */
+    sendUnsubscribe(channel: string): void;
+    /**
+     * Register a channel for receiving messages
+     */
+    registerChannel(name: string, channel: RealtimeChannel): void;
+    /**
+     * Unregister a channel
+     */
+    unregisterChannel(name: string): void;
+    /**
+     * Remove all subscriptions
+     */
+    removeAllChannels(): void;
+    /**
+     * Handle incoming WebSocket message
+     */
+    private handleMessage;
+    /**
+     * Send message to WebSocket server
+     */
+    private send;
+    /**
+     * Start ping interval to keep connection alive
+     */
+    private startPing;
+    /**
+     * Stop ping interval
+     */
+    private stopPing;
+    /**
+     * Attempt to reconnect
+     */
+    private reconnect;
+    /**
+     * Log debug message
+     */
+    private log;
+}
+
 /**
  * Query Builder - Supabase-style fluent API for database queries
  */
@@ -636,9 +846,12 @@ declare class QueryBuilder<T = any> {
 declare class KrisspyClient {
     private http;
     private backendId;
+    private baseUrl;
     private _auth;
     private _storage;
+    private _realtime;
     private useRLS;
+    private debug;
     constructor(options: KrisspyClientOptions);
     /**
      * Auth module for user authentication
@@ -685,6 +898,49 @@ declare class KrisspyClient {
      * const { error } = await krisspy.storage.from('uploads').remove(['old.jpg'])
      */
     get storage(): KrisspyStorage;
+    /**
+     * Create a realtime channel for subscribing to database changes
+     *
+     * @example
+     * // Subscribe to all changes on a table
+     * const channel = krisspy.channel('messages-changes')
+     *   .on('postgres_changes', { event: '*', table: 'messages' }, (payload) => {
+     *     console.log('Change:', payload)
+     *   })
+     *   .subscribe()
+     *
+     * // Subscribe to INSERT only
+     * const channel = krisspy.channel('new-messages')
+     *   .on('postgres_changes', { event: 'INSERT', table: 'messages' }, (payload) => {
+     *     console.log('New message:', payload.new)
+     *   })
+     *   .subscribe()
+     *
+     * // Subscribe with status callback
+     * const channel = krisspy.channel('my-channel')
+     *   .on('postgres_changes', { event: '*', table: 'items' }, (payload) => {
+     *     console.log('Item changed:', payload)
+     *   })
+     *   .subscribe((status, error) => {
+     *     if (status === 'connected') {
+     *       console.log('Connected to realtime!')
+     *     } else if (status === 'error') {
+     *       console.error('Connection error:', error)
+     *     }
+     *   })
+     *
+     * // Unsubscribe
+     * await channel.unsubscribe()
+     */
+    channel(name: string): RealtimeChannel;
+    /**
+     * Remove all realtime subscriptions
+     */
+    removeAllChannels(): void;
+    /**
+     * Get the realtime instance for advanced usage
+     */
+    get realtime(): KrisspyRealtime;
     /**
      * Create a query builder for a table
      *
@@ -769,7 +1025,7 @@ declare class KrisspyClient {
 /**
  * @krisspy/sdk - Krisspy Cloud SDK
  *
- * Database, Auth, Storage, and Functions for your apps.
+ * Database, Auth, Storage, Functions, and Realtime for your apps.
  * A simpler alternative to Supabase.
  *
  * @example
@@ -777,7 +1033,7 @@ declare class KrisspyClient {
  *
  * const krisspy = createClient({
  *   backendId: 'your-backend-id',
- *   apiKey: 'your-api-key', // optional
+ *   anonKey: 'your-anon-key', // from backend settings
  * })
  *
  * // Auth
@@ -801,6 +1057,13 @@ declare class KrisspyClient {
  *
  * // Functions
  * await krisspy.functions.invoke('hello', { body: { name: 'World' } })
+ *
+ * // Realtime
+ * const channel = krisspy.channel('messages')
+ *   .on('postgres_changes', { event: '*', table: 'messages' }, (payload) => {
+ *     console.log('Change:', payload)
+ *   })
+ *   .subscribe()
  */
 
 /**
@@ -812,10 +1075,10 @@ declare class KrisspyClient {
  * @example
  * const krisspy = createClient({
  *   backendId: 'abc123',
- *   apiKey: 'your-api-key',
+ *   anonKey: 'your-anon-key',
  *   url: 'https://api.krisspy.ai', // optional
  * })
  */
 declare function createClient(options: KrisspyClientOptions): KrisspyClient;
 
-export { type AuthChangeEvent, type AuthResponse, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, KrisspyAuth, KrisspyClient, type KrisspyClientOptions, type KrisspyError, KrisspyStorage, type MutationResponse, type OAuthProvider, type OrderBy, QueryBuilder, type QueryOptions, type QueryResponse, type Session, type SignInCredentials, type SignUpCredentials, type SingleResponse, StorageBucket, type User, createClient };
+export { type AuthChangeEvent, type AuthResponse, type ChannelState, type FileObject, type FileUploadOptions, type Filter, type FilterOperator, type FunctionInvokeOptions, type FunctionResponse, HttpClient, KrisspyAuth, KrisspyClient, type KrisspyClientOptions, type KrisspyError, KrisspyRealtime, KrisspyStorage, type MutationResponse, type OAuthProvider, type OrderBy, type PostgresChangesConfig, QueryBuilder, type QueryOptions, type QueryResponse, RealtimeChannel, type RealtimeEvent, type RealtimePayload, type Session, type SignInCredentials, type SignUpCredentials, type SingleResponse, StorageBucket, type UploadAndLinkOptions, type UploadAndLinkResponse, type User, createClient };