k9o 1.2.0-aarch64-linux → 1.5.2-aarch64-linux

data/lib/k9o/org.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
 module K9o
-  # Org-plane bound namespace — k9o.org.*. Singular
-  # bound-org namespace (distinct from k9o.orgs collection): members /
-  # groups / smtp / audit_log / gate (roles + idp_providers) + default_llm.
-  # Org-plane URL grammar routes against the org subdomain
-  # without the @<projectSlug>/ prefix.
+  # Org-plane bound namespace — k9o.org.*. Singular bound-org namespace (distinct from the k9o.orgs collection):
+  # members / groups / smtp / audit_log / gate (roles + idp_providers) + default_llm.
+  # Org-plane routes live on the org host without the @<projectSlug>/ prefix.
   class Org
     attr_reader :members, :groups, :smtp, :audit_log, :gate, :default_llm
 
@@ -19,7 +17,7 @@ module K9o
       @default_llm = DefaultLlm.new(config)
     end
 
-    # Read the current org (slug + name + status + settings).
+    # GET /org — the current org (slug + name + status).
     def get
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('org'))
     end
@@ -34,64 +32,57 @@ module K9o
         @config = config
       end
 
-      def list(status: nil)
-        q = status ? { 'status' => status } : nil
+      # GET /members. +status+ is the stored membership status ('active' or 'suspended'); +acceptance_status+ is
+      # 'accepted' or 'pending'.
+      def list(user_id: nil, role: nil, acceptance_status: nil, status: nil, state: nil)
+        q = {}
+        q['userId'] = user_id unless user_id.nil?
+        q['role'] = role unless role.nil?
+        q['acceptanceStatus'] = acceptance_status unless acceptance_status.nil?
+        q['status'] = status unless status.nil?
+        q['state'] = state unless state.nil?
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('members'), query: q)
       end
 
+      # POST /members { email, role }
       def invite(email:, role:)
         HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('members'),
                               body: { 'email' => email, 'role' => role })
       end
 
-      def get(user_id)
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path("members/#{Org.enc(user_id)}"))
-      end
-
       def remove(user_id)
         HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.org_path("members/#{Org.enc(user_id)}"))
       end
     end
 
-    # k9o.org.groups.*
+    # k9o.org.groups.* (read-only: the gateway has no group create or delete)
     class Groups
       def initialize(config)
         @config = config
       end
 
-      def list
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('groups'))
-      end
-
-      def create(name:)
-        HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('groups'), body: { 'name' => name })
+      # GET /groups — optionally only the groups +user_id+ belongs to.
+      def list(user_id: nil)
+        q = user_id.nil? ? nil : { 'userId' => user_id }
+        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('groups'), query: q)
       end
 
       def get(group_id)
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path("groups/#{Org.enc(group_id)}"))
       end
-
-      def delete(group_id)
-        HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.org_path("groups/#{Org.enc(group_id)}"))
-      end
     end
 
-    # k9o.org.audit_log.* (org-plane; distinct from project Audit).
+    # k9o.org.audit_log.* (org-plane; distinct from project Audit). The org audit route reads only +type+ (exact
+    # event type) and +limit+ (1 to 500, default 100).
     class AuditLog
       def initialize(config)
         @config = config
       end
 
-      def query(since: nil, until_: nil, type: nil, actor_id: nil, target_kind: nil, target_id: nil, limit: nil, cursor: nil)
+      def query(type: nil, limit: nil)
         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['type'] = type unless type.nil?
+        q['limit'] = limit unless limit.nil?
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('audit-log'), query: q)
       end
     end
@@ -105,88 +96,109 @@ module K9o
         @idp_providers = IdpProviders.new(config)
       end
 
-      # k9o.org.gate.roles.*
+      # k9o.org.gate.roles.* — org role grants.
       class Roles
         def initialize(config)
           @config = config
         end
 
-        def list(user_id: nil, role: nil)
-          q = {}
-          q['userId'] = user_id if user_id
-          q['role'] = role if role
-          HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('org-role-grants'), query: q)
+        # GET /role-grants (active grants).
+        def list
+          HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('role-grants'))
         end
 
-        def grant(user_id:, role:)
-          HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('org-role-grants'),
-                                body: { 'userId' => user_id, 'role' => role })
+        # POST /role-grants { userId, role, decisionReason? }
+        def grant(user_id:, role:, decision_reason: nil)
+          body = { 'userId' => user_id, 'role' => role }
+          body['decisionReason'] = decision_reason unless decision_reason.nil?
+          HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('role-grants'), body: body)
         end
 
         def get(grant_id)
-          HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path("org-role-grants/#{Org.enc(grant_id)}"))
+          HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path("role-grants/#{Org.enc(grant_id)}"))
         end
 
-        def revoke(grant_id)
-          HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.org_path("org-role-grants/#{Org.enc(grant_id)}"))
+        # DELETE /role-grants/<id> with an optional { decisionReason } body.
+        def revoke(grant_id, decision_reason: nil)
+          body = decision_reason.nil? ? nil : { 'decisionReason' => decision_reason }
+          HttpTransport.request(config: @config, method: 'DELETE',
+                                path: UrlGrammar.org_path("role-grants/#{Org.enc(grant_id)}"), body: body)
         end
       end
 
-      # k9o.org.gate.idp_providers.*
+      # k9o.org.gate.idp_providers.* — the org's identity providers (/identity-providers).
       class IdpProviders
+        CREATE_OPTIONAL = {
+          redirect_uri: 'redirectUri', metadata_url: 'metadataUrl', attribute_map: 'attributeMap', enabled: 'enabled'
+        }.freeze
+
         def initialize(config)
           @config = config
         end
 
         def list
-          HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('idp-providers'))
+          HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('identity-providers'))
         end
 
-        def create(name:, kind:, config:)
-          HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('idp-providers'),
-                                body: { 'name' => name, 'kind' => kind, 'config' => config })
+        # POST /identity-providers { idpProvider, displayName, clientId, clientSecretRef, ... }
+        #   idp_provider: google github microsoft oidc saml scim ldap active_directory apple facebook twitter
+        #   client_secret_ref: the OAuth client secret itself (the name is kept for compatibility); the gateway encrypts it and never returns it
+        def create(idp_provider:, display_name:, client_id:, client_secret_ref:, **opts)
+          body = { 'idpProvider' => idp_provider, 'displayName' => display_name, 'clientId' => client_id,
+                   'clientSecretRef' => client_secret_ref }
+          opts.each do |key, value|
+            wire = CREATE_OPTIONAL[key]
+            raise ArgumentError, "unknown idp_providers.create option: #{key}" if wire.nil?
+
+            body[wire] = value
+          end
+          HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('identity-providers'), body: body)
         end
 
         def get(idp_id)
-          HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path("idp-providers/#{Org.enc(idp_id)}"))
+          HttpTransport.request(config: @config, method: 'GET',
+                                path: UrlGrammar.org_path("identity-providers/#{Org.enc(idp_id)}"))
         end
 
+        # PATCH /identity-providers/<id>. +patch+ keys are the gateway's: displayName, clientId, clientSecretRef,
+        # redirectUri, metadataUrl, attributeMap, enabled.
         def configure(idp_id, patch)
           HttpTransport.request(config: @config, method: 'PATCH',
-                                path: UrlGrammar.org_path("idp-providers/#{Org.enc(idp_id)}"), body: patch)
+                                path: UrlGrammar.org_path("identity-providers/#{Org.enc(idp_id)}"), body: patch)
         end
 
         def delete(idp_id)
-          HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.org_path("idp-providers/#{Org.enc(idp_id)}"))
+          HttpTransport.request(config: @config, method: 'DELETE',
+                                path: UrlGrammar.org_path("identity-providers/#{Org.enc(idp_id)}"))
         end
       end
     end
 
-    # k9o.org.smtp.*
+    # k9o.org.smtp.* — the org's SMTP relay, stored in the org record (PATCH /org { smtpConfig }).
     class Smtp
       def initialize(config)
         @config = config
       end
 
-      def get
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('org/smtp'))
-      end
-
-      def set(host:, port:, username:, password:, from_email:, from_name:, encryption:, reply_to_email: nil)
+      # PATCH /org { smtpConfig: { host, port, username, passwordRef, fromAddress, fromName? } }.
+      # +password_ref+ references the stored SMTP password; it is never the password itself.
+      def set(host:, port:, username:, password_ref:, from_address:, from_name: nil)
         smtp = {
-          'host' => host, 'port' => port, 'username' => username, 'password' => password,
-          'fromEmail' => from_email, 'fromName' => from_name, 'encryption' => encryption
+          'host' => host, 'port' => port, 'username' => username, 'passwordRef' => password_ref,
+          'fromAddress' => from_address
         }
-        smtp['replyToEmail'] = reply_to_email if reply_to_email
+        smtp['fromName'] = from_name unless from_name.nil?
         HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.org_path('org'), body: { 'smtpConfig' => smtp })
       end
 
-      def test(to:, from_override: nil)
+      # POST /org/smtp/test-email { to, subject? }
+      def test(to:, subject: nil)
         body = { 'to' => to }
-        body['fromOverride'] = from_override if from_override
+        body['subject'] = subject unless subject.nil?
         HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('org/smtp/test-email'), body: body)
       end
 
+      # PATCH /org { smtpConfig: null }
       def unset
         HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.org_path('org'), body: { 'smtpConfig' => nil })
       end
@@ -198,15 +210,15 @@ module K9o
         @config = config
       end
 
-      # Read the org-default LLM model id (nil when unset → mistral-7b).
+      # GET /default-llm
       def get
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('org/default-llm'))
+        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('default-llm'))
       end
 
-      # Set the org-default LLM (ORG_ADMIN; tier-gated).
+      # PATCH /default-llm { modelId }
       def set(model_id)
         HttpTransport.request(config: @config, method: 'PATCH',
-                              path: UrlGrammar.org_path('org/default-llm'), body: { 'modelId' => model_id })
+                              path: UrlGrammar.org_path('default-llm'), body: { 'modelId' => model_id })
       end
     end
   end

data/lib/k9o/orgs.rb

@@ -13,6 +13,7 @@ module K9o
     end
 
     def get(org_slug)
+      UrlGrammar.validate_slug(org_slug, 'org')
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path("orgs/#{enc(org_slug)}"))
     end
 

data/lib/k9o/policies.rb

@@ -2,11 +2,18 @@
 
 module K9o
   # Policy bundle lifecycle namespace — k9o.policies.*.
+  #
+  # The policy document is a Hash of sections keyed by resource kind ('collections', 'storage', 'tools',
+  # 'functions', 'secrets', 'streams', 'analytics'; other keys are allowed). Only authoring roles write policy and
+  # only custodian roles publish; +validate+ is read-only.
   class Policies
+    EDITOR_MODES = %w[visual json unspecified].freeze
+
     def initialize(config)
       @config = config
     end
 
+    # GET /@<slug>/policy — the currently active policy (data is nil when none is published).
     def current
       slug = require_project_slug
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, 'policy'))
@@ -18,16 +25,18 @@ module K9o
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, 'policies'), query: q)
     end
 
-    def create(name:, rules:)
+    # POST /@<slug>/policies — create a draft bundle from a policy document.
+    def create(policy:, rules: nil, editor_mode: nil)
       slug = require_project_slug
       HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.project_path(slug, 'policies'),
-                            body: { 'name' => name, 'rules' => rules })
+                            body: policy_body(policy, rules, editor_mode))
     end
 
-    def validate(rules)
+    # POST /@<slug>/policies/validate — lint a candidate policy document without persisting.
+    def validate(policy:, rules: nil)
       slug = require_project_slug
       HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.project_path(slug, 'policies/validate'),
-                            body: { 'rules' => rules })
+                            body: policy_body(policy, rules, nil))
     end
 
     def get(bundle_id)
@@ -35,12 +44,15 @@ module K9o
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, "policies/#{enc(bundle_id)}"))
     end
 
-    def update(bundle_id, patch)
+    # PATCH /@<slug>/policies/<id> — replace a draft bundle's policy document. Published bundles cannot be patched.
+    def update(bundle_id, policy:, rules: nil, editor_mode: nil)
       slug = require_project_slug
       HttpTransport.request(config: @config, method: 'PATCH',
-                            path: UrlGrammar.project_path(slug, "policies/#{enc(bundle_id)}"), body: patch)
+                            path: UrlGrammar.project_path(slug, "policies/#{enc(bundle_id)}"),
+                            body: policy_body(policy, rules, editor_mode))
     end
 
+    # Delete a draft bundle. Published bundles cannot be deleted.
     def delete(bundle_id)
       slug = require_project_slug
       HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.project_path(slug, "policies/#{enc(bundle_id)}"))
@@ -54,6 +66,13 @@ module K9o
 
     private
 
+    def policy_body(policy, rules, editor_mode)
+      body = { 'policy' => policy }
+      body['rules'] = rules unless rules.nil?
+      body['editorMode'] = editor_mode unless editor_mode.nil?
+      body
+    end
+
     def require_project_slug
       Studio.require_project_slug(@config, 'policies')
     end

data/lib/k9o/projects.rb

@@ -2,32 +2,67 @@
 
 module K9o
   # Project lifecycle namespace — k9o.projects.* (Ruby snake_case).
+  #
+  # All four operations are org-plane: the client needs an org context (an
+  # +org_slug+ or a bearer token that carries one). Option names are snake_case
+  # spellings of the gateway's body property names.
   class Projects
+    CREATE_FIELDS = {
+      slug: 'slug', product_scope: 'productScope', region: 'region',
+      default_project_region: 'defaultProjectRegion', custody_mode: 'custodyMode',
+      processing_contexts: 'processingContexts', exec_seam_confined: 'execSeamConfined',
+      showroom_vertical: 'showroomVertical', persona: 'persona', showroom_locale: 'showroomLocale',
+      idempotency_key: 'idempotencyKey'
+    }.freeze
+
+    UPDATE_FIELDS = {
+      slug: 'slug', display_name: 'displayName', description: 'description', region: 'region',
+      product_scope: 'productScope', soft_delete_retention_days: 'softDeleteRetentionDays',
+      processing_contexts: 'processingContexts'
+    }.freeze
+
     def initialize(config)
       @config = config
     end
 
+    # GET /projects
     def list
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('projects'))
     end
 
-    def create(slug:, name:, custody_mode: nil)
-      UrlGrammar.validate_slug(slug, 'project')
-      body = { 'slug' => slug, 'name' => name }
-      body['custodyMode'] = custody_mode if custody_mode
+    # POST /projects. +display_name+ is required (1 to 128 characters); the gateway derives a slug from it when
+    # +slug+ is omitted. +custody_mode+ is one of PLATFORM_MANAGED, SKR, BYOK, HYOK. +idempotency_key+ makes a
+    # retried create return the first result instead of a second project.
+    def create(display_name:, **opts)
+      body = { 'displayName' => display_name }
+      opts.each do |key, value|
+        wire = CREATE_FIELDS[key]
+        raise ArgumentError, "unknown projects.create option: #{key}" if wire.nil?
+
+        body[wire] = value unless value.nil?
+      end
+      UrlGrammar.validate_slug(opts[:slug], 'project') unless opts[:slug].nil?
       HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('projects'), body: body)
     end
 
+    # GET /projects/<slug>
     def get(slug)
       UrlGrammar.validate_slug(slug, 'project')
-      HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, 'project'))
+      HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path("projects/#{slug}"))
     end
 
-    def update(slug, name: nil)
+    # PATCH /projects/<slug>. Pass only the fields to change; an explicit +nil+ is sent as null
+    # (for +description+ that clears it).
+    def update(slug, **fields)
       UrlGrammar.validate_slug(slug, 'project')
       patch = {}
-      patch['name'] = name if name
-      HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.project_path(slug, 'project'), body: patch)
+      fields.each do |key, value|
+        wire = UPDATE_FIELDS[key]
+        raise ArgumentError, "unknown projects.update field: #{key}" if wire.nil?
+
+        patch[wire] = value
+      end
+      HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.org_path("projects/#{slug}"), body: patch)
     end
   end
 end

data/lib/k9o/query.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module K9o
+  # `client.query(sql, params)` and `client.search(collection, column:, q:)`.
+  #
+  # Wire (project-plane):
+  #   POST /@<slug>/query   body { sql:, params? }   -> { data: [row, ...], meta }
+  #   GET  /@<slug>/data/<collection>?textSearch=<column>:<q>...   (the select builder's +text_search+)
+  #
+  # +params+ is an Array (positional, bound to $1, $2, ...; the SQL is sent as written) or a Hash of named values
+  # (+:name+ placeholders are rewritten to $n here and the values become the positional list). Values are bound by
+  # the database, never interpolated into the SQL text.
+  module Query
+    IDENT_START = /[A-Za-z_]/.freeze
+    IDENT_CHAR = /[A-Za-z0-9_]/.freeze
+    DOLLAR_TAG = /\A\$([A-Za-z_][A-Za-z0-9_]*)?\$/.freeze
+
+    module_function
+
+    def invalid(message, context = {})
+      KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: message, context: context)
+    end
+
+    def check_value(value, where)
+      return value if value.nil? || value == true || value == false || value.is_a?(String)
+      return value if value.is_a?(Integer)
+      return value if value.is_a?(Float) && value.finite?
+
+      raise invalid("#{where} must be a string, number, boolean or nil; serialise anything else (for example as JSON text) first")
+    end
+
+    def lookup(named, name)
+      return [true, named[name]] if named.key?(name)
+      return [true, named[name.to_sym]] if named.key?(name.to_sym)
+
+      [false, nil]
+    end
+
+    # Rewrite +:name+ placeholders to $n. Skips quoted text, comments, dollar-quoted strings and +::+ casts.
+    # Returns [sql, params].
+    def translate_named_params(sql, named)
+      order = []
+      out = +''
+      i = 0
+      n = sql.length
+      while i < n
+        c = sql[i]
+        nxt = i + 1 < n ? sql[i + 1] : ''
+        if c == "'" || ((c == 'E' || c == 'e') && nxt == "'" && !(i > 0 && sql[i - 1] =~ IDENT_CHAR))
+          escapes = c != "'"
+          j = escapes ? i + 2 : i + 1
+          while j < n
+            if escapes && sql[j] == '\\'
+              j += 2
+              next
+            end
+            if sql[j] == "'"
+              if sql[j + 1] == "'"
+                j += 2
+                next
+              end
+              break
+            end
+            j += 1
+          end
+          out << sql[i...[j + 1, n].min]
+          i = j + 1
+        elsif c == '"'
+          j = i + 1
+          while j < n
+            if sql[j] == '"'
+              if sql[j + 1] == '"'
+                j += 2
+                next
+              end
+              break
+            end
+            j += 1
+          end
+          out << sql[i...[j + 1, n].min]
+          i = j + 1
+        elsif c == '-' && nxt == '-'
+          j = sql.index("\n", i) || n
+          out << sql[i...j]
+          i = j
+        elsif c == '/' && nxt == '*'
+          depth = 1
+          j = i + 2
+          while j < n && depth > 0
+            if sql[j, 2] == '/*'
+              depth += 1
+              j += 2
+            elsif sql[j, 2] == '*/'
+              depth -= 1
+              j += 2
+            else
+              j += 1
+            end
+          end
+          out << sql[i...j]
+          i = j
+        elsif c == '$'
+          m = DOLLAR_TAG.match(sql[i..-1])
+          if m
+            close = sql.index(m[0], i + m[0].length)
+            stop = close.nil? ? n : close + m[0].length
+            out << sql[i...stop]
+            i = stop
+          else
+            out << c
+            i += 1
+          end
+        elsif c == ':' && nxt == ':'
+          out << '::'
+          i += 2
+        elsif c == ':' && nxt != '' && nxt =~ IDENT_START && !(i > 0 && sql[i - 1] =~ IDENT_CHAR)
+          j = i + 2
+          j += 1 while j < n && sql[j] =~ IDENT_CHAR
+          name = sql[(i + 1)...j]
+          unless order.include?(name)
+            found, = lookup(named, name)
+            raise invalid("no value for :#{name}", name: name) unless found
+
+            order << name
+          end
+          out << "$#{order.index(name) + 1}"
+          i = j
+        else
+          out << c
+          i += 1
+        end
+      end
+      values = order.map { |name| check_value(lookup(named, name)[1], "the value for :#{name}") }
+      [out, values]
+    end
+
+    # Builds [path, body] for POST /@<slug>/query.
+    def prepare(config, sql, params)
+      slug = Studio.require_project_slug(config, 'query')
+      text = sql
+      values = []
+      if params.is_a?(Hash)
+        text, values = translate_named_params(sql, params)
+      elsif !params.nil?
+        values = params.each_with_index.map { |v, i| check_value(v, "params[#{i}]") }
+      end
+      body = { 'sql' => text }
+      body['params'] = values unless values.empty?
+      [UrlGrammar.project_path(slug, 'query'), body]
+    end
+  end
+
+  # Client-root methods mixed into K9oClient.
+  module QueryMethods
+    # POST /@<slug>/query — run one read-only SQL statement; +data+ is the array of rows.
+    # An Array binds positionally to $1, $2, ...; a Hash binds +:name+ placeholders.
+    def query(sql, params = nil)
+      path, body = Query.prepare(@config, sql, params)
+      HttpTransport.request(config: @config, method: 'POST', path: path, body: body)
+    end
+
+    # Full-text search over one text column of a collection, best matches first. Sugar over
+    # +from(collection).select.text_search(column, q, ...)+; +limit+ and +cursor+ page the result.
+    def search(collection, column:, q:, language: nil, type: nil, limit: nil, cursor: nil)
+      opts = {}
+      opts[:language] = language unless language.nil?
+      opts[:type] = type unless type.nil?
+      builder = from(collection).select.text_search(column, q, **opts)
+      builder.limit(limit) unless limit.nil?
+      builder.cursor(cursor) unless cursor.nil?
+      builder.execute
+    end
+  end
+end