@sonatel-os/openapi-runtime 0.1.0

package/README.md

@@ -0,0 +1,191 @@
+# 🍊 @sonatel-os/openapi-runtime
+
+**Stop generating code. Start calling APIs.**
+
+[![npm version](https://img.shields.io/npm/v/@sonatel-os/openapi-runtime)](https://www.npmjs.com/package/@sonatel-os/openapi-runtime)
+![npm downloads](https://img.shields.io/npm/dm/@sonatel-os/openapi-runtime)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight, dynamic runtime wrapper for OpenAPI (Swagger) v3. 
+Consume APIs, validate payloads, and mock responses instantly ; without regenerating thousands of lines of JavaScript SDKs every time your backend changes.
+
+---
+
+## 🚀 Why?
+
+**The Old Way (Codegen):**
+1. Backend updates `swagger.json`.
+2. You run `openapi-generator`.
+3. You wait.
+4. You get 50 new files and a git conflict.
+5. Repeat.
+
+**The Runtime Way:**
+1. Drop `api.json` into your project.
+2. Call `runtime.executeAPI('getUsers')`.
+3. Done.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @sonatel-os/openapi-runtime
+# or
+yarn add @sonatel-os/openapi-runtime
+```
+
+-----
+
+## ⚡️ Quick Start
+
+### 1\. Load a Spec
+
+You can load multiple specs (e.g., `products`, `users`, `payment`).
+
+```javascript
+import * as runtime from '@sonatel-os/openapi-runtime';
+import mySpec from './specs/products.openapi.json'; // or fetch it
+
+// Initialize the registry
+await runtime.save({ 
+  name: 'products', 
+  specName: mySpec,
+  autoAuth: true // Magic auth enabled
+});
+```
+
+### 2\. Execute a Request
+
+Use the `operationId` defined in your Swagger file. No need to memorize URLs.
+
+```javascript
+// GET /products/{id}
+const response = await runtime.executeAPI({
+  name: 'products',
+  api: 'getProductById',
+  params: { id: 123 },
+  qs: { details: true } // Query string
+});
+
+console.log(response.body);
+```
+
+-----
+
+## 🔐 Magic Auto-Authentication
+
+Don't hardcode tokens. The runtime automatically injects credentials from `process.env` based on the security scheme names in your Swagger file.
+
+**Naming Convention:** `OAR_{SPEC_NAME}_{SCHEME_NAME}`
+
+| Security Scheme (in YAML) | Env Variable Required |
+|---------------------------|-----------------------|
+| `bearerAuth` (in `products` spec) | `OAR_PRODUCTS_BEARERAUTH` |
+| `apiKey` (in `legacy` spec) | `OAR_LEGACY_APIKEY` |
+| `oauth2` (ClientId) | `OAUTH_CLIENT_ID_PRODUCTS_OAUTH2` |
+
+**Example:**
+If your spec is named `eyone` and uses `BearerAuth`:
+
+```bash
+# .env
+OAR_EYONE_BEARERAUTH=eyJhbGciOiJIUzI1Ni...
+```
+
+*The runtime handles the rest.*
+
+-----
+
+## 🛠️ Features for Power Users
+
+### 1\. The "Poke" System (Mocking & Heuristics)
+
+Need to build a UI before the backend is ready? Or check if an API is alive?
+
+**Mock a Response:**
+Returns a dummy JSON object based on the schema definition.
+
+```javascript
+const mockData = runtime.mockAPI({ 
+  name: 'products', 
+  api: 'createProduct', 
+  status: 201 
+});
+```
+
+**Auto-Probe (Heuristic Check):**
+The runtime can inspect a contract and generate "safe" dummy data to ping an endpoint.
+
+```javascript
+const contract = runtime.showContract({ name: 'products', api: 'searchProducts' });
+// Returns: { method: 'POST', path: '/search', parameters: [...] }
+```
+
+### 2\. Validation
+
+Validate data against the OpenAPI schema without making a network request. Great for form validation.
+
+```javascript
+const result = runtime.validateResponse({
+  name: 'products',
+  api: 'createProduct',
+  data: { price: "invalid-string" } // Should be number
+});
+
+if (!result.valid) console.error(result.errors);
+```
+
+### 3\. Interceptors
+
+Hook into requests before they fly.
+
+```javascript
+runtime.setInterceptors('products', {
+  request: async (req) => {
+    console.log(`📡 Calling ${req.url}`);
+    return req;
+  },
+  error: (err) => {
+    console.error("🔥 API Fire:", err);
+    throw err;
+  }
+});
+```
+
+-----
+
+## ⚛️ Next.js Best Practices
+
+This library uses Node.js `fs` module for some operations.
+
+**Server Components (Recommended):**
+Import directly in `page.jsx` or `layout.jsx`.
+
+```javascript
+import 'server-only';
+import * as runtime from '@sonatel-os/openapi-runtime';
+// Works perfectly
+```
+
+**Client Components:**
+Do **not** import the runtime directly in Client Components (`"use client"`).
+Instead, fetch data in a Server Action or API Route and pass the pure JSON data to your client component.
+
+-----
+
+## 🤝 Contributing
+
+This project is part of the **Sonatel Open Source** initiative.
+PRs are welcome\!
+
+1.  Fork it
+2.  Create your feature branch (`git checkout -b feature/amazing-feature`)
+3.  Commit your changes (`git commit -m 'Add some amazing feature'`)
+4.  Push to the branch (`git push origin feature/amazing-feature`)
+5.  Open a Pull Request
+
+-----
+
+**License**
+MIT © [Sonatel](#)