@skillsmith/core 0.1.2 → 2.0.0

package/dist/src/api/cache.d.ts

@@ -0,0 +1,131 @@
+/**
+ * API Response Cache
+ * @module api/cache
+ *
+ * SMI-1245: Caching layer for API responses
+ *
+ * Provides in-memory caching with TTL for offline support.
+ * Uses a simple LRU-like eviction strategy.
+ */
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+    /** Default TTL in milliseconds (default: 1 hour) */
+    defaultTtl?: number;
+    /** Max entries in cache (default: 1000) */
+    maxEntries?: number;
+    /** Enable cache statistics (default: false) */
+    enableStats?: boolean;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    entries: number;
+    evictions: number;
+    hitRate: number;
+}
+/**
+ * TTL configuration for different endpoints
+ */
+export declare const DEFAULT_TTL: Record<string, number>;
+/**
+ * API Response Cache
+ *
+ * @example
+ * ```typescript
+ * const cache = new ApiCache({ defaultTtl: 3600000 });
+ *
+ * // Cache a search result
+ * cache.set('search:testing', results, 'search');
+ *
+ * // Get from cache
+ * const cached = cache.get<ApiSearchResult[]>('search:testing');
+ * ```
+ */
+export declare class ApiCache {
+    private cache;
+    private defaultTtl;
+    private maxEntries;
+    private enableStats;
+    private hits;
+    private misses;
+    private evictions;
+    private operationCount;
+    private readonly PRUNE_INTERVAL;
+    constructor(config?: CacheConfig);
+    /**
+     * Generate cache key from endpoint and parameters
+     */
+    static createKey(endpoint: string, params?: Record<string, unknown>): string;
+    /**
+     * Get item from cache
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set item in cache
+     */
+    set<T>(key: string, data: T, endpointType?: keyof typeof DEFAULT_TTL): void;
+    /**
+     * Check if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Delete item from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Clear expired entries
+     */
+    prune(): number;
+    /**
+     * Invalidate entries matching a pattern.
+     *
+     * When a string is provided, it is treated as a literal string and
+     * special RegExp characters are escaped to prevent RegExp injection.
+     * To use regex patterns, pass a RegExp object directly.
+     *
+     * @param pattern - Literal string to match or RegExp for pattern matching
+     * @returns Number of entries invalidated
+     *
+     * @example
+     * ```typescript
+     * // Literal string matching (special chars are escaped)
+     * cache.invalidatePattern('search:user.name') // Matches exactly 'search:user.name'
+     *
+     * // RegExp for pattern matching
+     * cache.invalidatePattern(/^search:/) // Matches all keys starting with 'search:'
+     * ```
+     */
+    invalidatePattern(pattern: string | RegExp): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Automatically prune expired entries every PRUNE_INTERVAL operations.
+     * SMI-1262: Prevents expired entries from accumulating until maxEntries is reached.
+     */
+    private maybeAutoPrune;
+    /**
+     * Evict least recently used entries
+     */
+    private evictLeastUsed;
+}
+/**
+ * Create a cache instance with default configuration
+ */
+export declare function createCache(config?: CacheConfig): ApiCache;
+/**
+ * Get or create the global cache instance
+ */
+export declare function getGlobalCache(): ApiCache;
+export default ApiCache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/src/api/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/api/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiCH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI9C,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,IAAI,CAAI;IAChB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,SAAS,CAAI;IAGrB,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAM;gBAEzB,MAAM,GAAE,WAAgB;IAOpC;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAa5E;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAuBlC;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,YAAY,CAAC,EAAE,MAAM,OAAO,WAAW,GAAG,IAAI;IAmB3E;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAUzB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,KAAK,IAAI,MAAM;IAcf;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAcnD;;OAEG;IACH,QAAQ,IAAI,UAAU;IAWtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;IACH,OAAO,CAAC,cAAc;CAwBvB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,QAAQ,CAE1D;AAOD;;GAEG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAKzC;AAED,eAAe,QAAQ,CAAA"}

package/dist/src/api/cache.js

@@ -0,0 +1,264 @@
+/**
+ * API Response Cache
+ * @module api/cache
+ *
+ * SMI-1245: Caching layer for API responses
+ *
+ * Provides in-memory caching with TTL for offline support.
+ * Uses a simple LRU-like eviction strategy.
+ */
+/**
+ * Escape special RegExp characters in a string.
+ *
+ * This prevents RegExp injection when user-provided strings are
+ * used to construct regular expressions.
+ *
+ * @param str - The string to escape
+ * @returns The escaped string safe for use in RegExp constructor
+ *
+ * @example
+ * ```typescript
+ * escapeRegExp('foo.bar') // Returns 'foo\\.bar'
+ * escapeRegExp('a*b+c?') // Returns 'a\\*b\\+c\\?'
+ * ```
+ */
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * TTL configuration for different endpoints
+ */
+export const DEFAULT_TTL = {
+    search: 60 * 60 * 1000, // 1 hour
+    getSkill: 24 * 60 * 60 * 1000, // 24 hours
+    recommend: 60 * 60 * 1000, // 1 hour
+};
+/**
+ * API Response Cache
+ *
+ * @example
+ * ```typescript
+ * const cache = new ApiCache({ defaultTtl: 3600000 });
+ *
+ * // Cache a search result
+ * cache.set('search:testing', results, 'search');
+ *
+ * // Get from cache
+ * const cached = cache.get<ApiSearchResult[]>('search:testing');
+ * ```
+ */
+export class ApiCache {
+    cache;
+    defaultTtl;
+    maxEntries;
+    enableStats;
+    // Statistics
+    hits = 0;
+    misses = 0;
+    evictions = 0;
+    // Auto-pruning (SMI-1262)
+    operationCount = 0;
+    PRUNE_INTERVAL = 100;
+    constructor(config = {}) {
+        this.cache = new Map();
+        this.defaultTtl = config.defaultTtl ?? DEFAULT_TTL.search;
+        this.maxEntries = config.maxEntries ?? 1000;
+        this.enableStats = config.enableStats ?? false;
+    }
+    /**
+     * Generate cache key from endpoint and parameters
+     */
+    static createKey(endpoint, params) {
+        if (!params || Object.keys(params).length === 0) {
+            return endpoint;
+        }
+        const sortedParams = Object.keys(params)
+            .sort()
+            .map((key) => `${key}=${JSON.stringify(params[key])}`)
+            .join('&');
+        return `${endpoint}?${sortedParams}`;
+    }
+    /**
+     * Get item from cache
+     */
+    get(key) {
+        this.maybeAutoPrune();
+        const entry = this.cache.get(key);
+        if (!entry) {
+            if (this.enableStats)
+                this.misses++;
+            return undefined;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            if (this.enableStats)
+                this.misses++;
+            return undefined;
+        }
+        // Update hit count and statistics
+        entry.hitCount++;
+        if (this.enableStats)
+            this.hits++;
+        return entry.data;
+    }
+    /**
+     * Set item in cache
+     */
+    set(key, data, endpointType) {
+        this.maybeAutoPrune();
+        // Evict if at capacity
+        if (this.cache.size >= this.maxEntries) {
+            this.evictLeastUsed();
+        }
+        const ttl = endpointType ? DEFAULT_TTL[endpointType] : this.defaultTtl;
+        const now = Date.now();
+        this.cache.set(key, {
+            data,
+            expiresAt: now + ttl,
+            createdAt: now,
+            hitCount: 0,
+        });
+    }
+    /**
+     * Check if key exists and is not expired
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete item from cache
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all cache entries
+     */
+    clear() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+    }
+    /**
+     * Clear expired entries
+     */
+    prune() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [key, entry] of this.cache) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+    /**
+     * Invalidate entries matching a pattern.
+     *
+     * When a string is provided, it is treated as a literal string and
+     * special RegExp characters are escaped to prevent RegExp injection.
+     * To use regex patterns, pass a RegExp object directly.
+     *
+     * @param pattern - Literal string to match or RegExp for pattern matching
+     * @returns Number of entries invalidated
+     *
+     * @example
+     * ```typescript
+     * // Literal string matching (special chars are escaped)
+     * cache.invalidatePattern('search:user.name') // Matches exactly 'search:user.name'
+     *
+     * // RegExp for pattern matching
+     * cache.invalidatePattern(/^search:/) // Matches all keys starting with 'search:'
+     * ```
+     */
+    invalidatePattern(pattern) {
+        const regex = typeof pattern === 'string' ? new RegExp(escapeRegExp(pattern)) : pattern;
+        let invalidated = 0;
+        for (const key of this.cache.keys()) {
+            if (regex.test(key)) {
+                this.cache.delete(key);
+                invalidated++;
+            }
+        }
+        return invalidated;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            entries: this.cache.size,
+            evictions: this.evictions,
+            hitRate: total > 0 ? this.hits / total : 0,
+        };
+    }
+    /**
+     * Automatically prune expired entries every PRUNE_INTERVAL operations.
+     * SMI-1262: Prevents expired entries from accumulating until maxEntries is reached.
+     */
+    maybeAutoPrune() {
+        if (++this.operationCount % this.PRUNE_INTERVAL === 0) {
+            this.prune();
+        }
+    }
+    /**
+     * Evict least recently used entries
+     */
+    evictLeastUsed() {
+        // Find entry with lowest hit count
+        let lowestKey;
+        let lowestHits = Infinity;
+        for (const [key, entry] of this.cache) {
+            // Also check for expired while iterating
+            if (Date.now() > entry.expiresAt) {
+                this.cache.delete(key);
+                if (this.enableStats)
+                    this.evictions++;
+                return;
+            }
+            if (entry.hitCount < lowestHits) {
+                lowestHits = entry.hitCount;
+                lowestKey = key;
+            }
+        }
+        if (lowestKey) {
+            this.cache.delete(lowestKey);
+            if (this.enableStats)
+                this.evictions++;
+        }
+    }
+}
+/**
+ * Create a cache instance with default configuration
+ */
+export function createCache(config) {
+    return new ApiCache(config);
+}
+/**
+ * Global cache instance for sharing across the application
+ */
+let globalCache;
+/**
+ * Get or create the global cache instance
+ */
+export function getGlobalCache() {
+    if (!globalCache) {
+        globalCache = new ApiCache({ enableStats: true });
+    }
+    return globalCache;
+}
+export default ApiCache;
+//# sourceMappingURL=cache.js.map

package/dist/src/api/cache.js.map

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

package/dist/src/api/client.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Skillsmith API Client
+ * @module api/client
+ *
+ * SMI-1244: API client for fetching skills from live Supabase endpoints
+ * SMI-1258: Runtime validation for API responses using zod
+ *
+ * Provides methods to interact with the Skillsmith API:
+ * - search: Search skills with filters
+ * - getSkill: Get skill by ID
+ * - getRecommendations: Get skill recommendations based on tech stack
+ * - recordEvent: Record telemetry event
+ */
+import { z } from 'zod';
+import type { Skill, TrustTier, SearchOptions } from '../types/skill.js';
+/**
+ * Trust tier enum values
+ */
+declare const TrustTierSchema: z.ZodEnum<{
+    verified: "verified";
+    community: "community";
+    experimental: "experimental";
+    unknown: "unknown";
+}>;
+/**
+ * Schema for individual search result from API
+ */
+declare const ApiSearchResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    author: z.ZodNullable<z.ZodString>;
+    repo_url: z.ZodNullable<z.ZodString>;
+    quality_score: z.ZodNullable<z.ZodNumber>;
+    trust_tier: z.ZodEnum<{
+        verified: "verified";
+        community: "community";
+        experimental: "experimental";
+        unknown: "unknown";
+    }>;
+    tags: z.ZodArray<z.ZodString>;
+    stars: z.ZodNullable<z.ZodNumber>;
+    installable: z.ZodNullable<z.ZodBoolean>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for telemetry response
+ */
+declare const TelemetryResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        ok: z.ZodBoolean;
+    }, z.core.$strip>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const SearchResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        author: z.ZodNullable<z.ZodString>;
+        repo_url: z.ZodNullable<z.ZodString>;
+        quality_score: z.ZodNullable<z.ZodNumber>;
+        trust_tier: z.ZodEnum<{
+            verified: "verified";
+            community: "community";
+            experimental: "experimental";
+            unknown: "unknown";
+        }>;
+        tags: z.ZodArray<z.ZodString>;
+        stars: z.ZodNullable<z.ZodNumber>;
+        installable: z.ZodNullable<z.ZodBoolean>;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    }, z.core.$strip>>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const SingleSkillResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        author: z.ZodNullable<z.ZodString>;
+        repo_url: z.ZodNullable<z.ZodString>;
+        quality_score: z.ZodNullable<z.ZodNumber>;
+        trust_tier: z.ZodEnum<{
+            verified: "verified";
+            community: "community";
+            experimental: "experimental";
+            unknown: "unknown";
+        }>;
+        tags: z.ZodArray<z.ZodString>;
+        stars: z.ZodNullable<z.ZodNumber>;
+        installable: z.ZodNullable<z.ZodBoolean>;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    }, z.core.$strip>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * API response wrapper
+ */
+export interface ApiResponse<T> {
+    data: T;
+    meta?: Record<string, unknown>;
+}
+/**
+ * API error response
+ */
+export interface ApiErrorResponse {
+    error: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Custom error class for API client errors with retry control
+ * SMI-1257: Replace string-based retry skip with custom error class
+ */
+export declare class ApiClientError extends Error {
+    readonly retryable: boolean;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, retryable?: boolean, statusCode?: number | undefined);
+}
+/**
+ * Search result from API
+ */
+export interface ApiSearchResult {
+    id: string;
+    name: string;
+    description: string | null;
+    author: string | null;
+    repo_url: string | null;
+    quality_score: number | null;
+    trust_tier: TrustTier;
+    tags: string[];
+    stars: number | null;
+    installable: boolean | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Recommendation request
+ */
+export interface RecommendationRequest {
+    stack: string[];
+    project_type?: string;
+    limit?: number;
+}
+/**
+ * Telemetry event
+ */
+export interface TelemetryEvent {
+    event: 'skill_view' | 'skill_install' | 'skill_uninstall' | 'skill_rate' | 'search' | 'recommend' | 'compare' | 'validate';
+    skill_id?: string;
+    anonymous_id: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * API client configuration
+ */
+export interface ApiClientConfig {
+    /** Base URL for the API (defaults to production Supabase) */
+    baseUrl?: string;
+    /** Supabase anon key for authentication */
+    anonKey?: string;
+    /** Request timeout in ms (default 30000) */
+    timeout?: number;
+    /** Max retry attempts (default 3) */
+    maxRetries?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Enable offline mode (disables API calls) */
+    offlineMode?: boolean;
+}
+/**
+ * Generate anonymous ID for telemetry using cryptographic randomness.
+ * Returns a UUID v4 format string (e.g., "550e8400-e29b-41d4-a716-446655440000").
+ *
+ * Note: This generates a fresh ID per session - it is NOT stored persistently.
+ * For persistent anonymous IDs, the caller must handle storage.
+ */
+export declare function generateAnonymousId(): string;
+/**
+ * Skillsmith API Client
+ *
+ * @example
+ * ```typescript
+ * const client = new SkillsmithApiClient({
+ *   anonKey: process.env.SUPABASE_ANON_KEY,
+ * });
+ *
+ * const results = await client.search({ query: 'testing' });
+ * console.log(results.data);
+ * ```
+ */
+export declare class SkillsmithApiClient {
+    private baseUrl;
+    private anonKey;
+    private timeout;
+    private maxRetries;
+    private debug;
+    private offlineMode;
+    constructor(config?: ApiClientConfig);
+    /**
+     * Check if client is running in offline mode
+     */
+    isOffline(): boolean;
+    /**
+     * Log debug message
+     */
+    private log;
+    /**
+     * Build request headers
+     */
+    private buildHeaders;
+    /**
+     * Make API request with retry logic and optional schema validation
+     * SMI-1258: Added runtime validation for API responses
+     *
+     * @param endpoint - API endpoint path
+     * @param options - Fetch options
+     * @param schema - Optional zod schema for response validation
+     */
+    private request;
+    /**
+     * Search for skills
+     * SMI-1258: Validates response against SearchResponseSchema
+     *
+     * @param options - Search options
+     * @returns Search results
+     */
+    search(options: SearchOptions): Promise<ApiResponse<ApiSearchResult[]>>;
+    /**
+     * Get skill by ID
+     * SMI-1258: Validates response against SingleSkillResponseSchema
+     *
+     * @param id - Skill ID (UUID or author/name format)
+     * @returns Skill details
+     */
+    getSkill(id: string): Promise<ApiResponse<ApiSearchResult>>;
+    /**
+     * Get skill recommendations based on tech stack
+     * SMI-1258: Validates response against SearchResponseSchema
+     *
+     * @param request - Recommendation request
+     * @returns Recommended skills
+     */
+    getRecommendations(request: RecommendationRequest): Promise<ApiResponse<ApiSearchResult[]>>;
+    /**
+     * Record telemetry event
+     * SMI-1258: Validates response against TelemetryResponseSchema
+     *
+     * @param event - Telemetry event
+     * @returns Success response
+     */
+    recordEvent(event: TelemetryEvent): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Check API health status
+     *
+     * Returns service health information including status, timestamp, and version.
+     * In offline mode, returns a synthetic healthy response.
+     *
+     * @returns Health status object
+     */
+    checkHealth(): Promise<{
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        timestamp: string;
+        version: string;
+    }>;
+    /**
+     * Convert API result to Skill type
+     */
+    static toSkill(result: ApiSearchResult): Skill;
+}
+/**
+ * Create a default API client instance
+ */
+export declare function createApiClient(config?: ApiClientConfig): SkillsmithApiClient;
+export { ApiSearchResultSchema, SearchResponseSchema, SingleSkillResponseSchema, TelemetryResponseSchema, TrustTierSchema, };
+export default SkillsmithApiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/src/api/client.d.ts.map

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