krawlet-js 2.1.2 → 2.2.1

package/dist/index.cjs

@@ -31,7 +31,9 @@ __export(index_exports, {
   ReportsResource: () => ReportsResource,
   ShopsResource: () => ShopsResource,
   StorageResource: () => StorageResource,
-  TransfersResource: () => TransfersResource
+  TransfersResource: () => TransfersResource,
+  WebsocketProtocolError: () => WebsocketProtocolError,
+  WebsocketsResource: () => WebsocketsResource
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -88,6 +90,12 @@ var HttpClient = class {
   getRateLimit() {
     return this.lastRateLimit;
   }
+  /**
+   * Get configured API base URL
+   */
+  getBaseUrl() {
+    return this.config.baseUrl;
+  }
   /**
    * Make an HTTP request
    */
@@ -828,6 +836,308 @@ var TransfersResource = class {
   }
 };
 
+// src/resources/websockets.ts
+var WebsocketProtocolError = class extends Error {
+  constructor(message, code, requestId) {
+    super(message);
+    this.name = "WebsocketProtocolError";
+    this.code = code;
+    this.requestId = requestId;
+  }
+};
+var WebsocketsResource = class {
+  constructor(client, options = {}) {
+    this.client = client;
+    this.ws = null;
+    this.connectPromise = null;
+    this.pending = /* @__PURE__ */ new Map();
+    this.transferUpdateListeners = /* @__PURE__ */ new Set();
+    this.nextRequestId = 1;
+    this.connectTimeoutMs = options.connectTimeoutMs ?? 1e4;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 15e3;
+    this.webSocketFactory = options.webSocketFactory ?? this.getDefaultWebSocketFactory();
+  }
+  /**
+   * Open websocket connection and wait for initial hello
+   */
+  async start() {
+    if (this.connectPromise) {
+      return this.connectPromise;
+    }
+    const url = this.buildWebSocketUrl();
+    this.connectPromise = new Promise((resolve, reject) => {
+      const ws = this.webSocketFactory(url);
+      this.ws = ws;
+      const timeout = setTimeout(() => {
+        this.connectPromise = null;
+        this.ws = null;
+        try {
+          ws.close();
+        } catch {
+        }
+        reject(new Error(`WebSocket connection timeout after ${this.connectTimeoutMs}ms`));
+      }, this.connectTimeoutMs);
+      ws.onopen = () => {
+      };
+      ws.onmessage = (event) => {
+        this.handleMessageEvent(event.data, resolve, reject, timeout);
+      };
+      ws.onerror = () => {
+        clearTimeout(timeout);
+        this.connectPromise = null;
+        this.ws = null;
+        reject(new Error("WebSocket connection failed"));
+      };
+      ws.onclose = (event) => {
+        clearTimeout(timeout);
+        this.connectPromise = null;
+        this.ws = null;
+        this.rejectAllPending(
+          new Error(`WebSocket closed (${event.code}${event.reason ? `: ${event.reason}` : ""})`)
+        );
+      };
+    });
+    return this.connectPromise;
+  }
+  /**
+   * Authenticate this connection as a client key
+   */
+  async authenticate(token, id = this.createRequestId()) {
+    const response = await this.sendAndWait("auth", {
+      type: "auth",
+      id,
+      token
+    });
+    if (response.type !== "auth_ok") {
+      throw new Error(`Unexpected auth response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * Ping the websocket server
+   */
+  async ping(id = this.createRequestId()) {
+    const response = await this.sendAndWait("ping", {
+      type: "ping",
+      id
+    });
+    if (response.type !== "pong") {
+      throw new Error(`Unexpected ping response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * Create a transfer over websocket
+   */
+  async createTransfer(payload, id = this.createRequestId()) {
+    const response = await this.sendAndWait("create_transfer", {
+      type: "create_transfer",
+      id,
+      payload
+    });
+    if (response.type !== "create_transfer_ok") {
+      throw new Error(`Unexpected create_transfer response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * Fetch transfer by id
+   */
+  async getTransfer(transferId, id = this.createRequestId()) {
+    const response = await this.sendAndWait("get_transfer", {
+      type: "get_transfer",
+      id,
+      payload: { transferId }
+    });
+    if (response.type !== "get_transfer_ok") {
+      throw new Error(`Unexpected get_transfer response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * Cancel transfer by id
+   */
+  async cancelTransfer(transferId, id = this.createRequestId()) {
+    const response = await this.sendAndWait("cancel_transfer", {
+      type: "cancel_transfer",
+      id,
+      payload: { transferId }
+    });
+    if (response.type !== "cancel_transfer_ok") {
+      throw new Error(`Unexpected cancel_transfer response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * List transfers for this client
+   */
+  async listTransfers(id = this.createRequestId()) {
+    const response = await this.sendAndWait("list_transfers", {
+      type: "list_transfers",
+      id,
+      payload: {}
+    });
+    if (response.type !== "list_transfers_ok") {
+      throw new Error(`Unexpected list_transfers response type: ${response.type}`);
+    }
+    return response.payload.transfers;
+  }
+  /**
+   * List targets available to this client
+   */
+  async listTargets(id = this.createRequestId()) {
+    const response = await this.sendAndWait("list_targets", {
+      type: "list_targets",
+      id,
+      payload: {}
+    });
+    if (response.type !== "list_targets_ok") {
+      throw new Error(`Unexpected list_targets response type: ${response.type}`);
+    }
+    return response.payload.targets;
+  }
+  /**
+   * Subscribe to unsolicited transfer updates.
+   * Returns an unsubscribe function.
+   */
+  onTransferUpdate(listener) {
+    this.transferUpdateListeners.add(listener);
+    return () => {
+      this.transferUpdateListeners.delete(listener);
+    };
+  }
+  /**
+   * Close the websocket connection
+   */
+  close(code, reason) {
+    if (!this.ws) {
+      return;
+    }
+    try {
+      this.ws.close(code, reason);
+    } finally {
+      this.ws = null;
+      this.connectPromise = null;
+      this.rejectAllPending(new Error("WebSocket connection closed"));
+    }
+  }
+  /**
+   * True if the websocket is currently open
+   */
+  isConnected() {
+    return Boolean(this.ws && this.ws.readyState === 1);
+  }
+  async sendAndWait(messageType, message) {
+    if (!this.ws || this.ws.readyState !== 1) {
+      await this.start();
+    }
+    if (!this.ws || this.ws.readyState !== 1) {
+      throw new Error("WebSocket is not connected");
+    }
+    const requestId = message.id;
+    const responsePromise = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(requestId);
+        reject(new Error(`WebSocket ${messageType} request timed out after ${this.requestTimeoutMs}ms`));
+      }, this.requestTimeoutMs);
+      this.pending.set(requestId, {
+        resolve: (value) => resolve(value),
+        reject,
+        timeout
+      });
+    });
+    this.ws.send(JSON.stringify(message));
+    return responsePromise;
+  }
+  handleMessageEvent(rawData, connectResolve, connectReject, connectTimeout) {
+    const parsed = this.safeParse(rawData);
+    if (!parsed) {
+      return;
+    }
+    if (parsed.type === "hello") {
+      clearTimeout(connectTimeout);
+      connectResolve(parsed);
+      return;
+    }
+    if (parsed.type === "transfer_update") {
+      this.emitTransferUpdate(parsed.payload);
+      return;
+    }
+    if (typeof parsed.id === "undefined") {
+      if (parsed.type === "error") {
+        const payload = parsed.payload;
+        connectReject(new WebsocketProtocolError(payload.message, payload.code));
+      }
+      return;
+    }
+    const pending = this.pending.get(parsed.id);
+    if (!pending) {
+      return;
+    }
+    clearTimeout(pending.timeout);
+    this.pending.delete(parsed.id);
+    if (parsed.type === "error") {
+      const payload = parsed.payload;
+      pending.reject(new WebsocketProtocolError(payload.message, payload.code, parsed.id));
+      return;
+    }
+    pending.resolve(parsed);
+  }
+  emitTransferUpdate(transfer) {
+    for (const listener of this.transferUpdateListeners) {
+      listener(transfer);
+    }
+  }
+  safeParse(rawData) {
+    try {
+      const parsed = JSON.parse(rawData);
+      if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string") {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  createRequestId() {
+    const id = this.nextRequestId;
+    this.nextRequestId += 1;
+    return id;
+  }
+  rejectAllPending(error) {
+    for (const entry of this.pending.values()) {
+      clearTimeout(entry.timeout);
+      entry.reject(error);
+    }
+    this.pending.clear();
+  }
+  buildWebSocketUrl() {
+    const base = new URL(this.client.getBaseUrl());
+    base.protocol = base.protocol === "https:" ? "wss:" : "ws:";
+    const trimmedPath = base.pathname.replace(/\/+$/, "");
+    if (trimmedPath.endsWith("/api/v1")) {
+      base.pathname = `${trimmedPath}/ws`;
+    } else if (trimmedPath.endsWith("/api")) {
+      base.pathname = `${trimmedPath}/v1/ws`;
+    } else if (trimmedPath.endsWith("/v1")) {
+      base.pathname = `${trimmedPath}/ws`;
+    } else {
+      base.pathname = "/v1/ws";
+    }
+    base.search = "";
+    base.hash = "";
+    return base.toString();
+  }
+  getDefaultWebSocketFactory() {
+    return (url) => {
+      if (typeof globalThis.WebSocket === "undefined") {
+        throw new Error("WebSocket is not available. Provide a webSocketFactory in WebsocketsResource options.");
+      }
+      return new globalThis.WebSocket(url);
+    };
+  }
+};
+
 // src/client.ts
 var KrawletClient = class {
   /**
@@ -854,6 +1164,7 @@ var KrawletClient = class {
     this.reports = new ReportsResource(this.httpClient);
     this.apiKey = new ApiKeyResource(this.httpClient);
     this.transfers = new TransfersResource(this.httpClient);
+    this.websockets = new WebsocketsResource(this.httpClient);
   }
   /**
    * Get the last known rate limit information
@@ -894,5 +1205,7 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ReportsResource,
   ShopsResource,
   StorageResource,
-  TransfersResource
+  TransfersResource,
+  WebsocketProtocolError,
+  WebsocketsResource
 });

package/dist/index.d.cts

@@ -458,6 +458,31 @@ interface PublicStorageTransferResponse {
     transfer: Transfer;
     sourceEntity: PublicStorageSourceEntity;
 }
+type WebsocketMessageId = string | number;
+interface WebsocketEnvelope<TPayload = unknown> {
+    type: string;
+    id?: WebsocketMessageId;
+    payload: TPayload;
+}
+interface WebsocketErrorPayload {
+    code: string;
+    message: string;
+}
+interface WebsocketHelloPayload {
+    supportedClientMessages?: string[];
+    [key: string]: unknown;
+}
+interface WebsocketAuthOk {
+    tier: ApiKeyTier;
+    name: string;
+    role: 'client';
+}
+interface WebsocketTransferListPayload {
+    transfers: Transfer[];
+}
+interface WebsocketTargetListPayload {
+    targets: TransferTarget[];
+}
 interface ReportRecords<TRecord = unknown> {
     count: number;
     records: TRecord[];
@@ -522,6 +547,7 @@ declare class HttpClient {
     private lastRateLimit?;
     constructor(config: HttpClientConfig);
     getRateLimit(): RateLimit | undefined;
+    getBaseUrl(): string;
     request<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
     private buildUrl;
     private buildHeaders;
@@ -632,6 +658,62 @@ declare class TransfersResource {
     requestPublicStorage(data: PublicStorageTransferRequest): Promise<PublicStorageTransferResponse>;
 }
 
+interface WebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: string;
+    }) => void) | null;
+    onerror: (() => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+}
+interface WebsocketClientOptions {
+    connectTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    webSocketFactory?: (url: string) => WebSocketLike;
+}
+declare class WebsocketProtocolError extends Error {
+    readonly code: string;
+    readonly requestId?: WebsocketMessageId;
+    constructor(message: string, code: string, requestId?: WebsocketMessageId);
+}
+declare class WebsocketsResource {
+    private client;
+    private ws;
+    private connectPromise;
+    private pending;
+    private transferUpdateListeners;
+    private nextRequestId;
+    private readonly connectTimeoutMs;
+    private readonly requestTimeoutMs;
+    private readonly webSocketFactory;
+    constructor(client: HttpClient, options?: WebsocketClientOptions);
+    start(): Promise<WebsocketEnvelope>;
+    authenticate(token: string, id?: WebsocketMessageId): Promise<WebsocketAuthOk>;
+    ping(id?: WebsocketMessageId): Promise<number>;
+    createTransfer(payload: TransferCreateRequest, id?: WebsocketMessageId): Promise<Transfer>;
+    getTransfer(transferId: string, id?: WebsocketMessageId): Promise<Transfer>;
+    cancelTransfer(transferId: string, id?: WebsocketMessageId): Promise<Transfer>;
+    listTransfers(id?: WebsocketMessageId): Promise<Transfer[]>;
+    listTargets(id?: WebsocketMessageId): Promise<TransferTarget[]>;
+    onTransferUpdate(listener: (transfer: Transfer) => void): () => void;
+    close(code?: number, reason?: string): void;
+    isConnected(): boolean;
+    private sendAndWait;
+    private handleMessageEvent;
+    private emitTransferUpdate;
+    private safeParse;
+    private createRequestId;
+    private rejectAllPending;
+    private buildWebSocketUrl;
+    private getDefaultWebSocketFactory;
+}
+
 interface KrawletClientConfig {
     baseUrl?: string;
     apiKey?: string;
@@ -652,6 +734,7 @@ declare class KrawletClient {
     readonly reports: ReportsResource;
     readonly apiKey: ApiKeyResource;
     readonly transfers: TransfersResource;
+    readonly websockets: WebsocketsResource;
     constructor(config?: KrawletClientConfig);
     getRateLimit(): RateLimit | undefined;
 }
@@ -668,4 +751,4 @@ declare class KrawletError extends Error {
     isRateLimitError(): boolean;
 }
 
-export { AddressesResource, type ApiKeyInfo, ApiKeyResource, type ApiKeyTier, type ApiKeyUsage, type ApiResponse, type ApiResponseMeta, type BaseQueryParams, type ChangeLogOptions, type ChangeLogResult, type ChatboxServiceInfo, type DetailedHealthResponse, type DiscordServiceInfo, type EStorageEntityType, type EnderStorageApiPayload, type EnderStorageChest, type EnderStorageCollection, type EnderStorageColor, type EnderStorageItem, type EnderStorageMeta, type EnderStoragePayload, ErrorCode, type ErrorResponse, type HealthChecks, HealthResource, type HealthResponse, type HealthServices, type HealthServicesDetailed, type Item, type ItemChangeLog, type ItemChangeLogResponse, type ItemChangeRecord, type ItemChangeType, type ItemChangesParams, type ItemSummary, type ItemUpdateSummary, ItemsResource, type KnownAddress, type KnownAddressType, KrawletClient, type KrawletClientConfig, KrawletError, type KromerServiceInfo, type Player, type PlayerNotifications, PlayersResource, type Price, type PriceChangeLog, type PriceChangeLogResponse, type PriceChangesParams, type PublicStorageSourceEntity, type PublicStorageTransferRequest, type PublicStorageTransferResponse, type QuickCodeGenerateResponse, type QuickCodeRedeemResponse, type RateLimit, type ReportRecords, type ReporterStats, ReportsResource, type RequestLog, type RequestLogsResponse, type ServiceInfo, type ServiceName, type ServiceStatus, type Shop, type ShopChangeField, type ShopChangeLog, type ShopChangeLogResponse, type ShopChangeRecord, type ShopChangesParams, type ShopSourceType, type ShopSyncData, ShopsResource, type StorageData, StorageResource, type StorageSlotContents, type StorageSlotItem, type SuccessfulPostRecord, type Transfer, type TransferCreateRequest, type TransferStatus, type TransferTarget, type TransferTargetLink, TransfersResource, type ValidationFailureRecord };
+export { AddressesResource, type ApiKeyInfo, ApiKeyResource, type ApiKeyTier, type ApiKeyUsage, type ApiResponse, type ApiResponseMeta, type BaseQueryParams, type ChangeLogOptions, type ChangeLogResult, type ChatboxServiceInfo, type DetailedHealthResponse, type DiscordServiceInfo, type EStorageEntityType, type EnderStorageApiPayload, type EnderStorageChest, type EnderStorageCollection, type EnderStorageColor, type EnderStorageItem, type EnderStorageMeta, type EnderStoragePayload, ErrorCode, type ErrorResponse, type HealthChecks, HealthResource, type HealthResponse, type HealthServices, type HealthServicesDetailed, type Item, type ItemChangeLog, type ItemChangeLogResponse, type ItemChangeRecord, type ItemChangeType, type ItemChangesParams, type ItemSummary, type ItemUpdateSummary, ItemsResource, type KnownAddress, type KnownAddressType, KrawletClient, type KrawletClientConfig, KrawletError, type KromerServiceInfo, type Player, type PlayerNotifications, PlayersResource, type Price, type PriceChangeLog, type PriceChangeLogResponse, type PriceChangesParams, type PublicStorageSourceEntity, type PublicStorageTransferRequest, type PublicStorageTransferResponse, type QuickCodeGenerateResponse, type QuickCodeRedeemResponse, type RateLimit, type ReportRecords, type ReporterStats, ReportsResource, type RequestLog, type RequestLogsResponse, type ServiceInfo, type ServiceName, type ServiceStatus, type Shop, type ShopChangeField, type ShopChangeLog, type ShopChangeLogResponse, type ShopChangeRecord, type ShopChangesParams, type ShopSourceType, type ShopSyncData, ShopsResource, type StorageData, StorageResource, type StorageSlotContents, type StorageSlotItem, type SuccessfulPostRecord, type Transfer, type TransferCreateRequest, type TransferStatus, type TransferTarget, type TransferTargetLink, TransfersResource, type ValidationFailureRecord, type WebsocketAuthOk, type WebsocketClientOptions, type WebsocketEnvelope, type WebsocketErrorPayload, type WebsocketHelloPayload, type WebsocketMessageId, WebsocketProtocolError, type WebsocketTargetListPayload, type WebsocketTransferListPayload, WebsocketsResource };

package/dist/index.d.ts

@@ -458,6 +458,31 @@ interface PublicStorageTransferResponse {
     transfer: Transfer;
     sourceEntity: PublicStorageSourceEntity;
 }
+type WebsocketMessageId = string | number;
+interface WebsocketEnvelope<TPayload = unknown> {
+    type: string;
+    id?: WebsocketMessageId;
+    payload: TPayload;
+}
+interface WebsocketErrorPayload {
+    code: string;
+    message: string;
+}
+interface WebsocketHelloPayload {
+    supportedClientMessages?: string[];
+    [key: string]: unknown;
+}
+interface WebsocketAuthOk {
+    tier: ApiKeyTier;
+    name: string;
+    role: 'client';
+}
+interface WebsocketTransferListPayload {
+    transfers: Transfer[];
+}
+interface WebsocketTargetListPayload {
+    targets: TransferTarget[];
+}
 interface ReportRecords<TRecord = unknown> {
     count: number;
     records: TRecord[];
@@ -522,6 +547,7 @@ declare class HttpClient {
     private lastRateLimit?;
     constructor(config: HttpClientConfig);
     getRateLimit(): RateLimit | undefined;
+    getBaseUrl(): string;
     request<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
     private buildUrl;
     private buildHeaders;
@@ -632,6 +658,62 @@ declare class TransfersResource {
     requestPublicStorage(data: PublicStorageTransferRequest): Promise<PublicStorageTransferResponse>;
 }
 
+interface WebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: string;
+    }) => void) | null;
+    onerror: (() => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+}
+interface WebsocketClientOptions {
+    connectTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    webSocketFactory?: (url: string) => WebSocketLike;
+}
+declare class WebsocketProtocolError extends Error {
+    readonly code: string;
+    readonly requestId?: WebsocketMessageId;
+    constructor(message: string, code: string, requestId?: WebsocketMessageId);
+}
+declare class WebsocketsResource {
+    private client;
+    private ws;
+    private connectPromise;
+    private pending;
+    private transferUpdateListeners;
+    private nextRequestId;
+    private readonly connectTimeoutMs;
+    private readonly requestTimeoutMs;
+    private readonly webSocketFactory;
+    constructor(client: HttpClient, options?: WebsocketClientOptions);
+    start(): Promise<WebsocketEnvelope>;
+    authenticate(token: string, id?: WebsocketMessageId): Promise<WebsocketAuthOk>;
+    ping(id?: WebsocketMessageId): Promise<number>;
+    createTransfer(payload: TransferCreateRequest, id?: WebsocketMessageId): Promise<Transfer>;
+    getTransfer(transferId: string, id?: WebsocketMessageId): Promise<Transfer>;
+    cancelTransfer(transferId: string, id?: WebsocketMessageId): Promise<Transfer>;
+    listTransfers(id?: WebsocketMessageId): Promise<Transfer[]>;
+    listTargets(id?: WebsocketMessageId): Promise<TransferTarget[]>;
+    onTransferUpdate(listener: (transfer: Transfer) => void): () => void;
+    close(code?: number, reason?: string): void;
+    isConnected(): boolean;
+    private sendAndWait;
+    private handleMessageEvent;
+    private emitTransferUpdate;
+    private safeParse;
+    private createRequestId;
+    private rejectAllPending;
+    private buildWebSocketUrl;
+    private getDefaultWebSocketFactory;
+}
+
 interface KrawletClientConfig {
     baseUrl?: string;
     apiKey?: string;
@@ -652,6 +734,7 @@ declare class KrawletClient {
     readonly reports: ReportsResource;
     readonly apiKey: ApiKeyResource;
     readonly transfers: TransfersResource;
+    readonly websockets: WebsocketsResource;
     constructor(config?: KrawletClientConfig);
     getRateLimit(): RateLimit | undefined;
 }
@@ -668,4 +751,4 @@ declare class KrawletError extends Error {
     isRateLimitError(): boolean;
 }
 
-export { AddressesResource, type ApiKeyInfo, ApiKeyResource, type ApiKeyTier, type ApiKeyUsage, type ApiResponse, type ApiResponseMeta, type BaseQueryParams, type ChangeLogOptions, type ChangeLogResult, type ChatboxServiceInfo, type DetailedHealthResponse, type DiscordServiceInfo, type EStorageEntityType, type EnderStorageApiPayload, type EnderStorageChest, type EnderStorageCollection, type EnderStorageColor, type EnderStorageItem, type EnderStorageMeta, type EnderStoragePayload, ErrorCode, type ErrorResponse, type HealthChecks, HealthResource, type HealthResponse, type HealthServices, type HealthServicesDetailed, type Item, type ItemChangeLog, type ItemChangeLogResponse, type ItemChangeRecord, type ItemChangeType, type ItemChangesParams, type ItemSummary, type ItemUpdateSummary, ItemsResource, type KnownAddress, type KnownAddressType, KrawletClient, type KrawletClientConfig, KrawletError, type KromerServiceInfo, type Player, type PlayerNotifications, PlayersResource, type Price, type PriceChangeLog, type PriceChangeLogResponse, type PriceChangesParams, type PublicStorageSourceEntity, type PublicStorageTransferRequest, type PublicStorageTransferResponse, type QuickCodeGenerateResponse, type QuickCodeRedeemResponse, type RateLimit, type ReportRecords, type ReporterStats, ReportsResource, type RequestLog, type RequestLogsResponse, type ServiceInfo, type ServiceName, type ServiceStatus, type Shop, type ShopChangeField, type ShopChangeLog, type ShopChangeLogResponse, type ShopChangeRecord, type ShopChangesParams, type ShopSourceType, type ShopSyncData, ShopsResource, type StorageData, StorageResource, type StorageSlotContents, type StorageSlotItem, type SuccessfulPostRecord, type Transfer, type TransferCreateRequest, type TransferStatus, type TransferTarget, type TransferTargetLink, TransfersResource, type ValidationFailureRecord };
+export { AddressesResource, type ApiKeyInfo, ApiKeyResource, type ApiKeyTier, type ApiKeyUsage, type ApiResponse, type ApiResponseMeta, type BaseQueryParams, type ChangeLogOptions, type ChangeLogResult, type ChatboxServiceInfo, type DetailedHealthResponse, type DiscordServiceInfo, type EStorageEntityType, type EnderStorageApiPayload, type EnderStorageChest, type EnderStorageCollection, type EnderStorageColor, type EnderStorageItem, type EnderStorageMeta, type EnderStoragePayload, ErrorCode, type ErrorResponse, type HealthChecks, HealthResource, type HealthResponse, type HealthServices, type HealthServicesDetailed, type Item, type ItemChangeLog, type ItemChangeLogResponse, type ItemChangeRecord, type ItemChangeType, type ItemChangesParams, type ItemSummary, type ItemUpdateSummary, ItemsResource, type KnownAddress, type KnownAddressType, KrawletClient, type KrawletClientConfig, KrawletError, type KromerServiceInfo, type Player, type PlayerNotifications, PlayersResource, type Price, type PriceChangeLog, type PriceChangeLogResponse, type PriceChangesParams, type PublicStorageSourceEntity, type PublicStorageTransferRequest, type PublicStorageTransferResponse, type QuickCodeGenerateResponse, type QuickCodeRedeemResponse, type RateLimit, type ReportRecords, type ReporterStats, ReportsResource, type RequestLog, type RequestLogsResponse, type ServiceInfo, type ServiceName, type ServiceStatus, type Shop, type ShopChangeField, type ShopChangeLog, type ShopChangeLogResponse, type ShopChangeRecord, type ShopChangesParams, type ShopSourceType, type ShopSyncData, ShopsResource, type StorageData, StorageResource, type StorageSlotContents, type StorageSlotItem, type SuccessfulPostRecord, type Transfer, type TransferCreateRequest, type TransferStatus, type TransferTarget, type TransferTargetLink, TransfersResource, type ValidationFailureRecord, type WebsocketAuthOk, type WebsocketClientOptions, type WebsocketEnvelope, type WebsocketErrorPayload, type WebsocketHelloPayload, type WebsocketMessageId, WebsocketProtocolError, type WebsocketTargetListPayload, type WebsocketTransferListPayload, WebsocketsResource };

package/dist/index.js

@@ -51,6 +51,12 @@ var HttpClient = class {
   getRateLimit() {
     return this.lastRateLimit;
   }
+  /**
+   * Get configured API base URL
+   */
+  getBaseUrl() {
+    return this.config.baseUrl;
+  }
   /**
    * Make an HTTP request
    */
@@ -791,6 +797,308 @@ var TransfersResource = class {
   }
 };
 
+// src/resources/websockets.ts
+var WebsocketProtocolError = class extends Error {
+  constructor(message, code, requestId) {
+    super(message);
+    this.name = "WebsocketProtocolError";
+    this.code = code;
+    this.requestId = requestId;
+  }
+};
+var WebsocketsResource = class {
+  constructor(client, options = {}) {
+    this.client = client;
+    this.ws = null;
+    this.connectPromise = null;
+    this.pending = /* @__PURE__ */ new Map();
+    this.transferUpdateListeners = /* @__PURE__ */ new Set();
+    this.nextRequestId = 1;
+    this.connectTimeoutMs = options.connectTimeoutMs ?? 1e4;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 15e3;
+    this.webSocketFactory = options.webSocketFactory ?? this.getDefaultWebSocketFactory();
+  }
+  /**
+   * Open websocket connection and wait for initial hello
+   */
+  async start() {
+    if (this.connectPromise) {
+      return this.connectPromise;
+    }
+    const url = this.buildWebSocketUrl();
+    this.connectPromise = new Promise((resolve, reject) => {
+      const ws = this.webSocketFactory(url);
+      this.ws = ws;
+      const timeout = setTimeout(() => {
+        this.connectPromise = null;
+        this.ws = null;
+        try {
+          ws.close();
+        } catch {
+        }
+        reject(new Error(`WebSocket connection timeout after ${this.connectTimeoutMs}ms`));
+      }, this.connectTimeoutMs);
+      ws.onopen = () => {
+      };
+      ws.onmessage = (event) => {
+        this.handleMessageEvent(event.data, resolve, reject, timeout);
+      };
+      ws.onerror = () => {
+        clearTimeout(timeout);
+        this.connectPromise = null;
+        this.ws = null;
+        reject(new Error("WebSocket connection failed"));
+      };
+      ws.onclose = (event) => {
+        clearTimeout(timeout);
+        this.connectPromise = null;
+        this.ws = null;
+        this.rejectAllPending(
+          new Error(`WebSocket closed (${event.code}${event.reason ? `: ${event.reason}` : ""})`)
+        );
+      };
+    });
+    return this.connectPromise;
+  }
+  /**
+   * Authenticate this connection as a client key
+   */
+  async authenticate(token, id = this.createRequestId()) {
+    const response = await this.sendAndWait("auth", {
+      type: "auth",
+      id,
+      token
+    });
+    if (response.type !== "auth_ok") {
+      throw new Error(`Unexpected auth response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * Ping the websocket server
+   */
+  async ping(id = this.createRequestId()) {
+    const response = await this.sendAndWait("ping", {
+      type: "ping",
+      id
+    });
+    if (response.type !== "pong") {
+      throw new Error(`Unexpected ping response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * Create a transfer over websocket
+   */
+  async createTransfer(payload, id = this.createRequestId()) {
+    const response = await this.sendAndWait("create_transfer", {
+      type: "create_transfer",
+      id,
+      payload
+    });
+    if (response.type !== "create_transfer_ok") {
+      throw new Error(`Unexpected create_transfer response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * Fetch transfer by id
+   */
+  async getTransfer(transferId, id = this.createRequestId()) {
+    const response = await this.sendAndWait("get_transfer", {
+      type: "get_transfer",
+      id,
+      payload: { transferId }
+    });
+    if (response.type !== "get_transfer_ok") {
+      throw new Error(`Unexpected get_transfer response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * Cancel transfer by id
+   */
+  async cancelTransfer(transferId, id = this.createRequestId()) {
+    const response = await this.sendAndWait("cancel_transfer", {
+      type: "cancel_transfer",
+      id,
+      payload: { transferId }
+    });
+    if (response.type !== "cancel_transfer_ok") {
+      throw new Error(`Unexpected cancel_transfer response type: ${response.type}`);
+    }
+    return response.payload;
+  }
+  /**
+   * List transfers for this client
+   */
+  async listTransfers(id = this.createRequestId()) {
+    const response = await this.sendAndWait("list_transfers", {
+      type: "list_transfers",
+      id,
+      payload: {}
+    });
+    if (response.type !== "list_transfers_ok") {
+      throw new Error(`Unexpected list_transfers response type: ${response.type}`);
+    }
+    return response.payload.transfers;
+  }
+  /**
+   * List targets available to this client
+   */
+  async listTargets(id = this.createRequestId()) {
+    const response = await this.sendAndWait("list_targets", {
+      type: "list_targets",
+      id,
+      payload: {}
+    });
+    if (response.type !== "list_targets_ok") {
+      throw new Error(`Unexpected list_targets response type: ${response.type}`);
+    }
+    return response.payload.targets;
+  }
+  /**
+   * Subscribe to unsolicited transfer updates.
+   * Returns an unsubscribe function.
+   */
+  onTransferUpdate(listener) {
+    this.transferUpdateListeners.add(listener);
+    return () => {
+      this.transferUpdateListeners.delete(listener);
+    };
+  }
+  /**
+   * Close the websocket connection
+   */
+  close(code, reason) {
+    if (!this.ws) {
+      return;
+    }
+    try {
+      this.ws.close(code, reason);
+    } finally {
+      this.ws = null;
+      this.connectPromise = null;
+      this.rejectAllPending(new Error("WebSocket connection closed"));
+    }
+  }
+  /**
+   * True if the websocket is currently open
+   */
+  isConnected() {
+    return Boolean(this.ws && this.ws.readyState === 1);
+  }
+  async sendAndWait(messageType, message) {
+    if (!this.ws || this.ws.readyState !== 1) {
+      await this.start();
+    }
+    if (!this.ws || this.ws.readyState !== 1) {
+      throw new Error("WebSocket is not connected");
+    }
+    const requestId = message.id;
+    const responsePromise = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(requestId);
+        reject(new Error(`WebSocket ${messageType} request timed out after ${this.requestTimeoutMs}ms`));
+      }, this.requestTimeoutMs);
+      this.pending.set(requestId, {
+        resolve: (value) => resolve(value),
+        reject,
+        timeout
+      });
+    });
+    this.ws.send(JSON.stringify(message));
+    return responsePromise;
+  }
+  handleMessageEvent(rawData, connectResolve, connectReject, connectTimeout) {
+    const parsed = this.safeParse(rawData);
+    if (!parsed) {
+      return;
+    }
+    if (parsed.type === "hello") {
+      clearTimeout(connectTimeout);
+      connectResolve(parsed);
+      return;
+    }
+    if (parsed.type === "transfer_update") {
+      this.emitTransferUpdate(parsed.payload);
+      return;
+    }
+    if (typeof parsed.id === "undefined") {
+      if (parsed.type === "error") {
+        const payload = parsed.payload;
+        connectReject(new WebsocketProtocolError(payload.message, payload.code));
+      }
+      return;
+    }
+    const pending = this.pending.get(parsed.id);
+    if (!pending) {
+      return;
+    }
+    clearTimeout(pending.timeout);
+    this.pending.delete(parsed.id);
+    if (parsed.type === "error") {
+      const payload = parsed.payload;
+      pending.reject(new WebsocketProtocolError(payload.message, payload.code, parsed.id));
+      return;
+    }
+    pending.resolve(parsed);
+  }
+  emitTransferUpdate(transfer) {
+    for (const listener of this.transferUpdateListeners) {
+      listener(transfer);
+    }
+  }
+  safeParse(rawData) {
+    try {
+      const parsed = JSON.parse(rawData);
+      if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string") {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  createRequestId() {
+    const id = this.nextRequestId;
+    this.nextRequestId += 1;
+    return id;
+  }
+  rejectAllPending(error) {
+    for (const entry of this.pending.values()) {
+      clearTimeout(entry.timeout);
+      entry.reject(error);
+    }
+    this.pending.clear();
+  }
+  buildWebSocketUrl() {
+    const base = new URL(this.client.getBaseUrl());
+    base.protocol = base.protocol === "https:" ? "wss:" : "ws:";
+    const trimmedPath = base.pathname.replace(/\/+$/, "");
+    if (trimmedPath.endsWith("/api/v1")) {
+      base.pathname = `${trimmedPath}/ws`;
+    } else if (trimmedPath.endsWith("/api")) {
+      base.pathname = `${trimmedPath}/v1/ws`;
+    } else if (trimmedPath.endsWith("/v1")) {
+      base.pathname = `${trimmedPath}/ws`;
+    } else {
+      base.pathname = "/v1/ws";
+    }
+    base.search = "";
+    base.hash = "";
+    return base.toString();
+  }
+  getDefaultWebSocketFactory() {
+    return (url) => {
+      if (typeof globalThis.WebSocket === "undefined") {
+        throw new Error("WebSocket is not available. Provide a webSocketFactory in WebsocketsResource options.");
+      }
+      return new globalThis.WebSocket(url);
+    };
+  }
+};
+
 // src/client.ts
 var KrawletClient = class {
   /**
@@ -817,6 +1125,7 @@ var KrawletClient = class {
     this.reports = new ReportsResource(this.httpClient);
     this.apiKey = new ApiKeyResource(this.httpClient);
     this.transfers = new TransfersResource(this.httpClient);
+    this.websockets = new WebsocketsResource(this.httpClient);
   }
   /**
    * Get the last known rate limit information
@@ -856,5 +1165,7 @@ export {
   ReportsResource,
   ShopsResource,
   StorageResource,
-  TransfersResource
+  TransfersResource,
+  WebsocketProtocolError,
+  WebsocketsResource
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "krawlet-js",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "description": "TypeScript/JavaScript client library for the Krawlet Minecraft economy tracking API",
   "type": "module",
   "main": "dist/index.cjs",