Client Ecosystem & Integration

Client Integration (coby-jack)

While mouse-php accepts standard mRPC JSON packets over any HTTP or WebSocket transport, the recommended client-side driver is coby-jack.

coby-jack coordinates request formatting, Web Crypto HMAC-SHA256 signing via mrpc-js, short-lived session token rotation, and automatic 419 state recovery out of the box.

Quick Setup

Install coby-jack alongside its mRPC encoding peer:

npm install coby-jack

Configure coby-jack at your application entry point to point directly to your mouse-php backend routes:

import { configure, send_request } from 'coby-jack';

configure({
    base_url: 'http://127.0.0.1:9000',
    version: '1.0.0',
    api_secret: 'your_shared_api_secret',
    refresh_endpoint: '/api/auth/refresh',
    reload_endpoint: '/api/auth/handshake',
    storage_type: 'session',
    keep_logged_in: true,
    on_token_change: (newToken) => {
        // Synchronize token state with your frontend auth store
    },
    on_logout: () => {
        // Handle session termination / UI redirect
    }
});

Dispatching Requests to mouse-php Controllers

mouse-php routes handle payload-driven mRPC requests dispatched via send_request. Set the third parameter to true for routes protected by mouse-php auth guards:

// Public Endpoint -> mouse-php guest controller
const publicRes = await send_request('/api/products/list', { category: 'tools' }, false);

// Authenticated Endpoint -> mouse-php Guard Pipe validation
const userRes = await send_request('/api/user/profile', { accountId: 108 }, true);

if (userRes.status === 'success') {
console.log('Profile Data:', userRes.data);
}

How mouse-php & coby-jack Communicate

1. Guard Pipe Verification: When coby-jack dispatches a secure request, mouse-php intercepts the envelope at its Guard Pipe, verifying the HMAC signature (data + seed + secret) before controller execution.

2. Action Directives: If a session requires token rotation or re-authentication, mouse-php responds with an action flag inside the mRPC response envelope (e.g., refresh_token).

3. Self-Healing Interception: coby-jack reads the action directive, rotates the session token seamlessly in module memory, and notifies your frontend through the on_token_change hook without breaking execution flow.