slash-tokens 1.3.0 → 1.4.1

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 James Wolfe (wolfejam)
+
+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.
+
+---
+
+This project's name, ⚡ mark, and red/gold color scheme ("brand") are not
+covered by the MIT license above and are reserved for the slash-tokens
+project. If you fork, you agree to ship your derivative under your own name
+and colors. Representing your product as "slash-tokens" / "Slash" without
+written consent is not permitted.

package/README.md

@@ -1,26 +1,35 @@
 # /slash-tokens
 
 [![CI/CD](https://github.com/Wolfe-Jam/slash-tokens/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/Wolfe-Jam/slash-tokens/actions/workflows/test.yml)
-[![npm version](https://img.shields.io/npm/v/slash-tokens.svg)](https://www.npmjs.com/package/slash-tokens)
-[![npm downloads](https://img.shields.io/npm/dm/slash-tokens.svg)](https://www.npmjs.com/package/slash-tokens)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/slash-tokens)](https://bundlephobia.com/package/slash-tokens)
-[![license](https://img.shields.io/npm/l/slash-tokens.svg)](./LICENSE)
+[![npm version](https://img.shields.io/npm/v/slash-tokens?style=flat&color=cb3837)](https://www.npmjs.com/package/slash-tokens)
+[![npm downloads](https://img.shields.io/npm/dm/slash-tokens?style=flat&color=brightgreen)](https://www.npmjs.com/package/slash-tokens)
+[![WASM size](https://img.shields.io/badge/WASM-4.8_KB-blue?style=flat)](https://bundlephobia.com/package/slash-tokens)
+[![license](https://img.shields.io/npm/l/slash-tokens?style=flat)](./LICENSE)
 [![⭐ Star on GitHub](https://img.shields.io/badge/%E2%AD%90_Star-black?logo=github&logoColor=white)](https://github.com/Wolfe-Jam/slash-tokens)
 
 Token Optimization for Context Engineers.
 For anyone building with LLMs. 4.8 KB WASM. Sub-millisecond. Zero dependencies.
 
-> 🆕 **v1.3 — The Opus 4.7 Edition.** Same-day support for Claude Opus 4.7 with measured token calibration (1.16–1.51x). Plus Gemini proxy fix and benchmark harness for any upstream.
+Know the cost before the call leaves your machine.
+
+> 🆕 **v1.4 — The Single-Source-of-Truth Edition.** New `preflightRoute()` matches the Slash proxy exactly — same-provider only, zero routing drift. `PROVIDER_MODELS` is now the single source of truth across the SDK.
+>
+> **v1.3 — The Opus 4.7 Edition.** Same-day support for Claude Opus 4.7 with measured token calibration (1.16–1.51x). Plus Gemini proxy fix and benchmark harness for any upstream.
 
 ```bash
 npm install slash-tokens
 ```
 
 ```js
-import { preflight } from 'slash-tokens'
+import { preflight, preflightRoute } from 'slash-tokens'
 
+// Analysis — all cheaper alternatives across all providers
 const check = preflight(prompt, 'claude-opus-4.7')
 // tokens: 47,000 | cost: $0.71 | 11 cheaper options | save 99%
+
+// Routing decision — matches Slash proxy behavior (same-provider only)
+const route = preflightRoute(prompt, 'claude-opus-4.7')
+// → { model: 'claude-haiku', cost: 0.14, salvaged: 0.57, ... } or null
 ```
 
 Or one line — every API call optimized pre-call:
@@ -49,4 +58,12 @@ Track savings across all your apps. Free key at [mcpaas.live/slash/setup](https:
 
 Full docs, examples, and model pricing at **[GitHub](https://github.com/Wolfe-Jam/slash-tokens)**
 
-[slashtokens.com](https://slashtokens.com) | MIT
+## License
+
+**Code: MIT.** Fork it, ship it, change it, sell it.
+
+**Brand: reserved.** The slash-tokens name, ⚡ mark, and red/gold colors stay with the project. If you're building on top of the SDK, ship under your own name and colors — don't represent your app as Slash.
+
+---
+
+🏎️ *Don't go to the Corner Shop in a Ferrari.* · [slashtokens.com](https://slashtokens.com)

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { slash, slashBytes } from './slash.js';
-export { preflight } from './preflight.js';
+export { preflight, preflightRoute } from './preflight.js';
 export type { PreflightResult, Alternative } from './preflight.js';
+export { PROVIDER_MODELS, providerOf } from './providers.js';
 export { MODELS, listModels } from './models.js';
 export type { ModelInfo } from './models.js';
 export { report } from './transact.js';

package/dist/index.js

@@ -1,7 +1,9 @@
 // Core estimation
 export { slash, slashBytes } from './slash.js';
 // Pre-flight checks
-export { preflight } from './preflight.js';
+export { preflight, preflightRoute } from './preflight.js';
+// Provider groups (shared between preflight + intercept — single source of truth)
+export { PROVIDER_MODELS, providerOf } from './providers.js';
 // Model intelligence
 export { MODELS, listModels } from './models.js';
 // Transaction reporting

package/dist/intercept.js

@@ -1,13 +1,7 @@
 import { slash } from './slash.js';
 import { getModel } from './models.js';
 import { shouldRoute, isModelAllowed } from './config.js';
-// Provider groups — routing only happens within same provider
-const PROVIDER_MODELS = {
-    'Anthropic': ['claude-opus', 'claude-sonnet', 'claude-haiku'],
-    'OpenAI': ['gpt-5.4', 'gpt-5.4-mini', 'gpt-5.4-nano'],
-    'xAI': ['grok-4.20', 'grok-4-1-fast'],
-    'Google': ['gemini-3.1-pro', 'gemini-2.5-flash'],
-};
+import { PROVIDER_MODELS } from './providers.js';
 // Reverse lookup: model name → provider model names in the API
 // (what to put back in the request body)
 const MODEL_API_NAMES = {

package/dist/preflight.d.ts

@@ -13,4 +13,43 @@ export interface PreflightResult {
     utilization: number;
     options: Alternative[];
 }
+/**
+ * Analysis tool — returns ALL cheaper models across ALL providers.
+ *
+ * Use this to SHOW developers what their alternatives are, regardless of
+ * whether Slash would actually route there. If you want "what will the
+ * Slash proxy ACTUALLY route to right now?", use `preflightRoute()`.
+ *
+ * TEST-NOTE (critical):
+ *   - `options` is intentionally cross-provider — this is an analysis tool.
+ *   - `options[0]` is NOT the routing decision. Using it as such is a bug.
+ *   - See `preflightRoute()` for the actual routing decision that matches
+ *     the mcpaas-cf proxy's findCheapestRoute semantics.
+ *   - A test should assert that preflight().options may contain cross-provider
+ *     entries (e.g. given model='claude-opus', options[0]?.model CAN be 'grok-...').
+ */
 export declare function preflight(content: string, model: string): PreflightResult;
+/**
+ * Routing decision — matches mcpaas-cf proxy's `findCheapestRoute` exactly.
+ *
+ * Returns the single cheapest SAME-PROVIDER alternative that fits the prompt,
+ * or null if no cheaper same-provider option exists (or model unknown,
+ * or model's provider unknown).
+ *
+ * This is what you want to display as "what would Slash route to" — it
+ * matches the proxy's actual behavior.
+ *
+ * TEST-NOTE (critical, must never regress):
+ *   - Same-provider only. `preflightRoute('hello', 'claude-opus')` must NEVER
+ *     return a model outside Anthropic. Add a test that asserts this for every
+ *     canonical model in PROVIDER_MODELS.
+ *   - Returns null when: model unknown, provider unknown, or no cheaper same-
+ *     provider alternative exists. Null is a valid result ("PASS, no route").
+ *   - Cheapest SAME-PROVIDER alternative by input price. If two alternatives
+ *     tie on price (unlikely but possible), returns the first encountered in
+ *     PROVIDER_MODELS order.
+ *   - Must agree with intercept.ts findCheapestRoute for identical inputs.
+ *     Cross-function semantic test: given the same (provider, tokens, model),
+ *     both functions return the same model name.
+ */
+export declare function preflightRoute(content: string, model: string): Alternative | null;

package/dist/preflight.js

@@ -1,27 +1,105 @@
 import { slash } from './slash.js';
 import { getModel, MODELS } from './models.js';
+import { PROVIDER_MODELS, providerOf } from './providers.js';
+/**
+ * Compute cost of a prompt of `tokens` tokens on the given ModelInfo.
+ * Uses input-token price only (output is not known at preflight time).
+ * Rounded to 6 decimals.
+ */
+function computeCost(tokens, info) {
+    return Math.round(((tokens / 1000000) * info.input) * 1000000) / 1000000;
+}
+function buildAlternative(model, originalCost, tokens, info) {
+    const altCost = computeCost(tokens, info);
+    return {
+        model,
+        cost: altCost,
+        salvaged: Math.round((originalCost - altCost) * 1000000) / 1000000,
+        salvagePercent: originalCost > 0 ? Math.round(((originalCost - altCost) / originalCost) * 10000) / 100 : 0,
+    };
+}
+/**
+ * Analysis tool — returns ALL cheaper models across ALL providers.
+ *
+ * Use this to SHOW developers what their alternatives are, regardless of
+ * whether Slash would actually route there. If you want "what will the
+ * Slash proxy ACTUALLY route to right now?", use `preflightRoute()`.
+ *
+ * TEST-NOTE (critical):
+ *   - `options` is intentionally cross-provider — this is an analysis tool.
+ *   - `options[0]` is NOT the routing decision. Using it as such is a bug.
+ *   - See `preflightRoute()` for the actual routing decision that matches
+ *     the mcpaas-cf proxy's findCheapestRoute semantics.
+ *   - A test should assert that preflight().options may contain cross-provider
+ *     entries (e.g. given model='claude-opus', options[0]?.model CAN be 'grok-...').
+ */
 export function preflight(content, model) {
     const tokens = slash(content);
     const info = getModel(model);
     if (!info) {
         throw new Error(`Unknown model: "${model}". Available: ${Object.keys(MODELS).join(', ')}`);
     }
-    const cost = Math.round(((tokens / 1000000) * info.input) * 1000000) / 1000000;
+    const cost = computeCost(tokens, info);
     const fits = tokens <= info.context;
     const utilization = Math.round((tokens / info.context) * 10000) / 10000;
     const options = Object.entries(MODELS)
         .filter(([m]) => m !== model)
-        .filter(([_, v]) => v.context >= tokens)
-        .map(([m, v]) => {
-        const altCost = Math.round(((tokens / 1000000) * v.input) * 1000000) / 1000000;
-        return {
-            model: m,
-            cost: altCost,
-            salvaged: Math.round((cost - altCost) * 1000000) / 1000000,
-            salvagePercent: cost > 0 ? Math.round(((cost - altCost) / cost) * 10000) / 100 : 0,
-        };
-    })
+        .filter(([, v]) => v.context >= tokens)
+        .map(([m, v]) => buildAlternative(m, cost, tokens, v))
         .filter(o => o.salvaged > 0)
         .sort((a, b) => a.cost - b.cost);
     return { tokens, cost, fits, model, context: info.context, utilization, options };
 }
+/**
+ * Routing decision — matches mcpaas-cf proxy's `findCheapestRoute` exactly.
+ *
+ * Returns the single cheapest SAME-PROVIDER alternative that fits the prompt,
+ * or null if no cheaper same-provider option exists (or model unknown,
+ * or model's provider unknown).
+ *
+ * This is what you want to display as "what would Slash route to" — it
+ * matches the proxy's actual behavior.
+ *
+ * TEST-NOTE (critical, must never regress):
+ *   - Same-provider only. `preflightRoute('hello', 'claude-opus')` must NEVER
+ *     return a model outside Anthropic. Add a test that asserts this for every
+ *     canonical model in PROVIDER_MODELS.
+ *   - Returns null when: model unknown, provider unknown, or no cheaper same-
+ *     provider alternative exists. Null is a valid result ("PASS, no route").
+ *   - Cheapest SAME-PROVIDER alternative by input price. If two alternatives
+ *     tie on price (unlikely but possible), returns the first encountered in
+ *     PROVIDER_MODELS order.
+ *   - Must agree with intercept.ts findCheapestRoute for identical inputs.
+ *     Cross-function semantic test: given the same (provider, tokens, model),
+ *     both functions return the same model name.
+ */
+export function preflightRoute(content, model) {
+    const tokens = slash(content);
+    const info = getModel(model);
+    if (!info)
+        return null;
+    const provider = providerOf(model);
+    if (!provider)
+        return null;
+    const providerModels = PROVIDER_MODELS[provider];
+    if (!providerModels)
+        return null;
+    const originalCost = computeCost(tokens, info);
+    let cheapest = null;
+    for (const m of providerModels) {
+        if (m === model)
+            continue;
+        const altInfo = getModel(m);
+        if (!altInfo)
+            continue;
+        if (tokens > altInfo.context)
+            continue; // doesn't fit
+        if (altInfo.input >= info.input)
+            continue; // not cheaper
+        const alt = buildAlternative(m, originalCost, tokens, altInfo);
+        if (!cheapest || alt.cost < cheapest.cost) {
+            cheapest = alt;
+        }
+    }
+    return cheapest;
+}

package/dist/providers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Provider groups — single source of truth.
+ *
+ * Slash routing is always SAME-PROVIDER. Opus → Haiku, GPT-5.4 → Nano,
+ * Grok-4.20 → Fast, Gemini 3.1 Pro → 2.5 Flash. Never cross-provider.
+ *
+ * This file is the canonical provider mapping. Both `intercept.ts`
+ * (runtime fetch patching) and `preflight.ts` (analysis + routing
+ * prediction) consume from here so they can never drift.
+ *
+ * TEST-NOTE: Whenever a new model is added, it MUST appear in exactly one
+ * provider group below. A model missing from here will:
+ *   - Never be a routing target from `findCheapestRoute` / `preflightRoute`
+ *   - Still appear in `preflight().options` (which is cross-provider analysis)
+ *   That mismatch is by design — see preflight.ts semantics.
+ */
+export declare const PROVIDER_MODELS: Record<string, string[]>;
+/**
+ * Identify a model's provider from its canonical key.
+ *
+ * TEST-NOTE: This function MUST return a non-null provider for every model
+ * present in `MODELS` (from models.ts). If `MODELS` adds a model without
+ * adding it to `PROVIDER_MODELS`, this returns null and routing is disabled
+ * for that model. Silent skip.
+ */
+export declare function providerOf(model: string): string | null;

package/dist/providers.js

@@ -0,0 +1,37 @@
+/**
+ * Provider groups — single source of truth.
+ *
+ * Slash routing is always SAME-PROVIDER. Opus → Haiku, GPT-5.4 → Nano,
+ * Grok-4.20 → Fast, Gemini 3.1 Pro → 2.5 Flash. Never cross-provider.
+ *
+ * This file is the canonical provider mapping. Both `intercept.ts`
+ * (runtime fetch patching) and `preflight.ts` (analysis + routing
+ * prediction) consume from here so they can never drift.
+ *
+ * TEST-NOTE: Whenever a new model is added, it MUST appear in exactly one
+ * provider group below. A model missing from here will:
+ *   - Never be a routing target from `findCheapestRoute` / `preflightRoute`
+ *   - Still appear in `preflight().options` (which is cross-provider analysis)
+ *   That mismatch is by design — see preflight.ts semantics.
+ */
+export const PROVIDER_MODELS = {
+    Anthropic: ['claude-opus', 'claude-opus-4.7', 'claude-sonnet', 'claude-haiku'],
+    OpenAI: ['gpt-5.4', 'gpt-5.4-mini', 'gpt-5.4-nano'],
+    xAI: ['grok-4.20', 'grok-4-1-fast'],
+    Google: ['gemini-3.1-pro', 'gemini-2.5-flash'],
+};
+/**
+ * Identify a model's provider from its canonical key.
+ *
+ * TEST-NOTE: This function MUST return a non-null provider for every model
+ * present in `MODELS` (from models.ts). If `MODELS` adds a model without
+ * adding it to `PROVIDER_MODELS`, this returns null and routing is disabled
+ * for that model. Silent skip.
+ */
+export function providerOf(model) {
+    for (const [provider, models] of Object.entries(PROVIDER_MODELS)) {
+        if (models.includes(model))
+            return provider;
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slash-tokens",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Token Optimization for Context Engineers. 4.8 KB WASM. Sub-millisecond. Zero dependencies.",
   "main": "dist/index.js",
   "module": "dist/index.js",