nafru-email 0.1.1

data/lib/nafru_email/dev_outbox.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+require "time"
+
+module Nafru
+  module Email
+    module DevOutbox
+      module_function
+
+      # `dev_outbox` verilmezse: yalnız `NODE_ENV=development` iken `.nafru/emails`; aksi hâlde gerçek gönderim.
+      def resolve(dev_outbox)
+        return dev_outbox unless dev_outbox.nil?
+
+        ENV["NODE_ENV"] == "development" ? ".nafru/emails" : false
+      end
+
+      # E-postayı göndermeden `dir` altına `.txt` ve `.html` olarak yazar, yolu ve düz metni konsola basar.
+      def write(dir, input)
+        email = input.transform_keys(&:to_s)
+        now = Time.now.utc
+        id = "dev_#{(now.to_f * 1000).to_i.to_s(36)}#{SecureRandom.alphanumeric(6).downcase}"
+        base = File.expand_path("#{now.iso8601(3).tr(':.', '--')}-#{id}", dir)
+        headers = [
+          "From: #{email['from']}",
+          "To: #{list(email['to'])}",
+          email["cc"] && "Cc: #{list(email['cc'])}",
+          email["bcc"] && "Bcc: #{list(email['bcc'])}",
+          email["reply_to"] && "Reply-To: #{list(email['reply_to'])}",
+          "Subject: #{email['subject']}",
+          email["scheduled_at"] && "Scheduled-At: #{email['scheduled_at']}"
+        ].compact
+        body = body_text(email)
+        text = "#{headers.join("\n")}\n\n#{body}\n"
+        html = email["html"] || "<pre>#{escape_html(body)}</pre>"
+
+        FileUtils.mkdir_p(File.expand_path(dir))
+        File.write("#{base}.txt", text)
+        File.write("#{base}.html", html)
+        $stdout.puts "[nafru] dev: e-posta gönderilmedi\n  #{base}.txt\n  #{base}.html\n\n#{text}"
+        { id: id }
+      end
+
+      def list(value) = value.is_a?(Array) ? value.join(", ") : value.to_s
+
+      def escape_html(text) = text.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
+
+      # shortcut: kaba HTML→metin dönüşümü (etiket silme); yalnız dev önizlemesi için, gerçek gönderime girmez.
+      def html_to_text(html)
+        html.gsub(%r{<(style|script)[\s\S]*?</\1>}i, "")
+            .gsub(%r{<br\s*/?>|</(p|div|h[1-6]|li|tr)>}i, "\n")
+            .gsub(/<[^>]+>/, "")
+            .gsub("&nbsp;", " ").gsub("&lt;", "<").gsub("&gt;", ">").gsub("&quot;", '"').gsub("&amp;", "&")
+            .gsub(/\n{3,}/, "\n\n")
+            .strip
+      end
+
+      def body_text(email)
+        return email["text"] if email["text"] && !email["text"].empty?
+        return html_to_text(email["html"]) if email["html"] && !email["html"].empty?
+
+        template = email["template"]&.transform_keys(&:to_s)
+        return "" unless template
+
+        "[şablon #{template['id']}]\n#{JSON.pretty_generate(template['variables'] || {})}"
+      end
+    end
+  end
+end

data/lib/nafru_email/error.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Nafru
+  module Email
+    # Her başarısız çağrının fırlattığı hata. `status_code` ağ hatalarında `nil`'dır. `name`, sunucunun hata adıdır
+    # (`validation_error`, `rate_limit_exceeded`, `not_found`, …); ağ ve zaman aşımı için `application_error` / `timeout_error`.
+    class Error < StandardError
+      NAMES_BY_STATUS = {
+        400 => "invalid_request",
+        401 => "unauthorized",
+        403 => "forbidden",
+        404 => "not_found",
+        409 => "conflict",
+        413 => "payload_too_large",
+        422 => "validation_error",
+        429 => "rate_limit_exceeded"
+      }.freeze
+
+      # @return [Integer, nil]
+      attr_reader :status_code
+      # @return [String]
+      attr_reader :name
+      # @return [Array<Hash>, nil] 422'de alan ayrıntısı: `{ field:, message:, i18nTranslationKey: }`
+      attr_reader :errors
+      # @return [Numeric, nil] `429` yanıtındaki `retry-after` (saniye)
+      attr_reader :retry_after
+
+      def initialize(message, name:, status_code: nil, errors: nil, retry_after: nil)
+        super(message)
+        @name = name
+        @status_code = status_code
+        @errors = errors
+        @retry_after = retry_after
+      end
+
+      def to_h
+        { status_code: status_code, name: name, message: message, errors: errors, retry_after: retry_after }
+          .reject { |key, value| value.nil? && key != :status_code }
+      end
+
+      def self.network(message) = new(message, name: "application_error")
+
+      def self.timeout(seconds) = new("İstek #{seconds} sn içinde tamamlanmadı", name: "timeout_error")
+
+      # Standart gövde (`statusCode`, `name`, `message`, `errors`) yoksa durumdan makul bir hata kurar (ara katman HTML'i, boş gövde).
+      def self.parse(status, headers, body, reason = nil)
+        raw = headers["retry-after"]
+        retry_after = raw && Float(raw, exception: false)
+        retry_after = nil if retry_after&.negative?
+        retry_after = retry_after.to_i if retry_after && retry_after == retry_after.to_i
+        fallback = NAMES_BY_STATUS.fetch(status, "application_error")
+        unless body.is_a?(Hash) && body[:message].is_a?(String)
+          return new(reason.to_s.empty? ? "HTTP #{status}" : reason, name: fallback, status_code: status, retry_after: retry_after)
+        end
+
+        errors = body[:errors].is_a?(Array) ? body[:errors].grep(Hash).map { |entry| field_error(entry) } : []
+        new(
+          body[:message],
+          name: body[:name].is_a?(String) ? body[:name] : fallback,
+          status_code: body[:statusCode].is_a?(Integer) ? body[:statusCode] : status,
+          errors: errors.empty? ? nil : errors,
+          retry_after: retry_after
+        )
+      end
+
+      def self.field_error(entry)
+        error = {
+          field: entry[:field].is_a?(String) ? entry[:field] : "",
+          message: entry[:message].is_a?(String) ? entry[:message] : ""
+        }
+        error[:i18nTranslationKey] = entry[:i18nTranslationKey] if entry[:i18nTranslationKey].is_a?(String)
+        error
+      end
+      private_class_method :field_error
+    end
+  end
+end

data/lib/nafru_email/http.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "json"
+require "net/http"
+require "uri"
+
+module Nafru
+  module Email
+    # Taşıyıcının döndürdüğü yanıt. `headers` anahtarları küçük harf olmalıdır.
+    Response = Struct.new(:status, :headers, :body, :reason, keyword_init: true)
+
+    # Yanıt gövdesi üst sınırı: bozuk ya da kötü niyetli bir ara katman belleği tüketemesin.
+    MAX_RESPONSE_BYTES = 10 * 1024 * 1024
+
+    def self.response_too_large = Error.new("Yanıt gövdesi #{MAX_RESPONSE_BYTES} baytı aşıyor", name: "response_too_large")
+
+    # Varsayılan taşıyıcı (Net::HTTP). Özel taşıyıcı aynı imzayla `call` yanıtlayan herhangi bir nesnedir.
+    # Net::HTTP yönlendirme izlemez ve TLS sertifikasını doğrular (VERIFY_PEER); bunu kapatan bir seçenek yoktur.
+    # shortcut: her istek yeni bağlantı açar (keep-alive yok); yüksek hacimde kalıcı bağlantılı bir taşıyıcı verin.
+    NET_HTTP_TRANSPORT = lambda do |method:, url:, headers:, body:, timeout:|
+      uri = URI(url)
+      request = Net::HTTPGenericRequest.new(method, !body.nil?, true, uri.request_uri, headers)
+      request.body = body
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https",
+                                              open_timeout: timeout, read_timeout: timeout, write_timeout: timeout) do |conn|
+        conn.request(request) do |response|
+          buffer = +""
+          response.read_body do |chunk|
+            buffer << chunk
+            raise Email.response_too_large if buffer.bytesize > MAX_RESPONSE_BYTES
+          end
+          return Response.new(status: response.code.to_i, headers: response.each_header.to_h, body: buffer,
+                              reason: response.message)
+        end
+      end
+    end
+
+    # http yalnız geri döngü/yerel adreslerde serbest: düz metin üzerinde API anahtarı ve belirteç taşınmasın.
+    def self.require_https!(url, label)
+      uri = URI(url)
+      host = uri.hostname.to_s.downcase
+      local = host == "localhost" || host.end_with?(".localhost") || (begin
+        IPAddr.new(host).loopback?
+      rescue IPAddr::Error
+        false
+      end)
+      return if uri.scheme == "https" || (uri.scheme == "http" && local)
+
+      raise ArgumentError, "Nafru SDK: #{label} https kullanmalı (http yalnız localhost için)"
+    rescue URI::InvalidURIError
+      raise ArgumentError, "Nafru SDK: #{label} geçerli bir adres değil"
+    end
+
+    # `Http`, `Connect` vb. sırları (anahtar, belirteç) tutar: `inspect`/`pp` çıktısına girmesinler.
+    module Redacted
+      def inspect = "#<#{self.class.name} [REDACTED]>"
+      alias to_s inspect
+    end
+
+    # İstek katmanı: kimlik, yeniden deneme, zaman aşımı, hata ayrıştırma.
+    class Http
+      include Redacted
+
+      MAX_BACKOFF = 8.0
+      BASE_BACKOFF = 0.3
+
+      # @param authorize [#call, nil] verilirse `api_key` yerine her denemede bundan alınan belirteç kullanılır (`nil`: başlık yok).
+      def initialize(base_url:, api_key: nil, authorize: nil, transport: nil, max_retries: 2, timeout: 30, user_agent: nil)
+        Email.require_https!(base_url, "base_url")
+        @base = base_url.sub(%r{/+\z}, "")
+        @api_key = api_key
+        @authorize = authorize
+        @transport = transport || NET_HTTP_TRANSPORT
+        @max_retries = max_retries
+        @timeout = timeout
+        @user_agent = user_agent || "nafru-email-ruby/#{VERSION}"
+      end
+
+      def self.serialize_query(query)
+        pairs = (query || {}).reject { |_, value| value.nil? || value == "" }.map { |key, value| [key.to_s, value.to_s] }
+        pairs.empty? ? "" : "?#{URI.encode_www_form(pairs)}"
+      end
+
+      # Yol parçası: kimlik ya da e-posta (kişi uçları e-postayı kimlik gibi kabul eder) güvenle kaçırılır (encodeURIComponent).
+      # Boş, `.` ve `..` reddedilir: URL normalleştirmesi bunları başka bir uca çevirirdi.
+      def self.seg(value)
+        text = value.to_s
+        raise ArgumentError, "Nafru SDK: yol parçası boş, '.' ya da '..' olamaz" if ["", ".", ".."].include?(text)
+
+        text.b.gsub(%r{[^A-Za-z0-9\-_.!~*'()]}) { |char| format("%%%02X", char.ord) }
+      end
+
+      # @return [Object] ayrıştırılmış JSON (sembol anahtarlı) ya da boş gövdede `nil`
+      # @raise [Error]
+      def request(method, path, query: nil, body: nil, idempotency_key: nil)
+        headers = { "accept" => "application/json", "user-agent" => @user_agent }
+        headers["authorization"] = "Bearer #{@api_key}" unless @authorize
+        payload = nil
+        unless body.nil?
+          payload = JSON.generate(body)
+          headers["content-type"] = "application/json"
+        end
+        unless idempotency_key.nil?
+          # Başlık enjeksiyonu: CR/LF ya da başka denetim karakteri başlığa giremez.
+          if idempotency_key.to_s.empty? || idempotency_key.to_s.match?(/[[:cntrl:]]/)
+            raise ArgumentError, "Nafru SDK: idempotency_key boş olamaz ve denetim karakteri içeremez"
+          end
+
+          headers["idempotency-key"] = idempotency_key.to_s
+        end
+        url = "#{@base}#{path}#{self.class.serialize_query(query)}"
+        # `GET`/`DELETE` yinelenebilir; `POST`/`PATCH` yalnız 429'da ya da `Idempotency-Key` varsa: anahtarsız sunucu hatasında e-posta çift gidebilir.
+        safe = %w[GET DELETE].include?(method) || !idempotency_key.nil?
+
+        attempt = 0
+        loop do
+          if @authorize
+            token = @authorize.call
+            token.nil? ? headers.delete("authorization") : headers["authorization"] = "Bearer #{token}"
+          end
+          last = attempt >= @max_retries
+
+          begin
+            response = @transport.call(method: method, url: url, headers: headers.dup, body: payload, timeout: @timeout)
+          rescue Error
+            raise
+          rescue StandardError => e
+            if !last && safe
+              pause([BASE_BACKOFF * (2**attempt), MAX_BACKOFF].min)
+              attempt += 1
+              next
+            end
+            raise e.is_a?(Timeout::Error) ? Error.timeout(@timeout) : Error.network(e.message.to_s.empty? ? "Sunucuya ulaşılamadı" : e.message)
+          end
+
+          raise Email.response_too_large if response.body.to_s.bytesize > MAX_RESPONSE_BYTES
+
+          # API hiç yönlendirmez; izlemek `Authorization`'ı başka bir sunucuya sızdırabilir. Yeniden denenmez.
+          if response.status.between?(300, 399)
+            raise Error.new("Beklenmeyen yönlendirme (HTTP #{response.status}); izlenmedi", name: "unexpected_redirect",
+                                                                                            status_code: response.status)
+          end
+
+          response_headers = (response.headers || {}).transform_keys { |key| key.to_s.downcase }
+          warn_deprecated(response_headers)
+          data = parse_body(response.body)
+          return data if response.status.between?(200, 299)
+
+          error = Error.parse(response.status, response_headers, data, response.reason)
+          retryable = response.status == 429 || (response.status >= 500 && safe)
+          raise error unless retryable && !last
+
+          pause([error.retry_after || (BASE_BACKOFF * (2**attempt)), MAX_BACKOFF].min)
+          attempt += 1
+        end
+      end
+
+      private
+
+      def pause(seconds) = sleep(seconds)
+
+      # Sunucu bu SDK sürümünü kullanımdan kaldırdıysa istemci başına bir kez uyarır; çağrıyı asla bozmaz.
+      def warn_deprecated(headers)
+        return if @deprecation_warned || !headers.key?("deprecation")
+
+        @deprecation_warned = true
+        message = +"[nafru] Bu SDK sürümü (ruby #{VERSION}) kullanımdan kaldırıldı; lütfen güncelleyin."
+        message << " Son tarih: #{headers['sunset']}" if headers["sunset"]
+        link = headers["link"].to_s[/<([^>]+)>/, 1] || headers["link"]
+        message << " Ayrıntı: #{link}" if link && !link.empty?
+        warn message
+      end
+
+      def parse_body(text)
+        return nil if text.nil? || text.empty?
+
+        JSON.parse(text, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/nafru_email/pagination.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Nafru
+  module Email
+    # Bir liste çağrısını tüm sayfalar boyunca gezer (`after` imleci, en yeni önce sırasında ileri). Hata gelirse
+    # numaralandırıcı o hatayı fırlatır: sayfalama döngüsünde sessizce kesmek eksik veri okutur.
+    #
+    #   Nafru::Email.paginate(nafru.contacts.method(:list), limit: 100).each { |contact| ... }
+    #
+    # @param list [#call] sorgu Hash'i alıp liste zarfı (`{ object:, data:, has_more: }`) döndüren çağrı
+    # @return [Enumerator]
+    def self.paginate(list, query = {})
+      query = query.reject { |key, _| %w[after before].include?(key.to_s) }
+      Enumerator.new do |yielder|
+        after = nil
+        loop do
+          page = list.call(after ? query.merge(after: after) : query)
+          page[:data].each { |item| yielder << item }
+          break if !page[:has_more] || page[:data].empty?
+
+          after = page[:data].last[:id]
+        end
+      end
+    end
+  end
+end

data/lib/nafru_email/resources.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Nafru
+  module Email
+    # Kaynaklar `Http#request` ile konuşur. Girdi ve yanıt alanları API'deki gibi snake_case'tir; şekiller `sig/nafru_email.rbs`'te.
+    module Resources
+      # Ortak taban: `http` `request(method, path, query:, body:, idempotency_key:)` yanıtlayan nesnedir.
+      class Base
+        def initialize(http) = @http = http
+
+        private
+
+        def req(method, path, **options) = @http.request(method, path, **options)
+
+        def seg(value) = Http.seg(value)
+      end
+
+      class Emails < Base
+        def initialize(http, dev_outbox = false)
+          super(http)
+          @dev_outbox = dev_outbox
+        end
+
+        # `POST /emails`. `scheduled_at` verilirse zamanlanır; `idempotency_key` ile yineleme güvenlidir.
+        def send(input, idempotency_key: nil)
+          return DevOutbox.write(@dev_outbox, input) if @dev_outbox
+
+          req("POST", "/emails", body: input, idempotency_key: idempotency_key)
+        end
+
+        # `POST /emails/batch`: en çok 100 e-posta; ek ve şablon desteklenmez.
+        def batch(input, idempotency_key: nil)
+          return { data: input.map { |item| DevOutbox.write(@dev_outbox, item) } } if @dev_outbox
+
+          req("POST", "/emails/batch", body: input, idempotency_key: idempotency_key)
+        end
+
+        def get(id) = req("GET", "/emails/#{seg(id)}")
+        def list(query = {}) = req("GET", "/emails", query: query)
+        # Zamanlanmış e-postanın gönderim anını değiştirir.
+        def update(id, input) = req("PATCH", "/emails/#{seg(id)}", body: input)
+        # Zamanlanmış e-postayı iptal eder.
+        def cancel(id) = req("POST", "/emails/#{seg(id)}/cancel")
+      end
+
+      class Domains < Base
+        def create(input) = req("POST", "/domains", body: input)
+        def get(id) = req("GET", "/domains/#{seg(id)}")
+        def list(query = {}) = req("GET", "/domains", query: query)
+        def update(id, input) = req("PATCH", "/domains/#{seg(id)}", body: input)
+        def remove(id) = req("DELETE", "/domains/#{seg(id)}")
+        # DNS kayıtlarını denetletir; sonuç `get` ile okunur.
+        def verify(id) = req("POST", "/domains/#{seg(id)}/verify")
+      end
+
+      # Kişi uçlarında `id` yerine e-posta adresi de verilebilir.
+      class Contacts < Base
+        attr_reader :segments, :topics
+
+        def initialize(http)
+          super
+          @segments = ContactSegments.new(http)
+          @topics = ContactTopics.new(http)
+        end
+
+        def create(input) = req("POST", "/contacts", body: input)
+        def get(id_or_email) = req("GET", "/contacts/#{seg(id_or_email)}")
+        def list(query = {}) = req("GET", "/contacts", query: query)
+        def update(id_or_email, input) = req("PATCH", "/contacts/#{seg(id_or_email)}", body: input)
+        def remove(id_or_email) = req("DELETE", "/contacts/#{seg(id_or_email)}")
+      end
+
+      class ContactSegments < Base
+        def list(id_or_email, query = {}) = req("GET", "/contacts/#{seg(id_or_email)}/segments", query: query)
+        # Kişiyi statik segmente ekler (dinamik segmentte 422).
+        def add(id_or_email, segment_id) = req("POST", "/contacts/#{seg(id_or_email)}/segments/#{seg(segment_id)}")
+        def remove(id_or_email, segment_id) = req("DELETE", "/contacts/#{seg(id_or_email)}/segments/#{seg(segment_id)}")
+      end
+
+      class ContactTopics < Base
+        def list(id_or_email, query = {}) = req("GET", "/contacts/#{seg(id_or_email)}/topics", query: query)
+
+        # `input`: `{ topics: [{ id:, subscription: "opt_in" | "opt_out" }] }`. Sunucu gövdede çıplak dizi bekler.
+        def update(id_or_email, input)
+          req("PATCH", "/contacts/#{seg(id_or_email)}/topics", body: input[:topics] || input["topics"])
+        end
+      end
+
+      class ContactProperties < Base
+        def create(input) = req("POST", "/contact-properties", body: input)
+        def get(id) = req("GET", "/contact-properties/#{seg(id)}")
+        def list(query = {}) = req("GET", "/contact-properties", query: query)
+        def update(id, input) = req("PATCH", "/contact-properties/#{seg(id)}", body: input)
+        def remove(id) = req("DELETE", "/contact-properties/#{seg(id)}")
+      end
+
+      class Segments < Base
+        def create(input) = req("POST", "/segments", body: input)
+        def get(id) = req("GET", "/segments/#{seg(id)}")
+        def list(query = {}) = req("GET", "/segments", query: query)
+        def remove(id) = req("DELETE", "/segments/#{seg(id)}")
+        # Segmentin kişileri; sayfalama kimlik sırasıyla, yalnız `after`.
+        def contacts(id, query = {}) = req("GET", "/segments/#{seg(id)}/contacts", query: query)
+      end
+
+      class Topics < Base
+        def create(input) = req("POST", "/topics", body: input)
+        def get(id) = req("GET", "/topics/#{seg(id)}")
+        def list(query = {}) = req("GET", "/topics", query: query)
+        def update(id, input) = req("PATCH", "/topics/#{seg(id)}", body: input)
+        def remove(id) = req("DELETE", "/topics/#{seg(id)}")
+      end
+
+      class Broadcasts < Base
+        # Taslak oluşturur; `send: true` ile aynı istekte gönderir.
+        def create(input) = req("POST", "/broadcasts", body: input)
+        def get(id) = req("GET", "/broadcasts/#{seg(id)}")
+        def list(query = {}) = req("GET", "/broadcasts", query: query)
+        # Yalnız taslakta (aksi 409).
+        def update(id, input) = req("PATCH", "/broadcasts/#{seg(id)}", body: input)
+        # Yalnız taslakta (aksi 409).
+        def remove(id) = req("DELETE", "/broadcasts/#{seg(id)}")
+        def send(id, input = {}) = req("POST", "/broadcasts/#{seg(id)}/send", body: input)
+        def cancel(id) = req("POST", "/broadcasts/#{seg(id)}/cancel")
+      end
+
+      # `id_or_alias`: kimlik ya da takma ad.
+      class Templates < Base
+        def create(input) = req("POST", "/templates", body: input)
+        def get(id_or_alias) = req("GET", "/templates/#{seg(id_or_alias)}")
+        def list(query = {}) = req("GET", "/templates", query: query)
+        # Taslağı kaydeder; yayımlanana kadar gönderimler eski sürümü kullanır.
+        def update(id_or_alias, input) = req("PATCH", "/templates/#{seg(id_or_alias)}", body: input)
+        def remove(id_or_alias) = req("DELETE", "/templates/#{seg(id_or_alias)}")
+        def publish(id_or_alias) = req("POST", "/templates/#{seg(id_or_alias)}/publish")
+        def duplicate(id_or_alias) = req("POST", "/templates/#{seg(id_or_alias)}/duplicate")
+
+        # Dil taslağını yazar; gönderimler bir sonraki yayından itibaren bu dili kullanır.
+        def put_translation(id_or_alias, locale, input)
+          req("PUT", "/templates/#{seg(id_or_alias)}/translations/#{seg(locale)}", body: input)
+        end
+
+        def remove_translation(id_or_alias, locale)
+          req("DELETE", "/templates/#{seg(id_or_alias)}/translations/#{seg(locale)}")
+        end
+      end
+
+      # Çalışma alanının markası: logo, renkler, yazı tipi, altbilgi. Şablonlar markayı `brand` alanıyla devralır.
+      class Brand < Base
+        def get = req("GET", "/brand")
+        # Markanın TAMAMINI değiştirir (gönderilmeyen alan "ayarlanmadı" olur).
+        def update(input) = req("PUT", "/brand", body: input)
+      end
+
+      class Webhooks < Base
+        # Yanıttaki `signing_secret` ile `Webhook.verify` kullanılır.
+        def create(input) = req("POST", "/webhooks", body: input)
+        def get(id) = req("GET", "/webhooks/#{seg(id)}")
+        def list(query = {}) = req("GET", "/webhooks", query: query)
+        def update(id, input) = req("PATCH", "/webhooks/#{seg(id)}", body: input)
+        def remove(id) = req("DELETE", "/webhooks/#{seg(id)}")
+      end
+
+      class ApiKeys < Base
+        def create(input) = req("POST", "/api-keys", body: input)
+        def list(query = {}) = req("GET", "/api-keys", query: query)
+        def remove(id) = req("DELETE", "/api-keys/#{seg(id)}")
+      end
+
+      # Otomasyonları tetikleyen özel olay API'si.
+      class Events < Base
+        def send(input, idempotency_key: nil) = req("POST", "/events", body: input, idempotency_key: idempotency_key)
+
+        # En çok 100 olay; biri geçersizse tüm istek 422.
+        def batch(input, idempotency_key: nil)
+          req("POST", "/events/batch", body: input, idempotency_key: idempotency_key)
+        end
+
+        def list(query = {}) = req("GET", "/events", query: query)
+      end
+    end
+  end
+end

data/lib/nafru_email/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Nafru
+  module Email
+    VERSION = "0.1.1"
+    SDK_VERSION = VERSION
+  end
+end

data/lib/nafru_email/webhook.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Nafru
+  module Email
+    # Svix / Standard Webhooks uyumlu imza doğrulama.
+    #
+    #   imzalanan  = "#{svix-id}.#{svix-timestamp}.#{ham gövde}"
+    #   anahtar    = `whsec_` sonrası base64 çözülmüş `signing_secret`
+    #   başlık     = `v1,<base64 HMAC-SHA256>` (anahtar döndürmede boşlukla ayrılmış birden çok imza)
+    module Webhook
+      SECRET_PREFIX = "whsec_"
+      DEFAULT_TOLERANCE_SECONDS = 300
+      # Bir başlıkta en çok bu kadar imza denenir: aşırı uzun başlıkla CPU tüketilmesin.
+      MAX_SIGNATURES = 32
+
+      module_function
+
+      # İmza ve zaman damgası geçerliyse `true`. Bozuk imza ya da zaman damgası `false`; bozuk `secret` ArgumentError fırlatır.
+      #
+      # @param payload [String] HAM istek gövdesi (bayt bayt; Rails'te `request.raw_post`): ayrıştırılıp yeniden dizilmiş JSON imzayı bozar.
+      # @param headers [Hash] `{ id:, timestamp:, signature: }` (`svix-id`, `svix-timestamp`, `svix-signature`)
+      # @param secret [String] webhook'un `signing_secret` değeri (`whsec_…`)
+      # @param now [Time, Numeric] şimdiki zaman (Time ya da Unix saniyesi); testler için
+      def verify(payload:, headers:, secret:, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: Time.now)
+        raise ArgumentError, "Geçersiz imza anahtarı: whsec_ ile başlamalı" unless secret.start_with?(SECRET_PREFIX)
+
+        key = begin
+          secret.delete_prefix(SECRET_PREFIX).unpack1("m0")
+        rescue ArgumentError
+          raise ArgumentError, "Geçersiz imza anahtarı: base64 çözülemedi"
+        end
+
+        id, timestamp, signature = (headers || {}).to_h.transform_keys(&:to_sym).values_at(:id, :timestamp, :signature).map(&:to_s)
+        return false if [id, timestamp, signature].any?(&:empty?)
+
+        # Fark mutlak değerle alınır: hem eski hem gelecekteki zaman damgası reddedilir.
+        stamp = Float(timestamp, exception: false)
+        return false if stamp.nil? || !stamp.finite? || (now.to_i - stamp).abs > tolerance_seconds
+
+        expected = OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{payload}")
+        signature.split(" ").first(MAX_SIGNATURES).any? do |candidate|
+          version, value = candidate.split(",", 2)
+          next false unless version == "v1" && value && !value.empty?
+
+          mac = begin
+            value.unpack1("m0")
+          rescue ArgumentError
+            next false
+          end
+          # Sabit zamanlı karşılaştırma (uzunluk gizli değil: HMAC-SHA256 hep 32 bayt).
+          mac.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(mac, expected)
+        end
+      end
+    end
+  end
+end

data/lib/nafru_email.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "nafru_email/version"
+require_relative "nafru_email/error"
+require_relative "nafru_email/http"
+require_relative "nafru_email/dev_outbox"
+require_relative "nafru_email/resources"
+require_relative "nafru_email/pagination"
+require_relative "nafru_email/webhook"
+require_relative "nafru_email/app"
+require_relative "nafru_email/client"
+