misardev 1.0.0

data/lib/misardev/core/sse.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MisarDev
+  # One Server-Sent Event. +data+ is the JSON-decoded payload (string keys), or
+  # the raw string when it is not JSON; +event+ and +id+ are the `event:` and
+  # `id:` fields when the server sends them.
+  StreamEvent = Struct.new(:event, :data, :id, keyword_init: true)
+
+  module Core
+    # Server-Sent Events parsing.
+    #
+    # Frames are separated by a blank line (\n\n or \r\n\r\n) and may span
+    # several `data:` lines, which are joined with newlines per the SSE spec.
+    # Comment lines (`:`) are keep-alives and are skipped. The terminator
+    # payload — `[DONE]` on the OpenAI-compatible /v1/chat/completions stream —
+    # ends iteration and is never yielded. A nil terminator reads to EOF.
+    class SSE
+      SEPARATOR = /\r?\n\r?\n/.freeze
+
+      # Parse one complete frame (the text between blank lines).
+      # @return [Hash] { event:, data:, id: } — data is nil when the frame had none
+      def self.parse_frame(frame)
+        event = nil
+        id = nil
+        data = []
+        frame.split(/\r?\n/).each do |line|
+          next if line.empty? || line.start_with?(":")
+
+          idx = line.index(":")
+          field = idx ? line[0...idx] : line
+          value = idx ? line[(idx + 1)..] : ""
+          value = value[1..] if value.start_with?(" ")
+          case field
+          when "data" then data << value
+          when "event" then event = value
+          when "id" then id = value
+          end
+        end
+        { event: event, data: data.empty? ? nil : data.join("\n"), id: id }
+      end
+
+      # JSON-decode a payload when possible, else hand back the raw string.
+      def self.decode(raw)
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        raw
+      end
+
+      def initialize(terminator = "[DONE]")
+        @terminator = terminator
+        @buffer = +""
+        @done = false
+      end
+
+      # True once the terminator has been seen; stop reading.
+      def done?
+        @done
+      end
+
+      # Feed a chunk; yields each StreamEvent completed by it.
+      def feed(chunk)
+        return if @done
+
+        @buffer << chunk
+        while (m = SEPARATOR.match(@buffer))
+          frame = @buffer[0...m.begin(0)]
+          @buffer = @buffer[m.end(0)..]
+          event = to_event(frame)
+          return if @done
+          next if event.nil?
+
+          yield event
+        end
+      end
+
+      # Flush a final frame the server never terminated with a blank line.
+      def finish
+        return if @done
+
+        event = to_event(@buffer)
+        @buffer = +""
+        yield event if event && !@done
+      end
+
+      private
+
+      def to_event(frame)
+        parsed = self.class.parse_frame(frame)
+        return nil if parsed[:data].nil?
+
+        if @terminator && parsed[:data].strip == @terminator
+          @done = true
+          return nil
+        end
+        StreamEvent.new(event: parsed[:event], data: self.class.decode(parsed[:data]), id: parsed[:id])
+      end
+    end
+  end
+end

data/lib/misardev/core/transport.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "../errors"
+require_relative "../version"
+require_relative "http"
+require_relative "sse"
+
+module MisarDev
+  module Core
+    # HTTP transport shared by the generated resource layer.
+    #
+    # Everything the SDK does goes through here, and it authenticates exactly
+    # one way: the account API key (mdk_…), sent as a bearer token. There is no
+    # second credential path. What a key may do — and how much of it — is
+    # decided server-side from the subscription behind that key; the SDK carries
+    # the key and surfaces the answer rather than deciding locally.
+    class Transport
+      DEFAULT_BASE_URL = "https://api.misar.io/dev"
+
+      # Statuses worth retrying. 429 only when it is NOT a plan limit.
+      RETRYABLE = [429, 500, 502, 503, 504].freeze
+
+      # A 5xx or a dropped connection on a POST may already have done its work —
+      # started a build, charged an allowance. Only requests that are safe to
+      # repeat are retried on those; a 429 is always safe because the server
+      # refused it before doing anything.
+      IDEMPOTENT = %w[GET HEAD OPTIONS PUT DELETE].freeze
+
+      MAX_BACKOFF = 60.0
+
+      attr_reader :base_url, :max_retries, :timeout
+
+      def initialize(api_key = nil, base_url: nil, max_retries: 3, timeout: 60, http_client: nil, headers: {})
+        key = present(api_key) || present(ENV["MISARDEV_API_KEY"])
+        if key.nil?
+          raise MisarDevError.new(
+            0,
+            "A MisarDev API key is required. Pass it to the client or set MISARDEV_API_KEY. " \
+            "Create one at https://www.misar.dev/settings/api-keys.",
+            code: "missing_api_key"
+          )
+        end
+
+        @api_key = key
+        @base_url = (present(base_url) || present(ENV["MISARDEV_BASE_URL"]) || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+        @max_retries = [1, max_retries.to_i].max
+        @timeout = timeout
+        @http = http_client || NetHttpClient.new
+        @headers = headers || {}
+      end
+
+      def inspect
+        "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+      end
+
+      # ── Helpers ───────────────────────────────────────────────────────────
+
+      UNRESERVED = /[^A-Za-z0-9\-._~]/.freeze
+
+      # Percent-encode everything but RFC 3986 unreserved characters:
+      # "a b/c" → "a%20b%2Fc".
+      def self.encode(value)
+        value.to_s.b.gsub(UNRESERVED) { |c| format("%%%02X", c.ord) }
+      end
+
+      # Path-segment encoding for a path parameter.
+      def self.segment(value)
+        encode(value)
+      end
+
+      # Build a query string. nil values are dropped, booleans are sent as
+      # true/false, an Array value repeats the key.
+      def self.build_query(query)
+        return "" if query.nil? || query.empty?
+
+        pairs = []
+        query.each do |key, value|
+          (value.is_a?(Array) ? value : [value]).each do |v|
+            next if v.nil?
+
+            pairs << "#{encode(key)}=#{encode(v)}"
+          end
+        end
+        pairs.empty? ? "" : "?#{pairs.join('&')}"
+      end
+
+      # Copy of +body+ with "stream" => true, whatever key style the caller used.
+      def self.force_stream(body)
+        (body || {}).reject { |k, _| k.to_s == "stream" }.merge("stream" => true)
+      end
+
+      # Seconds to wait before the next attempt: Retry-After when sent, else
+      # exponential (250 ms · 2^attempt) with jitter; capped at 60 s.
+      def self.backoff(attempt, retry_after = nil)
+        hinted = retry_after_seconds(retry_after)
+        return [hinted, MAX_BACKOFF].min if hinted
+
+        base = 0.25 * (2**attempt)
+        [base + (rand * base * 0.25), MAX_BACKOFF].min
+      end
+
+      # Parse a Retry-After header — delta seconds or an HTTP-date — into seconds.
+      def self.retry_after_seconds(value)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        s = value.to_s.strip
+        if s.match?(/\A\d+(\.\d+)?\z/)
+          s.to_f
+        else
+          [Time.httpdate(s) - Time.now, 0].max.to_f
+        end
+      rescue ArgumentError
+        nil
+      end
+
+      # True when a body is the plan-limit refusal.
+      def self.plan_limit_body?(body)
+        body.is_a?(Hash) && body["code"] == "plan_limit_exceeded"
+      end
+
+      # Pull a human message out of the API's several error shapes.
+      def self.message_of(body, fallback)
+        if body.is_a?(Hash)
+          return body["error"] if body["error"].is_a?(String)
+          # /v1/* answers in the OpenAI shape: { error: { message, type, code } }
+          return body["error"]["message"] if body["error"].is_a?(Hash) && body["error"]["message"].is_a?(String)
+          return body["message"] if body["message"].is_a?(String)
+        end
+        return body.strip[0, 500] if body.is_a?(String) && !body.strip.empty?
+
+        fallback
+      end
+
+      def self.code_of(body)
+        return nil unless body.is_a?(Hash)
+        return body["code"] if body["code"].is_a?(String)
+        return body["error"]["code"] if body["error"].is_a?(Hash) && body["error"]["code"].is_a?(String)
+
+        nil
+      end
+
+      # Map an error response to the right typed error. Plan limits first, by code.
+      def self.error_for(status, headers, body, reason = "")
+        headers ||= {}
+        request_id = headers["x-request-id"]
+        message = message_of(body, reason.to_s.empty? ? "HTTP #{status}" : reason.to_s)
+        code = code_of(body)
+        common = { code: code, body: body, request_id: request_id }
+
+        if plan_limit_body?(body)
+          return PlanLimitError.new(
+            status, message,
+            offer: body["upgrade"].is_a?(Hash) ? body["upgrade"] : nil,
+            retry_after: retry_after_seconds(headers["retry-after"]),
+            body: body, request_id: request_id
+          )
+        end
+
+        case status
+        when 400, 422 then ValidationError.new(status, message, **common)
+        when 401 then AuthenticationError.new(status, message, **common)
+        when 403 then PermissionDeniedError.new(status, message, **common)
+        when 404 then NotFoundError.new(status, message, **common)
+        when 409 then ConflictError.new(status, message, **common)
+        when 429 then RateLimitError.new(status, message, retry_after: retry_after_seconds(headers["retry-after"]), **common)
+        else
+          status >= 500 ? ServerError.new(status, message, **common) : MisarDevError.new(status, message, **common)
+        end
+      end
+
+      # 204/empty → nil; JSON → decoded (string keys); anything else → the raw string.
+      def self.decode_body(status, text)
+        return nil if status == 204 || text.nil? || text.empty?
+
+        JSON.parse(text)
+      rescue JSON::ParserError
+        text
+      end
+
+      # ── Requests ──────────────────────────────────────────────────────────
+
+      # Send one request, retrying throttles and (for idempotent verbs)
+      # transient failures.
+      #
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDevError]
+      def request(method, path, query: nil, body: nil, headers: {})
+        verb = method.to_s.upcase
+        req = Request.new(
+          method: verb,
+          url: "#{@base_url}#{path}#{self.class.build_query(query)}",
+          headers: headers_for("application/json", headers),
+          body: encode_body(body),
+          timeout: @timeout
+        )
+
+        attempt = 0
+        loop do
+          last = attempt >= @max_retries - 1
+          begin
+            res = @http.call(req)
+          rescue MisarDevError
+            raise
+          rescue StandardError => e
+            if !last && IDEMPOTENT.include?(verb)
+              sleep(self.class.backoff(attempt))
+              attempt += 1
+              next
+            end
+            raise NetworkError, e.message.to_s.empty? ? "Network error" : e.message
+          end
+
+          decoded = self.class.decode_body(res.status, res.body)
+          return decoded if res.status >= 200 && res.status < 300
+
+          # Read the body BEFORE deciding to retry: a 429 from the rate limiter
+          # and a 429 from a spent plan allowance share a status, and only the
+          # first is worth retrying.
+          error = self.class.error_for(res.status, res.headers, decoded, res.reason)
+          raise error if error.is_a?(PlanLimitError)
+
+          retryable = RETRYABLE.include?(res.status) && (res.status == 429 || IDEMPOTENT.include?(verb))
+          raise error unless retryable && !last
+
+          sleep(self.class.backoff(attempt, res.header("retry-after")))
+          attempt += 1
+        end
+      end
+
+      # Open a Server-Sent Events stream and yield each StreamEvent; returns an
+      # Enumerator when no block is given.
+      #
+      # Never retried: a stream that fails mid-flight cannot be replayed without
+      # duplicating what the caller already consumed. A
+      # {type:"error", code:"plan_limit_exceeded", upgrade} frame is raised as a
+      # PlanLimitError, exactly as the same refusal on a plain request would be.
+      def stream(method, path, query: nil, body: nil, terminator: "[DONE]", headers: {}, &block)
+        unless block
+          return enum_for(:stream, method, path, query: query, body: body, terminator: terminator, headers: headers)
+        end
+
+        req = Request.new(
+          method: method.to_s.upcase,
+          url: "#{@base_url}#{path}#{self.class.build_query(query)}",
+          headers: headers_for("text/event-stream", headers),
+          body: encode_body(body),
+          timeout: nil # a stream has no fixed duration
+        )
+
+        user_raised = false
+        deliver = lambda do |event, res|
+          # Other error frames are the stream's own business (the build stream
+          # reports a failed step and carries on), so only the plan refusal —
+          # which no amount of reading further will fix — is raised.
+          raise self.class.error_for(402, res.headers, event.data) if self.class.plan_limit_body?(event.data)
+
+          begin
+            block.call(event)
+          rescue Exception # rubocop:disable Lint/RescueException
+            user_raised = true
+            raise
+          end
+        end
+
+        begin
+          catch(:misardev_sse_done) do
+            @http.stream(req) do |res|
+              unless res.status >= 200 && res.status < 300
+                decoded = self.class.decode_body(res.status, res.read_all)
+                raise self.class.error_for(res.status, res.headers, decoded, res.reason)
+              end
+
+              parser = SSE.new(terminator)
+              res.each_chunk do |chunk|
+                parser.feed(chunk) { |event| deliver.call(event, res) }
+                # Leave the connection rather than reading on past the terminator.
+                throw :misardev_sse_done if parser.done?
+              end
+              parser.finish { |event| deliver.call(event, res) }
+            end
+          end
+        rescue MisarDevError
+          raise
+        rescue StandardError => e
+          raise if user_raised
+
+          raise NetworkError, e.message.to_s.empty? ? "Network error" : e.message
+        end
+        nil
+      end
+
+      private
+
+      def present(value)
+        value.nil? || value.to_s.empty? ? nil : value.to_s
+      end
+
+      def encode_body(body)
+        body.nil? ? nil : JSON.generate(body)
+      end
+
+      def headers_for(accept, extra)
+        {
+          "Authorization" => "Bearer #{@api_key}",
+          "Accept" => accept,
+          "Content-Type" => "application/json",
+          "X-Misar-SDK" => "misardev-ruby/#{VERSION}"
+        }.merge(@headers).merge(extra || {})
+      end
+    end
+  end
+end

data/lib/misardev/errors.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module MisarDev
+  # Base class for every error the SDK raises.
+  #
+  # Every non-2xx answer becomes a MisarDevError; the subclasses let a caller
+  # branch on the kind of failure without parsing strings.
+  # `rescue MisarDev::MisarDevError` (or its alias `MisarDev::Error`) catches
+  # everything the SDK raises.
+  class MisarDevError < StandardError
+    # @return [Integer] HTTP status, or 0 when the request never got an answer
+    attr_reader :status
+    # @return [String, nil] machine-readable error code from the body
+    attr_reader :code
+    # @return [Object, nil] the decoded error body
+    attr_reader :body
+    # @return [String, nil] the x-request-id header, for support requests
+    attr_reader :request_id
+
+    def initialize(status, message, code: nil, body: nil, request_id: nil)
+      @status = status
+      @code = code
+      @body = body
+      @request_id = request_id
+      super(message)
+    end
+
+    # Worth retrying as-is: a throttle or a transient server condition.
+    def retryable?
+      status == 429 || (status >= 500 && status < 600)
+    end
+  end
+
+  Error = MisarDevError
+
+  # 400 / 422 — the request was malformed or failed validation.
+  class ValidationError < MisarDevError; end
+
+  # 401 — the key is missing, revoked, expired, or not a MisarDev key.
+  class AuthenticationError < MisarDevError; end
+
+  # 403 — authenticated, but not allowed to touch this resource.
+  class PermissionDeniedError < MisarDevError; end
+
+  # 404 — no such resource, or not one this key can see.
+  class NotFoundError < MisarDevError; end
+
+  # 409 — conflicts with current state (e.g. a build already running).
+  class ConflictError < MisarDevError; end
+
+  # 5xx — the API failed. Retried automatically for idempotent requests.
+  class ServerError < MisarDevError; end
+
+  # 429 that is an ordinary throttle. Wait #retry_after seconds and try again —
+  # the transport already did so max_retries times before raising this.
+  class RateLimitError < MisarDevError
+    # @return [Float, nil] seconds the server asked us to wait, when it said
+    attr_reader :retry_after
+
+    def initialize(status, message, retry_after: nil, **kwargs)
+      @retry_after = retry_after
+      super(status, message, **kwargs)
+    end
+  end
+
+  # The request never got an HTTP answer (DNS, TLS, reset, timeout). #status is 0.
+  class NetworkError < MisarDevError
+    def initialize(message)
+      super(0, message, code: "network_error")
+    end
+  end
+
+  # The subscription behind the API key blocks this call.
+  #
+  # Detected by `code: "plan_limit_exceeded"` in the body — NEVER by status,
+  # because a spent quota is a 429 that would otherwise look like an ordinary
+  # throttle. A feature not on the plan answers 402 (`feature_locked`); a spent
+  # allowance answers 429 (`quota_exhausted`). Retrying cannot help until the
+  # plan changes or the period resets, so the transport never retries it.
+  class PlanLimitError < MisarDevError
+    # @return [Hash, nil] the full upgrade offer, every field the server sent.
+    #   Render it; all copy comes from the server.
+    attr_reader :offer
+    # @return [Float, nil] seconds until a quota resets (quota_exhausted blocks)
+    attr_reader :retry_after
+
+    def initialize(status, message, offer: nil, retry_after: nil, body: nil, request_id: nil)
+      @offer = offer
+      @retry_after = retry_after
+      super(status, message, code: "plan_limit_exceeded", body: body, request_id: request_id)
+    end
+
+    # Where to send the user to unblock themselves: billing, else pricing.
+    def upgrade_url
+      urls = offer.is_a?(Hash) ? offer["urls"] : nil
+      return nil unless urls.is_a?(Hash)
+
+      urls["billing"] || urls["pricing"]
+    end
+
+    # The machine key of the limit that was hit, e.g. "api_access".
+    def feature
+      offer.is_a?(Hash) ? offer["feature"] : nil
+    end
+
+    # The slug of the plan the key is on now, e.g. "starter".
+    def current_plan
+      plan = offer.is_a?(Hash) ? offer["current_plan"] : nil
+      plan.is_a?(Hash) ? plan["slug"] : nil
+    end
+
+    # The slug of the plan the server recommends, e.g. "pro".
+    def recommended_plan
+      offer.is_a?(Hash) ? offer["recommended_plan"] : nil
+    end
+  end
+end

data/lib/misardev/generated/account.rb

@@ -0,0 +1,72 @@
+# GENERATED by scripts/generate-sdk-resources.mjs from sdks/manifest.json.
+# Do not edit by hand — change the route, run `pnpm sdk:sync`, and regenerate.
+# frozen_string_literal: true
+
+module MisarDev
+  module Generated
+    # The `account` resource — 5 operation(s).
+    class AccountResource
+      def initialize(transport)
+        @t = transport
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      # `POST /account/api-keys`
+      #
+      # misardev:method account.createKey
+      #
+      # @param body [Hash] JSON request body
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDev::MisarDevError]
+      def create_key(body = {})
+        @t.request("POST", "/account/api-keys", body: body)
+      end
+
+      # `DELETE /account/api-keys/:keyId`
+      #
+      # misardev:method account.deleteKey
+      #
+      # @param key_id [String] path parameter `keyId`
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDev::MisarDevError]
+      def delete_key(key_id)
+        @t.request("DELETE", "/account/api-keys/#{Core::Transport.segment(key_id)}")
+      end
+
+      # `GET /account/export`
+      #
+      # misardev:method account.export
+      #
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDev::MisarDevError]
+      def export
+        @t.request("GET", "/account/export")
+      end
+
+      # `GET /account/api-keys`
+      #
+      # misardev:method account.listKeys
+      #
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDev::MisarDevError]
+      def list_keys
+        @t.request("GET", "/account/api-keys")
+      end
+
+      # `PATCH /account/api-keys/:keyId`
+      #
+      # misardev:method account.updateKey
+      #
+      # @param key_id [String] path parameter `keyId`
+      # @param body [Hash] JSON request body
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDev::MisarDevError]
+      def update_key(key_id, body = {})
+        @t.request("PATCH", "/account/api-keys/#{Core::Transport.segment(key_id)}", body: body)
+      end
+    end
+  end
+end

data/lib/misardev/generated/api_keys.rb

@@ -0,0 +1,51 @@
+# GENERATED by scripts/generate-sdk-resources.mjs from sdks/manifest.json.
+# Do not edit by hand — change the route, run `pnpm sdk:sync`, and regenerate.
+# frozen_string_literal: true
+
+module MisarDev
+  module Generated
+    # The `apiKeys` resource — 3 operation(s).
+    class ApiKeysResource
+      def initialize(transport)
+        @t = transport
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      # `POST /api-keys`
+      #
+      # misardev:method apiKeys.create
+      #
+      # @param body [Hash] JSON request body
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDev::MisarDevError]
+      def create(body = {})
+        @t.request("POST", "/api-keys", body: body)
+      end
+
+      # `DELETE /api-keys`
+      #
+      # misardev:method apiKeys.delete
+      #
+      # @param body [Hash] JSON request body
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDev::MisarDevError]
+      def delete(body = {})
+        @t.request("DELETE", "/api-keys", body: body)
+      end
+
+      # `GET /api-keys`
+      #
+      # misardev:method apiKeys.list
+      #
+      # @param query [Hash] optional query parameters (limit, offset); nils are dropped
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDev::MisarDevError]
+      def list(query = {})
+        @t.request("GET", "/api-keys", query: query)
+      end
+    end
+  end
+end

data/lib/misardev/generated/audit.rb

@@ -0,0 +1,28 @@
+# GENERATED by scripts/generate-sdk-resources.mjs from sdks/manifest.json.
+# Do not edit by hand — change the route, run `pnpm sdk:sync`, and regenerate.
+# frozen_string_literal: true
+
+module MisarDev
+  module Generated
+    # The `audit` resource — 1 operation(s).
+    class AuditResource
+      def initialize(transport)
+        @t = transport
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      # `GET /audit`
+      #
+      # misardev:method audit.list
+      #
+      # @return [Hash, Array, String, nil] decoded JSON, a raw string, or nil
+      # @raise [MisarDev::MisarDevError]
+      def list
+        @t.request("GET", "/audit")
+      end
+    end
+  end
+end