unitpost 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 258d8d544bae08baa517a8699aa32fd9cdb3edf2d6625b8c3e2da0607e3dd3dc
-  data.tar.gz: 0e6549783185c6b4ddba87aa75d607763538d2533dc4e441a808b34686af77fc
+  metadata.gz: fffb836d80d04f7e9a1fc9491451022bdd6f6349aceb18751b5bb8963c02db76
+  data.tar.gz: 1265d40f0d6c6da34a464f402eb54d12f02261459cd286d8980cc9cbae4907f4
 SHA512:
-  metadata.gz: 9f0ed12282ee80f55a36327a56afebe22aa4cb49fe5fc61b8519fb90046c17f1a252d8bf2bfa6861452ea9f010930e471e2ddb292367ea7a7ab259ebc5d35237
-  data.tar.gz: e74e10b17e8805170b810e16c3a2e1d158b6371898735cc20ee6844628d34e60069c1ec48fce401718445cf70a9428d48db5541bf90d6e6de85617cb711574c2
+  metadata.gz: 6f785497b63324e0398ea4d0c9e4c087b695c9c4bd59669722e2a8e340084837e480cbaf783b9b96b903f1ff44cf6cfcc689dd94da6ece8508233182e3c9decc
+  data.tar.gz: 4e4c44b15c5f38125a5c9206be4f55a6eac770ea1a594be4fd4f9bf80b1a665df09bda598101bed833c643179ab69acb9b2ae48f83054f9bd03b0e10df2cd384

data/README.md

@@ -1,4 +1,161 @@
-# unitpost (RubyGems)
+# unitpost
 
-Name reserved for **[Unitpost](https://unitpost.com)**. Placeholder gem; the
-official Unitpost Ruby SDK will be published under this name.
+Official [Unitpost](https://www.unitpost.com) SDK for Ruby. Send email and manage
+contacts, segments, campaigns, templates, domains, suppressions, and webhooks.
+
+## Install
+
+```bash
+gem install unitpost
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "unitpost"
+```
+
+Requires Ruby 3.0+.
+
+## Quick start
+
+```ruby
+require "unitpost"
+
+unitpost = Unitpost::Client.new # reads UNITPOST_API_KEY (or pass api_key:)
+
+result = unitpost.emails.send({
+  from: "Acme <you@yourdomain.com>", # bare address works too
+  to: "customer@example.com",
+  subject: "Hello",
+  html: "<p>It works!</p>"
+})
+
+if result.error
+  warn "#{result.error.code}: #{result.error.message}"
+else
+  puts result.data["id"]
+end
+```
+
+Every method returns a `Unitpost::Result` with `#data` and `#error` (and a
+`#success?` helper). An API-level failure populates `#error` (a
+`Unitpost::Error`) instead of raising.
+
+## Authentication
+
+Pass `api_key:` to `Unitpost::Client.new`, or set `UNITPOST_API_KEY`. Create a
+key at [unitpost.com → Settings → API keys](https://www.unitpost.com).
+
+## Client surface
+
+| Accessor | Covers |
+| --- | --- |
+| `emails` | Send, batch, list, get, update, stats, inbound (`received_*`) |
+| `contacts` | CRUD, import jobs |
+| `contact_fields` | Custom field definitions |
+| `segments` | Segments + membership |
+| `topics` | Topics + contact topic prefs |
+| `campaigns` | Draft, schedule, send, pause/resume |
+| `templates` | Template CRUD |
+| `brand_kits` | Brand kit |
+| `domains` | Domains + verify |
+| `webhooks` | Endpoints + `verify` |
+| `api_keys` | API key management |
+| `suppressions` | Suppression list |
+| `usage` | Billing-period usage snapshot |
+
+## Pagination
+
+```ruby
+unitpost.contacts.list_all.each do |contact|
+  puts contact["email"]
+end
+```
+
+## Suppressions
+
+The suppression list holds addresses excluded from every send — single, batch,
+and campaign, including cc/bcc — case-insensitively. Hard bounces and spam
+complaints are added automatically; you can also add your own:
+
+```ruby
+# Suppress one address, or many in a single call (idempotent — re-adding is a no-op).
+unitpost.suppressions.create({ email: "bounced@example.com", reason: "manual" })
+unitpost.suppressions.create({ emails: ["a@example.com", "b@example.com"] })
+
+# Look one up by id or email; list (optionally filter scope); un-suppress.
+unitpost.suppressions.get("bounced@example.com")
+unitpost.suppressions.list_all.each { |s| puts "#{s["email"]} #{s["reason"]}" }
+unitpost.suppressions.delete("bounced@example.com")
+```
+
+`reason` accepts `manual`, `import`, or `api` — the engine-written `bounce` and
+`complaint` reasons are read-only. Unitpost-wide (`platform`) entries are visible
+but can't be removed via the API.
+
+## Verifying webhooks
+
+```ruby
+event = Unitpost.verify_webhook(
+  payload: raw_body,            # the raw request body string
+  secret: ENV.fetch("UNITPOST_WEBHOOK_SECRET"),
+  headers: request.headers
+)
+```
+
+Or from the client (Resend-style alias):
+
+```ruby
+event = client.webhooks.verify(payload: raw_body, secret: secret, headers: request.headers)
+```
+
+## Idempotency
+
+`emails.send` and `emails.batch` are safe to retry by default — when you don't
+pass `idempotency_key:`, the SDK generates one so an automatic retry can't
+double-send. Pass your own to dedupe across separate calls:
+
+```ruby
+unitpost.emails.send({ ... }, idempotency_key: SecureRandom.uuid)
+unitpost.emails.batch([ ... ], idempotency_key: SecureRandom.uuid)
+```
+
+> The server dedupes on `(workspace, idempotency key)` for 24h and replays the
+> original result instead of re-sending (the email id for a send, the full list
+> envelope for a batch).
+
+## Retries
+
+Transient failures are retried automatically: `429`, `5xx`, and transport errors
+(timeouts / network) retry up to `max_retries` times (default `2`). A `429`/`503`
+`Retry-After` is honored; otherwise exponential backoff with full jitter is used.
+Client errors (`401`/`403`/`404`/`409`/`422`) are never retried. Only requests
+safe to replay are retried: `GET`s and writes carrying an idempotency key (which
+`emails.send` and `emails.batch` always do); any other keyless write is never
+auto-retried.
+
+```ruby
+# Defaults shown; set max_retries: 0 to disable.
+unitpost = Unitpost::Client.new(max_retries: 2, retry_base_delay: 0.5, max_retry_delay: 20.0)
+```
+
+## Resources
+
+| | |
+| --- | --- |
+| Docs + API reference | https://www.unitpost.com/docs |
+| Product / SMTP / MCP guides | https://www.unitpost.com/guides |
+| OpenAPI JSON | https://www.unitpost.com/api/v1/openapi.json |
+| LLM index | https://www.unitpost.com/llms.txt |
+| Dashboard / API keys | https://www.unitpost.com |
+| Email components (`@unitpost/email`) | https://www.unitpost.com/components |
+| Template gallery | https://www.unitpost.com/templates/gallery |
+| Playground | https://www.unitpost.com/playground |
+| Migration Assistant | https://www.unitpost.com/migration |
+| MCP + Agent Skills | https://www.unitpost.com/guides#ai-mcp · https://www.unitpost.com/guides#ai-skills |
+| Support | support@unitpost.com |
+
+## License
+
+MIT

data/lib/unitpost/client.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "http_client"
+require_relative "resources"
+
+module Unitpost
+  # The Unitpost client. Construct once, reuse everywhere.
+  #
+  #   require "unitpost"
+  #   unitpost = Unitpost::Client.new            # reads UNITPOST_API_KEY
+  #   result = unitpost.emails.send(from: ..., to: ..., subject: ..., html: ...)
+  #   if result.error
+  #     warn "#{result.error.code}: #{result.error.message}"
+  #   else
+  #     puts result.data["id"]
+  #   end
+  class Client
+    attr_reader :emails, :contacts, :contact_fields, :segments, :topics,
+                :campaigns, :templates, :brand_kits, :domains, :webhooks, :api_keys, :suppressions,
+                :usage
+
+    def initialize(api_key: nil, base_url: nil, timeout: 30, headers: {}, adapter: nil, stubs: nil,
+                   max_retries: 2, retry_base_delay: 0.5, max_retry_delay: 20.0, sleeper: nil)
+      http = HttpClient.new(
+        api_key: api_key,
+        base_url: base_url,
+        timeout: timeout,
+        headers: headers,
+        adapter: adapter,
+        stubs: stubs,
+        max_retries: max_retries,
+        retry_base_delay: retry_base_delay,
+        max_retry_delay: max_retry_delay,
+        sleeper: sleeper
+      )
+      @emails = Resources::Emails.new(http)
+      @contacts = Resources::Contacts.new(http)
+      @contact_fields = Resources::ContactFields.new(http)
+      @segments = Resources::Segments.new(http)
+      @topics = Resources::Topics.new(http)
+      @campaigns = Resources::Campaigns.new(http)
+      @templates = Resources::Templates.new(http)
+      @brand_kits = Resources::BrandKits.new(http)
+      @domains = Resources::Domains.new(http)
+      @webhooks = Resources::Webhooks.new(http)
+      @api_keys = Resources::ApiKeys.new(http)
+      @suppressions = Resources::Suppressions.new(http)
+      # NOTE (pre-launch): `events` is intentionally absent while the
+      # custom-events surface is behind the launch gate.
+      @usage = Resources::Usage.new(http)
+    end
+  end
+end

data/lib/unitpost/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Unitpost
+  # A structured API error. Returned on Result#error (not raised by default).
+  class Error < StandardError
+    attr_reader :code, :status, :request_id, :details
+
+    # +details+ holds field-level validation errors (present on 422
+    # validation_error): an array of { "field" => "<dotted.path>",
+    # "message" => "<why>" } hashes. Empty array otherwise.
+    def initialize(code:, message:, status:, request_id: nil, details: nil)
+      super(message)
+      @code = code
+      @status = status
+      @request_id = request_id
+      @details = details || []
+    end
+  end
+
+  # Raised by Unitpost.verify_webhook when a delivery can't be trusted.
+  class WebhookVerificationError < StandardError; end
+
+  # Every SDK method returns one of these; exactly one of data/error is set.
+  Result = Struct.new(:data, :error, keyword_init: true) do
+    def success?
+      error.nil?
+    end
+  end
+end