@progalaxyelabs/ngx-stonescriptphp-client 0.0.10 → 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**