@modrinth/api-client 0.31.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modrinth/api-client",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "An API client for Modrinth's API for use in nuxt, tauri and plain node/browser environments.",
   "license": "LGPL-3.0-only",
   "type": "module",
@@ -37,9 +37,11 @@
     "ofetch": "^1.4.1"
   },
   "devDependencies": {
+    "@microsoft/api-extractor": "^7.58.9",
     "@tauri-apps/plugin-http": "^2.0.0",
     "esbuild": "0.27.2",
     "typescript": "^5.9.3",
+    "unplugin-dts": "^1.0.3",
     "@modrinth/tooling-config": "0.0.0"
   },
   "peerDependencies": {
@@ -52,7 +54,7 @@
   },
   "scripts": {
     "clean": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "pnpm run clean && esbuild src/index.ts --bundle --format=esm --platform=neutral --target=es2020 --minify --legal-comments=none --outfile=dist/index.js --external:ofetch --external:mitt --external:@tauri-apps/plugin-http && tsc -p tsconfig.build.json",
+    "build": "pnpm run clean && node esbuild.config.mjs",
     "lint": "eslint . && prettier --check .",
     "fix": "eslint . --fix && prettier --write ."
   }

package/dist/core/abstract-client.d.ts

@@ -1,163 +0,0 @@
-import type { InferredClientModules } from '../modules';
-import type { BaseUrlConfig, ClientConfig } from '../types/client';
-import type { RequestContext, RequestOptions } from '../types/request';
-import type { UploadProgress, UploadRequestOptions } from '../types/upload';
-import type { AbstractFeature } from './abstract-feature';
-import type { AbstractSyncClient } from './abstract-sync';
-import { AbstractUploadClient } from './abstract-upload-client';
-import type { AbstractWebSocketClient } from './abstract-websocket';
-import { ModrinthApiError } from './errors';
-type ArchonClientModules = Omit<InferredClientModules['archon'], 'backups_v1'> & {
-    /** @deprecated Use `backups_queue_v1` for the Backups Queue API. */
-    backups_v1: InferredClientModules['archon']['backups_v1'];
-};
-/**
- * Abstract base client for Modrinth APIs
- */
-export declare abstract class AbstractModrinthClient extends AbstractUploadClient {
-    protected config: ClientConfig;
-    protected features: AbstractFeature[];
-    /**
-     * Maps full module ID (e.g., 'labrinth_projects_v2') to instantiated module
-     */
-    private _moduleInstances;
-    /**
-     * Maps API name (e.g., 'labrinth') to namespace object
-     */
-    private _moduleNamespaces;
-    readonly labrinth: InferredClientModules['labrinth'];
-    readonly archon: ArchonClientModules & {
-        sockets: AbstractWebSocketClient;
-        sync: AbstractSyncClient;
-    };
-    readonly kyros: InferredClientModules['kyros'];
-    readonly iso3166: InferredClientModules['iso3166'];
-    readonly mclogs: InferredClientModules['mclogs'];
-    readonly launchermeta: InferredClientModules['launchermeta'];
-    readonly paper: InferredClientModules['paper'];
-    readonly purpur: InferredClientModules['purpur'];
-    constructor(config: ClientConfig);
-    /**
-     * This creates the nested API structure (e.g., client.labrinth.projects_v2)
-     * but doesn't instantiate modules until first access
-     *
-     * Module IDs in the registry are validated at runtime to ensure they match
-     * what the module declares via getModuleID().
-     */
-    private initializeModules;
-    /**
-     * Make a request to the API
-     *
-     * @param path - API path (e.g., '/project/sodium')
-     * @param options - Request options
-     * @returns Promise resolving to the response data
-     * @throws {ModrinthApiError} When the request fails or features throw errors
-     */
-    request<T>(path: string, options: RequestOptions): Promise<T>;
-    stream(path: string, options: RequestOptions): Promise<ReadableStream<Uint8Array>>;
-    /**
-     * Execute the feature chain and the actual request
-     *
-     * Features are executed in order, with each feature calling next() to continue.
-     * The last "feature" in the chain is the actual request execution.
-     */
-    protected executeFeatureChain<T>(context: RequestContext, executeTerminal?: () => Promise<T>): Promise<T>;
-    /**
-     * Execute the feature chain for an upload
-     *
-     * Similar to executeFeatureChain but calls executeXHRUpload at the end.
-     * This allows features (auth, retry, etc.) to wrap the upload execution.
-     */
-    protected executeUploadFeatureChain<T>(context: RequestContext, progressCallbacks: Array<(p: UploadProgress) => void>, abortController: AbortController): Promise<T>;
-    /**
-     * Build the full URL for a request
-     */
-    protected buildUrl(path: string, baseUrl: string, version: number | 'internal' | string): string;
-    protected resolveBaseUrl(baseUrl: BaseUrlConfig): string;
-    /**
-     * Build the request context
-     */
-    protected buildContext(url: string, path: string, options: RequestOptions): RequestContext;
-    /**
-     * Build context for an upload request
-     *
-     * Sets metadata.isUpload = true so features can detect uploads.
-     * Supports both single file uploads and FormData uploads.
-     */
-    protected buildUploadContext(url: string, path: string, options: UploadRequestOptions): RequestContext;
-    /**
-     * Build default headers for all requests
-     *
-     * Subclasses can override this to add platform-specific headers
-     * (e.g., Nuxt rate limit key)
-     */
-    protected buildDefaultHeaders(): Promise<Record<string, string>>;
-    private resolveUserAgent;
-    protected attachArchonSentryCaptureHeader(options: RequestOptions): void;
-    private shouldCaptureArchonRequests;
-    /**
-     * Execute the actual HTTP request
-     *
-     * This must be implemented by platform-specific clients.
-     *
-     * @param url - Full URL to request
-     * @param options - Request options
-     * @returns Promise resolving to the response data
-     * @throws {Error} Platform-specific errors that will be normalized by normalizeError()
-     */
-    protected abstract executeRequest<T>(url: string, options: RequestOptions): Promise<T>;
-    protected abstract executeStreamRequest(url: string, options: RequestOptions): Promise<ReadableStream<Uint8Array>>;
-    /**
-     * Execute the actual XHR upload
-     *
-     * This must be implemented by platform clients that support uploads.
-     * Called at the end of the upload feature chain.
-     *
-     * @param context - Request context with upload metadata
-     * @param progressCallbacks - Callbacks to invoke on progress events
-     * @param abortController - Controller for cancellation
-     * @returns Promise resolving to the response data
-     */
-    protected abstract executeXHRUpload<T>(context: RequestContext, progressCallbacks: Array<(p: UploadProgress) => void>, abortController: AbortController): Promise<T>;
-    /**
-     * Normalize an error into a ModrinthApiError
-     *
-     * Platform implementations should override this to handle platform-specific errors
-     * (e.g., FetchError from ofetch, Tauri HTTP errors)
-     */
-    protected normalizeError(error: unknown, context?: RequestContext): ModrinthApiError;
-    /**
-     * Helper to create a normalized error from extracted status code and response data
-     */
-    protected createNormalizedError(error: Error, statusCode: number | undefined, responseData: unknown): ModrinthApiError;
-    /**
-     * Add a feature to this client
-     *
-     * Features are executed in the order they are added.
-     *
-     * @example
-     * ```typescript
-     * const client = new GenericModrinthClient()
-     * client.addFeature(new AuthFeature({ token: async () => getOAuthToken() }))
-     * client.addFeature(new RetryFeature({ maxAttempts: 3 }))
-     * ```
-     */
-    addFeature(feature: AbstractFeature): this;
-    /**
-     * Remove a feature from this client
-     *
-     * @example
-     * ```typescript
-     * const retryFeature = new RetryFeature({ maxAttempts: 3 })
-     * client.addFeature(retryFeature)
-     * // Later, remove it
-     * client.removeFeature(retryFeature)
-     * ```
-     */
-    removeFeature(feature: AbstractFeature): this;
-    /**
-     * Get all features on this client
-     */
-    getFeatures(): AbstractFeature[];
-}
-export {};

package/dist/core/abstract-feature.d.ts

@@ -1,72 +0,0 @@
-import type { RequestContext } from '../types/request';
-/**
- * Base configuration for features
- */
-export interface FeatureConfig {
-    /**
-     * Optional name for this feature (for debugging)
-     */
-    name?: string;
-    /**
-     * Whether this feature is enabled
-     * @default true
-     */
-    enabled?: boolean;
-}
-/**
- * Abstract base class for request features
- *
- * Features are composable middleware that can intercept and modify requests.
- * They are executed in a chain, with each feature calling next() to continue the chain.
- */
-export declare abstract class AbstractFeature {
-    protected config: FeatureConfig;
-    constructor(config?: FeatureConfig);
-    /**
-     * Execute the feature logic
-     *
-     * @param next - Function to call the next feature in the chain (or the actual request)
-     * @param context - Full request context
-     * @returns Promise resolving to the response data
-     *
-     * @example
-     * ```typescript
-     * async execute<T>(next: () => Promise<T>, context: RequestContext): Promise<T> {
-     *   // Do something before request
-     *   console.log('Before request:', context.url)
-     *
-     *   try {
-     *     const result = await next()
-     *
-     *     // Do something after successful request
-     *     console.log('Request succeeded')
-     *
-     *     return result
-     *   } catch (error) {
-     *     // Handle errors
-     *     console.error('Request failed:', error)
-     *     throw error
-     *   }
-     * }
-     * ```
-     */
-    abstract execute<T>(next: () => Promise<T>, context: RequestContext): Promise<T>;
-    /**
-     * Determine if this feature should apply to the given request
-     *
-     * By default, features apply if they are enabled.
-     * Override this to add custom logic (e.g., only apply to GET requests).
-     *
-     * @param context - Request context
-     * @returns true if the feature should execute, false to skip
-     */
-    shouldApply(_context: RequestContext): boolean;
-    /**
-     * Get the name of this feature (for debugging)
-     */
-    get name(): string;
-    /**
-     * Check if this feature is enabled
-     */
-    get enabled(): boolean;
-}

package/dist/core/abstract-module.d.ts

@@ -1,10 +0,0 @@
-import type { AbstractModrinthClient } from './abstract-client';
-export declare abstract class AbstractModule {
-    protected client: AbstractModrinthClient;
-    constructor(client: AbstractModrinthClient);
-    /**
-     * Get the module's name, used for error reporting & for module field generation.
-     * @returns Module name
-     */
-    abstract getModuleID(): string;
-}

package/dist/core/abstract-sync.d.ts

@@ -1,61 +0,0 @@
-import type mitt from 'mitt';
-import type { Archon } from '../modules/archon/types';
-import type { RequestOptions } from '../types/request';
-export type SyncEventType = Archon.Sync.v1.SyncEvent['type'];
-export type SyncEventOfType<E extends SyncEventType> = Extract<Archon.Sync.v1.SyncEvent, {
-    type: E;
-}>;
-export type SyncEventHandler<E extends Archon.Sync.v1.SyncEvent = Archon.Sync.v1.SyncEvent> = (event: E) => void;
-export type SyncStatusState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'error';
-export type SyncStatus = {
-    state: SyncStatusState;
-    connected: boolean;
-    reconnecting: boolean;
-    reconnectAttempts: number;
-    retryDelay: number;
-    lastEventId?: string;
-    error?: unknown;
-};
-export type SyncStatusHandler = (status: SyncStatus) => void;
-export type SyncConnectOptions = {
-    intent?: Archon.Sync.v1.SyncIntent;
-    force?: boolean;
-};
-export type SyncConnection = {
-    serverId: string;
-    intent: Archon.Sync.v1.SyncIntent;
-    controller?: AbortController;
-    reconnectAttempts: number;
-    reconnectTimer?: ReturnType<typeof setTimeout>;
-    reconnectResolve?: () => void;
-    retryDelay: number;
-    lastEventId?: string;
-    stopped: boolean;
-    status: SyncStatusState;
-    error?: unknown;
-};
-export type SyncEmitterEvents = Record<string, unknown>;
-export declare abstract class AbstractSyncClient {
-    protected client: {
-        stream: (path: string, options: RequestOptions) => Promise<ReadableStream<Uint8Array>>;
-    };
-    protected connections: Map<string, SyncConnection>;
-    protected abstract emitter: ReturnType<typeof mitt<SyncEmitterEvents>>;
-    constructor(client: {
-        stream: (path: string, options: RequestOptions) => Promise<ReadableStream<Uint8Array>>;
-    });
-    abstract safeConnectServer(serverId: string, options?: SyncConnectOptions): Promise<void>;
-    abstract disconnect(serverId: string): void;
-    abstract disconnectAll(): void;
-    on<E extends SyncEventType>(serverId: string, eventType: E, handler: SyncEventHandler<SyncEventOfType<E>>): () => void;
-    onAny(serverId: string, handler: SyncEventHandler): () => void;
-    onStatus(serverId: string, handler: SyncStatusHandler): () => void;
-    getStatus(serverId: string): SyncStatus | null;
-    protected emitSyncEvent(serverId: string, event: Archon.Sync.v1.SyncEvent): void;
-    protected updateStatus(connection: SyncConnection, status: SyncStatusState, error?: unknown): void;
-    protected clearListeners(serverId: string): void;
-    protected connectionToStatus(connection: SyncConnection): SyncStatus;
-    private getEventKey;
-    private getAnyEventKey;
-    private getStatusEventKey;
-}

package/dist/core/abstract-upload-client.d.ts

@@ -1,20 +0,0 @@
-import type { UploadHandle, UploadRequestOptions } from '../types/upload';
-/**
- * Abstract base class defining upload capability
- *
- * All clients that support file uploads must extend this class.
- * Platform-specific implementations should provide the actual upload mechanism
- * (e.g., XHR for browser environments).
- *
- * Upload goes through the feature chain (auth, retry, circuit-breaker, etc.)
- * just like regular requests.
- */
-export declare abstract class AbstractUploadClient {
-    /**
-     * Upload a file or FormData with progress tracking
-     * @param path - API path (e.g., '/fs/create')
-     * @param options - Upload options including file or formData, api, version
-     * @returns UploadHandle with promise, onProgress chain, and cancel method
-     */
-    abstract upload<T = void>(path: string, options: UploadRequestOptions): UploadHandle<T>;
-}

package/dist/core/abstract-websocket.d.ts

@@ -1,52 +0,0 @@
-import type mitt from 'mitt';
-import type { Archon } from '../modules/archon/types';
-export type WebSocketEventHandler<E extends Archon.Websocket.v0.WSEvent = Archon.Websocket.v0.WSEvent> = (event: E) => void;
-export interface WebSocketConnection {
-    serverId: string;
-    socket: WebSocket;
-    reconnectAttempts: number;
-    reconnectTimer?: ReturnType<typeof setTimeout>;
-    isReconnecting: boolean;
-}
-export interface WebSocketStatus {
-    connected: boolean;
-    reconnecting: boolean;
-    reconnectAttempts: number;
-}
-type WSEventMap = {
-    [K in Archon.Websocket.v0.WSEvent as `${string}:${K['event']}`]: K;
-};
-export declare abstract class AbstractWebSocketClient {
-    protected client: {
-        archon: {
-            servers_v0: {
-                getWebSocketAuth: (serverId: string) => Promise<Archon.Websocket.v0.WSAuth>;
-            };
-        };
-    };
-    protected connections: Map<string, WebSocketConnection>;
-    protected abstract emitter: ReturnType<typeof mitt<WSEventMap>>;
-    protected readonly MAX_RECONNECT_ATTEMPTS = 10;
-    protected readonly RECONNECT_BASE_DELAY = 1000;
-    protected readonly RECONNECT_MAX_DELAY = 30000;
-    constructor(client: {
-        archon: {
-            servers_v0: {
-                getWebSocketAuth: (serverId: string) => Promise<Archon.Websocket.v0.WSAuth>;
-            };
-        };
-    });
-    abstract connect(serverId: string, auth: Archon.Websocket.v0.WSAuth): Promise<void>;
-    abstract disconnect(serverId: string): void;
-    abstract disconnectAll(): void;
-    abstract send(serverId: string, message: Archon.Websocket.v0.WSOutgoingMessage): void;
-    safeConnect(serverId: string, options?: {
-        force?: boolean;
-    }): Promise<void>;
-    on<E extends Archon.Websocket.v0.WSEventType>(serverId: string, eventType: E, handler: WebSocketEventHandler<Extract<Archon.Websocket.v0.WSEvent, {
-        event: E;
-    }>>): () => void;
-    getStatus(serverId: string): WebSocketStatus | null;
-    protected getReconnectDelay(attempt: number): number;
-}
-export {};

package/dist/core/errors.d.ts

@@ -1,48 +0,0 @@
-import type { ApiErrorData, ModrinthErrorResponse } from '../types/errors';
-/**
- * Base error class for all Modrinth API errors
- */
-export declare class ModrinthApiError extends Error {
-    /**
-     * HTTP status code (if available)
-     */
-    readonly statusCode?: number;
-    /**
-     * Original error that was caught
-     */
-    readonly originalError?: Error;
-    /**
-     * Response data from the API (if available)
-     */
-    readonly responseData?: unknown;
-    /**
-     * Error context (e.g., module name, operation being performed)
-     */
-    readonly context?: string;
-    constructor(message: string, data?: ApiErrorData);
-    /**
-     * Create a ModrinthApiError from an unknown error
-     */
-    static fromUnknown(error: unknown, context?: string): ModrinthApiError;
-}
-/**
- * Error class for Modrinth server errors (kyros/archon)
- * Extends ModrinthApiError with V1 error response parsing
- */
-export declare class ModrinthServerError extends ModrinthApiError {
-    /**
-     * V1 error information (if available)
-     */
-    readonly v1Error?: ModrinthErrorResponse;
-    constructor(message: string, data?: ApiErrorData & {
-        v1Error?: ModrinthErrorResponse;
-    });
-    /**
-     * Create a ModrinthServerError from response data
-     */
-    static fromResponse(statusCode: number, responseData: unknown, context?: string): ModrinthServerError;
-    /**
-     * Create a ModrinthServerError from an unknown error
-     */
-    static fromUnknown(error: unknown, context?: string): ModrinthServerError;
-}

package/dist/features/auth.d.ts

@@ -1,47 +0,0 @@
-import { AbstractFeature, type FeatureConfig } from '../core/abstract-feature';
-import type { RequestContext } from '../types/request';
-/**
- * Authentication feature configuration
- */
-export interface AuthConfig extends FeatureConfig {
-    /**
-     * Authentication token
-     * - string: static token
-     * - function: async function that returns token (useful for dynamic tokens)
-     */
-    token: string | (() => Promise<string | undefined>);
-    /**
-     * Token prefix (e.g., 'Bearer', 'Token')
-     * @default 'Bearer'
-     */
-    tokenPrefix?: string;
-    /**
-     * Custom header name for the token
-     * @default 'Authorization'
-     */
-    headerName?: string;
-}
-/**
- * Authentication feature
- *
- * Automatically injects authentication tokens into request headers.
- * Supports both static tokens and dynamic token providers.
- *
- * @example
- * ```typescript
- * const auth = new AuthFeature({
- *   token: async () => process.env.MODRINTH_TOKEN
- * })
- * ```
- */
-export declare class AuthFeature extends AbstractFeature {
-    protected config: AuthConfig;
-    execute<T>(next: () => Promise<T>, context: RequestContext): Promise<T>;
-    shouldApply(context: RequestContext): boolean;
-    /**
-     * Get the authentication token
-     *
-     * Handles both static tokens and async token providers
-     */
-    private getToken;
-}

package/dist/features/circuit-breaker.d.ts

@@ -1,139 +0,0 @@
-import { AbstractFeature, type FeatureConfig } from '../core/abstract-feature';
-import type { RequestContext } from '../types/request';
-/**
- * Circuit breaker state
- */
-export type CircuitBreakerState = {
-    /**
-     * Number of consecutive failures
-     */
-    failures: number;
-    /**
-     * Timestamp of last failure
-     */
-    lastFailure: number;
-};
-/**
- * Circuit breaker storage interface
- */
-export interface CircuitBreakerStorage {
-    /**
-     * Get circuit breaker state for a key
-     */
-    get(key: string): CircuitBreakerState | undefined;
-    /**
-     * Set circuit breaker state for a key
-     */
-    set(key: string, state: CircuitBreakerState): void;
-    /**
-     * Clear circuit breaker state for a key
-     */
-    clear?(key: string): void;
-}
-/**
- * Circuit breaker feature configuration
- */
-export interface CircuitBreakerConfig extends FeatureConfig {
-    /**
-     * Maximum number of consecutive failures before opening circuit
-     * @default 3
-     */
-    maxFailures?: number;
-    /**
-     * Time in milliseconds before circuit resets after opening
-     * @default 30000
-     */
-    resetTimeout?: number;
-    /**
-     * HTTP status codes that count as failures
-     * @default [500, 502, 503, 504]
-     */
-    failureStatusCodes?: number[];
-    /**
-     * Storage implementation for circuit state
-     * If not provided, uses in-memory Map
-     */
-    storage?: CircuitBreakerStorage;
-    /**
-     * Function to generate circuit key from request context
-     * By default, uses the base path (without query params)
-     */
-    getCircuitKey?: (url: string, method: string) => string;
-}
-/**
- * In-memory storage for circuit breaker state
- */
-export declare class InMemoryCircuitBreakerStorage implements CircuitBreakerStorage {
-    private state;
-    get(key: string): CircuitBreakerState | undefined;
-    set(key: string, state: CircuitBreakerState): void;
-    clear(key: string): void;
-}
-/**
- * Circuit breaker feature
- *
- * Prevents requests to failing endpoints by "opening the circuit" after
- * a threshold of consecutive failures. The circuit automatically resets
- * after a timeout period.
- *
- * This implements the circuit breaker pattern to prevent cascading failures
- * and give failing services time to recover.
- *
- * @example
- * ```typescript
- * const circuitBreaker = new CircuitBreakerFeature({
- *   maxFailures: 3,
- *   resetTimeout: 30000, // 30 seconds
- *   failureStatusCodes: [500, 502, 503, 504]
- * })
- * ```
- */
-export declare class CircuitBreakerFeature extends AbstractFeature {
-    protected config: Required<CircuitBreakerConfig>;
-    private storage;
-    constructor(config?: CircuitBreakerConfig);
-    execute<T>(next: () => Promise<T>, context: RequestContext): Promise<T>;
-    shouldApply(context: RequestContext): boolean;
-    /**
-     * Get the circuit key for a request
-     *
-     * By default, uses the path and method to identify unique circuits
-     */
-    private getCircuitKey;
-    /**
-     * Check if the circuit is open for a given key
-     */
-    private isCircuitOpen;
-    /**
-     * Record a successful request
-     */
-    private recordSuccess;
-    /**
-     * Record a failed request
-     */
-    private recordFailure;
-    /**
-     * Determine if an error should count as a circuit failure
-     */
-    private isFailureError;
-    /**
-     * Get current circuit state for debugging
-     *
-     * @example
-     * ```typescript
-     * const state = circuitBreaker.getCircuitState('GET_/v2/project/sodium')
-     * console.log(`Failures: ${state?.failures}, Last failure: ${state?.lastFailure}`)
-     * ```
-     */
-    getCircuitState(key: string): CircuitBreakerState | undefined;
-    /**
-     * Manually reset a circuit
-     *
-     * @example
-     * ```typescript
-     * // Reset circuit after manual intervention
-     * circuitBreaker.resetCircuit('GET_/v2/project/sodium')
-     * ```
-     */
-    resetCircuit(key: string): void;
-}