krawlet-js 1.0.0

package/dist/index.js

@@ -0,0 +1,579 @@
+// src/error.ts
+var KrawletError = class _KrawletError extends Error {
+  constructor(message, code, statusCode, requestId, details, response) {
+    super(message);
+    this.name = "KrawletError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.requestId = requestId;
+    this.details = details;
+    this.response = response;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _KrawletError);
+    }
+  }
+  /**
+   * Check if this is a client error (4xx)
+   */
+  isClientError() {
+    return this.statusCode >= 400 && this.statusCode < 500;
+  }
+  /**
+   * Check if this is a server error (5xx)
+   */
+  isServerError() {
+    return this.statusCode >= 500;
+  }
+  /**
+   * Check if this is a rate limit error
+   */
+  isRateLimitError() {
+    return this.statusCode === 429 || this.code === "RATE_LIMIT_EXCEEDED";
+  }
+};
+
+// src/http-client.ts
+var HttpClient = class {
+  constructor(config) {
+    this.config = {
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey || "",
+      timeout: config.timeout || 3e4,
+      headers: config.headers || {},
+      enableRetry: config.enableRetry !== false,
+      maxRetries: config.maxRetries || 3,
+      retryDelay: config.retryDelay || 1e3
+    };
+  }
+  /**
+   * Get the last known rate limit information
+   */
+  getRateLimit() {
+    return this.lastRateLimit;
+  }
+  /**
+   * Make an HTTP request
+   */
+  async request(path, options = {}) {
+    const url = this.buildUrl(path, options.params);
+    const headers = this.buildHeaders(options.headers, options.apiKey);
+    let lastError;
+    let attempt = 0;
+    const maxAttempts = this.config.enableRetry ? this.config.maxRetries + 1 : 1;
+    while (attempt < maxAttempts) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        const response = await fetch(url, {
+          method: options.method || "GET",
+          headers,
+          body: options.body ? JSON.stringify(options.body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        this.extractRateLimit(response);
+        if (!response.ok) {
+          await this.handleErrorResponse(response);
+        }
+        const data = await response.json();
+        return data;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof KrawletError && error.isClientError() && !error.isRateLimitError()) {
+          throw error;
+        }
+        if (attempt < maxAttempts - 1 && this.shouldRetry(error)) {
+          const delay = this.calculateRetryDelay(attempt);
+          await this.sleep(delay);
+          attempt++;
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError || new Error("Request failed after retries");
+  }
+  /**
+   * Build the full URL with query parameters
+   */
+  buildUrl(path, params) {
+    const url = new URL(path, this.config.baseUrl);
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== void 0) {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+    return url.toString();
+  }
+  /**
+   * Build request headers
+   */
+  buildHeaders(customHeaders, apiKey) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.config.headers,
+      ...customHeaders
+    };
+    const key = apiKey || this.config.apiKey;
+    if (key) {
+      headers["Authorization"] = `Bearer ${key}`;
+    }
+    return headers;
+  }
+  /**
+   * Extract rate limit information from response headers
+   */
+  extractRateLimit(response) {
+    const limit = response.headers.get("X-RateLimit-Limit");
+    const remaining = response.headers.get("X-RateLimit-Remaining");
+    const reset = response.headers.get("X-RateLimit-Reset");
+    if (limit && remaining && reset) {
+      this.lastRateLimit = {
+        limit: parseInt(limit, 10),
+        remaining: parseInt(remaining, 10),
+        reset: parseInt(reset, 10)
+      };
+    }
+  }
+  /**
+   * Handle error responses
+   */
+  async handleErrorResponse(response) {
+    let errorData;
+    try {
+      errorData = await response.json();
+    } catch {
+      throw new KrawletError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        "UNKNOWN_ERROR",
+        response.status
+      );
+    }
+    throw new KrawletError(
+      errorData.error.message,
+      errorData.error.code,
+      response.status,
+      errorData.meta.requestId,
+      errorData.error.details,
+      errorData
+    );
+  }
+  /**
+   * Determine if a request should be retried
+   */
+  shouldRetry(error) {
+    if (error instanceof KrawletError) {
+      return error.isServerError() || error.isRateLimitError();
+    }
+    if (error instanceof Error) {
+      return error.name === "AbortError" || error.message.includes("fetch");
+    }
+    return false;
+  }
+  /**
+   * Calculate retry delay with exponential backoff
+   */
+  calculateRetryDelay(attempt) {
+    return this.config.retryDelay * Math.pow(2, attempt);
+  }
+  /**
+   * Sleep for a given duration
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/resources/health.ts
+var HealthResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Basic health check to verify API is operational
+   * @returns Health status information
+   */
+  async check() {
+    const response = await this.client.request("/v1/health");
+    return response.data;
+  }
+  /**
+   * Detailed health check with system information
+   * @returns Detailed health status with system metrics
+   */
+  async detailed() {
+    const response = await this.client.request("/v1/health/detailed");
+    return response.data;
+  }
+};
+
+// src/resources/players.ts
+var PlayersResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieve all players
+   * @returns Array of all players
+   */
+  async getAll() {
+    const response = await this.client.request("/v1/players");
+    return response.data;
+  }
+  /**
+   * Retrieve players by Kromer addresses
+   * @param addresses - Array of Kromer addresses
+   * @returns Array of matching players
+   */
+  async getByAddresses(addresses) {
+    const response = await this.client.request("/v1/players", {
+      params: {
+        addresses: addresses.join(",")
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Retrieve players by Minecraft names
+   * @param names - Array of player names (case-insensitive)
+   * @returns Array of matching players
+   */
+  async getByNames(names) {
+    const response = await this.client.request("/v1/players", {
+      params: {
+        names: names.join(",")
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Retrieve players by Minecraft UUIDs
+   * @param uuids - Array of player UUIDs
+   * @returns Array of matching players
+   */
+  async getByUuids(uuids) {
+    const response = await this.client.request("/v1/players", {
+      params: {
+        uuids: uuids.join(",")
+      }
+    });
+    return response.data;
+  }
+};
+
+// src/resources/shops.ts
+var ShopsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieve all shops with their items and addresses
+   * @returns Array of all shops
+   */
+  async getAll() {
+    const response = await this.client.request("/v1/shops");
+    return response.data;
+  }
+  /**
+   * Retrieve a specific shop by ID
+   * @param id - Shop ID (computer ID)
+   * @returns Shop data
+   * @throws KrawletError with SHOP_NOT_FOUND if shop doesn't exist
+   */
+  async get(id) {
+    const response = await this.client.request(`/v1/shops/${id}`);
+    return response.data;
+  }
+  /**
+   * Retrieve all items for a specific shop
+   * @param id - Shop ID
+   * @returns Array of items in the shop
+   */
+  async getItems(id) {
+    const response = await this.client.request(`/v1/shops/${id}/items`);
+    return response.data;
+  }
+  /**
+   * Create or update a shop (requires ShopSync authentication)
+   * @param data - Shop sync data
+   * @param token - ShopSync API token
+   * @returns Success message
+   * @throws KrawletError with VALIDATION_ERROR if data is invalid
+   * @throws KrawletError with UNAUTHORIZED if not authenticated
+   */
+  async update(data, token) {
+    const response = await this.client.request("/v1/shops", {
+      method: "POST",
+      body: data,
+      apiKey: token
+    });
+    return response.data;
+  }
+};
+
+// src/resources/items.ts
+var ItemsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieve all item listings with prices across all shops
+   * @returns Array of all items
+   */
+  async getAll() {
+    const response = await this.client.request("/v1/items");
+    return response.data;
+  }
+};
+
+// src/resources/addresses.ts
+var AddressesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieve all known Kromer addresses
+   * @returns Array of all known addresses
+   */
+  async getAll() {
+    const response = await this.client.request("/v1/addresses");
+    return response.data;
+  }
+};
+
+// src/resources/storage.ts
+var StorageResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieve the last stored ender storage data
+   * @returns Storage data and retrieval timestamp
+   * @throws KrawletError with NOT_FOUND if no data has been stored yet
+   */
+  async get() {
+    const response = await this.client.request("/v1/storage");
+    return response.data;
+  }
+  /**
+   * Store ender storage data (requires authentication)
+   * @param data - Any JSON object to store
+   * @param token - Ender Storage API token
+   * @returns Success message and timestamp
+   * @throws KrawletError with BAD_REQUEST if data is invalid
+   * @throws KrawletError with UNAUTHORIZED if not authenticated
+   */
+  async set(data, token) {
+    const response = await this.client.request(
+      "/v1/storage",
+      {
+        method: "POST",
+        body: data,
+        apiKey: token
+      }
+    );
+    return response.data;
+  }
+};
+
+// src/resources/reports.ts
+var ReportsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieve overall statistics for ShopSync reports
+   * @returns Statistics object
+   */
+  async getStats() {
+    const response = await this.client.request("/v1/reports/stats");
+    return response.data;
+  }
+  /**
+   * Retrieve recent validation failures
+   * @param options - Query options
+   * @param options.limit - Maximum records to return (default: 50)
+   * @returns Validation failure records
+   */
+  async getValidationFailures(options) {
+    const response = await this.client.request("/v1/reports/validation-failures", {
+      params: {
+        limit: options?.limit || 50
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Retrieve recent successful ShopSync posts
+   * @param options - Query options
+   * @param options.limit - Maximum records to return (default: 50)
+   * @returns Successful post records
+   */
+  async getSuccessfulPosts(options) {
+    const response = await this.client.request("/v1/reports/successful-posts", {
+      params: {
+        limit: options?.limit || 50
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Retrieve recent shop change events
+   * @param options - Query options
+   * @param options.limit - Maximum records to return (default: 50)
+   * @param options.shopId - Filter by shop ID
+   * @returns Shop change event records
+   */
+  async getShopChanges(options) {
+    const response = await this.client.request("/v1/reports/shop-changes", {
+      params: {
+        limit: options?.limit || 50,
+        shopId: options?.shopId
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Retrieve recent item change events
+   * @param options - Query options
+   * @param options.limit - Maximum records to return (default: 50)
+   * @param options.shopId - Filter by shop ID
+   * @returns Item change event records
+   */
+  async getItemChanges(options) {
+    const response = await this.client.request("/v1/reports/item-changes", {
+      params: {
+        limit: options?.limit || 50,
+        shopId: options?.shopId
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Retrieve shop change logs from the database
+   * @param options - Query options including pagination and filtering
+   * @returns Shop change logs
+   */
+  async getShopChangeLogs(options) {
+    const response = await this.client.request("/v1/reports/shop-change-logs", {
+      params: {
+        limit: options?.limit,
+        offset: options?.offset,
+        shopId: options?.shopId,
+        since: options?.since,
+        until: options?.until
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Retrieve item change logs from the database
+   * @param options - Query options including pagination and filtering
+   * @returns Item change logs
+   */
+  async getItemChangeLogs(options) {
+    const response = await this.client.request("/v1/reports/item-change-logs", {
+      params: {
+        limit: options?.limit,
+        offset: options?.offset,
+        shopId: options?.shopId,
+        since: options?.since,
+        until: options?.until
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Retrieve price change logs from the database
+   * @param options - Query options including pagination and filtering
+   * @returns Price change logs
+   */
+  async getPriceChangeLogs(options) {
+    const response = await this.client.request("/v1/reports/price-change-logs", {
+      params: {
+        limit: options?.limit,
+        offset: options?.offset,
+        shopId: options?.shopId,
+        since: options?.since,
+        until: options?.until
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Retrieve a specific report record by ID
+   * @param id - Report record ID
+   * @returns Report record
+   * @throws KrawletError with NOT_FOUND if record doesn't exist
+   */
+  async get(id) {
+    const response = await this.client.request(`/v1/reports/${id}`);
+    return response.data;
+  }
+};
+
+// src/client.ts
+var KrawletClient = class {
+  /**
+   * Create a new Krawlet API client
+   * @param config - Client configuration options
+   */
+  constructor(config = {}) {
+    const httpConfig = {
+      baseUrl: config.baseUrl || "https://api.krawlet.cc",
+      apiKey: config.apiKey,
+      timeout: config.timeout,
+      headers: config.headers,
+      enableRetry: config.enableRetry,
+      maxRetries: config.maxRetries,
+      retryDelay: config.retryDelay
+    };
+    this.httpClient = new HttpClient(httpConfig);
+    this.health = new HealthResource(this.httpClient);
+    this.players = new PlayersResource(this.httpClient);
+    this.shops = new ShopsResource(this.httpClient);
+    this.items = new ItemsResource(this.httpClient);
+    this.addresses = new AddressesResource(this.httpClient);
+    this.storage = new StorageResource(this.httpClient);
+    this.reports = new ReportsResource(this.httpClient);
+  }
+  /**
+   * Get the last known rate limit information
+   * @returns Rate limit data or undefined if no requests have been made
+   */
+  getRateLimit() {
+    return this.httpClient.getRateLimit();
+  }
+};
+
+// src/types.ts
+var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
+  ErrorCode2["BAD_REQUEST"] = "BAD_REQUEST";
+  ErrorCode2["UNAUTHORIZED"] = "UNAUTHORIZED";
+  ErrorCode2["FORBIDDEN"] = "FORBIDDEN";
+  ErrorCode2["NOT_FOUND"] = "NOT_FOUND";
+  ErrorCode2["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+  ErrorCode2["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+  ErrorCode2["PLAYER_NOT_FOUND"] = "PLAYER_NOT_FOUND";
+  ErrorCode2["SHOP_NOT_FOUND"] = "SHOP_NOT_FOUND";
+  ErrorCode2["TURTLE_NOT_FOUND"] = "TURTLE_NOT_FOUND";
+  ErrorCode2["INVALID_API_KEY"] = "INVALID_API_KEY";
+  ErrorCode2["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+  ErrorCode2["DATABASE_ERROR"] = "DATABASE_ERROR";
+  ErrorCode2["HEALTH_CHECK_FAILED"] = "HEALTH_CHECK_FAILED";
+  return ErrorCode2;
+})(ErrorCode || {});
+export {
+  AddressesResource,
+  ErrorCode,
+  HealthResource,
+  ItemsResource,
+  KrawletClient,
+  KrawletError,
+  PlayersResource,
+  ReportsResource,
+  ShopsResource,
+  StorageResource
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "krawlet-js",
+  "version": "1.0.0",
+  "description": "TypeScript/JavaScript client library for the Krawlet Minecraft economy tracking API",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest",
+    "test:coverage": "vverage",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": [
+    "krawlet",
+    "minecraft",
+    "economy",
+    "api",
+    "client",
+    "typescript"
+  ],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.28.1",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^9.18.0",
+    "prettier": "^3.4.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}