@qidcloud/sdk 1.1.1 → 1.2.1

package/README.md

@@ -1,310 +1,68 @@
 # @qidcloud/sdk
 
-Official JavaScript/TypeScript SDK for QidCloud 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 @qidcloud/sdk
 ```
 
-## Quick Start
-
+### 2. Initialize
 ```typescript
 import { QidCloud } from '@qidcloud/sdk';
 
-// Initialize with your API key
-const qgate = new QidCloud({
-  apiKey: 'your-api-key-here'
-  // baseUrl is optional, defaults to https://qgate.onrender.com
-});
-
-// 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
-
-### `new QidCloud(config)`
-
-Initialize the QidCloud client.
-
-**Parameters:**
-- `config.apiKey` (required): Your QidCloud 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)
-
-**Example:**
-```typescript
-const qgate = new QidCloud({
-  apiKey: 'qg-abc123...',
-  baseUrl: 'https://custom-backend.com' // optional
+const qid = new QidCloud({
+  apiKey: 'your_api_key',   // Found in QidCloud Console -> Settings
+  tenantId: 'your_project_id'
 });
 ```
 
 ---
 
-### `qgate.register(username, tenantId?)`
-
-Register a new user identity.
+## 🔑 Identity (`qid.auth`)
 
-**Parameters:**
-- `username` (required): Unique username
-- `tenantId` (optional): Custom tenant ID, defaults to 'default'
-
-**Returns:** `Promise<UserProfile>`
-
-**Example:**
-```typescript
-const user = await qgate.register('alice');
-console.log(user);
-// { userId: "uuid", username: "alice", role: "user" }
-```
+Enforce Pure Post-Quantum Identity with zero passwords.
 
-**Note:** This generates and stores cryptographic keys locally. **Backup the seed!**
+### `createSession()`
+Initiates a new QR handshake session.
+- **Returns**: `Promise<QidAuthSession>` 
 
 ---
 
-### `qgate.login()`
-
-Authenticate using stored identity.
-
-**Returns:** `Promise<string>` - Session token
+## 🏗️ React Integration
 
-**Example:**
-```typescript
-const token = await qgate.login();
-// Use token for API requests
-```
+The SDK provides powerful React tools for seamless integration.
 
-**Throws:**
-- `NO_IDENTITY` - User must register first
-- `MISSING_USER_ID` - Re-registration required
+### `useQidAuth(sdk)`
+The recommended way to manage auth state in React.
 
----
+```tsx
+import { useQidAuth } from '@qidcloud/sdk';
 
-### `qgate.getProfile()`
+function MyComponent({ qid }) {
+  const { user, token, session, login, initializing } = useQidAuth(qid);
 
-Get current user's profile.
+  if (user) return <p>Welcome, {user.username}</p>;
 
-**Returns:** `Promise<UserProfile>`
-
-**Example:**
-```typescript
-const profile = await qgate.getProfile();
-console.log(profile);
-// { userId: "uuid", username: "alice", role: "user", status: "active" }
-```
-
-**Requires:** Active session (must be logged in)
-
----
-
-### `qgate.logout()`
-
-End the current session.
-
-**Returns:** `Promise<void>`
-
-**Example:**
-```typescript
-await qgate.logout();
-```
-
-**Note:** Local keys are preserved for future login.
-
----
-
-### `qgate.hasIdentity()`
-
-Check if user has registered identity.
-
-**Returns:** `Promise<boolean>`
-
-**Example:**
-```typescript
-if (await qgate.hasIdentity()) {
-  await qgate.login();
-} else {
-  await qgate.register('alice');
-}
-```
-
----
-
-## Advanced Usage
-
-### Custom Storage
-
-Provide your own storage implementation:
-
-```typescript
-import { QidCloud, IStorage } from '@qidcloud/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 QidCloud({
-  apiKey: 'your-key',
-  storage: new CustomStorage()
-});
-```
-
-### Error Handling
-
-```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 { QidCloud, QidConfig, UserProfile } from '@qidcloud/sdk';
-
-const config: QidConfig = {
-  apiKey: 'your-key'
-};
-
-const qgate = new QidCloud(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)**
-
-## Examples
-
-### React Integration
-
-```typescript
-import { useState, useEffect } from 'react';
-import { QidCloud } from '@qidcloud/sdk';
-
-const qgate = new QidCloud({ 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>
+  return (
+    <button onClick={login}>
+      {initializing ? 'Connecting...' : 'Login'}
+    </button>
   );
 }
 ```
 
-### Node.js Backend
-
-```javascript
-const { QidCloud } = require('@qidcloud/sdk');
+### `QidSignInButton`
+A plug-and-play button that handles the entire handshake UI.
 
-const qgate = new QidCloud({
-  apiKey: process.env.QGATE_API_KEY
-});
+```tsx
+import { QidSignInButton } from '@qidcloud/sdk';
 
-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)}
+/>
 ```
-
-## 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 QidCloud Team**

package/dist/components/QidSignInButton.d.ts

@@ -0,0 +1,15 @@
+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;
+}
+/**
+ * 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

@@ -1,5 +1,25 @@
-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';
+export { useQidAuth } from './hooks/useQidAuth';