@hightop/cli 0.1.3 → 0.1.5

package/README.md

@@ -85,6 +85,8 @@ Examples:
 hightop self --pretty
 hightop balances --pretty
 hightop operations get <operation-id> --include-onchain --pretty
+hightop borrow collateral-options --pretty
+hightop borrow collateral add --asset <option-id> --amount-usd 25 --simulate --pretty
 hightop borrow repay --asset GREEN --amount-usd 25 --simulate --pretty
 hightop one-off-payments create --to 0x... --asset USDC --amount-usd 25 --simulate --pretty
 hightop webhooks create --url https://example.com/hook --event-types payment.executed,webhook.test --pretty
@@ -94,6 +96,8 @@ hightop raw GET /v1/agent/openapi.json --pretty
 
 The generated command layer supports all catalogued `/v1/agent/*` endpoints. CLI flags are generated from endpoint query/body field names by converting underscores to dashes, for example `amount_usd` becomes `--amount-usd`.
 
+For collateral, fetch `hightop borrow collateral-options` first and pass the returned option `id` as `--asset` to `hightop borrow collateral add`. Vault-backed options use the vault contract address as the option id.
+
 For complex bodies, pass a JSON object:
 
 ```sh

package/dist/cli.js

@@ -2,6 +2,8 @@ import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { agentApiEndpoints, buildAgentApiPath, createIdempotencyKey, HightopAgentClient, HightopAgentOperationWaitTimeoutError, HightopAgentSDKError, } from '@hightop/sdk';
+import { buildCliEndpointCommands, commandDisplayName, endpointCanSimulate as commandEndpointCanSimulate, endpointCanWait, KNOWN_BOOLEAN_REQUEST_FIELDS, requestFieldNames, } from './commandMetadata.js';
+import { SIMULATABLE_ENDPOINT_KEYS } from './simulatableEndpointKeys.js';
 class CliUsageError extends Error {
     constructor(message) {
         super(message);
@@ -22,18 +24,6 @@ class CliWriteError extends Error {
         this.response = input.response;
     }
 }
-const KNOWN_BOOLEAN_REQUEST_FIELDS = [
-    'allow_conversion',
-    'allow_partial',
-    'enabled',
-    'move_all',
-    'remove_all',
-    'repay_all',
-    'to_best_available',
-    'use_available_cash_first',
-    'use_best_available',
-    'withdraw_all',
-];
 const BOOLEAN_REQUEST_FIELDS = new Set(KNOWN_BOOLEAN_REQUEST_FIELDS);
 const NULLABLE_REQUEST_FIELDS = new Set(['body', 'description', 'note']);
 const BOOLEAN_FLAGS = new Set([
@@ -48,24 +38,6 @@ const BOOLEAN_FLAGS = new Set([
 ]);
 const PACKAGE_JSON_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
 const PUBLIC_NO_AUTH_CLI_ENDPOINT_KEYS = new Set(['GET /v1/agent/openapi.json', 'GET /v1/agent/capabilities.json']);
-// Mirrors SIMULATED_WRITE_ROUTES in src/backend/agentApi/simulate.ts.
-const SIMULATABLE_ENDPOINT_KEYS = new Set([
-    'POST /v1/agent/payments',
-    'POST /v1/agent/one-off-payments',
-    'POST /v1/agent/conversions/quote',
-    'POST /v1/agent/conversions',
-    'POST /v1/agent/earn/deposit',
-    'POST /v1/agent/earn/withdraw',
-    'POST /v1/agent/earn/move',
-    'POST /v1/agent/earn/rewards/claim',
-    'POST /v1/agent/borrow',
-    'POST /v1/agent/borrow/repay',
-    'POST /v1/agent/borrow/deleverage',
-    'POST /v1/agent/borrow/collateral/add',
-    'POST /v1/agent/borrow/collateral/remove',
-    'POST /v1/agent/withdrawals/to-bank',
-    'POST /v1/agent/withdrawals/to-crypto',
-]);
 function readCliVersion() {
     return JSON.parse(readFileSync(PACKAGE_JSON_PATH, 'utf8')).version;
 }
@@ -118,125 +90,11 @@ function hasFlag(parsed, name) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function endpointSegments(endpoint) {
-    return endpoint.path
-        .replace(/^\/v1\/agent\/?/, '')
-        .split('/')
-        .filter(Boolean);
-}
-function endpointPathParamsAfterCommand(endpoint) {
-    return endpoint.pathParams.filter((param) => !endpoint.queryParams.includes(param) && !endpoint.bodyParams.includes(param));
-}
-function endpointCanWait(endpoint) {
-    return ['AgentApiWriteResponse', 'AgentApiX402SignResponse', 'AgentApiX402PurchaseResponse'].includes(endpoint.responseType ?? '');
-}
+const CLI_ENDPOINT_COMMANDS = buildCliEndpointCommands(agentApiEndpoints, {
+    simulatableEndpointKeys: SIMULATABLE_ENDPOINT_KEYS,
+});
 function endpointCanSimulate(endpoint) {
-    return SIMULATABLE_ENDPOINT_KEYS.has(endpoint.key);
-}
-function commandUsage(commandPath, endpoint, pathParamsAfterCommand) {
-    const pathSuffix = pathParamsAfterCommand.map((param) => ` <${param}>`).join('');
-    const flags = [...endpoint.queryParams, ...endpoint.bodyParams]
-        .filter((param) => !endpoint.pathParams.includes(param))
-        .map((param) => ` [--${param.replace(/_/g, '-')} <value>]`)
-        .join('');
-    const waitFlag = endpointCanWait(endpoint) ? ' [--wait]' : '';
-    const simulateFlag = endpointCanSimulate(endpoint) ? ' [--simulate]' : '';
-    const submitFlags = endpoint.idempotencyRequired ? ` [--idempotency-key <key>]${waitFlag}${simulateFlag}` : '';
-    return `hightop ${commandPath.join(' ')}${pathSuffix}${flags}${submitFlags}`;
-}
-function commandFromEndpoint(endpoint) {
-    const segments = endpointSegments(endpoint);
-    const pathParamsAfterCommand = endpointPathParamsAfterCommand(endpoint);
-    const staticSegments = segments.filter((segment) => !segment.startsWith('{'));
-    if (endpoint.path === '/v1/agent/capabilities.json') {
-        return { commandPath: ['capabilities', 'json'], pathParamsAfterCommand };
-    }
-    if (endpoint.method === 'GET' && endpoint.pathParams.length === 0) {
-        return { commandPath: staticSegments, pathParamsAfterCommand };
-    }
-    if (endpoint.method === 'GET' && endpoint.pathParams.length > 0) {
-        const tail = staticSegments.slice(1);
-        if (tail.length > 0) {
-            return { commandPath: [staticSegments[0], ...tail], pathParamsAfterCommand };
-        }
-        return { commandPath: [staticSegments[0], 'get'], pathParamsAfterCommand };
-    }
-    if (endpoint.method === 'POST') {
-        if (endpoint.pathParams.length > 0) {
-            return { commandPath: staticSegments, pathParamsAfterCommand };
-        }
-        if (staticSegments.length === 1) {
-            if (staticSegments[0] === 'conversions') {
-                return { commandPath: ['conversions', 'execute'], pathParamsAfterCommand };
-            }
-            return { commandPath: [staticSegments[0], 'create'], pathParamsAfterCommand };
-        }
-        return { commandPath: staticSegments, pathParamsAfterCommand };
-    }
-    if (endpoint.method === 'PATCH') {
-        return { commandPath: [staticSegments[0], 'update'], pathParamsAfterCommand };
-    }
-    if (endpoint.method === 'DELETE') {
-        return { commandPath: [staticSegments[0], 'delete'], pathParamsAfterCommand };
-    }
-    return { commandPath: staticSegments, pathParamsAfterCommand };
-}
-function buildCliEndpointCommands() {
-    const commands = agentApiEndpoints
-        .filter((endpoint) => endpoint.key !== 'POST /v1/agent/simulate')
-        .flatMap((endpoint) => {
-        const primary = commandFromEndpoint(endpoint);
-        const aliases = [primary];
-        if (endpoint.key === 'GET /v1/agent/self/usage') {
-            aliases.push({ commandPath: ['usage'], pathParamsAfterCommand: [] });
-        }
-        if (endpoint.method === 'GET' &&
-            endpoint.pathParams.length === 0 &&
-            endpoint.queryParams.some((param) => param === 'cursor' || param === 'limit')) {
-            aliases.push({ commandPath: [...primary.commandPath, 'list'], pathParamsAfterCommand: [] });
-        }
-        return aliases.map((alias) => ({
-            commandPath: alias.commandPath,
-            endpoint,
-            pathParamsAfterCommand: alias.pathParamsAfterCommand,
-            usage: commandUsage(alias.commandPath, endpoint, alias.pathParamsAfterCommand),
-        }));
-    });
-    commands.push({
-        commandPath: ['openapi'],
-        endpoint: {
-            bodyParams: [],
-            bodySchema: null,
-            description: 'Return the public Agent API OpenAPI document.',
-            idempotencyRequired: false,
-            key: 'GET /v1/agent/openapi.json',
-            method: 'GET',
-            path: '/v1/agent/openapi.json',
-            pathParams: [],
-            queryParams: [],
-            requestSchema: null,
-            requestType: null,
-            responseSchema: null,
-            responseType: null,
-            routeClass: 'read',
-        },
-        pathParamsAfterCommand: [],
-        usage: 'hightop openapi',
-    });
-    const seen = new Set();
-    return commands.filter((command) => {
-        const key = command.commandPath.join(' ');
-        if (seen.has(key)) {
-            return false;
-        }
-        seen.add(key);
-        return true;
-    });
-}
-const CLI_ENDPOINT_COMMANDS = buildCliEndpointCommands();
-function commandDisplayName(command) {
-    const suffix = command.pathParamsAfterCommand.map((param) => ` <${param}>`).join('');
-    return `${command.commandPath.join(' ')}${suffix}`;
+    return commandEndpointCanSimulate(endpoint, SIMULATABLE_ENDPOINT_KEYS);
 }
 function formatGlobalHelp() {
     const commandLines = CLI_ENDPOINT_COMMANDS.map((command) => ({
@@ -292,7 +150,7 @@ function formatCommandHelp(commandPath) {
     const exact = matches.find((command) => command.commandPath.length === commandPath.length);
     if (exact && matches.length === 1) {
         const endpoint = exact.endpoint;
-        const requestFlags = [...endpoint.queryParams, ...endpoint.bodyParams].filter((param) => !endpoint.pathParams.includes(param));
+        const requestFlags = requestFieldNames(endpoint);
         const flagLines = requestFlags.length > 0
             ? `\nRequest flags:\n${requestFlags.map((param) => `  --${param.replace(/_/g, '-')} <value>`).join('\n')}\n`
             : '';

package/dist/commandMetadata.d.ts

@@ -0,0 +1,37 @@
+export type CliEndpointMetadata = {
+    readonly key: string;
+    readonly method: string;
+    readonly path: string;
+    readonly pathParams: readonly string[];
+    readonly queryParams: readonly string[];
+    readonly bodyParams: readonly string[];
+    readonly requestSchema: string | null;
+    readonly bodySchema: string | null;
+    readonly responseSchema: string | null;
+    readonly requestType: string | null;
+    readonly responseType: string | null;
+    readonly idempotencyRequired: boolean;
+    readonly routeClass: string;
+    readonly description: string;
+};
+export type CliEndpointCommand = {
+    commandPath: string[];
+    endpoint: CliEndpointMetadata;
+    pathParamsAfterCommand: string[];
+    requestFlags: string[];
+    usage: string;
+    canSimulate: boolean;
+    canWait: boolean;
+};
+type BuildCliEndpointCommandOptions = {
+    simulatableEndpointKeys: ReadonlySet<string>;
+};
+export declare const KNOWN_BOOLEAN_REQUEST_FIELDS: readonly ["allow_conversion", "allow_partial", "enabled", "move_all", "remove_all", "repay_all", "to_best_available", "use_available_cash_first", "use_best_available", "withdraw_all"];
+export declare function flagNameForField(field: string): string;
+export declare function requestFieldNames(endpoint: CliEndpointMetadata): string[];
+export declare function requestFlags(endpoint: CliEndpointMetadata): string[];
+export declare function endpointCanWait(endpoint: CliEndpointMetadata): boolean;
+export declare function endpointCanSimulate(endpoint: CliEndpointMetadata, simulatableEndpointKeys: ReadonlySet<string>): boolean;
+export declare function commandDisplayName(command: Pick<CliEndpointCommand, 'commandPath' | 'pathParamsAfterCommand'>): string;
+export declare function buildCliEndpointCommands(metadata: readonly CliEndpointMetadata[], options: BuildCliEndpointCommandOptions): CliEndpointCommand[];
+export {};

package/dist/commandMetadata.js

@@ -0,0 +1,151 @@
+export const KNOWN_BOOLEAN_REQUEST_FIELDS = [
+    'allow_conversion',
+    'allow_partial',
+    'enabled',
+    'move_all',
+    'remove_all',
+    'repay_all',
+    'to_best_available',
+    'use_available_cash_first',
+    'use_best_available',
+    'withdraw_all',
+];
+export function flagNameForField(field) {
+    return field.replace(/_/g, '-');
+}
+export function requestFieldNames(endpoint) {
+    return [...endpoint.queryParams, ...endpoint.bodyParams].filter((param) => !endpoint.pathParams.includes(param));
+}
+export function requestFlags(endpoint) {
+    return requestFieldNames(endpoint).map((param) => `--${flagNameForField(param)}`);
+}
+export function endpointCanWait(endpoint) {
+    return ['AgentApiWriteResponse', 'AgentApiX402SignResponse', 'AgentApiX402PurchaseResponse'].includes(endpoint.responseType ?? '');
+}
+export function endpointCanSimulate(endpoint, simulatableEndpointKeys) {
+    return simulatableEndpointKeys.has(endpoint.key);
+}
+export function commandDisplayName(command) {
+    const suffix = command.pathParamsAfterCommand.map((param) => ` <${param}>`).join('');
+    return `${command.commandPath.join(' ')}${suffix}`;
+}
+function endpointSegments(endpoint) {
+    return endpoint.path
+        .replace(/^\/v1\/agent\/?/, '')
+        .split('/')
+        .filter(Boolean);
+}
+function endpointPathParamsAfterCommand(endpoint) {
+    return endpoint.pathParams.filter((param) => !endpoint.queryParams.includes(param) && !endpoint.bodyParams.includes(param));
+}
+function commandUsage(commandPath, endpoint, pathParamsAfterCommand, options) {
+    const pathSuffix = pathParamsAfterCommand.map((param) => ` <${param}>`).join('');
+    const flags = requestFlags(endpoint)
+        .map((flag) => ` [${flag} <value>]`)
+        .join('');
+    const waitFlag = endpointCanWait(endpoint) ? ' [--wait]' : '';
+    const simulateFlag = endpointCanSimulate(endpoint, options.simulatableEndpointKeys) ? ' [--simulate]' : '';
+    const submitFlags = endpoint.idempotencyRequired ? ` [--idempotency-key <key>]${waitFlag}${simulateFlag}` : '';
+    return `hightop ${commandPath.join(' ')}${pathSuffix}${flags}${submitFlags}`;
+}
+function commandFromEndpoint(endpoint) {
+    const segments = endpointSegments(endpoint);
+    const pathParamsAfterCommand = endpointPathParamsAfterCommand(endpoint);
+    const staticSegments = segments.filter((segment) => !segment.startsWith('{'));
+    if (endpoint.path === '/v1/agent/capabilities.json') {
+        return { commandPath: ['capabilities', 'json'], pathParamsAfterCommand };
+    }
+    if (endpoint.method === 'GET' && endpoint.pathParams.length === 0) {
+        return { commandPath: staticSegments, pathParamsAfterCommand };
+    }
+    if (endpoint.method === 'GET' && endpoint.pathParams.length > 0) {
+        const tail = staticSegments.slice(1);
+        if (tail.length > 0) {
+            return { commandPath: [staticSegments[0], ...tail], pathParamsAfterCommand };
+        }
+        return { commandPath: [staticSegments[0], 'get'], pathParamsAfterCommand };
+    }
+    if (endpoint.method === 'POST') {
+        if (endpoint.pathParams.length > 0) {
+            return { commandPath: staticSegments, pathParamsAfterCommand };
+        }
+        if (staticSegments.length === 1) {
+            if (staticSegments[0] === 'conversions') {
+                return { commandPath: ['conversions', 'execute'], pathParamsAfterCommand };
+            }
+            return { commandPath: [staticSegments[0], 'create'], pathParamsAfterCommand };
+        }
+        return { commandPath: staticSegments, pathParamsAfterCommand };
+    }
+    if (endpoint.method === 'PATCH') {
+        return { commandPath: [staticSegments[0], 'update'], pathParamsAfterCommand };
+    }
+    if (endpoint.method === 'DELETE') {
+        return { commandPath: [staticSegments[0], 'delete'], pathParamsAfterCommand };
+    }
+    return { commandPath: staticSegments, pathParamsAfterCommand };
+}
+function openApiEndpoint() {
+    return {
+        bodyParams: [],
+        bodySchema: null,
+        description: 'Return the public Agent API OpenAPI document.',
+        idempotencyRequired: false,
+        key: 'GET /v1/agent/openapi.json',
+        method: 'GET',
+        path: '/v1/agent/openapi.json',
+        pathParams: [],
+        queryParams: [],
+        requestSchema: null,
+        requestType: null,
+        responseSchema: null,
+        responseType: null,
+        routeClass: 'read',
+    };
+}
+export function buildCliEndpointCommands(metadata, options) {
+    const commands = metadata
+        .filter((endpoint) => endpoint.key !== 'POST /v1/agent/simulate')
+        .flatMap((endpoint) => {
+        const primary = commandFromEndpoint(endpoint);
+        const aliases = [primary];
+        if (endpoint.key === 'GET /v1/agent/self/usage') {
+            aliases.push({ commandPath: ['usage'], pathParamsAfterCommand: [] });
+        }
+        if (endpoint.method === 'GET' &&
+            endpoint.pathParams.length === 0 &&
+            endpoint.queryParams.some((param) => param === 'cursor' || param === 'limit')) {
+            aliases.push({ commandPath: [...primary.commandPath, 'list'], pathParamsAfterCommand: [] });
+        }
+        return aliases.map((alias) => ({
+            commandPath: alias.commandPath,
+            endpoint,
+            pathParamsAfterCommand: alias.pathParamsAfterCommand,
+            requestFlags: requestFlags(endpoint),
+            usage: commandUsage(alias.commandPath, endpoint, alias.pathParamsAfterCommand, options),
+            canSimulate: endpointCanSimulate(endpoint, options.simulatableEndpointKeys),
+            canWait: endpointCanWait(endpoint),
+        }));
+    });
+    const openapi = openApiEndpoint();
+    commands.push({
+        commandPath: ['openapi'],
+        endpoint: openapi,
+        pathParamsAfterCommand: [],
+        requestFlags: [],
+        usage: 'hightop openapi',
+        canSimulate: false,
+        canWait: false,
+    });
+    const seen = new Set();
+    return commands
+        .filter((command) => {
+        const key = command.commandPath.join(' ');
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    })
+        .sort((a, b) => commandDisplayName(a).localeCompare(commandDisplayName(b)));
+}

package/dist/simulatableEndpointKeys.d.ts

@@ -0,0 +1 @@
+export declare const SIMULATABLE_ENDPOINT_KEYS: ReadonlySet<string>;

package/dist/simulatableEndpointKeys.js

@@ -0,0 +1,23 @@
+// CLI-supported write routes that may be routed through POST /v1/agent/simulate.
+// Keep this in sync with compatible entries in src/backend/agentApi/simulate.ts.
+const SIMULATABLE_ENDPOINT_KEY_VALUES = [
+    'POST /v1/agent/payments',
+    'POST /v1/agent/one-off-payments',
+    'POST /v1/agent/conversions/quote',
+    'POST /v1/agent/conversions',
+    'POST /v1/agent/earn/deposit',
+    'POST /v1/agent/earn/withdraw',
+    'POST /v1/agent/earn/move',
+    'POST /v1/agent/earn/rewards/claim',
+    'POST /v1/agent/borrow',
+    'POST /v1/agent/borrow/repay',
+    'POST /v1/agent/borrow/deleverage',
+    'POST /v1/agent/borrow/collateral/add',
+    'POST /v1/agent/borrow/collateral/remove',
+    'POST /v1/agent/withdrawals/to-bank',
+    'POST /v1/agent/withdrawals/to-crypto',
+    'POST /v1/agent/trusted-destinations/{id}/confirm',
+    'POST /v1/agent/trusted-destinations/{id}/cancel',
+    'DELETE /v1/agent/trusted-destinations/{id}',
+];
+export const SIMULATABLE_ENDPOINT_KEYS = new Set(SIMULATABLE_ENDPOINT_KEY_VALUES);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hightop/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -41,6 +41,6 @@
     "test": "vitest run --config vitest.config.ts"
   },
   "dependencies": {
-    "@hightop/sdk": "0.1.3"
+    "@hightop/sdk": "0.1.5"
   }
 }