@whatsmyfyi/sdk 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @whatsmyfyi/sdk
+
+Official TypeScript SDK for the [whatsmy.fyi](https://whatsmy.fyi) IP geolocation API.
+
+## Installation
+
+```bash
+npm install @whatsmyfyi/sdk
+```
+
+## Usage
+
+```typescript
+import { WhatsMyFyi } from '@whatsmyfyi/sdk'
+
+const client = new WhatsMyFyi({ apiKey: 'wmf_your_key_here' })
+
+// Full IP response
+const data = await client.ip.lookup()
+console.log(data.ip)      // "203.0.113.42"
+console.log(data.city)    // "Amsterdam"
+console.log(data.country) // "NL"
+
+// Quick helpers
+const ip       = await client.ip.address()   // "203.0.113.42"
+const location = await client.ip.location()  // { city, country, countryCode, lat, lng }
+const org      = await client.ip.org()       // { asn, name }
+```
+
+## Get an API Key
+
+Sign up at [whatsmy.fyi/signup](https://whatsmy.fyi/signup) and create a free API key in the dashboard. Free tier includes 10,000 requests/day.
+
+## Features
+
+- TypeScript-first — full type definitions included
+- Zero dependencies
+- Automatic retry on 5xx errors (max 3 attempts, exponential backoff)
+- Works in Node.js, Deno, Bun, and browser (fetch-based)
+- Throws `WhatsMyFyiError` with `code`, `message`, and `status` fields
+
+## Error Handling
+
+```typescript
+import { WhatsMyFyi, WhatsMyFyiError } from '@whatsmyfyi/sdk'
+
+const client = new WhatsMyFyi({ apiKey: 'wmf_...' })
+
+try {
+  const data = await client.ip.lookup()
+} catch (err) {
+  if (err instanceof WhatsMyFyiError) {
+    console.error(err.code)    // e.g. "rate_limit_exceeded"
+    console.error(err.status)  // HTTP status code
+  }
+}
+```
+
+## License
+
+MIT — [whatsmy.fyi](https://whatsmy.fyi)

package/dist/index.d.mts

@@ -0,0 +1,63 @@
+interface IpResponse {
+    status: 'success';
+    ip: string | null;
+    ipv6: string | null;
+    city?: string | null;
+    region?: string | null;
+    region_code?: string | null;
+    country?: string | null;
+    country_name?: string | null;
+    continent?: string | null;
+    latitude?: number | null;
+    longitude?: number | null;
+    timezone?: string | null;
+    timezone_offset?: number | null;
+    postal_code?: string | null;
+    asn?: number | null;
+    org?: string | null;
+    as?: string | null;
+    is_eu?: boolean | null;
+    currency?: string | null;
+    http_protocol?: string | null;
+    tls_version?: string | null;
+    tls_cipher?: string | null;
+    rtt?: number | null;
+    colo?: string | null;
+    proxy?: boolean | null;
+    hosting?: boolean | null;
+}
+interface LocationResult {
+    city: string | null;
+    country: string | null;
+    countryCode: string | null;
+    lat: number | null;
+    lng: number | null;
+}
+interface OrgResult {
+    asn: number | null;
+    name: string | null;
+}
+interface WhatsMyFyiOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+declare class WhatsMyFyiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
+declare class IpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl: string);
+    lookup(): Promise<IpResponse>;
+    address(): Promise<string | null>;
+    location(): Promise<LocationResult>;
+    org(): Promise<OrgResult>;
+}
+declare class WhatsMyFyi {
+    readonly ip: IpClient;
+    constructor({ apiKey, baseUrl }: WhatsMyFyiOptions);
+}
+
+export { type IpResponse, type LocationResult, type OrgResult, WhatsMyFyi, WhatsMyFyiError, type WhatsMyFyiOptions };

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+interface IpResponse {
+    status: 'success';
+    ip: string | null;
+    ipv6: string | null;
+    city?: string | null;
+    region?: string | null;
+    region_code?: string | null;
+    country?: string | null;
+    country_name?: string | null;
+    continent?: string | null;
+    latitude?: number | null;
+    longitude?: number | null;
+    timezone?: string | null;
+    timezone_offset?: number | null;
+    postal_code?: string | null;
+    asn?: number | null;
+    org?: string | null;
+    as?: string | null;
+    is_eu?: boolean | null;
+    currency?: string | null;
+    http_protocol?: string | null;
+    tls_version?: string | null;
+    tls_cipher?: string | null;
+    rtt?: number | null;
+    colo?: string | null;
+    proxy?: boolean | null;
+    hosting?: boolean | null;
+}
+interface LocationResult {
+    city: string | null;
+    country: string | null;
+    countryCode: string | null;
+    lat: number | null;
+    lng: number | null;
+}
+interface OrgResult {
+    asn: number | null;
+    name: string | null;
+}
+interface WhatsMyFyiOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+declare class WhatsMyFyiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
+declare class IpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl: string);
+    lookup(): Promise<IpResponse>;
+    address(): Promise<string | null>;
+    location(): Promise<LocationResult>;
+    org(): Promise<OrgResult>;
+}
+declare class WhatsMyFyi {
+    readonly ip: IpClient;
+    constructor({ apiKey, baseUrl }: WhatsMyFyiOptions);
+}
+
+export { type IpResponse, type LocationResult, type OrgResult, WhatsMyFyi, WhatsMyFyiError, type WhatsMyFyiOptions };

package/dist/index.js

@@ -0,0 +1,99 @@
+"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, {
+  WhatsMyFyi: () => WhatsMyFyi,
+  WhatsMyFyiError: () => WhatsMyFyiError
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://whatsmy.fyi";
+var MAX_RETRIES = 3;
+var WhatsMyFyiError = class extends Error {
+  constructor(code, message, status) {
+    super(message);
+    this.name = "WhatsMyFyiError";
+    this.code = code;
+    this.status = status;
+  }
+};
+async function fetchWithRetry(url, apiKey, attempt = 1) {
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiKey}` }
+  });
+  if (res.status >= 500 && attempt < MAX_RETRIES) {
+    const delay = Math.pow(2, attempt) * 100;
+    await new Promise((r) => setTimeout(r, delay));
+    return fetchWithRetry(url, apiKey, attempt + 1);
+  }
+  if (!res.ok) {
+    let code = "internal_error";
+    let message = `HTTP ${res.status}`;
+    try {
+      const body = await res.json();
+      if (body.error) code = body.error;
+      if (body.message) message = body.message;
+    } catch {
+    }
+    throw new WhatsMyFyiError(code, message, res.status);
+  }
+  return res.json();
+}
+var IpClient = class {
+  constructor(apiKey, baseUrl) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+  async lookup() {
+    return fetchWithRetry(`${this.baseUrl}/api/v1/ip`, this.apiKey);
+  }
+  async address() {
+    const data = await this.lookup();
+    return data.ip ?? data.ipv6 ?? null;
+  }
+  async location() {
+    const data = await this.lookup();
+    return {
+      city: data.city ?? null,
+      country: data.country_name ?? null,
+      countryCode: data.country ?? null,
+      lat: data.latitude ?? null,
+      lng: data.longitude ?? null
+    };
+  }
+  async org() {
+    const data = await this.lookup();
+    return {
+      asn: data.asn ?? null,
+      name: data.org ?? null
+    };
+  }
+};
+var WhatsMyFyi = class {
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL }) {
+    if (!apiKey) throw new Error("apiKey is required");
+    this.ip = new IpClient(apiKey, baseUrl.replace(/\/$/, ""));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WhatsMyFyi,
+  WhatsMyFyiError
+});

package/dist/index.mjs

@@ -0,0 +1,73 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://whatsmy.fyi";
+var MAX_RETRIES = 3;
+var WhatsMyFyiError = class extends Error {
+  constructor(code, message, status) {
+    super(message);
+    this.name = "WhatsMyFyiError";
+    this.code = code;
+    this.status = status;
+  }
+};
+async function fetchWithRetry(url, apiKey, attempt = 1) {
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiKey}` }
+  });
+  if (res.status >= 500 && attempt < MAX_RETRIES) {
+    const delay = Math.pow(2, attempt) * 100;
+    await new Promise((r) => setTimeout(r, delay));
+    return fetchWithRetry(url, apiKey, attempt + 1);
+  }
+  if (!res.ok) {
+    let code = "internal_error";
+    let message = `HTTP ${res.status}`;
+    try {
+      const body = await res.json();
+      if (body.error) code = body.error;
+      if (body.message) message = body.message;
+    } catch {
+    }
+    throw new WhatsMyFyiError(code, message, res.status);
+  }
+  return res.json();
+}
+var IpClient = class {
+  constructor(apiKey, baseUrl) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+  async lookup() {
+    return fetchWithRetry(`${this.baseUrl}/api/v1/ip`, this.apiKey);
+  }
+  async address() {
+    const data = await this.lookup();
+    return data.ip ?? data.ipv6 ?? null;
+  }
+  async location() {
+    const data = await this.lookup();
+    return {
+      city: data.city ?? null,
+      country: data.country_name ?? null,
+      countryCode: data.country ?? null,
+      lat: data.latitude ?? null,
+      lng: data.longitude ?? null
+    };
+  }
+  async org() {
+    const data = await this.lookup();
+    return {
+      asn: data.asn ?? null,
+      name: data.org ?? null
+    };
+  }
+};
+var WhatsMyFyi = class {
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL }) {
+    if (!apiKey) throw new Error("apiKey is required");
+    this.ip = new IpClient(apiKey, baseUrl.replace(/\/$/, ""));
+  }
+};
+export {
+  WhatsMyFyi,
+  WhatsMyFyiError
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@whatsmyfyi/sdk",
+  "version": "0.1.0",
+  "description": "Official SDK for the whatsmy.fyi IP geolocation API",
+  "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"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": ["dist", "README.md"],
+  "keywords": ["ip", "geolocation", "api", "whatsmy.fyi", "ip-address", "ip-lookup"],
+  "author": "whatsmy.fyi",
+  "homepage": "https://whatsmy.fyi",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0"
+  }
+}