immersivecommons 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 64529458b7a3d2d3702de67e334dfa5bc67ad9a1d18dff908c529414caa32ebf
+  data.tar.gz: 699bba540214da82cd7aedc674e90afae0f2798b5c6ed68d5ee7d0356f8e1f85
+SHA512:
+  metadata.gz: 15feca82dd9b11b815209fe3e784ea7563538fda457c3a9eac5a20dec79d35c141a31735c50d2b0d4588565cabf67b7158c61379ede3dd109fd386a007627e8c
+  data.tar.gz: 22b1954531b9781c575da9f38196189443e13ff912cfeb2a5b2bd32406a18bf0af441f52361a6059f63093076ee67da4503ef4c16e487939031e5eb56d0892df

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Immersive Commons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,67 @@
+# immersivecommons (Ruby) — Immersive Commons client
+
+Thin, spec-derived Ruby client for the [Immersive Commons](https://www.immersivecommons.com) Agent REST API. Immersive Commons is Floor 10 of Frontier Tower, a members-run AI builder space in San Francisco — this gem gives Ruby agents and services typed access to events & RSVPs, the members directory, resource booking, research Q&A, the donor wall, and RFC 8628 device-code token minting.
+
+- **Homepage:** <https://www.immersivecommons.com>
+- **Developer docs:** <https://www.immersivecommons.com/developers>
+- **OpenAPI spec:** <https://www.immersivecommons.com/openapi.json> (vendored here as `lib/immersivecommons/openapi.json`)
+- **Siblings:** [`@immersivecommons/sdk`](https://www.npmjs.com/package/@immersivecommons/sdk) (npm), [`immersivecommons`](https://pypi.org/project/immersivecommons/) (PyPI), [`ic-go`](https://pkg.go.dev/github.com/immersive-commons/ic-go) (Go)
+
+## Install
+
+```sh
+gem install immersivecommons
+```
+
+Zero runtime dependencies — stdlib `net/http` only. Ruby >= 3.0.
+
+## Use
+
+```ruby
+require "immersivecommons"
+
+# Public reads need no token.
+ic = ImmersiveCommons::Client.new
+events = ic.list_upcoming_events(limit: 5)
+puts events["count"]
+
+# Authenticated calls take an agent bearer token (agt_...).
+authed = ImmersiveCommons::Client.new(token: "agt_your_token")
+puts authed.setup_check
+
+# Writes that the spec marks idempotent accept an Idempotency-Key.
+receipt = authed.rsvp_to_event("https://luma.com/your-event",
+                               email: "you@example.com",
+                               name: "Your Name",
+                               idempotency_key: "rsvp-key-1")
+```
+
+### Minting a token (device-code grant)
+
+```ruby
+res = ic.authorize(["events:rsvp"], client_name: "my-agent",
+                   on_prompt: ->(start) {
+                     puts "Visit #{start['verify_url']} and enter code #{start['user_code']}"
+                   })
+ic.token = res["token"]
+```
+
+A human approves the grant in the browser; the loop polls until `completed`. Pass `sandbox: true` to `Client.new` (or `authorize`) to mint a sandbox token whose writes return simulated receipts.
+
+## How it derives from the spec
+
+`lib/immersivecommons/generated.rb` is emitted from the vendored `openapi.json` by `scripts/generate.py`: an operations table (operationId → method, path, query params, scopes, auth, idempotency, sandbox behavior). The transport is table-driven — one generic `call(operation_id, ...)` builds the URL, attaches the bearer token, and adds an `Idempotency-Key` only on operations the spec marks idempotent. The named methods are facades over that one call, so they cannot drift from the spec. Errors raise `ImmersiveCommons::ApiError` with `status`, `error_kind`, and `retry_after_seconds`.
+
+23 operations are in the table; the 4 Clerk-cookie-only operations (`tailAgentEvents`, `getMyTier`, `requestTier`, `cancelTierRequest`) have no facade methods — agents use the equivalent MCP tools instead. `batchPublicReads` is reachable via the generic `call`.
+
+## Test
+
+```sh
+ruby -Ilib test/test_client.rb
+```
+
+Mock transport, no network, no live writes.
+
+## Source of truth
+
+This gem is generated from and mirrored out of the [immersivecommons.com](https://www.immersivecommons.com) site repo; skills and sibling SDKs live in [immersive-commons/ic-skills](https://github.com/immersive-commons/ic-skills). MIT license.

data/lib/immersivecommons/client.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+# Thin, table-driven client for the Immersive Commons Agent REST API.
+#
+# `call` is the whole transport: it looks the operation up in the generated
+# OPERATIONS table, attaches auth + Idempotency-Key when the spec allows, and
+# sends the request. The named methods are typed facades over `call` — they
+# add no routing of their own, so they cannot drift from the spec. Zero
+# dependencies (stdlib net/http only).
+
+require "json"
+require "net/http"
+require "timeout"
+require "uri"
+
+module ImmersiveCommons
+  # Raised on a non-2xx response. Carries the parsed error body + metadata.
+  class ApiError < StandardError
+    attr_reader :status, :operation_id, :body, :error_kind, :retry_after_seconds
+
+    def initialize(status, operation_id, body)
+      @status = status
+      @operation_id = operation_id
+      @body = body.is_a?(Hash) ? body : {}
+      @error_kind = @body["error_kind"].is_a?(String) ? @body["error_kind"] : nil
+      ra = @body["retry_after_seconds"]
+      @retry_after_seconds = ra.is_a?(Integer) ? ra : nil
+
+      err = @body["error"]
+      msg = if err.is_a?(String)
+              err
+            elsif err.is_a?(Hash)
+              [err["code"], err["message"]].compact.join(": ")
+            end
+      msg = @body["message"] if (msg.nil? || msg.empty?) && @body["message"].is_a?(String)
+      text = "#{operation_id} failed (HTTP #{status})"
+      text += ": #{msg}" if msg && !msg.empty?
+      super(text)
+    end
+  end
+
+  class Client
+    attr_reader :base_url, :sandbox, :user_agent
+    attr_accessor :token
+
+    # transport: an object responding to call(method, url, headers, body) ->
+    # [status, headers, body_text]. Injectable for tests; defaults to Net::HTTP.
+    def initialize(token: nil, base_url: DEFAULT_BASE_URL, sandbox: false,
+                   timeout: 30, transport: nil, user_agent: nil)
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @token = token
+      # Documentation flag only: a sandbox token already behaves sandbox
+      # server-side. This just makes authorize request one by default.
+      @sandbox = sandbox
+      @user_agent = user_agent || "immersivecommons-ruby/#{API_VERSION}"
+      @transport = transport || default_transport(timeout)
+    end
+
+    # ---------------------------------------------------------------- generic
+
+    def call(operation_id, query: nil, body: nil, idempotency_key: nil, token: nil)
+      spec = OPERATIONS[operation_id]
+      raise ArgumentError, "Unknown operationId: #{operation_id}" unless spec
+
+      headers = { "accept" => "application/json", "user-agent" => @user_agent }
+      tok = token || @token
+      headers["authorization"] = "Bearer #{tok}" if tok
+
+      data = nil
+      if spec[:has_body] && !body.nil?
+        headers["content-type"] = "application/json"
+        data = JSON.generate(body)
+      end
+
+      if idempotency_key
+        unless spec[:idempotent]
+          raise ArgumentError, "#{operation_id} does not accept an Idempotency-Key"
+        end
+        headers["idempotency-key"] = idempotency_key
+      end
+
+      url = @base_url + spec[:path] + query_string(query)
+      status, _resp_headers, text = @transport.call(spec[:method], url, headers, data)
+      parsed = begin
+        text && !text.empty? ? JSON.parse(text) : nil
+      rescue JSON::ParserError
+        nil
+      end
+      unless (200..299).cover?(status)
+        raise ApiError.new(status, operation_id, parsed || { "error" => text })
+      end
+      parsed
+    end
+
+    # ------------------------------------------------------------------ reads
+
+    def list_upcoming_events(limit: nil)
+      call("listUpcomingEvents", query: limit.nil? ? nil : { "limit" => limit })
+    end
+
+    def get_event_by_luma_url(luma)
+      call("getEventByLumaUrl", query: { "luma" => luma })
+    end
+
+    def search_directory(q: nil, limit: nil)
+      call("searchDirectory", query: { "q" => q, "limit" => limit })
+    end
+
+    def list_resources
+      call("listResources")
+    end
+
+    def get_my_activity(limit: nil)
+      call("getMyActivity", query: limit.nil? ? nil : { "limit" => limit })
+    end
+
+    def get_my_leaderboard_status
+      call("getMyLeaderboardStatus")
+    end
+
+    def get_donor_wall(limit: nil)
+      call("getDonorWall", query: limit.nil? ? nil : { "limit" => limit })
+    end
+
+    def setup_check
+      call("setupCheck")
+    end
+
+    # ----------------------------------------------------------------- writes
+
+    def rsvp_to_event(event_url, email:, name: nil, idempotency_key: nil)
+      body = { "event_url" => event_url, "email" => email }
+      body["name"] = name unless name.nil?
+      call("rsvpToEvent", body: body, idempotency_key: idempotency_key)
+    end
+
+    def request_event(event, idempotency_key: nil)
+      call("requestEvent", body: event, idempotency_key: idempotency_key)
+    end
+
+    def book_resource(resource_id, start_iso:, end_iso:, email:, purpose: nil, idempotency_key: nil)
+      body = { "resource_id" => resource_id, "start_iso" => start_iso,
+               "end_iso" => end_iso, "email" => email }
+      body["purpose"] = purpose unless purpose.nil?
+      call("bookResource", body: body, idempotency_key: idempotency_key)
+    end
+
+    def set_leaderboard_optin(opt_in)
+      call("setLeaderboardOptIn", body: { "optIn" => opt_in })
+    end
+
+    def ask_research(q, k: nil, sources: nil, synthesize: nil, model: nil)
+      body = { "q" => q }
+      body["k"] = k unless k.nil?
+      body["sources"] = sources.to_a unless sources.nil?
+      body["synthesize"] = synthesize unless synthesize.nil?
+      body["model"] = model unless model.nil?
+      call("askResearch", body: body)
+    end
+
+    def submit_highlight_pending(story, idempotency_key: nil)
+      call("submitHighlightPending", body: story, idempotency_key: idempotency_key)
+    end
+
+    def submit_feedback(kind, message, **extra)
+      body = { "kind" => kind, "message" => message }
+      extra.each { |k, v| body[k.to_s] = v }
+      call("submitFeedback", body: body)
+    end
+
+    def revoke_own_token
+      call("revokeOwnToken")
+    end
+
+    # --------------------------------------------------------- device-code auth
+
+    def start_signup(scopes, client_name: nil, sandbox: nil)
+      body = { "scopes" => scopes.to_a }
+      body["client_name"] = client_name unless client_name.nil?
+      want = sandbox.nil? ? @sandbox : sandbox
+      body["sandbox"] = true if want
+      call("startSignup", body: body)
+    end
+
+    def poll_signup(device_code)
+      call("pollSignup", query: { "device_code" => device_code })
+    end
+
+    # Runs the full RFC 8628 device-code grant and returns the minted token as
+    # { "token", "granted_scopes", "tier", "sandbox" }. Does not store the
+    # token on the client — assign client.token yourself if you want to.
+    # on_prompt receives the start response (user_code, verify_url).
+    # sleeper is injectable for tests.
+    def authorize(scopes, client_name: "immersivecommons-ruby", sandbox: nil,
+                  on_prompt: nil, timeout_seconds: nil, sleeper: ->(s) { sleep(s) })
+      start = start_signup(scopes, client_name: client_name, sandbox: sandbox)
+      on_prompt&.call(start)
+      interval = [start["interval"].to_i, 1].max
+      deadline = monotonic_now + (timeout_seconds || start["expires_in"] || 900)
+      loop do
+        raise Timeout::Error, "Device-code grant timed out before approval." if monotonic_now > deadline
+
+        sleeper.call(interval)
+        poll = poll_signup(start.fetch("device_code"))
+        case poll["status"]
+        when "completed"
+          unless poll["agent_token"]
+            raise ApiError.new(500, "pollSignup", { "error" => "completed without token" })
+          end
+          return {
+            "token" => poll["agent_token"],
+            "granted_scopes" => poll["granted_scopes"] || [],
+            "tier" => poll["tier"],
+            "sandbox" => !!poll["sandbox"]
+          }
+        when "cancelled"
+          raise "Device-code grant cancelled: #{poll['reason']}".strip
+        end
+        # pending -> keep polling
+      end
+    end
+
+    private
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def query_string(query)
+      return "" if query.nil?
+
+      pairs = query.reject { |_k, v| v.nil? }
+      return "" if pairs.empty?
+
+      "?" + URI.encode_www_form(pairs)
+    end
+
+    def default_transport(timeout)
+      lambda do |method, url, headers, body|
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        req = Net::HTTP.const_get(method.capitalize).new(uri, headers)
+        req.body = body if body
+        resp = http.request(req)
+        [resp.code.to_i, resp.each_header.to_h, resp.body || ""]
+      end
+    end
+  end
+end

data/lib/immersivecommons/generated.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+# AUTO-GENERATED from openapi.json by scripts/generate.py — DO NOT EDIT.
+# Spec version: 2026-07-16. Regenerate with: python scripts/generate.py
+
+module ImmersiveCommons
+  API_VERSION = "2026-07-16"
+  DEFAULT_BASE_URL = "https://www.immersivecommons.com"
+
+  # operationId => operation spec (method, path, query, scopes, auth,
+  # idempotency, sandbox). The client transport is table-driven off this
+  # hash, so no method can describe a route the spec does not.
+  OPERATIONS = {
+    "listUpcomingEvents" => {
+      method: "GET",
+      path: "/api/events/upcoming",
+      query: [{ name: "limit", required: false }],
+      scopes: ["events:read_upcoming"],
+      requires_auth: false,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "getEventByLumaUrl" => {
+      method: "GET",
+      path: "/api/events/get",
+      query: [{ name: "luma", required: true }],
+      scopes: [],
+      requires_auth: false,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "batchPublicReads" => {
+      method: "POST",
+      path: "/api/batch",
+      query: [],
+      scopes: [],
+      requires_auth: false,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: true,
+      sandbox: "real"
+    }.freeze,
+    "tailAgentEvents" => {
+      method: "GET",
+      path: "/api/events/next",
+      query: [{ name: "since", required: false }, { name: "types", required: false }, { name: "limit", required: false }],
+      scopes: [],
+      requires_auth: true,
+      bearer_reachable: false,
+      browser_session: true,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "rsvpToEvent" => {
+      method: "POST",
+      path: "/api/events/rsvp",
+      query: [],
+      scopes: ["events:rsvp"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: true,
+      has_body: true,
+      sandbox: "simulated"
+    }.freeze,
+    "requestEvent" => {
+      method: "POST",
+      path: "/api/events/request",
+      query: [],
+      scopes: ["events:request"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: true,
+      has_body: true,
+      sandbox: "simulated"
+    }.freeze,
+    "searchDirectory" => {
+      method: "GET",
+      path: "/api/directory/search",
+      query: [{ name: "q", required: false }, { name: "limit", required: false }],
+      scopes: ["directory:search"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "listResources" => {
+      method: "GET",
+      path: "/api/resources/list",
+      query: [],
+      scopes: ["resources:read"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "bookResource" => {
+      method: "POST",
+      path: "/api/resources/book",
+      query: [],
+      scopes: ["resources:book"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: true,
+      has_body: true,
+      sandbox: "simulated"
+    }.freeze,
+    "getMyActivity" => {
+      method: "GET",
+      path: "/api/activity/me",
+      query: [{ name: "limit", required: false }],
+      scopes: ["membership:read"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "getMyLeaderboardStatus" => {
+      method: "GET",
+      path: "/api/leaderboard/me",
+      query: [],
+      scopes: ["leaderboard:manage"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "setLeaderboardOptIn" => {
+      method: "POST",
+      path: "/api/leaderboard/optin",
+      query: [],
+      scopes: ["leaderboard:manage"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: true,
+      sandbox: "simulated"
+    }.freeze,
+    "askResearch" => {
+      method: "POST",
+      path: "/api/research/ask",
+      query: [],
+      scopes: ["research:query"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: true,
+      sandbox: "real"
+    }.freeze,
+    "submitHighlightPending" => {
+      method: "POST",
+      path: "/api/ingest/highlights/pending",
+      query: [],
+      scopes: ["events:submit_recap"],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: true,
+      has_body: true,
+      sandbox: "simulated"
+    }.freeze,
+    "submitFeedback" => {
+      method: "POST",
+      path: "/api/agent/feedback",
+      query: [],
+      scopes: ["feedback:submit"],
+      requires_auth: false,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: true,
+      sandbox: "real"
+    }.freeze,
+    "revokeOwnToken" => {
+      method: "POST",
+      path: "/api/agent/token/revoke",
+      query: [],
+      scopes: [],
+      requires_auth: true,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: "real"
+    }.freeze,
+    "setupCheck" => {
+      method: "GET",
+      path: "/api/agent/setup-check",
+      query: [],
+      scopes: [],
+      requires_auth: false,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "startSignup" => {
+      method: "POST",
+      path: "/api/agent/signup/start",
+      query: [],
+      scopes: [],
+      requires_auth: false,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: true,
+      sandbox: nil
+    }.freeze,
+    "pollSignup" => {
+      method: "GET",
+      path: "/api/agent/signup/poll",
+      query: [{ name: "device_code", required: false }],
+      scopes: [],
+      requires_auth: false,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "getDonorWall" => {
+      method: "GET",
+      path: "/api/floor10/donations",
+      query: [{ name: "limit", required: false }],
+      scopes: [],
+      requires_auth: false,
+      bearer_reachable: true,
+      browser_session: false,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "getMyTier" => {
+      method: "GET",
+      path: "/api/tier/me",
+      query: [],
+      scopes: [],
+      requires_auth: true,
+      bearer_reachable: false,
+      browser_session: true,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+    "requestTier" => {
+      method: "POST",
+      path: "/api/tier/request",
+      query: [],
+      scopes: [],
+      requires_auth: true,
+      bearer_reachable: false,
+      browser_session: true,
+      idempotent: false,
+      has_body: true,
+      sandbox: nil
+    }.freeze,
+    "cancelTierRequest" => {
+      method: "DELETE",
+      path: "/api/tier/request",
+      query: [],
+      scopes: [],
+      requires_auth: true,
+      bearer_reachable: false,
+      browser_session: true,
+      idempotent: false,
+      has_body: false,
+      sandbox: nil
+    }.freeze,
+  }.freeze
+end