@adityanair98/api-oracle 0.5.0

package/dist/knowledge/schema.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Zod schemas and TypeScript types for API knowledge base entries.
+ * This is the central contract — all data must conform to this schema.
+ *
+ * Exports: ApiEntrySchema, ApiEntry, PartialApiEntrySchema, validateEntry
+ */
+import { z } from "zod";
+declare const UseCaseSchema: z.ZodObject<{
+    task: z.ZodString;
+    fit: z.ZodEnum<{
+        perfect: "perfect";
+        good: "good";
+        partial: "partial";
+    }>;
+}, z.core.$strip>;
+declare const AuthSchema: z.ZodObject<{
+    method: z.ZodEnum<{
+        api_key: "api_key";
+        oauth2: "oauth2";
+        bearer_token: "bearer_token";
+        basic_auth: "basic_auth";
+        none: "none";
+    }>;
+    setupSteps: z.ZodArray<z.ZodString>;
+    envVarName: z.ZodString;
+    codeSnippet: z.ZodString;
+}, z.core.$strip>;
+declare const PricingSchema: z.ZodObject<{
+    model: z.ZodEnum<{
+        free: "free";
+        freemium: "freemium";
+        paid: "paid";
+        usage_based: "usage_based";
+        open_source: "open_source";
+    }>;
+    freeTier: z.ZodNullable<z.ZodString>;
+    startingPrice: z.ZodNullable<z.ZodString>;
+    costPer: z.ZodNullable<z.ZodString>;
+    pricingUrl: z.ZodString;
+}, z.core.$strip>;
+declare const RateLimitsSchema: z.ZodObject<{
+    tier: z.ZodString;
+    limit: z.ZodString;
+    notes: z.ZodString;
+    retryStrategy: z.ZodString;
+}, z.core.$strip>;
+declare const SdkSchema: z.ZodObject<{
+    primaryLanguage: z.ZodString;
+    installCommand: z.ZodString;
+    importStatement: z.ZodString;
+    otherLanguages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const CodeExampleSchema: z.ZodObject<{
+    title: z.ZodString;
+    language: z.ZodString;
+    code: z.ZodString;
+    notes: z.ZodString;
+}, z.core.$strip>;
+declare const ReliabilitySchema: z.ZodObject<{
+    uptimeGuarantee: z.ZodNullable<z.ZodString>;
+    statusPageUrl: z.ZodNullable<z.ZodString>;
+    notes: z.ZodString;
+}, z.core.$strip>;
+export declare const ApiEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    slug: z.ZodString;
+    category: z.ZodEnum<{
+        auth: "auth";
+        email: "email";
+        payments: "payments";
+        ai: "ai";
+        storage: "storage";
+        search: "search";
+        messaging: "messaging";
+        analytics: "analytics";
+        database: "database";
+        media: "media";
+        notifications: "notifications";
+        maps: "maps";
+        communication: "communication";
+        devops: "devops";
+        infrastructure: "infrastructure";
+        commerce: "commerce";
+        cms: "cms";
+        forms: "forms";
+        scheduling: "scheduling";
+        testing: "testing";
+        security: "security";
+        workflow: "workflow";
+        integration: "integration";
+    }>;
+    subcategory: z.ZodString;
+    website: z.ZodString;
+    description: z.ZodString;
+    useCases: z.ZodArray<z.ZodObject<{
+        task: z.ZodString;
+        fit: z.ZodEnum<{
+            perfect: "perfect";
+            good: "good";
+            partial: "partial";
+        }>;
+    }, z.core.$strip>>;
+    auth: z.ZodObject<{
+        method: z.ZodEnum<{
+            api_key: "api_key";
+            oauth2: "oauth2";
+            bearer_token: "bearer_token";
+            basic_auth: "basic_auth";
+            none: "none";
+        }>;
+        setupSteps: z.ZodArray<z.ZodString>;
+        envVarName: z.ZodString;
+        codeSnippet: z.ZodString;
+    }, z.core.$strip>;
+    pricing: z.ZodObject<{
+        model: z.ZodEnum<{
+            free: "free";
+            freemium: "freemium";
+            paid: "paid";
+            usage_based: "usage_based";
+            open_source: "open_source";
+        }>;
+        freeTier: z.ZodNullable<z.ZodString>;
+        startingPrice: z.ZodNullable<z.ZodString>;
+        costPer: z.ZodNullable<z.ZodString>;
+        pricingUrl: z.ZodString;
+    }, z.core.$strip>;
+    rateLimits: z.ZodObject<{
+        tier: z.ZodString;
+        limit: z.ZodString;
+        notes: z.ZodString;
+        retryStrategy: z.ZodString;
+    }, z.core.$strip>;
+    sdk: z.ZodObject<{
+        primaryLanguage: z.ZodString;
+        installCommand: z.ZodString;
+        importStatement: z.ZodString;
+        otherLanguages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    codeExamples: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        language: z.ZodString;
+        code: z.ZodString;
+        notes: z.ZodString;
+    }, z.core.$strip>>;
+    gotchas: z.ZodArray<z.ZodString>;
+    reliability: z.ZodObject<{
+        uptimeGuarantee: z.ZodNullable<z.ZodString>;
+        statusPageUrl: z.ZodNullable<z.ZodString>;
+        notes: z.ZodString;
+    }, z.core.$strip>;
+    qualityScore: z.ZodNumber;
+    qualityJustification: z.ZodString;
+    alternatives: z.ZodArray<z.ZodString>;
+    complementary: z.ZodArray<z.ZodString>;
+    bestFor: z.ZodString;
+    lastVerified: z.ZodString;
+    entryVersion: z.ZodNumber;
+    addedBy: z.ZodString;
+}, z.core.$strip>;
+export declare const PartialApiEntrySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodEnum<{
+        auth: "auth";
+        email: "email";
+        payments: "payments";
+        ai: "ai";
+        storage: "storage";
+        search: "search";
+        messaging: "messaging";
+        analytics: "analytics";
+        database: "database";
+        media: "media";
+        notifications: "notifications";
+        maps: "maps";
+        communication: "communication";
+        devops: "devops";
+        infrastructure: "infrastructure";
+        commerce: "commerce";
+        cms: "cms";
+        forms: "forms";
+        scheduling: "scheduling";
+        testing: "testing";
+        security: "security";
+        workflow: "workflow";
+        integration: "integration";
+    }>>;
+    subcategory: z.ZodOptional<z.ZodString>;
+    website: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    useCases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        task: z.ZodString;
+        fit: z.ZodEnum<{
+            perfect: "perfect";
+            good: "good";
+            partial: "partial";
+        }>;
+    }, z.core.$strip>>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        method: z.ZodEnum<{
+            api_key: "api_key";
+            oauth2: "oauth2";
+            bearer_token: "bearer_token";
+            basic_auth: "basic_auth";
+            none: "none";
+        }>;
+        setupSteps: z.ZodArray<z.ZodString>;
+        envVarName: z.ZodString;
+        codeSnippet: z.ZodString;
+    }, z.core.$strip>>;
+    pricing: z.ZodOptional<z.ZodObject<{
+        model: z.ZodEnum<{
+            free: "free";
+            freemium: "freemium";
+            paid: "paid";
+            usage_based: "usage_based";
+            open_source: "open_source";
+        }>;
+        freeTier: z.ZodNullable<z.ZodString>;
+        startingPrice: z.ZodNullable<z.ZodString>;
+        costPer: z.ZodNullable<z.ZodString>;
+        pricingUrl: z.ZodString;
+    }, z.core.$strip>>;
+    rateLimits: z.ZodOptional<z.ZodObject<{
+        tier: z.ZodString;
+        limit: z.ZodString;
+        notes: z.ZodString;
+        retryStrategy: z.ZodString;
+    }, z.core.$strip>>;
+    sdk: z.ZodOptional<z.ZodObject<{
+        primaryLanguage: z.ZodString;
+        installCommand: z.ZodString;
+        importStatement: z.ZodString;
+        otherLanguages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    codeExamples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        language: z.ZodString;
+        code: z.ZodString;
+        notes: z.ZodString;
+    }, z.core.$strip>>>;
+    gotchas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    reliability: z.ZodOptional<z.ZodObject<{
+        uptimeGuarantee: z.ZodNullable<z.ZodString>;
+        statusPageUrl: z.ZodNullable<z.ZodString>;
+        notes: z.ZodString;
+    }, z.core.$strip>>;
+    qualityScore: z.ZodOptional<z.ZodNumber>;
+    qualityJustification: z.ZodOptional<z.ZodString>;
+    alternatives: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    complementary: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    bestFor: z.ZodOptional<z.ZodString>;
+    lastVerified: z.ZodOptional<z.ZodString>;
+    entryVersion: z.ZodOptional<z.ZodNumber>;
+    addedBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ApiEntry = z.infer<typeof ApiEntrySchema>;
+export type PartialApiEntry = z.infer<typeof PartialApiEntrySchema>;
+export type UseCase = z.infer<typeof UseCaseSchema>;
+export type Auth = z.infer<typeof AuthSchema>;
+export type Pricing = z.infer<typeof PricingSchema>;
+export type RateLimits = z.infer<typeof RateLimitsSchema>;
+export type Sdk = z.infer<typeof SdkSchema>;
+export type CodeExample = z.infer<typeof CodeExampleSchema>;
+export type Reliability = z.infer<typeof ReliabilitySchema>;
+export type Category = ApiEntry["category"];
+export declare function validateEntry(data: unknown): {
+    success: true;
+    data: ApiEntry;
+} | {
+    success: false;
+    errors: string[];
+};
+export {};

package/dist/knowledge/schema.js

@@ -0,0 +1,135 @@
+/**
+ * Zod schemas and TypeScript types for API knowledge base entries.
+ * This is the central contract — all data must conform to this schema.
+ *
+ * Exports: ApiEntrySchema, ApiEntry, PartialApiEntrySchema, validateEntry
+ */
+import { z } from "zod";
+// ─── Sub-schemas ─────────────────────────────────────────────────────────────
+const UseCaseSchema = z.object({
+    task: z.string().min(1, "Use case task cannot be empty"),
+    fit: z.enum(["perfect", "good", "partial"]),
+});
+const AuthSchema = z.object({
+    method: z.enum(["api_key", "oauth2", "bearer_token", "basic_auth", "none"]),
+    setupSteps: z.array(z.string().min(1)).min(1, "At least one setup step required"),
+    envVarName: z.string().min(1, "Environment variable name required"),
+    codeSnippet: z.string().min(1, "Auth code snippet required"),
+});
+const PricingSchema = z.object({
+    model: z.enum(["free", "freemium", "paid", "usage_based", "open_source"]),
+    freeTier: z.string().nullable(),
+    startingPrice: z.string().nullable(),
+    costPer: z.string().nullable(),
+    pricingUrl: z.string().url("Pricing URL must be a valid URL"),
+});
+const RateLimitsSchema = z.object({
+    tier: z.string().min(1),
+    limit: z.string().min(1),
+    notes: z.string().min(1),
+    retryStrategy: z.string().min(1),
+});
+const SdkSchema = z.object({
+    primaryLanguage: z.string().min(1),
+    installCommand: z.string().min(1),
+    importStatement: z.string().min(1),
+    otherLanguages: z.array(z.string()),
+});
+const CodeExampleSchema = z.object({
+    title: z.string().min(1, "Code example title required"),
+    language: z.string().min(1),
+    code: z.string().min(1, "Code example cannot be empty"),
+    notes: z.string(),
+});
+const ReliabilitySchema = z.object({
+    uptimeGuarantee: z.string().nullable(),
+    statusPageUrl: z.string().url("Status page URL must be valid").nullable(),
+    notes: z.string(),
+});
+// ─── Main Schema ──────────────────────────────────────────────────────────────
+export const ApiEntrySchema = z.object({
+    // IDENTITY
+    name: z.string().min(1, "API name required"),
+    slug: z
+        .string()
+        .min(1, "Slug required")
+        .regex(/^[a-z0-9-]+$/, "Slug must be lowercase kebab-case"),
+    category: z.enum([
+        "email",
+        "payments",
+        "ai",
+        "storage",
+        "search",
+        "auth",
+        "messaging",
+        "analytics",
+        "database",
+        "media",
+        "notifications",
+        "maps",
+        "communication",
+        // Session 4 additions
+        "devops",
+        "infrastructure",
+        "commerce",
+        "cms",
+        "forms",
+        "scheduling",
+        "testing",
+        "security",
+        "workflow",
+        "integration",
+    ]),
+    subcategory: z.string().min(1, "Subcategory required"),
+    website: z.string().url("Website must be a valid URL"),
+    description: z.string().min(20, "Description must be at least 20 characters"),
+    // USE CASES
+    useCases: z
+        .array(UseCaseSchema)
+        .min(1, "At least one use case required"),
+    // AUTHENTICATION
+    auth: AuthSchema,
+    // PRICING
+    pricing: PricingSchema,
+    // RATE LIMITS
+    rateLimits: RateLimitsSchema,
+    // SDK & INTEGRATION
+    sdk: SdkSchema,
+    // CODE EXAMPLES
+    codeExamples: z
+        .array(CodeExampleSchema)
+        .min(1, "At least one code example required"),
+    // GOTCHAS
+    gotchas: z
+        .array(z.string().min(1))
+        .min(2, "At least 2 gotchas required"),
+    // RELIABILITY
+    reliability: ReliabilitySchema,
+    // SCORING
+    qualityScore: z
+        .number()
+        .min(1, "Quality score minimum is 1")
+        .max(10, "Quality score maximum is 10"),
+    qualityJustification: z.string().min(10, "Quality justification required"),
+    // RELATIONSHIPS
+    alternatives: z.array(z.string()),
+    complementary: z.array(z.string()),
+    bestFor: z.string().min(1, "bestFor summary required"),
+    // METADATA
+    lastVerified: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, "lastVerified must be ISO date (YYYY-MM-DD)"),
+    entryVersion: z.number().int().min(1, "Entry version must be at least 1"),
+    addedBy: z.string().min(1, "addedBy required"),
+});
+// ─── Partial Schema (for filtering/search params) ─────────────────────────────
+export const PartialApiEntrySchema = ApiEntrySchema.partial();
+// ─── Validation Helper ────────────────────────────────────────────────────────
+export function validateEntry(data) {
+    const result = ApiEntrySchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    const errors = result.error.issues.map((issue) => `${issue.path.join(".")} — ${issue.message}`);
+    return { success: false, errors };
+}

package/dist/knowledge/scorer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Scoring/ranking engine — ranks API entries by relevance to a task description.
+ * Uses weighted multi-factor scoring across 6 dimensions.
+ *
+ * Exports: SCORING_WEIGHTS, DEFAULT_WEIGHTS, ScoreWeights, scoreEntry, rankEntries,
+ *          tokenize, scoreUseCaseFit, scoreDevExperience
+ */
+import type { ApiEntry } from "./schema.js";
+import type { SearchConstraints, RankedResult } from "./search.js";
+export interface ScoreWeights {
+    useCaseFit: number;
+    qualityScore: number;
+    developerExperience: number;
+    pricingFit: number;
+    keywordRelevance: number;
+    recencyBonus: number;
+}
+/** Default weights — must sum to exactly 1.0 */
+export declare const SCORING_WEIGHTS: ScoreWeights;
+/** Alias for backwards compatibility */
+export declare const DEFAULT_WEIGHTS: ScoreWeights;
+/**
+ * Normalize text to a set of lowercase tokens.
+ * Allows 2-char tokens (important for "ai", "db", "ml", "go").
+ */
+export declare function tokenize(text: string): Set<string>;
+/**
+ * Score against multiple fields with weighted relevance:
+ * - Use case tasks (40%) — with fit multiplier, best match wins
+ * - bestFor (25%) — concise purpose statement
+ * - Description (20%) — first 200 chars (signal-dense)
+ * - Category signals (15%) — broad category alignment
+ */
+export declare function scoreUseCaseFit(entry: ApiEntry, queryTokens: Set<string>): number;
+/**
+ * DX sub-scoring with measurable, explicit factors:
+ * - TypeScript as primary SDK: 3 pts
+ * - 2+ code examples: 2 pts
+ * - envVarName defined (clear auth setup): 1 pt
+ * - Single npm install command: 1 pt
+ * - Multiple language SDKs (3+): 1 pt
+ * - Required language match: up to 2 pts (only when requiredLanguage is specified)
+ *
+ * Normalized to 0-1 range. Base max = 8 pts; with language constraint = 10 pts.
+ */
+export declare function scoreDevExperience(entry: ApiEntry, constraints?: SearchConstraints): number;
+/**
+ * Compute a confidence value (0-1) for how certain we are about the top result.
+ *
+ * High confidence (>0.8): strong category match + high useCaseFit score
+ * Medium confidence (0.5-0.8): partial signals
+ * Low confidence (<0.5): weak query, no clear category
+ */
+export declare function computeConfidence(topResult: RankedResult, detectedCategory: string | null, detectedConfidence: number, allResults: RankedResult[]): number;
+/** Human-readable confidence label */
+export declare function confidenceLabel(confidence: number): "high" | "medium" | "low";
+export interface ScoringContext {
+    expandedQuery: string;
+    detectedCategory: string | null;
+    detectedConfidence: number;
+}
+export declare function scoreEntry(entry: ApiEntry, query: string, constraints?: SearchConstraints, weights?: ScoreWeights, context?: ScoringContext): RankedResult;
+export declare function rankEntries(entries: ApiEntry[], query: string, constraints?: SearchConstraints, topN?: number, weights?: ScoreWeights, context?: ScoringContext): RankedResult[];