@motebit/sdk 0.6.11 → 0.8.0

package/dist/provider-mode.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Top-level provider mode — the user's intent, not the concrete vendor.
+ *
+ * - `on-device`: the user wants inference to run locally (privacy, offline, latency).
+ * - `motebit-cloud`: the user wants the default product experience (subscription, auto-routing).
+ * - `byok`: the user brings their own API key to a named vendor.
+ */
+export type ProviderMode = "on-device" | "motebit-cloud" | "byok";
+/**
+ * On-device backend kinds. Not every backend is available on every platform:
+ *
+ * - `apple-fm`: Apple Foundation Models (iOS/macOS 26+ only).
+ * - `mlx`: MLX runtime (Apple Silicon, iOS 16+ / macOS).
+ * - `webllm`: MLC WebLLM in-browser (web surface + WebGPU only).
+ * - `local-server`: auto-detected local OpenAI-compatible server
+ *   (Ollama, LM Studio, llama.cpp, Jan, vLLM, …). Vendor-agnostic.
+ */
+export type OnDeviceBackend = "apple-fm" | "mlx" | "webllm" | "local-server";
+/** BYOK vendors — the only ones where the user holds the API key directly. */
+export type ByokVendor = "anthropic" | "openai" | "google";
+/** On-device mode config. */
+export interface OnDeviceProviderConfig {
+    mode: "on-device";
+    backend: OnDeviceBackend;
+    /** Model identifier. Meaning depends on backend (MLX name, WebLLM id, server tag, …). */
+    model?: string;
+    /** For `local-server`: endpoint URL (e.g., http://localhost:11434). Auto-detected otherwise. */
+    endpoint?: string;
+    /** Optional temperature override. */
+    temperature?: number;
+    /** Optional max_tokens override. */
+    maxTokens?: number;
+}
+/** Motebit Cloud mode config — the subscription-backed product. */
+export interface MotebitCloudProviderConfig {
+    mode: "motebit-cloud";
+    /** Optional preferred model. When omitted, the relay picks. */
+    model?: string;
+    /** Signed proxy token — included as x-proxy-token for authenticated requests. */
+    proxyToken?: string;
+    /** Override proxy base URL (dev/staging). */
+    baseUrl?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+/** BYOK mode config — user supplies the API key. */
+export interface ByokProviderConfig {
+    mode: "byok";
+    vendor: ByokVendor;
+    apiKey: string;
+    model?: string;
+    /**
+     * Optional custom base URL. Used e.g. for Google via the OpenAI-compatible
+     * endpoint (`https://generativelanguage.googleapis.com/v1beta/openai`).
+     */
+    baseUrl?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+/** Union of all three modes. Surfaces persist this shape. */
+export type UnifiedProviderConfig = OnDeviceProviderConfig | MotebitCloudProviderConfig | ByokProviderConfig;
+/**
+ * Heuristic: is this URL pointing at a local inference server?
+ * Shared across all surfaces so the migration behaves identically everywhere.
+ */
+export declare function isLocalServerUrl(url: string | undefined | null): boolean;
+/**
+ * Legacy provider config shape — a superset of every surface's historical fields.
+ * Used only as the input to `migrateLegacyProvider`.
+ */
+export interface LegacyProviderConfig {
+    type?: string;
+    provider?: string;
+    apiKey?: string;
+    api_key?: string;
+    model?: string;
+    baseUrl?: string;
+    base_url?: string;
+    proxyToken?: string;
+    proxy_token?: string;
+    maxTokens?: number;
+    max_tokens?: number;
+    temperature?: number;
+    localBackend?: string;
+    ollamaEndpoint?: string;
+    default_provider?: string;
+    default_model?: string;
+    mode?: string;
+    backend?: string;
+    vendor?: string;
+    endpoint?: string;
+}
+/**
+ * Migrate any legacy provider config shape to `UnifiedProviderConfig`.
+ *
+ * Rules:
+ * - `hybrid` and `proxy` map to `motebit-cloud` (the product).
+ * - `ollama` with a localhost URL maps to `on-device/local-server`.
+ * - `ollama` with a remote URL maps to `on-device/local-server` with that endpoint preserved.
+ * - `anthropic` / `openai` / `google` map to `byok` with that vendor.
+ * - Mobile `local` with `localBackend` maps to `on-device` with that backend.
+ * - If input is already a `UnifiedProviderConfig` (has `mode`), it passes through.
+ *
+ * Returns `null` only if the input is entirely unrecognizable.
+ */
+export declare function migrateLegacyProvider(legacy: LegacyProviderConfig | null | undefined): UnifiedProviderConfig | null;
+/** Sensible default when no config has ever been persisted. */
+export declare function defaultProviderConfig(): MotebitCloudProviderConfig;
+//# sourceMappingURL=provider-mode.d.ts.map

package/dist/provider-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-mode.d.ts","sourceRoot":"","sources":["../src/provider-mode.ts"],"names":[],"mappings":"AAYA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,cAAc,CAAC;AAE7E,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,6BAA6B;AAC7B,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,eAAe,CAAC;IACzB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,eAAe,CAAC;IACtB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,6DAA6D;AAC7D,MAAM,MAAM,qBAAqB,GAC7B,sBAAsB,GACtB,0BAA0B,GAC1B,kBAAkB,CAAC;AAuBvB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAkBxE;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IAEnC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAC9C,qBAAqB,GAAG,IAAI,CAmH9B;AAID,+DAA+D;AAC/D,wBAAgB,qBAAqB,IAAI,0BAA0B,CAElE"}

package/dist/provider-mode.js

@@ -0,0 +1,179 @@
+// === Provider Mode (Three-Mode Architecture) ===
+//
+// User-intent-based provider config — matches the pattern of settlement rails:
+// user picks the capability class, the system resolves the concrete vendor.
+//
+// Flat unions like "ollama" | "anthropic" | "openai" | "hybrid" mix implementation
+// details with user intent. "Hybrid" is an implementation detail, not a user choice.
+// "Ollama" is a vendor name, not a capability class.
+//
+// All surfaces (web, mobile, desktop, cli) persist and exchange this shape.
+// Platform-specific sub-options live inside each mode's discriminated variant.
+// === Migration ===
+//
+// Legacy shapes, in order of historical appearance:
+//
+//   Web (apps/web/src/storage.ts):
+//     { type: "anthropic" | "openai" | "ollama" | "webllm" | "proxy",
+//       apiKey?, model, baseUrl?, proxyToken?, maxTokens?, temperature? }
+//
+//   Mobile (apps/mobile/src/mobile-app.ts):
+//     { provider: "ollama" | "anthropic" | "openai" | "hybrid" | "proxy" | "local",
+//       localBackend?: "apple-fm" | "mlx",
+//       model?, apiKey?, ollamaEndpoint?, maxTokens? }
+//
+//   Desktop (apps/desktop/src/index.ts):
+//     { provider: "anthropic" | "ollama" | "openai" | "proxy" | "hybrid",
+//       model?, apiKey?, maxTokens? }
+//
+//   CLI (apps/cli/src/config.ts):
+//     { default_provider?: "anthropic" | "openai" | "ollama",
+//       default_model?, api_key? (in keyring) }
+/**
+ * Heuristic: is this URL pointing at a local inference server?
+ * Shared across all surfaces so the migration behaves identically everywhere.
+ */
+export function isLocalServerUrl(url) {
+    if (!url)
+        return false;
+    try {
+        const u = new URL(url);
+        const host = u.hostname.toLowerCase();
+        return (host === "localhost" ||
+            host === "127.0.0.1" ||
+            host === "::1" ||
+            host === "0.0.0.0" ||
+            host.endsWith(".local") ||
+            /^10\./.test(host) ||
+            /^192\.168\./.test(host) ||
+            /^172\.(1[6-9]|2\d|3[01])\./.test(host));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Migrate any legacy provider config shape to `UnifiedProviderConfig`.
+ *
+ * Rules:
+ * - `hybrid` and `proxy` map to `motebit-cloud` (the product).
+ * - `ollama` with a localhost URL maps to `on-device/local-server`.
+ * - `ollama` with a remote URL maps to `on-device/local-server` with that endpoint preserved.
+ * - `anthropic` / `openai` / `google` map to `byok` with that vendor.
+ * - Mobile `local` with `localBackend` maps to `on-device` with that backend.
+ * - If input is already a `UnifiedProviderConfig` (has `mode`), it passes through.
+ *
+ * Returns `null` only if the input is entirely unrecognizable.
+ */
+export function migrateLegacyProvider(legacy) {
+    if (!legacy)
+        return null;
+    // Already-new shape — passthrough with light validation.
+    if (legacy.mode === "on-device" || legacy.mode === "motebit-cloud" || legacy.mode === "byok") {
+        return legacy;
+    }
+    const apiKey = legacy.apiKey ?? legacy.api_key;
+    const baseUrl = legacy.baseUrl ?? legacy.base_url;
+    const proxyToken = legacy.proxyToken ?? legacy.proxy_token;
+    const maxTokens = legacy.maxTokens ?? legacy.max_tokens;
+    const temperature = legacy.temperature;
+    const model = legacy.model ?? legacy.default_model;
+    // Normalize the discriminator across shapes.
+    const kind = legacy.type ?? legacy.provider ?? legacy.default_provider;
+    if (!kind)
+        return null;
+    switch (kind) {
+        case "proxy":
+        case "hybrid":
+        case "motebit-cloud":
+            return {
+                mode: "motebit-cloud",
+                model,
+                proxyToken,
+                baseUrl,
+                maxTokens,
+                temperature,
+            };
+        case "anthropic":
+            return {
+                mode: "byok",
+                vendor: "anthropic",
+                apiKey: apiKey ?? "",
+                model,
+                baseUrl,
+                maxTokens,
+                temperature,
+            };
+        case "openai":
+            return {
+                mode: "byok",
+                vendor: "openai",
+                apiKey: apiKey ?? "",
+                model,
+                baseUrl,
+                maxTokens,
+                temperature,
+            };
+        case "google":
+            return {
+                mode: "byok",
+                vendor: "google",
+                apiKey: apiKey ?? "",
+                model,
+                baseUrl,
+                maxTokens,
+                temperature,
+            };
+        case "ollama": {
+            // Ollama is always a local server — endpoint may or may not be localhost.
+            const endpoint = baseUrl ?? legacy.ollamaEndpoint ?? legacy.endpoint;
+            return {
+                mode: "on-device",
+                backend: "local-server",
+                model,
+                endpoint,
+                maxTokens,
+                temperature,
+            };
+        }
+        case "webllm":
+            return {
+                mode: "on-device",
+                backend: "webllm",
+                model,
+                maxTokens,
+                temperature,
+            };
+        case "local": {
+            // Mobile legacy: `local` with `localBackend` sub-option.
+            const backend = (() => {
+                switch (legacy.localBackend) {
+                    case "apple-fm":
+                        return "apple-fm";
+                    case "mlx":
+                        return "mlx";
+                    case "local-server":
+                        return "local-server";
+                    default:
+                        return "mlx";
+                }
+            })();
+            return {
+                mode: "on-device",
+                backend,
+                model,
+                endpoint: legacy.ollamaEndpoint ?? legacy.endpoint,
+                maxTokens,
+                temperature,
+            };
+        }
+        default:
+            return null;
+    }
+}
+// === Defaults ===
+/** Sensible default when no config has ever been persisted. */
+export function defaultProviderConfig() {
+    return { mode: "motebit-cloud" };
+}
+//# sourceMappingURL=provider-mode.js.map

package/dist/provider-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-mode.js","sourceRoot":"","sources":["../src/provider-mode.ts"],"names":[],"mappings":"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"}

package/dist/provider-resolver.d.ts

@@ -0,0 +1,179 @@
+import type { UnifiedProviderConfig, ByokVendor, OnDeviceBackend } from "./provider-mode.js";
+/**
+ * Google's OpenAI-compatible chat completions endpoint. Used when the user
+ * picks Google as a BYOK vendor — Google is dispatched as OpenAI-compat
+ * because every cloud client (web, mobile, desktop, cli) already understands
+ * the OpenAI wire protocol. Single source of truth.
+ */
+export declare const GOOGLE_OPENAI_COMPAT_URL = "https://generativelanguage.googleapis.com/v1beta/openai";
+/** Canonical Anthropic API base URL. */
+export declare const ANTHROPIC_CANONICAL_URL = "https://api.anthropic.com";
+/** Canonical OpenAI API base URL. */
+export declare const OPENAI_CANONICAL_URL = "https://api.openai.com/v1";
+/** Default Motebit Cloud relay URL. Surfaces may override via env. */
+export declare const DEFAULT_MOTEBIT_CLOUD_URL = "https://api.motebit.com";
+/** Default WebLLM model when none specified — small enough to fit on most devices. */
+export declare const DEFAULT_WEBLLM_MODEL = "Llama-3.2-3B-Instruct-q4f16_1-MLC";
+/**
+ * Normalize a local-inference server URL so that it points at the
+ * OpenAI-compatible chat completions base path. Auto-appends `/v1` if
+ * the URL doesn't already contain it. Idempotent.
+ *
+ * Every supported local server (Ollama via its OpenAI shim, LM Studio,
+ * llama.cpp, Jan, vLLM, text-generation-webui) exposes
+ * `{base}/v1/chat/completions`. Users typically type just the host
+ * (`http://localhost:11434`) — this helper completes the path so the
+ * client can call `{normalized}/chat/completions` directly.
+ *
+ * Examples:
+ *   "http://localhost:11434"      → "http://localhost:11434/v1"
+ *   "http://localhost:11434/v1"   → "http://localhost:11434/v1"
+ *   "http://localhost:1234/"      → "http://localhost:1234/v1"
+ *   "http://192.168.1.42:11434"   → "http://192.168.1.42:11434/v1"
+ *   "/api/ollama"                 → "/api/ollama/v1"  (dev proxy path)
+ */
+export declare function normalizeLocalServerEndpoint(url: string): string;
+/** Default chat model for a BYOK vendor. */
+export declare function defaultModelForVendor(vendor: ByokVendor): string;
+/**
+ * Canonical (vendor-published) base URL for a BYOK vendor. Surfaces that
+ * need to substitute a CORS proxy or dev-mode path receive this canonical
+ * URL via the resolver and may rewrite it.
+ */
+export declare function canonicalVendorBaseUrl(vendor: ByokVendor): string;
+/**
+ * Discriminated union describing what concrete provider class the surface
+ * should instantiate, with all decision logic already resolved. The surface's
+ * job is reduced to a transport switch + class construction.
+ */
+export type ProviderSpec = CloudProviderSpec | WebLLMProviderSpec | AppleFoundationModelsSpec | MlxProviderSpec;
+/**
+ * Cloud HTTP provider — used for Anthropic, OpenAI, Google (via OpenAI-compat),
+ * Motebit Cloud (anthropic protocol via relay), and OpenAI-compat local
+ * servers (LM Studio, llama.cpp, etc.).
+ *
+ * The `wireProtocol` discriminates between Anthropic's messages API and
+ * OpenAI's chat completions API. The surface uses this to pick the right
+ * concrete class (`AnthropicProvider` or `OpenAIProvider`) to instantiate.
+ */
+export interface CloudProviderSpec {
+    kind: "cloud";
+    /** Wire protocol family this client speaks. */
+    wireProtocol: "anthropic" | "openai";
+    /** API key to use. Empty string for motebit-cloud (server injects). */
+    apiKey: string;
+    model: string;
+    /** Already-resolved base URL — env.cloudBaseUrl has been applied. */
+    baseUrl: string;
+    maxTokens?: number;
+    temperature?: number;
+    /** Extra HTTP headers (e.g., x-proxy-token for motebit-cloud). */
+    extraHeaders?: Record<string, string>;
+}
+/** Browser-only WebLLM provider — runs in-browser via WebGPU. */
+export interface WebLLMProviderSpec {
+    kind: "webllm";
+    model: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+/** Apple Foundation Models — iOS 26+ / macOS 26+ only. */
+export interface AppleFoundationModelsSpec {
+    kind: "apple-fm";
+    model?: string;
+    maxTokens?: number;
+}
+/** MLX runtime — Apple Silicon only. */
+export interface MlxProviderSpec {
+    kind: "mlx";
+    model?: string;
+    maxTokens?: number;
+}
+/**
+ * Per-surface environment that captures the only things the resolver can't
+ * decide on its own: platform-specific URL routing, which on-device backends
+ * are physically supported, and motebit-cloud session state.
+ *
+ * Each surface constructs one of these once (or per call if the session
+ * state changes) and passes it to `resolveProviderSpec`. The interface is
+ * intentionally narrow — anything that can be computed from a
+ * `UnifiedProviderConfig` alone stays inside the resolver.
+ */
+export interface ResolverEnv {
+    /**
+     * Resolve the actual base URL for a cloud provider given its canonical
+     * vendor URL. Most surfaces return `canonical` unchanged. Browser surfaces
+     * substitute a CORS proxy for vendors that block direct browser calls.
+     * Tauri dev mode substitutes a Vite proxy path.
+     *
+     * The function form (rather than a static map) lets surfaces compute the
+     * substitution lazily based on runtime state (e.g., `isTauri`).
+     */
+    cloudBaseUrl(wireProtocol: "anthropic" | "openai", canonical: string): string;
+    /**
+     * Default URL for the on-device local-server backend when the user
+     * hasn't supplied an endpoint. The resolver auto-appends `/v1` via
+     * `normalizeLocalServerEndpoint`, so this can be a bare host. Use
+     * `localServerBaseUrl` to translate the user-supplied URL into a
+     * surface-specific transport URL (e.g., a Vite dev proxy path).
+     */
+    defaultLocalServerUrl: string;
+    /**
+     * Optional translator from a logical local-server URL into the actual URL
+     * the provider should call. Most surfaces return the input unchanged.
+     * Desktop dev mode substitutes the Vite proxy path `/api/ollama` for any
+     * Ollama-shaped logical URL — but the dispatch decision (Ollama-native vs
+     * OpenAI-compat) is made BEFORE this substitution, on the logical URL.
+     *
+     * This separation lets surfaces use proxy/rewrite paths without losing
+     * the resolver's ability to dispatch on the user's intent.
+     */
+    localServerBaseUrl?(logical: string): string;
+    /**
+     * Which on-device backends this surface can physically run.
+     *   - web: webllm, local-server
+     *   - mobile: apple-fm, mlx, local-server
+     *   - desktop: local-server (today; could grow)
+     *   - cli: local-server
+     */
+    supportedBackends: ReadonlySet<OnDeviceBackend>;
+    /**
+     * Base URL for motebit-cloud requests. Each surface resolves this from
+     * its own session state / env (proxy session, VITE_PROXY_URL, etc.).
+     * Falls back to `DEFAULT_MOTEBIT_CLOUD_URL` if absent.
+     */
+    motebitCloudBaseUrl?: string;
+    /**
+     * Extra HTTP headers to attach to motebit-cloud requests. Typically
+     * `{ "x-proxy-token": "..." }` from the surface's proxy session state.
+     */
+    motebitCloudHeaders?: Record<string, string>;
+    /**
+     * Default model for motebit-cloud when the config doesn't specify.
+     * Most surfaces leave this undefined (resolver falls back to
+     * `DEFAULT_PROXY_MODEL`); the relay session may override based on tier.
+     */
+    motebitCloudDefaultModel?: string;
+}
+/**
+ * Thrown when the user picks an on-device backend that the current surface
+ * doesn't physically support (e.g., apple-fm on web). Surfaces should
+ * present a graceful error rather than letting it propagate.
+ */
+export declare class UnsupportedBackendError extends Error {
+    backend: OnDeviceBackend;
+    constructor(backend: OnDeviceBackend);
+}
+/**
+ * Resolve a `UnifiedProviderConfig` (the user's choice) against a surface's
+ * `ResolverEnv` (its physical capabilities) to produce a normalized
+ * `ProviderSpec` (what the surface should instantiate).
+ *
+ * Pure function. No I/O. No side effects. Tested once, used everywhere.
+ *
+ * @throws {UnsupportedBackendError} if the chosen on-device backend isn't
+ *   in `env.supportedBackends`. Surfaces should catch and present a
+ *   user-facing message.
+ */
+export declare function resolveProviderSpec(config: UnifiedProviderConfig, env: ResolverEnv): ProviderSpec;
+//# sourceMappingURL=provider-resolver.d.ts.map

package/dist/provider-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-resolver.d.ts","sourceRoot":"","sources":["../src/provider-resolver.ts"],"names":[],"mappings":"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"}