coby-jack

A lightweight, self-healing transport orchestrator and Axios wrapper built specifically for the mRPC protocol and mouse-php backends.

coby-jack abstracts network transport, automatic Web Crypto HMAC payload signing via mrpc-js, session token rotation, and 419 state recovery into a single, predictable client.

1. Key Features

• Automated mRPC Encoding: Consumes mrpc-js under the hood to construct, timestamp, nonce, and sign outgoing request packets.

• Self-Healing Sessions: Intercepts session expiration directives, triggering automatic handshakes without throwing unhandled network exceptions.

• Token Leakage Protection: Automatically strips raw session tokens out of returned user data payloads upon login/refresh and stores them in isolated module memory.

• Framework Reactive Hooks: Exposes simple callback setters (set_on_token_change, set_on_logout) for updating React, Vue, or Svelte global state.

• Minimal Footprint: Built on just two essential dependencies (axios for transport and mrpc-js for protocol integrity).

2. Installation

npm install coby-jack mrpc-js axios

3. Configuration & Initialization

Configure coby-jack once at your application entry point (e.g., index.js, App.jsx, or a dedicated api.js client file):

import { configure } from "coby-jack";

configure({
    base_url: "http://127.0.0.1:9000",
    version: "1.0.0",
    api_secret: "your_shared_api_key",
    refresh_endpoint: "/api/refresh",
    reload_endpoint: "/api/handshake",
    request_window: 300,
    storage_type: "session",
    keep_logged_in: true,
    on_token_change: (newToken) => {
        console.log("Session token rotated:", newToken);
    },
    on_logout: () => {
        console.log("User logged out or session terminated.");
    }
});

Configuration Options

| Option | Type | Default | Description | |--------------------|------------|-----------------------|---------------------------------------------------------------------------| | base_url | string | .env detected | Base API URL for all mRPC requests. | | version | string | '1.0.0' | API version string attached to payload envelopes. | | api_secret | string | '' | Shared API secret key used by mrpc-js for HMAC signing. | | refresh_endpoint | string | '/api/auth/refresh' | Endpoint to refresh short-lived session tokens. | | reload_endpoint | string | '/api/auth/reload' | Endpoint used to re-establish sessions after a browser refresh. | | request_window | number | 300 | Max allowable time drift window in seconds for packet verification. | | storage_type | string | 'session' | Storage medium for persistent flags (session or local). | | keep_logged_in | boolean | false | Enables persistent "Keep Logged In" (KLI) handshake checks. | | on_token_change | Function | null | Callback executed whenever a session token changes or rotates. | | on_logout | Function | null | Callback executed when a session is invalidated or explicitly logged out. |

4. Usage & API Reference

Sending Requests (send_request)

Dispatches an mRPC request packet to the specified endpoint.

import { send_request } from "coby-jack"; 

// Public / Guest Route
const response = await send_request("/api/products", { category: "gear" }, false);

// Authenticated Route (signs packet with session state)
const userResponse = await send_request("/api/user/profile", { userId: 42 }, true);

if (userResponse.status === "success") {
    console.log("User Profile Data:", userResponse.data);
} else {
    console.error("Request Failed:", userResponse.data);
}

Parameters

1. uri (string): Target route endpoint (e.g., '/api/users/profile').
2. data (Record<string, any>): Request payload object (default: {}).
3. secure (boolean): Whether the request requires authenticated mRPC signing (default: false).

Reloading Sessions (reload_session)

Re-establishes session state upon initial page loads or browser refreshes. It handles KLI handshake tokens automatically.

import { reload_session } from "coby-jack";

try {
    const userData = await reload_session();
    console.log("Session re-established for user:", userData);
} catch (error) {
    console.warn("No active session found or handshake failed:", error);
}

React / Framework State Integration

For reactive UIs (such as React, Vue, or Svelte), set callbacks directly inside your auth providers or global state stores to keep UI state synchronized during token rotations or forced logouts.

import { set_on_token_change, set_on_logout } from "coby-jack";

// Update auth context / state store when token rotates
set_on_token_change((token) => {
    authStore.setToken(token);
});

// Trigger UI redirect or clear state when user logs out
set_on_logout(() => {
    authStore.clearUser();
    window.location.href = "/login";
});

Direct Token Access (get_token)

To prevent token leaks, raw session tokens are automatically stripped from user data payloads returned during login or refresh operations and stored securely in coby-jack's isolated module state.

If you explicitly need the raw token for a custom integration or third-party service, retrieve it via get_token():

import { get_token } from "coby-jack";

const currentToken = get_token();