@alphafox/cli 0.3.2 → 0.3.4

package/dist/resolve-symbols/catalog.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MARKET_SYMBOLS_PATH = void 0;
+exports.marketSymbolsPath = marketSymbolsPath;
+exports.extractCatalogSymbols = extractCatalogSymbols;
+const errors_1 = require("./errors");
+exports.MARKET_SYMBOLS_PATH = "/api/v1/market/symbols";
+function marketSymbolsPath(exchangeId) {
+    const query = new URLSearchParams({ exchange: exchangeId }).toString();
+    return `${exports.MARKET_SYMBOLS_PATH}?${query}`;
+}
+function extractCatalogSymbols(json) {
+    const root = asRecord(json);
+    const payload = asRecord(root?.data) ?? root;
+    const symbols = payload?.symbols;
+    if (!Array.isArray(symbols)) {
+        throw new errors_1.ResolveSymbolsError({
+            type: "runtime",
+            subtype: "catalog_invalid",
+            message: "market.symbols.list response did not include a symbols array",
+            details: json,
+        });
+    }
+    const out = [];
+    const seen = new Set();
+    for (const item of symbols) {
+        if (typeof item !== "string")
+            continue;
+        const trimmed = item.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    if (out.length === 0) {
+        throw new errors_1.ResolveSymbolsError({
+            type: "runtime",
+            subtype: "catalog_empty",
+            message: "market.symbols.list returned no contract symbols",
+            details: json,
+        });
+    }
+    return out;
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}

package/dist/resolve-symbols/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class ResolveSymbolsError extends Error {
+    readonly type: string;
+    readonly subtype?: string;
+    readonly status?: number;
+    readonly code?: string | number;
+    readonly hint?: string;
+    readonly details?: unknown;
+    constructor(input: {
+        readonly message: string;
+        readonly type?: string;
+        readonly subtype?: string;
+        readonly status?: number;
+        readonly code?: string | number;
+        readonly hint?: string;
+        readonly details?: unknown;
+    });
+}
+export declare function isResolveSymbolsError(value: unknown): value is ResolveSymbolsError;

package/dist/resolve-symbols/errors.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResolveSymbolsError = void 0;
+exports.isResolveSymbolsError = isResolveSymbolsError;
+class ResolveSymbolsError extends Error {
+    type;
+    subtype;
+    status;
+    code;
+    hint;
+    details;
+    constructor(input) {
+        super(input.message);
+        this.name = "ResolveSymbolsError";
+        this.type = input.type ?? "runtime";
+        this.subtype = input.subtype;
+        this.status = input.status;
+        this.code = input.code;
+        this.hint = input.hint;
+        this.details = input.details;
+    }
+}
+exports.ResolveSymbolsError = ResolveSymbolsError;
+function isResolveSymbolsError(value) {
+    return value instanceof ResolveSymbolsError;
+}

package/dist/resolve-symbols/exchanges.d.ts

@@ -0,0 +1,8 @@
+export declare const RESOLVE_SYMBOLS_DEFAULT_EXCHANGE = "binance_perp_usdt";
+export interface ResolveSymbolsExchange {
+    readonly id: string;
+    readonly label: string;
+    readonly aliases: readonly string[];
+}
+export declare const RESOLVE_SYMBOLS_EXCHANGES: readonly ResolveSymbolsExchange[];
+export declare function resolveSymbolsExchangeId(raw: string): ResolveSymbolsExchange;

package/dist/resolve-symbols/exchanges.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOLVE_SYMBOLS_EXCHANGES = exports.RESOLVE_SYMBOLS_DEFAULT_EXCHANGE = void 0;
+exports.resolveSymbolsExchangeId = resolveSymbolsExchangeId;
+exports.RESOLVE_SYMBOLS_DEFAULT_EXCHANGE = "binance_perp_usdt";
+exports.RESOLVE_SYMBOLS_EXCHANGES = [
+    {
+        id: "binance_perp_usdt",
+        label: "Binance",
+        aliases: ["binance", "binanceusdm", "binance_perp_usdt"],
+    },
+    {
+        id: "okx_perp_usdt",
+        label: "OKX",
+        aliases: ["okx", "okx_perp_usdt"],
+    },
+    {
+        id: "bybit_perp_usdt",
+        label: "Bybit",
+        aliases: ["bybit", "bybit_perp_usdt"],
+    },
+    {
+        id: "bitget_perp_usdt",
+        label: "Bitget",
+        aliases: ["bitget", "bitget_perp_usdt"],
+    },
+    {
+        id: "hyperliquid_perp_usdc",
+        label: "HyperLiquid",
+        aliases: ["hyperliquid", "hyperliquid_perp_usdc"],
+    },
+    {
+        id: "aster_perp_usdt",
+        label: "Aster",
+        aliases: ["aster", "aster_perp_usdt"],
+    },
+];
+const EXCHANGE_BY_ALIAS = new Map();
+for (const exchange of exports.RESOLVE_SYMBOLS_EXCHANGES) {
+    EXCHANGE_BY_ALIAS.set(exchange.id, exchange);
+    for (const alias of exchange.aliases) {
+        EXCHANGE_BY_ALIAS.set(alias.toLowerCase(), exchange);
+    }
+}
+function resolveSymbolsExchangeId(raw) {
+    const key = raw.trim().toLowerCase();
+    const exchange = EXCHANGE_BY_ALIAS.get(key);
+    if (!exchange) {
+        const allowed = exports.RESOLVE_SYMBOLS_EXCHANGES.map((item) => item.aliases[0]).join("|");
+        throw new Error(`--exchange must be ${allowed} (got ${raw.trim() || "<empty>"})`);
+    }
+    return exchange;
+}

package/dist/resolve-symbols/match.d.ts

@@ -0,0 +1,6 @@
+import type { CatalogSymbol, ResolveSymbolsQueryResult } from "./types";
+export declare function normalizeSymbolSearchKey(value: string): string;
+export declare function parseCatalogSymbol(symbol: string): CatalogSymbol | null;
+export declare function indexCatalogSymbols(symbols: readonly string[]): readonly CatalogSymbol[];
+export declare function resolveQueryAgainstCatalog(query: string, catalog: readonly CatalogSymbol[], limit?: number): ResolveSymbolsQueryResult;
+export declare function levenshtein(left: string, right: string): number;

package/dist/resolve-symbols/match.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSymbolSearchKey = normalizeSymbolSearchKey;
+exports.parseCatalogSymbol = parseCatalogSymbol;
+exports.indexCatalogSymbols = indexCatalogSymbols;
+exports.resolveQueryAgainstCatalog = resolveQueryAgainstCatalog;
+exports.levenshtein = levenshtein;
+const LINEAR_PERP_PATTERN = /^([\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*)\/(USDT|USDC|USD):\2$/u;
+const QUOTE_ASSETS = ["USDT", "USDC", "BUSD", "USD"];
+const EXACT_REASONS = new Set([
+    "exact_canonical",
+    "exact_compact",
+    "exact_pair",
+    "exact_base",
+]);
+function normalizeSymbolSearchKey(value) {
+    return value
+        .trim()
+        .toUpperCase()
+        .replace(/[^\p{L}\p{N}]/gu, "");
+}
+function parseCatalogSymbol(symbol) {
+    const trimmed = symbol.trim();
+    if (!trimmed)
+        return null;
+    const upper = trimmed.toUpperCase();
+    const linear = LINEAR_PERP_PATTERN.exec(upper);
+    if (linear) {
+        const base = linear[1];
+        const quote = linear[2];
+        const canonical = `${base}/${quote}:${quote}`;
+        const compact = `${base}${quote}`;
+        return {
+            symbol: canonical,
+            base,
+            quote,
+            pair: `${base}/${quote}`,
+            compact,
+            searchKey: normalizeSymbolSearchKey(canonical),
+            baseKey: normalizeSymbolSearchKey(base),
+            compactKey: normalizeSymbolSearchKey(compact),
+        };
+    }
+    const slash = upper.indexOf("/");
+    const colon = upper.lastIndexOf(":");
+    if (slash > 0) {
+        const base = upper.slice(0, slash);
+        const quote = colon > slash ? upper.slice(slash + 1, colon) : upper.slice(slash + 1);
+        const compact = `${base}${quote}`;
+        return {
+            symbol: upper,
+            base,
+            quote,
+            pair: `${base}/${quote}`,
+            compact,
+            searchKey: normalizeSymbolSearchKey(upper),
+            baseKey: normalizeSymbolSearchKey(base),
+            compactKey: normalizeSymbolSearchKey(compact),
+        };
+    }
+    return {
+        symbol: upper,
+        base: upper,
+        quote: "",
+        pair: upper,
+        compact: upper,
+        searchKey: normalizeSymbolSearchKey(upper),
+        baseKey: normalizeSymbolSearchKey(upper),
+        compactKey: normalizeSymbolSearchKey(upper),
+    };
+}
+function indexCatalogSymbols(symbols) {
+    const seen = new Set();
+    const indexed = [];
+    for (const raw of symbols) {
+        const parsed = parseCatalogSymbol(raw);
+        if (!parsed)
+            continue;
+        if (seen.has(parsed.symbol))
+            continue;
+        seen.add(parsed.symbol);
+        indexed.push(parsed);
+    }
+    return indexed;
+}
+function resolveQueryAgainstCatalog(query, catalog, limit = 8) {
+    const trimmed = query.trim();
+    const matches = rankMatches(trimmed, catalog);
+    const exact = matches.filter((item) => EXACT_REASONS.has(item.reason));
+    const close = matches.filter((item) => !EXACT_REASONS.has(item.reason));
+    const capped = (items) => items.slice(0, Math.max(1, limit));
+    if (exact.length === 1) {
+        return {
+            query: trimmed,
+            status: "exact",
+            resolved: exact[0].symbol,
+            needsConfirmation: false,
+            matches: exact,
+            matchCount: exact.length,
+        };
+    }
+    if (exact.length > 1) {
+        return {
+            query: trimmed,
+            status: "ambiguous",
+            resolved: null,
+            needsConfirmation: true,
+            matches: capped(exact),
+            matchCount: exact.length,
+        };
+    }
+    if (close.length === 1) {
+        return {
+            query: trimmed,
+            status: "close",
+            resolved: close[0].symbol,
+            needsConfirmation: true,
+            matches: close,
+            matchCount: 1,
+        };
+    }
+    if (close.length > 1) {
+        return {
+            query: trimmed,
+            status: "ambiguous",
+            resolved: null,
+            needsConfirmation: true,
+            matches: capped(close),
+            matchCount: close.length,
+        };
+    }
+    return {
+        query: trimmed,
+        status: "none",
+        resolved: null,
+        needsConfirmation: false,
+        matches: [],
+        matchCount: 0,
+    };
+}
+function rankMatches(query, catalog) {
+    const canonicalQuery = query.trim().toUpperCase();
+    const queryKey = normalizeSymbolSearchKey(query);
+    if (!canonicalQuery || !queryKey)
+        return [];
+    if (isQuoteAssetKey(queryKey))
+        return [];
+    const queryBaseKey = queryBaseSearchKey(canonicalQuery, queryKey);
+    const scored = [];
+    for (const item of catalog) {
+        const ranked = rankCatalogSymbol(item, canonicalQuery, queryKey, queryBaseKey);
+        if (ranked)
+            scored.push(ranked);
+    }
+    scored.sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        return left.symbol.localeCompare(right.symbol);
+    });
+    return scored;
+}
+function rankCatalogSymbol(item, canonicalQuery, queryKey, queryBaseKey) {
+    if (item.symbol === canonicalQuery) {
+        return match(item.symbol, "exact_canonical", 100);
+    }
+    if (item.pair === canonicalQuery) {
+        return match(item.symbol, "exact_pair", 96);
+    }
+    if (item.compactKey === queryKey || item.searchKey === queryKey) {
+        return match(item.symbol, "exact_compact", 98);
+    }
+    if (item.baseKey === queryKey || item.baseKey === queryBaseKey) {
+        return match(item.symbol, "exact_base", 95);
+    }
+    let best = null;
+    const consider = (reason, score) => {
+        if (!best || score > best.score) {
+            best = match(item.symbol, reason, score);
+        }
+    };
+    if (queryBaseKey.length >= 2 && item.baseKey.startsWith(queryBaseKey)) {
+        consider("prefix", clampScore(80 - (item.baseKey.length - queryBaseKey.length)));
+    }
+    if (queryBaseKey.length >= 3 && queryBaseKey.startsWith(item.baseKey)) {
+        consider("prefix", clampScore(74 - (queryBaseKey.length - item.baseKey.length)));
+    }
+    if (queryBaseKey.length >= 3 && item.baseKey.includes(queryBaseKey)) {
+        consider("contains", 55);
+    }
+    const distance = levenshtein(queryBaseKey, item.baseKey);
+    if (isCloseDistance(queryBaseKey, item.baseKey, distance)) {
+        consider("close", clampScore(48 - distance * 8));
+    }
+    return best;
+}
+function queryBaseSearchKey(canonicalQuery, queryKey) {
+    const linear = LINEAR_PERP_PATTERN.exec(canonicalQuery);
+    if (linear)
+        return normalizeSymbolSearchKey(linear[1]);
+    const slash = canonicalQuery.indexOf("/");
+    if (slash > 0) {
+        return normalizeSymbolSearchKey(canonicalQuery.slice(0, slash));
+    }
+    for (const quote of QUOTE_ASSETS) {
+        if (queryKey.length > quote.length && queryKey.endsWith(quote)) {
+            return queryKey.slice(0, -quote.length);
+        }
+    }
+    return queryKey;
+}
+function isQuoteAssetKey(queryKey) {
+    return QUOTE_ASSETS.includes(queryKey);
+}
+function isCloseDistance(left, right, distance) {
+    const shortest = Math.min(left.length, right.length);
+    if (shortest < 2 || distance <= 0)
+        return false;
+    if (shortest <= 4)
+        return distance === 1;
+    return distance <= 2;
+}
+function match(symbol, reason, score) {
+    return { symbol, reason, score };
+}
+function clampScore(score) {
+    return Math.max(1, Math.min(94, score));
+}
+function levenshtein(left, right) {
+    if (left === right)
+        return 0;
+    if (left.length === 0)
+        return right.length;
+    if (right.length === 0)
+        return left.length;
+    const prev = new Array(right.length + 1);
+    const next = new Array(right.length + 1);
+    for (let j = 0; j <= right.length; j += 1)
+        prev[j] = j;
+    for (let i = 1; i <= left.length; i += 1) {
+        next[0] = i;
+        const leftCh = left.charCodeAt(i - 1);
+        for (let j = 1; j <= right.length; j += 1) {
+            const cost = leftCh === right.charCodeAt(j - 1) ? 0 : 1;
+            next[j] = Math.min((prev[j] ?? 0) + 1, (next[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        for (let j = 0; j <= right.length; j += 1)
+            prev[j] = next[j] ?? 0;
+    }
+    return prev[right.length] ?? Math.max(left.length, right.length);
+}

package/dist/resolve-symbols/parse-args.d.ts

@@ -0,0 +1,5 @@
+import type { ResolveSymbolsRunArgs } from "./types";
+export declare const RESOLVE_SYMBOLS_DEFAULT_LIMIT = 8;
+export declare const RESOLVE_SYMBOLS_MAX_LIMIT = 25;
+export declare const RESOLVE_SYMBOLS_USAGE: string[];
+export declare function parseResolveSymbolsArgs(args: readonly string[]): ResolveSymbolsRunArgs;

package/dist/resolve-symbols/parse-args.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOLVE_SYMBOLS_USAGE = exports.RESOLVE_SYMBOLS_MAX_LIMIT = exports.RESOLVE_SYMBOLS_DEFAULT_LIMIT = void 0;
+exports.parseResolveSymbolsArgs = parseResolveSymbolsArgs;
+const errors_1 = require("./errors");
+const exchanges_1 = require("./exchanges");
+exports.RESOLVE_SYMBOLS_DEFAULT_LIMIT = 8;
+exports.RESOLVE_SYMBOLS_MAX_LIMIT = 25;
+exports.RESOLVE_SYMBOLS_USAGE = [
+    "alphafox resolve-symbols <query...> [--exchange binance] [--limit 8]",
+    "alphafox resolve-symbols --query BTC --query ETH --exchange okx",
+];
+function usage(message, subtype = "invalid_args") {
+    throw new errors_1.ResolveSymbolsError({
+        type: "usage",
+        subtype,
+        message,
+        hint: exports.RESOLVE_SYMBOLS_USAGE[0],
+        status: 400,
+    });
+}
+function takeValue(args, i, flag) {
+    const next = args[i + 1];
+    if (next === undefined || next.startsWith("--")) {
+        usage(`Missing value for ${flag}`, "missing_flag_value");
+    }
+    return { value: next, next: i + 1 };
+}
+function parseResolveSymbolsArgs(args) {
+    const queries = [];
+    let exchange = exchanges_1.RESOLVE_SYMBOLS_DEFAULT_EXCHANGE;
+    let limit = exports.RESOLVE_SYMBOLS_DEFAULT_LIMIT;
+    let help = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--help" || a === "-h") {
+            help = true;
+            continue;
+        }
+        if (!a.startsWith("--")) {
+            queries.push(a);
+            continue;
+        }
+        const eq = a.indexOf("=");
+        const flag = eq >= 0 ? a.slice(0, eq) : a;
+        const inline = eq >= 0 ? a.slice(eq + 1) : undefined;
+        const read = () => {
+            if (inline !== undefined)
+                return inline;
+            const taken = takeValue(args, i, flag);
+            i = taken.next;
+            return taken.value;
+        };
+        switch (flag) {
+            case "--query":
+            case "--symbol":
+                queries.push(read());
+                break;
+            case "--exchange":
+                exchange = read();
+                break;
+            case "--limit": {
+                const n = Number(read());
+                if (!Number.isInteger(n) || n <= 0 || n > exports.RESOLVE_SYMBOLS_MAX_LIMIT) {
+                    usage(`--limit must be an integer 1..${exports.RESOLVE_SYMBOLS_MAX_LIMIT}`, "invalid_limit");
+                }
+                limit = n;
+                break;
+            }
+            default:
+                usage(`Unknown flag: ${flag}`, "unknown_flag");
+        }
+    }
+    if (help) {
+        return { help: true, queries: [], exchange, limit };
+    }
+    const normalizedQueries = queries.map((item) => item.trim()).filter(Boolean);
+    if (normalizedQueries.length === 0) {
+        usage("Provide at least one symbol query", "missing_query");
+    }
+    let resolvedExchange;
+    try {
+        resolvedExchange = (0, exchanges_1.resolveSymbolsExchangeId)(exchange).id;
+    }
+    catch (err) {
+        usage(err instanceof Error ? err.message : String(err), "invalid_exchange");
+    }
+    return {
+        help: false,
+        queries: uniqueQueries(normalizedQueries),
+        exchange: resolvedExchange,
+        limit,
+    };
+}
+function uniqueQueries(queries) {
+    const seen = new Set();
+    const out = [];
+    for (const query of queries) {
+        const key = query.toUpperCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(query);
+    }
+    return out;
+}

package/dist/resolve-symbols/run-command.d.ts

@@ -0,0 +1,21 @@
+import type { ApiRequestOptions, ApiResponse } from "../http/client";
+import type { ResolveSymbolsRunArgs, ResolveSymbolsSuccess } from "./types";
+export interface ResolveSymbolsCliFlags {
+    readonly profile?: string;
+    readonly format: "json" | "jsonl" | "text";
+    readonly yes: boolean;
+    readonly dryRun: boolean;
+    readonly noInput: boolean;
+    readonly unsafeCustomEndpoint?: string;
+    readonly jq?: string;
+}
+export interface ResolveSymbolsRunDeps {
+    readonly apiRequest?: (options: ApiRequestOptions, env?: NodeJS.ProcessEnv) => Promise<ApiResponse>;
+}
+export declare function resolveSymbolsHelpData(): {
+    readonly name: string;
+    readonly usage: string[];
+    readonly notes: string[];
+};
+export declare function executeResolveSymbols(args: ResolveSymbolsRunArgs, flags: ResolveSymbolsCliFlags, env?: NodeJS.ProcessEnv, deps?: ResolveSymbolsRunDeps): Promise<ResolveSymbolsSuccess>;
+export declare function cmdResolveSymbols(args: string[], flags: ResolveSymbolsCliFlags, env?: NodeJS.ProcessEnv, deps?: ResolveSymbolsRunDeps): Promise<number>;