k9o 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7181cb157e2075ffed56c186db0de091dc3bffb8e87ed498451e3b4dc4629e9f
-  data.tar.gz: 41415d026e53bea0e505e702b5fefe58200a26092ae3176c684385bd49bad18d
+  metadata.gz: 40ba93ba07b61c2255541b842d863f178c808a14aa818960f6f34c046ffa56a0
+  data.tar.gz: db5cbcf71af58764f38a50a3926897bf584911bdf25c3b2b0c75ce4565564b22
 SHA512:
-  metadata.gz: ea526dce965974039710f5ab14776ac274271793e0ea95ac979d46a51bba7ab5b552e418a0401fc8cf138ddaade8e169f13ca96df9b4bac51a3d491e2a0f7acb
-  data.tar.gz: bed73f779902b19472006ad86eac056c8a47f89da96c94675a70f201fdfbdd6dd1e5aaf5a2e15e2a59f0bfb4e4b9024b2b61e078696e8dd144e8e36af305af2e
+  metadata.gz: e185588f9e7e453e008ec5ad828b941e79c647ad48645064374acf757b87fc38a9f384cf48a261d1273e8b947c0fd0f336afb3d744b4e8fa60d6f2424964adb8
+  data.tar.gz: 47a5f42f3c43d1bd00b0d2c8eaf1c9d6f0150aa85d9a288e49613fc2a796b3e05474b14d26e5c64b3c1259795d72544d9b3693834422a9252d51a88c14ed8409

data/CHANGELOG.md

@@ -1,38 +1,10 @@
 # Changelog — k9o (Ruby)
 
-## Unreleased
+## 1.1.0 — 2026-10-25
 
-- `client.storage` buckets and objects — flat methods `create_bucket(name, ...)` / `get_bucket` / `list_buckets` / `update_bucket(name, patch)` / `delete_bucket(name, empty: false)` against `/@<slug>/storage/buckets[/<bucket>]` (`?empty=true` sent only when `empty: true`), and `storage.from(bucket)` handles with `upload(path, data, content_type:, upsert:, metadata:)` (a real `multipart/form-data` body built with the stdlib; the transport no longer forces a JSON content type for it), `create_signed_url(path, expires_in:, download:)`, `list(prefix:)` and `remove(path)`. `expires_in` is required, an Integer 1..604800, refused client-side with `K9O_INVALID_FIELD_VALUE` before any request; no default. Bucket and path values are always URL-encoded and never rewritten. No signed-PUT upload URL and no copy (no gateway route). Requires a bound `project_slug`. Adds `K9o::Storage` and `K9o::Multipart`; `HttpTransport.request(multipart:)`.
-- `client.gate.hosted` — `GET /@<slug>/gate/hosted`; returns the envelope `{ 'signInUrl', 'rpId' }` for the project's hosted sign-in page. Unauthenticated: no `Authorization` or `Cookie` header is sent even when `api_key` is configured. An unknown org, a deleted project and a non-Gate project all surface the same 404 `K9O_PROJECT_NOT_FOUND`. Requires a bound `project_slug`. Adds `HttpTransport.request(authenticated: false)`.
-- `client.ai.embed(input:, model: nil)` — `POST /@<slug>/ai/embeddings`; `input` is one string or an array of strings, sent exactly as given; `model` is omitted from the body when not given. Requires a bound `project_slug` (`K9O_MISSING_PROJECT_CONTEXT` otherwise). The input text never appears in an SDK-constructed error. Adds `K9o::Ai`.
+- Documentation rewritten with runnable examples and expected output; internal cross-references removed from the published sources. No change to the public API.
+- Error text for `update()` / `delete()` without an `id` filter no longer mentions a version or a roadmap.
 
-## v0.1.0 — 2026-05-26 (P3 wave 7 — Ruby idiomatic reshape; FINAL P3 WAVE)
+## 1.0.0 — 2026-10-23
 
-**Reshape** of `packages/ruby` from prior OpenAPI-generated `k9o-gate@0.3.0` raw client (214-file output; wrong gem name; not idiomatic) to hand-authored idiomatic `k9o` gem.
-
-NEW surfaces:
-
-- `K9o.create_client(base_url:, api_key:, org_slug:, project_slug:, ...)` factory + baseUrl validation (keyword arguments per Ruby idiom)
-- `K9o::KError < StandardError` — `.code` / `.message` / `.context` (frozen) / `.recommendation` / `.status` / `.request_id` readers; `#message` overridden to return raw text (avoids infinite recursion with `#to_s` override); `with_recommendation` helper
-- `K9o::Envelope` + `K9o::Meta` with 6 typed sub-accessor classes (`MetaCursor` / `MetaSubscription` Struct / `MetaIdempotency` Struct / `MetaWarning` Struct / `MetaTiming` Struct / `MetaContext` Struct); `from_wire` constructs from gateway JSON
-- `K9o::UrlGrammar.{validate_base_url, validate_slug, project_path, org_path, platform_path}` module functions; raises KError on violation
-- Data-plane DSL `client.from('collection')` chainable filter builder (11 ops: eq / neq / gt / gte / lt / lte / like / ilike / is + `in_(col, [...])` / `not_in` + generic `filter`) + `.limit(n)` / `.cursor(s)` / `.count(mode)` + `.execute` terminal; insert/update/delete with `.eq("id", ...)` discipline
-- `client.projects.{list, create(slug:, name:), get(slug), update(slug, name:)}` (keyword args)
-- `client.gate.{sign_up(email:, password:), sign_in(email:, password:), sign_out(refresh_token:), whoami, refresh_token(refresh_token:), verify_session}` (project-scoped; keyword args)
-- HTTP layer: `Net::HTTP` stdlib; KError rehydration on non-2xx; transport failure → K9O_UPSTREAM_UNAVAILABLE; malformed envelope → K9O_INTERNAL_ERROR; injectable `http_client:` for tests
-
-**Tests:** 21 pass / 54 assertions / 0 fail (`ruby test/*.rb` against system Ruby 2.6; gem targets 3.2+ per ch13 spec):
-- 5 KErrorTest (construct + raisable + to_s with status + with_recommendation + from_wire rehydration)
-- 8 UrlGrammarTest (accepts/rejects + path builders)
-- 8 ClientTest (construct + normalise + reject + DSL select/update requirements + projects + gate + collection validation)
-
-**Dependencies:** Ruby 3.2+ runtime; stdlib only (`Net::HTTP`, `json`, `uri`).
-**Dev:** minitest 5.20.
-
-Dropped Ruby from `openapitools.json` + `package.json` `sdks:generate:ruby` — hand-authored against `services/gateway/openapi.json` contract going forward.
-
-**P3 7-wave reshape COMPLETE.** All 7 server SDKs (Python + Go + Rust + Java + .NET + PHP + Ruby) shipped as idiomatic per-language reshapes.
-
----
-
-**Prior history**: `k9o-gate@0.3.0` OpenAPI-generator output retired at this version.
+First public release. See the README for the full API overview.

data/README.md

@@ -1,67 +1,546 @@
-# k9o — Kilimanjaro platform SDK (Ruby)
+# k9o
 
-Idiomatic Ruby SDK. `snake_case` methods; raise `K9o::KError`; keyword arguments; Net::HTTP stdlib transport.
+The Kilimanjaro platform SDK for Ruby.
 
-## Status
+Documentation: https://kilimanjaro.dev. Platform API: https://api.k9o.io.
 
-v0.1.0 — first-pass idiomatic ship (P3 wave 7; reshape from prior `k9o-gate@0.3.0` OpenAPI codegen).
+## Contents
 
-## Install (when published to RubyGems)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Authentication and project context](#authentication-and-project-context)
+- [Running queries](#running-queries)
+- [Handling errors](#handling-errors)
+- [Appendix](#appendix)
+- [License](#license)
+
+## Install
 
 ```bash
 gem install k9o
 ```
 
+Or add it to your `Gemfile`:
+
+```ruby
+gem "k9o"
+```
+
+Requires Ruby 3.2 or newer. See [requirements](#requirements) for details.
+
 ## Quick start
 
+The examples use a `tasks` collection with `title` and `done` fields.
+
+### Create the client
+
 ```ruby
-require 'k9o'
+require "k9o"
 
 k9o = K9o.create_client(
-  base_url: "https://acme.api.k9o.io",
-  api_key: ENV["K9O_API_KEY"],
   org_slug: "acme",
-  project_slug: "member-portal"
+  project_slug: "task-app",
+  api_key: ENV.fetch("K9O_API_KEY")
+)
+```
+
+### Add a task
+
+```ruby
+new_task = { "title" => "Write the README", "done" => false }
+created = k9o.from("tasks").insert(new_task)
+puts "created: #{created.data['title']}"
+```
+
+```text
+created: Write the README
+```
+
+### List tasks
+
+```ruby
+response = k9o.from("tasks").select.eq("done", false).limit(10).execute
+response.data.each do |task|
+  puts "#{task['title']} #{task['done']}"
+end
+```
+
+```text
+Write the README false
+```
+
+### Update and delete a task
+
+Both calls need an `eq("id", ...)` filter.
+
+```ruby
+task_id = created.data["id"]
+
+patch = { "done" => true }
+k9o.from("tasks").update(patch).eq("id", task_id).execute
+
+k9o.from("tasks").delete.eq("id", task_id).execute
+```
+
+## Authentication and project context
+
+The client needs a key and, for project calls, an org and project.
+
+| Option | What it does |
+|---|---|
+| `api_key:` | Bearer token sent with every request. |
+| `org_slug:` | Organization. On the default host the SDK uses `https://<org_slug>.api.k9o.io`. |
+| `project_slug:` | Project. Required by every project-scoped namespace. |
+
+See [client options](#client-options) for every option.
+
+### Choose a host
+
+Pick one of two forms.
+
+- Default platform host: pass the org slug, project slug and key.
+- Custom or self-hosted host: pass `base_url`, project slug and key, and no org slug.
+
+```ruby
+k9o = K9o.create_client(
+  base_url: "https://k9o.internal.example.com",
+  project_slug: "task-app",
+  api_key: ENV.fetch("K9O_API_KEY")
 )
+```
+
+The base URL rules are listed under [regional hosts](#regional-hosts).
+
+## Running queries
 
+Chain filters on `select`, then call `execute`. The result carries rows in `data` and details in `meta`.
+
+| Call | What it does |
+|---|---|
+| `eq(column, value)` | Keep rows where the column equals the value. |
+| `limit(n)` | Return at most `n` rows. |
+| `cursor(token)` | Continue from `meta.cursor.next`. |
+
+See [filters](#filters) and [paging](#paging) for all calls, and [response metadata](#response-metadata) for every `meta` field.
+
+A sub-object the server did not send is `nil`, so use `&.` when it may be absent.
+
+```ruby
+request_id = response.meta.context.request_id
+total = response.meta.cursor.total_count
+puts "#{request_id} #{total}"
+```
+
+```text
+req_01H... 1
+```
+
+## Handling errors
+
+Failures raise `K9o::KError`, a subclass of `StandardError`. Branch on `code`.
+
+```ruby
 begin
-  response = k9o.from("posts").select.limit(10).execute
-  response.data.each { |row| puts row }
-  puts "next cursor: #{response.meta.cursor&.next}"
-
-  session = k9o.gate.sign_in(email: "u@x.com", password: "...")
-  puts "signed in: #{session.data['user']['id']}"
-rescue K9o::KError => e
-  warn "[#{e.code}] #{e.message}: #{e.recommendation}"
-  raise
+  k9o.from("missing").select.execute
+rescue K9o::KError => error
+  puts "#{error.code} #{error.status} #{error.request_id}"
+  puts error.message
 end
 ```
 
-## Idiomatic shape (per ch13)
+```text
+K9O_NOT_FOUND 404 req_01H...
+Collection not found
+```
+
+- See [error attributes](#error-attributes) for every field.
+- See [error codes](#error-codes) for the codes the SDK raises.
+- See [retries](#retries) for automatic retry rules.
+
+
+## Appendix
+
+### Requirements
+
+| Requirement | Version |
+|---|---|
+| `Ruby` | 3.2 or newer |
+| `Runtime gems` | None (uses `Net::HTTP`, `json` and `uri` from the standard library) |
+
+### Client options
+
+| Option | What it does |
+|---|---|
+| `api_key:` | Bearer token sent with every request. |
+| `org_slug:` | Organization. On the default host the SDK uses `https://<org_slug>.api.k9o.io`. |
+| `project_slug:` | Project. Required by every project-scoped namespace. |
+| `base_url:` | Scheme and host only. Defaults to `https://api.k9o.io`. |
+| `default_headers:` | Extra headers added to every request. |
+| `http_client:` | A `Net::HTTP`-compatible object used instead of the default connection. |
+
+`org_slug` and `project_slug` are also sent as the `x-k9o-org-slug` and `x-k9o-project-slug` headers.
+
+### Methods by namespace
+
+Every method is called on the client, for example `k9o.projects.list`. Return values are `Envelope` objects.
+
+
+
+#### Data
+
+`k9o.from(collection)` reads and writes rows in one collection of the active project.
+
+| Method | What it does |
+|---|---|
+| `select` | Start a query. Finish with `execute`. |
+| `insert(record)` | Add one row and return it. |
+| `update(patch)` | Change one row. Needs `eq("id", ...)`. |
+| `delete` | Remove one row. Needs `eq("id", ...)`. |
+
+##### Filters
+
+Chain filters before `execute`. Values are matched against one column.
+
+| Method | What it does |
+|---|---|
+| `eq(column, value)` | Equal to value. |
+| `neq(column, value)` | Not equal to value. |
+| `gt(column, value)` | Greater than value. |
+| `gte(column, value)` | Greater than or equal. |
+| `lt(column, value)` | Less than value. |
+| `lte(column, value)` | Less than or equal. |
+| `in_(column, values)` | Equal to any value in the list. |
+| `not_in(column, values)` | Equal to none of the values. |
+| `like(column, pattern)` | Case-sensitive pattern match. |
+| `ilike(column, pattern)` | Case-insensitive pattern match. |
+| `is(column, value)` | Match `null`, `true` or `false`. |
+| `filter(column, op, value)` | Generic form with an explicit operator name. |
+
+##### Paging
+
+| Method | What it does |
+|---|---|
+| `limit(n)` | Maximum rows to return. |
+| `cursor(token)` | Continue from `meta.cursor.next`. |
+| `count(mode)` | Row count mode: `none`, `exact` or `estimated`. |
+
+#### Projects
+
+`k9o.projects` manages projects in the active organization.
+
+| Method | What it does |
+|---|---|
+| `k9o.projects.list` | List projects you can access. |
+| `k9o.projects.create` | Create a project from `slug` and `name`. |
+| `k9o.projects.get` | Read a project by slug. |
+| `k9o.projects.update` | Change a project's `name`. |
+
+#### Gate (end-user sign-in)
+
+`k9o.gate` signs in the active project's end users and needs `project_slug`.
+
+| Method | What it does |
+|---|---|
+| `k9o.gate.sign_up` | Create an end user from email and password. |
+| `k9o.gate.sign_in` | Sign in with email and password. |
+| `k9o.gate.sign_out` | Revoke the session's refresh token. |
+| `k9o.gate.whoami` | Return the signed-in identity. |
+| `k9o.gate.refresh_token` | Exchange a refresh token for a new access token. |
+| `k9o.gate.verify_session` | Check that the current session is valid. |
+| `k9o.gate.hosted` | Return the hosted sign-in `signInUrl` and `rpId`. |
+
+```ruby
+session = k9o.gate.sign_in(email: "ada@example.com", password: "correct-horse")
+user = session.data["user"]
+puts user["email"]
+```
+
+```text
+ada@example.com
+```
+
+#### Storage
+
+`k9o.storage` manages buckets and the objects inside them.
+
+##### Buckets
+
+| Method | What it does |
+|---|---|
+| `k9o.storage.create_bucket` | Create a bucket by name. |
+| `k9o.storage.get_bucket` | Read one bucket. |
+| `k9o.storage.list_buckets` | List buckets. |
+| `k9o.storage.update_bucket` | Change bucket settings. |
+| `k9o.storage.delete_bucket` | Delete a bucket. Pass `empty` to purge its objects first. |
+
+##### Objects
+
+`k9o.storage.from(bucket)` returns a handle for one bucket.
+
+| Method | What it does |
+|---|---|
+| `k9o.storage.from(bucket).upload` | Store bytes at a path. Existing paths are kept unless `upsert` is true. |
+| `k9o.storage.from(bucket).create_signed_url` | Create a time-limited download link. |
+| `k9o.storage.from(bucket).list` | List objects, optionally under a `prefix`. |
+| `k9o.storage.from(bucket).remove` | Delete the object at a path. |
+
+`expires_in` is required, in seconds from 1 to 604800.
+
+```ruby
+avatars = k9o.storage.from("avatars")
+avatars.upload("ada.png", "...image bytes...", content_type: "image/png")
+signed = avatars.create_signed_url("ada.png", expires_in: 300)
+```
+
+#### Functions
+
+`k9o.functions` deploys and runs server-side functions.
+
+| Method | What it does |
+|---|---|
+| `k9o.functions.deploy` | Deploy a function from `name`, `runtime` and `code`. |
+| `k9o.functions.list` | List functions. |
+| `k9o.functions.get` | Read one function by name. |
+| `k9o.functions.delete` | Remove a function. |
+| `k9o.functions.invoke` | Run a function with a payload. |
+
+#### Migrations
+
+`k9o.migrations` changes the project's schema.
+
+| Method | What it does |
+|---|---|
+| `k9o.migrations.apply` | Apply migrations now. |
+| `k9o.migrations.list` | List applied migrations. |
+| `k9o.migrations.get` | Read one migration by version. |
+| `k9o.migrations.queue` | Queue migrations for approval. |
+| `k9o.migrations.list_pending` | List queued migrations. |
+| `k9o.migrations.apply_pending` | Apply one queued migration. |
+| `k9o.migrations.reject_pending` | Reject one queued migration. |
+| `k9o.migrations.delete_pending` | Delete one queued migration. |
+
+#### Policies
+
+`k9o.policies` manages access policy bundles.
+
+| Method | What it does |
+|---|---|
+| `k9o.policies.current` | Read the published bundle. |
+| `k9o.policies.list` | List bundles. |
+| `k9o.policies.create` | Create a bundle from `name` and `rules`. |
+| `k9o.policies.validate` | Check rules without saving. |
+| `k9o.policies.get` | Read one bundle. |
+| `k9o.policies.update` | Change a bundle. |
+| `k9o.policies.delete` | Remove a bundle. |
+| `k9o.policies.publish` | Make a bundle current. |
+
+#### Audit
+
+`k9o.audit` reads the project's audit events.
+
+| Method | What it does |
+|---|---|
+| `k9o.audit.query` | Search events by time range, type and more. |
+
+#### AI embeddings
+
+`k9o.ai` creates text embeddings.
+
+| Method | What it does |
+|---|---|
+| `k9o.ai.embed(input:, model: nil)` | Embed one string or a list of strings. |
+
+#### Language models
+
+`k9o.compute.llms` lists and calls hosted models.
+
+| Method | What it does |
+|---|---|
+| `k9o.compute.llms.list` | List available models. |
+| `k9o.compute.llms.read` | Read one model. |
+| `k9o.compute.llms.invoke` | Send a prompt and get the reply. |
+| `k9o.compute.llms.invoke_stream` | Stream the reply token by token (returns an `Enumerator`). |
+
+#### Realtime
+
+`k9o.realtime` delivers live events for a topic.
+
+| Method | What it does |
+|---|---|
+| `k9o.realtime.subscribe` | Stream live events (returns an `Enumerator`). |
+| `k9o.realtime.replay` | Read past events from a sequence number. |
+| `k9o.realtime.subscribe_poll` | Poll for events from a sequence number. |
+
+`K9o::Realtime::Topic` builds topic names, for example `Topic.collection("tasks")`.
+
+#### Studio
+
+`k9o.studio` manages workflows and dashboards.
+
+##### Workflows
+
+| Method | What it does |
+|---|---|
+| `k9o.studio.workflows.list` | List workflows. |
+| `k9o.studio.workflows.create` | Create a workflow. |
+| `k9o.studio.workflows.read` | Read one workflow. |
+| `k9o.studio.workflows.update` | Change a workflow. |
+| `k9o.studio.workflows.delete` | Delete a workflow. |
+| `k9o.studio.workflows.trigger` | Start a run. |
+| `k9o.studio.workflows.runs.list` | List a workflow's runs. |
+| `k9o.studio.workflows.runs.read` | Read one run. |
+| `k9o.studio.workflows.runs.cancel` | Cancel a run. |
+
+##### Dashboards
+
+| Method | What it does |
+|---|---|
+| `k9o.studio.dashboards.list` | List dashboards. |
+| `k9o.studio.dashboards.create` | Create a dashboard. |
+| `k9o.studio.dashboards.read` | Read one dashboard. |
+| `k9o.studio.dashboards.update` | Change a dashboard. |
+| `k9o.studio.dashboards.delete` | Delete a dashboard. |
+| `k9o.studio.dashboards.pin` | Pin to the workspace. |
+| `k9o.studio.dashboards.unpin` | Remove from the workspace. |
+
+#### Current user
+
+`k9o.me` covers the signed-in account.
+
+| Method | What it does |
+|---|---|
+| `k9o.me.profile.get` | Read the profile. |
+| `k9o.me.profile.update` | Change the display name. |
+| `k9o.me.sessions.list` | List active sessions. |
+| `k9o.me.sessions.revoke` | End one session. |
+| `k9o.me.sessions.revoke_all` | End all sessions. |
+| `k9o.me.api_tokens.list` | List API tokens. |
+| `k9o.me.api_tokens.create` | Create an API token. |
+| `k9o.me.api_tokens.delete` | Delete an API token. |
+| `k9o.me.notifications.list` | List notifications. |
+| `k9o.me.notifications.mark_read` | Mark one as read. |
+| `k9o.me.notifications.mark_all_read` | Mark all as read. |
+| `k9o.me.audit_log.query` | Search your own audit events. |
+| `k9o.me.data_export.request` | Request a data export. |
+| `k9o.me.data_export.status` | Check an export job. |
+
+#### Organization
+
+`k9o.orgs` lists organizations and `k9o.org` administers the active one.
+
+##### Organizations
+
+| Method | What it does |
+|---|---|
+| `k9o.orgs.list` | List your organizations. |
+| `k9o.orgs.get` | Read one by slug. |
+| `k9o.orgs.current` | Read the active organization. |
+| `k9o.orgs.restore` | Restore a deleted organization. |
+
+##### Administration
+
+| Method | What it does |
+|---|---|
+| `k9o.org.get` | Read the active organization. |
+| `k9o.org.members.list` | List members. |
+| `k9o.org.members.invite` | Invite a member by email and role. |
+| `k9o.org.members.get` | Read one member. |
+| `k9o.org.members.remove` | Remove a member. |
+| `k9o.org.groups.list` | List groups. |
+| `k9o.org.groups.create` | Create a group. |
+| `k9o.org.groups.get` | Read one group. |
+| `k9o.org.groups.delete` | Delete a group. |
+| `k9o.org.audit_log.query` | Search organization audit events. |
+| `k9o.org.gate.roles.list` | List role grants. |
+| `k9o.org.gate.roles.grant` | Grant a role to a user. |
+| `k9o.org.gate.roles.get` | Read one grant. |
+| `k9o.org.gate.roles.revoke` | Revoke a grant. |
+| `k9o.org.gate.idp_providers.list` | List identity providers. |
+| `k9o.org.gate.idp_providers.create` | Add an identity provider. |
+| `k9o.org.gate.idp_providers.get` | Read one provider. |
+| `k9o.org.gate.idp_providers.configure` | Change a provider. |
+| `k9o.org.gate.idp_providers.delete` | Remove a provider. |
+| `k9o.org.smtp.get` | Read the mail server settings. |
+| `k9o.org.smtp.set` | Save the mail server settings. |
+| `k9o.org.smtp.test` | Send a test email. |
+| `k9o.org.smtp.unset` | Remove the mail server settings. |
+| `k9o.org.default_llm.get` | Read the default model. |
+| `k9o.org.default_llm.set` | Set the default model. |
+
+#### Vault secrets
+
+`k9o.kibo.vault.secrets` stores and reveals secrets in the project's vault.
+
+| Method | What it does |
+|---|---|
+| `k9o.kibo.vault.secrets.list` | List secrets by prefix. |
+| `k9o.kibo.vault.secrets.get` | Read a secret's details. |
+| `k9o.kibo.vault.secrets.create` | Store a new secret. |
+| `k9o.kibo.vault.secrets.reveal_challenge` | Get a one-time challenge for revealing. |
+| `k9o.kibo.vault.secrets.reveal` | Reveal the value using the challenge. |
+| `k9o.kibo.vault.secrets.update` | Replace the value. |
+| `k9o.kibo.vault.secrets.rotate` | Rotate the secret. |
+| `k9o.kibo.vault.secrets.move` | Move to a new path. |
+| `k9o.kibo.vault.secrets.delete` | Delete the secret. |
+
+### Response metadata
+
+| Field | What it holds |
+|---|---|
+| `meta.cursor` | Pagination: `next` and `total_count`. |
+| `meta.context` | Request tracing: `request_id`. |
+| `meta.timing` | Server time: `total_ms`. |
+| `meta.warnings` | List of non-fatal warnings, each with `code` and `message`. |
+| `meta.idempotency` | `replayed` flag for repeated requests. |
+| `meta.subscription` | `is_initial` flag for streamed events. |
+| `meta.cost` | Usage cost details as a hash. |
 
-| Aspect | This SDK |
+### Error attributes
+
+| Attribute | Meaning |
+|---|---|
+| `code` | Error code such as `K9O_NOT_FOUND`. |
+| `message` | Human-readable explanation. |
+| `recommendation` | Suggested next step, or `nil`. |
+| `status` | HTTP status, or `nil` if no request was made. |
+| `request_id` | Server trace id. Quote it when contacting support. |
+| `context` | Read-only details for the error. |
+
+The server may send codes not listed here, so keep a fallback branch.
+
+### Error codes
+
+| Code | When |
 |---|---|
-| Gem name | `k9o` (RubyGems) |
-| Module | `K9o` |
-| Method casing | `snake_case` |
-| Error delivery | `raise K9o::KError < StandardError` |
-| Factory pattern | `K9o.create_client(base_url:, api_key:, org_slug:, project_slug:)` (keyword args) |
-| Data DSL entry | `client.from('collection')` |
-| Filter chain | `.eq(col, val)` / `.gt()` / `.in_(col, [...])` / `.is(col, val)` / `.filter(col, op, val)` |
-| Terminal verb | `.execute` (parameterless method chain — Ruby idiom) |
-| Meta accessor | `response.meta.cursor&.next` (safe-navigation `&.`); `.meta.timing&.total_ms`; `.meta.context&.request_id` |
-| Wire format | Always camelCase JSON; explicit field-name translation in `Envelope.from_wire` |
-| Runtime | Ruby 3.2+ (per ch13 §2.1.8 spec) |
-| HTTP library | `Net::HTTP` (stdlib; no external deps) |
+| `K9O_INVALID_BASE_URL` | `base_url` has a path, query or bad scheme. |
+| `K9O_MISSING_PROJECT_CONTEXT` | A project call was made without `project_slug`. |
+| `K9O_INVALID_FIELD_VALUE` | An argument failed validation before sending. |
+| `K9O_UPSTREAM_UNAVAILABLE` | Network failure reaching the gateway. |
+| `K9O_INTERNAL_ERROR` | The response could not be read. |
+
+`error.to_s` reads like `[K9O_NOT_FOUND] Collection not found (status=404)`.
 
-## Architectural notes
+### Retries
 
-- **Stdlib only**: uses `Net::HTTP` + `json` + `uri`; no Typhoeus or Faraday.
-- **Keyword arguments throughout**: `K9o.create_client(base_url:, api_key:, ...)` and `k9o.gate.sign_in(email:, password:)` per Ruby 3.x idiom.
-- **`&.` safe navigation**: caller pattern `response.meta.cursor&.next` (cursor may be nil if gateway omits the sub-namespace).
-- **`message` override**: `K9o::KError#message` returns the raw text directly to avoid infinite recursion with `to_s` override (Ruby's `Exception#message` calls `to_s` by default).
-- **`.execute` method**: no parens for terminal verb per Ruby convention; chain reads naturally.
+- GET, HEAD, OPTIONS and DELETE are retried on network errors.
+- They are also retried on 429, 502, 503 and 504.
+- The default is 3 retries with exponential backoff.
+- Other methods are never retried.
+
+### Regional hosts
+
+- Organization hosts such as `https://acme.api.k9o.io` are region-free.
+- The SDK sends one credential-free `HEAD` request to learn the region.
+- Later requests go to the regional host.
+- Any other base URL is used exactly as given.
+
+### Related packages
+
+| Package | What it is |
+|---|---|
+| `@k9o/core` | TypeScript SDK |
+| `@k9o/cli` | Command-line tool |
 
 ## License
 
-UNLICENSED — internal to Kilimanjaro.
+Apache-2.0 © Formelo Inc. See `LICENSE` and `NOTICE`.

data/lib/k9o/client.rb

@@ -36,7 +36,7 @@ module K9o
 
   # Factory — construct a K9oClient bound to the supplied options.
   #
-  # Per ch13 §2.1.8 spec sample:
+  # Per spec sample:
   #   k9o = K9o.create_client(
   #     api_key: ENV["K9O_API_KEY"],
   #     org_slug: "acme",

data/lib/k9o/compute.rb

@@ -4,7 +4,7 @@ module K9o
   # Compute namespace (Compute LLMs registry).
   # k9o.compute.llms.*
   class Compute
-    # Curated 9-model closed enum per ch07 §10.1 (extensible v2.x).
+    # Curated 9-model closed enum (extensible v2.x).
     LLM_MODEL_IDS = %w[
       mistral-7b mistral-8x7b llama-3-8b llama-3-70b
       claude-3-5-sonnet gpt-4o gpt-4o-mini
@@ -17,7 +17,7 @@ module K9o
       @llms = Llms.new(config)
     end
 
-    # k9o.compute.llms.* per ch07 §10.
+    # k9o.compute.llms.*.
     class Llms
       def initialize(config)
         @config = config
@@ -36,7 +36,7 @@ module K9o
                               path: UrlGrammar.project_path(slug, "compute/llms/#{enc(model_id)}"))
       end
 
-      # Synchronous inference per ch07 §10.2 (PROJECT_AUTHOR/ADMIN).
+      # Synchronous inference (PROJECT_AUTHOR/ADMIN).
       def invoke(model_id, prompt:, params: nil)
         slug = Studio.require_project_slug(@config, 'compute.llms')
         body = { 'prompt' => prompt }
@@ -45,8 +45,8 @@ module K9o
                               path: UrlGrammar.project_path(slug, "compute/llms/#{enc(model_id)}/invoke"), body: body)
       end
 
-      # Streaming inference (SSE per-token) per ch07 §10.2. Returns an
-      # Enumerator of chunk hashes (ch13 §8 Ruby idiom). Consume with
+      # Streaming inference (SSE per-token). Returns an
+      # Enumerator of chunk hashes (Ruby idiom). Consume with
       # `.each { |chunk| ... }`.
       def invoke_stream(model_id, prompt:, params: nil)
         slug = Studio.require_project_slug(@config, 'compute.llms')

data/lib/k9o/data.rb

@@ -132,7 +132,7 @@ module K9o
       id_filter = @filters.find { |col, op, _| col == 'id' && op == 'eq' }
       raise KError.new(
         code: 'K9O_INVALID_FIELD_VALUE',
-        message: 'update() requires .eq("id", ...) filter; row-mass update is not supported at v0.1.0',
+        message: 'update() requires .eq("id", ...) filter; changing many rows in one call is not supported',
         context: { collection: @collection }
       ) unless id_filter
 
@@ -146,7 +146,7 @@ module K9o
       id_filter = @filters.find { |col, op, _| col == 'id' && op == 'eq' }
       raise KError.new(
         code: 'K9O_INVALID_FIELD_VALUE',
-        message: 'delete() requires .eq("id", ...) filter; row-mass delete is not supported at v0.1.0',
+        message: 'delete() requires .eq("id", ...) filter; deleting many rows in one call is not supported',
         context: { collection: @collection }
       ) unless id_filter
 

data/lib/k9o/envelope.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module K9o
-  # Standard ch01 §1.1 envelope returned by every k9o surface on success.
+  # Standard envelope returned by every k9o surface on success.
   class Envelope
     attr_reader :data, :meta
 
@@ -18,7 +18,7 @@ module K9o
     end
   end
 
-  # Meta accessor sugar per ch13 §5.
+  # Meta accessor sugar.
   class Meta
     attr_reader :cursor, :subscription, :idempotency, :warnings, :cost, :timing, :context
 

data/lib/k9o/http_transport.rb

@@ -6,7 +6,7 @@ require 'uri'
 require_relative 'multipart'
 
 module K9o
-  # Retry + backoff policy (ch13 §7.1). Applied to idempotent methods
+  # Retry + backoff policy. Applied to idempotent methods
   # (GET/HEAD/OPTIONS/DELETE) on transient failures only (transport error /
   # 502 / 503 / 504 / 429); semantic 4xx and non-idempotent methods are
   # never retried.
@@ -55,7 +55,7 @@ module K9o
     module_function
 
     # Issue a request with retry on transient failures. Idempotent methods
-    # are retried with backoff per config.retry_config (ch13 §7.1);
+    # are retried with backoff per config.retry_config;
     # semantic / non-idempotent failures raise immediately.
     #
     # `headers:` carries per-call header overrides on top of
@@ -210,12 +210,12 @@ module K9o
     end
 
     # Open an SSE stream and return an Enumerator yielding decoded `data:`
-    # payloads (parsed JSON). Used by Compute LLMs #invoke_stream (ch07
-    # §10.2) + Realtime #subscribe SSE transport (ch07 §11.3). The [DONE]
+    # payloads (parsed JSON). Used by Compute LLMs #invoke_stream
+    # and the Realtime #subscribe SSE transport. The [DONE]
     # sentinel terminates the stream; non-2xx raises KError before any
     # event is yielded.
     #
-    # Per ch13 §8 the Ruby async-iteration idiom is Enumerator — caller
+    # Per 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/migrations.rb

@@ -3,7 +3,7 @@
 module K9o
   # Migration lifecycle namespace — k9o.migrations.*.
   #
-  # TYPE MODEL (ch13 §2.2, cemented f21b3c15 — Ruby is TIER-3):
+  # TYPE MODEL (, cemented f21b3c15 — Ruby is TIER-3):
   #
   #   Ruby keeps a RUNTIME HASH PASS-THROUGH for migration payloads (the
   #   gateway is the fail-closed source of truth; SDK types are ergonomics +
@@ -104,7 +104,7 @@ module K9o
                             path: UrlGrammar.project_path(slug, "migrations/#{enc(version)}"))
     end
 
-    # Queue migrations for maker-checker approval per ch06 §8.
+    # Queue migrations for maker-checker approval.
     def queue(migrations)
       slug = require_project_slug
       HttpTransport.request(config: @config, method: 'POST',

data/lib/k9o/org.rb

@@ -4,7 +4,7 @@ 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 per v2.5.68 §5.4 routes against the org subdomain
+  # Org-plane URL grammar routes against the org subdomain
   # without the @<projectSlug>/ prefix.
   class Org
     attr_reader :members, :groups, :smtp, :audit_log, :gate, :default_llm
@@ -192,7 +192,7 @@ module K9o
       end
     end
 
-    # k9o.org.default_llm.* per ch07 §10.3 (ORG_ADMIN; tier-gated).
+    # k9o.org.default_llm.* (ORG_ADMIN; tier-gated).
     class DefaultLlm
       def initialize(config)
         @config = config
@@ -203,7 +203,7 @@ module K9o
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('org/default-llm'))
       end
 
-      # Set the org-default LLM (ORG_ADMIN; tier-gated per §10.1).
+      # Set the org-default LLM (ORG_ADMIN; tier-gated).
       def set(model_id)
         HttpTransport.request(config: @config, method: 'PATCH',
                               path: UrlGrammar.org_path('org/default-llm'), body: { 'modelId' => model_id })

data/lib/k9o/realtime.rb

@@ -3,8 +3,8 @@
 module K9o
   # Realtime Subscriptions namespace (ALL-LIVE primitive).
   #
-  # Ruby idiom per ch13 §8: #subscribe returns an Enumerator iterated via
-  # `.each`. Per ch07 §11.3 + the SDK-abstracted-primitive discipline the
+  # Ruby idiom: #subscribe returns an Enumerator iterated via
+  # `.each`. Per + the SDK-abstracted-primitive discipline the
   # SDK picks the transport; SPLIT (polling) is the internal fallback. The
   # Net::HTTP-based Ruby SDK uses SSE primary (no stdlib WebSocket);
   # #subscribe_poll exposes the poll fallback. #replay is one-shot catch-up.
@@ -13,7 +13,7 @@ module K9o
       @config = config
     end
 
-    # Subscribe via SSE transport (primary per §11.3); returns an
+    # Subscribe via SSE transport (primary); returns an
     # Enumerator yielding event hashes.
     def subscribe(topic, filter: nil)
       slug = Studio.require_project_slug(@config, 'realtime')
@@ -23,7 +23,7 @@ module K9o
                                path: UrlGrammar.project_path(slug, 'realtime/subscribe'), query: q)
     end
 
-    # One-shot historical replay per ch07 §11.2 (capped 10k server-side).
+    # One-shot historical replay (capped 10k server-side).
     def replay(topic, from_sequence:, filter: nil, until_sequence: nil, limit: nil)
       slug = Studio.require_project_slug(@config, 'realtime')
       unless from_sequence.is_a?(Integer) && from_sequence >= 0
@@ -42,13 +42,13 @@ module K9o
                             path: UrlGrammar.project_path(slug, 'realtime/replay'), body: body)
     end
 
-    # Poll-transport fallback per §11.3 (SDK-internal SPLIT). Single batch
+    # Poll-transport fallback (SDK-internal SPLIT). Single batch
     # via replay endpoint; caller loops tracking highest observed sequence.
     def subscribe_poll(topic, from_sequence:, filter: nil)
       replay(topic, from_sequence: from_sequence, filter: filter)
     end
 
-    # Typed builders for the 6 closed topic families per ch07 §11.1.
+    # Typed builders for the 6 closed topic families.
     module Topic
       module_function
 

data/lib/k9o/storage.rb

@@ -3,7 +3,7 @@
 require 'cgi'
 
 module K9o
-  # `client.storage` buckets and objects (ch04 §9), against
+  # `client.storage` buckets and objects, against
   # `/@<project_slug>/storage/buckets...`.
   #
   #   k9o.storage.create_bucket('avatars', public: false)

data/lib/k9o/studio.rb

@@ -2,7 +2,7 @@
 
 module K9o
   # Studio namespace (workflows + dashboards).
-  # Ruby idiom per ch13 §2.1.8: snake_case + raise K9o::KError + Envelope return.
+  # Ruby idiom: snake_case + raise K9o::KError + Envelope return.
   #
   #   k9o.studio.workflows.list(status: 'active')
   #   k9o.studio.dashboards.pin('dsh_x')
@@ -25,7 +25,7 @@ module K9o
       slug
     end
 
-    # k9o.studio.workflows.* per ch07 §9.
+    # k9o.studio.workflows.*.
     class Workflows
       attr_reader :runs
 
@@ -69,7 +69,7 @@ module K9o
                               path: UrlGrammar.project_path(slug, "workflows/#{encode(workflow_id)}"))
       end
 
-      # Manual-trigger a run (trigger_type=manual only) per ch07 §9.6.
+      # Manual-trigger a run (trigger_type=manual only).
       def trigger(workflow_id, trigger_context = {})
         slug = Studio.require_project_slug(@config, 'studio.workflows')
         HttpTransport.request(config: @config, method: 'POST',
@@ -83,7 +83,7 @@ module K9o
         ::URI.encode_www_form_component(s)
       end
 
-      # k9o.studio.workflows.runs.* per ch07 §9.6.
+      # k9o.studio.workflows.runs.*.
       class Runs
         def initialize(config)
           @config = config
@@ -116,7 +116,7 @@ module K9o
       end
     end
 
-    # k9o.studio.dashboards.* per ch04 §3.10.
+    # k9o.studio.dashboards.*.
     class Dashboards
       def initialize(config)
         @config = config

data/lib/k9o/url_grammar.rb

@@ -3,7 +3,7 @@
 require 'uri'
 
 module K9o
-  # URL grammar v2.5.68 helpers.
+  # URL grammar helpers.
   module UrlGrammar
     SLUG_RE = /\A[a-z][a-z0-9-]{1,62}\z/
 
@@ -69,7 +69,7 @@ module K9o
     # OPTIONAL — it defaults to the platform apex https://api.k9o.io. When the
     # (validated) host is a bare apex in ORG_DERIVABLE_APEXES and org_slug is
     # supplied, the SDK composes the canonical org-subdomain wire root
-    # https://<org_slug>.<apex> (ch01 §5.4). An explicit <org_slug> subdomain,
+    # https://<org_slug>.<apex>. An explicit <org_slug> subdomain,
     # a self-hosted / Sovereign host, or a dev host (anything not in that
     # set) passes through unchanged — org_slug is intentionally NOT composed
     # onto a non-apex host.

data/lib/k9o/vault.rb

@@ -4,7 +4,7 @@ require 'base64'
 require 'uri'
 
 module K9o
-  # `k9o.kibo.vault.secrets.*` — the §14 typed secrets surface
+  # `k9o.kibo.vault.secrets.*` — the typed secrets surface
   # (`services/gateway/src/routes/vault-secrets.ts`). Full family: list / get /
   # create / reveal_challenge / reveal / update / rotate / move / delete.
   #
@@ -206,8 +206,8 @@ module K9o
   end
 
   # `k9o.kibo.vault.*` — the Kibo vault surface (member-plane, project-scoped).
-  # Currently just `secrets` (ch08 §14); a `zk_deks` accessor
-  # (ch08 §11.3.2 F.5, `POST vault/zk-deks` / `GET vault/zk-deks/<id>`) would
+  # Currently just `secrets`; a `zk_deks` accessor
+  # (F.5, `POST vault/zk-deks` / `GET vault/zk-deks/<id>`) would
   # nest here alongside it if/when that surface is built for Ruby — out of
   # scope for this wrapper, which only covers the vault-secrets audit gap.
   class KiboVault
@@ -220,7 +220,7 @@ module K9o
 
   # `k9o.kibo.*` — per-client namespace root for the Kibo vault REST surface.
   # Distinct from the module-level `K9o::Kibo` (native ZK `encrypt`/`decrypt`
-  # FFI bindings, ch08 §11.3.1/§11.3.3.6, called directly as
+  # FFI bindings, /, called directly as
   # `K9o::Kibo.encrypt`/`.decrypt` since that surface needs no per-client HTTP
   # config): this class exists so `client.kibo.vault.secrets.*` is reachable
   # per client instance, mirroring the TS reference's

data/lib/k9o/version.rb

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

data/lib/k9o.rb

@@ -46,7 +46,7 @@ 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'
-# kibo vault REST surface (client.kibo.vault.secrets) — ch08 §14.
+# kibo vault REST surface (client.kibo.vault.secrets) —.
 require_relative 'k9o/vault'
 # Barbican guardrail SDK — self-guards its native binding (LoadError-safe), so
 # requiring k9o never breaks on a platform without the barbican native lib.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: k9o
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Kilimanjaro
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest