Skip to content
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ npx skills add longbridge/developers -g -y
### Critical Rules

1. **LongBridge CLI is user-installed** — NEVER bundle it in the app
2. **Symbol validation** — Validate with `/^[A-Z0-9]{1,5}\.(US|HK|SG|SH|SZ|HAS)$/` before exec
2. **Symbol validation** — Validate with `/^[A-Z0-9]{1,6}\.(US|HK|SG|SH|SZ|HAS)$/` before exec. The body is 1–6 characters: A-share codes such as `600519.SH` are 6 digits, so a 5-character limit rejects valid listings.
3. **Use execa array params** — Never string concatenation for commands
4. **Session isolation** — Use `atomFamily` for per-session state

Expand Down
2 changes: 2 additions & 0 deletions docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ Complete reference for all LongBridge CLI commands used by Finance Agent.
| Indices | `.US` | `.VIX.US`, `.SPX.US` | Start with `.` |
| Crypto | `.HAS` | `BTCUSD.HAS` | LongBridge crypto suffix |

The code before the suffix is 1–6 letters or digits. Shanghai and Shenzhen listings use 6-digit codes (`600519.SH`); a 5-character limit rejects them. Codes longer than 6 characters (`6005191.SH`, `TOOLONG.US`) are not valid Folio symbols.

---

## Market Data Commands
Expand Down
2 changes: 1 addition & 1 deletion packages/longbridge-tools/src/validator.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { LongBridgeError } from './errors.ts';

// Symbol format: AAPL.US, 0700.HK, 600519.SH, 0388.HK, etc.
// Allow 1-5 chars of A-Z and 0-9
// 1–6 characters. A-share listings are 6 digits; a 5-character limit rejects them.
const SYMBOL_REGEX = /^[A-Z0-9]{1,6}\.(US|HK|SG|SH|SZ|HAS)$/;

export function validateSymbol(symbol: string): boolean {
Expand Down
107 changes: 107 additions & 0 deletions packages/shared/src/portfolio-import/parsers.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,24 @@ describe('checkSymbol', () => {
it('rejects unknown market suffixes', () => {
expect(checkSymbol('AAPL.XX').ambiguous).toBe(true)
})

it('does not treat over-long codes as canonical symbols', () => {
for (const symbol of ['6005191.SH', 'TOOLONG.US', 'DELISTED.US']) {
const check = checkSymbol(symbol)
expect(check.ambiguous).toBe(true)
expect(check.issue).toContain('not a recognized ticker')
}
const bare = checkSymbol('6005191')
expect(bare.ambiguous).toBe(true)
expect(bare.issue).toContain('not a recognized ticker')
expect(bare.issue).not.toContain('6005191.US')
})

it('still hints a market suffix for a 6-character bare ticker', () => {
const check = checkSymbol('600519')
expect(check.ambiguous).toBe(true)
expect(check.issue).toContain('600519.US')
})
})

describe('toFiniteNumber', () => {
Expand Down Expand Up @@ -79,6 +97,43 @@ describe('toFiniteNumber', () => {
expect(toFiniteNumber(' 1,234.56 ')).toBe(1234.56)
})

it('reads HK$, US$, yuan, and ISO currency glued onto the number', () => {
expect(toFiniteNumber('HK$1,234.50')).toBe(1234.5)
expect(toFiniteNumber('hk$180.5')).toBe(180.5)
expect(toFiniteNumber('US$180.50')).toBe(180.5)
expect(toFiniteNumber('¥180.5')).toBe(180.5)
expect(toFiniteNumber('¥1,600')).toBe(1600)
expect(toFiniteNumber('CN¥180')).toBe(180)
expect(toFiniteNumber('RMB 180.5')).toBe(180.5)
expect(toFiniteNumber('180.50 USD')).toBe(180.5)
expect(toFiniteNumber('320 HKD')).toBe(320)
expect(toFiniteNumber('-HK$12.5')).toBe(-12.5)
expect(toFiniteNumber('-$0.00')).toBe(0)
expect(toFiniteNumber('USD')).toBeUndefined()
expect(toFiniteNumber('HK$')).toBeUndefined()
})

it('reads accounting parentheses and a trailing minus as negative amounts', () => {
expect(toFiniteNumber('(180.50)')).toBe(-180.5)
expect(toFiniteNumber('($1,234.56)')).toBe(-1234.56)
expect(toFiniteNumber('(HK$12.5)')).toBe(-12.5)
expect(toFiniteNumber('(¥180.5)')).toBe(-180.5)
expect(toFiniteNumber('1,234.56-')).toBe(-1234.56)
expect(toFiniteNumber('($0.00)')).toBe(0)
expect(toFiniteNumber('()')).toBeUndefined()
expect(toFiniteNumber('($)')).toBeUndefined()
expect(toFiniteNumber('-45.2')).toBe(-45.2)
})

it('folds fullwidth digits and separators before parsing', () => {
expect(toFiniteNumber('1,234.56')).toBe(1234.56)
expect(toFiniteNumber('$180.50')).toBe(180.5)
expect(toFiniteNumber('¥180')).toBe(180)
expect(toFiniteNumber('(180.50)')).toBe(-180.5)
expect(toFiniteNumber('-45.2')).toBe(-45.2)
expect(toFiniteNumber(',,,')).toBeUndefined()
})

it('does not coerce a trailing percent into a number', () => {
for (const value of ['100%', '12.5%', '-3.25%', '0%', '1,000%', ' 100 % ', '$12.5%']) {
expect(toFiniteNumber(value)).toBeUndefined()
Expand Down Expand Up @@ -152,6 +207,32 @@ describe('parseCsv', () => {
expect(mapped).toMatchObject({ symbol: 'AAPL.US', quantity: 1000, costPrice: 180.5, issues: [] })
})

it('ignores zero-width characters glued to headers and numbers', () => {
const rows = parseCsv('\u200BSymbol,Quantity,Cost\nAAPL.US,1\u200B000,180.5')
expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 1000, costPrice: 180.5, confidence: 1, issues: [] })
const wordJoiner = parseCsv('\u2060代码,数量,成本\n0700.HK,500,320')
expect(wordJoiner[0]).toMatchObject({ symbol: '0700.HK', quantity: 500, costPrice: 320, confidence: 1, issues: [] })
expect(toFiniteNumber('1\u200B,000')).toBe(1000)
expect(toFiniteNumber('\u200B')).toBeUndefined()
})

it('parses fullwidth quantity and cost cells', () => {
const [row] = parseCsv('代码,数量,成本\n600519.SH,10,1,600.50')
expect(row).toMatchObject({ symbol: '600519.SH', quantity: 10, costPrice: 1600.5, confidence: 1, issues: [] })
})

it('parses parenthesized cost cells as negative amounts', () => {
const [row] = parseCsv('Symbol,Quantity,Cost\nAAPL.US,(100),"(HK$1,234.50)"')
expect(row).toMatchObject({ symbol: 'AAPL.US', quantity: -100, costPrice: -1234.5, confidence: 1, issues: [] })
})

it('parses currency-prefixed cost cells from a brokerage CSV', () => {
const rows = parseCsv('Symbol,Quantity,Cost,Currency\nAAPL.US,"1,000","US$180.50",USD\n0700.HK,500,HK$320,HKD\n600519.SH,10,¥1600,CNY')
expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 1000, costPrice: 180.5, currency: 'USD', confidence: 1, issues: [] })
expect(rows[1]).toMatchObject({ symbol: '0700.HK', quantity: 500, costPrice: 320, currency: 'HKD' })
expect(rows[2]).toMatchObject({ symbol: '600519.SH', quantity: 10, costPrice: 1600, currency: 'CNY' })
})

it('flags 100% and 12.5% quantity and cost for confirmation instead of booking them', () => {
const [both] = parseCsv('Symbol,Quantity,Cost\nAAPL.US,100%,12.5%')
expect(both.quantity).toBeUndefined()
Expand Down Expand Up @@ -274,6 +355,24 @@ describe('parseCsv', () => {
expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5 })
})

it('keeps Price as a cost fallback only when no specific cost column exists', () => {
const rows = parseCsv('Symbol,Price,Shares\nAAPL.US,180.5,100')
expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5, confidence: 1, issues: [] })
})

it('uses the specific cost column when an earlier Price column is also present', () => {
const rows = parseCsv('Symbol,Price,Cost,Qty\nAAPL.US,190.25,180.5,100\n0700.HK,330,320,500')
expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5, confidence: 1, issues: [] })
expect(rows[1]).toMatchObject({ symbol: '0700.HK', quantity: 500, costPrice: 320 })
})

it('prefers Avg Cost and 成本 over a generic price column', () => {
const english = parseCsv('Ticker,Price,Avg Cost,Shares\nAAPL.US,190.25,180.5,100')
expect(english[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5 })
const chinese = parseCsv('代码,价格,成本,数量\n600519.SH,1700,1600,10')
expect(chinese[0]).toMatchObject({ symbol: '600519.SH', quantity: 10, costPrice: 1600, confidence: 1, issues: [] })
})

it('supports an explicit headerMapping override', () => {
const rows = parseCsv('Ticker,Avg Cost,Units\nAAPL.US,180.5,100', { symbol: 'Ticker', cost: 'Avg Cost', quantity: 'Units' })
expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5 })
Expand Down Expand Up @@ -313,6 +412,14 @@ describe('parseCsv', () => {
expect(parseCsv('\n\n')).toEqual([])
})

it('keeps an over-long symbol for review instead of importing it as clean', () => {
const [row] = parseCsv('Symbol,Quantity,Cost\nTOOLONG.US,100,180.5\n600519.SH,10,1600')
expect(row.confidence).toBe(0.3)
expect(row.issues.some((issue) => issue.includes('not a recognized ticker'))).toBe(true)
const valid = parseCsv('Symbol,Quantity,Cost\n600519.SH,10,1600')[0]
expect(valid).toMatchObject({ symbol: '600519.SH', quantity: 10, costPrice: 1600, confidence: 1, issues: [] })
})

it('keeps a row when a required column is missing (review required)', () => {
const rows = parseCsv('Symbol,Cost\nAAPL.US,180.5')
expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', costPrice: 180.5 })
Expand Down
108 changes: 96 additions & 12 deletions packages/shared/src/portfolio-import/parsers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,15 @@
*/
import type { ImportSource, PortfolioImportRow } from '@finagent/core'

/** Canonical symbol: 1–8 alphanumerics plus a known market suffix. */
export const SYMBOL_RE = /^[A-Z0-9]{1,8}\.(US|HK|SG|SH|SZ|HAS)$/
/**
* Canonical symbol: 1–6 alphanumerics plus a known market suffix.
* Matches `symbolSchema` / Longbridge validation. A-share codes are 6 digits;
* 7–8 character bodies are not canonical and must not import as clean rows.
*/
export const SYMBOL_RE = /^[A-Z0-9]{1,6}\.(US|HK|SG|SH|SZ|HAS)$/

/** Bare ticker with no market suffix — usable, but ambiguous (review). */
export const BARE_TICKER_RE = /^[A-Z0-9]{1,8}$/
export const BARE_TICKER_RE = /^[A-Z0-9]{1,6}$/

/**
* A plain decimal with one trailing `%`, after thousands separators, `$`, and
Expand Down Expand Up @@ -42,18 +46,24 @@ export const HEADER_ALIASES: Record<HeaderField, readonly string[]> = {
symbol: ['symbol', 'ticker', 'code', 'stock', '代码', '股票代码', '证券代码'],
name: ['name', 'company', 'stockname', '名称', '股票名称', '证券名称'],
quantity: ['quantity', 'qty', 'shares', '数量', '持股数量', '股数', '持仓数量'],
// Specific cost headers come first. `price` / `价格` are fallbacks only:
// a leftmost "Price" column must not steal the value when "Cost" or
// "Avg Cost" is also present.
cost: [
'cost',
'costprice',
'cost price',
'price',
'avgcost',
'avg cost',
'averagecost',
'average cost',
'成本',
'成本价',
'买入价',
'持仓成本',
'均价',
'价格',
'price',
],
currency: ['currency', 'ccy', '货币', '币种'],
account: ['account', '账户', '账号', '组合'],
Expand Down Expand Up @@ -99,11 +109,60 @@ export function checkSymbol(raw: string): SymbolCheck {
}
}

/** Map fullwidth digits and separators onto the ASCII forms `Number` understands. */
function foldNumericWidth(value: string): string {
return value
.replace(/[0-9]/g, (digit) => String.fromCharCode(digit.charCodeAt(0) - 0xfee0))
.replace(/./g, '.')
.replace(/,/g, ',')
.replace(/[-−]/g, '-')
.replace(/$/g, '$')
}

/**
* Accounting exports write negatives as `(180.50)` or `180.50-`.
* Fullwidth parentheses are accepted. A normal leading minus is left for
* the numeric parse.
*/
function takeAccountingSign(value: string): { text: string; negative: boolean } {
let text = value.trim()
let negative = false
const wrapped = /^(?:\(|()\s*(.*?)\s*(?:\)|))$/.exec(text)
if (wrapped) {
negative = true
text = wrapped[1].trim()
}
if (text.endsWith('-') && !/^[+-]/.test(text)) {
negative = true
text = text.slice(0, -1).trim()
}
return { text, negative }
}

/**
* Drop currency markers brokerage exports glue onto a number.
* `HK$1,234.50`, `US$180`, `¥180.5`, `180.50 USD` all reduce to the digits.
* A leading sign is preserved (`-HK$12` stays negative).
*/
function stripCurrencyAffixes(value: string): string {
let text = value.trim()
const sign = text.startsWith('-') || text.startsWith('+') ? text[0] : ''
if (sign !== '') text = text.slice(1).trim()
text = text.replace(/^(?:HK|US|S|A|C)\s*\$\s*/i, '')
text = text.replace(/^(?:CN|RMB)\s*[¥¥]\s*/i, '')
text = text.replace(/^(?:RMB|CNY|USD|HKD|SGD|EUR|GBP|AUD|CAD)\s*/i, '')
text = text.replace(/^[¥¥€£$]\s*/, '')
text = text.replace(/\s*(?:RMB|CNY|USD|HKD|SGD|EUR|GBP|AUD|CAD)\s*$/i, '')
text = text.replace(/\s*[$¥¥€£]\s*$/, '')
return `${sign}${text.trim()}`
}

/**
* Coerce a CSV/paste cell to a finite number. Strings with thousands
* separators or a leading `$` are handled. A trailing `%` is not stripped:
* `100%` and `12.5%` stay non-numeric so they cannot be booked as 100 / 12.5.
* Empty/null/non-numeric → undefined.
* separators, currency affixes (`$`, `HK$`, `US$`, `¥`, `USD`), full-width
* digits or accounting negatives (`(180.50)`, `180.50-`) are handled.
* A trailing `%` is not stripped: `100%` and `12.5%` stay non-numeric so
* they cannot be booked as 100 / 12.5. Empty/null/non-numeric → undefined.
*/
export function toFiniteNumber(value: unknown): number | undefined {
if (typeof value === 'number') {
Expand All @@ -112,13 +171,17 @@ export function toFiniteNumber(value: unknown): number | undefined {
if (typeof value !== 'string') {
return undefined
}
const cleaned = stripNumericDecorations(value)
const accounting = takeAccountingSign(foldNumericWidth(stripInvisible(value)))
const trimmed = stripCurrencyAffixes(accounting.text)
const cleaned = stripNumericDecorations(trimmed)
// Number('') is zero, but formatting alone does not supply a numeric value.
if (cleaned === '') {
if (cleaned === '' || cleaned === '+' || cleaned === '-') {
return undefined
}
const parsed = Number(cleaned)
return Number.isFinite(parsed) ? parsed : undefined
if (!Number.isFinite(parsed)) return undefined
if (parsed === 0) return 0
return accounting.negative ? -Math.abs(parsed) : parsed
}

// ── CSV ────────────────────────────────────────────────────────────────────
Expand Down Expand Up @@ -188,8 +251,29 @@ export function splitCsvLine(line: string, delimiter: CsvDelimiter = csvDelimite
return cells
}

/** Characters `trim` does not remove, but spreadsheets and web paste often insert. */
const INVISIBLE_CHARS = /[\uFEFF\u200B\u200C\u200D\u2060]/g

function stripInvisible(value: string): string {
return value.replace(INVISIBLE_CHARS, '')
}

function normalizeHeaderCell(cell: string): string {
return cell.trim().toLowerCase().replace(/[\s_\-]/g, '')
return stripInvisible(cell).trim().toLowerCase().replace(/[\s_\-]/g, '')
}

/**
* Pick a column by alias specificity, not by leftmost match.
* The first alias that appears anywhere in the row wins, so a generic
* fallback such as `price` does not override an earlier specific header
* that happens to sit further right.
*/
function columnForAliases(cells: readonly string[], aliases: readonly string[]): number {
for (const alias of aliases) {
const index = cells.indexOf(normalizeHeaderCell(alias))
if (index >= 0) return index
}
return -1
}

/** Field → resolved column index for one CSV file. */
Expand Down Expand Up @@ -221,7 +305,7 @@ export function resolveCsvColumns(
found = cells.indexOf(normalizeHeaderCell(explicit))
}
if (found === -1) {
found = cells.findIndex((cell) => HEADER_ALIASES[field].some((alias) => normalizeHeaderCell(alias) === cell))
found = columnForAliases(cells, HEADER_ALIASES[field])
}
if (found >= 0) byIndex.set(found, field)
}
Expand Down