@technomoron/apicore-client 1.0.0-beta.1

package/dist/esm/apicore-client.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 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.
+ */
+export type maybeFile = File | Blob | [string, File | Blob];
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type SerializableBody = JsonValue;
+export interface ApiResponseData<T = unknown> {
+    success: boolean;
+    code: number;
+    message: string;
+    data: T | null;
+    errors: Record<string, string>;
+}
+export type SafeUser = Record<string, unknown>;
+export type AuthIdentifier = string | number;
+export interface PingResponseData {
+    success: boolean;
+    status: string;
+    apiVersion: string;
+    minClientVersion: string;
+    uptimeSec: number;
+    startedAt: string;
+    timestamp: string;
+}
+export interface ApiClientConfig {
+    apiKey?: string | null;
+    timeout?: number;
+    maxRetries?: number;
+    debug?: boolean;
+    enableTokens?: boolean;
+}
+/**
+ * Authentication token response shape
+ */
+export interface AuthTokenData<User = SafeUser> {
+    accessToken?: string;
+    refreshToken?: string;
+    user?: User;
+}
+export interface WhoAmIResponseData<User = SafeUser, UserId extends AuthIdentifier = AuthIdentifier> {
+    user: User;
+    isImpersonating: boolean;
+    realUser?: User | null;
+    realUserId?: UserId | null;
+}
+export interface LogoutResponseData {
+    revoked: number;
+}
+export declare class ApiResponse<T = unknown> implements ApiResponseData<T> {
+    success: boolean;
+    code: number;
+    message: string;
+    data: T | null;
+    errors: Record<string, string>;
+    constructor(response?: Partial<ApiResponseData<T>>);
+    /**
+     * 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<T>(data: T, overrides?: Partial<Omit<ApiResponseData<T>, 'data'>>): ApiResponse<T>;
+    /**
+     * 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<T>(messageOrError: unknown, overrides?: Partial<Omit<ApiResponseData<T>, 'data'>>): ApiResponse<T>;
+    /**
+     * 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: string, value: string): void;
+    /**
+     * 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(): this is ApiResponse<T> & {
+        data: T;
+    };
+}
+declare class ApiClient {
+    private apiKey;
+    private aToken;
+    private rToken;
+    private apiUrl;
+    private _refreshPromise;
+    private timeoutMs;
+    private maxRetries;
+    private debug;
+    private tokens;
+    constructor(apiUrl: string, config?: ApiClientConfig);
+    /**
+     * Updates the client configuration
+     * @param {Partial<ApiClientConfig>} config - Configuration updates
+     */
+    configure(config: Partial<ApiClientConfig>): void;
+    /**
+     * Gets the current configuration
+     * @returns {ApiClientConfig} Current configuration
+     */
+    getConfig(): ApiClientConfig;
+    private tryStringify;
+    /**
+     * 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(): string | null;
+    /**
+     * 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: string | null): void;
+    /**
+     * 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(): string | null;
+    /**
+     * 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: string | null): void;
+    /**
+     * 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: string | null): void;
+    /**
+     * 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(): string | null;
+    /**
+     * Builds authentication headers based on current configuration
+     * @returns {Record<string, string>} Headers object with authentication if available
+     */
+    private buildAuthHeaders;
+    /**
+     * 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.
+     */
+    private safeFetch;
+    /**
+     * Safely parses JSON response with proper error handling
+     * @param {Response} response - The fetch response
+     * @returns {Promise<RawApiResponse<T>>} The parsed JSON data
+     */
+    private parseJsonResponse;
+    login<T = AuthTokenData>(username: string, password: string, domain?: string, fingerprint?: string): Promise<ApiResponse<T>>;
+    logout<T = LogoutResponseData>(token?: string): Promise<ApiResponse<T>>;
+    private refreshAccessToken;
+    private performRefresh;
+    private fetchWithRetry;
+    /**
+     * 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
+     */
+    request<T>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', command: string, body?: SerializableBody, files?: maybeFile[]): Promise<ApiResponse<T>>;
+    get<T>(command: string): Promise<ApiResponse<T>>;
+    post<T>(command: string, body?: SerializableBody, files?: maybeFile[]): Promise<ApiResponse<T>>;
+    put<T>(command: string, body?: SerializableBody): Promise<ApiResponse<T>>;
+    delete<T>(command: string, body?: SerializableBody): Promise<ApiResponse<T>>;
+    ping(): Promise<ApiResponse<PingResponseData>>;
+}
+export default ApiClient;