Skip to content

Commit d2fdf77

Browse files
danrowdendanrowden
committed
New contact property endpoints; APIError
1 parent c019c34 commit d2fdf77

File tree

2 files changed

+245
-84
lines changed

2 files changed

+245
-84
lines changed

‎README.md

Lines changed: 176 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,23 @@ See the API documentation to learn more about [rate limiting](https://loops.so/d
2727
## Usage
2828

2929
```javascript
30-
import { LoopsClient } from "loops";
30+
import { LoopsClient, APIError } from "loops";
3131

3232
const loops = new LoopsClient(process.env.LOOPS_API_KEY);
3333

34-
const resp = await loops.createContact("[email protected]");
34+
try {
35+
const resp = await loops.createContact("[email protected]");
36+
// resp.success and resp.id available when successful
37+
} catch (error) {
38+
if (error instanceof APIError) {
39+
// JSON returned by the API is in error.json and the HTTP code is in error.statusCode
40+
// Error messages explaining the issue can be found in error.json.message
41+
console.log(error.json);
42+
console.log(error.statusCode);
43+
} else {
44+
// Non-API errors
45+
}
46+
}
3547
```
3648

3749
## Handling rate limits
@@ -41,7 +53,7 @@ If you import `RateLimitExceededError` you can check for rate limit issues with
4153
You can access details about the rate limits from the `limit` and `remaining` attributes.
4254

4355
```javascript
44-
import { LoopsClient, RateLimitExceededError } from "loops";
56+
import { LoopsClient, APIError, RateLimitExceededError } from "loops";
4557

4658
const loops = new LoopsClient(process.env.LOOPS_API_KEY);
4759

@@ -81,10 +93,11 @@ You can use custom contact properties in API calls. Please make sure to [add cus
8193
- [updateContact()](#updatecontact)
8294
- [findContact()](#findcontact)
8395
- [deleteContact()](#deletecontact)
96+
- [createContactProperty()](#createcontactproperty)
97+
- [getContactProperties()](#getcontactproperties)
8498
- [getMailingLists()](#getmailinglists)
8599
- [sendEvent()](#sendevent)
86100
- [sendTransactionalEmail()](#sendtransactionalemail)
87-
- [getCustomFields()](#getcustomfields)
88101

89102
---
90103

@@ -106,16 +119,17 @@ const resp = await loops.testApiKey();
106119

107120
#### Response
108121

109-
This method will return a success or error message:
110-
111122
```json
112123
{
113124
"success": true,
114125
"teamName": "My team"
115126
}
116127
```
117128

129+
Error handling is done through the `APIError` class, which provides `statusCode` and `json` properties containing the API's error response details. For implementation examples, see the [Usage section](#usage).
130+
118131
```json
132+
HTTP 401 Unauthorized
119133
{
120134
"error": "Invalid API key"
121135
}
@@ -159,16 +173,17 @@ const resp = await loops.createContact(
159173

160174
#### Response
161175

162-
This method will return a success or error message:
163-
164176
```json
165177
{
166178
"success": true,
167179
"id": "id_of_contact"
168180
}
169181
```
170182

183+
Error handling is done through the `APIError` class, which provides `statusCode` and `json` properties containing the API's error response details. For implementation examples, see the [Usage section](#usage).
184+
171185
```json
186+
HTTP 400 Bad Request
172187
{
173188
"success": false,
174189
"message": "An error message here."
@@ -210,16 +225,17 @@ const resp = await loops.updateContact("[email protected]", {
210225

211226
#### Response
212227

213-
This method will return a success or error message:
214-
215228
```json
216229
{
217230
"success": true,
218231
"id": "id_of_contact"
219232
}
220233
```
221234

235+
Error handling is done through the `APIError` class, which provides `statusCode` and `json` properties containing the API's error response details. For implementation examples, see the [Usage section](#usage).
236+
222237
```json
238+
HTTP 400 Bad Request
223239
{
224240
"success": false,
225241
"message": "An error message here."
@@ -303,16 +319,25 @@ const resp = await loops.deleteContact({ userId: "12345" });
303319

304320
#### Response
305321

306-
This method will return a success or error message:
307-
308322
```json
309323
{
310324
"success": true,
311325
"message": "Contact deleted."
312326
}
313327
```
314328

329+
Error handling is done through the `APIError` class, which provides `statusCode` and `json` properties containing the API's error response details. For implementation examples, see the [Usage section](#usage).
330+
315331
```json
332+
HTTP 400 Bad Request
333+
{
334+
"success": false,
335+
"message": "An error message here."
336+
}
337+
```
338+
339+
```json
340+
HTTP 404 Not Found
316341
{
317342
"success": false,
318343
"message": "An error message here."
@@ -321,6 +346,133 @@ This method will return a success or error message:
321346

322347
---
323348

349+
### createContactProperty()
350+
351+
Create a new contact property.
352+
353+
[API Reference](https://loops.so/docs/api-reference/create-contact-property)
354+
355+
#### Parameters
356+
357+
| Name | Type | Required | Notes |
358+
| ------- | ------ | -------- | -------------------------------------------------------------------------------------- |
359+
| `name` | string | Yes | The name of the property. Should be in camelCase, like `planName` or `favouriteColor`. |
360+
| `ttype` | string | Yes | The property's value type.<br />Can be one of `string`, `number`, `boolean` or `date`. |
361+
362+
#### Examples
363+
364+
```javascript
365+
const resp = await loops.createContactProperty("planName", "string");
366+
```
367+
368+
#### Response
369+
370+
```json
371+
{
372+
"success": true
373+
}
374+
```
375+
376+
Error handling is done through the `APIError` class, which provides `statusCode` and `json` properties containing the API's error response details. For implementation examples, see the [Usage section](#usage).
377+
378+
```json
379+
HTTP 400 Bad Request
380+
{
381+
"success": false,
382+
"message": "An error message here."
383+
}
384+
```
385+
386+
---
387+
388+
### getContactProperties()
389+
390+
Get a list of your account's contact properties.
391+
392+
[API Reference](https://loops.so/docs/api-reference/list-contact-properties)
393+
394+
#### Parameters
395+
396+
You must use one parameter in the request.
397+
398+
| Name | Type | Required | Notes |
399+
| ------ | ------ | -------- | --------------------------------------------------------------- |
400+
| `list` | string | No | Use "custom" to retrieve only your account's custom properties. |
401+
402+
#### Example
403+
404+
```javascript
405+
const resp = await loops.getContactProperties();
406+
407+
const resp = await loops.getContactProperties("custom");
408+
```
409+
410+
#### Response
411+
412+
This method will return a list of contact property objects containing `key`, `label` and `type` attributes.
413+
414+
```json
415+
[
416+
{
417+
"key": "firstName",
418+
"label": "First Name",
419+
"type": "string"
420+
},
421+
{
422+
"key": "lastName",
423+
"label": "Last Name",
424+
"type": "string"
425+
},
426+
{
427+
"key": "email",
428+
"label": "Email",
429+
"type": "string"
430+
},
431+
{
432+
"key": "notes",
433+
"label": "Notes",
434+
"type": "string"
435+
},
436+
{
437+
"key": "source",
438+
"label": "Source",
439+
"type": "string"
440+
},
441+
{
442+
"key": "userGroup",
443+
"label": "User Group",
444+
"type": "string"
445+
},
446+
{
447+
"key": "userId",
448+
"label": "User Id",
449+
"type": "string"
450+
},
451+
{
452+
"key": "subscribed",
453+
"label": "Subscribed",
454+
"type": "boolean"
455+
},
456+
{
457+
"key": "createdAt",
458+
"label": "Created At",
459+
"type": "date"
460+
},
461+
{
462+
"key": "favoriteColor",
463+
"label": "Favorite Color",
464+
"type": "string"
465+
},
466+
{
467+
"key": "plan",
468+
"label": "Plan",
469+
"type": "string"
470+
}
471+
]
472+
```
473+
474+
---
475+
324476
### getMailingLists()
325477

326478
Get a list of your account's mailing lists. [Read more about mailing lists](https://loops.so/docs/contacts/mailing-lists)
@@ -373,10 +525,10 @@ Send an event to trigger an email in Loops. [Read more about events](https://loo
373525
| Name | Type | Required | Notes |
374526
| ------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
375527
| `email` | string | No | The contact's email address. Required if `userId` is not present. |
376-
| `userId` | string | No | The contact's unique user ID. If you use `userID` without `email`, this value must have already been added to your contact in Loops. Required if `email` is not present. |
528+
| `userId` | string | No | The contact's unique user ID. If you use `userId` without `email`, this value must have already been added to your contact in Loops. Required if `email` is not present. |
377529
| `eventName` | string | Yes | |
378530
| `contactProperties` | object | No | An object containing contact properties, which will be updated or added to the contact when the event is received.<br />Please [add custom properties](https://loops.so/docs/contacts/properties#custom-contact-properties) in your Loops account before using them with the SDK.<br />Values can be of type `string`, `number`, `null` (to reset a value), `boolean` or `date` ([see allowed date formats](https://loops.so/docs/contacts/properties#dates)). |
379-
| `eventProperties` | object | No | An object containing event properties, which will be made availabe in emails that are triggered by this event.<br />Values can be of type `string`, `number`, `boolean` or `date` ([see allowed date formats](https://loops.so/docs/events/properties#important-information-about-event-properties)). |
531+
| `eventProperties` | object | No | An object containing event properties, which will be made available in emails that are triggered by this event.<br />Values can be of type `string`, `number`, `boolean` or `date` ([see allowed date formats](https://loops.so/docs/events/properties#important-information-about-event-properties)). |
380532
| `mailingLists` | object | No | An object of mailing list IDs and boolean subscription statuses. |
381533

382534
#### Examples
@@ -418,15 +570,16 @@ const resp = await loops.sendEvent({
418570

419571
#### Response
420572

421-
This method will return a success or error:
422-
423573
```json
424574
{
425575
"success": true
426576
}
427577
```
428578

579+
Error handling is done through the `APIError` class, which provides `statusCode` and `json` properties containing the API's error response details. For implementation examples, see the [Usage section](#usage).
580+
429581
```json
582+
HTTP 400 Bad Request
430583
{
431584
"success": false,
432585
"message": "An error message here."
@@ -484,17 +637,16 @@ const resp = await loops.sendTransactionalEmail({
484637

485638
#### Response
486639

487-
This method will return a success or error message.
488-
489640
```json
490641
{
491642
"success": true
492643
}
493644
```
494645

495-
If there is a problem with the request, a descriptive error message will be returned:
646+
Error handling is done through the `APIError` class, which provides `statusCode` and `json` properties containing the API's error response details. For implementation examples, see the [Usage section](#usage).
496647

497648
```json
649+
HTTP 400 Bad Request
498650
{
499651
"success": false,
500652
"path": "dataVariables",
@@ -503,6 +655,7 @@ If there is a problem with the request, a descriptive error message will be retu
503655
```
504656

505657
```json
658+
HTTP 400 Bad Request
506659
{
507660
"success": false,
508661
"error": {
@@ -515,47 +668,12 @@ If there is a problem with the request, a descriptive error message will be retu
515668

516669
---
517670

518-
### getCustomFields()
519-
520-
Get a list of your account's custom fields. These are custom properties that can be added to contacts to store extra data. [Read more about contact properties](https://loops.so/docs/contacts/properties)
521-
522-
[API Reference](https://loops.so/docs/api-reference/list-custom-fields)
523-
524-
#### Parameters
525-
526-
None
527-
528-
#### Example
529-
530-
```javascript
531-
const resp = await loops.getCustomFields();
532-
```
533-
534-
#### Response
535-
536-
This method will return a list of custom field objects containing `key`, `label` and `type` attributes.
537-
538-
If your account has no custom fields, an empty list will be returned.
539-
540-
```json
541-
[
542-
{
543-
"key": "favoriteColor",
544-
"label": "Favorite Color",
545-
"type": "string"
546-
},
547-
{
548-
"key": "plan",
549-
"label": "Plan",
550-
"type": "string"
551-
}
552-
]
553-
```
554-
555-
---
556-
557671
## Version history
558672

673+
- `v4.0.0` (Jan 16, 2024)
674+
- Added `APIError` to more easily understand API errors. [See usage example](#usage).
675+
- Added support for two new contact property endpoints: [List contact properties](#listcontactproperties) and [Create contact property](#createcontactproperty).
676+
- Deprecated and removed the `getCustomFields()` method (you can now use [`listContactProperties()`](#listcontactproperties) instead).
559677
- `v3.4.1` (Dec 18, 2024) - Support for a new `description` attribute in [`getMailingLists()`](#getmailinglists).
560678
- `v3.4.0` (Oct 29, 2024) - Added rate limit handling with [`RateLimitExceededError`](#handling-rate-limits).
561679
- `v3.3.0` (Sep 9, 2024) - Added [`testApiKey()`](#testapikey) method.

0 commit comments

Comments
 (0)