@skillsmith/core 0.1.2 → 0.4.0

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

@@ -0,0 +1,286 @@
+/**
+ * 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
+ * SMI-1577: Added .optional() and .default() to handle partial API responses
+ */
+declare const ApiSearchResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    author: z.ZodNullable<z.ZodString>;
+    repo_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    quality_score: z.ZodNullable<z.ZodNumber>;
+    trust_tier: z.ZodDefault<z.ZodEnum<{
+        verified: "verified";
+        community: "community";
+        experimental: "experimental";
+        unknown: "unknown";
+    }>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    stars: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    installable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    created_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<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.ZodOptional<z.ZodNullable<z.ZodString>>;
+        quality_score: z.ZodNullable<z.ZodNumber>;
+        trust_tier: z.ZodDefault<z.ZodEnum<{
+            verified: "verified";
+            community: "community";
+            experimental: "experimental";
+            unknown: "unknown";
+        }>>;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        stars: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        installable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        created_at: z.ZodOptional<z.ZodString>;
+        updated_at: z.ZodOptional<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.ZodOptional<z.ZodNullable<z.ZodString>>;
+        quality_score: z.ZodNullable<z.ZodNumber>;
+        trust_tier: z.ZodDefault<z.ZodEnum<{
+            verified: "verified";
+            community: "community";
+            experimental: "experimental";
+            unknown: "unknown";
+        }>>;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        stars: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        installable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        created_at: z.ZodOptional<z.ZodString>;
+        updated_at: z.ZodOptional<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
+ * SMI-1577: Made repo_url, created_at, updated_at optional to match schema
+ */
+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
+     * SMI-1577: Handle optional fields with sensible defaults
+     * Uses epoch timestamp as sentinel for missing dates to avoid data integrity issues
+     */
+    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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"}