@technomoron/apicore-client 1.0.0-beta.1

package/dist/esm/apicore-client.js

@@ -0,0 +1,632 @@
+/**
+ * Copyright (c) 2025 Bjørn Erik Jacobsen / Technomoron
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message || undefined;
+    }
+    if (isPlainObject(error)) {
+        const potentialMessage = error['message'];
+        if (typeof potentialMessage === 'string') {
+            return potentialMessage;
+        }
+    }
+    return undefined;
+}
+function getErrorCode(error) {
+    if (isPlainObject(error)) {
+        const potentialCode = error['code'];
+        if (typeof potentialCode === 'string') {
+            return potentialCode;
+        }
+    }
+    return undefined;
+}
+function hasErrorName(error, expected) {
+    if (isPlainObject(error)) {
+        const potentialName = error['name'];
+        if (typeof potentialName === 'string') {
+            return potentialName === expected;
+        }
+    }
+    return false;
+}
+/**
+ * Parses an error message from various error types
+ * @param {unknown} error - The error to parse
+ * @param {string} def - Default message if no message can be extracted
+ * @returns {string} The extracted error message or default message
+ */
+function parseMessage(error, def = '') {
+    if (typeof error === 'string') {
+        return error;
+    }
+    const message = getErrorMessage(error);
+    if (message) {
+        return message;
+    }
+    return def || '[Unknown error type - neither string, Error nor has .message]';
+}
+export class ApiResponse {
+    constructor(response = {}) {
+        this.success = false;
+        this.code = 500;
+        this.message = '[No Message]';
+        this.data = null;
+        this.errors = {};
+        this.success = response.success ?? false;
+        this.code = response.code ?? 500;
+        this.message = parseMessage(response.message, '[No Message]');
+        this.data = response.data ?? null;
+        this.errors = response.errors ?? {};
+    }
+    /**
+     * Creates a successful response with the provided data
+     * @param {T} data - The response data
+     * @param {Partial<ApiResponseData<T>>} overrides - Optional overrides for response properties
+     * @returns {ApiResponse<T>} A configured successful response
+     */
+    static ok(data, overrides = {}) {
+        return new ApiResponse({
+            success: true,
+            code: 200,
+            message: 'OK',
+            data,
+            ...overrides
+        });
+    }
+    /**
+     * Creates an error response with the provided message
+     * @param {unknown} messageOrError - The error message, error object, or existing ApiResponse
+     * @param {Partial<ApiResponseData<T>>} overrides - Optional overrides for response properties
+     * @returns {ApiResponse<T>} A configured error response
+     */
+    static error(messageOrError, overrides = {}) {
+        if (messageOrError instanceof ApiResponse) {
+            return messageOrError;
+        }
+        // Use parseMessage to handle any error type consistently
+        const message = parseMessage(messageOrError, 'Unknown error');
+        return new ApiResponse({
+            success: false,
+            code: overrides.code ?? 500,
+            message,
+            data: null,
+            ...overrides
+        });
+    }
+    /**
+     * Adds a named error to the errors collection
+     * @param {string} name - The name/key for the error
+     * @param {string} value - The error message
+     */
+    addError(name, value) {
+        this.errors[name] = value;
+    }
+    /**
+     * Type guard to check if the response is successful and contains data
+     * When this returns true, TypeScript narrows the type to ensure data is not null
+     * @returns {boolean} True if the response is successful and contains data
+     */
+    isSuccess() {
+        return this.success && this.data !== null;
+    }
+}
+class ApiClient {
+    constructor(apiUrl, config = {}) {
+        this.apiKey = null;
+        this.aToken = null;
+        this.rToken = null;
+        // Shared promise so that concurrent 401s all await the same refresh attempt.
+        this._refreshPromise = null;
+        this.timeoutMs = 15000;
+        this.maxRetries = 1;
+        this.debug = false;
+        this.tokens = true;
+        this.apiUrl = apiUrl.endsWith('/') ? apiUrl.slice(0, -1) : apiUrl;
+        this.apiKey = config.apiKey ?? null;
+        this.timeoutMs = config.timeout ?? 15000;
+        this.maxRetries = config.maxRetries ?? 1;
+        this.debug = config.debug ?? false;
+        this.tokens = config.enableTokens ?? true;
+    }
+    /**
+     * Updates the client configuration
+     * @param {Partial<ApiClientConfig>} config - Configuration updates
+     */
+    configure(config) {
+        if (config.apiKey !== undefined)
+            this.apiKey = config.apiKey;
+        if (config.timeout !== undefined && config.timeout !== null)
+            this.timeoutMs = config.timeout;
+        if (config.maxRetries !== undefined && config.maxRetries !== null)
+            this.maxRetries = config.maxRetries;
+        if (config.debug !== undefined && config.debug !== null)
+            this.debug = config.debug;
+        if (config.enableTokens !== undefined && config.enableTokens !== null)
+            this.tokens = config.enableTokens;
+    }
+    /**
+     * Gets the current configuration
+     * @returns {ApiClientConfig} Current configuration
+     */
+    getConfig() {
+        return {
+            // Omit the raw API key — return a boolean sentinel so callers can check
+            // whether a key is configured without being able to extract its value.
+            apiKey: this.apiKey ? '***' : null,
+            timeout: this.timeoutMs,
+            maxRetries: this.maxRetries,
+            debug: this.debug,
+            enableTokens: this.tokens
+        };
+    }
+    tryStringify(obj) {
+        try {
+            return JSON.stringify(obj);
+        }
+        catch (err) {
+            if (this.debug) {
+                console.error('[ApiClient] JSON.stringify failed:', err);
+            }
+            throw ApiResponse.error('Failed to serialize request body', {
+                code: 400
+            });
+        }
+    }
+    /**
+     * Retrieves the stored access token
+     * Designed to be overridden in subclasses for custom token storage
+     * @returns {string|null} The current access token or null if not set
+     */
+    get_access_token() {
+        return this.aToken;
+    }
+    /**
+     * Stores the access token
+     * Designed to be overridden in subclasses for custom token storage
+     * @param {string|null} access - The access token to store, or null to clear
+     */
+    set_access_token(access) {
+        this.aToken = access;
+    }
+    /**
+     * Retrieves the stored refresh token
+     * Designed to be overridden in subclasses for custom token storage
+     * @returns {string|null} The current refresh token or null if not set
+     */
+    get_refresh_token() {
+        return this.rToken;
+    }
+    /**
+     * Stores the refresh token
+     * Designed to be overridden in subclasses for custom token storage
+     * @param {string|null} refresh - The refresh token to store, or null to clear
+     */
+    set_refresh_token(refresh) {
+        this.rToken = refresh;
+    }
+    /**
+     * Sets the API key for authentication
+     * Designed to be overridden in subclasses for custom API key storage
+     * @param {string|null} apikey - The API key to use for authentication, or null to clear
+     */
+    set_apikey(apikey) {
+        this.apiKey = apikey;
+    }
+    /**
+     * Retrieves the stored API key
+     * Designed to be overridden in subclasses for custom API key storage
+     * @returns {string|null} The current API key or null if not set
+     */
+    get_apikey() {
+        return this.apiKey;
+    }
+    /**
+     * Builds authentication headers based on current configuration
+     * @returns {Record<string, string>} Headers object with authentication if available
+     */
+    buildAuthHeaders() {
+        const headers = {};
+        if (this.apiKey) {
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        }
+        else if (this.tokens) {
+            const accessToken = this.get_access_token();
+            if (accessToken) {
+                headers.Authorization = `Bearer ${accessToken}`;
+            }
+        }
+        return headers;
+    }
+    /**
+     * A drop‑in replacement for fetch() that handles timeouts and
+     * normalized network errors and throws an ApiResponse on failure.
+     * Uses the instance's configured timeout value.
+     */
+    async safeFetch(input, init = {}) {
+        const controller = new AbortController();
+        const id = setTimeout(() => controller.abort(), this.timeoutMs);
+        const headers = new Headers(init.headers);
+        const authHeaders = this.buildAuthHeaders();
+        for (const [k, v] of Object.entries(authHeaders)) {
+            headers.set(k, v);
+        }
+        const method = (init.method ?? 'GET').toUpperCase();
+        if (method !== 'GET' &&
+            init.body !== undefined &&
+            init.body !== null &&
+            !headers.has('Content-Type') &&
+            !(init.body instanceof FormData)) {
+            headers.set('Content-Type', 'application/json');
+        }
+        if (this.debug) {
+            console.log('[safeFetch] Request:', input);
+            console.log('[safeFetch] Method:', method);
+            console.log('[safeFetch] Headers:', headers);
+        }
+        try {
+            const res = await fetch(input, {
+                ...init,
+                headers,
+                signal: controller.signal
+            });
+            return res;
+        }
+        catch (err) {
+            if (hasErrorName(err, 'AbortError')) {
+                throw ApiResponse.error('Fetch timed out', { code: 504 });
+            }
+            let reason = '';
+            let status = 500;
+            const isBrowser = typeof window !== 'undefined' &&
+                typeof window.document !== 'undefined';
+            if (isBrowser) {
+                // Browser environment
+                if (err instanceof TypeError && err.message === 'Failed to fetch') {
+                    reason = 'Possible CORS issue or server unreachable';
+                    status = 503;
+                }
+                else {
+                    reason = getErrorMessage(err) || 'Unknown browser fetch error';
+                }
+            }
+            else {
+                // Node.js environment
+                switch (getErrorCode(err)) {
+                    case 'ECONNREFUSED':
+                        reason = 'Connection refused by server';
+                        status = 503;
+                        break;
+                    case 'ENOTFOUND':
+                        reason = 'DNS lookup failed - host not found';
+                        status = 503;
+                        break;
+                    case 'ETIMEDOUT':
+                        reason = 'Connection timed out';
+                        status = 504;
+                        break;
+                    case 'ECONNRESET':
+                        reason = 'Connection reset by server';
+                        status = 503;
+                        break;
+                    case 'EHOSTUNREACH':
+                        reason = 'Host unreachable';
+                        status = 503;
+                        break;
+                    default:
+                        reason = getErrorMessage(err) || 'Unknown network error';
+                }
+            }
+            throw ApiResponse.error(`Fetch failed: ${reason}`, { code: status });
+        }
+        finally {
+            clearTimeout(id);
+        }
+    }
+    /**
+     * Safely parses JSON response with proper error handling
+     * @param {Response} response - The fetch response
+     * @returns {Promise<RawApiResponse<T>>} The parsed JSON data
+     */
+    async parseJsonResponse(response) {
+        try {
+            return (await response.json());
+        }
+        catch (err) {
+            throw ApiResponse.error(`Failed to parse JSON response: ${parseMessage(err)}`, {
+                code: response.status
+            });
+        }
+    }
+    async login(username, password, domain = '', fingerprint = '') {
+        try {
+            const loginBody = { login: username, password };
+            if (domain)
+                loginBody.domain = domain;
+            if (fingerprint)
+                loginBody.fingerprint = fingerprint;
+            const response = await this.safeFetch(`${this.apiUrl}/api/auth/v1/login`, {
+                method: 'POST',
+                body: this.tryStringify(loginBody),
+                credentials: 'include'
+            });
+            const jsondata = await this.parseJsonResponse(response);
+            if (this.debug) {
+                console.log('Login Response Headers:');
+                response.headers.forEach((value, name) => {
+                    console.log(`${name}: ${value}`);
+                });
+            }
+            if (response.ok) {
+                // Type-safe access to token data — only update tokens when explicitly present
+                const tokenData = jsondata.data;
+                if (tokenData?.accessToken !== undefined) {
+                    this.set_access_token(tokenData.accessToken ?? null);
+                }
+                if (tokenData?.refreshToken !== undefined) {
+                    this.set_refresh_token(tokenData.refreshToken ?? null);
+                }
+                return ApiResponse.ok(jsondata.data, {
+                    message: jsondata.message || 'Login successful',
+                    code: response.status
+                });
+            }
+            else {
+                return ApiResponse.error(jsondata.message || 'Login Failed', {
+                    code: response.status,
+                    errors: jsondata.errors || {}
+                });
+            }
+        }
+        catch (e) {
+            if (e instanceof ApiResponse) {
+                return e;
+            }
+            return ApiResponse.error(e);
+        }
+    }
+    async logout(token = '') {
+        try {
+            // Use the caller-supplied token; fall back to the stored refresh token so
+            // that cookieless environments (Node.js, no cookie jar) still revoke the token.
+            const refreshToken = token || this.get_refresh_token() || '';
+            const response = await this.safeFetch(`${this.apiUrl}/api/auth/v1/logout`, {
+                method: 'POST',
+                body: refreshToken ? this.tryStringify({ token: refreshToken }) : '{}',
+                credentials: 'include'
+            });
+            const jsondata = await this.parseJsonResponse(response);
+            if (this.debug) {
+                console.log('Logout Response Headers:');
+                response.headers.forEach((value, name) => {
+                    console.log(`${name}: ${value}`);
+                });
+            }
+            // Always clear local tokens on logout attempt, regardless of server response
+            this.set_access_token(null);
+            this.set_refresh_token(null);
+            if (!response.ok) {
+                return ApiResponse.error(jsondata.message || 'Logout Failed', {
+                    code: response.status,
+                    errors: jsondata.errors || {}
+                });
+            }
+            return ApiResponse.ok(jsondata.data, {
+                message: jsondata.message || 'Logout Successful',
+                code: response.status
+            });
+        }
+        catch (e) {
+            if (e instanceof ApiResponse) {
+                return e;
+            }
+            return ApiResponse.error(e);
+        }
+    }
+    async refreshAccessToken() {
+        // Serialise concurrent refresh attempts: if a refresh is already in flight,
+        // await it instead of launching a second one (which would fail because the
+        // server rotates the refresh token on every use).
+        if (this._refreshPromise) {
+            return this._refreshPromise;
+        }
+        this._refreshPromise = this.performRefresh();
+        try {
+            return (await this._refreshPromise);
+        }
+        finally {
+            this._refreshPromise = null;
+        }
+    }
+    async performRefresh() {
+        try {
+            if (!this.get_refresh_token()) {
+                return ApiResponse.error('No Refresh Token Available', { code: 401 });
+            }
+            const response = await this.safeFetch(`${this.apiUrl}/api/auth/v1/refresh`, {
+                method: 'POST',
+                body: this.tryStringify({ refreshToken: this.get_refresh_token() }),
+                credentials: 'include'
+            });
+            const jsondata = await this.parseJsonResponse(response);
+            if (!response.ok) {
+                // Clear stale tokens when the server rejects the refresh token.
+                if (response.status === 401 || response.status === 403) {
+                    this.set_access_token(null);
+                    this.set_refresh_token(null);
+                }
+                return ApiResponse.error(jsondata.message || 'Token Refresh Failed', {
+                    code: response.status,
+                    errors: jsondata.errors || {}
+                });
+            }
+            // Only update tokens when the field is explicitly present in the response.
+            const tokenData = jsondata.data;
+            if (tokenData?.accessToken !== undefined) {
+                this.set_access_token(tokenData.accessToken ?? null);
+            }
+            if (tokenData?.refreshToken !== undefined) {
+                this.set_refresh_token(tokenData.refreshToken ?? null);
+            }
+            return ApiResponse.ok(jsondata.data, {
+                message: jsondata.message || 'Token Refreshed',
+                code: response.status
+            });
+        }
+        catch (e) {
+            if (e instanceof ApiResponse) {
+                return e;
+            }
+            return ApiResponse.error(e);
+        }
+    }
+    async fetchWithRetry(url, init = {}) {
+        let allowAuthRetry = true;
+        // Iterative retry loop to avoid deep call stack
+        for (let timeoutRetryCount = 0; timeoutRetryCount <= this.maxRetries; timeoutRetryCount++) {
+            try {
+                const response = await this.safeFetch(url, {
+                    ...init,
+                    credentials: 'include'
+                });
+                // Parse JSON with type safety
+                const payload = await this.parseJsonResponse(response);
+                // Success case (HTTP layer)
+                // If the API uses a JSON { success: false } shape even on 2xx, respect it.
+                if (response.ok) {
+                    if (payload.success === false) {
+                        return ApiResponse.error(payload.message || 'Request failed', {
+                            code: payload.code ?? response.status,
+                            errors: payload.errors || {}
+                        });
+                    }
+                    return ApiResponse.ok(payload.data, {
+                        message: payload.message || 'OK',
+                        code: payload.code ?? response.status,
+                        errors: payload.errors || {}
+                    });
+                }
+                // If using API key, don't retry on auth failures
+                if (this.apiKey) {
+                    return ApiResponse.error(payload.message || 'Request failed with API key authentication', {
+                        code: response.status,
+                        errors: payload.errors || {}
+                    });
+                }
+                // Try to refresh token on 401 (only once)
+                if (allowAuthRetry && response.status === 401 && this.get_refresh_token()) {
+                    if (this.debug) {
+                        console.log('Received 401, attempting token refresh...');
+                    }
+                    const refreshRes = await this.refreshAccessToken();
+                    if (!refreshRes.success) {
+                        return ApiResponse.error(refreshRes.message, {
+                            code: refreshRes.code,
+                            errors: refreshRes.errors
+                        });
+                    }
+                    // Allow one more iteration but disable further auth retries
+                    timeoutRetryCount = 0;
+                    allowAuthRetry = false;
+                    continue; // Retry with new token
+                }
+                // Final fallback error
+                return ApiResponse.error(payload.message || 'Unable to serve request', {
+                    code: response.status,
+                    errors: payload.errors || {}
+                });
+            }
+            catch (err) {
+                // Handle thrown ApiResponse errors from safeFetch or parseJsonResponse
+                if (err instanceof ApiResponse) {
+                    // Check if this is a timeout error and we can retry
+                    if (err.code === 504 && timeoutRetryCount < this.maxRetries) {
+                        if (this.debug) {
+                            console.log(`Request timed out, retrying... (attempt ${timeoutRetryCount + 1}/${this.maxRetries + 1})`);
+                        }
+                        continue; // Retry
+                    }
+                    return err; // Return error
+                }
+                return ApiResponse.error(err);
+            }
+        }
+        // This should never be reached, but TypeScript needs it
+        return ApiResponse.error('Maximum retries exceeded', { code: 500 });
+    }
+    /**
+     * Performs a generic HTTP request to the API
+     * @param {'GET'|'POST'|'PUT'|'DELETE'} method - The HTTP method to use
+     * @param {string} command - The API endpoint path
+     * @param {SerializableBody} [body] - Optional request body (for POST/PUT/DELETE requests)
+     * @returns {Promise<ApiResponse<T>>} A promise resolving to the API response
+     * @template T - The expected type of the response data
+     */
+    async request(method, command, body, files) {
+        const url = `${this.apiUrl}${command}`;
+        const options = {
+            method
+        };
+        if (files && files.length > 0) {
+            const form = new FormData();
+            if (body !== undefined && body !== null) {
+                if (isPlainObject(body)) {
+                    for (const [key, value] of Object.entries(body)) {
+                        form.append(key, typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value));
+                    }
+                }
+                else {
+                    form.append('payload', this.tryStringify(body));
+                }
+            }
+            for (const fileEntry of files) {
+                if (Array.isArray(fileEntry)) {
+                    const [name, file] = fileEntry;
+                    form.append(name, file);
+                }
+                else {
+                    form.append('files', fileEntry); // default field name
+                }
+            }
+            options.body = form;
+        }
+        else if (body !== undefined) {
+            try {
+                options.body = this.tryStringify(body);
+            }
+            catch (e) {
+                return ApiResponse.error(e);
+            }
+        }
+        if (this.debug) {
+            console.log(`Making ${method} request to: ${url} (timeout: ${this.timeoutMs}ms, max retries: ${this.maxRetries})`);
+            if (body !== undefined) {
+                console.log('Request body:', options.body);
+            }
+        }
+        return this.fetchWithRetry(url, options);
+    }
+    async get(command) {
+        return this.request('GET', command);
+    }
+    async post(command, body, files) {
+        return this.request('POST', command, body, files);
+    }
+    async put(command, body) {
+        return this.request('PUT', command, body);
+    }
+    async delete(command, body) {
+        return this.request('DELETE', command, body);
+    }
+    async ping() {
+        return this.get('/api/v1/ping');
+    }
+}
+export default ApiClient;

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { default as ApiClient, ApiResponse } from './apicore-client.js';
+export { default } from './apicore-client.js';
+export type { maybeFile } from './apicore-client.js';
+export type { ApiClientConfig, ApiResponseData, AuthIdentifier, AuthTokenData, LogoutResponseData, PingResponseData, SafeUser, WhoAmIResponseData } from './apicore-client.js';

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { default as ApiClient, ApiResponse } from './apicore-client.js';
+export { default } from './apicore-client.js';