@simpleapps-com/augur-api 0.2.5 → 0.2.7

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 (45) hide show
  1. package/API-DISCOVERY.md +132 -0
  2. package/AUTHENTICATION.md +371 -0
  3. package/QUICKSTART.md +255 -0
  4. package/README.md +125 -91
  5. package/dist/cjs/client.d.ts +36 -1
  6. package/dist/cjs/client.d.ts.map +1 -1
  7. package/dist/cjs/client.js +54 -1
  8. package/dist/cjs/client.js.map +1 -1
  9. package/dist/cjs/core/config.d.ts +24 -0
  10. package/dist/cjs/core/config.d.ts.map +1 -1
  11. package/dist/cjs/core/config.js +12 -1
  12. package/dist/cjs/core/config.js.map +1 -1
  13. package/dist/cjs/index.d.ts +2 -2
  14. package/dist/cjs/index.d.ts.map +1 -1
  15. package/dist/cjs/index.js +5 -2
  16. package/dist/cjs/index.js.map +1 -1
  17. package/dist/cjs/services/vmi/client.d.ts +501 -1
  18. package/dist/cjs/services/vmi/client.d.ts.map +1 -1
  19. package/dist/cjs/services/vmi/client.js +408 -0
  20. package/dist/cjs/services/vmi/client.js.map +1 -1
  21. package/dist/esm/client.d.ts +36 -1
  22. package/dist/esm/client.d.ts.map +1 -1
  23. package/dist/esm/client.js +52 -0
  24. package/dist/esm/client.js.map +1 -1
  25. package/dist/esm/core/config.d.ts +24 -0
  26. package/dist/esm/core/config.d.ts.map +1 -1
  27. package/dist/esm/core/config.js +10 -0
  28. package/dist/esm/core/config.js.map +1 -1
  29. package/dist/esm/index.d.ts +2 -2
  30. package/dist/esm/index.d.ts.map +1 -1
  31. package/dist/esm/index.js +3 -1
  32. package/dist/esm/index.js.map +1 -1
  33. package/dist/esm/services/vmi/client.d.ts +501 -1
  34. package/dist/esm/services/vmi/client.d.ts.map +1 -1
  35. package/dist/esm/services/vmi/client.js +408 -0
  36. package/dist/esm/services/vmi/client.js.map +1 -1
  37. package/dist/types/client.d.ts +36 -1
  38. package/dist/types/client.d.ts.map +1 -1
  39. package/dist/types/core/config.d.ts +24 -0
  40. package/dist/types/core/config.d.ts.map +1 -1
  41. package/dist/types/index.d.ts +2 -2
  42. package/dist/types/index.d.ts.map +1 -1
  43. package/dist/types/services/vmi/client.d.ts +501 -1
  44. package/dist/types/services/vmi/client.d.ts.map +1 -1
  45. package/package.json +5 -2
package/QUICKSTART.md ADDED
@@ -0,0 +1,255 @@
1
+ # Quick Start Guide
2
+
3
+ Get up and running with the Augur API Client in under 5 minutes.
4
+
5
+ ## What is This?
6
+
7
+ The Augur API Client connects your application to 13 different business services (like user management, inventory, pricing) through a single, easy-to-use interface. Instead of learning 13 different APIs, you learn one.
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ npm install @simpleapps-com/augur-api
13
+ ```
14
+
15
+ ## Your First API Call
16
+
17
+ ### Step 1: Get Your Credentials
18
+
19
+ You need two pieces of information:
20
+ - **Site ID**: Identifies which site/tenant you're working with (e.g., `my-company-site`)
21
+ - **Bearer Token**: Your authentication JWT token (looks like `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`)
22
+
23
+ Ask your system administrator or check your project's environment variables.
24
+
25
+ ### Step 2: Make Your First Call
26
+
27
+ ```typescript
28
+ import { AugurAPI } from '@simpleapps-com/augur-api';
29
+
30
+ // Create the API client
31
+ const api = new AugurAPI({
32
+ siteId: 'your-site-id', // Replace with your actual site ID
33
+ bearerToken: 'your-jwt-token' // Replace with your actual token
34
+ });
35
+
36
+ // Make your first API call - list users
37
+ try {
38
+ const users = await api.joomla.users.list({ limit: 5 });
39
+ console.log('Success! Found users:', users.data.length);
40
+ console.log('First user:', users.data[0]?.name);
41
+ } catch (error) {
42
+ console.error('Something went wrong:', error.message);
43
+ }
44
+ ```
45
+
46
+ ### Step 3: Verify It Works
47
+
48
+ If you see output like this, you're ready to go:
49
+ ```
50
+ Success! Found users: 5
51
+ First user: John Smith
52
+ ```
53
+
54
+ ## Common First Steps
55
+
56
+ ### Health Check (No Authentication Required)
57
+ Test your connection without needing authentication:
58
+
59
+ ```typescript
60
+ const api = new AugurAPI({
61
+ siteId: 'your-site-id'
62
+ // No bearerToken needed for health checks
63
+ });
64
+
65
+ const health = await api.joomla.getHealthCheck();
66
+ console.log('Service is:', health.data.status); // Should show "OK"
67
+ ```
68
+
69
+ ### Environment Variables Setup
70
+ Create a `.env` file in your project:
71
+
72
+ ```bash
73
+ # .env file
74
+ AUGUR_SITE_ID=your-site-id-here
75
+ AUGUR_JWT_TOKEN=your-jwt-token-here
76
+ ```
77
+
78
+ Then use them in your code:
79
+
80
+ ```typescript
81
+ const api = new AugurAPI({
82
+ siteId: process.env.AUGUR_SITE_ID!,
83
+ bearerToken: process.env.AUGUR_JWT_TOKEN!
84
+ });
85
+ ```
86
+
87
+ ## Understanding the Response Format
88
+
89
+ All API calls return data in the same format:
90
+
91
+ ```typescript
92
+ const response = await api.joomla.users.list();
93
+
94
+ // Response structure:
95
+ // {
96
+ // status: 200, // HTTP status code
97
+ // message: "Ok", // Status message
98
+ // data: [...], // The actual data you want
99
+ // totalResults: 150 // Total count (for lists)
100
+ // }
101
+
102
+ // Access the actual data:
103
+ const users = response.data; // Array of users
104
+ const totalCount = response.totalResults; // Total number of users
105
+ ```
106
+
107
+ ## Two Ways to Get Data
108
+
109
+ Every API call has two versions:
110
+
111
+ ```typescript
112
+ // 1. Full response (includes metadata)
113
+ const response = await api.joomla.users.list();
114
+ console.log('Users:', response.data);
115
+ console.log('Total:', response.totalResults);
116
+
117
+ // 2. Data only (just the data you want)
118
+ const users = await api.joomla.users.listData();
119
+ console.log('Users:', users); // Direct array access
120
+ ```
121
+
122
+ ## What Can You Do?
123
+
124
+ The API gives you access to:
125
+
126
+ | Service | What It Does | Example |
127
+ |---------|--------------|---------|
128
+ | **joomla** | Users, content, site management | `api.joomla.users.list()` |
129
+ | **commerce** | Shopping carts, checkout | `api.commerce.cartHeaders.list()` |
130
+ | **pricing** | Product pricing, calculations | `api.pricing.getPrice()` |
131
+ | **vmi** | Inventory, warehouses | `api.vmi.warehouses.list()` |
132
+ | **opensearch** | Product search | `api.opensearch.itemSearch.search()` |
133
+ | **items** | Product catalog | `api.items.categories.list()` |
134
+ | **customers** | Customer data | `api.customers.customer.list()` |
135
+
136
+ ## Common Patterns
137
+
138
+ ### List Things with Limits
139
+ ```typescript
140
+ // Get first 10 users
141
+ const users = await api.joomla.users.list({ limit: 10 });
142
+
143
+ // Get first 20 products
144
+ const products = await api.items.products.list({ limit: 20 });
145
+ ```
146
+
147
+ ### Get Single Items
148
+ ```typescript
149
+ // Get specific user by ID
150
+ const user = await api.joomla.users.get('123');
151
+
152
+ // Get specific product by ID
153
+ const product = await api.items.products.get(456);
154
+ ```
155
+
156
+ ### Search for Things
157
+ ```typescript
158
+ // Search for products
159
+ const results = await api.opensearch.itemSearch.search({
160
+ q: 'wire', // Search term
161
+ size: 10 // Number of results
162
+ });
163
+ ```
164
+
165
+ ## Performance Tip: Caching
166
+
167
+ Add caching to make your app faster:
168
+
169
+ ```typescript
170
+ // Cache user list for 2 hours
171
+ const users = await api.joomla.users.list({
172
+ limit: 10,
173
+ edgeCache: 2 // Cache for 2 hours
174
+ });
175
+
176
+ // Cache product search for 4 hours
177
+ const products = await api.opensearch.itemSearch.search({
178
+ q: 'electrical',
179
+ size: 20,
180
+ edgeCache: 4 // Cache for 4 hours
181
+ });
182
+ ```
183
+
184
+ **Cache Options:** 1, 2, 3, 4, 5, or 8 hours only.
185
+
186
+ ## Don't Know What's Available?
187
+
188
+ Use the discovery system to explore:
189
+
190
+ ```typescript
191
+ // See all available services
192
+ const services = await api.discover();
193
+ services.forEach(service => {
194
+ console.log(`${service.serviceName}: ${service.description}`);
195
+ });
196
+
197
+ // Find specific functionality
198
+ const userStuff = await api.findEndpoint('user management');
199
+ const inventoryStuff = await api.findEndpoint('inventory');
200
+ ```
201
+
202
+ Learn more in the [API Discovery Guide](./API-DISCOVERY.md).
203
+
204
+ ## Error Handling
205
+
206
+ Wrap your API calls in try/catch:
207
+
208
+ ```typescript
209
+ try {
210
+ const users = await api.joomla.users.list();
211
+ console.log('Got users:', users.data.length);
212
+ } catch (error) {
213
+ if (error.message.includes('401')) {
214
+ console.error('Authentication failed - check your token');
215
+ } else if (error.message.includes('404')) {
216
+ console.error('Endpoint not found - check your URL');
217
+ } else {
218
+ console.error('Something else went wrong:', error.message);
219
+ }
220
+ }
221
+ ```
222
+
223
+ ## Troubleshooting
224
+
225
+ **"Authentication failed"**
226
+ - Check your `bearerToken` is correct and not expired
227
+ - Verify your `siteId` matches your environment
228
+
229
+ **"Cannot find endpoint"**
230
+ - Try a health check first: `api.joomla.getHealthCheck()`
231
+ - Verify you're using the right service name
232
+
233
+ **"Network error"**
234
+ - Check your internet connection
235
+ - Verify the API endpoints are accessible from your network
236
+
237
+ **"Validation error"**
238
+ - Check the parameter names and types match the examples
239
+ - Look at the error message for specific field issues
240
+
241
+ ## Next Steps
242
+
243
+ 1. **Read the main [README](./README.md)** for comprehensive documentation
244
+ 2. **Explore the [API Discovery Guide](./API-DISCOVERY.md)** to find functionality
245
+ 3. **Check the Integration Guides** in the README for React, Node.js, etc.
246
+ 4. **Look at Error Handling** section for production-ready error management
247
+
248
+ ## Need Help?
249
+
250
+ - Check the comprehensive [README](./README.md) for detailed examples
251
+ - Use `api.discover()` to explore available functionality
252
+ - Look at the error messages - they usually tell you what's wrong
253
+ - Ask your team lead or system administrator for credentials
254
+
255
+ You're ready to build! Start with simple calls like listing users or checking health, then gradually explore more functionality as you need it.
package/README.md CHANGED
@@ -4,12 +4,14 @@ A comprehensive TypeScript client library for accessing Augur microservices with
4
4
 
5
5
  ## Table of Contents
6
6
 
7
+ - [🚀 Quick Start Guide](./QUICKSTART.md) - **New to Augur API? Start here!**
7
8
  - [Overview](#overview)
8
9
  - [🎯 AI-Powered Discovery System - Where Code Writes Itself](#-ai-powered-discovery-system---where-code-writes-itself)
10
+ - [📖 API Discovery Guide](./API-DISCOVERY.md) - Complete discovery system reference
9
11
  - [Features](#features)
10
12
  - [Installation](#installation)
11
13
  - [Getting Started](#getting-started)
12
- - [Authentication & Security](#authentication--security)
14
+ - [Authentication & Security](#authentication--security) | [📋 Complete Auth Guide](./AUTHENTICATION.md)
13
15
  - [API Documentation](#api-documentation)
14
16
  - [Advanced Features](#advanced-features)
15
17
  - [Integration Guides](#integration-guides)
@@ -130,6 +132,7 @@ const results = await api.findEndpoint('settings', {
130
132
 
131
133
  ## Features
132
134
 
135
+ ✅ **Context-Aware Magic** - Eliminate 70% of setup boilerplate with `fromContext()` ⭐ NEW!
133
136
  ✅ **AI-Powered Discovery** - Natural language search finds any functionality instantly
134
137
  ✅ **Semantic Intelligence** - Understands business context and suggests workflows
135
138
  ✅ **Cross-Service Awareness** - Maps relationships between all microservices
@@ -165,12 +168,15 @@ pnpm add @simpleapps-com/augur-api
165
168
  ```typescript
166
169
  import { AugurAPI } from '@simpleapps-com/augur-api';
167
170
 
168
- // Initialize the client
171
+ // Traditional approach - manual configuration
169
172
  const api = new AugurAPI({
170
173
  siteId: 'your-site-id', // Required for all endpoints
171
174
  bearerToken: 'your-jwt-token', // Required except for health checks
172
175
  });
173
176
 
177
+ // Context-aware approach (recommended) - eliminates boilerplate
178
+ const api = AugurAPI.fromContext(context);
179
+
174
180
  // Make your first API call
175
181
  const users = await api.joomla.users.list({
176
182
  limit: 10,
@@ -180,6 +186,82 @@ const users = await api.joomla.users.list({
180
186
  console.log(`Found ${users.data.length} users`);
181
187
  ```
182
188
 
189
+ ### Context-Aware Client Creation ⭐ NEW!
190
+
191
+ The `fromContext()` method dramatically simplifies API client initialization by automatically extracting authentication and site information from your context object:
192
+
193
+ ```typescript
194
+ import { AugurAPI, type AugurContext } from '@simpleapps-com/augur-api';
195
+
196
+ // Your context object (common in tool handlers, middleware, etc.)
197
+ const context: AugurContext = {
198
+ siteId: 'my-site-123',
199
+ jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
200
+ parameters: { limit: 10 },
201
+ filters: { search: 'electrical' },
202
+ userId: 456
203
+ };
204
+
205
+ // Before: 35+ lines of boilerplate
206
+ const userJwt = await getToken({ req: request });
207
+ if (!userJwt?.jwtToken) {
208
+ throw new Error('Authentication failed');
209
+ }
210
+ const api = new AugurAPI({
211
+ siteId: context.siteId,
212
+ bearerToken: userJwt.jwtToken
213
+ });
214
+
215
+ // After: 1 line of business intent ✨
216
+ const api = AugurAPI.fromContext(context);
217
+
218
+ // Optional configuration overrides
219
+ const api = AugurAPI.fromContext(context, {
220
+ timeout: 10000,
221
+ retries: 1
222
+ });
223
+ ```
224
+
225
+ #### Context Interface
226
+
227
+ ```typescript
228
+ interface AugurContext {
229
+ siteId: string; // Required: Site identifier
230
+ jwt?: string; // JWT token (preferred)
231
+ bearerToken?: string; // Alternative token field
232
+ parameters?: Record<string, unknown>; // Request parameters
233
+ filters?: Record<string, unknown>; // Filter parameters
234
+ userId?: string | number; // User identifier
235
+ }
236
+ ```
237
+
238
+ #### Error Handling
239
+
240
+ The `fromContext()` method provides clear, actionable error messages:
241
+
242
+ ```typescript
243
+ import { ContextCreationError } from '@simpleapps-com/augur-api';
244
+
245
+ try {
246
+ const api = AugurAPI.fromContext(context);
247
+ } catch (error) {
248
+ if (error instanceof ContextCreationError) {
249
+ console.error(`Context validation failed: ${error.message}`);
250
+ console.error(`Problem field: ${error.field}`);
251
+
252
+ // Handle specific issues
253
+ switch (error.field) {
254
+ case 'siteId':
255
+ // Handle missing site ID
256
+ break;
257
+ case 'bearerToken':
258
+ // Handle missing authentication
259
+ break;
260
+ }
261
+ }
262
+ }
263
+ ```
264
+
183
265
  ### Environment Setup
184
266
 
185
267
  ```typescript
@@ -223,7 +305,9 @@ const searchResults = await api.opensearch.itemSearch.search({
223
305
 
224
306
  ## Authentication & Security
225
307
 
226
- ### Dual Authentication System
308
+ > 📋 **[Complete Authentication Guide](./AUTHENTICATION.md)** - Comprehensive guide including cross-site authentication for multi-tenant applications.
309
+
310
+ ### Standard Authentication (Most Common)
227
311
 
228
312
  The Augur API uses a dual authentication system:
229
313
 
@@ -251,75 +335,18 @@ const pricing = await api.pricing.getHealthCheck();
251
335
  const vmiPing = await api.vmi.health.ping();
252
336
  ```
253
337
 
254
- ### Cross-Site Authentication
255
-
256
- Enable multi-tenant authentication using the special `augur_info` site:
257
-
258
- #### Option 1: Streamlined Utility Function (Recommended)
338
+ ### Environment Variables Setup
259
339
 
260
340
  ```typescript
261
- import { authenticateUserForSite } from '@simpleapps-com/augur-api';
262
-
263
- // Simple one-function approach
264
- const result = await authenticateUserForSite({
265
- targetSiteId: 'tenant_site_1',
266
- username: 'user@tenant.com',
267
- password: 'userpassword',
268
- augurInfoToken: 'admin-jwt-token' // JWT with augur_info admin privileges
269
- });
270
-
271
- if (result.success) {
272
- // Ready-to-use API client for the target site
273
- const userData = await result.targetSiteAPI!.joomla.users.get(result.userId!);
274
- console.log('User authenticated:', result.username);
275
- console.log('User data:', userData);
276
- } else {
277
- console.error('Authentication failed:', result.error);
278
- }
279
- ```
280
-
281
- #### Option 2: Reusable Authenticator
282
-
283
- ```typescript
284
- import { createCrossSiteAuthenticator } from '@simpleapps-com/augur-api';
285
-
286
- // Create reusable authenticator
287
- const crossSiteAuth = createCrossSiteAuthenticator('admin-jwt-token');
288
-
289
- // Use for multiple sites
290
- const result1 = await crossSiteAuth('tenant_site_1', 'user1@tenant.com', 'pass1');
291
- const result2 = await crossSiteAuth('tenant_site_2', 'user2@tenant.com', 'pass2');
292
-
293
- if (result1.success) {
294
- const tenantData = await result1.targetSiteAPI!.joomla.content.list({ limit: 10 });
295
- }
296
- ```
297
-
298
- #### Option 3: Manual Approach
299
-
300
- ```typescript
301
- // Manual approach using the API client directly
302
- const crossSiteAPI = new AugurAPI({
303
- siteId: 'augur_info', // Special site for cross-site operations
304
- bearerToken: 'admin-jwt-token', // JWT token with augur_info admin privileges
305
- });
341
+ // .env file
342
+ AUGUR_SITE_ID=your-site-id
343
+ AUGUR_JWT_TOKEN=your-jwt-token
306
344
 
307
- // Authenticate user against a different site
308
- const authResult = await crossSiteAPI.joomla.users.verifyPassword({
309
- username: 'user@tenant.com',
310
- password: 'userpassword',
311
- siteId: 'tenant_site_1' // Target site for authentication
345
+ // app.ts
346
+ const api = new AugurAPI({
347
+ siteId: process.env.AUGUR_SITE_ID!,
348
+ bearerToken: process.env.AUGUR_JWT_TOKEN!,
312
349
  });
313
-
314
- if (authResult.data.isVerified) {
315
- // Create API instance for the target site
316
- const tenantAPI = new AugurAPI({
317
- siteId: 'tenant_site_1',
318
- bearerToken: authResult.data.token, // Token scoped to tenant site
319
- });
320
-
321
- const userData = await tenantAPI.joomla.users.get(authResult.data.id);
322
- }
323
350
  ```
324
351
 
325
352
  ### Dynamic Authentication Updates
@@ -342,28 +369,27 @@ async function refreshTokenIfNeeded() {
342
369
  }
343
370
  ```
344
371
 
345
- ### Security Best Practices
372
+ ### Advanced: Cross-Site Authentication
346
373
 
347
- 1. **Environment Variables**: Store credentials in environment variables
348
- 2. **Token Rotation**: Implement regular token rotation in production
349
- 3. **HTTPS Only**: All API requests use HTTPS in production
350
- 4. **Secure Storage**: Never store tokens in localStorage for web apps
351
- 5. **Minimal Permissions**: Use tokens with minimal required permissions
374
+ For multi-tenant applications that need to authenticate users across different sites:
352
375
 
353
376
  ```typescript
354
- // Good: Environment-based configuration
355
- const api = new AugurAPI({
356
- siteId: process.env.AUGUR_SITE_ID!,
357
- bearerToken: getSecurelyStoredToken(), // From secure storage
358
- });
377
+ import { authenticateUserForSite } from '@simpleapps-com/augur-api';
359
378
 
360
- // Bad: Hardcoded credentials
361
- const api = new AugurAPI({
362
- siteId: 'hardcoded-site-id',
363
- bearerToken: 'hardcoded-token', // Never do this!
379
+ const result = await authenticateUserForSite({
380
+ targetSiteId: 'tenant_site_1',
381
+ username: 'user@tenant.com',
382
+ password: 'user-password',
383
+ augurInfoToken: 'admin-jwt-token'
364
384
  });
385
+
386
+ if (result.success) {
387
+ const userData = await result.targetSiteAPI!.joomla.users.get(result.userId!);
388
+ }
365
389
  ```
366
390
 
391
+ > ⚠️ **Cross-site authentication is an advanced feature.** See the [Complete Authentication Guide](./AUTHENTICATION.md) for detailed implementation patterns, security considerations, and troubleshooting.
392
+
367
393
  ## API Documentation
368
394
 
369
395
  ### Service Overview
@@ -1031,14 +1057,22 @@ const api = new AugurAPI({
1031
1057
 
1032
1058
  ```tsx
1033
1059
  import React, { useState, useEffect } from 'react';
1034
- import { AugurAPI, User, AugurAPIError } from '@simpleapps-com/augur-api';
1035
-
1036
- // Custom hook for Augur API
1037
- function useAugurAPI() {
1038
- const [api] = useState(() => new AugurAPI({
1039
- siteId: process.env.REACT_APP_AUGUR_SITE_ID!,
1040
- bearerToken: getStoredToken()
1041
- }));
1060
+ import { AugurAPI, User, AugurAPIError, type AugurContext } from '@simpleapps-com/augur-api';
1061
+
1062
+ // Custom hook for Augur API - Context-aware approach
1063
+ function useAugurAPI(context?: AugurContext) {
1064
+ const [api] = useState(() => {
1065
+ if (context) {
1066
+ // Use context-aware creation (recommended)
1067
+ return AugurAPI.fromContext(context);
1068
+ }
1069
+
1070
+ // Fallback to manual configuration
1071
+ return new AugurAPI({
1072
+ siteId: process.env.REACT_APP_AUGUR_SITE_ID!,
1073
+ bearerToken: getStoredToken()
1074
+ });
1075
+ });
1042
1076
 
1043
1077
  return api;
1044
1078
  }
@@ -1,4 +1,4 @@
1
- import { AugurAPIConfig } from './core/config';
1
+ import { AugurAPIConfig, AugurContext } from './core/config';
2
2
  import { DiscoveryEndpoint as BaseDiscoveryEndpoint } from './core/base-client';
3
3
  import { JoomlaClient } from './services/joomla';
4
4
  import { CommerceClient } from './services/commerce';
@@ -17,6 +17,11 @@ import { PaymentsClient } from './services/payments';
17
17
  * Interface for discovery endpoint information - re-export base discovery endpoint
18
18
  */
19
19
  export type DiscoveryEndpoint = BaseDiscoveryEndpoint;
20
+ /**
21
+ * Re-export context and error types for convenience
22
+ */
23
+ export type { AugurContext } from './core/config';
24
+ export { ContextCreationError } from './core/config';
20
25
  /**
21
26
  * Interface for service discovery results
22
27
  */
@@ -48,11 +53,15 @@ export interface EndpointSearchResult {
48
53
  *
49
54
  * @example
50
55
  * ```typescript
56
+ * // Traditional approach
51
57
  * const api = new AugurAPI({
52
58
  * siteId: 'my-site-id',
53
59
  * bearerToken: 'my-bearer-token'
54
60
  * });
55
61
  *
62
+ * // Context-aware approach (recommended)
63
+ * const api = AugurAPI.fromContext(context);
64
+ *
56
65
  * // Access Joomla service
57
66
  * const users = await api.joomla.users.list();
58
67
  *
@@ -141,6 +150,32 @@ export declare class AugurAPI {
141
150
  private _p21Pim?;
142
151
  private _payments?;
143
152
  constructor(config: AugurAPIConfig);
153
+ /**
154
+ * Create AugurAPI client from context object
155
+ *
156
+ * Automatically extracts siteId and authentication token from context,
157
+ * eliminating the need for manual configuration boilerplate.
158
+ *
159
+ * @param context Context object containing siteId and authentication
160
+ * @param options Optional configuration overrides
161
+ * @returns AugurAPI instance configured from context
162
+ *
163
+ * @example
164
+ * ```typescript
165
+ * // Instead of manual configuration:
166
+ * const userJwt = await getToken({ req: request });
167
+ * const api = new AugurAPI({ siteId: context.siteId, bearerToken: userJwt.jwtToken });
168
+ *
169
+ * // Simply use:
170
+ * const api = AugurAPI.fromContext(context);
171
+ *
172
+ * // With optional overrides:
173
+ * const api = AugurAPI.fromContext(context, { timeout: 10000 });
174
+ * ```
175
+ *
176
+ * @throws {ContextCreationError} When context is invalid or missing required fields
177
+ */
178
+ static fromContext(context: AugurContext, options?: Partial<AugurAPIConfig>): AugurAPI;
144
179
  /**
145
180
  * Access Joomla service endpoints
146
181
  */
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}