@xbbg/core 1.1.2

package/README.md

@@ -0,0 +1,145 @@
+# @xbbg/core
+
+Bloomberg data API for Node.js — powered by Rust.
+
+## Status
+
+🚧 **Experimental alpha** — native N-API bindings are implemented, high-level API is in active development.
+
+## Install
+
+Supported prebuilt addon targets:
+- macOS arm64
+- Linux x64
+- Windows x64
+
+```bash
+bun add @xbbg/core
+# or
+npm install @xbbg/core
+```
+
+`@xbbg/core` loads a packaged native `napi_xbbg.node` addon via platform-specific optional dependencies on supported targets. If no packaged addon is available for your platform, build from source locally instead.
+
+## Local Development
+
+```bash
+# Preferred: build and copy js-xbbg/napi_xbbg.node into the package directory
+npm --prefix js-xbbg run build
+
+# Lower-level Rust build (useful while hacking on napi-xbbg itself)
+cargo build -p napi-xbbg
+
+# Stage the current platform package template with the built addon
+npm --prefix js-xbbg run stage:native-package
+
+# Run JS smoke test from js-xbbg/
+npm test
+```
+
+The JS package automatically loads a local `js-xbbg/napi_xbbg.node` addon first, then falls back to packaged optional native dependencies for supported platforms.
+
+## Planned Usage
+
+```typescript
+import * as xbbg from '@xbbg/core';
+
+xbbg.configure({
+  host: 'localhost',
+  port: 8194,
+});
+
+// BPIPE / leased-line capable session config
+const engine = await xbbg.connect({
+  servers: [
+    { host: 'bpipe-primary.example.com', port: 8194 },
+    { host: 'bpipe-secondary.example.com', port: 8196 },
+  ],
+  auth: { method: 'userapp', appName: 'my-bpipe-app' },
+  tls: {
+    clientCredentials: '/secure/client.p12',
+    clientCredentialsPassword: process.env.BPIPE_TLS_PASSWORD,
+    trustMaterial: '/secure/trust.p7',
+  },
+  zfpRemote: '8194',
+});
+
+// Python-style blp namespace
+const hist = await xbbg.blp.abdh(['AAPL US Equity'], ['PX_LAST'], '2024-01-01', '2024-12-31');
+const ref = await xbbg.blp.abdp(['AAPL US Equity'], ['PX_LAST', 'SECURITY_NAME']);
+const bulk = await xbbg.blp.abds(['ES1 Index'], ['FUT_CHAIN_LAST_TRADE_DATES']);
+const bars = await xbbg.blp.abdib('AAPL US Equity', '2024-12-01', 5);
+const ticks = await xbbg.blp.abdtick('AAPL US Equity', '2024-12-01T09:30:00', '2024-12-01T10:00:00');
+
+// Live streaming
+const sub = await xbbg.blp.asubscribe(['AAPL US Equity'], ['LAST_PRICE', 'BID', 'ASK']);
+for await (const tick of sub) {
+  console.log(tick);
+}
+
+// CDX analytics
+const cdxInfo = await xbbg.ext.cdx.acdx_info('CDX IG CDSI GEN 5Y Corp');
+const cdxPricing = await xbbg.ext.cdx.acdx_pricing('CDX IG CDSI GEN 5Y Corp');
+const cdxRisk = await xbbg.ext.cdx.acdx_risk('CDX IG CDSI GEN 5Y Corp');
+
+engine.signalShutdown();
+```
+
+## Recipes
+
+High-level workflows that wrap common Bloomberg request patterns. Each recipe returns an Arrow `Table` by default (or a JSON/Polars result when `backend` is set) and errors are mapped to the standard `BlpError` hierarchy.
+
+```javascript
+// Fixed income
+const yas = await engine.yas(['US912810TM69 Govt'], ['YAS_BOND_YLD'], {
+  settleDt: '20240115',
+  yieldType: 1, // 1=YTM, 2=YTC, 3=YTW, 4=YTB, 5=YTP, 6=YTN, 7=OAS, 8=YTS, 9=YTAL
+  price: 99.5,
+});
+const bqr = await engine.bqr('US912810TM69 Govt', {
+  startDatetime: '2024-06-03T14:30:00',
+  endDatetime: '2024-06-03T15:00:00',
+  eventTypes: ['BID', 'ASK'],
+});
+const preferreds = await engine.preferreds('BAC US Equity');
+const corpBonds = await engine.corporateBonds('AAPL', { ccy: 'USD' });
+
+// Futures and CDX resolution
+const front = await engine.futTicker('ES1 Index', '20240301');
+const active = await engine.activeFutures('CL1 Comdty', '20240301', { freq: 'M' });
+const cdx = await engine.cdxTicker('CDX IG CDSI GEN 5Y Corp', '20240301');
+const activeCdx = await engine.activeCdx('CDX IG CDSI GEN 5Y Corp', '20240301', {
+  lookbackDays: 10,
+});
+
+// Historical helpers
+const dvd = await engine.dividend(['AAPL US Equity'], '20230101', '20231231');
+const turn = await engine.turnover(['AAPL US Equity'], '20240101', '20240131', {
+  ccy: 'USD',
+});
+const holdings = await engine.etfHoldings('SPY US Equity');
+
+// Currency-converted prices
+const px = await engine.currencyConversion('700 HK Equity', 'USD', '20240101', '20240131');
+```
+
+## Engine configuration
+
+`connect()` and `configure()` accept a structured `EngineConfig` object. The most important connection controls are:
+
+- `host` / `port` for a single Bloomberg session endpoint
+- `servers` for ordered failover across multiple Bloomberg hosts
+- `auth` for Bloomberg session identity auth: `user`, `app`, `userapp`, `dir`, `manual`, or `token`
+- `tls` plus `zfpRemote` for leased-line / BPIPE-style sessions
+- `socks5` for proxied Bloomberg connectivity
+- `retryPolicy`, `numStartAttempts`, and recovery settings for reconnect behavior
+
+The JS binding now forwards these fields directly to the Rust engine, so Node can configure the same auth and transport features already available in the core runtime.
+
+## Features (planned)
+
+- Native N-API bindings (no HTTP overhead)
+- Zero-copy Arrow buffers via `apache-arrow`
+- Async/await with proper backpressure
+- TypeScript-first with full type definitions
+- Cross-platform prebuilt addon packaging: macOS arm64, Linux x64, Windows x64

package/errors.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * Base error class for all Bloomberg API errors.
+ * All xbbg errors inherit from BlpError, allowing users to catch all
+ * Bloomberg-related errors with a single except clause.
+ */
+class BlpError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+/**
+ * Session lifecycle errors (start, connect, service open).
+ */
+class BlpSessionError extends BlpError {}
+
+/**
+ * Request-level errors from the Bloomberg API.
+ * 
+ * Attributes:
+ *   service: The Bloomberg service URI (e.g., "//blp/refdata").
+ *   operation: The request operation name (e.g., "ReferenceDataRequest").
+ *   request_id: Optional correlation ID for debugging.
+ *   code: Optional Bloomberg error code.
+ */
+class BlpRequestError extends BlpError {
+  constructor(message, options = {}) {
+    super(message);
+    this.service = options.service;
+    this.operation = options.operation;
+    this.request_id = options.request_id;
+    this.code = options.code;
+  }
+}
+
+/**
+ * Request validation errors.
+ * 
+ * Raised when request parameters fail validation against Bloomberg schemas.
+ * Includes helpful suggestions for typos and invalid enum values.
+ * 
+ * Attributes:
+ *   element: The element name that caused the error (if available).
+ *   suggestion: Suggested correction for typos (if available).
+ */
+class BlpValidationError extends BlpError {
+  constructor(message, options = {}) {
+    super(message);
+    this.element = options.element;
+    this.suggestion = options.suggestion;
+  }
+}
+
+/**
+ * Request timeout.
+ */
+class BlpTimeoutError extends BlpError {}
+
+/**
+ * Internal errors (should not happen in normal operation).
+ * If you encounter this error, please report it as a bug.
+ */
+class BlpInternalError extends BlpError {}
+
+/**
+ * Wraps a native NAPI error into the appropriate xbbg error class.
+ * 
+ * Pattern-matches on error message to determine the error type.
+ * 
+ * @param {Error} napiError - The native NAPI error to wrap
+ * @returns {BlpError} - An instance of the appropriate error class
+ */
+function wrapError(napiError) {
+  const msg = napiError.message || '';
+
+  // Session errors
+  if (
+    msg.includes('Session start failed') ||
+    msg.includes('session start failed') ||
+    msg.includes('Failed to start session') ||
+    msg.includes('Failed to open service') ||
+    msg.includes('failed to spawn worker') ||
+    msg.includes('connect event failed')
+  ) {
+    return new BlpSessionError(msg);
+  }
+
+  // Request errors
+  if (msg.includes('Request failed') || msg.includes('Subscription failed')) {
+    const options = {};
+
+    // Parse service and operation from "Request failed on {service}::{op}"
+    const serviceOpMatch = msg.match(/on ([^:]+)::([^ (]+)/);
+    if (serviceOpMatch) {
+      options.service = serviceOpMatch[1];
+      options.operation = serviceOpMatch[2];
+    }
+
+    // Native messages append " [request_id=<uuid>]" when a correlation id is known.
+    const requestIdMatch = msg.match(/\[request_id=([^\]]+)\]/);
+    if (requestIdMatch) {
+      options.request_id = requestIdMatch[1];
+    }
+
+    return new BlpRequestError(msg, options);
+  }
+
+  // Validation errors
+  if (
+    msg.includes('Invalid argument') ||
+    msg.includes('Configuration error') ||
+    msg.includes('Operation not found') ||
+    msg.includes('Schema element not found') ||
+    msg.includes('Schema type mismatch') ||
+    msg.includes('Unsupported schema') ||
+    msg.includes('invalid extractor') ||
+    msg.includes('(did you mean') // Validation with suggestion
+  ) {
+    const options = {};
+    
+    // Parse suggestion from "(did you mean 'xxx'?)" pattern
+    const suggestionMatch = msg.match(/\(did you mean '([^']+)'\?\)/);
+    if (suggestionMatch) {
+      options.suggestion = suggestionMatch[1];
+    }
+    
+    return new BlpValidationError(msg, options);
+  }
+
+  // Timeout errors
+  if (msg.includes('Request timed out')) {
+    return new BlpTimeoutError(msg);
+  }
+
+  // Internal errors
+  if (
+    msg.includes('Internal error') ||
+    msg.includes('Channel closed') ||
+    msg.includes('Stream buffer full') ||
+    msg.includes('Request was cancelled')
+  ) {
+    return new BlpInternalError(msg);
+  }
+
+  // Default fallback
+  return new BlpError(msg);
+}
+
+module.exports = {
+  BlpError,
+  BlpSessionError,
+  BlpRequestError,
+  BlpValidationError,
+  BlpTimeoutError,
+  BlpInternalError,
+  wrapError,
+};