gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/futures-curve/client.ts

@@ -1,10 +1,12 @@
+import { logFailure } from "../../../utils/log-failure";
 import { apiClient } from "../../../api-client";
 import type { FuturesCurvePayload } from "../../../api-client/futures-curve";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { isFuturesContractSpec } from "../../../market-data/futures-contract";
 import { loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
-import type { DataProvider } from "../../../types/data-provider";
-import { archivedFuturesCurve, curveLookbackDate, curveSpot, normalizeCurveRoot, unsupportedCurveRootMessage, withTradedExpirations, type CurveSpot } from "./model";
+import type { AssetDataProvider, DataProvider } from "../../../types/data-provider";
+import type { TimeRange } from "../../../time-series/range";
+import { archivedFuturesCurve, curveLookbackDate, curveSpot, normalizeCurveRoot, spotBarsFromHistory, unsupportedCurveRootMessage, withSettleChanges, withTradedExpirations, type CurveSpot, type SpotBar } from "./model";
 
 export const futuresCurveCache = createPluginCache<FuturesCurvePayload>({
   kind: "futures-curve", source: "gloom-cloud", schemaVersion: 1,
@@ -53,26 +55,31 @@ export function validateFuturesCurve(data: FuturesCurvePayload, root: string): F
   const slope = data.slope;
   if (![slope.value, slope.annualizedRollYield].every(finiteOrNull)
     || ![slope.percentile, slope.rollPercentile].every(rank) || !Number.isInteger(slope.samples) || slope.samples < 0
-    || slope.asOf !== null && !timestamp(slope.asOf)) throw new Error("The server returned an invalid futures spread");
+    || slope.asOf !== null && !timestamp(slope.asOf)
+    || slope.basis != null && slope.basis !== "last" && slope.basis !== "settle"
+    || slope.thinSymbol != null && typeof slope.thinSymbol !== "string") throw new Error("The server returned an invalid futures spread");
   return data;
 }
 
+/** A live curve as every reader takes it: expiring on last trading days, its changes against the settlement shown. */
+const liveCurve = (data: FuturesCurvePayload) => withSettleChanges(withTradedExpirations(data));
+
 export async function fetchFuturesCurve(root: string, client: Pick<typeof apiClient, "getCloudFuturesCurve"> = apiClient): Promise<FuturesCurvePayload> {
   const normalized = normalizeCurveRoot(root);
   if (!normalized) throw new Error(unsupportedCurveRootMessage(root));
-  try { return withTradedExpirations(validateFuturesCurve(await client.getCloudFuturesCurve(normalized), normalized)); }
+  try { return liveCurve(validateFuturesCurve(await client.getCloudFuturesCurve(normalized), normalized)); }
   catch (error) { throw unavailableOnServer(error, "Futures curves are not available yet."); }
 }
 
 export function getCachedFuturesCurve(root: string): FuturesCurvePayload | null {
   const cached = futuresCurveCache.get(root, { allowExpired: true });
   // The pane revalidates this copy on mount; only the source or a failed refresh makes it stale.
-  return cached?.data ? withTradedExpirations(cached.data) : null;
+  return cached?.data ? liveCurve(cached.data) : null;
 }
 
 export async function loadFuturesCurve(root: string, force = false): Promise<FuturesCurvePayload> {
   const { payload, stale, refreshError } = await loadCloudResource(futuresCurveCache, root, () => fetchFuturesCurve(root), { force });
-  return { ...withTradedExpirations(payload), stale: stale || payload.stale, gaps: [...payload.gaps, ...(refreshError ? [refreshError] : [])] };
+  return { ...liveCurve(payload), stale: stale || payload.stale, gaps: [...payload.gaps, ...(refreshError ? [refreshError] : [])] };
 }
 
 /** The archived curve on a past date with the curves a week and a month before it. */
@@ -83,8 +90,8 @@ export async function loadFuturesCurveAsOf(root: string, date: string,
   try {
     const [curve, week, month] = await Promise.all([
       client.getCloudFuturesCurveAsOf(normalized, date),
-      client.getCloudFuturesCurveAsOf(normalized, curveLookbackDate(date, 7)).catch(() => null),
-      client.getCloudFuturesCurveAsOf(normalized, curveLookbackDate(date, 30)).catch(() => null),
+      client.getCloudFuturesCurveAsOf(normalized, curveLookbackDate(date, 7)).catch(logFailure("futures-curve.client", "Load week comparison curve failed", null)),
+      client.getCloudFuturesCurveAsOf(normalized, curveLookbackDate(date, 30)).catch(logFailure("futures-curve.client", "Load month comparison curve failed", null)),
     ]);
     if (!curve || curve.root !== normalized || !Array.isArray(curve.contracts) || !Array.isArray(curve.gaps)
       || curve.contracts.some((row) => !row || typeof row.symbol !== "string" || !Number.isFinite(row.price)
@@ -101,5 +108,29 @@ export async function loadFuturesCurveAsOf(root: string, date: string,
  * A failed read is a missing spot, never a failed report: the curve stands without its basis.
  */
 export async function loadCurveSpot(symbol: string, provider: Pick<DataProvider, "getQuote">, now = Date.now()): Promise<CurveSpot> {
-  return curveSpot(symbol, await provider.getQuote(symbol, "").catch(() => null), now);
+  return curveSpot(symbol, await provider.getQuote(symbol, "").catch(logFailure("futures-curve.client", "Load curve spot quote failed", null)), now);
+}
+
+/** The last day of one-minute bars: the reach of a curve's trades a basis is read for, the far months' older ones aside. */
+const SPOT_BAR_RANGE: TimeRange = "1D";
+
+/**
+ * The spot pair's one-minute bars over the last day, read through the same
+ * history path the charts use, which the basis pairs each trade with by
+ * minute. Bars of any other size pair nothing, and a failed read has none:
+ * the curve stands without its basis, each blank saying why.
+ */
+export async function loadCurveSpotBars(symbol: string,
+  provider: Pick<AssetDataProvider, "getPriceHistoryForResolutionWithMetadata" | "getPriceHistoryForResolution">, force = false): Promise<SpotBar[]> {
+  const context = force ? { cacheMode: "refresh" as const } : undefined;
+  try {
+    if (provider.getPriceHistoryForResolutionWithMetadata) {
+      const history = await provider.getPriceHistoryForResolutionWithMetadata(symbol, "", SPOT_BAR_RANGE, "1m", context);
+      return history.resolution && history.resolution !== "1m" ? [] : spotBarsFromHistory(history.points);
+    }
+    return provider.getPriceHistoryForResolution
+      ? spotBarsFromHistory(await provider.getPriceHistoryForResolution(symbol, "", SPOT_BAR_RANGE, "1m", context)) : [];
+  } catch (error) {
+    return logFailure("futures-curve.client", "Load curve spot bars failed", [] as SpotBar[])(error);
+  }
 }

package/src/plugins/builtin/futures-curve/headless.ts

@@ -4,8 +4,8 @@ import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneEntry, Hea
 import { formatPercentRaw } from "../../../utils/format";
 import { DATE_OPTION_EXAMPLES } from "../../../utils/calendar-date";
 import { newestReportTime, oldestReportTime } from "../../../utils/utc-time";
-import { fetchFuturesCurve, loadCurveSpot, loadFuturesCurveAsOf } from "./client";
-import { basisSpotSymbol, BASIS_CONVENTION, blankBasisNote, catalogueCurveUnit, curveAsOfDate, curveBasisPercent, curveBasisRows, curveChangeText, curveContractCode, curvePrice, curveRoundedPrice, curveSpotLabel, curveSpotSource, curveSpreadLabel, curveTimestamp, curveUnitLabel, normalizeCurveRoot, shortDatedBasisNote, thinContractCount, unsupportedCurveRootMessage, type ContractBasis } from "./model";
+import { fetchFuturesCurve, loadCurveSpot, loadCurveSpotBars, loadFuturesCurveAsOf } from "./client";
+import { basisSpotSymbol, BASIS_CONVENTION, blankBasisNote, catalogueCurveUnit, curveAsOfDate, curveBasisPercent, curveBasisRows, curveChangeText, curveContractCode, curvePrice, curveRoundedPrice, curveSpotSource, curveSpreadLabel, curveTimestamp, curveNoTradeSince, curveUnitLabel, noTradeChangeNote, normalizeCurveRoot, shortDatedBasisNote, thinSpreadNotice, unpairedContractCount, unsupportedCurveRootMessage, type ContractBasis } from "./model";
 import { COMMODITIES_VIEW_STATE } from "../commodities-energy/view-state";
 
 /** The root a report shows when none is given. */
@@ -22,6 +22,11 @@ const basisValue = (value: number | null) => value == null ? null : Number(value
  * every root. Prices and changes are at the root's tick precision. `price` is
  * the latest trade and `settlement` the exchange settlement for the curve's
  * settlement session (a past curve's settled rows have no separate trade).
+ * `change` is `price` less `settlement`; `noTradeSince` dates the settlement
+ * a contract has not traded since, whose change is therefore blank. A crypto
+ * root adds the basis: the spot in the minute of `price`'s trade and that
+ * minute (`spot`, `spotTime`), the fractional days from the trade to final
+ * settlement, and the premium and its yearly rate.
  */
 function contractRow(row: FuturesContract, data: FuturesCurvePayload, root: string, past: boolean, basis?: ContractBasis) {
   const price = (value: number | null | undefined) => curveRoundedPrice(value, root);
@@ -30,15 +35,21 @@ function contractRow(row: FuturesContract, data: FuturesCurvePayload, root: stri
     firstNotice: row.firstNotice ?? null, inDelivery: row.inDelivery ?? false,
     settlement: price(row.settlement), settlementDate: row.settlement != null ? data.settlementDate ?? null : null,
     price: past && row.settlement != null ? null : price(row.price), change: price(row.change),
+    noTradeSince: past ? null : curveNoTradeSince(row, data),
     asOf: row.asOf, stale: row.stale, volume: row.volume, openInterest: row.openInterest, percentile: rank(row.percentile),
     samples: row.samples, historyStart: row.historyStart, historyEnd: row.historyEnd,
     currency: row.currency, quoteUnit: curveUnitLabel(data) ?? row.quoteUnit, delayMinutes: row.delayMinutes,
-    ...(basis ? { vsSpotPct: basisValue(basis.vsSpotPct), annualisedBasisPct: basisValue(basis.annualisedBasisPct) } : {}),
+    ...(basis ? { spot: price(basis.spot), spotTime: basis.spotTime, daysToExpiry: basisValue(basis.daysToExpiry),
+      vsSpotPct: basisValue(basis.vsSpotPct), annualisedBasisPct: basisValue(basis.annualisedBasisPct) } : {}),
   };
 }
 
-/** The text table: what a hedge reads, in one order for every root; JSON keeps every field. */
-function contractColumns(root: string, settlementDate: string | null, options: { basis: boolean; last: boolean; notice: boolean }): HeadlessPaneColumn[] {
+/**
+ * The table: what a hedge reads, in one order for every root; JSON keeps every
+ * field. A crypto root's spot is the one each trade is read against; the
+ * export dates it, where the text leaves its minute to As Of UTC, the trade's.
+ */
+function contractColumns(root: string, settlementDate: string | null, options: { basis: boolean; last: boolean; notice: boolean; text?: boolean }): HeadlessPaneColumn[] {
   const price = (value: unknown) => typeof value === "number" ? curvePrice(value, root) : "--";
   const date = (value: unknown) => typeof value === "string" ? value : "--";
   return [
@@ -51,7 +62,10 @@ function contractColumns(root: string, settlementDate: string | null, options: {
     // A Cboe price is the settlement itself, with no separate last trade.
     ...options.last ? [{ key: "price", header: "Last", align: "right" as const, format: price }] : [],
     { key: "change", header: "Change", align: "right", format: (value) => typeof value === "number" ? curveChangeText(value, root) : "--" },
-    ...options.basis ? [{ key: "vsSpotPct", header: "Vs Spot", align: "right" as const, format: (value: unknown) => curveBasisPercent(typeof value === "number" ? value : null, 2) },
+    ...options.basis ? [{ key: "spot", header: "Spot", align: "right" as const, format: price },
+      ...options.text ? [] : [{ key: "spotTime", header: "Spot Time UTC", shrink: false, format: (value: unknown) => typeof value === "string" ? curveTimestamp(value) : "--" }],
+      { key: "vsSpotPct", header: "Vs Spot", align: "right" as const, format: (value: unknown) => curveBasisPercent(typeof value === "number" ? value : null, 2) },
+      { key: "daysToExpiry", header: "Days to Expiry", textHeader: "Days", align: "right" as const, format: (value: unknown) => typeof value === "number" ? value.toFixed(1) : "--" },
       { key: "annualisedBasisPct", header: "Ann Basis", align: "right" as const, format: (value: unknown) => curveBasisPercent(typeof value === "number" ? value : null, 1) }] : [],
     { key: "asOf", header: "As Of UTC", shrink: false, format: (value) => typeof value === "string" ? curveTimestamp(value) : "--" },
     { key: "openInterest", header: "Open Int", align: "right", format: (value) => typeof value === "number" ? value.toLocaleString("en-US") : "--" },
@@ -70,8 +84,9 @@ function fieldColumns(order: readonly string[], fields: object, formats: Record<
     .map((key) => ({ key, header: key, ...formats[key] ? { textFormat: formats[key] } : {} }));
 }
 
+// `basis` says which prices the value subtracts: two last trades made together, or the settlements of the session in `asOf`.
 const FRONT_SPREAD_FIELDS = ["label", "frontSymbol", "nextSymbol", "value", "annualizedRollYield", "percentile", "rollPercentile",
-  "samples", "historyStart", "historyEnd", "asOf", "state"];
+  "samples", "historyStart", "historyEnd", "asOf", "basis", "state", "thinSymbol"];
 const GHOST_FIELDS = ["symbol", "expiration", "price", "asOf"];
 /** The annualized roll yield reads as the percent it is (+32.36%); an export keeps the number. */
 const ROLL_YIELD_FORMAT = { annualizedRollYield: (value: unknown) => typeof value === "number" ? formatPercentRaw(value) : "--" };
@@ -93,7 +108,7 @@ function specEntries(data: FuturesCurvePayload): HeadlessPaneEntry[] {
 export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
   discovery: { aliases: ["CTM"], dataRequirements: ["Gloom Cloud futures curve endpoint"],
     limitations: ["Listed-contract catalogues can be incomplete.", "Ghosts and percentiles use the same listed contracts.", "Cboe VIX is daily settlement.",
-    "Ann Basis is simple actual/365 on the latest trade against the spot quote, and noisy under 30 days to expiry."],
+    "Ann Basis is simple actual/365, each last trade against spot in the same minute, and noisy under 7 days to expiry."],
     intents: ["futures basis trade", "cash and carry", "basis against spot"] },
   shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "root", description: "FUT root such as CL, ES, ZN or VX, or a CME crypto root (BTC, ETH, SOL, XRP). Defaults to ES." },
   // Only the pane reads the tab; the report always carries both.
@@ -106,23 +121,30 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
     const input = args.argument || DEFAULT_ROOT;
     const root = normalizeCurveRoot(input);
     if (!root) throw new Error(unsupportedCurveRootMessage(input));
-    const date = curveAsOfDate(args.options.date);
+    const date = curveAsOfDate(args.options.date, new Date(), "--date");
     // The archive keeps no spot history, so a past curve has no basis.
     const spotSymbol = date ? null : basisSpotSymbol(root);
     const now = Date.now();
-    const [data, spot] = await Promise.all([
+    // The quote names the spot and its feed; the one-minute bars price each trade's own minute.
+    const [data, spot, bars] = await Promise.all([
       date ? loadFuturesCurveAsOf(root, date, ctx.apiClient) : fetchFuturesCurve(root, ctx.apiClient),
       spotSymbol ? loadCurveSpot(spotSymbol, ctx.marketData, now) : null,
+      spotSymbol ? loadCurveSpotBars(spotSymbol, ctx.marketData, ctx.refresh === true) : null,
     ]);
-    const bases = spot ? curveBasisRows(data.contracts, spot) : null;
+    const bases = spot && bars ? curveBasisRows(data.contracts, bars) : null;
     const unit = curveUnitLabel(data);
     const terms = specEntries(data);
     const source = spot ? curveSpotSource(spot) : null;
     const notices = [...args.argument ? [] : [`Showing ${DEFAULT_ROOT}. Try fn CTM ${EXAMPLE_ROOT}.`],
-      ...spot ? [spot.status === "ok" ? `Basis against ${curveSpotLabel(spot, root, now)}${source ? ` (${source})` : ""}; not the CME reference rate.` : `Basis blank: ${spot.reason}.`] : []];
+      ...spot ? [`Basis against ${spot.symbol} spot in each last trade's own minute${source ? ` (${source})` : ""}; not the CME reference rate.`] : []];
     // The footnotes under the table: the convention, why a cell is blank, and where a short-dated rate is not to be trusted.
-    // Against a spot that is not usable every cell is blank for the spot's reason, which the notice above already gives.
-    const notes = spot && bases ? [BASIS_CONVENTION, ...spot.status === "ok" ? [blankBasisNote(data.contracts, bases), shortDatedBasisNote(data.contracts, bases, spot)].filter((note): note is string => !!note) : []] : [];
+    const basisNotes = bases ? [BASIS_CONVENTION, blankBasisNote(data.contracts, bases), shortDatedBasisNote(data.contracts, bases)]
+      .filter((note): note is string => !!note) : [];
+    // A blank Change says why, as a blank basis does; a past curve has no session change to blank.
+    const changeNote = date ? null : noTradeChangeNote(data.contracts, data);
+    const thinSpread = thinSpreadNotice(data);
+    const notes = [...thinSpread ? [`${thinSpread}.`] : [], ...changeNote ? [changeNote] : [], ...basisNotes];
+    const columnOptions = { basis: !!bases, last: data.source !== "cboe", notice: data.contracts.some((row) => row.firstNotice) };
     // Dated by the contracts' own quotes; the same-contract history rows are a year of context, not observations.
     const quoted = data.contracts.map((row) => row.asOf);
     const freshness: HeadlessPaneFreshness = date
@@ -132,8 +154,8 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
     return {
       freshness,
       sections: [
-        { title: "Contracts", columns: contractColumns(root, data.settlementDate ?? null,
-          { basis: !!spot, last: data.source !== "cboe", notice: data.contracts.some((row) => row.firstNotice) }),
+        { title: "Contracts", columns: contractColumns(root, data.settlementDate ?? null, columnOptions),
+          ...bases ? { textColumns: contractColumns(root, data.settlementDate ?? null, { ...columnOptions, text: true }) } : {},
           rows: data.contracts.map((row) => contractRow(row, data, root, !!date, bases?.get(row.symbol))) },
         { title: "Front spread", columns: fieldColumns(FRONT_SPREAD_FIELDS, data.slope, ROLL_YIELD_FORMAT), rows: [{ label: curveSpreadLabel(data.slope), ...data.slope, value: curveRoundedPrice(data.slope.value, root),
           annualizedRollYield: data.slope.annualizedRollYield == null ? null : Number(data.slope.annualizedRollYield.toFixed(2)),
@@ -144,7 +166,7 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
       ],
       errors: data.gaps,
       ...(notes.length ? { notes } : {}),
-      metadata: { ...data, quoteUnit: unit, ...(spot && bases ? { spot, basisBlankedThin: thinContractCount(bases.values()) } : {}), ...(args.argument ? {} : { defaultArgument: DEFAULT_ROOT }),
+      metadata: { ...data, quoteUnit: unit, ...(spot && bases ? { spot, basisBlankedUnpaired: unpairedContractCount(bases.values()) } : {}), ...(args.argument ? {} : { defaultArgument: DEFAULT_ROOT }),
         ...(notices.length ? { notices } : {}),
         complete: data.status === "available", percentileBasis: "Same-contract observations within one year; actual sample start/end retained" },
     };