@skillsmith/core 0.2.0 → 0.4.1

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

@@ -3,6 +3,7 @@
  * @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
@@ -10,7 +11,93 @@
  * - 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
  */
@@ -25,21 +112,32 @@ 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;
+    repo_url?: string | null;
     quality_score: number | null;
     trust_tier: TrustTier;
     tags: string[];
-    stars: number | null;
-    created_at: string;
-    updated_at: string;
+    stars?: number | null;
+    installable?: boolean | null;
+    created_at?: string;
+    updated_at?: string;
 }
 /**
  * Recommendation request
@@ -72,9 +170,15 @@ export interface ApiClientConfig {
     maxRetries?: number;
     /** Enable debug logging */
     debug?: boolean;
+    /** Enable offline mode (disables API calls) */
+    offlineMode?: boolean;
 }
 /**
- * Generate anonymous ID for telemetry
+ * 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;
 /**
@@ -96,7 +200,12 @@ export declare class SkillsmithApiClient {
     private timeout;
     private maxRetries;
     private debug;
+    private offlineMode;
     constructor(config?: ApiClientConfig);
+    /**
+     * Check if client is running in offline mode
+     */
+    isOffline(): boolean;
     /**
      * Log debug message
      */
@@ -106,11 +215,17 @@ export declare class SkillsmithApiClient {
      */
     private buildHeaders;
     /**
-     * Make API request with retry logic
+     * 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
@@ -118,6 +233,7 @@ export declare class SkillsmithApiClient {
     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
@@ -125,6 +241,7 @@ export declare class SkillsmithApiClient {
     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
@@ -132,6 +249,7 @@ export declare class SkillsmithApiClient {
     getRecommendations(request: RecommendationRequest): Promise<ApiResponse<ApiSearchResult[]>>;
     /**
      * Record telemetry event
+     * SMI-1258: Validates response against TelemetryResponseSchema
      *
      * @param event - Telemetry event
      * @returns Success response
@@ -139,8 +257,24 @@ export declare class SkillsmithApiClient {
     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
+     * SMI-825: Added security scan fields
      */
     static toSkill(result: ApiSearchResult): Skill;
 }
@@ -148,5 +282,6 @@ export declare class SkillsmithApiClient {
  * 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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAExE;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAA;IACP,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,UAAU,EAAE,SAAS,CAAA;IACrB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,YAAY,GAAG,eAAe,GAAG,iBAAiB,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAA;IAC1H,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAaD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAO5C;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,GAAE,eAAoB;IAQxC;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB;;OAEG;YACW,OAAO;IAgErB;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;IAa7E;;;;;OAKG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;IAKjE;;;;;OAKG;IACG,kBAAkB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;IAOjG;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAclE;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK;CAc/C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,mBAAmB,CAE7E;AAED,eAAe,mBAAmB,CAAA"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAOxE;;GAEG;AACH,QAAA,MAAM,eAAe;;;;;EAA+D,CAAA;AAEpF;;;GAGG;AACH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;iBAazB,CAAA;AAYF;;GAEG;AACH,QAAA,MAAM,uBAAuB;;;;;iBAK3B,CAAA;AAGF,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;iBAA0D,CAAA;AACpF,QAAA,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;iBAAiD,CAAA;AAEhF;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAA;IACP,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;aAGrB,SAAS,EAAE,OAAO;aAClB,UAAU,CAAC,EAAE,MAAM;gBAFnC,OAAO,EAAE,MAAM,EACC,SAAS,GAAE,OAAe,EAC1B,UAAU,CAAC,EAAE,MAAM,YAAA;CAKtC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,UAAU,EAAE,SAAS,CAAA;IACrB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EACD,YAAY,GACZ,eAAe,GACf,iBAAiB,GACjB,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,SAAS,GACT,UAAU,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,+CAA+C;IAC/C,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAiBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAyB5C;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,GAAE,eAAoB;IAexC;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB;;;;;;;OAOG;YACW,OAAO;IAmHrB;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;IAkB7E;;;;;;OAMG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;IASjE;;;;;;OAMG;IACG,kBAAkB,CACtB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;IAW1C;;;;;;OAMG;IACG,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAkBlE;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC;QAC3B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAA;QAC5C,SAAS,EAAE,MAAM,CAAA;QACjB,OAAO,EAAE,MAAM,CAAA;KAChB,CAAC;IA0DF;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK;CAsB/C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,mBAAmB,CAE7E;AAGD,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,eAAe,GAChB,CAAA;AAED,eAAe,mBAAmB,CAAA"}

package/dist/src/api/client.js

@@ -3,6 +3,7 @@
  * @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
@@ -10,7 +11,73 @@
  * - getRecommendations: Get skill recommendations based on tech stack
  * - recordEvent: Record telemetry event
  */
-const DEFAULT_BASE_URL = 'https://vrcnzpmndtroqxxoqkzy.supabase.co/functions/v1';
+import { z } from 'zod';
+import { SkillsmithError, ErrorCodes } from '../errors.js';
+// ============================================================================
+// Zod Schemas for API Response Validation (SMI-1258)
+// ============================================================================
+/**
+ * Trust tier enum values
+ */
+const TrustTierSchema = z.enum(['verified', 'community', 'experimental', 'unknown']);
+/**
+ * Schema for individual search result from API
+ * SMI-1577: Added .optional() and .default() to handle partial API responses
+ */
+const ApiSearchResultSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    author: z.string().nullable(),
+    repo_url: z.string().nullable().optional(),
+    quality_score: z.number().nullable(),
+    trust_tier: TrustTierSchema.default('unknown'),
+    tags: z.array(z.string()).default([]),
+    stars: z.number().nullable().optional(),
+    installable: z.boolean().nullable().optional(),
+    created_at: z.string().optional(),
+    updated_at: z.string().optional(),
+});
+/**
+ * Schema for generic API response wrapper
+ */
+function createApiResponseSchema(dataSchema) {
+    return z.object({
+        data: dataSchema,
+        meta: z.record(z.string(), z.unknown()).optional(),
+    });
+}
+/**
+ * Schema for telemetry response
+ */
+const TelemetryResponseSchema = z.object({
+    data: z.object({
+        ok: z.boolean(),
+    }),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
+// Pre-built schemas for common responses
+const SearchResponseSchema = createApiResponseSchema(z.array(ApiSearchResultSchema));
+const SingleSkillResponseSchema = createApiResponseSchema(ApiSearchResultSchema);
+/**
+ * Custom error class for API client errors with retry control
+ * SMI-1257: Replace string-based retry skip with custom error class
+ */
+export class ApiClientError extends Error {
+    retryable;
+    statusCode;
+    constructor(message, retryable = false, statusCode) {
+        super(message);
+        this.retryable = retryable;
+        this.statusCode = statusCode;
+        this.name = 'ApiClientError';
+    }
+}
+// Default base URL is constructed from SUPABASE_URL environment variable
+// Falls back to undefined to fail explicitly if not configured
+const DEFAULT_BASE_URL = process.env.SUPABASE_URL
+    ? `${process.env.SUPABASE_URL}/functions/v1`
+    : undefined;
 /**
  * Calculate delay with exponential backoff and jitter
  */
@@ -20,15 +87,35 @@ function calculateBackoff(attempt, baseDelay = 1000) {
     return Math.min(exponentialDelay + jitter, 30000); // Max 30s
 }
 /**
- * Generate anonymous ID for telemetry
+ * 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 function generateAnonymousId() {
+    // Use Node.js crypto.randomUUID() for cryptographically secure random IDs
+    // This is available in Node.js 14.17.0+ and all modern browsers
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // Fallback for older environments: use crypto.getRandomValues if available
+    if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+        const bytes = new Uint8Array(16);
+        crypto.getRandomValues(bytes);
+        // Set version (4) and variant (RFC4122) bits
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+    // Last resort fallback (not cryptographically secure, but functional)
     const chars = 'abcdef0123456789';
     let id = '';
     for (let i = 0; i < 32; i++) {
         id += chars[Math.floor(Math.random() * chars.length)];
     }
-    return id;
+    return `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20)}`;
 }
 /**
  * Skillsmith API Client
@@ -49,13 +136,25 @@ export class SkillsmithApiClient {
     timeout;
     maxRetries;
     debug;
+    offlineMode;
     constructor(config = {}) {
-        this.baseUrl = config.baseUrl || process.env.SKILLSMITH_API_URL || DEFAULT_BASE_URL;
+        const baseUrl = config.baseUrl || process.env.SKILLSMITH_API_URL || DEFAULT_BASE_URL;
+        // Auto-enable offline mode if no URL is configured (graceful degradation)
+        // This allows the client to work in test/dev environments without explicit configuration
+        const explicitOfflineMode = config.offlineMode ?? process.env.SKILLSMITH_OFFLINE_MODE === 'true';
+        this.offlineMode = explicitOfflineMode || !baseUrl;
+        this.baseUrl = baseUrl || 'offline://not-configured';
         this.anonKey = config.anonKey || process.env.SUPABASE_ANON_KEY;
         this.timeout = config.timeout ?? 30000;
         this.maxRetries = config.maxRetries ?? 3;
         this.debug = config.debug ?? false;
     }
+    /**
+     * Check if client is running in offline mode
+     */
+    isOffline() {
+        return this.offlineMode;
+    }
     /**
      * Log debug message
      */
@@ -79,9 +178,14 @@ export class SkillsmithApiClient {
         return headers;
     }
     /**
-     * Make API request with retry logic
+     * 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
      */
-    async request(endpoint, options = {}) {
+    async request(endpoint, options = {}, schema) {
         const url = `${this.baseUrl}${endpoint}`;
         let lastError;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
@@ -99,26 +203,59 @@ export class SkillsmithApiClient {
                 });
                 clearTimeout(timeoutId);
                 if (!response.ok) {
-                    const errorBody = await response.json().catch(() => ({ error: 'Unknown error' }));
-                    // Don't retry on client errors (4xx)
+                    const errorBody = (await response
+                        .json()
+                        .catch(() => ({ error: 'Unknown error' })));
+                    // Don't retry on client errors (4xx) - not retryable
                     if (response.status >= 400 && response.status < 500) {
-                        throw new Error(errorBody.error || `API error: ${response.status}`);
+                        throw new ApiClientError(errorBody.error || `API error: ${response.status}`, false, // not retryable
+                        response.status);
                     }
-                    // Retry on server errors (5xx) and rate limits (429)
+                    // Retry on server errors (5xx) and rate limits (429) - retryable
                     if (response.status === 429 || response.status >= 500) {
-                        throw new Error(`Server error: ${response.status}`);
+                        throw new ApiClientError(`Server error: ${response.status}`, true, response.status);
                     }
-                    throw new Error(errorBody.error || `API error: ${response.status}`);
+                    // Default: not retryable
+                    throw new ApiClientError(errorBody.error || `API error: ${response.status}`, false, response.status);
                 }
-                const data = await response.json();
+                const rawData = await response.json();
+                // SMI-1258: Validate response against schema if provided
+                if (schema) {
+                    const validated = schema.safeParse(rawData);
+                    if (!validated.success) {
+                        const errorMessage = validated.error.issues
+                            .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                            .join(', ');
+                        this.log('Response validation failed:', validated.error.issues);
+                        throw new SkillsmithError(ErrorCodes.NETWORK_INVALID_RESPONSE, `Invalid API response: ${errorMessage}`, {
+                            details: {
+                                endpoint,
+                                validationErrors: validated.error.issues,
+                            },
+                        });
+                    }
+                    this.log('Response received and validated:', { status: response.status });
+                    return validated.data;
+                }
+                // Fallback: return unvalidated data (for backwards compatibility)
                 this.log('Response received:', { status: response.status });
-                return data;
+                return rawData;
             }
             catch (error) {
                 lastError = error instanceof Error ? error : new Error(String(error));
                 this.log(`Attempt ${attempt + 1} failed:`, lastError.message);
-                // Don't retry on abort or client errors
-                if (lastError.name === 'AbortError' || lastError.message.includes('API error')) {
+                // Don't retry on abort errors
+                if (lastError.name === 'AbortError') {
+                    throw lastError;
+                }
+                // Don't retry on validation errors - malformed responses won't fix themselves
+                if (lastError instanceof SkillsmithError &&
+                    lastError.code === ErrorCodes.NETWORK_INVALID_RESPONSE) {
+                    throw lastError;
+                }
+                // SMI-1257: Use custom error class instead of string matching
+                // Don't retry on non-retryable API errors
+                if (lastError instanceof ApiClientError && !lastError.retryable) {
                     throw lastError;
                 }
                 if (attempt < this.maxRetries) {
@@ -132,6 +269,7 @@ export class SkillsmithApiClient {
     }
     /**
      * Search for skills
+     * SMI-1258: Validates response against SearchResponseSchema
      *
      * @param options - Search options
      * @returns Search results
@@ -149,20 +287,22 @@ export class SkillsmithApiClient {
             params.set('min_score', String(options.minQualityScore));
         if (options.category)
             params.set('category', options.category);
-        return this.request(`/skills-search?${params.toString()}`);
+        return this.request(`/skills-search?${params.toString()}`, {}, SearchResponseSchema);
     }
     /**
      * Get skill by ID
+     * SMI-1258: Validates response against SingleSkillResponseSchema
      *
      * @param id - Skill ID (UUID or author/name format)
      * @returns Skill details
      */
     async getSkill(id) {
         const encodedId = encodeURIComponent(id);
-        return this.request(`/skills-get?id=${encodedId}`);
+        return this.request(`/skills-get?id=${encodedId}`, {}, SingleSkillResponseSchema);
     }
     /**
      * Get skill recommendations based on tech stack
+     * SMI-1258: Validates response against SearchResponseSchema
      *
      * @param request - Recommendation request
      * @returns Recommended skills
@@ -171,10 +311,11 @@ export class SkillsmithApiClient {
         return this.request('/skills-recommend', {
             method: 'POST',
             body: JSON.stringify(request),
-        });
+        }, SearchResponseSchema);
     }
     /**
      * Record telemetry event
+     * SMI-1258: Validates response against TelemetryResponseSchema
      *
      * @param event - Telemetry event
      * @returns Success response
@@ -184,7 +325,7 @@ export class SkillsmithApiClient {
             const response = await this.request('/events', {
                 method: 'POST',
                 body: JSON.stringify(event),
-            });
+            }, TelemetryResponseSchema);
             return response.data;
         }
         catch {
@@ -193,21 +334,93 @@ export class SkillsmithApiClient {
             return { ok: false };
         }
     }
+    /**
+     * 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
+     */
+    async checkHealth() {
+        // In offline mode, return synthetic healthy status
+        if (this.offlineMode) {
+            return {
+                status: 'healthy',
+                timestamp: new Date().toISOString(),
+                version: 'offline',
+            };
+        }
+        try {
+            // Simple health check - try to reach the API
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 5000); // 5s timeout for health
+            const response = await fetch(`${this.baseUrl}/health`, {
+                headers: this.buildHeaders(),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                // Try to parse JSON response, fall back to basic healthy status
+                try {
+                    const data = (await response.json());
+                    return {
+                        status: 'healthy',
+                        timestamp: new Date().toISOString(),
+                        version: data.version || '1.0.0',
+                    };
+                }
+                catch {
+                    return {
+                        status: 'healthy',
+                        timestamp: new Date().toISOString(),
+                        version: '1.0.0',
+                    };
+                }
+            }
+            // Non-OK response indicates degraded service
+            return {
+                status: response.status >= 500 ? 'unhealthy' : 'degraded',
+                timestamp: new Date().toISOString(),
+                version: 'unknown',
+            };
+        }
+        catch (error) {
+            this.log('Health check failed:', error);
+            // Network errors indicate unhealthy service
+            return {
+                status: 'unhealthy',
+                timestamp: new Date().toISOString(),
+                version: 'unknown',
+            };
+        }
+    }
     /**
      * 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
+     * SMI-825: Added security scan fields
      */
     static toSkill(result) {
+        // Sentinel value for missing timestamps - clearly indicates unknown date
+        const UNKNOWN_DATE = '1970-01-01T00:00:00.000Z';
         return {
             id: result.id,
             name: result.name,
             description: result.description,
             author: result.author,
-            repoUrl: result.repo_url,
+            repoUrl: result.repo_url ?? null,
             qualityScore: result.quality_score,
             trustTier: result.trust_tier,
             tags: result.tags || [],
-            createdAt: result.created_at,
-            updatedAt: result.updated_at,
+            installable: result.installable ?? false,
+            // SMI-825: Security scan fields (default to not scanned for API results)
+            riskScore: null,
+            securityFindingsCount: 0,
+            securityScannedAt: null,
+            securityPassed: null,
+            createdAt: result.created_at ?? UNKNOWN_DATE,
+            updatedAt: result.updated_at ?? UNKNOWN_DATE,
         };
     }
 }
@@ -217,5 +430,7 @@ export class SkillsmithApiClient {
 export function createApiClient(config) {
     return new SkillsmithApiClient(config);
 }
+// SMI-1258: Export schemas for testing and external validation
+export { ApiSearchResultSchema, SearchResponseSchema, SingleSkillResponseSchema, TelemetryResponseSchema, TrustTierSchema, };
 export default SkillsmithApiClient;
 //# sourceMappingURL=client.js.map