intents-1click-rule-engine 1.0.0

package/README.md

@@ -0,0 +1,473 @@
+# intents-1click-rule-engine
+
+Fee configuration rule engine for NEAR Intents 1Click API. Matches swap requests against configurable rules to determine fees.
+
+## Installation
+
+```bash
+bun add intents-1click-rule-engine
+```
+
+## Usage
+
+```typescript
+import { RuleEngine, getTotalBps, calculateFee, type FeeConfig } from "intents-1click-rule-engine";
+
+const feeConfig: FeeConfig = {
+  version: "1.0.0",
+  default_fee: { type: "bps", bps: 20, recipient: "fees.near" },
+  rules: [
+    {
+      id: "usdc-swaps",
+      enabled: true,
+      priority: 100,
+      match: {
+        in: { symbol: "USDC", blockchain: "*" },
+        out: { symbol: "USDC", blockchain: "*" },
+      },
+      fee: { type: "bps", bps: 10, recipient: "fees.near" },
+    },
+  ],
+};
+
+// Create engine (validates config, throws on error)
+const engine = new RuleEngine(feeConfig);
+
+// Initialize token registry
+await engine.initialize();
+
+// Match a swap request
+const result = engine.match({
+  originAsset: "nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near",
+  destinationAsset: "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
+});
+
+console.log(result.matched);           // true
+console.log(result.fee);               // { type: "bps", bps: 10, recipient: "fees.near" }
+console.log(result.rule?.id);          // "usdc-swaps"
+console.log(getTotalBps(result.fee));  // 10
+
+// Calculate fee amount
+const feeAmount = calculateFee("1000000", getTotalBps(result.fee)); // "1000" (0.10% of 1000000)
+```
+
+## Fee Calculation
+
+The `calculateFee` and `calculateAmountAfterFee` functions validate their inputs:
+
+```typescript
+// Valid usage
+calculateFee("1000000", 20);        // "2000" (0.20% of 1000000)
+calculateFee(1000000n, 20);         // "2000" (bigint input also works)
+calculateAmountAfterFee("1000000", 20); // "998000" (amount minus fee)
+
+// Input validation - these throw descriptive errors:
+calculateFee("abc", 20);            // Error: not a valid integer string
+calculateFee("12.5", 20);           // Error: not a valid integer string
+calculateFee("-100", 20);           // Error: must be non-negative
+calculateFee("1000", -5);           // Error: bps must be non-negative
+calculateFee("1000", 10001);        // Error: bps exceeds maximum of 10000 (100%)
+calculateFee("1000", 20.5);         // Error: bps must be an integer
+```
+
+The `bps` parameter must be between 0 and 10000 (0% to 100%).
+
+## Token Registry
+
+The engine fetches the token list from `https://1click.chaindefuser.com/v0/tokens` to resolve asset IDs to their `blockchain` and `symbol`. This allows rules to match by symbol/blockchain instead of exact asset IDs.
+
+```
+Swap Request                          Token Registry Lookup
+─────────────                         ─────────────────────
+originAsset: "nep141:eth-..."      → { blockchain: "eth", symbol: "USDC" }
+destinationAsset: "nep141:sol-..." → { blockchain: "sol", symbol: "USDC" }
+```
+
+Call `engine.initialize()` before matching to fetch the token list. The list is cached for 1 hour by default.
+
+## Rule Matching
+
+Rules are evaluated by priority (highest first). The first matching rule wins. If no rules match, `default_fee` is used.
+
+Each rule can match on:
+
+- `assetId` - exact asset identifier (string or array)
+- `blockchain` - chain identifier (e.g., `"eth"`, `"polygon"`)
+- `symbol` - token symbol (e.g., `"USDC"`, `"WBTC"`)
+
+Special patterns:
+- `"*"` - wildcard, matches any value
+- `"!value"` - negation, matches anything except `value`
+- `["a", "b"]` - array, matches any value in the list (OR logic)
+
+**Important:** All pattern matching is **case-sensitive**. `"USDC"` will not match `"usdc"` or `"Usdc"`. Ensure your rules use the exact casing from the token registry.
+
+## Fee Structure
+
+Each fee requires a `type`, `bps`, and `recipient`. Fees can be a single object or an array for multiple recipients:
+
+### Single fee
+
+```typescript
+fee: { type: "bps", bps: 20, recipient: "fees.near" }
+```
+
+### Multiple fees (split between recipients)
+
+Each recipient can have their own fee amount:
+
+```typescript
+fee: [
+  { type: "bps", bps: 14, recipient: "fees.near" },     // 0.14%
+  { type: "bps", bps: 6, recipient: "partner.near" },   // 0.06%
+]
+// Total: 0.20%
+```
+
+## Rule Examples
+
+### Match by symbol (any chain)
+
+```typescript
+{
+  id: "usdc-to-usdc",
+  enabled: true,
+  priority: 100,
+  match: {
+    in: { symbol: "USDC" },
+    out: { symbol: "USDC" },
+  },
+  fee: { type: "bps", bps: 10, recipient: "fees.near" },
+}
+```
+
+### Match by blockchain route
+
+```typescript
+{
+  id: "eth-to-polygon",
+  enabled: true,
+  priority: 100,
+  match: {
+    in: { blockchain: "eth" },
+    out: { blockchain: "polygon" },
+  },
+  fee: { type: "bps", bps: 15, recipient: "fees.near" },
+}
+```
+
+### Match exact asset pair
+
+```typescript
+{
+  id: "eth-usdc-to-polygon-usdc",
+  enabled: true,
+  priority: 200,
+  match: {
+    in: { assetId: "nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near" },
+    out: { assetId: "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near" },
+  },
+  fee: { type: "bps", bps: 5, recipient: "fees.near" },
+}
+```
+
+### Mixed matching (blockchain + symbol)
+
+```typescript
+{
+  id: "eth-usdc-to-any-usdc",
+  enabled: true,
+  priority: 150,
+  match: {
+    in: { blockchain: "eth", symbol: "USDC" },
+    out: { symbol: "USDC", blockchain: "*" },
+  },
+  fee: { type: "bps", bps: 8, recipient: "fees.near" },
+}
+```
+
+### Wildcard for any token on specific chain
+
+```typescript
+{
+  id: "anything-to-solana",
+  enabled: true,
+  priority: 50,
+  match: {
+    in: { blockchain: "*" },
+    out: { blockchain: "sol" },
+  },
+  fee: { type: "bps", bps: 25, recipient: "fees.near" },
+}
+```
+
+### Negation (exclude specific values)
+
+```typescript
+{
+  id: "non-eth-swaps",
+  enabled: true,
+  priority: 100,
+  match: {
+    in: { blockchain: "!eth" },
+    out: { blockchain: "!eth" },
+  },
+  fee: { type: "bps", bps: 12, recipient: "fees.near" },
+}
+```
+
+### Array values (match multiple options)
+
+```typescript
+{
+  id: "stablecoin-swaps",
+  enabled: true,
+  priority: 100,
+  match: {
+    in: { symbol: ["USDC", "USDT", "DAI"] },
+    out: { symbol: ["USDC", "USDT", "DAI"] },
+  },
+  fee: { type: "bps", bps: 5, recipient: "fees.near" },
+}
+```
+
+```typescript
+{
+  id: "l2-to-l2",
+  enabled: true,
+  priority: 100,
+  match: {
+    in: { blockchain: ["arb", "polygon", "base", "op"] },
+    out: { blockchain: ["arb", "polygon", "base", "op"] },
+  },
+  fee: { type: "bps", bps: 8, recipient: "fees.near" },
+}
+```
+
+### Array values for assetId
+
+```typescript
+{
+  id: "specific-usdc-tokens",
+  enabled: true,
+  priority: 150,
+  match: {
+    in: {
+      assetId: [
+        "nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near",
+        "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
+      ]
+    },
+    out: { symbol: "USDC" },
+  },
+  fee: { type: "bps", bps: 5, recipient: "fees.near" },
+}
+```
+
+### Time-based rules (promotional periods)
+
+Rules can have `valid_from` and `valid_until` timestamps. Dates must be valid ISO 8601 strings - invalid dates will throw an error during matching.
+
+```typescript
+{
+  id: "new-year-promo",
+  enabled: true,
+  priority: 200,
+  valid_from: "2025-01-01T00:00:00Z",
+  valid_until: "2025-01-07T23:59:59Z",
+  match: {
+    in: { symbol: "*" },
+    out: { symbol: "*" },
+  },
+  fee: { type: "bps", bps: 0, recipient: "fees.near" },
+}
+```
+
+```typescript
+{
+  id: "summer-discount",
+  enabled: true,
+  priority: 150,
+  valid_from: "2025-06-01T00:00:00Z",
+  // No valid_until - runs indefinitely after start
+  match: {
+    in: { symbol: "USDC" },
+    out: { symbol: "USDC" },
+  },
+  fee: { type: "bps", bps: 5, recipient: "fees.near" },
+}
+```
+
+### Multiple fee recipients
+
+Split fees between multiple accounts (e.g., platform + partner):
+
+```typescript
+{
+  id: "partner-referral",
+  enabled: true,
+  priority: 100,
+  match: {
+    in: { symbol: "USDC" },
+    out: { symbol: "USDC" },
+  },
+  fee: [
+    { type: "bps", bps: 7, recipient: "fees.near" },
+    { type: "bps", bps: 3, recipient: "partner.near" },
+  ],
+}
+// Total fee: 10 bps (0.10%), split 70/30
+```
+
+### Complete config example
+
+```typescript
+const feeConfig = {
+  version: "1.0.0",
+  default_fee: { type: "bps", bps: 30, recipient: "fees.near" },
+  rules: [
+    // Most specific first (higher priority)
+    {
+      id: "eth-usdc-to-polygon-usdc",
+      enabled: true,
+      priority: 200,
+      match: {
+        in: { assetId: "nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near" },
+        out: { assetId: "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near" },
+      },
+      fee: { type: "bps", bps: 5, recipient: "fees.near" },
+    },
+    // Chain + symbol combo
+    {
+      id: "eth-usdc-to-any",
+      enabled: true,
+      priority: 150,
+      match: {
+        in: { blockchain: "eth", symbol: "USDC" },
+        out: { blockchain: "*" },
+      },
+      fee: { type: "bps", bps: 12, recipient: "fees.near" },
+    },
+    // All stablecoin swaps
+    {
+      id: "usdc-swaps",
+      enabled: true,
+      priority: 100,
+      match: {
+        in: { symbol: "USDC" },
+        out: { symbol: "USDC" },
+      },
+      fee: { type: "bps", bps: 10, recipient: "fees.near" },
+    },
+    // Disabled rule (won't match)
+    {
+      id: "promo-free-swaps",
+      enabled: false,
+      priority: 300,
+      match: {
+        in: { blockchain: "*" },
+        out: { blockchain: "*" },
+      },
+      fee: { type: "bps", bps: 0, recipient: "fees.near" },
+    },
+  ],
+};
+```
+
+### Priority ordering
+
+- Higher priority rules are evaluated first
+- First matching rule wins
+- Use priority gaps (50, 100, 150, 200) to allow inserting rules later
+- More specific rules should have higher priority
+
+## Rule Builder UI
+
+A simple browser-based tool for building fee configurations is included:
+
+**Online:** https://bonnevoyager.github.io/intents-1click-rule-engine/
+
+**Local:**
+```bash
+open index.html
+```
+
+Features:
+- Visual rule editor with all matching options
+- Support for wildcards, negation, and arrays
+- Multiple fee recipients
+- Time-based rules
+- Import/export JSON configurations
+- No dependencies - works offline
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+```
+
+## Publishing to npm
+
+### Prerequisites
+
+1. Create an [npm account](https://www.npmjs.com/signup) if you don't have one
+2. Login to npm:
+
+```bash
+npm login
+```
+
+### Publish
+
+1. Update the version in `package.json`:
+
+```bash
+# Patch release (1.0.0 -> 1.0.1)
+npm version patch
+
+# Minor release (1.0.0 -> 1.1.0)
+npm version minor
+
+# Major release (1.0.0 -> 2.0.0)
+npm version major
+```
+
+2. Run tests to ensure everything works:
+
+```bash
+bun test && bun run typecheck
+```
+
+3. Publish to npm:
+
+```bash
+npm publish
+```
+
+### Publishing a scoped package
+
+If you want to publish under a scope (e.g., `@myorg/intents-1click-rule-engine`):
+
+1. Update the `name` in `package.json`:
+
+```json
+{
+  "name": "@myorg/intents-1click-rule-engine"
+}
+```
+
+2. Publish with public access (scoped packages are private by default):
+
+```bash
+npm publish --access public
+```
+
+### Verify publication
+
+After publishing, verify the package is available:
+
+```bash
+npm info intents-1click-rule-engine
+```

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./src/types";
+export * from "./src/matcher";
+export * from "./src/token-registry";
+export * from "./src/validator";
+export * from "./src/rule-engine";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./src/types";
+export * from "./src/matcher";
+export * from "./src/token-registry";
+export * from "./src/validator";
+export * from "./src/rule-engine";

package/dist/src/matcher.d.ts

@@ -0,0 +1,15 @@
+import type { FeeConfig, MatchResult, SwapRequest, TokenRegistry } from "./types";
+export declare class RuleMatcher {
+    private rules;
+    private defaultFee;
+    private tokenRegistry;
+    constructor(config: FeeConfig, tokenRegistry: TokenRegistry);
+    private sortRulesByPriority;
+    private matchesSinglePattern;
+    private matchesValue;
+    private matchesToken;
+    private parseDate;
+    private isRuleValidNow;
+    match(request: SwapRequest): MatchResult;
+}
+//# sourceMappingURL=matcher.d.ts.map

package/dist/src/matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../../src/matcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,SAAS,EAA2C,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEjI,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,aAAa,CAAgB;gBAEzB,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa;IAM3D,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,YAAY;IAyBpB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,cAAc;IAatB,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW;CAuCzC"}

package/dist/src/matcher.js

@@ -0,0 +1,110 @@
+export class RuleMatcher {
+    rules;
+    defaultFee;
+    tokenRegistry;
+    constructor(config, tokenRegistry) {
+        this.defaultFee = config.default_fee;
+        this.rules = this.sortRulesByPriority(config.rules);
+        this.tokenRegistry = tokenRegistry;
+    }
+    sortRulesByPriority(rules) {
+        return [...rules].sort((a, b) => {
+            const priorityA = a.priority ?? 100;
+            const priorityB = b.priority ?? 100;
+            return priorityB - priorityA;
+        });
+    }
+    matchesSinglePattern(pattern, value) {
+        if (pattern === "*")
+            return true;
+        if (pattern.startsWith("!")) {
+            return value !== pattern.slice(1);
+        }
+        return pattern === value;
+    }
+    matchesValue(pattern, value) {
+        if (Array.isArray(pattern)) {
+            return pattern.some((p) => this.matchesSinglePattern(p, value));
+        }
+        return this.matchesSinglePattern(pattern, value);
+    }
+    matchesToken(matcher, token) {
+        const matchedBy = {};
+        if (matcher.assetId) {
+            if (!this.matchesValue(matcher.assetId, token.assetId)) {
+                return null;
+            }
+            matchedBy.assetId = true;
+        }
+        if (matcher.blockchain) {
+            if (!this.matchesValue(matcher.blockchain, token.blockchain)) {
+                return null;
+            }
+            matchedBy.blockchain = true;
+        }
+        if (matcher.symbol) {
+            if (!this.matchesValue(matcher.symbol, token.symbol)) {
+                return null;
+            }
+            matchedBy.symbol = true;
+        }
+        return { token, matchedBy };
+    }
+    parseDate(dateStr, fieldName) {
+        const timestamp = new Date(dateStr).getTime();
+        if (Number.isNaN(timestamp)) {
+            throw new Error(`Invalid ${fieldName}: "${dateStr}" is not a valid date string`);
+        }
+        return timestamp;
+    }
+    isRuleValidNow(rule) {
+        const now = Date.now();
+        if (rule.valid_from) {
+            const from = this.parseDate(rule.valid_from, "valid_from");
+            if (now < from)
+                return false;
+        }
+        if (rule.valid_until) {
+            const until = this.parseDate(rule.valid_until, "valid_until");
+            if (now > until)
+                return false;
+        }
+        return true;
+    }
+    match(request) {
+        const originToken = this.tokenRegistry.getToken(request.originAsset);
+        const destinationToken = this.tokenRegistry.getToken(request.destinationAsset);
+        if (!originToken || !destinationToken) {
+            return {
+                matched: false,
+                fee: this.defaultFee,
+            };
+        }
+        for (const rule of this.rules) {
+            if (!rule.enabled)
+                continue;
+            if (!this.isRuleValidNow(rule))
+                continue;
+            const inMatchInfo = this.matchesToken(rule.match.in, originToken);
+            const outMatchInfo = this.matchesToken(rule.match.out, destinationToken);
+            if (inMatchInfo && outMatchInfo) {
+                return {
+                    matched: true,
+                    rule,
+                    fee: rule.fee,
+                    matchDetails: {
+                        originToken,
+                        destinationToken,
+                        in: inMatchInfo,
+                        out: outMatchInfo,
+                    },
+                };
+            }
+        }
+        return {
+            matched: false,
+            fee: this.defaultFee,
+            matchDetails: { originToken, destinationToken },
+        };
+    }
+}

package/dist/src/rule-engine.d.ts

@@ -0,0 +1,21 @@
+import type { Fee, FeeConfig, SwapRequest, MatchResult } from "./types";
+export declare function getTotalBps(fee: Fee | Fee[]): number;
+export declare function calculateFee(amount: string | bigint, bps: number): string;
+export declare function calculateAmountAfterFee(amount: string | bigint, bps: number): string;
+export interface RuleEngineOptions {
+    tokenRegistryUrl?: string;
+    tokenRegistryCacheTtlMs?: number;
+}
+export declare class RuleEngine {
+    private matcher;
+    private tokenRegistry;
+    private feeConfig;
+    constructor(feeConfig: FeeConfig, options?: RuleEngineOptions);
+    initialize(): Promise<void>;
+    ensureReady(): Promise<void>;
+    match(request: SwapRequest): MatchResult;
+    matchWithRefresh(request: SwapRequest): Promise<MatchResult>;
+    getTokenRegistrySize(): number;
+    getFeeConfig(): FeeConfig;
+}
+//# sourceMappingURL=rule-engine.d.ts.map

package/dist/src/rule-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-engine.d.ts","sourceRoot":"","sources":["../../src/rule-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAUxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,EAAE,GAAG,MAAM,CAKpD;AAqCD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKzE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKpF;AAED,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,SAAS,CAAY;gBAEjB,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB;IAcvD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW;IAIlC,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAKlE,oBAAoB,IAAI,MAAM;IAI9B,YAAY,IAAI,SAAS;CAG1B"}

package/dist/src/rule-engine.js

@@ -0,0 +1,94 @@
+import { RuleMatcher } from "./matcher";
+import { CachedTokenRegistry } from "./token-registry";
+import { validateConfig } from "./validator";
+const DEFAULT_TOKEN_REGISTRY_URL = "https://1click.chaindefuser.com/v0/tokens";
+const DEFAULT_CACHE_TTL_MS = 3600000; // 1 hour
+const BPS_DIVISOR = 10000n;
+const MAX_BPS = 10000; // 100% fee cap
+export function getTotalBps(fee) {
+    if (Array.isArray(fee)) {
+        return fee.reduce((sum, f) => sum + f.bps, 0);
+    }
+    return fee.bps;
+}
+function parseAmount(amount) {
+    if (typeof amount === "bigint") {
+        return amount;
+    }
+    if (typeof amount !== "string") {
+        throw new Error(`Invalid amount: expected string or bigint, got ${typeof amount}`);
+    }
+    if (amount.trim() === "") {
+        throw new Error("Invalid amount: empty string");
+    }
+    if (!/^-?\d+$/.test(amount)) {
+        throw new Error(`Invalid amount: "${amount}" is not a valid integer string`);
+    }
+    const result = BigInt(amount);
+    if (result < 0n) {
+        throw new Error(`Invalid amount: "${amount}" must be non-negative`);
+    }
+    return result;
+}
+function validateBps(bps) {
+    if (typeof bps !== "number" || !Number.isFinite(bps)) {
+        throw new Error(`Invalid bps: expected a finite number, got ${bps}`);
+    }
+    if (!Number.isInteger(bps)) {
+        throw new Error(`Invalid bps: ${bps} must be an integer`);
+    }
+    if (bps < 0) {
+        throw new Error(`Invalid bps: ${bps} must be non-negative`);
+    }
+    if (bps > MAX_BPS) {
+        throw new Error(`Invalid bps: ${bps} exceeds maximum of ${MAX_BPS} (100%)`);
+    }
+}
+export function calculateFee(amount, bps) {
+    const amountBigInt = parseAmount(amount);
+    validateBps(bps);
+    const fee = (amountBigInt * BigInt(bps)) / BPS_DIVISOR;
+    return fee.toString();
+}
+export function calculateAmountAfterFee(amount, bps) {
+    const amountBigInt = parseAmount(amount);
+    validateBps(bps);
+    const fee = BigInt(calculateFee(amountBigInt, bps));
+    return (amountBigInt - fee).toString();
+}
+export class RuleEngine {
+    matcher;
+    tokenRegistry;
+    feeConfig;
+    constructor(feeConfig, options) {
+        const validation = validateConfig(feeConfig);
+        if (!validation.valid) {
+            throw new Error(`Invalid fee config: ${validation.errors.map((e) => `${e.path}: ${e.message}`).join(", ")}`);
+        }
+        this.feeConfig = feeConfig;
+        this.tokenRegistry = new CachedTokenRegistry({
+            url: options?.tokenRegistryUrl ?? DEFAULT_TOKEN_REGISTRY_URL,
+            cacheTtlMs: options?.tokenRegistryCacheTtlMs ?? DEFAULT_CACHE_TTL_MS,
+        });
+        this.matcher = new RuleMatcher(this.feeConfig, this.tokenRegistry);
+    }
+    async initialize() {
+        await this.tokenRegistry.refresh();
+    }
+    async ensureReady() {
+        await this.tokenRegistry.ensureFresh();
+    }
+    match(request) {
+        return this.matcher.match(request);
+    }
+    async matchWithRefresh(request) {
+        await this.ensureReady();
+        return this.match(request);
+    }
+    getTokenRegistrySize() {
+        return this.tokenRegistry.size;
+    }
+    getFeeConfig() {
+        return this.feeConfig;
+    }
+}

package/dist/src/token-registry.d.ts

@@ -0,0 +1,20 @@
+import type { TokenInfo, TokenRegistry } from "./types";
+export interface TokenRegistryConfig {
+    url: string;
+    cacheTtlMs: number;
+}
+export declare class CachedTokenRegistry implements TokenRegistry {
+    private config;
+    private cache;
+    private lastFetchTime;
+    private refreshPromise;
+    constructor(config: TokenRegistryConfig);
+    private isCacheValid;
+    refresh(): Promise<void>;
+    private doRefresh;
+    ensureFresh(): Promise<void>;
+    getToken(assetId: string): TokenInfo | undefined;
+    getAllTokens(): TokenInfo[];
+    get size(): number;
+}
+//# sourceMappingURL=token-registry.d.ts.map

package/dist/src/token-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-registry.d.ts","sourceRoot":"","sources":["../../src/token-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAuBD,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,cAAc,CAA8B;gBAExC,MAAM,EAAE,mBAAmB;IAIvC,OAAO,CAAC,YAAY;IAId,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAchB,SAAS;IAoCjB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIhD,YAAY,IAAI,SAAS,EAAE;IAI3B,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/src/token-registry.js

@@ -0,0 +1,78 @@
+function isValidTokenResponse(token) {
+    if (typeof token !== "object" || token === null)
+        return false;
+    const t = token;
+    return (typeof t.assetId === "string" &&
+        typeof t.blockchain === "string" &&
+        typeof t.symbol === "string" &&
+        typeof t.decimals === "number");
+}
+export class CachedTokenRegistry {
+    config;
+    cache = new Map();
+    lastFetchTime = 0;
+    refreshPromise = null;
+    constructor(config) {
+        this.config = config;
+    }
+    isCacheValid() {
+        return Date.now() - this.lastFetchTime < this.config.cacheTtlMs;
+    }
+    async refresh() {
+        // If a refresh is already in progress, return the existing promise
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.doRefresh();
+        try {
+            await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    async doRefresh() {
+        const response = await fetch(this.config.url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch tokens: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        if (!Array.isArray(data)) {
+            throw new Error(`Invalid token registry response: expected array, got ${typeof data}`);
+        }
+        const newCache = new Map();
+        const invalidTokens = [];
+        for (let i = 0; i < data.length; i++) {
+            const token = data[i];
+            if (!isValidTokenResponse(token)) {
+                invalidTokens.push(i);
+                continue;
+            }
+            newCache.set(token.assetId, {
+                assetId: token.assetId,
+                blockchain: token.blockchain,
+                symbol: token.symbol,
+                decimals: token.decimals,
+            });
+        }
+        if (invalidTokens.length > 0 && newCache.size === 0) {
+            throw new Error(`Invalid token registry response: all ${data.length} tokens failed validation`);
+        }
+        this.cache = newCache;
+        this.lastFetchTime = Date.now();
+    }
+    async ensureFresh() {
+        if (!this.isCacheValid()) {
+            await this.refresh();
+        }
+    }
+    getToken(assetId) {
+        return this.cache.get(assetId);
+    }
+    getAllTokens() {
+        return Array.from(this.cache.values());
+    }
+    get size() {
+        return this.cache.size;
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,76 @@
+export interface TokenInfo {
+    assetId: string;
+    blockchain: string;
+    symbol: string;
+    decimals: number;
+}
+/**
+ * Matcher for filtering tokens by blockchain, symbol, or assetId.
+ *
+ * **Important: All string matching is case-sensitive.**
+ * - `symbol: "USDC"` will NOT match a token with symbol `"usdc"` or `"Usdc"`
+ * - `blockchain: "eth"` will NOT match `"ETH"` or `"Eth"`
+ *
+ * Supported patterns:
+ * - Exact match: `"eth"` matches only `"eth"`
+ * - Wildcard: `"*"` matches any value
+ * - Negation: `"!eth"` matches any value except `"eth"`
+ * - Array (OR logic): `["eth", "base"]` matches `"eth"` or `"base"`
+ */
+export interface TokenMatcher {
+    blockchain?: string | string[];
+    symbol?: string | string[];
+    assetId?: string | string[];
+}
+export interface RuleMatch {
+    in: TokenMatcher;
+    out: TokenMatcher;
+}
+export interface Fee {
+    type: "bps";
+    bps: number;
+    recipient: string;
+}
+export interface Rule {
+    id: string;
+    enabled: boolean;
+    priority?: number;
+    description?: string;
+    match: RuleMatch;
+    fee: Fee | Fee[];
+    valid_from?: string;
+    valid_until?: string;
+}
+export interface FeeConfig {
+    version: string;
+    default_fee: Fee | Fee[];
+    rules: Rule[];
+}
+export interface SwapRequest {
+    originAsset: string;
+    destinationAsset: string;
+    amount?: string;
+}
+export interface TokenMatchInfo {
+    token: TokenInfo;
+    matchedBy: {
+        assetId?: boolean;
+        blockchain?: boolean;
+        symbol?: boolean;
+    };
+}
+export interface MatchResult {
+    matched: boolean;
+    rule?: Rule;
+    fee: Fee | Fee[];
+    matchDetails?: {
+        originToken: TokenInfo;
+        destinationToken: TokenInfo;
+        in?: TokenMatchInfo;
+        out?: TokenMatchInfo;
+    };
+}
+export interface TokenRegistry {
+    getToken(assetId: string): TokenInfo | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,YAAY,CAAC;IACjB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,GAAG,GAAG,GAAG,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,GAAG,GAAG,GAAG,EAAE,CAAC;IACzB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE;QACT,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,GAAG,EAAE,GAAG,GAAG,GAAG,EAAE,CAAC;IACjB,YAAY,CAAC,EAAE;QACb,WAAW,EAAE,SAAS,CAAC;QACvB,gBAAgB,EAAE,SAAS,CAAC;QAC5B,EAAE,CAAC,EAAE,cAAc,CAAC;QACpB,GAAG,CAAC,EAAE,cAAc,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;CAClD"}

package/dist/src/validator.d.ts

@@ -0,0 +1,11 @@
+import type { FeeConfig } from "./types";
+export interface ValidationError {
+    path: string;
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export declare function validateConfig(config: FeeConfig): ValidationResult;
+//# sourceMappingURL=validator.d.ts.map

package/dist/src/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAA2B,MAAM,SAAS,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAwDD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAuGD,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,gBAAgB,CAkClE"}

package/dist/src/validator.js

@@ -0,0 +1,175 @@
+const NEAR_ACCOUNT_REGEX = /^(?:[a-z\d]+[-_])*[a-z\d]+(?:\.[a-z\d]+[-_]*[a-z\d]+)*$/;
+const NEAR_IMPLICIT_ACCOUNT_REGEX = /^[a-f0-9]{64}$/;
+const MAX_BPS = 10000; // 100% fee cap
+function isValidNearAccount(account) {
+    if (account.length < 2 || account.length > 64)
+        return false;
+    return NEAR_ACCOUNT_REGEX.test(account) || NEAR_IMPLICIT_ACCOUNT_REGEX.test(account);
+}
+function isValidDateString(dateStr) {
+    const timestamp = new Date(dateStr).getTime();
+    return !Number.isNaN(timestamp);
+}
+function validateSingleFee(fee, path) {
+    const errors = [];
+    if (fee.type !== "bps") {
+        errors.push({ path: `${path}.type`, message: "fee.type must be 'bps'" });
+    }
+    if (typeof fee.bps !== "number" || fee.bps < 0) {
+        errors.push({ path: `${path}.bps`, message: "fee.bps must be a non-negative number" });
+    }
+    else if (fee.bps > MAX_BPS) {
+        errors.push({ path: `${path}.bps`, message: `fee.bps exceeds maximum of ${MAX_BPS} (100%)` });
+    }
+    if (!fee.recipient || typeof fee.recipient !== "string") {
+        errors.push({ path: `${path}.recipient`, message: "fee.recipient is required and must be a string" });
+    }
+    else if (!isValidNearAccount(fee.recipient)) {
+        errors.push({ path: `${path}.recipient`, message: "fee.recipient must be a valid NEAR account" });
+    }
+    return errors;
+}
+function validateFee(fee, path) {
+    const errors = [];
+    if (Array.isArray(fee)) {
+        if (fee.length === 0) {
+            errors.push({ path, message: "fee array must not be empty" });
+            return errors;
+        }
+        for (let i = 0; i < fee.length; i++) {
+            errors.push(...validateSingleFee(fee[i], `${path}[${i}]`));
+        }
+    }
+    else if (fee && typeof fee === "object") {
+        errors.push(...validateSingleFee(fee, path));
+    }
+    else {
+        errors.push({ path, message: "fee is required" });
+    }
+    return errors;
+}
+function isNonEmptyStringOrArray(value) {
+    if (typeof value === "string")
+        return value.length > 0;
+    if (Array.isArray(value))
+        return value.length > 0 && value.every((v) => typeof v === "string" && v.length > 0);
+    return false;
+}
+function validateTokenMatcher(matcher, path) {
+    const errors = [];
+    // Check for empty arrays
+    if (Array.isArray(matcher.blockchain) && matcher.blockchain.length === 0) {
+        errors.push({ path: `${path}.blockchain`, message: "blockchain array must not be empty" });
+    }
+    if (Array.isArray(matcher.symbol) && matcher.symbol.length === 0) {
+        errors.push({ path: `${path}.symbol`, message: "symbol array must not be empty" });
+    }
+    if (Array.isArray(matcher.assetId) && matcher.assetId.length === 0) {
+        errors.push({ path: `${path}.assetId`, message: "assetId array must not be empty" });
+    }
+    // Check for empty strings in arrays
+    if (Array.isArray(matcher.blockchain) && matcher.blockchain.some((v) => v === "")) {
+        errors.push({ path: `${path}.blockchain`, message: "blockchain array must not contain empty strings" });
+    }
+    if (Array.isArray(matcher.symbol) && matcher.symbol.some((v) => v === "")) {
+        errors.push({ path: `${path}.symbol`, message: "symbol array must not contain empty strings" });
+    }
+    if (Array.isArray(matcher.assetId) && matcher.assetId.some((v) => v === "")) {
+        errors.push({ path: `${path}.assetId`, message: "assetId array must not contain empty strings" });
+    }
+    const hasIdentifier = isNonEmptyStringOrArray(matcher.blockchain) ||
+        isNonEmptyStringOrArray(matcher.symbol) ||
+        isNonEmptyStringOrArray(matcher.assetId);
+    if (!hasIdentifier) {
+        errors.push({
+            path,
+            message: "At least one of blockchain, symbol, or assetId must be defined",
+        });
+    }
+    return errors;
+}
+function validateRule(rule, index) {
+    const errors = [];
+    const path = `rules[${index}]`;
+    if (!rule.id || typeof rule.id !== "string") {
+        errors.push({ path: `${path}.id`, message: "id is required and must be a string" });
+    }
+    if (typeof rule.enabled !== "boolean") {
+        errors.push({ path: `${path}.enabled`, message: "enabled is required and must be a boolean" });
+    }
+    if (rule.priority !== undefined && (typeof rule.priority !== "number" || rule.priority < 0)) {
+        errors.push({ path: `${path}.priority`, message: "priority must be a non-negative number" });
+    }
+    if (!rule.match) {
+        errors.push({ path: `${path}.match`, message: "match is required" });
+    }
+    else {
+        if (!rule.match.in) {
+            errors.push({ path: `${path}.match.in`, message: "match.in is required" });
+        }
+        else {
+            errors.push(...validateTokenMatcher(rule.match.in, `${path}.match.in`));
+        }
+        if (!rule.match.out) {
+            errors.push({ path: `${path}.match.out`, message: "match.out is required" });
+        }
+        else {
+            errors.push(...validateTokenMatcher(rule.match.out, `${path}.match.out`));
+        }
+    }
+    if (!rule.fee) {
+        errors.push({ path: `${path}.fee`, message: "fee is required" });
+    }
+    else {
+        errors.push(...validateFee(rule.fee, `${path}.fee`));
+    }
+    if (rule.valid_from !== undefined) {
+        if (typeof rule.valid_from !== "string") {
+            errors.push({ path: `${path}.valid_from`, message: "valid_from must be a string" });
+        }
+        else if (!isValidDateString(rule.valid_from)) {
+            errors.push({ path: `${path}.valid_from`, message: `valid_from "${rule.valid_from}" is not a valid date string` });
+        }
+    }
+    if (rule.valid_until !== undefined) {
+        if (typeof rule.valid_until !== "string") {
+            errors.push({ path: `${path}.valid_until`, message: "valid_until must be a string" });
+        }
+        else if (!isValidDateString(rule.valid_until)) {
+            errors.push({ path: `${path}.valid_until`, message: `valid_until "${rule.valid_until}" is not a valid date string` });
+        }
+    }
+    return errors;
+}
+export function validateConfig(config) {
+    const errors = [];
+    if (!config.version || typeof config.version !== "string") {
+        errors.push({ path: "version", message: "version is required and must be a string" });
+    }
+    if (!config.default_fee) {
+        errors.push({ path: "default_fee", message: "default_fee is required" });
+    }
+    else {
+        errors.push(...validateFee(config.default_fee, "default_fee"));
+    }
+    if (!Array.isArray(config.rules)) {
+        errors.push({ path: "rules", message: "rules must be an array" });
+    }
+    else {
+        const ruleIds = new Set();
+        for (let i = 0; i < config.rules.length; i++) {
+            const rule = config.rules[i];
+            errors.push(...validateRule(rule, i));
+            if (rule.id) {
+                if (ruleIds.has(rule.id)) {
+                    errors.push({ path: `rules[${i}].id`, message: `Duplicate rule id: ${rule.id}` });
+                }
+                ruleIds.add(rule.id);
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "intents-1click-rule-engine",
+  "version": "1.0.0",
+  "description": "Fee configuration rule engine for NEAR Intents 1Click API",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "near",
+    "intents",
+    "1click",
+    "fee",
+    "rules",
+    "swap"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}