k9o 1.2.0 → 1.4.0

data/lib/k9o/ai.rb

@@ -7,6 +7,8 @@ module K9o
   # Wire (project-plane):
   #   POST /@<slug>/ai/embeddings  body { model?, input: String | [String] }
   #   -> { data: { embeddings: [[Float]], model:, dimensions: }, meta }
+  #   POST /@<slug>/ai/generate    body { prompt:, model?, maxTokens?, temperature?, usageType? }
+  #   -> { data: { modelId:, content:, finishReason:, usage:, usageType: }, meta }
   #
   # Bounds are enforced by the gateway, not here. The SDK sends `input`
   # exactly as given and never puts it in an error.
@@ -24,5 +26,18 @@ module K9o
       HttpTransport.request(config: @config, method: 'POST',
                             path: UrlGrammar.project_path(slug, 'ai/embeddings'), body: body)
     end
+
+    # POST /@<slug>/ai/generate — one synchronous text generation (verb sugar over compute.llms.invoke).
+    # Only the fields given are sent; without `model` the gateway uses the org's default LLM.
+    def generate(prompt, model: nil, max_tokens: nil, temperature: nil, usage_type: nil)
+      slug = Studio.require_project_slug(@config, 'ai')
+      body = { 'prompt' => prompt }
+      body['model'] = model unless model.nil?
+      body['maxTokens'] = max_tokens unless max_tokens.nil?
+      body['temperature'] = temperature unless temperature.nil?
+      body['usageType'] = usage_type unless usage_type.nil?
+      HttpTransport.request(config: @config, method: 'POST',
+                            path: UrlGrammar.project_path(slug, 'ai/generate'), body: body)
+    end
   end
 end

data/lib/k9o/approvals.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module K9o
+  # Shared argument checks for the approvals, approval policy and schema namespaces. A bad value raises
+  # K9o::KError K9O_INVALID_FIELD_VALUE before any request is sent.
+  module ApprovalChecks
+    module_function
+
+    def invalid(message, context = {})
+      KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: message, context: context)
+    end
+
+    def check_limit(limit)
+      return if limit.nil?
+      return if limit.is_a?(Integer) && limit >= 1 && limit <= 200
+
+      raise invalid('limit must be a whole number from 1 to 200', limit: limit)
+    end
+
+    def id_segment(value, what)
+      raise invalid("#{what} id must be a non-empty string") unless value.is_a?(String) && !value.empty?
+
+      ::URI.encode_www_form_component(value).gsub('+', '%20')
+    end
+
+    def reason!(reason)
+      raise invalid('reason is required and must be a non-empty string') unless reason.is_a?(String) && !reason.strip.empty?
+
+      reason
+    end
+
+    def predicate!(value, field)
+      raise invalid("#{field} must be a predicate object") unless value.is_a?(Hash)
+
+      value
+    end
+
+    def enum!(value, allowed, field)
+      text = value.is_a?(Symbol) ? value.to_s : value
+      return text if allowed.include?(text)
+
+      raise invalid("#{field} must be #{allowed.map { |a| "\"#{a}\"" }.join(', ')}", field.to_sym => value)
+    end
+  end
+
+  # Pending-change queue: k9o.approvals.*
+  #
+  #   list(status:, limit:)                GET  /@<slug>/pending-approvals
+  #   get(id)                              GET  /@<slug>/pending-approvals/<id>
+  #   approve(id, reason:)                 POST /@<slug>/pending-approvals/<id>/approve
+  #   reject(id, reason:)                  POST /@<slug>/pending-approvals/<id>/reject
+  #   bulk(action:, criteria:, reason:)    POST /@<slug>/pending-approvals/bulk
+  #
+  # +list+ is not paginated: it returns the newest +limit+ changes (1 to 200, default 50). +approve+ can answer 200
+  # with +status+ still +pending_approval+: the approval is recorded and more approvers are needed. +bulk+ skips rows
+  # that fail without a report, so compare +affectedIds+ with what you intended.
+  class Approvals
+    def initialize(config)
+      @config = config
+    end
+
+    # Pending changes, newest first. Only +limit+ caps the result.
+    def list(status: nil, limit: nil)
+      ApprovalChecks.check_limit(limit)
+      query = {}
+      query['status'] = status.to_s unless status.nil?
+      query['limit'] = limit unless limit.nil?
+      call('GET', path, query: query)
+    end
+
+    # One pending change. Members who are not queue admins can read only their own.
+    def get(id)
+      call('GET', path("/#{ApprovalChecks.id_segment(id, 'approval')}"))
+    end
+
+    # Approve a pending change. Read +status+ on the answer: +pending_approval+ means more approvers are needed.
+    def approve(id, reason: nil)
+      seg = ApprovalChecks.id_segment(id, 'approval')
+      call('POST', path("/#{seg}/approve"), body: reason.nil? ? {} : { 'reason' => reason })
+    end
+
+    # Reject a pending change. +reason+ is required and must not be empty.
+    def reject(id, reason:)
+      seg = ApprovalChecks.id_segment(id, 'approval')
+      call('POST', path("/#{seg}/reject"), body: { 'reason' => ApprovalChecks.reason!(reason) })
+    end
+
+    # Approve or reject every pending change matching +criteria+ (a predicate Hash). +reason+ is required to reject.
+    # Rows that fail are skipped without a report: compare +affectedIds+ with what you intended.
+    def bulk(action:, criteria:, reason: nil)
+      act = ApprovalChecks.enum!(action, %w[approve reject], 'action')
+      body = { 'action' => act, 'criteria' => ApprovalChecks.predicate!(criteria, 'criteria') }
+      if act == 'reject'
+        body['reason'] = ApprovalChecks.reason!(reason)
+      elsif !reason.nil?
+        body['reason'] = reason
+      end
+      call('POST', path('/bulk'), body: body)
+    end
+
+    private
+
+    def call(method, route, body: nil, query: nil)
+      HttpTransport.request(config: @config, method: method, path: route, body: body, query: query)
+    end
+
+    def path(tail = '')
+      UrlGrammar.project_path(Studio.require_project_slug(@config, 'approvals'), "pending-approvals#{tail}")
+    end
+  end
+
+  # Approval policies: k9o.approval_policies.*
+  #
+  #   list                                              GET    /@<slug>/approval-policies
+  #   create(collection:, operation:, action:, predicate:)  POST   /@<slug>/approval-policies
+  #   delete(id)                                        DELETE /@<slug>/approval-policies/<id>
+  class ApprovalPolicies
+    COLLECTION_RE = /\A[a-zA-Z_][a-zA-Z0-9_]{0,62}\z/.freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    # All policies, oldest first. The first matching policy for a write decides.
+    def list
+      call('GET', path)
+    end
+
+    # Create a policy. Identical policies are not de-duplicated.
+    def create(collection:, operation:, action:, predicate:)
+      unless collection.is_a?(String) && COLLECTION_RE.match?(collection)
+        raise ApprovalChecks.invalid('collection must match ^[a-zA-Z_][a-zA-Z0-9_]{0,62}$', collection: collection)
+      end
+
+      body = {
+        'collection' => collection,
+        'operation' => ApprovalChecks.enum!(operation, %w[insert update delete], 'operation'),
+        'action' => ApprovalChecks.enum!(action, %w[auto_approve queue], 'action'),
+        'predicate' => ApprovalChecks.predicate!(predicate, 'predicate')
+      }
+      call('POST', path, body: body)
+    end
+
+    # Delete a policy; the answer is { 'id' => ... }.
+    def delete(id)
+      call('DELETE', path("/#{ApprovalChecks.id_segment(id, 'policy')}"))
+    end
+
+    private
+
+    def call(method, route, body: nil)
+      HttpTransport.request(config: @config, method: method, path: route, body: body)
+    end
+
+    def path(tail = '')
+      UrlGrammar.project_path(Studio.require_project_slug(@config, 'approval_policies'), "approval-policies#{tail}")
+    end
+  end
+end

data/lib/k9o/audit.rb

@@ -2,27 +2,25 @@
 
 module K9o
   # Project-plane audit log namespace — k9o.audit.*.
-  # Distinct from k9o.org.audit_log + k9o.me.audit_log.
+  # Distinct from k9o.org.audit_log.
   class Audit
     def initialize(config)
       @config = config
     end
 
-    # Query the audit log (reverse-chronological; filters AND-compose).
-    # Accepts keyword filters: since/until/type/actor_id/target_kind/
-    # target_id/limit/cursor (wire camelCase mapping applied here).
-    def query(since: nil, until_: nil, type: nil, actor_id: nil,
-              target_kind: nil, target_id: nil, limit: nil, cursor: nil)
+    # GET /@<slug>/audit-log — reverse-chronological; filters AND-compose. Requires the AUDIT_READER role.
+    #   event_type: audit-event name prefix (e.g. 'data.write.access')    actor_id: filter by actor
+    #   after / before: ISO 8601 bounds (events after / before this instant)
+    #   limit: page size (bounded server-side)    cursor: from the prior response's meta.cursor.next
+    def query(event_type: nil, actor_id: nil, after: nil, before: nil, limit: nil, cursor: nil)
       slug = Studio.require_project_slug(@config, 'audit')
       q = {}
-      q['since'] = since if since
-      q['until'] = until_ if until_
-      q['type'] = type if type
-      q['actorId'] = actor_id if actor_id
-      q['targetKind'] = target_kind if target_kind
-      q['targetId'] = target_id if target_id
-      q['limit'] = limit if limit
-      q['cursor'] = cursor if cursor
+      q['eventType'] = event_type unless event_type.nil?
+      q['actorId'] = actor_id unless actor_id.nil?
+      q['after'] = after unless after.nil?
+      q['before'] = before unless before.nil?
+      q['limit'] = limit unless limit.nil?
+      q['cursor'] = cursor unless cursor.nil?
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, 'audit-log'), query: q)
     end
   end

data/lib/k9o/client.rb

@@ -3,8 +3,10 @@
 module K9o
   # The customer-facing client returned by K9o.create_client.
   class K9oClient
-    attr_reader :config, :projects, :gate, :studio, :compute, :realtime, :org,
-                :orgs, :migrations, :functions, :policies, :audit, :me, :kibo, :ai, :storage
+    include QueryMethods
+
+    attr_reader :config, :projects, :gate, :studio, :compute, :realtime, :streams, :org,
+                :approvals, :approval_policies, :schema, :orgs, :migrations, :functions, :policies, :audit, :me, :kibo, :ai, :storage
 
     def initialize(config)
       @config = config
@@ -13,6 +15,10 @@ module K9o
       @studio = Studio.new(config)
       @compute = Compute.new(config)
       @realtime = Realtime.new(config)
+      @streams = Streams.new(config)
+      @approvals = Approvals.new(config)
+      @approval_policies = ApprovalPolicies.new(config)
+      @schema = Schema.new(config)
       @org = Org.new(config)
       @orgs = Orgs.new(config)
       @migrations = Migrations.new(config)
@@ -36,17 +42,15 @@ module K9o
 
   # Factory — construct a K9oClient bound to the supplied options.
   #
-  # Per spec sample:
   #   k9o = K9o.create_client(
   #     api_key: ENV["K9O_API_KEY"],
   #     org_slug: "acme",
   #     project_slug: "member-portal",
   #   )
   #
-  # base_url is OPTIONAL. When omitted it
-  # defaults to the platform apex https://api.k9o.io; when the host is the
-  # bare apex and org_slug is set, the canonical org-subdomain wire root
-  # https://<org_slug>.api.k9o.io is composed. Any other host passes through.
+  # base_url is OPTIONAL. When omitted it defaults to the public-cloud platform host (a convenience only, never used
+  # to parse a host). When the host is a platform host (+api.<apex>+ or +api-staging.<apex>+, any apex) and org_slug
+  # is set, the org host +<org_slug>.<host>+ is composed. Any other host passes through unchanged.
   def self.create_client(base_url: nil, api_key: nil, org_slug: nil, project_slug: nil, default_headers: {}, http_client: nil)
     normalised = UrlGrammar.resolve_base_url(base_url, org_slug)
     config = HttpClientConfig.new(

data/lib/k9o/compute.rb

@@ -4,30 +4,37 @@ module K9o
   # Compute namespace (Compute LLMs registry).
   # k9o.compute.llms.*
   class Compute
-    # Curated 9-model closed enum (extensible v2.x).
+    # The curated model ids (closed enum).
     LLM_MODEL_IDS = %w[
       mistral-7b mistral-8x7b llama-3-8b llama-3-70b
       claude-3-5-sonnet gpt-4o gpt-4o-mini
       text-embedding-3-small text-embedding-3-large
     ].freeze
 
+    # Inference parameters the gateway reads (top-level body fields next to +prompt+). Snake_case spellings map to
+    # the gateway's.
+    PARAM_FIELDS = {
+      'max_tokens' => 'maxTokens', 'maxTokens' => 'maxTokens',
+      'temperature' => 'temperature',
+      'usage_type' => 'usageType', 'usageType' => 'usageType'
+    }.freeze
+
     attr_reader :llms
 
     def initialize(config)
       @llms = Llms.new(config)
     end
 
-    # k9o.compute.llms.*.
+    # k9o.compute.llms.*
     class Llms
       def initialize(config)
         @config = config
       end
 
-      def list(modality: nil)
+      # GET /@<slug>/compute/llms
+      def list
         slug = Studio.require_project_slug(@config, 'compute.llms')
-        q = modality ? { 'modality' => modality } : nil
-        HttpTransport.request(config: @config, method: 'GET',
-                              path: UrlGrammar.project_path(slug, 'compute/llms'), query: q)
+        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, 'compute/llms'))
       end
 
       def read(model_id)
@@ -36,29 +43,39 @@ module K9o
                               path: UrlGrammar.project_path(slug, "compute/llms/#{enc(model_id)}"))
       end
 
-      # Synchronous inference (PROJECT_AUTHOR/ADMIN).
+      # Synchronous inference: POST /@<slug>/compute/llms/<id>/invoke { prompt, maxTokens?, temperature?,
+      # usageType? }. +params+ takes max_tokens / temperature / usage_type (the gateway's spellings also work).
+      # The envelope's data is { 'modelId', 'content', 'finishReason', 'usage' => { 'promptTokens',
+      # 'completionTokens', 'totalTokens' }, 'usageType' }.
       def invoke(model_id, prompt:, params: nil)
         slug = Studio.require_project_slug(@config, 'compute.llms')
-        body = { 'prompt' => prompt }
-        body['params'] = params if params
         HttpTransport.request(config: @config, method: 'POST',
-                              path: UrlGrammar.project_path(slug, "compute/llms/#{enc(model_id)}/invoke"), body: body)
+                              path: UrlGrammar.project_path(slug, "compute/llms/#{enc(model_id)}/invoke"),
+                              body: invoke_body(prompt, params))
       end
 
-      # Streaming inference (SSE per-token). Returns an
-      # Enumerator of chunk hashes (Ruby idiom). Consume with
+      # Streaming inference (SSE per-token). Returns an Enumerator of chunk hashes. Consume with
       # `.each { |chunk| ... }`.
       def invoke_stream(model_id, prompt:, params: nil)
         slug = Studio.require_project_slug(@config, 'compute.llms')
-        body = { 'prompt' => prompt }
-        body['params'] = params if params
         HttpTransport.stream_sse(config: @config, method: 'POST',
                                  path: UrlGrammar.project_path(slug, "compute/llms/#{enc(model_id)}/invoke-stream"),
-                                 body: body)
+                                 body: invoke_body(prompt, params))
       end
 
       private
 
+      def invoke_body(prompt, params)
+        body = { 'prompt' => prompt }
+        (params || {}).each do |key, value|
+          wire = PARAM_FIELDS[key.to_s]
+          raise ArgumentError, "unknown inference parameter: #{key}" if wire.nil?
+
+          body[wire] = value unless value.nil?
+        end
+        body
+      end
+
       def enc(s)
         ::URI.encode_www_form_component(s)
       end

data/lib/k9o/data.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module K9o
   # Data-plane DSL.
   #
@@ -113,13 +115,77 @@ module K9o
   end
 
   class SelectBuilder < BaseBuilder
+    SEARCH_COLUMN = /\A[a-zA-Z_][a-zA-Z0-9_]{0,62}\z/.freeze
+    SEARCH_LANGUAGE = /\A[a-zA-Z_]+\z/.freeze
+    TEXT_TYPES = %w[plain phrase websearch].freeze
+    VECTOR_METRICS = %w[cosine euclidean dot].freeze
+
+    def initialize(config, collection)
+      super
+      @search = {}
+    end
+
+    # Full-text search over one text column. +type+ is "plain", "phrase" or "websearch".
+    def text_search(column, query, language: 'english', type: 'plain')
+      check_search_column(column)
+      raise search_error('text search query must be a non-empty string') unless query.is_a?(String) && !query.empty?
+      unless language.is_a?(String) && language.match?(SEARCH_LANGUAGE)
+        raise search_error('text search language must be letters and underscores only')
+      end
+
+      type = type.to_s
+      raise search_error("text search type must be one of #{TEXT_TYPES.join(', ')}") unless TEXT_TYPES.include?(type)
+
+      @search.delete('textSearchLanguage')
+      @search.delete('textSearchType')
+      @search['textSearch'] = "#{column}:#{query}"
+      @search['textSearchLanguage'] = language unless language == 'english'
+      @search['textSearchType'] = type unless type == 'plain'
+      self
+    end
+
+    # Nearest-neighbour search over one vector column; results come back closest first.
+    # +metric+ is "cosine", "euclidean" or "dot"; +limit+ is 1 to 1000 (server default 10).
+    def vector_search(column, embedding, metric: 'cosine', limit: nil)
+      check_search_column(column)
+      unless embedding.is_a?(Array) && !embedding.empty? &&
+             embedding.all? { |v| v.is_a?(Integer) || (v.is_a?(Float) && v.finite?) }
+        raise search_error('embedding must be a non-empty array of finite numbers')
+      end
+
+      metric = metric.to_s
+      raise search_error("vector metric must be one of #{VECTOR_METRICS.join(', ')}") unless VECTOR_METRICS.include?(metric)
+      unless limit.nil? || (limit.is_a?(Integer) && limit >= 1 && limit <= 1000)
+        raise search_error('vector limit must be an integer from 1 to 1000')
+      end
+
+      @search.delete('vectorMetric')
+      @search.delete('vectorLimit')
+      @search['vectorSearch'] = "#{column}:#{JSON.generate(embedding)}"
+      @search['vectorMetric'] = metric unless metric == 'cosine'
+      @search['vectorLimit'] = limit.to_s unless limit.nil?
+      self
+    end
+
     def execute
       HttpTransport.request(
         config: @config, method: 'GET',
         path: FromBuilder.collection_path(@config, @collection),
-        query: to_query
+        query: to_query.merge(@search)
       )
     end
+
+    private
+
+    def search_error(message)
+      KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: message, context: { collection: @collection })
+    end
+
+    def check_search_column(column)
+      return if column.is_a?(String) && column.match?(SEARCH_COLUMN)
+
+      raise search_error('search column must be a column name: letters, digits and underscores, starting with a letter or underscore')
+    end
   end
 
   class UpdateBuilder < BaseBuilder

data/lib/k9o/functions.rb

@@ -2,22 +2,52 @@
 
 module K9o
   # Function lifecycle namespace — k9o.functions.*.
+  #
+  # Upload the function's bytes first (+upload_artifact+ returns the +artifactKey+), then +deploy+ references that
+  # artifact. Deploy requires PROJECT_ADMIN and returns with status +deploying+; the function is ready when status
+  # flips to +active+.
   class Functions
+    ARTIFACT_CONTENT_TYPES = { 'wasm' => 'application/wasm', 'tar' => 'application/x-tar' }.freeze
+
     def initialize(config)
       @config = config
     end
 
-    def deploy(name:, runtime:, code:, tier: nil, config: nil)
+    # POST /@<slug>/functions/artifacts with the raw bytes: a WebAssembly module for the gateway tier (up to 16 MiB,
+    # +kind+ 'wasm') or an OCI image archive for the sandbox tier (up to 256 MiB, +kind+ 'tar'). Uploading the same
+    # bytes again returns the same key. The envelope's data is { 'artifactKey' => String }.
+    def upload_artifact(bytes, kind)
+      content_type = ARTIFACT_CONTENT_TYPES[kind.to_s]
+      raise ArgumentError, "kind must be 'wasm' or 'tar'" if content_type.nil?
+
+      bytes = bytes.read if bytes.respond_to?(:read)
+      raise ArgumentError, 'bytes must be a String or an IO' unless bytes.is_a?(String)
+
+      slug = require_project_slug
+      HttpTransport.request(config: @config, method: 'POST',
+                            path: UrlGrammar.project_path(slug, 'functions/artifacts'),
+                            raw_body: bytes, headers: { 'content-type' => content_type })
+    end
+
+    # POST /@<slug>/functions — deploy or redeploy from an uploaded artifact.
+    #   runtime: bun python go java kotlin dotnet swift php ruby rust tinygo zig assemblyscript
+    #   tier:    'gateway' (WebAssembly) or 'sandbox' (OCI image archive)
+    #   artifact_key: the key +upload_artifact+ returned; version: label for this deploy (1 to 64 characters)
+    def deploy(name:, runtime:, tier:, artifact_key:, version:, description: nil)
       slug = require_project_slug
-      body = { 'name' => name, 'runtime' => runtime, 'code' => code }
-      body['tier'] = tier if tier
-      body['config'] = config if config
+      body = { 'name' => name, 'runtime' => runtime, 'tier' => tier, 'artifactKey' => artifact_key,
+               'version' => version }
+      body['description'] = description unless description.nil?
       HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.project_path(slug, 'functions'), body: body)
     end
 
-    def list(status: nil)
+    # GET /@<slug>/functions (cursor pagination).
+    def list(status: nil, limit: nil, cursor: nil)
       slug = require_project_slug
-      q = status ? { 'status' => status } : nil
+      q = {}
+      q['status'] = status unless status.nil?
+      q['limit'] = limit unless limit.nil?
+      q['cursor'] = cursor unless cursor.nil?
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, 'functions'), query: q)
     end
 
@@ -26,16 +56,25 @@ module K9o
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, "functions/#{enc(name)}"))
     end
 
+    # Retire a function; its name enters a 24h cooldown.
     def delete(name)
       slug = require_project_slug
       HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.project_path(slug, "functions/#{enc(name)}"))
     end
 
-    # Invoke a function; payload passed to the runtime verbatim.
-    def invoke(name, payload)
+    # POST /@<slug>/functions/<name>/invoke. +payload+ is sent as the +payload+ field of the request body and passed
+    # to the function runtime verbatim. Optional controls: +background+ (run asynchronously), +delegation+
+    # ({ 'token' => ..., 'invokeSessionId' => ... }), +on_behalf_of+, +confined_to+.
+    def invoke(name, payload = nil, background: nil, delegation: nil, on_behalf_of: nil, confined_to: nil)
       slug = require_project_slug
+      body = {}
+      body['payload'] = payload unless payload.nil?
+      body['background'] = background unless background.nil?
+      body['delegation'] = delegation unless delegation.nil?
+      body['onBehalfOf'] = on_behalf_of unless on_behalf_of.nil?
+      body['confinedTo'] = confined_to unless confined_to.nil?
       HttpTransport.request(config: @config, method: 'POST',
-                            path: UrlGrammar.project_path(slug, "functions/#{enc(name)}/invoke"), body: payload)
+                            path: UrlGrammar.project_path(slug, "functions/#{enc(name)}/invoke"), body: body)
     end
 
     private

data/lib/k9o/gate.rb

@@ -1,18 +1,20 @@
 # frozen_string_literal: true
 
 module K9o
-  # Gate (Identity-Aware Kernel) namespace. Project-scoped.
+  # Gate (Identity-Aware Kernel) namespace. Project-scoped; the gateway closes each body to the fields shown.
   class Gate
     def initialize(config)
       @config = config
     end
 
+    # POST /@<slug>/gate/signup { email, password, displayName? }
     def sign_up(email:, password:, display_name: nil)
       body = { 'email' => email, 'password' => password }
       body['displayName'] = display_name if display_name
       HttpTransport.request(config: @config, method: 'POST', path: gate_path('signup'), body: body)
     end
 
+    # POST /@<slug>/gate/signin { email, password }
     def sign_in(email:, password:)
       HttpTransport.request(
         config: @config, method: 'POST', path: gate_path('signin'),
@@ -20,15 +22,18 @@ module K9o
       )
     end
 
-    def sign_out(refresh_token: nil)
-      body = refresh_token ? { 'refreshToken' => refresh_token } : {}
-      HttpTransport.request(config: @config, method: 'POST', path: gate_path('signout'), body: body)
+    # POST /@<slug>/gate/signout { refreshToken } — the refresh token is required (the gateway answers 400 without it).
+    def sign_out(refresh_token:)
+      HttpTransport.request(config: @config, method: 'POST', path: gate_path('signout'),
+                            body: { 'refreshToken' => refresh_token })
     end
 
+    # GET /@<slug>/gate/whoami
     def whoami
       HttpTransport.request(config: @config, method: 'GET', path: gate_path('whoami'))
     end
 
+    # POST /@<slug>/gate/refresh { refreshToken }
     def refresh_token(refresh_token:)
       HttpTransport.request(
         config: @config, method: 'POST', path: gate_path('refresh'),
@@ -36,20 +41,6 @@ module K9o
       )
     end
 
-    def verify_session
-      HttpTransport.request(config: @config, method: 'GET', path: gate_path('verify'))
-    end
-
-    # The project's hosted sign-in URL and WebAuthn rpId:
-    # GET /@<slug>/gate/hosted. Unauthenticated and cacheable; no credential is
-    # sent even when an api_key is configured. Returns an Envelope whose `data`
-    # is { 'signInUrl' => String, 'rpId' => String }. Take both values as given:
-    # an unknown org, a deleted project and a non-Gate project all answer the
-    # same 404 K9O_PROJECT_NOT_FOUND.
-    def hosted
-      HttpTransport.request(config: @config, method: 'GET', path: gate_path('hosted'), authenticated: false)
-    end
-
     private
 
     def gate_path(action)

data/lib/k9o/http_transport.rb

@@ -68,10 +68,11 @@ module K9o
     #
     # `authenticated: false` sends NO credential: no api_key bearer, and any
     # authorization / cookie header from `default_headers` or `headers:` is dropped.
-    def request(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil)
+    def request(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil,
+                raw_body: nil)
       retry_with_backoff(method, config.retry_config || RetryConfig.default) do
         request_once(config: config, method: method, path: path, body: body, query: query, headers: headers,
-                     authenticated: authenticated, multipart: multipart)
+                     authenticated: authenticated, multipart: multipart, raw_body: raw_body)
       end
     end
 
@@ -116,7 +117,8 @@ module K9o
     end
 
     # Single-attempt request. `request` wraps this in retry-with-backoff.
-    def request_once(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil)
+    def request_once(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil,
+                     raw_body: nil)
       url = "#{Region.resolve_origin(config).sub(%r{/\z}, '')}#{path}"
       if query && !query.empty?
         url += '?' + URI.encode_www_form(query)
@@ -149,7 +151,10 @@ module K9o
         req.delete('cookie')
       end
 
-      if multipart
+      if raw_body
+        # Binary routes: the bytes go unchanged; the caller supplies the content-type in +headers+.
+        req.body = raw_body
+      elsif multipart
         # multipart/form-data: the encoder sets the boundary; never force JSON.
         data, content_type = Multipart.encode(multipart)
         req['content-type'] = content_type
@@ -215,7 +220,7 @@ module K9o
     # sentinel terminates the stream; non-2xx raises KError before any
     # event is yielded.
     #
-    # Per the Ruby async-iteration idiom is Enumerator — caller
+    # The Ruby async-iteration idiom is Enumerator — caller
     # writes `client.compute.llms.invoke_stream(...).each { |chunk| ... }`.
     def stream_sse(config:, method:, path:, body: nil, query: nil)
       url = "#{Region.resolve_origin(config).sub(%r{/\z}, '')}#{path}"