sendclipper 0.1.0

data/lib/sendclipper/resources/audience.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SendClipper
+  module Resources
+    class Contacts < Base
+      # Fields: audience_id, status, page, page_size.
+      def list(params = nil, **kw)
+        query, options = split(params, kw)
+        api_get("/contacts", query: query, options: options)
+      end
+
+      # Every contact, page after page (an Enumerator).
+      def each(params = nil, **kw, &block)
+        query, options = split(params, kw)
+        size = (query["pageSize"] || 200).to_i
+        stop = ->(res, page, _size, _items) { page >= res["totalPages"].to_i }
+        enum = Paging.numbered(size, "items", stop) do |page, page_size|
+          api_get("/contacts", query: query.merge("page" => page, "pageSize" => page_size), options: options)
+        end
+        block ? enum.each(&block) : enum
+      end
+
+      # Fields: name, email, audience_id, status.
+      def create(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/contacts", body, options: options)
+      end
+
+      # Import a CSV or vCard file. Importing never suppresses anyone.
+      #
+      #   client.contacts.import(file: File.read("contacts.csv"), filename: "contacts.csv", on_duplicate: "update")
+      #
+      # The filename's extension picks the parser. Other fields: audience_id,
+      # new_audience, create_audiences, mapping.
+      def import(file:, filename: "contacts.csv", **kw)
+        fields, options = split(nil, kw)
+        @http.call("POST", "/contacts/import", form: import_form(file, filename, fields), options: options)
+      end
+
+      # What an import would do, without importing.
+      def import_preview(file:, filename: "contacts.csv", **options)
+        @http.call("POST", "/contacts/import/preview", form: import_form(file, filename, {}), options: options)
+      end
+
+      # Every contact as CSV (re-importable) or vCard 4.0 (format: "vcf").
+      def export(params = nil, **kw)
+        query, options = split(params, kw)
+        @http.call("GET", "/contacts/export", query: query, as: :text, options: options)
+      end
+
+      private
+
+      def import_form(file, filename, fields)
+        type = filename.to_s.downcase.end_with?(".vcf") ? "text/vcard" : "text/csv"
+        parts = fields.filter_map do |k, v|
+          next if v.nil? || v == ""
+
+          [k, k == "mapping" ? JSON.generate(v) : v.to_s]
+        end
+        HttpClient.multipart(parts, [["file", filename.to_s, type, file]])
+      end
+    end
+
+    class Audiences < Base
+      # { "audiences" => [...], "totalContacts" => n }.
+      def list(**options) = api_get("/audiences", options: options)
+    end
+
+    class Suppressions < Base
+      # Fields: q (address search), reason, cursor, limit.
+      def list(params = nil, **kw)
+        query, options = split(params, kw)
+        api_get("/suppressions", query: query, options: options)
+      end
+
+      def each(params = nil, **kw, &block)
+        query, options = split(params, kw)
+        query.delete("cursor")
+        enum = Paging.cursor("data") { |c| api_get("/suppressions", query: query.merge("cursor" => c), options: options) }
+        block ? enum.each(&block) : enum
+      end
+
+      # Stop all mail to an address (reason +manual+). Fields: email, note.
+      # "created" is false when the address was already suppressed; "row" is
+      # the entry either way.
+      def create(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/suppressions", body, options: options)
+      end
+
+      # Lift a suppression. +reason+ (10+ characters) is recorded. Complaint and
+      # provider suppressions cannot be removed (+suppression_not_removable+).
+      def remove(id, reason, **options) = api_delete("/suppressions/#{seg(id)}", { "reason" => reason }, options: options)
+
+      # The list as CSV. Fields: q, reason.
+      def export(params = nil, **kw)
+        query, options = split(params, kw)
+        query = query.reject { |k, _| %w[cursor limit].include?(k) }
+        @http.call("GET", "/suppressions/export", query: query, as: :text, options: options)
+      end
+    end
+  end
+end

data/lib/sendclipper/resources/base.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SendClipper
+  module Resources
+    # Every method takes its fields as a Hash or as keyword arguments, and the
+    # request options +idempotency_key:+, +timeout:+ (seconds), +max_retries:+
+    # and +headers:+ alongside them.
+    #
+    # Top-level field names may be the API's own (+templateId+) or snake_case
+    # (+template_id+); snake_case is turned into the API's camelCase. Values,
+    # such as the +variables+ map, are sent exactly as given.
+    class Base
+      def initialize(http)
+        @http = http
+      end
+
+      private
+
+      def seg(value) = HttpClient.seg(value)
+
+      # Split keyword arguments into [fields, options].
+      def split(params, kw)
+        options = kw.slice(*HttpClient::OPTION_KEYS)
+        fields = (params || {}).to_h.merge(kw.reject { |k, _| HttpClient::OPTION_KEYS.include?(k) })
+        [camelize(fields), options]
+      end
+
+      def camelize(fields)
+        fields.each_with_object({}) do |(k, v), out|
+          next if v.nil?
+
+          out[k.to_s.gsub(/_([a-z0-9])/) { Regexp.last_match(1).upcase }] = v
+        end
+      end
+
+      def api_get(path, query: nil, as: :json, options: {})
+        @http.call("GET", path, query: query, as: as, options: options)
+      end
+
+      def api_post(path, body = {}, options: {}, bearer: nil)
+        @http.call("POST", path, body: body, bearer: bearer, options: options)
+      end
+
+      def api_patch(path, body, options: {}) = @http.call("PATCH", path, body: body, options: options)
+
+      def api_put(path, body, options: {}) = @http.call("PUT", path, body: body, options: options)
+
+      def api_delete(path, body = nil, options: {}) = @http.call("DELETE", path, body: body, options: options)
+    end
+
+    # Iterators over a numbered or a cursor list. They raise ApiError on a
+    # refusal, since a loop has no +error+ to hand back.
+    module Paging
+      module_function
+
+      def numbered(page_size, items_key, stop)
+        Enumerator.new do |y|
+          page = 1
+          loop do
+            res = yield(page, page_size).unwrap
+            items = res[items_key] || []
+            items.each { |item| y << item }
+            break if items.empty? || stop.call(res, page, page_size, items)
+
+            page += 1
+          end
+        end
+      end
+
+      def cursor(items_key)
+        Enumerator.new do |y|
+          cursor = nil
+          loop do
+            res = yield(cursor).unwrap
+            (res[items_key] || []).each { |item| y << item }
+            info = res["page"] || {}
+            break unless info["hasMore"] && info["cursor"].to_s != ""
+
+            cursor = info["cursor"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sendclipper/resources/domains.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SendClipper
+  module Resources
+    class Domains < Base
+      def list(**options) = api_get("/domains", options: options)
+
+      # Register a sending domain (name:, region: "us-east-1" | "eu-west-1" | "us-west-2").
+      # Next: #records, publish them, then #verify.
+      def create(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/domains", body, options: options)
+      end
+
+      # The DNS records to publish, each with its current status.
+      def records(id, **options) = api_get("/domains/#{seg(id)}/records", options: options)
+
+      # Check DNS now instead of waiting for the background check.
+      def verify(id, **options) = api_post("/domains/#{seg(id)}/verify", nil, options: options)
+
+      # Start receiving mail on this domain. Adds receiving records; never blocks sending.
+      def enable_receiving(id, **options) = api_post("/domains/#{seg(id)}/receiving", nil, options: options)
+
+      def disable_receiving(id, **options) = api_delete("/domains/#{seg(id)}/receiving", options: options)
+
+      # Move a domain to another region. Refused (+region_immutable+) once it holds messages.
+      def set_region(id, region, **options) = api_patch("/domains/#{seg(id)}/region", { "region" => region }, options: options)
+
+      # What deleting the domain would take with it.
+      def deletion_preview(id, **options) = api_get("/domains/#{seg(id)}/deletion", options: options)
+
+      def remove(id, **options) = api_delete("/domains/#{seg(id)}", options: options)
+    end
+  end
+end

data/lib/sendclipper/resources/emails.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SendClipper
+  module Resources
+    class Emails < Base
+      # Send one message. Returns once SendClipper accepted it (status +queued+);
+      # delivery is reported later through #get and webhooks.
+      #
+      #   client.emails.send(from: "hello@send.acme.io", to: "ada@lumen.io", subject: "Hi", html: "<p>Hi</p>")
+      #
+      # Every call carries an Idempotency-Key, so the SDK's own retries never
+      # send twice. Pass +idempotency_key:+ to make YOUR retries safe too.
+      def send(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/emails", body, options: options)
+      end
+
+      # Same as client.batch.send.
+      def send_batch(emails, **options) = Batch.post(@http, emails, options)
+
+      # One message with its body and event timeline.
+      def get(id, **options) = api_get("/emails/#{seg(id)}", options: options)
+
+      # One page of the sent-mail log, newest first. Fields: search, status,
+      # domain, broadcast_id, from, to, page, page_size.
+      def list(params = nil, **kw)
+        query, options = split(params, kw)
+        get_list("/emails", query, options)
+      end
+
+      # Every message matching the fields, page after page (an Enumerator).
+      def each(params = nil, **kw, &block)
+        query, options = split(params, kw)
+        size = (query["pageSize"] || 100).to_i
+        stop = ->(res, page, page_size, items) { items.length < page_size || page * page_size >= res["total"].to_i }
+        enum = Paging.numbered(size, "items", stop) do |page, page_size|
+          get_list("/emails", query.merge("page" => page, "pageSize" => page_size), options)
+        end
+        block ? enum.each(&block) : enum
+      end
+
+      # Counts per status.
+      def stats(**options) = get_list("/emails/stats/summary", nil, options)
+
+      private
+
+      def get_list(path, query, options) = @http.call("GET", path, query: query, options: options)
+    end
+
+    class Batch < Base
+      # Up to 500 messages in one request (one recipient each). Every item is
+      # accepted or refused on its own; a refused item costs its siblings nothing.
+      def send(emails, **options) = self.class.post(@http, emails, options)
+
+      # @api private
+      def self.post(http, emails, options)
+        items = emails.map { |e| new(http).__send__(:camelize, e.to_h) }
+        http.call("POST", "/emails/batch", body: { "emails" => items }, options: options)
+      end
+    end
+  end
+end

data/lib/sendclipper/resources/mailboxes.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SendClipper
+  module Resources
+    class Mailboxes < Base
+      attr_reader :messages
+
+      def initialize(http)
+        super
+        @messages = MailboxMessages.new(http)
+      end
+
+      # Fields: include_archived.
+      def list(params = nil, **kw)
+        query, options = split(params, kw)
+        api_get("/mailboxes", query: query, options: options)
+      end
+
+      def get(id, **options) = api_get("/mailboxes/#{seg(id)}", options: options)
+
+      # A new address on a receiving domain. Fields: domain_id, local_part,
+      # display_name, color, catch_all.
+      def create(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/mailboxes", body, options: options)
+      end
+
+      def update(id, params = nil, **kw)
+        body, options = split(params, kw)
+        api_patch("/mailboxes/#{seg(id)}", body, options: options)
+      end
+
+      # Archives the address. Its mail is kept.
+      def archive(id, **options) = api_delete("/mailboxes/#{seg(id)}", options: options)
+    end
+
+    class MailboxMessages < Base
+      # Mail filed under one address. Reading never marks anything read.
+      # Fields: folder, search, label, limit, cursor.
+      def list(mailbox_id, params = nil, **kw)
+        query, options = split(params, kw)
+        api_get("/mailboxes/#{seg(mailbox_id)}/messages", query: query, options: options)
+      end
+
+      def each(mailbox_id, params = nil, **kw, &block)
+        query, options = split(params, kw)
+        query.delete("cursor")
+        enum = Paging.cursor("items") do |c|
+          api_get("/mailboxes/#{seg(mailbox_id)}/messages", query: query.merge("cursor" => c), options: options)
+        end
+        block ? enum.each(&block) : enum
+      end
+
+      def get(mailbox_id, message_id, **options) = api_get("/mailboxes/#{seg(mailbox_id)}/messages/#{seg(message_id)}", options: options)
+
+      # Download one attachment: a DownloadedFile with content, content_type and filename.
+      def attachment(mailbox_id, message_id, attachment_id, **options)
+        api_get("/mailboxes/#{seg(mailbox_id)}/messages/#{seg(message_id)}/parts/#{seg(attachment_id)}",
+                query: { "download" => 1 }, as: :bytes, options: options)
+      end
+    end
+  end
+end

data/lib/sendclipper/resources/sandboxes.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "time"
+
+module SendClipper
+  module Resources
+    class Sandboxes < Base
+      attr_reader :messages
+
+      def initialize(http)
+        super
+        @messages = SandboxMessages.new(http)
+      end
+
+      def list(**options) = api_get("/sandboxes", options: options)
+
+      def get(id, **options) = api_get("/sandboxes/#{seg(id)}", options: options)
+
+      # Fields: name, project_label, color (#rrggbb).
+      def create(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/sandboxes", body, options: options)
+      end
+
+      # Renaming never changes the address or the credentials.
+      def update(id, params = nil, **kw)
+        body, options = split(params, kw)
+        api_patch("/sandboxes/#{seg(id)}", body, options: options)
+      end
+
+      # Deletes the sandbox and every message in it.
+      def remove(id, **options) = api_delete("/sandboxes/#{seg(id)}", options: options)
+
+      # SMTP host, port, username and password to point a project at.
+      def credentials(id, **options) = api_get("/sandboxes/#{seg(id)}/credentials", options: options)
+
+      # Replace BOTH the SMTP password and the +sc_sbx_+ token. The token is shown only here.
+      def reset_credentials(id, **options) = api_post("/sandboxes/#{seg(id)}/credentials", nil, options: options)
+
+      # Send to a sandbox through its JSON door, with the sandbox's own
+      # +sc_sbx_...+ token. Same fields as emails.send; nothing is delivered.
+      def send(sandbox_token, params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/sandbox/emails", body, options: options, bearer: sandbox_token)
+      end
+    end
+
+    class SandboxMessages < Base
+      # Fields: search, limit.
+      def list(sandbox_id, params = nil, **kw)
+        query, options = split(params, kw)
+        api_get("/sandboxes/#{seg(sandbox_id)}/messages", query: query, options: options)
+      end
+
+      def get(sandbox_id, message_id, **options) = api_get("/sandboxes/#{seg(sandbox_id)}/messages/#{seg(message_id)}", options: options)
+
+      # The message's raw MIME source.
+      def raw(sandbox_id, message_id, **options)
+        @http.call("GET", "/sandboxes/#{seg(sandbox_id)}/messages/#{seg(message_id)}/raw", as: :text, options: options)
+      end
+
+      def remove(sandbox_id, message_id, **options) = api_delete("/sandboxes/#{seg(sandbox_id)}/messages/#{seg(message_id)}", options: options)
+
+      # Empty the sandbox. { "deleted" => n }.
+      def clear(sandbox_id, **options) = api_delete("/sandboxes/#{seg(sandbox_id)}/messages", options: options)
+
+      # { "updated" => n }.
+      def mark_all_read(sandbox_id, **options) = api_post("/sandboxes/#{seg(sandbox_id)}/read-all", nil, options: options)
+
+      # Poll until a message arrives that the block accepts (default: any
+      # message trapped after this call started). Handy in end-to-end tests.
+      # +timeout:+ and +interval:+ are seconds; on timeout +error.name+ is "timeout".
+      #
+      #   msg, error = client.sandboxes.messages.wait_for(box["id"]) { |m| m["subject"] == "Hi" }
+      def wait_for(sandbox_id, timeout: 30, interval: 1, &match)
+        started = Time.now
+        deadline = started + timeout
+        match ||= lambda do |m|
+          Time.iso8601(m["trappedAt"].to_s) >= started - 1
+        rescue ArgumentError
+          false
+        end
+        loop do
+          page = list(sandbox_id, limit: 50)
+          return page unless page.ok?
+
+          found = (page.data || []).find { |m| match.call(m) }
+          return get(sandbox_id, found["id"]) if found
+
+          if Time.now >= deadline
+            return Result.new(nil, ErrorResponse.new(name: "timeout", status_code: nil,
+                                                     message: "No matching message reached sandbox #{sandbox_id} within #{timeout} s."), nil)
+          end
+          sleep(interval) if interval.positive?
+        end
+      end
+    end
+  end
+end

data/lib/sendclipper/resources/templates.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module SendClipper
+  module Resources
+    class Templates < Base
+      attr_reader :tags, :assets
+
+      def initialize(http)
+        super
+        @tags = TemplateTags.new(http)
+        @assets = TemplateAssets.new(http)
+      end
+
+      # Fields: tag (a tag id), project (a domain id).
+      def list(params = nil, **kw)
+        query, options = split(params, kw)
+        api_get("/templates", query: query, options: options)
+      end
+
+      # By uuid or public id (+tpl_...+).
+      def get(id, **options) = api_get("/templates/#{seg(id)}", options: options)
+
+      # The rendered HTML, tags left in place.
+      def html(id, **options) = @http.call("GET", "/templates/#{seg(id)}/html", as: :text, options: options)
+
+      # A new draft. Publish it before sending with it. Fields: name, subject,
+      # preheader, blocks, project_domain_id, key.
+      def create(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/templates", body, options: options)
+      end
+
+      def update(id, params = nil, **kw)
+        body, options = split(params, kw)
+        api_patch("/templates/#{seg(id)}", body, options: options)
+      end
+
+      def remove(id, **options) = api_delete("/templates/#{seg(id)}", options: options)
+
+      def duplicate(id, **options) = api_post("/templates/#{seg(id)}/duplicate", nil, options: options)
+
+      def publish(id, **options) = api_post("/templates/#{seg(id)}/publish", nil, options: options)
+
+      def unpublish(id, **options) = api_post("/templates/#{seg(id)}/unpublish", nil, options: options)
+
+      # Render with +variables+ without sending anything.
+      def preview(id, variables = {}, **options)
+        api_post("/templates/#{seg(id)}/preview", { "variables" => variables.to_h }, options: options)
+      end
+
+      # Replace the template's tags with these tag ids.
+      def set_tags(id, tag_ids, **options) = api_put("/templates/#{seg(id)}/tags", { "tagIds" => tag_ids.to_a }, options: options)
+
+      # The projects (domains) templates can belong to.
+      def projects(**options) = api_get("/templates/projects", options: options)
+    end
+
+    class TemplateTags < Base
+      # Every tag, each with its templateCount.
+      def list(**options) = api_get("/templates/tags", options: options)
+
+      # Fields: name, color (gray, red, orange, amber, green, teal, blue, purple, pink).
+      def create(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/templates/tags", body, options: options)
+      end
+
+      def update(id, params = nil, **kw)
+        body, options = split(params, kw)
+        api_patch("/templates/tags/#{seg(id)}", body, options: options)
+      end
+
+      # { "deleted" => true, "templateCount" => n }: the tag is taken off n templates.
+      def remove(id, **options) = api_delete("/templates/tags/#{seg(id)}", options: options)
+    end
+
+    class TemplateAssets < Base
+      def list(**options) = api_get("/templates/assets", options: options)
+
+      # Upload an image a template can show and get its public URL. +data:+ is
+      # the file's bytes (base64-encoded for you); +mime_type:+ is image/png,
+      # image/jpeg, image/gif or image/webp.
+      #
+      #   client.templates.assets.upload(data: File.binread("logo.png"), mime_type: "image/png", name: "logo")
+      def upload(data:, mime_type:, name: nil, **options)
+        body = { "mimeType" => mime_type, "base64" => [data.to_s].pack("m0") }
+        body["name"] = name if name && !name.empty?
+        api_post("/templates/assets", body, options: options)
+      end
+    end
+  end
+end

data/lib/sendclipper/resources/webhooks.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SendClipper
+  module Resources
+    class Webhooks < Base
+      attr_reader :dispatches
+
+      def initialize(http)
+        super
+        @dispatches = WebhookDispatches.new(http)
+      end
+
+      def list(**options) = api_get("/webhook-endpoints", options: options)
+
+      # Fields: url, events, allow_insecure_http. The response carries the
+      # signing "secret" once: store it.
+      def create(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/webhook-endpoints", body, options: options)
+      end
+
+      def update(id, params = nil, **kw)
+        body, options = split(params, kw)
+        api_patch("/webhook-endpoints/#{seg(id)}", body, options: options)
+      end
+
+      def remove(id, **options) = api_delete("/webhook-endpoints/#{seg(id)}", options: options)
+
+      # A new secret. The old one keeps signing alongside it for the grace window.
+      def rotate_secret(id, **options) = api_post("/webhook-endpoints/#{seg(id)}/rotate-secret", nil, options: options)
+
+      # Recent delivery attempts. Fields: endpoint_id, final_only, limit.
+      def deliveries(params = nil, **kw)
+        query, options = split(params, kw)
+        api_get("/webhook-deliveries", query: query, options: options)
+      end
+
+      # Verify a delivery's signature and return the parsed event. Makes no
+      # request. Same as SendClipper.verify_webhook.
+      def verify(payload, headers, secret, **kw) = SendClipper.verify_webhook(payload, headers, secret, **kw)
+    end
+
+    class WebhookDispatches < Base
+      # Undelivered events: dead letters by default, or state: "retrying".
+      # Fields: state, endpoint_id, cursor, limit.
+      def list(params = nil, **kw)
+        query, options = split(params, kw)
+        api_get("/webhook-dispatches", query: query, options: options)
+      end
+
+      def each(params = nil, **kw, &block)
+        query, options = split(params, kw)
+        query.delete("cursor")
+        enum = Paging.cursor("data") { |c| api_get("/webhook-dispatches", query: query.merge("cursor" => c), options: options) }
+        block ? enum.each(&block) : enum
+      end
+
+      def get(id, **options) = api_get("/webhook-dispatches/#{seg(id)}", options: options)
+
+      # One more immediate attempt for a dead-lettered event.
+      def replay(id, **options) = api_post("/webhook-dispatches/#{seg(id)}/replay", nil, options: options)
+
+      # Replay every dead letter (optionally of one endpoint), up to the server's cap.
+      def replay_all(params = nil, **kw)
+        body, options = split(params, kw)
+        api_post("/webhook-dispatches/replay-all", body, options: options)
+      end
+    end
+  end
+end

data/lib/sendclipper/resources/workspace.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SendClipper
+  module Resources
+    class Workspace < Base
+      # The workspace this key belongs to.
+      def get(**options) = api_get("/workspace", options: options)
+    end
+
+    class ApiKeys < Base
+      # The workspace's keys, masked. Keys are created and revoked in the dashboard only.
+      def list(**options) = api_get("/api-keys", options: options)
+    end
+
+    class Automations < Base
+      # Start a Live automation with a +manual+ trigger for one contact.
+      def enroll(automation_id, email, **options)
+        api_post("/automations/#{seg(automation_id)}/enrollments", { "email" => email }, options: options)
+      end
+    end
+  end
+end