@qidcloud/sdk 1.2.0 → 1.2.2

package/README.md

@@ -1,153 +1,142 @@
 # @qidcloud/sdk
 
-The official JavaScript/TypeScript SDK for QidCloud. Build PQC-secured, enclave-backed applications in minutes.
+The official JavaScript/TypeScript SDK for QidCloud. Build PQC-secured, enclave-backed applications with ease.
 
-## 🚀 30-Minute Quick Start
+## 🚀 Installation
 
-### 1. Install
 ```bash
 npm install @qidcloud/sdk
 ```
 
-### 2. Initialize
+## 🛠️ Initialization
+
 ```typescript
 import { QidCloud } from '@qidcloud/sdk';
 
 const qid = new QidCloud({
   apiKey: 'your_api_key',   // Found in QidCloud Console -> Settings
-  tenantId: 'your_project_id'
+  tenantId: 'your_project_id' // Optional, for project-scoped operations
 });
 ```
 
 ---
 
-## 🔑 Identity (`qid.auth`)
-
-Enforce Pure Post-Quantum Identity with zero passwords.
+## 🛡️ Identity & Auth (`qid.auth`)
 
 ### `createSession()`
-Initiates a new QR handshake session.
-- **Returns**: `Promise<QidAuthSession>` 
-  - `sessionId`: String
-  - `qrData`: String (Format: `qid:handshake:...`)
-  - `expiresAt`: Number (Timestamp)
-
-### `listen(sessionId, onAuthorized, onDenied)`
-Listens for the mobile app to approve the session.
-- **`sessionId`**: String (from `createSession`)
-- **`onAuthorized`**: `(token: string) => void` - Callback when login succeeds.
-- **`onDenied`**: `(msg: string) => void` - Callback when user rejects.
+Initializes a new PQC handshake session for QR login.
+- **Returns**: `Promise<{ sessionId: string, qrData: string, expiresAt: number }>`
+```typescript
+const { sessionId, qrData } = await qid.auth.createSession();
+```
 
 ### `getProfile(token)`
-Fetches user details.
-- **`token`**: String (The session token)
+Verifies a session token and retrieves the user profile.
 - **Returns**: `Promise<QidUser>`
+```typescript
+const user = await qid.auth.getProfile(sessionToken);
+```
 
----
+### `listen(sessionId, onAuthorized, onDenied?)`
+Listen for real-time authorization events via WebSocket.
+```typescript
+qid.auth.listen(sessionId, 
+  (token) => console.log('Authenticated:', token), 
+  (error) => console.error('Denied:', error)
+);
+```
 
-## 🗄️ Enclave DB (`qid.db`)
+---
 
-Programmatic SQL access to your project's isolated Postgres schema.
+## 🗄️ Secure Vault (`qid.vault`)
 
-### `query(sql, params, userToken?)`
-Executor for **all** SQL operations (Select, Insert, Update, Delete, and DDL).
-- **`sql`**: String (e.g., `'INSERT INTO users (name) VALUES ($1) RETURNING *'`)
-- **`params`**: Array (Parameterized values to prevent SQL injection)
-- **`userToken`**: Optional String (Required if the user's role must be checked for Mutations/Schema changes)
-- **Returns**: `Promise<QidDbResponse>`
+### `upload(file, name, metadata?, userToken?)`
+Encrypt and upload a file to the secure enclave.
+- **Returns**: `Promise<QidUploadResponse>`
+```typescript
+await qid.vault.upload(fileBlob, 'secret.pdf', { tag: 'confidential' }, userToken);
+```
 
-**Examples:**
-```javascript
-// Mutation (Write)
-await qid.db.query('INSERT INTO logs (message) VALUES ($1)', ['User logged in']);
+### `list(userToken?)`
+List all encrypted files.
+- **Returns**: `Promise<QidFile[]>`
+```typescript
+const files = await qid.vault.list(userToken);
+```
 
-// Schema (DDL)
-await qid.db.query('CREATE TABLE IF NOT EXISTS test (id SERIAL PRIMARY KEY)');
+### `download(fileId, userToken?)`
+Download a file as an ArrayBuffer.
+```typescript
+const buffer = await qid.vault.download('file_123', userToken);
 ```
 
-### `setup(userToken?)`
-Ensures the project's isolated Postgres schema is properly initialized.
-- **`userToken`**: Optional String
-- **Returns**: `Promise<{ success: boolean; schemaName: string }>`
+### `delete(fileId, userToken?)`
+Soft delete a file (move to recycle bin).
+```typescript
+await qid.vault.delete('file_123', userToken);
+```
 
 ---
 
-## ⚡ Edge Compute (`qid.edge`)
-
-Invoke serverless functions within your enclave.
+## ⚡ Edge Computing (`qid.edge`)
 
-### `invoke(name, params, userToken?)`
-- **`name`**: String (Function name)
-- **`params`**: Object (Arguments)
-- **`userToken`**: Optional String
+### `invoke(name, params?, userToken?)`
+Invoke a serverless edge function.
 - **Returns**: `Promise<QidEdgeResponse>`
+```typescript
+const result = await qid.edge.invoke('secure-calc', { input: 42 }, userToken);
+```
 
 ### `list()`
-Lists all deployed functions in the project.
+List all provisioned functions.
+```typescript
+const functions = await qid.edge.list();
+```
 
 ### `getLogs(name, userToken?)`
-Fetches the latest execution logs for a specific function.
-- **`name`**: String (Function name)
-
-### `getProjectLogs(userToken?)`
-Fetches all enclave-wide system logs. Great for debugging connectivity/auth issues.
-
-### `delete(name, userToken?)`
-Permanently destroys a function from the enclave.
-
----
-
-## 📦 Vault Storage (`qid.vault`)
-
-Secure file management.
-
-### `upload(file, fileName, metadata?, userToken?)`
-- **`file`**: Buffer | Blob
-- **`fileName`**: String
-- **`metadata`**: Object (Custom tags/E2EE keys)
-- **`userToken`**: Optional String
-
-### `list(userToken?)`
-Lists enclave files.
+Get logs for a specific function.
+```typescript
+const logs = await qid.edge.getLogs('my-function', userToken);
+```
 
-### `delete(fileId, userToken?)`
-Permanently destroys a file from storage.
+### `deploy(data, userToken?)`
+Deploy or update a function.
+```typescript
+await qid.edge.deploy({ 
+  name: 'new-func', 
+  code: '...', 
+  runtime: 'node18' 
+}, userToken);
+```
 
 ---
 
-## 📝 App Logs (`qid.logs`)
-
-Audit logs for your application logic.
+## 📊 Observability (`qid.logs`)
 
-### `write(message, source?, level?, metadata?)`
-- **`message`**: String (Log content)
-- **`source`**: String (Optional, e.g., 'frontend', 'auth-service')
-- **`level`**: String (Default: `'info'`)
-- **`metadata`**: Object (e.g., `{ userId: '123', event: 'checkout' }`)
+### `write(message, source?, level?, meta?)`
+Ingest custom telemetry into the enclave.
+```typescript
+await qid.logs.write('User action detected', 'frontend', 'info', { userId: '123' });
+```
 
 ### `fetch(query?)`
-- **`query`**: Object (e.g., `{ limit: 50, level: 'error' }`)
+Retrieve project logs.
+```typescript
+const logs = await qid.logs.fetch({ limit: 50, level: 'error' });
+```
 
 ---
 
-## 🎨 UI Components (React)
+## ⚛️ React Helpers
+
+### `useQidAuth(sdk)`
+Hook for managing authentication state.
+```tsx
+const { user, login, logout } = useQidAuth(qid);
+```
 
 ### `QidSignInButton`
-The easiest way to add QR login.
+Pre-built component for PQC login.
 ```tsx
-import { QidSignInButton } from '@qidcloud/sdk';
-
-<QidSignInButton 
-  sdk={qid}
-  onSuccess={(user, token) => console.log(user)}
-  onError={(err) => alert(err)}
-  buttonText="Authorize with QidCloud"
-/>
-```
-
-**Props:**
-- `sdk`: Instance of `QidCloud`
-- `onSuccess`: `(user, token) => void`
-- `onError`: `(error) => void`
-- `buttonText`: String (Default: "Login with QidCloud")
-- `className`: String (Custom CSS class)
+<QidSignInButton sdk={qid} onSuccess={(user) => console.log(user)} />
+```

package/dist/components/QidSignInButton.d.ts

@@ -8,5 +8,8 @@ interface QidSignInButtonProps {
     className?: string;
     buttonText?: string;
 }
+/**
+ * A ready-to-use React component for QidCloud QR identity authentication.
+ */
 export declare const QidSignInButton: React.FC<QidSignInButtonProps>;
 export {};

package/dist/hooks/useQidAuth.d.ts

@@ -0,0 +1,18 @@
+import { QidCloud } from '../index';
+import { QidUser, QidAuthSession } from '../types';
+export interface UseQidAuthReturn {
+    user: QidUser | null;
+    token: string | null;
+    loading: boolean;
+    error: string | null;
+    session: QidAuthSession | null;
+    initializing: boolean;
+    login: () => Promise<void>;
+    logout: () => void;
+    cancel: () => void;
+}
+/**
+ * A React hook for managing QidCloud authentication lifecycle.
+ * Handles handshake initialization, WebSocket listeners, and profile fetching.
+ */
+export declare function useQidAuth(sdk: QidCloud): UseQidAuthReturn;

package/dist/index.d.ts

@@ -22,3 +22,4 @@ export declare class QidCloud {
 export default QidCloud;
 export * from './types';
 export { QidSignInButton } from './components/QidSignInButton';
+export { useQidAuth } from './hooks/useQidAuth';

package/dist/index.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var axios = require('axios');
 var socket_ioClient = require('socket.io-client');
+var qrcode_react = require('qrcode.react');
 
 class AuthModule {
     sdk;
@@ -160,6 +161,37 @@ class EdgeModule {
         const resp = await this.sdk.api.delete(`/api/edge/${name}`, { headers });
         return resp.data;
     }
+    /**
+     * Deploy a new function or update an existing one
+     * @param data Deployment data including name, code, and optional envVars
+     * @param userToken Optional session token
+     */
+    async deploy(data, userToken) {
+        const headers = {};
+        if (userToken)
+            headers['Authorization'] = `Bearer ${userToken}`;
+        const resp = await this.sdk.api.post('/api/edge/deploy', data, { headers });
+        return resp.data;
+    }
+    /**
+     * Get available serverless runtimes
+     */
+    async getRuntimes() {
+        const resp = await this.sdk.api.get('/api/edge/runtimes');
+        return resp.data;
+    }
+    /**
+     * Toggle centralized logging for the project's edge functions
+     * @param enabled Whether to enable or disable logging
+     * @param userToken Optional session token
+     */
+    async toggleLogging(enabled, userToken) {
+        const headers = {};
+        if (userToken)
+            headers['Authorization'] = `Bearer ${userToken}`;
+        const resp = await this.sdk.api.post('/api/edge/logs/settings', { enabled }, { headers });
+        return resp.data;
+    }
 }
 
 class VaultModule {
@@ -216,7 +248,7 @@ class VaultModule {
         return resp.data;
     }
     /**
-     * Delete a file from storage
+     * Delete a file from storage (Soft Delete)
      * @param fileId Unique ID of the file
      * @param userToken Session token for user-scoped storage
      */
@@ -228,6 +260,44 @@ class VaultModule {
         const resp = await this.sdk.api.delete(`/api/storage/${fileId}`, { headers });
         return resp.data;
     }
+    /**
+     * List deleted files in the project enclave (Recycle Bin)
+     * @param userToken Session token for user-scoped storage
+     */
+    async listDeleted(userToken) {
+        const headers = {};
+        if (userToken) {
+            headers['Authorization'] = `Bearer ${userToken}`;
+        }
+        const resp = await this.sdk.api.get('/api/storage/deleted', { headers });
+        return resp.data;
+    }
+    /**
+     * Restore a deleted file from the recycle bin
+     * @param fileId Unique ID of the file
+     * @param userToken Session token for user-scoped storage
+     */
+    async restore(fileId, userToken) {
+        const headers = {};
+        if (userToken) {
+            headers['Authorization'] = `Bearer ${userToken}`;
+        }
+        const resp = await this.sdk.api.post(`/api/storage/restore/${fileId}`, {}, { headers });
+        return resp.data;
+    }
+    /**
+     * Permanently purge a deleted file
+     * @param fileId Unique ID of the file
+     * @param userToken Session token for user-scoped storage
+     */
+    async purge(fileId, userToken) {
+        const headers = {};
+        if (userToken) {
+            headers['Authorization'] = `Bearer ${userToken}`;
+        }
+        const resp = await this.sdk.api.delete(`/api/storage/purge/${fileId}`, { headers });
+        return resp.data;
+    }
 }
 
 class LogsModule {
@@ -2126,87 +2196,199 @@ function requireReact () {
 var reactExports = requireReact();
 var React = /*@__PURE__*/getDefaultExportFromCjs(reactExports);
 
-const QidSignInButton = ({ sdk, onSuccess, onError, className, buttonText = 'Login with QidCloud' }) => {
-    const [modalOpen, setModalOpen] = reactExports.useState(false);
-    const [qrData, setQrData] = reactExports.useState(null);
+/**
+ * A React hook for managing QidCloud authentication lifecycle.
+ * Handles handshake initialization, WebSocket listeners, and profile fetching.
+ */
+function useQidAuth(sdk) {
+    const [user, setUser] = reactExports.useState(null);
+    const [token, setToken] = reactExports.useState(null);
+    const [session, setSession] = reactExports.useState(null);
     const [loading, setLoading] = reactExports.useState(false);
-    const startLogin = async () => {
-        setLoading(true);
+    const [initializing, setInitializing] = reactExports.useState(false);
+    const [error, setError] = reactExports.useState(null);
+    // Use ref to track if we should still be listening (to avoid state updates after unmount/cancel)
+    const activeSessionId = reactExports.useRef(null);
+    const logout = reactExports.useCallback(() => {
+        setUser(null);
+        setToken(null);
+        setSession(null);
+        sdk.auth.disconnect();
+    }, [sdk]);
+    const cancel = reactExports.useCallback(() => {
+        activeSessionId.current = null;
+        setSession(null);
+        setInitializing(false);
+        sdk.auth.disconnect();
+    }, [sdk]);
+    const login = reactExports.useCallback(async () => {
+        setInitializing(true);
+        setError(null);
         try {
-            const session = await sdk.auth.createSession();
-            setQrData(session.qrData);
-            setModalOpen(true);
-            sdk.auth.listen(session.sessionId, async (token) => {
-                const user = await sdk.auth.getProfile(token);
-                setModalOpen(false);
-                onSuccess(user, token);
+            const newSession = await sdk.auth.createSession();
+            setSession(newSession);
+            activeSessionId.current = newSession.sessionId;
+            sdk.auth.listen(newSession.sessionId, async (receivedToken) => {
+                // Safety check: is this still the active session?
+                if (activeSessionId.current !== newSession.sessionId)
+                    return;
+                setLoading(true);
+                setInitializing(false);
+                try {
+                    const profile = await sdk.auth.getProfile(receivedToken);
+                    setToken(receivedToken);
+                    setUser(profile);
+                }
+                catch (err) {
+                    setError(err.message || 'Failed to fetch user profile');
+                }
+                finally {
+                    setLoading(false);
+                    setSession(null);
+                }
             }, (err) => {
-                if (onError)
-                    onError(err);
-                setModalOpen(false);
+                if (activeSessionId.current !== newSession.sessionId)
+                    return;
+                setError(err);
+                setInitializing(false);
+                setSession(null);
             });
         }
         catch (err) {
-            if (onError)
-                onError(err.message || 'Failed to initiate login');
-        }
-        finally {
-            setLoading(false);
+            setError(err.message || 'Failed to initiate login handshake');
+            setInitializing(false);
         }
+    }, [sdk]);
+    // Cleanup on unmount
+    reactExports.useEffect(() => {
+        return () => {
+            sdk.auth.disconnect();
+        };
+    }, [sdk]);
+    return {
+        user,
+        token,
+        loading,
+        error,
+        session,
+        initializing,
+        login,
+        logout,
+        cancel
     };
+}
+
+/**
+ * A ready-to-use React component for QidCloud QR identity authentication.
+ */
+const QidSignInButton = ({ sdk, onSuccess, onError, className, buttonText = 'Login with QidCloud' }) => {
+    const { user, token, error, session, initializing, login, cancel } = useQidAuth(sdk);
+    // Watch for success
+    React.useEffect(() => {
+        if (user && token) {
+            onSuccess(user, token);
+        }
+    }, [user, token, onSuccess]);
+    // Watch for errors
+    React.useEffect(() => {
+        if (error && onError) {
+            onError(error);
+        }
+    }, [error, onError]);
     return (React.createElement(React.Fragment, null,
-        React.createElement("button", { onClick: startLogin, disabled: loading, className: className || 'qid-signin-btn', style: {
+        React.createElement("button", { onClick: login, disabled: initializing || !!session, className: className || 'qid-signin-btn', style: {
                 backgroundColor: '#00e5ff',
                 color: '#000',
-                padding: '10px 20px',
-                borderRadius: '8px',
+                padding: '12px 24px',
+                borderRadius: '12px',
                 border: 'none',
-                fontWeight: 'bold',
-                cursor: 'pointer',
+                fontWeight: '900',
+                cursor: (initializing || !!session) ? 'not-allowed' : 'pointer',
                 display: 'flex',
                 alignItems: 'center',
-                gap: '10px'
-            } }, loading ? 'Initializing...' : buttonText),
-        modalOpen && (React.createElement("div", { className: "qid-modal-overlay", style: {
+                gap: '10px',
+                textTransform: 'uppercase',
+                fontSize: '0.85rem',
+                letterSpacing: '0.5px',
+                boxShadow: '0 4px 15px rgba(0, 229, 255, 0.3)',
+                transition: 'all 0.2s'
+            } },
+            React.createElement("div", { style: {
+                    width: '8px',
+                    height: '8px',
+                    borderRadius: '50%',
+                    backgroundColor: (initializing || !!session) ? '#333' : '#000',
+                    boxShadow: (initializing || !!session) ? 'none' : '0 0 8px rgba(0,0,0,0.5)'
+                } }),
+            initializing ? 'Preparing Handshake...' : (session ? 'Awaiting Scan...' : buttonText)),
+        session && (React.createElement("div", { className: "qid-modal-overlay", style: {
                 position: 'fixed',
                 top: 0, left: 0, right: 0, bottom: 0,
-                backgroundColor: 'rgba(0,0,0,0.8)',
+                backgroundColor: 'rgba(0,0,0,0.92)',
                 display: 'flex',
                 justifyContent: 'center',
                 alignItems: 'center',
-                zIndex: 9999
+                zIndex: 9999,
+                backdropFilter: 'blur(8px)'
             } },
             React.createElement("div", { className: "qid-modal-content", style: {
-                    backgroundColor: '#1a1a1a',
-                    padding: '30px',
-                    borderRadius: '16px',
+                    backgroundColor: '#0a0a0a',
+                    padding: '40px',
+                    borderRadius: '28px',
                     textAlign: 'center',
                     color: '#fff',
-                    maxWidth: '400px',
-                    width: '90%'
+                    maxWidth: '420px',
+                    width: '90%',
+                    border: '1px solid rgba(0, 229, 255, 0.2)',
+                    boxShadow: '0 25px 50px -12px rgba(0, 0, 0, 0.5)'
                 } },
-                React.createElement("h2", { style: { marginBottom: '10px' } }, "Identity Handshake"),
-                React.createElement("p", { style: { marginBottom: '20px', fontSize: '14px', color: '#ccc' } }, "Open your QidCloud Mobile App and scan this PQC-secured QR code."),
+                React.createElement("div", { style: { marginBottom: '25px' } },
+                    React.createElement("div", { style: {
+                            display: 'inline-block',
+                            padding: '12px 20px',
+                            borderRadius: '30px',
+                            backgroundColor: 'rgba(0, 229, 255, 0.1)',
+                            border: '1px solid rgba(0, 229, 255, 0.3)',
+                            marginBottom: '15px'
+                        } },
+                        React.createElement("span", { style: { color: '#00e5ff', fontSize: '0.7rem', fontWeight: '900', letterSpacing: '2px' } }, "PQC ENCLAVE SECURED")),
+                    React.createElement("h2", { style: { fontSize: '1.75rem', fontWeight: '900', marginBottom: '10px', letterSpacing: '-0.5px' } }, "Identity Handshake"),
+                    React.createElement("p", { style: { fontSize: '0.95rem', color: '#94a3b8', lineHeight: '1.6' } }, "Scan this encrypted gateway with your QidCloud app to authorize access.")),
                 React.createElement("div", { style: {
                         backgroundColor: '#fff',
-                        padding: '10px',
+                        padding: '24px',
                         display: 'inline-block',
-                        borderRadius: '8px',
-                        marginBottom: '20px'
+                        borderRadius: '24px',
+                        marginBottom: '30px',
+                        boxShadow: '0 10px 40px rgba(0,0,0,0.3)'
                     } },
-                    React.createElement("div", { style: { color: '#000', fontSize: '12px', wordBreak: 'break-all', width: '200px' } },
-                        "QR: ",
-                        qrData)),
-                React.createElement("button", { onClick: () => setModalOpen(false), style: {
-                        display: 'block',
-                        width: '100%',
-                        padding: '10px',
-                        backgroundColor: '#333',
-                        color: '#fff',
-                        border: 'none',
-                        borderRadius: '8px',
-                        cursor: 'pointer'
-                    } }, "Cancel"))))));
+                    React.createElement(qrcode_react.QRCodeSVG, { value: session.qrData, size: 220, level: "H", includeMargin: false, imageSettings: {
+                            src: "https://api.qidcloud.com/favicon.ico",
+                            x: undefined,
+                            y: undefined,
+                            height: 40,
+                            width: 40,
+                            excavate: true,
+                        } })),
+                React.createElement("div", { style: { display: 'flex', flexDirection: 'column', gap: '15px' } },
+                    React.createElement("div", { style: { height: '4px', width: '60px', backgroundColor: '#00e5ff', margin: '0 auto', borderRadius: '2px', opacity: 0.5 } }),
+                    React.createElement("button", { onClick: cancel, style: {
+                            display: 'block',
+                            width: '100%',
+                            padding: '16px',
+                            backgroundColor: 'transparent',
+                            color: '#64748b',
+                            border: '1px solid rgba(148, 163, 184, 0.2)',
+                            borderRadius: '16px',
+                            cursor: 'pointer',
+                            fontWeight: '700',
+                            transition: 'all 0.2s',
+                            fontSize: '0.9rem'
+                        } }, "Cancel Handshake")),
+                React.createElement("div", { style: { marginTop: '25px', fontSize: '0.75rem', color: '#475569' } },
+                    "Session ID: ",
+                    session.sessionId.slice(0, 8),
+                    "..."))))));
 };
 
 class QidCloud {
@@ -2246,4 +2428,5 @@ class QidCloud {
 exports.QidCloud = QidCloud;
 exports.QidSignInButton = QidSignInButton;
 exports.default = QidCloud;
+exports.useQidAuth = useQidAuth;
 //# sourceMappingURL=index.js.map