k9o 1.3.0 → 1.5.0

data/lib/k9o/schema.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module K9o
+  # Schema: k9o.schema.*
+  #
+  #   collections.list(limit:, cursor:)    GET /@<slug>/schema/collections
+  #
+  # The list is cursor-paginated and ordered by collection name: pass +meta.cursor.next+ of one page as +cursor+ of
+  # the next, until it is nil.
+  class Schema
+    attr_reader :collections
+
+    def initialize(config)
+      @collections = SchemaCollections.new(config)
+    end
+  end
+
+  class SchemaCollections
+    def initialize(config)
+      @config = config
+    end
+
+    # The project's collections by name, one page at a time. +limit+ is 1 to 200 (default 50).
+    def list(limit: nil, cursor: nil)
+      route = UrlGrammar.project_path(Studio.require_project_slug(@config, 'schema'), 'schema/collections')
+      ApprovalChecks.check_limit(limit)
+      raise ApprovalChecks.invalid('cursor must be a string', cursor: cursor) unless cursor.nil? || cursor.is_a?(String)
+
+      query = {}
+      query['limit'] = limit unless limit.nil?
+      query['cursor'] = cursor unless cursor.nil?
+      HttpTransport.request(config: @config, method: 'GET', path: route, query: query)
+    end
+  end
+end

data/lib/k9o/streams.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module K9o
+  # User data streams namespace: k9o.streams.*.
+  #
+  # Routes under /@<slug>/data-streams/user. Publish needs project admin; subscribe and replay need admin or
+  # auditor. While the stream data plane is unavailable the gateway answers K9O_STREAM_UNAVAILABLE (503); a bad
+  # subject answers K9O_STREAM_INVALID. Both raise K9o::KError.
+  class Streams
+    @reconnect_delay = 0.25
+
+    class << self
+      # Seconds to wait before reconnecting after the server closes a subscribe connection.
+      attr_accessor :reconnect_delay
+    end
+
+    def initialize(config)
+      @config = config
+    end
+
+    # POST /@<slug>/data-streams/user — +max_bytes+ is the storage ceiling; the slug is derived from +display_name+.
+    def create(display_name, max_bytes, retention_seconds: nil)
+      body = { 'displayName' => display_name, 'maxBytes' => max_bytes }
+      body['retentionSeconds'] = retention_seconds unless retention_seconds.nil?
+      call('POST', path, body)
+    end
+
+    # GET /@<slug>/data-streams/user — the project's active user streams.
+    def list
+      call('GET', path)
+    end
+
+    # GET /@<slug>/data-streams/user/<slug>
+    def get(slug)
+      call('GET', path(slug))
+    end
+
+    # DELETE /@<slug>/data-streams/user/<slug> — retire the stream.
+    def delete(slug)
+      call('DELETE', path(slug))
+    end
+
+    # POST .../<slug>/publish — +data+ is any JSON value; +subject+ is an optional dot-separated routing suffix.
+    def publish(slug, data, subject: nil)
+      body = { 'data' => data }
+      body['subject'] = subject unless subject.nil?
+      call('POST', path(slug, 'publish'), body)
+    end
+
+    # POST .../<slug>/replay — a bounded range of past events: data['events'], data['nextCursor'], data['hasMore'].
+    def replay(slug, from_sequence: nil, until_sequence: nil, limit: nil)
+      body = {}
+      body['fromSequence'] = from_sequence unless from_sequence.nil?
+      body['untilSequence'] = until_sequence unless until_sequence.nil?
+      body['limit'] = limit unless limit.nil?
+      call('POST', path(slug, 'replay'), body)
+    end
+
+    # GET .../<slug>/subscribe — an Enumerator tailing live events { 'sequence', 'subject', 'data', 'publishedAt' }.
+    # The gateway bounds each connection and closes it; the enumerator reconnects from the last sequence it yielded.
+    # Stop by leaving the +each+ block (break) or by taking a finite number (+first(n)+).
+    def subscribe(slug, from_sequence: nil)
+      route = path(slug, 'subscribe')
+      Enumerator.new do |yielder|
+        cursor = from_sequence
+        loop do
+          query = cursor.nil? ? nil : { 'fromSequence' => cursor.to_s }
+          HttpTransport.stream_sse(config: @config, method: 'GET', path: route, query: query).each do |event|
+            next unless event.is_a?(Hash) && event.key?('sequence')
+
+            cursor = event['sequence']
+            yielder << event
+          end
+          delay = self.class.reconnect_delay
+          sleep(delay) if delay.positive?
+        end
+      end
+    end
+
+    private
+
+    def call(method, route, body = nil)
+      HttpTransport.request(config: @config, method: method, path: route, body: body)
+    end
+
+    def path(stream_slug = nil, suffix = nil)
+      project = Studio.require_project_slug(@config, 'streams')
+      sub = +'data-streams/user'
+      sub << "/#{::URI.encode_www_form_component(stream_slug)}" if stream_slug
+      sub << "/#{suffix}" if suffix
+      UrlGrammar.project_path(project, sub)
+    end
+  end
+end

data/lib/k9o/vault.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'base64'
 require 'uri'
 
 module K9o
@@ -81,7 +80,7 @@ module K9o
     # `metadata` (`Hash[String, String]`) are passed through verbatim.
     def create(name:, value:, region: nil, visibility: nil, metadata: nil)
       slug = require_project_slug
-      body = { 'value' => Base64.strict_encode64(value) }
+      body = { 'value' => [value].pack('m0') }
       body['visibility'] = visibility if visibility
       body['metadata'] = metadata if metadata
       HttpTransport.request(
@@ -119,7 +118,7 @@ module K9o
       )
       data = envelope.data
       if data.is_a?(Hash) && data.key?('value')
-        data = data.merge('value' => Base64.decode64(data['value']))
+        data = data.merge('value' => data['value'].unpack1('m'))
       end
       Envelope.new(data: data, meta: envelope.meta)
     end
@@ -132,7 +131,7 @@ module K9o
     # schema claims — call `get` afterward if the full summary is needed.
     def update(name, value:, region: nil, metadata: nil)
       slug = require_project_slug
-      body = { 'value' => Base64.strict_encode64(value) }
+      body = { 'value' => [value].pack('m0') }
       body['metadata'] = metadata if metadata
       HttpTransport.request(
         config: @config, method: 'PUT',

data/lib/k9o/vectors.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module K9o
+  # Vector collections: k9o.vectors.* store embeddings you computed yourself, next to the text and metadata they came
+  # from, and find the nearest ones.
+  #
+  #   nearest(collection, query_vector, top_k:, min_score:, metric:, filters:)  POST /@<slug>/vectors/<collection>/search
+  #   upsert(collection, rows)                                                  POST /@<slug>/vectors/<collection>/upsert
+  #
+  # Both send the vector in the request body, so they take real embeddings of any common size (up to 16000 numbers).
+  # The collection name must start with +_+. The first upsert creates the collection and fixes its dimension; every
+  # later vector must have the same length. Searching a collection that was never upserted answers 404
+  # K9O_COLLECTION_NOT_FOUND.
+  class Vectors
+    METRICS = %w[cosine euclidean dot].freeze
+    MAX_VECTOR = 16_000
+    MAX_ROWS = 1000
+    # Snake_case spellings accepted for the camelCase wire keys of a row and of its +_source+.
+    ROW_ALIASES = { 'content_hash' => 'contentHash', 'subject_ids' => 'subjectIds' }.freeze
+    SOURCE_ALIASES = { 'chunk_index' => 'chunkIndex' }.freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    # The rows nearest to +query_vector+ (1 to 16000 numbers), closest first. +top_k+ is 1 to 1000 (the gateway
+    # defaults to 10); +min_score+ drops results scoring below it; +metric+ is cosine (default), euclidean or dot;
+    # +filters+ is a Hash of equality checks on +id+, +contentHash+, +source.<key>+ and +metadata.<key>+.
+    # +data+ is { 'results' => [...], 'collection' => name }.
+    def nearest(collection, query_vector, top_k: nil, min_score: nil, metric: nil, filters: nil)
+      route = path(collection, 'search')
+      check_vector(query_vector, 'query_vector')
+      body = { 'queryVector' => query_vector.to_a }
+      unless top_k.nil?
+        unless top_k.is_a?(Integer) && top_k >= 1 && top_k <= 1000
+          raise invalid('top_k must be a whole number from 1 to 1000', top_k: top_k)
+        end
+
+        body['topK'] = top_k
+      end
+      unless min_score.nil?
+        raise invalid('min_score must be a number', min_score: min_score) unless finite?(min_score)
+
+        body['minScore'] = min_score
+      end
+      body['metric'] = ApprovalChecks.enum!(metric, METRICS, 'metric') unless metric.nil?
+      unless filters.nil?
+        raise invalid('filters must be a Hash of path to value') unless filters.is_a?(Hash)
+
+        body['filters'] = filters.transform_keys(&:to_s)
+      end
+      call(route, body)
+    end
+
+    # Insert or overwrite 1 to 1000 rows in one request; the first upsert creates the collection. A row is a Hash
+    # with +vector+ and +_source+ ({ handle:, chunkIndex: }), and optionally +id+, +contentHash+, +text+, +metadata+
+    # and +subjectIds+ (one end-user id, ["eu_..."]; required unless the collection was declared shared). Keys may
+    # be strings or symbols, and +content_hash+, +subject_ids+ and +chunk_index+ are accepted for the camelCase
+    # names. A single row may be passed on its own, with or without braces. +data+ is { 'upserted' => n,
+    # 'collection' => name }.
+    def upsert(collection, rows = nil, **row)
+      route = path(collection, 'upsert')
+      rows = [row] if rows.nil? && !row.empty?
+      rows = [rows] if rows.is_a?(Hash)
+      unless rows.is_a?(Array) && rows.size >= 1 && rows.size <= MAX_ROWS
+        raise invalid("rows must be an array of 1 to #{MAX_ROWS} rows")
+      end
+
+      wire = rows.each_with_index.map do |entry, index|
+        raise invalid("rows[#{index}] must be a Hash") unless entry.is_a?(Hash)
+
+        normalize_row(entry, index)
+      end
+      call(route, 'rows' => wire)
+    end
+
+    private
+
+    def normalize_row(entry, index)
+      row = entry.each_with_object({}) do |(key, value), out|
+        name = key.to_s
+        out[ROW_ALIASES.fetch(name, name)] = value
+      end
+      check_vector(row['vector'], "rows[#{index}].vector")
+      source = row['_source']
+      if source.is_a?(Hash)
+        row['_source'] = source.each_with_object({}) do |(key, value), out|
+          name = key.to_s
+          out[SOURCE_ALIASES.fetch(name, name)] = value
+        end
+      end
+      row['vector'] = row['vector'].to_a
+      row
+    end
+
+    def check_vector(vector, name)
+      unless vector.is_a?(Array) && vector.size >= 1 && vector.size <= MAX_VECTOR
+        raise invalid("#{name} must be an array of 1 to #{MAX_VECTOR} numbers")
+      end
+      return if vector.all? { |n| finite?(n) }
+
+      raise invalid("#{name} must contain only finite numbers")
+    end
+
+    def finite?(value)
+      value.is_a?(Numeric) && !value.is_a?(Complex) && (!value.respond_to?(:finite?) || value.finite?)
+    end
+
+    def invalid(message, context = {})
+      ApprovalChecks.invalid(message, context)
+    end
+
+    def call(route, body)
+      HttpTransport.request(config: @config, method: 'POST', path: route, body: body)
+    end
+
+    def path(collection, tail)
+      raise invalid('a vector collection name must start with _', collection: collection) unless collection.is_a?(String) && collection.start_with?('_')
+
+      slug = Studio.require_project_slug(@config, 'vectors')
+      UrlGrammar.project_path(slug, "vectors/#{::URI.encode_www_form_component(collection).gsub('+', '%20')}/#{tail}")
+    end
+  end
+end

data/lib/k9o/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module K9o
-  VERSION = '1.3.0'
+  VERSION = '1.5.0'
 end

data/lib/k9o.rb

@@ -29,15 +29,30 @@ require_relative 'k9o/url_grammar'
 require_relative 'k9o/region'
 require_relative 'k9o/http_transport'
 require_relative 'k9o/data'
+require_relative 'k9o/query'
 require_relative 'k9o/projects'
+require_relative 'k9o/locate'
 require_relative 'k9o/gate'
 require_relative 'k9o/studio'
 require_relative 'k9o/compute'
 require_relative 'k9o/ai'
 require_relative 'k9o/storage'
 require_relative 'k9o/realtime'
+require_relative 'k9o/streams'
+require_relative 'k9o/approvals'
+require_relative 'k9o/schema'
 require_relative 'k9o/migrations'
 require_relative 'k9o/functions'
+require_relative 'k9o/schedules'
+require_relative 'k9o/vectors'
+require_relative 'k9o/metadata'
+require_relative 'k9o/rampart'
+require_relative 'k9o/moat'
+require_relative 'k9o/custody'
+require_relative 'k9o/analytics'
+require_relative 'k9o/keys'
+require_relative 'k9o/crypto'
+require_relative 'k9o/end_users'
 require_relative 'k9o/policies'
 require_relative 'k9o/audit'
 require_relative 'k9o/orgs'
@@ -46,6 +61,8 @@ require_relative 'k9o/org'
 # kibo ZK BYOK/HYOK crypto — self-guards its native binding (LoadError-safe), so
 # requiring k9o never breaks on a platform without the kibo native lib.
 require_relative 'k9o/kibo'
+require_relative 'k9o/kibo_client_core'
+require_relative 'k9o/kibo_ffi_core'
 # kibo vault REST surface (client.kibo.vault.secrets) —.
 require_relative 'k9o/vault'
 # Barbican guardrail SDK — self-guards its native binding (LoadError-safe), so

data/sig/k9o/ai.rbs

@@ -8,6 +8,10 @@ module K9o
     # { "embeddings" => Array[Array[Float]], "model" => String, "dimensions" => Integer }.
     def initialize: (untyped config) -> void
     def embed: (input: (String | Array[String]), ?model: String?) -> Envelope
+
+    # Only the fields given are sent. Returns an Envelope whose `data` is
+    # { "modelId" => String, "content" => String, "finishReason" => String, "usage" => Hash, "usageType" => String }.
+    def generate: (String prompt, ?model: String?, ?max_tokens: Integer?, ?temperature: Numeric?, ?usage_type: String?) -> Envelope
   end
 
   class K9oClient

data/sig/k9o/approvals.rbs

@@ -0,0 +1,71 @@
+# RBS signatures for `client.approvals`, `client.approval_policies` and `client.schema`.
+
+module K9o
+  module ApprovalChecks
+    def self.invalid: (String message, ?Hash[Symbol, untyped] context) -> KError
+    def self.check_limit: (untyped limit) -> void
+    def self.id_segment: (untyped value, String what) -> String
+    def self.reason!: (untyped reason) -> String
+    def self.predicate!: (untyped value, String field) -> Hash[untyped, untyped]
+    def self.enum!: (untyped value, Array[String] allowed, String field) -> String
+  end
+
+  class Approvals
+    attr_reader comments: ApprovalComments
+    def initialize: (untyped config) -> void
+    # One page, newest first. `limit` is 1 to 200 (default 50); pass `meta.cursor.next` back as `cursor`
+    # (nil on the last page).
+    def list: (?status: (String | Symbol)?, ?limit: Integer?, ?cursor: String?) -> Envelope
+    def get: (String id) -> Envelope
+    # `status` on the answer stays "pending_approval" while more approvers are needed.
+    def approve: (String id, ?reason: String?) -> Envelope
+    def reject: (String id, reason: String) -> Envelope
+    # HTTP 200 even when rows fail: `data["failed"]` is an Array of { "id", "code", "reason" } (empty when none).
+    # Compare `affectedIds` with what you intended.
+    def bulk: (action: (String | Symbol), criteria: Hash[(String | Symbol), untyped], ?reason: String?) -> Envelope
+  end
+
+  # `approvals.comments`. Posting needs a session (a personal access token alone is refused, K9O_RBAC_DENY).
+  class ApprovalComments
+    VISIBILITIES: Array[String]
+    BODY_MAX: Integer
+
+    # An Envelope whose data is the Array of comments, oldest first; `next_cursor` is nil on the last page.
+    # A comment is { "id", "caseId", "authorId", "visibility", "body", "createdAt" }.
+    class Page < Envelope
+      attr_reader next_cursor: String?
+      def initialize: (data: untyped, meta: Meta, ?next_cursor: String?) -> void
+    end
+
+    def initialize: (untyped config) -> void
+    # `body` is 1 to 4000 characters; `visibility` is "everyone" or "approvers_only", fixed once posted. HTTP 201.
+    def add: (String pending_id, body: String, visibility: (String | Symbol)) -> Envelope
+    # `limit` is 1 to 200 (default 50); pass `next_cursor` back as `cursor`.
+    def list: (String pending_id, ?limit: Integer?, ?cursor: String?) -> Page
+  end
+
+  class ApprovalPolicies
+    COLLECTION_RE: Regexp
+
+    def initialize: (untyped config) -> void
+    def list: () -> Envelope
+    def create: (collection: String, operation: (String | Symbol), action: (String | Symbol), predicate: Hash[(String | Symbol), untyped]) -> Envelope
+    def delete: (String id) -> Envelope
+  end
+
+  class SchemaCollections
+    def initialize: (untyped config) -> void
+    def list: (?limit: Integer?, ?cursor: String?) -> Envelope
+  end
+
+  class Schema
+    attr_reader collections: SchemaCollections
+    def initialize: (untyped config) -> void
+  end
+
+  class K9oClient
+    attr_reader approvals: Approvals
+    attr_reader approval_policies: ApprovalPolicies
+    attr_reader schema: Schema
+  end
+end

data/sig/k9o/datasets.rbs

@@ -0,0 +1,125 @@
+# RBS signatures for `client.analytics` (datasets), `client.rollups` and `client.keys`.
+
+module K9o
+  class Download
+    attr_reader body: String
+    attr_reader content_type: String?
+    def initialize: (body: String, ?content_type: String?) -> void
+  end
+
+  class AnalyticsRollups
+    def initialize: (untyped config) -> void
+    def create: (String dataset_slug, slug: String, source: String, measures: Array[Hash[Symbol | String, untyped]], window_seconds: Integer,
+                 ?dimensions: Array[String]?, ?subject_field: String?, ?non_personal: bool?, ?reattest_interval_days: Integer?) -> Envelope
+    def list: (String dataset_slug) -> Envelope
+    def delete: (String dataset_slug, String rollup_id) -> Envelope
+    # People only: a service, workload or extension token gets 403 K9O_RBAC_DENY (reason human_only).
+    def reattest: (String dataset_slug, String rollup_id, ?reattest_interval_days: Integer?) -> Envelope
+  end
+
+  class AnalyticsSchedules
+    def initialize: (untyped config) -> void
+    def create: (String dataset_slug, from_collection: String, interval_seconds: Integer, ?reattest_interval_days: Integer?) -> Envelope
+    def list: (String dataset_slug) -> Envelope
+    def delete: (String dataset_slug, String schedule_id) -> Envelope
+    def reattest: (String dataset_slug, String schedule_id, ?reattest_interval_days: Integer?) -> Envelope
+  end
+
+  class Analytics
+    attr_reader rollups: AnalyticsRollups
+    attr_reader schedules: AnalyticsSchedules
+    def initialize: (untyped config) -> void
+    def list: () -> Envelope
+    def query: (String sql, Array[String] datasets) -> Envelope
+    def create: (String slug, display_name: String, columns: Array[Hash[Symbol | String, untyped]], residency_class: (String | Symbol),
+                 ?partition_by: Array[String]?, ?storage_target: Hash[Symbol | String, untyped]?) -> Envelope
+    def get: (String slug) -> Envelope
+    def delete: (String slug) -> Envelope
+    def materialize: (String slug, ?from_collection: String?, ?from_query: String?) -> Envelope
+    def read: (String slug, ?partition_filter: Hash[Symbol | String, untyped]?, ?cursor: String?, ?limit: Integer?) -> Envelope
+    def write: (String slug, (Array[Hash[Symbol | String, untyped]] | String) rows, ?on_error: (String | Symbol)?) -> Envelope
+    def upload: (String slug, (String | IO) data, format: (String | Symbol), ?filename: String, ?manifest: Hash[Symbol | String, untyped]?,
+                 ?dry_run: bool?, ?on_error: (String | Symbol)?, ?delimiter: String?, ?encoding: String?, ?has_header: bool?) -> Envelope
+    def download_original: (String slug) -> Download
+  end
+
+  class Rollups
+    def initialize: (untyped config) -> void
+    def list: () -> Envelope
+    def read: (String rollup_slug, ?from: (String | Time)?, ?to: (String | Time)?, ?dims: (Array[String] | String)?) -> Envelope
+    def subscribe: (String rollup_slug, ?from_sequence: Integer?, ?on_resync: (^(Hash[String, untyped]) -> untyped)?) -> Enumerator[Hash[String, untyped], untyped]
+  end
+
+  class Keys
+    STATUSES: Array[String]
+    def initialize: (untyped config) -> void
+    # data: { "items" => [key] } (not paged)
+    def list: (?status: (String | Symbol)?) -> Envelope
+    def get: (String key_id) -> Envelope
+    # data: { "keyId", "previousVersion", "newVersion", "status" => "rotated" }
+    # step_up: ^(StepUpChallenge, String, String) -> { method: String, proof: String }
+    def rotate: (String key_id, ?step_up: untyped, ?headers: Hash[String, String]?) -> Envelope
+
+    class StepUpChallenge < Struct[untyped]
+      attr_reader scope_set_root: String
+      attr_reader nonce: String
+      attr_reader min_tier: String?
+      attr_reader methods: Array[String]
+      attr_reader max_age_sec: Integer?
+      attr_reader single_use: bool?
+      attr_reader rp_id: String?
+    end
+  end
+
+  class Crypto
+    def initialize: (untyped config) -> void
+    def encrypt: (String crypt, Array[Hash[Symbol | String, untyped] | String] items) -> Envelope
+    def decrypt: (String crypt, Array[Hash[Symbol | String, untyped] | String] items) -> Envelope
+    def rewrap: (String crypt, Array[Hash[Symbol | String, untyped] | String] items) -> Envelope
+    def self.text: (Hash[String, untyped] item) -> String?
+    # Reads the project's custody mode; every encrypt does this first, with no cache.
+    def mode: () -> Mode
+    # Registers the Kibo client core (an object with encrypt, decrypt and rewrap); nil removes it.
+    def use_client_core: (untyped core) -> untyped
+    def self.check_expected_key_refs: (Array[String]? refs) -> Array[String]?
+    def self.key_ref_matches?: (String key_ref, Array[String] expected, provider: (:aws | :gcp | :azure | :vault)) -> bool
+
+    # Ask for a short-lived federated token for +op+ ("encrypt", "decrypt" or "rewrap") on +crypt+.
+    def federated_token: (String crypt, String op) -> FederatedToken
+
+    # Crypts: data is { "crypts" => [...] } (list) or one { "name", "status", "createdAt", "retiredAt" } Hash.
+    def crypts_list: () -> Envelope
+    def crypts_create: (String name) -> Envelope
+    def crypts_retire: (String name) -> Envelope
+
+    class Mode < Struct[untyped]
+      def custody_mode: () -> String?
+      def epoch: () -> String?
+    end
+
+    # +provider+ and +project_id+ are nil unless the gateway names them; they are only checked against configuration.
+    class FederatedToken < Struct[untyped]
+      attr_reader token: String
+      attr_reader expires_at: String
+      attr_reader issuer: String
+      attr_reader subject: String
+      attr_reader audience: String
+      attr_reader kid: String
+      attr_reader provider: String?
+      attr_reader project_id: String?
+    end
+  end
+
+  class Audit
+    # Yields { "auditEventId", "type", "actorType", "occurredAt", "outcome", "eventId" }.
+    def tail: (?types: (Array[String | Symbol] | String | Symbol)?, ?on_resync: (^(Hash[String, untyped]) -> untyped)?) -> Enumerator[Hash[String, untyped], untyped]
+    def replay: (?topic: String, ?after_audit_event_id: String?, ?from_sequence: Integer?, ?until_sequence: Integer?, ?limit: Integer?) -> Envelope
+  end
+
+  class K9oClient
+    attr_reader analytics: Analytics
+    attr_reader rollups: Rollups
+    attr_reader keys: Keys
+    attr_reader crypto: Crypto
+  end
+end

data/sig/k9o/gate.rbs

@@ -7,6 +7,8 @@ module K9o
     # The refresh token is required: the gateway answers 400 without it.
     def sign_out: (refresh_token: String) -> Envelope
     def whoami: () -> Envelope
+    def revoke_all_sessions: () -> Envelope
+    # `data` is `{ accessToken, refreshToken, expiresAt }`; the refresh token sent stops working, so store the new one.
     def refresh_token: (refresh_token: String) -> Envelope
   end
 end

data/sig/k9o/kerror.rbs

@@ -0,0 +1,24 @@
+# RBS signatures for the error type raised by every call.
+
+module K9o
+  class KError < StandardError
+    attr_reader code: String
+    attr_reader context: Hash[untyped, untyped]
+    # Suggested next step as text, or nil.
+    attr_reader recommendation: String?
+    attr_reader status: Integer?
+    attr_reader request_id: String?
+    # Seconds the gateway asks the caller to wait before retrying, or nil.
+    attr_reader retry_after_sec: Numeric?
+    # The step-up challenge of a 401 K9O_STEP_UP_REQUIRED, or nil.
+    def step_up: () -> Keys::StepUpChallenge?
+
+    def initialize: (code: String, message: String, ?context: Hash[untyped, untyped], ?recommendation: String?, ?status: Integer?, ?request_id: String?, ?retry_after_sec: Numeric?) -> void
+    def with_recommendation: (String? rec) -> KError
+    def message: () -> String
+    def to_s: () -> String
+    def self.from_wire: (Hash[String, untyped] wire, Integer? status) -> KError
+    def self.recommendation_text: (untyped raw) -> String?
+    def self.retry_after: (untyped raw) -> Numeric?
+  end
+end

data/sig/k9o/kibo_client_core.rbs

@@ -0,0 +1,25 @@
+# RBS signatures for the Kibo client core of client.crypto (BYOK and HYOK projects).
+
+module K9o
+  class KiboClientCore
+    EXCHANGE_TIMEOUT: String
+    CORE_FUNCTIONS: Array[Symbol]
+    PROVIDER_WIRE: Hash[Symbol, String]
+    SKEW_SECS: Integer
+    DEFAULT_DEADLINE_SECS: Integer
+
+    # +core+ responds to app_crypto_seal_blocking, app_crypto_open_blocking, acquire_kms_credential_blocking and
+    # core_capabilities (the generated KiboKmsRestFfi module does). +federated_token+ answers call(crypt, op) with a
+    # Crypto::FederatedToken.
+    def initialize: (provider: (:aws | :gcp | :azure | :vault), posture: (:byok | :hyok), key_ref: Hash[Symbol, untyped],
+                     federation: Hash[Symbol | String, untyped], expected_key_refs: Array[String], federated_token: untyped, core: untyped,
+                     ?project_id: String?, ?provider_config: Hash[Symbol | String, String?], ?exchange_deadline: Numeric,
+                     ?now: ^() -> Integer) -> void
+    def enforces_expected_key_refs?: () -> true
+    def encrypt: (String crypt, Array[Hash[Symbol, untyped]] items, **untyped options) -> Hash[String, Array[Hash[String, untyped]]]
+    def decrypt: (String crypt, Array[Hash[Symbol, untyped]] items, **untyped options) -> Hash[String, Array[Hash[String, untyped]]]
+    def rewrap: (String crypt, Array[Hash[Symbol, untyped]] items, **untyped options) -> Hash[String, Array[Hash[String, untyped]]]
+    def inspect: () -> String
+    def to_s: () -> String
+  end
+end

data/sig/k9o/metadata.rbs

@@ -0,0 +1,54 @@
+# RBS signatures for `client.metadata`.
+
+module K9o
+  class Metadata
+    # An Envelope whose data is the Array of rows; `cursor` is the next page's cursor, or nil on the last page.
+    # A row is { "surface", "scope", "recordId" (collection) or "eventId" (telemetry), "metadata" => { column => value } }.
+    class Page < Envelope
+      def cursor: () -> String?
+    end
+
+    OPS: Array[String]
+    METRICS: Array[String]
+    SLICES: Array[String]
+    PREFIX: String
+    MAX_COLUMNS: Integer
+    MAX_LIMIT: Integer
+    TELEMETRY_FIELDS: Array[String]
+
+    attr_reader vectors: MetadataVectors
+    attr_reader index: MetadataIndex
+
+    def initialize: (untyped config) -> void
+    # surfaces: ["collection:posts"]; where: [{ field:, op:, value: }]; limit 1..1000; cursor only with one surface.
+    # Options may be keyword arguments or one Hash.
+    def filter: (?Hash[String | Symbol, untyped]? input, ?surfaces: Array[String], ?where: Array[Hash[String | Symbol, untyped]]?, ?limit: Integer?, ?cursor: String?) -> Page
+    # data is the whole updated record. Columns may be keyword arguments or one Hash.
+    def set: (String | Symbol collection, String id, ?Hash[String | Symbol, untyped]? columns, **untyped extra) -> Envelope
+    def search: (?Hash[String | Symbol, untyped]? input, ?surface: String, ?field: String | Symbol, ?q: String, ?limit: Integer?) -> Page
+    # Yields { "topic", "eventType", "payload" => { "collection", "id" }, "occurredAt", "eventId"? }.
+    def subscribe: (String surface, ?Hash[String | Symbol, untyped]? input, ?from_sequence: Integer?, ?fromSequence: Integer?, ?on_resync: (^(Hash[String, untyped]) -> untyped)?) -> Enumerator[Hash[String, untyped], untyped]
+  end
+
+  class MetadataVectors
+    def initialize: (untyped config) -> void
+    # Rows carry no score; at most 50 rows come back whatever k is.
+    def nearest: (?Hash[String | Symbol, untyped]? input, ?surface: String, ?column: String | Symbol, ?embedding: Array[Numeric], ?k: Integer?, ?metric: (String | Symbol)?, ?where: Array[Hash[String | Symbol, untyped]]?) -> Metadata::Page
+  end
+
+  class MetadataIndex
+    def initialize: (untyped config) -> void
+    # data is { "collection" => String, "columns" => [{ "column" => String, "indexed" => bool }] }.
+    def get: (String | Symbol collection) -> Envelope
+    def declare: (String | Symbol collection, Array[Hash[String | Symbol, untyped]] columns) -> Envelope
+  end
+
+  class Realtime
+    # The reconnecting reader behind subscribe; initial_query applies to the first connection only.
+    def feed: (String route, Hash[String, untyped] q, Hash[String, untyped]? initial_query, (^(Hash[String, untyped]) -> untyped)? on_resync) -> Enumerator[Hash[String, untyped], untyped]
+  end
+
+  class K9oClient
+    attr_reader metadata: Metadata
+  end
+end