@qidcloud/sdk 1.1.0 → 1.2.0

package/README.md

@@ -1,310 +1,153 @@
-# @pqcloud/sdk
+# @qidcloud/sdk
 
-Official JavaScript/TypeScript SDK for Q-Gate Authentication - Quantum-resistant, passwordless authentication for modern applications.
+The official JavaScript/TypeScript SDK for QidCloud. Build PQC-secured, enclave-backed applications in minutes.
 
-## Installation
+## 🚀 30-Minute Quick Start
 
+### 1. Install
 ```bash
-npm install @pqcloud/sdk
+npm install @qidcloud/sdk
 ```
 
-## Quick Start
-
+### 2. Initialize
 ```typescript
-import { QGateClient } from '@pqcloud/sdk';
+import { QidCloud } from '@qidcloud/sdk';
 
-// Initialize with your API key
-const qgate = new QGateClient({
-  apiKey: 'your-api-key-here'
-  // baseUrl is optional, defaults to https://qgate.onrender.com
+const qid = new QidCloud({
+  apiKey: 'your_api_key',   // Found in QidCloud Console -> Settings
+  tenantId: 'your_project_id'
 });
-
-// Register a new user
-const user = await qgate.register('alice');
-
-// Login
-const token = await qgate.login();
-
-// Get user profile
-const profile = await qgate.getProfile();
-
-// Logout
-await qgate.logout();
 ```
 
-## Features
-
-✅ **Quantum-Resistant** - Uses CRYSTALS-Dilithium and Kyber  
-✅ **Passwordless** - No passwords to remember or manage  
-✅ **Zero-Knowledge** - Keys never leave the device  
-✅ **TypeScript Support** - Full type definitions included  
-✅ **Browser & Node.js** - Works everywhere
+---
 
-## API Reference
+## 🔑 Identity (`qid.auth`)
 
-### `new QGateClient(config)`
+Enforce Pure Post-Quantum Identity with zero passwords.
 
-Initialize the Q-Gate client.
+### `createSession()`
+Initiates a new QR handshake session.
+- **Returns**: `Promise<QidAuthSession>` 
+  - `sessionId`: String
+  - `qrData`: String (Format: `qid:handshake:...`)
+  - `expiresAt`: Number (Timestamp)
 
-**Parameters:**
-- `config.apiKey` (required): Your Q-Gate API key
-- `config.baseUrl` (optional): Custom backend URL, defaults to `https://qgate.onrender.com`
-- `config.storage` (optional): Custom storage implementation (defaults to localStorage in browser, memory in Node.js)
+### `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.
 
-**Example:**
-```typescript
-const qgate = new QGateClient({
-  apiKey: 'qg-abc123...',
-  baseUrl: 'https://custom-backend.com' // optional
-});
-```
+### `getProfile(token)`
+Fetches user details.
+- **`token`**: String (The session token)
+- **Returns**: `Promise<QidUser>`
 
 ---
 
-### `qgate.register(username, tenantId?)`
+## 🗄️ Enclave DB (`qid.db`)
 
-Register a new user identity.
+Programmatic SQL access to your project's isolated Postgres schema.
 
-**Parameters:**
-- `username` (required): Unique username
-- `tenantId` (optional): Custom tenant ID, defaults to 'default'
+### `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>`
 
-**Returns:** `Promise<UserProfile>`
+**Examples:**
+```javascript
+// Mutation (Write)
+await qid.db.query('INSERT INTO logs (message) VALUES ($1)', ['User logged in']);
 
-**Example:**
-```typescript
-const user = await qgate.register('alice');
-console.log(user);
-// { userId: "uuid", username: "alice", role: "user" }
+// Schema (DDL)
+await qid.db.query('CREATE TABLE IF NOT EXISTS test (id SERIAL PRIMARY KEY)');
 ```
 
-**Note:** This generates and stores cryptographic keys locally. **Backup the seed!**
+### `setup(userToken?)`
+Ensures the project's isolated Postgres schema is properly initialized.
+- **`userToken`**: Optional String
+- **Returns**: `Promise<{ success: boolean; schemaName: string }>`
 
 ---
 
-### `qgate.login()`
-
-Authenticate using stored identity.
-
-**Returns:** `Promise<string>` - Session token
-
-**Example:**
-```typescript
-const token = await qgate.login();
-// Use token for API requests
-```
-
-**Throws:**
-- `NO_IDENTITY` - User must register first
-- `MISSING_USER_ID` - Re-registration required
+## ⚡ Edge Compute (`qid.edge`)
 
----
+Invoke serverless functions within your enclave.
 
-### `qgate.getProfile()`
+### `invoke(name, params, userToken?)`
+- **`name`**: String (Function name)
+- **`params`**: Object (Arguments)
+- **`userToken`**: Optional String
+- **Returns**: `Promise<QidEdgeResponse>`
 
-Get current user's profile.
+### `list()`
+Lists all deployed functions in the project.
 
-**Returns:** `Promise<UserProfile>`
+### `getLogs(name, userToken?)`
+Fetches the latest execution logs for a specific function.
+- **`name`**: String (Function name)
 
-**Example:**
-```typescript
-const profile = await qgate.getProfile();
-console.log(profile);
-// { userId: "uuid", username: "alice", role: "user", status: "active" }
-```
+### `getProjectLogs(userToken?)`
+Fetches all enclave-wide system logs. Great for debugging connectivity/auth issues.
 
-**Requires:** Active session (must be logged in)
+### `delete(name, userToken?)`
+Permanently destroys a function from the enclave.
 
 ---
 
-### `qgate.logout()`
+## 📦 Vault Storage (`qid.vault`)
 
-End the current session.
+Secure file management.
 
-**Returns:** `Promise<void>`
+### `upload(file, fileName, metadata?, userToken?)`
+- **`file`**: Buffer | Blob
+- **`fileName`**: String
+- **`metadata`**: Object (Custom tags/E2EE keys)
+- **`userToken`**: Optional String
 
-**Example:**
-```typescript
-await qgate.logout();
-```
+### `list(userToken?)`
+Lists enclave files.
 
-**Note:** Local keys are preserved for future login.
+### `delete(fileId, userToken?)`
+Permanently destroys a file from storage.
 
 ---
 
-### `qgate.hasIdentity()`
+## 📝 App Logs (`qid.logs`)
 
-Check if user has registered identity.
+Audit logs for your application logic.
 
-**Returns:** `Promise<boolean>`
+### `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' }`)
 
-**Example:**
-```typescript
-if (await qgate.hasIdentity()) {
-  await qgate.login();
-} else {
-  await qgate.register('alice');
-}
-```
+### `fetch(query?)`
+- **`query`**: Object (e.g., `{ limit: 50, level: 'error' }`)
 
 ---
 
-## Advanced Usage
-
-### Custom Storage
-
-Provide your own storage implementation:
-
-```typescript
-import { QGateClient, IStorage } from '@pqcloud/sdk';
-
-class CustomStorage implements IStorage {
-  async getItem(key: string): Promise<string | null> {
-    // Your implementation
-  }
-  
-  async setItem(key: string, value: string): Promise<void> {
-    // Your implementation
-  }
-  
-  async removeItem(key: string): Promise<void> {
-    // Your implementation
-  }
-}
-
-const qgate = new QGateClient({
-  apiKey: 'your-key',
-  storage: new CustomStorage()
-});
-```
-
-### Error Handling
+## 🎨 UI Components (React)
 
-```typescript
-try {
-  await qgate.login();
-} catch (error) {
-  if (error.message === 'NO_IDENTITY') {
-    console.log('User not registered');
-  } else if (error.response?.status === 401) {
-    console.log('Authentication failed');
-  }
-}
-```
-
-### Session Management
-
-```typescript
-// Check if user is logged in
-const hasIdentity = await qgate.hasIdentity();
-
-// Auto-login on app start
-if (hasIdentity) {
-  try {
-    await qgate.login();
-  } catch {
-    // Handle expired/invalid session
-  }
-}
-```
-
-## TypeScript
-
-Full TypeScript support included:
-
-```typescript
-import { QGateClient, QGateConfig, UserProfile } from '@pqcloud/sdk';
-
-const config: QGateConfig = {
-  apiKey: 'your-key'
-};
-
-const qgate = new QGateClient(config);
-
-const profile: UserProfile = await qgate.getProfile();
-```
-
-## Security Notes
-
-🔒 **Private keys never leave the device**  
-🔒 **All communication is encrypted**  
-🔒 **Quantum-resistant cryptography**  
-🔒 **Store API keys securely (environment variables)**
+### `QidSignInButton`
+The easiest way to add QR login.
+```tsx
+import { QidSignInButton } from '@qidcloud/sdk';
 
-## Examples
-
-### React Integration
-
-```typescript
-import { useState, useEffect } from 'react';
-import { QGateClient } from '@pqcloud/sdk';
-
-const qgate = new QGateClient({ apiKey: process.env.REACT_APP_QGATE_KEY });
-
-function App() {
-  const [user, setUser] = useState(null);
-  
-  useEffect(() => {
-    async function init() {
-      if (await qgate.hasIdentity()) {
-        await qgate.login();
-        const profile = await qgate.getProfile();
-        setUser(profile);
-      }
-    }
-    init();
-  }, []);
-  
-  const register = async (username) => {
-    const user = await qgate.register(username);
-    setUser(user);
-  };
-  
-  const logout = async () => {
-    await qgate.logout();
-    setUser(null);
-  };
-  
-  return user ? (
-    <div>
-      <h1>Welcome, {user.username}!</h1>
-      <button onClick={logout}>Logout</button>
-    </div>
-  ) : (
-    <button onClick={() => register('alice')}>Register</button>
-  );
-}
-```
-
-### Node.js Backend
-
-```javascript
-const { QGateClient } = require('@pqcloud/sdk');
-
-const qgate = new QGateClient({
-  apiKey: process.env.QGATE_API_KEY
-});
-
-async function authenticateUser(username) {
-  if (!await qgate.hasIdentity()) {
-    await qgate.register(username);
-  }
-  
-  const token = await qgate.login();
-  return token;
-}
+<QidSignInButton 
+  sdk={qid}
+  onSuccess={(user, token) => console.log(user)}
+  onError={(err) => alert(err)}
+  buttonText="Authorize with QidCloud"
+/>
 ```
 
-## Support
-
-**Documentation:** [Provider Guide](../PROVIDER_API_GUIDE.md)  
-**Issues:** [GitHub Issues](https://github.com/qgate/sdk/issues)  
-**Email:** support@qgate.io
-
-## License
-
-ISC
-
----
-
-**Built with ❤️ by the Q-Gate Team**
+**Props:**
+- `sdk`: Instance of `QidCloud`
+- `onSuccess`: `(user, token) => void`
+- `onError`: `(error) => void`
+- `buttonText`: String (Default: "Login with QidCloud")
+- `className`: String (Custom CSS class)

package/dist/components/QidSignInButton.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { QidCloud } from '../index';
+import { QidUser } from '../types';
+interface QidSignInButtonProps {
+    sdk: QidCloud;
+    onSuccess: (user: QidUser, token: string) => void;
+    onError?: (error: string) => void;
+    className?: string;
+    buttonText?: string;
+}
+export declare const QidSignInButton: React.FC<QidSignInButtonProps>;
+export {};

package/dist/index.d.ts

@@ -1,5 +1,24 @@
-import { QidCloud, QidConfig, UserProfile } from './QidCloud';
-import UnifiedStorage from './storage';
-import * as PQC from './crypto/pqc';
-export { QidCloud, QidCloud as PQAuth, QidConfig, UserProfile, UnifiedStorage, PQC };
+import { AxiosInstance } from 'axios';
+import { QidConfig } from './types';
+import { AuthModule } from './modules/auth';
+import { DbModule } from './modules/db';
+import { EdgeModule } from './modules/edge';
+import { VaultModule } from './modules/vault';
+import { LogsModule } from './modules/logs';
+export declare class QidCloud {
+    private config;
+    api: AxiosInstance;
+    auth: AuthModule;
+    db: DbModule;
+    edge: EdgeModule;
+    vault: VaultModule;
+    logs: LogsModule;
+    constructor(config: QidConfig);
+    /**
+     * Get the current project configuration
+     */
+    getConfig(): QidConfig;
+}
 export default QidCloud;
+export * from './types';
+export { QidSignInButton } from './components/QidSignInButton';