loops_sdk 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5cbc02e88853c1dfb986f2d18fc113badcc569865c83c21a58d42809651245c
-  data.tar.gz: d38a4ff09a27e949dcae803cbd9c4f143f32b8dfb7100e6e3cbdc9323d61ccb9
+  metadata.gz: 8eeddad6948c305215fe8efe6bd218550fad021aaa12615f6e32b8d69d552fda
+  data.tar.gz: b4632c42a4762b587fc5a96b05c8aa25f734823bb2fe5de31a181556a6ac976d
 SHA512:
-  metadata.gz: e9298ac3c8a13c8e207a1c621bd74a5370881537e11a520a85dc2b9ac7a302ece4d2b13a3997c8726b825a474391624d8f5127610823f4dbb5bb75c3bde7b90f
-  data.tar.gz: c3b0de412fea85c5635880c5bdf962164fac8884cd25344b46ad975125dacd89809c541ce4cc921c0e2b304b6204b12fe15455b905479b0593d093126a70c175
+  metadata.gz: e9cff4116be11b5c86aa25137b0fe832ee1dd1875a33a3625554a094048781b2637388ed6065c8cd23be28d6b1771567f1fd5704c63f2f985aae4f3abd5b9f1f
+  data.tar.gz: fc376fc43f139688c1e76bbe5a06cad0c39e6b3762f481636438a33e1548fa9af6eb1ea90f228384cccad162acb88aec927f50cf1487d35e88e18cdba1abc893

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,12 @@ begin
       loginUrl: "https://app.domain.com/login?code=1234567890"
     }
   )
-
   render json: response
 
 rescue LoopsSdk::APIError => e
-  # Do something if there is an error from the API
+  # 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
 ```
 
@@ -98,15 +100,17 @@ 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)
+- [Transactional.list()](#transactionallist)
 
 ---
 
@@ -145,7 +149,7 @@ This method will return a success or error message:
 
 ---
 
-## Contacts.create()
+### Contacts.create()
 
 Create a new contact.
 
@@ -199,7 +203,7 @@ This method will return a success or error message:
 
 ---
 
-## Contacts.update()
+### Contacts.update()
 
 Update a contact.
 
@@ -232,7 +236,8 @@ response = LoopsSdk::Contacts.update(
   email: "newemail@gmail.com",
   properties: {
     userId: "1234",
-  })
+  }
+)
 ```
 
 #### Response
@@ -348,6 +353,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)
@@ -366,7 +498,7 @@ response = LoopsSdk::MailingLists.list
 
 #### Response
 
-This method will return a list of mailing list objects containing `id`, `name` and `isPublic` 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.
 
@@ -375,11 +507,13 @@ If your account has no mailing lists, an empty list will be returned.
   {
     "id": "cm06f5v0e45nf0ml5754o9cix",
     "name": "Main list",
+    "description": "All customers.",
     "isPublic": true
   },
   {
     "id": "cm16k73gq014h0mmj5b6jdi9r",
     "name": "Investors",
+    "description": null,
     "isPublic": false
   }
 ]
@@ -423,7 +557,7 @@ response = LoopsSdk::Events.send(
     cm06f5v0e45nf0ml5754o9cix: true,
     cm16k73gq014h0mmj5b6jdi9r: false,
   },
-})
+)
 
 # In this case with both email and userId present, the system will look for a contact with either a
 #  matching `email` or `user_id` value.
@@ -438,7 +572,7 @@ response = LoopsSdk::Events.send(
     firstName: "Bob",
     plan: "pro",
   },
-})
+)
 ```
 
 #### Response
@@ -504,7 +638,7 @@ response = LoopsSdk::Transactional.send(
       data: "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPD...",
     },
   ],
-})
+)
 ```
 
 #### Response
@@ -540,41 +674,64 @@ If there is a problem with the request, a descriptive error message will be retu
 
 ---
 
-### CustomFields.list()
+### Transactional.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)
+Get a list of published transactional emails.
 
-[API Reference](https://loops.so/docs/api-reference/list-custom-fields)
+[API Reference](https://loops.so/docs/api-reference/list-transactional-emails)
 
 #### Parameters
 
-None
+| Name      | Type    | Required | Notes                                                                                                                         |
+| --------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `perPage` | integer | No       | How many results to return per page. Must be between 10 and 50. Defaults to 20 if omitted.                                    |
+| `cursor`  | string  | No       | A cursor, to return a specific page of results. Cursors can be found from the `pagination.nextCursor` value in each response. |
 
 #### Example
 
 ```ruby
-response LoopsSdk::CustomFields.list
+response = LoopsSdk::Transactional.list
+
+response = LoopsSdk::Transactional.list(perPage: 15)
 ```
 
 #### 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"
+{
+  "pagination": {
+    "totalResults": 23,
+    "returnedResults": 20,
+    "perPage": 20,
+    "totalPages": 2,
+    "nextCursor": "clyo0q4wo01p59fsecyxqsh38",
+    "nextPage": "https://app.loops.so/api/v1/transactional?cursor=clyo0q4wo01p59fsecyxqsh38&perPage=20"
   },
-  {
-    "key": "plan",
-    "label": "Plan",
-    "type": "string"
-  }
-]
+  "data": [
+    {
+      "id": "clfn0k1yg001imo0fdeqg30i8",
+      "lastUpdated": "2023-11-06T17:48:07.249Z",
+      "dataVariables": []
+    },
+    {
+      "id": "cll42l54f20i1la0lfooe3z12",
+      "lastUpdated": "2025-02-02T02:56:28.845Z",
+      "dataVariables": [
+        "confirmationUrl"
+      ]
+    },
+    {
+      "id": "clw6rbuwp01rmeiyndm80155l",
+      "lastUpdated": "2024-05-14T19:02:52.000Z",
+      "dataVariables": [
+        "firstName",
+        "lastName",
+        "inviteLink"
+      ]
+    },
+    ...
+  ]
+}
 ```
 
 ---

data/lib/loops_sdk/base.rb

@@ -40,12 +40,18 @@ module LoopsSdk
   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/contact_properties.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LoopsSdk
+  class ContactProperties < Base
+    class << self
+      def create(name:, type:)
+        body = {
+          name: name,
+          type: type
+        }
+        make_request(:post, "v1/contacts/properties", {}, body)
+      end
+      def list(list: nil)
+        raise ArgumentError, "List value must be nil, 'custom' or 'all'." unless [nil, "custom", "all"].include?(list)
+        make_request(:get, "v1/contacts/properties", {list: list || "all"})
+      end
+    end
+  end
+end

data/lib/loops_sdk/transactional.rb

@@ -3,6 +3,9 @@
 module LoopsSdk
   class Transactional < Base
     class << self
+      def list(perPage: 20, cursor: nil)
+        make_request(:get, "v1/transactional", { perPage: perPage, cursor: cursor })
+      end
       def send(transactional_id:, email:, add_to_audience: false, data_variables: {}, attachments: [])
         attachments = attachments.map do |attachment|
           attachment.transform_keys { |key| key == :content_type ? :contentType : key }

data/lib/loops_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LoopsSdk
-  VERSION = "0.2.0"
+  VERSION = "1.1.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.2.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Dan Rowden
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-29 00:00:00.000000000 Z
+date: 2025-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -31,24 +31,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rubocop.yml"
-- CHANGELOG.md
-- CODE_OF_CONDUCT.md
-- CONTRIBUTING.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/loops_sdk.rb
 - lib/loops_sdk/api_key.rb
 - lib/loops_sdk/base.rb
 - lib/loops_sdk/configuration.rb
+- lib/loops_sdk/contact_properties.rb
 - lib/loops_sdk/contacts.rb
-- lib/loops_sdk/custom_fields.rb
 - lib/loops_sdk/events.rb
 - lib/loops_sdk/mailing_lists.rb
 - lib/loops_sdk/transactional.rb
 - lib/loops_sdk/version.rb
-- sig/loops_sdk.rbs
 homepage: https://loops.so/docs/api-reference
 licenses:
 - MIT

data/.rubocop.yml

@@ -1,11 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.0
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
-
-Metrics/ParameterLists:
-  Max: 6

data/CHANGELOG.md

@@ -1,15 +0,0 @@
-## 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`.
-
-## v0.1.1 - Aug 16, 2024
-
-Added `ApiKey.test` method for testing API keys.
-
-## v0.1.0 - Aug 16, 2024
-
-Initial release.

data/CODE_OF_CONDUCT.md

@@ -1,132 +0,0 @@
-# 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

@@ -1,51 +0,0 @@
-# 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/Rakefile

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: :rubocop

data/lib/loops_sdk/custom_fields.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module LoopsSdk
-  class CustomFields < Base
-    class << self
-      def list
-        make_request(:get, "v1/contacts/customFields")
-      end
-    end
-  end
-end

data/sig/loops_sdk.rbs

@@ -1,4 +0,0 @@
-module LoopsSdk
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end