portage-ucp-client 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a1a9cbc441c1893347b4f899fe968932fb297f626285f37d848d65d2ca91e749
4
- data.tar.gz: 0455b81249ce937ccbc88fb3ee19cf5590e1b0c94a187490ffb35116863bbf72
3
+ metadata.gz: be5ef7d67c34c11b54f60611b6dd6fabd97e2721f62ac41667261e8c41fdf505
4
+ data.tar.gz: 6d4da870ffec123ee561f1423573279caa14b8d4aea94fa50a66fb7cdbf86639
5
5
  SHA512:
6
- metadata.gz: 0ef87e49709386c5f6f05ac388526ef9df1bedf8f7f2d5e6609a26b769d2ba3c9f56d5e4160e03eced891f502a55c795c340ffd17d09b694c8f4fe5d8ee81bb7
7
- data.tar.gz: 712af022a1faea02752ba88b2023e34ec893bf567d6f8d2cc237ccf15981994fb7f85bee20124368369f4984c43699ca011b2d4af194ed308fc128a3dd46d0af
6
+ metadata.gz: b81cb1592180fe79c724c717ef4674b24aa772845c494bf80a580551ca38352e37165bbfc4cf1b2e002ea7a5d7e51d0ed5ce1ee1bb1ed5f003af7382a5b99f1a
7
+ data.tar.gz: 600d1c4f691ddd89ffdef9f923d1c882e72a277c9257469b2878d69ac7328bc6bd63a5c49df4df5f7ff2e7cedcc8540c02b16941e13d49e1bd62510f4f6f2883
data/CHANGELOG.md CHANGED
@@ -6,6 +6,17 @@ pre-1.0, so APIs may still shift between minor versions.
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.8.0] - 2026-11-18
10
+
11
+ - **Added: REST transport.** `Client.discover` now falls back to a store's
12
+ `rest` service entry when it has no `mcp` one (MCP still wins when both are
13
+ offered; the newest `version` wins within a transport), so REST-only stores
14
+ such as issue #178's sandbox can be driven. `Client.connect(url:, transport:
15
+ :rest)` builds a `Transports::Rest` session; `:mcp` stays the default and
16
+ other values raise `ArgumentError`. `Session#transport_name` returns `:mcp`
17
+ or `:rest`. A manifest with neither raises `ManifestShapeError` listing the
18
+ transports it saw.
19
+
9
20
  ## [0.7.0] - 2026-10-22
10
21
 
11
22
  - **Changed: requires `mcp` `~> 1.8`** (was `~> 0.24`), which serves MCP 2026-07-28 through `server/discover` and keeps `initialize` for 2025-11-25 and earlier. Minor bump because the `mcp` requirement moved from 0.x to 1.x; no API change and no changes under `lib/`. `portage-ucp` stays at `~> 0.8`: the client calls nothing newer, and the shared `mcp` `~> 1.8` requirement makes resolution pick `portage-ucp` 0.17.0 or later.
@@ -24,13 +24,17 @@ module Portage
24
24
  # names advertised by the server, when known upfront (Client.discover
25
25
  # populates this from the manifest; Client.for_adapter/.connect leave
26
26
  # it nil since nothing was fetched to populate it from).
27
- def initialize(transport:, capabilities: nil)
27
+ def initialize(transport:, capabilities: nil, transport_name: :mcp)
28
28
  @transport = transport
29
+ @transport_name = transport_name
29
30
  @capabilities = capabilities
30
31
  end
31
32
 
32
33
  attr_reader :capabilities
33
34
 
35
+ # @return [Symbol] `:rest` over the REST transport, `:mcp` otherwise.
36
+ attr_reader :transport_name
37
+
34
38
  # @return [Boolean, nil] nil when capabilities weren't known upfront
35
39
  # (see #capabilities) — callers with a nil result can't tell either
36
40
  # way and should just attempt the call.
@@ -0,0 +1,103 @@
1
+ require "faraday"
2
+ require "json"
3
+ require "erb"
4
+ require_relative "../errors"
5
+ require_relative "ucp_wire_shape"
6
+
7
+ module Portage
8
+ module Ucp
9
+ module Client
10
+ module Transports
11
+ # Connects to a UCP server's REST service (2026-08-25's core
12
+ # transport) — the same Session seam as Http, a different wire. REST
13
+ # bodies are the bare capability object, so this reuses UcpWireShape
14
+ # to build the MCP body and drops the capability wrapper key; ids go
15
+ # in the path; `meta` becomes headers instead of body fields.
16
+ class Rest
17
+ include UcpWireShape
18
+
19
+ # action => [verb, path (`{id}` is the action's identifying
20
+ # argument), wrapper key of the body — nil for no body].
21
+ ROUTES = {
22
+ "search_catalog" => ["POST", "/catalog/search", "catalog"],
23
+ "lookup_catalog" => ["POST", "/catalog/lookup", "catalog"],
24
+ "get_product" => ["POST", "/catalog/product", "catalog"],
25
+ "create_cart" => ["POST", "/carts", "cart"],
26
+ "get_cart" => ["GET", "/carts/{id}", nil],
27
+ "update_cart" => ["PUT", "/carts/{id}", "cart"],
28
+ "cancel_cart" => ["POST", "/carts/{id}/cancel", nil],
29
+ "create_checkout" => ["POST", "/checkout-sessions", "checkout"],
30
+ "get_checkout" => ["GET", "/checkout-sessions/{id}", nil],
31
+ "update_checkout" => ["PUT", "/checkout-sessions/{id}", "checkout"],
32
+ "complete_checkout" => ["POST", "/checkout-sessions/{id}/complete", "checkout"],
33
+ "cancel_checkout" => ["POST", "/checkout-sessions/{id}/cancel", nil],
34
+ "get_order" => ["GET", "/orders/{id}", nil]
35
+ }.freeze
36
+
37
+ # @param url [String] the service entry's `endpoint`; paths are
38
+ # appended to it, keeping any version prefix.
39
+ # @param proxy [String, Hash, URI, nil] as for Http.
40
+ def initialize(url:, headers: {}, proxy: nil)
41
+ @base = url.to_s.chomp("/")
42
+ @connection = Faraday.new(headers: Client.with_user_agent(headers), proxy: proxy)
43
+ end
44
+
45
+ # Returns the response body as a string-keyed Hash, like Http.
46
+ def call_tool(name:, arguments:, meta: nil)
47
+ verb, path, wrapper = ROUTES.fetch(name) do
48
+ raise UnsupportedWireShapeError, "#{name} has no REST operation in UCP 2026-08-25"
49
+ end
50
+ idempotency_key = arguments[:idempotency_key] || arguments["idempotency_key"]
51
+ wire = wire_arguments(name, arguments)
52
+ headers = request_headers(meta, idempotency_key)
53
+ body = wrapper && JSON.generate(wire.fetch(wrapper))
54
+ response = @connection.run_request(verb.downcase.to_sym, url_for(path, wire["id"]), body, headers)
55
+ handle(response, name)
56
+ end
57
+
58
+ private
59
+
60
+ def url_for(path, id)
61
+ @base + path.sub("{id}") { ERB::Util.url_encode(id.to_s) }
62
+ end
63
+
64
+ def request_headers(meta, idempotency_key)
65
+ profile = meta && (meta[:agent_profile] || meta["agent_profile"])
66
+ unless profile
67
+ raise MissingAgentProfileError,
68
+ "meta: { agent_profile: <url> } is required for REST calls — real UCP servers fetch " \
69
+ "and verify this URL to identify the calling agent"
70
+ end
71
+
72
+ headers = { "UCP-Agent" => %(profile="#{profile}"),
73
+ "Content-Type" => "application/json", "Accept" => "application/json" }
74
+ headers["Idempotency-Key"] = idempotency_key if idempotency_key
75
+ headers
76
+ end
77
+
78
+ def handle(response, name)
79
+ payload = parse(response.body)
80
+ return payload if response.success? && payload
81
+
82
+ error = ServerError.new("HTTP #{response.status}: #{detail(payload, response.body)}", payload: payload)
83
+ raise permission_error(error) if name == "complete_checkout" && permission_refusal?(error.message)
84
+
85
+ raise error
86
+ end
87
+
88
+ def detail(payload, body)
89
+ contents = Array(payload && payload["messages"]).filter_map { |m| m["content"] if m.is_a?(Hash) }
90
+ contents.empty? ? body : contents.join("; ")
91
+ end
92
+
93
+ def parse(body)
94
+ parsed = JSON.parse(body.to_s)
95
+ parsed.is_a?(Hash) ? parsed : nil
96
+ rescue JSON::ParserError
97
+ nil
98
+ end
99
+ end
100
+ end
101
+ end
102
+ end
103
+ end
@@ -1,7 +1,7 @@
1
1
  module Portage
2
2
  module Ucp
3
3
  module Client
4
- VERSION = "0.7.0".freeze
4
+ VERSION = "0.8.0".freeze
5
5
  end
6
6
  end
7
7
  end
@@ -12,6 +12,7 @@ require_relative "client/transports/local_arguments"
12
12
  require_relative "client/transports/loopback"
13
13
  require_relative "client/transports/stdio"
14
14
  require_relative "client/transports/http"
15
+ require_relative "client/transports/rest"
15
16
 
16
17
  module Portage
17
18
  module Ucp
@@ -38,24 +39,33 @@ module Portage
38
39
  Session.new(transport: Transports::Loopback.new(adapter: adapter, **server_opts))
39
40
  end
40
41
 
41
- # Connects over stdio (a subprocess) or Streamable HTTP (a URL) — pass
42
- # exactly one of `command:` or `url:`.
42
+ # Connects over stdio (a subprocess), Streamable HTTP (a URL) or REST (a
43
+ # URL with `transport: :rest`) — pass exactly one of `command:` or `url:`.
44
+ # @param transport [Symbol] `:mcp` (default) or `:rest`; only for `url:`.
43
45
  # @param proxy [String, Hash, nil] forwarded to Transports::Http (a
44
46
  # `url:` connection only) — see its own doc comment.
45
- def self.connect(command: nil, args: [], env: nil, url: nil, headers: {}, capabilities: nil, proxy: nil)
46
- transport = if command
47
- Transports::Stdio.new(command: command, args: args, env: env)
48
- elsif url
49
- Transports::Http.new(url: url, headers: headers, proxy: proxy)
50
- else
51
- raise ArgumentError, "connect requires either command: or url:"
52
- end
53
- Session.new(transport: transport, capabilities: capabilities)
47
+ def self.connect(command: nil, args: [], env: nil, url: nil, headers: {}, capabilities: nil, proxy: nil,
48
+ transport: :mcp)
49
+ unless %i[mcp rest].include?(transport)
50
+ raise ArgumentError, "transport must be :mcp or :rest, got #{transport.inspect}"
51
+ end
52
+
53
+ raise ArgumentError, "transport: :rest needs url:, not command:" if command && transport == :rest
54
+
55
+ wire = if command
56
+ Transports::Stdio.new(command: command, args: args, env: env)
57
+ elsif url
58
+ (transport == :rest ? Transports::Rest : Transports::Http).new(url: url, headers: headers,
59
+ proxy: proxy)
60
+ else
61
+ raise ArgumentError, "connect requires either command: or url:"
62
+ end
63
+ Session.new(transport: wire, capabilities: capabilities, transport_name: transport)
54
64
  end
55
65
 
56
66
  # GETs `<url>/.well-known/ucp`, parses the manifest, and connects to the
57
- # `mcp`-transport endpoint it advertises in `services` (see
58
- # Portage::Ucp::Manifest#services — the core-gem fix this client
67
+ # `mcp`-transport endpoint it advertises in `services` (else its `rest`
68
+ # one; see Portage::Ucp::Manifest#services — the core-gem fix this client
59
69
  # depends on to know where to connect).
60
70
  # @return [Session] scoped to the manifest's advertised capabilities.
61
71
  # @param headers [Hash{String => String}] sent with the manifest GET
@@ -65,7 +75,9 @@ module Portage
65
75
  # connection this discovers into — see Transports::Http.
66
76
  def self.discover(url, headers: {}, proxy: nil)
67
77
  manifest = fetch_manifest(url, headers)
68
- connect(url: mcp_endpoint(manifest), headers: headers, capabilities: capability_names(manifest), proxy: proxy)
78
+ transport, endpoint = service_endpoint(manifest)
79
+ connect(url: endpoint, headers: headers, capabilities: capability_names(manifest), proxy: proxy,
80
+ transport: transport)
69
81
  end
70
82
 
71
83
  def self.fetch_manifest(url, headers = {})
@@ -105,17 +117,25 @@ module Portage
105
117
  end
106
118
  private_class_method :ucp_section
107
119
 
108
- def self.mcp_endpoint(manifest)
120
+ # MCP when the store offers it, else REST; the newest `version` wins
121
+ # within a transport.
122
+ # @return [Array(Symbol, String)] `[:mcp | :rest, endpoint]`
123
+ def self.service_endpoint(manifest)
109
124
  services = ucp_section(manifest)["services"]
110
125
  entries = services.is_a?(Hash) ? services.values.flatten : Array(services)
111
- endpoint = entries.select { |s| s["transport"] == "mcp" }
112
- .max_by { |s| s["version"].to_s }
113
- &.fetch("endpoint", nil)
114
- raise ManifestShapeError, "manifest has no mcp service entry to connect to" unless endpoint
126
+ %w[mcp rest].each do |transport|
127
+ endpoint = newest_endpoint(entries, transport)
128
+ return [transport.to_sym, endpoint] if endpoint
129
+ end
130
+ seen = entries.map { |s| s["transport"] }.compact.uniq
131
+ raise ManifestShapeError, "manifest has no mcp or rest service entry to connect to (saw: #{seen.join(', ')})"
132
+ end
133
+ private_class_method :service_endpoint
115
134
 
116
- endpoint
135
+ def self.newest_endpoint(entries, transport)
136
+ entries.select { |s| s["transport"] == transport }.max_by { |s| s["version"].to_s }&.fetch("endpoint", nil)
117
137
  end
118
- private_class_method :mcp_endpoint
138
+ private_class_method :newest_endpoint
119
139
 
120
140
  def self.capability_names(manifest)
121
141
  capabilities = ucp_section(manifest)["capabilities"]
metadata CHANGED
@@ -1,14 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: portage-ucp-client
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.7.0
4
+ version: 0.8.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tom Whitbread
8
- autorequire:
9
8
  bindir: bin
10
9
  cert_chain: []
11
- date: 2026-10-22 00:00:00.000000000 Z
10
+ date: 1980-01-02 00:00:00.000000000 Z
12
11
  dependencies:
13
12
  - !ruby/object:Gem::Dependency
14
13
  name: faraday
@@ -115,7 +114,6 @@ description: 'Every other portage-ucp gem lets a Ruby program expose a commerce
115
114
  Adapter, stdio, Streamable HTTP) — callers never know which they got. Depends only
116
115
  on portage-ucp, the mcp gem''s client half, and faraday (the HTTP transport''s backend);
117
116
  no adapter gem is a dependency.'
118
- email:
119
117
  executables: []
120
118
  extensions: []
121
119
  extra_rdoc_files: []
@@ -131,6 +129,7 @@ files:
131
129
  - lib/portage/ucp/client/transports/http/complete_checkout_wire_shape.rb
132
130
  - lib/portage/ucp/client/transports/local_arguments.rb
133
131
  - lib/portage/ucp/client/transports/loopback.rb
132
+ - lib/portage/ucp/client/transports/rest.rb
134
133
  - lib/portage/ucp/client/transports/stdio.rb
135
134
  - lib/portage/ucp/client/transports/ucp_wire_shape.rb
136
135
  - lib/portage/ucp/client/version.rb
@@ -141,7 +140,6 @@ metadata:
141
140
  source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp-client
142
141
  changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp-client/CHANGELOG.md
143
142
  rubygems_mfa_required: 'true'
144
- post_install_message:
145
143
  rdoc_options: []
146
144
  require_paths:
147
145
  - lib
@@ -156,8 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
156
154
  - !ruby/object:Gem::Version
157
155
  version: '0'
158
156
  requirements: []
159
- rubygems_version: 3.5.22
160
- signing_key:
157
+ rubygems_version: 4.0.20
161
158
  specification_version: 4
162
159
  summary: Client-side SDK for portage-ucp — act as the shopper's agent against any
163
160
  UCP/MCP server