k9o 1.2.0 → 1.3.0

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}"

data/lib/k9o/kibo.rb

@@ -97,14 +97,14 @@ module K9o
       case e
       when KiboKmsRestFfi::ZkFfiUniffiError::PostureViolation
         K9o::KError.new(
-          code: e.code, message: e.message,
+          code: e.code, message: e.detail,
           context: { dimension: e.dimension, requested: e.requested, declared: e.declared }
         )
       when KiboKmsRestFfi::ZkFfiUniffiError::Platform
-        K9o::KError.new(code: e.code, message: e.message)
+        K9o::KError.new(code: e.code, message: e.detail)
       when KiboKmsRestFfi::ZkFfiUniffiError::UpstreamKms
         # Customer's own KMS failed — no K9O_* code (outside the platform error namespace).
-        K9o::KError.new(code: 'UPSTREAM_KMS_ERROR', message: e.message)
+        K9o::KError.new(code: 'UPSTREAM_KMS_ERROR', message: e.detail)
       else
         K9o::KError.new(code: 'KIBO_FFI_ERROR', message: e.message)
       end

data/lib/k9o/me.rb

@@ -1,23 +1,21 @@
 # frozen_string_literal: true
 
 module K9o
-  # Operator-self namespace — k9o.me.*. Cross-org;
-  # org-plane routes under /me. Sub-namespaces: profile / sessions /
-  # api_tokens / notifications / audit_log / data_export.
+  # Operator-self namespace — k9o.me.*. Cross-org; org-plane routes under /me.
+  # Sub-namespaces: profile / sessions / api_tokens.
   class Me
-    attr_reader :profile, :sessions, :api_tokens, :notifications, :audit_log, :data_export
+    attr_reader :profile, :sessions, :api_tokens
 
     def initialize(config)
       @profile = Profile.new(config)
       @sessions = Sessions.new(config)
       @api_tokens = ApiTokens.new(config)
-      @notifications = Notifications.new(config)
-      @audit_log = AuditLog.new(config)
-      @data_export = DataExport.new(config)
     end
 
     # k9o.me.profile.*
     class Profile
+      PATCH_FIELDS = { display_name: 'displayName', locale: 'locale', timezone: 'timezone' }.freeze
+
       def initialize(config)
         @config = config
       end
@@ -26,9 +24,17 @@ module K9o
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me'))
       end
 
-      def update(display_name: nil)
-        HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.org_path('me'),
-                              body: { 'displayName' => display_name })
+      # PATCH /me. Pass only the fields to change (display_name, locale, timezone); an explicit +nil+ is sent as
+      # null.
+      def update(**fields)
+        patch = {}
+        fields.each do |key, value|
+          wire = PATCH_FIELDS[key]
+          raise ArgumentError, "unknown profile field: #{key}" if wire.nil?
+
+          patch[wire] = value
+        end
+        HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.org_path('me'), body: patch)
       end
     end
 
@@ -42,13 +48,15 @@ module K9o
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me/sessions'))
       end
 
+      # POST /auth/sessions/<id>/revoke
       def revoke(session_id)
-        HttpTransport.request(config: @config, method: 'DELETE',
-                              path: UrlGrammar.org_path("me/sessions/#{enc(session_id)}"))
+        HttpTransport.request(config: @config, method: 'POST',
+                              path: UrlGrammar.org_path("auth/sessions/#{enc(session_id)}/revoke"))
       end
 
+      # POST /me/sessions/revoke-all
       def revoke_all
-        HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.org_path('me/sessions'))
+        HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('me/sessions/revoke-all'))
       end
 
       private
@@ -68,10 +76,12 @@ module K9o
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me/api-tokens'))
       end
 
-      def create(name:, expires_in_days: nil, scope: nil)
-        body = { 'name' => name }
-        body['expiresInDays'] = expires_in_days if expires_in_days
-        body['scope'] = scope if scope
+      # POST /me/api-tokens { label, scopeManifest, ttlSeconds? }. +scope_manifest+ is a Hash with the gateway's keys
+      # (each may be nil for "no restriction"): 'operations' (read / write / admin), 'projects', 'resourceClasses',
+      # 'collections', 'cidrs'. The response carries the token's plaintext once.
+      def create(label:, scope_manifest:, ttl_seconds: nil)
+        body = { 'label' => label, 'scopeManifest' => scope_manifest }
+        body['ttlSeconds'] = ttl_seconds unless ttl_seconds.nil?
         HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('me/api-tokens'), body: body)
       end
 
@@ -86,75 +96,5 @@ module K9o
         ::URI.encode_www_form_component(s)
       end
     end
-
-    # k9o.me.notifications.*
-    class Notifications
-      def initialize(config)
-        @config = config
-      end
-
-      def list(unread_only: nil, limit: nil, cursor: nil)
-        q = {}
-        q['unreadOnly'] = unread_only unless unread_only.nil?
-        q['limit'] = limit if limit
-        q['cursor'] = cursor unless cursor.nil?
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me/notifications'), query: q)
-      end
-
-      def mark_read(notification_id)
-        HttpTransport.request(config: @config, method: 'PATCH',
-                              path: UrlGrammar.org_path("me/notifications/#{enc(notification_id)}"), body: { 'read' => true })
-      end
-
-      def mark_all_read
-        HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.org_path('me/notifications'),
-                              body: { 'read' => true })
-      end
-
-      private
-
-      def enc(s)
-        ::URI.encode_www_form_component(s)
-      end
-    end
-
-    # k9o.me.audit_log.*
-    class AuditLog
-      def initialize(config)
-        @config = config
-      end
-
-      def query(since: nil, until_: nil, type: nil, limit: nil, cursor: nil)
-        q = {}
-        q['since'] = since if since
-        q['until'] = until_ if until_
-        q['type'] = type if type
-        q['limit'] = limit if limit
-        q['cursor'] = cursor if cursor
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me/audit-log'), query: q)
-      end
-    end
-
-    # k9o.me.data_export.*
-    class DataExport
-      def initialize(config)
-        @config = config
-      end
-
-      def request(format: 'json')
-        HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('me/data-export'),
-                              body: { 'format' => format })
-      end
-
-      def status(job_id)
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path("me/data-export/#{enc(job_id)}"))
-      end
-
-      private
-
-      def enc(s)
-        ::URI.encode_www_form_component(s)
-      end
-    end
   end
 end

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,110 @@ 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, tierGating, ... }
+        #   idp_provider: google github microsoft oidc saml scim ldap active_directory apple facebook twitter
+        #   tier_gating:  'free_tier_ok' or 'ridge_plus'
+        #   client_secret_ref: a reference to the stored client secret, never the secret itself
+        def create(idp_provider:, display_name:, client_id:, client_secret_ref:, tier_gating:, **opts)
+          body = { 'idpProvider' => idp_provider, 'displayName' => display_name, 'clientId' => client_id,
+                   'clientSecretRef' => client_secret_ref, 'tierGating' => tier_gating }
+          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 +211,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