zone4code-sdk 1.0.2 → 1.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 Official TypeScript & JavaScript Client SDK for the **Zone4Code Platform** & **Singulary**.
 
-Provides a type-safe, chainable interface (similar to Supabase / Prisma) for **Keycloak Authentication**, **Adaptive Object-Model (AOM) Dynamic Schemas**, and **JSONB Querying** over the Unified API Gateway.
+Provides a type-safe, chainable interface (similar to Supabase / Prisma) for **Keycloak Authentication**, **Adaptive Object-Model (AOM) Dynamic Schemas**, **JSONB Querying**, **Audit Revisions**, **Graph Relations**, and **Workflow Plugins** over the Unified API Gateway.
 
 ---
 
@@ -22,11 +22,12 @@ pnpm add zone4code-sdk
 import { createClient } from 'zone4code-sdk';
 
 const client = createClient({
-  gatewayUrl: 'http://localhost:8080', // Or your remote server: https://api.yourdomain.com
-  tenantId: 'my-workspace-id'
+  gatewayUrl: 'http://localhost:8080', // Or your production server: https://api.yourdomain.com
+  tenantId: 'my-workspace-id',
+  // storageKey: 'stayz.tokens' // Optional custom storage key name
 });
 
-// 1. Check Gateway Health
+// Check Gateway Health
 const health = await client.health();
 console.log('Connected to Gateway:', health.licenseTier);
 ```
@@ -35,25 +36,60 @@ console.log('Connected to Gateway:', health.licenseTier);
 
 ## 🔐 Authentication
 
+### 1. Registration & Auto-Login
+Registers a user in Keycloak (`POST /auth/:tenantId/user`) and automatically signs them in:
 ```typescript
-// Register a new user
-await client.auth.register({
+const { token, user } = await client.auth.register({
   email: 'alice@example.com',
   password: 'SecurePassword123!',
   name: 'Alice Smith'
 });
+```
 
-// Login (JWT token is automatically saved to localStorage/Memory)
-const { token } = await client.auth.login({
+### 2. Login
+Accepts `email`, `username`, or `login`:
+```typescript
+const { token, refreshToken, user } = await client.auth.login({
   email: 'alice@example.com',
   password: 'SecurePassword123!'
 });
+```
+
+### 3. Synchronous User Inspection (`getUser`)
+Decodes the active JWT token instantaneously without any network overhead:
+```typescript
+const user = client.auth.getUser();
+console.log(user?.id, user?.email, user?.roles);
+```
+
+### 4. Password Recovery & Reset
+```typescript
+// Send recovery email
+await client.auth.forgotPassword('alice@example.com');
+
+// Complete reset with action token
+await client.auth.resetPassword({
+  token: actionTokenFromEmail,
+  newPassword: 'NewSecurePassword123!'
+});
 
-// Check status & profile
-if (client.auth.isAuthenticated()) {
-  const profile = await client.auth.getProfile();
-  console.log('Logged in as:', profile.email);
-}
+// Change password (while logged in)
+await client.auth.changePassword({
+  oldPassword: 'OldPassword123!',
+  newPassword: 'NewSecurePassword123!'
+});
+```
+
+### 5. Token Renewal & Google OAuth
+```typescript
+// Silent token renewal
+await client.auth.refreshToken();
+
+// Google OAuth login
+await client.auth.loginWithGoogle(googleIdToken);
+
+// Update user profile attributes
+await client.auth.updateProfile({ firstName: 'Alice', attributes: { theme: 'dark' } });
 
 // Logout
 client.auth.logout();
@@ -90,14 +126,56 @@ console.log(`Found ${total} orders:`, data);
 ### 3. Update & Delete
 ```typescript
 // Update
-await client.from('order').update(orderId, {
-  status: 'paid'
-});
+await client.from('order').update(orderId, { status: 'paid' });
 
 // Soft Delete
 await client.from('order').delete(orderId);
 ```
 
+### 4. Revisions & Audit History
+```typescript
+const revisions = await client.from('order').revisions(orderId);
+console.log('Audit history:', revisions);
+```
+
+### 5. Graph Relations (Linking Records)
+```typescript
+// Link order to a client record
+await client.from('order').link(orderId, {
+  targetTypeName: 'client',
+  targetId: clientId,
+  relationName: 'belongs_to'
+});
+
+// Fetch all relations
+const relations = await client.from('order').getRelations(orderId);
+
+// Unlink
+await client.from('order').unlink(orderId, 'belongs_to', clientId, 'client');
+```
+
+### 6. Workflow Plugin Actions
+```typescript
+// Type-level action (e.g. checkout quote)
+await client.from('quote').action('checkout', { quoteId });
+
+// Instance-level action (e.g. cancel order)
+await client.from('order').instanceAction(orderId, 'cancel', { reason: 'Customer request' });
+```
+
+### 7. Export CSV
+```typescript
+// Returns raw CSV string matching active filters
+const csv = await client.from('order').eq('status', 'paid').exportCsv();
+```
+
+### 8. User Profile & Wallet (`/me`)
+```typescript
+// Returns user profile + loyalty wallet points from generic-api
+const me = await client.getMe();
+console.log(me.name, me.wallet?.available_points);
+```
+
 ---
 
 ## 🛠️ Dynamic Schema Alteration