@funyard-org/cli 0.0.0-stage → 0.6.2

package/src/cli.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+import { agentFlags } from './agents.js';
+import { randomBytes } from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { FunyardClient, FunyardError, DEFAULT_BASE_URL, validateBaseURL, redact, safeError } from './client.js';
+import { readConfig, writeConfig, readSecret } from './config.js';
+import { browserLogin } from './browser-login.js';
+import { setupAgent } from './agent-setup.js';
+import { selectAgent } from './agent-selection.js';
+import { runMCP } from './mcp.js';
+
+const HELP = `funyard — independent client (Node >=22)
+Usage: funyard <command> [options]
+Commands:
+  setup [--agent ${agentFlags}]  Detect your Agent, install Agent instructions, authorize in browser and verify access
+  login | auth login          Authorize through your browser (use --key for a hidden API key prompt)
+  agent setup [--agent ${agentFlags}]  Detect your Agent, install FunYard instructions for your Agent
+  logout                      Remove the stored API key (not environment variables)
+  config [--base-url ORIGIN]   Show safe config or set API origin
+  me                          Show account
+  explore [DOMAIN] [--capability ID | --group ID | --search TEXT]
+                              Browse what you can call: domains -> capabilities -> field groups -> fields
+  call CAPABILITY --arg NAME=VALUE ... [--fields A,B]
+                              Call any listed capability, including ones newer than this CLI
+  capabilities [ID]           List capabilities or show one
+  fields [--category NAME]    List field ids, their billing group and group price
+  fields-quote --fields A,B   Dry-run price for a field list (nothing reserved)
+  quote SYMBOL | --symbol SYMBOL  finance.quote
+  get --symbol SYMBOL --fields A,B  finance.get: fields by id, charged per field group
+  crypto --coin ID --fields A,B     crypto.get: e.g. --coin bitcoin --fields crypto.market.price
+  economy --series ID --fields A,B  economy.get: e.g. --series UNRATE --fields economy.latest.value
+  tiktok|instagram|youtube --handle NAME --fields A,B  public social profiles, e.g. tiktok.profile.followers
+  linkedin --company SLUG --fields A,B  linkedin.get: company pages only, e.g. --company stripe
+  trending --platform weibo   social.trending: current hot-search list
+  search --query TEXT         web.search
+  news --query TEXT           news.search
+  read --url URL              web.read
+  company --domain DOMAIN     company.discover
+  research --query TEXT       research.search
+  status --request-id ID | --call-id ID
+  usage                       Show latest 100 account ledger entries
+  cancel --call-id ID
+  mcp                         Serve newline-delimited stdio MCP JSON-RPC
+Options: --base-url ORIGIN, --request-id ID (required for paid calls), --json, --help, --version
+Search/news: --language LANGUAGE --region REGION; research: --language LANGUAGE
+Start with \`funyard explore\`; every level shows prices, arguments and whether this key may call it.
+MCP: one tool per available capability (finance_get, crypto_get, web_search, ...) plus explore, get_call, cancel_call, me, capabilities, fields, fields_quote.
+Paid calls require an explicit stable request_id; no client generates one silently.
+Authentication: FUNYARD_API_KEY or a permission-600 config file.
+Do not pass API keys as command-line arguments or URL parameters.
+`;
+
+let activeKey;
+let jsonOutput = process.argv.includes('--json');
+function readable(value, prefix = '') {
+  if (Array.isArray(value))
+    return value.length
+      ? value.map((item, index) => readable(item, `${prefix}${index + 1}. `)).join('\n')
+      : `${prefix}(none)`;
+  if (value && typeof value === 'object') {
+    return Object.entries(value)
+      .map(([key, item]) =>
+        item && typeof item === 'object'
+          ? `${prefix}${key}:\n${readable(item, `${prefix}  `)}`
+          : `${prefix}${key}: ${item === null ? '—' : String(item)}`,
+      )
+      .join('\n');
+  }
+  return `${prefix}${String(value)}`;
+}
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      allowPositionals: true,
+      strict: true,
+      options: {
+        'base-url': { type: 'string' },
+        key: { type: 'boolean' },
+        'no-browser': { type: 'boolean' },
+        agent: { type: 'string' },
+        'request-id': { type: 'string' },
+        'call-id': { type: 'string' },
+        capability: { type: 'string' },
+        group: { type: 'string' },
+        search: { type: 'string' },
+        arg: { type: 'string', multiple: true },
+        symbol: { type: 'string' },
+        coin: { type: 'string' },
+        series: { type: 'string' },
+        handle: { type: 'string' },
+        company: { type: 'string' },
+        platform: { type: 'string' },
+        fields: { type: 'string' },
+        category: { type: 'string' },
+        query: { type: 'string' },
+        url: { type: 'string' },
+        domain: { type: 'string' },
+        language: { type: 'string' },
+        region: { type: 'string' },
+        start: { type: 'string' },
+        end: { type: 'string' },
+        page: { type: 'string' },
+        'page-size': { type: 'string' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean' },
+        json: { type: 'boolean' },
+      },
+    });
+  } catch {
+    throw new FunyardError('Invalid command or options. Run funyard --help. API keys are never accepted as arguments.');
+  }
+  const { values: flags, positionals } = parsed;
+  jsonOutput = Boolean(flags.json);
+  if (flags.help || (!positionals.length && !flags.version))
+    return process.stdout.write(jsonOutput ? `${JSON.stringify({ help: HELP })}\n` : HELP);
+  if (flags.version) return process.stdout.write(jsonOutput ? '{"version":"0.6.2"}\n' : '0.6.2\n');
+  let [command, ...rest] = positionals;
+  if (command === 'auth' && rest[0] === 'login') {
+    command = 'login';
+    rest = rest.slice(1);
+  }
+  const allowed = {
+    setup: ['agent', 'no-browser'],
+    login: ['key', 'no-browser'],
+    agent: ['agent'],
+    logout: [],
+    config: [],
+    me: [],
+    capabilities: [],
+    fields: ['category'],
+    explore: ['domain', 'capability', 'group', 'search'],
+    call: ['arg', 'fields', 'request-id'],
+    'fields-quote': ['fields'],
+    usage: [],
+    mcp: [],
+    quote: ['symbol', 'request-id'],
+    get: ['symbol', 'fields', 'request-id'],
+    crypto: ['coin', 'fields', 'request-id'],
+    economy: ['series', 'fields', 'request-id'],
+    tiktok: ['handle', 'fields', 'request-id'],
+    instagram: ['handle', 'fields', 'request-id'],
+    youtube: ['handle', 'fields', 'request-id'],
+    linkedin: ['company', 'fields', 'request-id'],
+    trending: ['platform', 'request-id'],
+    search: ['query', 'request-id', 'language', 'region'],
+    news: ['query', 'request-id', 'language', 'region'],
+    read: ['url', 'request-id'],
+    company: ['domain', 'request-id'],
+    research: ['query', 'request-id', 'language'],
+    status: ['call-id', 'request-id'],
+    cancel: ['call-id'],
+  };
+  if (
+    !Object.hasOwn(allowed, command) ||
+    rest.length > (['capabilities', 'quote', 'agent', 'explore', 'call'].includes(command) ? 1 : 0) ||
+    Object.keys(flags).some(flag => !['base-url', 'json', ...allowed[command]].includes(flag))
+  )
+    throw new FunyardError('Invalid command or options. Run funyard --help.');
+  if (command === 'quote' && rest[0]) {
+    if (flags.symbol !== undefined) throw new FunyardError('Provide a positional symbol or --symbol, not both.');
+    flags.symbol = rest[0];
+  }
+  if (command === 'agent') {
+    if (rest[0] !== 'setup') throw new FunyardError(`Use funyard agent setup [--agent ${agentFlags}].`);
+    const installed = await setupAgent(await selectAgent(flags.agent));
+    return process.stdout.write(JSON.stringify(installed) + '\n');
+  }
+  const config = await readConfig();
+  const baseURL = validateBaseURL(
+    flags['base-url'] || process.env.FUNYARD_BASE_URL || config.baseURL || DEFAULT_BASE_URL,
+  );
+  const credentialOrigin = Object.hasOwn(config, 'credentialOrigin') ? config.credentialOrigin : config.baseURL;
+  const print = value => {
+    const safe = redact(value, activeKey);
+    process.stdout.write(`${jsonOutput ? safe : readable(JSON.parse(safe))}\n`);
+  };
+  if (command === 'config') {
+    if (flags['base-url'])
+      await writeConfig({
+        ...config,
+        ...(config.apiKey ? { credentialOrigin: credentialOrigin || null } : {}),
+        baseURL,
+      });
+    return print({ baseURL, hasStoredKey: Boolean(config.apiKey), credentialOrigin: credentialOrigin || null });
+  }
+  if (command === 'logout') {
+    const { apiKey, ...remaining } = config;
+    await writeConfig(remaining);
+    return print({ loggedOut: true, environmentKeyStillSet: Boolean(process.env.FUNYARD_API_KEY) });
+  }
+  if (command === 'login' || command === 'setup') {
+    // Refuse conflicting Agent instructions before starting an authorization request.
+    const installed = command === 'setup' ? await setupAgent(await selectAgent(flags.agent)) : undefined;
+    // Per-origin installation secret survives logout and failed grants; never print it or put it in a URL.
+    const installations =
+      config.installations && typeof config.installations === 'object' && !Array.isArray(config.installations)
+        ? config.installations
+        : {};
+    const installationSecret =
+      typeof installations[baseURL] === 'string' && /^[A-Za-z0-9_-]{43}$/.test(installations[baseURL])
+        ? installations[baseURL]
+        : randomBytes(32).toString('base64url');
+    if (!flags.key) {
+      config.installations = { ...installations, [baseURL]: installationSecret };
+      await writeConfig(config);
+    }
+    activeKey = flags.key
+      ? await readSecret()
+      : (await browserLogin(baseURL, { noBrowser: flags['no-browser'], installationSecret })).apiKey;
+    // Persist a rotated credential before read-only verification; a transient /me failure must not lose it.
+    if (!flags.key) await writeConfig({ ...config, baseURL, credentialOrigin: baseURL, apiKey: activeKey });
+    const client = new FunyardClient({ apiKey: activeKey, baseURL });
+    await client.me();
+    await writeConfig({ ...config, baseURL, credentialOrigin: baseURL, apiKey: activeKey });
+    if (installed) {
+      await client.capabilities();
+      return print({
+        loggedIn: true,
+        baseURL,
+        agent: installed.agent,
+        skill: installed.path,
+        verified: true,
+        next: installed.next,
+      });
+    }
+    return print({ loggedIn: true, baseURL, environmentKeyStillSet: Boolean(process.env.FUNYARD_API_KEY) });
+  }
+  if (
+    process.env.FUNYARD_API_KEY &&
+    !flags['base-url'] &&
+    !process.env.FUNYARD_BASE_URL &&
+    baseURL !== DEFAULT_BASE_URL
+  )
+    throw new FunyardError(
+      'An environment API key cannot implicitly use a non-default origin from config. Set FUNYARD_BASE_URL or pass --base-url explicitly, or unset FUNYARD_API_KEY to use the origin-bound stored key.',
+      { code: 'EXPLICIT_ORIGIN_REQUIRED' },
+    );
+  if (!process.env.FUNYARD_API_KEY && config.apiKey && credentialOrigin !== baseURL)
+    throw new FunyardError(
+      'Stored API key belongs to a different or unknown origin. Run funyard login --base-url with the intended origin; legacy credentials.json is never imported automatically.',
+    );
+  activeKey = process.env.FUNYARD_API_KEY || config.apiKey;
+  const client = new FunyardClient({ apiKey: activeKey, baseURL });
+  if (command === 'mcp') return runMCP(client);
+  if (command === 'me') return print(await client.me());
+  if (command === 'capabilities') return print(await client.capabilities(rest[0], { raw: jsonOutput }));
+  if (command === 'usage') return print(await client.usage());
+  if (command === 'fields') return print(await client.fields(flags.category));
+  if (command === 'explore') {
+    if (rest[0] !== undefined && flags.domain !== undefined)
+      throw new FunyardError('Provide a positional domain or --domain, not both.');
+    return print(
+      await client.explore({
+        domain: rest[0] ?? flags.domain,
+        capability: flags.capability,
+        group: flags.group,
+        q: flags.search,
+      }),
+    );
+  }
+  if (command === 'call') {
+    // Any capability the catalog lists, including ones added after this release: --arg name=value.
+    if (!rest[0]) throw new FunyardError('Missing capability, e.g. funyard call crypto.get --arg coin=bitcoin.');
+    const args = {};
+    for (const pair of flags.arg ?? []) {
+      const at = pair.indexOf('=');
+      if (at < 1 || Object.hasOwn(args, pair.slice(0, at)))
+        throw new FunyardError('Each --arg is name=value, once per name.', { code: 'INVALID_ARGUMENTS' });
+      args[pair.slice(0, at)] = pair.slice(at + 1);
+    }
+    if (flags.fields !== undefined) {
+      if (Object.hasOwn(args, 'fields')) throw new FunyardError('Provide fields once.');
+      args.fields = flags.fields;
+    }
+    return print(await client.call(rest[0], args, { requestId: flags['request-id'] }));
+  }
+  if (command === 'fields-quote') {
+    if (!flags.fields?.trim()) throw new FunyardError('Missing --fields.');
+    return print(await client.fieldsQuote(flags.fields));
+  }
+  if (command === 'status')
+    return print(await client.status({ callId: flags['call-id'], requestId: flags['request-id'] }));
+  if (command === 'cancel') return print(await client.cancel(flags['call-id']));
+  const mapping = {
+    quote: ['finance.quote', 'symbol'],
+    get: ['finance.get', 'symbol'],
+    crypto: ['crypto.get', 'coin'],
+    economy: ['economy.get', 'series'],
+    tiktok: ['tiktok.get', 'handle'],
+    instagram: ['instagram.get', 'handle'],
+    youtube: ['youtube.get', 'handle'],
+    linkedin: ['linkedin.get', 'company'],
+    trending: ['social.trending', 'platform'],
+    search: ['web.search', 'query'],
+    news: ['news.search', 'query'],
+    read: ['web.read', 'url'],
+    company: ['company.discover', 'domain'],
+    research: ['research.search', 'query'],
+  };
+  const [capability, field] = mapping[command];
+  if (!flags[field]?.trim()) throw new FunyardError(`Missing --${field}.`);
+  const fielded = ['get', 'crypto', 'economy', 'tiktok', 'instagram', 'youtube', 'linkedin'].includes(command);
+  if (fielded && !flags.fields?.trim()) throw new FunyardError('Missing --fields.');
+  const requestId = flags['request-id'];
+  const response = await client.call(
+    capability,
+    {
+      [field]: flags[field],
+      ...(fielded ? { fields: flags.fields } : {}),
+      ...(flags.language === undefined ? {} : { language: flags.language }),
+      ...(flags.region === undefined ? {} : { region: flags.region }),
+    },
+    { requestId },
+  );
+  print(response);
+}
+
+main().catch(error => {
+  const safe = redact(safeError(error), activeKey);
+  // Stderr remains structured even when stdout uses the human-readable view.
+  process.stderr.write(`${safe}\n`);
+  process.exitCode = 1;
+});

package/src/client.d.ts

@@ -0,0 +1,97 @@
+import type {
+  Arguments,
+  CapabilityId,
+  CallResponse,
+  CatalogResponse,
+  FieldsCatalogResponse,
+  FieldsQuoteResponse,
+  MeResponse,
+  UsageResponse,
+} from './protocol/index.js';
+export type {
+  Arguments,
+  BillingLine,
+  CapabilityId,
+  Result,
+  EmptyResult,
+  CallResponse,
+  CallSubmission,
+  CatalogResponse,
+  FieldsCatalogResponse,
+  FieldsQuoteResponse,
+  MeResponse,
+  UsageResponse,
+  ErrorResponse,
+} from './protocol/index.js';
+export { REQUEST_ID, CALL_ID } from './protocol/index.js';
+export const DEFAULT_BASE_URL: string;
+export interface ClientOptions {
+  apiKey?: string;
+  FUNYARD_API_KEY?: string;
+  baseURL?: string;
+  FUNYARD_BASE_URL?: string;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+  onDiagnostic?: (event: Record<string, unknown>) => void;
+}
+export class FunyardError extends Error {
+  status?: number;
+  code?: string;
+  requestId?: string;
+  callId?: string;
+  reason?: string;
+  retryAfter?: number;
+  constructor(
+    message: string,
+    options?: {
+      status?: number;
+      code?: string;
+      requestId?: string;
+      callId?: string;
+      reason?: string;
+      retryAfter?: number;
+    },
+  );
+}
+export class FunyardClient {
+  constructor(options?: ClientOptions, extra?: Pick<ClientOptions, 'timeoutMs' | 'fetch' | 'onDiagnostic'>);
+  readonly apiKey: string;
+  readonly baseURL: string;
+  me(signal?: AbortSignal): Promise<MeResponse>;
+  capabilities(id?: CapabilityId, options?: { signal?: AbortSignal }): Promise<CatalogResponse>;
+  usage(options?: Record<string, never>): Promise<UsageResponse>;
+  fields(category?: string, options?: { signal?: AbortSignal }): Promise<FieldsCatalogResponse>;
+  fieldsQuote(fields: string | readonly string[], options?: { signal?: AbortSignal }): Promise<FieldsQuoteResponse>;
+  call<C extends CapabilityId>(
+    capability: C,
+    args: Arguments<C>,
+    options: { requestId: string; signal?: AbortSignal },
+  ): Promise<CallResponse<C>>;
+  create<C extends CapabilityId>(
+    capability: C,
+    requestId: string,
+    args: Arguments<C>,
+    signal?: AbortSignal,
+  ): Promise<CallResponse<C>>;
+  status(
+    ids: { callId: string; requestId?: never } | { callId?: never; requestId: string },
+    signal?: AbortSignal,
+  ): Promise<CallResponse>;
+  getCall(
+    ids: { call_id: string; request_id?: never } | { call_id?: never; request_id: string },
+    signal?: AbortSignal,
+  ): Promise<CallResponse>;
+  cancel(callId: string, signal?: AbortSignal): Promise<CallResponse>;
+  request(
+    path: string,
+    options?: { method?: 'GET' | 'POST'; body?: unknown; requestId?: string; callId?: string; signal?: AbortSignal },
+  ): Promise<unknown>;
+  request(
+    method: 'GET' | 'POST',
+    route: string,
+    options?: { body?: unknown; requestID?: string; callID?: string; signal?: AbortSignal },
+  ): Promise<unknown>;
+}
+export function validateBaseURL(value: string): string;
+export function safeError(error: unknown): Record<string, unknown>;
+export function redact(value: unknown, secret?: string): string;