sevk 1.0.0 → 1.1.0

data/lib/sevk/resources/emails.rb

@@ -1,55 +1,106 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
+require_relative '../markup/renderer'
 
 module Sevk
   module Resources
     class Emails < Base
-      # Send an email with optional attachments
-      #
-      # @param to [String, Array<String>] Recipient email(s)
-      # @param subject [String] Email subject
-      # @param html [String] HTML content
-      # @param from [String] Sender email
-      # @param from_name [String, nil] Sender name
-      # @param reply_to [String, nil] Reply-to address
-      # @param text [String, nil] Plain text content
-      # @param headers [Hash, nil] Custom headers
-      # @param tags [Array, nil] Tags
-      # @param attachments [Array<Hash>, nil] Attachments (max 10, 10MB total)
-      #   Each attachment: { filename: String, content: String (base64), content_type: String }
-      # @return [Hash] Response with :id or :ids
-      def send(to:, subject:, html:, from:, from_name: nil, reply_to: nil, text: nil, headers: nil, tags: nil, attachments: nil)
+      # Sends one transactional email, rendering local markup when supplied.
+      def send(to:, subject:, from:, html: nil, text: nil, markup: nil, reply_to: nil, cc: nil, bcc: nil,
+               attachments: nil, tracking: nil, headers: nil, scheduled_at: nil, options: nil)
         body = {
           to: to,
           subject: subject,
-          html: html,
           from: from
         }
-        body[:fromName] = from_name if from_name
-        body[:replyTo] = reply_to if reply_to
-        body[:text] = text if text
-        body[:headers] = headers if headers
-        body[:tags] = tags if tags
-        body[:attachments] = attachments if attachments
-        client.post("emails", body)
+        body[:html] = html unless html.nil?
+        body[:html] = Sevk::Markup::Renderer.new.render(markup) if markup && !markup.empty?
+        body[:text] = text unless text.nil?
+        body[:reply_to] = reply_to unless reply_to.nil?
+        body[:cc] = cc unless cc.nil?
+        body[:bcc] = bcc unless bcc.nil?
+        body[:attachments] = normalize_attachments(attachments) unless attachments.nil?
+        body[:tracking] = tracking unless tracking.nil?
+        body[:headers] = headers unless headers.nil?
+        body[:scheduledAt] = scheduled_at unless scheduled_at.nil?
+
+        client.post('/emails', body, headers: idempotency_headers(options))
       end
 
-      # Send multiple emails in bulk
-      #
-      # @param emails [Array<Hash>] Array of email parameter hashes (max 100)
-      # @return [Hash] Response with :success, :failed, :ids, :errors
-      def send_bulk(emails)
-        client.post("emails/bulk", { emails: emails })
+      # Sends up to 100 transactional emails and returns per-request results.
+      def send_bulk(emails, options: nil)
+        unless emails.is_a?(Array)
+          return client.post('/emails/bulk', { emails: emails }, headers: idempotency_headers(options))
+        end
+
+        wire_emails = emails.map do |email|
+          next email unless email.is_a?(Hash)
+
+          payload = email.dup
+          symbol_markup = payload.delete(:markup)
+          string_markup = payload.delete('markup')
+          mk = symbol_markup.nil? ? string_markup : symbol_markup
+          unless mk.nil? || mk.empty?
+            payload.delete(:html)
+            payload.delete('html')
+            payload[:html] = Sevk::Markup::Renderer.new.render(mk)
+          end
+          attachments = payload[:attachments] || payload['attachments']
+          if attachments
+            payload.delete('attachments')
+            payload[:attachments] = normalize_attachments(attachments)
+          end
+          payload
+        end
+
+        client.post('/emails/bulk', { emails: wire_emails }, headers: idempotency_headers(options))
       end
 
-      # Get an email by ID
-      #
-      # @param id [String] Email ID
-      # @return [Hash] Email details
+      # Retrieves a sent email and its current delivery state.
       def get(id)
         client.get("/emails/#{id}")
       end
+
+      # moves an unattempted scheduled email to a new delivery time.
+      def update(id, scheduled_at:)
+        client.patch("/emails/#{id}", { scheduledAt: scheduled_at })
+      end
+
+      # cancels an unattempted scheduled email.
+      def cancel(id)
+        client.post("/emails/#{id}/cancel")
+      end
+
+      private
+
+      def normalize_attachments(attachments)
+        return attachments unless attachments.is_a?(Array)
+
+        attachments.map do |attachment|
+          next attachment unless attachment.is_a?(Hash)
+
+          normalized = attachment.dup
+          content_type = normalized.delete(:content_type)
+          content_type = normalized.delete('content_type') if content_type.nil?
+          unless content_type.nil? || normalized.key?(:contentType) || normalized.key?('contentType')
+            normalized[:contentType] = content_type
+          end
+
+          normalized
+        end
+      end
+
+      # Builds the optional idempotency header used to make retries safe.
+      def idempotency_headers(options)
+        return nil unless options
+
+        return nil unless options.key?(:idempotency_key) || options.key?('idempotency_key')
+
+        key = options.key?(:idempotency_key) ? options[:idempotency_key] : options['idempotency_key']
+
+        { 'Idempotency-Key' => key.to_s }
+      end
     end
   end
 end

data/lib/sevk/resources/inbound.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Sevk
+  module Resources
+    class Inbound < Base
+      # Lists received email with optional pagination and filtering.
+      def list(page: nil, limit: nil, after: nil, before: nil, search: nil, status: nil, domain_id: nil,
+               broadcast_id: nil, is_spam: nil, is_virus: nil)
+        params = {
+          page: page,
+          limit: limit,
+          after: after,
+          before: before,
+          search: search,
+          status: status,
+          domainId: domain_id,
+          broadcastId: broadcast_id,
+          isSpam: is_spam,
+          isVirus: is_virus
+        }
+
+        client.get("/inbound#{build_query_string(params)}")
+      end
+
+      # Retrieves a received email with parsed content and attachment metadata.
+      def get(id)
+        client.get("/inbound/#{id}")
+      end
+
+      # Deletes a received email and its stored content.
+      def delete(id)
+        client.delete("/inbound/#{id}")
+      end
+
+      # Returns aggregate inbound processing statistics, optionally for one domain.
+      def stats(domain_id: nil)
+        params = { domainId: domain_id }
+
+        client.get("/inbound/stats#{build_query_string(params)}")
+      end
+
+      # Downloads the original content and metadata for an inbound attachment.
+      def download_attachment(email_id, attachment_id)
+        client.get("/inbound/#{email_id}/attachments/#{attachment_id}/download")
+      end
+
+      # Lists rules used to store or forward matching inbound email.
+      def list_routes(**params)
+        client.get("/inbound-settings/routes#{build_query_string(params)}")
+      end
+
+      def route_items(**params)
+        list_routes(**params).fetch('items')
+      end
+
+      # Retrieves an inbound routing rule by id.
+      def get_route(id)
+        client.get("/inbound-settings/routes/#{id}")
+      end
+
+      # Creates an inbound routing rule.
+      def create_route(**params)
+        client.post('/inbound-settings/routes', wire_keys(params))
+      end
+
+      # Updates an inbound routing rule while preserving omitted fields.
+      def update_route(id, **params)
+        client.put("/inbound-settings/routes/#{id}", wire_keys(params))
+      end
+
+      # Deletes an inbound routing rule without deleting stored email.
+      def delete_route(id)
+        client.delete("/inbound-settings/routes/#{id}")
+      end
+
+      # Lists blocked addresses with optional offset or cursor pagination.
+      def list_blocklist(**params)
+        client.get("/inbound-settings/blocklist#{build_query_string(params)}")
+      end
+
+      def blocklist_items(**params)
+        list_blocklist(**params).fetch('items')
+      end
+
+      # Adds an address to the inbound blocklist.
+      def add_blocklist_entry(**params)
+        client.post('/inbound-settings/blocklist', wire_keys(params))
+      end
+
+      # Removes an address from the inbound blocklist.
+      def remove_blocklist_entry(id)
+        client.delete("/inbound-settings/blocklist/#{id}")
+      end
+
+      # Returns inbound quota settings and current usage counters.
+      def get_quota
+        client.get('/inbound-settings/quota')
+      end
+
+      # Updates the inbound monthly limit while preserving omitted fields.
+      def update_quota(**params)
+        client.put('/inbound-settings/quota', wire_keys(params))
+      end
+
+      # Clears a quota pause without resetting current-period usage.
+      def reset_quota
+        client.post('/inbound-settings/quota/reset', {})
+      end
+
+      # Returns effective inbound security settings for a domain.
+      def get_security_config(domain_id)
+        client.get("/inbound-settings/security/#{domain_id}")
+      end
+
+      # Updates inbound security settings for a domain.
+      def update_security_config(domain_id, **params)
+        client.put("/inbound-settings/security/#{domain_id}", wire_keys(params))
+      end
+    end
+  end
+end

data/lib/sevk/resources/outbound.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Sevk
+  module Resources
+    # Outbound resource. Read and adjust the project's monthly outbound
+    # sending cap, and pause / resume transactional sending.
+    #
+    # Pause affects +POST /emails+, +POST /emails/bulk+, and SMTP relay.
+    # Broadcasts run on a separate balance check and are NOT affected.
+    #
+    # Access via +sevk.outbound+. Requires an API key with +outbound:read+
+    # for +get_quota+, or +outbound:write+ for the others.
+    class Outbound < Base
+      # Get outbound quota settings and current usage counters.
+      # Requires +outbound:read+.
+      def get_quota
+        client.get('/outbound-settings/quota')
+      end
+
+      # Set the user-side monthly outbound cap. Pass +monthlyEmailLimit:+
+      # as a positive Integer to cap, or +nil+ to clear the user-set cap
+      # (admin ceiling still applies). Raising the cap above current
+      # usage clears a +monthly_cap_exhausted+ pause; does not clear
+      # +manual_suspend+.
+      # Requires +outbound:write+.
+      def update_quota(**params)
+        client.put('/outbound-settings/quota', wire_keys(params))
+      end
+
+      # Preserve the monthly counter and clear any pause (including
+      # +manual_suspend+ and +balance_exhausted+). The user-set cap is
+      # preserved.
+      # Requires +outbound:write+.
+      def reset_quota
+        client.post('/outbound-settings/quota/reset', {})
+      end
+
+      # Reset custom-limit usage while preserving the cap and monthly usage.
+      # Requires +outbound:write+.
+      def reset_limit
+        client.post('/outbound-settings/quota/reset-limit', {})
+      end
+
+      # Pause outbound transactional sending with
+      # +pausedReason: manual_suspend+. Manual pauses do NOT auto-clear;
+      # call +reset_quota+ to resume. Does not affect broadcasts.
+      # Requires +outbound:write+.
+      def pause_quota
+        client.post('/outbound-settings/quota/pause', {})
+      end
+    end
+  end
+end

data/lib/sevk/resources/segments.rb

@@ -1,42 +1,56 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
 
 module Sevk
   module Resources
     class Segments < Base
-      def list(audience_id, page: nil, limit: nil)
-        params = { page: page, limit: limit }
-        client.get("/audiences/#{audience_id}/segments#{build_query_string(params)}")
-      end
+      # Lists segments belonging to an audience with optional filtering.
+      def list(audience_id, page: nil, limit: nil, after: nil, before: nil, search: nil)
+        params = { page: page, limit: limit, after: after, before: before, search: search }
 
-      def get(audience_id, segment_id)
-        client.get("/audiences/#{audience_id}/segments/#{segment_id}")
+        client.get("/audiences/#{audience_id}/segments#{build_query_string(params)}")
       end
 
-      def create(audience_id, name:, rules:, operator: "AND")
+      # Creates a saved contact segment under an audience.
+      def create(audience_id, name:, rules:, operator: 'AND', limit_to_topics: nil, groups: nil)
         body = { name: name, rules: rules, operator: operator }
+        body[:limitToTopics] = limit_to_topics unless limit_to_topics.nil?
+        body[:groups] = groups unless groups.nil?
+
         client.post("/audiences/#{audience_id}/segments", body)
       end
 
-      def update(audience_id, segment_id, name: nil, rules: nil, operator: nil)
-        body = {}
-        body[:name] = name if name
-        body[:rules] = rules if rules
-        body[:operator] = operator if operator
-        client.put("/audiences/#{audience_id}/segments/#{segment_id}", body)
+      # Evaluates segment rules and returns matches without saving a segment.
+      def preview(audience_id, data)
+        client.post("/audiences/#{audience_id}/segments/preview", wire_keys(data))
       end
 
-      def delete(audience_id, segment_id)
-        client.delete("/audiences/#{audience_id}/segments/#{segment_id}")
+      # Retrieves a saved segment by id.
+      def get(segment_id)
+        client.get("/segments/#{segment_id}")
       end
 
-      def calculate(audience_id, segment_id)
-        client.get("/audiences/#{audience_id}/segments/#{segment_id}/calculate")
+      # Updates a segment while preserving omitted fields.
+      def update(segment_id, name: nil, rules: nil, operator: nil, limit_to_topics: nil, groups: nil)
+        body = {}
+        body[:name] = name unless name.nil?
+        body[:rules] = rules unless rules.nil?
+        body[:operator] = operator unless operator.nil?
+        body[:limitToTopics] = limit_to_topics unless limit_to_topics.nil?
+        body[:groups] = groups unless groups.nil?
+
+        client.put("/segments/#{segment_id}", body)
       end
 
-      def preview(audience_id, data)
-        client.post("/audiences/#{audience_id}/segments/preview", data)
+      # Deletes a segment without deleting any contacts.
+      def delete(segment_id)
+        client.delete("/segments/#{segment_id}")
+      end
+
+      # Recalculates and returns the current matching contact count.
+      def calculate(segment_id)
+        client.get("/segments/#{segment_id}/calculate")
       end
     end
   end

data/lib/sevk/resources/subscriptions.rb

@@ -1,22 +1,29 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
 
 module Sevk
   module Resources
     class Subscriptions < Base
-      def subscribe(email:, audience_id:, topic_ids: nil, metadata: nil)
-        body = { email: email, audienceId: audience_id }
-        body[:topicIds] = topic_ids if topic_ids
-        body[:metadata] = metadata if metadata
-        client.post("/subscriptions/subscribe", body)
+      # Subscribes a contact and optionally adds it to an audience.
+      def subscribe(email:, audience_id: nil, data: nil)
+        body = { email: email }
+        body[:audienceId] = audience_id unless audience_id.nil?
+        body[:data] = data unless data.nil?
+
+        client.post('/subscriptions/subscribe', body)
       end
 
-      def unsubscribe(email:, audience_id: nil, topic_ids: nil)
-        body = { email: email }
-        body[:audienceId] = audience_id if audience_id
-        body[:topicIds] = topic_ids if topic_ids
-        client.post("/subscriptions/unsubscribe", body)
+      # Global opt-out. Provide at least one of email or contact_id (if both are
+      # given, contact_id wins). broadcast_id only attributes the opt-out to a
+      # broadcast (activity + counters); it does NOT scope the unsubscribe.
+      def unsubscribe(email: nil, contact_id: nil, broadcast_id: nil)
+        body = {}
+        body[:email] = email unless email.nil?
+        body[:contactId] = contact_id unless contact_id.nil?
+        body[:broadcastId] = broadcast_id unless broadcast_id.nil?
+
+        client.post('/subscriptions/unsubscribe', body)
       end
     end
   end

data/lib/sevk/resources/templates.rb

@@ -1,34 +1,46 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
 
 module Sevk
   module Resources
     class Templates < Base
-      def list(page: nil, limit: nil, search: nil)
-        params = { page: page, limit: limit, search: search }
+      # Lists reusable email templates with optional pagination and search.
+      def list(page: nil, limit: nil, after: nil, before: nil, search: nil)
+        params = { page: page, limit: limit, after: after, before: before, search: search }
+
         client.get("/templates#{build_query_string(params)}")
       end
 
+      # Retrieves a template by id.
       def get(id)
         client.get("/templates/#{id}")
       end
 
-      def create(title:, content:)
-        client.post("/templates", { title: title, content: content })
+      # Creates a reusable email template from markup and optional styles.
+      def create(title:, content:, style: nil)
+        body = { title: title, content: content }
+        body[:style] = style unless style.nil?
+
+        client.post('/templates', body)
       end
 
-      def update(id, title: nil, content: nil)
+      # Updates a template while preserving omitted fields.
+      def update(id, title: nil, content: nil, style: nil)
         body = {}
-        body[:title] = title if title
-        body[:content] = content if content
+        body[:title] = title unless title.nil?
+        body[:content] = content unless content.nil?
+        body[:style] = style unless style.nil?
+
         client.put("/templates/#{id}", body)
       end
 
+      # Deletes a template without affecting email already sent from it.
       def delete(id)
         client.delete("/templates/#{id}")
       end
 
+      # Creates an independent copy of a template for further editing.
       def duplicate(id)
         client.post("/templates/#{id}/duplicate", {})
       end

data/lib/sevk/resources/topics.rb

@@ -1,46 +1,57 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
 
 module Sevk
   module Resources
     class Topics < Base
-      def list(audience_id, page: nil, limit: nil)
-        params = { page: page, limit: limit }
-        client.get("/audiences/#{audience_id}/topics#{build_query_string(params)}")
-      end
+      # Lists topics belonging to an audience with optional filtering.
+      def list(audience_id, page: nil, limit: nil, after: nil, before: nil, search: nil)
+        params = { page: page, limit: limit, after: after, before: before, search: search }
 
-      def get(audience_id, topic_id)
-        client.get("/audiences/#{audience_id}/topics/#{topic_id}")
+        client.get("/audiences/#{audience_id}/topics#{build_query_string(params)}")
       end
 
+      # Creates a subscription topic under an audience.
       def create(audience_id, name:, description: nil)
         body = { name: name }
-        body[:description] = description if description
+        body[:description] = description unless description.nil?
+
         client.post("/audiences/#{audience_id}/topics", body)
       end
 
-      def update(audience_id, topic_id, name: nil, description: nil)
+      # Retrieves a topic by id.
+      def get(topic_id)
+        client.get("/topics/#{topic_id}")
+      end
+
+      # Updates a topic while preserving omitted fields.
+      def update(topic_id, name: nil, description: nil)
         body = {}
-        body[:name] = name if name
-        body[:description] = description if description
-        client.put("/audiences/#{audience_id}/topics/#{topic_id}", body)
+        body[:name] = name unless name.nil?
+        body[:description] = description unless description.nil?
+
+        client.put("/topics/#{topic_id}", body)
       end
 
-      def delete(audience_id, topic_id)
-        client.delete("/audiences/#{audience_id}/topics/#{topic_id}")
+      # Deletes a topic without deleting its contacts or parent audience.
+      def delete(topic_id)
+        client.delete("/topics/#{topic_id}")
       end
 
-      def add_contacts(audience_id, topic_id, contact_ids:)
-        client.post("/audiences/#{audience_id}/topics/#{topic_id}/contacts", { contactIds: contact_ids })
+      # Adds contacts to a topic, ignoring memberships that already exist.
+      def add_contacts(topic_id, contact_ids:)
+        client.post("/topics/#{topic_id}/contacts", { contactIds: contact_ids })
       end
 
-      def remove_contact(audience_id, topic_id, contact_id)
-        client.delete("/audiences/#{audience_id}/topics/#{topic_id}/contacts/#{contact_id}")
+      # Removes a contact from the topic without deleting the contact.
+      def remove_contact(topic_id, contact_id)
+        client.delete("/topics/#{topic_id}/contacts/#{contact_id}")
       end
 
-      def list_contacts(audience_id, topic_id, params = {})
-        client.get("/audiences/#{audience_id}/topics/#{topic_id}/contacts#{build_query_string(params)}")
+      # Lists contacts by page, cursor, search text, or subscription state.
+      def list_contacts(topic_id, params = {})
+        client.get("/topics/#{topic_id}/contacts#{build_query_string(params)}")
       end
     end
   end

data/lib/sevk/resources/usage.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Sevk
+  module Resources
+    # Reads project limits, resource counts, and current email usage.
+    class Usage < Base
+      # Returns current limits, resource counts, and inbound and outbound usage.
+      def get
+        client.get('/limits')
+      end
+    end
+  end
+end

data/lib/sevk/resources/webhooks.rb

@@ -1,37 +1,51 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
 
 module Sevk
   module Resources
     class Webhooks < Base
-      def list(page: nil, limit: nil)
-        params = { page: page, limit: limit }
+      def rotate(id)
+        client.post("/webhooks/#{id}/rotate", {})
+      end
+
+      # Lists configured webhooks and the available event catalog.
+      def list(page: nil, limit: nil, after: nil, before: nil)
+        params = { page: page, limit: limit, after: after, before: before }
+
         client.get("/webhooks#{build_query_string(params)}")
       end
 
+      # Retrieves a webhook and its recent delivery state. Its secret is the
+      # masked placeholder (••••••••), not a usable verification secret.
       def get(id)
         client.get("/webhooks/#{id}")
       end
 
+      # Creates a webhook subscription. The returned Hash always contains a non-nil
+      # :secret/"secret" value prefixed with whsec_; this usable secret appears only once.
       def create(params)
-        client.post("/webhooks", params)
+        client.post('/webhooks', wire_keys(params))
       end
 
+      # Updates a webhook while preserving omitted fields.
       def update(id, params)
-        client.put("/webhooks/#{id}", params)
+        client.put("/webhooks/#{id}", wire_keys(params))
       end
 
+      # Deletes a webhook and stops future deliveries to its URL.
       def delete(id)
         client.delete("/webhooks/#{id}")
       end
 
+      # Sends a test event to a webhook and returns the delivery result.
       def test(id)
         client.post("/webhooks/#{id}/test", {})
       end
 
-      def list_events
-        client.get("/webhooks/events")
+      # Lists event names that can be assigned to a webhook.
+      def events
+        client.get('/webhooks/events')
       end
     end
   end

data/lib/sevk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sevk
-  VERSION = "1.0.0"
+  VERSION = '1.1.0'
 end