misarblog 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 668bfc444b17b3b94fcf0cee95e32d9b4666c8e592f2620e4bb1ca84900d96fc
+  data.tar.gz: 5eab33effad1e6be69d8c8c6f7585afbc87b0b8031a05f030046256f5b2b74f7
+SHA512:
+  metadata.gz: '09713e47a720fb3028f62d13fb14b9650b7f079bac11f90a9576376e7d45454d8f90e68cf04f019f680916c7a8d809589e690adeec32c5f94ef36681a3697221'
+  data.tar.gz: e2475931a76cdbbbbd1f388e66ad9197d7f48ffd49924f321ffe5e4d7674e69b0f5732344b0bbe5e386a6a49cb8b9a7257233b2e8661daac61b93aa98b7c75c5

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this SDK are documented here. Versions follow
+[semantic versioning](https://semver.org/).
+
+## 1.1.0 — 2026-08-16
+
+### Added
+- `comments.list(...)` — `GET /comments`, an article's thread with replies
+  nested one level deep.
+- `follows.status(...)` — `GET /follows`, follower/following counts plus
+  whether the key's owner follows the profile.
+- A dedicated plan-limit error type carrying the plan slug, the pricing URL and
+  seconds until the allowance resets. The API answers a spent allowance with
+  429 and a locked feature with 402, both tagged `plan_limit_exceeded`.
+
+### Changed
+- Plan refusals no longer consume the retry budget. A `plan_limit_exceeded`
+  response is surfaced immediately instead of being retried three times with
+  back-off — retrying cannot help until the allowance resets or the plan
+  changes. Plain rate-limit 429s still retry as before.
+- The SDK now covers all 25 key-authenticated operations.
+
+### Removed
+- The `auth` token-refresh helper. It posted to `misar.blog/api/auth/refresh`,
+  a route that no longer exists, and did not use API-key authentication.
+
+## 1.0.0
+
+- Initial release: 23 developer-API operations, typed models, retry with
+  exponential back-off.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Misar AI Technology Pvt Ltd
+
+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,81 @@
+# Misar.Blog Ruby SDK
+
+Official Ruby client for the Misar.Blog developer API. Standard library only, retry with back-off.
+
+## Install
+
+```bash
+gem install misarblog
+```
+
+## Quick start
+
+```ruby
+require "misarblog"
+
+blog = MisarBlog.new(api_key: "mbk_...")
+
+me = blog.account.profile
+thread = blog.comments.list(article_id: "article-id", limit: 50)
+follows = blog.follows.status(user_id: me["id"])
+
+begin
+  blog.ai.complete(prompt: "Draft an intro paragraph")
+rescue MisarBlog::PlanLimitError => e
+  puts "#{e.plan} plan is out of credits — upgrade at #{e.upgrade_url}"
+end
+```
+
+## Authentication and plan gating
+
+Every call goes through the metered gateway at `https://api.misar.io/blog/v1`
+with your developer key as a Bearer token. Mint a key in the dashboard at
+<https://www.misar.blog/dashboard/settings/api> — key management is a
+cookie-session flow and is deliberately not exposed by this SDK.
+
+Feature access and throughput follow the subscription attached to that key:
+
+| Signal | Meaning |
+| --- | --- |
+| `401` | Missing, expired or revoked key |
+| `403` | The key is scoped and lacks the scope this route needs |
+| `429` (plain) | Rate limit — 100 requests/minute per key. The SDK retries with back-off |
+| `429` + `plan_limit_exceeded` | A metered allowance is spent. Retrying will not help until it resets |
+| `402` + `plan_limit_exceeded` | The feature is not on this plan |
+
+The last two raise ``MisarBlog::PlanLimitError`` rather than a generic error, carrying the
+plan slug, the pricing URL and (when the API supplies it) seconds until reset.
+Show the upgrade URL instead of reporting a bare failure — the SDK does not
+retry these, because retrying cannot change the outcome.
+
+## Covered operations
+
+All 25 key-authenticated operations:
+
+| Group | Operations |
+| --- | --- |
+| Articles | list, get, create, update, create draft, search, recommendations |
+| Series | list, create, add article |
+| Reactions | get, add, remove |
+| Comments | list |
+| Follows | status |
+| AI | complete, titles |
+| Images | generate, upload |
+| Account | profile, plan, trial status, start trial |
+| Analytics | summary, upsell funnel |
+
+The API exposes no SSE or WebSocket endpoint that accepts an API key, so this
+SDK is request/response only. See [`openapi/blog.openapi.json`][spec] for the
+machine-readable contract.
+
+[spec]: https://api.misar.io/blog/v1/openapi.json
+
+## Links
+
+- API docs — <https://docs.misar.io/blog>
+- OpenAPI spec — <https://api.misar.io/blog/v1/openapi.json>
+- Dashboard — <https://www.misar.blog/dashboard/settings/api>
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/misarblog/client.rb

@@ -0,0 +1,370 @@
+require "net/http"
+require "uri"
+require "json"
+
+require_relative "errors"
+require_relative "models"
+
+module MisarBlog
+  # Base URL for the Misar.Blog dev-API. The gateway strips `/api`, so the
+  # public base is `https://api.misar.io/blog/v1` (never add `/api`).
+  BASE_URL     = "https://api.misar.io/blog/v1".freeze
+  RETRYABLE    = [429, 500, 502, 503, 504].freeze
+  RETRY_BASE_S = 0.3
+
+  # ── Resource base ────────────────────────────────────────────────────────────
+
+  class Resource
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    # Drop nil values so optional params are never serialized.
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
+
+    def query(params)
+      compacted = compact(params)
+      compacted.empty? ? "" : "?#{URI.encode_www_form(compacted)}"
+    end
+  end
+
+  # ── Resource: AI ─────────────────────────────────────────────────────────────
+
+  class AiResource < Resource
+    # POST /ai/complete — free-form completion.
+    def complete(prompt:, system: nil, max_tokens: nil)
+      body = compact(system: system, prompt: prompt, max_tokens: max_tokens)
+      Models::AiText.new(@client.request(:post, "/ai/complete", body))
+    end
+
+    # POST /ai/titles — SEO/AEO/GEO title suggestions.
+    # action: "suggest" | "seo"
+    def titles(action:, prompt: nil, context: nil)
+      body = compact(action: action, prompt: prompt, context: context)
+      Models::TitlesResult.new(@client.request(:post, "/ai/titles", body))
+    end
+  end
+
+  # ── Resource: Articles ───────────────────────────────────────────────────────
+
+  class ArticlesResource < Resource
+    # GET /articles
+    def list(status: nil, visibility: nil, webhook_only: nil, sort: nil, limit: nil)
+      qs = query(status: status, visibility: visibility,
+                 webhook_only: webhook_only, sort: sort, limit: limit)
+      Models::ArticleList.new(@client.request(:get, "/articles#{qs}"))
+    end
+
+    # GET /articles/{slug}
+    def get(slug)
+      Models::Article.new(@client.request(:get, "/articles/#{escape(slug)}"))
+    end
+
+    # POST /articles — publish (or schedule) a new article.
+    def publish(title:, body_markdown:, tags: nil, cover_image_url: nil,
+                schedule_at: nil, visibility: nil)
+      body = compact(title: title, body_markdown: body_markdown, tags: tags,
+                     cover_image_url: cover_image_url, schedule_at: schedule_at,
+                     visibility: visibility)
+      Models::Article.new(@client.request(:post, "/articles", body))
+    end
+
+    # PATCH /articles/{slug} — update an existing article.
+    def update(slug, title: nil, body_markdown: nil, tags: nil, publish: nil)
+      body = compact(title: title, body_markdown: body_markdown,
+                     tags: tags, publish: publish)
+      Models::Article.new(@client.request(:patch, "/articles/#{escape(slug)}", body))
+    end
+
+    # POST /drafts — create an unpublished draft.
+    def create_draft(title:, body_markdown:, tags: nil)
+      body = compact(title: title, body_markdown: body_markdown, tags: tags)
+      Models::Article.new(@client.request(:post, "/drafts", body))
+    end
+
+    # GET /search — full-text search across articles/profiles/tags.
+    def search(q: nil, type: nil, tag: nil, author: nil, sort: nil,
+               from: nil, to: nil, limit: nil)
+      qs = query(q: q, type: type, tag: tag, author: author, sort: sort,
+                 from: from, to: to, limit: limit)
+      @client.request(:get, "/search#{qs}")
+    end
+
+    # GET /recommendations — related articles for a given article.
+    def recommendations(article_id:, limit: nil)
+      qs = query(article_id: article_id, limit: limit)
+      @client.request(:get, "/recommendations#{qs}")
+    end
+
+    private
+
+    def escape(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+  end
+
+  # ── Resource: Images ─────────────────────────────────────────────────────────
+
+  class ImagesResource < Resource
+    # POST /images/generate — AI cover-image generation.
+    def generate(prompt:, size: nil)
+      body = compact(prompt: prompt, size: size)
+      Models::ImageResult.new(@client.request(:post, "/images/generate", body))
+    end
+
+    # POST /images/upload — register/host an image. Accepts a raw payload Hash.
+    def upload(data = {})
+      Models::ImageResult.new(@client.request(:post, "/images/upload", data))
+    end
+  end
+
+  # ── Resource: Reactions ──────────────────────────────────────────────────────
+
+  class ReactionsResource < Resource
+    # GET /reactions?article_id=
+    def get(article_id:)
+      qs = query(article_id: article_id)
+      Models::ArticleReactions.new(@client.request(:get, "/reactions#{qs}"))
+    end
+
+    # POST /reactions
+    def add(article_id:, type:)
+      body = compact(article_id: article_id, type: type)
+      Models::ReactionResult.new(@client.request(:post, "/reactions", body))
+    end
+
+    # DELETE /reactions?article_id=&type=
+    def remove(article_id:, type:)
+      qs = query(article_id: article_id, type: type)
+      Models::ReactionResult.new(@client.request(:delete, "/reactions#{qs}"))
+    end
+  end
+
+  # ── Resource: Series ─────────────────────────────────────────────────────────
+
+  class SeriesResource < Resource
+    # GET /series
+    def list
+      Models::SeriesList.new(@client.request(:get, "/series"))
+    end
+
+    # POST /series
+    def create(title:, description: nil)
+      body = compact(title: title, description: description)
+      Models::Series.new(@client.request(:post, "/series", body))
+    end
+
+    # POST /series/{slug}/articles — add an article to a series.
+    def add_article(slug, article_slug:, position: nil)
+      body = compact(article_slug: article_slug, position: position)
+      @client.request(:post, "/series/#{escape(slug)}/articles", body)
+    end
+
+    private
+
+    def escape(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+  end
+
+  # ── Resource: Account ────────────────────────────────────────────────────────
+
+  class AccountResource < Resource
+    # GET /me
+    def profile
+      Models::Profile.new(@client.request(:get, "/me"))
+    end
+
+    # GET /plan
+    def plan
+      Models::Plan.new(@client.request(:get, "/plan"))
+    end
+
+    # GET /trial
+    def trial_status
+      Models::TrialStatus.new(@client.request(:get, "/trial"))
+    end
+
+    # POST /trial — start a trial for a gated feature.
+    def start_trial(feature: nil, ref: nil)
+      body = compact(feature: feature, ref: ref)
+      @client.request(:post, "/trial", body)
+    end
+
+    # GET /upsell-funnel
+    def upsell_funnel(days: nil, feature: nil)
+      qs = query(days: days, feature: feature)
+      @client.request(:get, "/upsell-funnel#{qs}")
+    end
+  end
+
+  # ── Resource: Analytics ──────────────────────────────────────────────────────
+
+  class AnalyticsResource < Resource
+    # GET /analytics
+    def get(days: nil)
+      qs = query(days: days)
+      Models::Analytics.new(@client.request(:get, "/analytics#{qs}"))
+    end
+  end
+
+  # ── Main Client ──────────────────────────────────────────────────────────────
+
+  # GET /comments — an article's comment thread.
+  class CommentsResource < Resource
+    # List an article's comments, newest first, replies nested one level deep.
+    # @param article_id [String]
+    # @param limit  [Integer, nil] 1..100, defaults to 20 server-side
+    # @param offset [Integer, nil] defaults to 0 server-side
+    def list(article_id:, limit: nil, offset: nil)
+      @client.request(:get, "/comments#{query(compact(
+        article_id: article_id, limit: limit, offset: offset
+      ))}")
+    end
+  end
+
+  # GET /follows — follower counts and the caller's follow state.
+  class FollowsResource < Resource
+    # @param user_id [String]
+    def status(user_id:)
+      @client.request(:get, "/follows#{query(compact(user_id: user_id))}")
+    end
+  end
+
+  class Client
+    attr_reader :ai, :articles, :images, :reactions, :series, :account, :analytics,
+                :comments, :follows
+
+    # @param api_key     [String] a `mbk_...` developer key or an OAuth 2.1 access token
+    # @param base_url    [String] override the API base (default BASE_URL)
+    # @param timeout     [Integer] per-request read timeout in seconds
+    # @param max_retries [Integer] total attempts for retryable failures (>= 1)
+    def initialize(api_key:, base_url: BASE_URL, timeout: 30, max_retries: 3)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key     = api_key
+      @base_url    = base_url.chomp("/")
+      @timeout     = timeout
+      @max_retries = [max_retries, 1].max
+
+      @ai        = AiResource.new(self)
+      @articles  = ArticlesResource.new(self)
+      @images    = ImagesResource.new(self)
+      @reactions = ReactionsResource.new(self)
+      @series    = SeriesResource.new(self)
+      @account   = AccountResource.new(self)
+      @analytics = AnalyticsResource.new(self)
+      @comments  = CommentsResource.new(self)
+      @follows   = FollowsResource.new(self)
+    end
+
+    # @param method [Symbol] :get, :post, :patch, :put, :delete
+    # @param path   [String] e.g. "/articles"
+    # @param data   [Hash]   request body (post/put/patch only)
+    # @return [Hash]  decoded JSON body (empty Hash for 204/no-content)
+    # @raise [ApiError, NetworkError]
+    def request(method, path, data = {})
+      url       = URI.parse(@base_url + "/" + path.delete_prefix("/"))
+      has_body  = !data.empty? && %i[post put patch].include?(method)
+      json_body = has_body ? JSON.generate(data) : nil
+
+      last_status = 0
+
+      @max_retries.times do |attempt|
+        final = attempt == @max_retries - 1
+        begin
+          http              = Net::HTTP.new(url.host, url.port)
+          http.use_ssl      = url.scheme == "https"
+          http.open_timeout = 10
+          http.read_timeout = @timeout
+
+          req  = build_request(method, url, json_body)
+          resp = http.request(req)
+          last_status = resp.code.to_i
+
+          # Retry on transient statuses — but on the FINAL attempt, still
+          # return/raise from the real response (never swallow the send).
+          # A plan-limit 429 is not "slow down" — retrying cannot help until
+          # the allowance resets or the plan changes, so fall straight through
+          # to parse_response and raise instead of burning the retry budget.
+          if RETRYABLE.include?(last_status) && !final && !plan_limit?(resp)
+            sleep(RETRY_BASE_S * (2**attempt))
+            next
+          end
+
+          return parse_response(resp, last_status)
+        rescue Net::OpenTimeout, Net::ReadTimeout,
+               Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError => e
+          raise NetworkError.new(e.message, e) if final
+
+          sleep(RETRY_BASE_S * (2**attempt))
+          next
+        end
+      end
+
+      raise ApiError.new(last_status, "Max retries exceeded")
+    end
+
+    private
+
+    def build_request(method, url, json_body)
+      klass = case method
+              when :get    then Net::HTTP::Get
+              when :post   then Net::HTTP::Post
+              when :patch  then Net::HTTP::Patch
+              when :put    then Net::HTTP::Put
+              when :delete then Net::HTTP::Delete
+              else raise ArgumentError, "Unsupported HTTP method: #{method}"
+              end
+
+      req = klass.new(url.request_uri)
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Content-Type"]  = "application/json"
+      req["Accept"]        = "application/json"
+      req.body = json_body if json_body
+      req
+    end
+
+    # True when the response body carries the API's plan-limit code.
+    def plan_limit?(resp)
+      body = resp.body
+      return false if body.nil? || body.empty?
+
+      decoded = JSON.parse(body)
+      decoded.is_a?(Hash) && decoded["code"] == "plan_limit_exceeded"
+    rescue JSON::ParserError
+      false
+    end
+
+    def response_headers(resp)
+      resp.each_header.to_h
+    rescue StandardError
+      {}
+    end
+
+    def parse_response(resp, status)
+      return {} if status == 204 || resp.body.nil? || resp.body.empty?
+
+      decoded = begin
+        JSON.parse(resp.body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      if status >= 400
+        msg = decoded.is_a?(Hash) ? (decoded["error"] || decoded["message"] || resp.body) : resp.body
+        if decoded.is_a?(Hash) && decoded["code"] == "plan_limit_exceeded"
+          raise PlanLimitError.new(status, msg, decoded, response_headers(resp))
+        end
+
+        raise ApiError.new(status, msg, "api_error", decoded)
+      end
+
+      decoded.is_a?(Hash) ? decoded : { "data" => decoded }
+    end
+  end
+end

data/lib/misarblog/embed.rb

@@ -0,0 +1,11 @@
+module MisarBlog
+  EMBED_BASE = "https://misar.blog".freeze
+
+  def self.embed_url(username:, slug: nil, theme: "auto")
+    url = "#{EMBED_BASE}/#{username}"
+    url = "#{url}/#{slug}" if slug && !slug.empty?
+    url = "#{url}/embed"
+    url = "#{url}?theme=#{theme}" if theme != "auto"
+    url
+  end
+end

data/lib/misarblog/errors.rb

@@ -0,0 +1,54 @@
+module MisarBlog
+  # Raised when the Misar.Blog dev-API returns a non-2xx response.
+  class ApiError < StandardError
+    attr_reader :status, :error_type, :body
+
+    def initialize(status, message, error_type = "api_error", body = nil)
+      @status = status
+      @error_type = error_type
+      @body = body
+      super("misar-blog: API error #{status} (#{error_type}): #{message}")
+    end
+  end
+
+  # Raised when the subscription attached to the API key blocks the call.
+  #
+  # The API signals this with `code: "plan_limit_exceeded"` and answers 429 when
+  # a metered allowance is exhausted (retryable once the period rolls over) or
+  # 402 when the feature is locked outright. It is raised as its own class
+  # rather than a generic 429 because retrying cannot help until the allowance
+  # resets or the plan changes — the client stops retrying on sight.
+  class PlanLimitError < ApiError
+    # @return [String, nil] the account's current plan slug
+    attr_reader :plan
+    # @return [String, nil] pricing page to send the user to
+    attr_reader :upgrade_url
+    # @return [Integer, nil] seconds until the allowance resets
+    attr_reader :retry_after
+    # @return [Hash] the full upgrade offer from the response body
+    attr_reader :upgrade
+
+    def initialize(status, message, body = nil, headers = {})
+      body    ||= {}
+      headers   = (headers || {}).transform_keys { |k| k.to_s.downcase }
+      @upgrade  = body["upgrade"].is_a?(Hash) ? body["upgrade"] : {}
+      @plan     = headers["x-misar-plan"] || @upgrade.dig("current_plan", "slug")
+      # Headers are authoritative; fall back to the offer body when a proxy has
+      # stripped them.
+      @upgrade_url = headers["x-misar-upgrade-url"] || @upgrade.dig("urls", "pricing")
+      ra           = headers["retry-after"]
+      @retry_after = ra&.match?(/\A\d+\z/) ? ra.to_i : nil
+      super(status, message, "plan_limit_exceeded", body)
+    end
+  end
+
+  # Raised for connectivity failures where no HTTP response was received.
+  class NetworkError < ApiError
+    attr_reader :cause_error
+
+    def initialize(message, cause = nil)
+      super(0, message, "network_error")
+      @cause_error = cause
+    end
+  end
+end

data/lib/misarblog/models.rb

@@ -0,0 +1,146 @@
+module MisarBlog
+  # Typed models for the Misar.Blog dev-API. Each wraps the decoded JSON body
+  # and exposes the documented fields, while `#raw` keeps the original Hash for
+  # forward-compatibility with fields added after this SDK was published.
+  module Models
+    # Base class: stores the raw Hash and offers indifferent-ish access.
+    class Base
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw || {}
+      end
+
+      def [](key)
+        @raw[key.to_s]
+      end
+
+      def to_h
+        @raw
+      end
+    end
+
+    # An article (draft, scheduled, published, ...).
+    class Article < Base
+      def id;           @raw["id"];            end
+      def slug;         @raw["slug"];          end
+      def title;        @raw["title"];         end
+      def status;       @raw["status"];        end
+      def url;          @raw["url"];           end
+      def editor_url;   @raw["editor_url"];    end
+      def excerpt;      @raw["excerpt"];       end
+      def tags;         @raw["tags"] || [];    end
+      def visibility;   @raw["visibility"];    end
+      def published_at; @raw["published_at"];  end
+      def created_at;   @raw["created_at"];    end
+    end
+
+    # Result of GET /articles.
+    class ArticleList < Base
+      def articles; (@raw["articles"] || []).map { |a| Article.new(a) }; end
+      def total;    @raw["total"];                                       end
+    end
+
+    # A series/collection of articles.
+    class Series < Base
+      def id;            @raw["id"];            end
+      def slug;          @raw["slug"];          end
+      def title;         @raw["title"];         end
+      def description;   @raw["description"];   end
+      def article_count; @raw["article_count"]; end
+      def created_at;    @raw["created_at"];    end
+    end
+
+    # Result of GET /series.
+    class SeriesList < Base
+      def series; (@raw["series"] || []).map { |s| Series.new(s) }; end
+    end
+
+    # The authenticated developer's public profile (GET /me).
+    class Profile < Base
+      def id;               @raw["id"];               end
+      def username;         @raw["username"];         end
+      def display_name;     @raw["display_name"];     end
+      def bio;              @raw["bio"];              end
+      def avatar_url;       @raw["avatar_url"];       end
+      def stripe_connected; @raw["stripe_connected"]; end
+      def profile_url;      @raw["profile_url"];      end
+      def created_at;       @raw["created_at"];       end
+    end
+
+    # A single plan-usage counter row.
+    class PlanUsage < Base
+      def feature;       @raw["feature"];       end
+      def feature_label; @raw["feature_label"]; end
+      def used;          @raw["used"];          end
+      def limit;         @raw["limit"];         end
+      def remaining;     @raw["remaining"];     end
+      def period;        @raw["period"];        end
+      def resets_at;     @raw["resets_at"];     end
+    end
+
+    # Plan + usage snapshot (GET /plan).
+    class Plan < Base
+      def plan;    @raw["plan"];                                          end
+      def slug;    (@raw["plan"] || {})["slug"];                          end
+      def name;    (@raw["plan"] || {})["name"];                          end
+      def usage;   (@raw["usage"] || []).map { |u| PlanUsage.new(u) };    end
+      def upgrade; @raw["upgrade"];                                       end
+    end
+
+    # Account-wide analytics summary (GET /analytics).
+    class Analytics < Base
+      def period_days;       @raw["period_days"];       end
+      def views;             @raw["views"];             end
+      def revenue_cents;     @raw["revenue_cents"];     end
+      def revenue_net_cents; @raw["revenue_net_cents"]; end
+      def active_subscribers; @raw["active_subscribers"]; end
+    end
+
+    # Reaction counts for an article (GET /reactions).
+    class ArticleReactions < Base
+      def article_id;     @raw["article_id"];              end
+      def counts;         @raw["counts"] || {};            end
+      def total;          @raw["total"];                   end
+      def user_reactions; @raw["user_reactions"] || [];    end
+    end
+
+    # Result of adding/removing a reaction.
+    class ReactionResult < Base
+      def success; @raw["success"]; end
+      def reacted; @raw["reacted"]; end
+    end
+
+    # Trial eligibility/status (GET /trial).
+    class TrialStatus < Base
+      def eligible;      @raw["eligible"];      end
+      def active;        @raw["active"];        end
+      def ends_at;       @raw["ends_at"];       end
+      def plan_slug;     @raw["plan_slug"];     end
+      def days;          @raw["days"];          end
+      def requires_card; @raw["requires_card"]; end
+      def reason;        @raw["reason"];        end
+    end
+
+    # A single generated title suggestion.
+    class TitleSuggestion < Base
+      def title; @raw["title"]; end
+      def hint;  @raw["hint"];  end
+    end
+
+    # Result of POST /ai/titles.
+    class TitlesResult < Base
+      def titles; (@raw["titles"] || []).map { |t| TitleSuggestion.new(t) }; end
+    end
+
+    # Result of POST /ai/complete.
+    class AiText < Base
+      def text; @raw["text"]; end
+    end
+
+    # Result of the image endpoints.
+    class ImageResult < Base
+      def url; @raw["url"]; end
+    end
+  end
+end

data/lib/misarblog.rb

@@ -0,0 +1,11 @@
+require "misarblog/embed"
+require "misarblog/errors"
+require "misarblog/models"
+require "misarblog/client"
+
+module MisarBlog
+  # Convenience constructor: MisarBlog.new(api_key: "mbk_...")
+  def self.new(**kwargs)
+    Client.new(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: misarblog
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Misar AI
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: Full-featured Ruby SDK for the Misar.Blog developer API (api.misar.io/blog/v1).
+  Covers all 25 dev-API operations with typed models, mbk_ bearer auth, and retry
+  with exponential backoff.
+email:
+- hello@misar.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/misarblog.rb
+- lib/misarblog/client.rb
+- lib/misarblog/embed.rb
+- lib/misarblog/errors.rb
+- lib/misarblog/models.rb
+homepage: https://www.misar.blog/docs/sdks/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.misar.blog/docs/sdks/ruby
+  source_code_uri: https://github.com/Misar-AI/misarblog-sdks
+  changelog_uri: https://github.com/Misar-AI/misarblog-sdks/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for Misar.Blog — articles, series, reactions, AI, analytics
+test_files: []