@taruvi/refine-providers 1.3.3 → 1.3.4-beta.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { DataProvider, AuthProvider, AccessControlProvider, MetaQuery, CrudFilter, CrudSort, Pagination } from '@refinedev/core';
-import { Client, GraphFormat, GraphInclude } from '@taruvi/sdk';
+import { Client, GraphFormat, GraphInclude, Database, BackendFilterTreeRoot } from '@taruvi/sdk';
 
 /**
  * Creates a Refine DataProvider for Taruvi database operations.
@@ -94,11 +94,16 @@ declare function functionsDataProvider(client: Client): DataProvider;
 declare function analyticsDataProvider(client: Client): DataProvider;
 
 /**
- * Login params
+ * Login params - supports both redirect flow and credentials flow
  */
 interface LoginParams {
-    /** URL to redirect after successful login */
+    /** For redirect-based login - URL to redirect after successful login */
     callbackUrl?: string;
+    /** For credentials-based login (if supported) */
+    username?: string;
+    password?: string;
+    /** Whether to use redirect flow (default: true) */
+    redirect?: boolean;
 }
 /**
  * Logout params
@@ -118,10 +123,11 @@ declare let _cachedUser: Record<string, any> | null;
 /**
  * Creates a Refine AuthProvider for Taruvi authentication.
  *
- * Uses redirect-based Web UI Flow:
+ * Supports redirect-based authentication flow (Web UI Flow):
  * 1. User calls login() → Redirects to backend /accounts/login/
  * 2. User authenticates on backend
- * 3. Backend redirects back and sets session token
+ * 3. Backend redirects back with tokens in URL hash
+ * 4. Client extracts and stores tokens automatically
  */
 declare function authProvider(client: Client): AuthProvider;
 
@@ -229,11 +235,74 @@ interface TaruviListResponse<T> {
  * Example: { field: "age", operator: "gte", value: 18 } → "age__gte=18"
  */
 declare const REFINE_OPERATOR_MAP: Record<string, string>;
+type ConvertRefineFiltersOptions = {
+    /**
+     * `bracket` (default): logical `and` / `or` use Taruvi CrudFilters bracket query keys.
+     * `flatten`: legacy merge (OR becomes AND) — only for Storage list filters that do not support CrudFilters.
+     */
+    logicalEncoding?: "bracket" | "flatten";
+};
+/** One leaf filter ready for flat `field__op=value` query encoding. */
+type FlatFilterLeaf = {
+    field: string;
+    operator: string;
+    value: unknown;
+};
+/** Root logical filter for JSON `filters` query param (not wrapped in an array). */
+type LogicalCrudFilter = {
+    operator: "and" | "or";
+    value: CrudFilter[];
+};
+/**
+ * Taruvi list filter payload: leaf array → flat query params; logical object → JSON tree.
+ */
+type TaruviListFilters = FlatFilterLeaf[] | LogicalCrudFilter;
+/** True when `filters` is a non-logical array of field leaves (may be empty). */
+declare function isFlatFilterList(filters: unknown): filters is FlatFilterLeaf[];
+/** True when `filters` is a single logical object (and / or), not an array. */
+declare function isLogicalCrudFilter(filters: unknown): filters is LogicalCrudFilter;
+/**
+ * Normalize Refine `CrudFilter[]` or Taruvi payloads for `applyFilters`.
+ * Legacy: all field leaves → flat array; single root logical → logical object.
+ */
+declare function normalizeTaruviListFilters(filters: unknown): TaruviListFilters | undefined;
+/**
+ * Collect field filters that can be sent as top-level query params (implicit AND).
+ *
+ * Returns `null` when the list contains `or` or other shapes that require the JSON
+ * `filters` tree. FK-traversal fields (`department_id.name`, etc.) must use flat
+ * params on the current platform — nesting them under JSON `and` breaks traversal.
+ */
+declare function collectFlatLeaves(filters?: CrudFilter[]): FlatFilterLeaf[] | null;
+/** Backend operator token for CrudFilters bracket payloads (suffix or `eq`). */
+declare function refineOperatorToBackendKey(operator: string): string;
+/** String value for a leaf filter (flat or bracket). */
+declare function formatRefineLeafValue(operator: string, value: unknown): string;
+/** Encode one CrudFilter node (logical or leaf) into bracket-style flat query keys. */
+declare function encodeCrudFilterBracket(filter: CrudFilter, path: string, out: Record<string, string>): void;
+/**
+ * Converts Refine `CrudFilter[]` into the backend JSON `filters` query param tree
+ * (root array of `{ operator: "and"|"or", value: [...] }` nodes).
+ *
+ * Leaf `operator` values are **Taruvi / platform** tokens after `refineOperatorToBackendKey`.
+ * Leaf `operator` values use Taruvi / platform tokens from `refineOperatorToBackendKey`.
+ */
+declare function convertRefineFiltersToBackendTree(filters?: CrudFilter[]): BackendFilterTreeRoot | null;
+/**
+ * Converts one logical CrudFilter object into the backend JSON `filters` tree root.
+ */
+declare function convertLogicalFilterToBackendTree(filter: LogicalCrudFilter): BackendFilterTreeRoot | null;
+/** Encode leaf filters as flat `field__op` query param keys. */
+declare function encodeFlatFilterListToParams(leaves: FlatFilterLeaf[]): Record<string, string>;
 /**
  * Converts Refine CrudFilter[] to Taruvi query parameters.
- * Handles both simple filters and logical operators (and/or).
+ * Logical `and` / `or` use CrudFilters bracket notation unless `logicalEncoding: 'flatten'`.
+ */
+declare function convertRefineFilters(filters?: CrudFilter[], options?: ConvertRefineFiltersOptions): Record<string, string>;
+/**
+ * Applies flat query param entries (including bracket keys) onto a Database query.
  */
-declare function convertRefineFilters(filters?: CrudFilter[]): Record<string, string>;
+declare function applyRefineQueryParamsToDatabase<T>(query: Database<T>, params: Record<string, string>): Database<T>;
 /**
  * Converts Refine CrudSort[] to Taruvi ordering parameter.
  * Uses DRF convention: "-field" for DESC, "field" for ASC.
@@ -264,4 +333,4 @@ declare function buildQueryString(params?: Record<string, unknown>): string;
  */
 declare function handleError(error: unknown): never;
 
-export { type AllowedAction, type AnalyticsMeta, type AppCustomMeta, type FunctionMeta, type LoginParams, type LogoutParams, REFINE_OPERATOR_MAP, type RegisterParams, type StorageDownloadResponse, type StorageUploadVariables, type TaruviListResponse, type TaruviMeta, _cachedUser, accessControlProvider, analyticsDataProvider, appDataProvider, authProvider, buildQueryString, buildRefineQueryParams, convertRefineFilters, convertRefinePagination, convertRefineSorters, dataProvider, functionsDataProvider, handleError, storageDataProvider, userDataProvider };
+export { type AllowedAction, type AnalyticsMeta, type AppCustomMeta, type ConvertRefineFiltersOptions, type FlatFilterLeaf, type FunctionMeta, type LogicalCrudFilter, type LoginParams, type LogoutParams, REFINE_OPERATOR_MAP, type RegisterParams, type StorageDownloadResponse, type StorageUploadVariables, type TaruviListFilters, type TaruviListResponse, type TaruviMeta, _cachedUser, accessControlProvider, analyticsDataProvider, appDataProvider, applyRefineQueryParamsToDatabase, authProvider, buildQueryString, buildRefineQueryParams, collectFlatLeaves, convertLogicalFilterToBackendTree, convertRefineFilters, convertRefineFiltersToBackendTree, convertRefinePagination, convertRefineSorters, dataProvider, encodeCrudFilterBracket, encodeFlatFilterListToParams, formatRefineLeafValue, functionsDataProvider, handleError, isFlatFilterList, isLogicalCrudFilter, normalizeTaruviListFilters, refineOperatorToBackendKey, storageDataProvider, userDataProvider };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { DataProvider, AuthProvider, AccessControlProvider, MetaQuery, CrudFilter, CrudSort, Pagination } from '@refinedev/core';
-import { Client, GraphFormat, GraphInclude } from '@taruvi/sdk';
+import { Client, GraphFormat, GraphInclude, Database, BackendFilterTreeRoot } from '@taruvi/sdk';
 
 /**
  * Creates a Refine DataProvider for Taruvi database operations.
@@ -94,11 +94,16 @@ declare function functionsDataProvider(client: Client): DataProvider;
 declare function analyticsDataProvider(client: Client): DataProvider;
 
 /**
- * Login params
+ * Login params - supports both redirect flow and credentials flow
  */
 interface LoginParams {
-    /** URL to redirect after successful login */
+    /** For redirect-based login - URL to redirect after successful login */
     callbackUrl?: string;
+    /** For credentials-based login (if supported) */
+    username?: string;
+    password?: string;
+    /** Whether to use redirect flow (default: true) */
+    redirect?: boolean;
 }
 /**
  * Logout params
@@ -118,10 +123,11 @@ declare let _cachedUser: Record<string, any> | null;
 /**
  * Creates a Refine AuthProvider for Taruvi authentication.
  *
- * Uses redirect-based Web UI Flow:
+ * Supports redirect-based authentication flow (Web UI Flow):
  * 1. User calls login() → Redirects to backend /accounts/login/
  * 2. User authenticates on backend
- * 3. Backend redirects back and sets session token
+ * 3. Backend redirects back with tokens in URL hash
+ * 4. Client extracts and stores tokens automatically
  */
 declare function authProvider(client: Client): AuthProvider;
 
@@ -229,11 +235,74 @@ interface TaruviListResponse<T> {
  * Example: { field: "age", operator: "gte", value: 18 } → "age__gte=18"
  */
 declare const REFINE_OPERATOR_MAP: Record<string, string>;
+type ConvertRefineFiltersOptions = {
+    /**
+     * `bracket` (default): logical `and` / `or` use Taruvi CrudFilters bracket query keys.
+     * `flatten`: legacy merge (OR becomes AND) — only for Storage list filters that do not support CrudFilters.
+     */
+    logicalEncoding?: "bracket" | "flatten";
+};
+/** One leaf filter ready for flat `field__op=value` query encoding. */
+type FlatFilterLeaf = {
+    field: string;
+    operator: string;
+    value: unknown;
+};
+/** Root logical filter for JSON `filters` query param (not wrapped in an array). */
+type LogicalCrudFilter = {
+    operator: "and" | "or";
+    value: CrudFilter[];
+};
+/**
+ * Taruvi list filter payload: leaf array → flat query params; logical object → JSON tree.
+ */
+type TaruviListFilters = FlatFilterLeaf[] | LogicalCrudFilter;
+/** True when `filters` is a non-logical array of field leaves (may be empty). */
+declare function isFlatFilterList(filters: unknown): filters is FlatFilterLeaf[];
+/** True when `filters` is a single logical object (and / or), not an array. */
+declare function isLogicalCrudFilter(filters: unknown): filters is LogicalCrudFilter;
+/**
+ * Normalize Refine `CrudFilter[]` or Taruvi payloads for `applyFilters`.
+ * Legacy: all field leaves → flat array; single root logical → logical object.
+ */
+declare function normalizeTaruviListFilters(filters: unknown): TaruviListFilters | undefined;
+/**
+ * Collect field filters that can be sent as top-level query params (implicit AND).
+ *
+ * Returns `null` when the list contains `or` or other shapes that require the JSON
+ * `filters` tree. FK-traversal fields (`department_id.name`, etc.) must use flat
+ * params on the current platform — nesting them under JSON `and` breaks traversal.
+ */
+declare function collectFlatLeaves(filters?: CrudFilter[]): FlatFilterLeaf[] | null;
+/** Backend operator token for CrudFilters bracket payloads (suffix or `eq`). */
+declare function refineOperatorToBackendKey(operator: string): string;
+/** String value for a leaf filter (flat or bracket). */
+declare function formatRefineLeafValue(operator: string, value: unknown): string;
+/** Encode one CrudFilter node (logical or leaf) into bracket-style flat query keys. */
+declare function encodeCrudFilterBracket(filter: CrudFilter, path: string, out: Record<string, string>): void;
+/**
+ * Converts Refine `CrudFilter[]` into the backend JSON `filters` query param tree
+ * (root array of `{ operator: "and"|"or", value: [...] }` nodes).
+ *
+ * Leaf `operator` values are **Taruvi / platform** tokens after `refineOperatorToBackendKey`.
+ * Leaf `operator` values use Taruvi / platform tokens from `refineOperatorToBackendKey`.
+ */
+declare function convertRefineFiltersToBackendTree(filters?: CrudFilter[]): BackendFilterTreeRoot | null;
+/**
+ * Converts one logical CrudFilter object into the backend JSON `filters` tree root.
+ */
+declare function convertLogicalFilterToBackendTree(filter: LogicalCrudFilter): BackendFilterTreeRoot | null;
+/** Encode leaf filters as flat `field__op` query param keys. */
+declare function encodeFlatFilterListToParams(leaves: FlatFilterLeaf[]): Record<string, string>;
 /**
  * Converts Refine CrudFilter[] to Taruvi query parameters.
- * Handles both simple filters and logical operators (and/or).
+ * Logical `and` / `or` use CrudFilters bracket notation unless `logicalEncoding: 'flatten'`.
+ */
+declare function convertRefineFilters(filters?: CrudFilter[], options?: ConvertRefineFiltersOptions): Record<string, string>;
+/**
+ * Applies flat query param entries (including bracket keys) onto a Database query.
  */
-declare function convertRefineFilters(filters?: CrudFilter[]): Record<string, string>;
+declare function applyRefineQueryParamsToDatabase<T>(query: Database<T>, params: Record<string, string>): Database<T>;
 /**
  * Converts Refine CrudSort[] to Taruvi ordering parameter.
  * Uses DRF convention: "-field" for DESC, "field" for ASC.
@@ -264,4 +333,4 @@ declare function buildQueryString(params?: Record<string, unknown>): string;
  */
 declare function handleError(error: unknown): never;
 
-export { type AllowedAction, type AnalyticsMeta, type AppCustomMeta, type FunctionMeta, type LoginParams, type LogoutParams, REFINE_OPERATOR_MAP, type RegisterParams, type StorageDownloadResponse, type StorageUploadVariables, type TaruviListResponse, type TaruviMeta, _cachedUser, accessControlProvider, analyticsDataProvider, appDataProvider, authProvider, buildQueryString, buildRefineQueryParams, convertRefineFilters, convertRefinePagination, convertRefineSorters, dataProvider, functionsDataProvider, handleError, storageDataProvider, userDataProvider };
+export { type AllowedAction, type AnalyticsMeta, type AppCustomMeta, type ConvertRefineFiltersOptions, type FlatFilterLeaf, type FunctionMeta, type LogicalCrudFilter, type LoginParams, type LogoutParams, REFINE_OPERATOR_MAP, type RegisterParams, type StorageDownloadResponse, type StorageUploadVariables, type TaruviListFilters, type TaruviListResponse, type TaruviMeta, _cachedUser, accessControlProvider, analyticsDataProvider, appDataProvider, applyRefineQueryParamsToDatabase, authProvider, buildQueryString, buildRefineQueryParams, collectFlatLeaves, convertLogicalFilterToBackendTree, convertRefineFilters, convertRefineFiltersToBackendTree, convertRefinePagination, convertRefineSorters, dataProvider, encodeCrudFilterBracket, encodeFlatFilterListToParams, formatRefineLeafValue, functionsDataProvider, handleError, isFlatFilterList, isLogicalCrudFilter, normalizeTaruviListFilters, refineOperatorToBackendKey, storageDataProvider, userDataProvider };