nafru-email 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b0757004d9bfc0f06bd29e97e0ffb2a83ff5f57584415e4ee1245c500a5441a
+  data.tar.gz: 1b0bd6c50163282e5e2201783486da5743109bf501dfca6d092e83c82907a9f4
+SHA512:
+  metadata.gz: aa7c5d92768166f66b849eb8542c35db61265fcf41100c2baea4c7a6f07c71f4fd3eab60060837da8fb445a903c42ce49fe8d714d126074c1bacb0cb3a335217
+  data.tar.gz: a14f1717cac80ebd6da7e48e5c9ea9342c30ff847a8551f77df76fed87755a2a1386468f38b8de92c862e55c97b10f5840c8e2664bd932f9472cc365ee59c579

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nafru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,316 @@
+# Nafru Email Ruby SDK
+
+The official **Nafru Email Ruby SDK** lets you send email from Ruby (and Rails) through the Nafru Email API. Use it for
+transactional email (sign-up confirmations, password resets, receipts) and marketing broadcasts, to manage contacts, templates and
+domains, to trigger automations with custom events, and to verify webhooks. The email API is Resend-compatible, so request and
+response shapes will feel familiar if you are coming from Resend.
+
+[![Gem Version](https://img.shields.io/gem/v/nafru-email)](https://rubygems.org/gems/nafru-email)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nafrucom/nafru-email-sdks/blob/main/ruby/LICENSE)
+
+## Requirements
+
+- Ruby 3.1 or later
+- No dependencies: only the standard library (`net/http`, `json`, `openssl`).
+
+## Installation
+
+```sh
+gem install nafru-email
+# or in your Gemfile: gem "nafru-email"
+```
+
+## Quick start: send an email
+
+```ruby
+require "nafru_email"
+
+nafru = NafruEmail.new("nafru_123")
+# NafruEmail.new with no key reads the NAFRU_API_KEY environment variable.
+# Optional settings: NafruEmail.new("nafru_123", base_url: "http://localhost:48787/api", max_retries: 2, timeout: 30)
+# base_url defaults to Nafru::Email::DEFAULT_BASE_URL (https://email.nafru.com/api).
+
+email = nafru.emails.send(
+  {
+    from: "Acme <hello@example.com>",
+    to: "ali@example.org",
+    subject: "Welcome",
+    html: "<p>Hello!</p>",
+    scheduled_at: "in 1 hour" # optional: ISO 8601 or a relative expression, up to 30 days ahead
+  },
+  idempotency_key: "signup-1042" # retrying with the same key returns the same email
+)
+email[:id]
+```
+
+Body fields are `snake_case`, exactly as in the API (`reply_to`, `scheduled_at`, `first_name`); there is no conversion layer. Input
+hashes may use symbol or string keys; responses are hashes with **symbol keys**. The full shapes live in `sig/nafru_email.rbs` (checkable
+with Steep/RBS).
+
+> `emails.send` and `events.send` shadow Ruby's `Object#send`; use `__send__` / `public_send` if you need dynamic dispatch.
+
+## No real sending in development (dev outbox)
+
+When `NODE_ENV=development`, `emails.send` and `emails.batch` (and `emails.send` on a connection client) do **not** send anything.
+Each email is written under `.nafru/emails/` as plain text (`.txt`, headers + body) plus an `.html` file with the same name, and the
+file paths and plain text are printed to the console. The response is `{ id: "dev_…" }`. Change the folder with
+`dev_outbox: "tmp/mail"`, or turn it off with `dev_outbox: false`.
+
+## Errors
+
+Every failed call raises `Nafru::Email::Error`:
+
+```ruby
+begin
+  nafru.emails.send({ to: "ali@example.org", text: "hi" })
+rescue Nafru::Email::Error => e
+  e.status_code  # Integer; nil on network errors and timeouts
+  e.name         # validation_error, not_found, rate_limit_exceeded, application_error, timeout_error, …
+  e.message
+  e.errors       # on 422: [{ field:, message: }]
+  e.retry_after  # on 429: seconds to wait
+end
+```
+
+Configuration problems such as a missing API key (none passed and `NAFRU_API_KEY` unset) raise `ArgumentError`.
+
+## Retries, timeouts and idempotency
+
+- `429` is retried for every method, honoring `retry-after` (the request was rejected before it was processed).
+- `5xx` responses and network errors are retried for `GET`/`DELETE` (300 ms × 2ⁿ, at most 8 s).
+- `POST`/`PATCH` are **not** retried on server errors, because the email could go out twice. Pass an `idempotency_key` and they are.
+- Defaults: 2 retries (`max_retries:`) and a 30 s timeout (`timeout:`, in seconds).
+- Custom transport (`transport:`): any object that responds to `call(method:, url:, headers:, body:, timeout:)` and returns a
+  `Nafru::Email::Response` (tests, proxies, persistent connection pools). The default `Net::HTTP` transport opens a new connection
+  per request.
+
+## Resources
+
+| Resource             | Methods                                                                                                        |
+| -------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `emails`             | `send` `batch` `get` `list` `update` `cancel`                                                                  |
+| `domains`            | `create` `get` `list` `update` `remove` `verify`                                                               |
+| `contacts`           | `create` `get` `list` `update` `remove`, `segments.{list,add,remove}`, `topics.{list,update}` (by id or email) |
+| `contact_properties` | `create` `get` `list` `update` `remove`                                                                        |
+| `segments`           | `create` `get` `list` `remove` `contacts`                                                                      |
+| `topics`             | `create` `get` `list` `update` `remove`                                                                        |
+| `broadcasts`         | `create` `get` `list` `update` `remove` `send` `cancel`                                                        |
+| `templates`          | `create` `get` `list` `update` `remove` `publish` `duplicate` `put_translation` `remove_translation`           |
+| `brand`              | `get` `update`: workspace brand (`update` replaces the whole brand; read it with `get` first)                  |
+| `webhooks`           | `create` `get` `list` `update` `remove`                                                                        |
+| `api_keys`           | `create` `list` `remove`                                                                                       |
+| `events`             | `send` `batch` `list`: custom events that trigger automations                                                  |
+
+## Pagination
+
+Lists are cursor-based (`limit`, `after`, `before`). To walk every page (the enumerator raises if a page fails):
+
+```ruby
+Nafru::Email.paginate(nafru.contacts.method(:list), limit: 100).each do |contact|
+  puts contact[:email]
+end
+```
+
+## Templates
+
+```ruby
+nafru.templates.create({ name: "Welcome", alias: "welcome", subject: "Welcome {{{NAME|friend}}}",
+                         html: "<p>Hello {{{NAME|friend}}}</p>", brand: { mode: "inherit" } })
+nafru.templates.publish("welcome")
+nafru.emails.send({ from: "Acme <hello@acme.example>", to: "ali@example.org",
+                    template: { id: "welcome", variables: { NAME: "Ali" } } })
+```
+
+## Recurring broadcasts and data sources
+
+A broadcast with `recurrence` repeats on a schedule, and `data` / `data_source` fill the template's `{{{data.*}}}` variables:
+
+```ruby
+nafru.broadcasts.create({
+  segment_id: "seg_…", from: "Acme <hello@acme.example>", subject: "Weekly digest",
+  html: "<p>Plan: {{{data.plan}}}</p>",
+  recurrence: { type: "weekly", days: [1], time: "09:00" }, # monthly { day:, time: } · interval { every_days:, time: }
+  data_source: { type: "url", url: "https://acme.example/digest.json", header_name: "x-key", header_value: "…" }
+})
+nafru.broadcasts.update("bc_…", { recurrence: nil }) # nil clears a field; omitted fields are left unchanged
+nafru.broadcasts.send("bc_…", { data: { plan: "pro" } })
+```
+
+Because responses are hashes, an unknown `type` (a new recurrence kind, for example) does not break parsing; it is returned as is.
+
+## Custom events
+
+```ruby
+nafru.events.send({ name: "plan_upgraded", contact: { email: "ali@example.org" }, properties: { plan: "pro", seats: 3 } })
+```
+
+## Verifying webhook signatures
+
+Webhooks are signed in the Svix / Standard Webhooks format. Use the **raw** request body; JSON that has been parsed and re-encoded
+will not match the signature.
+
+```ruby
+# Rails: request.raw_post; Rack: request.body.read
+ok = Nafru::Email::Webhook.verify(
+  payload: request.raw_post,
+  headers: {
+    id: request.headers["svix-id"],
+    timestamp: request.headers["svix-timestamp"],
+    signature: request.headers["svix-signature"]
+  },
+  secret: ENV.fetch("NAFRU_WEBHOOK_SECRET") # the signing_secret from the webhooks.create response
+)
+head :bad_request unless ok
+```
+
+Timestamps more than 5 minutes in the past or future are rejected (`tolerance_seconds:`). During key rotation several signatures may
+be sent; one valid signature is enough. A malformed `secret` (no `whsec_` prefix, not base64) raises `ArgumentError`.
+
+## Connect with Nafru (for apps)
+
+If you want your customers to send from **their own** Nafru Email account, don't ask them to paste an API key. Register your app in
+Nafru Email (Developer → Apps) and use `NafruConnect`, which implements an OAuth flow with PKCE.
+
+```ruby
+connect = NafruConnect.new(
+  client_id: ENV.fetch("NAFRU_CLIENT_ID"),
+  client_secret: ENV.fetch("NAFRU_CLIENT_SECRET") # server side only
+  # base_url: optional (defaults to https://email.nafru.com/api; use "http://localhost:48787/api" locally)
+  # web_url: the consent screen; defaults to base_url with the trailing /api removed
+)
+
+# 1) Redirect the customer. Store code_verifier and state in the session.
+auth = connect.authorize_url(
+  redirect_uri: "https://myapp.example/nafru/callback",
+  state: session[:nafru_state] = SecureRandom.hex(16),
+  scopes: %w[emails.send templates.read senders.read connection.read]
+)
+session[:nafru_verifier] = auth[:code_verifier]
+redirect_to auth[:url], allow_other_host: true
+
+# 2) On the callback, check state and exchange the code for a connection.
+grant = connect.exchange(code: params[:code], code_verifier: session[:nafru_verifier], redirect_uri: redirect_uri)
+# Map grant[:connection_id] to the customer; store grant[:refresh_token] ENCRYPTED.
+
+# 3) Call the API on the customer's behalf. The access token refreshes automatically; the refresh token CHANGES on every refresh.
+connection = connect.connection(connection_id, refresh_token: load(connection_id)) do |tokens|
+  save(connection_id, tokens[:refresh_token]) # the old token is invalid until this is persisted
+end
+
+connection.status          # ready, missing: ["domain", "sender", …], setup_url
+connection.senders.list
+connection.templates.list  # the customer's templates + your app's bundle
+connection.emails.send({ from: from, to: to, template: { id: "welcome", variables: {} } })
+```
+
+- If the customer disconnected your app or the refresh token is invalid, `Error#name == "connection_revoked"`; ask the customer to
+  connect again.
+- Concurrent threads sharing one connection object share a single refresh (single flight, `Mutex`). If several processes (Puma
+  workers, Sidekiq) use the same connection, keep the refresh token in a shared, consistent store and serialize refreshes with a
+  lock: reusing an old refresh token revokes the connection for security.
+- If `on_token_refresh` raises, the call fails with `token_persist_failed`; the new token stays in memory and the next call retries
+  saving it. Don't call the same connection from inside the callback (the lock is not reentrant).
+- Management endpoints (API keys, domains, contacts, broadcasts) cannot be called with a connection token; only sending, reading and
+  discovery are available.
+- When the customer closes their account in your app, call `connect.revoke(refresh_token: token)`.
+
+## Deprecation warnings
+
+If the API has deprecated this SDK version (`Deprecation` response header), the client prints a warning to stderr once per client.
+The call itself is not affected. Deprecated versions and their sunset dates are listed in
+[deprecations.json](https://github.com/nafrucom/nafru-email-sdks/blob/main/deprecations.json).
+
+## Security
+
+- **Keep keys server-side.** Never embed your API key or `client_secret` in browser or mobile code; even a `sending_access` key
+  can send email. Store refresh tokens encrypted.
+- **HTTPS enforced.** `base_url` and `web_url` must use `https`; plain `http` is accepted only for `localhost`, `*.localhost`,
+  `127.0.0.0/8` and `[::1]` (local development). Anything else raises `ArgumentError` at construction time. TLS certificates are
+  always verified; there is no option to turn that off.
+- **Redirects refused.** The API never redirects, so a `3xx` response is not followed (that could leak `Authorization` to another
+  host); it raises `Nafru::Email::Error` with `name == "unexpected_redirect"` and is not retried.
+- **Input checks.** Path parameters are percent-encoded and an empty, `.` or `..` segment raises `ArgumentError` before any request;
+  `idempotency_key` may not be empty or contain control characters (no header injection). Response bodies are capped at 10 MB
+  (`response_too_large`).
+- **Secrets redacted.** `inspect`, `to_s` and `pp` of `NafruEmail`, `NafruConnect`, connections and `ConnectionGrant` never show the
+  API key, client secret or tokens (`[REDACTED]`); error messages never include them. Read the value explicitly
+  (`grant.refresh_token`) when you store it.
+- **Webhooks.** Verify against the **raw** request body (`request.raw_post`); comparison is constant-time, timestamps outside ±5
+  minutes are rejected, missing headers return `false`, and at most 32 signatures per header are checked.
+- **Reporting vulnerabilities.** Please don't open a public issue. Use GitHub
+  [private vulnerability reporting](https://github.com/nafrucom/nafru-email-sdks/security/advisories/new) or email security@nafru.com; see
+  [SECURITY.md](https://github.com/nafrucom/nafru-email-sdks/blob/main/SECURITY.md).
+
+## Development
+
+Contributions are welcome; see [CONTRIBUTING.md](https://github.com/nafrucom/nafru-email-sdks/blob/main/CONTRIBUTING.md).
+
+```sh
+bundle install
+bundle exec rake test
+gem build nafru-email.gemspec
+```
+
+The version lives in one place, `lib/nafru_email/version.rb` (`VERSION`); the gemspec reads it from there.
+
+## Troubleshooting
+
+Every API failure raises `Nafru::Email::Error`; check `e.name`, `e.status_code` and `e.message`. Configuration mistakes raise
+`ArgumentError` before any request is made.
+
+- **`missing_api_key` / `invalid_api_key` / `unauthorized` (401/403).** The key is missing, wrong or revoked. `NafruEmail.new` with no
+  argument reads `NAFRU_API_KEY`; if that is unset too it raises `ArgumentError` ("api_key gerekli"). Create a new key in the
+  dashboard if it was revoked.
+- **`forbidden` (403).** The key lacks permission: a `sending_access` key can send email but cannot list or manage resources, and
+  may be restricted to one domain. Use a `full_access` key for management calls.
+- **`validation_error` (422).** The request body is invalid. `e.errors` lists each problem as `{ field:, message: }`.
+- **`rate_limit_exceeded` (429).** Retried automatically (up to `max_retries`, honoring `Retry-After`, capped at 8 s). If it still
+  fails, `e.retry_after` tells you how many seconds to wait.
+- **`timeout_error` / `application_error` with `status_code == nil`.** A network failure or timeout (`timeout:` defaults to 30 s).
+  `GET`/`DELETE` are retried; a `POST`/`PATCH` is retried only with an `idempotency_key`, so pass one to make sending safe to retry.
+- **`unexpected_redirect` (3xx).** The API never redirects. The `base_url` is probably wrong (missing `/api`, `http` → `https`
+  upgrade, a login page) or a proxy is in between. Redirects are never followed or retried.
+- **`ArgumentError: base_url https kullanmalı (http yalnız localhost için)`.** `base_url`/`web_url` must be `https`; `http` is only
+  allowed for `localhost`, `*.localhost`, `127.0.0.0/8` and `[::1]`.
+- **`response_too_large`.** The response body exceeded 10 MB. This points to a misbehaving proxy or the wrong `base_url`.
+- **`connection_revoked` (Connect).** The customer disconnected your app or the refresh token is invalid or was reused. Ask the
+  customer to connect again.
+- **`token_persist_failed` (Connect).** Your `on_token_refresh` callback raised. The new refresh token is kept in memory and saving it
+  is retried on the next call; fix the storage, because the old token is no longer valid.
+- **`Webhook.verify` returns `false`.** Pass the **raw** body (`request.raw_post`, not re-serialized JSON). Use that webhook's own
+  `whsec_…` signing secret. Pass the `svix-id`, `svix-timestamp` and `svix-signature` headers. Keep the server clock in sync
+  (timestamps more than 5 minutes off are rejected).
+- **Emails are not being sent.** With `NODE_ENV=development` the dev outbox is on: emails are written to `.nafru/emails/` and the
+  paths printed instead of sending. Pass `dev_outbox: false` to send for real.
+
+## Links
+
+- API documentation: https://email.nafru.com
+- Source and issues: https://github.com/nafrucom/nafru-email-sdks
+
+Other official SDKs:
+
+| Language             | Package                                                                 |
+| -------------------- | ----------------------------------------------------------------------- |
+| TypeScript / Node.js | [`@nafrucom/email`](https://www.npmjs.com/package/@nafrucom/email)      |
+| Python               | [python](https://github.com/nafrucom/nafru-email-sdks/tree/main/python) |
+| PHP                  | [php](https://github.com/nafrucom/nafru-email-sdks/tree/main/php)       |
+| Ruby                 | [ruby](https://github.com/nafrucom/nafru-email-sdks/tree/main/ruby)     |
+| Java                 | [java](https://github.com/nafrucom/nafru-email-sdks/tree/main/java)     |
+| .NET (C#)            | [dotnet](https://github.com/nafrucom/nafru-email-sdks/tree/main/dotnet) |
+| Go                   | [go](https://github.com/nafrucom/nafru-email-sdks/tree/main/go)         |
+| Rust                 | [rust](https://github.com/nafrucom/nafru-email-sdks/tree/main/rust)     |
+| Swift                | [swift](https://github.com/nafrucom/nafru-email-sdks/tree/main/swift)   |
+
+## Support
+
+- Questions and how-to: [GitHub Discussions](https://github.com/nafrucom/nafru-email-sdks/discussions)
+- Bugs in this SDK: [GitHub issues](https://github.com/nafrucom/nafru-email-sdks/issues)
+- Account, billing and deliverability: destek@nafru.com
+- Security issues: see [SECURITY.md](https://github.com/nafrucom/nafru-email-sdks/blob/main/SECURITY.md) (do not open a public issue)
+
+More details are in [SUPPORT.md](https://github.com/nafrucom/nafru-email-sdks/blob/main/SUPPORT.md).
+
+## License
+
+MIT. See [LICENSE](https://github.com/nafrucom/nafru-email-sdks/blob/main/ruby/LICENSE).

data/lib/nafru_email/app.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+require "uri"
+
+module Nafru
+  module Email
+    # Uygulamanın müşteriden isteyebileceği izinler.
+    SCOPES = %w[emails.send emails.read templates.read domains.read senders.read connection.read].freeze
+
+    def self.base64url(bytes) = [bytes].pack("m0").tr("+/", "-_").delete("=")
+
+    # PKCE (S256): 32 rastgele bayttan 43 karakterlik doğrulayıcı ve SHA-256 sınaması.
+    # @return [Hash] `{ verifier:, challenge: }`
+    def self.create_pkce
+      verifier = base64url(SecureRandom.random_bytes(32))
+      { verifier: verifier, challenge: base64url(OpenSSL::Digest::SHA256.digest(verifier)) }
+    end
+
+    # `exchange` sonucu. `inspect`/`to_s` yenileme belirtecini göstermez; değere `grant.refresh_token` ya da `grant[:refresh_token]` ile erişin.
+    ConnectionGrant = Struct.new(:connection_id, :refresh_token, :scopes, keyword_init: true) do
+      def inspect = "#<ConnectionGrant connection_id=#{connection_id.inspect} refresh_token=[REDACTED] scopes=#{scopes.inspect}>"
+      alias_method :to_s, :inspect
+
+      def pretty_print(pp) = pp.text(inspect)
+    end
+
+    # "Nafru ile bağlan" uçları: izin adresi, kod değişimi, iptal.
+    class Connect
+      include Redacted
+
+      def initialize(oauth, client_id:, client_secret:, web_url:)
+        @oauth = oauth
+        @client_id = client_id
+        @client_secret = client_secret
+        Email.require_https!(web_url, "web_url")
+        @web = web_url.sub(%r{/+\z}, "")
+      end
+
+      # Müşteriyi yönlendireceğiniz "Nafru ile bağlan" adresi. `code_verifier`'ı oturumda saklayın; dönüşte `exchange`'e verin.
+      # Dönüşte `state`'i kendi sakladığınız değerle karşılaştırmak sizin sorumluluğunuzdur.
+      # @return [Hash] `{ url:, code_verifier: }`
+      def authorize_url(redirect_uri:, state:, scopes:, login_hint: nil)
+        raise ArgumentError, "Nafru SDK: state gerekli (CSRF koruması)" if state.to_s.empty?
+        raise ArgumentError, "Nafru SDK: en az bir izin (scopes) gerekli" if scopes.empty?
+
+        pkce = Email.create_pkce
+        params = {
+          client_id: @client_id, redirect_uri: redirect_uri, state: state, scope: scopes.join(" "),
+          code_challenge: pkce[:challenge], code_challenge_method: "S256"
+        }
+        params[:login_hint] = login_hint if login_hint && !login_hint.empty?
+        { url: "#{@web}/connect?#{URI.encode_www_form(params)}", code_verifier: pkce[:verifier] }
+      end
+
+      # Dönüşteki tek kullanımlık `code`'u bağlantıya çevirir (sunucunuzdan çağırın).
+      # @return [ConnectionGrant]
+      def exchange(code:, code_verifier:, redirect_uri:)
+        data = @oauth.request("POST", "/oauth/token", body: {
+          grant_type: "authorization_code", client_id: @client_id, client_secret: @client_secret,
+          code: code, code_verifier: code_verifier, redirect_uri: redirect_uri
+        })
+        ConnectionGrant.new(connection_id: data[:connection_id], refresh_token: data[:refresh_token], scopes: data[:scopes])
+      end
+
+      # Bağlantıyı uygulama tarafından iptal eder (müşteri hesabını kapattığında). Belirteçler anında geçersiz olur.
+      def revoke(refresh_token:)
+        @oauth.request("POST", "/oauth/revoke", body: { client_id: @client_id, client_secret: @client_secret, token: refresh_token })
+        nil
+      end
+    end
+
+    # Bağlantının erişim belirtecini tutar ve yeniler. Eşzamanlı çağrılar TEK yenilemeyi paylaşır (tek uçuş): dönüşlü yenileme
+    # belirteci ikinci bir eşzamanlı yenilemede "yeniden kullanım" sayılır ve bağlantıyı iptal ettirirdi.
+    class TokenManager
+      include Redacted
+
+      # Süre dolmadan bu kadar önce yenilenir (saat farkı ve ağ gecikmesi payı).
+      EARLY_REFRESH = 30
+
+      def initialize(oauth, client_id:, client_secret:, refresh_token:, on_token_refresh:)
+        @oauth = oauth
+        @client_id = client_id
+        @client_secret = client_secret
+        @refresh_token = refresh_token
+        @on_token_refresh = on_token_refresh
+        @access_token = nil
+        @expires_at = 0
+        # Yenileme sunucuda başarılı oldu ama yeni yenileme belirteci saklanamadı: eski belirteç artık geçersiz, bu kaybolmamalı.
+        @unpersisted = false
+        @mutex = Mutex.new
+      end
+
+      # Geçerli erişim belirteci; yoksa ya da dolmak üzereyse yeniler. Kilit, bekleyenlerin tek yenilemenin sonucunu görmesini sağlar.
+      def access_token
+        @mutex.synchronize do
+          persist if @unpersisted
+          return @access_token if @access_token && now < @expires_at - EARLY_REFRESH
+
+          refresh
+        end
+      end
+
+      # Sunucu 401 `invalid_token` dedi: eldeki belirteci at ve yenile (aynı belirteçle eşzamanlı 401'ler tek yenilemeyi paylaşır).
+      def invalidate(stale)
+        @mutex.synchronize do
+          @access_token = nil if @access_token == stale
+          @access_token || refresh
+        end
+      end
+
+      private
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def persist
+        @on_token_refresh.call({ refresh_token: @refresh_token })
+        @unpersisted = false
+      rescue StandardError => e
+        @unpersisted = true
+        raise Error.new("Yeni yenileme belirteci saklanamadı: #{e.message}", name: "token_persist_failed")
+      end
+
+      def refresh
+        data = begin
+          @oauth.request("POST", "/oauth/token", body: {
+            grant_type: "refresh_token", client_id: @client_id, client_secret: @client_secret, refresh_token: @refresh_token
+          })
+        rescue Error => e
+          # Geçersiz/tüketilmiş belirteç ya da iptal: kalıcı hata. Ağ ve 5xx geçici hata olarak olduğu gibi döner.
+          raise e unless %w[invalid_grant connection_revoked].include?(e.name) ||
+                         (e.status_code == 403 && e.name != "rate_limit_exceeded")
+
+          raise Error.new("Bağlantı iptal edilmiş ya da yenileme belirteci geçersiz; müşterinin yeniden bağlanması gerekir.",
+                          name: "connection_revoked", status_code: e.status_code, errors: e.errors, retry_after: e.retry_after)
+        end
+        @refresh_token = data[:refresh_token]
+        @access_token = data[:access_token]
+        @expires_at = now + data[:expires_in].to_f
+        persist
+        @access_token
+      end
+    end
+
+    # Bir müşteri bağlantısı adına çağrı yapar. Her denemede `TokenManager#access_token` ile belirteç alınır; 401 `invalid_token`
+    # (süre dolmuş / yenilenmiş) ise bir kez yenileyip tekrar dener.
+    class Connection
+      include Redacted
+
+      attr_reader :id, :senders, :templates, :emails
+
+      # Bağlantı istemcisinde yalnız gönderim ve okuma vardır.
+      class Emails
+        def initialize(emails) = @emails = emails
+        def send(...) = @emails.send(...)
+        def get(...) = @emails.get(...)
+        def list(...) = @emails.list(...)
+      end
+
+      Senders = Struct.new(:conn) do
+        def list = conn.request("GET", "/senders")
+      end
+
+      # Müşterinin yayınlanmış şablonları ile uygulamanın paketi: anahtar başına tek öğe (müşterinin kendi kopyası paketi gölgeler).
+      Templates = Struct.new(:conn) do
+        def list = conn.request("GET", "/templates")
+      end
+
+      def initialize(id, tokens:, http_factory:, dev_outbox: false)
+        @id = id
+        @tokens = tokens
+        @current = nil
+        @http = http_factory.call(lambda {
+          @current = @tokens.access_token
+        })
+        @senders = Senders.new(self)
+        @templates = Templates.new(self)
+        @emails = Emails.new(Resources::Emails.new(self, dev_outbox))
+      end
+
+      # `GET /connection`: hazır mı, eksik ne, ücret modu ve müşterinin kurulum adresi.
+      def status = request("GET", "/connection")
+
+      # @api private
+      def request(method, path, **options)
+        @http.request(method, path, **options)
+      rescue Error => e
+        raise unless e.name == "invalid_token" && @current
+
+        @tokens.invalidate(@current)
+        @http.request(method, path, **options)
+      end
+    end
+  end
+end

data/lib/nafru_email/client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Nafru
+  module Email
+    # Nafru Email üretim API'si; `base_url` verilmezse (ya da boşsa) kullanılır.
+    DEFAULT_BASE_URL = "https://email.nafru.com/api"
+  end
+end
+
+# API anahtarıyla istemci (Resend tarzı): `NafruEmail.new("nafru_...")`. Anahtar verilmezse `NAFRU_API_KEY` okunur.
+class NafruEmail
+  include Nafru::Email::Redacted
+
+  attr_reader :emails, :domains, :contacts, :contact_properties, :segments, :topics, :broadcasts, :templates, :brand,
+              :webhooks, :api_keys, :events
+
+  # @param api_key [String, nil] Dashboard'dan üretilen API anahtarı; boşsa `NAFRU_API_KEY`. Tarayıcıya/istemciye gömmeyin.
+  # @param base_url [String, nil] API'nin kök adresi; varsayılan `DEFAULT_BASE_URL` (yerelde `http://localhost:48787/api`).
+  # @param transport [#call, nil] özel taşıyıcı (test, proxy); bkz. `NET_HTTP_TRANSPORT`.
+  # @param max_retries [Integer] `429` ve güvenli isteklerde sunucu/ağ hatası için yeniden deneme; `0` kapatır.
+  # @param timeout [Numeric] istek başına zaman aşımı (saniye).
+  # @param dev_outbox [String, false, nil] verilirse `emails.send`/`batch` göndermez, bu klasöre yazar;
+  #   `nil`: `NODE_ENV=development` iken `.nafru/emails`; `false` her zaman gerçek gönderim.
+  def initialize(api_key = nil, base_url: nil, transport: nil, max_retries: 2, timeout: 30, dev_outbox: nil)
+    api_key = ENV.fetch("NAFRU_API_KEY", nil) if api_key.to_s.empty?
+    raise ArgumentError, "Nafru SDK: api_key gerekli" if api_key.to_s.empty?
+    base_url = Nafru::Email::DEFAULT_BASE_URL if base_url.to_s.empty?
+
+    @http = Nafru::Email::Http.new(api_key: api_key, base_url: base_url, transport: transport, max_retries: max_retries, timeout: timeout)
+    @emails = Nafru::Email::Resources::Emails.new(@http, Nafru::Email::DevOutbox.resolve(dev_outbox))
+    @domains = Nafru::Email::Resources::Domains.new(@http)
+    @contacts = Nafru::Email::Resources::Contacts.new(@http)
+    @contact_properties = Nafru::Email::Resources::ContactProperties.new(@http)
+    @segments = Nafru::Email::Resources::Segments.new(@http)
+    @topics = Nafru::Email::Resources::Topics.new(@http)
+    @broadcasts = Nafru::Email::Resources::Broadcasts.new(@http)
+    @templates = Nafru::Email::Resources::Templates.new(@http)
+    @brand = Nafru::Email::Resources::Brand.new(@http)
+    @webhooks = Nafru::Email::Resources::Webhooks.new(@http)
+    @api_keys = Nafru::Email::Resources::ApiKeys.new(@http)
+    @events = Nafru::Email::Resources::Events.new(@http)
+  end
+end
+
+# "Nafru ile bağlan" fabrikası: müşterinin Nafru Email hesabına tek tıkla bağlanır, o hesap adına gönderir.
+# Tek alan adı/anahtar için `NafruEmail` kullanın.
+class NafruConnect
+  extend Forwardable
+  include Nafru::Email::Redacted
+
+  # `authorize_url(redirect_uri:, state:, scopes:, login_hint: nil)`, `exchange(code:, code_verifier:, redirect_uri:)`,
+  # `revoke(refresh_token:)`: bkz. `Nafru::Email::Connect`.
+  def_delegators :@connect, :authorize_url, :exchange, :revoke
+
+  # @param client_secret [String] yalnız sunucunuzda.
+  # @param base_url [String, nil] API'nin kök adresi; varsayılan `DEFAULT_BASE_URL`.
+  # @param web_url [String, nil] izin ekranının kök adresi; verilmezse `base_url` sonundaki `/api` atılır.
+  def initialize(client_id:, client_secret:, base_url: nil, web_url: nil, transport: nil, max_retries: 2, timeout: 30,
+                 dev_outbox: nil)
+    raise ArgumentError, "Nafru SDK: client_id gerekli" if client_id.to_s.empty?
+    raise ArgumentError, "Nafru SDK: client_secret gerekli" if client_secret.to_s.empty?
+    base_url = Nafru::Email::DEFAULT_BASE_URL if base_url.to_s.empty?
+
+    @credentials = { client_id: client_id, client_secret: client_secret }
+    @shared = { base_url: base_url, transport: transport, max_retries: max_retries, timeout: timeout }
+    @dev_outbox = Nafru::Email::DevOutbox.resolve(dev_outbox)
+    # Token uçları kimlik bilgisini gövdede taşır; Authorization başlığı yok.
+    @oauth = Nafru::Email::Http.new(**@shared, authorize: -> {})
+    @connect = Nafru::Email::Connect.new(@oauth, **@credentials, web_url: web_url || base_url.sub(%r{/api/*\z}, ""))
+  end
+
+  # Saklanan yenileme belirteciyle bir müşteri bağlantısı. Yenileme otomatiktir; yeni belirteç `on_token_refresh` ile gelir.
+  # @param on_token_refresh [#call] `{ refresh_token: }` alır; yeni değeri KALICI yazmadan eskisi geçersizdir. Hata fırlatırsa
+  #   çağrı `token_persist_failed` ile hata verir. Blok olarak da verilebilir.
+  def connection(connection_id, refresh_token:, on_token_refresh: nil, &block)
+    callback = on_token_refresh || block or raise ArgumentError, "Nafru SDK: on_token_refresh gerekli"
+    tokens = Nafru::Email::TokenManager.new(@oauth, **@credentials, refresh_token: refresh_token, on_token_refresh: callback)
+    Nafru::Email::Connection.new(connection_id, tokens: tokens, dev_outbox: @dev_outbox,
+                                  http_factory: ->(authorize) { Nafru::Email::Http.new(**@shared, authorize: authorize) })
+  end
+end