Merge pull request #18 from Shopify/auth-budget

Add delegated-budget awareness and Shop Pay availability detection

Author: joerj123

.changeset/auth-budget.md

@@ -0,0 +1,9 @@
+---
+"@shopify/shop-cli": minor
+---
+
+Add delegated-budget awareness: a `shop auth budget` command and automatic Shop Pay availability detection at checkout.
+
+- `shop auth budget` reads `GET https://shop.app/pay/agents/payment_tokens` and returns `{ available, limit?, remaining_amount?, currency?, renewal_type?, renews_at?, units: "minor" }` (amounts in minor units), or `{ available: false }` when no budget is set. The raw wallet token is never surfaced or persisted.
+- Sign-in now requests the `pay:wallet_tokens:read` scope (required by the budget endpoint; not unrolled from `personal_agent`). If a token ever lacks it, the budget read degrades to `{ available: false, reason: "missing_payment_scope" }` instead of breaking sign-in.
+- `shop checkout create` / `update` now disambiguate an empty `payment.instruments`: the CLI probes the budget endpoint once and adds a `shop_pay_availability` block with `budget_available` and a `message`. When `budget_available: true` the buyer has budget but this store doesn't accept Shop agent payments yet, so the agent should search for similar alternatives; when `false` the agent should offer to set up a budget. This resolves the confusing "no token returned" checkout state.

.changeset/fix-keytar-esm-interop.md

@@ -0,0 +1,9 @@
+---
+"@shopify/shop-cli": patch
+---
+
+Fix keytar CJS/ESM interop that broke every secret-store write.
+
+Under ESM, `import('keytar')` produced a namespace where some named exports (e.g. `getPassword`) were present but the write methods (`setPassword`, `deletePassword`) were `undefined` — the complete API lives on `.default`. As a result `store.set`/`store.delete` threw `keytar.setPassword is not a function`, breaking `auth login`, `auth poll`, `config set-country`, device-id persistence, and any command that writes to the keychain.
+
+`KeytarSecretStore` now resolves the module via `.default` (falling back to the namespace) and only uses it when the read **and** write methods are functions; otherwise it falls back to the macOS `security` CLI instead of throwing.

README.md

@@ -38,7 +38,7 @@ shop orders search --type recent
 
 - `shop search` — search the catalog by text, similar items (`--like-id`), or image (`--image`).
 - `shop catalog lookup` / `shop catalog get-product` — look up IDs you already hold and fetch full product detail.
-- `shop auth` — sign in (`login`, or the non-blocking `device-code` + `poll`), check `status`, or `logout`.
+- `shop auth` — sign in (`login`, or the non-blocking `device-code` + `poll`), check `status`, read the remaining delegated spending `budget`, or `logout`.
 - `shop checkout` — `create`, `update`, and `complete` a UCP checkout on the merchant domain (`complete` requires `--confirm`).
 - `shop orders search` — search recent orders, tracking, order info, returns, and reorder candidates.
 - `shop config` — persist CLI preferences such as a default country.

skill/SKILL.md

@@ -87,6 +87,7 @@ shop orders search --type reorder --query "coffee"
 shop auth status
 shop auth device-code --device-name "<your name> - <device>"   # e.g. "Max - Mac Mini"
 shop auth poll
+shop auth budget   # remaining delegated spend (minor units); available:false = no budget set
 shop auth logout
 ```
 
@@ -163,7 +164,9 @@ When the item is visual (clothing, shoes, accessories, furniture, decor, art) **
 
 Then take one of two paths:
 
-**A. Default checkout (no saved payment).** If `payment.instruments` is empty, present `continue_url` as a [Finish in Shop](url) link (format it nicely for the channel; don't print the raw URL) AND (IMPORTANT) immediately after sending it, offer a spending budget (below).
+**A. Default checkout (no saved payment).** If `payment.instruments` is empty, read the `shop_pay_availability` block the CLI adds:
+- `budget_available: true` — you have a delegated budget but this store didn't issue a payment instrument, so it doesn't accept Shop agent payments yet. Search for similar alternatives and message the user about relevant options. Do NOT offer a budget.
+- `budget_available: false` — present `continue_url` as a [Finish in Shop](url) link (format nicely; don't print the raw URL) AND (IMPORTANT) immediately after, offer a spending budget (below) — a budget lets you complete purchases on stores that accept Shop agent payments.
 
 **B. Delegated-budget checkout.** If `status` is `ready_for_complete` and `payment.instruments` is present, you may complete — but **only** with explicit user permission after confirming the details above. Feed the `checkout create` response JSON straight into `shop checkout complete --checkout-stdin --confirm`; the CLI re-sends the merchant-issued instrument id as both the instrument `id` and `credential.token`. Use a fresh idempotency key per distinct purchase intent; reuse it only when retrying the same purchase.
 

skill/references/direct-api.md

@@ -142,7 +142,7 @@ Create with line items, or pass a checkout body that already contains a `cart_id
 }
 ```
 
-If response status is `ready_for_complete` and includes a Shop Pay payment token, complete after clear purchase intent. If no payment token is present, present the UCP `continue_url` as a Finish in Shop link.
+If response status is `ready_for_complete` and includes a Shop Pay payment token, complete after clear purchase intent. If no payment token is present, present the UCP `continue_url` as a Finish in Shop link. **If the buyer has a delegated budget (see Payment Budget) but the checkout still returns no payment instruments, the merchant does not accept Shop Pay** — hand off `continue_url` or suggest another store; do not re-prompt the user to set up a budget (they already have one).
 
 The checkout response may include a `messages[]` array. You MUST display every `warning` message's `content` to the user (e.g. `final_sale`, `prop65`, `age_restricted`) before completing. Show `presentation: "disclosure"` warnings verbatim and do not omit or summarize them away. Never complete a purchase without surfacing these messages.
 
@@ -225,6 +225,37 @@ Use `update_checkout` with the checkout ID from create and only the fields that
 }
 ```
 
+## Payment Budget (Delegated Spending)
+
+When the buyer enables purchasing without approval in [Shop → Settings → Connections](https://shop.app/account/settings/connections), Shop issues a budgeted wallet payment token. Read the remaining budget:
+
+```text
+GET https://shop.app/pay/agents/payment_tokens
+Authorization: Bearer <access_token>
+```
+
+Requires the `pay:wallet_tokens:read` scope. Authoritative success shape:
+
+```json
+{
+  "payment_tokens": [
+    {
+      "id": "<wallet token — never log or persist>",
+      "default_currency_code": "USD",
+      "display": { "limit": 10000, "remaining_amount": 5750, "renewal_type": "monthly", "renews_at": "2026-05-01T00:00:00Z" }
+    }
+  ],
+  "has_more": false,
+  "next_cursor": null
+}
+```
+
+**`limit` and `remaining_amount` are minor units (cents)** — `remaining_amount: 5750` is $57.50. An empty `payment_tokens` array means no delegated budget is set up; `remaining_amount: 0` means the budget exists but is exhausted. (Stay tolerant: older shapes put the token at `.token`/`.id` and amounts at the root or `.display`.)
+
+Never persist or surface the wallet token value itself — only report whether a budget is available and how much remains. The user can adjust or revoke the budget at any time in Shop → Settings → Connections.
+
+**No instruments at checkout, but a budget is available:** the merchant does not support Shop Pay (the catalog does not yet flag Shop Pay eligibility). When a checkout returns no `payment.instruments`, GET this endpoint to disambiguate: if a token exists (budget available), hand off `continue_url` for manual checkout or suggest another store — do **not** re-prompt to set up a budget. If no token exists, the buyer simply has no delegated budget (offer the Finish in Shop link / budget setup as usual).
+
 ## Orders
 
 Authenticated order search:

src/cli.ts

@@ -245,6 +245,15 @@ export function createProgram(deps: CliDependencies = {}): Command {
       )
     })
 
+  auth
+    .command('budget')
+    .description('Show the remaining delegated spending budget (minor units). `available: false` means no budget is set.')
+    .action(async () => {
+      await runAction({ stdout, stderr, exit }, async () =>
+        resolveClient(deps, program).budget(),
+      )
+    })
+
   auth
     .command('logout')
     .description('Delete stored Shop tokens and preferences')
@@ -271,13 +280,15 @@ export function createProgram(deps: CliDependencies = {}): Command {
         if (!options.variantId && !checkout) {
           throw new Error('checkout create requires --variant-id or --checkout-stdin')
         }
-        return resolveClient(deps, program).createCheckout({
+        const client = resolveClient(deps, program)
+        const result = await client.createCheckout({
           shopDomain: options.shopDomain,
           variantId: options.variantId,
           quantity: options.quantity,
           checkout,
           buyerIp: options.buyerIp,
         })
+        return annotateShopPayAvailability(client, result)
       })
     })
 
@@ -289,14 +300,16 @@ export function createProgram(deps: CliDependencies = {}): Command {
     .requiredOption('--checkout-stdin', 'Read checkout update JSON from stdin')
     .option('--buyer-ip <ip>', 'Buyer public IP, forwarded to the merchant for checkout fraud/risk checks (auto-detected via api.ipify.org; override here or with SHOP_BUYER_IP)')
     .action(async (options) => {
-      await runCheckoutAction({ stdout, stderr, exit }, async () =>
-        resolveClient(deps, program).updateCheckout({
+      await runCheckoutAction({ stdout, stderr, exit }, async () => {
+        const client = resolveClient(deps, program)
+        const result = await client.updateCheckout({
           shopDomain: options.shopDomain,
           checkoutId: options.checkoutId,
           checkout: await readJsonFromStdin(deps.stdin ?? process.stdin),
           buyerIp: options.buyerIp,
-        }),
-      )
+        })
+        return annotateShopPayAvailability(client, result)
+      })
     })
 
   checkout
@@ -578,10 +591,32 @@ async function readJsonFromStdin(stdin: NodeJS.ReadStream | AsyncIterable<Buffer
   return parsed as Record<string, unknown>
 }
 
-// Pull the payment instruments out of whatever the caller piped in: either the
-// full create_checkout response ({ payment: { instruments: [...] } }) or a bare
-// payment block ({ instruments: [...] }). complete_checkout must echo these back
-// so the merchant can match the instrument id it issued for this checkout.
+async function annotateShopPayAvailability(
+  client: ShopCatalogClient,
+  checkout: unknown,
+): Promise<unknown> {
+  if (!isObject(checkout)) return checkout
+  const payment = isObject(checkout.payment) ? checkout.payment : undefined
+  const instruments = payment && Array.isArray(payment.instruments) ? payment.instruments : []
+  if (instruments.length > 0) return checkout
+
+  const budget = (await client.budget().catch(() => null)) as Record<string, unknown> | null
+  const shop_pay_availability =
+    budget?.available === true
+      ? {
+          budget_available: true,
+          message:
+            "You have budget remaining to pay for the user, but this store doesn't accept Shop agent payments yet. Search for similar alternatives, then message the user about relevant options.",
+        }
+      : {
+          budget_available: false,
+          message:
+            'No spending budget is set. Offer to set up a budget so you can complete purchases on stores that accept Shop agent payments.',
+        }
+
+  return { ...checkout, shop_pay_availability }
+}
+
 function extractInstruments(checkout: Record<string, unknown>): Record<string, unknown>[] {
   const payment = isObject(checkout.payment) ? checkout.payment : checkout
   const instruments = isObject(payment) ? payment.instruments : undefined

src/constants.ts

@@ -13,6 +13,7 @@ export const USER_AGENT = `shop-cli/${CLI_VERSION}`
 export const GLOBAL_CATALOG_AUDIENCE = 'api.shopify.com'
 export const ACCESS_TOKEN_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token'
 export const TOKEN_EXCHANGE_URL = 'https://shop.app/oauth/token'
+export const PAYMENT_TOKENS_URL = 'https://shop.app/pay/agents/payment_tokens'
 export const SHOP_AGENT_SERVICE = 'shop-agent'
 export const ACCESS_TOKEN_ACCOUNT = 'access_token'
 export const REFRESH_TOKEN_ACCOUNT = 'refresh_token'
@@ -21,6 +22,6 @@ export const COUNTRY_ACCOUNT = 'country'
 // Short-lived device-authorization state persisted between `auth device-code`
 // (emits the sign-in URL) and `auth poll` (exchanges + stores tokens).
 export const PENDING_DEVICE_AUTH_ACCOUNT = 'pending_device_auth'
-export const AUTH_SCOPES = 'openid email personal_agent'
+export const AUTH_SCOPES = 'openid email personal_agent pay:wallet_tokens:read'
 export const UCP_PROFILE =
   'https://shopify.dev/ucp/agent-profiles/2026-04-08/personal_agent.json'

src/shop-client.ts

@@ -6,12 +6,20 @@ import {
   ACCESS_TOKEN_TOKEN_TYPE,
   GLOBAL_CATALOG_AUDIENCE,
   GLOBAL_CATALOG_MCP_URL,
+  PAYMENT_TOKENS_URL,
   REFRESH_TOKEN_ACCOUNT,
   TOKEN_EXCHANGE_URL,
   UCP_PROFILE,
 } from './constants.js'
 import { ShopCliError } from './errors.js'
-import { formBody, jsonHeaders, parseJsonResponse, parseTextResponse, withUserAgent } from './http.js'
+import {
+  formBody,
+  jsonHeaders,
+  parseJsonResponse,
+  parseOptionalJsonResponse,
+  parseTextResponse,
+  withUserAgent,
+} from './http.js'
 import { AuthClient } from './auth.js'
 import { getCountry, getOrCreateDeviceId } from './storage.js'
 import type { FetchLike, JsonObject, SecretStore } from './types.js'
@@ -277,6 +285,27 @@ export class ShopCatalogClient {
     return this.status()
   }
 
+  async budget(): Promise<unknown> {
+    const accessToken = await this.auth.getValidAccessToken()
+    if (!accessToken) return { authenticated: false }
+    const deviceId = await getOrCreateDeviceId(this.options.store)
+    const response = await this.authenticatedShopFetch(PAYMENT_TOKENS_URL, {
+      accessToken,
+      deviceId,
+      label: 'Fetch payment budget',
+    })
+    if (response.status === 401 || response.status === 403) {
+      return {
+        available: false,
+        reason: response.status === 403 ? 'missing_payment_scope' : 'unauthenticated',
+        message:
+          'This sign-in cannot read a spending budget (the token lacks payment permission). Ask the user to enable purchasing without approval in Shop → Settings → Connections, then run `shop auth login` again to re-authorize.',
+      }
+    }
+    const json = await parseOptionalJsonResponse<JsonObject>(response, 'Fetch payment budget', {})
+    return summarizeBudget(json)
+  }
+
   private async catalogInput(
     input: CatalogSearchInput | CatalogLookupInput | CatalogGetProductInput,
     opts: { alignCountryToShipsTo?: boolean } = {},
@@ -669,6 +698,63 @@ function normalizeLikeItems(like: unknown[]): unknown[] {
   )
 }
 
+function summarizeBudget(json: unknown): JsonObject {
+  const root = isPlainObject(json) ? json : {}
+  const tokens = Array.isArray(root.payment_tokens) ? root.payment_tokens : []
+  const first = isPlainObject(tokens[0]) ? tokens[0] : {}
+  const display = isPlainObject(first.display)
+    ? first.display
+    : isPlainObject(root.display)
+      ? root.display
+      : {}
+
+  const available = Boolean(pickString(first.id, first.token, root.token, root.id))
+  if (!available) {
+    return {
+      available: false,
+      message:
+        'No delegated spending budget. Ask the user to enable purchasing without approval in Shop → Settings → Connections.',
+    }
+  }
+
+  const limit = pickAmount(display.limit, first.limit, root.limit)
+  const remaining = pickAmount(display.remaining_amount, first.remaining_amount, root.remaining_amount)
+  const currency = pickString(
+    first.default_currency_code,
+    display.currency,
+    root.default_currency_code,
+    root.currency,
+  )
+  const renewalType = pickString(display.renewal_type, first.renewal_type)
+  const renewsAt = pickString(display.renews_at, first.renews_at)
+  return {
+    available: true,
+    ...(limit !== undefined ? { limit } : {}),
+    ...(remaining !== undefined ? { remaining_amount: remaining } : {}),
+    ...(currency ? { currency } : {}),
+    ...(renewalType ? { renewal_type: renewalType } : {}),
+    ...(renewsAt ? { renews_at: renewsAt } : {}),
+    units: 'minor',
+  }
+}
+
+function pickAmount(...candidates: unknown[]): number | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'number' && Number.isFinite(candidate)) return candidate
+    if (typeof candidate === 'string' && candidate.trim() !== '' && Number.isFinite(Number(candidate))) {
+      return Number(candidate)
+    }
+  }
+  return undefined
+}
+
+function pickString(...candidates: unknown[]): string | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim() !== '') return candidate
+  }
+  return undefined
+}
+
 function isCatalogTool(toolName: string): boolean {
   return toolName === 'search_catalog' || toolName === 'lookup_catalog' || toolName === 'get_product'
 }

src/storage.ts

@@ -12,11 +12,22 @@ import { promisify } from 'node:util'
 
 const execFileAsync = promisify(execFile)
 
+type KeytarApi = Pick<typeof import('keytar'), 'getPassword' | 'setPassword' | 'deletePassword'>
+
 export class KeytarSecretStore implements SecretStore {
-  private keytarPromise: Promise<typeof import('keytar') | null>
+  private keytarPromise: Promise<KeytarApi | null>
 
   constructor(private readonly service = SHOP_AGENT_SERVICE) {
-    this.keytarPromise = import('keytar').catch(() => null)
+    this.keytarPromise = import('keytar')
+      .then((mod) => {
+        const candidate = ((mod as { default?: unknown }).default ?? mod) as Partial<KeytarApi>
+        const usable =
+          typeof candidate.getPassword === 'function' &&
+          typeof candidate.setPassword === 'function' &&
+          typeof candidate.deletePassword === 'function'
+        return usable ? (candidate as KeytarApi) : null
+      })
+      .catch(() => null)
   }
 
   async get(account: string): Promise<string | null> {