apistack-sdk 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# apistack-sdk
+
+Official JavaScript client for [APIStack](https://apistack.online): 100+ production APIs (email and phone validation, business days and holidays, loan and mortgage calculators, DNS/SSL/WHOIS, reference data, AI text tools) behind one API key. Free plan: 1,000 calls/month.
+
+```bash
+npm install apistack-sdk
+```
+
+```js
+import { APIStack } from 'apistack-sdk'
+
+const apistack = new APIStack() // reads APISTACK_API_KEY
+
+const email = await apistack.post('/api/utilities/email-address-validator/v1', { email: 'jane.doe@gmial.com' })
+console.log(email.data.isValid, email.data.typoSuggestion) // false { suggestion: 'gmail.com', ... }
+
+const loan = await apistack.get('/api/finance/loan-calculator/v1/payment', { principal: 350000, rate: 6.5, term: 30 })
+console.log(loan.paymentCalculation.monthlyPayment) // 2212.24
+```
+
+Every API's path, parameters and a live tester are in the [catalog](https://apistack.online/tools).
+Errors throw `APIStackError` with `status`, `code` and the response `body`. 429 and 5xx responses are retried with backoff (`maxRetries`, default 2).
+
+**AI agents:** you don't need this package. Connect the MCP server at `https://apistack.online/api/mcp/connect` instead ([setup](https://apistack.online/mcp)).

package/index.d.ts

@@ -0,0 +1,31 @@
+export interface APIStackOptions {
+    /** Defaults to process.env.APISTACK_API_KEY */
+    apiKey?: string
+    /** Defaults to https://apistack.online */
+    baseUrl?: string
+    /** Per-request timeout, default 30000 */
+    timeoutMs?: number
+    /** Retries for network errors, 429 and 5xx; default 2 */
+    maxRetries?: number
+}
+
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+    body?: unknown
+    query?: Record<string, string | number | boolean | null | undefined>
+}
+
+export declare class APIStackError extends Error {
+    status?: number
+    code?: string
+    body?: unknown
+}
+
+export declare class APIStack {
+    constructor(options?: APIStackOptions)
+    request<T = any>(path: string, options?: RequestOptions): Promise<T>
+    get<T = any>(path: string, query?: RequestOptions['query']): Promise<T>
+    post<T = any>(path: string, body?: unknown): Promise<T>
+}
+
+export default APIStack

package/index.js

@@ -0,0 +1,71 @@
+const DEFAULT_BASE_URL = 'https://apistack.online'
+
+export class APIStackError extends Error {
+    constructor(message, { status, code, body } = {}) {
+        super(message)
+        this.name = 'APIStackError'
+        this.status = status
+        this.code = code
+        this.body = body
+    }
+}
+
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms))
+
+export class APIStack {
+    /**
+     * @param {{ apiKey?: string, baseUrl?: string, timeoutMs?: number, maxRetries?: number }} [options]
+     */
+    constructor({ apiKey = globalThis.process?.env?.APISTACK_API_KEY, baseUrl = DEFAULT_BASE_URL, timeoutMs = 30000, maxRetries = 2 } = {}) {
+        if (!apiKey) throw new APIStackError('Missing API key: pass { apiKey } or set APISTACK_API_KEY')
+        this.apiKey = apiKey
+        this.baseUrl = baseUrl.replace(/\/$/, '')
+        this.timeoutMs = timeoutMs
+        this.maxRetries = maxRetries
+    }
+
+    /**
+     * Call any APIStack endpoint, e.g. request('/api/utilities/base64/v1', { body: { operation: 'encode', text: 'hi' } }).
+     * Defaults to POST when a body is given, GET otherwise. Retries 429 and 5xx responses with backoff.
+     */
+    async request(path, { method, body, query } = {}) {
+        const url = new URL(path.startsWith('/') ? path : `/${path}`, this.baseUrl)
+        for (const [key, value] of Object.entries(query || {})) {
+            if (value !== undefined && value !== null) url.searchParams.set(key, String(value))
+        }
+        const verb = (method || (body === undefined ? 'GET' : 'POST')).toUpperCase()
+
+        for (let attempt = 0; ; attempt++) {
+            let response
+            try {
+                response = await fetch(url, {
+                    method: verb,
+                    headers: { 'x-api-key': this.apiKey, ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: AbortSignal.timeout(this.timeoutMs)
+                })
+            } catch (error) {
+                if (attempt < this.maxRetries) { await sleep(500 * 2 ** attempt); continue }
+                throw new APIStackError(`Request failed: ${error.message}`)
+            }
+
+            const text = await response.text()
+            let data
+            try { data = text ? JSON.parse(text) : null } catch { data = text }
+
+            if (response.ok) return data
+            if ((response.status === 429 || response.status >= 500) && attempt < this.maxRetries) {
+                const retryAfter = Number(response.headers.get('retry-after'))
+                await sleep(retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt)
+                continue
+            }
+            const message = (data && (data.message || (typeof data.error === 'string' ? data.error : data.error?.message))) || `HTTP ${response.status}`
+            throw new APIStackError(message, { status: response.status, code: data?.code || data?.error?.code, body: data })
+        }
+    }
+
+    get(path, query) { return this.request(path, { method: 'GET', query }) }
+    post(path, body) { return this.request(path, { method: 'POST', body }) }
+}
+
+export default APIStack

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "apistack-sdk",
+  "version": "0.1.0",
+  "description": "Official client for APIStack: 100+ developer APIs (validation, dates, finance, web/DNS/SSL, reference data, AI text) behind one key",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": { ".": { "types": "./index.d.ts", "default": "./index.js" } },
+  "files": ["index.js", "index.d.ts", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["api", "apistack", "mcp", "ai-agents", "validation", "business-days", "finance"],
+  "homepage": "https://apistack.online/docs",
+  "license": "MIT"
+}