nextmail 0.0.1

data/lib/nextmail/languages.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Nextmail
+  module Languages
+    module_function
+
+    def key(value)
+      value.to_s.strip.downcase
+    end
+
+    BY_CODE = LANGUAGES.to_h { |language| [key(language[:code]), language] }.freeze
+    BY_LABEL = LANGUAGES.to_h { |language| [key(language[:label]), language] }.freeze
+    BY_NATIVE = LANGUAGES.to_h { |language| [key(language[:native]), language] }.freeze
+    ALIASES = Protocol::LANGUAGE_ALIASES.to_h { |(name, code)| [key(name), key(code)] }.freeze
+
+    def by_code(code)
+      return nil if code.nil? || code == ""
+
+      BY_CODE[key(code)]
+    end
+
+    def resolve(input)
+      return nil if input.nil? || input == ""
+
+      wanted = key(input)
+      return nil if wanted.empty?
+      return BY_CODE[ALIASES[wanted]] if ALIASES.key?(wanted)
+
+      direct = BY_CODE[wanted] || BY_LABEL[wanted] || BY_NATIVE[wanted]
+      return direct if direct
+
+      base = wanted.split(Defaults::LANGUAGE_SUBTAG_PATTERN).first
+      return nil if base.nil? || base.empty? || base == wanted
+
+      BY_CODE[ALIASES.fetch(base, base)]
+    end
+
+    def rtl?(code)
+      resolve(code)&.fetch(:rtl, false) == true
+    end
+  end
+end

data/lib/nextmail/pagination.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Nextmail
+  module Pagination
+    CURSOR = Protocol::CURSOR_STYLES[:CURSOR]
+    PAGE_TOKEN = Protocol::CURSOR_STYLES[:PAGE_TOKEN]
+
+    module_function
+
+    def fetch_page(transport, path, query: nil, style: CURSOR, limit: nil, cursor: nil, api_key: nil)
+      payload = transport.request(path, query: page_query(query, style, limit, cursor), api_key:)
+      envelope = payload.is_a?(Hash) ? payload : {}
+      next_cursor = cursor_of(envelope[style[:FIELD].to_sym])
+
+      Page.new(items: items_of(envelope), has_more: more?(envelope, next_cursor), next_cursor:)
+    end
+
+    def iterate(transport, path, query: nil, style: CURSOR, limit: nil, cursor: nil, api_key: nil)
+      walk(cursor) { |current| fetch_page(transport, path, query:, style:, limit:, cursor: current, api_key:) }
+    end
+
+    def collect_all(transport, path, **options)
+      iterate(transport, path, **options).to_a
+    end
+
+    def fetch_list(transport, path, query: nil, api_key: nil)
+      payload = transport.request(path, query:, api_key:)
+      items_of(payload.is_a?(Hash) ? payload : {})
+    end
+
+    def walk(cursor, &fetch)
+      Enumerator.new do |yielder|
+        current = cursor
+
+        loop do
+          page = fetch.call(current)
+          page.items.each { |item| yielder << item }
+
+          break if !page.has_more || page.next_cursor.nil? || page.next_cursor == current
+
+          current = page.next_cursor
+        end
+      end
+    end
+
+    def page_query(query, style, limit, cursor)
+      (query || {}).merge(Protocol::QUERY_KEYS[:LIMIT] => limit, style[:PARAM] => cursor)
+    end
+
+    def items_of(envelope)
+      envelope[:data].is_a?(Array) ? envelope[:data] : []
+    end
+
+    def more?(envelope, next_cursor)
+      flag = envelope[:hasMore]
+      (flag == true || flag == false) ? flag : !next_cursor.nil?
+    end
+
+    def cursor_of(value)
+      (value.is_a?(String) && !value.empty?) ? value : nil
+    end
+  end
+end

data/lib/nextmail/protocol.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Nextmail
+  module Protocol
+    ACCESS_TOKEN_RULES = {RESERVED_PREFIX: "nm_", MAX_LENGTH: 512}.freeze
+
+    API_KEY_MODES = {LIVE: "live", TEST: "test"}.freeze
+
+    API_KEY_PREFIXES = {LIVE: "nm_live_", TEST: "nm_test_"}.freeze
+
+    CONTENT_TYPES = {
+      JSON: "application/json",
+      CALENDAR: "text/calendar",
+      VCARD: "text/vcard",
+      OCTET_STREAM: "application/octet-stream"
+    }.freeze
+
+    CURSOR_STYLES = {
+      CURSOR: {PARAM: "cursor", FIELD: "nextCursor"}.freeze,
+      PAGE_TOKEN: {PARAM: "pageToken", FIELD: "nextPageToken"}.freeze
+    }.freeze
+
+    ENV_VARS = {
+      API_KEY: "NEXTMAIL_API_KEY",
+      ACCESS_TOKEN: "NEXTMAIL_ACCESS_TOKEN",
+      BASE_URL: "NEXTMAIL_BASE_URL"
+    }.freeze
+
+    ERROR_CODES = {
+      INSUFFICIENT_SCOPE: "insufficient_scope",
+      CONSOLE_ONLY: "console_only",
+      UNRECOGNISED_RESPONSE: "unrecognised_response"
+    }.freeze
+
+    ERROR_TYPE_BY_STATUS = {
+      401 => "authentication_error",
+      403 => "permission_error",
+      404 => "not_found_error",
+      409 => "conflict_error",
+      422 => "validation_error",
+      429 => "rate_limit_error"
+    }.freeze
+
+    HEADER_KEYS = {
+      AUTHORIZATION: "Authorization",
+      ACCEPT: "Accept",
+      CONTENT_TYPE: "Content-Type",
+      USER_AGENT: "User-Agent",
+      IDEMPOTENCY_KEY: "Idempotency-Key",
+      RETRY_AFTER: "retry-after",
+      REQUEST_ID: "x-request-id"
+    }.freeze
+
+    HTTP_METHODS = {GET: "GET", POST: "POST", PUT: "PUT", PATCH: "PATCH", DELETE: "DELETE"}.freeze
+
+    IDEMPOTENCY_KEY_PREFIX = "nm-"
+
+    IMAGE_CROP_DECIMALS = 6
+
+    IMAGE_CROP_SEPARATOR = ","
+
+    LANGUAGE_ALIASES = [
+      ["zh", "zh-Hans"].freeze,
+      ["zh-cn", "zh-Hans"].freeze,
+      ["zh-sg", "zh-Hans"].freeze,
+      ["cmn", "zh-Hans"].freeze,
+      ["zh-tw", "zh-Hant"].freeze,
+      ["zh-mo", "zh-HK"].freeze,
+      ["iw", "he"].freeze,
+      ["in", "id"].freeze,
+      ["ji", "yi"].freeze,
+      ["mo", "ro"].freeze,
+      ["sh", "sr-Latn"].freeze,
+      ["sr-latn-rs", "sr-Latn"].freeze,
+      ["prs", "fa-AF"].freeze,
+      ["fa-af", "fa-AF"].freeze,
+      ["kmr", "ku"].freeze,
+      ["pt-pt", "pt"].freeze,
+      ["es-mx", "es-419"].freeze,
+      ["es-ar", "es-419"].freeze,
+      ["es-co", "es-419"].freeze,
+      ["es-cl", "es-419"].freeze
+    ].freeze
+
+    LIST_SEPARATOR = ","
+
+    LOCAL_HOSTS = ["localhost", "::1", "[::1]", "127.0.0.1", "0.0.0.0", "::", "[::]"].freeze
+
+    LOOPBACK_HOSTNAMES = ["localhost", "::1", "[::1]"].freeze
+
+    LOOPBACK_IPV4_ADDRESS = "127.0.0.1"
+
+    LOOPBACK_IPV6_ADDRESS = "[::1]"
+
+    QUERY_KEYS = {
+      LIMIT: "limit",
+      CURSOR: "cursor",
+      STATUS: "status",
+      FROM: "from",
+      TO: "to",
+      TIMEZONE: "timezone",
+      ENABLED: "enabled",
+      RULE_ID: "ruleId",
+      THREAD_ID: "threadId",
+      FOLDER: "folder",
+      QUERY: "query",
+      LABEL_IDS: "labelIds",
+      OPENED: "opened",
+      CLICKED: "clicked",
+      DAYS: "days",
+      MINUTES: "minutes",
+      GRAIN: "grain",
+      OFFSET_MINUTES: "offsetMinutes",
+      INCLUDE_MACHINE: "includeMachine",
+      REASSIGN_TO: "reassignTo",
+      SOURCE: "source",
+      ADDRESS: "address",
+      DIRECTION: "direction",
+      FILTER: "filter",
+      SEARCH: "search",
+      SORT: "sort",
+      PAGE: "page",
+      PAGE_SIZE: "pageSize",
+      VERSION: "version",
+      TRACKED: "tracked",
+      Q: "q",
+      AUDIENCE_IDS: "audienceIds",
+      AUDIENCE_ID: "audienceId",
+      BROADCAST_ID: "broadcastId",
+      BROADCAST_IDS: "broadcastIds",
+      EMAIL: "email",
+      WITHOUT_EMAIL: "withoutEmail",
+      BLOCKED: "blocked",
+      DATE_FROM: "dateFrom",
+      DATE_TO: "dateTo",
+      FROM_CONTACTS: "fromContacts",
+      SEMANTIC: "semantic",
+      REASON: "reason",
+      KIND: "kind",
+      ENDPOINT_IDS: "endpointIds",
+      KEY_IDS: "keyIds",
+      RULE_IDS: "ruleIds",
+      SINCE: "since",
+      UNTIL: "until",
+      FAILED_ONLY: "failedOnly",
+      FILENAME: "filename",
+      DOMAIN: "domain",
+      SCHEDULED_FROM: "scheduledFrom",
+      SCHEDULED_TO: "scheduledTo",
+      ADDRESSES: "addresses",
+      OFFSET: "offset",
+      REFRESH: "refresh",
+      CONFIRM: "confirm",
+      USERNAME: "username",
+      SCOPE: "scope",
+      LEVEL: "level",
+      PINNED: "pinned",
+      TITLE: "title",
+      ITEM_ID: "itemId",
+      SENDS: "sends",
+      DOMAINS: "domains",
+      PEOPLE: "people",
+      AI_ACTIONS: "aiActions",
+      INTERVAL: "interval",
+      CATEGORY: "category",
+      DEEP: "deep",
+      PATH: "path",
+      STEP_KEY: "stepKey",
+      NAME: "name",
+      CONNECTED_APPS: "connectedApps",
+      TASK_ID: "taskId",
+      RUN_ID: "runId",
+      VIEW: "view",
+      PAGE_ID: "pageId",
+      DURATION_MINUTES: "durationMinutes",
+      APP: "app",
+      CONNECTOR_ID: "connectorId",
+      INCLUDE_TEAM: "includeTeam",
+      EMAILS: "emails",
+      OCCURRENCE_START: "occurrenceStart",
+      AUTOMATION_IDS: "automationIds",
+      EVENT: "event",
+      OUTCOME: "outcome",
+      TAG: "tag",
+      RECIPIENT: "recipient",
+      GROUP_ID: "groupId",
+      PAGE_IDS: "pageIds",
+      BOOKING_ID: "bookingId",
+      SUGGESTED: "suggested",
+      CROP: "crop",
+      ORDER: "order",
+      INCLUDE_REVOKED: "includeRevoked",
+      START_INDEX: "startIndex",
+      COUNT: "count",
+      HIDE_LABELLED: "hideLabelled",
+      INACTIVE_DAYS: "inactiveDays",
+      MESSAGE_ID: "messageId"
+    }.freeze
+
+    RETRY = {
+      STATUSES: [408, 429, 500, 502, 503, 504].freeze,
+      METHODS: ["GET"].freeze,
+      BASE_BACKOFF_MS: 500,
+      MAX_BACKOFF_MS: 8000,
+      MAX_HONOURED_RETRY_AFTER_MS: 60000,
+      RATE_LIMIT_STATUS: 429
+    }.freeze
+
+    SEALED_ENCRYPTION_FORMATS = ["pgp-mime", "pgp-inline", "smime-encrypted"].freeze
+
+    UNSPECIFIED_HOSTNAMES = ["0.0.0.0", "::", "[::]"].freeze
+
+    WEBHOOK_SIGNATURE = {
+      VERSION: "v1",
+      TIMESTAMP: "t",
+      PAIR_SEPARATOR: ",",
+      VALUE_SEPARATOR: "=",
+      TOLERANCE_SECONDS: 300
+    }.freeze
+  end
+end

data/lib/nextmail/raw_body.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Nextmail
+  module RawBody
+    module_function
+
+    def read(data)
+      case data
+      when String then data
+      when Pathname then File.binread(data)
+      else read_stream(data)
+      end
+    end
+
+    def size(data)
+      case data
+      when String then data.bytesize
+      when Pathname then File.size(data)
+      else stream_size(data)
+      end
+    end
+
+    def slice(data, offset, length)
+      case data
+      when String then data.byteslice(offset, length)
+      when Pathname then File.open(data, "rb") { |file| stream_slice(file, offset, length) }
+      else stream_slice(data, offset, length)
+      end
+    end
+
+    def content_type(data, explicit)
+      return explicit unless explicit.nil? || explicit.to_s.empty?
+
+      declared = data.respond_to?(:content_type) ? data.content_type : nil
+      return declared if declared.is_a?(String) && !declared.empty?
+
+      name = file_name(data)
+      Defaults::CONTENT_TYPES_BY_EXTENSION[File.extname(name).downcase] if name
+    end
+
+    def file_name(data)
+      return data.original_filename if data.respond_to?(:original_filename) && data.original_filename
+      return File.basename(data) if data.is_a?(Pathname)
+
+      File.basename(data.path) if data.respond_to?(:path) && data.path
+    end
+
+    def read_stream(data)
+      raise ArgumentError, Defaults::MESSAGES[:RAW_BODY_SHAPE] unless data.respond_to?(:read)
+
+      rewind(data)
+      data.read.to_s.b
+    end
+
+    def stream_size(data)
+      raise ArgumentError, Defaults::MESSAGES[:RAW_BODY_SHAPE] unless data.respond_to?(:read)
+      return data.size if data.respond_to?(:size)
+
+      data.stat.size
+    end
+
+    def stream_slice(data, offset, length)
+      raise ArgumentError, Defaults::MESSAGES[:RAW_BODY_SHAPE] unless data.respond_to?(:read)
+
+      position(data, offset)
+      data.read(length).to_s.b
+    end
+
+    def position(data, offset)
+      return data.seek(offset) if data.respond_to?(:seek)
+
+      rewind(data) if offset.zero?
+    rescue Errno::ESPIPE
+      nil
+    end
+
+    def rewind(data)
+      data.rewind if data.respond_to?(:rewind)
+    rescue Errno::ESPIPE
+      nil
+    end
+  end
+end

data/lib/nextmail/request_path.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Nextmail
+  module RequestPath
+    module_function
+
+    def fill(pattern, params)
+      values = params.transform_keys(&:to_s)
+
+      pattern.scan(Defaults::PATH_PARAM) { |(name)| assert_segment(values[name]) }
+
+      pattern
+        .gsub(Defaults::OPTIONAL_PATH_PARAM) { optional_segment(values[Regexp.last_match(1)]) }
+        .gsub(Defaults::PATH_PARAM) { encode(values[Regexp.last_match(1)]) }
+    end
+
+    def assert_segment(value)
+      text = segment_text(value)
+
+      raise ArgumentError, Defaults::MESSAGES[:EMPTY_SEGMENT] if text.nil? || text.empty?
+      raise ArgumentError, "#{text.inspect} #{Defaults::MESSAGES[:DOT_SEGMENT]}" if Defaults::DOT_SEGMENT.match?(text)
+    end
+
+    def segment_text(value)
+      case value
+      when String, Symbol then utf8(value.to_s)
+      when Numeric then Wire.number(value).to_s
+      end
+    end
+
+    def utf8(text)
+      converted = (text.encoding == Encoding::BINARY) ? text.dup.force_encoding(Encoding::UTF_8) : text.encode(Encoding::UTF_8)
+      raise ArgumentError, Defaults::MESSAGES[:SEGMENT_ENCODING] unless converted.valid_encoding?
+
+      converted
+    rescue EncodingError
+      raise ArgumentError, Defaults::MESSAGES[:SEGMENT_ENCODING]
+    end
+
+    def optional_segment(value)
+      (value.nil? || value == "") ? "" : "/#{encode(value)}"
+    end
+
+    def encode(value)
+      segment_text(value).to_s.gsub(Defaults::URI_COMPONENT_UNSAFE) do |character|
+        character.bytes.map { |byte| format("%%%02X", byte) }.join
+      end
+    end
+  end
+end

data/lib/nextmail/resource.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Nextmail
+  class Resource
+    CURSOR = Pagination::CURSOR
+    PAGE_TOKEN = Pagination::PAGE_TOKEN
+
+    def initialize(transport)
+      @transport = transport
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def request(path, **options)
+      @transport.request(path, **options)
+    end
+
+    def fill(pattern, **params)
+      RequestPath.fill(pattern, params)
+    end
+
+    def payload(body, fields)
+      Wire.body(body, fields)
+    end
+
+    def query_params(**values)
+      values.to_h { |name, value| [Protocol::QUERY_KEYS.fetch(name.to_s.upcase.to_sym), value] }
+    end
+
+    def joined(values)
+      Wire.collection?(values) ? Wire.list(values).join(Protocol::LIST_SEPARATOR) : values
+    end
+
+    def flag(value)
+      value&.to_s
+    end
+
+    def instant(value)
+      Wire.instant(value)
+    end
+
+    def log_window_query(since, until_value)
+      query_params(since: instant(since), until: instant(until_value))
+    end
+
+    def log_request_query(since, until_value, failed_only, statuses, path)
+      status = (statuses.nil? || statuses.empty?) ? nil : joined(statuses)
+      log_window_query(since, until_value).merge(query_params(failed_only: flag(failed_only), status:, path:))
+    end
+
+    def fetch_page(path, query = nil, style: CURSOR, limit: nil, cursor: nil, api_key: nil)
+      Pagination.fetch_page(@transport, path, query:, style:, limit:, cursor:, api_key:)
+    end
+
+    def iterate_pages(path, query = nil, style: CURSOR, limit: nil, cursor: nil, api_key: nil, &)
+      each_or_enumerator(Pagination.iterate(@transport, path, query:, style:, limit:, cursor:, api_key:), &)
+    end
+
+    def each_or_enumerator(enumerator, &block)
+      block ? enumerator.each(&block) : enumerator
+    end
+
+    def collect_all(path, query = nil, style: CURSOR, limit: nil, cursor: nil, api_key: nil)
+      iterate_pages(path, query, style:, limit:, cursor:, api_key:).to_a
+    end
+
+    def fetch_list(path, query = nil, api_key: nil)
+      Pagination.fetch_list(@transport, path, query:, api_key:)
+    end
+
+    def raw_content_type(data, content_type)
+      RawBody.content_type(data, content_type)
+    end
+
+    def crop_query(crop)
+      query_params(crop: ImageCrop.query(crop))
+    end
+
+    def upload_name(data, filename)
+      name = (filename.nil? ? RawBody.file_name(data) : filename).to_s.strip
+      raise ArgumentError, Defaults::MESSAGES[:FILENAME_REQUIRED] if name.empty?
+
+      name
+    end
+
+    def optional_upload_name(data, filename)
+      filename.nil? ? RawBody.file_name(data) : filename
+    end
+
+    def upload_timeout(timeout = nil)
+      at_least(Defaults::UPLOAD_TIMEOUT, timeout)
+    end
+
+    def turn_timeout(timeout = nil)
+      at_least(Defaults::CHAT_TURN_TIMEOUT, timeout)
+    end
+
+    def at_least(floor, timeout)
+      return timeout unless timeout.nil?
+
+      base = @transport.timeout
+      base.to_f.positive? ? [base, floor].max : base
+    end
+  end
+end