@zorveus/sdk 0.1.0 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +52 -68
  2. package/package.json +6 -1
package/README.md CHANGED
@@ -1,51 +1,43 @@
1
- # @zorveus/sdk
1
+ # `@zorveus/sdk`
2
2
 
3
- The official TypeScript and JavaScript client library for the [Zorveus](https://zorveus.com) AI Infrastructure Platform.
3
+ Official TypeScript and JavaScript client library for the [Zorveus](https://zorveus.com) AI platform.
4
4
 
5
- ---
5
+ ## Features
6
6
 
7
- ## 📦 Key Capabilities
7
+ - **AI Gateway and streaming**: OpenAI-compatible chat completions across OpenAI, Anthropic, Gemini, DeepSeek, and custom models.
8
+ - **Product User management and credit grants**: Track spend limits, query live balances, and grant promotional credits using `externalUserId`.
9
+ - **Model discovery**: Query available models for an inference key with `client.models.list({ routeStatus: "available" })`.
10
+ - **Spend tracking**: Real-time spending and remaining balance queries with `client.getUsage()`.
11
+ - **OAuth 2.0 PKCE utilities**: PKCE parameters generation, authorization URL construction, and token exchange helpers.
12
+ - **Provider credentials management**: Store and route provider keys.
8
13
 
9
- - **Unified AI Gateway & Streaming**: OpenAI-compatible chat completions across OpenAI, Anthropic, Gemini, DeepSeek, and more.
10
- - **Product User Management & Credit Grants**: Manage spend limits, query live balances, and issue promotional AI credits using your application's `external_user_id`.
11
- - **Live Model Discovery**: Query accessible models for any inference key with `client.models.list({ routeStatus: "available" })`.
12
- - **Live Spend Cap Tracking**: Real-time spending, monthly budget caps, and remaining allowances with `client.getUsage()`.
13
- - **OAuth 2.0 PKCE Helpers**: Complete PKCE authorization and token exchange utilities for user-owned AI wallet connections.
14
- - **Provider Credentials Management**: Securely store and route BYOK foundation model provider keys.
15
-
16
- ---
17
-
18
- ## 🚀 Installation
14
+ ## Installation
19
15
 
20
16
  ```bash
21
17
  npm install @zorveus/sdk
22
18
  ```
23
19
 
24
- ---
25
-
26
- ## 🔑 Client Types
20
+ ## Client types
27
21
 
28
- `@zorveus/sdk` provides two specialized clients:
22
+ `@zorveus/sdk` exports two clients:
29
23
 
30
- 1. **`Zorveus`**: Client for AI inference, chat streaming, model discovery, and spend cap queries using an **Inference API Key** or **User OAuth Token**.
31
- 2. **`ZorveusServiceClient`**: Client for backend administration, product user provisioning, and credit grants using a **Master Organization Service Key** (`zrv_service_...`).
24
+ 1. **`Zorveus`**: Client for AI inference, chat streaming, model discovery, and usage queries using an Inference API key or user OAuth access token.
25
+ 2. **`ZorveusServiceClient`**: Client for administration, product user provisioning, and credit grants using an Organization service key (`zrv_svc_...`).
32
26
 
33
- ---
34
-
35
- ## ⚡ Quickstart 1: AI Inference & Streaming (`Zorveus`)
27
+ ## Quickstart for AI inference and streaming (`Zorveus`)
36
28
 
37
29
  ```typescript
38
30
  import { Zorveus } from "@zorveus/sdk";
39
31
 
40
32
  const client = new Zorveus({
41
- apiKey: process.env.ZORVEUS_INFERENCE_KEY // Direct inference key or user access token
33
+ apiKey: process.env.ZORVEUS_INFERENCE_KEY
42
34
  });
43
35
 
44
- // 1. Live Model Discovery (Zero Mock Fallbacks)
36
+ // List available models
45
37
  const models = await client.models.list({ routeStatus: "available" });
46
38
  console.log(`Available models: ${models.data.map(m => m.id).join(", ")}`);
47
39
 
48
- // 2. Real-Time Chat Streaming with User Attribution
40
+ // Stream completions with user attribution
49
41
  const stream = await client.chat.completions.create({
50
42
  model: "openai/gpt-4.1-mini",
51
43
  messages: [
@@ -64,29 +56,27 @@ for await (const chunk of stream) {
64
56
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
65
57
  }
66
58
 
67
- // 3. Query Live Spend Cap & Usage (GET /inference-keys/usage)
59
+ // Query current usage and spend cap
68
60
  const usage = await client.getUsage();
69
61
  console.log(`Spent this period: $${usage.spent_this_period} / $${usage.spend_cap} ${usage.currency}`);
70
62
  console.log(`Remaining balance: $${usage.remaining_balance}`);
71
63
  ```
72
64
 
73
- ---
74
-
75
- ## 🏢 Quickstart 2: Product Users & Credit Grants (`ZorveusServiceClient`)
65
+ ## Quickstart for product users and credit grants (`ZorveusServiceClient`)
76
66
 
77
- Anchor all product user operations directly to your SaaS user identifiers (`external_user_id`), without needing Zorveus internal IDs or session cookies.
67
+ Anchor product user operations to your SaaS user identifiers (`externalUserId`):
78
68
 
79
69
  ```typescript
80
70
  import { ZorveusServiceClient } from "@zorveus/sdk";
81
71
 
82
72
  const zorveus = new ZorveusServiceClient({
83
- apiKey: process.env.ZORVEUS_SERVICE_KEY // Master Service Key: zrv_svc_...
73
+ apiKey: process.env.ZORVEUS_SERVICE_KEY
84
74
  });
85
75
 
86
76
  const appId = "app_startup_123";
87
77
  const externalUserId = "usr_sara_101";
88
78
 
89
- // 1. Auto-Provision or Upsert User Profile
79
+ // Create or update user profile
90
80
  const profile = await zorveus.productUsers.createOrUpdate({
91
81
  appId,
92
82
  externalUserId,
@@ -98,52 +88,50 @@ const profile = await zorveus.productUsers.createOrUpdate({
98
88
  console.log("Status:", profile.product_user.status);
99
89
  console.log("Live Balance:", profile.product_user.credits?.available_credits);
100
90
 
101
- // 2. Grant Promotional AI Credits (Using External ID)
91
+ // Grant promotional credits
102
92
  const grantRes = await zorveus.productUsers.grantCreditByExternalId({
103
93
  appId,
104
94
  externalUserId,
105
- amount: "25.000000000000", // Strict decimal string
95
+ amount: "25.000000000000",
106
96
  currency: "USD",
107
- source: "promotion", // 'admin_adjustment' | 'promotion' | 'purchase' | 'monthly_allowance' | 'support_credit'
97
+ source: "promotion",
108
98
  reason: "Welcome Growth Bonus"
109
99
  });
110
100
 
111
101
  console.log("Issued Grant ID:", grantRes.credit_grant.credit_grant_id);
112
102
  console.log("New Balance:", grantRes.credit_summary.remaining_balance);
113
103
 
114
- // 3. Query User's Credit Grants Ledger (Using External ID)
104
+ // Query user credit grants ledger
115
105
  const ledger = await zorveus.productUsers.listCreditGrantsByExternalId({
116
106
  appId,
117
107
  externalUserId,
118
- status: "active" // Optional: 'active' | 'exhausted' | 'expired' | 'revoked'
108
+ status: "active"
119
109
  });
120
110
 
121
111
  for (const grant of ledger.credit_grants) {
122
112
  console.log(`- Grant $${grant.amount} (${grant.source}): ${grant.reason}`);
123
113
  }
124
114
 
125
- // 4. Query Lightweight Credit Summary
115
+ // Query credit summary
126
116
  const summary = await zorveus.productUsers.getCreditSummaryByExternalId({
127
117
  appId,
128
118
  externalUserId,
129
119
  currency: "USD"
130
120
  });
131
121
 
132
- console.log("Available Credits:", summary.available_credits);
133
- console.log("Expiring Soon:", summary.expiring_soon_amount);
122
+ console.log("Available credits:", summary.available_credits);
123
+ console.log("Expiring soon:", summary.expiring_soon_amount);
134
124
  ```
135
125
 
136
- ---
137
-
138
- ## 🔐 Quickstart 3: OAuth 2.0 PKCE Authentication (`ZorveusOAuth`)
126
+ ## Quickstart for OAuth 2.0 PKCE authentication (`ZorveusOAuth`)
139
127
 
140
128
  ```typescript
141
129
  import { ZorveusOAuth } from "@zorveus/sdk";
142
130
 
143
- // Step 1: Generate PKCE parameters
131
+ // Generate PKCE parameters
144
132
  const pkce = ZorveusOAuth.generatePKCE();
145
133
 
146
- // Step 2: Generate authorization URL for user consent
134
+ // Generate authorization URL for user consent
147
135
  const authUrl = ZorveusOAuth.generateAuthUrl({
148
136
  clientId: "zrv_client_123456",
149
137
  redirectUri: "https://yourapp.com/oauth/callback",
@@ -152,9 +140,7 @@ const authUrl = ZorveusOAuth.generateAuthUrl({
152
140
  scopes: ["inference:write", "models:*"]
153
141
  });
154
142
 
155
- // Redirect user to authUrl...
156
-
157
- // Step 3: Exchange authorization code for Access Token
143
+ // Exchange authorization code for Access Token
158
144
  const tokenData = await ZorveusOAuth.exchangeToken({
159
145
  clientId: "zrv_client_123456",
160
146
  code: callbackCode,
@@ -162,33 +148,34 @@ const tokenData = await ZorveusOAuth.exchangeToken({
162
148
  redirectUri: "https://yourapp.com/oauth/callback"
163
149
  });
164
150
 
165
- console.log("User Access Token:", tokenData.access_token);
166
- console.log("App Connection ID:", tokenData.app_connection_id);
151
+ console.log("User access token:", tokenData.access_token);
152
+ console.log("App connection ID:", tokenData.app_connection_id);
167
153
  ```
168
154
 
169
- ---
155
+ ## API reference
170
156
 
171
- ## 📚 Complete API Reference
157
+ ### `Zorveus` (Inference client)
172
158
 
173
- ### `Zorveus` (Inference Client)
174
159
  | Method | Description |
175
160
  | :--- | :--- |
176
161
  | `client.chat.completions.create(params)` | Create streaming or non-streaming chat completions with model routing and metadata attribution |
177
162
  | `client.models.list(params)` | List accessible foundation models (`GET /v1/models?route_status=available`) |
178
163
  | `client.getUsage(options)` | Query live spend cap, period spend, and remaining allowance (`GET /inference-keys/usage`) |
179
164
 
180
- ### `ZorveusServiceClient.productUsers` (Product Users & Credits)
165
+ ### `ZorveusServiceClient.productUsers` (Product users and credits)
166
+
181
167
  | Method | Description |
182
168
  | :--- | :--- |
183
- | `createOrUpdate(params)` | Upsert product user by external ID (`PUT /product-users/by-external-id`) |
184
- | `getByExternalId(params)` | Get product user profile with live cap & credit summary (`GET /product-users/by-external-id`) |
185
- | `getCreditSummaryByExternalId(params)` | Fetch aggregated live credit balance (`GET /product-users/by-external-id/credit-summary`) |
186
- | `listCreditGrantsByExternalId(params)` | Query user's credit grants ledger (`GET /product-users/by-external-id/credit-grants`) |
169
+ | `createOrUpdate(params)` | Upsert product user profile by external ID (`PUT /product-users/by-external-id`) |
170
+ | `getByExternalId(params)` | Get product user profile with cap and credit summary (`GET /product-users/by-external-id`) |
171
+ | `getCreditSummaryByExternalId(params)` | Fetch aggregated credit balance (`GET /product-users/by-external-id/credit-summary`) |
172
+ | `listCreditGrantsByExternalId(params)` | Query user credit grants ledger (`GET /product-users/by-external-id/credit-grants`) |
187
173
  | `grantCreditByExternalId(params)` | Issue credits anchored to external ID (`POST /product-users/by-external-id/credit-grants`) |
188
174
  | `list(params)` | List organization product users (`GET /product-users`) |
189
175
  | `revokeCredit(userIdentifier, grantId)` | Revoke active grant (`POST /product-users/{id}/credit-grants/{grantId}/revoke`) |
190
176
 
191
- ### `ZorveusServiceClient.providerCredentials` (BYOK Management)
177
+ ### `ZorveusServiceClient.providerCredentials` (BYOK management)
178
+
192
179
  | Method | Description |
193
180
  | :--- | :--- |
194
181
  | `create(params)` | Store encrypted provider credential (OpenAI, Anthropic, Gemini, DeepSeek, etc.) |
@@ -196,7 +183,8 @@ console.log("App Connection ID:", tokenData.app_connection_id);
196
183
  | `get(credentialId)` | Get credential metadata |
197
184
  | `delete(credentialId)` | Revoke provider credential |
198
185
 
199
- ### `ZorveusOAuth` (OAuth PKCE Utilities)
186
+ ### `ZorveusOAuth` (OAuth PKCE utilities)
187
+
200
188
  | Method | Description |
201
189
  | :--- | :--- |
202
190
  | `generatePKCE()` | Generates cryptographically secure `codeVerifier`, `codeChallenge`, and `state` |
@@ -205,11 +193,9 @@ console.log("App Connection ID:", tokenData.app_connection_id);
205
193
  | `exchangeToken(params)` | Exchanges authorization code for Bearer access token |
206
194
  | `revokeToken(params)` | Revokes connection or access token |
207
195
 
208
- ---
209
-
210
- ## 🛡️ Error Handling
196
+ ## Error handling
211
197
 
212
- The SDK exposes strongly-typed errors for easy handling:
198
+ The SDK exposes error classes for error handling:
213
199
 
214
200
  ```typescript
215
201
  import { ZorveusError, AuthenticationError, RateLimitError, InvalidDecimalError } from "@zorveus/sdk";
@@ -229,8 +215,6 @@ try {
229
215
  }
230
216
  ```
231
217
 
232
- ---
233
-
234
- ## 📄 License
218
+ ## License
235
219
 
236
220
  MIT © [Zorveus Inc.](https://zorveus.com)
package/package.json CHANGED
@@ -1,7 +1,12 @@
1
1
  {
2
2
  "name": "@zorveus/sdk",
3
- "version": "0.1.0",
3
+ "version": "0.1.8",
4
4
  "description": "Official TypeScript/JavaScript SDK for Zorveus AI Gateway and Management API",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/zorveus/zorveus-ts",
8
+ "directory": "packages/sdk"
9
+ },
5
10
  "main": "./dist/index.js",
6
11
  "module": "./dist/index.mjs",
7
12
  "types": "./dist/index.d.ts",