@sonatel-os/openapi-runtime 0.1.0 → 0.1.1

package/README.md

@@ -73,28 +73,121 @@ console.log(response.body);
 
 -----
 
+You are absolutely right. The previous README was too high-level regarding the specific configuration keys for `openapi.auth.yml` and how `save()` orchestrates the magic.
+
+Here is the detailed **"Magic Authentication"** section to replace the short one in your README. It documents the YAML structure and the manual binding methods based on your source code.
+
+-----
+
 ## 🔐 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.
+The runtime provides three ways to handle authentication: **Implicit (Env Vars)**, **Explicit (YAML)**, and **Manual (Code)**.
 
-**Naming Convention:** `OAR_{SPEC_NAME}_{SCHEME_NAME}`
+When you call `runtime.save()`, it automatically attempts to configure authentication in this order:
 
-| 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` |
+1.  **YAML Config:** Checks for `openapi.auth.yml` in your project root.
+2.  **Environment Variables:** Scans `process.env` for matching naming conventions.
 
-**Example:**
-If your spec is named `eyone` and uses `BearerAuth`:
+### 1\. Environment Variables (Zero Config)
 
-```bash
-# .env
-OAR_EYONE_BEARERAUTH=eyJhbGciOiJIUzI1Ni...
+If your OpenAPI spec has `securitySchemes` defined, the runtime automatically looks for environment variables matching this pattern:
+
+`OAR_<SPEC_NAME>_<SCHEME_NAME>`
+
+  * **API Key:** `OAR_MYAPI_APIKEY`
+  * **Bearer Token:** `OAR_MYAPI_BEARERAUTH` (or `BEARER_MYAPI_BEARERAUTH`)
+  * **Basic Auth:** `BASIC_USER_MYAPI_BASICAUTH` and `BASIC_PASS_MYAPI_BASICAUTH`
+  * **OAuth2 (Client Creds):**
+      * `OAUTH_CLIENT_ID_MYAPI_OAUTH`
+      * `OAUTH_CLIENT_SECRET_MYAPI_OAUTH`
+      * `OAUTH_TOKEN_URL_MYAPI_OAUTH`
+
+*(Note: Spec names and Scheme names are converted to Uppercase and sanitized).*
+
+-----
+
+### 2\. The `openapi.auth.yml` File (Advanced)
+
+For more control (e.g., mapping custom env var names, setting specific scopes, or defining audiences), create a file named **`openapi.auth.yml`** in your project root.
+
+The runtime loads this file during `save()`. You can use `${VAR_NAME}` syntax to inject environment variables.
+
+```yaml
+# openapi.auth.yml
+
+auth:
+  # Matches the 'name' you passed to runtime.save({ name: 'products', ... })
+  products:
+    schemes:
+      # Matches the name in components.securitySchemes in your Swagger file
+      bearerAuth:
+        type: http
+        scheme: bearer
+        tokenFromEnv: MY_CUSTOM_TOKEN_VAR # Maps to process.env.MY_CUSTOM_TOKEN_VAR
+
+      legacyApiKey:
+        type: apiKey
+        in: header
+        name: X-API-KEY
+        valueFromEnv: LEGACY_KEY_VAR
+
+      auth0:
+        type: oauth2
+        flow: client_credentials
+        tokenUrl: https://my-tenant.auth0.com/oauth/token
+        clientIdFromEnv: AUTH0_CLIENT_ID
+        clientSecretFromEnv: AUTH0_CLIENT_SECRET
+        audience: https://api.orange-sonatel.sn
+        scope: "read:products write:orders"
 ```
 
-*The runtime handles the rest.*
+**Supported Config Keys:**
+
+| Type | Config Keys |
+| :--- | :--- |
+| **apiKey** | `in` (header/query), `name`, `value` (hardcoded), `valueFromEnv` |
+| **http (bearer)** | `token`, `tokenFromEnv` |
+| **http (basic)** | `username`, `password`, `usernameFromEnv`, `passwordFromEnv` |
+| **oauth2** | `flow` (only 'client\_credentials'), `tokenUrl`, `clientIdFromEnv`, `clientSecretFromEnv`, `scope`, `audience` |
+
+-----
+
+### 3\. Manual Binding (Programmatic)
 
+If you need dynamic tokens (e.g., retrieved from a database) or want to skip the auto-configuration, you can bind providers manually using `setAuth`.
+
+This is useful for Client Components or complex server-side logic.
+
+```javascript
+import { save, setAuth, bearer, apiKey } from '@sonatel-os/openapi-runtime';
+
+// 1. Load the spec (disable autoAuth if you want full manual control)
+await save({ name: 'products', specName: 'products.json', autoAuth: false });
+
+// 2. Define providers
+// The keys here must match the security scheme names in your Swagger definition.
+setAuth('products', {
+  // Simple Bearer
+  bearerAuth: bearer({ 
+    token: 'my-hardcoded-jwt' 
+  }),
+
+  // Dynamic Bearer (Async) - Great for rotating tokens
+  internalAuth: bearer({
+    getToken: async () => {
+      const token = await db.getValidToken();
+      return token;
+    }
+  }),
+
+  // API Key
+  apiKeyAuth: apiKey({
+    in: 'header',
+    name: 'X-Special-Key',
+    getValue: () => process.env.SPECIAL_KEY
+  })
+});
+```
 -----
 
 ## 🛠️ Features for Power Users

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonatel-os/openapi-runtime",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The dynamic, zero-codegen OpenAPI SDK. Load specs at runtime, mock responses, validate payloads, and execute requests without generating a single file.",
   "license": "MIT",
   "author": "Sonatel Open Source <opensource@sonatel.com>",