@zorveus/sdk 0.1.7 → 0.1.9

package/README.md

@@ -1,51 +1,43 @@
-# @zorveus/sdk
+# `@zorveus/sdk`
 
-The official TypeScript and JavaScript client library for the [Zorveus](https://zorveus.com) AI Infrastructure Platform.
+Official TypeScript and JavaScript client library for the [Zorveus](https://zorveus.com) AI platform.
 
----
+## Features
 
-## 📦 Key Capabilities
+- **AI Gateway and streaming**: OpenAI-compatible chat completions across OpenAI, Anthropic, Gemini, DeepSeek, and custom models.
+- **Product User management and credit grants**: Track spend limits, query live balances, and grant promotional credits using `externalUserId`.
+- **Model discovery**: Query available models for an inference key with `client.models.list({ routeStatus: "available" })`.
+- **Spend tracking**: Real-time spending and remaining balance queries with `client.getUsage()`.
+- **OAuth 2.0 PKCE utilities**: PKCE parameters generation, authorization URL construction, and token exchange helpers.
+- **Provider credentials management**: Store and route provider keys.
 
-- **Unified AI Gateway & Streaming**: OpenAI-compatible chat completions across OpenAI, Anthropic, Gemini, DeepSeek, and more.
-- **Product User Management & Credit Grants**: Manage spend limits, query live balances, and issue promotional AI credits using your application's `external_user_id`.
-- **Live Model Discovery**: Query accessible models for any inference key with `client.models.list({ routeStatus: "available" })`.
-- **Live Spend Cap Tracking**: Real-time spending, monthly budget caps, and remaining allowances with `client.getUsage()`.
-- **OAuth 2.0 PKCE Helpers**: Complete PKCE authorization and token exchange utilities for user-owned AI wallet connections.
-- **Provider Credentials Management**: Securely store and route BYOK foundation model provider keys.
-
----
-
-## 🚀 Installation
+## Installation
 
 ```bash
 npm install @zorveus/sdk
 ```
 
----
-
-## 🔑 Client Types
-
-`@zorveus/sdk` provides two specialized clients:
+## Client types
 
-1. **`Zorveus`**: Client for AI inference, chat streaming, model discovery, and spend cap queries using an **Inference API Key** or **User OAuth Token**.
-2. **`ZorveusServiceClient`**: Client for backend administration, product user provisioning, and credit grants using a **Master Organization Service Key** (`zrv_service_...`).
+`@zorveus/sdk` exports two clients:
 
----
+1. **`Zorveus`**: Client for AI inference, chat streaming, model discovery, and usage queries using an Inference API key or user OAuth access token.
+2. **`ZorveusServiceClient`**: Client for administration, product user provisioning, and credit grants using an Organization service key (`zrv_svc_...`).
 
-## ⚡ Quickstart 1: AI Inference & Streaming (`Zorveus`)
+## Quickstart for AI inference and streaming (`Zorveus`)
 
 ```typescript
 import { Zorveus } from "@zorveus/sdk";
 
 const client = new Zorveus({
-  apiKey: process.env.ZORVEUS_INFERENCE_KEY // Direct inference key or user access token
+  apiKey: process.env.ZORVEUS_INFERENCE_KEY
 });
 
-// 1. Live Model Discovery (Zero Mock Fallbacks)
+// List available models
 const models = await client.models.list({ routeStatus: "available" });
 console.log(`Available models: ${models.data.map(m => m.id).join(", ")}`);
 
-// 2. Real-Time Chat Streaming with User Attribution
+// Stream completions with user attribution
 const stream = await client.chat.completions.create({
   model: "openai/gpt-4.1-mini",
   messages: [
@@ -64,29 +56,27 @@ for await (const chunk of stream) {
   process.stdout.write(chunk.choices[0]?.delta?.content || "");
 }
 
-// 3. Query Live Spend Cap & Usage (GET /inference-keys/usage)
+// Query current usage and spend cap
 const usage = await client.getUsage();
 console.log(`Spent this period: $${usage.spent_this_period} / $${usage.spend_cap} ${usage.currency}`);
 console.log(`Remaining balance: $${usage.remaining_balance}`);
 ```
 
----
+## Quickstart for product users and credit grants (`ZorveusServiceClient`)
 
-## 🏢 Quickstart 2: Product Users & Credit Grants (`ZorveusServiceClient`)
-
-Anchor all product user operations directly to your SaaS user identifiers (`external_user_id`), without needing Zorveus internal IDs or session cookies.
+Anchor product user operations to your SaaS user identifiers (`externalUserId`):
 
 ```typescript
 import { ZorveusServiceClient } from "@zorveus/sdk";
 
 const zorveus = new ZorveusServiceClient({
-  apiKey: process.env.ZORVEUS_SERVICE_KEY // Master Service Key: zrv_svc_...
+  apiKey: process.env.ZORVEUS_SERVICE_KEY
 });
 
 const appId = "app_startup_123";
 const externalUserId = "usr_sara_101";
 
-// 1. Auto-Provision or Upsert User Profile
+// Create or update user profile
 const profile = await zorveus.productUsers.createOrUpdate({
   appId,
   externalUserId,
@@ -98,52 +88,50 @@ const profile = await zorveus.productUsers.createOrUpdate({
 console.log("Status:", profile.product_user.status);
 console.log("Live Balance:", profile.product_user.credits?.available_credits);
 
-// 2. Grant Promotional AI Credits (Using External ID)
+// Grant promotional credits
 const grantRes = await zorveus.productUsers.grantCreditByExternalId({
   appId,
   externalUserId,
-  amount: "25.000000000000", // Strict decimal string
+  amount: "25.000000000000",
   currency: "USD",
-  source: "promotion",       // 'admin_adjustment' | 'promotion' | 'purchase' | 'monthly_allowance' | 'support_credit'
+  source: "promotion",
   reason: "Welcome Growth Bonus"
 });
 
 console.log("Issued Grant ID:", grantRes.credit_grant.credit_grant_id);
 console.log("New Balance:", grantRes.credit_summary.remaining_balance);
 
-// 3. Query User's Credit Grants Ledger (Using External ID)
+// Query user credit grants ledger
 const ledger = await zorveus.productUsers.listCreditGrantsByExternalId({
   appId,
   externalUserId,
-  status: "active" // Optional: 'active' | 'exhausted' | 'expired' | 'revoked'
+  status: "active"
 });
 
 for (const grant of ledger.credit_grants) {
   console.log(`- Grant $${grant.amount} (${grant.source}): ${grant.reason}`);
 }
 
-// 4. Query Lightweight Credit Summary
+// Query credit summary
 const summary = await zorveus.productUsers.getCreditSummaryByExternalId({
   appId,
   externalUserId,
   currency: "USD"
 });
 
-console.log("Available Credits:", summary.available_credits);
-console.log("Expiring Soon:", summary.expiring_soon_amount);
+console.log("Available credits:", summary.available_credits);
+console.log("Expiring soon:", summary.expiring_soon_amount);
 ```
 
----
-
-## 🔐 Quickstart 3: OAuth 2.0 PKCE Authentication (`ZorveusOAuth`)
+## Quickstart for OAuth 2.0 PKCE authentication (`ZorveusOAuth`)
 
 ```typescript
 import { ZorveusOAuth } from "@zorveus/sdk";
 
-// Step 1: Generate PKCE parameters
+// Generate PKCE parameters
 const pkce = ZorveusOAuth.generatePKCE();
 
-// Step 2: Generate authorization URL for user consent
+// Generate authorization URL for user consent
 const authUrl = ZorveusOAuth.generateAuthUrl({
   clientId: "zrv_client_123456",
   redirectUri: "https://yourapp.com/oauth/callback",
@@ -152,9 +140,7 @@ const authUrl = ZorveusOAuth.generateAuthUrl({
   scopes: ["inference:write", "models:*"]
 });
 
-// Redirect user to authUrl...
-
-// Step 3: Exchange authorization code for Access Token
+// Exchange authorization code for Access Token
 const tokenData = await ZorveusOAuth.exchangeToken({
   clientId: "zrv_client_123456",
   code: callbackCode,
@@ -162,33 +148,37 @@ const tokenData = await ZorveusOAuth.exchangeToken({
   redirectUri: "https://yourapp.com/oauth/callback"
 });
 
-console.log("User Access Token:", tokenData.access_token);
-console.log("App Connection ID:", tokenData.app_connection_id);
+console.log("User access token:", tokenData.access_token);
+console.log("App connection ID:", tokenData.app_connection_id);
 ```
 
----
+> [!NOTE]
+> OAuth authorization requests require at least one model scope such as `models:*` alongside `inference:write`. Omitting model scopes triggers a `zorveus_model_scope_required` authorization error.
 
-## 📚 Complete API Reference
+## API reference
+
+### `Zorveus` (Inference client)
 
-### `Zorveus` (Inference Client)
 | Method | Description |
 | :--- | :--- |
 | `client.chat.completions.create(params)` | Create streaming or non-streaming chat completions with model routing and metadata attribution |
 | `client.models.list(params)` | List accessible foundation models (`GET /v1/models?route_status=available`) |
 | `client.getUsage(options)` | Query live spend cap, period spend, and remaining allowance (`GET /inference-keys/usage`) |
 
-### `ZorveusServiceClient.productUsers` (Product Users & Credits)
+### `ZorveusServiceClient.productUsers` (Product users and credits)
+
 | Method | Description |
 | :--- | :--- |
-| `createOrUpdate(params)` | Upsert product user by external ID (`PUT /product-users/by-external-id`) |
-| `getByExternalId(params)` | Get product user profile with live cap & credit summary (`GET /product-users/by-external-id`) |
-| `getCreditSummaryByExternalId(params)` | Fetch aggregated live credit balance (`GET /product-users/by-external-id/credit-summary`) |
-| `listCreditGrantsByExternalId(params)` | Query user's credit grants ledger (`GET /product-users/by-external-id/credit-grants`) |
+| `createOrUpdate(params)` | Upsert product user profile by external ID (`PUT /product-users/by-external-id`) |
+| `getByExternalId(params)` | Get product user profile with cap and credit summary (`GET /product-users/by-external-id`) |
+| `getCreditSummaryByExternalId(params)` | Fetch aggregated credit balance (`GET /product-users/by-external-id/credit-summary`) |
+| `listCreditGrantsByExternalId(params)` | Query user credit grants ledger (`GET /product-users/by-external-id/credit-grants`) |
 | `grantCreditByExternalId(params)` | Issue credits anchored to external ID (`POST /product-users/by-external-id/credit-grants`) |
 | `list(params)` | List organization product users (`GET /product-users`) |
 | `revokeCredit(userIdentifier, grantId)` | Revoke active grant (`POST /product-users/{id}/credit-grants/{grantId}/revoke`) |
 
-### `ZorveusServiceClient.providerCredentials` (BYOK Management)
+### `ZorveusServiceClient.providerCredentials` (BYOK management)
+
 | Method | Description |
 | :--- | :--- |
 | `create(params)` | Store encrypted provider credential (OpenAI, Anthropic, Gemini, DeepSeek, etc.) |
@@ -196,7 +186,8 @@ console.log("App Connection ID:", tokenData.app_connection_id);
 | `get(credentialId)` | Get credential metadata |
 | `delete(credentialId)` | Revoke provider credential |
 
-### `ZorveusOAuth` (OAuth PKCE Utilities)
+### `ZorveusOAuth` (OAuth PKCE utilities)
+
 | Method | Description |
 | :--- | :--- |
 | `generatePKCE()` | Generates cryptographically secure `codeVerifier`, `codeChallenge`, and `state` |
@@ -205,11 +196,9 @@ console.log("App Connection ID:", tokenData.app_connection_id);
 | `exchangeToken(params)` | Exchanges authorization code for Bearer access token |
 | `revokeToken(params)` | Revokes connection or access token |
 
----
-
-## 🛡️ Error Handling
+## Error handling
 
-The SDK exposes strongly-typed errors for easy handling:
+The SDK exposes error classes for error handling:
 
 ```typescript
 import { ZorveusError, AuthenticationError, RateLimitError, InvalidDecimalError } from "@zorveus/sdk";
@@ -229,8 +218,6 @@ try {
 }
 ```
 
----
-
-## 📄 License
+## License
 
 MIT © [Zorveus Inc.](https://zorveus.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zorveus/sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Official TypeScript/JavaScript SDK for Zorveus AI Gateway and Management API",
   "repository": {
     "type": "git",