@suronai/sdk 0.1.19 → 0.1.21

package/README.md

@@ -1,6 +1,6 @@
 # @suronai/sdk
 
-App SDK for Suron — call `await vault()` on boot to load your secrets via Telegram approval.
+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`.
 
 ## Install
 
@@ -10,26 +10,50 @@ npm install @suronai/sdk
 
 ## Usage
 
-Add two lines at the very top of your app entry point, before any `process.env` access:
+Replace your `dotenv` bootstrap with two lines at the very top of your entry point, before any `process.env` access:
 
-```typescript
-import { vault } from '@suronai/sdk'
-await vault()
+```js
+// before
+import { config } from 'dotenv'
+config()
 
-// All process.env values are now available:
-console.log(process.env.DATABASE_URL)
+// after
+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.
+
 ## Requirements
 
-- `SURON_API_URL` env var pointing to your Convex deployment (e.g. `https://happy-animal-123.convex.site`)
 - `.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
+
+## Advanced: `vault()`
+
+If you want to handle errors yourself instead of letting Suron exit the process, use `vault()` directly:
+
+```js
+import { vault, SuronDeniedError, SuronTimeoutError, SuronConfigError, SuronAppNotFoundError } from '@suronai/sdk'
+
+try {
+  await vault()
+} catch (err) {
+  if (err instanceof SuronDeniedError)      { console.error('[suron] Boot denied.');        process.exit(1) }
+  if (err instanceof SuronTimeoutError)     { console.error('[suron] Approval timed out.'); process.exit(1) }
+  if (err instanceof SuronConfigError)      { console.error('[suron]', err.message);        process.exit(1) }
+  if (err instanceof SuronAppNotFoundError) { console.error('[suron]', err.message);        process.exit(1) }
+  throw err
+}
+```
 
 ## Options
 
-```typescript
-await vault({
+Both `config()` and `vault()` accept the same options:
+
+```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
@@ -46,6 +70,8 @@ await vault({
 | `SuronDeniedError` | You tapped Deny in Telegram |
 | `SuronTimeoutError` | No approval received within timeout |
 
+`config()` handles all of the above with `console.error + process.exit(1)`. Only `SuronRateLimitError` and unknown errors are re-thrown.
+
 ## 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.

package/index.d.ts

@@ -8,17 +8,26 @@ export interface VaultOptions {
 }
 
 /**
+ * Drop-in replacement for `dotenv`'s config().
+ *
  * Waits for Telegram approval, then decrypts .env into process.env.
+ * Handles all known Suron errors with console.error + process.exit(1).
+ * Unknown errors are re-thrown.
+ *
+ * Usage:
+ *   import { config } from '@suronai/sdk'
+ *   await config()
+ *
  * Must be awaited before any code that reads process.env.
  */
-export function vault(options?: VaultOptions): Promise<void>;
+export function config(options?: VaultOptions): Promise<void>;
 
 /**
- * Safe wrapper around vault(). Handles all known Suron errors with
- * console.error + process.exit(1). Unknown errors are re-thrown.
+ * Low-level vault. Waits for Telegram approval, then decrypts .env into process.env.
+ * Throws on all errors — use config() if you want automatic error handling.
  * Must be awaited before any code that reads process.env.
  */
-export function config(options?: VaultOptions): Promise<void>;
+export function vault(options?: VaultOptions): Promise<void>;
 
 export class SuronError extends Error {}
 export class SuronConfigError extends SuronError {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suronai/sdk",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "App SDK for Suron — await vault() to load secrets",
   "type": "module",
   "main": "./src/index.js",
@@ -20,7 +20,7 @@
     "lint": "node --check src/index.js src/vault.js src/errors.js src/poll.js src/decrypt.js"
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.0.0"
+    "@dotenvx/dotenvx": "latest"
   },
   "engines": {
     "node": ">=18.0.0"