@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.
- package/API-DISCOVERY.md +132 -0
- package/AUTHENTICATION.md +371 -0
- package/QUICKSTART.md +255 -0
- package/README.md +125 -91
- package/dist/cjs/client.d.ts +36 -1
- package/dist/cjs/client.d.ts.map +1 -1
- package/dist/cjs/client.js +54 -1
- package/dist/cjs/client.js.map +1 -1
- package/dist/cjs/core/config.d.ts +24 -0
- package/dist/cjs/core/config.d.ts.map +1 -1
- package/dist/cjs/core/config.js +12 -1
- package/dist/cjs/core/config.js.map +1 -1
- package/dist/cjs/index.d.ts +2 -2
- package/dist/cjs/index.d.ts.map +1 -1
- package/dist/cjs/index.js +5 -2
- package/dist/cjs/index.js.map +1 -1
- package/dist/cjs/services/vmi/client.d.ts +501 -1
- package/dist/cjs/services/vmi/client.d.ts.map +1 -1
- package/dist/cjs/services/vmi/client.js +408 -0
- package/dist/cjs/services/vmi/client.js.map +1 -1
- package/dist/esm/client.d.ts +36 -1
- package/dist/esm/client.d.ts.map +1 -1
- package/dist/esm/client.js +52 -0
- package/dist/esm/client.js.map +1 -1
- package/dist/esm/core/config.d.ts +24 -0
- package/dist/esm/core/config.d.ts.map +1 -1
- package/dist/esm/core/config.js +10 -0
- package/dist/esm/core/config.js.map +1 -1
- package/dist/esm/index.d.ts +2 -2
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +3 -1
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/services/vmi/client.d.ts +501 -1
- package/dist/esm/services/vmi/client.d.ts.map +1 -1
- package/dist/esm/services/vmi/client.js +408 -0
- package/dist/esm/services/vmi/client.js.map +1 -1
- package/dist/types/client.d.ts +36 -1
- package/dist/types/client.d.ts.map +1 -1
- package/dist/types/core/config.d.ts +24 -0
- package/dist/types/core/config.d.ts.map +1 -1
- package/dist/types/index.d.ts +2 -2
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/services/vmi/client.d.ts +501 -1
- package/dist/types/services/vmi/client.d.ts.map +1 -1
- 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
|
-
//
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
262
|
-
|
|
263
|
-
|
|
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
|
-
//
|
|
308
|
-
const
|
|
309
|
-
|
|
310
|
-
|
|
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
|
-
###
|
|
372
|
+
### Advanced: Cross-Site Authentication
|
|
346
373
|
|
|
347
|
-
|
|
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
|
-
|
|
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
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
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(() =>
|
|
1039
|
-
|
|
1040
|
-
|
|
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
|
}
|
package/dist/cjs/client.d.ts
CHANGED
|
@@ -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
|
*/
|
package/dist/cjs/client.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}
|