nylas 6.2.3 → 6.8.1

data/lib/nylas/handler/service_account_signer.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "securerandom"
+
+module Nylas
+  # Builds Nylas Service Account request signing headers for organization admin APIs.
+  #
+  # @see https://developer.nylas.com/docs/v3/auth/nylas-service-account/
+  class ServiceAccountSigner
+    NONCE_ALPHABET = ("a".."z").to_a.concat(("A".."Z").to_a, ("0".."9").to_a).freeze
+    DEFAULT_NONCE_LENGTH = 20
+    SIGNED_BODY_METHODS = %w[post put patch].freeze
+
+    attr_reader :private_key_id
+
+    # @param private_key_pem [String] RSA private key in PEM format.
+    # @param private_key_id [String] Value for the X-Nylas-Kid header.
+    def initialize(private_key_pem:, private_key_id:)
+      @private_key = self.class.load_rsa_private_key(private_key_pem)
+      @private_key_id = private_key_id
+    end
+
+    # Returns deterministic JSON with keys sorted at every object level and no extra whitespace.
+    #
+    # @param data [Hash, Array, String, Numeric, true, false, nil] Data to serialize.
+    # @return [String] Canonical JSON string.
+    def self.canonical_json(data)
+      JSON.generate(canonicalize(data))
+    end
+
+    # Loads an RSA private key from a PEM string.
+    #
+    # @param private_key_pem [String] RSA private key in PEM format.
+    # @return [OpenSSL::PKey::RSA]
+    def self.load_rsa_private_key(private_key_pem)
+      key = OpenSSL::PKey::RSA.new(private_key_pem)
+      raise ArgumentError, "Private key must be RSA private key" unless key.private?
+      raise ArgumentError, "Private key must be at least 2048 bits" if key.n.num_bits < 2048
+
+      key
+    rescue OpenSSL::PKey::PKeyError
+      raise ArgumentError, "Private key must be RSA PEM"
+    end
+
+    # Generates a cryptographically secure alphanumeric nonce.
+    #
+    # @param length [Integer] Length of the nonce to generate.
+    # @return [String] Generated nonce.
+    def self.generate_nonce(length = DEFAULT_NONCE_LENGTH)
+      Array.new(length) { NONCE_ALPHABET[SecureRandom.random_number(NONCE_ALPHABET.length)] }.join
+    end
+
+    # Builds signed headers and, for JSON body methods, the exact canonical body to send.
+    #
+    # @param method [String, Symbol] HTTP method.
+    # @param path [String] Relative request path, for example "/v3/admin/domains".
+    # @param body [Hash, nil] Request body for POST/PUT/PATCH requests.
+    # @param timestamp [Integer, nil] Optional Unix timestamp in seconds, mainly for tests.
+    # @param nonce [String, nil] Optional nonce, mainly for tests.
+    # @return [Array(Hash, String)] Signed headers and optional serialized JSON body.
+    def build_headers(method:, path:, body: nil, timestamp: nil, nonce: nil)
+      timestamp ||= Time.now.to_i
+      nonce ||= self.class.generate_nonce
+      method_value = method.to_s.downcase
+      serialized_body = nil
+
+      if SIGNED_BODY_METHODS.include?(method_value) && !body.nil?
+        serialized_body = self.class.canonical_json(body)
+      end
+
+      envelope = {
+        method: method_value,
+        nonce: nonce,
+        path: path,
+        timestamp: timestamp
+      }
+      envelope[:payload] = serialized_body if serialized_body
+
+      signature = @private_key.sign(OpenSSL::Digest.new("SHA256"), self.class.canonical_json(envelope))
+
+      [
+        {
+          "X-Nylas-Kid" => private_key_id,
+          "X-Nylas-Nonce" => nonce,
+          "X-Nylas-Timestamp" => timestamp.to_s,
+          "X-Nylas-Signature" => Base64.strict_encode64(signature)
+        },
+        serialized_body
+      ]
+    end
+
+    class << self
+      private
+
+      def canonicalize(value)
+        case value
+        when Hash
+          value.keys.sort_by(&:to_s).each_with_object({}) do |key, result|
+            result[key.to_s] = canonicalize(value[key])
+          end
+        when Array
+          value.map { |item| canonicalize(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/nylas/resources/applications.rb

@@ -8,6 +8,7 @@ module Nylas
   # Application
   class Applications < Resource
     include ApiOperations::Get
+    include ApiOperations::Patch
 
     attr_reader :redirect_uris
 
@@ -23,5 +24,18 @@ module Nylas
     def get_details
       get(path: "#{api_uri}/v3/applications")
     end
+
+    # Update application details.
+    #
+    # @param request_body [Hash] The values to update the application with. Include
+    #   +callback_uris+ entries with +id+ when preserving or updating existing
+    #   callback URIs.
+    # @return [Array(Hash, String)] The updated application details and API Request ID.
+    def update(request_body:)
+      patch(
+        path: "#{api_uri}/v3/applications",
+        request_body: request_body
+      )
+    end
   end
 end

data/lib/nylas/resources/bookings.rb

@@ -64,11 +64,13 @@ module Nylas
     # Delete a booking.
     # @param booking_id [String] The id of the booking to delete.
     # @param query_params [Hash, nil] Query params to pass to the request.
+    # @param request_body [Hash, nil] Optional body params (e.g. cancellation_reason).
     # @return [Array(TrueClass, String)] True and the API Request ID for the delete operation.
-    def destroy(booking_id:, query_params: nil)
+    def destroy(booking_id:, query_params: nil, request_body: nil)
       _, request_id = delete(
         path: "#{api_uri}/v3/scheduling/bookings/#{booking_id}",
-        query_params: query_params
+        query_params: query_params,
+        request_body: request_body
       )
 
       [true, request_id]

data/lib/nylas/resources/calendars.rb

@@ -39,6 +39,7 @@ module Nylas
     #
     # @param identifier [String] Grant ID or email account in which to create the object.
     # @param request_body [Hash] The values to create the calendar with.
+    #   This can include a `notetaker` object with settings and calendar sync rules for the Notetaker bot.
     # @return [Array(Hash, String)] The created calendar and API Request ID.
     def create(identifier:, request_body:)
       post(
@@ -52,7 +53,8 @@ module Nylas
     # @param identifier [String] Grant ID or email account in which to update an object.
     # @param calendar_id [String] The id of the calendar to update.
     #   Use "primary" to refer to the primary calendar associated with grant.
-    # @param request_body [Hash] The values to update the calendar with
+    # @param request_body [Hash] The values to update the calendar with.
+    #   This can include a `notetaker` object with settings and calendar sync rules for the Notetaker bot.
     # @return [Array(Hash, String)] The updated calendar and API Request ID.
     def update(identifier:, calendar_id:, request_body:)
       put(
@@ -88,8 +90,13 @@ module Nylas
 
     # Get the free/busy schedule for a list of email addresses.
     #
-    # @param identifier [str] The identifier of the grant to act upon.
-    # @param request_body [Hash] Request body to pass to the request.
+    # @param identifier [String] The identifier of the grant to act upon.
+    # @param request_body [Hash] Request body to pass to the request. Supported keys:
+    #   - `:start_time` [Integer] Unix timestamp for the start time to check free/busy for.
+    #   - `:end_time` [Integer] Unix timestamp for the end time to check free/busy for.
+    #   - `:emails` [Array<String>] List of email addresses to check free/busy for.
+    #   - `:tentative_as_busy` [Boolean, nil] When set to `false`, treats tentative calendar events as
+    #     `busy: false`. Only applicable for Microsoft and EWS calendar providers. Defaults to `true`.
     # @return [Array(Array(Hash), String)] The free/busy response.
     def get_free_busy(identifier:, request_body:)
       post(

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/events.rb

@@ -40,6 +40,7 @@ module Nylas
     #
     # @param identifier [String] Grant ID or email account in which to create the object.
     # @param request_body [Hash] The values to create the event with.
+    #   This can include a `notetaker` object with settings for the Notetaker bot.
     # @param query_params [Hash] The query parameters to include in the request.
     # @return [Array(Hash, String)] The created event and API Request ID.
     def create(identifier:, request_body:, query_params:)
@@ -54,7 +55,8 @@ module Nylas
     #
     # @param identifier [String] Grant ID or email account in which to update an object.
     # @param event_id [String] The id of the event to update.
-    # @param request_body [Hash] The values to update the event with
+    # @param request_body [Hash] The values to update the event with.
+    #   This can include a `notetaker` object with settings for the Notetaker bot.
     # @param query_params [Hash] The query parameters to include in the request
     # @return [Array(Hash, String)] The updated event and API Request ID.
     def update(identifier:, event_id:, request_body:, query_params:)
@@ -94,5 +96,19 @@ module Nylas
         request_body: request_body
       )
     end
+
+    # Returns a list of recurring events, recurring event exceptions, and single events
+    # from the specified calendar within a given time frame. This is useful when you
+    # want to import, store, and synchronize events from the time frame to your application
+    #
+    # @param identifier [String] Grant ID or email account to import events from.
+    # @param query_params [Hash] The query parameters to include in the request
+    # @return [(Array(Hash), String, String)] The list of events, API Request ID, and next cursor.
+    def list_import_events(identifier:, query_params:)
+      get_list(
+        path: "#{api_uri}/v3/grants/#{identifier}/events/import",
+        query_params: query_params
+      )
+    end
   end
 end

data/lib/nylas/resources/folders.rb

@@ -15,6 +15,11 @@ module Nylas
     #
     # @param identifier [String] Grant ID or email account to query.
     # @param query_params [Hash, nil] Query params to pass to the request.
+    #   Supported parameters include:
+    #   - single_level: (Boolean) For Microsoft accounts only. If true, retrieves folders from
+    #     a single-level hierarchy only. If false (default), retrieves folders across a
+    #     multi-level hierarchy.
+    #   - include_hidden_folders [Boolean] (Microsoft only) When true, includes hidden folders.
     # @return [Array(Array(Hash), String, String)] The list of folders, API Request ID, and next cursor.
     def list(identifier:, query_params: nil)
       get_list(

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/messages.rb

@@ -6,6 +6,19 @@ require_relative "../handler/api_operations"
 require_relative "../utils/file_utils"
 
 module Nylas
+  # Module representing the possible 'fields' values for Messages API requests.
+  # @see https://developer.nylas.com/docs/api/messages#get-/v3/grants/-identifier-/messages
+  module MessageFields
+    # Return the standard message payload (default)
+    STANDARD = "standard"
+    # Return messages and their custom headers
+    INCLUDE_HEADERS = "include_headers"
+    # Return messages and their tracking settings
+    INCLUDE_TRACKING_OPTIONS = "include_tracking_options"
+    # Return the grant_id, object, id, and raw_mime fields only
+    RAW_MIME = "raw_mime"
+  end
+
   # Nylas Messages API
   class Messages < Resource
     include ApiOperations::Get
@@ -26,6 +39,11 @@ module Nylas
     #
     # @param identifier [String] Grant ID or email account to query.
     # @param query_params [Hash, nil] Query params to pass to the request.
+    #   You can use the fields parameter to specify which data to return:
+    #   - MessageFields::STANDARD (default): Returns the standard message payload
+    #   - MessageFields::INCLUDE_HEADERS: Returns messages and their custom headers
+    #   - MessageFields::INCLUDE_TRACKING_OPTIONS: Returns messages and their tracking settings
+    #   - MessageFields::RAW_MIME: Returns the grant_id, object, id, and raw_mime fields only
     # @return [Array(Array(Hash), String, String)] The list of messages, API Request ID, and next cursor.
     def list(identifier:, query_params: nil)
       get_list(
@@ -39,6 +57,11 @@ module Nylas
     # @param identifier [String] Grant ID or email account to query.
     # @param message_id [String] The id of the message to return.
     # @param query_params [Hash, nil] Query params to pass to the request.
+    #   You can use the fields parameter to specify which data to return:
+    #   - MessageFields::STANDARD (default): Returns the standard message payload
+    #   - MessageFields::INCLUDE_HEADERS: Returns messages and their custom headers
+    #   - MessageFields::INCLUDE_TRACKING_OPTIONS: Returns messages and their tracking settings
+    #   - MessageFields::RAW_MIME: Returns the grant_id, object, id, and raw_mime fields only
     # @return [Array(Hash, String)] The message and API request ID.
     def find(identifier:, message_id:, query_params: nil)
       get(
@@ -103,7 +126,7 @@ module Nylas
         request_body: payload
       )
 
-      opened_files.each(&:close)
+      opened_files.each { |file| file.close if file.respond_to?(:close) }
 
       response
     end