pushizo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f33d90710be708d8c1564539e767f76f570f49505122780696d768ad402b66b
+  data.tar.gz: 782a0f46dd24bb0248fa564180316575c2173f5b74115459a3ef494a5e249cd7
+SHA512:
+  metadata.gz: 1c674747a8637ae7cae4303f0b2125acda5317649b96004a890d02755160f77610852fd1ea481732e511746d5e60af579b30f0038d384d6e733f8f346cd3c066
+  data.tar.gz: 2fc0239d42ebc22d32a228ac235ec33b3d145ee88615844c2b33ae2ad5635ef42f64136884e9fef849b076a787deb546cbe5d417bb0d10660a19d03df11dd19a

data/README.md

@@ -0,0 +1,170 @@
+<!-- pushizo:header -->
+<p align="center">
+  <a href="https://pushizo.com"><img src="https://raw.githubusercontent.com/pushizo/.github/main/profile/assets/mark.svg" alt="Pushizo" width="56" height="56"></a>
+</p>
+<p align="center">
+  <a href="https://docs.pushizo.com/docs/sdk/ruby"><img src="https://img.shields.io/badge/docs-docs.pushizo.com-5b4bdb" alt="Docs"></a>
+  <a href="https://docs.pushizo.com/docs/api"><img src="https://img.shields.io/badge/API-reference-b44fc4" alt="API reference"></a>
+  <a href="https://github.com/pushizo/pushizo-ruby/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-16130f" alt="License: MIT"></a>
+</p>
+<p align="center"><a href="#english">English</a> · <a href="#türkçe">Türkçe</a></p>
+
+## English
+
+**Pushizo Ruby SDK** — Server-side SDK for Ruby. Models and resources are generated from the Pushizo OpenAPI schema; retries, idempotency, pagination and webhook verification are built in. Works with Rails.
+
+> **Status:** Publishing to RubyGems is in progress.<br>
+> **Durum:** RubyGems yayını hazırlanıyor.
+
+**Install from GitHub until then · O zamana kadar GitHub'dan kurulum:**
+
+```ruby
+# Gemfile
+gem "pushizo", git: "https://github.com/pushizo/pushizo-ruby", tag: "v0.1.0"
+```
+
+**After publication · Yayından sonra:**
+
+```bash
+gem install pushizo
+```
+
+The detailed guide below is in Turkish; code samples are language-neutral. Full documentation:
+[docs.pushizo.com/docs/sdk/ruby](https://docs.pushizo.com/docs/sdk/ruby) · API reference: [docs.pushizo.com/docs/api](https://docs.pushizo.com/docs/api).
+
+## Türkçe
+<!-- /pushizo:header -->
+
+# Pushizo Ruby SDK
+
+Pushizo public API'si için Ruby sunucu SDK'sı (Ruby 3.0+, `Net::HTTP`; çalışma zamanı bağımlılığı yok).
+Modeller ve kaynak metotları [Pushizo OpenAPI şemasından](https://github.com/pushizo/pushizo-openapi) üretilir (`lib/pushizo/generated/`); kimlik doğrulama,
+yeniden deneme, idempotency, sayfalama ve webhook imza doğrulaması el yazımıdır.
+
+## Kurulum
+
+```ruby
+# Gemfile
+gem "pushizo"
+```
+
+## Kullanım
+
+```ruby
+require "pushizo"
+
+hs = Pushizo::Client.new(api_key: ENV.fetch("HS_API_KEY"), app_id: "app_…") # yerelde base_url: "http://localhost:4000"
+
+# Bildirim gönder: Idempotency-Key verilmezse otomatik UUID (yeniden denemelerde aynı anahtar)
+res = hs.notifications.create(
+  {
+    target: { include_aliases: { external_id: ["user-42"] } },
+    contents: { en: "Your order shipped", tr: "Siparişiniz kargoya verildi" }
+  },
+  idempotency_key: "order-1001"
+)
+puts res.id, res.status
+
+# Kullanıcı oluştur/güncelle (Hash veya model nesnesi kabul edilir)
+hs.users.upsert(Pushizo::Models::UpsertUserDto.new(external_id: "user-42", tags: { plan: "pro" }))
+
+# Cursor sayfalama: Enumerator, sayfalar tembel yüklenir
+hs.segments.list_all(limit: 100).each { |segment| puts segment.name }
+
+# Başka bir app için tek çağrı
+hs.apps.get(app_id: "app_diger")
+
+# SDK identity verification
+identity_hash = Pushizo.identity_hash(ENV.fetch("HS_SDK_SECRET"), "user-42")
+```
+
+Yanıtlar `Pushizo::Models::*` nesneleridir: alanlara snake_case metotla (`msg.status`) veya `msg["status"]` ile
+erişilir, `to_h` JSON adlarıyla ham hash döner, bilinmeyen alanlar korunur. Ruby'nin `Object#send` yöntemiyle
+çakışmaması için `events.send` → `send_events`, `campaigns.send` → `send_campaign` olarak adlandırılmıştır.
+SDK'da metodu olmayan uçlar veya JSON dışı yanıtlar için
+`hs.request(:get, "/v1/apps/{appId}/analytics/messages", query: { format: "csv" })` kullanılabilir.
+
+### Ayarlar
+
+| Parametre | Varsayılan | Açıklama |
+|-----------|------------|----------|
+| `api_key:` | — | `hs_live_…` API anahtarı (Bearer) |
+| `app_id:` | `nil` | Çağrıda `app_id:` verilmezse kullanılan app |
+| `base_url:` | `https://api.pushizo.com` | API adresi |
+| `timeout:` | `30` | Deneme başına zaman aşımı (sn) |
+| `max_retries:` | `3` | En fazla yeniden deneme (politika: aşağıda) |
+| `auto_idempotency_key:` | `true` | `Idempotency-Key` destekleyen çağrılarda otomatik UUID |
+| `transport:` | `NetHttpTransport` | Özel taşıma (`#call(method, url, headers, body, timeout)`) |
+
+Her çağrı `request_options: { timeout: 5, max_retries: 0, headers: { … } }` ile ayrıca ayarlanabilir.
+
+### Hatalar
+
+429 her metotta; 5xx ve ağ hataları GET/HEAD/OPTIONS/PUT/DELETE'te, POST/PATCH'te yalnızca `Idempotency-Key` varsa (otomatik anahtar dahil) veya istek sunucuya hiç gönderilemediyse (bağlantı reddi, DNS hatası, bağlantı zaman aşımı) üstel geri çekilmeyle (0,3 / 1 / 3 sn) yeniden denenir; `Retry-After` başlığına uyulur.
+Kalıcı hatalar `Pushizo::Error` alt sınıflarıdır ve `status`, `code` (`HS_…`), `request_id`, `details` taşır:
+
+```ruby
+begin
+  hs.notifications.get("msg_yok")
+rescue Pushizo::NotFoundError
+  # 404
+rescue Pushizo::InvalidRequestError => e
+  # 400/422 — e.code == Pushizo::ErrorCode::NO_RECIPIENTS
+rescue Pushizo::Error => e
+  # AuthenticationError, PermissionDeniedError, ConflictError, RateLimitError, ServerError, NetworkError
+  warn "#{e.status} #{e.code} #{e.message}"
+end
+```
+
+## Webhook imza doğrulaması
+
+```ruby
+# Rails
+class PushizoWebhooksController < ActionController::API
+  def create
+    events = Pushizo::Webhook.construct_events(
+      request.raw_post,                               # ham gövde
+      request.headers["Pushizo-Signature"],
+      ENV.fetch("HS_WEBHOOK_SECRET")                  # rotasyonda [eski, yeni] verilebilir
+    )
+    events.each { |event| } # tekil veya batch; event["id"] ile tekrarları ayıklayın
+    head :no_content
+  rescue Pushizo::WebhookSignatureError => e
+    render plain: e.reason, status: :bad_request
+  end
+end
+```
+
+Zaman damgası 5 dakikadan eskiyse (`tolerance:`) istek tekrar (replay) sayılır. Yalnızca doğrulama için
+`Pushizo::Webhook.verify_signature(...)` `ok?`, `timestamp`, `reason` döner.
+
+## Geliştirme
+
+```bash
+rake test        # veya: ruby -Ilib -Itest -e 'Dir["test/test_*.rb"].each { |f| require_relative f }'
+node sdk/scripts/generate-server-sdks.mjs --lang ruby    # depo kökünde; generated/ yenilenir
+```
+
+`lib/pushizo/generated/` elle düzenlenmez. Webhook testleri `sdk/testdata/webhook-signature-vectors.json`
+ortak vektörlerini kullanır.
+
+<!-- pushizo:footer -->
+---
+
+## Support · Destek
+
+- **Guide · Rehber:** [docs.pushizo.com/docs/sdk/ruby](https://docs.pushizo.com/docs/sdk/ruby)
+- **API reference & OpenAPI · API referansı ve OpenAPI:** [docs.pushizo.com/docs/api](https://docs.pushizo.com/docs/api) ·
+  [pushizo-openapi](https://github.com/pushizo/pushizo-openapi)
+- **Bugs & ideas · Hata ve öneri:** [Issues](https://github.com/pushizo/pushizo-ruby/issues)
+- **Security · Güvenlik:** please do not open public issues; email [security@pushizo.com](mailto:security@pushizo.com) ·
+  herkese açık issue açmayın, bu adrese yazın.
+- **Help · Destek:** [support@pushizo.com](mailto:support@pushizo.com)
+
+This repository is mirrored automatically from the Pushizo main repository on every release. Please open an issue
+instead of a pull request; fixes land in the main repository and ship with the next release.
+Bu depo her sürümde Pushizo ana deposundan otomatik yansıtılır. Pull request yerine issue açın; düzeltmeler ana depoda
+yapılır ve bir sonraki sürümle buraya gelir.
+
+Released under the MIT License · MIT lisanslıdır — [LICENSE](https://github.com/pushizo/pushizo-ruby/blob/main/LICENSE).
+<!-- /pushizo:footer -->

data/lib/pushizo/base_resource.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Pushizo
+  # Üretilmiş kaynak sınıflarının tabanı.
+  class BaseResource
+    def initialize(client)
+      @client = client
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+  end
+end

data/lib/pushizo/client.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+require "openssl"
+require "securerandom"
+require "time"
+
+module Pushizo
+  # Pushizo API istemcisi. Kaynak erişimcileri (notifications, users, segments …) api/openapi.yaml'dan üretilir.
+  #
+  #   hs = Pushizo::Client.new(api_key: ENV.fetch("HS_API_KEY"), app_id: "app_…")
+  #   hs.segments.list_all(limit: 50).each { |segment| puts segment.name }
+  class Client
+    include GeneratedResources
+
+    DEFAULT_BASE_URL = "https://api.pushizo.com"
+    BACKOFF = [0.3, 1.0, 3.0].freeze
+    NETWORK_ERRORS = [
+      IOError, EOFError, SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError,
+      Net::OpenTimeout, Net::ReadTimeout, Net::HTTPBadResponse
+    ].freeze
+
+    # Sunucuda tekrarlanması ek yan etki doğurmayan HTTP metotları; 5xx ve ağ hatalarında serbestçe yeniden denenir.
+    IDEMPOTENT_METHODS = %w[GET HEAD OPTIONS PUT DELETE].freeze
+
+    # Bağlantı kurulmadan oluşan hatalar (DNS çözümlenemedi, bağlantı reddi, ağ/sunucu erişilemez, bağlantı zaman
+    # aşımı): istek sunucuya hiç gönderilmemiştir.
+    NOT_SENT_ERRORS = [
+      SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Net::OpenTimeout
+    ].freeze
+
+    attr_reader :app_id, :base_url
+
+    # api_key:: hs_live_… API anahtarı (Bearer).
+    # app_id:: Çağrılarda app_id: verilmezse kullanılacak varsayılan app.
+    # base_url:: API adresi; yerel geliştirmede http://localhost:4000.
+    # timeout:: Deneme başına zaman aşımı (sn).
+    # max_retries:: 429/5xx ve ağ hatalarında en fazla yeniden deneme.
+    # auto_idempotency_key:: Idempotency-Key destekleyen çağrılarda anahtar verilmezse UUID üret.
+    # transport:: Özel taşıma (#call); varsayılan NetHttpTransport.
+    # sleeper:: Yeniden deneme beklemesi (testlerde değiştirilebilir).
+    def initialize(api_key:, app_id: nil, base_url: DEFAULT_BASE_URL, timeout: 30, max_retries: 3,
+                   auto_idempotency_key: true, user_agent: nil, transport: nil, sleeper: nil)
+      raise ArgumentError, "Pushizo: api_key gerekli." if api_key.nil? || api_key.to_s.empty?
+
+      @api_key = api_key.to_s
+      @app_id = app_id
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = max_retries
+      @auto_idempotency_key = auto_idempotency_key
+      @user_agent = user_agent || "pushizo-ruby/#{VERSION}"
+      @transport = transport || NetHttpTransport.new
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+    end
+
+    # API anahtarı inspect çıktısında görünmez.
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect} app_id=#{@app_id.inspect}>"
+    end
+
+    # SDK identity verification için identity_hash = HMAC-SHA256(sdk_secret, external_id) (hex).
+    def self.identity_hash(sdk_secret, external_id)
+      Pushizo.identity_hash(sdk_secret, external_id)
+    end
+
+    # Düşük seviyeli istek (SDK'da metodu olmayan uçlar veya format=csv gibi JSON dışı yanıtlar için).
+    # path "/v1/…" biçimindedir; {appId} varsa app kimliğiyle doldurulur. JSON yanıt Hash, diğerleri String döner.
+    def request(method, path, query: nil, body: nil, app_id: nil, request_options: nil)
+      call(method, path, path_params: {}, query: query, body: body, app_id: app_id, request_options: request_options)
+    end
+
+    # İç API: üretilmiş kaynakların çağırdığı yürütücü.
+    def call(method, path, path_params: {}, query: nil, body: nil, form: nil, app_id: nil, query_app_id: false,
+             body_app_id: false, idempotent: false, idempotency_key: nil, response: nil, request_options: nil)
+      opts = request_options || {}
+      url_path = path.dup
+      url_path = url_path.gsub("{appId}", escape(resolve_app_id(app_id))) if url_path.include?("{appId}")
+      path_params.each do |name, value|
+        raise ArgumentError, "Pushizo: '#{name}' yol parametresi boş olamaz." if value.nil? || value.to_s.empty?
+
+        url_path = url_path.gsub("{#{name}}", escape(value.to_s))
+      end
+
+      items = []
+      items << ["app_id", resolve_app_id(app_id)] if query_app_id
+      (query || {}).each do |key, value|
+        next if value.nil?
+
+        Array(value.is_a?(Hash) ? [value] : value).each { |v| items << [key.to_s, scalar(v)] unless v.nil? }
+      end
+      url = "#{@base_url}#{url_path}"
+      url += "?#{items.map { |k, v| "#{escape(k)}=#{escape(v)}" }.join('&')}" unless items.empty?
+
+      key = idempotency_key || opts[:idempotency_key]
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => @user_agent
+      }
+      payload = nil
+      if form
+        boundary = "----pushizo#{SecureRandom.hex(16)}"
+        payload = multipart(form, boundary)
+        headers["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+      elsif !body.nil?
+        data = Types.serialize(body)
+        if data.is_a?(Hash)
+          data = data.merge("app_id" => resolve_app_id(app_id)) if body_app_id && data["app_id"].to_s.empty?
+          key ||= data["idempotency_key"] if idempotent && data["idempotency_key"].is_a?(String)
+        end
+        payload = JSON.generate(data)
+        headers["Content-Type"] = "application/json"
+      end
+      key = SecureRandom.uuid if (key.nil? || key.to_s.empty?) && idempotent && @auto_idempotency_key
+      headers["Idempotency-Key"] = key.to_s if key && !key.to_s.empty?
+      (opts[:headers] || {}).each { |k, v| headers[k.to_s] = v.to_s }
+
+      raw = send_with_retries(method, url, headers, payload, opts)
+      response ? Types.coerce(raw, response) : raw
+    end
+
+    # İç API: data / next_cursor / has_more zarfını sayfa sayfa dolaşan Enumerator.
+    def paginate(cursor)
+      Enumerator.new do |yielder|
+        next_cursor = cursor
+        loop do
+          page = yield(next_cursor)
+          data = page.is_a?(BaseModel) ? page["data"] : (page || {})["data"]
+          (data || []).each { |item| yielder << item }
+          next_cursor = page["next_cursor"]
+          break unless page["has_more"] && next_cursor && !next_cursor.to_s.empty?
+        end
+      end
+    end
+
+    private
+
+    def resolve_app_id(app_id)
+      id = app_id || @app_id
+      raise ArgumentError, "Pushizo: app_id verilmedi (istemci seçeneği veya çağrı parametresi)." if id.nil? || id.to_s.empty?
+
+      id.to_s
+    end
+
+    def escape(value)
+      ERB::Util.url_encode(value.to_s)
+    end
+
+    def scalar(value)
+      case value
+      when String then value
+      when Symbol then value.to_s
+      when true, false, Numeric then value.to_s
+      else JSON.generate(Types.serialize(value))
+      end
+    end
+
+    def send_with_retries(method, url, headers, payload, opts)
+      timeout = opts[:timeout] || @timeout
+      max_retries = opts.key?(:max_retries) ? opts[:max_retries] : @max_retries
+      has_key = headers.any? { |k, v| k.to_s.casecmp?("idempotency-key") && !v.to_s.empty? }
+      attempt = 0
+      loop do
+        error = nil
+        not_sent = false
+        begin
+          status, response_headers, response_body = @transport.call(method, url, headers, payload, timeout)
+          return parse_body(response_headers, response_body) if status.between?(200, 299)
+
+          error = error_from(status, response_headers, response_body)
+        rescue *NETWORK_ERRORS => e
+          error = NetworkError.new(0, ErrorCode::NETWORK, e.message.to_s.empty? ? e.class.name : e.message)
+          not_sent = NOT_SENT_ERRORS.any? { |klass| e.is_a?(klass) }
+        end
+        raise error if attempt >= max_retries || !retry?(method, error, has_key, not_sent)
+
+        delay = error.retry_after && error.retry_after.positive? ? error.retry_after : BACKOFF[[attempt, BACKOFF.size - 1].min]
+        @sleeper.call(delay)
+        attempt += 1
+      end
+    end
+
+    # Yeniden deneme politikası: 429 her metotta (istek işlenmeden reddedilmiştir); 5xx ve ağ hataları idempotent
+    # metotlarda, POST/PATCH'te yalnızca Idempotency-Key varsa ya da istek sunucuya hiç gönderilmediyse. Aksi hâlde
+    # sunucu isteği işlemiş olabilir ve tekrar çift kayıt üretebilir.
+    def retry?(method, error, has_idempotency_key, not_sent)
+      return true if error.status == 429
+      return false unless error.retryable?
+
+      IDEMPOTENT_METHODS.include?(method.to_s.upcase) || has_idempotency_key || not_sent
+    end
+
+    def parse_body(headers, body)
+      return nil if body.nil? || body.empty?
+
+      content_type = headers["content-type"].to_s
+      return body unless content_type.empty? || content_type.include?("json")
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def error_from(status, headers, body)
+      envelope = begin
+        parsed = JSON.parse(body.to_s)
+        parsed.is_a?(Hash) && parsed["error"].is_a?(Hash) ? parsed["error"] : {}
+      rescue JSON::ParserError
+        {}
+      end
+      details = envelope["details"].is_a?(Hash) ? envelope["details"] : nil
+      Error.class_for(status).new(
+        status,
+        (envelope["code"] || "HTTP_#{status}").to_s,
+        (envelope["message"] || "HTTP #{status}").to_s,
+        request_id: envelope["request_id"] || headers["x-request-id"],
+        details: details,
+        retry_after: parse_retry_after(headers["retry-after"])
+      )
+    end
+
+    # Retry-After: saniye veya HTTP tarihi.
+    def parse_retry_after(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      text = value.to_s.strip
+      if text.match?(/\A\d+(\.\d+)?\z/)
+        seconds = text.to_f
+        return seconds.positive? ? seconds : nil
+      end
+      delta = Time.httpdate(text) - Time.now
+      delta.positive? ? delta : nil
+    rescue ArgumentError
+      nil
+    end
+
+    def multipart(form, boundary)
+      out = +"".b
+      form.each do |name, value|
+        next if value.nil?
+
+        out << "--#{boundary}\r\n".b
+        if value.is_a?(FileUpload) || value.respond_to?(:read)
+          file = FileUpload.wrap(value)
+          out << "Content-Disposition: form-data; name=\"#{quote(name)}\"; filename=\"#{quote(file.filename)}\"\r\n".b
+          out << "Content-Type: #{file.content_type}\r\n\r\n".b
+          out << file.content
+        else
+          out << "Content-Disposition: form-data; name=\"#{quote(name)}\"\r\n\r\n".b
+          out << scalar(value).b
+        end
+        out << "\r\n".b
+      end
+      out << "--#{boundary}--\r\n".b
+      out
+    end
+
+    def quote(value)
+      value.to_s.gsub("\\", "\\\\\\\\").gsub('"', '\\"').delete("\r\n")
+    end
+  end
+end

data/lib/pushizo/errors.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Pushizo
+  # API hata zarfındaki error.code değerleri (HS_ önekli katalog).
+  module ErrorCode
+    VALIDATION_ERROR = "HS_VALIDATION_ERROR"
+    BAD_REQUEST = "HS_BAD_REQUEST"
+    UNAUTHENTICATED = "HS_UNAUTHENTICATED"
+    FORBIDDEN = "HS_FORBIDDEN"
+    TENANT_MISMATCH = "HS_TENANT_MISMATCH"
+    NOT_FOUND = "HS_NOT_FOUND"
+    CONFLICT = "HS_CONFLICT"
+    IDEMPOTENCY_CONFLICT = "HS_IDEMPOTENCY_CONFLICT"
+    IDEMPOTENCY_IN_PROGRESS = "HS_IDEMPOTENCY_IN_PROGRESS"
+    NO_RECIPIENTS = "HS_NO_RECIPIENTS"
+    CHANNEL_NOT_CONFIGURED = "HS_CHANNEL_NOT_CONFIGURED"
+    CONTENT_INVALID = "HS_CONTENT_INVALID"
+    SUBSCRIPTION_INVALID = "HS_SUBSCRIPTION_INVALID"
+    UNPROCESSABLE = "HS_UNPROCESSABLE"
+    RATE_LIMITED = "HS_RATE_LIMITED"
+    QUOTA_EXCEEDED = "HS_QUOTA_EXCEEDED"
+    INTERNAL = "HS_INTERNAL"
+    NOT_IMPLEMENTED = "HS_NOT_IMPLEMENTED"
+    PROVIDER_UNAVAILABLE = "HS_PROVIDER_UNAVAILABLE"
+    SERVICE_UNAVAILABLE = "HS_SERVICE_UNAVAILABLE"
+    # İstemci tarafı: bağlantı kurulamadı veya zaman aşımı (status 0).
+    NETWORK = "NETWORK"
+  end
+
+  # API hata zarfından ({"error": {"code", "message", "request_id", "details"}}) türetilen istisna.
+  # HTTP durumuna göre alt sınıflar fırlatılır (NotFoundError, RateLimitError …).
+  class Error < StandardError
+    attr_reader :status, :code, :request_id, :details, :retry_after
+
+    def initialize(status, code, message, request_id: nil, details: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @code = code
+      @request_id = request_id
+      @details = details
+      @retry_after = retry_after
+    end
+
+    # 429, 5xx veya ağ hatası: yeniden denenebilir.
+    def retryable?
+      status.zero? || status == 429 || status >= 500
+    end
+
+    def to_s
+      suffix = request_id ? " (request_id=#{request_id})" : ""
+      "[#{status} #{code}] #{super}#{suffix}"
+    end
+
+    # HTTP durumuna karşılık gelen sınıf.
+    def self.class_for(status)
+      case status
+      when 0 then NetworkError
+      when 400, 422 then InvalidRequestError
+      when 401 then AuthenticationError
+      when 403 then PermissionDeniedError
+      when 404 then NotFoundError
+      when 409 then ConflictError
+      when 429 then RateLimitError
+      else status >= 500 ? ServerError : Error
+      end
+    end
+  end
+
+  # Bağlantı kurulamadı veya zaman aşımı (status 0).
+  class NetworkError < Error; end
+  # 400 / 422: istek doğrulanamadı veya işlenemedi (details alan hatalarını içerir).
+  class InvalidRequestError < Error; end
+  # 401: API anahtarı eksik veya geçersiz.
+  class AuthenticationError < Error; end
+  # 403: anahtarın kapsamı yetersiz, IP izin listesi dışı veya kaynak başka kiracıya ait.
+  class PermissionDeniedError < Error; end
+  # 404: kaynak bulunamadı.
+  class NotFoundError < Error; end
+  # 409: kaynak çakışması veya idempotency anahtarı çakışması.
+  class ConflictError < Error; end
+  # 429: hız sınırı veya plan kotası aşıldı.
+  class RateLimitError < Error; end
+  # 5xx: sunucu veya sağlayıcı geçici olarak kullanılamıyor.
+  class ServerError < Error; end
+
+  # Webhook imzası geçersiz. reason: missing_header, malformed_header, timestamp_out_of_tolerance,
+  # signature_mismatch veya malformed_body.
+  class WebhookSignatureError < StandardError
+    attr_reader :reason
+
+    def initialize(reason)
+      super("Pushizo webhook imzası geçersiz: #{reason}")
+      @reason = reason
+    end
+  end
+end

data/lib/pushizo/file_upload.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pushizo
+  # Multipart dosya alanı. İçerik bellekte tutulur ki yeniden denemeler aynı gövdeyi göndersin.
+  class FileUpload
+    attr_reader :filename, :content, :content_type
+
+    def initialize(content, filename: "upload", content_type: nil)
+      @content = content.to_s.b
+      @filename = filename.to_s.empty? ? "upload" : filename.to_s
+      @content_type = content_type || (@filename.end_with?(".csv") ? "text/csv" : "application/octet-stream")
+    end
+
+    # Diskteki dosyayı okur.
+    def self.from_path(path, content_type: nil)
+      new(File.binread(path), filename: File.basename(path), content_type: content_type)
+    end
+
+    # FileUpload, IO (ör. File.open(path, "rb")) veya String içeriği FileUpload'a çevirir.
+    def self.wrap(value)
+      case value
+      when FileUpload then value
+      when String then new(value)
+      else
+        name = value.respond_to?(:path) && value.path ? File.basename(value.path) : "upload"
+        new(value.read, filename: name)
+      end
+    end
+  end
+end