slash-tokens 1.3.0 → 1.4.0

package/README.md

@@ -17,10 +17,15 @@ 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 +54,10 @@ 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)**
 
+## Brand
+
+By using the SDK, you agree not to use the ⚡slash-tokens brand or colors for your app without written consent. Violators will get a takedown request issued immediately.
+
+## License
+
 [slashtokens.com](https://slashtokens.com) | MIT

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.0",
   "description": "Token Optimization for Context Engineers. 4.8 KB WASM. Sub-millisecond. Zero dependencies.",
   "main": "dist/index.js",
   "module": "dist/index.js",