@cundi/refine-xaf 1.0.0 → 1.0.2

package/README.md

@@ -264,4 +264,46 @@ export const DemoObjectCreate = () => {
 
 1. **Install Dependencies**: `npm install`
 2. **Build SDK**: `npm run build`
-3. **Development Mode**: `npm run dev`
+3. **Development Mode**: `npm run dev` (watch mode)
+4. **Run Tests**: `npm run test`
+5. **Test Coverage**: `npm run test:coverage`
+
+## Utilities
+
+The SDK provides several utility functions:
+
+### Password Utilities
+
+```tsx
+import { generatePassword, validatePasswordStrength } from "@cundi/refine-xaf";
+
+// Generate a secure random password
+const password = generatePassword(16); // Optional length, default 12
+
+// Validate password strength
+const result = validatePasswordStrength(password);
+if (result.isValid) {
+    console.log("Password is strong!");
+}
+```
+
+### JWT Parsing
+
+```tsx
+import { parseJwt } from "@cundi/refine-xaf";
+
+const token = localStorage.getItem("refine-auth");
+const claims = parseJwt(token);
+console.log(claims.sub, claims.exp);
+```
+
+## Changelog
+
+### v1.0.1 (Latest)
+- Added `generatePassword` and `validatePasswordStrength` utilities
+- Added retry mechanism to `httpClient` (exponential backoff)
+- Improved `SmartList` performance with `useMemo`
+- Extracted TiptapEditor styles to separate CSS file
+- Enhanced environment variable validation for Keycloak
+- Added Jest test framework
+

package/dist/antd-column-ext.d.ts

@@ -0,0 +1,16 @@
+
+// Augment definitions for Ant Design Table Column for defaultVisible support in SmartList
+import 'antd/es/table/Column';
+import 'antd/lib/table/Column';
+
+declare module 'antd/es/table/Column' {
+    export interface ColumnProps<RecordType> {
+        defaultVisible?: boolean;
+    }
+}
+
+declare module 'antd/lib/table/Column' {
+    export interface ColumnProps<RecordType> {
+        defaultVisible?: boolean;
+    }
+}

package/dist/index.css

@@ -0,0 +1,90 @@
+/* src/styles/tiptap.css */
+.ProseMirror pre {
+  background: var(--tiptap-code-bg, #f5f5f5);
+  color: var(--tiptap-code-text, inherit);
+  font-family:
+    "JetBrainsMono",
+    "Courier New",
+    monospace;
+  padding: 0.75rem 1rem;
+  border-radius: 0.5rem;
+}
+.ProseMirror pre code {
+  color: inherit;
+  padding: 0;
+  background: none;
+  font-size: 0.8rem;
+}
+.ProseMirror p {
+  margin-bottom: 0px;
+}
+.ProseMirror:focus {
+  outline: none;
+}
+.ProseMirror table {
+  border-collapse: collapse;
+  table-layout: fixed;
+  width: 100%;
+  margin: 0;
+  overflow: hidden;
+}
+.ProseMirror td,
+.ProseMirror th {
+  min-width: 1em;
+  border: 2px solid var(--tiptap-border, #d9d9d9);
+  padding: 3px 5px;
+  vertical-align: top;
+  box-sizing: border-box;
+  position: relative;
+}
+.ProseMirror th {
+  font-weight: bold;
+  text-align: left;
+  background-color: var(--tiptap-header-bg, #fafafa);
+}
+.ProseMirror .selectedCell:after {
+  z-index: 2;
+  position: absolute;
+  content: "";
+  left: 0;
+  right: 0;
+  top: 0;
+  bottom: 0;
+  background: rgba(200, 200, 255, 0.4);
+  pointer-events: none;
+}
+.ProseMirror .column-resize-handle {
+  position: absolute;
+  right: -2px;
+  top: 0;
+  bottom: -2px;
+  width: 4px;
+  background-color: #adf;
+  pointer-events: none;
+}
+ul[data-type=taskList] {
+  list-style: none;
+  padding: 0;
+}
+ul[data-type=taskList] li {
+  display: flex;
+  align-items: center;
+}
+ul[data-type=taskList] li > label {
+  flex: 0 0 auto;
+  margin-right: 0.5rem;
+  user-select: none;
+}
+ul[data-type=taskList] li > div {
+  flex: 1 1 auto;
+}
+ul[data-type=taskList] input[type=checkbox] {
+  cursor: pointer;
+}
+.ProseMirror p.is-editor-empty:first-child::before {
+  color: var(--tiptap-placeholder, #bfbfbf);
+  content: attr(data-placeholder);
+  float: left;
+  height: 0;
+  pointer-events: none;
+}

package/dist/index.d.mts

@@ -6,42 +6,109 @@ declare const authProvider: AuthProvider;
 
 declare const dataProvider: (apiUrl: string) => DataProvider;
 
-interface IApplicationUser {
+/**
+ * Base entity interface for XAF persistent objects
+ */
+interface IXafEntity {
+    /** Object identifier (GUID) */
     Oid: string;
+}
+/**
+ * Application user entity with authentication and profile information
+ */
+interface IApplicationUser extends IXafEntity {
+    /** Login username */
     UserName: string;
+    /** Display name shown in UI */
     DisplayName: string;
+    /** Email address */
     Email: string;
+    /** Base64 encoded profile photo */
     Photo?: string;
+    /** Whether the user account is active */
     IsActive: boolean;
+    /** Number of failed login attempts */
     AccessFailedCount: number;
+    /** Lockout end timestamp (ISO 8601) */
     LockoutEnd?: string;
+    /** Assigned roles */
     Roles?: IPermissionPolicyRole[];
 }
+/**
+ * Permission policy for role-based access control
+ */
 declare enum SecurityPermissionPolicy {
+    /** Deny all access by default, explicitly grant permissions */
     DenyAllByDefault = "DenyAllByDefault",
+    /** Allow read-only access by default */
     ReadOnlyAllByDefault = "ReadOnlyAllByDefault",
+    /** Allow all access by default, explicitly deny permissions */
     AllowAllByDefault = "AllowAllByDefault"
 }
+/**
+ * Permission state for type-level security
+ */
 declare enum SecurityPermissionState {
+    /** Allow the operation */
     Allow = "Allow",
+    /** Deny the operation */
     Deny = "Deny"
 }
-interface IPermissionPolicyTypePermissionObject {
-    Oid?: string;
+/**
+ * Type-level permission configuration for a specific business object
+ */
+interface IPermissionPolicyTypePermissionObject extends Partial<IXafEntity> {
+    /** Full type name of the target business object */
     TargetType: string;
+    /** Read permission state */
     ReadState?: SecurityPermissionState;
+    /** Write/Update permission state */
     WriteState?: SecurityPermissionState;
+    /** Create permission state */
     CreateState?: SecurityPermissionState;
+    /** Delete permission state */
     DeleteState?: SecurityPermissionState;
+    /** Navigation permission state */
     NavigateState?: SecurityPermissionState;
 }
-interface IPermissionPolicyRole {
-    Oid: string;
+/**
+ * Permission policy role with type-level permissions
+ */
+interface IPermissionPolicyRole extends IXafEntity {
+    /** Role name */
     Name: string;
+    /** Whether this role grants full administrative access */
     IsAdministrative: boolean;
+    /** Default permission policy for this role */
     PermissionPolicy: SecurityPermissionPolicy;
+    /** Type-level permissions for specific business objects */
     TypePermissions?: IPermissionPolicyTypePermissionObject[];
 }
+/**
+ * JWT token claims structure
+ */
+interface IJwtClaims {
+    /** Subject (user ID) */
+    sub?: string;
+    /** Token expiration timestamp */
+    exp?: number;
+    /** Token issued at timestamp */
+    iat?: number;
+    /** Issuer */
+    iss?: string;
+    /** Audience */
+    aud?: string;
+    /** Preferred username (Keycloak) */
+    preferred_username?: string;
+    /** User name claim (XAF) */
+    unique_name?: string;
+    /** Name identifier claim */
+    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"?: string;
+    /** Name claim */
+    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"?: string;
+    /** Allow additional claims */
+    [key: string]: unknown;
+}
 
 declare const TOKEN_KEY = "refine-auth";
 declare class HttpError extends Error {
@@ -52,11 +119,42 @@ declare class HttpError extends Error {
 }
 interface RequestOptions extends RequestInit {
     skipAuth?: boolean;
+    /** Disable automatic retry for this request */
+    noRetry?: boolean;
 }
+/**
+ * Get the API base URL from environment configuration
+ */
 declare const getBaseUrl: () => any;
-declare const httpClient: (endpoint: string, options?: RequestOptions) => Promise<Response | null>;
+/**
+ * HTTP client with automatic retry for transient errors
+ * @param endpoint - API endpoint (relative or absolute URL)
+ * @param options - Request options (extends RequestInit)
+ * @param retryCount - Current retry attempt (internal use)
+ */
+declare const httpClient: (endpoint: string, options?: RequestOptions, retryCount?: number) => Promise<Response | null>;
 declare const parseJwt: (token: string) => any;
 
+/**
+ * Password generation utilities
+ * Provides secure random password generation using crypto API
+ */
+/**
+ * Generate a random password using cryptographically secure random values
+ * @param length - Length of the password (default: 12)
+ * @returns A randomly generated password string
+ */
+declare const generatePassword: (length?: number) => string;
+/**
+ * Validate password strength
+ * @param password - Password to validate
+ * @returns Object with isValid flag and message
+ */
+declare const validatePasswordStrength: (password: string) => {
+    isValid: boolean;
+    message: string;
+};
+
 declare const authService: {
     login: ({ username, password }: any) => Promise<string>;
     getUserByUsername: (username: string) => Promise<IApplicationUser | null>;
@@ -64,6 +162,38 @@ declare const authService: {
     resetPassword: (userId: string, newPassword: string) => Promise<boolean>;
 };
 
+interface KeycloakTokenResponse {
+    access_token: string;
+    id_token?: string;
+    expires_in: number;
+    refresh_expires_in: number;
+    refresh_token: string;
+    token_type: string;
+    "not-before-policy"?: number;
+    session_state?: string;
+    scope?: string;
+}
+declare const keycloakService: {
+    /**
+     * Start Authorization Code Flow with PKCE
+     * Redirects user to Keycloak login page
+     */
+    startAuthorizationFlow: () => Promise<void>;
+    /**
+     * Handle callback from Keycloak
+     * Exchange authorization code for access token
+     */
+    handleCallback: (code: string, state: string) => Promise<{
+        accessToken: string;
+        idToken: string;
+    }>;
+    /**
+     * Logout from Keycloak
+     * Redirects to Keycloak logout endpoint to properly clear the session
+     */
+    logout: (idToken?: string) => void;
+};
+
 declare const Header: React.FC;
 
 interface SmartListProps {
@@ -107,6 +237,14 @@ declare const TiptapEditor: React.FC<TiptapEditorProps>;
 
 declare const LoginPage: React.FC;
 
+declare const KeycloakLoginPage: React.FC;
+
+/**
+ * Auth Callback Component
+ * Handles the OAuth2 callback from Keycloak after user authentication
+ */
+declare const AuthCallback: React.FC;
+
 declare const ApplicationUserList: React.FC<IResourceComponentsProps>;
 
 declare const ApplicationUserCreate: React.FC<IResourceComponentsProps>;
@@ -137,4 +275,4 @@ interface IModelType {
 }
 declare const useModelTypes: () => _tanstack_react_query.UseQueryResult<IModelType[], Error>;
 
-export { ApplicationUserCreate, ApplicationUserEdit, ApplicationUserList, Base64Upload, ColorModeContext, ColorModeContextProvider, Header, HttpError, type IApplicationUser, type IModelType, type IPermissionPolicyRole, type IPermissionPolicyTypePermissionObject, LoginPage, RelatedList, type RequestOptions, RoleCreate, RoleEdit, RoleList, SecurityPermissionPolicy, SecurityPermissionState, SmartList, TOKEN_KEY, TiptapEditor, type TiptapEditorProps, authProvider, authService, dataProvider, getBaseUrl, httpClient, parseJwt, useColorMode, useModelTypes };
+export { ApplicationUserCreate, ApplicationUserEdit, ApplicationUserList, AuthCallback, Base64Upload, ColorModeContext, ColorModeContextProvider, Header, HttpError, type IApplicationUser, type IJwtClaims, type IModelType, type IPermissionPolicyRole, type IPermissionPolicyTypePermissionObject, type IXafEntity, KeycloakLoginPage, type KeycloakTokenResponse, LoginPage, RelatedList, type RequestOptions, RoleCreate, RoleEdit, RoleList, SecurityPermissionPolicy, SecurityPermissionState, SmartList, TOKEN_KEY, TiptapEditor, type TiptapEditorProps, authProvider, authService, dataProvider, generatePassword, getBaseUrl, httpClient, keycloakService, parseJwt, useColorMode, useModelTypes, validatePasswordStrength };

package/dist/index.d.ts

@@ -6,42 +6,109 @@ declare const authProvider: AuthProvider;
 
 declare const dataProvider: (apiUrl: string) => DataProvider;
 
-interface IApplicationUser {
+/**
+ * Base entity interface for XAF persistent objects
+ */
+interface IXafEntity {
+    /** Object identifier (GUID) */
     Oid: string;
+}
+/**
+ * Application user entity with authentication and profile information
+ */
+interface IApplicationUser extends IXafEntity {
+    /** Login username */
     UserName: string;
+    /** Display name shown in UI */
     DisplayName: string;
+    /** Email address */
     Email: string;
+    /** Base64 encoded profile photo */
     Photo?: string;
+    /** Whether the user account is active */
     IsActive: boolean;
+    /** Number of failed login attempts */
     AccessFailedCount: number;
+    /** Lockout end timestamp (ISO 8601) */
     LockoutEnd?: string;
+    /** Assigned roles */
     Roles?: IPermissionPolicyRole[];
 }
+/**
+ * Permission policy for role-based access control
+ */
 declare enum SecurityPermissionPolicy {
+    /** Deny all access by default, explicitly grant permissions */
     DenyAllByDefault = "DenyAllByDefault",
+    /** Allow read-only access by default */
     ReadOnlyAllByDefault = "ReadOnlyAllByDefault",
+    /** Allow all access by default, explicitly deny permissions */
     AllowAllByDefault = "AllowAllByDefault"
 }
+/**
+ * Permission state for type-level security
+ */
 declare enum SecurityPermissionState {
+    /** Allow the operation */
     Allow = "Allow",
+    /** Deny the operation */
     Deny = "Deny"
 }
-interface IPermissionPolicyTypePermissionObject {
-    Oid?: string;
+/**
+ * Type-level permission configuration for a specific business object
+ */
+interface IPermissionPolicyTypePermissionObject extends Partial<IXafEntity> {
+    /** Full type name of the target business object */
     TargetType: string;
+    /** Read permission state */
     ReadState?: SecurityPermissionState;
+    /** Write/Update permission state */
     WriteState?: SecurityPermissionState;
+    /** Create permission state */
     CreateState?: SecurityPermissionState;
+    /** Delete permission state */
     DeleteState?: SecurityPermissionState;
+    /** Navigation permission state */
     NavigateState?: SecurityPermissionState;
 }
-interface IPermissionPolicyRole {
-    Oid: string;
+/**
+ * Permission policy role with type-level permissions
+ */
+interface IPermissionPolicyRole extends IXafEntity {
+    /** Role name */
     Name: string;
+    /** Whether this role grants full administrative access */
     IsAdministrative: boolean;
+    /** Default permission policy for this role */
     PermissionPolicy: SecurityPermissionPolicy;
+    /** Type-level permissions for specific business objects */
     TypePermissions?: IPermissionPolicyTypePermissionObject[];
 }
+/**
+ * JWT token claims structure
+ */
+interface IJwtClaims {
+    /** Subject (user ID) */
+    sub?: string;
+    /** Token expiration timestamp */
+    exp?: number;
+    /** Token issued at timestamp */
+    iat?: number;
+    /** Issuer */
+    iss?: string;
+    /** Audience */
+    aud?: string;
+    /** Preferred username (Keycloak) */
+    preferred_username?: string;
+    /** User name claim (XAF) */
+    unique_name?: string;
+    /** Name identifier claim */
+    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"?: string;
+    /** Name claim */
+    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"?: string;
+    /** Allow additional claims */
+    [key: string]: unknown;
+}
 
 declare const TOKEN_KEY = "refine-auth";
 declare class HttpError extends Error {
@@ -52,11 +119,42 @@ declare class HttpError extends Error {
 }
 interface RequestOptions extends RequestInit {
     skipAuth?: boolean;
+    /** Disable automatic retry for this request */
+    noRetry?: boolean;
 }
+/**
+ * Get the API base URL from environment configuration
+ */
 declare const getBaseUrl: () => any;
-declare const httpClient: (endpoint: string, options?: RequestOptions) => Promise<Response | null>;
+/**
+ * HTTP client with automatic retry for transient errors
+ * @param endpoint - API endpoint (relative or absolute URL)
+ * @param options - Request options (extends RequestInit)
+ * @param retryCount - Current retry attempt (internal use)
+ */
+declare const httpClient: (endpoint: string, options?: RequestOptions, retryCount?: number) => Promise<Response | null>;
 declare const parseJwt: (token: string) => any;
 
+/**
+ * Password generation utilities
+ * Provides secure random password generation using crypto API
+ */
+/**
+ * Generate a random password using cryptographically secure random values
+ * @param length - Length of the password (default: 12)
+ * @returns A randomly generated password string
+ */
+declare const generatePassword: (length?: number) => string;
+/**
+ * Validate password strength
+ * @param password - Password to validate
+ * @returns Object with isValid flag and message
+ */
+declare const validatePasswordStrength: (password: string) => {
+    isValid: boolean;
+    message: string;
+};
+
 declare const authService: {
     login: ({ username, password }: any) => Promise<string>;
     getUserByUsername: (username: string) => Promise<IApplicationUser | null>;
@@ -64,6 +162,38 @@ declare const authService: {
     resetPassword: (userId: string, newPassword: string) => Promise<boolean>;
 };
 
+interface KeycloakTokenResponse {
+    access_token: string;
+    id_token?: string;
+    expires_in: number;
+    refresh_expires_in: number;
+    refresh_token: string;
+    token_type: string;
+    "not-before-policy"?: number;
+    session_state?: string;
+    scope?: string;
+}
+declare const keycloakService: {
+    /**
+     * Start Authorization Code Flow with PKCE
+     * Redirects user to Keycloak login page
+     */
+    startAuthorizationFlow: () => Promise<void>;
+    /**
+     * Handle callback from Keycloak
+     * Exchange authorization code for access token
+     */
+    handleCallback: (code: string, state: string) => Promise<{
+        accessToken: string;
+        idToken: string;
+    }>;
+    /**
+     * Logout from Keycloak
+     * Redirects to Keycloak logout endpoint to properly clear the session
+     */
+    logout: (idToken?: string) => void;
+};
+
 declare const Header: React.FC;
 
 interface SmartListProps {
@@ -107,6 +237,14 @@ declare const TiptapEditor: React.FC<TiptapEditorProps>;
 
 declare const LoginPage: React.FC;
 
+declare const KeycloakLoginPage: React.FC;
+
+/**
+ * Auth Callback Component
+ * Handles the OAuth2 callback from Keycloak after user authentication
+ */
+declare const AuthCallback: React.FC;
+
 declare const ApplicationUserList: React.FC<IResourceComponentsProps>;
 
 declare const ApplicationUserCreate: React.FC<IResourceComponentsProps>;
@@ -137,4 +275,4 @@ interface IModelType {
 }
 declare const useModelTypes: () => _tanstack_react_query.UseQueryResult<IModelType[], Error>;
 
-export { ApplicationUserCreate, ApplicationUserEdit, ApplicationUserList, Base64Upload, ColorModeContext, ColorModeContextProvider, Header, HttpError, type IApplicationUser, type IModelType, type IPermissionPolicyRole, type IPermissionPolicyTypePermissionObject, LoginPage, RelatedList, type RequestOptions, RoleCreate, RoleEdit, RoleList, SecurityPermissionPolicy, SecurityPermissionState, SmartList, TOKEN_KEY, TiptapEditor, type TiptapEditorProps, authProvider, authService, dataProvider, getBaseUrl, httpClient, parseJwt, useColorMode, useModelTypes };
+export { ApplicationUserCreate, ApplicationUserEdit, ApplicationUserList, AuthCallback, Base64Upload, ColorModeContext, ColorModeContextProvider, Header, HttpError, type IApplicationUser, type IJwtClaims, type IModelType, type IPermissionPolicyRole, type IPermissionPolicyTypePermissionObject, type IXafEntity, KeycloakLoginPage, type KeycloakTokenResponse, LoginPage, RelatedList, type RequestOptions, RoleCreate, RoleEdit, RoleList, SecurityPermissionPolicy, SecurityPermissionState, SmartList, TOKEN_KEY, TiptapEditor, type TiptapEditorProps, authProvider, authService, dataProvider, generatePassword, getBaseUrl, httpClient, keycloakService, parseJwt, useColorMode, useModelTypes, validatePasswordStrength };