@mostlyrightmd/core 1.1.3 → 1.4.0

package/dist/discovery/index.d.cts

@@ -234,7 +234,7 @@ interface BuildSnapshotOptions {
  */
 declare function buildSnapshot(opts: BuildSnapshotOptions): DataSnapshot;
 
-interface TradewindsErrorOptions {
+interface MostlyRightErrorOptions {
     errorCode?: string;
     source?: string | null;
     requestId?: string | null;
@@ -247,13 +247,13 @@ interface TradewindsErrorOptions {
  * involved (e.g. "iem.archive") when applicable, and `requestId` correlates a
  * JSON-RPC / MCP request id when applicable.
  */
-declare class TradewindsError extends Error {
+declare class MostlyRightError extends Error {
     /** Subclass override — the stable string enum surfaced via `errorCode`. */
     static defaultErrorCode: string;
     readonly errorCode: string;
     readonly source: string | null;
     readonly requestId: string | null;
-    constructor(message?: string, options?: TradewindsErrorOptions);
+    constructor(message?: string, options?: MostlyRightErrorOptions);
     /**
      * Subclass hook returning the structured attributes for `toDict`.
      * Values are passed through `toJsonSafe` by `toDict()`, so subclasses
@@ -263,6 +263,20 @@ declare class TradewindsError extends Error {
     /** Return a JSON-safe dict suitable for MCP `error.data`. */
     toDict(): Record<string, unknown>;
 }
+/** Shared reason enum — MUST match Python EXACTLY (Phase 21 D-04). */
+declare const DATA_AVAILABILITY_REASONS: readonly ["model_unavailable", "out_of_window", "cache_miss", "source_404", "source_5xx", "rate_limited"];
+type DataAvailabilityReason = (typeof DATA_AVAILABILITY_REASONS)[number];
+interface DataAvailabilityErrorOptions extends MostlyRightErrorOptions {
+    reason: DataAvailabilityReason;
+    hint: string;
+}
+declare class DataAvailabilityError extends MostlyRightError {
+    static defaultErrorCode: string;
+    readonly reason: DataAvailabilityReason;
+    readonly hint: string;
+    constructor(options: DataAvailabilityErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
 
 interface SchemaInfo {
     readonly id: string;
@@ -283,12 +297,12 @@ declare function registerSchema(info: SchemaInfo): void;
 /**
  * Return a multi-line description of a registered schema.
  *
- * @throws TradewindsError if `schemaId` is not registered. The error code is
+ * @throws MostlyRightError if `schemaId` is not registered. The error code is
  *   `UNKNOWN_SCHEMA` so callers can distinguish from validation/IO errors.
  */
 declare function describe(schemaId: string): string;
 /** Thrown by `describe` when `schemaId` is not registered. */
-declare class UnknownSchemaError extends TradewindsError {
+declare class UnknownSchemaError extends MostlyRightError {
     constructor(message: string);
     static readonly defaultErrorCode = "UNKNOWN_SCHEMA";
 }
@@ -299,15 +313,29 @@ declare class UnknownSchemaError extends TradewindsError {
  * snake_case names, here the camelCase TS names sorted identically.
  */
 declare function featureCatalog(): ReadonlyArray<string>;
+
 /**
- * Climate-gap scanning is Python-only in v0.1.0 (TS has no climate-year
- * parquet cache yet). Throws to match the documented contract.
+ * Climate-gap scanning — TS v1.x deferral.
+ *
+ * Phase 21 21-11 messaging upgrade: raises DataAvailabilityError with a
+ * multi-paragraph hint explaining the architectural constraint (GHCNh
+ * CSVs are 10+ MB per station-year; browser cache layer doesn't scale).
+ *
+ * @throws DataAvailabilityError with reason="model_unavailable" and a
+ *   hint pointing at the Python SDK as the supported v1.x workaround.
  */
 declare function climateGaps(_station: string, _fromDate: string, _toDate: string): never;
-/** Thrown by `climateGaps` until the TS climate cache lands. */
-declare class ClimateGapsNotImplementedError extends TradewindsError {
-    constructor(message: string);
-    static readonly defaultErrorCode = "NOT_IMPLEMENTED";
+/**
+ * Back-compat subclass of DataAvailabilityError raised by `climateGaps`
+ * in v1.x. Existing `catch (e instanceof ClimateGapsNotImplementedError)`
+ * sites keep working; new code should catch the parent class
+ * `DataAvailabilityError` and dispatch on `reason === "model_unavailable"`.
+ *
+ * @deprecated Prefer catching `DataAvailabilityError` directly.
+ */
+declare class ClimateGapsNotImplementedError extends DataAvailabilityError {
+    static readonly defaultErrorCode = "DATA_AVAILABILITY";
+    constructor();
 }
 
 export { type AvailabilityOptions, type AvailabilityResult, type BuildSnapshotOptions, ClimateGapsNotImplementedError, type DailyExtreme, type DataSnapshot, type DataVersion, type DataVersionComponents, type InternationalDailyExtremesOptions, type InternationalRow, type KeyEnumerableStore, UnknownSchemaError, availability, buildSnapshot, climateGaps, dataVersionForResearch, dataVersionFromComponents, describe, featureCatalog, internationalDailyExtremes, registerSchema };

package/dist/discovery/index.d.ts

@@ -234,7 +234,7 @@ interface BuildSnapshotOptions {
  */
 declare function buildSnapshot(opts: BuildSnapshotOptions): DataSnapshot;
 
-interface TradewindsErrorOptions {
+interface MostlyRightErrorOptions {
     errorCode?: string;
     source?: string | null;
     requestId?: string | null;
@@ -247,13 +247,13 @@ interface TradewindsErrorOptions {
  * involved (e.g. "iem.archive") when applicable, and `requestId` correlates a
  * JSON-RPC / MCP request id when applicable.
  */
-declare class TradewindsError extends Error {
+declare class MostlyRightError extends Error {
     /** Subclass override — the stable string enum surfaced via `errorCode`. */
     static defaultErrorCode: string;
     readonly errorCode: string;
     readonly source: string | null;
     readonly requestId: string | null;
-    constructor(message?: string, options?: TradewindsErrorOptions);
+    constructor(message?: string, options?: MostlyRightErrorOptions);
     /**
      * Subclass hook returning the structured attributes for `toDict`.
      * Values are passed through `toJsonSafe` by `toDict()`, so subclasses
@@ -263,6 +263,20 @@ declare class TradewindsError extends Error {
     /** Return a JSON-safe dict suitable for MCP `error.data`. */
     toDict(): Record<string, unknown>;
 }
+/** Shared reason enum — MUST match Python EXACTLY (Phase 21 D-04). */
+declare const DATA_AVAILABILITY_REASONS: readonly ["model_unavailable", "out_of_window", "cache_miss", "source_404", "source_5xx", "rate_limited"];
+type DataAvailabilityReason = (typeof DATA_AVAILABILITY_REASONS)[number];
+interface DataAvailabilityErrorOptions extends MostlyRightErrorOptions {
+    reason: DataAvailabilityReason;
+    hint: string;
+}
+declare class DataAvailabilityError extends MostlyRightError {
+    static defaultErrorCode: string;
+    readonly reason: DataAvailabilityReason;
+    readonly hint: string;
+    constructor(options: DataAvailabilityErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
 
 interface SchemaInfo {
     readonly id: string;
@@ -283,12 +297,12 @@ declare function registerSchema(info: SchemaInfo): void;
 /**
  * Return a multi-line description of a registered schema.
  *
- * @throws TradewindsError if `schemaId` is not registered. The error code is
+ * @throws MostlyRightError if `schemaId` is not registered. The error code is
  *   `UNKNOWN_SCHEMA` so callers can distinguish from validation/IO errors.
  */
 declare function describe(schemaId: string): string;
 /** Thrown by `describe` when `schemaId` is not registered. */
-declare class UnknownSchemaError extends TradewindsError {
+declare class UnknownSchemaError extends MostlyRightError {
     constructor(message: string);
     static readonly defaultErrorCode = "UNKNOWN_SCHEMA";
 }
@@ -299,15 +313,29 @@ declare class UnknownSchemaError extends TradewindsError {
  * snake_case names, here the camelCase TS names sorted identically.
  */
 declare function featureCatalog(): ReadonlyArray<string>;
+
 /**
- * Climate-gap scanning is Python-only in v0.1.0 (TS has no climate-year
- * parquet cache yet). Throws to match the documented contract.
+ * Climate-gap scanning — TS v1.x deferral.
+ *
+ * Phase 21 21-11 messaging upgrade: raises DataAvailabilityError with a
+ * multi-paragraph hint explaining the architectural constraint (GHCNh
+ * CSVs are 10+ MB per station-year; browser cache layer doesn't scale).
+ *
+ * @throws DataAvailabilityError with reason="model_unavailable" and a
+ *   hint pointing at the Python SDK as the supported v1.x workaround.
  */
 declare function climateGaps(_station: string, _fromDate: string, _toDate: string): never;
-/** Thrown by `climateGaps` until the TS climate cache lands. */
-declare class ClimateGapsNotImplementedError extends TradewindsError {
-    constructor(message: string);
-    static readonly defaultErrorCode = "NOT_IMPLEMENTED";
+/**
+ * Back-compat subclass of DataAvailabilityError raised by `climateGaps`
+ * in v1.x. Existing `catch (e instanceof ClimateGapsNotImplementedError)`
+ * sites keep working; new code should catch the parent class
+ * `DataAvailabilityError` and dispatch on `reason === "model_unavailable"`.
+ *
+ * @deprecated Prefer catching `DataAvailabilityError` directly.
+ */
+declare class ClimateGapsNotImplementedError extends DataAvailabilityError {
+    static readonly defaultErrorCode = "DATA_AVAILABILITY";
+    constructor();
 }
 
 export { type AvailabilityOptions, type AvailabilityResult, type BuildSnapshotOptions, ClimateGapsNotImplementedError, type DailyExtreme, type DataSnapshot, type DataVersion, type DataVersionComponents, type InternationalDailyExtremesOptions, type InternationalRow, type KeyEnumerableStore, UnknownSchemaError, availability, buildSnapshot, climateGaps, dataVersionForResearch, dataVersionFromComponents, describe, featureCatalog, internationalDailyExtremes, registerSchema };