harper-knowledge 0.1.0

package/dist/resources/KnowledgeEntryResource.js

@@ -0,0 +1,157 @@
+/**
+ * Knowledge Entry Resource
+ *
+ * REST endpoint for knowledge base entries.
+ * GET is public; POST, PUT, DELETE require authentication.
+ *
+ * Routes:
+ *   GET  /Knowledge/<id>      — return single entry
+ *   GET  /Knowledge/?query=.. — search entries
+ *   POST /Knowledge/          — create new entry (auth required)
+ *   PUT  /Knowledge/<id>      — update entry (auth required)
+ *   DELETE /Knowledge/<id>    — deprecate entry (team role required)
+ */
+import { createEntry, getEntry, updateEntry, deprecateEntry, stripEmbedding, } from "../core/entries.js";
+import { search } from "../core/search.js";
+function getResourceClass() {
+    return globalThis.Resource;
+}
+export class KnowledgeEntryResource extends getResourceClass() {
+    static loadAsInstance = false;
+    /**
+     * GET /Knowledge/<id> — return a single entry by ID.
+     * GET /Knowledge/?query=... — search the knowledge base.
+     * PUBLIC — no auth required.
+     */
+    async get(target) {
+        const id = this.getId();
+        if (id) {
+            const entry = await getEntry(String(id));
+            if (!entry) {
+                return { status: 404, data: { error: "Entry not found" } };
+            }
+            return stripEmbedding(entry);
+        }
+        // Search mode: extract query params from target
+        const query = target?.get?.("query") || target?.query;
+        if (!query) {
+            return { error: "Provide an id or query parameter" };
+        }
+        const tagsParam = target?.get?.("tags") || target?.tags;
+        const limitParam = target?.get?.("limit") || target?.limit;
+        const contextParam = target?.get?.("context") || target?.context;
+        const modeParam = target?.get?.("mode") || target?.mode;
+        let context;
+        if (contextParam) {
+            try {
+                context =
+                    typeof contextParam === "string"
+                        ? JSON.parse(contextParam)
+                        : contextParam;
+            }
+            catch {
+                return {
+                    status: 400,
+                    data: { error: "Invalid context parameter: must be valid JSON" },
+                };
+            }
+        }
+        const params = {
+            query: String(query),
+            tags: tagsParam ? String(tagsParam).split(",") : undefined,
+            limit: limitParam ? parseInt(String(limitParam), 10) : undefined,
+            context,
+            mode: modeParam,
+        };
+        const results = await search(params);
+        return results.map(stripEmbedding);
+    }
+    /**
+     * POST /Knowledge/ — create a new knowledge entry.
+     * AUTH REQUIRED. AI agents have their confidence forced to "ai-generated".
+     */
+    async post(_target, data) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        if (!data?.title || !data?.content) {
+            return { status: 400, data: { error: "title and content are required" } };
+        }
+        if (data.title.length > 500 || data.content.length > 100_000) {
+            return {
+                status: 400,
+                data: { error: "Title max 500 chars, content max 100,000 chars" },
+            };
+        }
+        // Force ai-generated confidence for ai-agent role
+        if (user.role === "ai-agent") {
+            data.confidence = "ai-generated";
+        }
+        if (!data.addedBy) {
+            data.addedBy = user.username || user.id || "unknown";
+        }
+        return createEntry(data);
+    }
+    /**
+     * PUT /Knowledge/<id> — create or update an entry.
+     * AUTH REQUIRED. AI agents have their confidence forced to "ai-generated".
+     */
+    async put(_target, data) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        const id = this.getId();
+        if (!id) {
+            return { status: 400, data: { error: "Entry ID required" } };
+        }
+        if (user.role === "ai-agent") {
+            data.confidence = "ai-generated";
+        }
+        if (!data.addedBy) {
+            data.addedBy = user.username || user.id || "unknown";
+        }
+        // Upsert: try update first, create if not found
+        try {
+            return await updateEntry(String(id), data);
+        }
+        catch (error) {
+            if (error.message.includes("not found")) {
+                // Entry doesn't exist — create if full data provided, otherwise 404
+                if (!data.title || !data.content) {
+                    return { status: 404, data: { error: "Entry not found" } };
+                }
+                return createEntry({ ...data, id: String(id) });
+            }
+            throw error;
+        }
+    }
+    /**
+     * DELETE /Knowledge/<id> — deprecate an entry (soft delete).
+     * AUTH REQUIRED: team role only.
+     */
+    async delete(_target) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        if (user.role !== "team") {
+            return { status: 403, data: { error: "Team role required" } };
+        }
+        const id = this.getId();
+        if (!id) {
+            return { status: 400, data: { error: "Entry ID required" } };
+        }
+        try {
+            await deprecateEntry(String(id));
+            return true;
+        }
+        catch (error) {
+            if (error.message.includes("not found")) {
+                return { status: 404, data: { error: error.message } };
+            }
+            throw error;
+        }
+    }
+}

package/dist/resources/QueryLogResource.d.ts

@@ -0,0 +1,20 @@
+/**
+ * QueryLog Resource
+ *
+ * REST endpoint for search query analytics.
+ *
+ * Routes:
+ *   GET /QueryLog/        — list recent query logs (team role required)
+ *   GET /QueryLog/<id>    — get a single query log entry (team role required)
+ */
+declare const QueryLogResource_base: any;
+export declare class QueryLogResource extends QueryLogResource_base {
+    static loadAsInstance: boolean;
+    /**
+     * GET /QueryLog/ — list query logs, optionally filtered.
+     * GET /QueryLog/<id> — get a single query log entry.
+     * AUTH REQUIRED: team role only.
+     */
+    get(target?: any): Promise<Record<string, unknown> | Record<string, unknown>[]>;
+}
+export {};

package/dist/resources/QueryLogResource.js

@@ -0,0 +1,57 @@
+/**
+ * QueryLog Resource
+ *
+ * REST endpoint for search query analytics.
+ *
+ * Routes:
+ *   GET /QueryLog/        — list recent query logs (team role required)
+ *   GET /QueryLog/<id>    — get a single query log entry (team role required)
+ */
+function getResourceClass() {
+    return globalThis.Resource;
+}
+export class QueryLogResource extends getResourceClass() {
+    static loadAsInstance = false;
+    /**
+     * GET /QueryLog/ — list query logs, optionally filtered.
+     * GET /QueryLog/<id> — get a single query log entry.
+     * AUTH REQUIRED: team role only.
+     */
+    async get(target) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        if (user.role !== "team") {
+            return { status: 403, data: { error: "Team role required" } };
+        }
+        const id = this.getId();
+        if (id) {
+            const entry = await databases.kb.QueryLog.get(String(id));
+            if (!entry) {
+                return { status: 404, data: { error: "Query log entry not found" } };
+            }
+            return entry;
+        }
+        // List mode: support optional limit and query filter
+        const limitParam = target?.get?.("limit") || target?.limit;
+        const queryFilter = target?.get?.("query") || target?.query;
+        const limit = limitParam ? parseInt(String(limitParam), 10) : 50;
+        const conditions = [];
+        if (queryFilter) {
+            conditions.push({
+                attribute: "query",
+                comparator: "contains",
+                value: String(queryFilter),
+            });
+        }
+        const results = [];
+        for await (const item of databases.kb.QueryLog.search({
+            conditions: conditions.length > 0 ? conditions : undefined,
+            limit,
+        })) {
+            results.push(item);
+        }
+        return results;
+    }
+}

package/dist/resources/ServiceKeyResource.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ServiceKey Resource
+ *
+ * REST endpoint for managing API keys for webhooks and service accounts.
+ * All operations require team role.
+ *
+ * Routes:
+ *   GET    /ServiceKey/       — list all keys (team role, keyHash never returned)
+ *   GET    /ServiceKey/<id>   — get a single key (team role, keyHash never returned)
+ *   POST   /ServiceKey/       — create a new key (team role, returns plaintext key once)
+ *   DELETE /ServiceKey/<id>   — delete a key (team role)
+ */
+declare const ServiceKeyResource_base: any;
+export declare class ServiceKeyResource extends ServiceKeyResource_base {
+    static loadAsInstance: boolean;
+    /**
+     * GET /ServiceKey/ — list all service keys (keyHash excluded).
+     * GET /ServiceKey/<id> — get a single key (keyHash excluded).
+     * AUTH REQUIRED: team role only.
+     */
+    get(target?: any): Promise<Record<string, unknown> | Record<string, unknown>[]>;
+    /**
+     * POST /ServiceKey/ — create a new API key.
+     * AUTH REQUIRED: team role only.
+     *
+     * Body: { name: string, role: "service_account" | "ai_agent", permissions?: object }
+     *
+     * Returns the plaintext key exactly once. It is never stored or retrievable again.
+     */
+    post(_target: any, data: any): Promise<{
+        status: number;
+        data: {
+            error: string;
+        };
+    } | {
+        key: string;
+        status?: undefined;
+        data?: undefined;
+    }>;
+    /**
+     * DELETE /ServiceKey/<id> — delete a service key.
+     * AUTH REQUIRED: team role only.
+     */
+    delete(_target?: any): Promise<true | {
+        status: number;
+        data: {
+            error: string;
+        };
+    }>;
+}
+export {};

package/dist/resources/ServiceKeyResource.js

@@ -0,0 +1,132 @@
+/**
+ * ServiceKey Resource
+ *
+ * REST endpoint for managing API keys for webhooks and service accounts.
+ * All operations require team role.
+ *
+ * Routes:
+ *   GET    /ServiceKey/       — list all keys (team role, keyHash never returned)
+ *   GET    /ServiceKey/<id>   — get a single key (team role, keyHash never returned)
+ *   POST   /ServiceKey/       — create a new key (team role, returns plaintext key once)
+ *   DELETE /ServiceKey/<id>   — delete a key (team role)
+ */
+import crypto from "node:crypto";
+function getResourceClass() {
+    return globalThis.Resource;
+}
+/**
+ * Hash an API key using scrypt with the given salt.
+ * Returns the hex-encoded hash.
+ */
+function hashKey(key, salt) {
+    return crypto.scryptSync(key, salt, 64).toString("hex");
+}
+/**
+ * Strip keyHash from a service key record before returning to the client.
+ */
+function sanitizeKey(record) {
+    const { keyHash: _keyHash, ...safe } = record;
+    return safe;
+}
+export class ServiceKeyResource extends getResourceClass() {
+    static loadAsInstance = false;
+    /**
+     * GET /ServiceKey/ — list all service keys (keyHash excluded).
+     * GET /ServiceKey/<id> — get a single key (keyHash excluded).
+     * AUTH REQUIRED: team role only.
+     */
+    async get(target) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        if (user.role !== "team") {
+            return { status: 403, data: { error: "Team role required" } };
+        }
+        const id = this.getId();
+        if (id) {
+            const record = await databases.kb.ServiceKey.get(String(id));
+            if (!record) {
+                return { status: 404, data: { error: "Service key not found" } };
+            }
+            return sanitizeKey(record);
+        }
+        // List mode
+        const limitParam = target?.get?.("limit") || target?.limit;
+        const limit = limitParam ? parseInt(String(limitParam), 10) : 100;
+        const results = [];
+        for await (const item of databases.kb.ServiceKey.search({ limit })) {
+            results.push(sanitizeKey(item));
+        }
+        return results;
+    }
+    /**
+     * POST /ServiceKey/ — create a new API key.
+     * AUTH REQUIRED: team role only.
+     *
+     * Body: { name: string, role: "service_account" | "ai_agent", permissions?: object }
+     *
+     * Returns the plaintext key exactly once. It is never stored or retrievable again.
+     */
+    async post(_target, data) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        if (user.role !== "team") {
+            return { status: 403, data: { error: "Team role required" } };
+        }
+        if (!data?.name) {
+            return { status: 400, data: { error: "name is required" } };
+        }
+        if (!data?.role ||
+            (data.role !== "service_account" && data.role !== "ai_agent")) {
+            return {
+                status: 400,
+                data: { error: 'role must be "service_account" or "ai_agent"' },
+            };
+        }
+        // Generate a random API key and hash it
+        const plaintextKey = crypto.randomBytes(32).toString("hex");
+        const salt = crypto.randomBytes(16).toString("hex");
+        const hash = hashKey(plaintextKey, salt);
+        const id = crypto.randomUUID();
+        const record = {
+            id,
+            name: data.name,
+            keyHash: `${salt}:${hash}`,
+            role: data.role,
+            permissions: data.permissions || null,
+            createdBy: user.username || user.id || "unknown",
+        };
+        await databases.kb.ServiceKey.put(record);
+        // Return the record without keyHash, plus the plaintext key (shown only once)
+        return {
+            ...sanitizeKey(record),
+            key: plaintextKey,
+        };
+    }
+    /**
+     * DELETE /ServiceKey/<id> — delete a service key.
+     * AUTH REQUIRED: team role only.
+     */
+    async delete(_target) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        if (user.role !== "team") {
+            return { status: 403, data: { error: "Team role required" } };
+        }
+        const id = this.getId();
+        if (!id) {
+            return { status: 400, data: { error: "Service key ID required" } };
+        }
+        const existing = await databases.kb.ServiceKey.get(String(id));
+        if (!existing) {
+            return { status: 404, data: { error: "Service key not found" } };
+        }
+        await databases.kb.ServiceKey.delete(String(id));
+        return true;
+    }
+}

package/dist/resources/TagResource.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tag Resource
+ *
+ * REST endpoint for knowledge base tags.
+ *
+ * Routes:
+ *   GET /KnowledgeTag/       — list all tags (public)
+ *   GET /KnowledgeTag/<id>   — get a single tag by name (public)
+ */
+declare const TagResource_base: any;
+export declare class TagResource extends TagResource_base {
+    static loadAsInstance: boolean;
+    /**
+     * GET /KnowledgeTag/ — list all tags.
+     * GET /KnowledgeTag/<id> — get a single tag by name.
+     * PUBLIC — no auth required.
+     */
+    get(_target?: any): Promise<import("../types.ts").KnowledgeTag | import("../types.ts").KnowledgeTag[] | {
+        status: number;
+        data: {
+            error: string;
+        };
+    }>;
+}
+export {};

package/dist/resources/TagResource.js

@@ -0,0 +1,32 @@
+/**
+ * Tag Resource
+ *
+ * REST endpoint for knowledge base tags.
+ *
+ * Routes:
+ *   GET /KnowledgeTag/       — list all tags (public)
+ *   GET /KnowledgeTag/<id>   — get a single tag by name (public)
+ */
+import { listTags, getTag } from "../core/tags.js";
+function getResourceClass() {
+    return globalThis.Resource;
+}
+export class TagResource extends getResourceClass() {
+    static loadAsInstance = false;
+    /**
+     * GET /KnowledgeTag/ — list all tags.
+     * GET /KnowledgeTag/<id> — get a single tag by name.
+     * PUBLIC — no auth required.
+     */
+    async get(_target) {
+        const id = this.getId();
+        if (id) {
+            const tag = await getTag(String(id));
+            if (!tag) {
+                return { status: 404, data: { error: "Tag not found" } };
+            }
+            return tag;
+        }
+        return listTags();
+    }
+}

package/dist/resources/TriageResource.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Triage Resource
+ *
+ * REST endpoint for the triage intake queue.
+ *
+ * Routes:
+ *   GET  /Triage/       — list pending triage items (team role required)
+ *   POST /Triage/       — submit a new triage item (service_account or ai_agent role)
+ *   PUT  /Triage/<id>   — process a triage item (team role required)
+ */
+declare const TriageResource_base: any;
+export declare class TriageResource extends TriageResource_base {
+    static loadAsInstance: boolean;
+    /**
+     * GET /Triage/ — list pending triage items.
+     * AUTH REQUIRED: team role only.
+     */
+    get(_target?: any): Promise<import("../types.ts").TriageItem[] | {
+        status: number;
+        data: {
+            error: string;
+        };
+    }>;
+    /**
+     * POST /Triage/ — submit a new triage item.
+     * AUTH REQUIRED: service_account or ai_agent role.
+     */
+    post(_target: any, data: any): Promise<import("../types.ts").TriageItem | {
+        status: number;
+        data: {
+            error: string;
+        };
+    }>;
+    /**
+     * PUT /Triage/<id> — process a triage item.
+     * AUTH REQUIRED: team role only.
+     *
+     * Body should include:
+     *   { action: "accepted" | "dismissed" | "linked",
+     *     processedBy?: string,
+     *     entryData?: KnowledgeEntryInput,
+     *     linkedEntryId?: string }
+     */
+    put(_target: any, data: any): Promise<import("../types.ts").TriageItem | {
+        status: number;
+        data: {
+            error: string;
+        };
+    }>;
+}
+export {};

package/dist/resources/TriageResource.js

@@ -0,0 +1,107 @@
+/**
+ * Triage Resource
+ *
+ * REST endpoint for the triage intake queue.
+ *
+ * Routes:
+ *   GET  /Triage/       — list pending triage items (team role required)
+ *   POST /Triage/       — submit a new triage item (service_account or ai_agent role)
+ *   PUT  /Triage/<id>   — process a triage item (team role required)
+ */
+import { submitTriage, processTriage, listPending } from "../core/triage.js";
+function getResourceClass() {
+    return globalThis.Resource;
+}
+export class TriageResource extends getResourceClass() {
+    static loadAsInstance = false;
+    /**
+     * GET /Triage/ — list pending triage items.
+     * AUTH REQUIRED: team role only.
+     */
+    async get(_target) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        if (user.role !== "team") {
+            return { status: 403, data: { error: "Team role required" } };
+        }
+        return listPending();
+    }
+    /**
+     * POST /Triage/ — submit a new triage item.
+     * AUTH REQUIRED: service_account or ai_agent role.
+     */
+    async post(_target, data) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        if (user.role !== "service_account" && user.role !== "ai_agent") {
+            return {
+                status: 403,
+                data: { error: "service_account or ai_agent role required" },
+            };
+        }
+        if (!data?.source || !data?.summary) {
+            return {
+                status: 400,
+                data: { error: "source and summary are required" },
+            };
+        }
+        return submitTriage(data.source, data.summary, data.rawPayload);
+    }
+    /**
+     * PUT /Triage/<id> — process a triage item.
+     * AUTH REQUIRED: team role only.
+     *
+     * Body should include:
+     *   { action: "accepted" | "dismissed" | "linked",
+     *     processedBy?: string,
+     *     entryData?: KnowledgeEntryInput,
+     *     linkedEntryId?: string }
+     */
+    async put(_target, data) {
+        const user = this.getCurrentUser();
+        if (!user) {
+            return { status: 401, data: { error: "Authentication required" } };
+        }
+        if (user.role !== "team") {
+            return { status: 403, data: { error: "Team role required" } };
+        }
+        const id = this.getId();
+        if (!id) {
+            return { status: 400, data: { error: "Triage item ID required" } };
+        }
+        if (!data?.action) {
+            return {
+                status: 400,
+                data: { error: "action is required (accepted, dismissed, or linked)" },
+            };
+        }
+        if (!["accepted", "dismissed", "linked"].includes(data.action)) {
+            return {
+                status: 400,
+                data: { error: "action must be accepted, dismissed, or linked" },
+            };
+        }
+        const action = data.action;
+        const processedBy = data.processedBy || user.username || user.id || "unknown";
+        const options = {};
+        if (data.entryData) {
+            options.entryData = data.entryData;
+        }
+        if (data.linkedEntryId) {
+            options.linkedEntryId = data.linkedEntryId;
+        }
+        try {
+            return await processTriage(String(id), action, processedBy, options);
+        }
+        catch (error) {
+            if (error.message.includes("not found")) {
+                return { status: 404, data: { error: error.message } };
+            }
+            throw error;
+        }
+    }
+}