@progalaxyelabs/ngx-stonescriptphp-client 1.0.0 → 1.0.4

package/HLD.md

@@ -0,0 +1,31 @@
+# ngx-stonescriptphp-client - High Level Design
+
+## Overview
+Official Angular HTTP client library for StoneScriptPHP backend framework.
+
+## Purpose
+Provides type-safe HTTP calls to StoneScriptPHP APIs using auto-generated TypeScript interfaces.
+
+## Architecture
+
+### Components
+- **ApiConnectionService** - HTTP client wrapper with error handling
+- **AuthService** - JWT token management
+- **DbService** - IndexedDB offline storage integration
+- **TokenService** - Token storage and refresh logic
+- **SigninStatusService** - Authentication state management
+
+### Flow
+1. StoneScriptPHP generates TypeScript DTOs from PHP
+2. Angular imports generated interfaces
+3. HTTP calls use interfaces for type safety
+4. Responses validated against DTOs
+
+## Tech Stack
+- Angular >= 19.0
+- RxJS >= 7.8
+- TypeScript >= 5.8
+
+## Distribution
+- Published to npm as @progalaxyelabs/ngx-stonescriptphp-client
+- Future migration to @stonescriptphp namespace planned

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ProGalaxy eLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,6 +7,19 @@
 
 **Note:** While published as `@progalaxyelabs/ngx-stonescriptphp-client`, this is the official client for [StoneScriptPHP](https://stonescriptphp.org). Future versions will migrate to the `@stonescriptphp` namespace.
 
+## ✅ Authentication Support (v1.0.0+)
+
+**Fully compatible with StoneScriptPHP Framework v2.1.x authentication!**
+
+- ✅ **Cookie-based auth**: Secure httpOnly cookies + CSRF (StoneScriptPHP v2.1.x default)
+- ✅ **Body-based auth**: Legacy mode for custom backends
+- ✅ **Configurable**: Choose your auth strategy via environment config
+- ✅ **All HTTP methods**: GET, POST, PUT, PATCH, DELETE with automatic token refresh
+
+See [Configuration](#configuration) section below for setup details.
+
+📖 **Documentation**: [CHANGELOG](docs/CHANGELOG.md) | [Auth Compatibility](docs/AUTH_COMPATIBILITY.md)
+
 ---
 
 ## What is this?
@@ -27,7 +40,7 @@ This library provides the HTTP client that consumes those contracts, giving you
 - ✅ **RxJS observables** - Native Angular integration
 - ✅ **Error handling** - Consistent error responses
 - ✅ **Interceptors ready** - Add auth, logging, retry logic
-- ✅ **Angular 19+** - Modern Angular standalone components
+- ✅ **Angular 19+ & 20+** - Modern Angular standalone components
 
 ## Installation
 
@@ -105,6 +118,80 @@ PHP Backend (StoneScriptPHP)          Angular Frontend
 3. Import generated TypeScript interfaces in Angular
 4. Make type-safe HTTP calls
 
+## Configuration
+
+### Authentication Modes (v1.0.0+)
+
+Choose your authentication strategy based on your backend:
+
+#### Cookie-based Auth (Recommended - StoneScriptPHP v2.1.x)
+
+```typescript
+// environment.ts
+export const environment = {
+    production: false,
+    apiServer: {
+        host: 'http://localhost:8000/'
+    },
+    auth: {
+        mode: 'cookie',  // Default mode
+        refreshEndpoint: '/auth/refresh',  // Default endpoint
+        useCsrf: true,  // Default for cookie mode
+        refreshTokenCookieName: 'refresh_token',  // Default
+        csrfTokenCookieName: 'csrf_token',  // Default
+        csrfHeaderName: 'X-CSRF-Token'  // Default
+    }
+}
+```
+
+**Features:**
+- Secure httpOnly cookies prevent XSS attacks
+- CSRF token protection
+- Token rotation on refresh
+- Works with StoneScriptPHP `AuthRoutes::register($router)`
+
+#### Body-based Auth (Legacy/Custom Backends)
+
+```typescript
+// environment.ts
+export const environment = {
+    production: false,
+    apiServer: {
+        host: 'http://localhost:8000/'
+    },
+    auth: {
+        mode: 'body',
+        refreshEndpoint: '/user/refresh_access',
+        useCsrf: false
+    }
+}
+```
+
+**Use when:**
+- Your backend accepts tokens in request body
+- Custom authentication implementation
+- Migrating from older systems
+
+#### Manual Auth (No Auto-Refresh)
+
+```typescript
+// environment.ts
+export const environment = {
+    production: false,
+    apiServer: {
+        host: 'http://localhost:8000/'
+    },
+    auth: {
+        mode: 'none'
+    }
+}
+```
+
+**Use when:**
+- You handle token refresh manually
+- No authentication needed
+- Custom auth logic
+
 ## Advanced Usage
 
 ### With Interceptors
@@ -151,7 +238,7 @@ StoneScriptPHP responses follow this structure:
 
 ## Requirements
 
-- Angular >= 19.0.0
+- Angular >= 19.0.0 or 20.0.0
 - RxJS >= 7.8.0
 - TypeScript >= 5.8.0
 

package/dist/ngx-stonescriptphp-client/README.md

@@ -0,0 +1,186 @@
+# ngx-stonescriptphp-client
+
+> Official Angular client library for StoneScriptPHP backend framework
+
+[![npm version](https://badge.fury.io/js/%40progalaxyelabs%2Fngx-stonescriptphp-client.svg)](https://www.npmjs.com/package/@progalaxyelabs/ngx-stonescriptphp-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Note:** While published as `@progalaxyelabs/ngx-stonescriptphp-client`, this is the official client for [StoneScriptPHP](https://stonescriptphp.org). Future versions will migrate to the `@stonescriptphp` namespace.
+
+---
+
+## What is this?
+
+The Angular HTTP client library for **StoneScriptPHP** - a modern PHP backend framework that auto-generates TypeScript clients from your backend DTOs and contracts.
+
+When you build APIs with StoneScriptPHP, you define:
+- Request DTOs (TypeScript interfaces)
+- Response DTOs (TypeScript interfaces)
+- Route contracts (interfaces)
+
+This library provides the HTTP client that consumes those contracts, giving you **100% type-safe** API calls with zero manual typing.
+
+## Features
+
+- ✅ **Type-safe HTTP calls** - Full TypeScript support from backend DTOs
+- ✅ **Auto-generated clients** - StoneScriptPHP generates TypeScript from PHP
+- ✅ **RxJS observables** - Native Angular integration
+- ✅ **Error handling** - Consistent error responses
+- ✅ **Interceptors ready** - Add auth, logging, retry logic
+- ✅ **Angular 19+** - Modern Angular standalone components
+
+## Installation
+
+```bash
+npm install @progalaxyelabs/ngx-stonescriptphp-client
+```
+
+## Quick Start
+
+### 1. Generate TypeScript Client from Backend
+
+In your StoneScriptPHP project:
+
+```bash
+php stone generate typescript-client
+```
+
+This generates TypeScript interfaces from your PHP DTOs.
+
+### 2. Use in Angular
+
+```typescript
+import { Component } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+
+// Auto-generated from StoneScriptPHP backend
+interface ProductRequest {
+  name: string;
+  price: number;
+}
+
+interface ProductResponse {
+  productId: number;
+  status: string;
+}
+
+@Component({
+  selector: 'app-products',
+  standalone: true,
+  template: `<button (click)="createProduct()">Create Product</button>`
+})
+export class ProductsComponent {
+  constructor(private http: HttpClient) {}
+
+  createProduct(): void {
+    const request: ProductRequest = {
+      name: 'Widget',
+      price: 99.99
+    };
+
+    this.http.post<ProductResponse>('http://localhost:9100/products', request)
+      .subscribe(response => {
+        console.log('Product created:', response.productId);
+      });
+  }
+}
+```
+
+## How it Works
+
+StoneScriptPHP follows a **contract-first** approach:
+
+```
+PHP Backend (StoneScriptPHP)          Angular Frontend
+┌─────────────────────────┐          ┌──────────────────────┐
+│ ProductRequest DTO      │  ──────> │ ProductRequest.ts    │
+│ ProductResponse DTO     │  ──────> │ ProductResponse.ts   │
+│ IProductRoute contract  │  ──────> │ Type-safe HTTP calls │
+└─────────────────────────┘          └──────────────────────┘
+```
+
+1. Define DTOs in PHP
+2. Run `php stone generate typescript-client`
+3. Import generated TypeScript interfaces in Angular
+4. Make type-safe HTTP calls
+
+## Advanced Usage
+
+### With Interceptors
+
+```typescript
+import { HttpInterceptor, HttpRequest, HttpHandler } from '@angular/common/http';
+
+export class AuthInterceptor implements HttpInterceptor {
+  intercept(req: HttpRequest<any>, next: HttpHandler) {
+    const authReq = req.clone({
+      headers: req.headers.set('Authorization', 'Bearer ' + getToken())
+    });
+    return next.handle(authReq);
+  }
+}
+```
+
+### With Error Handling
+
+```typescript
+this.http.post<ProductResponse>('/products', request)
+  .pipe(
+    catchError(error => {
+      console.error('API Error:', error);
+      return throwError(() => error);
+    })
+  )
+  .subscribe(response => {
+    // Handle success
+  });
+```
+
+## API Response Format
+
+StoneScriptPHP responses follow this structure:
+
+```typescript
+{
+  "status": "ok" | "error",
+  "message": "Success message",
+  "data": { /* Your DTO */ }
+}
+```
+
+## Requirements
+
+- Angular >= 19.0.0
+- RxJS >= 7.8.0
+- TypeScript >= 5.8.0
+
+## Documentation
+
+- **Framework Docs:** [stonescriptphp.org](https://stonescriptphp.org)
+- **Getting Started:** [stonescriptphp.org/docs/getting-started](https://stonescriptphp.org/docs/getting-started)
+- **TypeScript Client Guide:** [stonescriptphp.org/docs/typescript-client](https://stonescriptphp.org/docs/typescript-client)
+
+## Example Projects
+
+Check out the [StoneScriptPHP examples repository](https://github.com/progalaxyelabs/StoneScriptPHP/tree/main/examples) for full-stack example apps.
+
+## Contributing
+
+This is part of the StoneScriptPHP ecosystem. Contributions welcome!
+
+- Report issues: [GitHub Issues](https://github.com/progalaxyelabs/ngx-stonescriptphp-client/issues)
+- Framework repo: [StoneScriptPHP](https://github.com/progalaxyelabs/StoneScriptPHP)
+
+## License
+
+MIT
+
+## Related Projects
+
+- [StoneScriptPHP](https://github.com/progalaxyelabs/StoneScriptPHP) - The PHP backend framework
+- [sunbird-garden](https://github.com/progalaxyelabs/sunbird-garden) - Reference implementation
+
+---
+
+**Made with ❤️ by the StoneScriptPHP team**

package/{fesm2022 → dist/ngx-stonescriptphp-client/fesm2022}/progalaxyelabs-ngx-stonescriptphp-client.mjs

@@ -98,15 +98,15 @@ class TokenService {
         localStorage.removeItem(this.lsAccessTokenKey);
         localStorage.removeItem(this.lsRefreshTokenKey);
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: TokenService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: TokenService, providedIn: 'root' }); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TokenService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TokenService, providedIn: 'root' }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: TokenService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TokenService, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root'
                 }]
-        }], ctorParameters: function () { return []; } });
+        }], ctorParameters: () => [] });
 
 class SigninStatusService {
     constructor() {
@@ -118,15 +118,15 @@ class SigninStatusService {
     signedIn() {
         this.status.next(true);
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: SigninStatusService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: SigninStatusService, providedIn: 'root' }); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: SigninStatusService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: SigninStatusService, providedIn: 'root' }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: SigninStatusService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: SigninStatusService, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root'
                 }]
-        }], ctorParameters: function () { return []; } });
+        }], ctorParameters: () => [] });
 
 class MyEnvironmentModel {
     constructor() {
@@ -193,10 +193,10 @@ class CsrfService {
         // Can only clear non-httpOnly cookies
         document.cookie = `${cookieName}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;`;
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: CsrfService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: CsrfService, providedIn: 'root' }); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: CsrfService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: CsrfService, providedIn: 'root' }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: CsrfService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: CsrfService, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root'
@@ -396,7 +396,7 @@ class ApiConnectionService {
             let refreshTokenResponse = await fetch(refreshTokenUrl, {
                 method: 'POST',
                 mode: 'cors',
-                credentials: 'include',
+                credentials: 'include', // Important: send cookies
                 redirect: 'error',
                 headers: headers
             });
@@ -490,39 +490,39 @@ class ApiConnectionService {
         }
         return '';
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: ApiConnectionService, deps: [{ token: TokenService }, { token: SigninStatusService }, { token: MyEnvironmentModel }, { token: CsrfService }], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: ApiConnectionService, providedIn: 'root' }); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: ApiConnectionService, deps: [{ token: TokenService }, { token: SigninStatusService }, { token: MyEnvironmentModel }, { token: CsrfService }], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: ApiConnectionService, providedIn: 'root' }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: ApiConnectionService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: ApiConnectionService, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root'
                 }]
-        }], ctorParameters: function () { return [{ type: TokenService }, { type: SigninStatusService }, { type: MyEnvironmentModel }, { type: CsrfService }]; } });
+        }], ctorParameters: () => [{ type: TokenService }, { type: SigninStatusService }, { type: MyEnvironmentModel }, { type: CsrfService }] });
 
 class AuthService {
     constructor() { }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: AuthService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: AuthService, providedIn: 'root' }); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: AuthService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: AuthService, providedIn: 'root' }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: AuthService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: AuthService, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root'
                 }]
-        }], ctorParameters: function () { return []; } });
+        }], ctorParameters: () => [] });
 
 class DbService {
     constructor() { }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: DbService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: DbService, providedIn: 'root' }); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: DbService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: DbService, providedIn: 'root' }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: DbService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: DbService, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root'
                 }]
-        }], ctorParameters: function () { return []; } });
+        }], ctorParameters: () => [] });
 
 class NgxStoneScriptPhpClientModule {
     static forRoot(environment) {
@@ -533,11 +533,11 @@ class NgxStoneScriptPhpClientModule {
             ]
         };
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: NgxStoneScriptPhpClientModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule }); }
-    static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "16.2.12", ngImport: i0, type: NgxStoneScriptPhpClientModule, imports: [CommonModule] }); }
-    static { this.ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: NgxStoneScriptPhpClientModule, imports: [CommonModule] }); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: NgxStoneScriptPhpClientModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule }); }
+    static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "20.3.15", ngImport: i0, type: NgxStoneScriptPhpClientModule, imports: [CommonModule] }); }
+    static { this.ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: NgxStoneScriptPhpClientModule, imports: [CommonModule] }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImport: i0, type: NgxStoneScriptPhpClientModule, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: NgxStoneScriptPhpClientModule, decorators: [{
             type: NgModule,
             args: [{
                     declarations: [],