zone4code-sdk 1.0.1 → 1.0.3

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

package/dist/index.cjs

@@ -75,7 +75,9 @@ var AuthClient = class _AuthClient {
   tenantId;
   storage;
   storageKey;
+  refreshStorageKey;
   token = null;
+  refreshTokenValue = null;
   fetchFn;
   static TOKEN_KEY_PREFIX = "z4c_token_";
   constructor(options) {
@@ -83,6 +85,7 @@ var AuthClient = class _AuthClient {
     this.tenantId = options.tenantId;
     this.storage = options.storage;
     this.storageKey = options.storageKey || _AuthClient.TOKEN_KEY_PREFIX + this.tenantId;
+    this.refreshStorageKey = this.storageKey + "_refresh";
     this.fetchFn = options.fetchFn || (typeof fetch !== "undefined" ? fetch : globalThis.fetch);
     if (options.initialToken) {
       this.setToken(options.initialToken);
@@ -91,11 +94,18 @@ var AuthClient = class _AuthClient {
         if (stored) this.token = stored;
       }).catch(() => {
       });
+      Promise.resolve(this.storage.getItem(this.refreshStorageKey)).then((stored) => {
+        if (stored) this.refreshTokenValue = stored;
+      }).catch(() => {
+      });
     }
   }
   getToken() {
     return this.token;
   }
+  getRefreshToken() {
+    return this.refreshTokenValue;
+  }
   setToken(token) {
     this.token = token;
     if (token) {
@@ -104,6 +114,14 @@ var AuthClient = class _AuthClient {
       this.storage.removeItem(this.storageKey);
     }
   }
+  setRefreshToken(token) {
+    this.refreshTokenValue = token;
+    if (token) {
+      this.storage.setItem(this.refreshStorageKey, token);
+    } else {
+      this.storage.removeItem(this.refreshStorageKey);
+    }
+  }
   isAuthenticated() {
     return !!this.token;
   }
@@ -212,6 +230,9 @@ var AuthClient = class _AuthClient {
     if (token) {
       this.setToken(token);
     }
+    if (json.refresh_token) {
+      this.setRefreshToken(json.refresh_token);
+    }
     const user = this.getUser() || json.user;
     return {
       token: token || "",
@@ -220,6 +241,163 @@ var AuthClient = class _AuthClient {
       ...json
     };
   }
+  /**
+   * Authenticate via Google OAuth ID token
+   */
+  async loginWithGoogle(token) {
+    const url = `${this.gatewayUrl}/auth/${this.tenantId}/login/google`;
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-tenant-id": this.tenantId
+      },
+      body: JSON.stringify({ token })
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || err.error || `Google login failed with HTTP ${res.status}`);
+    }
+    const json = await res.json();
+    const jwt = json.token || json.access_token;
+    if (jwt) {
+      this.setToken(jwt);
+    }
+    if (json.refresh_token) {
+      this.setRefreshToken(json.refresh_token);
+    }
+    const user = this.getUser() || json.user;
+    return {
+      token: jwt || "",
+      refreshToken: json.refresh_token,
+      user,
+      ...json
+    };
+  }
+  /**
+   * Renew expired access token using stored or provided refresh token
+   */
+  async refreshToken(refreshToken) {
+    const tokenToUse = refreshToken || this.getRefreshToken();
+    if (!tokenToUse) {
+      throw new Error("No refresh token available");
+    }
+    const url = `${this.gatewayUrl}/auth/${this.tenantId}/refresh`;
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-tenant-id": this.tenantId
+      },
+      body: JSON.stringify({ refresh_token: tokenToUse })
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || err.error || `Token refresh failed with HTTP ${res.status}`);
+    }
+    const json = await res.json();
+    const token = json.token || json.access_token;
+    if (token) {
+      this.setToken(token);
+    }
+    if (json.refresh_token) {
+      this.setRefreshToken(json.refresh_token);
+    }
+    const user = this.getUser() || json.user;
+    return {
+      token: token || "",
+      refreshToken: json.refresh_token,
+      user,
+      ...json
+    };
+  }
+  /**
+   * Request password reset email
+   */
+  async forgotPassword(data) {
+    const payload = typeof data === "string" ? { email: data } : data;
+    const url = `${this.gatewayUrl}/auth/${this.tenantId}/auth/forgot-password`;
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-tenant-id": this.tenantId
+      },
+      body: JSON.stringify(payload)
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(json.message || json.error || `Forgot password request failed with HTTP ${res.status}`);
+    }
+    return json;
+  }
+  /**
+   * Complete password reset using action token
+   */
+  async resetPassword(data) {
+    const url = `${this.gatewayUrl}/auth/${this.tenantId}/auth/reset-password`;
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-tenant-id": this.tenantId
+      },
+      body: JSON.stringify(data)
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(json.message || json.error || `Reset password failed with HTTP ${res.status}`);
+    }
+    return json;
+  }
+  /**
+   * Change password for current or specified user
+   */
+  async changePassword(data, userId) {
+    const targetUserId = userId || this.getUser()?.id;
+    if (!targetUserId) {
+      throw new Error("User ID required: user is not logged in and no userId was provided");
+    }
+    const url = `${this.gatewayUrl}/auth/${this.tenantId}/user/${targetUserId}/change-password`;
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-tenant-id": this.tenantId,
+        ...this.token ? { "Authorization": `Bearer ${this.token}` } : {}
+      },
+      body: JSON.stringify(data)
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || err.error || `Change password failed with HTTP ${res.status}`);
+    }
+    return res.json().catch(() => ({ success: true }));
+  }
+  /**
+   * Update profile attributes for current or specified user
+   */
+  async updateProfile(data, userId) {
+    const targetUserId = userId || this.getUser()?.id;
+    if (!targetUserId) {
+      throw new Error("User ID required: user is not logged in and no userId was provided");
+    }
+    const url = `${this.gatewayUrl}/auth/${this.tenantId}/user/${targetUserId}`;
+    const res = await this.fetchFn(url, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        "x-tenant-id": this.tenantId,
+        ...this.token ? { "Authorization": `Bearer ${this.token}` } : {}
+      },
+      body: JSON.stringify(data)
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || err.error || `Update profile failed with HTTP ${res.status}`);
+    }
+    return res.json();
+  }
   /**
    * Fetch current authenticated user profile
    */
@@ -245,10 +423,11 @@ var AuthClient = class _AuthClient {
     return res.json();
   }
   /**
-   * Log out and clear saved token
+   * Log out and clear saved tokens
    */
   logout() {
     this.setToken(null);
+    this.setRefreshToken(null);
   }
 };
 
@@ -484,6 +663,132 @@ var EntityQueryBuilder = class {
     }
     return { success: true };
   }
+  /**
+   * Fetch revision history for an entity record
+   */
+  async revisions(id) {
+    const url = `${this.gatewayUrl}/generic/${this.tenantId}/${this.typeName}/${id}/revisions`;
+    const res = await this.fetchFn(url, {
+      headers: this.getHeaders()
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || `Failed to fetch revisions for ${this.typeName}/${id}`);
+    }
+    return res.json();
+  }
+  /**
+   * Fetch all graph relations for this entity record
+   */
+  async getRelations(id, lang) {
+    const qs = lang ? `?lang=${encodeURIComponent(lang)}` : "";
+    const url = `${this.gatewayUrl}/generic/${this.tenantId}/${this.typeName}/${id}/relations${qs}`;
+    const res = await this.fetchFn(url, {
+      headers: this.getHeaders()
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || `Failed to fetch relations for ${this.typeName}/${id}`);
+    }
+    return res.json();
+  }
+  /**
+   * Link this record to another entity record
+   */
+  async link(id, payload) {
+    const url = `${this.gatewayUrl}/generic/${this.tenantId}/${this.typeName}/${id}/relations`;
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: this.getHeaders(),
+      body: JSON.stringify(payload)
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || `Failed to create relation for ${this.typeName}/${id}`);
+    }
+    return res.json().catch(() => ({ success: true }));
+  }
+  /**
+   * Replace the full set of relations of one relation name
+   */
+  async setLinks(id, payload) {
+    const url = `${this.gatewayUrl}/generic/${this.tenantId}/${this.typeName}/${id}/relations`;
+    const res = await this.fetchFn(url, {
+      method: "PUT",
+      headers: this.getHeaders(),
+      body: JSON.stringify(payload)
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || `Failed to replace relations for ${this.typeName}/${id}`);
+    }
+    return res.json().catch(() => ({ success: true }));
+  }
+  /**
+   * Remove one graph link between two records
+   */
+  async unlink(id, relationName, targetId, targetTypeName) {
+    const url = `${this.gatewayUrl}/generic/${this.tenantId}/${this.typeName}/${id}/relations/${encodeURIComponent(relationName)}/${encodeURIComponent(targetId)}?targetTypeName=${encodeURIComponent(targetTypeName)}`;
+    const res = await this.fetchFn(url, {
+      method: "DELETE",
+      headers: this.getHeaders()
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || `Failed to delete relation ${relationName} for ${this.typeName}/${id}`);
+    }
+    return res.json().catch(() => ({ success: true }));
+  }
+  /**
+   * Execute a type-level workflow plugin action (e.g. checkout, batch-process)
+   */
+  async action(actionName, payload) {
+    const url = `${this.gatewayUrl}/generic/${this.tenantId}/${this.typeName}/actions/${actionName}`;
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: this.getHeaders(),
+      body: payload ? JSON.stringify(payload) : void 0
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || `Action ${actionName} failed on type ${this.typeName}`);
+    }
+    return res.json();
+  }
+  /**
+   * Execute an instance-level workflow plugin action (e.g. cancel order, approve)
+   */
+  async instanceAction(id, actionName, payload) {
+    const url = `${this.gatewayUrl}/generic/${this.tenantId}/${this.typeName}/${id}/actions/${actionName}`;
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: this.getHeaders(),
+      body: payload ? JSON.stringify(payload) : void 0
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || `Action ${actionName} failed on ${this.typeName}/${id}`);
+    }
+    return res.json();
+  }
+  /**
+   * Export matching entity records to CSV format with active filters
+   */
+  async exportCsv() {
+    const qs = this.queryParams.toString();
+    const url = `${this.gatewayUrl}/generic/${this.tenantId}/${this.typeName}/export/csv${qs ? `?${qs}` : ""}`;
+    const res = await this.fetchFn(url, {
+      headers: {
+        ...this.getHeaders(),
+        "Accept": "text/csv"
+      }
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || `Failed to export CSV for ${this.typeName}`);
+    }
+    return res.text();
+  }
 };
 
 // src/client.ts
@@ -538,6 +843,27 @@ var Zone4CodeClient = class {
   entities(typeName) {
     return this.from(typeName);
   }
+  /**
+   * Get current authenticated user profile and platform wallet
+   */
+  async getMe() {
+    const token = this.auth.getToken();
+    if (!token) {
+      throw new Error("Not authenticated: please call login() or setToken() first");
+    }
+    const res = await this.fetchFn(`${this.gatewayUrl}/generic/${this.tenantId}/me`, {
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${token}`,
+        "x-tenant-id": this.tenantId
+      }
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ message: res.statusText }));
+      throw new Error(err.message || `Failed to fetch profile & wallet (HTTP ${res.status})`);
+    }
+    return res.json();
+  }
   /**
    * Check gateway connectivity & health
    */