@mercuryo-ai/magicsearch

MagicSearch resolves a refined purchase prompt to the best URL for an agent to continue a checkout, provider, or product discovery flow.

It is the search layer used by MagicPay SDK and CLI surfaces before browser handoff. It can rank a first-party provider catalog, call the MagicPay remote MagicSearch API, or fall back to public search URLs when no indexed provider URL is available.

Install

npm install @mercuryo-ai/magicsearch

This package is ESM-only and supports Node.js 18 or newer.

Remote Client

Use the remote client when an application should query the MagicPay gateway.

import { createRemoteMagicSearchClient } from "@mercuryo-ai/magicsearch";

const search = createRemoteMagicSearchClient({
  apiKey: process.env.MAGICPAY_API_KEY!,
  apiUrl: "https://api.mercuryo.example/functions/v1/api",
});

const result = await search.query({
  query: "buy Claude Pro",
  hints: {
    merchantHint: "Claude",
    country: "US",
  },
});

console.log(result.url);

The remote client posts to POST /magicsearch/query and returns a MagicSearchUrlResult.

Local Client

Use the local client when a runtime already has a provider catalog or wants deterministic public-search fallback behavior.

import { createLocalMagicSearchClient } from "@mercuryo-ai/magicsearch";

const search = createLocalMagicSearchClient({
  fallbackProvider: "duckduckgo",
});

const result = await search.query({
  query: "book a flight from Singapore to Istanbul",
  hints: {
    merchantHint: "Google Flights",
  },
});

If EXA_API_KEY is available, the local client can use Exa before public search fallbacks. Pass exaApiKey: null to force public-search fallback URLs.

Exports

• createRemoteMagicSearchClient
• createLocalMagicSearchClient
• resolveMagicSearchUrl
• buildMagicSearchDiscoveryQuery
• buildMagicSearchProviderQuery
• buildMagicSearchFallbackUrl
• Provider ranking and provider URL helpers
• Public MagicSearch result, query, provider, catalog, and fallback types

CLI

For a standalone command-line tool, install @mercuryo-ai/magicsearch-cli.

License

MIT