@grandlinex/base-con 1.0.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, GrandlineX
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,11 @@
+# @grandlinex/base-con
+
+A foundational library that provides core api request handling for GrandLineX projects.  
+It offers a set of utilities and conventions to streamline development and integration across the GrandLineX ecosystem.
+ 
+## Description
+
+`@grandlinex/base-con` is a lightweight module designed to serve as a base for other GrandLineX packages.  
+It encapsulates common utilities and patterns, ensuring consistency and reducing boilerplate across projects.
+
+ 

package/dist/cjs/AxiosCon.d.ts

@@ -0,0 +1,3 @@
+import { ConHandle } from './BaseCon.js';
+declare const AxiosCon: ConHandle;
+export default AxiosCon;

package/dist/cjs/AxiosCon.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const axios_1 = __importDefault(require("axios"));
+async function acTransform(r) {
+    const res = await r;
+    return {
+        code: res.status,
+        data: res.data,
+        headers: res.headers,
+    };
+}
+const AxiosCon = {
+    get: async (url, config) => {
+        return acTransform(axios_1.default.get(url, {
+            headers: config?.headers,
+            validateStatus: (status) => true,
+        }));
+    },
+    post: async (url, body, config) => {
+        return acTransform(axios_1.default.post(url, body, {
+            headers: config?.headers,
+            validateStatus: (status) => true,
+        }));
+    },
+    patch: async (url, body, config) => {
+        return acTransform(axios_1.default.patch(url, body, {
+            headers: config?.headers,
+            validateStatus: (status) => true,
+        }));
+    },
+    delete: async (url, config) => {
+        return acTransform(axios_1.default.delete(url, {
+            headers: config?.headers,
+            validateStatus: (status) => true,
+        }));
+    },
+};
+exports.default = AxiosCon;

package/dist/cjs/BaseCon.d.ts

@@ -0,0 +1,182 @@
+/**
+ * THIS FILE IS AUTOMATICALLY GENERATED
+ * DO NOT EDIT THIS FILE
+ */
+export type ErrorType = {
+    type: string;
+    global?: string[];
+    field?: {
+        key: string;
+        message: string;
+    }[];
+};
+export type HeaderType = string | string[] | number | undefined;
+export type HandleRes<T> = {
+    success: boolean;
+    data: T | null;
+    code?: number;
+    error?: ErrorType;
+    headers?: Record<string, HeaderType>;
+};
+export type PathParam = {
+    [key: string]: string | number | undefined;
+};
+export declare function isErrorType(x: any): x is ErrorType;
+export interface ConHandleConfig {
+    headers?: Record<string, string>;
+    param?: PathParam;
+    query?: PathParam;
+}
+export interface ConHandleResponse<T> {
+    code: number;
+    data: T | null;
+    headers: Record<string, HeaderType>;
+}
+export interface ConHandle {
+    get<T>(url: string, config?: ConHandleConfig): Promise<ConHandleResponse<T>>;
+    post<T, J>(url: string, body?: J, config?: ConHandleConfig): Promise<ConHandleResponse<T>>;
+    patch<T, J>(url: string, body?: J, config?: ConHandleConfig): Promise<ConHandleResponse<T>>;
+    delete<T>(url: string, config?: ConHandleConfig): Promise<ConHandleResponse<T>>;
+}
+/**
+ * BaseCon provides a minimal client for interacting with an HTTP backend.
+ * It manages connection state, authentication tokens, and reconnection
+ * logic while delegating actual HTTP requests to a supplied {@link ConHandle}.
+ *
+ * @class
+ */
+export default class BaseCon {
+    private api;
+    private permanentHeader;
+    private authorization;
+    private noAuth;
+    private disconnected;
+    private readonly logger;
+    con: ConHandle;
+    reconnect: () => Promise<boolean>;
+    onReconnect: (con: BaseCon) => Promise<boolean>;
+    constructor(conf: {
+        con: ConHandle;
+        endpoint: string;
+        logger?: (arg: any) => void;
+        permanentHeader?: Record<string, string>;
+    });
+    /**
+     * Retrieves the API endpoint.
+     *
+     * @return {string} The API endpoint string.
+     */
+    getApiEndpoint(): string;
+    /**
+     * Sets the API endpoint URL used by the client.
+     *
+     * @param {string} endpoint - The full URL of the API endpoint.
+     * @returns {void}
+     */
+    setApiEndpoint(endpoint: string): void;
+    /**
+     * Indicates whether the instance is considered connected.
+     *
+     * The instance is regarded as connected when it either does not require authentication
+     * (`noAuth` is true) or it has an authorization token set (`authorization` is not null),
+     * and it is not currently marked as disconnected.
+     *
+     * @return {boolean} `true` if the instance is connected, `false` otherwise.
+     */
+    isConnected(): boolean;
+    /**
+     * Returns the current authorization token.
+     *
+     * @return {string} The authorization token or an empty string if none is set.
+     */
+    token(): string | null;
+    /**
+     * Returns the current authorization token.
+     *
+     * @return {string} The authorization token or an empty string if none is set.
+     */
+    getBearer(): string | null;
+    private p;
+    /**
+     * Sends a ping request to the API to verify connectivity and version availability.
+     *
+     * @return {boolean} `true` if the API responded with a 200 status code and a valid version object; `false` otherwise.
+     */
+    ping(): Promise<boolean>;
+    private tokenHeader;
+    setPermanentHeader(header: Record<string, string>): void;
+    /**
+     * Validates the current authentication token by performing a ping and a test request
+     * to the backend. The method first ensures connectivity via {@link ping}. If the ping
+     * succeeds, it attempts to retrieve a token from the `/test/auth` endpoint using the
+     * current token in the `Authorization` header. The operation is considered successful
+     * if the response status code is 200 or 201.
+     *
+     * If any step fails, an error is logged and the method returns {@code false}. On
+     * success, it returns {@code true}.
+     *
+     * @return {Promise<boolean>} A promise that resolves to {@code true} if the token
+     * test succeeds, otherwise {@code false}.
+     */
+    testToken(): Promise<boolean>;
+    /**
+     * Attempts to establish a connection to the backend without authentication.
+     *
+     * This method sends a ping request.  If the ping succeeds, it clears any
+     * existing authorization data, marks the instance as connected,
+     * enables the no‑authentication mode, and returns `true`.  If the ping
+     * fails, it logs a warning, clears authorization, marks the instance
+     * as disconnected, and returns `false`.
+     *
+     * @return {Promise<boolean>} `true` when a connection is successfully
+     * established without authentication, otherwise `false`.
+     */
+    connectNoAuth(): Promise<boolean>;
+    /**
+     * Forces a connection using the provided bearer token.
+     *
+     * @param {string|null} token The token to be used for authentication.
+     * @returns {void}
+     */
+    forceConnect(token: string | null): void;
+    coppyFrom(con: BaseCon): void;
+    /**
+     * Establishes a connection to the backend using the supplied credentials.
+     * Performs a health‑check ping first; if successful, it requests an authentication
+     * token from the `/token` endpoint.  When the token is obtained, the method
+     * updates internal state (authorization header, connection flags) and, unless
+     * a dry run is requested, sets up a reconnection routine.  Any errors are
+     * logged and the method resolves to `false`.
+     *
+     * @param {string} email - The user's email address for authentication.
+     * @param {string} pw - The password (or token) for the specified user.
+     * @param {boolean} [dry=false] - If `true`, the method performs a dry run
+     *   without persisting credentials or configuring reconnection logic.
+     *
+     * @returns  Promise<boolean>  `true` if the connection was successfully
+     *   established, otherwise `false`.
+     */
+    connect(email: string, pw: string, dry?: boolean): Promise<boolean>;
+    /**
+     * Performs an HTTP request using the client’s internal connection.
+     *
+     * The method verifies that the client is connected before attempting a request.
+     * It automatically injects the authorization token, permanent headers, and any
+     * headers supplied in `config`. If the request body is a `FormData` instance
+     * (or provides a `getHeaders` method), the appropriate form headers are added.
+     *
+     * Response handling:
+     * - `200` or `201`: returns `success: true` with the received data.
+     * - `498`: attempts to reconnect and retries the request once.
+     * - `401`: logs an authentication error, marks the client as disconnected.
+     * - `403` and other status codes: return `success: false` with the status code.
+     *
+     * @param {'POST'|'GET'|'PATCH'|'DELETE'} type The HTTP method to use.
+     * @param {string} path The endpoint path relative to the base URL.
+     * @param {J} [body] Optional request payload. May be `FormData` or a plain object.
+     * @param {ConHandleConfig} [config] Optional Axios-like configuration for the request.
+     * @returns {Promise<HandleRes<T>>} A promise that resolves to a `HandleRes` object
+     * containing the response data, status code, any error information, and headers.
+     */
+    handle<T, J>(type: 'POST' | 'GET' | 'PATCH' | 'DELETE', path: string, body?: J, config?: ConHandleConfig): Promise<HandleRes<T>>;
+}

package/dist/cjs/BaseCon.js

@@ -0,0 +1,411 @@
+"use strict";
+/**
+ * THIS FILE IS AUTOMATICALLY GENERATED
+ * DO NOT EDIT THIS FILE
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isErrorType = isErrorType;
+const form_data_1 = __importDefault(require("form-data"));
+function isErrorType(x) {
+    return x && typeof x === 'object' && x.type === 'error';
+}
+/**
+ * BaseCon provides a minimal client for interacting with an HTTP backend.
+ * It manages connection state, authentication tokens, and reconnection
+ * logic while delegating actual HTTP requests to a supplied {@link ConHandle}.
+ *
+ * @class
+ */
+class BaseCon {
+    constructor(conf) {
+        this.api = conf.endpoint;
+        this.logger = conf.logger ?? console.log;
+        this.disconnected = true;
+        this.noAuth = false;
+        this.authorization = null;
+        this.con = conf.con;
+        this.permanentHeader = conf.permanentHeader || {};
+        this.reconnect = async () => {
+            this.disconnected = true;
+            return false;
+        };
+        this.onReconnect = () => Promise.resolve(true);
+        this.handle = this.handle.bind(this);
+    }
+    /**
+     * Retrieves the API endpoint.
+     *
+     * @return {string} The API endpoint string.
+     */
+    getApiEndpoint() {
+        return this.api;
+    }
+    /**
+     * Sets the API endpoint URL used by the client.
+     *
+     * @param {string} endpoint - The full URL of the API endpoint.
+     * @returns {void}
+     */
+    setApiEndpoint(endpoint) {
+        this.api = endpoint;
+    }
+    /**
+     * Indicates whether the instance is considered connected.
+     *
+     * The instance is regarded as connected when it either does not require authentication
+     * (`noAuth` is true) or it has an authorization token set (`authorization` is not null),
+     * and it is not currently marked as disconnected.
+     *
+     * @return {boolean} `true` if the instance is connected, `false` otherwise.
+     */
+    isConnected() {
+        return (this.noAuth || this.authorization !== null) && !this.disconnected;
+    }
+    /**
+     * Returns the current authorization token.
+     *
+     * @return {string} The authorization token or an empty string if none is set.
+     */
+    token() {
+        return this.authorization;
+    }
+    /**
+     * Returns the current authorization token.
+     *
+     * @return {string} The authorization token or an empty string if none is set.
+     */
+    getBearer() {
+        if (this.authorization) {
+            return `Bearer ${this.authorization}`;
+        }
+        return null;
+    }
+    p(path, config) {
+        let pp = path;
+        if (config?.param) {
+            const e = Object.keys(config.param);
+            for (const d of e) {
+                pp = pp.replace(`{${d}}`, `${config.param[d]}`);
+            }
+        }
+        if (config?.query) {
+            const e = Object.keys(config.query);
+            const slices = [];
+            for (const d of e) {
+                if (config.query[d]) {
+                    slices.push(`${d}=${config.query[d]}`);
+                }
+            }
+            if (slices.length > 0) {
+                pp += `?${slices.join('&')}`;
+            }
+        }
+        return `${this.api}${pp}`;
+    }
+    /**
+     * Sends a ping request to the API to verify connectivity and version availability.
+     *
+     * @return {boolean} `true` if the API responded with a 200 status code and a valid version object; `false` otherwise.
+     */
+    async ping() {
+        try {
+            const version = await this.con.get(this.p('/version'));
+            return version.data?.api !== undefined && version.code === 200;
+        }
+        catch (e) {
+            this.logger('ping failed');
+            return false;
+        }
+    }
+    tokenHeader() {
+        if (this.authorization) {
+            return {
+                Authorization: this.getBearer(),
+            };
+        }
+        return {};
+    }
+    setPermanentHeader(header) {
+        this.permanentHeader = header;
+    }
+    /**
+     * Validates the current authentication token by performing a ping and a test request
+     * to the backend. The method first ensures connectivity via {@link ping}. If the ping
+     * succeeds, it attempts to retrieve a token from the `/test/auth` endpoint using the
+     * current token in the `Authorization` header. The operation is considered successful
+     * if the response status code is 200 or 201.
+     *
+     * If any step fails, an error is logged and the method returns {@code false}. On
+     * success, it returns {@code true}.
+     *
+     * @return {Promise<boolean>} A promise that resolves to {@code true} if the token
+     * test succeeds, otherwise {@code false}.
+     */
+    async testToken() {
+        const ping = await this.ping();
+        if (ping) {
+            try {
+                const con = await this.con.get(this.p('/test/auth'), {
+                    headers: this.tokenHeader(),
+                });
+                return con.code === 200 || con.code === 201;
+            }
+            catch (e) {
+                this.logger(e);
+                this.logger('cant connect to backend');
+            }
+        }
+        this.logger('test ping failed');
+        return false;
+    }
+    /**
+     * Attempts to establish a connection to the backend without authentication.
+     *
+     * This method sends a ping request.  If the ping succeeds, it clears any
+     * existing authorization data, marks the instance as connected,
+     * enables the no‑authentication mode, and returns `true`.  If the ping
+     * fails, it logs a warning, clears authorization, marks the instance
+     * as disconnected, and returns `false`.
+     *
+     * @return {Promise<boolean>} `true` when a connection is successfully
+     * established without authentication, otherwise `false`.
+     */
+    async connectNoAuth() {
+        const ping = await this.ping();
+        if (ping) {
+            this.authorization = null;
+            this.disconnected = false;
+            this.noAuth = true;
+            return true;
+        }
+        this.logger('cant connect to backend');
+        this.authorization = null;
+        this.disconnected = true;
+        return false;
+    }
+    /**
+     * Forces a connection using the provided bearer token.
+     *
+     * @param {string|null} token The token to be used for authentication.
+     * @returns {void}
+     */
+    forceConnect(token) {
+        if (token) {
+            this.authorization = token.replace('Bearer ', '').replace('bearer ', '');
+        }
+        else {
+            this.authorization = null;
+        }
+        this.disconnected = false;
+        this.noAuth = token === null;
+    }
+    coppyFrom(con) {
+        this.authorization = con.authorization;
+        this.disconnected = con.disconnected;
+        this.noAuth = con.noAuth;
+    }
+    /**
+     * Establishes a connection to the backend using the supplied credentials.
+     * Performs a health‑check ping first; if successful, it requests an authentication
+     * token from the `/token` endpoint.  When the token is obtained, the method
+     * updates internal state (authorization header, connection flags) and, unless
+     * a dry run is requested, sets up a reconnection routine.  Any errors are
+     * logged and the method resolves to `false`.
+     *
+     * @param {string} email - The user's email address for authentication.
+     * @param {string} pw - The password (or token) for the specified user.
+     * @param {boolean} [dry=false] - If `true`, the method performs a dry run
+     *   without persisting credentials or configuring reconnection logic.
+     *
+     * @returns  Promise<boolean>  `true` if the connection was successfully
+     *   established, otherwise `false`.
+     */
+    async connect(email, pw, dry = false) {
+        const ping = await this.ping();
+        if (ping) {
+            try {
+                const token = await this.con.post(this.p('/token'), {
+                    username: email,
+                    token: pw,
+                });
+                if (token.code === 200 || token.code === 201) {
+                    if (!dry) {
+                        this.authorization = `Bearer ${token.data?.token}`;
+                        this.disconnected = false;
+                        this.noAuth = false;
+                        this.reconnect = async () => {
+                            return ((await this.connect(email, pw)) && (await this.testToken()));
+                        };
+                    }
+                    return true;
+                }
+            }
+            catch (e) {
+                this.logger(e);
+            }
+        }
+        this.logger('cant connect to backend');
+        this.authorization = null;
+        this.disconnected = true;
+        this.noAuth = false;
+        return false;
+    }
+    /**
+     * Performs an HTTP request using the client’s internal connection.
+     *
+     * The method verifies that the client is connected before attempting a request.
+     * It automatically injects the authorization token, permanent headers, and any
+     * headers supplied in `config`. If the request body is a `FormData` instance
+     * (or provides a `getHeaders` method), the appropriate form headers are added.
+     *
+     * Response handling:
+     * - `200` or `201`: returns `success: true` with the received data.
+     * - `498`: attempts to reconnect and retries the request once.
+     * - `401`: logs an authentication error, marks the client as disconnected.
+     * - `403` and other status codes: return `success: false` with the status code.
+     *
+     * @param {'POST'|'GET'|'PATCH'|'DELETE'} type The HTTP method to use.
+     * @param {string} path The endpoint path relative to the base URL.
+     * @param {J} [body] Optional request payload. May be `FormData` or a plain object.
+     * @param {ConHandleConfig} [config] Optional Axios-like configuration for the request.
+     * @returns {Promise<HandleRes<T>>} A promise that resolves to a `HandleRes` object
+     * containing the response data, status code, any error information, and headers.
+     */
+    async handle(type, path, body, config) {
+        if (!this.isConnected()) {
+            this.logger('Disconnected');
+            return {
+                success: false,
+                data: null,
+                code: -1,
+            };
+        }
+        let formHeader = null;
+        const cK = body;
+        if (cK &&
+            (cK instanceof form_data_1.default || typeof cK?.getHeaders === 'function')) {
+            formHeader = cK?.getHeaders?.() || {};
+        }
+        else {
+            formHeader = {};
+        }
+        let dat;
+        switch (type) {
+            case 'GET':
+                dat = await this.con.get(this.p(path, config), {
+                    ...config,
+                    headers: {
+                        ...this.tokenHeader(),
+                        ...formHeader,
+                        ...config?.headers,
+                        ...this.permanentHeader,
+                    },
+                });
+                break;
+            case 'POST':
+                dat = await this.con.post(this.p(path, config), body, {
+                    ...config,
+                    headers: {
+                        ...this.tokenHeader(),
+                        ...formHeader,
+                        ...config?.headers,
+                        ...this.permanentHeader,
+                    },
+                });
+                break;
+            case 'PATCH':
+                dat = await this.con.patch(this.p(path, config), body, {
+                    ...config,
+                    headers: {
+                        ...this.tokenHeader(),
+                        ...formHeader,
+                        ...config?.headers,
+                        ...this.permanentHeader,
+                    },
+                });
+                break;
+            case 'DELETE':
+                dat = await this.con.delete(this.p(path, config), {
+                    ...config,
+                    headers: {
+                        ...this.tokenHeader(),
+                        ...formHeader,
+                        ...config?.headers,
+                        ...this.permanentHeader,
+                    },
+                });
+                break;
+            default:
+                return {
+                    success: false,
+                    data: null,
+                    code: -1,
+                };
+        }
+        let error;
+        if (isErrorType(dat.data)) {
+            error = dat.data;
+        }
+        let x = false;
+        switch (dat.code) {
+            case 200:
+            case 201:
+                return {
+                    success: true,
+                    data: dat.data,
+                    code: dat.code,
+                    error,
+                    headers: dat.headers,
+                };
+            case 498:
+                x = await this.reconnect();
+                if (x) {
+                    this.onReconnect(this).catch((dx) => {
+                        this.logger(dx);
+                    });
+                    return this.handle(type, path, body, config);
+                }
+                this.reconnect = async () => {
+                    this.disconnected = true;
+                    return false;
+                };
+                this.disconnected = true;
+                return {
+                    success: false,
+                    data: null,
+                    code: dat.code,
+                    error,
+                    headers: dat.headers,
+                };
+            case 401:
+                this.logger('AUTH NOT VALID');
+                return {
+                    success: false,
+                    data: null,
+                    code: dat.code,
+                    error,
+                    headers: dat.headers,
+                };
+            case 403:
+                return {
+                    success: false,
+                    data: null,
+                    error,
+                    code: dat.code,
+                    headers: dat.headers,
+                };
+            default:
+                return {
+                    success: false,
+                    data: null,
+                    error,
+                    code: dat.code,
+                    headers: dat.headers,
+                };
+        }
+    }
+}
+exports.default = BaseCon;

package/dist/cjs/ConMerger.d.ts

@@ -0,0 +1,2 @@
+import BaseCon from "./BaseCon.js";
+export default function ConMerger<A extends BaseCon, B extends BaseCon>(conA: A, conB: B): A & B;