k9o 1.0.0

data/lib/k9o/realtime.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module K9o
+  # Realtime Subscriptions namespace (ALL-LIVE primitive).
+  #
+  # Ruby idiom per ch13 §8: #subscribe returns an Enumerator iterated via
+  # `.each`. Per ch07 §11.3 + the SDK-abstracted-primitive discipline the
+  # SDK picks the transport; SPLIT (polling) is the internal fallback. The
+  # Net::HTTP-based Ruby SDK uses SSE primary (no stdlib WebSocket);
+  # #subscribe_poll exposes the poll fallback. #replay is one-shot catch-up.
+  class Realtime
+    def initialize(config)
+      @config = config
+    end
+
+    # Subscribe via SSE transport (primary per §11.3); returns an
+    # Enumerator yielding event hashes.
+    def subscribe(topic, filter: nil)
+      slug = Studio.require_project_slug(@config, 'realtime')
+      q = { 'topic' => topic }
+      q['filter'] = JSON.dump(filter) if filter
+      HttpTransport.stream_sse(config: @config, method: 'GET',
+                               path: UrlGrammar.project_path(slug, 'realtime/subscribe'), query: q)
+    end
+
+    # One-shot historical replay per ch07 §11.2 (capped 10k server-side).
+    def replay(topic, from_sequence:, filter: nil, until_sequence: nil, limit: nil)
+      slug = Studio.require_project_slug(@config, 'realtime')
+      unless from_sequence.is_a?(Integer) && from_sequence >= 0
+        raise KError.new(
+          code: 'K9O_INVALID_FILTER',
+          message: 'replay from_sequence must be a non-negative integer',
+          context: { fromSequence: from_sequence },
+          recommendation: 'Pass the highest sequence number you have already observed (or 0 to replay from the start).'
+        )
+      end
+      body = { 'topic' => topic, 'fromSequence' => from_sequence }
+      body['filter'] = filter if filter
+      body['untilSequence'] = until_sequence if until_sequence
+      body['limit'] = limit if limit
+      HttpTransport.request(config: @config, method: 'POST',
+                            path: UrlGrammar.project_path(slug, 'realtime/replay'), body: body)
+    end
+
+    # Poll-transport fallback per §11.3 (SDK-internal SPLIT). Single batch
+    # via replay endpoint; caller loops tracking highest observed sequence.
+    def subscribe_poll(topic, from_sequence:, filter: nil)
+      replay(topic, from_sequence: from_sequence, filter: filter)
+    end
+
+    # Typed builders for the 6 closed topic families per ch07 §11.1.
+    module Topic
+      module_function
+
+      def collection(collection)
+        "collections.#{collection}.*"
+      end
+
+      def workflow_runs
+        'studio.workflows.runs.*'
+      end
+
+      def query_executed(query_id)
+        "studio.queries.executed.#{query_id}"
+      end
+
+      def dashboard_refresh(dashboard_id)
+        "studio.dashboards.refresh.#{dashboard_id}"
+      end
+
+      def function_invocations(function_id)
+        "forge.functions.invocations.#{function_id}"
+      end
+
+      def audit_org(event_family)
+        "audit.org.#{event_family}"
+      end
+    end
+  end
+end

data/lib/k9o/region.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module K9o
+  # Regional host resolution.
+  #
+  # The region-free org host `<org>.api[-staging].k9o.io` redirects GET/HEAD
+  # only and REFUSES a request carrying a body / Authorization / cookie, so
+  # credentials must go to `<org>.api[-staging]-<rgn>.k9o.io`. The SDK learns
+  # the region with ONE unauthenticated `HEAD https://<org>.api[-staging].k9o.io/`
+  # (Net::HTTP never follows redirects, so the 308 is read, not followed),
+  # takes the 308 `Location`, and caches the regional origin per client config.
+  #
+  # - Only a region-free org host is ever probed; any other base URL is used
+  #   exactly as given.
+  # - The probe carries no Authorization, cookie or default header.
+  # - The Location is trusted only if https, no userinfo, no port, and host is
+  #   exactly `<same org>.<same apex family>-<rgn>.k9o.io` (rgn = [a-z]{2}\d{2}).
+  # - Any other status or failure keeps the configured base URL. A definite
+  #   answer is cached; a network failure of the probe is not.
+  module Region
+    REGION_FREE_ORG_HOST = /\A([a-z][a-z0-9-]{1,62})\.(api|api-staging)\.k9o\.io\z/.freeze
+    REGION_CODE = /\A[a-z]{2}\d{2}\z/.freeze
+
+    module_function
+
+    # The regional origin `location` may name for `host`, or nil. Pure.
+    def origin_from_location(host, location, base)
+      m = REGION_FREE_ORG_HOST.match(host)
+      return nil if m.nil?
+
+      begin
+        u = URI.join(base.sub(%r{/+\z}, '') + '/', location)
+      rescue URI::Error, ArgumentError
+        return nil
+      end
+      return nil unless u.is_a?(URI::HTTPS) && u.scheme == 'https'
+      return nil unless u.userinfo.nil? && u.user.nil? && u.password.nil?
+      return nil unless u.port == u.default_port
+
+      org = Regexp.escape(m[1])
+      apex = Regexp.escape(m[2])
+      h = u.host.to_s.downcase
+      r = /\A#{org}\.#{apex}-([a-z0-9]+)\.k9o\.io\z/.match(h)
+      return nil if r.nil? || !REGION_CODE.match?(r[1])
+
+      "https://#{h}"
+    end
+
+    # The origin requests for this client go to: the cached regional origin
+    # once learned, else the configured base URL. Never raises.
+    def resolve_origin(config)
+      config.region_mutex.synchronize do
+        cached = config.regional_origin
+        return cached unless cached.nil?
+
+        origin, cacheable = probe(config)
+        config.regional_origin = origin if cacheable
+        origin
+      end
+    end
+
+    def probe(config)
+      configured = config.base_url
+      begin
+        uri = URI.parse(configured)
+        host = uri.host.to_s.downcase
+      rescue URI::Error
+        return [configured, true]
+      end
+      return [configured, true] unless REGION_FREE_ORG_HOST.match?(host)
+
+      begin
+        probe_uri = URI.parse("#{configured.sub(%r{/+\z}, '')}/")
+        http = config.http_client || ::Net::HTTP.new(probe_uri.host, probe_uri.port)
+        http.use_ssl = (probe_uri.scheme == 'https')
+        http.read_timeout = 30
+        # Deliberately NOT built from default_headers / api_key / org slug.
+        req = ::Net::HTTP::Head.new(probe_uri.request_uri)
+        req['accept'] = '*/*'
+        res = http.request(req)
+        if res.code.to_s == '308'
+          loc = res['location']
+          origin = loc.nil? ? nil : origin_from_location(host, loc.to_s, configured)
+          return [origin, true] unless origin.nil?
+        end
+        [configured, true]
+      rescue StandardError
+        [configured, false]
+      end
+    end
+  end
+end

data/lib/k9o/storage.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module K9o
+  # `client.storage` buckets and objects (ch04 §9), against
+  # `/@<project_slug>/storage/buckets...`.
+  #
+  #   k9o.storage.create_bucket('avatars', public: false)
+  #   k9o.storage.from('avatars').upload('user/a.jpg', bytes, content_type: 'image/jpeg')
+  #   k9o.storage.from('avatars').create_signed_url('user/a.jpg', expires_in: 300)
+  #
+  # Bucket names are logical (the platform resolves the physical store).
+  # Signed URLs require an explicit `expires_in` (1..604800, no default).
+  # Not offered, by design: signed PUT upload URLs (no gateway route) and copy.
+  # Errors pass through unchanged as K9o::KError; object bytes never appear in
+  # an SDK-constructed error.
+  class Storage
+    MAX_EXPIRES_IN = 604_800
+
+    def initialize(config)
+      @config = config
+    end
+
+    # GET /@<slug>/storage/buckets
+    def list_buckets
+      HttpTransport.request(config: @config, method: 'GET', path: buckets_path)
+    end
+
+    # GET .../buckets/<name>
+    def get_bucket(name)
+      HttpTransport.request(config: @config, method: 'GET', path: bucket_path(name))
+    end
+
+    # POST .../buckets  body { name, ...options }. Options are sent as given:
+    # public, fileSizeLimit, allowedMimeTypes, versioning, deleteAfterDays,
+    # byosBindingId (snake_case keys are mapped to the wire's camelCase).
+    def create_bucket(name, public: nil, file_size_limit: nil, allowed_mime_types: nil, versioning: nil,
+                      delete_after_days: nil, byos_binding_id: nil)
+      body = { 'name' => name }
+      body['public'] = public unless public.nil?
+      body['fileSizeLimit'] = file_size_limit unless file_size_limit.nil?
+      body['allowedMimeTypes'] = allowed_mime_types unless allowed_mime_types.nil?
+      body['versioning'] = versioning unless versioning.nil?
+      body['deleteAfterDays'] = delete_after_days unless delete_after_days.nil?
+      body['byosBindingId'] = byos_binding_id unless byos_binding_id.nil?
+      HttpTransport.request(config: @config, method: 'POST', path: buckets_path, body: body)
+    end
+
+    # PATCH .../buckets/<name>. `patch` is a Hash of only the fields to change
+    # (snake_case or wire camelCase keys); an explicit nil clears a limit
+    # (fileSizeLimit, allowedMimeTypes, deleteAfterDays, byosBindingId).
+    def update_bucket(name, patch)
+      body = patch.each_with_object({}) { |(k, v), h| h[wire_key(k)] = v }
+      HttpTransport.request(config: @config, method: 'PATCH', path: bucket_path(name), body: body)
+    end
+
+    # DELETE .../buckets/<name>; `?empty=true` only when empty is true
+    # (purges the bucket's objects first).
+    def delete_bucket(name, empty: false)
+      query = empty == true ? { 'empty' => 'true' } : nil
+      HttpTransport.request(config: @config, method: 'DELETE', path: bucket_path(name), query: query)
+    end
+
+    # A handle on one bucket for object operations.
+    def from(bucket)
+      BucketHandle.new(@config, bucket)
+    end
+
+    WIRE_KEYS = {
+      'file_size_limit' => 'fileSizeLimit', 'allowed_mime_types' => 'allowedMimeTypes',
+      'delete_after_days' => 'deleteAfterDays', 'byos_binding_id' => 'byosBindingId'
+    }.freeze
+
+    def self.buckets_path(config, suffix = '')
+      slug = Studio.require_project_slug(config, 'storage')
+      UrlGrammar.project_path(slug, "storage/buckets#{suffix}")
+    end
+
+    def self.bucket_path(config, name, suffix = '')
+      invalid('bucket name must not be empty', 'bucket') unless name.is_a?(String) && !name.empty?
+      # `.` and `..` survive percent-encoding and are collapsed as dot segments
+      # by URL layers, so they would address a different route.
+      invalid('bucket name must not be a dot segment', 'bucket', 'dot_segment') if name == '.' || name == '..'
+      buckets_path(config, "/#{CGI.escape(name).gsub('+', '%20')}#{suffix}")
+    end
+
+    def self.invalid(message, field, reason = 'empty')
+      raise KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: message,
+                       context: { field: field, reason: reason })
+    end
+
+    private
+
+    def wire_key(key)
+      k = key.to_s
+      WIRE_KEYS.fetch(k, k)
+    end
+
+    def buckets_path
+      Storage.buckets_path(@config)
+    end
+
+    def bucket_path(name)
+      Storage.bucket_path(@config, name)
+    end
+
+    # Object operations on one bucket: k9o.storage.from('avatars').
+    class BucketHandle
+      def initialize(config, bucket)
+        @config = config
+        @bucket = bucket
+      end
+
+      # POST .../objects (multipart/form-data: file, path, contentType?, upsert, metadata?).
+      # `data` is a String (sent as its bytes), or an IO-like responding to #read.
+      # `upsert: false` (default) refuses to overwrite an existing path (409).
+      def upload(path, data, content_type: nil, upsert: false, metadata: nil)
+        require_object_path(path)
+        bytes = data.respond_to?(:read) ? data.read : data
+        unless bytes.is_a?(String)
+          Storage.invalid('upload data must be a String or an IO', 'data', 'type')
+        end
+        bytes = bytes.encode(Encoding::UTF_8) unless [Encoding::BINARY, Encoding::UTF_8].include?(bytes.encoding)
+        file = { name: 'file', value: bytes, filename: path.split('/').last.to_s.then { |f| f.empty? ? 'file' : f } }
+        file[:content_type] = content_type || 'application/octet-stream'
+        parts = [file, { name: 'path', value: path }]
+        parts << { name: 'contentType', value: content_type } unless content_type.nil?
+        parts << { name: 'upsert', value: upsert == true ? 'true' : 'false' }
+        parts << { name: 'metadata', value: JSON.dump(metadata) } unless metadata.nil?
+        HttpTransport.request(config: @config, method: 'POST', path: objects_path, multipart: parts)
+      end
+
+      # POST .../objects/sign { path, expiresIn, download? }. `expires_in` is
+      # required: an Integer from 1 to 604800 seconds; refused before any request.
+      def create_signed_url(path, expires_in:, download: nil)
+        require_object_path(path)
+        unless expires_in.is_a?(Integer) && expires_in >= 1 && expires_in <= MAX_EXPIRES_IN
+          raise KError.new(
+            code: 'K9O_INVALID_FIELD_VALUE',
+            message: "expires_in is required and must be an integer from 1 to #{MAX_EXPIRES_IN} seconds",
+            context: { field: 'expiresIn', reason: 'out_of_range' },
+            recommendation: 'Pass an explicit expires_in; signed URLs have no default lifetime.'
+          )
+        end
+        body = { 'path' => path, 'expiresIn' => expires_in }
+        body['download'] = download unless download.nil?
+        HttpTransport.request(config: @config, method: 'POST', path: objects_path('/sign'), body: body)
+      end
+
+      # GET .../objects, with ?prefix= only when given.
+      def list(prefix: nil)
+        query = prefix.nil? ? nil : { 'prefix' => prefix }
+        HttpTransport.request(config: @config, method: 'GET', path: objects_path, query: query)
+      end
+
+      # DELETE .../objects?path=
+      def remove(path)
+        require_object_path(path)
+        HttpTransport.request(config: @config, method: 'DELETE', path: objects_path, query: { 'path' => path })
+      end
+
+      private
+
+      def objects_path(suffix = '')
+        Storage.bucket_path(@config, @bucket, "/objects#{suffix}")
+      end
+
+      def require_object_path(path)
+        return if path.is_a?(String) && !path.empty?
+
+        Storage.invalid('object path must not be empty', 'path')
+      end
+    end
+  end
+end

data/lib/k9o/studio.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module K9o
+  # Studio namespace (workflows + dashboards).
+  # Ruby idiom per ch13 §2.1.8: snake_case + raise K9o::KError + Envelope return.
+  #
+  #   k9o.studio.workflows.list(status: 'active')
+  #   k9o.studio.dashboards.pin('dsh_x')
+  class Studio
+    attr_reader :workflows, :dashboards
+
+    def initialize(config)
+      @workflows = Workflows.new(config)
+      @dashboards = Dashboards.new(config)
+    end
+
+    def self.require_project_slug(config, surface)
+      slug = config.project_slug
+      if slug.nil? || slug.empty?
+        raise KError.new(
+          code: 'K9O_MISSING_PROJECT_CONTEXT',
+          message: "#{surface} operations require project_slug bound on the client"
+        )
+      end
+      slug
+    end
+
+    # k9o.studio.workflows.* per ch07 §9.
+    class Workflows
+      attr_reader :runs
+
+      def initialize(config)
+        @config = config
+        @runs = Runs.new(config)
+      end
+
+      def list(status: nil, trigger_type: nil, limit: nil, cursor: nil)
+        slug = Studio.require_project_slug(@config, 'studio.workflows')
+        q = {}
+        q['status'] = status if status
+        q['triggerType'] = trigger_type if trigger_type
+        q['limit'] = limit if limit
+        q['cursor'] = cursor if cursor
+        HttpTransport.request(config: @config, method: 'GET',
+                              path: UrlGrammar.project_path(slug, 'workflows'), query: q)
+      end
+
+      def create(workflow)
+        slug = Studio.require_project_slug(@config, 'studio.workflows')
+        HttpTransport.request(config: @config, method: 'POST',
+                              path: UrlGrammar.project_path(slug, 'workflows'), body: workflow)
+      end
+
+      def read(workflow_id)
+        slug = Studio.require_project_slug(@config, 'studio.workflows')
+        HttpTransport.request(config: @config, method: 'GET',
+                              path: UrlGrammar.project_path(slug, "workflows/#{encode(workflow_id)}"))
+      end
+
+      def update(workflow_id, updates)
+        slug = Studio.require_project_slug(@config, 'studio.workflows')
+        HttpTransport.request(config: @config, method: 'PATCH',
+                              path: UrlGrammar.project_path(slug, "workflows/#{encode(workflow_id)}"), body: updates)
+      end
+
+      def delete(workflow_id)
+        slug = Studio.require_project_slug(@config, 'studio.workflows')
+        HttpTransport.request(config: @config, method: 'DELETE',
+                              path: UrlGrammar.project_path(slug, "workflows/#{encode(workflow_id)}"))
+      end
+
+      # Manual-trigger a run (trigger_type=manual only) per ch07 §9.6.
+      def trigger(workflow_id, trigger_context = {})
+        slug = Studio.require_project_slug(@config, 'studio.workflows')
+        HttpTransport.request(config: @config, method: 'POST',
+                              path: UrlGrammar.project_path(slug, "workflows/#{encode(workflow_id)}/runs"),
+                              body: trigger_context)
+      end
+
+      private
+
+      def encode(s)
+        ::URI.encode_www_form_component(s)
+      end
+
+      # k9o.studio.workflows.runs.* per ch07 §9.6.
+      class Runs
+        def initialize(config)
+          @config = config
+        end
+
+        def list(workflow_id, status: nil)
+          slug = Studio.require_project_slug(@config, 'studio.workflows')
+          q = status ? { 'status' => status } : nil
+          HttpTransport.request(config: @config, method: 'GET',
+                                path: UrlGrammar.project_path(slug, "workflows/#{enc(workflow_id)}/runs"), query: q)
+        end
+
+        def read(workflow_id, run_id)
+          slug = Studio.require_project_slug(@config, 'studio.workflows')
+          HttpTransport.request(config: @config, method: 'GET',
+                                path: UrlGrammar.project_path(slug, "workflows/#{enc(workflow_id)}/runs/#{enc(run_id)}"))
+        end
+
+        def cancel(workflow_id, run_id)
+          slug = Studio.require_project_slug(@config, 'studio.workflows')
+          HttpTransport.request(config: @config, method: 'POST',
+                                path: UrlGrammar.project_path(slug, "workflows/#{enc(workflow_id)}/runs/#{enc(run_id)}/cancel"))
+        end
+
+        private
+
+        def enc(s)
+          ::URI.encode_www_form_component(s)
+        end
+      end
+    end
+
+    # k9o.studio.dashboards.* per ch04 §3.10.
+    class Dashboards
+      def initialize(config)
+        @config = config
+      end
+
+      def list(status: nil)
+        slug = Studio.require_project_slug(@config, 'studio.dashboards')
+        q = status ? { 'status' => status } : nil
+        HttpTransport.request(config: @config, method: 'GET',
+                              path: UrlGrammar.project_path(slug, 'dashboards'), query: q)
+      end
+
+      def create(dashboard)
+        slug = Studio.require_project_slug(@config, 'studio.dashboards')
+        HttpTransport.request(config: @config, method: 'POST',
+                              path: UrlGrammar.project_path(slug, 'dashboards'), body: dashboard)
+      end
+
+      def read(dashboard_id)
+        slug = Studio.require_project_slug(@config, 'studio.dashboards')
+        HttpTransport.request(config: @config, method: 'GET',
+                              path: UrlGrammar.project_path(slug, "dashboards/#{enc(dashboard_id)}"))
+      end
+
+      def update(dashboard_id, updates)
+        slug = Studio.require_project_slug(@config, 'studio.dashboards')
+        HttpTransport.request(config: @config, method: 'PATCH',
+                              path: UrlGrammar.project_path(slug, "dashboards/#{enc(dashboard_id)}"), body: updates)
+      end
+
+      def delete(dashboard_id)
+        slug = Studio.require_project_slug(@config, 'studio.dashboards')
+        HttpTransport.request(config: @config, method: 'DELETE',
+                              path: UrlGrammar.project_path(slug, "dashboards/#{enc(dashboard_id)}"))
+      end
+
+      def pin(dashboard_id)
+        slug = Studio.require_project_slug(@config, 'studio.dashboards')
+        HttpTransport.request(config: @config, method: 'POST',
+                              path: UrlGrammar.project_path(slug, "dashboards/#{enc(dashboard_id)}/pin"))
+      end
+
+      def unpin(dashboard_id)
+        slug = Studio.require_project_slug(@config, 'studio.dashboards')
+        HttpTransport.request(config: @config, method: 'POST',
+                              path: UrlGrammar.project_path(slug, "dashboards/#{enc(dashboard_id)}/unpin"))
+      end
+
+      private
+
+      def enc(s)
+        ::URI.encode_www_form_component(s)
+      end
+    end
+  end
+end

data/lib/k9o/url_grammar.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module K9o
+  # URL grammar v2.5.68 helpers.
+  module UrlGrammar
+    SLUG_RE = /\A[a-z][a-z0-9-]{1,62}\z/
+
+    # Bare platform apex hosts org-subdomain derivation applies to —
+    # production and staging share the <org_slug>.<apex> wire-routing
+    # scheme (confirmed live). A third apex needs the same confirmation
+    # before joining this set.
+    ORG_DERIVABLE_APEXES = %w[api.k9o.io api-staging.k9o.io].freeze
+
+    module_function
+
+    def validate_base_url(base_url)
+      raise KError.new(
+        code: 'K9O_INVALID_BASE_URL',
+        message: "base_url #{base_url.inspect} is not a valid URL",
+        context: { base_url: base_url }
+      ) unless base_url.is_a?(String) && !base_url.empty?
+
+      begin
+        uri = URI.parse(base_url)
+      rescue URI::InvalidURIError => e
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} is not a valid URL: #{e.message}",
+          context: { base_url: base_url }
+        )
+      end
+
+      unless %w[http https].include?(uri.scheme)
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} uses unsupported scheme #{uri.scheme.inspect}; expected http or https",
+          context: { base_url: base_url, scheme: uri.scheme }
+        )
+      end
+      if uri.host.nil? || uri.host.empty?
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} missing host",
+          context: { base_url: base_url }
+        )
+      end
+      if uri.path && uri.path != '' && uri.path != '/'
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} must not contain a path segment; got #{uri.path.inspect}",
+          context: { base_url: base_url, path: uri.path }
+        )
+      end
+      if uri.query || uri.fragment
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} must not contain query or fragment",
+          context: { base_url: base_url }
+        )
+      end
+
+      host_port = uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+      "#{uri.scheme}://#{host_port}"
+    end
+
+    # Resolve the effective base_url. base_url is
+    # OPTIONAL — it defaults to the platform apex https://api.k9o.io. When the
+    # (validated) host is a bare apex in ORG_DERIVABLE_APEXES and org_slug is
+    # supplied, the SDK composes the canonical org-subdomain wire root
+    # https://<org_slug>.<apex> (ch01 §5.4). An explicit <org_slug> subdomain,
+    # a self-hosted / Sovereign host, or a dev host (anything not in that
+    # set) passes through unchanged — org_slug is intentionally NOT composed
+    # onto a non-apex host.
+    #
+    # Fixed 2026-08-30 (SDK-2): this used to silently ignore org_slug for
+    # api-staging.k9o.io too, not just genuine self-hosted/custom hosts,
+    # since only the literal production apex string was checked.
+    def resolve_base_url(base_url, org_slug = nil)
+      validated = validate_base_url(base_url.nil? ? 'https://api.k9o.io' : base_url)
+      uri = URI.parse(validated)
+      if ORG_DERIVABLE_APEXES.include?(uri.host) && org_slug
+        validate_slug(org_slug, 'org')
+        return "#{uri.scheme}://#{org_slug}.#{uri.host}"
+      end
+      validated
+    end
+
+    def validate_slug(slug, kind)
+      unless slug.is_a?(String) && slug.match?(SLUG_RE) && !slug.end_with?('-')
+        raise KError.new(
+          code: 'K9O_INVALID_FIELD_VALUE',
+          message: "#{kind}_slug #{slug.inspect} does not match required format ^[a-z][a-z0-9-]{1,62}$ (must not end with hyphen)",
+          context: { slug: slug, kind: kind }
+        )
+      end
+    end
+
+    def project_path(project_slug, sub_resource)
+      cleaned = sub_resource.sub(%r{\A/}, '')
+      "/@#{project_slug}/#{cleaned}"
+    end
+
+    def org_path(resource)
+      "/#{resource.sub(%r{\A/}, '')}"
+    end
+
+    def platform_path(resource)
+      "/#{resource.sub(%r{\A/}, '')}"
+    end
+  end
+end