nylas 6.7.0 → 6.8.0

data/lib/nylas/resources/domains.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/api_operations"
+require_relative "../handler/service_account_signer"
+require "uri"
+
+module Nylas
+  # Module representing the possible 'type' values in a domain verification request.
+  # @see https://developer.nylas.com/docs/reference/api/manage-domains/
+  module DomainVerificationRequestType
+    OWNERSHIP = "ownership"
+    MX = "mx"
+    SPF = "spf"
+    DKIM = "dkim"
+    FEEDBACK = "feedback"
+  end
+
+  # Module representing the possible 'type' values in a domain verification result.
+  # @see https://developer.nylas.com/docs/reference/api/manage-domains/
+  module DomainVerificationType
+    OWNERSHIP = DomainVerificationRequestType::OWNERSHIP
+    MX = DomainVerificationRequestType::MX
+    SPF = DomainVerificationRequestType::SPF
+    DKIM = DomainVerificationRequestType::DKIM
+    FEEDBACK = DomainVerificationRequestType::FEEDBACK
+    DMARC = "dmarc"
+    ARC = "arc"
+  end
+
+  # Module representing the possible 'status' values in a domain verification result.
+  module DomainVerificationStatus
+    PENDING = "pending"
+    DONE = "done"
+    FAILED = "failed"
+  end
+
+  # Nylas Manage Domains API
+  #
+  # These endpoints require Nylas Service Account request signing. Pass headers
+  # containing `X-Nylas-Kid`, `X-Nylas-Timestamp`, `X-Nylas-Nonce`, and
+  # `X-Nylas-Signature` generated for the exact request being sent.
+  class Domains < Resource
+    include ApiOperations::Get
+    include ApiOperations::Post
+    include ApiOperations::Put
+    include ApiOperations::Delete
+
+    REQUIRED_SERVICE_ACCOUNT_HEADERS = %w[
+      X-Nylas-Kid
+      X-Nylas-Timestamp
+      X-Nylas-Nonce
+      X-Nylas-Signature
+    ].freeze
+    DOMAINS_PATH = "/v3/admin/domains"
+
+    # Return all domains for the caller's organization.
+    #
+    # @param query_params [Hash, nil] Query params to pass to the request.
+    #   Supported keys: `limit`, `page_token`.
+    # @param headers [Hash, nil] Nylas Service Account request signing headers.
+    # @param signer [ServiceAccountSigner, nil] Signer to generate Nylas Service Account headers.
+    # @return [Array(Array(Hash), String, String, Hash)]
+    #   The list of domains, API Request ID, next cursor, and response headers.
+    def list(headers: nil, query_params: nil, signer: nil)
+      request_headers, = signed_request_headers(method: :get, relative_path: DOMAINS_PATH,
+                                                headers: headers, signer: signer)
+
+      get_list(
+        path: full_path(DOMAINS_PATH),
+        query_params: query_params,
+        headers: request_headers
+      )
+    end
+
+    # Return a domain.
+    #
+    # @param domain_id [String] The identifier of the domain to return.
+    #   Accepts either a UUID or a domain address (FQDN/email format).
+    # @param headers [Hash, nil] Nylas Service Account request signing headers.
+    # @param signer [ServiceAccountSigner, nil] Signer to generate Nylas Service Account headers.
+    # @return [Array(Hash, String, Hash)] The domain, API request ID, and response headers.
+    def find(domain_id:, headers: nil, signer: nil)
+      relative_path = "#{DOMAINS_PATH}/#{encoded_domain_id(domain_id)}"
+      request_headers, = signed_request_headers(method: :get, relative_path: relative_path,
+                                                headers: headers, signer: signer)
+
+      get(
+        path: full_path(relative_path),
+        headers: request_headers
+      )
+    end
+
+    # Create a domain.
+    #
+    # @param request_body [Hash] The values to create the domain with.
+    #   Requires `name` and `domain_address`.
+    # @param headers [Hash, nil] Nylas Service Account request signing headers.
+    # @param signer [ServiceAccountSigner, nil] Signer to generate Nylas Service Account headers.
+    # @return [Array(Hash, String, Hash)] The created domain, API Request ID, and response headers.
+    def create(request_body:, headers: nil, signer: nil)
+      request_headers, serialized_body = signed_request_headers(
+        method: :post,
+        relative_path: DOMAINS_PATH,
+        body: request_body,
+        headers: headers,
+        signer: signer
+      )
+
+      request = {
+        path: full_path(DOMAINS_PATH),
+        request_body: serialized_body.nil? ? request_body : nil,
+        headers: request_headers
+      }
+      request[:serialized_json_body] = serialized_body unless serialized_body.nil?
+      post(**request)
+    end
+
+    # Update a domain.
+    #
+    # @param domain_id [String] The identifier of the domain to update.
+    #   Accepts either a UUID or a domain address (FQDN/email format).
+    # @param request_body [Hash] The values to update the domain with.
+    #   The response echoes only the updated fields, not a full domain object.
+    # @param headers [Hash, nil] Nylas Service Account request signing headers.
+    # @param signer [ServiceAccountSigner, nil] Signer to generate Nylas Service Account headers.
+    # @return [Array(Hash, String)] The updated domain fields and API Request ID.
+    def update(domain_id:, request_body:, headers: nil, signer: nil)
+      relative_path = "#{DOMAINS_PATH}/#{encoded_domain_id(domain_id)}"
+      request_headers, serialized_body = signed_request_headers(
+        method: :put,
+        relative_path: relative_path,
+        body: request_body,
+        headers: headers,
+        signer: signer
+      )
+
+      request = {
+        path: full_path(relative_path),
+        request_body: serialized_body.nil? ? request_body : nil,
+        headers: request_headers
+      }
+      request[:serialized_json_body] = serialized_body unless serialized_body.nil?
+      put(**request)
+    end
+
+    # Delete a domain.
+    #
+    # @param domain_id [String] The identifier of the domain to delete.
+    #   Accepts either a UUID or a domain address (FQDN/email format).
+    # @param headers [Hash, nil] Nylas Service Account request signing headers.
+    # @param signer [ServiceAccountSigner, nil] Signer to generate Nylas Service Account headers.
+    # @return [Array(TrueClass, String)] True and the API Request ID for the delete operation.
+    def destroy(domain_id:, headers: nil, signer: nil)
+      relative_path = "#{DOMAINS_PATH}/#{encoded_domain_id(domain_id)}"
+      request_headers, = signed_request_headers(method: :delete, relative_path: relative_path,
+                                                headers: headers, signer: signer)
+
+      _, request_id = delete(
+        path: full_path(relative_path),
+        headers: request_headers
+      )
+
+      [true, request_id]
+    end
+
+    # Get the DNS record info for a domain verification type.
+    #
+    # @param domain_id [String] The identifier of the domain.
+    #   Accepts either a UUID or a domain address (FQDN/email format).
+    # @param request_body [Hash] The verification attempt values. Requires `type`.
+    # @param headers [Hash, nil] Nylas Service Account request signing headers.
+    # @param signer [ServiceAccountSigner, nil] Signer to generate Nylas Service Account headers.
+    # @return [Array(Hash, String, Hash)]
+    #   The domain verification result, API Request ID, and response headers.
+    def info(domain_id:, request_body:, headers: nil, signer: nil)
+      relative_path = "#{DOMAINS_PATH}/#{encoded_domain_id(domain_id)}/info"
+      request_headers, serialized_body = signed_request_headers(
+        method: :post,
+        relative_path: relative_path,
+        body: request_body,
+        headers: headers,
+        signer: signer
+      )
+
+      request = {
+        path: full_path(relative_path),
+        request_body: serialized_body.nil? ? request_body : nil,
+        headers: request_headers
+      }
+      request[:serialized_json_body] = serialized_body unless serialized_body.nil?
+      post(**request)
+    end
+
+    # Trigger a DNS verification check for a domain verification type.
+    #
+    # @param domain_id [String] The identifier of the domain.
+    #   Accepts either a UUID or a domain address (FQDN/email format).
+    # @param request_body [Hash] The verification attempt values. Requires `type`.
+    # @param headers [Hash, nil] Nylas Service Account request signing headers.
+    # @param signer [ServiceAccountSigner, nil] Signer to generate Nylas Service Account headers.
+    # @return [Array(Hash, String, Hash)]
+    #   The domain verification result, API Request ID, and response headers.
+    def verify(domain_id:, request_body:, headers: nil, signer: nil)
+      relative_path = "#{DOMAINS_PATH}/#{encoded_domain_id(domain_id)}/verify"
+      request_headers, serialized_body = signed_request_headers(
+        method: :post,
+        relative_path: relative_path,
+        body: request_body,
+        headers: headers,
+        signer: signer
+      )
+
+      request = {
+        path: full_path(relative_path),
+        request_body: serialized_body.nil? ? request_body : nil,
+        headers: request_headers
+      }
+      request[:serialized_json_body] = serialized_body unless serialized_body.nil?
+      post(**request)
+    end
+
+    private
+
+    # Manage Domains uses Nylas Service Account signing headers instead of API-key bearer auth.
+    def api_key
+      nil
+    end
+
+    def full_path(relative_path)
+      "#{api_uri}#{relative_path}"
+    end
+
+    def encoded_domain_id(domain_id)
+      URI.encode_www_form_component(domain_id)
+    end
+
+    def signed_request_headers(method:, relative_path:, headers:, signer:, body: nil)
+      request_headers = headers.nil? ? {} : headers.dup
+      serialized_body = body.nil? ? nil : Nylas::ServiceAccountSigner.canonical_json(body)
+      if signer
+        signer_headers, serialized_body = signer.build_headers(
+          method: method,
+          path: relative_path,
+          body: body
+        )
+        request_headers.merge!(signer_headers)
+      end
+
+      validate_service_account_headers!(request_headers)
+      [request_headers, serialized_body]
+    end
+
+    def validate_service_account_headers!(headers)
+      header_values = headers || {}
+      normalized_headers = header_values.transform_keys do |key|
+        key.to_s.downcase
+      end
+      missing_headers = REQUIRED_SERVICE_ACCOUNT_HEADERS.select do |header|
+        normalized_headers[header.downcase].to_s.empty?
+      end
+
+      return if missing_headers.empty?
+
+      raise ArgumentError,
+            "Missing required service account authentication headers: #{missing_headers.join(', ')}"
+    end
+  end
+end

data/lib/nylas/resources/lists.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/api_operations"
+
+module Nylas
+  # Module representing the possible 'type' values for a List.
+  module ListType
+    DOMAIN = "domain"
+    TLD = "tld"
+    ADDRESS = "address"
+  end
+
+  # Nylas Lists API
+  #
+  # Lists are typed collections of domains, TLDs, or email addresses that can
+  # be referenced by Rules using the +in_list+ condition operator.
+  class Lists < Resource
+    include ApiOperations::Post
+
+    # Create a list for the application.
+    #
+    # @param request_body [Hash] The public values to create the list with.
+    #   Supported keys: +name+ (required, 1-256 chars), +type+ (required; one of
+    #   +domain+, +tld+, or +address+), and +description+ (optional). The server
+    #   assigns identifiers, item counts, timestamps, and application ownership.
+    # @return [Array(Hash, String, Hash)] The created list, API Request ID, and
+    #   response headers.
+    def create(request_body:)
+      post(
+        path: "#{api_uri}/v3/lists",
+        request_body: request_body
+      )
+    end
+  end
+end

data/lib/nylas/resources/policies.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/api_operations"
+
+module Nylas
+  # Nylas Policies API (beta)
+  #
+  # Policies define message limits, spam-detection settings, options, and linked
+  # rules for Nylas Agent Accounts. `application_id` and `organization_id` are
+  # derived from the API key / gateway headers and are read-only.
+  #
+  # Policy objects (the Hash returned/accepted by these methods) carry these keys:
+  # - +id+ [String] Policy UUID. Read-only; server-assigned on create.
+  # - +name+ [String] 1-256 chars. Required on create.
+  # - +application_id+ [String] Read-only; derived from the API key.
+  # - +organization_id+ [String] Read-only; derived from the API key.
+  # - +rules+ [Array<String>] Linked rule IDs.
+  # - +created_at+ [Integer] Unix timestamp (seconds). Read-only.
+  # - +updated_at+ [Integer] Unix timestamp (seconds). Read-only.
+  # - +limits+ [Hash] Per-policy limits. Returned as *effective* values resolved
+  #   against the org's billing plan, which may differ from what was sent. Keys:
+  #   - +limit_attachment_size_limit+ [Integer] Bytes; >= 0, <= plan max.
+  #   - +limit_attachment_count_limit+ [Integer] >= 0, <= plan max.
+  #   - +limit_attachment_allowed_types+ [Array<String>] MIME types from the plan allow-list.
+  #   - +limit_size_total_mime+ [Integer] Bytes; >= 0, <= plan max.
+  #   - +limit_storage_total+ [Integer] Bytes. Unlimited-capable: -1 = unlimited.
+  #   - +limit_count_daily_message_received+ [Integer] Per-grant daily received-message
+  #     cap. Unlimited-capable: -1 = unlimited.
+  #   - +limit_count_daily_email_sent+ [Integer] Per-grant daily sent-email cap.
+  #     Unlimited-capable: -1 = unlimited.
+  #   - +limit_inbox_retention_period+ [Integer] Days. Unlimited-capable: -1. Must be
+  #     greater than spam retention when both set.
+  #   - +limit_spam_retention_period+ [Integer] Days. Unlimited-capable: -1. Must be
+  #     shorter than inbox retention when both set.
+  # - +options+ [Hash] Policy options. Keys:
+  #   - +additional_folders+ [Array<String>] Only allowed when the plan permits.
+  #   - +use_cidr_aliasing+ [Boolean] Only allowed when the plan permits.
+  # - +spam_detection+ [Hash] Spam-detection settings. Keys:
+  #   - +use_list_dnsbl+ [Boolean] Always present in responses (false when unset).
+  #   - +use_header_anomaly_detection+ [Boolean] Always present in responses (false when unset).
+  #   - +spam_sensitivity+ [Float] 0.1-5.0 inclusive. Default 1.0.
+  #
+  # The unlimited sentinel for unlimited-capable fields is -1 only; values < -1 are
+  # rejected, and -1 is honored only when the plan permits unlimited for that field.
+  class Policies < Resource
+    include ApiOperations::Get
+    include ApiOperations::Post
+    include ApiOperations::Put
+    include ApiOperations::Delete
+
+    # Return all policies.
+    #
+    # The list envelope is flat: the data array is the policies themselves and
+    # +next_cursor+ is a top-level sibling. +next_cursor+ is present on every
+    # non-empty page (including the last) and is not a has-more flag; page until
+    # an empty data array is returned.
+    #
+    # @param query_params [Hash, nil] Query params to pass to the request
+    #   (e.g. +limit+ — default 10, no server max; +page_token+ — opaque cursor).
+    # @return [Array(Array(Hash), String, String, Hash)] The list of policies,
+    #   API Request ID, next cursor, and response headers.
+    def list(query_params: nil)
+      get_list(
+        path: "#{api_uri}/v3/policies",
+        query_params: query_params
+      )
+    end
+
+    # Return a policy.
+    #
+    # @param policy_id [String] The id of the policy to return.
+    # @return [Array(Hash, String, Hash)] The policy, API request ID, and response headers.
+    def find(policy_id:)
+      get(
+        path: "#{api_uri}/v3/policies/#{policy_id}"
+      )
+    end
+
+    # Create a policy.
+    #
+    # @param request_body [Hash] The values to create the policy with. Honored keys:
+    #   +name+ (required), +options+, +limits+, +rules+, +spam_detection+. Any
+    #   +id+/+created_at+/+updated_at+/+application_id+/+organization_id+ are ignored.
+    #   Omitted +limits+/+options+/+spam_detection+ sub-fields fall back to plan defaults.
+    # @return [Array(Hash, String, Hash)] The created policy, API Request ID, and response headers.
+    def create(request_body:)
+      post(
+        path: "#{api_uri}/v3/policies",
+        request_body: request_body
+      )
+    end
+
+    # Update a policy.
+    #
+    # The route verb is PUT, but the update is a partial nested merge: provided
+    # sub-objects (+limits+/+options+/+spam_detection+) are merged field-by-field
+    # onto the stored policy. Send only the fields you intend to change.
+    #
+    # @param policy_id [String] The id of the policy to update.
+    # @param request_body [Hash] The values to update the policy with. Honored keys:
+    #   +name+, +options+, +limits+, +rules+, +spam_detection+. Any
+    #   +id+/+created_at+/+updated_at+/+application_id+/+organization_id+ are ignored.
+    # @return [Array(Hash, String)] The updated policy and API Request ID.
+    def update(policy_id:, request_body:)
+      put(
+        path: "#{api_uri}/v3/policies/#{policy_id}",
+        request_body: request_body
+      )
+    end
+
+    # Delete a policy.
+    #
+    # @param policy_id [String] The id of the policy to delete.
+    # @return [Array(TrueClass, String)] True and the API Request ID for the delete operation.
+    def destroy(policy_id:)
+      _, request_id = delete(
+        path: "#{api_uri}/v3/policies/#{policy_id}"
+      )
+
+      [true, request_id]
+    end
+  end
+end

data/lib/nylas/resources/redirect_uris.rb

@@ -8,7 +8,7 @@ module Nylas
   class RedirectUris < Resource
     include ApiOperations::Get
     include ApiOperations::Post
-    include ApiOperations::Put
+    include ApiOperations::Patch
     include ApiOperations::Delete
 
     # Return all redirect uris.
@@ -47,7 +47,7 @@ module Nylas
     # @param request_body [Hash] The values to update the redirect uri with
     # @return [Array(Hash, String)] The updated redirect uri and API Request ID.
     def update(redirect_uri_id:, request_body:)
-      put(
+      patch(
         path: "#{api_uri}/v3/applications/redirect-uris/#{redirect_uri_id}",
         request_body: request_body
       )

data/lib/nylas/resources/rules.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/api_operations"
+
+module Nylas
+  # Module representing the possible 'trigger' values for a Rule.
+  module RuleTrigger
+    INBOUND = "inbound"
+    OUTBOUND = "outbound"
+  end
+
+  # Module representing the possible 'match.operator' values for a Rule.
+  module RuleMatchOperator
+    ANY = "any"
+    ALL = "all"
+  end
+
+  # Module representing the possible condition 'field' values for a Rule.
+  module RuleConditionField
+    FROM_ADDRESS = "from.address"
+    FROM_DOMAIN = "from.domain"
+    FROM_TLD = "from.tld"
+    RECIPIENT_ADDRESS = "recipient.address"
+    RECIPIENT_DOMAIN = "recipient.domain"
+    RECIPIENT_TLD = "recipient.tld"
+    OUTBOUND_TYPE = "outbound.type"
+  end
+
+  # Module representing the possible condition 'operator' values for a Rule.
+  module RuleConditionOperator
+    IS = "is"
+    IS_NOT = "is_not"
+    CONTAINS = "contains"
+    IN_LIST = "in_list"
+  end
+
+  # Module representing the possible 'outbound.type' condition values for a Rule.
+  module RuleOutboundType
+    COMPOSE = "compose"
+    REPLY = "reply"
+  end
+
+  # Module representing the possible action 'type' values for a Rule.
+  module RuleActionType
+    BLOCK = "block"
+    MARK_AS_SPAM = "mark_as_spam"
+    ASSIGN_TO_FOLDER = "assign_to_folder"
+    MARK_AS_READ = "mark_as_read"
+    MARK_AS_STARRED = "mark_as_starred"
+    ARCHIVE = "archive"
+    TRASH = "trash"
+  end
+
+  # Module representing the possible 'evaluation_stage' values in a rule evaluation.
+  module RuleEvaluationStage
+    SMTP_RCPT = "smtp_rcpt"
+    INBOX_PROCESSING = "inbox_processing"
+    OUTBOUND_SEND = "outbound_send"
+  end
+
+  # Nylas Rules API
+  class Rules < Resource
+    include ApiOperations::Get
+    include ApiOperations::Post
+    include ApiOperations::Put
+    include ApiOperations::Delete
+
+    # Return all rules.
+    #
+    # The list endpoint returns a nested envelope
+    # ({ request_id, data: { items: [...], next_cursor } }), so the items and
+    # cursor are unwrapped here defensively rather than via the standard
+    # get_list helper, which would mis-read the nested shape.
+    #
+    # @param query_params [Hash, nil] Query params to pass to the request.
+    # @return [Array(Array(Hash), String, String, Hash)]
+    #   The list of rules, API Request ID, next cursor, and response headers.
+    def list(query_params: nil)
+      response = get_raw(
+        path: "#{api_uri}/v3/rules",
+        query_params: query_params
+      )
+
+      data = response[:data]
+      # Unwrap only when the envelope actually carries an :items key. Go's
+      # ListWithCursorResult serializes a nil slice as "items": null, so coerce
+      # that to [] rather than falling back to the envelope hash itself.
+      items = if data.is_a?(Hash) && data.key?(:items)
+                data[:items] || []
+              else
+                data
+              end
+      next_cursor = data.is_a?(Hash) ? data[:next_cursor] : response[:next_cursor]
+
+      [items, response[:request_id], next_cursor, response[:headers]]
+    end
+
+    # Return a rule.
+    #
+    # @param rule_id [String] The id of the rule to return.
+    # @return [Array(Hash, String, Hash)] The rule, API request ID, and response headers.
+    def find(rule_id:)
+      get(
+        path: "#{api_uri}/v3/rules/#{rule_id}"
+      )
+    end
+
+    # Create a rule.
+    #
+    # @param request_body [Hash] The values to create the rule with.
+    # @return [Array(Hash, String)] The created rule and API Request ID.
+    def create(request_body:)
+      post(
+        path: "#{api_uri}/v3/rules",
+        request_body: request_body
+      )
+    end
+
+    # Update a rule. Only the provided fields are changed (partial update).
+    #
+    # @param rule_id [String] The id of the rule to update.
+    # @param request_body [Hash] The values to update the rule with.
+    # @return [Array(Hash, String)] The updated rule and API Request ID.
+    def update(rule_id:, request_body:)
+      put(
+        path: "#{api_uri}/v3/rules/#{rule_id}",
+        request_body: request_body
+      )
+    end
+
+    # Delete a rule.
+    #
+    # @param rule_id [String] The id of the rule to delete.
+    # @return [Array(TrueClass, String)] True and the API Request ID for the delete operation.
+    def destroy(rule_id:)
+      _, request_id = delete(
+        path: "#{api_uri}/v3/rules/#{rule_id}"
+      )
+
+      [true, request_id]
+    end
+
+    # Return all rule evaluations for a grant.
+    #
+    # This endpoint returns a flat array with no cursor, so the standard
+    # get_list helper is used (next_cursor is always nil).
+    #
+    # @param grant_id [String] The id of the grant to query rule evaluations for.
+    # @param query_params [Hash, nil] Query params to pass to the request.
+    # @return [Array(Array(Hash), String, String, Hash)]
+    #   The list of rule evaluations, API Request ID, next cursor (always nil
+    #   for this endpoint), and response headers.
+    def list_evaluations(grant_id:, query_params: nil)
+      get_list(
+        path: "#{api_uri}/v3/grants/#{grant_id}/rule-evaluations",
+        query_params: query_params
+      )
+    end
+  end
+end

data/lib/nylas/resources/webhooks.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "cgi"
 require_relative "resource"
 require_relative "../handler/api_operations"
 
@@ -115,14 +114,14 @@ module Nylas
     # @return [String] The challenge parameter
     def self.extract_challenge_parameter(url)
       url_object = URI.parse(url)
-      query = CGI.parse(url_object.query || "")
+      params = URI.decode_www_form(url_object.query || "")
+      challenge_pair = params.find { |k, _| k == "challenge" }
 
-      challenge_parameter = query["challenge"]
-      if challenge_parameter.nil? || challenge_parameter.empty? || challenge_parameter.first.nil?
+      if challenge_pair.nil? || challenge_pair.last.to_s.empty?
         raise "Invalid URL or no challenge parameter found."
       end
 
-      challenge_parameter.first
+      challenge_pair.last
     end
   end
 end