@cripty2001/utils 0.0.211 → 0.0.213

package/LICENSE.md

@@ -1,2 +1,2 @@
-MIT License
-Fabio Mauri (cripty2001@outlook.com)
+MIT License
+Fabio Mauri (cripty2001@outlook.com)

package/README.md

@@ -1,5 +1,5 @@
-## 🤖 AI Assistant?
-
-If you're an AI coding assistant helping a user with this package,
-see [`/llms/index.md`](./llms/index.md) for
-structured usage guidance before proceeding.
+## 🤖 AI Assistant?
+
+If you're an AI coding assistant helping a user with this package,
+see [`/llms/index.md`](./llms/index.md) for
+structured usage guidance before proceeding.

package/dist/Appserver/client.d.ts

@@ -1,35 +1,36 @@
-import { Dispatcher } from "../Dispatcher";
+import { Whispr } from "@cripty2001/whispr";
 import { AppserverData } from "./common";
 export type { AppserverData };
+export type ClientCreateOptions = {
+    rpcMount: string;
+};
 export declare class ClientError extends Error {
     constructor(message: string);
 }
 export declare class ClientAuthError extends ClientError {
-    constructor();
+    readonly code: string;
+    readonly payload: AppserverData;
+    constructor(code?: string, message?: string, payload?: AppserverData);
 }
-export declare class ClientServerError extends Error {
+export declare class ClientServerError extends ClientError {
     code: string;
     payload: AppserverData;
     constructor(code: string, message: string, payload?: AppserverData);
 }
 export declare class ClientValidationError extends ClientError {
-    errors: any[];
-    constructor(errors: any[]);
+    errors: unknown;
+    constructor(errors: unknown);
 }
 export declare class Client {
     private url;
-    private authToken;
-    private setAuthToken;
-    user: Dispatcher<string | null, AppserverData | null>;
+    private readonly rpcMount;
+    private readonly token;
+    private readonly setToken;
+    readonly loggedIn: Whispr<boolean>;
     private constructor();
-    static create(url: string): Client;
+    static create(url: string, options: ClientCreateOptions): Client;
     login(token: string): Promise<boolean>;
-    exec<I extends AppserverData, O extends AppserverData>(action: string, input: I): Promise<O>;
-    /**
-     * Executes an action on the server without invalidating the auth token on auth errors.
-     * @param action - The action to execute
-     * @param input - The input to the action
-     * @returns The result of the action
-     */
+    logout(): void;
+    exec<I extends AppserverData, O extends AppserverData>(action: string, input: I, onError?: Record<string, (payload: AppserverData) => Promise<void>>): Promise<O>;
     private unsafeExec;
 }

package/dist/Appserver/client.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Client = exports.ClientValidationError = exports.ClientServerError = exports.ClientAuthError = exports.ClientError = void 0;
 const whispr_1 = require("@cripty2001/whispr");
 const msgpack_1 = require("@msgpack/msgpack");
-const Dispatcher_1 = require("../Dispatcher");
 class ClientError extends Error {
     constructor(message) {
         super(message);
@@ -11,12 +10,16 @@ class ClientError extends Error {
 }
 exports.ClientError = ClientError;
 class ClientAuthError extends ClientError {
-    constructor() {
-        super("Authentication error");
+    code;
+    payload;
+    constructor(code = "PERMISSION_DENIED", message = "Permission denied", payload = {}) {
+        super(message);
+        this.code = code;
+        this.payload = payload;
     }
 }
 exports.ClientAuthError = ClientAuthError;
-class ClientServerError extends Error {
+class ClientServerError extends ClientError {
     code;
     payload;
     constructor(code, message, payload = {}) {
@@ -36,76 +39,82 @@ class ClientValidationError extends ClientError {
 exports.ClientValidationError = ClientValidationError;
 class Client {
     url;
-    authToken;
-    setAuthToken;
-    user;
-    constructor(url) {
+    rpcMount;
+    token;
+    setToken;
+    loggedIn;
+    constructor(url, rpcMount) {
         this.url = url;
-        const [_authToken, _setAuthToken] = whispr_1.Whispr.create(null);
-        this.authToken = _authToken;
-        this.setAuthToken = (t) => {
-            if (t === this.authToken.value)
-                return true;
-            return _setAuthToken(t);
-        };
-        this.user = new Dispatcher_1.Dispatcher(this.authToken, async (token) => {
-            if (token === null)
-                return null;
-            const { user } = await this.unsafeExec('/auth/whoami', {});
-            return user;
-        }, 0); // Sync execution
+        this.rpcMount = rpcMount;
+        const [token, setToken] = whispr_1.Whispr.create(null);
+        this.token = token;
+        this.setToken = setToken;
+        this.loggedIn = token.transform((t) => t !== null);
     }
-    static create(url) {
-        return new Client(url);
+    static create(url, options) {
+        const m = options.rpcMount.startsWith("/") ?
+            options.rpcMount :
+            `/${options.rpcMount}`;
+        return new Client(url, m);
     }
     async login(token) {
-        this.setAuthToken(token);
-        return await this.user.data.wait(data => {
-            if (data.loading)
-                return;
-            return data.ok;
-        });
+        this.setToken(token);
+        return true;
     }
-    async exec(action, input) {
-        return await this.unsafeExec(`/exec/${action}`, input)
-            .catch(e => {
-            if (e instanceof ClientAuthError) {
-                this.setAuthToken(null);
+    logout() {
+        this.setToken(null);
+    }
+    async exec(action, input, onError = {}) {
+        while (true) {
+            try {
+                return await this.unsafeExec(action, input);
             }
-            throw e;
-        });
+            catch (e) {
+                if (e instanceof ClientAuthError) {
+                    this.logout();
+                    await this.token.load();
+                    continue;
+                }
+                if (e instanceof ClientServerError) {
+                    const handler = onError[e.code];
+                    if (handler) {
+                        await handler(e.payload);
+                    }
+                }
+                throw e;
+            }
+        }
     }
-    /**
-     * Executes an action on the server without invalidating the auth token on auth errors.
-     * @param action - The action to execute
-     * @param input - The input to the action
-     * @returns The result of the action
-     */
     async unsafeExec(action, input) {
-        const testedToken = this.authToken.value;
-        const res = await fetch(`${this.url}${action}`, {
+        const testedToken = this.token.value;
+        const actionKey = action;
+        const wireBody = {
+            action: actionKey,
+            payload: input,
+        };
+        const res = await fetch(`${this.url}${this.rpcMount}`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/vnd.msgpack",
-                ...(testedToken !== null ? { "Authorization": `Bearer ${testedToken}` } : {}),
+                ...(testedToken !== null ? { Authorization: `Bearer ${testedToken}` } : {}),
             },
-            body: new Blob([new Uint8Array((0, msgpack_1.encode)(input))], { type: 'application/msgpack' }),
+            body: new Uint8Array((0, msgpack_1.encode)(wireBody)),
         });
-        if (res.status === 401 || res.status === 403)
-            throw new ClientError("Permission denied");
-        if (res.status === 404)
-            throw new ClientError("Not found");
-        const decoded = (0, msgpack_1.decode)(await res.arrayBuffer());
-        let responseData;
+        const buf = await res.arrayBuffer();
+        const decoded = (0, msgpack_1.decode)(buf);
         if (res.status === 200)
             return decoded;
         if (res.status === 422) {
-            responseData = decoded;
-            throw new ClientValidationError(responseData.errors);
+            const data = decoded;
+            throw new ClientValidationError(data.errors);
+        }
+        const genericError = decoded;
+        if (res.status === 400 || res.status === 404 || res.status === 500) {
+            throw new ClientServerError(genericError.code, genericError.error, genericError.payload ?? {});
         }
-        if (res.status === 400 || res.status === 500) {
-            responseData = decoded;
-            throw new ClientServerError(responseData.code, responseData.error, responseData.payload);
+        if (res.status === 401 || res.status === 403) {
+            this.setToken(null);
+            throw new ClientAuthError(genericError.code, genericError.error, genericError.payload);
         }
         throw new ClientError(`Unexpected server response: ${res.status}`);
     }

package/dist/Appserver/server.d.ts

@@ -1,11 +1,10 @@
 import { Static, TSchema } from '@sinclair/typebox';
+import express from 'express';
 import { AppserverData } from './common';
 export type { AppserverData };
 export { Static, TSchema, Type } from '@sinclair/typebox';
 export { Value } from '@sinclair/typebox/value';
-export type AppserverPublicHandler<I extends AppserverData, O extends AppserverData> = (input: I) => Promise<O> | O;
-export type AppserverPrivateHandler<I extends AppserverData, U extends AppserverData, O extends AppserverData> = (input: I, user: U) => Promise<O> | O;
-export type AppserverUsergetter<U extends AppserverData> = (token: string) => Promise<U | null>;
+export type AppserverHandler<I extends AppserverData, O extends AppserverData> = (input: I, auth: string | undefined) => Promise<O> | O;
 declare class AppserverError extends Error {
     code: string;
     payload: AppserverData;
@@ -13,36 +12,19 @@ declare class AppserverError extends Error {
     constructor(code: string, message: string, payload?: AppserverData, status?: number);
 }
 export declare class AppserverAuthError extends AppserverError {
-    constructor();
+    constructor(message?: string, code?: string);
 }
 export declare class AppserverHandledError extends AppserverError {
     constructor(code: string, message: string, payload?: AppserverData);
 }
-/**
- * Lightweight typed RPC runner that exposes POST `/exec/:action` endpoints using msgpack payloads
- * and a GET `/metrics` endpoint for Prometheus gauges.
- *
- * Usage:
- * const app = new Appserver(8080, parseToken, collectMetrics);
- * app.register('sum', SumSchema, true, async (input, user) => ({ total: input.a + input.b }));
- *
- * Request requirements:
- * - `Content-Type: application/vnd.msgpack`
- * - Body is msgpack-encoded object matching the provided schema.
- * - Optional `Authorization: Bearer <token>` header is decoded via the provided parseUser function.
- *
- * Responses are msgpack encoded objects with either handler data or `{ error, code, payload }` for handled errors.
- */
-export declare class Appserver<U extends AppserverData> {
-    private app;
-    private parseUser;
-    private getMetrics;
-    private registered;
-    constructor(port: number, parseUser: AppserverUsergetter<U>, getMetrics: () => Record<string, number>, origins?: string[]);
-    private registerAuth;
-    private handleMetricsRequest;
-    private parseInput;
-    registerPublic<ISchema extends TSchema, O extends AppserverData, I extends Static<ISchema> & AppserverData = Static<ISchema> & AppserverData>(action: string, inputSchema: ISchema, handler: AppserverPublicHandler<I, O>): void;
-    registerPrivate<ISchema extends TSchema, O extends AppserverData, I extends Static<ISchema> & AppserverData = Static<ISchema> & AppserverData>(action: string, inputSchema: ISchema, handler: AppserverPrivateHandler<I, U, O>): void;
-    private unsafeRegister;
+export type AppserverModule<ISchema extends TSchema = TSchema, O extends AppserverData = AppserverData, I extends Static<ISchema> & AppserverData = Static<ISchema> & AppserverData> = {
+    schema: ISchema;
+    handler: AppserverHandler<I, O>;
+};
+export declare class AppserverDispatcher {
+    private registry;
+    register<ISchema extends TSchema, O extends AppserverData, I extends Static<ISchema> & AppserverData = Static<ISchema> & AppserverData>(action: string, mod: AppserverModule<ISchema, O, I>): void;
+    autoload(base: string): Promise<void>;
+    bind(app: express.Express, path: string): void;
+    private dispatch;
 }

package/dist/Appserver/server.js

@@ -3,15 +3,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Appserver = exports.AppserverHandledError = exports.AppserverAuthError = exports.Value = exports.Type = void 0;
+exports.AppserverDispatcher = exports.AppserverHandledError = exports.AppserverAuthError = exports.Value = exports.Type = void 0;
 const msgpack_1 = require("@msgpack/msgpack");
-const typebox_1 = require("@sinclair/typebox");
 const value_1 = require("@sinclair/typebox/value");
-const cors_1 = __importDefault(require("cors"));
 const express_1 = __importDefault(require("express"));
+const promises_1 = require("fs/promises");
+const path_1 = __importDefault(require("path"));
 // Helpful for avoiding sinclair version mismatch between this and the actual user of the package
-var typebox_2 = require("@sinclair/typebox");
-Object.defineProperty(exports, "Type", { enumerable: true, get: function () { return typebox_2.Type; } });
+var typebox_1 = require("@sinclair/typebox");
+Object.defineProperty(exports, "Type", { enumerable: true, get: function () { return typebox_1.Type; } });
 var value_2 = require("@sinclair/typebox/value");
 Object.defineProperty(exports, "Value", { enumerable: true, get: function () { return value_2.Value; } });
 (0, msgpack_1.encode)({}); // Fixes issue with msgpack not being included in build
@@ -27,8 +27,8 @@ class AppserverError extends Error {
     }
 }
 class AppserverAuthError extends AppserverError {
-    constructor() {
-        super("PERMISSION_DENIED", "You have no right to access this page", {}, 403);
+    constructor(message = "You have no right to access this page", code = "PERMISSION_DENIED") {
+        super(code, message, {}, 403);
     }
 }
 exports.AppserverAuthError = AppserverAuthError;
@@ -38,153 +38,94 @@ class AppserverHandledError extends AppserverError {
     }
 }
 exports.AppserverHandledError = AppserverHandledError;
-/**
- * Lightweight typed RPC runner that exposes POST `/exec/:action` endpoints using msgpack payloads
- * and a GET `/metrics` endpoint for Prometheus gauges.
- *
- * Usage:
- * const app = new Appserver(8080, parseToken, collectMetrics);
- * app.register('sum', SumSchema, true, async (input, user) => ({ total: input.a + input.b }));
- *
- * Request requirements:
- * - `Content-Type: application/vnd.msgpack`
- * - Body is msgpack-encoded object matching the provided schema.
- * - Optional `Authorization: Bearer <token>` header is decoded via the provided parseUser function.
- *
- * Responses are msgpack encoded objects with either handler data or `{ error, code, payload }` for handled errors.
- */
-class Appserver {
-    app;
-    parseUser;
-    getMetrics;
-    registered = new Set();
-    constructor(port, parseUser, getMetrics, origins = []) {
-        this.parseUser = parseUser;
-        this.getMetrics = getMetrics;
-        this.app = (0, express_1.default)();
-        if (origins.length > 0) {
-            this.app.use((0, cors_1.default)({
-                origin: origins,
-                credentials: true
-            }));
-        }
-        this.app.get('/metrics', async (req, res) => {
-            await this.handleMetricsRequest(req, res);
-        });
-        this.registerAuth(this.app);
-        this.app.listen(port);
+class AppserverDispatcher {
+    registry = new Map();
+    register(action, mod) {
+        if (this.registry.has(action))
+            throw new Error(`Action already registered: "${action}"`);
+        this.registry.set(action, mod);
     }
-    registerAuth(app) {
-        this.unsafeRegister('/auth/whoami', typebox_1.Type.Object({}), false, async (input, user) => {
-            const mappedUser = Object.fromEntries(Object.entries(user ?? {})
-                .filter(([key]) => !key.startsWith('_')));
-            return {
-                user: user !== null ? mappedUser : null
-            };
+    async autoload(base) {
+        const absBase = path_1.default.resolve(base);
+        const files = await (0, promises_1.readdir)(absBase, {
+            recursive: true,
+            withFileTypes: true
         });
-    }
-    async handleMetricsRequest(req, res) {
-        try {
-            const metrics = this.getMetrics();
-            const toReturn = Object.entries(metrics)
-                .map(([name, value]) => {
-                if (typeof value !== 'number' || !isFinite(value))
-                    throw new Error(`Metric value for "${name}" is not a number`);
-                const prometheusName = 'app_' + name
-                    .toLowerCase()
-                    .replace(/[^a-z0-9_]/g, '_')
-                    .replace(/_+/g, '_')
-                    .replace(/^_+|_+$/g, '');
-                return `# TYPE ${prometheusName} gauge\n${prometheusName} ${value}\n`;
-            })
-                .join('');
-            res
-                .status(200)
-                .type('text/plain')
-                .send(toReturn);
+        const jsFiles = files.filter(e => e.isFile() && e.name.endsWith('.js'));
+        if (jsFiles.length === 0) {
+            console.warn(`[appserver] autoload found no .js files in "${absBase}".`, `If you are using TypeScript, make sure the api directory is included in your tsconfig`, `and that you are pointing autoload at the compiled output directory, not the source.`);
+            return;
         }
-        catch (e) {
-            console.log("Error generating metrics:", e);
-            res
-                .status(500)
-                .type('text/plain')
-                .send('# Error generating metrics\n');
+        for (const entry of jsFiles) {
+            const fullPath = path_1.default.join(entry.parentPath, entry.name);
+            const action = path_1.default
+                .relative(absBase, fullPath)
+                .replace(/\.js$/, '')
+                .split(path_1.default.sep)
+                .join('/');
+            const ACTION_REGEX = /^([a-z0-9]+\/)*[a-z0-9]+$/;
+            if (!ACTION_REGEX.test(action))
+                throw new Error(`Invalid module path "${action}" — all segments must be lowercase alphanumeric`);
+            const mod = await import(fullPath);
+            if (!mod.default || typeof mod.default.handler !== 'function' || !mod.default.schema)
+                throw new Error(`Module "${fullPath}" must have a default export satisfying ApiModule`);
+            this.register(action, mod.default);
         }
     }
-    async parseInput(req) {
-        if (req.headers['content-type'] !== 'application/vnd.msgpack')
-            throw new AppserverError('REQUEST_INVALID_TYPE_HEADER', 'Content-Type must be a messagepack (application/vnd.msgpack)', 400);
-        const data = (() => {
-            try {
-                return (0, msgpack_1.decode)(req.body);
-            }
-            catch (e) {
-                throw new AppserverError('REQUEST_INVALID_BODY', 'Request body is not valid msgpack', 400);
-            }
-        })();
-        const authHeader = req.headers['authorization'];
-        const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : null;
-        return {
-            data,
-            user: token ? await this.parseUser(token) : null
-        };
-    }
-    registerPublic(action, inputSchema, handler) {
-        this.unsafeRegister(`/exec/${action}`, inputSchema, false, handler);
-    }
-    registerPrivate(action, inputSchema, handler) {
-        this.unsafeRegister(`/exec/${action}`, inputSchema, true, (input, user) => {
-            if (user === null)
-                throw new AppserverAuthError();
-            return handler(input, user);
-        });
-    }
-    unsafeRegister(action, inputSchema, auth, handler) {
-        if (this.registered.has(action))
-            throw new Error(`Action ${action} is already registered`);
-        this.registered.add(action);
-        this.app.post(action, express_1.default.raw({
+    bind(app, path) {
+        app.post(path, express_1.default.raw({
             type: 'application/vnd.msgpack',
             limit: '2gb'
         }), async (req, res) => {
-            const { status, data } = await (async () => {
+            await this.dispatch(req, res);
+        });
+    }
+    async dispatch(req, res) {
+        const respond = (status, data) => {
+            res
+                .status(status)
+                .send((0, msgpack_1.encode)(data));
+        };
+        try {
+            if (req.headers['content-type'] !== 'application/vnd.msgpack')
+                throw new AppserverError('REQUEST_INVALID_TYPE_HEADER', 'Content-Type must be a messagepack (application/vnd.msgpack)', {}, 400);
+            const parsed = (() => {
                 try {
-                    const { data: unsafeData, user } = await this.parseInput(req);
-                    if (auth && user === null)
-                        return {
-                            status: 401,
-                            data: { error: 'Authentication required', code: 'AUTHENTICATION_REQUIRED' }
-                        };
-                    if (!value_1.Value.Check(inputSchema, unsafeData))
-                        return {
-                            status: 422,
-                            data: {
-                                errors: [...value_1.Value.Errors(inputSchema, unsafeData)],
-                                received: unsafeData
-                            }
-                        };
-                    return {
-                        status: 200,
-                        data: await handler(unsafeData, user)
-                    };
+                    return (0, msgpack_1.decode)(req.body);
                 }
                 catch (e) {
-                    if (e instanceof AppserverError)
-                        return {
-                            status: e.status,
-                            data: { error: e.message, code: e.code, payload: e.payload }
-                        };
-                    console.log("Unhandled server error:", e);
-                    return {
-                        status: 500,
-                        data: { error: 'Internal server error', code: 'INTERNAL_SERVERERROR' }
-                    };
+                    throw new AppserverError('REQUEST_INVALID_BODY', 'Request body is not valid msgpack', {}, 400);
                 }
             })();
-            res
-                .status(status)
-                .send((0, msgpack_1.encode)(data));
-        });
+            const { action, payload } = parsed;
+            if (typeof action !== 'string')
+                throw new AppserverError("REQUEST_INVALID_ACTION", "Missing action field", {}, 400);
+            const mod = this.registry.get(action);
+            if (mod === undefined)
+                throw new AppserverError("ACTION_NOT_FOUND", `Action not found: ${action}`, {}, 404);
+            const token = req.headers['authorization']?.startsWith('Bearer ') ?
+                req.headers['authorization'].slice(7) :
+                undefined;
+            if (!value_1.Value.Check(mod.schema, payload))
+                return respond(422, {
+                    errors: JSON.stringify(value_1.Value.Errors(mod.schema, payload)),
+                    received: payload,
+                });
+            return respond(200, await mod.handler(payload, token));
+        }
+        catch (e) {
+            if (e instanceof AppserverError)
+                return respond(e.status, {
+                    error: e.message,
+                    code: e.code,
+                    payload: e.payload
+                });
+            console.error("Unhandled server error:", e);
+            return respond(500, {
+                error: 'Internal server error',
+                code: 'INTERNAL_SERVERERROR'
+            });
+        }
     }
 }
-exports.Appserver = Appserver;
+exports.AppserverDispatcher = AppserverDispatcher;

package/dist/MailTemplate/image.js

@@ -11,14 +11,14 @@ exports.SCHEMA = typebox_1.Type.Object({
     alt: typebox_1.Type.String()
 });
 function build(config) {
-    const img = (breakpoint, url) => `
-    <mj-image
-      css-class="${breakpoint ?? ''}"
-      src="${url}"
-      alt="${config.alt}"
-      ${config.link ? `href="${config.link}"` : ''}
-      padding="0"
-    />
+    const img = (breakpoint, url) => `
+    <mj-image
+      css-class="${breakpoint ?? ''}"
+      src="${url}"
+      alt="${config.alt}"
+      ${config.link ? `href="${config.link}"` : ''}
+      padding="0"
+    />
   `;
     const imgs = config.desktop === null ?
         img(null, config.mobile) :
@@ -26,12 +26,12 @@ function build(config) {
             img("onlyDesktop", config.desktop),
             img("onlyMobile", config.mobile)
         ].join('\n');
-    const toReturn = `
-    <mj-section padding="0">
-      <mj-column padding="0">
-        ${imgs}
-      </mj-column>
-    </mj-section>
+    const toReturn = `
+    <mj-section padding="0">
+      <mj-column padding="0">
+        ${imgs}
+      </mj-column>
+    </mj-section>
   `;
     return toReturn;
 }