feat(web-sdk): add full TypeScript definitions and improve TS support#403

Author: sakirr05

sdk/runanywhere-web/README.md

@@ -162,6 +162,59 @@ module.exports = {
 
 ---
 
+## TypeScript Usage
+
+`@runanywhere/web` ships with full TypeScript definitions. No `@types/` package is needed.
+
+```typescript
+import {
+  RunAnywhere,
+  SDKEnvironment,
+  SDKError,
+  SDKErrorCode,
+  isSDKError,
+  type SDKInitOptions,    // canonical name (or InitializeOptions alias)
+  type GenerationOptions, // canonical name (or GenerateOptions alias)
+  type ChatMessage,
+  type ModelDescriptor,
+} from '@runanywhere/web';
+
+// Fully typed initialization
+const options: SDKInitOptions = {
+  environment: SDKEnvironment.Development,
+};
+await RunAnywhere.initialize(options);
+
+// Typed generation options (used by backend packages: LlamaCPP, ONNX)
+const genOptions: GenerationOptions = {
+  systemPrompt: 'You are a helpful assistant.',
+  maxTokens: 256,
+  temperature: 0.7,
+};
+
+// Typed error handling
+try {
+  // ... any SDK call (e.g. loadModel, or backend TextGeneration.generate, etc.)
+} catch (error) {
+  if (isSDKError(error)) {
+    switch (error.code) {
+      case SDKErrorCode.NotInitialized:
+        console.error('Call RunAnywhere.initialize() first.');
+        break;
+      case SDKErrorCode.ModelNotLoaded:
+        console.error('Load a model first.');
+        break;
+      default:
+        console.error('SDK error:', error.message);
+    }
+  }
+}
+```
+
+Note: `InitializeOptions` is a convenience alias for `SDKInitOptions`; `GenerateOptions` for `GenerationOptions`. Backend-specific APIs (e.g. `TextGeneration`, `STT`, `TTS`) live in `@runanywhere/web-llamacpp` and `@runanywhere/web-onnx` when using the split-package layout.
+
+---
+
 ## Quick Start
 
 ### 1. Initialize the SDK

sdk/runanywhere-web/packages/core/package.json

@@ -5,58 +5,44 @@
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/types/index.d.ts",
   "sideEffects": false,
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
-  "files": [
-    "dist/",
-    "README.md"
-  ],
+  "files": ["dist", "README.md"],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "lint": "tsc --noEmit",
+    "lint": "eslint src --max-warnings 0",
+"lint:ts": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
+    "test:types": "tsd",
+    "test": "tsd",
+    "test:e2e": "npm run build && (cd ../../../../examples/web/RunAnywhereAI && npm run build)",
     "clean": "rm -rf dist",
     "prepublishOnly": "test -d dist || (echo 'ERROR: Not built. Run npm run build first.' && exit 1)"
   },
-  "keywords": [
-    "runanywhere",
-    "ai",
-    "llm",
-    "stt",
-    "tts",
-    "vad",
-    "wasm",
-    "webgpu",
-    "on-device",
-    "browser",
-    "inference"
-  ],
+  "keywords": ["runanywhere", "ai", "llm", "stt", "tts", "vad", "wasm", "webgpu", "on-device", "browser", "inference"],
   "author": "RunAnywhere AI",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/RunanywhereAI/runanywhere-sdks.git",
-    "directory": "sdk/runanywhere-web/packages/core"
-  },
+  "repository": {"type": "git", "url": "https://github.com/RunanywhereAI/runanywhere-sdks.git", "directory": "sdk/runanywhere-web/packages/core"},
   "homepage": "https://github.com/RunanywhereAI/runanywhere-sdks/tree/main/sdk/runanywhere-web",
-  "bugs": {
-    "url": "https://github.com/RunanywhereAI/runanywhere-sdks/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
+  "bugs": {"url": "https://github.com/RunanywhereAI/runanywhere-sdks/issues"},
+  "publishConfig": {"access": "public"},
+  "engines": {"node": ">=18.0.0"},
   "peerDependencies": {},
+  "tsd": {
+    "directory": "src/__tests__"
+  },
   "devDependencies": {
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "tsd": "^0.33.0",
+    "eslint": "^9.0.0",
+    "@eslint/js": "^9.0.0",
+    "typescript-eslint": "^8.0.0"
   }
 }

sdk/runanywhere-web/packages/core/src/Foundation/ErrorTypes.ts

@@ -119,3 +119,8 @@ export class SDKError extends Error {
     );
   }
 }
+
+/** Type guard: returns true if the value is an SDKError instance. */
+export function isSDKError(error: unknown): error is SDKError {
+  return error instanceof SDKError;
+}

sdk/runanywhere-web/packages/core/src/Infrastructure/LocalFileStorage.ts

@@ -35,7 +35,6 @@ const logger = new SDKLogger('LocalFileStorage');
 // (Not yet in standard TypeScript DOM lib)
 // ---------------------------------------------------------------------------
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
 interface FileSystemPermissionDescriptor {
   mode: 'read' | 'readwrite';
 }
@@ -44,7 +43,6 @@ interface FileSystemHandlePermissionMethods {
   queryPermission(descriptor: FileSystemPermissionDescriptor): Promise<PermissionState>;
   requestPermission(descriptor: FileSystemPermissionDescriptor): Promise<PermissionState>;
 }
-/* eslint-enable @typescript-eslint/no-explicit-any */
 
 // ---------------------------------------------------------------------------
 // IndexedDB Constants
@@ -128,8 +126,8 @@ export class LocalFileStorage {
 
     try {
       // showDirectoryPicker requires user gesture (button click)
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      this.dirHandle = await (window as any).showDirectoryPicker({
+      const win = window as Window & { showDirectoryPicker?(options?: { mode?: 'read' | 'readwrite' }): Promise<FileSystemDirectoryHandle> };
+      this.dirHandle = await win.showDirectoryPicker!({
         mode: 'readwrite',
       });
 
@@ -423,8 +421,7 @@ export class LocalFileStorage {
 
     const models: Array<{ id: string; sizeBytes: number; lastModified: number }> = [];
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    for await (const [name, handle] of (this.dirHandle as any).entries()) {
+    for await (const [name, handle] of this.dirHandle.entries()) {
       if (handle.kind === 'file') {
         const file = await (handle as FileSystemFileHandle).getFile();
         models.push({

sdk/runanywhere-web/packages/core/src/Infrastructure/ModelManager.ts

@@ -424,8 +424,7 @@ class ModelManagerImpl {
     try {
       const root = await navigator.storage.getDirectory();
       const modelsDir = await root.getDirectoryHandle('models');
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      for await (const [name, handle] of (modelsDir as any).entries()) {
+      for await (const [name, handle] of modelsDir.entries()) {
         if (handle.kind === 'file' && !name.startsWith('_')) {
           modelCount++;
           const file = await (handle as FileSystemFileHandle).getFile();

sdk/runanywhere-web/packages/core/src/Infrastructure/OPFSStorage.ts

@@ -294,7 +294,7 @@ export class OPFSStorage {
 
     const models: StoredModelInfo[] = [];
 
-    for await (const [name, handle] of (this.modelsDir as any).entries()) {
+    for await (const [name, handle] of this.modelsDir.entries()) {
       if (handle.kind === 'file') {
         const file = await (handle as FileSystemFileHandle).getFile();
         models.push({

sdk/runanywhere-web/packages/core/src/Public/RunAnywhere.ts

@@ -26,6 +26,16 @@ import { ExtensionRegistry } from '../Infrastructure/ExtensionRegistry';
 import { ExtensionPoint } from '../Infrastructure/ExtensionPoint';
 import { LocalFileStorage } from '../Infrastructure/LocalFileStorage';
 
+/** Options for showOpenFilePicker. */
+interface OpenFilePickerOptions {
+  types?: Array<{ description?: string; accept?: { [k: string]: string[] } }>;
+  multiple?: boolean;
+}
+/** Window with File System Access API (showOpenFilePicker). */
+interface WindowWithFilePicker extends Window {
+  showOpenFilePicker?(options?: OpenFilePickerOptions): Promise<FileSystemFileHandle[]>;
+}
+
 const logger = new SDKLogger('RunAnywhere');
 
 // ---------------------------------------------------------------------------
@@ -164,11 +174,9 @@ export const RunAnywhere = {
   async importModelFromPicker(options?: { modelId?: string; accept?: string[] }): Promise<string | null> {
     const acceptExts = options?.accept ?? ['.gguf', '.onnx', '.bin'];
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     if ('showOpenFilePicker' in window) {
       try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const [handle] = await (window as any).showOpenFilePicker({
+        const [handle] = await (window as WindowWithFilePicker).showOpenFilePicker!({
           types: [{
             description: 'AI Model Files',
             accept: { 'application/octet-stream': acceptExts },

sdk/runanywhere-web/packages/core/src/__tests__/types.test-d.ts

@@ -0,0 +1,67 @@
+/**
+ * Type-level tests for @runanywhere/web public API.
+ * Run with: npx tsd
+ */
+import { expectType } from 'tsd';
+import {
+  RunAnywhere,
+  SDKEnvironment,
+  SDKError,
+  SDKErrorCode,
+  isSDKError,
+  DownloadStage,
+  type GenerateOptions,
+  type ChatMessage,
+  type ModelDescriptor,
+  type DownloadProgress,
+  type IRunAnywhere,
+} from '../index';
+
+// InitializeOptions (SDKInitOptions) must accept environment
+type InitOptions = Parameters<(typeof RunAnywhere)['initialize']>[0];
+const opts: InitOptions = {
+  environment: SDKEnvironment.Development,
+};
+expectType<Promise<void>>(RunAnywhere.initialize(opts));
+
+// GenerateOptions.onToken must be optional
+const genOpts: GenerateOptions = { temperature: 0.8 };
+expectType<number | undefined>(genOpts.temperature);
+
+// isSDKError must be a type guard
+const e: unknown = new SDKError(SDKErrorCode.NotInitialized, 'test');
+if (isSDKError(e)) {
+  const code: SDKErrorCode = e.code;
+  expectType<SDKErrorCode>(code);
+}
+
+// ChatMessage role must be a union literal
+const msg: ChatMessage = { role: 'user', content: 'Hello' };
+expectType<'user' | 'assistant' | 'system'>(msg.role);
+
+// role must not accept arbitrary strings
+// @ts-expect-error role must not accept 'admin'
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- intentional for type test
+const bad: ChatMessage = { role: 'admin', content: 'x' };
+
+// ModelDescriptor and DownloadProgress are exported
+const desc: ModelDescriptor = {
+  id: 'm1',
+  name: 'Model',
+  url: 'https://example.com/m.gguf',
+  memoryRequirement: 1e9,
+};
+expectType<string>(desc.id);
+
+const prog: DownloadProgress = {
+  modelId: 'm1',
+  stage: DownloadStage.Downloading,
+  progress: 0.5,
+  bytesDownloaded: 100,
+  totalBytes: 200,
+};
+expectType<number>(prog.progress);
+
+// IRunAnywhere must be satisfied by the RunAnywhere export
+const sdk: IRunAnywhere = RunAnywhere;
+expectType<IRunAnywhere>(sdk);

sdk/runanywhere-web/packages/core/src/index.ts

@@ -33,7 +33,7 @@ export type { VoicePipelineCallbacks, VoicePipelineOptions, VoicePipelineTurnRes
 export * from './types';
 
 // Foundation
-export { SDKError, SDKErrorCode } from './Foundation/ErrorTypes';
+export { SDKError, SDKErrorCode, isSDKError } from './Foundation/ErrorTypes';
 export { SDKLogger, LogLevel } from './Foundation/SDKLogger';
 export { EventBus } from './Foundation/EventBus';
 export type { EventListener, Unsubscribe, SDKEventEnvelope } from './Foundation/EventBus';