@progalaxyelabs/ngx-stonescriptphp-client 1.0.0 → 1.0.4

package/docs/AUTH_COMPATIBILITY.md

@@ -0,0 +1,310 @@
+# Authentication Compatibility Guide
+
+## StoneScriptPHP Framework vs ngx-stonescriptphp-client
+
+This document outlines the authentication flow compatibility between the Angular client library and StoneScriptPHP backend framework (v2.1.x).
+
+---
+
+## ⚠️ CRITICAL INCOMPATIBILITY FOUND
+
+### Token Refresh Endpoint Mismatch
+
+**CLIENT IMPLEMENTATION** (`api-connection.service.ts:187`):
+```typescript
+const refreshTokenUrl = this.host + 'user/refresh_access'
+await fetch(refreshTokenUrl, {
+    method: 'POST',
+    body: JSON.stringify({
+        access_token: this.accessToken,
+        refresh_token: refreshToken
+    })
+})
+```
+
+**SERVER IMPLEMENTATION** (StoneScriptPHP `RefreshRoute.php`):
+```php
+// Default route: POST /auth/refresh
+// OR custom: AuthRoutes::register($router, ['prefix' => '/api/auth']);
+
+// Expected request:
+// - Refresh token comes from httpOnly cookie (NOT request body)
+// - CSRF token required in X-CSRF-Token header
+// - Does NOT accept tokens in request body for security
+
+// Response:
+{
+    "status": "ok",
+    "data": {
+        "access_token": "eyJ...",
+        "expires_in": 900,
+        "token_type": "Bearer"
+    }
+}
+```
+
+### Issues Identified
+
+#### 1. **Endpoint Path Mismatch**
+- **Client expects**: `/user/refresh_access`
+- **Server provides**: `/auth/refresh` (default) or custom prefix
+
+#### 2. **Token Transmission Mismatch**
+- **Client sends**: Tokens in JSON request body
+- **Server expects**:
+  - Refresh token in httpOnly cookie (named `refresh_token`)
+  - CSRF token in `X-CSRF-Token` header
+  - **Does NOT read tokens from request body**
+
+#### 3. **Security Model Mismatch**
+- **Client**: Stores tokens in localStorage/sessionStorage (via TokenService)
+- **Server**: Uses httpOnly cookies + CSRF protection (XSS-safe)
+
+#### 4. **Response Format Mismatch**
+- **Client expects**: `response.data.access_token`
+- **Server returns**: `ApiResponse` where data is the second parameter:
+  ```php
+  return new ApiResponse('ok', [
+      'access_token' => $token,
+      'expires_in' => 900,
+      'token_type' => 'Bearer'
+  ]);
+  ```
+
+---
+
+## Authentication Flow Analysis
+
+### StoneScriptPHP Framework Auth System
+
+The framework provides **two authentication modes**:
+
+#### Mode 1: Built-in Cookie-Based Auth (Secure, Recommended)
+Located in `/src/Auth/Routes/`:
+- `POST /auth/refresh` - Refresh access token using httpOnly cookies
+- `POST /auth/logout` - Logout and invalidate refresh token
+
+**Security Features**:
+- httpOnly cookies prevent XSS attacks
+- CSRF token protection
+- Refresh token rotation
+- Optional token blacklisting via `TokenStorageInterface`
+
+**Registration**:
+```php
+// In your index.php or bootstrap
+use StoneScriptPHP\Auth\AuthRoutes;
+
+AuthRoutes::register($router, [
+    'prefix' => '/auth',  // or '/api/auth'
+    'token_storage' => $tokenStorage  // optional
+]);
+```
+
+#### Mode 2: Custom Implementation (Templates)
+Located in `/src/Templates/Auth/`:
+- `email-password/LoginRoute.php.template`
+- `email-password/RegisterRoute.php.template`
+- `email-password/PasswordResetRoute.php.template`
+- `mobile-otp/SendOtpRoute.php.template`
+- And more...
+
+**Note**: Templates are **scaffolding code** that developers customize. They show:
+- Example status values: `'success'` vs `'ok'` (inconsistent!)
+- Example token format
+- Database queries
+- But are NOT the actual built-in implementation
+
+---
+
+## Current Client Implementation Analysis
+
+### What Works ✅
+
+1. **HTTP Methods**: All match (GET, POST, PUT, PATCH, DELETE)
+2. **ApiResponse Structure**: Compatible
+   - Client expects: `{ status: string, message: string, data: any }`
+   - Server returns: Same structure
+3. **Bearer Token Authentication**: Client correctly adds `Authorization: Bearer {token}`
+4. **Automatic 401 Retry**: Client attempts token refresh on 401 errors
+
+### What's Broken ❌
+
+1. **Token Refresh Flow**: Completely incompatible
+   - Different endpoint paths
+   - Different token transmission method
+   - Different security model
+
+2. **AuthService**: Empty placeholder (no implementation)
+
+3. **Login/Register Endpoints**: Not standardized
+   - Templates show `/api/auth/login` but customizable
+   - Response format varies (some templates use `'success'` vs `'ok'`)
+
+---
+
+## Compatibility Matrix
+
+| Feature | Client (v0.0.13) | Framework (v2.1.x) | Compatible? |
+|---------|------------------|-------------------|-------------|
+| **HTTP Methods** | GET, POST, PUT, PATCH, DELETE | All supported | ✅ Yes |
+| **ApiResponse Format** | `{status, message, data}` | Same | ✅ Yes |
+| **Bearer Auth** | `Authorization: Bearer {token}` | Same | ✅ Yes |
+| **Token Refresh Endpoint** | `/user/refresh_access` | `/auth/refresh` | ❌ No |
+| **Token Storage** | localStorage | httpOnly cookies | ❌ No |
+| **CSRF Protection** | Not implemented | Required | ❌ No |
+| **Login Endpoint** | Not defined | Custom (templates) | ⚠️ Varies |
+| **Token Format** | JWT in response body | JWT in cookie + body | ⚠️ Partial |
+
+---
+
+## Recommended Solutions
+
+### Option 1: Update Client to Match Framework (Recommended)
+
+**Pros**:
+- Better security (httpOnly cookies)
+- CSRF protection
+- Aligns with framework best practices
+
+**Cons**:
+- Breaking change for existing users
+- Requires cookie handling
+
+**Implementation**:
+1. Update `refreshAccessToken()` to:
+   - Call `POST /auth/refresh` with credentials: 'include'
+   - Send CSRF token from cookie
+   - Don't send tokens in body
+2. Add `CsrfService` to manage CSRF tokens
+3. Update `TokenService` to work with cookies
+4. Add cookie configuration to `MyEnvironmentModel`
+
+### Option 2: Add Server-Side Compatibility Endpoint
+
+**Pros**:
+- No client breaking changes
+- Backward compatible
+
+**Cons**:
+- Less secure (tokens in body)
+- Developers must implement it
+
+**Implementation**:
+Create custom route in StoneScriptPHP project:
+```php
+// src/App/Routes/LegacyRefreshRoute.php
+class LegacyRefreshRoute implements IRouteHandler {
+    public function process(): ApiResponse {
+        // Read tokens from request body
+        $accessToken = request()->input['access_token'] ?? null;
+        $refreshToken = request()->input['refresh_token'] ?? null;
+
+        // Verify and refresh...
+        // Return new access token
+    }
+}
+
+// Register in routes.php
+'POST' => [
+    '/user/refresh_access' => LegacyRefreshRoute::class
+]
+```
+
+### Option 3: Make Client Configurable
+
+**Pros**:
+- Supports both modes
+- Migration path
+
+**Cons**:
+- More complex
+- Maintenance burden
+
+**Implementation**:
+```typescript
+export interface AuthConfig {
+    mode: 'cookie' | 'body';
+    refreshEndpoint: string;
+    useCsrf: boolean;
+}
+```
+
+---
+
+## Migration Path for Existing Apps
+
+For apps currently using the client with custom backends:
+
+### Step 1: Check Your Backend Auth Implementation
+```bash
+# Does your backend match the client's expectations?
+curl -X POST http://localhost:8000/user/refresh_access \
+  -H "Content-Type: application/json" \
+  -d '{"access_token": "...", "refresh_token": "..."}'
+```
+
+### Step 2: Update to StoneScriptPHP v2.1.x Auth
+```php
+// Option A: Use built-in secure auth
+AuthRoutes::register($router, ['prefix' => '/api/auth']);
+
+// Option B: Create legacy compatibility route
+// See Option 2 above
+```
+
+### Step 3: Update Client Configuration
+```typescript
+// Wait for v0.0.14+ with auth config support
+// OR implement custom auth service extending ApiConnectionService
+```
+
+---
+
+## Action Items for Next Release (v0.0.14)
+
+### Must Fix (Breaking Changes Acceptable):
+1. ✅ Add configurable auth endpoints
+2. ✅ Implement cookie-based auth mode
+3. ✅ Add CSRF token support
+4. ✅ Update AuthService with actual implementation
+5. ✅ Document both auth modes
+
+### Should Have:
+1. Add login/register/logout helper methods
+2. Add auth state management (RxJS)
+3. Add auth guards/interceptors examples
+4. Create migration guide with code examples
+
+### Nice to Have:
+1. Social auth helpers (Google, etc.)
+2. Password reset flow helpers
+3. Email verification helpers
+4. Multi-factor auth support
+
+---
+
+## Conclusion
+
+**Current Status**: ❌ **NOT FULLY COMPATIBLE**
+
+The v0.0.13 client library is **compatible for general API calls** (CRUD operations) but **incompatible for authentication flows**.
+
+### For Developers:
+- ✅ Use for: CRUD API calls with manually managed auth
+- ❌ Don't use: Built-in token refresh (broken)
+- ⚠️ Workaround: Implement custom refresh logic or wait for v0.0.14
+
+### For Package Maintainers:
+- 🔴 **Priority**: Fix auth compatibility before promoting package
+- 📝 Add clear warnings in README about auth limitations
+- 🚀 Plan v0.0.14 with breaking changes to align with framework
+
+---
+
+## References
+
+- **StoneScriptPHP Auth**: `/src/Auth/Routes/RefreshRoute.php`
+- **Client Auth**: `/projects/ngx-stonescriptphp-client/src/lib/api-connection.service.ts`
+- **Framework Version**: v2.1.x (on Packagist)
+- **Client Version**: v0.0.13

package/docs/CHANGELOG.md

@@ -0,0 +1,261 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-12-14
+
+### 🎉 Production Ready Release
+
+This is the first stable production release of `@progalaxyelabs/ngx-stonescriptphp-client`.
+
+#### Repository Organization
+- **Documentation**: Moved CHANGELOG.md and AUTH_COMPATIBILITY.md to `docs/` folder
+- **Project Structure**: Cleaned up root directory - only README.md and HLD.md remain
+- **.gitignore**: Updated for proper npm package exclusions
+- **package.json**: Added `docs` folder to published files
+
+#### Why 1.0.0?
+- ✅ Full compatibility with StoneScriptPHP Framework v2.1.x
+- ✅ All major HTTP methods implemented (GET, POST, PUT, PATCH, DELETE)
+- ✅ Configurable authentication modes (cookie/body/none)
+- ✅ CSRF protection support
+- ✅ Comprehensive documentation
+- ✅ Clean repository structure
+- ✅ Production-ready and stable API
+
+**No code changes from v0.0.15** - purely organizational improvements and version bump to indicate production readiness.
+
+---
+
+## [0.0.15] - 2025-12-14 (Pre-release)
+
+### 🎉 Major Feature: Configurable Authentication Modes
+
+This release adds **full compatibility with StoneScriptPHP Framework v2.1.x authentication** while maintaining backward compatibility.
+
+### Added
+
+#### Authentication Configuration
+- **`AuthConfig` interface**: Configure authentication mode, endpoints, and CSRF settings
+- **`AuthMode` type**: Choose between `'cookie'`, `'body'`, or `'none'` authentication modes
+- **Cookie-based auth mode**: Full support for StoneScriptPHP v2.1.x secure httpOnly cookie + CSRF auth (recommended)
+- **Body-based auth mode**: Legacy mode for custom backends (sends tokens in request body)
+- **No-auth mode**: Disable automatic token refresh for manual auth management
+
+#### New Services & Methods
+- **`CsrfService`**: Manage CSRF tokens from cookies for secure authentication
+- **`TokenService.setAccessToken()`**: Set only access token
+- **`TokenService.setRefreshToken()`**: Set only refresh token
+- **`MyEnvironmentModel.auth`**: Authentication configuration object
+
+### Changed
+
+#### Auth Mode Configuration (Breaking Change with Migration Path)
+- **Default auth mode**: Now defaults to `'cookie'` mode (StoneScriptPHP v2.1.x compatible)
+- **Token refresh**: Completely rewritten to support multiple auth strategies:
+  - **Cookie mode**: Uses httpOnly cookies + CSRF tokens, calls `/auth/refresh` (default)
+  - **Body mode**: Sends tokens in request body (legacy), calls `/user/refresh_access`
+  - **None mode**: Disables automatic token refresh
+
+#### Migration Guide for v0.0.10 → v0.0.15
+
+**For StoneScriptPHP v2.1.x users (recommended):**
+```typescript
+// environment.ts
+export const environment = {
+    apiServer: { host: 'http://localhost:8000/' },
+    auth: {
+        mode: 'cookie',  // Default, can omit
+        refreshEndpoint: '/auth/refresh'  // Default, can omit
+    }
+}
+```
+
+**For legacy/custom backend users:**
+```typescript
+// environment.ts
+export const environment = {
+    apiServer: { host: 'http://localhost:8000/' },
+    auth: {
+        mode: 'body',
+        refreshEndpoint: '/user/refresh_access'
+    }
+}
+```
+
+**To disable auto-refresh:**
+```typescript
+// environment.ts
+export const environment = {
+    apiServer: { host: 'http://localhost:8000/' },
+    auth: { mode: 'none' }
+}
+```
+
+### Fixed
+- ✅ **Authentication compatibility with StoneScriptPHP v2.1.x** - Now fully compatible!
+- ✅ Cookie-based auth with CSRF protection
+- ✅ Configurable refresh endpoints
+- ✅ Proper error handling in both auth modes
+
+### Documentation
+- Updated [AUTH_COMPATIBILITY.md](AUTH_COMPATIBILITY.md) (in docs/) - Auth now fully compatible!
+- Added configuration examples for all auth modes
+- Comprehensive migration guide
+
+---
+
+## [0.0.13] - 2025-12-14 (Skipped - Never Published)
+
+### Added
+
+#### ApiConnectionService
+- **DELETE method**: Added `delete<T>(endpoint: string, queryParamsObj?: any): Promise<ApiResponse<T>>` for DELETE HTTP requests
+- **PUT method**: Added `put<T>(pathWithQueryParams: string, data: any): Promise<ApiResponse<T>>` for PUT HTTP requests (full updates)
+- **PATCH method**: Added `patch<T>(pathWithQueryParams: string, data: any): Promise<ApiResponse<T>>` for PATCH HTTP requests (partial updates)
+
+#### ApiResponse Model
+- **isSuccess()**: Returns `true` if status is 'ok'
+- **isError()**: Returns `true` if status is 'error' or 'not ok'
+- **getData()**: Returns the data payload or null
+- **getError()**: Returns the error message or 'Unknown error'
+- **getStatus()**: Returns the status string
+- **getMessage()**: Returns the message string
+
+### Fixed
+- Version synchronization between root package.json (0.0.12) and library package.json (was 0.0.10, now 0.0.12)
+
+### Notes
+- `onOk()` and `onNotOk()` methods were already present in ApiResponse (since earlier versions)
+- `DbService` is exported but remains unimplemented - placeholder for future database query functionality
+
+## [0.0.10] - 2025-12-08
+
+### Published to NPM
+- Initial NPM release with GET and POST methods
+- Basic authentication flow with token refresh
+- ApiResponse model with `onOk()`, `onNotOk()`, and `onError()` callbacks
+
+## [0.0.9] - 2025-12-07
+
+### Changed
+- Documentation improvements
+- README updates for npm presentation
+
+## [0.0.8] - 2025-12-06
+
+### Changed
+- Package naming fixes
+- Documentation updates
+
+---
+
+## Migration Guide: v0.0.10 → v0.0.13
+
+### New HTTP Methods Available
+
+You can now use all standard REST HTTP methods:
+
+```typescript
+// Before (v0.0.10) - Had to use raw HttpClient for these operations
+constructor(private http: HttpClient) {}
+this.http.delete(`${apiUrl}/users/${id}`).subscribe(...)
+
+// After (v0.0.13) - Use ApiConnectionService directly
+constructor(private apiConnection: ApiConnectionService) {}
+
+// DELETE
+await this.apiConnection.delete(`/users/${id}`)
+await this.apiConnection.delete(`/users/${id}`, { force: true }) // with query params
+
+// PUT (full update)
+await this.apiConnection.put(`/users/${id}`, { name: 'John', email: 'john@example.com' })
+
+// PATCH (partial update)
+await this.apiConnection.patch(`/users/${id}`, { name: 'John' })
+```
+
+### New ApiResponse Helper Methods
+
+```typescript
+// Before (v0.0.10) - Manual status checking
+const response = await this.apiConnection.get('/users')
+if (response.status === 'ok') {
+    this.users = response.data
+} else {
+    this.error = response.message
+}
+
+// After (v0.0.13) - Use helper methods
+const response = await this.apiConnection.get('/users')
+
+// Option 1: Helper methods
+if (response.isSuccess()) {
+    this.users = response.getData()
+} else {
+    this.error = response.getError()
+}
+
+// Option 2: Fluent API (still available)
+response
+    .onOk(data => this.users = data)
+    .onNotOk((message, data) => this.error = message)
+    .onError(() => console.error('Network error'))
+```
+
+---
+
+## Known Issues
+
+### 🔴 CRITICAL: Authentication Flow Incompatibility
+
+The token refresh mechanism in v0.0.13 is **incompatible** with StoneScriptPHP Framework v2.1.x built-in authentication.
+
+**Issue**: Client expects `/user/refresh_access` endpoint with tokens in request body, but the framework's built-in `RefreshRoute` uses:
+- Endpoint: `/auth/refresh` (default, customizable)
+- Security: httpOnly cookies + CSRF tokens
+- Does NOT accept tokens in request body
+
+**Impact**:
+- ✅ **Works**: General API calls (GET, POST, PUT, PATCH, DELETE) with manual token management
+- ❌ **Broken**: Automatic token refresh on 401 errors
+- ⚠️ **Workaround**: Implement custom `/user/refresh_access` route on your backend OR manage auth manually
+
+**See**: [AUTH_COMPATIBILITY.md](AUTH_COMPATIBILITY.md) for detailed analysis and solutions.
+
+**Fix Planned**: v0.0.14 will add configurable auth modes to support both cookie-based and body-based authentication.
+
+### DbService (Not Yet Implemented)
+The `DbService` is exported in the public API but contains no implementation. It is a placeholder for future database query functionality. Do not use it in production.
+
+### Angular Version Compatibility
+The package is built with Angular 16 but declares peer dependencies for Angular 16-20. While it should work across these versions, comprehensive testing has only been done with Angular 16. If you encounter issues with Angular 19/20, please report them at: https://github.com/progalaxyelabs/ngx-stonescriptphp-client/issues
+
+---
+
+## Roadmap
+
+### Planned for v0.0.13+
+- Complete `DbService` implementation with type-safe database queries
+- HTTP interceptor support for custom auth/logging/retry logic
+- File upload/download support
+- Comprehensive unit tests
+- Rebuild with Angular 19/20 for production
+
+### Future Versions
+- RxJS operators for common patterns
+- WebSocket support for real-time features
+- Migration to `@stonescriptphp` namespace
+- Demo application and Storybook documentation
+
+---
+
+## Links
+
+- **NPM Package**: https://www.npmjs.com/package/@progalaxyelabs/ngx-stonescriptphp-client
+- **GitHub Repository**: https://github.com/progalaxyelabs/ngx-stonescriptphp-client
+- **StoneScriptPHP Framework**: https://stonescriptphp.org
+- **Report Issues**: https://github.com/progalaxyelabs/ngx-stonescriptphp-client/issues

package/package.json

@@ -1,25 +1,82 @@
 {
   "name": "@progalaxyelabs/ngx-stonescriptphp-client",
-  "version": "1.0.0",
+  "version": "1.0.4",
+  "description": "Angular client library for StoneScriptPHP backend framework",
+  "keywords": [
+    "angular",
+    "stonescriptphp",
+    "http-client",
+    "api-client",
+    "typescript"
+  ],
+  "homepage": "https://stonescriptphp.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/progalaxyelabs/ngx-stonescriptphp-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/progalaxyelabs/ngx-stonescriptphp-client/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "StoneScriptPHP Team",
+    "email": "team@stonescriptphp.org",
+    "url": "https://stonescriptphp.org"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "HLD.md",
+    "LICENSE",
+    "docs"
+  ],
+  "scripts": {
+    "ng": "ng",
+    "start": "ng serve",
+    "prebuild": "npm --no-git-tag-version version patch",
+    "build": "ng build",
+    "watch": "ng build --watch --configuration development",
+    "test": "ng test",
+    "publish:npm": "npm publish --access public"
+  },
+  "private": false,
   "peerDependencies": {
-    "@angular/common": "^16.2.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0",
-    "@angular/core": "^16.2.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0"
+    "@angular/common": "^19.0.0 || ^20.0.0",
+    "@angular/core": "^19.0.0 || ^20.0.0",
+    "rxjs": "^7.8.0"
   },
   "dependencies": {
-    "tslib": "^2.3.0"
+    "@angular-devkit/schematics": "^20.0.0",
+    "@angular/animations": "^20.0.0",
+    "@angular/common": "^20.0.0",
+    "@angular/compiler": "^20.0.0",
+    "@angular/core": "^20.0.0",
+    "@angular/forms": "^20.0.0",
+    "@angular/platform-browser": "^20.0.0",
+    "@angular/platform-browser-dynamic": "^20.0.0",
+    "@angular/router": "^20.0.0",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.8.0",
+    "zone.js": "~0.15.0"
+  },
+  "devDependencies": {
+    "@angular-devkit/build-angular": "^20.0.0",
+    "@angular/cli": "^20.0.0",
+    "@angular/compiler-cli": "^20.0.0",
+    "@schematics/angular": "^20.0.0",
+    "@types/jasmine": "~5.1.0",
+    "jasmine-core": "~5.5.0",
+    "karma": "~6.4.0",
+    "karma-chrome-launcher": "~3.2.0",
+    "karma-coverage": "~2.2.0",
+    "karma-jasmine": "~5.1.0",
+    "karma-jasmine-html-reporter": "~2.1.0",
+    "ng-packagr": "^20.0.0",
+    "typescript": "~5.8.0"
   },
-  "sideEffects": false,
-  "module": "fesm2022/progalaxyelabs-ngx-stonescriptphp-client.mjs",
-  "typings": "index.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "esm2022": "./esm2022/progalaxyelabs-ngx-stonescriptphp-client.mjs",
-      "esm": "./esm2022/progalaxyelabs-ngx-stonescriptphp-client.mjs",
-      "default": "./fesm2022/progalaxyelabs-ngx-stonescriptphp-client.mjs"
-    }
+  "publishConfig": {
+    "access": "public"
   }
-}
+}