@artsnoa/ipc-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,55 @@
+Proprietary License
+
+Copyright (c) 2026 Artsnoa.com(mirseo)
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are the proprietary
+and confidential information of Artsnoa.com(mirseo). The Software is licensed, not sold.
+
+NOTICE TO USER: This Software is protected by copyright laws and international copyright
+treaties, as well as other intellectual property laws and treaties. The Software is
+licensed, not sold.
+
+PERMITTED USE:
+
+You may use this Software in accordance with the terms and conditions specified at
+https://ipc.artsnoa.com. Usage rights are granted as defined in the IPC service terms
+and conditions.
+
+RESTRICTIONS:
+
+1. You may NOT modify, alter, adapt, or create derivative works of the Software.
+
+2. You may NOT reverse engineer, decompile, or disassemble the Software, except and
+   only to the extent that such activity is expressly permitted by applicable law
+   notwithstanding this limitation.
+
+3. You may NOT remove, alter, or obscure any copyright, trademark, or other proprietary
+   rights notices contained in or on the Software.
+
+4. You may NOT redistribute, sublicense, rent, lease, or lend the Software in modified
+   form.
+
+5. Any modifications, alterations, or tampering with the Software code is strictly
+   prohibited.
+
+DISCLAIMER:
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+TERMINATION:
+
+This license is effective until terminated. Your rights under this license will
+terminate automatically without notice if you fail to comply with any of its terms.
+
+FOR LICENSING INQUIRIES:
+
+For information regarding licensing of this Software, please contact:
+Email: aurora@artsnoa.com
+Website: https://ipc.artsnoa.com

package/README.md

@@ -0,0 +1,325 @@
+# IPC Artsnoa JavaScript SDK
+
+Official JavaScript/TypeScript SDK for [ipc.artsnoa.com](https://ipc.artsnoa.com) API - Get your IP address and location information.
+
+## Features
+
+- Full TypeScript support with type definitions
+- Simple and intuitive API
+- Comprehensive error handling
+- Works in Node.js environments
+- Minimal dependencies
+- ESM and CommonJS support
+
+## Installation
+
+```bash
+npm install @artsnoa/ipc-sdk
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @artsnoa/ipc-sdk
+```
+
+Or with yarn:
+
+```bash
+yarn add @artsnoa/ipc-sdk
+```
+
+## Quick Start
+
+```javascript
+import { IPCClient } from '@artsnoa/ipc-sdk';
+
+// Initialize client (API key is optional)
+const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+
+// Get detailed IP information
+const details = await client.getIPDetails();
+console.log(`Your IP: ${details.ip}, Country: ${details.country}`);
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```javascript
+import { IPCClient } from '@artsnoa/ipc-sdk';
+
+// Create client with API key
+const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+
+// Get IP details
+const data = await client.getIPDetails();
+console.log(`IP: ${data.ip}`);
+console.log(`Country: ${data.country}`);
+
+// Without API key
+const publicClient = new IPCClient();
+const publicData = await publicClient.getIPDetails();
+console.log(`Your IP: ${publicData.ip}`);
+```
+
+### TypeScript Usage
+
+```typescript
+import { IPCClient, IPDetailsResponse } from '@artsnoa/ipc-sdk';
+
+const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+
+// Type-safe IP details
+const details: IPDetailsResponse = await client.getIPDetails();
+console.log(`IP: ${details.ip}`);
+console.log(`User Agent: ${details.userAgent}`);
+console.log(`ASN: ${details.asn}`);
+console.log(`Country: ${details.country}`);
+console.log(`Currency: ${details.currency}`);
+console.log(`Languages: ${details.languages.join(', ')}`);
+console.log(`Timestamp: ${details.timestamp}`);
+```
+
+### SDK Version Information
+
+```javascript
+import { IPCClient } from '@artsnoa/ipc-sdk';
+
+const client = new IPCClient();
+
+// Get available SDK versions
+const versions = await client.getSDKVersions();
+console.log(`JavaScript SDK: ${versions.javascript}`);
+console.log(`Python SDK: ${versions.python}`);
+```
+
+### Custom Configuration
+
+```javascript
+import { IPCClient } from '@artsnoa/ipc-sdk';
+
+// Custom timeout and base URL
+const client = new IPCClient({
+  apiKey: 'YOUR_API_KEY',
+  timeout: 15000, // 15 seconds in milliseconds
+  baseUrl: 'https://custom-domain.com'
+});
+
+const data = await client.getIPDetails();
+```
+
+### CommonJS Usage
+
+```javascript
+const { IPCClient } = require('@artsnoa/ipc-sdk');
+
+const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+
+client.getIPDetails().then(data => {
+  console.log(`IP: ${data.ip}, Country: ${data.country}`);
+});
+```
+
+## Error Handling
+
+The SDK provides a custom error class for handling API errors:
+
+```javascript
+import { IPCClient, IPCError } from '@artsnoa/ipc-sdk';
+
+const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+
+try {
+  const data = await client.getIPDetails();
+  console.log(`Your IP: ${data.ip}`);
+} catch (error) {
+  if (error instanceof IPCError) {
+    console.error(`IPC Error: ${error.message}`);
+    if (error.statusCode) {
+      console.error(`Status code: ${error.statusCode}`);
+    }
+    if (error.code) {
+      console.error(`Error code: ${error.code}`);
+    }
+  } else {
+    console.error(`Unexpected error: ${error}`);
+  }
+}
+```
+
+### TypeScript Error Handling
+
+```typescript
+import { IPCClient, IPCError } from '@artsnoa/ipc-sdk';
+
+const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+
+async function getIPSafely() {
+  try {
+    const data = await client.getIPDetails();
+    return data;
+  } catch (error) {
+    if (error instanceof IPCError) {
+      console.error(`API error: ${error.message}`);
+      console.error(`Status: ${error.statusCode ?? 'unknown'}`);
+    } else if (error instanceof Error) {
+      console.error(`Error: ${error.message}`);
+    }
+    throw error;
+  }
+}
+```
+
+## API Reference
+
+### IPCClient
+
+#### Constructor
+
+```typescript
+new IPCClient(options?: IPCClientOptions)
+```
+
+**Parameters:**
+- `options` (IPCClientOptions): Configuration options
+  - `apiKey` (string, optional): API key for authentication
+  - `baseUrl` (string, optional): Base URL for the API. Defaults to `https://ipc.artsnoa.com`
+  - `timeout` (number, optional): Request timeout in milliseconds. Defaults to 10000 (10 seconds)
+
+**Example:**
+```javascript
+const client = new IPCClient({
+  apiKey: 'YOUR_API_KEY',
+  timeout: 15000,
+  baseUrl: 'https://ipc.artsnoa.com'
+});
+```
+
+#### Methods
+
+##### `getIPDetails(): Promise<IPDetailsResponse>`
+
+Get detailed IP address and location information.
+
+**Returns:**
+- Promise that resolves to an object containing:
+  - `ip` (string): Your IP address
+  - `userAgent` (string): Browser user agent string
+  - `asn` (string): Autonomous System Number
+  - `country` (string): Country code (ISO 3166-1 alpha-2)
+  - `currency` (string): Country currency code (ISO 4217)
+  - `languages` (string[]): Array of supported language codes
+  - `timestamp` (string): Request timestamp (ISO 8601 format)
+  - `version` (string): API version
+
+**Throws:**
+- `IPCError`: When the API request fails or returns an invalid response
+
+**Example:**
+```javascript
+const details = await client.getIPDetails();
+console.log(`IP: ${details.ip}, Country: ${details.country}`);
+console.log(`ASN: ${details.asn}, Currency: ${details.currency}`);
+```
+
+##### `getSDKVersions(): Promise<SDKVersionsResponse>`
+
+Get available SDK versions for different platforms.
+
+**Returns:**
+- Promise that resolves to an object containing:
+  - `javascript` (string): JavaScript/TypeScript SDK version
+  - `python` (string): Python SDK version
+
+**Throws:**
+- `IPCError`: When the API request fails or returns an invalid response
+
+**Example:**
+```javascript
+const versions = await client.getSDKVersions();
+console.log(`JavaScript SDK: ${versions.javascript}`);
+console.log(`Python SDK: ${versions.python}`);
+```
+
+### Types
+
+#### IPCClientOptions
+
+Configuration options for the IPCClient constructor.
+
+```typescript
+interface IPCClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  timeout?: number;
+}
+```
+
+#### IPDetailsResponse
+
+Response structure from the `getIPDetails()` method.
+
+```typescript
+interface IPDetailsResponse {
+  ip: string;
+  userAgent: string;
+  asn: string;
+  country: string;
+  currency: string;
+  languages: string[];
+  timestamp: string;
+  version: string;
+}
+```
+
+#### SDKVersionsResponse
+
+Response structure from the `getSDKVersions()` method.
+
+```typescript
+interface SDKVersionsResponse {
+  javascript: string;
+  python: string;
+}
+```
+
+#### IPCError
+
+Custom error class for IPC SDK errors.
+
+```typescript
+class IPCError extends Error {
+  statusCode?: number;
+  code?: string;
+}
+```
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/artsnoa/ipc-javascript-sdk.git
+cd ipc-javascript-sdk
+
+# Install dependencies
+pnpm install
+
+# Build package
+pnpm run build
+```
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- No external runtime dependencies
+
+## License
+
+MIT License
+
+## Support
+
+- Documentation: [https://github.com/artsnoa/ipc-javascript-sdk](https://github.com/artsnoa/ipc-javascript-sdk)
+- Issues: [https://github.com/artsnoa/ipc-javascript-sdk/issues](https://github.com/artsnoa/ipc-javascript-sdk/issues)
+- Email: aurora@artsnoa.com

package/dist/index.d.mts

@@ -0,0 +1,174 @@
+/**
+ * Configuration options for IPCClient
+ */
+interface IPCClientOptions {
+    /**
+     * API key for authentication (optional)
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the IPC API
+     * @default 'https://ipc.artsnoa.com'
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 10000
+     */
+    timeout?: number;
+}
+/**
+ * Response from the IP API
+ */
+interface IPResponse {
+    /**
+     * IP address
+     */
+    ip: string;
+    /**
+     * Country code (ISO 3166-1 alpha-2)
+     */
+    country: string;
+}
+/**
+ * Response from the IP details API
+ */
+interface IPDetailsResponse {
+    /**
+     * IP address
+     */
+    ip: string;
+    /**
+     * User agent string
+     */
+    userAgent: string;
+    /**
+     * Autonomous System Number
+     */
+    asn: string;
+    /**
+     * Country code (ISO 3166-1 alpha-2)
+     */
+    country: string;
+    /**
+     * Currency code (ISO 4217)
+     */
+    currency: string;
+    /**
+     * Array of language codes
+     */
+    languages: string[];
+    /**
+     * Timestamp of the request (ISO 8601 format)
+     */
+    timestamp: string;
+    /**
+     * API version
+     */
+    version: string;
+}
+/**
+ * Response from the SDK versions API
+ */
+interface SDKVersionsResponse {
+    /**
+     * JavaScript SDK version
+     */
+    javascript: string;
+    /**
+     * Python SDK version
+     */
+    python: string;
+}
+/**
+ * Custom error class for IPC SDK errors
+ */
+declare class IPCError extends Error {
+    readonly statusCode?: number;
+    readonly code?: string;
+    constructor(message: string, statusCode?: number, code?: string);
+}
+
+/**
+ * IPCClient - Client for interacting with the IPC API
+ *
+ * @example
+ * ```typescript
+ * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+ * const data = await client.getIPDetails();
+ * console.log(data);
+ * ```
+ */
+declare class IPCClient {
+    private readonly baseUrls;
+    private readonly apiKey?;
+    private readonly timeout;
+    /**
+     * Creates a new IPCClient instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: IPCClientOptions);
+    /**
+     * Retrieves basic IP information from the API
+     *
+     * @returns IP information with country code
+     * @throws {IPCError} If the request fails or response is invalid
+     *
+     * @example
+     * ```typescript
+     * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+     * try {
+     *   const data = await client.getIP();
+     *   console.log(`Your IP: ${data.ip}, Country: ${data.country}`);
+     * } catch (error) {
+     *   if (error instanceof IPCError) {
+     *     console.error(`Error: ${error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    getIP(): Promise<IPResponse>;
+    /**
+     * Retrieves IP details from the API
+     *
+     * @returns IP details response
+     * @throws {IPCError} If the request fails or response is invalid
+     *
+     * @example
+     * ```typescript
+     * const client = new IPCClient();
+     * try {
+     *   const details = await client.getIPDetails();
+     *   console.log(`IP: ${details.ip}, Country: ${details.country}`);
+     * } catch (error) {
+     *   if (error instanceof IPCError) {
+     *     console.error(`Error: ${error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    getIPDetails(): Promise<IPDetailsResponse>;
+    /**
+     * Retrieves SDK versions from the API
+     *
+     * @returns SDK versions response
+     * @throws {IPCError} If the request fails or response is invalid
+     *
+     * @example
+     * ```typescript
+     * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+     * try {
+     *   const versions = await client.getSDKVersions();
+     *   console.log('SDK Versions:', versions);
+     * } catch (error) {
+     *   if (error instanceof IPCError) {
+     *     console.error(`Error: ${error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    getSDKVersions(): Promise<SDKVersionsResponse>;
+}
+
+export { IPCClient, type IPCClientOptions, IPCError, type IPDetailsResponse, type IPResponse, type SDKVersionsResponse };

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Configuration options for IPCClient
+ */
+interface IPCClientOptions {
+    /**
+     * API key for authentication (optional)
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the IPC API
+     * @default 'https://ipc.artsnoa.com'
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 10000
+     */
+    timeout?: number;
+}
+/**
+ * Response from the IP API
+ */
+interface IPResponse {
+    /**
+     * IP address
+     */
+    ip: string;
+    /**
+     * Country code (ISO 3166-1 alpha-2)
+     */
+    country: string;
+}
+/**
+ * Response from the IP details API
+ */
+interface IPDetailsResponse {
+    /**
+     * IP address
+     */
+    ip: string;
+    /**
+     * User agent string
+     */
+    userAgent: string;
+    /**
+     * Autonomous System Number
+     */
+    asn: string;
+    /**
+     * Country code (ISO 3166-1 alpha-2)
+     */
+    country: string;
+    /**
+     * Currency code (ISO 4217)
+     */
+    currency: string;
+    /**
+     * Array of language codes
+     */
+    languages: string[];
+    /**
+     * Timestamp of the request (ISO 8601 format)
+     */
+    timestamp: string;
+    /**
+     * API version
+     */
+    version: string;
+}
+/**
+ * Response from the SDK versions API
+ */
+interface SDKVersionsResponse {
+    /**
+     * JavaScript SDK version
+     */
+    javascript: string;
+    /**
+     * Python SDK version
+     */
+    python: string;
+}
+/**
+ * Custom error class for IPC SDK errors
+ */
+declare class IPCError extends Error {
+    readonly statusCode?: number;
+    readonly code?: string;
+    constructor(message: string, statusCode?: number, code?: string);
+}
+
+/**
+ * IPCClient - Client for interacting with the IPC API
+ *
+ * @example
+ * ```typescript
+ * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+ * const data = await client.getIPDetails();
+ * console.log(data);
+ * ```
+ */
+declare class IPCClient {
+    private readonly baseUrls;
+    private readonly apiKey?;
+    private readonly timeout;
+    /**
+     * Creates a new IPCClient instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: IPCClientOptions);
+    /**
+     * Retrieves basic IP information from the API
+     *
+     * @returns IP information with country code
+     * @throws {IPCError} If the request fails or response is invalid
+     *
+     * @example
+     * ```typescript
+     * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+     * try {
+     *   const data = await client.getIP();
+     *   console.log(`Your IP: ${data.ip}, Country: ${data.country}`);
+     * } catch (error) {
+     *   if (error instanceof IPCError) {
+     *     console.error(`Error: ${error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    getIP(): Promise<IPResponse>;
+    /**
+     * Retrieves IP details from the API
+     *
+     * @returns IP details response
+     * @throws {IPCError} If the request fails or response is invalid
+     *
+     * @example
+     * ```typescript
+     * const client = new IPCClient();
+     * try {
+     *   const details = await client.getIPDetails();
+     *   console.log(`IP: ${details.ip}, Country: ${details.country}`);
+     * } catch (error) {
+     *   if (error instanceof IPCError) {
+     *     console.error(`Error: ${error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    getIPDetails(): Promise<IPDetailsResponse>;
+    /**
+     * Retrieves SDK versions from the API
+     *
+     * @returns SDK versions response
+     * @throws {IPCError} If the request fails or response is invalid
+     *
+     * @example
+     * ```typescript
+     * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+     * try {
+     *   const versions = await client.getSDKVersions();
+     *   console.log('SDK Versions:', versions);
+     * } catch (error) {
+     *   if (error instanceof IPCError) {
+     *     console.error(`Error: ${error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    getSDKVersions(): Promise<SDKVersionsResponse>;
+}
+
+export { IPCClient, type IPCClientOptions, IPCError, type IPDetailsResponse, type IPResponse, type SDKVersionsResponse };

package/dist/index.js

@@ -0,0 +1,283 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  IPCClient: () => IPCClient,
+  IPCError: () => IPCError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var IPCError = class _IPCError extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.name = "IPCError";
+    this.statusCode = statusCode;
+    this.code = code;
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, _IPCError);
+    }
+  }
+};
+
+// src/modules/constants.ts
+var DEFAULT_BASE_URL = "https://ipc.artsnoa.com";
+var FALLBACK_BASE_URL = "https://ipc.makedns.net";
+var DEFAULT_TIMEOUT = 1e4;
+var API_VERSION = "v1";
+
+// src/modules/url-utils.ts
+function sanitizeBaseUrl(url) {
+  try {
+    const parsedUrl = new URL(url);
+    if (parsedUrl.protocol !== "https:") {
+      throw new IPCError("Base URL must use https protocol. HTTP is not allowed for security reasons");
+    }
+    return parsedUrl.origin + parsedUrl.pathname.replace(/\/$/, "");
+  } catch (error) {
+    if (error instanceof IPCError) {
+      throw error;
+    }
+    throw new IPCError(`Invalid base URL: ${url}`);
+  }
+}
+function buildUrl(baseUrl, path) {
+  const sanitizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${baseUrl}${sanitizedPath}`;
+}
+
+// src/modules/validators.ts
+function validateIPResponse(data) {
+  if (!data || typeof data !== "object") {
+    return false;
+  }
+  const response = data;
+  return typeof response.ip === "string" && typeof response.country === "string";
+}
+function validateIPDetailsResponse(data) {
+  if (!data || typeof data !== "object") {
+    return false;
+  }
+  const response = data;
+  return typeof response.ip === "string" && typeof response.userAgent === "string" && typeof response.asn === "string" && typeof response.country === "string" && typeof response.currency === "string" && Array.isArray(response.languages) && response.languages.every((lang) => typeof lang === "string") && typeof response.timestamp === "string" && typeof response.version === "string";
+}
+function validateSDKVersionsResponse(data) {
+  if (!data || typeof data !== "object") {
+    return false;
+  }
+  const response = data;
+  return typeof response.javascript === "string" && typeof response.python === "string";
+}
+
+// src/modules/http-client.ts
+async function makeRequestWithFallback(urls, apiKey, timeout) {
+  let lastError = null;
+  for (let i = 0; i < urls.length; i++) {
+    try {
+      return await makeRequest(urls[i], apiKey, timeout);
+    } catch (error) {
+      lastError = error;
+      if (i < urls.length - 1) {
+        continue;
+      }
+    }
+  }
+  throw lastError || new IPCError("All requests failed");
+}
+async function makeRequest(url, apiKey, timeout) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const headers = {
+      "Content-Type": "application/json",
+      "Accept": "application/json"
+    };
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+    const response = await fetch(url, {
+      method: "GET",
+      headers,
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+      let errorCode;
+      try {
+        const errorData = await response.json();
+        if (errorData.message) {
+          errorMessage = errorData.message;
+        }
+        if (errorData.code) {
+          errorCode = errorData.code;
+        }
+      } catch {
+      }
+      throw new IPCError(errorMessage, response.status, errorCode);
+    }
+    const contentType = response.headers.get("Content-Type");
+    if (!contentType || !contentType.includes("application/json")) {
+      throw new IPCError("Invalid response content type. Expected application/json");
+    }
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new IPCError(`Request timeout after ${timeout}ms`);
+    }
+    if (error instanceof IPCError) {
+      throw error;
+    }
+    if (error instanceof TypeError) {
+      throw new IPCError(`Network error: ${error.message}`);
+    }
+    throw new IPCError(
+      error instanceof Error ? error.message : "An unknown error occurred"
+    );
+  }
+}
+
+// src/functions/getIP.ts
+async function getIP(baseUrls, apiKey, timeout) {
+  const urls = baseUrls.map((baseUrl) => buildUrl(baseUrl, `/api/${API_VERSION}/ip`));
+  const data = await makeRequestWithFallback(urls, apiKey, timeout);
+  if (!validateIPResponse(data)) {
+    throw new IPCError("Invalid response structure from API");
+  }
+  return data;
+}
+
+// src/functions/getIPDetails.ts
+async function getIPDetails(baseUrls, apiKey, timeout) {
+  const urls = baseUrls.map((baseUrl) => buildUrl(baseUrl, `/api/${API_VERSION}/ip/details`));
+  const data = await makeRequestWithFallback(urls, apiKey, timeout);
+  if (!validateIPDetailsResponse(data)) {
+    throw new IPCError("Invalid response structure from API");
+  }
+  return data;
+}
+
+// src/functions/getSDKVersions.ts
+async function getSDKVersions(baseUrls, apiKey, timeout) {
+  const urls = baseUrls.map((baseUrl) => buildUrl(baseUrl, `/api/${API_VERSION}/sdk/version`));
+  const data = await makeRequestWithFallback(urls, apiKey, timeout);
+  if (!validateSDKVersionsResponse(data)) {
+    throw new IPCError("Invalid response structure from API");
+  }
+  return data;
+}
+
+// src/client.ts
+var IPCClient = class {
+  /**
+   * Creates a new IPCClient instance
+   *
+   * @param options - Configuration options
+   */
+  constructor(options = {}) {
+    if (options.baseUrl) {
+      this.baseUrls = [sanitizeBaseUrl(options.baseUrl)];
+    } else {
+      this.baseUrls = [
+        sanitizeBaseUrl(DEFAULT_BASE_URL),
+        sanitizeBaseUrl(FALLBACK_BASE_URL)
+      ];
+    }
+    this.apiKey = options.apiKey;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    if (this.timeout <= 0 || this.timeout > 6e4) {
+      throw new IPCError("Timeout must be between 1 and 60000 milliseconds");
+    }
+  }
+  /**
+   * Retrieves basic IP information from the API
+   *
+   * @returns IP information with country code
+   * @throws {IPCError} If the request fails or response is invalid
+   *
+   * @example
+   * ```typescript
+   * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+   * try {
+   *   const data = await client.getIP();
+   *   console.log(`Your IP: ${data.ip}, Country: ${data.country}`);
+   * } catch (error) {
+   *   if (error instanceof IPCError) {
+   *     console.error(`Error: ${error.message}`);
+   *   }
+   * }
+   * ```
+   */
+  async getIP() {
+    return getIP(this.baseUrls, this.apiKey, this.timeout);
+  }
+  /**
+   * Retrieves IP details from the API
+   *
+   * @returns IP details response
+   * @throws {IPCError} If the request fails or response is invalid
+   *
+   * @example
+   * ```typescript
+   * const client = new IPCClient();
+   * try {
+   *   const details = await client.getIPDetails();
+   *   console.log(`IP: ${details.ip}, Country: ${details.country}`);
+   * } catch (error) {
+   *   if (error instanceof IPCError) {
+   *     console.error(`Error: ${error.message}`);
+   *   }
+   * }
+   * ```
+   */
+  async getIPDetails() {
+    return getIPDetails(this.baseUrls, this.apiKey, this.timeout);
+  }
+  /**
+   * Retrieves SDK versions from the API
+   *
+   * @returns SDK versions response
+   * @throws {IPCError} If the request fails or response is invalid
+   *
+   * @example
+   * ```typescript
+   * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+   * try {
+   *   const versions = await client.getSDKVersions();
+   *   console.log('SDK Versions:', versions);
+   * } catch (error) {
+   *   if (error instanceof IPCError) {
+   *     console.error(`Error: ${error.message}`);
+   *   }
+   * }
+   * ```
+   */
+  async getSDKVersions() {
+    return getSDKVersions(this.baseUrls, this.apiKey, this.timeout);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IPCClient,
+  IPCError
+});

package/dist/index.mjs

@@ -0,0 +1,255 @@
+// src/types.ts
+var IPCError = class _IPCError extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.name = "IPCError";
+    this.statusCode = statusCode;
+    this.code = code;
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, _IPCError);
+    }
+  }
+};
+
+// src/modules/constants.ts
+var DEFAULT_BASE_URL = "https://ipc.artsnoa.com";
+var FALLBACK_BASE_URL = "https://ipc.makedns.net";
+var DEFAULT_TIMEOUT = 1e4;
+var API_VERSION = "v1";
+
+// src/modules/url-utils.ts
+function sanitizeBaseUrl(url) {
+  try {
+    const parsedUrl = new URL(url);
+    if (parsedUrl.protocol !== "https:") {
+      throw new IPCError("Base URL must use https protocol. HTTP is not allowed for security reasons");
+    }
+    return parsedUrl.origin + parsedUrl.pathname.replace(/\/$/, "");
+  } catch (error) {
+    if (error instanceof IPCError) {
+      throw error;
+    }
+    throw new IPCError(`Invalid base URL: ${url}`);
+  }
+}
+function buildUrl(baseUrl, path) {
+  const sanitizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${baseUrl}${sanitizedPath}`;
+}
+
+// src/modules/validators.ts
+function validateIPResponse(data) {
+  if (!data || typeof data !== "object") {
+    return false;
+  }
+  const response = data;
+  return typeof response.ip === "string" && typeof response.country === "string";
+}
+function validateIPDetailsResponse(data) {
+  if (!data || typeof data !== "object") {
+    return false;
+  }
+  const response = data;
+  return typeof response.ip === "string" && typeof response.userAgent === "string" && typeof response.asn === "string" && typeof response.country === "string" && typeof response.currency === "string" && Array.isArray(response.languages) && response.languages.every((lang) => typeof lang === "string") && typeof response.timestamp === "string" && typeof response.version === "string";
+}
+function validateSDKVersionsResponse(data) {
+  if (!data || typeof data !== "object") {
+    return false;
+  }
+  const response = data;
+  return typeof response.javascript === "string" && typeof response.python === "string";
+}
+
+// src/modules/http-client.ts
+async function makeRequestWithFallback(urls, apiKey, timeout) {
+  let lastError = null;
+  for (let i = 0; i < urls.length; i++) {
+    try {
+      return await makeRequest(urls[i], apiKey, timeout);
+    } catch (error) {
+      lastError = error;
+      if (i < urls.length - 1) {
+        continue;
+      }
+    }
+  }
+  throw lastError || new IPCError("All requests failed");
+}
+async function makeRequest(url, apiKey, timeout) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const headers = {
+      "Content-Type": "application/json",
+      "Accept": "application/json"
+    };
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+    const response = await fetch(url, {
+      method: "GET",
+      headers,
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+      let errorCode;
+      try {
+        const errorData = await response.json();
+        if (errorData.message) {
+          errorMessage = errorData.message;
+        }
+        if (errorData.code) {
+          errorCode = errorData.code;
+        }
+      } catch {
+      }
+      throw new IPCError(errorMessage, response.status, errorCode);
+    }
+    const contentType = response.headers.get("Content-Type");
+    if (!contentType || !contentType.includes("application/json")) {
+      throw new IPCError("Invalid response content type. Expected application/json");
+    }
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new IPCError(`Request timeout after ${timeout}ms`);
+    }
+    if (error instanceof IPCError) {
+      throw error;
+    }
+    if (error instanceof TypeError) {
+      throw new IPCError(`Network error: ${error.message}`);
+    }
+    throw new IPCError(
+      error instanceof Error ? error.message : "An unknown error occurred"
+    );
+  }
+}
+
+// src/functions/getIP.ts
+async function getIP(baseUrls, apiKey, timeout) {
+  const urls = baseUrls.map((baseUrl) => buildUrl(baseUrl, `/api/${API_VERSION}/ip`));
+  const data = await makeRequestWithFallback(urls, apiKey, timeout);
+  if (!validateIPResponse(data)) {
+    throw new IPCError("Invalid response structure from API");
+  }
+  return data;
+}
+
+// src/functions/getIPDetails.ts
+async function getIPDetails(baseUrls, apiKey, timeout) {
+  const urls = baseUrls.map((baseUrl) => buildUrl(baseUrl, `/api/${API_VERSION}/ip/details`));
+  const data = await makeRequestWithFallback(urls, apiKey, timeout);
+  if (!validateIPDetailsResponse(data)) {
+    throw new IPCError("Invalid response structure from API");
+  }
+  return data;
+}
+
+// src/functions/getSDKVersions.ts
+async function getSDKVersions(baseUrls, apiKey, timeout) {
+  const urls = baseUrls.map((baseUrl) => buildUrl(baseUrl, `/api/${API_VERSION}/sdk/version`));
+  const data = await makeRequestWithFallback(urls, apiKey, timeout);
+  if (!validateSDKVersionsResponse(data)) {
+    throw new IPCError("Invalid response structure from API");
+  }
+  return data;
+}
+
+// src/client.ts
+var IPCClient = class {
+  /**
+   * Creates a new IPCClient instance
+   *
+   * @param options - Configuration options
+   */
+  constructor(options = {}) {
+    if (options.baseUrl) {
+      this.baseUrls = [sanitizeBaseUrl(options.baseUrl)];
+    } else {
+      this.baseUrls = [
+        sanitizeBaseUrl(DEFAULT_BASE_URL),
+        sanitizeBaseUrl(FALLBACK_BASE_URL)
+      ];
+    }
+    this.apiKey = options.apiKey;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    if (this.timeout <= 0 || this.timeout > 6e4) {
+      throw new IPCError("Timeout must be between 1 and 60000 milliseconds");
+    }
+  }
+  /**
+   * Retrieves basic IP information from the API
+   *
+   * @returns IP information with country code
+   * @throws {IPCError} If the request fails or response is invalid
+   *
+   * @example
+   * ```typescript
+   * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+   * try {
+   *   const data = await client.getIP();
+   *   console.log(`Your IP: ${data.ip}, Country: ${data.country}`);
+   * } catch (error) {
+   *   if (error instanceof IPCError) {
+   *     console.error(`Error: ${error.message}`);
+   *   }
+   * }
+   * ```
+   */
+  async getIP() {
+    return getIP(this.baseUrls, this.apiKey, this.timeout);
+  }
+  /**
+   * Retrieves IP details from the API
+   *
+   * @returns IP details response
+   * @throws {IPCError} If the request fails or response is invalid
+   *
+   * @example
+   * ```typescript
+   * const client = new IPCClient();
+   * try {
+   *   const details = await client.getIPDetails();
+   *   console.log(`IP: ${details.ip}, Country: ${details.country}`);
+   * } catch (error) {
+   *   if (error instanceof IPCError) {
+   *     console.error(`Error: ${error.message}`);
+   *   }
+   * }
+   * ```
+   */
+  async getIPDetails() {
+    return getIPDetails(this.baseUrls, this.apiKey, this.timeout);
+  }
+  /**
+   * Retrieves SDK versions from the API
+   *
+   * @returns SDK versions response
+   * @throws {IPCError} If the request fails or response is invalid
+   *
+   * @example
+   * ```typescript
+   * const client = new IPCClient({ apiKey: 'YOUR_API_KEY' });
+   * try {
+   *   const versions = await client.getSDKVersions();
+   *   console.log('SDK Versions:', versions);
+   * } catch (error) {
+   *   if (error instanceof IPCError) {
+   *     console.error(`Error: ${error.message}`);
+   *   }
+   * }
+   * ```
+   */
+  async getSDKVersions() {
+    return getSDKVersions(this.baseUrls, this.apiKey, this.timeout);
+  }
+};
+export {
+  IPCClient,
+  IPCError
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@artsnoa/ipc-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for IPC API - IP address and country lookup",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "pnpm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "ipc",
+    "ip",
+    "geolocation",
+    "country",
+    "sdk",
+    "api"
+  ],
+  "author": "Artsnoa.com(mirseo) <aurora@artsnoa.com>",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Artsnoa/IPC-Javascript-SDK.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Artsnoa/IPC-Javascript-SDK/issues"
+  },
+  "homepage": "https://ipc.artsnoa.com",
+  "packageManager": "pnpm@10.28.2",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}