@uvrn/farm 3.0.0 → 4.0.0

package/README.md

@@ -71,6 +71,33 @@ const farm = new MultiFarm([
 
 `ConnectorRegistry` stores named connectors and can assemble a `MultiFarm` instance from all registered connectors or a named subset.
 
+## Rate limiting and circuit breaker
+
+Every `BaseConnector` request made through `requestJson()` (or the protected `withGuards()` helper) is guarded by an in-process rate limiter and a circuit breaker. Both are configured per connector instance via `ConnectorConfig`:
+
+| Option | Default | Behavior |
+|---|---|---|
+| `rateLimitPerMinute` | unset (no limit) | Sliding 60-second window. A request that would exceed the limit rejects with `RateLimitError` before any network I/O. |
+| `circuitBreakerThreshold` | `5` | Consecutive request failures before the circuit opens. |
+| `circuitBreakerResetMs` | `30_000` | Time the circuit stays open. After it elapses, one half-open probe is admitted — success closes the circuit, failure reopens it. |
+| `now` | `Date.now` | Injectable clock (epoch ms) so tests can advance time without sleeping. |
+
+While the circuit is open, requests reject fast with `CircuitOpenError`. Both error types extend `FarmConnectorError` and carry a `retryAfterMs` hint.
+
+```ts
+import { CoinGeckoFarm, RateLimitError, CircuitOpenError } from '@uvrn/farm';
+
+const connector = new CoinGeckoFarm({
+  rateLimitPerMinute: 30,
+  circuitBreakerThreshold: 5,
+  circuitBreakerResetMs: 30_000,
+});
+```
+
+**Zero-config note:** connectors constructed without these options behave exactly as before, except that 5 consecutive failures now open the breaker for 30 seconds (previously failures never tripped anything). There is no default rate limit.
+
+Custom connectors that bypass `requestJson()` can opt in by wrapping their own I/O in `this.withGuards(fn)`.
+
 ## Public API
 
 - `BaseConnector`
@@ -88,6 +115,8 @@ const farm = new MultiFarm([
 - `ConnectorConfig`
 - `MultiFarmOptions`
 - `FarmConnectorError`
+- `RateLimitError`
+- `CircuitOpenError`
 
 ## Dependencies
 

package/dist/connectors/base/BaseConnector.d.ts

@@ -2,13 +2,52 @@ import type { ClaimRegistration, FarmConnector, FarmResult } from '@uvrn/agent';
 import { type ConnectorConfig } from '../../types';
 export declare abstract class BaseConnector implements FarmConnector {
     abstract readonly name: string;
-    protected readonly config: Required<Pick<ConnectorConfig, 'timeout' | 'maxRetries'>> & ConnectorConfig;
+    protected readonly config: Required<Pick<ConnectorConfig, 'timeout' | 'maxRetries' | 'circuitBreakerThreshold' | 'circuitBreakerResetMs'>> & ConnectorConfig;
+    /** Injectable clock (epoch ms) — defaults to `Date.now`. */
+    private readonly now;
+    /** Timestamps of requests made inside the current sliding 60s window. */
+    private requestTimestamps;
+    /** Consecutive request failures while the circuit is closed. */
+    private consecutiveFailures;
+    /** Epoch ms at which the circuit opened, or `null` when closed. */
+    private circuitOpenedAt;
+    /** True while the single half-open probe request is in flight. */
+    private halfOpenProbeInFlight;
     constructor(config?: ConnectorConfig);
     abstract fetch(claim: ClaimRegistration): Promise<FarmResult>;
     protected claimFromString(claim: string): ClaimRegistration;
     protected withRetry<T>(fn: () => Promise<T>): Promise<T>;
     protected withTimeout<T>(fn: () => Promise<T>, ms?: number): Promise<T>;
     protected requestJson<T>(url: string, init?: RequestInit): Promise<T>;
+    /**
+     * Runs `fn` behind the connector's circuit breaker and rate limiter.
+     *
+     * Rejects with {@link CircuitOpenError} (without invoking `fn`) while the
+     * circuit is open, and with {@link RateLimitError} when the call would
+     * exceed `rateLimitPerMinute` within the sliding 60-second window. Each
+     * guarded call consumes one rate-limit slot. A guarded failure counts
+     * toward `circuitBreakerThreshold` (default 5 consecutive failures open
+     * the circuit); after `circuitBreakerResetMs` (default 30 000 ms) the
+     * circuit goes half-open and admits a single probe — success closes the
+     * circuit, failure reopens it.
+     *
+     * `requestJson()` is wrapped automatically; custom connectors that bypass
+     * `requestJson()` can wrap their own I/O with this helper.
+     */
+    protected withGuards<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Validates circuit state before a request. Throws {@link CircuitOpenError}
+     * while open; returns `true` when this call is the half-open probe.
+     */
+    private checkCircuit;
+    /**
+     * Throws {@link RateLimitError} when another request would exceed the
+     * configured `rateLimitPerMinute`; otherwise records the request timestamp.
+     * No-op when `rateLimitPerMinute` is not configured.
+     */
+    private enforceRateLimit;
+    private recordSuccess;
+    private recordFailure;
     protected buildResult(claim: ClaimRegistration, sources: FarmResult['sources'], startedAt: number): FarmResult;
     protected requireApiKey(): string;
     private sleep;

package/dist/connectors/base/BaseConnector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseConnector.d.ts","sourceRoot":"","sources":["../../../src/connectors/base/BaseConnector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAAE,KAAK,eAAe,EAAsB,MAAM,aAAa,CAAC;AAGvE,8BAAsB,aAAc,YAAW,aAAa;IAC1D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,YAAY,CAAC,CAAC,GAAG,eAAe,CAAC;gBAE3F,MAAM,GAAE,eAAoB;IAQxC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IAE7D,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB;cAI3C,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;cAkB9C,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;cAoB7D,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAc3E,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU;IAS9G,SAAS,CAAC,aAAa,IAAI,MAAM;IAQjC,OAAO,CAAC,KAAK;CAGd"}
+{"version":3,"file":"BaseConnector.d.ts","sourceRoot":"","sources":["../../../src/connectors/base/BaseConnector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAAE,KAAK,eAAe,EAAwD,MAAM,aAAa,CAAC;AAKzG,8BAAsB,aAAc,YAAW,aAAa;IAC1D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CACjC,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,YAAY,GAAG,yBAAyB,GAAG,uBAAuB,CAAC,CACtG,GAAG,eAAe,CAAC;IAEpB,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,yEAAyE;IACzE,OAAO,CAAC,iBAAiB,CAAgB;IACzC,gEAAgE;IAChE,OAAO,CAAC,mBAAmB,CAAK;IAChC,mEAAmE;IACnE,OAAO,CAAC,eAAe,CAAuB;IAC9C,kEAAkE;IAClE,OAAO,CAAC,qBAAqB,CAAS;gBAE1B,MAAM,GAAE,eAAoB;IAWxC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IAE7D,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB;cAI3C,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;cAkB9C,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;cAoB7D,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAgB3E;;;;;;;;;;;;;;OAcG;cACa,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAuB/D;;;OAGG;IACH,OAAO,CAAC,YAAY;IAoBpB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,aAAa;IAerB,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU;IAS9G,SAAS,CAAC,aAAa,IAAI,MAAM;IAQjC,OAAO,CAAC,KAAK;CAGd"}

package/dist/connectors/base/BaseConnector.js

@@ -3,14 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseConnector = void 0;
 const types_1 = require("../../types");
 const defaultClaimRegistration_1 = require("../../internal/defaultClaimRegistration");
+const RATE_LIMIT_WINDOW_MS = 60_000;
 class BaseConnector {
     config;
+    /** Injectable clock (epoch ms) — defaults to `Date.now`. */
+    now;
+    /** Timestamps of requests made inside the current sliding 60s window. */
+    requestTimestamps = [];
+    /** Consecutive request failures while the circuit is closed. */
+    consecutiveFailures = 0;
+    /** Epoch ms at which the circuit opened, or `null` when closed. */
+    circuitOpenedAt = null;
+    /** True while the single half-open probe request is in flight. */
+    halfOpenProbeInFlight = false;
     constructor(config = {}) {
         this.config = {
             timeout: 10_000,
             maxRetries: 3,
+            circuitBreakerThreshold: 5,
+            circuitBreakerResetMs: 30_000,
             ...config,
         };
+        this.now = config.now ?? Date.now;
     }
     claimFromString(claim) {
         return (0, defaultClaimRegistration_1.defaultClaimRegistration)(claim);
@@ -49,13 +63,105 @@ class BaseConnector {
         });
     }
     async requestJson(url, init) {
-        return this.withRetry(async () => this.withTimeout(async () => {
+        return this.withGuards(async () => this.withRetry(async () => this.withTimeout(async () => {
             const response = await fetch(url, init);
             if (!response.ok) {
                 throw new types_1.FarmConnectorError(this.name, `Request failed with status ${response.status}`);
             }
             return response.json();
-        }));
+        })));
+    }
+    /**
+     * Runs `fn` behind the connector's circuit breaker and rate limiter.
+     *
+     * Rejects with {@link CircuitOpenError} (without invoking `fn`) while the
+     * circuit is open, and with {@link RateLimitError} when the call would
+     * exceed `rateLimitPerMinute` within the sliding 60-second window. Each
+     * guarded call consumes one rate-limit slot. A guarded failure counts
+     * toward `circuitBreakerThreshold` (default 5 consecutive failures open
+     * the circuit); after `circuitBreakerResetMs` (default 30 000 ms) the
+     * circuit goes half-open and admits a single probe — success closes the
+     * circuit, failure reopens it.
+     *
+     * `requestJson()` is wrapped automatically; custom connectors that bypass
+     * `requestJson()` can wrap their own I/O with this helper.
+     */
+    async withGuards(fn) {
+        const isProbe = this.checkCircuit();
+        try {
+            this.enforceRateLimit();
+            const value = await fn();
+            this.recordSuccess();
+            return value;
+        }
+        catch (error) {
+            if (error instanceof types_1.RateLimitError) {
+                // A rate-limited call never reached the network; release the probe
+                // slot (if held) without counting a breaker failure.
+                if (isProbe) {
+                    this.halfOpenProbeInFlight = false;
+                }
+                throw error;
+            }
+            this.recordFailure(isProbe);
+            throw error;
+        }
+    }
+    /**
+     * Validates circuit state before a request. Throws {@link CircuitOpenError}
+     * while open; returns `true` when this call is the half-open probe.
+     */
+    checkCircuit() {
+        if (this.circuitOpenedAt == null) {
+            return false;
+        }
+        const elapsed = this.now() - this.circuitOpenedAt;
+        const remaining = this.config.circuitBreakerResetMs - elapsed;
+        if (remaining > 0) {
+            throw new types_1.CircuitOpenError(this.name, remaining);
+        }
+        if (this.halfOpenProbeInFlight) {
+            throw new types_1.CircuitOpenError(this.name, this.config.circuitBreakerResetMs);
+        }
+        this.halfOpenProbeInFlight = true;
+        return true;
+    }
+    /**
+     * Throws {@link RateLimitError} when another request would exceed the
+     * configured `rateLimitPerMinute`; otherwise records the request timestamp.
+     * No-op when `rateLimitPerMinute` is not configured.
+     */
+    enforceRateLimit() {
+        const limit = this.config.rateLimitPerMinute;
+        if (limit == null) {
+            return;
+        }
+        const now = this.now();
+        const windowStart = now - RATE_LIMIT_WINDOW_MS;
+        this.requestTimestamps = this.requestTimestamps.filter((timestamp) => timestamp > windowStart);
+        if (this.requestTimestamps.length >= limit) {
+            const oldest = this.requestTimestamps[0] ?? now;
+            throw new types_1.RateLimitError(this.name, limit, oldest + RATE_LIMIT_WINDOW_MS - now);
+        }
+        this.requestTimestamps.push(now);
+    }
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+        this.circuitOpenedAt = null;
+        this.halfOpenProbeInFlight = false;
+    }
+    recordFailure(wasProbe) {
+        if (wasProbe) {
+            // Failed half-open probe: reopen for a full reset period.
+            this.halfOpenProbeInFlight = false;
+            this.circuitOpenedAt = this.now();
+            return;
+        }
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= this.config.circuitBreakerThreshold) {
+            this.circuitOpenedAt = this.now();
+            this.consecutiveFailures = 0;
+        }
     }
     buildResult(claim, sources, startedAt) {
         return {

package/dist/connectors/base/BaseConnector.js.map

@@ -1 +1 @@
-{"version":3,"file":"BaseConnector.js","sourceRoot":"","sources":["../../../src/connectors/base/BaseConnector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseConnector.js","sourceRoot":"","sources":["../../../src/connectors/base/BaseConnector.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -3,7 +3,28 @@ export interface ConnectorConfig {
     apiKey?: string;
     timeout?: number;
     maxRetries?: number;
+    /**
+     * Maximum number of outbound requests allowed per sliding 60-second window.
+     * When unset, no rate limit is enforced (default behavior).
+     */
     rateLimitPerMinute?: number;
+    /**
+     * Number of consecutive request failures before the circuit breaker opens.
+     * While open, requests reject immediately with {@link CircuitOpenError}.
+     * Defaults to 5.
+     */
+    circuitBreakerThreshold?: number;
+    /**
+     * Milliseconds the circuit stays open before transitioning to half-open,
+     * at which point a single probe request is allowed through. Defaults to 30_000.
+     */
+    circuitBreakerResetMs?: number;
+    /**
+     * Injectable clock returning the current epoch milliseconds. Used by the
+     * rate limiter and circuit breaker; defaults to `Date.now`. Override in
+     * tests to advance time without sleeping.
+     */
+    now?: () => number;
 }
 export interface MultiFarmOptions {
     timeoutMs?: number;
@@ -14,4 +35,24 @@ export declare class FarmConnectorError extends Error {
     readonly cause?: unknown;
     constructor(connectorName: string, message: string, cause?: unknown);
 }
+/**
+ * Thrown when a request would exceed the connector's configured
+ * `rateLimitPerMinute`. The request is rejected before any network I/O.
+ */
+export declare class RateLimitError extends FarmConnectorError {
+    /** The configured per-minute limit that was hit. */
+    readonly limit: number;
+    /** Milliseconds until the oldest in-window request expires and a slot frees up. */
+    readonly retryAfterMs: number;
+    constructor(connectorName: string, limit: number, retryAfterMs: number);
+}
+/**
+ * Thrown when the connector's circuit breaker is open (or a half-open probe
+ * is already in flight). The request is rejected before any network I/O.
+ */
+export declare class CircuitOpenError extends FarmConnectorError {
+    /** Milliseconds until the circuit transitions to half-open and allows a probe. */
+    readonly retryAfterMs: number;
+    constructor(connectorName: string, retryAfterMs: number);
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAMpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAMpE;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,kBAAkB;IACpD,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAMvE;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,kBAAkB;IACtD,kFAAkF;IAClF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAKxD"}

package/dist/types/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FarmConnectorError = void 0;
+exports.CircuitOpenError = exports.RateLimitError = exports.FarmConnectorError = void 0;
 class FarmConnectorError extends Error {
     connectorName;
     cause;
@@ -12,4 +12,35 @@ class FarmConnectorError extends Error {
     }
 }
 exports.FarmConnectorError = FarmConnectorError;
+/**
+ * Thrown when a request would exceed the connector's configured
+ * `rateLimitPerMinute`. The request is rejected before any network I/O.
+ */
+class RateLimitError extends FarmConnectorError {
+    /** The configured per-minute limit that was hit. */
+    limit;
+    /** Milliseconds until the oldest in-window request expires and a slot frees up. */
+    retryAfterMs;
+    constructor(connectorName, limit, retryAfterMs) {
+        super(connectorName, `Rate limit of ${limit} requests/minute exceeded; retry in ${retryAfterMs}ms`);
+        this.name = 'RateLimitError';
+        this.limit = limit;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Thrown when the connector's circuit breaker is open (or a half-open probe
+ * is already in flight). The request is rejected before any network I/O.
+ */
+class CircuitOpenError extends FarmConnectorError {
+    /** Milliseconds until the circuit transitions to half-open and allows a probe. */
+    retryAfterMs;
+    constructor(connectorName, retryAfterMs) {
+        super(connectorName, `Circuit breaker is open; retry in ${retryAfterMs}ms`);
+        this.name = 'CircuitOpenError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;AAmBA,MAAa,kBAAmB,SAAQ,KAAK;IAClC,aAAa,CAAS;IACb,KAAK,CAAW;IAElC,YAAY,aAAqB,EAAE,OAAe,EAAE,KAAe;QACjE,KAAK,CAAC,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAVD,gDAUC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;AAwCA,MAAa,kBAAmB,SAAQ,KAAK;IAClC,aAAa,CAAS;IACb,KAAK,CAAW;IAElC,YAAY,aAAqB,EAAE,OAAe,EAAE,KAAe;QACjE,KAAK,CAAC,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAVD,gDAUC;AAED;;;GAGG;AACH,MAAa,cAAe,SAAQ,kBAAkB;IACpD,oDAAoD;IAC3C,KAAK,CAAS;IACvB,mFAAmF;IAC1E,YAAY,CAAS;IAE9B,YAAY,aAAqB,EAAE,KAAa,EAAE,YAAoB;QACpE,KAAK,CAAC,aAAa,EAAE,iBAAiB,KAAK,uCAAuC,YAAY,IAAI,CAAC,CAAC;QACpG,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAZD,wCAYC;AAED;;;GAGG;AACH,MAAa,gBAAiB,SAAQ,kBAAkB;IACtD,kFAAkF;IACzE,YAAY,CAAS;IAE9B,YAAY,aAAqB,EAAE,YAAoB;QACrD,KAAK,CAAC,aAAa,EAAE,qCAAqC,YAAY,IAAI,CAAC,CAAC;QAC5E,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AATD,4CASC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uvrn/farm",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Standardized data source connectors for the UVRN protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,19 +19,26 @@
       "default": "./dist/connectors/index.js"
     }
   },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "test:watch": "jest --watch",
+    "clean": "rm -rf dist"
+  },
   "peerDependencies": {
-    "@uvrn/core": "^3.0.0",
-    "@uvrn/agent": "^3.0.0"
+    "@uvrn/core": "^4.0.0",
+    "@uvrn/agent": "^4.0.0"
   },
   "devDependencies": {
+    "@uvrn/core": "workspace:*",
+    "@uvrn/agent": "workspace:*",
+    "@uvrn/test": "workspace:*",
     "@types/jest": "^29.5.0",
     "@types/node": "^20.0.0",
     "jest": "^29.5.0",
     "ts-jest": "^29.1.0",
-    "typescript": "^5.3.0",
-    "@uvrn/core": "3.0.0",
-    "@uvrn/agent": "3.0.0",
-    "@uvrn/test": "3.0.0"
+    "typescript": "^5.3.0"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -52,11 +59,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "clean": "rm -rf dist"
   }
-}
+}