loops_sdk 0.1.0 → 0.2.0

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 (13) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +14 -2
  3. data/CODE_OF_CONDUCT.md +132 -0
  4. data/CONTRIBUTING.md +51 -0
  5. data/README.md +535 -10
  6. data/lib/loops_sdk/api_key.rb +11 -0
  7. data/lib/loops_sdk/base.rb +14 -2
  8. data/lib/loops_sdk/contacts.rb +2 -2
  9. data/lib/loops_sdk/custom_fields.rb +1 -1
  10. data/lib/loops_sdk/events.rb +1 -1
  11. data/lib/loops_sdk/version.rb +1 -1
  12. data/lib/loops_sdk.rb +1 -0
  13. metadata +5 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2f72e2f62c89ee3d1ba4bf2803ce036d1bbaf0c5090cb59bc5dfed76310e0d64
4
- data.tar.gz: 611b4184d555033ba4c4166426519a4bf9cea4fb47675b4b2b99ed0cafea9a58
3
+ metadata.gz: e5cbc02e88853c1dfb986f2d18fc113badcc569865c83c21a58d42809651245c
4
+ data.tar.gz: d38a4ff09a27e949dcae803cbd9c4f143f32b8dfb7100e6e3cbdc9323d61ccb9
5
5
  SHA512:
6
- metadata.gz: 128ae813b6a85b3420a30f6400c9ab11151d1cb95d73518bf776f31e54a64aa6b17d0e548abb54048bb4e4446395a1b7e71b6d2f145b81ab18adf834ded6ba0f
7
- data.tar.gz: 10d6820a08203cbac614de06c54f482b9beea538a73d0d9fa31543a43150cb8183552d52a7ae58a9bd4a82299edb2f807e7f8deb400060e0675c2c37e71c9534
6
+ metadata.gz: e9298ac3c8a13c8e207a1c621bd74a5370881537e11a520a85dc2b9ac7a302ece4d2b13a3997c8726b825a474391624d8f5127610823f4dbb5bb75c3bde7b90f
7
+ data.tar.gz: c3b0de412fea85c5635880c5bdf962164fac8884cd25344b46ad975125dacd89809c541ce4cc921c0e2b304b6204b12fe15455b905479b0593d093126a70c175
data/CHANGELOG.md CHANGED
@@ -1,3 +1,15 @@
1
- ## [0.1.0] - [TBD]
1
+ ## v0.2.0 - Oct 29, 2024
2
2
 
3
- - Initial release
3
+ Added rate limit handling with `RateLimitError`.
4
+
5
+ ## v0.1.2 - Aug 16, 2024
6
+
7
+ Support for resetting contact properties with `nil`.
8
+
9
+ ## v0.1.1 - Aug 16, 2024
10
+
11
+ Added `ApiKey.test` method for testing API keys.
12
+
13
+ ## v0.1.0 - Aug 16, 2024
14
+
15
+ Initial release.
data/CODE_OF_CONDUCT.md ADDED
@@ -0,0 +1,132 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ We as members, contributors, and leaders pledge to make participation in our
6
+ community a harassment-free experience for everyone, regardless of age, body
7
+ size, visible or invisible disability, ethnicity, sex characteristics, gender
8
+ identity and expression, level of experience, education, socio-economic status,
9
+ nationality, personal appearance, race, caste, color, religion, or sexual
10
+ identity and orientation.
11
+
12
+ We pledge to act and interact in ways that contribute to an open, welcoming,
13
+ diverse, inclusive, and healthy community.
14
+
15
+ ## Our Standards
16
+
17
+ Examples of behavior that contributes to a positive environment for our
18
+ community include:
19
+
20
+ - Demonstrating empathy and kindness toward other people
21
+ - Being respectful of differing opinions, viewpoints, and experiences
22
+ - Giving and gracefully accepting constructive feedback
23
+ - Accepting responsibility and apologizing to those affected by our mistakes,
24
+ and learning from the experience
25
+ - Focusing on what is best not just for us as individuals, but for the overall
26
+ community
27
+
28
+ Examples of unacceptable behavior include:
29
+
30
+ - The use of sexualized language or imagery, and sexual attention or advances of
31
+ any kind
32
+ - Trolling, insulting or derogatory comments, and personal or political attacks
33
+ - Public or private harassment
34
+ - Publishing others' private information, such as a physical or email address,
35
+ without their explicit permission
36
+ - Other conduct which could reasonably be considered inappropriate in a
37
+ professional setting
38
+
39
+ ## Enforcement Responsibilities
40
+
41
+ Community leaders are responsible for clarifying and enforcing our standards of
42
+ acceptable behavior and will take appropriate and fair corrective action in
43
+ response to any behavior that they deem inappropriate, threatening, offensive,
44
+ or harmful.
45
+
46
+ Community leaders have the right and responsibility to remove, edit, or reject
47
+ comments, commits, code, wiki edits, issues, and other contributions that are
48
+ not aligned to this Code of Conduct, and will communicate reasons for moderation
49
+ decisions when appropriate.
50
+
51
+ ## Scope
52
+
53
+ This Code of Conduct applies within all community spaces, and also applies when
54
+ an individual is officially representing the community in public spaces.
55
+ Examples of representing our community include using an official email address,
56
+ posting via an official social media account, or acting as an appointed
57
+ representative at an online or offline event.
58
+
59
+ ## Enforcement
60
+
61
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
62
+ reported to the community leaders responsible for enforcement at
63
+ [INSERT CONTACT METHOD].
64
+ All complaints will be reviewed and investigated promptly and fairly.
65
+
66
+ All community leaders are obligated to respect the privacy and security of the
67
+ reporter of any incident.
68
+
69
+ ## Enforcement Guidelines
70
+
71
+ Community leaders will follow these Community Impact Guidelines in determining
72
+ the consequences for any action they deem in violation of this Code of Conduct:
73
+
74
+ ### 1. Correction
75
+
76
+ **Community Impact**: Use of inappropriate language or other behavior deemed
77
+ unprofessional or unwelcome in the community.
78
+
79
+ **Consequence**: A private, written warning from community leaders, providing
80
+ clarity around the nature of the violation and an explanation of why the
81
+ behavior was inappropriate. A public apology may be requested.
82
+
83
+ ### 2. Warning
84
+
85
+ **Community Impact**: A violation through a single incident or series of
86
+ actions.
87
+
88
+ **Consequence**: A warning with consequences for continued behavior. No
89
+ interaction with the people involved, including unsolicited interaction with
90
+ those enforcing the Code of Conduct, for a specified period of time. This
91
+ includes avoiding interactions in community spaces as well as external channels
92
+ like social media. Violating these terms may lead to a temporary or permanent
93
+ ban.
94
+
95
+ ### 3. Temporary Ban
96
+
97
+ **Community Impact**: A serious violation of community standards, including
98
+ sustained inappropriate behavior.
99
+
100
+ **Consequence**: A temporary ban from any sort of interaction or public
101
+ communication with the community for a specified period of time. No public or
102
+ private interaction with the people involved, including unsolicited interaction
103
+ with those enforcing the Code of Conduct, is allowed during this period.
104
+ Violating these terms may lead to a permanent ban.
105
+
106
+ ### 4. Permanent Ban
107
+
108
+ **Community Impact**: Demonstrating a pattern of violation of community
109
+ standards, including sustained inappropriate behavior, harassment of an
110
+ individual, or aggression toward or disparagement of classes of individuals.
111
+
112
+ **Consequence**: A permanent ban from any sort of public interaction within the
113
+ community.
114
+
115
+ ## Attribution
116
+
117
+ This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118
+ version 2.1, available at
119
+ [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120
+
121
+ Community Impact Guidelines were inspired by
122
+ [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
123
+
124
+ For answers to common questions about this code of conduct, see the FAQ at
125
+ [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
126
+ [https://www.contributor-covenant.org/translations][translations].
127
+
128
+ [homepage]: https://www.contributor-covenant.org
129
+ [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
130
+ [Mozilla CoC]: https://github.com/mozilla/diversity
131
+ [FAQ]: https://www.contributor-covenant.org/faq
132
+ [translations]: https://www.contributor-covenant.org/translations
data/CONTRIBUTING.md ADDED
@@ -0,0 +1,51 @@
1
+ # Contributing to Loops Ruby SDK
2
+
3
+ Thank you for your interest in contributing to Loops Ruby SDK. We welcome contributions from the community and are excited to see what you'll bring to the project.
4
+
5
+ ## Getting Started
6
+
7
+ 1. Fork the repository on GitHub.
8
+ 2. Clone your fork locally: `git clone <https://github.com/Loops-so/loops-rb.git`>
9
+ 3. Create a new branch for your feature or bug fix: `git checkout -b your-branch-name`
10
+
11
+ ## Making Changes
12
+
13
+ 1. Make your changes in your branch.
14
+ 2. Follow the coding style and conventions used in the project.
15
+ 3. Write clear, concise commit messages.
16
+ 4. Test your changes thoroughly.
17
+
18
+ ## Submitting a Pull Request
19
+
20
+ 1. Push your changes to your fork on GitHub.
21
+ 2. From your fork, open a pull request in the correct branch of the main repository.
22
+ 3. Provide a clear title and description for your pull request using our PR template.
23
+ 4. Link any relevant issues in the pull request description.
24
+
25
+ ## Code of Conduct
26
+
27
+ Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project, you agree to abide by its terms.
28
+
29
+ ## Reporting Bugs
30
+
31
+ If you find a bug, please open an issue on GitHub. Include as much detail as possible:
32
+
33
+ - A clear and descriptive title
34
+ - Steps to reproduce the issue
35
+ - Expected behavior
36
+ - Actual behavior
37
+ - Any error messages or screenshots
38
+
39
+ ## Suggesting Enhancements
40
+
41
+ We welcome suggestions for enhancements! Please open an issue on GitHub with:
42
+
43
+ - A clear and descriptive title
44
+ - A detailed description of the proposed enhancement
45
+ - Any examples or mock-ups if applicable
46
+
47
+ ## Questions?
48
+
49
+ If you have any questions, feel free to open an issue or contact the maintainers directly.
50
+
51
+ Thank you for contributing!
data/README.md CHANGED
@@ -6,29 +6,31 @@ This is the official Ruby SDK for [Loops](https://loops.so), an email platform f
6
6
 
7
7
  ## Installation
8
8
 
9
- Install the gem and add to the application's Gemfile by executing:
9
+ Install the gem and add it to the application's Gemfile like this:
10
10
 
11
- $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
11
+ ```bash
12
+ bundle add loops_sdk
13
+ ```
12
14
 
13
- If bundler is not being used to manage dependencies, install the gem by executing:
15
+ If bundler is not being used to manage dependencies, you can install the gem like this:
14
16
 
15
- $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
17
+ ```bash
18
+ gem install loops_sdk
19
+ ```
16
20
 
17
21
  ## Usage
18
22
 
19
23
  You will need a Loops API key to use the package.
20
24
 
21
- In your Loops account, go to the [API Settings page](https://app.loops.so/settings?page=api) and click "Generate key".
25
+ In your Loops account, go to the [API Settings page](https://app.loops.so/settings?page=api) and click **Generate key**.
22
26
 
23
- Copy this key and save it in your application code (for example as `LOOPS_API_KEY` in an `.env` file).
27
+ Copy this key and save it in your application code (for example, in an environment variable).
24
28
 
25
29
  See the API documentation to learn more about [rate limiting](https://loops.so/docs/api-reference#rate-limiting) and [error handling](https://loops.so/docs/api-reference#debugging).
26
30
 
27
31
  In an initializer, import and configure the SDK:
28
32
 
29
- ```ruby
30
- # config/initializers/loops.rb
31
-
33
+ ```ruby config/initializers/loops.rb
32
34
  require "loops_sdk"
33
35
 
34
36
  LoopsSdk.configure do |config|
@@ -54,6 +56,529 @@ rescue LoopsSdk::APIError => e
54
56
  end
55
57
  ```
56
58
 
59
+ ## Handling rate limits
60
+
61
+ You can use the check for rate limit issues with your requests.
62
+
63
+ You can access details about the rate limits from the `limit` and `remaining` attributes.
64
+
65
+ ```ruby
66
+ begin
67
+
68
+ response = LoopsSdk::Contacts.update(
69
+ email: "dan@loops.so"
70
+ )
71
+
72
+ render json: response
73
+
74
+ rescue LoopsSdk::RateLimitError => e
75
+ Rails.logger.error("Rate limit exceeded (#{e.limit} requests per second)")
76
+ # Code here to re-try this request
77
+ rescue LoopsSdk::APIError => e
78
+ # Handle other errors
79
+ end
80
+ ```
81
+
82
+ ## Default contact properties
83
+
84
+ Each contact in Loops has a set of default properties. These will always be returned in API results.
85
+
86
+ - `id`
87
+ - `email`
88
+ - `firstName`
89
+ - `lastName`
90
+ - `source`
91
+ - `subscribed`
92
+ - `userGroup`
93
+ - `userId`
94
+
95
+ ## Custom contact properties
96
+
97
+ You can use custom contact properties in API calls. Please make sure to [add custom properties](https://loops.so/docs/contacts/properties#custom-contact-properties) in your Loops account before using them with the SDK.
98
+
99
+ ## Methods
100
+
101
+ - [ApiKey.test()](#apikey-test)
102
+ - [Contacts.create()](#contacts-create)
103
+ - [Contacts.update()](#contacts-update)
104
+ - [Contacts.find()](#contacts-find)
105
+ - [Contacts.delete()](#contacts-delete)
106
+ - [MailingLists.list()](#mailinglists-list)
107
+ - [Events.send()](#events-send)
108
+ - [Transactional.send()](#transactional-send)
109
+ - [CustomFields.list()](#customfields-list)
110
+
111
+ ---
112
+
113
+ ### ApiKey.test()
114
+
115
+ Test if your API key is valid.
116
+
117
+ [API Reference](https://loops.so/docs/api-reference/api-key)
118
+
119
+ #### Parameters
120
+
121
+ None
122
+
123
+ #### Example
124
+
125
+ ```ruby
126
+ response LoopsSdk::ApiKey.test
127
+ ```
128
+
129
+ #### Response
130
+
131
+ This method will return a success or error message:
132
+
133
+ ```json
134
+ {
135
+ "success": true,
136
+ "teamName": "Company name"
137
+ }
138
+ ```
139
+
140
+ ```json
141
+ {
142
+ "error": "Invalid API key"
143
+ }
144
+ ```
145
+
146
+ ---
147
+
148
+ ## Contacts.create()
149
+
150
+ Create a new contact.
151
+
152
+ [API Reference](https://loops.so/docs/api-reference/create-contact)
153
+
154
+ #### Parameters
155
+
156
+ | Name | Type | Required | Notes |
157
+ | --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
158
+ | `email` | string | Yes | If a contact already exists with this email address, an error response will be returned. |
159
+ | `properties` | object | No | An object containing default and any custom properties for your contact.<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`, `nil` (to reset a value), `boolean` or `date` ([see allowed date formats](https://loops.so/docs/contacts/properties#dates)). |
160
+ | `mailing_lists` | object | No | An object of mailing list IDs and boolean subscription statuses. |
161
+
162
+ #### Examples
163
+
164
+ ```ruby
165
+ response = LoopsSdk::Contacts.create(email: "hello@gmail.com")
166
+
167
+ contact_properties = {
168
+ firstName: "Bob" /* Default property */,
169
+ favoriteColor: "Red" /* Custom property */,
170
+ };
171
+ mailing_lists = {
172
+ cm06f5v0e45nf0ml5754o9cix: true,
173
+ cm16k73gq014h0mmj5b6jdi9r: false,
174
+ };
175
+ response = LoopsSdk::Contacts.create(
176
+ email: "hello@gmail.com",
177
+ properties: contact_properties,
178
+ mailing_lists: mailing_lists
179
+ )
180
+ ```
181
+
182
+ #### Response
183
+
184
+ This method will return a success or error message:
185
+
186
+ ```json
187
+ {
188
+ "success": true,
189
+ "id": "id_of_contact"
190
+ }
191
+ ```
192
+
193
+ ```json
194
+ {
195
+ "success": false,
196
+ "message": "An error message here."
197
+ }
198
+ ```
199
+
200
+ ---
201
+
202
+ ## Contacts.update()
203
+
204
+ Update a contact.
205
+
206
+ Note: To update a contact's email address, the contact requires a `userId` value. Then you can make a request with their `userId` and an updated email address.
207
+
208
+ [API Reference](https://loops.so/docs/api-reference/update-contact)
209
+
210
+ #### Parameters
211
+
212
+ | Name | Type | Required | Notes |
213
+ | --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
214
+ | `email` | string | Yes | The email address of the contact to update. If there is no contact with this email address, a new contact will be created using the email and properties in this request. |
215
+ | `properties` | object | No | An object containing default and any custom properties for your contact.<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`, `nil` (to reset a value), `boolean` or `date` ([see allowed date formats](https://loops.so/docs/contacts/properties#dates)). |
216
+ | `mailing_lists` | object | No | An object of mailing list IDs and boolean subscription statuses. |
217
+
218
+ #### Example
219
+
220
+ ```ruby
221
+ contact_properties = {
222
+ firstName: "Bob" /* Default property */,
223
+ favoriteColor: "Blue" /* Custom property */,
224
+ };
225
+ response = LoopsSdk::Contacts.update(
226
+ email: "hello@gmail.com",
227
+ properties: contact_properties
228
+ )
229
+
230
+ # Updating a contact's email address using userId
231
+ response = LoopsSdk::Contacts.update(
232
+ email: "newemail@gmail.com",
233
+ properties: {
234
+ userId: "1234",
235
+ })
236
+ ```
237
+
238
+ #### Response
239
+
240
+ This method will return a success or error message:
241
+
242
+ ```json
243
+ {
244
+ "success": true,
245
+ "id": "id_of_contact"
246
+ }
247
+ ```
248
+
249
+ ```json
250
+ {
251
+ "success": false,
252
+ "message": "An error message here."
253
+ }
254
+ ```
255
+
256
+ ---
257
+
258
+ ### Contacts.find()
259
+
260
+ Find a contact.
261
+
262
+ [API Reference](https://loops.so/docs/api-reference/find-contact)
263
+
264
+ #### Parameters
265
+
266
+ You must use one parameter in the request.
267
+
268
+ | Name | Type | Required | Notes |
269
+ | --------- | ------ | -------- | ----- |
270
+ | `email` | string | No | |
271
+ | `user_id` | string | No | |
272
+
273
+ #### Examples
274
+
275
+ ```ruby
276
+ response = LoopsSdk::Contacts.find(email: "hello@gmail.com")
277
+
278
+ response = LoopsSdk::Contacts.find(user_id: "12345")
279
+ ```
280
+
281
+ #### Response
282
+
283
+ This method will return a list containing a single contact object, which will include all default properties and any custom properties.
284
+
285
+ If no contact is found, an empty list will be returned.
286
+
287
+ ```json
288
+ [
289
+ {
290
+ "id": "cll6b3i8901a9jx0oyktl2m4u",
291
+ "email": "hello@gmail.com",
292
+ "firstName": "Bob",
293
+ "lastName": null,
294
+ "source": "API",
295
+ "subscribed": true,
296
+ "userGroup": "",
297
+ "userId": "12345",
298
+ "mailingLists": {
299
+ "cm06f5v0e45nf0ml5754o9cix": true
300
+ },
301
+ "favoriteColor": "Blue" /* Custom property */
302
+ }
303
+ ]
304
+ ```
305
+
306
+ ---
307
+
308
+ ### Contacts.delete()
309
+
310
+ Delete a contact.
311
+
312
+ [API Reference](https://loops.so/docs/api-reference/delete-contact)
313
+
314
+ #### Parameters
315
+
316
+ You must use one parameter in the request.
317
+
318
+ | Name | Type | Required | Notes |
319
+ | --------- | ------ | -------- | ----- |
320
+ | `email` | string | No | |
321
+ | `user_id` | string | No | |
322
+
323
+ #### Example
324
+
325
+ ```ruby
326
+ response = LoopsSdk::Contacts.delete(email: "hello@gmail.com")
327
+
328
+ response = LoopsSdk::Contacts.delete(user_id: "12345")
329
+ ```
330
+
331
+ #### Response
332
+
333
+ This method will return a success or error message:
334
+
335
+ ```json
336
+ {
337
+ "success": true,
338
+ "message": "Contact deleted."
339
+ }
340
+ ```
341
+
342
+ ```json
343
+ {
344
+ "success": false,
345
+ "message": "An error message here."
346
+ }
347
+ ```
348
+
349
+ ---
350
+
351
+ ### MailingLists.list()
352
+
353
+ Get a list of your account's mailing lists. [Read more about mailing lists](https://loops.so/docs/contacts/mailing-lists)
354
+
355
+ [API Reference](https://loops.so/docs/api-reference/list-mailing-lists)
356
+
357
+ #### Parameters
358
+
359
+ None
360
+
361
+ #### Example
362
+
363
+ ```ruby
364
+ response = LoopsSdk::MailingLists.list
365
+ ```
366
+
367
+ #### Response
368
+
369
+ This method will return a list of mailing list objects containing `id`, `name` and `isPublic` attributes.
370
+
371
+ If your account has no mailing lists, an empty list will be returned.
372
+
373
+ ```json
374
+ [
375
+ {
376
+ "id": "cm06f5v0e45nf0ml5754o9cix",
377
+ "name": "Main list",
378
+ "isPublic": true
379
+ },
380
+ {
381
+ "id": "cm16k73gq014h0mmj5b6jdi9r",
382
+ "name": "Investors",
383
+ "isPublic": false
384
+ }
385
+ ]
386
+ ```
387
+
388
+ ---
389
+
390
+ ### Events.send()
391
+
392
+ Send an event to trigger an email in Loops. [Read more about events](https://loops.so/docs/events)
393
+
394
+ [API Reference](https://loops.so/docs/api-reference/send-event)
395
+
396
+ #### Parameters
397
+
398
+ | Name | Type | Required | Notes |
399
+ | -------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
400
+ | `event_name` | string | Yes | |
401
+ | `email` | string | No | The contact's email address. Required if `user_id` is not present. |
402
+ | `user_id` | string | No | The contact's unique user ID. If you use `user_id` without `email`, this value must have already been added to your contact in Loops. Required if `email` is not present. |
403
+ | `contact_properties` | 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`, `nil` (to reset a value), `boolean` or `date` ([see allowed date formats](https://loops.so/docs/contacts/properties#dates)). |
404
+ | `event_properties` | 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)). |
405
+ | `mailing_lists` | object | No | An object of mailing list IDs and boolean subscription statuses. |
406
+
407
+ #### Examples
408
+
409
+ ```ruby
410
+ response = LoopsSdk::Events.send(
411
+ event_name: "signup",
412
+ email: "hello@gmail.com"
413
+ )
414
+
415
+ response = LoopsSdk::Events.send(
416
+ event_name: "signup",
417
+ email: "hello@gmail.com",
418
+ event_properties: {
419
+ username: "user1234",
420
+ signupDate: "2024-03-21T10:09:23Z",
421
+ },
422
+ mailing_lists: {
423
+ cm06f5v0e45nf0ml5754o9cix: true,
424
+ cm16k73gq014h0mmj5b6jdi9r: false,
425
+ },
426
+ })
427
+
428
+ # In this case with both email and userId present, the system will look for a contact with either a
429
+ # matching `email` or `user_id` value.
430
+ # If a contact is found for one of the values (e.g. `email`), the other value (e.g. `user_id`) will be updated.
431
+ # If a contact is not found, a new contact will be created using both `email` and `user_id` values.
432
+ # Any values added in `contact_properties` will also be updated on the contact.
433
+ response = LoopsSdk::Events.send(
434
+ event_name: "signup",
435
+ email: "hello@gmail.com",
436
+ user_id: "1234567890",
437
+ contact_properties: {
438
+ firstName: "Bob",
439
+ plan: "pro",
440
+ },
441
+ })
442
+ ```
443
+
444
+ #### Response
445
+
446
+ This method will return a success or error:
447
+
448
+ ```json
449
+ {
450
+ "success": true
451
+ }
452
+ ```
453
+
454
+ ```json
455
+ {
456
+ "success": false,
457
+ "message": "An error message here."
458
+ }
459
+ ```
460
+
461
+ ---
462
+
463
+ ### Transactional.send()
464
+
465
+ Send a transactional email to a contact. [Learn about sending transactional email](https://loops.so/docs/transactional/guide)
466
+
467
+ [API Reference](https://loops.so/docs/api-reference/send-transactional-email)
468
+
469
+ #### Parameters
470
+
471
+ | Name | Type | Required | Notes |
472
+ | ---------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
473
+ | `transactional_id` | string | Yes | The ID of the transactional email to send. |
474
+ | `email` | string | Yes | The email address of the recipient. |
475
+ | `add_to_audience` | boolean | No | If `true`, a contact will be created in your audience using the `email` value (if a matching contact doesn’t already exist). |
476
+ | `data_variables` | object | No | An object containing data as defined by the data variables added to the transactional email template.<br />Values can be of type `string` or `number`. |
477
+ | `attachments` | object[] | No | A list of attachments objects.<br />**Please note**: Attachments need to be enabled on your account before using them with the API. [Read more](https://loops.so/docs/transactional/attachments) |
478
+ | `attachments[].filename` | string | No | The name of the file, shown in email clients. |
479
+ | `attachments[].content_type` | string | No | The MIME type of the file. |
480
+ | `attachments[].data` | string | No | The base64-encoded content of the file. |
481
+
482
+ #### Examples
483
+
484
+ ```ruby
485
+ response = LoopsSdk::Transactional.send(
486
+ transactional_id: "clfq6dinn000yl70fgwwyp82l",
487
+ email: "hello@gmail.com",
488
+ data_variables: {
489
+ loginUrl: "https://myapp.com/login/",
490
+ },
491
+ )
492
+
493
+ # Please contact us to enable attachments on your account.
494
+ response = LoopsSdk::Transactional.send(
495
+ transactional_id: "clfq6dinn000yl70fgwwyp82l",
496
+ email: "hello@gmail.com",
497
+ data_variables: {
498
+ loginUrl: "https://myapp.com/login/",
499
+ },
500
+ attachments: [
501
+ {
502
+ filename: "presentation.pdf",
503
+ content_type: "application/pdf",
504
+ data: "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPD...",
505
+ },
506
+ ],
507
+ })
508
+ ```
509
+
510
+ #### Response
511
+
512
+ This method will return a success or error message.
513
+
514
+ ```json
515
+ {
516
+ "success": true
517
+ }
518
+ ```
519
+
520
+ If there is a problem with the request, a descriptive error message will be returned:
521
+
522
+ ```json
523
+ {
524
+ "success": false,
525
+ "path": "dataVariables",
526
+ "message": "There are required fields for this email. You need to include a 'dataVariables' object with the required fields."
527
+ }
528
+ ```
529
+
530
+ ```json
531
+ {
532
+ "success": false,
533
+ "error": {
534
+ "path": "dataVariables",
535
+ "message": "Missing required fields: login_url"
536
+ },
537
+ "transactionalId": "clfq6dinn000yl70fgwwyp82l"
538
+ }
539
+ ```
540
+
541
+ ---
542
+
543
+ ### CustomFields.list()
544
+
545
+ 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)
546
+
547
+ [API Reference](https://loops.so/docs/api-reference/list-custom-fields)
548
+
549
+ #### Parameters
550
+
551
+ None
552
+
553
+ #### Example
554
+
555
+ ```ruby
556
+ response LoopsSdk::CustomFields.list
557
+ ```
558
+
559
+ #### Response
560
+
561
+ This method will return a list of custom field objects containing `key`, `label` and `type` attributes.
562
+
563
+ If your account has no custom fields, an empty list will be returned.
564
+
565
+ ```json
566
+ [
567
+ {
568
+ "key": "favoriteColor",
569
+ "label": "Favorite Color",
570
+ "type": "string"
571
+ },
572
+ {
573
+ "key": "plan",
574
+ "label": "Plan",
575
+ "type": "string"
576
+ }
577
+ ]
578
+ ```
579
+
580
+ ---
581
+
57
582
  ## Contributing
58
583
 
59
- Bug reports and pull requests are welcome on GitHub at https://github.com/Loops-so/loops-rb.
584
+ Bug reports and pull requests are welcome. Please read our [Contributing Guidelines](CONTRIBUTING.md).
data/lib/loops_sdk/api_key.rb ADDED
@@ -0,0 +1,11 @@
1
+ # frozen_string_literal: true
2
+
3
+ module LoopsSdk
4
+ class ApiKey < Base
5
+ class << self
6
+ def test
7
+ make_request(:get, "v1/api-key")
8
+ end
9
+ end
10
+ end
11
+ end
data/lib/loops_sdk/base.rb CHANGED
@@ -9,6 +9,10 @@ module LoopsSdk
9
9
  case response.status
10
10
  when 200
11
11
  JSON.parse(response.body)
12
+ when 429
13
+ limit = response.headers["x-ratelimit-limit"]
14
+ remaining = response.headers["x-ratelimit-remaining"]
15
+ raise RateLimitError.new(limit, remaining)
12
16
  when 400, 404, 405, 409, 500
13
17
  raise APIError.new(response.status, response.body)
14
18
  else
@@ -25,8 +29,16 @@ module LoopsSdk
25
29
  end
26
30
  end
27
31
 
28
- # The `APIError` class in Ruby represents an error that occurs during an API request with specific
29
- # status and response body information.
32
+ class RateLimitError < StandardError
33
+ attr_reader :limit, :remaining
34
+
35
+ def initialize(limit, remaining)
36
+ @limit = limit
37
+ @remaining = remaining
38
+ super("Rate limit of #{limit} requests per second exceeded.")
39
+ end
40
+ end
41
+
30
42
  class APIError < StandardError
31
43
  attr_reader :status, :body
32
44
 
data/lib/loops_sdk/contacts.rb CHANGED
@@ -7,7 +7,7 @@ module LoopsSdk
7
7
  contact_data = {
8
8
  email: email,
9
9
  mailingLists: mailing_lists
10
- }.merge(properties.compact).compact
10
+ }.merge(properties)
11
11
  make_request(:post, "v1/contacts/create", {}, contact_data)
12
12
  end
13
13
 
@@ -15,7 +15,7 @@ module LoopsSdk
15
15
  contact_data = {
16
16
  email: email,
17
17
  mailingLists: mailing_lists
18
- }.merge(properties.compact).compact
18
+ }.merge(properties)
19
19
  make_request(:put, "v1/contacts/update", {}, contact_data)
20
20
  end
21
21
 
data/lib/loops_sdk/custom_fields.rb CHANGED
@@ -4,7 +4,7 @@ module LoopsSdk
4
4
  class CustomFields < Base
5
5
  class << self
6
6
  def list
7
- make_request(:get, "v1/customFields")
7
+ make_request(:get, "v1/contacts/customFields")
8
8
  end
9
9
  end
10
10
  end
data/lib/loops_sdk/events.rb CHANGED
@@ -12,7 +12,7 @@ module LoopsSdk
12
12
  eventName: event_name,
13
13
  eventProperties: event_properties.compact,
14
14
  mailingLists: mailing_lists.compact
15
- }.merge(contact_properties.compact).compact
15
+ }.merge(contact_properties)
16
16
  make_request(:post, "v1/events/send", {}, event_data)
17
17
  end
18
18
  end
data/lib/loops_sdk/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module LoopsSdk
4
- VERSION = "0.1.0"
4
+ VERSION = "0.2.0"
5
5
  end
data/lib/loops_sdk.rb CHANGED
@@ -10,6 +10,7 @@ require_relative "loops_sdk/events"
10
10
  require_relative "loops_sdk/mailing_lists"
11
11
  require_relative "loops_sdk/transactional"
12
12
  require_relative "loops_sdk/custom_fields"
13
+ require_relative "loops_sdk/api_key"
13
14
 
14
15
  module LoopsSdk
15
16
  class << self
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: loops_sdk
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Dan Rowden
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2024-08-16 00:00:00.000000000 Z
11
+ date: 2024-10-29 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: faraday
@@ -33,10 +33,13 @@ extra_rdoc_files: []
33
33
  files:
34
34
  - ".rubocop.yml"
35
35
  - CHANGELOG.md
36
+ - CODE_OF_CONDUCT.md
37
+ - CONTRIBUTING.md
36
38
  - LICENSE.txt
37
39
  - README.md
38
40
  - Rakefile
39
41
  - lib/loops_sdk.rb
42
+ - lib/loops_sdk/api_key.rb
40
43
  - lib/loops_sdk/base.rb
41
44
  - lib/loops_sdk/configuration.rb
42
45
  - lib/loops_sdk/contacts.rb