loops_sdk 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85549597f27cc413d5ebafb39a9974172a8f2dfc613e6190c8c1a664f964006b
-  data.tar.gz: cd13f142b86862541207dfb9c1ef2531b3712474de3f9320c2649f2fea697fa9
+  metadata.gz: 0a8b0b6350209acdbb57d8414d35d24c27dc3b53ddbb8dfebf30893221863483
+  data.tar.gz: 462b317da348740e35285efb05d67aa59f71adb54644094f2fe666b6968f8fad
 SHA512:
-  metadata.gz: aae6977f6e8664bb8fb716a28f90be6a6a6ddc5a35a14bb3c9fc9cb0ba54b91847989b36911d03d299e07b04c2e55494f07fb387ccc8bffc494d954c19194c39
-  data.tar.gz: f156ba183d35d9825d85ff949cda127d702f84b7a878a6efae3edc73c901235c89731cdb1435f72623131c42c463ecd0ced1475674a3741c80ab1e8ca4d002db
+  metadata.gz: 2a4b0181a592ff98fda831db5235def393d934375957215cb223219148dce1cbe940271ff5a6881dddec2dc5a9b68bc307009d1ebce947a2522aa672f6f8d752
+  data.tar.gz: b6134652c05daf397d23c1a30bf86fb89f8ae681c60b88e645f6921941f2c327dc1acedc2e86c6db26addb819e7e2b09287373e58460942aaa66766471e1a2c9

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## v1.0.0 - Feb 26, 2025
+
+- JSON from API errors is now accessible from the `APIError` class.
+- Added support for two new contact property endpoints: `ContactProperties.create()` and `ContactProperties.list()`.
+- Deprecated and removed the `CustomFields.list()` method (you can now use `ContactProperties.list()` instead).
+
+## v0.2.0 - Oct 29, 2024
+
+Added rate limit handling with `RateLimitError`.
+
 ## v0.1.2 - Aug 16, 2024
 
 Support for resetting contact properties with `nil`.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to Loops Ruby SDK
+
+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.
+
+## Getting Started
+
+1. Fork the repository on GitHub.
+2. Clone your fork locally: `git clone <https://github.com/Loops-so/loops-rb.git`>
+3. Create a new branch for your feature or bug fix: `git checkout -b your-branch-name`
+
+## Making Changes
+
+1. Make your changes in your branch.
+2. Follow the coding style and conventions used in the project.
+3. Write clear, concise commit messages.
+4. Test your changes thoroughly.
+
+## Submitting a Pull Request
+
+1. Push your changes to your fork on GitHub.
+2. From your fork, open a pull request in the correct branch of the main repository.
+3. Provide a clear title and description for your pull request using our PR template.
+4. Link any relevant issues in the pull request description.
+
+## Code of Conduct
+
+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.
+
+## Reporting Bugs
+
+If you find a bug, please open an issue on GitHub. Include as much detail as possible:
+
+- A clear and descriptive title
+- Steps to reproduce the issue
+- Expected behavior
+- Actual behavior
+- Any error messages or screenshots
+
+## Suggesting Enhancements
+
+We welcome suggestions for enhancements! Please open an issue on GitHub with:
+
+- A clear and descriptive title
+- A detailed description of the proposed enhancement
+- Any examples or mock-ups if applicable
+
+## Questions?
+
+If you have any questions, feel free to open an issue or contact the maintainers directly.
+
+Thank you for contributing!

data/README.md

@@ -38,9 +38,10 @@ LoopsSdk.configure do |config|
 end
 ```
 
+Then you can call methods in your code:
+
 ```ruby
 begin
-
   response = LoopsSdk::Transactional.send(
     transactional_id: "closfz8ui02yq......",
     email: "dan@loops.so",
@@ -48,11 +49,35 @@ begin
       loginUrl: "https://app.domain.com/login?code=1234567890"
     }
   )
+  render json: response
+
+rescue LoopsSdk::APIError => e
+  # JSON returned by the API is in error.json and the HTTP code is in error.statusCode
+  # Error messages explaining the issue can be found in error.json['message']
+  Rails.logger.error("Loops API Error: #{e.json['message']} (Status: #{e.statusCode})")
+end
+```
+
+## Handling rate limits
+
+You can use the check for rate limit issues with your requests.
+
+You can access details about the rate limits from the `limit` and `remaining` attributes.
+
+```ruby
+begin
+
+  response = LoopsSdk::Contacts.update(
+    email: "dan@loops.so"
+  )
 
   render json: response
 
+rescue LoopsSdk::RateLimitError => e
+  Rails.logger.error("Rate limit exceeded (#{e.limit} requests per second)")
+  # Code here to re-try this request
 rescue LoopsSdk::APIError => e
-  # Do something if there is an error from the API
+  # Handle other errors
 end
 ```
 
@@ -75,15 +100,16 @@ You can use custom contact properties in API calls. Please make sure to [add cus
 
 ## Methods
 
-- [ApiKey.test()](#apikey-test)
-- [Contacts.create()](#contacts-create)
-- [Contacts.update()](#contacts-update)
-- [Contacts.find()](#contacts-find)
-- [Contacts.delete()](#contacts-delete)
-- [MailingLists.list()](#mailinglists-list)
-- [Events.send()](#events-send)
-- [Transactional.send()](#transactional-send)
-- [CustomFields.list()](#customfields-list)
+- [ApiKey.test()](#apikeytest)
+- [Contacts.create()](#contactscreate)
+- [Contacts.update()](#contactsupdate)
+- [Contacts.find()](#contactsfind)
+- [Contacts.delete()](#contactsdelete)
+- [ContactProperties.create()](#contactpropertiescreate)
+- [ContactProperties.list()](#contactpropertieslist)
+- [MailingLists.list()](#mailinglistslist)
+- [Events.send()](#eventssend)
+- [Transactional.send()](#transactionalsend)
 
 ---
 
@@ -122,7 +148,7 @@ This method will return a success or error message:
 
 ---
 
-## Contacts.create()
+### Contacts.create()
 
 Create a new contact.
 
@@ -146,8 +172,8 @@ contact_properties = {
   favoriteColor: "Red" /* Custom property */,
 };
 mailing_lists = {
-  list_123: true,
-  list_456: false,
+  cm06f5v0e45nf0ml5754o9cix: true,
+  cm16k73gq014h0mmj5b6jdi9r: false,
 };
 response = LoopsSdk::Contacts.create(
   email: "hello@gmail.com",
@@ -176,7 +202,7 @@ This method will return a success or error message:
 
 ---
 
-## Contacts.update()
+### Contacts.update()
 
 Update a contact.
 
@@ -252,7 +278,7 @@ You must use one parameter in the request.
 ```ruby
 response = LoopsSdk::Contacts.find(email: "hello@gmail.com")
 
-response = LoopsSdk::Contacts.find(userId: "12345")
+response = LoopsSdk::Contacts.find(user_id: "12345")
 ```
 
 #### Response
@@ -272,6 +298,9 @@ If no contact is found, an empty list will be returned.
     "subscribed": true,
     "userGroup": "",
     "userId": "12345",
+    "mailingLists": {
+      "cm06f5v0e45nf0ml5754o9cix": true
+    },
     "favoriteColor": "Blue" /* Custom property */
   }
 ]
@@ -281,7 +310,7 @@ If no contact is found, an empty list will be returned.
 
 ### Contacts.delete()
 
-Delete a contact, either by email address or `userId`.
+Delete a contact.
 
 [API Reference](https://loops.so/docs/api-reference/delete-contact)
 
@@ -299,7 +328,7 @@ You must use one parameter in the request.
 ```ruby
 response = LoopsSdk::Contacts.delete(email: "hello@gmail.com")
 
-response = LoopsSdk::Contacts.delete(userId: "12345")
+response = LoopsSdk::Contacts.delete(user_id: "12345")
 ```
 
 #### Response
@@ -322,6 +351,133 @@ This method will return a success or error message:
 
 ---
 
+### ContactProperties.create()
+
+Create a new contact property.
+
+[API Reference](https://loops.so/docs/api-reference/create-contact-property)
+
+#### Parameters
+
+| Name   | Type   | Required | Notes                                                                                  |
+| ------ | ------ | -------- | -------------------------------------------------------------------------------------- |
+| `name` | string | Yes      | The name of the property. Should be in camelCase, like `planName` or `favouriteColor`. |
+| `type` | string | Yes      | The property's value type.<br />Can be one of `string`, `number`, `boolean` or `date`. |
+
+#### Examples
+
+```ruby
+response = LoopsSdk::ContactProperties.create(
+  name: "planName",
+  type: "string"
+)
+```
+
+#### Response
+
+This method will return a success or error message:
+
+```json
+{
+  "success": true
+}
+```
+
+```json
+{
+  "success": false,
+  "message": "An error message here."
+}
+```
+
+---
+
+### ContactProperties.list()
+
+Get a list of your account's contact properties.
+
+[API Reference](https://loops.so/docs/api-reference/list-contact-properties)
+
+#### Parameters
+
+| Name   | Type   | Required | Notes                                                           |
+| ------ | ------ | -------- | --------------------------------------------------------------- |
+| `list` | string | No       | Use "custom" to retrieve only your account's custom properties. |
+
+#### Example
+
+```ruby
+response = LoopsSdk::ContactProperties.list
+
+response = LoopsSdk::ContactProperties.list(list: "custom")
+```
+
+#### Response
+
+This method will return a list of contact property objects containing `key`, `label` and `type` attributes.
+
+```json
+[
+  {
+    "key": "firstName",
+    "label": "First Name",
+    "type": "string"
+  },
+  {
+    "key": "lastName",
+    "label": "Last Name",
+    "type": "string"
+  },
+  {
+    "key": "email",
+    "label": "Email",
+    "type": "string"
+  },
+  {
+    "key": "notes",
+    "label": "Notes",
+    "type": "string"
+  },
+  {
+    "key": "source",
+    "label": "Source",
+    "type": "string"
+  },
+  {
+    "key": "userGroup",
+    "label": "User Group",
+    "type": "string"
+  },
+  {
+    "key": "userId",
+    "label": "User Id",
+    "type": "string"
+  },
+  {
+    "key": "subscribed",
+    "label": "Subscribed",
+    "type": "boolean"
+  },
+  {
+    "key": "createdAt",
+    "label": "Created At",
+    "type": "date"
+  },
+  {
+    "key": "favoriteColor",
+    "label": "Favorite Color",
+    "type": "string"
+  },
+  {
+    "key": "plan",
+    "label": "Plan",
+    "type": "string"
+  }
+]
+```
+
+---
+
 ### MailingLists.list()
 
 Get a list of your account's mailing lists. [Read more about mailing lists](https://loops.so/docs/contacts/mailing-lists)
@@ -340,19 +496,23 @@ response = LoopsSdk::MailingLists.list
 
 #### Response
 
-This method will return a list of mailing list objects containing `id` and `name` attributes.
+This method will return a list of mailing list objects containing `id`, `name`, `description` and `isPublic` attributes.
 
 If your account has no mailing lists, an empty list will be returned.
 
 ```json
 [
   {
-    "id": "list_123",
-    "name": "Main list"
+    "id": "cm06f5v0e45nf0ml5754o9cix",
+    "name": "Main list",
+    "description": "All customers.",
+    "isPublic": true
   },
   {
-    "id": "list_456",
-    "name": "Investors"
+    "id": "cm16k73gq014h0mmj5b6jdi9r",
+    "name": "Investors",
+    "description": null,
+    "isPublic": false
   }
 ]
 ```
@@ -392,8 +552,8 @@ response = LoopsSdk::Events.send(
     signupDate: "2024-03-21T10:09:23Z",
   },
   mailing_lists: {
-    list_123: true,
-    list_456: false,
+    cm06f5v0e45nf0ml5754o9cix: true,
+    cm16k73gq014h0mmj5b6jdi9r: false,
   },
 })
 
@@ -476,7 +636,7 @@ response = LoopsSdk::Transactional.send(
       data: "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPD...",
     },
   ],
-})
+)
 ```
 
 #### Response
@@ -512,45 +672,6 @@ If there is a problem with the request, a descriptive error message will be retu
 
 ---
 
-### CustomFields.list()
-
-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)
-
-[API Reference](https://loops.so/docs/api-reference/list-custom-fields)
-
-#### Parameters
-
-None
-
-#### Example
-
-```ruby
-response LoopsSdk::CustomFields.list
-```
-
-#### Response
-
-This method will return a list of custom field objects containing `key`, `label` and `type` attributes.
-
-If your account has no custom fields, an empty list will be returned.
-
-```json
-[
-  {
-    "key": "favoriteColor",
-    "label": "Favorite Color",
-    "type": "string"
-  },
-  {
-    "key": "plan",
-    "label": "Plan",
-    "type": "string"
-  }
-]
-```
-
----
-
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/Loops-so/loops-rb.
+Bug reports and pull requests are welcome. Please read our [Contributing Guidelines](CONTRIBUTING.md).

data/lib/loops_sdk/base.rb

@@ -9,6 +9,10 @@ module LoopsSdk
         case response.status
         when 200
           JSON.parse(response.body)
+        when 429
+          limit = response.headers["x-ratelimit-limit"]
+          remaining = response.headers["x-ratelimit-remaining"]
+          raise RateLimitError.new(limit, remaining)
         when 400, 404, 405, 409, 500
           raise APIError.new(response.status, response.body)
         else
@@ -25,15 +29,29 @@ module LoopsSdk
     end
   end
 
-  # The `APIError` class in Ruby represents an error that occurs during an API request with specific
-  # status and response body information.
+  class RateLimitError < StandardError
+    attr_reader :limit, :remaining
+
+    def initialize(limit, remaining)
+      @limit = limit
+      @remaining = remaining
+      super("Rate limit of #{limit} requests per second exceeded.")
+    end
+  end
+
   class APIError < StandardError
-    attr_reader :status, :body
+    attr_reader :statusCode, :json
 
     def initialize(status, body)
-      @status = status
-      @body = body
-      super("API request failed with status #{status}: #{body}")
+      @statusCode = status
+      @json = body
+      message = begin
+                  parsed = JSON.parse(body)
+                  parsed["message"] ? ": #{parsed["message"]}" : ""
+                rescue JSON::ParserError
+                  ""
+                end
+      super("API request failed with status #{statusCode}#{message}")
     end
   end
 end

data/lib/loops_sdk/contacts.rb

@@ -16,7 +16,6 @@ module LoopsSdk
           email: email,
           mailingLists: mailing_lists
         }.merge(properties)
-        puts "Contact Data: #{contact_data.inspect}"
         make_request(:put, "v1/contacts/update", {}, contact_data)
       end
 

data/lib/loops_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LoopsSdk
-  VERSION = "0.1.2"
+  VERSION = "1.0.0"
 end

data/lib/loops_sdk.rb

@@ -9,7 +9,7 @@ require_relative "loops_sdk/contacts"
 require_relative "loops_sdk/events"
 require_relative "loops_sdk/mailing_lists"
 require_relative "loops_sdk/transactional"
-require_relative "loops_sdk/custom_fields"
+require_relative "loops_sdk/contact_properties"
 require_relative "loops_sdk/api_key"
 
 module LoopsSdk

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: loops_sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Dan Rowden
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-16 00:00:00.000000000 Z
+date: 2025-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -33,6 +33,8 @@ extra_rdoc_files: []
 files:
 - ".rubocop.yml"
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE.txt
 - README.md
 - Rakefile