youspot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fd49e47802c4f96a2684403bf62fccb965f6e0d9c6dda693a44a73fc6bd905ce
+  data.tar.gz: 9b6ea5d2351ff2837b0637b7038c8e03593380682f4daaddb21a87199d7aef9f
+SHA512:
+  metadata.gz: 4ceb88a88554b4699b23b2b027c7601ea3740cdaa7e788b9de46363bd3bdadf337c0253f0234a445b7871b263fb8a33c7903f4032c113471af2cdc92ae51d378
+  data.tar.gz: 56f4f1938b91dbeef4572448c7ebb853f66ec0c0c9627131e82e40e5806a5cd26bda6f644042e516dff9d7c1304267849d422d129fce997ea02f01e9370c85dc

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First release: ask, docs, markdown, tools, call_tool, the sandbox, member, directory, batch and identity, matching the youspot npm and PyPI packages.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YouSpot, Inc.
+
+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,42 @@
+# youspot
+
+The official Ruby client for [YouSpot](https://youspot.com), the AI-native personal CRM. Standard library only, Ruby 2.7 or newer.
+
+```bash
+gem install youspot
+```
+
+Everything except `call_tool` works with no credential. Every YouSpot tool reads one person's own contacts, companies, notes and files, so a token always belongs to a person: mint one at [youspot.com/user/mcp](https://youspot.com/user/mcp) and set `YOUSPOT_TOKEN`, or follow the OAuth 2.1 flow in [auth.md](https://youspot.com/auth.md).
+
+```ruby
+require "youspot"
+
+client = YouSpot::Client.new
+
+answer = client.ask("how do I connect an MCP client", limit: 3)
+answer["results"].each { |hit| puts "#{hit["name"]}: #{hit["url"]}" }
+
+client.tools                                                          # every tool on the product server
+client.call_sandbox_tool("search_graph_objects", { query: "Meridian" })  # the demo account, no credential
+client.call_tool("get_connections_summary")                           # needs YOUSPOT_TOKEN
+client.batch([{ id: "dir", path: "/api/network/members", query: { q: "consulting" } }])
+```
+
+| Method                                 | What it does                                           | Credential      |
+| -------------------------------------- | ------------------------------------------------------ | --------------- |
+| `index`                                | Every endpoint, and what each one costs in credentials | none            |
+| `ask`                                  | A question about YouSpot, answered from its own pages  | none            |
+| `search_docs`, `read_doc`, `list_docs` | The developer docs over the documentation MCP server   | none            |
+| `read_markdown`                        | Any public page as markdown                            | none            |
+| `tools`                                | The tools on the product MCP server                    | none            |
+| `call_tool`                            | One tool, as the member whose token the client holds   | `YOUSPOT_TOKEN` |
+| `sandbox_tools`, `call_sandbox_tool`   | The read tools over a demo account                     | none            |
+| `member`, `directory`                  | Public profiles and the public directory               | none            |
+| `batch`                                | Up to 20 reads in one round trip                       | none            |
+| `identity`                             | What identity the caller can hold here                 | optional        |
+
+Every failure raises `YouSpot::Error` carrying `status`, the stable `code` and the `url`. `YOUSPOT_BASE_URL` overrides the origin.
+
+The machine descriptions this client follows: [openapi.json](https://youspot.com/openapi.json), [the MCP server card](https://youspot.com/.well-known/mcp/server-card.json), [agents.md](https://youspot.com/agents.md) and [llms.txt](https://youspot.com/llms.txt). Developer docs: <https://youspot.com/docs>.
+
+MIT licensed. Support: support@youspot.com.

data/lib/youspot/client.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module YouSpot
+  class Client
+    DEFAULT_BASE_URL = "https://youspot.com"
+
+    attr_reader :base_url, :token
+
+    def initialize(base_url: nil, token: nil)
+      @base_url = (base_url || ENV["YOUSPOT_BASE_URL"] || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @token = token || ENV["YOUSPOT_TOKEN"]
+    end
+
+    def index
+      get("/v1")
+    end
+
+    def ask(query, limit: 5)
+      get("/ask", query: { query: query, limit: limit })
+    end
+
+    def search_docs(query, limit: 5)
+      rpc("/mcp/docs", "tools/call", { name: "search_docs", arguments: { query: query, limit: limit } })
+    end
+
+    def read_doc(path)
+      rpc("/mcp/docs", "tools/call", { name: "read_doc", arguments: { path: path } })
+    end
+
+    def list_docs
+      rpc("/mcp/docs", "tools/call", { name: "list_docs", arguments: {} })
+    end
+
+    def read_markdown(path)
+      clean = path.start_with?("/") ? path : "/#{path}"
+      target = clean == "/" ? "/index.md" : "#{clean.delete_suffix('.md')}.md"
+      request(:get, target, accept: "text/markdown")
+    end
+
+    def tools
+      rpc("/mcp/v1", "tools/list")
+    end
+
+    def call_tool(name, arguments = {}, token: nil)
+      bearer = token || @token
+      unless bearer
+        raise Error.new(
+          "Calling #{name} needs a token, because every tool reads one person's own CRM. " \
+          "Mint one at #{@base_url}/user/mcp and set YOUSPOT_TOKEN, or read #{@base_url}/auth.md " \
+          "for the OAuth flow.", code: "no_token"
+        )
+      end
+      rpc("/mcp/v1", "tools/call", { name: name, arguments: arguments }, token: bearer)
+    end
+
+    def sandbox_tools
+      rpc("/mcp/sandbox", "tools/list")
+    end
+
+    def call_sandbox_tool(name, arguments = {})
+      rpc("/mcp/sandbox", "tools/call", { name: name, arguments: arguments })
+    end
+
+    def identity(type = "anonymous")
+      request(:post, "/agent/identity", body: { type: type }, token: @token)
+    end
+
+    def member(username)
+      get("/api/human/#{URI.encode_www_form_component(username)}")
+    end
+
+    def directory(limit: 20, page: 1)
+      get("/api/network/members", query: { limit: limit, page: page })
+    end
+
+    def batch(requests)
+      request(:post, "/api/batch", body: { requests: requests }, token: @token)
+    end
+
+    private
+
+    def get(path, query: nil)
+      target = query ? "#{path}?#{URI.encode_www_form(query)}" : path
+      request(:get, target)
+    end
+
+    def rpc(path, method, params = nil, token: nil)
+      body = { jsonrpc: "2.0", id: 1, method: method }
+      body[:params] = params if params
+      answer = request(:post, path, body: body, token: token)
+      if answer.key?("error")
+        error = answer["error"]
+        raise Error.new(error["message"] || "JSON-RPC error", code: error["code"].to_s, url: @base_url + path)
+      end
+      answer["result"]
+    end
+
+    def request(method, path, body: nil, token: nil, accept: "application/json")
+      uri = URI.parse(@base_url + path)
+      klass = method == :post ? Net::HTTP::Post : Net::HTTP::Get
+      req = klass.new(uri)
+      req["Accept"] = accept
+      req["User-Agent"] = "youspot-ruby/#{VERSION}"
+      req["Authorization"] = "Bearer #{token}" if token
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      response = begin
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 60) do |http|
+          http.request(req)
+        end
+      rescue SystemCallError, SocketError, Timeout::Error => e
+        raise Error.new("#{uri} could not be reached: #{e.message}", url: uri.to_s)
+      end
+      status = response.code.to_i
+      text = response.body.to_s
+
+      if accept != "application/json"
+        raise Error.new("#{uri} answered #{status}", status: status, url: uri.to_s) if status >= 400
+
+        return text
+      end
+
+      parsed = text.empty? ? {} : JSON.parse(text)
+      raise api_error(parsed, status, uri.to_s) if status >= 400
+
+      parsed
+    rescue JSON::ParserError
+      raise Error.new("#{uri} answered #{status} with something other than JSON", status: status, url: uri.to_s)
+    end
+
+    def api_error(parsed, status, url)
+      error = parsed["error"]
+      code = error.is_a?(Hash) ? error["code"] : error
+      message = parsed["error_description"] ||
+                (error.is_a?(Hash) ? error["message"] : error) ||
+                "#{url} answered #{status}"
+      Error.new(message, status: status, code: code, url: url)
+    end
+  end
+end

data/lib/youspot/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module YouSpot
+  VERSION = "0.1.0"
+end

data/lib/youspot.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "youspot/version"
+require_relative "youspot/client"
+
+# The official Ruby client for YouSpot, the AI-native personal CRM.
+#
+# Everything except +call_tool+ works with no credential. A token always
+# belongs to a person, because every tool reads one person's own CRM.
+module YouSpot
+  class Error < StandardError
+    attr_reader :status, :code, :url
+
+    def initialize(message, status: nil, code: nil, url: nil)
+      super(message)
+      @status = status
+      @code = code
+      @url = url
+    end
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: youspot
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- YouSpot, Inc.
+bindir: bin
+cert_chain: []
+date: 2026-09-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: Ask questions, read the docs, list and call the MCP tools, try them in
+  the sandbox, and read the public member directory at youspot.com. Standard library
+  only; only calling a tool needs a member's token.
+email:
+- support@youspot.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/youspot.rb
+- lib/youspot/client.rb
+- lib/youspot/version.rb
+homepage: https://youspot.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://youspot.com
+  documentation_uri: https://youspot.com/docs/api
+  source_code_uri: https://github.com/OnStartups/youspot-ruby
+  changelog_uri: https://github.com/OnStartups/youspot-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://youspot.com/support
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Official Ruby client for YouSpot, the AI-native personal CRM
+test_files: []