zone4code-sdk 1.0.7 → 1.0.9

package/dist/index.d.cts

@@ -42,7 +42,17 @@ interface Zone4CodeConfig {
      * Callback invoked when a user session expires (e.g. refresh token expired or invalid).
      */
     onSessionExpired?: () => void;
+    /**
+     * Default language locale for API requests (e.g. 'en', 'fr', 'ar').
+     * Can be overridden per query with `.lang(locale)` or set to '*' for raw translations.
+     */
+    defaultLanguage?: string;
 }
+/**
+ * Represents either a plain localized string or a dictionary of multilingual values:
+ * e.g. "Beach Villa" or { en: "Beach Villa", fr: "Villa Plage", ar: "فيلا الشاطئ" }
+ */
+type Translatable<T = string> = T | Record<string, T>;
 interface AuthUser {
     id: string;
     email?: string;
@@ -77,6 +87,12 @@ interface EntityListResponse<T = Record<string, any>> {
     limit?: number;
     cursor?: string;
 }
+interface GetEntityOptions {
+    flat?: boolean;
+    include?: string[];
+    lang?: string;
+    rawTranslations?: boolean;
+}
 interface SchemaProperty {
     type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
     description?: string;
@@ -85,6 +101,11 @@ interface SchemaProperty {
     items?: SchemaProperty;
     properties?: Record<string, SchemaProperty>;
     required?: string[];
+    /**
+     * If true, this field accepts multilingual JSONB dictionaries ({ en: "...", fr: "..." })
+     * and automatically flattens to the active language during queries.
+     */
+    translatable?: boolean;
 }
 interface EntitySchemaDefinition {
     typeName: string;
@@ -159,6 +180,7 @@ declare class AuthClient {
     private sessionExpiredListeners;
     private activeRefreshPromise;
     private storageLoadedPromise;
+    private getLanguage?;
     private static TOKEN_KEY_PREFIX;
     constructor(options: {
         gatewayUrl: string;
@@ -170,6 +192,7 @@ declare class AuthClient {
         autoRefresh?: boolean;
         tokenExpiryBuffer?: number;
         onSessionExpired?: () => void;
+        getLanguage?: () => string | null;
     });
     getToken(): string | null;
     getRefreshToken(): string | null;
@@ -287,15 +310,30 @@ declare class EntityQueryBuilder<T = Record<string, any>> {
         getToken?: () => string | null;
         fetchFn?: typeof fetch;
         fetchWithAuth?: (url: string, init?: RequestInit) => Promise<Response>;
+        defaultLanguage?: string | null | (() => string | null);
     });
     private getHeaders;
     private executeRequest;
     eq(field: string, value: string | number | boolean): this;
     ne(field: string, value: string | number | boolean): this;
-    gt(field: string, value: number): this;
-    gte(field: string, value: number): this;
-    lt(field: string, value: number): this;
-    lte(field: string, value: number): this;
+    gt(field: string, value: string | number | Date): this;
+    gte(field: string, value: string | number | Date): this;
+    lt(field: string, value: string | number | Date): this;
+    lte(field: string, value: string | number | Date): this;
+    /**
+     * Filter records within a numeric or date range (inclusive)
+     * Example: .between('price', 100, 500) or .between('check_in', '2026-10-01', '2026-10-15')
+     */
+    between(field: string, from: string | number | Date, to: string | number | Date): this;
+    /**
+     * Alias for .between(...)
+     */
+    range(field: string, min: string | number | Date, max: string | number | Date): this;
+    /**
+     * Helper specifically for date/timestamp range filtering
+     * Example: .dateRange('created_at', '2026-09-01', '2026-09-30')
+     */
+    dateRange(field: string, startDate: string | Date, endDate: string | Date): this;
     /**
      * Case-insensitive substring search (ILIKE %substring%)
      */
@@ -321,17 +359,29 @@ declare class EntityQueryBuilder<T = Record<string, any>> {
     offset(offset: number): this;
     cursor(token: string): this;
     flat(enabled?: boolean): this;
+    /**
+     * Set target language for automatic JSONB translation flattening.
+     * Example: .lang('fr') returns French fields, falling back to 'en'.
+     * Set to '*' or call .rawTranslations() to get raw multilingual dictionaries.
+     */
+    lang(locale: string): this;
+    /**
+     * Alias for .lang(locale)
+     */
+    language(locale: string): this;
+    /**
+     * Request raw, unflattened multilingual dictionaries ({ en: "...", fr: "..." })
+     * Essential for Admin/CMS forms to avoid overwriting other language translations on update.
+     */
+    rawTranslations(enabled?: boolean): this;
     /**
      * Execute query and list matching records with pagination metadata
      */
     list(): Promise<EntityListResponse<T>>;
     /**
-     * Fetch a single entity by ID with optional expansion and flattening
+     * Fetch a single entity by ID with optional expansion, translation locale, and flattening
      */
-    get(id: string, options?: {
-        flat?: boolean;
-        include?: string[];
-    }): Promise<EntityRecord<T>>;
+    get(id: string, options?: GetEntityOptions): Promise<EntityRecord<T>>;
     /**
      * Create a new entity record matching schema
      */
@@ -420,7 +470,16 @@ declare class Zone4CodeClient {
     readonly schema: SchemaClient;
     private storage;
     private fetchFn;
+    private currentLanguage;
     constructor(config: Zone4CodeConfig);
+    /**
+     * Set the active default language for API requests (e.g., 'en', 'fr', 'ar', or '*' for raw)
+     */
+    setLanguage(lang: string | null): this;
+    /**
+     * Get the active default language
+     */
+    getLanguage(): string | null;
     /**
      * Access an entity collection with chainable query builder (like Supabase .from('orders'))
      */
@@ -458,4 +517,4 @@ declare class MemoryStorage implements StorageAdapter {
 }
 declare function getDefaultStorage(): StorageAdapter;
 
-export { AuthClient, type AuthResponse, type AuthUser, type EntityListResponse, EntityQueryBuilder, type EntityRecord, type EntityRelationPayload, type EntityRelationRecord, type EntityReplaceRelationsPayload, type EntityRevision, type EntitySchemaDefinition, type FilterOperator, MemoryStorage, SchemaClient, type SchemaProperty, type StorageAdapter, type UserProfileWithWallet, Zone4CodeClient, type Zone4CodeConfig, createClient, createClient as default, getDefaultStorage };
+export { AuthClient, type AuthResponse, type AuthUser, type EntityListResponse, EntityQueryBuilder, type EntityRecord, type EntityRelationPayload, type EntityRelationRecord, type EntityReplaceRelationsPayload, type EntityRevision, type EntitySchemaDefinition, type FilterOperator, type GetEntityOptions, MemoryStorage, SchemaClient, type SchemaProperty, type StorageAdapter, type Translatable, type UserProfileWithWallet, Zone4CodeClient, type Zone4CodeConfig, createClient, createClient as default, getDefaultStorage };

package/dist/index.d.ts

@@ -42,7 +42,17 @@ interface Zone4CodeConfig {
      * Callback invoked when a user session expires (e.g. refresh token expired or invalid).
      */
     onSessionExpired?: () => void;
+    /**
+     * Default language locale for API requests (e.g. 'en', 'fr', 'ar').
+     * Can be overridden per query with `.lang(locale)` or set to '*' for raw translations.
+     */
+    defaultLanguage?: string;
 }
+/**
+ * Represents either a plain localized string or a dictionary of multilingual values:
+ * e.g. "Beach Villa" or { en: "Beach Villa", fr: "Villa Plage", ar: "فيلا الشاطئ" }
+ */
+type Translatable<T = string> = T | Record<string, T>;
 interface AuthUser {
     id: string;
     email?: string;
@@ -77,6 +87,12 @@ interface EntityListResponse<T = Record<string, any>> {
     limit?: number;
     cursor?: string;
 }
+interface GetEntityOptions {
+    flat?: boolean;
+    include?: string[];
+    lang?: string;
+    rawTranslations?: boolean;
+}
 interface SchemaProperty {
     type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
     description?: string;
@@ -85,6 +101,11 @@ interface SchemaProperty {
     items?: SchemaProperty;
     properties?: Record<string, SchemaProperty>;
     required?: string[];
+    /**
+     * If true, this field accepts multilingual JSONB dictionaries ({ en: "...", fr: "..." })
+     * and automatically flattens to the active language during queries.
+     */
+    translatable?: boolean;
 }
 interface EntitySchemaDefinition {
     typeName: string;
@@ -159,6 +180,7 @@ declare class AuthClient {
     private sessionExpiredListeners;
     private activeRefreshPromise;
     private storageLoadedPromise;
+    private getLanguage?;
     private static TOKEN_KEY_PREFIX;
     constructor(options: {
         gatewayUrl: string;
@@ -170,6 +192,7 @@ declare class AuthClient {
         autoRefresh?: boolean;
         tokenExpiryBuffer?: number;
         onSessionExpired?: () => void;
+        getLanguage?: () => string | null;
     });
     getToken(): string | null;
     getRefreshToken(): string | null;
@@ -287,15 +310,30 @@ declare class EntityQueryBuilder<T = Record<string, any>> {
         getToken?: () => string | null;
         fetchFn?: typeof fetch;
         fetchWithAuth?: (url: string, init?: RequestInit) => Promise<Response>;
+        defaultLanguage?: string | null | (() => string | null);
     });
     private getHeaders;
     private executeRequest;
     eq(field: string, value: string | number | boolean): this;
     ne(field: string, value: string | number | boolean): this;
-    gt(field: string, value: number): this;
-    gte(field: string, value: number): this;
-    lt(field: string, value: number): this;
-    lte(field: string, value: number): this;
+    gt(field: string, value: string | number | Date): this;
+    gte(field: string, value: string | number | Date): this;
+    lt(field: string, value: string | number | Date): this;
+    lte(field: string, value: string | number | Date): this;
+    /**
+     * Filter records within a numeric or date range (inclusive)
+     * Example: .between('price', 100, 500) or .between('check_in', '2026-10-01', '2026-10-15')
+     */
+    between(field: string, from: string | number | Date, to: string | number | Date): this;
+    /**
+     * Alias for .between(...)
+     */
+    range(field: string, min: string | number | Date, max: string | number | Date): this;
+    /**
+     * Helper specifically for date/timestamp range filtering
+     * Example: .dateRange('created_at', '2026-09-01', '2026-09-30')
+     */
+    dateRange(field: string, startDate: string | Date, endDate: string | Date): this;
     /**
      * Case-insensitive substring search (ILIKE %substring%)
      */
@@ -321,17 +359,29 @@ declare class EntityQueryBuilder<T = Record<string, any>> {
     offset(offset: number): this;
     cursor(token: string): this;
     flat(enabled?: boolean): this;
+    /**
+     * Set target language for automatic JSONB translation flattening.
+     * Example: .lang('fr') returns French fields, falling back to 'en'.
+     * Set to '*' or call .rawTranslations() to get raw multilingual dictionaries.
+     */
+    lang(locale: string): this;
+    /**
+     * Alias for .lang(locale)
+     */
+    language(locale: string): this;
+    /**
+     * Request raw, unflattened multilingual dictionaries ({ en: "...", fr: "..." })
+     * Essential for Admin/CMS forms to avoid overwriting other language translations on update.
+     */
+    rawTranslations(enabled?: boolean): this;
     /**
      * Execute query and list matching records with pagination metadata
      */
     list(): Promise<EntityListResponse<T>>;
     /**
-     * Fetch a single entity by ID with optional expansion and flattening
+     * Fetch a single entity by ID with optional expansion, translation locale, and flattening
      */
-    get(id: string, options?: {
-        flat?: boolean;
-        include?: string[];
-    }): Promise<EntityRecord<T>>;
+    get(id: string, options?: GetEntityOptions): Promise<EntityRecord<T>>;
     /**
      * Create a new entity record matching schema
      */
@@ -420,7 +470,16 @@ declare class Zone4CodeClient {
     readonly schema: SchemaClient;
     private storage;
     private fetchFn;
+    private currentLanguage;
     constructor(config: Zone4CodeConfig);
+    /**
+     * Set the active default language for API requests (e.g., 'en', 'fr', 'ar', or '*' for raw)
+     */
+    setLanguage(lang: string | null): this;
+    /**
+     * Get the active default language
+     */
+    getLanguage(): string | null;
     /**
      * Access an entity collection with chainable query builder (like Supabase .from('orders'))
      */
@@ -458,4 +517,4 @@ declare class MemoryStorage implements StorageAdapter {
 }
 declare function getDefaultStorage(): StorageAdapter;
 
-export { AuthClient, type AuthResponse, type AuthUser, type EntityListResponse, EntityQueryBuilder, type EntityRecord, type EntityRelationPayload, type EntityRelationRecord, type EntityReplaceRelationsPayload, type EntityRevision, type EntitySchemaDefinition, type FilterOperator, MemoryStorage, SchemaClient, type SchemaProperty, type StorageAdapter, type UserProfileWithWallet, Zone4CodeClient, type Zone4CodeConfig, createClient, createClient as default, getDefaultStorage };
+export { AuthClient, type AuthResponse, type AuthUser, type EntityListResponse, EntityQueryBuilder, type EntityRecord, type EntityRelationPayload, type EntityRelationRecord, type EntityReplaceRelationsPayload, type EntityRevision, type EntitySchemaDefinition, type FilterOperator, type GetEntityOptions, MemoryStorage, SchemaClient, type SchemaProperty, type StorageAdapter, type Translatable, type UserProfileWithWallet, Zone4CodeClient, type Zone4CodeConfig, createClient, createClient as default, getDefaultStorage };

package/dist/index.js

@@ -48,6 +48,7 @@ var AuthClient = class _AuthClient {
   sessionExpiredListeners = [];
   activeRefreshPromise = null;
   storageLoadedPromise;
+  getLanguage;
   static TOKEN_KEY_PREFIX = "z4c_token_";
   constructor(options) {
     const storage = options.storage;
@@ -59,9 +60,10 @@ var AuthClient = class _AuthClient {
     this.storageKey = storageKey;
     this.refreshStorageKey = refreshStorageKey;
     this.fetchFn = options.fetchFn || (typeof fetch !== "undefined" ? fetch : globalThis.fetch);
-    this.autoRefresh = options.autoRefresh ?? true;
-    this.tokenExpiryBuffer = options.tokenExpiryBuffer ?? 30;
+    this.autoRefresh = options.autoRefresh !== void 0 ? options.autoRefresh : true;
+    this.tokenExpiryBuffer = options.tokenExpiryBuffer !== void 0 ? options.tokenExpiryBuffer : 30;
     this.onSessionExpiredCallback = options.onSessionExpired;
+    this.getLanguage = options.getLanguage;
     this.storageLoadedPromise = (async () => {
       if (options.initialToken) {
         this.setToken(options.initialToken);
@@ -176,6 +178,10 @@ var AuthClient = class _AuthClient {
     if (token && !headers["Authorization"] && !headers["authorization"]) {
       headers["Authorization"] = `Bearer ${token}`;
     }
+    const currentLang = this.getLanguage ? this.getLanguage() : null;
+    if (currentLang && !headers["Accept-Language"] && !headers["accept-language"]) {
+      headers["Accept-Language"] = currentLang;
+    }
     let res = await this.fetchFn(url, { ...init, headers });
     if (res.status === 401 && this.autoRefresh && this.getRefreshToken()) {
       try {
@@ -523,6 +529,12 @@ var EntityQueryBuilder = class {
     this.getToken = options.getToken || (() => null);
     this.fetchFn = options.fetchFn || (typeof fetch !== "undefined" ? fetch : globalThis.fetch);
     this.fetchWithAuth = options.fetchWithAuth;
+    if (options.defaultLanguage) {
+      const langVal = typeof options.defaultLanguage === "function" ? options.defaultLanguage() : options.defaultLanguage;
+      if (langVal) {
+        this.queryParams.set("lang", langVal);
+      }
+    }
   }
   getHeaders() {
     const headers = {
@@ -554,21 +566,47 @@ var EntityQueryBuilder = class {
     return this;
   }
   gt(field, value) {
-    this.queryParams.append(`${field}[gt]`, String(value));
+    const val = value instanceof Date ? value.toISOString() : String(value);
+    this.queryParams.append(`${field}[gt]`, val);
     return this;
   }
   gte(field, value) {
-    this.queryParams.append(`${field}[gte]`, String(value));
+    const val = value instanceof Date ? value.toISOString() : String(value);
+    this.queryParams.append(`${field}[gte]`, val);
     return this;
   }
   lt(field, value) {
-    this.queryParams.append(`${field}[lt]`, String(value));
+    const val = value instanceof Date ? value.toISOString() : String(value);
+    this.queryParams.append(`${field}[lt]`, val);
     return this;
   }
   lte(field, value) {
-    this.queryParams.append(`${field}[lte]`, String(value));
+    const val = value instanceof Date ? value.toISOString() : String(value);
+    this.queryParams.append(`${field}[lte]`, val);
+    return this;
+  }
+  /**
+   * Filter records within a numeric or date range (inclusive)
+   * Example: .between('price', 100, 500) or .between('check_in', '2026-10-01', '2026-10-15')
+   */
+  between(field, from, to) {
+    this.gte(field, from);
+    this.lte(field, to);
     return this;
   }
+  /**
+   * Alias for .between(...)
+   */
+  range(field, min, max) {
+    return this.between(field, min, max);
+  }
+  /**
+   * Helper specifically for date/timestamp range filtering
+   * Example: .dateRange('created_at', '2026-09-01', '2026-09-30')
+   */
+  dateRange(field, startDate, endDate) {
+    return this.between(field, startDate, endDate);
+  }
   /**
    * Case-insensitive substring search (ILIKE %substring%)
    */
@@ -641,6 +679,37 @@ var EntityQueryBuilder = class {
     this.queryParams.set("flat", enabled ? "true" : "false");
     return this;
   }
+  /**
+   * Set target language for automatic JSONB translation flattening.
+   * Example: .lang('fr') returns French fields, falling back to 'en'.
+   * Set to '*' or call .rawTranslations() to get raw multilingual dictionaries.
+   */
+  lang(locale) {
+    this.queryParams.set("lang", locale);
+    return this;
+  }
+  /**
+   * Alias for .lang(locale)
+   */
+  language(locale) {
+    return this.lang(locale);
+  }
+  /**
+   * Request raw, unflattened multilingual dictionaries ({ en: "...", fr: "..." })
+   * Essential for Admin/CMS forms to avoid overwriting other language translations on update.
+   */
+  rawTranslations(enabled = true) {
+    if (enabled) {
+      this.queryParams.set("lang", "*");
+      this.queryParams.set("rawTranslations", "true");
+    } else {
+      this.queryParams.delete("rawTranslations");
+      if (this.queryParams.get("lang") === "*") {
+        this.queryParams.delete("lang");
+      }
+    }
+    return this;
+  }
   // ----------------------------------------------------
   // Execution Methods
   // ----------------------------------------------------
@@ -658,13 +727,20 @@ var EntityQueryBuilder = class {
     return res.json();
   }
   /**
-   * Fetch a single entity by ID with optional expansion and flattening
+   * Fetch a single entity by ID with optional expansion, translation locale, and flattening
    */
   async get(id, options) {
     const params = new URLSearchParams(this.queryParams);
     if (options?.flat !== void 0) {
       params.set("flat", options.flat ? "true" : "false");
     }
+    if (options?.lang) {
+      params.set("lang", options.lang);
+    }
+    if (options?.rawTranslations) {
+      params.set("lang", "*");
+      params.set("rawTranslations", "true");
+    }
     if (options?.include && options.include.length > 0) {
       const existing = params.get("include");
       const existingList = existing ? existing.split(",").map((s) => s.trim()) : [];
@@ -740,7 +816,8 @@ var EntityQueryBuilder = class {
    * Fetch all graph relations for this entity record
    */
   async getRelations(id, lang) {
-    const qs = lang ? `?lang=${encodeURIComponent(lang)}` : "";
+    const activeLang = lang || this.queryParams.get("lang");
+    const qs = activeLang ? `?lang=${encodeURIComponent(activeLang)}` : "";
     const url = `${this.gatewayUrl}/generic/${this.tenantId}/${this.typeName}/${id}/relations${qs}`;
     const res = await this.executeRequest(url);
     if (!res.ok) {
@@ -939,6 +1016,7 @@ var Zone4CodeClient = class {
   schema;
   storage;
   fetchFn;
+  currentLanguage = null;
   constructor(config) {
     if (!config.gatewayUrl) {
       throw new Error("Zone4CodeClient requires a `gatewayUrl` (e.g., http://localhost:8080)");
@@ -950,6 +1028,7 @@ var Zone4CodeClient = class {
     this.tenantId = config.tenantId;
     this.storage = config.storage || getDefaultStorage();
     this.fetchFn = config.fetch || (typeof fetch !== "undefined" ? fetch : globalThis.fetch);
+    this.currentLanguage = config.defaultLanguage || null;
     this.auth = new AuthClient({
       gatewayUrl: this.gatewayUrl,
       tenantId: this.tenantId,
@@ -959,7 +1038,8 @@ var Zone4CodeClient = class {
       fetchFn: this.fetchFn,
       autoRefresh: config.autoRefresh,
       tokenExpiryBuffer: config.tokenExpiryBuffer,
-      onSessionExpired: config.onSessionExpired
+      onSessionExpired: config.onSessionExpired,
+      getLanguage: () => this.getLanguage()
     });
     this.schema = new SchemaClient({
       gatewayUrl: this.gatewayUrl,
@@ -969,6 +1049,19 @@ var Zone4CodeClient = class {
       fetchWithAuth: (url, init) => this.auth.fetchWithAuth(url, init)
     });
   }
+  /**
+   * Set the active default language for API requests (e.g., 'en', 'fr', 'ar', or '*' for raw)
+   */
+  setLanguage(lang) {
+    this.currentLanguage = lang;
+    return this;
+  }
+  /**
+   * Get the active default language
+   */
+  getLanguage() {
+    return this.currentLanguage;
+  }
   /**
    * Access an entity collection with chainable query builder (like Supabase .from('orders'))
    */
@@ -979,7 +1072,8 @@ var Zone4CodeClient = class {
       typeName,
       getToken: () => this.auth.getToken(),
       fetchFn: this.fetchFn,
-      fetchWithAuth: (url, init) => this.auth.fetchWithAuth(url, init)
+      fetchWithAuth: (url, init) => this.auth.fetchWithAuth(url, init),
+      defaultLanguage: () => this.getLanguage()
     });
   }
   /**