xapi-to 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xapi-to",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Agent-friendly CLI for xapi - discover and call capabilities and APIs",
   "type": "module",
   "bin": {

package/src/codegen.ts

@@ -0,0 +1,306 @@
+/**
+ * Code snippet generation for API actions.
+ *
+ * Generates executable code in curl, Python, JavaScript, TypeScript, and Go
+ * that calls the xapi action execute endpoint.
+ */
+
+import { scheme } from './config.ts';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface CodegenParams {
+  actionId: string;
+  input: Record<string, unknown>;
+  actionHost: string;
+}
+
+interface ResolvedTarget {
+  lang: string;
+  lib: string;
+}
+
+// ── Target resolution ────────────────────────────────────────────────────────
+
+const TARGET_MAP: Record<string, ResolvedTarget> = {
+  'curl':                { lang: 'curl',       lib: 'curl' },
+  'python':              { lang: 'python',     lib: 'requests' },
+  'py':                  { lang: 'python',     lib: 'requests' },
+  'python.requests':     { lang: 'python',     lib: 'requests' },
+  'python.httpx':        { lang: 'python',     lib: 'httpx' },
+  'py.requests':         { lang: 'python',     lib: 'requests' },
+  'py.httpx':            { lang: 'python',     lib: 'httpx' },
+  'javascript':          { lang: 'javascript', lib: 'fetch' },
+  'js':                  { lang: 'javascript', lib: 'fetch' },
+  'javascript.fetch':    { lang: 'javascript', lib: 'fetch' },
+  'javascript.axios':    { lang: 'javascript', lib: 'axios' },
+  'js.fetch':            { lang: 'javascript', lib: 'fetch' },
+  'js.axios':            { lang: 'javascript', lib: 'axios' },
+  'typescript':          { lang: 'typescript', lib: 'fetch' },
+  'ts':                  { lang: 'typescript', lib: 'fetch' },
+  'typescript.fetch':    { lang: 'typescript', lib: 'fetch' },
+  'ts.fetch':            { lang: 'typescript', lib: 'fetch' },
+  'go':                  { lang: 'go',         lib: 'net/http' },
+};
+
+const SUPPORTED_TARGETS = [
+  'curl',
+  'python (py) [.requests, .httpx]',
+  'javascript (js) [.fetch, .axios]',
+  'typescript (ts) [.fetch]',
+  'go [net/http]',
+];
+
+export function resolveTarget(raw: string): ResolvedTarget {
+  const target = TARGET_MAP[raw.toLowerCase()];
+  if (!target) {
+    throw new Error(
+      `unknown --code target: "${raw}". Supported: ${SUPPORTED_TARGETS.join(', ')}`,
+    );
+  }
+  return target;
+}
+
+// ── Default input builder ────────────────────────────────────────────────────
+
+interface InputSchema {
+  properties?: Record<string, { type?: string; default?: unknown }>;
+  required?: string[];
+}
+
+function typeDefault(type: string): unknown {
+  switch (type) {
+    case 'string': return '';
+    case 'number': case 'integer': return 0;
+    case 'boolean': return false;
+    case 'object': return {};
+    case 'array': return [];
+    default: return '';
+  }
+}
+
+export function buildDefaultInput(schema: InputSchema): Record<string, unknown> {
+  if (!schema.properties) return {};
+  const result: Record<string, unknown> = {};
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    if (prop.default !== undefined) {
+      // Clone reference types to avoid shared mutation
+      const val = prop.default;
+      result[key] = (typeof val === 'object' && val !== null) ? JSON.parse(JSON.stringify(val)) : val;
+    } else {
+      result[key] = typeDefault(prop.type ?? 'string');
+    }
+  }
+  return result;
+}
+
+// ── Code generators ──────────────────────────────────────────────────────────
+
+const SAFE_HOST_PATTERN = /^[a-zA-Z0-9._\-]+(:\d{1,5})?$/;
+
+function validateHost(host: string): void {
+  if (!SAFE_HOST_PATTERN.test(host)) {
+    throw new Error(`invalid actionHost: "${host}" — must be a valid hostname with optional port`);
+  }
+}
+
+function baseUrl(actionHost: string): string {
+  validateHost(actionHost);
+  return `${scheme(actionHost)}://${actionHost}/v1/actions/execute`;
+}
+
+function jsonBody(actionId: string, input: Record<string, unknown>): string {
+  return JSON.stringify({ action_id: actionId, input }, null, 2);
+}
+
+/** Re-indent a multi-line string so continuation lines are aligned */
+function indent(text: string, spaces: number): string {
+  const pad = ' '.repeat(spaces);
+  const lines = text.split('\n');
+  return lines.map((line, i) => (i === 0 ? line : pad + line)).join('\n');
+}
+
+/** Escape single quotes for POSIX shell single-quoted strings */
+function shellEscape(s: string): string {
+  return s.replace(/'/g, "'\\''");
+}
+
+function genCurl(params: CodegenParams): string {
+  const url = baseUrl(params.actionHost);
+  const body = jsonBody(params.actionId, params.input);
+  return [
+    '# Set XAPI_API_KEY env var or replace with your key',
+    `curl -X POST '${shellEscape(url)}' \\`,
+    `  -H 'Content-Type: application/json' \\`,
+    `  -H "XAPI-Key: \${XAPI_API_KEY}" \\`,
+    `  -d '${shellEscape(body)}'`,
+  ].join('\n');
+}
+
+function genPython(lib: 'requests' | 'httpx', params: CodegenParams): string {
+  const url = baseUrl(params.actionHost);
+  const payload = { action_id: params.actionId, input: params.input };
+  return [
+    `# pip install ${lib}`,
+    '# Set XAPI_API_KEY env var or replace with your key',
+    'import os',
+    `import ${lib}`,
+    '',
+    `resp = ${lib}.post(`,
+    `    "${url}",`,
+    `    headers={`,
+    `        "Content-Type": "application/json",`,
+    `        "XAPI-Key": os.environ["XAPI_API_KEY"],`,
+    `    },`,
+    `    json=${indent(pythonDict(payload), 4)},`,
+    `)`,
+    'print(resp.json())',
+  ].join('\n');
+}
+
+function genJavaScriptFetch(params: CodegenParams): string {
+  const url = baseUrl(params.actionHost);
+  const body = jsonBody(params.actionId, params.input);
+  return [
+    '// Set XAPI_API_KEY env var or replace with your key',
+    `const resp = await fetch("${url}", {`,
+    `  method: "POST",`,
+    `  headers: {`,
+    `    "Content-Type": "application/json",`,
+    `    "XAPI-Key": process.env.XAPI_API_KEY,`,
+    `  },`,
+    `  body: JSON.stringify(${indent(body, 2)}),`,
+    `});`,
+    'console.log(await resp.json());',
+  ].join('\n');
+}
+
+function genJavaScriptAxios(params: CodegenParams): string {
+  const url = baseUrl(params.actionHost);
+  const body = jsonBody(params.actionId, params.input);
+  return [
+    '// npm install axios',
+    '// Set XAPI_API_KEY env var or replace with your key',
+    'import axios from "axios";',
+    '',
+    `const resp = await axios.post(`,
+    `  "${url}",`,
+    `  ${indent(body, 2)},`,
+    `  {`,
+    `    headers: {`,
+    `      "Content-Type": "application/json",`,
+    `      "XAPI-Key": process.env.XAPI_API_KEY,`,
+    `    },`,
+    `  },`,
+    `);`,
+    'console.log(resp.data);',
+  ].join('\n');
+}
+
+function genTypescriptFetch(params: CodegenParams): string {
+  const url = baseUrl(params.actionHost);
+  const body = jsonBody(params.actionId, params.input);
+  return [
+    '// Set XAPI_API_KEY env var or replace with your key',
+    `const resp: Response = await fetch("${url}", {`,
+    `  method: "POST",`,
+    `  headers: {`,
+    `    "Content-Type": "application/json",`,
+    `    "XAPI-Key": process.env.XAPI_API_KEY!,`,
+    `  },`,
+    `  body: JSON.stringify(${indent(body, 2)}),`,
+    `});`,
+    'const data: unknown = await resp.json();',
+    'console.log(data);',
+  ].join('\n');
+}
+
+function genGo(params: CodegenParams): string {
+  const url = baseUrl(params.actionHost);
+  const body = jsonBody(params.actionId, params.input);
+  const escaped = body.replace(/`/g, '` + "`" + `');
+  return [
+    '// Set XAPI_API_KEY env var or replace with your key',
+    'package main',
+    '',
+    'import (',
+    '\t"fmt"',
+    '\t"io"',
+    '\t"net/http"',
+    '\t"os"',
+    '\t"strings"',
+    ')',
+    '',
+    'func main() {',
+    `\tbody := \`${escaped}\``,
+    `\treq, err := http.NewRequest("POST", "${url}", strings.NewReader(body))`,
+    '\tif err != nil {',
+    '\t\tpanic(err)',
+    '\t}',
+    '\treq.Header.Set("Content-Type", "application/json")',
+    '\treq.Header.Set("XAPI-Key", os.Getenv("XAPI_API_KEY"))',
+    '',
+    '\tresp, err := http.DefaultClient.Do(req)',
+    '\tif err != nil {',
+    '\t\tpanic(err)',
+    '\t}',
+    '\tdefer resp.Body.Close()',
+    '',
+    '\tresult, err := io.ReadAll(resp.Body)',
+    '\tif err != nil {',
+    '\t\tpanic(err)',
+    '\t}',
+    '\tfmt.Println(string(result))',
+    '}',
+  ].join('\n');
+}
+
+// ── Python dict formatter ────────────────────────────────────────────────────
+
+function pythonDict(obj: unknown, depth = 0): string {
+  const pad = '    '.repeat(depth);
+  const inner = '    '.repeat(depth + 1);
+
+  if (obj === null || obj === undefined) return 'None';
+  if (typeof obj === 'boolean') return obj ? 'True' : 'False';
+  if (typeof obj === 'number') return String(obj);
+  if (typeof obj === 'string') return JSON.stringify(obj);
+
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) return '[]';
+    const items = obj.map(v => `${inner}${pythonDict(v, depth + 1)}`);
+    return `[\n${items.join(',\n')}\n${pad}]`;
+  }
+
+  if (typeof obj === 'object') {
+    const entries = Object.entries(obj as Record<string, unknown>);
+    if (entries.length === 0) return '{}';
+    const items = entries.map(
+      ([k, v]) => `${inner}${JSON.stringify(k)}: ${pythonDict(v, depth + 1)}`,
+    );
+    return `{\n${items.join(',\n')}\n${pad}}`;
+  }
+
+  return String(obj);
+}
+
+// ── Main entry point ─────────────────────────────────────────────────────────
+
+type Generator = (params: CodegenParams) => string;
+
+const GENERATORS: Record<string, Record<string, Generator>> = {
+  curl:       { curl: genCurl },
+  python:     { requests: p => genPython('requests', p), httpx: p => genPython('httpx', p) },
+  javascript: { fetch: genJavaScriptFetch, axios: genJavaScriptAxios },
+  typescript: { fetch: genTypescriptFetch },
+  go:         { 'net/http': genGo },
+};
+
+export function generateCode(target: string, params: CodegenParams): { lang: string; lib: string; code: string } {
+  const { lang, lib } = resolveTarget(target);
+  const generator = GENERATORS[lang]?.[lib];
+  if (!generator) {
+    throw new Error(`no generator for ${lang}.${lib}`);
+  }
+  return { lang, lib, code: generator(params) };
+}

package/src/commands/action.ts

@@ -6,10 +6,144 @@
 
 import { getConfig, requireApiKey } from '../config.ts';
 import * as client from '../client.ts';
-import { output, err } from '../format.ts';
+import { output, err, getFormat } from '../format.ts';
+import { generateCode, buildDefaultInput, resolveTarget } from '../codegen.ts';
 
 const VALID_SOURCES = ['capability', 'api'];
 
+// ── Subcommand help texts ────────────────────────────────────────────────────
+
+const LIST_HELP = `xapi list - List all actions
+
+USAGE
+  xapi list [flags]
+
+FLAGS
+  --source capability|api   Filter by source type
+  --category <name>         Filter by category
+  --service-id <id>         Filter by service
+  --page N                  Page number (default: 1)
+  --page-size N             Results per page
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi list
+  xapi list --source api --format table
+  xapi list --category social --page 2
+`;
+
+const SEARCH_HELP = `xapi search - Search actions by keyword
+
+USAGE
+  xapi search <query> [flags]
+
+FLAGS
+  --source capability|api   Filter by source type
+  --category <name>         Filter by category
+  --page N                  Page number (default: 1)
+  --page-size N             Results per page
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi search twitter
+  xapi search "tweet detail" --source api
+  xapi search weather --category utility --format table
+`;
+
+const GET_HELP = `xapi get - Get action schema
+
+USAGE
+  xapi get <id> [flags]
+
+FLAGS
+  --method GET|POST|...     Filter by HTTP method
+  --code <target>           Generate code snippet instead of showing schema
+  --format json|pretty|table  Output format
+
+CODE TARGETS
+  curl                      cURL command
+  py, python                Python (requests)
+  python.requests           Python with requests
+  py.requests               alias for python.requests
+  python.httpx              Python with httpx
+  py.httpx                  alias for python.httpx
+  js, javascript            JavaScript (fetch)
+  javascript.fetch          JavaScript with fetch
+  js.fetch                  alias for javascript.fetch
+  javascript.axios          JavaScript with axios
+  js.axios                  alias for javascript.axios
+  ts, typescript            TypeScript (fetch)
+  typescript.fetch          TypeScript with fetch
+  ts.fetch                  alias for typescript.fetch
+  go                        Go (net/http)
+
+EXAMPLES
+  xapi get twitter.tweet_detail
+  xapi get twitter.tweet_detail --method POST
+  xapi get twitter.tweet_detail --code curl
+  xapi get twitter.tweet_detail --code python.httpx --format pretty
+`;
+
+const CALL_HELP = `xapi call - Execute an action
+
+USAGE
+  xapi call <id> --input '{"key":"val"}' [flags]
+
+FLAGS
+  --input <json>            Input payload as JSON (required for execution)
+  --method GET|POST|...     Override HTTP method
+  --code <target>           Generate code snippet instead of executing
+  --format json|pretty|table  Output format
+
+CODE TARGETS
+  curl                      cURL command
+  py, python                Python (requests)
+  python.requests           Python with requests
+  py.requests               alias for python.requests
+  python.httpx              Python with httpx
+  py.httpx                  alias for python.httpx
+  js, javascript            JavaScript (fetch)
+  javascript.fetch          JavaScript with fetch
+  js.fetch                  alias for javascript.fetch
+  javascript.axios          JavaScript with axios
+  js.axios                  alias for javascript.axios
+  ts, typescript            TypeScript (fetch)
+  typescript.fetch          TypeScript with fetch
+  ts.fetch                  alias for typescript.fetch
+  go                        Go (net/http)
+
+EXAMPLES
+  xapi call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+  xapi call twitter.tweet_detail --input '{"tweet_id":"123"}' --code py
+  xapi call twitter.tweet_detail --input '{"tweet_id":"123"}' --code curl --format pretty
+`;
+
+/** Print subcommand help and exit if --help flag is set */
+function showHelpIfRequested(flags: Record<string, string>, helpText: string): void {
+  if (flags.help) {
+    console.log(helpText);
+    process.exit(0);
+  }
+}
+
+/** Validate --code flag: check for bare flag and unknown target (fail fast before I/O) */
+function validateCodeFlag(flags: Record<string, string>): void {
+  if (flags.code === 'true') {
+    err('--code requires a target language, e.g. --code curl, --code py, --code js');
+  }
+  resolveTarget(flags.code);
+}
+
+/** Output code snippet respecting --format */
+function outputCode(result: { lang: string; lib: string; code: string }, flags: Record<string, string>) {
+  const fmt = flags.format || getFormat();
+  if (fmt === 'json') {
+    output({ language: result.lang, library: result.lib, code: result.code }, 'json');
+  } else {
+    console.log(result.code);
+  }
+}
+
 /** Validate and return source filter from --source flag */
 function getSource(flags: Record<string, string>): string | undefined {
   if (!flags.source) return undefined;
@@ -20,6 +154,7 @@ function getSource(flags: Record<string, string>): string | undefined {
 }
 
 export async function actionList(args: string[], flags: Record<string, string>) {
+  showHelpIfRequested(flags, LIST_HELP);
   const cfg = getConfig();
   try {
     const res = await client.actionList(cfg, {
@@ -49,6 +184,7 @@ export async function actionList(args: string[], flags: Record<string, string>)
 }
 
 export async function actionSearch(args: string[], flags: Record<string, string>) {
+  showHelpIfRequested(flags, SEARCH_HELP);
   const query = args[0];
   if (!query) err('usage: xapi search <query>');
   const cfg = getConfig();
@@ -119,8 +255,10 @@ export async function actionServices(args: string[], flags: Record<string, strin
 }
 
 export async function actionGet(args: string[], flags: Record<string, string>) {
+  showHelpIfRequested(flags, GET_HELP);
   const id = args[0];
   if (!id) err('usage: xapi get <id> [--method GET|POST|DELETE|...]');
+  if (flags.code) validateCodeFlag(flags);
   const cfg = getConfig();
   try {
     const res = await client.actionGet(id, cfg);
@@ -132,6 +270,20 @@ export async function actionGet(args: string[], flags: Record<string, string>) {
     if (filtered.length === 0) {
       err(`no endpoint found for method "${methodFilter}" in action "${id}"`);
     }
+
+    if (flags.code) {
+      if (filtered.length > 1) {
+        process.stderr.write(
+          `Warning: action "${id}" has ${filtered.length} endpoints; using method "${(filtered[0] as any).method}". Use --method to select a specific one.\n`,
+        );
+      }
+      const action = filtered[0] as any;
+      const input = buildDefaultInput(action.input ?? {});
+      const result = generateCode(flags.code, { actionId: id, input, actionHost: cfg.actionHost });
+      outputCode(result, flags);
+      return;
+    }
+
     output(filtered.length === 1 ? filtered[0] : filtered, flags.format as any);
   } catch (e: any) {
     err('get failed', e.message);
@@ -139,10 +291,11 @@ export async function actionGet(args: string[], flags: Record<string, string>) {
 }
 
 export async function actionCall(args: string[], flags: Record<string, string>) {
+  showHelpIfRequested(flags, CALL_HELP);
   const id = args[0];
   if (!id) err('usage: xapi call <id> --input \'{"key":"val"}\'');
+  if (flags.code) validateCodeFlag(flags);
   const cfg = getConfig();
-  requireApiKey(cfg);
   let input: Record<string, unknown> = {};
   if (flags.input) {
     try {
@@ -154,6 +307,14 @@ export async function actionCall(args: string[], flags: Record<string, string>)
   if (flags.method) {
     input = { ...input, method: flags.method.toUpperCase() };
   }
+
+  if (flags.code) {
+    const result = generateCode(flags.code, { actionId: id, input, actionHost: cfg.actionHost });
+    outputCode(result, flags);
+    return;
+  }
+
+  requireApiKey(cfg);
   try {
     const res = await client.actionCall(id, input, cfg);
     output(res, flags.format as any);

package/src/commands/oauth.ts

@@ -109,6 +109,32 @@ async function findCurrentKeyRecord(
   return match;
 }
 
+// ── Help text ──────────────────────────────────────────────────────────────────
+
+export const OAUTH_HELP = `xapi oauth - Manage OAuth bindings
+
+USAGE
+  xapi oauth <command> [flags]
+
+COMMANDS
+  bind [--provider <name>]   Bind an OAuth account to your API key
+  status                     List current OAuth bindings
+  unbind <binding-id>        Remove an OAuth binding
+  providers                  List available OAuth providers
+
+FLAGS
+  --provider <name>          OAuth provider (default: twitter)
+  --format json|pretty|table   Output format
+
+EXAMPLES
+  xapi oauth bind
+  xapi oauth bind --provider twitter
+  xapi oauth status
+  xapi oauth status --format pretty
+  xapi oauth unbind abc123
+  xapi oauth providers
+`;
+
 // ── Commands ───────────────────────────────────────────────────────────────────
 
 /**

package/src/index.ts

@@ -7,8 +7,8 @@
  *   xapi search <query> [--source capability|api] [--category X] [--page N] [--page-size N]
  *   xapi categories [--source capability|api]
  *   xapi services [--page N] [--page-size N] [--category X]
- *   xapi get <id>
- *   xapi call <id> --input '{"k":"v"}'
+ *   xapi get <id> [--code curl|py|js|ts|go]
+ *   xapi call <id> --input '{"k":"v"}' [--code curl|py|js|ts|go]
  *
  *   xapi config show
  *   xapi config set apiKey=<key>
@@ -30,6 +30,7 @@ import * as regCmds from './commands/register.ts';
 import * as topupCmds from './commands/topup.ts';
 import * as balanceCmds from './commands/balance.ts';
 import * as oauthCmds from './commands/oauth.ts';
+const { OAUTH_HELP } = oauthCmds;
 
 // ── Argument parser ───────────────────────────────────────────────────────────
 
@@ -85,7 +86,10 @@ COMMANDS
     --page N  --page-size N         Pagination
     --category <name>               Filter by category
   get <id> [--method GET|POST|...]   Get action schema (filter by HTTP method)
+    --code <target>                  Generate code snippet (curl, py, js, ts, go)
   call <id> --input '{"key":"val"}'  Execute an action
+    --code <target>                  Generate code snippet instead of executing
+    Variants: python.requests, python.httpx, javascript.fetch, javascript.axios
 
   oauth bind [--provider twitter]   Bind Twitter OAuth to your API key
   oauth status                      List current OAuth bindings
@@ -102,7 +106,7 @@ COMMANDS
 
 GLOBAL FLAGS
   --format json|pretty|table        Output format (default: json)
-  --help                            Show this help
+  --help                            Show help (use with a command for details, e.g. xapi get --help)
 
 ENV VARS
   XAPI_API_KEY       API key (header: XAPI-Key)
@@ -115,7 +119,10 @@ EXAMPLES
   xapi list --source capability
   xapi search twitter --source api
   xapi get twitter.tweet_detail
+  xapi get twitter.tweet_detail --code curl
+  xapi get twitter.tweet_detail --code py --format pretty
   xapi call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+  xapi call twitter.tweet_detail --input '{"tweet_id":"1234567890"}' --code python
   xapi categories
   xapi services --format table
   xapi config set apiKey=xapi_abc123
@@ -127,7 +134,7 @@ EXAMPLES
 async function main() {
   const { positional, flags } = parseArgs(process.argv.slice(2));
 
-  if (flags.help || positional.length === 0) {
+  if (positional.length === 0) {
     console.log(HELP);
     process.exit(0);
   }
@@ -148,6 +155,10 @@ async function main() {
 
     // ── OAuth commands ──
     case 'oauth': {
+      if (flags.help || rest.length === 0) {
+        console.log(OAUTH_HELP);
+        process.exit(0);
+      }
       const [subCmd, ...subRest] = rest;
       switch (subCmd) {
         case 'bind':      return oauthCmds.oauthBind(subRest, flags);