misarmail 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7fb5ef6ef30c000df0e5737eac0e056e77db86562b67199aa0c53f4097846ba6
+  data.tar.gz: 37092f3124bab5b9fedad156bac2199e99c4c4115121f7277ee1103363a013b4
+SHA512:
+  metadata.gz: 88f14c434908fe0f189680689f173de703ae22903c46cbe1377ebdcffa294b60e2e99ed10fbd909d8ac07967149db4f77e1b8e29c7de8651ff0e860d75908d2d
+  data.tar.gz: dad272747a6a1d4a9d492ef25f6d2e28a218a14bc3a937d7aff2b87367c47b6f3b486c2a592bdcaff828b32a7f1a1c1fa7ee441c8d3a4c1d7ff59bc29b25f346

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this SDK are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-08-17
+
+First release.
+
+### Added
+
+- Full coverage of the MisarMail REST API, authenticated with a `msk_` developer
+  key sent as `Authorization: Bearer msk_…`.
+- Server-Sent Events for `POST /api/ai/generate-email/stream` and
+  `GET /api/campaigns/{id}/send-stream`. Unnamed frames terminated by
+  `data: [DONE]`, which the SDK consumes rather than handing on.
+- `GET /plan` for reading the subscription's allowances and per-feature usage,
+  so an expensive call can be checked before it is attempted rather than after
+  it is refused.
+- Retries with exponential back-off on genuinely transient statuses
+  (429 rate limits, 500, 502, 503, 504).
+
+### Notes
+
+- Plan limits are enforced server-side against the subscription attached to the
+  API key. Both a spent allowance and a locked feature answer 403 carrying
+  `code: "plan_limit_exceeded"`. The client keys on that code rather than the
+  status — 403 is otherwise an authorization failure — and surfaces a distinct
+  error type that is never retried, since retrying cannot help until the
+  allowance resets or the plan changes.
+- Streams are never retried: replaying one that failed mid-flight would
+  duplicate whatever the caller had already consumed.
+
+[1.0.0]: https://misarmail.com/docs

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Misar AI Technology Private Limited
+
+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,95 @@
+# MisarMail Ruby SDK
+
+Official Ruby SDK for the [MisarMail](https://misarmail.com) API — transactional
+send, campaigns, contacts, templates, automations, deliverability, warmup,
+monetization and the two AI streams.
+
+Full reference: [`misarmail.com/docs`](https://misarmail.com/docs).
+
+## Install
+
+```bash
+gem install misarmail
+```
+
+## Auth
+
+Use a MisarMail developer key (`msk_…`), created at
+[misarmail.com/developers](https://misarmail.com/developers). It is sent as
+`Authorization: Bearer msk_…`.
+
+Every call is metered against the subscription attached to that key. There is no
+client-side limit checking — the server decides, and the SDK surfaces its answer.
+
+## Quick start
+
+```ruby
+require "misar_mail"
+
+mail = MisarMail::Client.new(api_key: "msk_your_key")
+
+mail.email.send(
+  from: { email: "you@yourdomain.com" },
+  to: [{ email: "someone@example.com" }],
+  subject: "Hello",
+  html: "<p>Hi there</p>"
+)
+
+contacts = mail.contacts.list(page: 1, limit: 50)
+```
+
+## Plan limits
+
+Both a spent allowance and a feature that is not on the plan answer **`403`**,
+carrying `code: "plan_limit_exceeded"`. The SDK keys on that code rather than
+the status, which is why a refusal is typed correctly even though 403 is
+otherwise an authorization failure. The SDK raises
+`PlanLimitError` for either, and **does not retry** it — retrying cannot
+help until the allowance resets or the plan changes. Read ``upgrade_url`` to
+send the user somewhere useful.
+
+`GET /plan` returns `plan`, `sending` (the per-day and per-month email caps),
+`usage` — an array with one entry per metered feature, each carrying `used`,
+`limit` and `remaining` — and `upgrade`, which is null until a quota is tight.
+A null `limit` means unlimited, and `remaining` is null alongside it rather than
+0. Read it before an expensive call rather than discovering the ceiling through
+a refusal.
+
+The key needs the `read` or `subscription` scope.
+
+```ruby
+plan = mail.plan.get
+
+begin
+  mail.campaigns.create(
+    name: "Blast", subject: "We just shipped",
+    fromName: "Your Name", fromEmail: "you@yourdomain.com"
+  )
+rescue MisarMail::PlanLimitError => e
+  warn "#{e.feature} exhausted on #{e.plan}: #{e.upgrade_url}"
+end
+```
+
+## Streaming
+
+Two endpoints stream Server-Sent Events. Both sit **outside** `/v1`, which the
+SDK handles for you:
+
+| Method | Route |
+| --- | --- |
+| `streaming.generateEmail` | `POST /api/ai/generate-email/stream` |
+| `streaming.campaignSend` | `GET /api/campaigns/{id}/send-stream` |
+
+Frames are unnamed (`data: {…}`) and the stream ends with `data: [DONE]`, which
+the SDK consumes rather than handing on. A stream is never retried: replaying one
+that failed mid-flight would duplicate whatever you had already read.
+
+```ruby
+mail.streaming.generate_email(prompt: "a launch email") do |event|
+  print event.data["delta"]
+end
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).