@skillsmith/core 0.5.4 → 0.5.6

package/dist/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/api/cache.d.ts.map

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

@@ -0,0 +1,34 @@
+/**
+ * Client-side response cache wiring
+ * @module api/client.cache
+ *
+ * SMI-4120: Extracted from client.ts to keep the client under the 500-line
+ * audit:standards gate. Contains cache construction, the per-call option
+ * type, and the `withCache` helper used by search/getSkill/recommend.
+ */
+import { ApiCache, type CacheConfig } from './cache.js';
+import type { ApiResponse } from './client.js';
+/**
+ * SMI-4120: Per-call cache directive, matching `fetch` RequestInit semantics.
+ * `no-store` skips both cache read and write for the call.
+ */
+export interface CallCacheOptions {
+    cache?: 'default' | 'no-store';
+}
+/**
+ * Cache configuration accepted by `SkillsmithApiClient`. Pass `false` to
+ * disable; pass a pre-built `ApiCache` to share one across clients; pass a
+ * `CacheConfig` object to customize TTLs.
+ */
+export type ClientCacheSetting = ApiCache | CacheConfig | false;
+/**
+ * SMI-4120: Build the response cache honoring the env kill-switch. Returns
+ * `null` when disabled so callers can branch cheaply.
+ */
+export declare function buildResponseCache(setting: ClientCacheSetting | undefined): ApiCache | null;
+/**
+ * SMI-4120: Run a thunk through the response cache. Stored values are the
+ * same `ApiResponse` reference — callers must not mutate.
+ */
+export declare function withResponseCache<T>(cache: ApiCache | null, endpointType: 'search' | 'getSkill' | 'recommend', key: string, noStore: boolean, fetcher: () => Promise<ApiResponse<T>>): Promise<ApiResponse<T>>;
+//# sourceMappingURL=client.cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.cache.d.ts","sourceRoot":"","sources":["../../src/api/client.cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,CAAA;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAA;AAE/D;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAK3F;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,KAAK,EAAE,QAAQ,GAAG,IAAI,EACtB,YAAY,EAAE,QAAQ,GAAG,UAAU,GAAG,WAAW,EACjD,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAOzB"}

package/dist/api/client.cache.js

@@ -0,0 +1,37 @@
+/**
+ * Client-side response cache wiring
+ * @module api/client.cache
+ *
+ * SMI-4120: Extracted from client.ts to keep the client under the 500-line
+ * audit:standards gate. Contains cache construction, the per-call option
+ * type, and the `withCache` helper used by search/getSkill/recommend.
+ */
+import { ApiCache } from './cache.js';
+/**
+ * SMI-4120: Build the response cache honoring the env kill-switch. Returns
+ * `null` when disabled so callers can branch cheaply.
+ */
+export function buildResponseCache(setting) {
+    if (process.env.SKILLSMITH_DISABLE_CLIENT_CACHE === '1')
+        return null;
+    if (setting === false)
+        return null;
+    if (setting instanceof ApiCache)
+        return setting;
+    return new ApiCache(setting ?? {});
+}
+/**
+ * SMI-4120: Run a thunk through the response cache. Stored values are the
+ * same `ApiResponse` reference — callers must not mutate.
+ */
+export async function withResponseCache(cache, endpointType, key, noStore, fetcher) {
+    if (!cache || noStore)
+        return fetcher();
+    const hit = cache.get(key);
+    if (hit)
+        return hit;
+    const fresh = await fetcher();
+    cache.set(key, fresh, endpointType);
+    return fresh;
+}
+//# sourceMappingURL=client.cache.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.cache.js","sourceRoot":"","sources":["../../src/api/client.cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAoB,MAAM,YAAY,CAAA;AAkBvD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAuC;IACxE,IAAI,OAAO,CAAC,GAAG,CAAC,+BAA+B,KAAK,GAAG;QAAE,OAAO,IAAI,CAAA;IACpE,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,IAAI,CAAA;IAClC,IAAI,OAAO,YAAY,QAAQ;QAAE,OAAO,OAAO,CAAA;IAC/C,OAAO,IAAI,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,CAAA;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAsB,EACtB,YAAiD,EACjD,GAAW,EACX,OAAgB,EAChB,OAAsC;IAEtC,IAAI,CAAC,KAAK,IAAI,OAAO;QAAE,OAAO,OAAO,EAAE,CAAA;IACvC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAiB,GAAG,CAAC,CAAA;IAC1C,IAAI,GAAG;QAAE,OAAO,GAAG,CAAA;IACnB,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAA;IAC7B,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC,CAAA;IACnC,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/api/client.d.ts

@@ -0,0 +1,55 @@
+import type { Skill, SearchOptions } from '../types/skill.js';
+import { type ApiResponse, type ApiSearchResult, type ApiClientConfig, type RecommendationRequest, type TelemetryEvent } from './client.types.js';
+export { ApiClientError, type ApiResponse, type ApiErrorResponse, type ApiSearchResult, type ApiClientConfig, type RecommendationRequest, type TelemetryEvent, } from './client.types.js';
+import { ApiCache } from './cache.js';
+import { type CallCacheOptions } from './client.cache.js';
+export type { CallCacheOptions } from './client.cache.js';
+export { generateAnonymousId } from './utils.js';
+export { checkApiHealth } from './client.health.js';
+export { ApiSearchResultSchema, SearchResponseSchema, SingleSkillResponseSchema, TelemetryResponseSchema, TrustTierSchema, } from './schemas.js';
+export declare class SkillsmithApiClient {
+    private baseUrl;
+    private anonKey;
+    private apiKey;
+    private jwtToken;
+    private timeout;
+    private maxRetries;
+    private debug;
+    private offlineMode;
+    /** SMI-4119: Lazily-initialized batcher for telemetry events. */
+    private eventBatcher;
+    /** SMI-4120: Response cache (null when disabled). */
+    private responseCache;
+    constructor(config?: ApiClientConfig);
+    /** SMI-4120: Expose the response cache (null when disabled). */
+    getResponseCache(): ApiCache | null;
+    isOffline(): boolean;
+    hasPersonalApiKey(): boolean;
+    getAuthMode(): 'jwt' | 'personal' | 'anonymous' | 'none';
+    /** SMI-4402: Update the JWT token (e.g. after a refresh). */
+    setJwtToken(token: string): void;
+    private log;
+    private request;
+    search(options: SearchOptions, callOptions?: CallCacheOptions): Promise<ApiResponse<ApiSearchResult[]>>;
+    getSkill(id: string, options?: {
+        includeContent?: boolean;
+    } & CallCacheOptions): Promise<ApiResponse<ApiSearchResult>>;
+    getRecommendations(request: RecommendationRequest, callOptions?: CallCacheOptions): Promise<ApiResponse<ApiSearchResult[]>>;
+    recordEvent(event: TelemetryEvent): Promise<{
+        ok: boolean;
+    }>;
+    /** SMI-4119: Flush queued telemetry events (drain the batcher). */
+    flushEvents(): Promise<void>;
+    /** SMI-4119: Dispose batcher (detach exit listeners, clear timers). */
+    disposeEventBatcher(): void;
+    private getOrCreateBatcher;
+    checkHealth(): Promise<{
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        timestamp: string;
+        version: string;
+    }>;
+    static toSkill(result: ApiSearchResult): Skill;
+}
+export declare function createApiClient(config?: ApiClientConfig): SkillsmithApiClient;
+export default SkillsmithApiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/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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"}

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

@@ -0,0 +1,39 @@
+/**
+ * Event batching glue for SkillsmithApiClient
+ * @module api/client.events
+ *
+ * SMI-4119: Keeps batcher wiring out of client.ts to stay under the 500-line cap.
+ *
+ * This module exposes a small helper that builds a flush function bound to a
+ * client's base URL / auth headers and posts batches to `POST /events`.
+ */
+import type { TelemetryEvent } from './client.js';
+import { type EventBatcher } from './event-batcher.js';
+/**
+ * Inputs required to POST a batch to `/events`.
+ * Kept narrow so we don't expose private client fields.
+ */
+export interface BatchPostContext {
+    baseUrl: string;
+    anonKey: string | undefined;
+    apiKey: string | undefined;
+    /** Request timeout in ms. */
+    timeout: number;
+}
+/**
+ * Build a flush function that POSTs a batch to `${baseUrl}/events`.
+ *
+ * Emits `X-Skillsmith-Batched: true` so the edge function can stamp
+ * `audit_logs.metadata.batched` and post-deploy SQL can distinguish
+ * batched vs stale single-client traffic.
+ *
+ * Throws on non-2xx responses so the batcher can retry.
+ */
+export declare function createBatchFlushFn(ctx: () => BatchPostContext): (events: TelemetryEvent[]) => Promise<void>;
+/**
+ * Build an EventBatcher that POSTs to `${baseUrl}/events` using the live
+ * auth context returned by `ctx()`. Lazily re-reads context on each flush so
+ * config changes (e.g. API key rotation) are honored.
+ */
+export declare function buildClientEventBatcher(ctx: () => BatchPostContext): EventBatcher;
+//# sourceMappingURL=client.events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.events.d.ts","sourceRoot":"","sources":["../../src/api/client.events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAE1E;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,gBAAgB,GAC1B,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAmC7C;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,gBAAgB,GAAG,YAAY,CAWjF"}