@net-mesh/sdk 0.19.0

package/dist/subnets.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Subnet configuration — hierarchical 4-level grouping for routing
+ * and visibility enforcement.
+ *
+ * Each node pins itself to one `SubnetId` (1–4 bytes, levels 0–3)
+ * and optionally derives peer subnets from their capability
+ * announcements via a `SubnetPolicy`. Channel visibility on the
+ * publish + subscribe paths then consults `SubnetId` geometry to
+ * decide whether a peer may see a given packet.
+ *
+ * @example
+ * ```ts
+ * import { MeshNode } from '@net-mesh/sdk';
+ *
+ * const policy = {
+ *   rules: [
+ *     { tagPrefix: 'region:', level: 0, values: { us: 3, eu: 4 } },
+ *     { tagPrefix: 'fleet:', level: 1, values: { blue: 7, green: 8 } },
+ *   ],
+ * };
+ *
+ * const node = await MeshNode.create({
+ *   bindAddr: '127.0.0.1:9000',
+ *   psk: '42'.repeat(32),
+ *   subnet: { levels: [3, 7] },
+ *   subnetPolicy: policy,
+ * });
+ * ```
+ *
+ * Today visibility enforcement covers `'subnet-local'` and
+ * `'parent-visible'`. `'exported'` (per-channel export tables) and
+ * multi-hop gateway routing are follow-ups.
+ */
+export interface SubnetId {
+    /**
+     * 1–4 level bytes. Example: `[3, 7, 2]` = level 0 bucket 3,
+     * level 1 bucket 7, level 2 bucket 2, level 3 unset.
+     *
+     * Each value must fit in a u8 (0–255); at most 4 entries.
+     */
+    levels: number[];
+}
+/** Construct the conventional "no restriction" subnet. */
+export declare const GLOBAL_SUBNET: SubnetId;
+/**
+ * A single rule in a [`SubnetPolicy`]. When the policy runs against
+ * a node's `CapabilitySet`, the first capability tag starting with
+ * `tagPrefix` is looked up in `values`; the mapped byte fills the
+ * rule's `level` slot in the derived `SubnetId`.
+ */
+export interface SubnetRule {
+    /** Tag prefix to match — e.g. `'region:'`. */
+    tagPrefix: string;
+    /** Hierarchy level this rule fills (0–3). */
+    level: number;
+    /**
+     * Map from tag suffix to subnet byte. E.g.
+     * `{ eu: 1, us: 2, apac: 3 }` — a tag `"region:us"` against a
+     * rule with `tagPrefix: "region:"` produces subnet byte `2` at
+     * the rule's level.
+     */
+    values: Record<string, number>;
+}
+/**
+ * Policy that derives each peer's `SubnetId` from their capability
+ * tags. Rules are evaluated in order; unmatched levels remain zero.
+ *
+ * Mesh-wide policy consistency is assumed — mismatched policies
+ * across nodes lead to asymmetric views of peer subnets.
+ */
+export interface SubnetPolicy {
+    rules: SubnetRule[];
+}
+/** Build a `SubnetId` from an inline byte list, validating ranges. */
+export declare function subnetId(...levels: number[]): SubnetId;

package/dist/subnets.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Subnet configuration — hierarchical 4-level grouping for routing
+ * and visibility enforcement.
+ *
+ * Each node pins itself to one `SubnetId` (1–4 bytes, levels 0–3)
+ * and optionally derives peer subnets from their capability
+ * announcements via a `SubnetPolicy`. Channel visibility on the
+ * publish + subscribe paths then consults `SubnetId` geometry to
+ * decide whether a peer may see a given packet.
+ *
+ * @example
+ * ```ts
+ * import { MeshNode } from '@net-mesh/sdk';
+ *
+ * const policy = {
+ *   rules: [
+ *     { tagPrefix: 'region:', level: 0, values: { us: 3, eu: 4 } },
+ *     { tagPrefix: 'fleet:', level: 1, values: { blue: 7, green: 8 } },
+ *   ],
+ * };
+ *
+ * const node = await MeshNode.create({
+ *   bindAddr: '127.0.0.1:9000',
+ *   psk: '42'.repeat(32),
+ *   subnet: { levels: [3, 7] },
+ *   subnetPolicy: policy,
+ * });
+ * ```
+ *
+ * Today visibility enforcement covers `'subnet-local'` and
+ * `'parent-visible'`. `'exported'` (per-channel export tables) and
+ * multi-hop gateway routing are follow-ups.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GLOBAL_SUBNET = void 0;
+exports.subnetId = subnetId;
+/** Construct the conventional "no restriction" subnet. */
+exports.GLOBAL_SUBNET = { levels: [0] };
+// ----------------------------------------------------------------------------
+// Helpers
+// ----------------------------------------------------------------------------
+/** Build a `SubnetId` from an inline byte list, validating ranges. */
+function subnetId(...levels) {
+    if (levels.length === 0 || levels.length > 4) {
+        throw new Error(`subnet: levels must have 1–4 entries, got ${levels.length}`);
+    }
+    for (const [i, v] of levels.entries()) {
+        if (!Number.isInteger(v) || v < 0 || v > 255) {
+            throw new Error(`subnet: level ${i} value ${v} must be an integer in [0, 255]`);
+        }
+    }
+    return { levels };
+}

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared types for the Net SDK.
+ */
+import type { Net as NapiNet, EventBusOptions, PollResponse as NapiPollResponse, StoredEvent as NapiStoredEvent, IngestResult as NapiIngestResult, Stats as NapiStats, RedisOptions, JetStreamOptions } from '@net-mesh/core';
+export type { RedisOptions, JetStreamOptions, NapiNet, EventBusOptions, NapiPollResponse, NapiStoredEvent, NapiIngestResult, NapiStats, };
+/** Transport configuration. */
+export type Transport = {
+    type: 'memory';
+} | ({
+    type: 'redis';
+} & RedisOptions) | ({
+    type: 'jetstream';
+} & JetStreamOptions) | {
+    type: 'mesh';
+    bind: string;
+    peer: string;
+    psk: string;
+    role?: 'initiator' | 'responder';
+    peerPublicKey?: string;
+    secretKey?: string;
+    publicKey?: string;
+    reliability?: 'none' | 'light' | 'full';
+    heartbeatIntervalMs?: number;
+    sessionTimeoutMs?: number;
+    batchedIo?: boolean;
+    packetPoolSize?: number;
+};
+/** Configuration for creating a NetNode. */
+export interface NetNodeConfig {
+    /** Number of shards (defaults to CPU core count). */
+    shards?: number;
+    /** Ring buffer capacity per shard (must be power of 2). */
+    bufferCapacity?: number;
+    /** Backpressure strategy. */
+    backpressure?: 'drop_newest' | 'drop_oldest' | 'fail_producer';
+    /** Transport configuration. */
+    transport?: Transport;
+}
+/** Receipt from a successful ingestion. */
+export interface Receipt {
+    /** The shard the event was assigned to. */
+    shardId: number;
+    /** Insertion timestamp (nanoseconds). */
+    timestamp: number;
+}
+/** A stored event from the bus. */
+export interface StoredEvent {
+    /** Backend-specific event ID. */
+    id: string;
+    /** Raw JSON payload. */
+    raw: string;
+    /** Insertion timestamp (nanoseconds). */
+    insertionTs: number;
+    /** Shard ID. */
+    shardId: number;
+}
+/** Poll request options. */
+export interface PollRequest {
+    /** Maximum events to return. */
+    limit: number;
+    /** Cursor to resume from. */
+    cursor?: string;
+    /** JSON filter expression. */
+    filter?: string;
+    /** Event ordering. */
+    ordering?: 'none' | 'insertion_ts';
+}
+/** Poll response. */
+export interface PollResponseData {
+    /** Events returned. */
+    events: StoredEvent[];
+    /** Cursor for the next poll. */
+    nextId?: string;
+    /** Whether more events are available. */
+    hasMore: boolean;
+}
+/** Ingestion statistics.
+ *
+ * Counters cross the napi boundary as `bigint` because a long-running
+ * bus can outrun `Number.MAX_SAFE_INTEGER` (2^53) over weeks at high
+ * event rates. Use `Number(stats.eventsIngested)` for display when you
+ * know the value fits; keep as `bigint` for arithmetic.
+ */
+export interface Stats {
+    /** Total events ingested. */
+    eventsIngested: bigint;
+    /** Events dropped due to backpressure. */
+    eventsDropped: bigint;
+}
+/** Options for subscribing to events. */
+export interface SubscribeOpts {
+    /** Maximum events per poll batch. */
+    limit?: number;
+    /** JSON filter expression. */
+    filter?: string;
+    /** Event ordering. */
+    ordering?: 'none' | 'insertion_ts';
+    /** Base poll interval in ms. */
+    pollIntervalMs?: number;
+    /** Maximum backoff interval in ms. */
+    maxBackoffMs?: number;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Shared types for the Net SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@net-mesh/sdk",
+  "version": "0.19.0",
+  "description": "Ergonomic TypeScript SDK for the Net mesh network",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ai-2070/net"
+  },
+  "keywords": [
+    "net",
+    "mesh",
+    "event-bus",
+    "streaming",
+    "ai",
+    "llm",
+    "inference",
+    "rust"
+  ],
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "node -e \"const fs=require('fs'),cp=require('child_process');if(!fs.existsSync('../bindings/node/index.d.ts')){cp.execSync('npm --prefix ../bindings/node i --ignore-scripts',{stdio:'inherit'});cp.execSync('npm --prefix ../bindings/node run build',{stdio:'inherit'})}\"",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@net-mesh/core": ">=0.19.0"
+  },
+  "devDependencies": {
+    "@net-mesh/core": "file:../bindings/node",
+    "@types/node": "^24.0.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}