@nodora/client 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nodora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @nodora/client
+
+A lightweight client for the [Nodora](https://app.nodora.net) platform. Evaluate business rules in your application with built-in caching, event batching, and multi-environment support.
+
+## Installation
+
+```bash
+npm install @nodora/client
+```
+
+## Quick start
+
+```typescript
+import { NodoraClient } from "@nodora/client";
+
+const client = new NodoraClient({
+  apiKey: "apikey_abc123...",
+});
+
+const checkout = client.ruleset("Checkout");
+const result = await checkout.evaluate("IsDiscountEligible", {
+  total: 100,
+  pastCustomer: true,
+});
+```
+
+For configuration options, caching strategies, and detailed usage, see the official [documentation](https://docs.nodora.org).
+
+## License
+
+MIT

package/lib/client.d.ts

@@ -0,0 +1,203 @@
+import type { EvaluationResult } from "@nodora/js";
+
+/**
+ * The deployment environment the client is running in.
+ *
+ * @example "production"
+ */
+export type Environment = "staging" | "production";
+
+/**
+ * Caching strategy configuration.
+ *
+ * Currently supports a stale-while-revalidate approach:
+ * - Returns cached data immediately (even if stale)
+ * - Fetches fresh data in the background and updates cache
+ */
+export type Strategy = {
+  /**
+   * Strategy type.
+   */
+  type: "stale-while-revalidate";
+
+  /**
+   * Time-to-live for cached data (in milliseconds).
+   * After this duration, cached data is considered stale and will revalidate.
+   *
+   * @example 60000 // 1 minute
+   */
+  ttl: number;
+};
+
+export interface ClientOptions {
+  /**
+   * Base URL of the Nodora instance.
+   *
+   * @default "https://app.nodora.net"
+   */
+  baseUrl?: string;
+
+  /**
+   * Public API key used to authenticate requests.
+   *
+   * @example "apikey_abc123..."
+   */
+  apiKey: string;
+
+  /**
+   * Target environment for the client.
+   *
+   * @default "production"
+   * @example "staging"
+   */
+  env?: Environment;
+
+  /**
+   * Optional caching strategy.
+   *
+   * If omitted, caching is disabled.
+   *
+   * @example { type: "stale-while-revalidate", ttl: 30000 }
+   */
+  strategy?: Strategy;
+
+  /**
+   * Maximum number of events to batch before sending.
+   *
+   * Helps reduce network overhead by grouping events.
+   *
+   * @default 60
+   */
+  flushThreshold?: number;
+
+  /**
+   * Time interval (in ms) to flush events even if the threshold is not reached.
+   *
+   * Ensures events are sent during low activity periods.
+   *
+   * @default 10000
+   */
+  flushInterval?: number;
+
+  /**
+   * Maximum number of events to keep in the buffer.
+   *
+   * When the buffer exceeds this size (e.g. due to persistent flush failures),
+   * the oldest events are dropped to prevent unbounded memory growth.
+   *
+   * @default 300
+   */
+  maxBufferSize?: number;
+
+  /**
+   * Timeout (in ms) for HTTP requests to the Nodora API.
+   *
+   * Applies to both data fetching and event ingestion requests.
+   *
+   * @default 10000
+   */
+  timeout?: number;
+
+  /**
+   * Called when a non-fatal background error occurs,
+   * such as a failed event flush or background refresh.
+   *
+   * @param error - The error that occurred.
+   *
+   * @example
+   * onError: (err) => logger.warn(err)
+   */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * A handle for interacting with a specific ruleset.
+ * Provides methods to evaluate rules against input data.
+ */
+export declare class RulesetHandle {
+  /**
+   * Evaluates a rule within the ruleset.
+   *
+   * @param rule - The name or identifier of the rule to evaluate.
+   * @param input - Input data used during evaluation.
+   *
+   * @returns A promise that resolves to the evaluation result.
+   *
+   * @example
+   * const result = await ruleset.evaluate("IsEligible", { age: 25 });
+   */
+  evaluate(
+    rule: string,
+    input?: Record<string, any>,
+  ): Promise<EvaluationResult>;
+}
+
+/**
+ * Main client for interacting with the Nodora API.
+ * Handles configuration, batching, caching, and ruleset evaluation.
+ */
+export declare class NodoraClient {
+  /**
+   * Creates a new Nodora client instance.
+   *
+   * @param options - Configuration options for the client.
+   *
+   * @example
+   * const client = new NodoraClient({
+   *   apiKey: "apikey_abc123...",
+   *   environment: "production",
+   * });
+   */
+  constructor(options: ClientOptions);
+
+  /**
+   * Prefetches all rulesets and required data for evaluation.
+   *
+   * Typically used to warm up cache or reduce latency
+   * before performing evaluations.
+   *
+   * @returns A promise that resolves when prefetching is complete.
+   *
+   * @example
+   * await client.prefetch();
+   */
+  prefetch(): Promise<void>;
+
+  /**
+   * Returns a handle for a specific ruleset.
+   *
+   * @param ruleset - The name or identifier of the ruleset.
+   *
+   * @returns A RulesetHandle instance used to evaluate rules.
+   *
+   * @example
+   * const rules = client.ruleset("Checkout");
+   * const result = await rules.evaluate("IsDiscountEligible", { total: 100 });
+   */
+  ruleset(ruleset: string): RulesetHandle;
+
+  /**
+   * Flushes any buffered events to the server immediately.
+   *
+   * Call this before `destroy()` if you need to ensure
+   * all pending events are sent.
+   *
+   * @example
+   * await client.flush();
+   * await client.destroy();
+   */
+  flush(): Promise<void>;
+
+  /**
+   * Cleans up internal resources used by the client.
+   *
+   * Should be called when the client is no longer needed
+   * to prevent memory leaks, timers, or pending network activity.
+   * Buffered events are discarded — call `flush()` first if needed.
+   *
+   * @example
+   * await client.flush();
+   * await client.destroy();
+   */
+  destroy(): Promise<void>;
+}

package/lib/client.js

@@ -0,0 +1,247 @@
+import { createEvaluator } from "@nodora/js";
+import { MetricAccumulator } from "./metrics";
+import { asyncGate } from "./utils";
+
+export class NodoraClient {
+  constructor(options) {
+    if (!options || !options.apiKey) {
+      throw new Error("apiKey is required");
+    }
+
+    const defaultOptions = {
+      baseUrl: "https://app.nodora.net",
+      env: "production",
+      flushThreshold: 60,
+      flushInterval: 10000,
+      maxBufferSize: 300,
+      timeout: 10000,
+    };
+
+    this._options = { ...defaultOptions, ...options };
+    this._onError = options.onError || (() => {});
+    this._cache = new Map();
+    this._lastFetchedAt = 0;
+    this._flushTimer = null;
+    this._eventBuffer = [];
+    this._initPromise = null;
+    this._refreshGate = asyncGate();
+    this._flushGate = asyncGate();
+    this._abortController = new AbortController();
+    this._metrics = new MetricAccumulator();
+  }
+
+  async prefetch() {
+    if (!this._initPromise) {
+      this._initPromise = this._init();
+    }
+    return this._initPromise;
+  }
+
+  async flush() {
+    return this._flushEvents();
+  }
+
+  ruleset(rulesetName) {
+    return new RulesetHandle(this, rulesetName);
+  }
+
+  _evaluate(rulesetName, ruleName, input) {
+    if (this._abortController.signal.aborted) return;
+
+    const entry = this._cache.get(rulesetName);
+    if (!entry) {
+      throw new Error(`Ruleset "${rulesetName}" not found`);
+    }
+
+    let result;
+    let succeeded = false;
+
+    try {
+      result = entry.evaluator.evaluate(ruleName, input);
+      succeeded = true;
+    } catch (err) {
+      throw err;
+    } finally {
+      this._metrics.record(entry.rulesetId, "evaluations", ruleName, succeeded);
+    }
+
+    if (result.emitted_signals && result.emitted_signals.length > 0) {
+      for (const signal of result.emitted_signals) {
+        this._bufferEvent({
+          type: "signal",
+          payload: {
+            rulesetId: entry.rulesetId,
+            env: this._options.env,
+            payload: {
+              name: signal.name,
+              args: signal.args || [],
+            },
+          },
+        });
+      }
+    }
+
+    // trigger background refresh if TTL expired
+    const strategy = this._options.strategy;
+    if (
+      strategy &&
+      strategy.type === "stale-while-revalidate" &&
+      Date.now() - this._lastFetchedAt > strategy.ttl
+    ) {
+      this._refreshGate(() => this._refresh()).catch((err) =>
+        this._onError(err)
+      );
+    }
+
+    return result;
+  }
+
+  _bufferEvent(event) {
+    this._eventBuffer.push(event);
+    if (this._eventBuffer.length >= this._options.flushThreshold) {
+      this._flushEvents();
+    }
+  }
+
+  async _init() {
+    await this._refresh();
+
+    if (this._flushTimer) return;
+    this._flushTimer = setInterval(() => {
+      if (this._abortController.signal.aborted) {
+        clearInterval(this._flushTimer);
+        this._flushTimer = null;
+        return;
+      }
+      this._flushEvents();
+    }, this._options.flushInterval);
+  }
+
+  async _fetch() {
+    const { baseUrl, apiKey, env, timeout } = this._options;
+    const url = `${baseUrl}/api/releases/latest?env=${env}`;
+    const res = await fetch(url, {
+      headers: { "x-api-key": apiKey },
+      signal: AbortSignal.any([
+        AbortSignal.timeout(timeout),
+        this._abortController.signal,
+      ]),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Failed to fetch releases: HTTP ${res.status}`);
+    }
+
+    return res.json();
+  }
+
+  async _syncEvaluators(data) {
+    const entries = Object.entries(data);
+    await Promise.all(
+      entries.map(async ([rulesetName, release]) => {
+        const existing = this._cache.get(rulesetName);
+
+        if (existing && existing.checksum === release.checksum) {
+          return;
+        }
+
+        if (existing && existing.evaluator) {
+          existing.evaluator.destroy();
+        }
+
+        const evaluator = await createEvaluator(release.compiled);
+        this._cache.set(rulesetName, {
+          rulesetId: release.rulesetId,
+          checksum: release.checksum,
+          evaluator,
+        });
+      })
+    );
+
+    // clean up deleted rulesets
+    for (const rulesetName of this._cache.keys()) {
+      if (!(rulesetName in data)) {
+        const entry = this._cache.get(rulesetName);
+        if (entry.evaluator) entry.evaluator.destroy();
+        this._cache.delete(rulesetName);
+      }
+    }
+  }
+
+  async _refresh() {
+    try {
+      const data = await this._fetch();
+      this._lastFetchedAt = Date.now();
+      await this._syncEvaluators(data);
+    } catch (err) {
+      if (this._abortController.signal.aborted) return;
+      throw err;
+    }
+  }
+
+  _flushEvents() {
+    for (const event of this._metrics.drain()) {
+      this._eventBuffer.push(event);
+    }
+    if (this._eventBuffer.length === 0) return Promise.resolve();
+
+    return this._flushGate(async () => {
+      const batch = this._eventBuffer.splice(0);
+      const { baseUrl, apiKey, timeout } = this._options;
+
+      try {
+        return await fetch(`${baseUrl}/api/ingest`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-api-key": apiKey,
+          },
+          body: JSON.stringify(batch),
+          signal: AbortSignal.any([
+            AbortSignal.timeout(timeout),
+            this._abortController.signal,
+          ]),
+        });
+      } catch (err) {
+        this._eventBuffer.unshift(...batch);
+        const max = this._options.maxBufferSize;
+        if (this._eventBuffer.length > max) {
+          this._eventBuffer.length = max;
+        }
+        this._onError(err);
+      }
+    });
+  }
+
+  async destroy() {
+    this._abortController.abort();
+
+    if (this._flushTimer) {
+      clearInterval(this._flushTimer);
+      this._flushTimer = null;
+    }
+
+    this._eventBuffer.length = 0;
+    this._metrics.clear();
+
+    for (const entry of this._cache.values()) {
+      if (entry.evaluator) {
+        entry.evaluator.destroy();
+      }
+    }
+
+    this._cache.clear();
+  }
+}
+
+class RulesetHandle {
+  constructor(client, ruleset) {
+    this._client = client;
+    this._ruleset = ruleset;
+  }
+
+  async evaluate(rule, input = {}) {
+    await this._client.prefetch();
+    return this._client._evaluate(this._ruleset, rule, input);
+  }
+}

package/lib/metrics.js

@@ -0,0 +1,41 @@
+export class MetricAccumulator {
+  constructor() {
+    this._counters = new Map();
+  }
+
+  record(rulesetId, type, bucket, succeeded) {
+    const key = `${rulesetId}:${type}:${bucket}`;
+    const counter = this._counters.get(key);
+    if (counter) {
+      counter.count++;
+      if (succeeded) counter.succeeded++;
+      else counter.failed++;
+    } else {
+      this._counters.set(key, {
+        rulesetId,
+        type,
+        bucket,
+        count: 1,
+        succeeded: succeeded ? 1 : 0,
+        failed: succeeded ? 0 : 1,
+        timestamp: Date.now(),
+      });
+    }
+  }
+
+  drain() {
+    const events = [];
+    for (const payload of this._counters.values()) {
+      events.push({
+        type: "metric",
+        payload,
+      });
+    }
+    this._counters.clear();
+    return events;
+  }
+
+  clear() {
+    this._counters.clear();
+  }
+}

package/lib/utils.js

@@ -0,0 +1,10 @@
+export function asyncGate() {
+  let pending = null;
+  return (fn) => {
+    if (pending) return pending;
+    pending = fn().finally(() => {
+      pending = null;
+    });
+    return pending;
+  };
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@nodora/client",
+  "version": "0.0.1",
+  "description": "Nodora platform client for ruleset evaluation",
+  "main": "lib/client.js",
+  "types": "lib/client.d.ts",
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "nodora",
+    "client"
+  ],
+  "author": "Nodora",
+  "license": "MIT",
+  "dependencies": {
+    "@nodora/js": "^0.0.3"
+  },
+  "exports": {
+    ".": {
+      "import": "./lib/client.js",
+      "require": "./lib/client.js",
+      "types": "./lib/client.d.ts"
+    }
+  }
+}