portage-cli 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4a32f5894d104c340e147d698772d21492c3172d6b8e102c4508e431d210a9e
-  data.tar.gz: dbf75ae4f0c5bd7996095d40c0a7e019d4cf9e0376b529356e227d5879363a4a
+  metadata.gz: 8a7b8a3138a4fdb27a32fdd32637d783ded5536e8933ad27a42ba688e550d51e
+  data.tar.gz: 7e55c31d7d3ca91b7647152bff300c191b4593ca7e4956baf11488384ba7dd75
 SHA512:
-  metadata.gz: e41a7814ccdf875fae65a3ec9001c678e6cd0f951c504a0f675d3a34c3126349486df39919e514056b2529305d6560745ca4e028269c69b58e60d6610465f3fc
-  data.tar.gz: 75503266fb054b39739bcd2786083454e0afdefae6e64aaa2573ebc6b4633fd4c3956b16c61707cdbb3bc688a56e31734c4b04293678473b8ffc776a80ceb4d5
+  metadata.gz: 6f081ed17df4df877b15a25d3f0892c1f9fc891ce5fa82a5782acbe5a9deec9636b0b4a9b4c98f0ceea631e9711af9bb321ed1d2e65b34733f114cff35c3a5b1
+  data.tar.gz: 120db3f4d0cbf97ce2a24e877ac3ce017ba9db39bb53bcf944249cf3e507c04a49193267253b41940d5688cd4aa55c3c420f2e1ccbc6e15541bde045585013ff

data/CHANGELOG.md

@@ -4,7 +4,18 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
-## [0.1.0] - Unreleased
+## [0.2.0] - 2026-08-21
+
+- `PORTAGE_SHIP_*` env vars (`Portage::Cli::ShippingProfile`) — configure a
+  default shipping address for `portage buy`'s own-store adapter-loopback
+  path, the same way adapter credentials already live in env. `portage buy`
+  auto-picks the cheapest priced option per fulfillment group once an address
+  is submitted; there's no interactive rate picker, since the CLI drives one
+  automated purchase rather than a conversation. The native UCP session path
+  (a third-party store over stdio/HTTP) isn't wired yet — no real UCP server
+  to verify a `fulfillment` wire shape against.
+
+## [0.1.0] - 2026-08-14
 
 - Initial pre-release. `portage buy <url>` — native UCP discovery first,
   adapter fallback only when this process already has that platform's own

data/README.md

@@ -82,6 +82,31 @@ Exits `0` when a checkout completed (or a dry-run/browse/search resolved
 successfully), `1` otherwise — including the "no native manifest, no adapter
 credentials" dead-end case, so it's scriptable in CI.
 
+### Shipping address (own-store checkouts only)
+
+When buying against your own store (`portage buy`'s step 2 adapter-credentials
+fallback, described at the top of this file) and that adapter supports
+`dev.ucp.shopping.fulfillment`, set a default shipping address via env
+rather than a flag, same posture as adapter credentials:
+
+```bash
+export PORTAGE_SHIP_STREET="1 Main St"
+export PORTAGE_SHIP_CITY="Erie"
+export PORTAGE_SHIP_REGION="PA"          # optional
+export PORTAGE_SHIP_COUNTRY="US"
+export PORTAGE_SHIP_POSTAL_CODE="16501"
+export PORTAGE_SHIP_FIRST_NAME="Ada"     # optional
+export PORTAGE_SHIP_LAST_NAME="Lovelace" # optional
+export PORTAGE_SHIP_PHONE="+1..."        # optional
+```
+
+`street`/`city`/`country`/`postal_code` are required — a partial profile is
+treated as no profile at all. Once the merchant prices shipping options
+against that address, `portage buy` auto-picks the cheapest per fulfillment
+group; there's no interactive rate picker, since this drives one automated
+purchase. Native (non-adapter) UCP stores don't get this yet — see
+`portage-ucp`'s design log for why.
+
 ## Buying without a URL
 
 `portage find` and URL-less `portage buy` share one pipeline:

data/lib/portage/cli/buy.rb

@@ -113,7 +113,7 @@ module Portage
 
         adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
         if adapter_supports_checkout?(adapter)
-          full_buy(client_for(adapter), source: "adapter:#{platform.name}")
+          full_buy(client_for(adapter), source: "adapter:#{platform.name}", fulfillment_adapter: adapter)
         else
           catalog_only_adapter(adapter, platform)
         end
@@ -152,7 +152,13 @@ module Portage
 
       # --- The actual buy, shared by native and adapter-loopback sources ---
 
-      def full_buy(session, source:)
+      # `fulfillment_adapter:` is only ever set by #adapter_flow (the
+      # own-store loopback path) — #native_flow has no raw Adapter object to
+      # inspect for `fulfillment_supported?`, just a Session talking to a
+      # remote store, so shipping-address/rate selection stays loopback-only
+      # for now rather than guessing at a wire shape no real UCP server has
+      # confirmed (see docs/design-log.md).
+      def full_buy(session, source:, fulfillment_adapter: nil)
         products = safe_search(session)
         product = select_product(products)
         unless product
@@ -160,10 +166,68 @@ module Portage
                               message: no_match_message)
         end
 
-        checkout = session.create_checkout(line_items: [{ product_id: product_id_of(product), quantity: @qty }])
+        checkout = session.create_checkout(line_items: [{ product_id: product_id_of(product), quantity: @qty }],
+                                           fulfillment: requested_fulfillment(fulfillment_adapter))
+        checkout = select_cheapest_shipping(session, checkout) if fulfillment_adapter
         finish_checkout(session, source, products, checkout)
       end
 
+      # Submits PORTAGE_SHIP_* (see Portage::Cli::ShippingProfile) as the
+      # checkout's shipping destination, but only when the adapter actually
+      # advertises dev.ucp.shopping.fulfillment — an adapter that doesn't
+      # override #fulfillment_supported? would just ignore the param anyway
+      # (Adapter#create_checkout's default), but there's no point building it
+      # at all in that case.
+      def requested_fulfillment(adapter)
+        return nil unless adapter && Portage::Ucp::Capabilities::FULFILLMENT.advertised_for?(adapter)
+
+        address = Portage::Cli::ShippingProfile.from_env
+        return nil unless address
+
+        Portage::Ucp::CheckoutFulfillment.new(
+          shipping_methods: [Portage::Ucp::FulfillmentMethod.new(
+            id: "requested", type: "shipping", line_item_ids: [],
+            destinations: [Portage::Ucp::ShippingDestination.new(id: "current", address: address)]
+          )]
+        )
+      end
+
+      # Once the merchant has priced options against the submitted address,
+      # auto-picks the cheapest unselected option per fulfillment group and
+      # submits it via #update_checkout — no interactive rate picker; a CLI
+      # driving a single automated purchase needs a deterministic default,
+      # not a prompt. A checkout with no fulfillment groups at all (no
+      # address was submitted, or the merchant hasn't priced anything yet)
+      # passes through unchanged.
+      def select_cheapest_shipping(session, checkout)
+        groups = checkout.dig("fulfillment", "methods", 0, "groups") || []
+        selections = groups.filter_map { |g| cheapest_option_selection(g) }
+        return checkout if selections.empty?
+
+        session.update_checkout(
+          checkout_id: checkout["id"], line_items: current_line_items(checkout),
+          fulfillment: Portage::Ucp::CheckoutFulfillment.new(
+            shipping_methods: [Portage::Ucp::FulfillmentMethod.new(id: "requested", type: "shipping",
+                                                                   line_item_ids: [], groups: selections)]
+          )
+        )
+      end
+
+      def cheapest_option_selection(group)
+        return nil if group["selected_option_id"] || (group["options"] || []).empty?
+
+        cheapest = group["options"].min_by { |o| o.dig("totals", 0, "amount") || 0 }
+        Portage::Ucp::FulfillmentGroup.new(id: group["id"], line_item_ids: group["line_item_ids"],
+                                           selected_option_id: cheapest["id"])
+      end
+
+      # Checkout's line_items are response-shaped ({item: {id, ...}, ...});
+      # #update_checkout takes request-shaped hashes, same asymmetry
+      # #product_id_of already handles for search results.
+      def current_line_items(checkout)
+        checkout["line_items"].map { |li| { product_id: li.dig("item", "id"), quantity: li["quantity"] } }
+      end
+
       def no_match_message
         return "No product matched \"#{@query}\"." unless @product_id
 

data/lib/portage/cli/shipping_profile.rb

@@ -0,0 +1,32 @@
+require "portage/ucp"
+
+module Portage
+  module Cli
+    # Reads a shopper's default shipping address from the process environment
+    # — the same "your own credentials live in env, not on the command line"
+    # posture Resolver.env_for already uses for adapter credentials, applied
+    # here to a buyer-profile concern instead of a platform-credential one
+    # (so it lives in portage-cli, not Portage::Ucp::Resolver).
+    module ShippingProfile
+      ENV_VARS = {
+        street_address: "PORTAGE_SHIP_STREET", extended_address: "PORTAGE_SHIP_EXTENDED",
+        address_locality: "PORTAGE_SHIP_CITY", address_region: "PORTAGE_SHIP_REGION",
+        address_country: "PORTAGE_SHIP_COUNTRY", postal_code: "PORTAGE_SHIP_POSTAL_CODE",
+        first_name: "PORTAGE_SHIP_FIRST_NAME", last_name: "PORTAGE_SHIP_LAST_NAME",
+        phone_number: "PORTAGE_SHIP_PHONE"
+      }.freeze
+
+      REQUIRED = %i[street_address address_locality address_country postal_code].freeze
+
+      # @return [Portage::Ucp::PostalAddress, nil] nil unless every required
+      #   field is set — a partial profile isn't enough to submit, and this
+      #   module never guesses at a missing field.
+      def self.from_env
+        attrs = ENV_VARS.filter_map { |key, var| [key, ENV.fetch(var, nil)] if ENV.key?(var) }.to_h
+        return nil unless REQUIRED.all? { |key| attrs.key?(key) }
+
+        Portage::Ucp::PostalAddress.new(**attrs)
+      end
+    end
+  end
+end

data/lib/portage/cli/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Cli
-    VERSION = "0.1.0".freeze
+    VERSION = "0.2.0".freeze
   end
 end

data/lib/portage/cli.rb

@@ -2,6 +2,7 @@ require "optparse"
 require "json"
 
 require_relative "cli/version"
+require_relative "cli/shipping_profile"
 require_relative "cli/buy"
 require_relative "cli/find"
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tom Whitbread
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: portage-ucp
@@ -16,28 +15,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -104,7 +103,6 @@ description: 'Ships the `portage` executable. `portage buy <url>` tries native U
   ones answering /.well-known/ucp, and search their catalogs — documented APIs only,
   no SERP scraping. Depends on portage-ucp (for platform detection via Resolver) and
   portage-ucp-client (for the actual buy calls); no single adapter gem is a hard dependency.'
-email:
 executables:
 - portage
 extensions: []
@@ -119,6 +117,7 @@ files:
 - lib/portage/cli/find.rb
 - lib/portage/cli/probe_cache.rb
 - lib/portage/cli/search_backends.rb
+- lib/portage/cli/shipping_profile.rb
 - lib/portage/cli/version.rb
 homepage: https://github.com/tomtom87/Portage/tree/main/portage-cli
 licenses:
@@ -127,7 +126,6 @@ metadata:
   source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-cli
   changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-cli/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -142,8 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.18
 specification_version: 4
 summary: portage — one CLI command to buy from any store, native UCP or not
 test_files: []