ngx-stonescriptphp-client

Official Angular client library for StoneScriptPHP backend framework

Note: While published as @progalaxyelabs/ngx-stonescriptphp-client, this is the official client for StoneScriptPHP. Future versions will migrate to the @stonescriptphp namespace.

✅ Authentication Support (v2.0.0+)

Current Version: 1.8.1

Recent Updates

• v1.8.1: Renamed authServer to accountsServer for naming consistency
• v1.8.0: Added accountsServer property for microservices architecture
• v1.7.1: Fixed URL concatenation (removed trailing slash requirement)

Fully compatible with StoneScriptPHP Framework v2.1.x authentication!

HTTP Client 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

Multi-Auth Server Support (NEW)

• ✅ Multiple identity providers: Authenticate against different auth servers (customer auth vs employee auth)
• ✅ Runtime server switching: Switch between auth servers dynamically
• ✅ Per-request server selection: Specify server for individual auth calls
• ✅ Backward compatible: Single-server config still works
• ✅ Use case: Shared admin platforms that accept both customer and employee logins

// Multi-server configuration
authServers: {
  customer: { url: 'https://auth.progalaxyelabs.com', default: true },
  employee: { url: 'https://admin-auth.progalaxyelabs.com' }
}

See MULTI-AUTH-SERVER.md for complete documentation.

Full-Page Authentication UI (NEW in v1.4.0)

• ✅ AuthPageComponent: Embeddable full-page auth with custom branding
• ✅ Customizable Branding: Logo, colors, gradients, app name, subtitle
• ✅ Login/Register Toggle: Seamless switching between modes
• ✅ Styled Card Layout: Professional gradient background with centered card
• ✅ Zero Configuration: Works out-of-the-box with sensible defaults

// Quick Example: Branded auth page
<lib-auth-page
  [providers]="['google', 'emailPassword']"
  (authenticated)="onAuth($event)">
</lib-auth-page>

Modal-Based User Authentication (v2.0.0)

• ✅ 6 Auth Providers: Google, LinkedIn, Apple, Microsoft, GitHub, Email/Password
• ✅ Declarative Configuration: Enable/disable providers via environment
• ✅ Popup OAuth: Social login via popup windows (no full-page redirects)
• ✅ Fetch API: Promise-based authentication (minimal RxJS)
• ✅ Observable User State: Reactive user$ for UI updates

// Quick Example: Configure auth providers
authProviders: {
  google: { label: 'Sign in with Google', enabled: true },
  linkedin: { label: 'Sign in with LinkedIn', enabled: true },
  emailPassword: { label: 'Email', enabled: true }
}

See Configuration and AUTH-PROVIDER-CONFIG.md for details.

📖 Documentation: CHANGELOG | Auth Compatibility | Provider Config | Modal Auth Spec | Multi-Auth Server

---

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+ & 20+ - Modern Angular standalone components

Installation

npm install @progalaxyelabs/ngx-stonescriptphp-client

Quick Start

1. Generate TypeScript Client from Backend

In your StoneScriptPHP project:

php stone generate typescript-client

This generates TypeScript interfaces from your PHP DTOs.

2. Use in Angular

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

Configuration

Server Configuration (v1.7.1+)

Important: As of v1.7.1, host URLs should NOT include trailing slashes. Endpoints should include leading slashes.

// app.config.ts
NgxStoneScriptPhpClientModule.forRoot({
  // ✅ Correct: No trailing slash
  apiServer: { host: 'http://localhost:3011' },

  // ❌ Wrong: Has trailing slash
  // apiServer: { host: 'http://localhost:3011/' },
})

For Microservices: If your authentication is on a different server than your API, use accountsServer (v1.8.1+):

NgxStoneScriptPhpClientModule.forRoot({
  apiServer: { host: 'http://localhost:3011' },      // Business API
  accountsServer: { host: 'http://localhost:3139' }, // Auth service
  auth: {
    mode: 'body',
    refreshEndpoint: '/api/auth/refresh'  // Just the path, no server URL
  }
})

Fallback chain for auth server:

1. accountsServer.host (if specified)
2. accountsUrl (deprecated, for backward compatibility)
3. apiServer.host (same-server auth)

Branding Configuration (v1.4.0+)

Customize your authentication pages with your brand identity:

// app.config.ts or environment.ts
import { NgxStoneScriptPhpClientModule, MyEnvironmentModel } from '@progalaxyelabs/ngx-stonescriptphp-client';

export const appConfig: ApplicationConfig = {
  providers: [
    NgxStoneScriptPhpClientModule.forRoot({
      apiServer: {
        host: 'http://localhost:9100'  // No trailing slash
      },
      branding: {
        appName: 'My Platform',           // Required: App name on auth pages
        logo: '/assets/logo.png',         // Optional: Logo URL
        primaryColor: '#667eea',          // Optional: Auto-generates gradient
        gradientStart: '#667eea',         // Optional: Custom gradient start
        gradientEnd: '#764ba2',           // Optional: Custom gradient end
        subtitle: 'Secure authentication' // Optional: Subtitle text
      }
    } as MyEnvironmentModel)
  ]
};

Using the AuthPageComponent:

import { Component } from '@angular/core';
import { AuthPageComponent, TenantSelectedEvent } from '@progalaxyelabs/ngx-stonescriptphp-client';

@Component({
  selector: 'app-login',
  standalone: true,
  imports: [AuthPageComponent],
  template: `
    <lib-auth-page
      [providers]="['google', 'linkedin', 'emailPassword']"
      (authenticated)="onAuthenticated($event)">
    </lib-auth-page>
  `
})
export class LoginComponent {
  onAuthenticated(event: TenantSelectedEvent) {
    console.log('User authenticated:', event);
    // Navigate to dashboard, etc.
  }
}

Branding Options:

Option	Type	Description
appName	string	Required. Application name displayed on auth pages
logo	string	Optional. URL to logo image (max 200x80px recommended)
primaryColor	string	Optional. Primary brand color (hex). Auto-generates gradient if no gradient colors provided
gradientStart	string	Optional. Gradient start color (hex). Overrides primaryColor
gradientEnd	string	Optional. Gradient end color (hex). Required if gradientStart is set
subtitle	string	Optional. Subtitle text below app name

Default Styling:

• Gradient: linear-gradient(135deg, #667eea 0%, #764ba2 100%)
• White card with rounded corners and shadow
• Responsive design (mobile-friendly)

---

Authentication Modes (v1.0.0+)

Choose your authentication strategy based on your backend:

Cookie-based Auth (Recommended - StoneScriptPHP v2.1.x)

// 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)

// 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)

// 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

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

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:

{
  "status": "ok" | "error",
  "message": "Success message",
  "data": { /* Your DTO */ }
}

Requirements

• Angular >= 19.0.0 or 20.0.0
• RxJS >= 7.8.0
• TypeScript >= 5.8.0

Documentation

• Framework Docs: stonescriptphp.org
• Getting Started: stonescriptphp.org/docs/getting-started
• TypeScript Client Guide: stonescriptphp.org/docs/typescript-client

Example Projects

Check out the StoneScriptPHP examples repository for full-stack example apps.

Contributing

This is part of the StoneScriptPHP ecosystem. Contributions welcome!

• Report issues: GitHub Issues
• Framework repo: StoneScriptPHP

License

MIT

Related Projects

• StoneScriptPHP - The PHP backend framework
• sunbird-garden - Reference implementation

---

Made with ❤️ by the StoneScriptPHP team