Add BOPIS location discovery

[woodward4422]

Summary

• add shop locations <shop-id> <variant-id> as the exact-variant BOPIS discovery primitive
• query the established locationSpecificStorefrontProductVariant.possiblePickupLocationsV2 API with available: true
• authenticate through the CLI's existing Shop OAuth flow instead of spoofing a Shop client or browser identity
• return pickup-enabled stores with point-in-time quantity, distance, pickup timing, public address, and pagination
• require an explicit buyer-provided coarse location; never infer proximity from an account, saved address, IP, or default
• hand off an available item with the exact variant's existing catalog-provided checkout link

BOPIS checkout handoff

The CLI does not attempt to select pickup through UCP. Current merchant UCP checkout advertises shipping, not pickup, so the skill now uses this flow:

1. Resolve the exact variant through Shop catalog discovery.
2. Retrieve its catalog-provided checkout_url with shop catalog get-product.
3. Check nearby inventory with shop locations.
4. Show store, address, distance, quantity, and pickup timing.
5. Return the exact checkout link without reconstructing it.

The checkout link adds the exact variant, but it does not preselect pickup or a store. The buyer chooses both during normal merchant checkout. Inventory remains point-in-time and is not reserved. If the catalog does not return checkout_url, the skill returns the catalog-provided product URL instead.

This needs no UCP pickup platform change and does not integrate directly with Storefront Cart API.

Example

shop locations 6230952 61407327715350 \
  --near-country US \
  --near-postal-code 02127 \
  --max-distance 25 \
  --distance-unit miles

The command accepts the merchant broker ID and exact variant ID shown in Shop catalog/discovery output, or their full supported GIDs.

Authentication and location privacy

shop locations requires Shop sign-in. The OAuth bearer establishes API caller identity for rate limiting; it does not provide the pickup search location.

The query always sends the buyer-provided coarse address as mailingAddress and, by default, pickupAddress. Parse country plus city or postal code from the buyer's request. If missing, ask and wait. Never infer location from an account, saved address, IP geolocation, or another default.

Use --near-latitude and --near-longitude only when the buyer explicitly authorizes precise location use. Never persist the buyer's location. Returned location addresses are public merchant data.

Live top-hat

Validated pickup discovery against Clarke Banks Table Lamp from dev-st-us-testmode:

• discovery product: 10698486743062
• merchant broker ID: 6230952
• exact variant: 61407327715350
• buyer-supplied postal code: 02127
• result: Boston Store, available quantity 35, usually ready in 24 hours

The same request was anonymously throttled with HTTP 429. The standard Shop OAuth bearer removed that throttle without user-agent or native-platform spoofing.

The internal test-store product is not indexed in Global Catalog, so it has no catalog-provided checkout link and the CLI does not fabricate one.

Validation

• pnpm typecheck
• pnpm test — 110 tests pass
• pnpm build
• git diff --check
• live authenticated production pickup query succeeded

Co-authored by AI