OneAPI

Universal category-based API SDK for developers and AI agents.

One package. 18 categories. 54 provider SDKs. Typed methods. Shared error model. Tree-shakeable imports.

If an agent or developer knows OneAPI, they can call AI, payments, email, storage, auth, databases, maps, social, analytics, search, media, ecommerce, CRM, weather, finance, translation, and DevOps APIs through one consistent interface.

---

Table of contents

• Install
• Quick start
• Categories & SDKs
• Project structure
• Core concepts
• For AI agents
• Documentation
• Contributing
• Scripts
• License

---

Install

npm install apione

Requires Node.js 18+ (native fetch).

import { OpenAI } from "apione/ai";

Or from GitHub / local link:

npm install github:foisalislambd/apione
# or
git clone https://github.com/foisalislambd/apione.git
cd apione && npm install && npm run build
npm link   # then `npm link apione` in your app

---

Quick start

import { OpenAI, Stripe, Resend, OneApiError } from "apione";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
const stripe = new Stripe({ apiKey: process.env.STRIPE_SECRET_KEY! });
const resend = new Resend({ apiKey: process.env.RESEND_API_KEY! });

try {
  const chat = await openai.chatCompletions({
    messages: [{ role: "user", content: "Hello OneAPI" }],
  });

  await resend.sendEmail({
    from: "onboarding@yourdomain.com",
    to: "user@example.com",
    subject: "Welcome",
    html: "<p>Hello</p>",
  });

  console.log(chat);
} catch (err) {
  if (err instanceof OneApiError) {
    console.error(err.provider, err.status, err.code, err.message);
  }
}

Category imports (recommended for tree-shaking)

import { OpenAI, Anthropic, Gemini } from "apione/ai";
import { Stripe, PayPal, Razorpay } from "apione/payment";
import { Twilio, Slack, Discord } from "apione/communication";
import { SendGrid, Resend, Mailgun } from "apione/email";
import { S3, Cloudinary, Uploadcare } from "apione/storage";
import { Auth0, Clerk, FirebaseAuth } from "apione/auth";
import { Supabase, Firebase, Neon } from "apione/database";
import { GoogleMaps, Mapbox, Nominatim } from "apione/maps";
import { Twitter, LinkedIn, Reddit } from "apione/social";
import { Mixpanel, Segment, PostHog } from "apione/analytics";
import { Algolia, Meilisearch, Typesense } from "apione/search";
import { Mux, YouTube, CloudflareStream } from "apione/media";
import { Shopify, WooCommerce, Printful } from "apione/ecommerce";
import { HubSpot, Salesforce, Pipedrive } from "apione/crm";
import { OpenWeatherMap, WeatherApi, Tomorrow } from "apione/weather";
import { CoinGecko, ExchangeRate, Plaid } from "apione/finance";
import { DeepL, GoogleTranslate, LibreTranslate } from "apione/translation";
import { Sentry, GitHub, Vercel } from "apione/devops";

---

Categories & SDKs

Category	Path	SDKs	Docs
AI & ML	apione/ai	OpenAI, Anthropic, Gemini	README
Payments	apione/payment	Stripe, PayPal, Razorpay	README
Communication	apione/communication	Twilio, Slack, Discord	README
Email	apione/email	SendGrid, Resend, Mailgun	README
Storage	apione/storage	S3, Cloudinary, Uploadcare	README
Auth	apione/auth	Auth0, Clerk, Firebase Auth	README
Database	apione/database	Supabase, Firebase, Neon	README
Maps	apione/maps	Google Maps, Mapbox, Nominatim	README
Social	apione/social	Twitter/X, LinkedIn, Reddit	README
Analytics	apione/analytics	Mixpanel, Segment, PostHog	README
Search	apione/search	Algolia, Meilisearch, Typesense	README
Media	apione/media	Mux, YouTube, Cloudflare Stream	README
Ecommerce	apione/ecommerce	Shopify, WooCommerce, Printful	README
CRM	apione/crm	HubSpot, Salesforce, Pipedrive	README
Weather	apione/weather	OpenWeatherMap, WeatherAPI, Tomorrow.io	README
Finance	apione/finance	CoinGecko, ExchangeRate, Plaid	README
Translation	apione/translation	DeepL, Google Translate, LibreTranslate	README
DevOps	apione/devops	Sentry, GitHub, Vercel	README

Every provider folder also has its own full README (src/categories/<category>/<sdk>/README.md) with env vars, constructor options, method tables, and agent notes.

---

Project structure

apione/
|-- src/
|   |-- core/                 # HttpClient, OneApiError, shared types
|   |-- categories/
|   |   |-- ai/
|   |   |   |-- openai/
|   |   |   |-- anthropic/
|   |   |   `-- gemini/
|   |   |-- payment/ ...
|   |   `-- ... (18 categories)
|   `-- index.ts
|-- docs/                     # Architecture & contributor guides
|-- .github/                  # Issue / PR templates, CI
|-- package.json
|-- tsup.config.ts
`-- README.md

Each SDK follows the same layout:

<sdk>/
  types.ts    # request/response param types
  client.ts   # class with methods
  index.ts    # public exports
  README.md   # full documentation

---

Core concepts

Shared client

All SDKs use HttpClient from apione core:

• JSON by default
• Timeout + abort
• Auth schemes: Bearer, Basic, Bot, Token, Key, custom header
• Unified OneApiError (provider, status, code, details)

import { OneApiError } from "apione";

try {
  // any SDK call
} catch (err) {
  if (err instanceof OneApiError) {
    // err.provider === "stripe" | "openai" | ...
  }
}

Configuration pattern

new SomeSdk({
  apiKey: string;                 // required (or provider-specific keys)
  baseUrl?: string;               // override endpoint / sandbox
  timeout?: number;               // ms, default 30000
  headers?: Record<string, string>;
  // + provider-specific options (region, shop, domain, ...)
})

---

For AI agents

1. Prefer category imports (apione/ai) to reduce bundle noise.
2. Always load secrets from environment variables - never hardcode.
3. Use typed methods (chatCompletions, createPaymentIntent) instead of raw http.request unless the endpoint is missing.
4. On failure, read OneApiError.status + details before retrying.
5. Each SDK README includes an AI agent notes section for auth quirks (paise vs cents, query keys, Bot tokens, etc.).

---

Documentation

Doc	Description
docs/README.md	Docs index
docs/architecture.md	Core design, HttpClient, errors
docs/adding-an-sdk.md	Step-by-step guide to add a provider
CONTRIBUTING.md	How to contribute
CODE_OF_CONDUCT.md	Community standards
SECURITY.md	Vulnerability reporting
SUPPORT.md	Where to get help
CHANGELOG.md	Release history

---

Contributing

Contributions are welcome - new SDKs, docs, bug fixes, and examples.

1. Read CONTRIBUTING.md
2. Open an issue (bug / feature / new SDK) or a PR
3. Keep the category -> SDK -> README pattern

git clone https://github.com/foisalislambd/apione.git
cd apione
npm install
npm run typecheck
npm run build

---

Scripts

npm install
npm run build      # tsup -> dist/ (CJS + ESM + d.ts)
npm run typecheck  # tsc --noEmit
npm run smoke      # optional smoke scripts (needs API keys)

---

Versioning & license

• Package: apione@1.0.0
• License: MIT
• Engines: Node >=18
• Changelog: CHANGELOG.md

---

Roadmap

• More providers per category
• Streaming helpers for LLM SDKs
• Built-in AWS SigV4 signer for S3
• Webhook signature utilities
• Official MCP server for agent tooling

See open issues to pick something up.