@ipwho/ipwho 1.0.1

package/README.md

@@ -0,0 +1,90 @@
+# IPWho TypeScript SDK
+
+## Introduction
+
+`ipwho` is an npm-ready TypeScript wrapper around the [IPWho public API](https://ipwho.is/). The client handles API key injection, chooses between `/me` and `/ip/{ip}` automatically, and provides typed helpers (`getLocation`, `getTimezone`, `getConnection`, `getSecurity`) that normalize and narrow the nested payload so you can pull just the information your service needs without re-implementing parsing logic.
+
+## Table of Contents
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Helper methods](#helper-methods)
+- [Typed responses](#typed-responses)
+- [Forwarding headers](#forwarding-headers)
+
+## Installation
+
+```bash
+npm install ipwho
+```
+
+Or, if you install via yarn:
+
+```bash
+yarn add ipwho
+```
+
+## Getting Started
+
+```ts
+import { IPWho } from 'ipwho';
+
+const client = new IPWho(process.env.IPWHO_API_KEY);
+
+// Resolve the caller's IP by default (calls /me)
+const location = await client.getLocation();
+
+// Look up another IP
+const armyLocation = await client.getLocation('8.8.8.8');
+
+// Use the typed helpers
+const timezone = await client.getTimezone();
+const connection = await client.getConnection();
+const security = await client.getSecurity('1.1.1.1');
+
+// Grab raw payloads when needed
+const me = await client.getMe();
+const remote = await client.getIp('1.2.3.4');
+```
+
+### API key handling
+
+- Provide your `apiKey` when constructing the client: `new IPWho('sk_live_XXXX')`.
+- The SDK adds `apiKey` to every request (query param + `X-API-Key` header).
+- Missing keys throw immediately, so you can fail fast in CI.
+
+## Helper Methods
+
+| Method | Description | Returns |
+| --- | --- | --- |
+| `getLocation(ip?: string)` | Normalized geo data for the requested IP (street-level; defaults to caller). | `GeoLocation` |
+| `getTimezone(ip?: string)` | Timezone metadata, offset, DST, and current time. | `Timezone` |
+| `getConnection(ip?: string)` | ISP connection details (ASN, org, domain, connection type). | `Connection` |
+| `getSecurity(ip?: string)` | VPN/Tor/threat flags and status. | `Security` |
+| `getMe()` | Full raw payload for the caller's IP (identical to `/me`). | `IPWhoData` |
+| `getIp(ip: string)` | Full raw payload for any other IP. | `IPWhoData` |
+
+Each helper accepts an optional `ip` parameter. When `ip` is omitted the SDK automatically calls `/me`; when `ip` is provided it calls `/ip/{ip}`.
+
+## Typed Responses
+
+- `GeoLocation` exports continent, country, coordinates, `dialCode`, and accuracy radius with camel-cased fields that accept both snake_case and camelCase from the API.
+- `Timezone` includes `timeZone`, `abbr`, `offset`, `currentTime`, DST flags, and UTC offset.
+- `Connection`, `Security`, `Currency`, `Flag`, and `UserAgent` wrap nested data (browser/engine/os/device/cpu info, currencies, flags) so you never handle untyped JSON in your application.
+- Refer to `src/types.ts` for the complete interfaces if you need to extend or reconstruct payloads.
+
+## Forwarding Headers
+
+The SDK no longer injects a `User-Agent` header. When proxying requests (e.g., from a browser) forward relevant headers:
+
+```ts
+const forwardHeaders = new Headers();
+for (const [key, value] of request.headers) {
+  if (['user-agent', 'accept'].includes(key.toLowerCase())) {
+    forwardHeaders.set(key, value);
+  }
+}
+
+const client = new IPWho(process.env.IPWHO_API_KEY, { headers: forwardHeaders });
+```
+
+You can add headers by extending the `fetcher` call if you wrap the client; the SDK focuses on the API key and payload normalization.

package/dist/index.d.mts

@@ -0,0 +1,17 @@
+interface IPWhoResponse {
+    success: boolean;
+    message?: string;
+    data?: any;
+    [key: string]: any;
+}
+
+declare class IPWho {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string);
+    private fetcher;
+    getIp(ip: string): Promise<IPWhoResponse>;
+    getMe(): Promise<IPWhoResponse>;
+}
+
+export { IPWho, type IPWhoResponse };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+interface IPWhoResponse {
+    success: boolean;
+    message?: string;
+    data?: any;
+    [key: string]: any;
+}
+
+declare class IPWho {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string);
+    private fetcher;
+    getIp(ip: string): Promise<IPWhoResponse>;
+    getMe(): Promise<IPWhoResponse>;
+}
+
+export { IPWho, type IPWhoResponse };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var a=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var f=(s,e)=>{for(var r in e)a(s,r,{get:e[r],enumerable:!0})},g=(s,e,r,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of h(e))!c.call(s,t)&&t!==r&&a(s,t,{get:()=>e[t],enumerable:!(i=p(e,t))||i.enumerable});return s};var y=s=>g(a({},"__esModule",{value:!0}),s);var u={};f(u,{IPWho:()=>n});module.exports=y(u);var n=class{constructor(e){this.baseUrl="https://api.ipwho.org";if(!e)throw new Error("API Key is required");this.apiKey=e}async fetcher(e){let r=e.includes("?")?"&":"?",i=`${this.baseUrl}${e}${r}apiKey=${this.apiKey}`,o=await(await fetch(i,{headers:{"X-API-Key":this.apiKey,"User-Agent":"ipwho-node-sdk/1.0.0"}})).json();if(!o.success)throw new Error(o.message||"Request failed");return o.data}async getIp(e){return this.fetcher(`/ip/${e}`)}async getMe(){return this.fetcher("/me")}};0&&(module.exports={IPWho});

package/dist/index.mjs

@@ -0,0 +1 @@
+var r=class{constructor(e){this.baseUrl="https://api.ipwho.org";if(!e)throw new Error("API Key is required");this.apiKey=e}async fetcher(e){let t=e.includes("?")?"&":"?",i=`${this.baseUrl}${e}${t}apiKey=${this.apiKey}`,s=await(await fetch(i,{headers:{"X-API-Key":this.apiKey,"User-Agent":"ipwho-node-sdk/1.0.0"}})).json();if(!s.success)throw new Error(s.message||"Request failed");return s.data}async getIp(e){return this.fetcher(`/ip/${e}`)}async getMe(){return this.fetcher("/me")}};export{r as IPWho};

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@ipwho/ipwho",
+  "version": "1.0.1",
+  "description": "SDK for IPWho API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --minify --dts",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}