misarblog 1.1.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 668bfc444b17b3b94fcf0cee95e32d9b4666c8e592f2620e4bb1ca84900d96fc
-  data.tar.gz: 5eab33effad1e6be69d8c8c6f7585afbc87b0b8031a05f030046256f5b2b74f7
+  metadata.gz: c8085dfc4b323a9b12d169e1e5a5f28a45bd28511c239f1a7d318bdb8c1d0db0
+  data.tar.gz: 17064b11fcb64cb83755c8d13fd5475b21edad5680da643b50f6c9e41c3a0dee
 SHA512:
-  metadata.gz: '09713e47a720fb3028f62d13fb14b9650b7f079bac11f90a9576376e7d45454d8f90e68cf04f019f680916c7a8d809589e690adeec32c5f94ef36681a3697221'
-  data.tar.gz: e2475931a76cdbbbbd1f388e66ad9197d7f48ffd49924f321ffe5e4d7674e69b0f5732344b0bbe5e386a6a49cb8b9a7257233b2e8661daac61b93aa98b7c75c5
+  metadata.gz: e586d6906800b2fd4917ee3468d3e8187d4f7e991d8e57af09a7f5f30d076439acddffa1df8ef9eb0075c2a59389164c09afedecc3a74d4320c688c4bc8c9445
+  data.tar.gz: 8934679336eafb88534627b17d73760f8f6d2f8c2fc33766366b57d0d8ffb5ca6eec44679eba5acdc74907df5aa060a68ede2f839f0d451bf9bec31dd02cd891

data/README.md

@@ -1,6 +1,17 @@
 # Misar.Blog Ruby SDK
 
-Official Ruby client for the Misar.Blog developer API. Standard library only, retry with back-off.
+> The official Ruby client for the Misar.Blog developer API.
+
+[![gem](https://img.shields.io/gem/v/misarblog)](https://rubygems.org/gems/misarblog) [![Ruby](https://img.shields.io/badge/ruby-%3E%3D2.7-CC342D)](https://www.ruby-lang.org) [![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+**9 resource groups · 25 operations · standard library only (net/http)**
+
+Works with any Ruby 2.7+ program that needs to drive a
+[Misar.Blog](https://www.misar.blog) account: automating publishing, syncing a
+blog out of CI or another CMS, or building a reader, dashboard or integration on
+top of the API at `https://api.misar.io/blog/v1`.
+
+---
 
 ## Install
 
@@ -8,74 +19,273 @@ Official Ruby client for the Misar.Blog developer API. Standard library only, re
 gem install misarblog
 ```
 
-## Quick start
+Or in a `Gemfile`:
+
+```ruby
+gem "misarblog", "~> 1.1"
+```
+
+Ruby 2.7+.
+
+---
+
+## Authentication
+
+Mint a key at <https://www.misar.blog/dashboard/settings/api>. Keys are prefixed
+`mbk_`; an OAuth 2.1 access token works on the same header. Key management
+`MisarBlog.new(api_key:, base_url:, timeout:, max_retries:)` is a shorthand that
+delegates to `MisarBlog::Client.new`; the key is sent as
+`Authorization: Bearer`. See the first example below. The full request/response
+contract is published as an OpenAPI document at
+<https://api.misar.io/blog/v1/openapi.json>.
+
+---
+
+## API surface
+
+| Resource | Method | Endpoint | What it does |
+| --- | --- | --- | --- |
+| `articles` | `list` | `GET /articles` | list your articles, filtered by status/visibility/sort |
+| `articles` | `get` | `GET /articles/{slug}` | fetch one article by slug or UUID, full Markdown body |
+| `articles` | `publish` | `POST /articles` | publish or schedule an article from Markdown |
+| `articles` | `update` | `PATCH /articles/{slug}` | update title/body/tags in place; `publish: true` flips a draft live |
+| `articles` | `create_draft` | `POST /drafts` | save a draft without publishing |
+| `articles` | `search` | `GET /search` | full-text search across articles, profiles and tags |
+| `articles` | `recommendations` | `GET /recommendations` | related articles for an article id |
+| `series` | `list` | `GET /series` | list your series |
+| `series` | `create` | `POST /series` | create a series |
+| `series` | `add_article` | `POST /series/{slug}/articles` | add an article to a series at a position |
+| `reactions` | `get` | `GET /reactions` | reaction counts and the caller's own reactions |
+| `reactions` | `add` | `POST /reactions` | add a `like` / `clap` / `bookmark` |
+| `reactions` | `remove` | `DELETE /reactions` | remove a reaction |
+| `comments` | `list` | `GET /comments` | an article's comment thread, newest first, replies one level deep |
+| `follows` | `status` | `GET /follows` | follower/following counts and whether the key's owner follows |
+| `ai` | `complete` | `POST /ai/complete` | free-form system + user completion |
+| `ai` | `titles` | `POST /ai/titles` | SEO/AEO/GEO title suggestions (`seo` from a keyword, `suggest` from copy) |
+| `images` | `generate` | `POST /images/generate` | AI cover image (`1024x1024`, `1792x1024`, `1024x1792`) |
+| `images` | `upload` | `POST /images/upload` | upload an image to the CDN |
+| `account` | `profile` | `GET /me` | the authenticated creator profile |
+| `account` | `plan` | `GET /plan` | live plan and per-feature quota |
+| `account` | `trial_status` | `GET /trial` | whether a self-serve trial is active |
+| `account` | `start_trial` | `POST /trial` | start a self-serve trial |
+| `account` | `upsell_funnel` | `GET /upsell-funnel` | per-feature upsell funnel (platform-admin keys only; a creator key gets 403) |
+| `analytics` | `get` | `GET /analytics` | views, gross/net revenue, active subscribers for trailing N days |
+
+Note the two groupings that differ from the other Misar.Blog SDKs: profile,
+plan, trial and upsell all hang off `account`, and the analytics summary is
+`analytics.get` rather than `analytics.summary`.
+
+---
+
+## What's in the package
+
+| Item | What it is |
+| --- | --- |
+| `MisarBlog::Client` | The client. `MisarBlog.new(api_key:, base_url:, timeout: 30, max_retries: 3)` is the shorthand constructor. Resource readers: `articles`, `series`, `reactions`, `comments`, `follows`, `ai`, `images`, `account`, `analytics`. |
+| Errors | `MisarBlog::ApiError`, `MisarBlog::PlanLimitError`, `MisarBlog::NetworkError`. |
+| `MisarBlog.embed_url(username:, slug:, theme:)` | Pure string building for public embeds. |
+| `MisarBlog::Models` | `Article`, `ArticleList`, `Series`, `SeriesList`, `Profile`, `Plan`, `PlanUsage`, `Analytics`, `ArticleReactions`, `ReactionResult`, `TrialStatus`, `TitlesResult`, `TitleSuggestion`, `AiText`, `ImageResult`. Each wraps the decoded body: named readers for the documented fields, `#[]` for string-key access, and `#raw` / `#to_h` for the untouched Hash, so a field the API adds after this release is still reachable. |
+| `client.request(method, path, data)` | Public, so an endpoint this SDK does not wrap yet is still one call away. |
+
+**Not everything is modelled.** `comments.list`, `follows.status`,
+`articles.search`, `articles.recommendations`, `account.start_trial` and
+`account.upsell_funnel` return the plain decoded `Hash` with string keys.
+
+**Transport.** Standard library only — `net/http`, `uri`, `json`; no runtime
+gem dependencies. Base URL `https://api.misar.io/blog/v1`; the key goes on
+`Authorization: Bearer`. Statuses 429/500/502/503/504 and connection failures
+are retried up to `max_retries` attempts (default 3) with exponential back-off
+from 300 ms; the final attempt is always surfaced. Open timeout 10 s, read
+timeout `timeout:` (default 30 s). A `204` or empty body returns `{}`.
+
+**No streaming or webhooks.** Every operation is a single request/response. No
+SSE or WebSocket endpoint accepts an API key, and the API has no webhook
+registration route — `webhook_only` is an article *visibility* value, not a
+subscription.
+
+---
+
+## Examples
+
+### Authenticate and publish
 
 ```ruby
 require "misarblog"
 
-blog = MisarBlog.new(api_key: "mbk_...")
+blog = MisarBlog.new(api_key: ENV.fetch("MISARBLOG_API_KEY"))
 
 me = blog.account.profile
-thread = blog.comments.list(article_id: "article-id", limit: 50)
-follows = blog.follows.status(user_id: me["id"])
+puts "authenticated as @#{me.username}"
 
-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}"
+article = blog.articles.publish(
+  title: "Shipping a blog from CI",
+  body_markdown: "# Shipping a blog from CI\n\nMarkdown in, article out.",
+  tags: %w[ci automation]
+)
+puts article.url
+```
+
+### Publish (or schedule) an article
+
+```ruby
+article = blog.articles.publish(
+  title: "Hello, Misar",
+  body_markdown: "# Hello\n\nFirst post.",
+  tags: ["intro"],
+  cover_image_url: "https://cdn.example.com/cover.png",
+  visibility: "public",                # public | subscribers | paid | private | webhook_only
+  schedule_at: "2026-09-01T09:00:00Z"  # omit to publish immediately
+)
+puts "#{article.slug} #{article.status} #{article.url}"
+```
+
+`title:` and `body_markdown:` are required keywords; every other keyword is
+dropped from the request body when left nil.
+
+### Save a draft
+
+```ruby
+draft = blog.articles.create_draft(
+  title: "Work in progress",
+  body_markdown: "Notes so far…",
+  tags: ["draft"]
+)
+puts draft.editor_url # open in the Misar.Blog editor
+```
+
+### List your articles
+
+```ruby
+result = blog.articles.list(status: "published", limit: 20)
+result.articles.each { |a| puts "#{a.slug} #{a["view_count"]}" }
+puts "#{result.articles.size} of #{result.total}"
+```
+
+`status:` accepts `draft`, `published`, `scheduled`, `archived` or `flagged`;
+`visibility:`, `webhook_only:` and `sort:` narrow it further. `Article` exposes
+the common fields as readers and everything else through `#[]` or `#raw`.
+
+### Update an article — and publish a draft
+
+```ruby
+updated = blog.articles.update(
+  "work-in-progress",
+  title: "Finished at last",
+  body_markdown: "The complete post.",
+  publish: true # flips a draft to published in the same call
+)
+puts "#{updated.status} #{updated.published_at}"
+```
+
+The slug is positional; everything else is a keyword, and omitted keywords are
+left out of the body so those fields stay unchanged.
+
+### Read an article's comment thread
+
+```ruby
+thread = blog.comments.list(article_id: article.id, limit: 50, offset: 0)
+thread["comments"].each do |c|
+  puts "@#{c["user"]["username"]}: #{c["content"]} (#{c["reply_count"]} replies)"
 end
+puts "#{thread["totalCount"]} #{thread["hasMore"]}"
 ```
 
-## Authentication and plan gating
+This one returns a plain Hash, not a model. Leave `limit:`/`offset:` out to take
+the server defaults of 20 (max 100) and 0.
 
-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.
+### Read and add reactions
 
-Feature access and throughput follow the subscription attached to that key:
+```ruby
+counts = blog.reactions.get(article_id: article.id)
+puts "#{counts.counts["clap"]} #{counts.total} #{counts.user_reactions}"
 
-| 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 |
+blog.reactions.add(article_id: article.id, type: "clap")    # like | clap | bookmark
+blog.reactions.remove(article_id: article.id, type: "clap")
+```
 
-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.
+### Generate SEO titles
 
-## Covered operations
+```ruby
+result = blog.ai.titles(
+  action: "seo", # "seo" from a keyword, "suggest" from existing copy
+  prompt: "shipping a static blog from GitHub Actions"
+)
+result.titles.each { |t| puts "#{t.title} — #{t.hint}" }
+```
 
-All 25 key-authenticated operations:
+For `"suggest"`, pass the article text as `context:` instead of `prompt:`.
 
-| 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
+### Read the analytics summary
 
-## Links
+```ruby
+summary = blog.analytics.get(days: 30)
+puts "#{summary.views} #{summary.revenue_cents} #{summary.active_subscribers}"
+```
+
+### Generate a cover image
+
+```ruby
+image = blog.images.generate(
+  prompt: "a dark editorial illustration of a printing press",
+  size: "1792x1024"
+)
+puts image.url
+```
 
-- 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>
+`blog.images.upload(data)` posts to the CDN upload route as JSON — pass the Hash
+the API expects (a base64 `data` field). This SDK does not build a multipart
+request for you; the Go and Python clients do.
+
+### Embed a public article
+
+```ruby
+puts MisarBlog.embed_url(username: "gulshan", slug: "hello-misar", theme: "dark")
+# https://misar.blog/gulshan/hello-misar/embed?theme=dark
+```
+
+Omit `slug:` to embed the whole profile; `theme:` defaults to `"auto"`, which
+adds no query parameter.
+
+---
+
+## Errors
+
+Every failure raises. `PlanLimitError` and `NetworkError` both subclass
+`ApiError`, which subclasses `StandardError` — so a single `rescue
+MisarBlog::ApiError` catches everything from this SDK. Order narrowest-first.
+
+| Type | Raised when | Readers |
+| --- | --- | --- |
+| `ApiError` | Any non-2xx the SDK did not classify further — `400` bad payload, `401` missing/expired/revoked key, `403` the key lacks the route's scope, `404` unknown slug, plain `429` rate limit (100 req/min per key) after retries are exhausted, `5xx` after retries | `status`, `error_type`, `body` (the decoded error Hash) |
+| `PlanLimitError` | The subscription blocks the call: `429` + `code: "plan_limit_exceeded"` (a metered allowance is spent) or `402` (the feature is not on this plan). **Never retried** — retrying cannot help until the allowance resets or the plan changes | `plan`, `upgrade_url`, `retry_after`, `upgrade` |
+| `NetworkError` | The request never reached the API — DNS, TLS, connection refused/reset, open or read timeout — on the final attempt | `cause_error`; `status` is `0` |
+
+```ruby
+begin
+  blog.ai.complete(prompt: "Draft an intro paragraph")
+rescue MisarBlog::PlanLimitError => e
+  # Route the reader to checkout instead of reporting a bare failure.
+  puts "#{e.plan} plan is out of credits — upgrade at #{e.upgrade_url}"
+rescue MisarBlog::NetworkError => e
+  puts "could not reach the API: #{e.cause_error}"
+rescue MisarBlog::ApiError => e
+  puts "#{e.status} #{e.body && e.body["required_scope"]}"
+end
+```
+
+The 403 scope details are not promoted to named readers here — read
+`required_scope` and `granted_scopes` off `e.body`. If a failure lands in the
+wrong class, file it at <https://github.com/Misar-AI/misarblog-sdks/issues>.
+
+---
+
+## Links
 
-## License
+- Website — https://www.misar.blog
+- App — https://www.misar.blog
+- Parent — https://misar.io
+- Documentation — https://docs.misar.io/blog
+- Source — https://github.com/Misar-AI/misarblog-sdks
+- RubyGems — https://rubygems.org/gems/misarblog
 
-MIT — see [LICENSE](LICENSE).
+MIT © [Misar AI](https://misar.io)

data/lib/misarblog/client.rb

@@ -347,7 +347,10 @@ module MisarBlog
     end
 
     def parse_response(resp, status)
-      return {} if status == 204 || resp.body.nil? || resp.body.empty?
+      # Only a *successful* empty body means "no content". An error with an empty
+      # body — a bare 401, or anything a proxy stripped — must still raise, or the
+      # caller reads a failure as an empty result set.
+      return {} if status < 400 && (status == 204 || resp.body.nil? || resp.body.empty?)
 
       decoded = begin
         JSON.parse(resp.body)
@@ -357,6 +360,8 @@ module MisarBlog
 
       if status >= 400
         msg = decoded.is_a?(Hash) ? (decoded["error"] || decoded["message"] || resp.body) : resp.body
+        # A stripped body leaves nothing to report; fall back to the reason phrase.
+        msg = resp.message.to_s if msg.nil? || msg.empty?
         if decoded.is_a?(Hash) && decoded["code"] == "plan_limit_exceeded"
           raise PlanLimitError.new(status, msg, decoded, response_headers(resp))
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: misarblog
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Misar AI
@@ -38,9 +38,14 @@ dependencies:
     - - "~>"
       - !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.
+description: 'Ruby client for the developer API of Misar.Blog (misar.blog), a hosted
+  blogging platform. Publish or schedule Markdown articles, save and update drafts,
+  group articles into series, read comment threads, reactions and follows, pull an
+  analytics summary and live plan/quota state, generate SEO/AEO/GEO title suggestions,
+  completions and AI cover images, search articles, profiles and tags, and build public
+  iframe embed URLs — all 25 key-authenticated operations. Standard library only (net/http):
+  mbk_ bearer auth, retry with exponential back-off, and a typed PlanLimitError carrying
+  the upgrade URL.'
 email:
 - hello@misar.io
 executables: []
@@ -55,13 +60,15 @@ files:
 - lib/misarblog/embed.rb
 - lib/misarblog/errors.rb
 - lib/misarblog/models.rb
-homepage: https://www.misar.blog/docs/sdks/ruby
+homepage: https://www.misar.blog
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://www.misar.blog/docs/sdks/ruby
+  homepage_uri: https://www.misar.blog
   source_code_uri: https://github.com/Misar-AI/misarblog-sdks
   changelog_uri: https://github.com/Misar-AI/misarblog-sdks/releases
+  documentation_uri: https://docs.misar.io/blog
+  bug_tracker_uri: https://github.com/Misar-AI/misarblog-sdks/issues
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -80,5 +87,7 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Official Ruby SDK for Misar.Blog — articles, series, reactions, AI, analytics
+summary: 'Ruby client for misar.blog, a hosted blogging platform: publish and schedule
+  Markdown articles, manage drafts and series, read comments, reactions, follows and
+  analytics, and generate AI titles and covers.'
 test_files: []