StoneScriptPHP TypeScript Client

A framework-agnostic TypeScript HTTP client for StoneScriptPHP backend applications. Works seamlessly with React, Vue, Angular, vanilla JavaScript, and any other frontend framework.

Features

• Framework Agnostic: Works with any JavaScript framework or vanilla JS
• Multiple Authentication Modes: Cookie-based and body-based authentication
• Automatic Token Refresh: Built-in JWT token refresh with retry logic
• CSRF Protection: Configurable CSRF token handling for cookie-based auth
• TypeScript Support: Full TypeScript definitions included
• Error Handling: Comprehensive error classes for different scenarios
• Flexible Storage: Browser localStorage, sessionStorage, or memory storage
• Type-Safe API: Generic type support for request/response data

Installation

npm install @progalaxyelabs/stonescriptphp-ts-client

or

yarn add @progalaxyelabs/stonescriptphp-ts-client

or

pnpm add @progalaxyelabs/stonescriptphp-ts-client

Quick Start

Basic Usage

import { StoneScriptClient } from '@progalaxyelabs/stonescriptphp-ts-client';

// Initialize the client
const client = new StoneScriptClient({
  baseUrl: 'https://api.example.com',
  auth: {
    mode: 'cookie', // or 'body' or 'none'
    refreshEndpoint: '/auth/refresh',
    useCsrf: true
  }
});

// Make API requests
async function fetchUsers() {
  try {
    const users = await client.get<User[]>('/users');
    console.log(users);
  } catch (error) {
    console.error('Failed to fetch users:', error);
  }
}

Authentication

Login

// Login with credentials
await client.login('/auth/login', {
  email: '[email protected]',
  password: 'password123'
});

// Check authentication status
if (client.isAuthenticated()) {
  console.log('User is authenticated');
}

Logout

// Logout and optionally call logout endpoint
await client.logout('/auth/logout');

Auth State Monitoring

// Subscribe to authentication state changes
const unsubscribe = client.onAuthChange((isAuthenticated) => {
  console.log('Auth state changed:', isAuthenticated);
});

// Clean up when needed
unsubscribe();

Configuration

Client Configuration

interface ClientConfig {
  baseUrl: string;                          // API base URL (required)
  auth?: AuthConfig;                        // Authentication configuration
  timeout?: number;                         // Request timeout in ms (default: 30000)
  defaultHeaders?: Record<string, string>;  // Default headers for all requests
  debug?: boolean;                          // Enable debug logging (default: false)
}

Authentication Configuration

interface AuthConfig {
  mode: 'cookie' | 'body' | 'none';        // Authentication mode (required)
  refreshEndpoint?: string;                 // Token refresh endpoint (default: '/auth/refresh')
  useCsrf?: boolean;                        // Enable CSRF protection (default: true for cookie mode)
  refreshTokenCookieName?: string;          // Refresh token cookie name (default: 'refresh_token')
  csrfTokenCookieName?: string;             // CSRF token cookie name (default: 'csrf_token')
  csrfHeaderName?: string;                  // CSRF header name (default: 'X-CSRF-Token')
}

Authentication Modes

Cookie-Based Authentication (Recommended for web apps)

Best for web applications where you want the browser to handle cookie storage automatically.

const client = new StoneScriptClient({
  baseUrl: 'https://api.example.com',
  auth: {
    mode: 'cookie',
    refreshEndpoint: '/auth/refresh',
    useCsrf: true,
    csrfTokenCookieName: 'csrf_token',
    csrfHeaderName: 'X-CSRF-Token'
  }
});

Features:

• Access token stored in localStorage/sessionStorage
• Refresh token stored in HTTP-only cookie
• Automatic CSRF token handling
• Credentials automatically included in requests

Body-Based Authentication

Best for mobile apps or when you need full control over token storage.

const client = new StoneScriptClient({
  baseUrl: 'https://api.example.com',
  auth: {
    mode: 'body',
    refreshEndpoint: '/auth/refresh'
  }
});

Features:

• Both access and refresh tokens stored in localStorage/sessionStorage
• Tokens sent in request body for refresh
• No cookie dependencies

No Authentication

For public APIs or when authentication is handled externally.

const client = new StoneScriptClient({
  baseUrl: 'https://api.example.com',
  auth: {
    mode: 'none'
  }
});

API Methods

HTTP Methods

All methods support generic typing for type-safe responses:

// GET request
const users = await client.get<User[]>('/users');

// POST request
const newUser = await client.post<User>('/users', {
  name: 'John Doe',
  email: '[email protected]'
});

// PUT request
const updatedUser = await client.put<User>('/users/123', {
  name: 'Jane Doe'
});

// PATCH request
const patchedUser = await client.patch<User>('/users/123', {
  email: '[email protected]'
});

// DELETE request
await client.delete('/users/123');

Request Options

All HTTP methods accept optional request options:

interface RequestOptions {
  params?: Record<string, any>;             // Query parameters
  headers?: Record<string, string>;         // Additional headers
  timeout?: number;                         // Override default timeout
  skipAuth?: boolean;                       // Skip authentication for this request
  skipRefresh?: boolean;                    // Skip token refresh on 401
  credentials?: RequestCredentials;         // Fetch credentials option
}

Example:

// GET with query parameters and custom headers
const users = await client.get<User[]>('/users', {
  params: { page: 1, limit: 10 },
  headers: { 'X-Custom-Header': 'value' }
});

// POST without authentication
const data = await client.post('/public/newsletter',
  { email: '[email protected]' },
  { skipAuth: true }
);

Error Handling

The client provides specific error classes for different scenarios:

import {
  ApiError,
  AuthError,
  ValidationError,
  NetworkError
} from '@progalaxyelabs/stonescriptphp-ts-client';

try {
  const user = await client.get<User>('/users/123');
} catch (error) {
  if (error instanceof AuthError) {
    console.error('Authentication failed:', error.message);
    // Redirect to login
  } else if (error instanceof ValidationError) {
    console.error('Validation errors:', error.errors);
    // Display field-specific errors
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
    // Show offline message
  } else if (error instanceof ApiError) {
    console.error('API error:', error.message, error.statusCode);
    // Handle general API errors
  }
}

Error Types

• ApiError: General API errors with status code
• AuthError: Authentication/authorization failures (401, 403)
• ValidationError: Validation failures (422) with field-specific errors
• NetworkError: Network connectivity issues

Storage Options

By default, the client uses browser localStorage for token storage. You can customize this:

import { BrowserStorage, MemoryStorage } from '@progalaxyelabs/stonescriptphp-ts-client';

// Use sessionStorage instead of localStorage
const sessionStore = new BrowserStorage('session');

// Use in-memory storage (tokens lost on page refresh)
const memoryStore = new MemoryStorage();

// Custom storage implementation
class CustomStorage implements TokenStorage {
  getItem(key: string): string | null {
    // Your implementation
  }
  setItem(key: string, value: string): void {
    // Your implementation
  }
  removeItem(key: string): void {
    // Your implementation
  }
}

Framework Examples

React

import { StoneScriptClient } from '@progalaxyelabs/stonescriptphp-ts-client';
import { useEffect, useState } from 'react';

const client = new StoneScriptClient({
  baseUrl: 'https://api.example.com',
  auth: { mode: 'cookie' }
});

function App() {
  const [isAuthenticated, setIsAuthenticated] = useState(client.isAuthenticated());

  useEffect(() => {
    const unsubscribe = client.onAuthChange(setIsAuthenticated);
    return unsubscribe;
  }, []);

  const handleLogin = async () => {
    await client.login('/auth/login', { email, password });
  };

  return <div>{isAuthenticated ? 'Logged in' : 'Logged out'}</div>;
}

Vue 3

import { StoneScriptClient } from '@progalaxyelabs/stonescriptphp-ts-client';
import { ref, onMounted, onUnmounted } from 'vue';

const client = new StoneScriptClient({
  baseUrl: 'https://api.example.com',
  auth: { mode: 'cookie' }
});

export default {
  setup() {
    const isAuthenticated = ref(client.isAuthenticated());
    let unsubscribe: (() => void) | null = null;

    onMounted(() => {
      unsubscribe = client.onAuthChange((auth) => {
        isAuthenticated.value = auth;
      });
    });

    onUnmounted(() => {
      unsubscribe?.();
    });

    const login = async (email: string, password: string) => {
      await client.login('/auth/login', { email, password });
    };

    return { isAuthenticated, login };
  }
};

Vanilla JavaScript

import { StoneScriptClient } from '@progalaxyelabs/stonescriptphp-ts-client';

const client = new StoneScriptClient({
  baseUrl: 'https://api.example.com',
  auth: { mode: 'cookie' }
});

// Login
document.getElementById('loginBtn').addEventListener('click', async () => {
  const email = document.getElementById('email').value;
  const password = document.getElementById('password').value;

  try {
    await client.login('/auth/login', { email, password });
    console.log('Login successful');
  } catch (error) {
    console.error('Login failed:', error);
  }
});

// Fetch data
async function loadUsers() {
  try {
    const users = await client.get('/users');
    // Render users
  } catch (error) {
    console.error('Failed to load users:', error);
  }
}

Advanced Usage

Custom Headers

const client = new StoneScriptClient({
  baseUrl: 'https://api.example.com',
  defaultHeaders: {
    'X-API-Version': '1.0',
    'X-Client-App': 'MyApp'
  }
});

Request Timeout

// Global timeout
const client = new StoneScriptClient({
  baseUrl: 'https://api.example.com',
  timeout: 10000 // 10 seconds
});

// Per-request timeout
await client.get('/users', { timeout: 5000 });

Manual Token Management

// Get current access token
const token = client.getAccessToken();

// Check if user is authenticated
if (client.isAuthenticated()) {
  // Make authenticated requests
}

API Response Format

The client expects StoneScriptPHP-compatible API responses:

interface ApiResponse<T> {
  status: 'ok' | 'error';
  message?: string;
  data?: T;
  errors?: Record<string, string[]>;
}

Success response:

{
  "status": "ok",
  "data": { "id": 1, "name": "John" }
}

Error response:

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "email": ["Email is required"],
    "password": ["Password must be at least 8 characters"]
  }
}

Building and Development

# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Development mode with watch
npm run dev

# Lint code
npm run lint

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Requires ES2015+ environment with Fetch API support.

TypeScript

This library is written in TypeScript and includes type definitions. No additional @types packages needed.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub Issues page.

Author

Progalaxy E-Labs

Related Projects

• StoneScriptPHP - The backend framework this client is designed for