@withaevum/sdk 1.3.16 → 1.3.18
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/README.md +197 -12
- package/dist/types.d.ts +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
|
-
# @
|
|
1
|
+
# @withaevum/sdk
|
|
2
2
|
|
|
3
3
|
TypeScript SDK for the Aevum API - a comprehensive scheduling and booking management platform.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
npm install @
|
|
8
|
+
npm install @withaevum/sdk
|
|
9
9
|
# or
|
|
10
|
-
yarn add @
|
|
10
|
+
yarn add @withaevum/sdk
|
|
11
11
|
# or
|
|
12
|
-
pnpm add @
|
|
12
|
+
pnpm add @withaevum/sdk
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
## Usage
|
|
@@ -17,12 +17,12 @@ pnpm add @aevum/sdk
|
|
|
17
17
|
### Initialization
|
|
18
18
|
|
|
19
19
|
```typescript
|
|
20
|
-
import { AevumClient } from '@
|
|
20
|
+
import { AevumClient } from '@withaevum/sdk';
|
|
21
21
|
|
|
22
22
|
const client = new AevumClient({
|
|
23
23
|
apiKey: process.env.AEVUM_API_KEY,
|
|
24
|
-
// Optional: customize base URL (default: https://
|
|
25
|
-
baseUrl: 'https://
|
|
24
|
+
// Optional: customize base URL (default: https://withaevum.com)
|
|
25
|
+
baseUrl: 'https://withaevum.com',
|
|
26
26
|
});
|
|
27
27
|
```
|
|
28
28
|
|
|
@@ -74,7 +74,7 @@ const bookings = await client.bookings.list({
|
|
|
74
74
|
|
|
75
75
|
```typescript
|
|
76
76
|
const updatedBooking = await client.bookings.reschedule('booking_123', {
|
|
77
|
-
start_time: '2024-01-15T11:00:00Z',
|
|
77
|
+
start_time: '2024-01-15T11:00:00Z', // Note: API uses snake_case for these fields
|
|
78
78
|
end_time: '2024-01-15T11:30:00Z',
|
|
79
79
|
sendNotification: true, // Optional, default: false
|
|
80
80
|
});
|
|
@@ -89,6 +89,23 @@ const cancelledBooking = await client.bookings.cancel(
|
|
|
89
89
|
);
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
+
#### Confirm a booking
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
const confirmedBooking = await client.bookings.confirm('booking_123', {
|
|
96
|
+
sendNotification: true, // Optional, default: false
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
#### Update a booking
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
const updatedBooking = await client.bookings.update('booking_123', {
|
|
104
|
+
status: 'confirmed', // Optional: update status
|
|
105
|
+
notes: 'Updated notes', // Optional: update notes
|
|
106
|
+
});
|
|
107
|
+
```
|
|
108
|
+
|
|
92
109
|
### Offerings
|
|
93
110
|
|
|
94
111
|
#### List offerings
|
|
@@ -179,9 +196,44 @@ const offering = await client.offerings.createRecurringDaily({
|
|
|
179
196
|
});
|
|
180
197
|
```
|
|
181
198
|
|
|
199
|
+
#### Update an offering
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
const updatedOffering = await client.offerings.update('offering_123', {
|
|
203
|
+
price_cents: 12000, // Optional: update price
|
|
204
|
+
duration_minutes: 90, // Optional: update duration
|
|
205
|
+
// Many more optional fields available
|
|
206
|
+
});
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
#### Delete an offering
|
|
210
|
+
|
|
211
|
+
```typescript
|
|
212
|
+
await client.offerings.delete('offering_123');
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
#### Create offering from simple endpoint
|
|
216
|
+
|
|
217
|
+
```typescript
|
|
218
|
+
// Uses the simplified /offerings/simple endpoint with preset-based configuration
|
|
219
|
+
const offering = await client.offerings.createFromSimple({
|
|
220
|
+
name: 'Therapy Session',
|
|
221
|
+
duration_minutes: 60,
|
|
222
|
+
price_cents: 15000,
|
|
223
|
+
preset: 'simple_1on1', // 'simple_1on1' | 'simple_group' | 'recurring_weekly' | 'recurring_daily'
|
|
224
|
+
provider_ids: ['provider_123'],
|
|
225
|
+
// For recurring_weekly:
|
|
226
|
+
// weekly_days: ['monday', 'wednesday'],
|
|
227
|
+
// weekly_time_slots: [{ start: '09:00', end: '17:00' }],
|
|
228
|
+
// For recurring_daily:
|
|
229
|
+
// daily_time_slots: [{ start: '09:00', end: '17:00' }],
|
|
230
|
+
});
|
|
231
|
+
```
|
|
232
|
+
|
|
182
233
|
**When to use helper methods vs. full API:**
|
|
183
234
|
- Use `createSimple()` for basic offerings that rely on provider availability schedules
|
|
184
235
|
- Use `createRecurringWeekly()` or `createRecurringDaily()` for recurring offerings with fixed time slots
|
|
236
|
+
- Use `createFromSimple()` for preset-based configuration via the simplified endpoint
|
|
185
237
|
- Use `create()` directly when you need advanced features like custom recurrence intervals, monthly/yearly patterns, windowed modes, or other complex configurations
|
|
186
238
|
|
|
187
239
|
### Customers
|
|
@@ -216,6 +268,22 @@ const customer = await client.customers.create({
|
|
|
216
268
|
|
|
217
269
|
Note: If a customer with the same email already exists, they will be merged/updated.
|
|
218
270
|
|
|
271
|
+
#### Update a customer
|
|
272
|
+
|
|
273
|
+
```typescript
|
|
274
|
+
const updatedCustomer = await client.customers.update('customer_123', {
|
|
275
|
+
name: 'John Smith', // Optional
|
|
276
|
+
email: 'john.smith@example.com', // Optional
|
|
277
|
+
phone: '+1987654321', // Optional
|
|
278
|
+
});
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
#### Delete a customer
|
|
282
|
+
|
|
283
|
+
```typescript
|
|
284
|
+
await client.customers.delete('customer_123');
|
|
285
|
+
```
|
|
286
|
+
|
|
219
287
|
#### Get customer history
|
|
220
288
|
|
|
221
289
|
```typescript
|
|
@@ -253,6 +321,39 @@ const provider = await client.providers.create({
|
|
|
253
321
|
});
|
|
254
322
|
```
|
|
255
323
|
|
|
324
|
+
#### Update a provider
|
|
325
|
+
|
|
326
|
+
```typescript
|
|
327
|
+
const updatedProvider = await client.providers.update('provider_123', {
|
|
328
|
+
name: 'Dr. Jane Smith, PhD', // Optional
|
|
329
|
+
email: 'jane.smith@example.com', // Optional
|
|
330
|
+
phone: '+1987654321', // Optional
|
|
331
|
+
bio: 'Updated bio', // Optional
|
|
332
|
+
minimum_advance_booking_minutes: 60, // Optional: minimum advance booking time in minutes
|
|
333
|
+
});
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
#### Delete a provider
|
|
337
|
+
|
|
338
|
+
```typescript
|
|
339
|
+
await client.providers.delete('provider_123');
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
#### Google Calendar integration
|
|
343
|
+
|
|
344
|
+
```typescript
|
|
345
|
+
// Get Google Calendar connection status
|
|
346
|
+
const status = await client.providers.getGoogleCalendarStatus('provider_123');
|
|
347
|
+
// Returns: { connected: boolean, email?: string, lastSync?: string }
|
|
348
|
+
|
|
349
|
+
// Sync Google Calendar
|
|
350
|
+
const syncResult = await client.providers.syncGoogleCalendar('provider_123');
|
|
351
|
+
// Returns: { success: boolean, syncedEvents?: number }
|
|
352
|
+
|
|
353
|
+
// Disconnect Google Calendar
|
|
354
|
+
await client.providers.disconnectGoogleCalendar('provider_123');
|
|
355
|
+
```
|
|
356
|
+
|
|
256
357
|
### Calendar
|
|
257
358
|
|
|
258
359
|
#### Get calendar events
|
|
@@ -290,6 +391,49 @@ const payouts = await client.analytics.getPayouts({
|
|
|
290
391
|
});
|
|
291
392
|
```
|
|
292
393
|
|
|
394
|
+
### Payments
|
|
395
|
+
|
|
396
|
+
#### Get payment intent
|
|
397
|
+
|
|
398
|
+
```typescript
|
|
399
|
+
const paymentIntent = await client.payments.getIntent('pi_1234567890');
|
|
400
|
+
// Returns: { paymentIntentId, clientSecret, amount, status }
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
#### Update payment intent
|
|
404
|
+
|
|
405
|
+
```typescript
|
|
406
|
+
const updatedIntent = await client.payments.updateIntent({
|
|
407
|
+
paymentIntentId: 'pi_1234567890',
|
|
408
|
+
tipAmountCents: 500, // Tip amount in cents
|
|
409
|
+
bookingId: 'booking_123', // Optional: associate with booking
|
|
410
|
+
});
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
### Organizations
|
|
414
|
+
|
|
415
|
+
#### Get organization details
|
|
416
|
+
|
|
417
|
+
```typescript
|
|
418
|
+
const org = await client.orgs.get();
|
|
419
|
+
// Returns: { id, name, slug, timezone, clerk_org_id }
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
#### Get booking settings
|
|
423
|
+
|
|
424
|
+
```typescript
|
|
425
|
+
const settings = await client.orgs.getBookingSettings();
|
|
426
|
+
// Returns booking configuration including safe period hours
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
#### Update booking settings
|
|
430
|
+
|
|
431
|
+
```typescript
|
|
432
|
+
const updatedSettings = await client.orgs.updateBookingSettings({
|
|
433
|
+
safe_period_hours: 24, // Minimum hours before bookings can be made
|
|
434
|
+
});
|
|
435
|
+
```
|
|
436
|
+
|
|
293
437
|
### Availability
|
|
294
438
|
|
|
295
439
|
#### Get available slots
|
|
@@ -330,6 +474,47 @@ const isAvailable = await client.availability.check({
|
|
|
330
474
|
});
|
|
331
475
|
```
|
|
332
476
|
|
|
477
|
+
#### Create an availability schedule
|
|
478
|
+
|
|
479
|
+
```typescript
|
|
480
|
+
const schedule = await client.availability.createSchedule({
|
|
481
|
+
providerId: 'provider_123',
|
|
482
|
+
name: 'Business Hours',
|
|
483
|
+
timezone: 'America/New_York',
|
|
484
|
+
weekly_hours: {
|
|
485
|
+
monday: [{ start: '09:00', end: '17:00' }],
|
|
486
|
+
tuesday: [{ start: '09:00', end: '17:00' }],
|
|
487
|
+
wednesday: [{ start: '09:00', end: '17:00' }],
|
|
488
|
+
thursday: [{ start: '09:00', end: '17:00' }],
|
|
489
|
+
friday: [{ start: '09:00', end: '17:00' }],
|
|
490
|
+
},
|
|
491
|
+
recurrence_preset: 'weekly',
|
|
492
|
+
recurrence_end_mode: 'never', // or 'date' | 'count'
|
|
493
|
+
});
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
#### Get an availability schedule
|
|
497
|
+
|
|
498
|
+
```typescript
|
|
499
|
+
const schedule = await client.availability.getSchedule('schedule_123');
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
#### Update an availability schedule
|
|
503
|
+
|
|
504
|
+
```typescript
|
|
505
|
+
const updatedSchedule = await client.availability.updateSchedule('schedule_123', {
|
|
506
|
+
name: 'Updated Schedule Name', // Optional
|
|
507
|
+
timezone: 'America/Los_Angeles', // Optional
|
|
508
|
+
weekly_hours: { /* updated hours */ }, // Optional
|
|
509
|
+
});
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
#### Delete an availability schedule
|
|
513
|
+
|
|
514
|
+
```typescript
|
|
515
|
+
await client.availability.deleteSchedule('schedule_123');
|
|
516
|
+
```
|
|
517
|
+
|
|
333
518
|
## Error Handling
|
|
334
519
|
|
|
335
520
|
The SDK throws typed errors for different scenarios:
|
|
@@ -341,7 +526,7 @@ import {
|
|
|
341
526
|
AevumAuthenticationError,
|
|
342
527
|
AevumValidationError,
|
|
343
528
|
AevumNotFoundError,
|
|
344
|
-
} from '@
|
|
529
|
+
} from '@withaevum/sdk';
|
|
345
530
|
|
|
346
531
|
try {
|
|
347
532
|
const booking = await client.bookings.get('invalid_id');
|
|
@@ -374,7 +559,7 @@ import type {
|
|
|
374
559
|
RevenueResponse,
|
|
375
560
|
PayoutsResponse,
|
|
376
561
|
// ... and many more
|
|
377
|
-
} from '@
|
|
562
|
+
} from '@withaevum/sdk';
|
|
378
563
|
```
|
|
379
564
|
|
|
380
565
|
## Migration Guide (from Custom Client)
|
|
@@ -393,7 +578,7 @@ const offerings = await client.getOfferings({ eventId: 'event_123' });
|
|
|
393
578
|
### After (SDK)
|
|
394
579
|
|
|
395
580
|
```typescript
|
|
396
|
-
import { AevumClient } from '@
|
|
581
|
+
import { AevumClient } from '@withaevum/sdk';
|
|
397
582
|
|
|
398
583
|
const client = new AevumClient({ apiKey });
|
|
399
584
|
const offerings = await client.offerings.list({ eventId: 'event_123' });
|
|
@@ -401,7 +586,7 @@ const offerings = await client.offerings.list({ eventId: 'event_123' });
|
|
|
401
586
|
|
|
402
587
|
### Key Changes
|
|
403
588
|
|
|
404
|
-
1. **Installation**: `npm install @
|
|
589
|
+
1. **Installation**: `npm install @withaevum/sdk`
|
|
405
590
|
2. **Initialization**: No need to pass `orgId` - it's resolved automatically
|
|
406
591
|
3. **Method Names**: Use namespaced methods (e.g., `client.offerings.list()` instead of `client.getOfferings()`)
|
|
407
592
|
4. **Error Handling**: Use SDK error classes instead of generic errors
|
package/dist/types.d.ts
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
export interface AevumClientConfig {
|
|
5
5
|
/** API key for authentication */
|
|
6
6
|
apiKey: string;
|
|
7
|
-
/** Base URL for the API (default: https://
|
|
7
|
+
/** Base URL for the API (default: https://withaevum.com) */
|
|
8
8
|
baseUrl?: string;
|
|
9
9
|
/** Organization ID (optional, will be resolved from API key if not provided) */
|
|
10
10
|
orgId?: string;
|