@suronai/sdk 0.1.21 → 0.1.22

package/README.md

@@ -1,6 +1,6 @@
 # @suronai/sdk
 
-App SDK for Suron — drop-in replacement for `dotenv`. Every app boot is gated behind a Telegram approval before secrets are decrypted into `process.env`.
+Runtime SDK for [Suron](https://suronai.com) — a drop-in replacement for `dotenv` that gates every app boot behind a Telegram approval before secrets are decrypted into `process.env`.
 
 ## Install
 
@@ -8,9 +8,13 @@ App SDK for Suron — drop-in replacement for `dotenv`. Every app boot is gated
 npm install @suronai/sdk
 ```
 
+Requires Node.js 18+. Run [`suron init`](https://www.npmjs.com/package/@suronai/cli) in your project first.
+
+---
+
 ## Usage
 
-Replace your `dotenv` bootstrap with two lines at the very top of your entry point, before any `process.env` access:
+Replace your `dotenv` bootstrap at the very top of your entry point, before any `process.env` access:
 
 ```js
 // before
@@ -22,17 +26,39 @@ import { config } from '@suronai/sdk'
 await config()
 ```
 
-That's it. `config()` handles all errors internally — denied boots and timeouts exit the process with a clear message. Any `process.env` access after `await config()` will have the decrypted secrets available.
+That's it. When your app starts:
+
+1. Suron sends a message to your Telegram bot with an **Approve / Deny** button
+2. `await config()` blocks until you tap Approve
+3. Secrets are decrypted into `process.env` — your app continues normally
+4. If you tap Deny, or the timeout expires, the process exits with a clear message
+
+`suron init` can patch this automatically — it detects `dotenv` in your entry point and offers to replace it interactively.
+
+---
 
 ## Requirements
 
-- `.suron.json` in the working directory (created by `suron init`)
-- Encrypted `.env` in the working directory (created by `suron init`)
-- No `SURON_API_URL` setup needed — the URL is stored in `.suron.json` automatically
+- `.suron.json` in the working directory — created by `suron init`
+- Encrypted `.env` in the working directory — created by `suron init`
+- No extra environment variables needed — the API URL is stored in `.suron.json`
+
+---
+
+## API
+
+### `config(options?)`
+
+Drop-in safe wrapper. Handles all known Suron errors with `console.error` + `process.exit(1)`. Only unexpected errors are re-thrown.
+
+```js
+import { config } from '@suronai/sdk'
+await config()
+```
 
-## Advanced: `vault()`
+### `vault(options?)`
 
-If you want to handle errors yourself instead of letting Suron exit the process, use `vault()` directly:
+Same as `config()` but throws on all errors, giving you full control over error handling:
 
 ```js
 import { vault, SuronDeniedError, SuronTimeoutError, SuronConfigError, SuronAppNotFoundError } from '@suronai/sdk'
@@ -48,30 +74,58 @@ try {
 }
 ```
 
-## Options
+### Options
 
-Both `config()` and `vault()` accept the same options:
+Both `config()` and `vault()` accept the same options object:
 
 ```js
 await config({
-  configPath: '/custom/path',  // directory containing .suron.json, default: cwd
-  timeout: 300_000,            // ms to wait for approval, default: 5 minutes
-  pollInterval: 3_000,         // ms between /status polls, default: 3s
+  configPath:   '/custom/path', // dir containing .suron.json — default: process.cwd()
+  timeout:      300_000,        // ms to wait for Telegram approval — default: 5 minutes
+  pollInterval: 3_000,          // ms between /status polls — default: 3s
 })
 ```
 
+---
+
 ## Errors
 
-| Class | When |
+| Class | Thrown when |
 |---|---|
-| `SuronConfigError` | `.suron.json` missing or malformed, or `SURON_API_URL` not set |
-| `SuronAppNotFoundError` | App not registered (`suron init` not run) |
+| `SuronConfigError` | `.suron.json` missing, malformed, or `SURON_API_URL` not set |
+| `SuronAppNotFoundError` | App not registered — run `suron init` |
 | `SuronRateLimitError` | More than 20 boot requests in 1 hour |
 | `SuronDeniedError` | You tapped Deny in Telegram |
-| `SuronTimeoutError` | No approval received within timeout |
+| `SuronTimeoutError` | No approval received within the timeout |
+
+`config()` exits the process for all errors except `SuronRateLimitError` and unknown errors, which are re-thrown. `vault()` always throws.
+
+---
 
-`config()` handles all of the above with `console.error + process.exit(1)`. Only `SuronRateLimitError` and unknown errors are re-thrown.
+## How it works
+
+```
+await config()
+  └─ reads .suron.json             # gets app_id and api_url
+  └─ POST /request-access          # triggers Telegram approval message
+  └─ GET  /status (polling)        # waits for Approve / Deny tap
+  └─ POST /fetch-key               # retrieves private key (single-use token)
+  └─ dotenvx.parse(.env, key)      # decrypts secrets into process.env
+```
+
+The private key never touches disk during runtime. It's received in memory, used to decrypt, and the reference is dropped immediately after.
+
+---
 
 ## Security
 
-The SDK never reads `~/.suron`. It only reads `.suron.json` for the `app_id`, and it never handles the `MASTER_KEY` — that lives exclusively inside the Convex deployment.
+- The SDK reads only `.suron.json` for the `app_id` — no access to `~/.suron-config`
+- The `MASTER_KEY` lives exclusively inside the Convex deployment — the SDK never sees it
+- `/fetch-key` is single-use — the token is consumed on first retrieval
+- `DOTENV_PUBLIC_KEY` and `DOTENV_PRIVATE_KEY` are filtered out of `process.env` after decryption
+
+---
+
+## Related
+
+- [`@suronai/cli`](https://www.npmjs.com/package/@suronai/cli) — the CLI for setup and key rotation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suronai/sdk",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "App SDK for Suron — await vault() to load secrets",
   "type": "module",
   "main": "./src/index.js",