@zknexus/bap 0.1.0 → 0.1.1

package/README.md

@@ -12,9 +12,9 @@ From the repository checkout, enter the package directory and run the following
 npm ci
 npm test
 npm pack
-npx --package=./zknexus-bap-0.1.0.tgz bap --help
+npx --package=./zknexus-bap-0.1.1.tgz bap doctor
 ~~~
 
-Once the package is published, users can run npx @zknexus/bap@0.1.0 doctor.
+The 0.1.1 doctor report separates catalog configuration from unsigned quote availability on Base and Solana. Once this version is published, run `npx @zknexus/bap@0.1.1 doctor`.
 
 The local storage directory defaults to ~/.bap. Set BAP_HOME to use a separate private profile. Wallets are encrypted with the passphrase entered in the terminal. Keep an encrypted backup and protect the receipt database, which contains the original x402 proofs. MCP clients can request quotes and read results. Each purchase requires separate approval in the terminal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zknexus/bap",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Bid Advisor Partners CLI and local MCP bridge for public procurement and x402",
   "type": "module",
   "bin": { "bap": "src/cli.mjs" },

package/skills/procurement-opportunities/SKILL.md

@@ -7,6 +7,8 @@ description: Search public procurement by country, inspect official evidence and
 
 Use this skill when asked to find public tenders or professional-service opportunities in selected countries. Do not infer company authority or submit offers.
 
+For Codex, Claude or ChatGPT users, start with https://docs.bidadvisorpartners.com/agents/connect. Use the conversation language for replies and for the language argument of local BAP MCP calls (en or es when supported). If the local BAP tool or wallet is missing, use https://docs.bidadvisorpartners.com/agents/cli for English or https://docs.bidadvisorpartners.com/es/cli for Spanish. Give the user only the first missing step, with the exact command for their client. If the catalog cannot be reached, start with the connection check. Distinguish a published price from a quote with a purchase ID.
+
 1. Read https://www.bidadvisorpartners.com/developers and https://www.bidadvisorpartners.com/api/agent/v1. Confirm runtime state, supported networks and prices. Discovery is free. Disabled or unavailable is not zero coverage.
 2. Check https://www.bidadvisorpartners.com/api/coverage. Coverage varies by source; never claim a country is fully covered.
 3. Ask for countries if they are unknown. Search GET https://www.bidadvisorpartners.com/api/agent/v1/opportunities?countries=MX&q=software&lifecycle=open&limit=10 with one to five supported country codes. Historical records use lifecycle=expired; unknown state uses lifecycle=unknown. Do not silently expand countries.

package/src/cli.mjs

@@ -6,7 +6,8 @@ import { stdin, stderr } from 'node:process'
 import { createInterface } from 'node:readline/promises'
 import { Writable } from 'node:stream'
 import { parseArgs } from 'node:util'
-import { apiOrigin, getQuote, networkConfig, requestJson, resourceUrl, walletBalance } from './network.mjs'
+import { doctor } from './doctor.mjs'
+import { apiOrigin, getQuote, networkConfig, resourceUrl, walletBalance } from './network.mjs'
 import { quoteForApproval, sendOriginal, signPurchase } from './payment.mjs'
 import { getReceipt, openReceipts, publicReceipt, quotePurchase, withReceipts } from './receipts.mjs'
 import { createWallet, privateDirectory, unlockWallet, walletAddress } from './wallet.mjs'
@@ -47,12 +48,19 @@ async function terminalQuestion(prompt, secret = false) {
   }
 }
 
-function profile(home, values) {
+function profile(home, values, { allowMissingWallet = false } = {}) {
   const name = required(values.network, 'network')
   const network = networkConfig(name)
-  const wallet = walletAddress(home, required(values.wallet, 'wallet'))
+  const origin = apiOrigin(values.origin, network)
+  const walletName = required(values.wallet, 'wallet')
+  let wallet
+  try { wallet = walletAddress(home, walletName) }
+  catch (error) {
+    if (allowMissingWallet && error.code === 'ENOENT') return { name, network, origin, walletMissing: true }
+    throw error
+  }
   if (network.chain !== wallet.chain) throw Error('Wallet and network are incompatible')
-  return { wallet: wallet.name, name, network, origin: apiOrigin(values.origin, network) }
+  return { wallet: wallet.name, name, network, origin }
 }
 
 async function main(args) {
@@ -62,9 +70,10 @@ async function main(args) {
   if (command === 'doctor') {
     const values = parse(args.slice(1), { network: textOption, origin: textOption })
     const base = apiOrigin(values.origin, values.network ? networkConfig(values.network) : undefined)
-    const { status, body } = await requestJson(base + '/api/agent/v1')
-    if (status !== 200) throw Error('Catalog unavailable. HTTP ' + status)
-    return output({ version, node: process.version, origin: base, state: body.state, paymentOptions: body.paymentOptions })
+    const report = await doctor(base, values.network)
+    output({ version, node: process.version, origin: base, ...report })
+    if (report.configuration.state === 'catalog_unavailable') process.exitCode = 1
+    return
   }
   if (command === 'skills' && action === 'install') {
     const values = parse(options, { client: textOption })
@@ -140,7 +149,7 @@ async function main(args) {
     if (!values.stdio) throw Error('Supply --stdio')
     const home = privateDirectory()
     const configuration = values.wallet || values.network || values.origin
-      ? profile(home, values) : { origin: apiOrigin() }
+      ? profile(home, values, { allowMissingWallet: true }) : { origin: apiOrigin() }
     const { serve } = await import('./mcp.mjs')
     const db = openReceipts(home)
     process.once('exit', () => db.close())

package/src/doctor.mjs

@@ -0,0 +1,54 @@
+import { networkConfig, requestJson, resourceUrl, validateQuote } from './network.mjs'
+
+export async function doctor(origin, networkName, fetcher) {
+  const resource = resourceUrl(origin, 'search', { countries: ['MX'], limit: 1 })
+  const [catalog, quote] = await Promise.allSettled([
+    requestJson(origin + '/api/agent/v1', {}, fetcher),
+    requestJson(resource, {}, fetcher)
+  ])
+
+  const catalogResponse = catalog.status === 'fulfilled' ? catalog.value : null
+  const catalogBody = catalogResponse?.status === 200 ? catalogResponse.body : null
+  const configuration = {
+    state: typeof catalogBody?.state === 'string' ? catalogBody.state : 'catalog_unavailable',
+    httpStatus: catalogResponse?.status ?? null
+  }
+  const paymentOptions = Array.isArray(catalogBody?.paymentOptions) ? catalogBody.paymentOptions : []
+  const names = networkName ? [networkName] : ['base', 'solana']
+  const response = quote.status === 'fulfilled' ? quote.value : null
+
+  const operational = names.map(name => {
+    const network = networkConfig(name)
+    const result = {
+      name,
+      network: network.id,
+      configured: Array.isArray(catalogBody?.paymentOptions)
+        ? paymentOptions.some(option => option?.network === network.id)
+        : null,
+      httpStatus: response?.status ?? null
+    }
+    if (!response) return { ...result, state: 'probe_failed' }
+    if (response.status !== 402) return { ...result, state: 'quote_unavailable' }
+
+    const challenge = response.body
+    if (challenge?.x402Version !== 2 || challenge.resource?.url !== resource ||
+      !Array.isArray(challenge.accepts) || challenge.accepts.length === 0) {
+      return { ...result, state: 'invalid_quote' }
+    }
+    if (!challenge.accepts.some(offer => offer?.network === network.id)) {
+      return { ...result, state: 'quote_not_offered' }
+    }
+    try {
+      const { amount } = validateQuote(challenge, resource, network)
+      return { ...result, state: 'quote_available', amountAtomic: amount }
+    } catch {
+      return { ...result, state: 'invalid_quote' }
+    }
+  })
+
+  return {
+    // Keep the original catalog fields for consumers of the CLI's JSON output.
+    state: configuration.state, paymentOptions, configuration,
+    quoteProbe: { resource, operational }
+  }
+}

package/src/mcp.mjs

@@ -4,48 +4,86 @@ import { z } from 'zod'
 import { getQuote, requestJson, resourceUrl } from './network.mjs'
 import { getReceipt, publicReceipt, quotePurchase } from './receipts.mjs'
 
-export function createBridge({ db, origin, wallet, name, network, fetcher }) {
+const languageInput = z.enum(['en', 'es']).optional()
+  .describe('Reply language for BAP instructions. Use es for a user speaking Spanish or en for English. Defaults to en.')
+
+const guide = {
+  en: 'https://docs.bidadvisorpartners.com/agents/cli',
+  es: 'https://docs.bidadvisorpartners.com/es/cli'
+}
+const messages = {
+  en: {
+    wallet_missing: 'Check the wallet name in your BAP setup. Create that wallet in your terminal or update the MCP registration to use your existing wallet, then reopen the client.',
+    wallet_setup_required: 'Follow the quick start to create or select a local wallet and register BAP with its wallet name and network. Then reopen the client and retry your quote.',
+    catalog_unavailable: 'BAP returned an error. Run bap doctor in your terminal to check service availability.',
+    catalog_unreachable: 'The client could not read the BAP catalog. Run bap doctor in your terminal. If it works there, check network access in this client.',
+    quote_unavailable: 'BAP could not prepare a valid quote. Run bap doctor for your network and check the connection before retrying.',
+    purchase_unavailable: 'Check the purchase ID and use the same wallet, network and local BAP profile used to request the quote.',
+    approve: 'Show the purchase ID to the user. If they choose to pay, they must approve it in their terminal.'
+  },
+  es: {
+    wallet_missing: 'Revisa el nombre de la billetera en la configuración de BAP. Crea esa billetera en tu terminal o configura el MCP con una que ya tengas. Luego vuelve a abrir el cliente.',
+    wallet_setup_required: 'Sigue la guía para crear o elegir una billetera local y conectar BAP con el nombre de la billetera y la red. Vuelve a abrir el cliente y pide la cotización de nuevo.',
+    catalog_unavailable: 'BAP devolvió un error. Ejecuta bap doctor en tu terminal para comprobar si el servicio está disponible.',
+    catalog_unreachable: 'El cliente no pudo consultar el catálogo de BAP. Ejecuta bap doctor en tu terminal. Si funciona allí, revisa el acceso a internet de este cliente.',
+    quote_unavailable: 'BAP no pudo preparar una cotización válida. Ejecuta bap doctor para tu red y revisa la conexión antes de reintentar.',
+    purchase_unavailable: 'Revisa el ID de compra y usa la misma billetera, red y configuración local de BAP con la que pediste la cotización.',
+    approve: 'Muestra al usuario el ID de compra. Si decide pagar, debe aprobar la compra en su terminal.'
+  }
+}
+
+export function createBridge({ db, origin, wallet, name, network, walletMissing, fetcher }) {
   const server = new McpServer({ name: 'bid-advisor-partners-cli', version: '0.1.0' })
   const result = data => ({ content: [{ type: 'text', text: JSON.stringify(data) }], structuredContent: data })
-  const safe = handler => async args => {
-    try { return result(await handler(args)) }
-    catch {
-      return { isError: true, content: [{ type: 'text', text: 'Request unavailable. Check the runtime catalog or the purchase ID. Use the terminal to approve or recover a payment.' }] }
-    }
+  const failure = (code, language, details = {}) => ({
+    ...result({ code, instruction: messages[language][code], guide: guide[language], ...details }),
+    isError: true
+  })
+  const needsWallet = language => failure(walletMissing ? 'wallet_missing' : 'wallet_setup_required', language)
+  const safe = (handler, errorCode) => async (args = {}) => {
+    const language = args.language ?? 'en'
+    try { return await handler(args, language) }
+    catch { return failure(errorCode, language) }
   }
+
   server.registerTool('get_agent_catalog', {
-    description: 'Free BAP runtime catalog and available networks', annotations: { readOnlyHint: true }
-  }, safe(async () => {
+    description: 'Free BAP runtime catalog and available networks. Works without a local wallet.',
+    inputSchema: { language: languageInput }, annotations: { readOnlyHint: true }
+  }, safe(async (_args, language) => {
     const { status, body } = await requestJson(origin + '/api/agent/v1', {}, fetcher)
-    if (status !== 200) throw Error('Catalog unavailable')
-    return body
-  }))
-  const read = operation => safe(async args => {
-    if (!wallet || !network) throw Error('Wallet and network are required')
+    if (status !== 200) {
+      return failure('catalog_unavailable', language, { httpStatus: status })
+    }
+    return result(body)
+  }, 'catalog_unreachable'))
+
+  const read = operation => safe(async (args, language) => {
+    if (!wallet || !network) return needsWallet(language)
     const resource = resourceUrl(origin, operation, args)
     const row = await quotePurchase(db, { resource, wallet, network: name }, () => getQuote(resource, network, fetcher))
-    return { ...publicReceipt(row), ...(row.proof ? {} : { instruction: 'Ask the user to approve this purchase ID from their terminal. The MCP bridge cannot approve or sign it.' }) }
-  })
+    return result({ ...publicReceipt(row), ...(row.proof ? {} : { instruction: messages[language].approve }) })
+  }, 'quote_unavailable')
   server.registerTool('search_opportunities', {
     description: 'Quote a public procurement search for terminal approval, or return an existing paid result. This tool never signs or sends payment.',
     inputSchema: {
       countries: z.array(z.string().regex(/^[A-Z]{2}$/)).min(1).max(5), q: z.string().max(120).optional(),
       kind: z.enum(['business', 'professional']).optional(), lifecycle: z.enum(['open', 'expired', 'unknown']).optional(),
-      page: z.number().int().min(1).max(100).optional(), limit: z.number().int().min(1).max(25).optional()
+      page: z.number().int().min(1).max(100).optional(), limit: z.number().int().min(1).max(25).optional(), language: languageInput
     }
   }, read('search'))
   server.registerTool('get_opportunity', {
     description: 'Quote one public procurement detail for terminal approval, or return its existing paid result. This tool never signs or sends payment.',
-    inputSchema: { id: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/) }
+    inputSchema: { id: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/), language: languageInput }
   }, read('detail'))
   server.registerTool('get_purchase_status', {
     description: 'Read local purchase state and any delivered result. Payment proof is private.',
-    inputSchema: { id: z.string().uuid() }, annotations: { readOnlyHint: true }
-  }, safe(({ id }) => {
+    inputSchema: { id: z.string().uuid(), language: languageInput }, annotations: { readOnlyHint: true }
+  }, safe(({ id }, language) => {
+    if (!wallet || !network) return needsWallet(language)
     const row = getReceipt(db, id)
     if (row.wallet !== wallet || row.network !== name || new URL(row.resource).origin !== origin) throw Error('Purchase belongs to another profile')
-    return publicReceipt(row)
-  }))
+    return result(publicReceipt(row))
+  }, 'purchase_unavailable'))
   return server
 }