lexmount 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,492 @@
+import { AxiosResponse } from 'axios';
+
+/**
+ * Supported SDK log levels.
+ */
+type LogLevel = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL' | 'SILENT';
+/**
+ * Shared SDK logger.
+ */
+declare class LexmountLogger {
+    /**
+     * Current SDK log level.
+     */
+    get level(): LogLevel;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    critical(...args: unknown[]): void;
+}
+/**
+ * Return the shared SDK logger instance.
+ */
+declare function getLogger(): LexmountLogger;
+/**
+ * Set the SDK log level.
+ */
+declare function setLogLevel(level: LogLevel | string): void;
+/**
+ * Disable all SDK logging.
+ */
+declare function disableLogging(): void;
+/**
+ * Re-enable SDK logging.
+ */
+declare function enableLogging(level?: LogLevel | string): void;
+
+/**
+ * Browser modes supported by the Lexmount API.
+ */
+type BrowserMode = 'normal' | 'light';
+/**
+ * Session status returned by the API.
+ */
+type SessionStatus = 'active' | 'closed' | string;
+/**
+ * Context status returned by the API.
+ */
+type ContextStatus = 'available' | 'locked' | string;
+/**
+ * Supported context access modes.
+ *
+ * The camelCase values are recommended for the Node SDK.
+ * The snake_case values are accepted for convenience and mapped internally.
+ */
+type ContextAccessMode = 'readWrite' | 'readOnly' | 'read_write' | 'read_only';
+/**
+ * Context selection when creating a session.
+ */
+interface SessionContext {
+    /**
+     * Context identifier.
+     */
+    id: string;
+    /**
+     * Context access mode.
+     */
+    mode: ContextAccessMode;
+}
+/**
+ * SDK client configuration.
+ */
+interface LexmountConfig {
+    /**
+     * API key for authentication.
+     */
+    apiKey?: string;
+    /**
+     * Project identifier.
+     */
+    projectId?: string;
+    /**
+     * API base URL.
+     *
+     * Defaults to `https://api.lexmount.cn`.
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     *
+     * Defaults to 60000.
+     */
+    timeout?: number;
+    /**
+     * Optional SDK log level.
+     */
+    logLevel?: LogLevel;
+}
+/**
+ * Session creation options.
+ */
+interface SessionCreateOptions {
+    /**
+     * Override the default project identifier.
+     */
+    projectId?: string;
+    /**
+     * Browser mode to start.
+     */
+    browserMode?: BrowserMode;
+    /**
+     * Optional persistent context configuration.
+     */
+    context?: SessionContext;
+}
+/**
+ * Session list options.
+ */
+interface SessionListOptions {
+    /**
+     * Override the default project identifier.
+     */
+    projectId?: string;
+    /**
+     * Optional session status filter.
+     */
+    status?: SessionStatus;
+}
+/**
+ * Session deletion options.
+ */
+interface SessionDeleteOptions {
+    /**
+     * Session identifier to delete.
+     */
+    sessionId: string;
+    /**
+     * Override the default project identifier.
+     */
+    projectId?: string;
+}
+/**
+ * Metadata attached to a context.
+ */
+type ContextMetadata = Record<string, unknown>;
+/**
+ * Context creation options.
+ */
+interface ContextCreateOptions {
+    /**
+     * Optional metadata used to organize contexts.
+     */
+    metadata?: ContextMetadata;
+}
+/**
+ * Context list options.
+ */
+interface ContextListOptions {
+    /**
+     * Optional context status filter.
+     */
+    status?: ContextStatus;
+    /**
+     * Maximum number of contexts to return.
+     *
+     * Defaults to 20.
+     */
+    limit?: number;
+}
+/**
+ * Context force-release response.
+ */
+interface ForceReleaseResponse {
+    status: string;
+    message: string;
+}
+/**
+ * Session pagination metadata.
+ */
+interface PaginationInfoShape {
+    currentPage: number;
+    pageSize: number;
+    totalCount: number;
+    totalPages: number;
+    activeCount: number;
+    closedCount: number;
+}
+
+/**
+ * Context resource implementation.
+ */
+
+/**
+ * Context information returned by the API.
+ */
+declare class ContextInfo {
+    readonly id: string;
+    readonly status: ContextStatus;
+    readonly metadata: ContextMetadata;
+    readonly createdAt: string | null;
+    readonly updatedAt: string | null;
+    constructor(options: {
+        id: string;
+        status: ContextStatus;
+        metadata?: ContextMetadata;
+        createdAt?: string | null;
+        updatedAt?: string | null;
+    });
+    get createdAtDate(): Date | null;
+    get updatedAtDate(): Date | null;
+    isLocked(): boolean;
+    isAvailable(): boolean;
+}
+/**
+ * Response object from `contexts.list()`.
+ */
+declare class ContextListResponse implements Iterable<ContextInfo> {
+    readonly data: ContextInfo[];
+    constructor(data: ContextInfo[]);
+    get length(): number;
+    [Symbol.iterator](): Iterator<ContextInfo>;
+    at(index: number): ContextInfo | undefined;
+}
+/**
+ * Context resource operations.
+ */
+declare class ContextsResource {
+    private readonly client;
+    constructor(client: Lexmount);
+    /**
+     * Create a new persistent context.
+     */
+    create(options?: ContextCreateOptions): Promise<ContextInfo>;
+    /**
+     * List contexts in the current project.
+     */
+    list(options?: ContextListOptions): Promise<ContextListResponse>;
+    /**
+     * Fetch a single context.
+     */
+    get(contextId: string): Promise<ContextInfo>;
+    /**
+     * Delete a persistent context.
+     */
+    delete(contextId: string): Promise<void>;
+    /**
+     * Force-release a stuck lock on a context.
+     */
+    forceRelease(contextId: string): Promise<ForceReleaseResponse>;
+    private handleError;
+}
+
+/**
+ * Session resource implementation.
+ */
+
+/**
+ * Session pagination information.
+ */
+declare class PaginationInfo implements PaginationInfoShape {
+    readonly currentPage: number;
+    readonly pageSize: number;
+    readonly totalCount: number;
+    readonly totalPages: number;
+    readonly activeCount: number;
+    readonly closedCount: number;
+    constructor(shape: PaginationInfoShape);
+}
+interface SessionInfoOptions {
+    id: string;
+    status: SessionStatus;
+    apiKey: string;
+    projectId: string;
+    browserType: BrowserMode | string;
+    createdAt: string;
+    inspectUrl: string;
+    containerId: string | null;
+    inspectUrlDbg?: string;
+    ws?: string | null;
+    client?: Lexmount;
+}
+/**
+ * Session information returned by the API.
+ */
+declare class SessionInfo {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly status: SessionStatus;
+    readonly apiKey: string;
+    readonly projectId: string;
+    readonly browserType: BrowserMode | string;
+    readonly createdAt: string;
+    readonly inspectUrl: string;
+    readonly containerId: string | null;
+    readonly inspectUrlDbg?: string;
+    readonly ws: string | null;
+    private readonly client?;
+    private closed;
+    /** @internal */
+    constructor(options: SessionInfoOptions);
+    /**
+     * Playwright/CDP connection URL.
+     */
+    get connectUrl(): string;
+    /**
+     * Parsed session creation time.
+     */
+    get createdAtDate(): Date | null;
+    /**
+     * Close the current session.
+     *
+     * This method is idempotent. Errors are logged and swallowed to keep cleanup safe.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Response object from `sessions.list()`.
+ */
+declare class SessionListResponse implements Iterable<SessionInfo> {
+    readonly sessions: SessionInfo[];
+    readonly pagination: PaginationInfo;
+    constructor(sessions: SessionInfo[], pagination: PaginationInfo);
+    /**
+     * Number of sessions in the current page.
+     */
+    get length(): number;
+    [Symbol.iterator](): Iterator<SessionInfo>;
+    at(index: number): SessionInfo | undefined;
+}
+/**
+ * Alias kept for parity with the Python SDK.
+ */
+type SessionCreateResponse = SessionInfo;
+/**
+ * Session resource operations.
+ */
+declare class SessionsResource {
+    private readonly client;
+    constructor(client: Lexmount);
+    /**
+     * Create a new browser session.
+     */
+    create(options?: SessionCreateOptions): Promise<SessionCreateResponse>;
+    /**
+     * List sessions for the current project.
+     */
+    list(options?: SessionListOptions): Promise<SessionListResponse>;
+    /**
+     * Delete a browser session.
+     */
+    delete(options: SessionDeleteOptions): Promise<void>;
+    /**
+     * Fetch the debugger WebSocket URL for a session.
+     *
+     * @internal
+     */
+    _getWebSocketDebuggerUrl(sessionId: string): Promise<string | null>;
+    private handleCreateError;
+    private handleListError;
+    private handleDeleteError;
+}
+
+/**
+ * Lexmount API client.
+ */
+
+/**
+ * Main Lexmount SDK client.
+ */
+declare class Lexmount {
+    /**
+     * API key used for authentication.
+     */
+    readonly apiKey: string;
+    /**
+     * Default project identifier used by resource methods.
+     */
+    readonly projectId: string;
+    /**
+     * API base URL.
+     */
+    readonly baseUrl: string;
+    /**
+     * Session operations.
+     */
+    readonly sessions: SessionsResource;
+    /**
+     * Persistent context operations.
+     */
+    readonly contexts: ContextsResource;
+    private readonly httpClient;
+    constructor(config?: LexmountConfig);
+    /**
+     * Internal POST request helper with timeout and network error mapping.
+     *
+     * @internal
+     */
+    _post<T = unknown>(url: string, data: Record<string, unknown>): Promise<AxiosResponse<T>>;
+    /**
+     * Internal GET request helper with timeout and network error mapping.
+     *
+     * @internal
+     */
+    _get<T = unknown>(url: string, params: Record<string, unknown>): Promise<AxiosResponse<T>>;
+    /**
+     * Internal DELETE request helper with timeout and network error mapping.
+     *
+     * @internal
+     */
+    _delete<T = unknown>(url: string, data: Record<string, unknown>): Promise<AxiosResponse<T>>;
+    /**
+     * Close the client.
+     *
+     * Axios does not require explicit teardown, but the method is kept for API symmetry.
+     */
+    close(): void;
+    /**
+     * String representation of the client.
+     */
+    toString(): string;
+    private request;
+    private normalizeRequestError;
+}
+
+/**
+ * Lexmount SDK error hierarchy.
+ */
+/**
+ * Base error for all Lexmount SDK failures.
+ */
+declare class LexmountError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when API authentication fails.
+ */
+declare class AuthenticationError extends LexmountError {
+}
+/**
+ * Raised when a session cannot be found.
+ */
+declare class SessionNotFoundError extends LexmountError {
+}
+/**
+ * Raised when a context cannot be found.
+ */
+declare class ContextNotFoundError extends LexmountError {
+}
+/**
+ * Raised when a context is locked by another active session.
+ */
+declare class ContextLockedError extends LexmountError {
+    readonly activeSessionId?: string;
+    readonly retryAfter?: number;
+    constructor(message: string, options?: {
+        activeSessionId?: string;
+        retryAfter?: number;
+    });
+}
+/**
+ * Raised when the Lexmount API returns a non-success response.
+ */
+declare class APIError extends LexmountError {
+    readonly statusCode?: number;
+    readonly response?: unknown;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        response?: unknown;
+    });
+}
+/**
+ * Raised when a network error prevents the request from reaching the API.
+ */
+declare class NetworkError extends LexmountError {
+}
+/**
+ * Raised when input validation fails.
+ */
+declare class ValidationError extends LexmountError {
+}
+/**
+ * Raised when a request exceeds the configured timeout.
+ */
+declare class TimeoutError extends LexmountError {
+}
+
+/**
+ * Lexmount Node.js SDK.
+ */
+declare const VERSION = "0.2.0";
+
+export { APIError, AuthenticationError, type BrowserMode, type ContextAccessMode, type ContextCreateOptions, ContextInfo, type ContextListOptions, ContextListResponse, ContextLockedError, type ContextMetadata, ContextNotFoundError, type ContextStatus, ContextsResource, type ForceReleaseResponse, Lexmount, type LexmountConfig, LexmountError, LexmountLogger, type LogLevel, NetworkError, PaginationInfo, type PaginationInfoShape, type SessionContext, type SessionCreateOptions, type SessionCreateResponse, type SessionDeleteOptions, SessionInfo, type SessionListOptions, SessionListResponse, SessionNotFoundError, type SessionStatus, SessionsResource, TimeoutError, VERSION, ValidationError, Lexmount as default, disableLogging, enableLogging, getLogger, setLogLevel };