@ailu-ai/contracts 2.0.0

package/dist/knowledge.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+/**
+ * A document stored in the knowledge base (without its embedding vector). Carries the
+ * Open Knowledge Format (OKF) frontmatter so a bundle round-trips: `type` (OKF's only
+ * required field), plus the recommended `title`/`description`/`resource`/`tags`/`timestamp`,
+ * the bundle-relative `path`, the markdown cross-reference `links`, and any extra producer
+ * keys preserved in `frontmatter`.
+ */
+export const KbDocumentDtoSchema = z.object({
+    id: z.string().min(1),
+    namespace: z.string().min(1),
+    content: z.string(),
+    type: z.string().min(1),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    resource: z.string().optional(),
+    timestamp: z.string().optional(),
+    path: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    links: z.array(z.string()).optional(),
+    createdAt: z.string().datetime()
+});
+/** A single semantic-search hit: the matched document and its cosine score (1 = identical). */
+export const KbSearchHitDtoSchema = z.object({
+    id: z.string().min(1),
+    content: z.string(),
+    score: z.number(),
+    type: z.string().optional(),
+    title: z.string().optional()
+});
+/**
+ * Body for ingesting raw documents into a namespace — each is embedded then stored. `.max(500)`
+ * (issue #453, security audit 2026-07-20 MEDIUM finding): the array itself had no upper bound,
+ * so a single request could enqueue an unbounded embedding workload. 500 comfortably covers a
+ * real batch ingest without leaving the endpoint effectively unbounded.
+ */
+export const IngestKbDocumentsDtoSchema = z.object({
+    documents: z
+        .array(z.object({
+        id: z.string().min(1).optional(),
+        content: z.string().min(1)
+    }))
+        .min(1)
+        .max(500)
+});
+/** One file of an OKF bundle: a bundle-relative path and its raw markdown contents. */
+export const OkfFileSchema = z.object({
+    path: z.string().min(1),
+    content: z.string()
+});
+/** Body for ingesting an OKF bundle — a set of markdown (+frontmatter) files. */
+export const IngestOkfBundleDtoSchema = z.object({
+    // Same unbounded-array gap as IngestKbDocumentsDtoSchema.documents (issue #453) — capped for
+    // the same reason: a client-supplied file array with no upper bound.
+    files: z.array(OkfFileSchema).min(1).max(500)
+});
+/** An OKF bundle returned by export — markdown files reconstructed from stored documents. */
+export const OkfBundleDtoSchema = z.object({
+    files: z.array(OkfFileSchema)
+});
+/** Body for ingesting a web page by URL — fetched, stripped to text, stored with provenance. */
+export const IngestUrlDtoSchema = z.object({
+    url: z.string().url(),
+    title: z.string().optional()
+});
+/**
+ * Body for ingesting records from a JSON HTTP API (the generic SaaS-connector substrate:
+ * Slack/Notion/HubSpot are this with their base URL + a bearer header). Fetches `url`,
+ * walks `itemsPath` to an array, and maps each record's fields to an OKF document.
+ */
+export const IngestApiDtoSchema = z.object({
+    url: z.string().url(),
+    /** Dot path to the array of records (omit when the body is itself the array/object). */
+    itemsPath: z.string().optional(),
+    /** Field holding each record's text content. */
+    contentField: z.string().min(1),
+    idField: z.string().optional(),
+    titleField: z.string().optional(),
+    /** Extra request headers, e.g. `{ "authorization": "Bearer <token>" }`. */
+    headers: z.record(z.string(), z.string()).optional()
+});
+/** A node of the knowledge graph (a KB document). */
+export const KbGraphNodeSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().optional(),
+    type: z.string()
+});
+/** A typed edge of the knowledge graph: `from --type--> to`. */
+export const KbGraphEdgeSchema = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    type: z.string()
+});
+/** The knowledge graph of a namespace: typed relations between documents. */
+export const KbGraphDtoSchema = z.object({
+    nodes: z.array(KbGraphNodeSchema),
+    edges: z.array(KbGraphEdgeSchema)
+});
+/** Body for activation: search the KB for `query` and push the hits to a downstream webhook. */
+export const ActivateDtoSchema = z.object({
+    query: z.string().min(1),
+    webhookUrl: z.string().url(),
+    k: z.number().int().min(1).max(20).optional()
+});
+/** Result of an activation delivery. */
+export const ActivationResultDtoSchema = z.object({
+    delivered: z.boolean(),
+    status: z.number().int(),
+    hits: z.number().int().min(0)
+});
+//# sourceMappingURL=knowledge.js.map

package/dist/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../src/knowledge.ts"],"names":[],"mappings":"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"}

package/dist/knowledge.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=knowledge.test.d.ts.map

package/dist/knowledge.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.test.d.ts","sourceRoot":"","sources":["../src/knowledge.test.ts"],"names":[],"mappings":""}

package/dist/knowledge.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { IngestKbDocumentsDtoSchema, IngestOkfBundleDtoSchema } from "./knowledge.js";
+describe("IngestKbDocumentsDtoSchema (issue #453 — bounded documents array)", () => {
+    it("accepts a batch within the 500-document cap", () => {
+        const documents = Array.from({ length: 500 }, (_, i) => ({ content: `doc-${i}` }));
+        expect(() => IngestKbDocumentsDtoSchema.parse({ documents })).not.toThrow();
+    });
+    it("rejects a batch over the 500-document cap", () => {
+        const documents = Array.from({ length: 501 }, (_, i) => ({ content: `doc-${i}` }));
+        expect(() => IngestKbDocumentsDtoSchema.parse({ documents })).toThrow();
+    });
+    it("still rejects an empty batch (pre-existing .min(1))", () => {
+        expect(() => IngestKbDocumentsDtoSchema.parse({ documents: [] })).toThrow();
+    });
+});
+describe("IngestOkfBundleDtoSchema (issue #453 — bounded files array)", () => {
+    it("rejects a bundle over the 500-file cap", () => {
+        const files = Array.from({ length: 501 }, (_, i) => ({ path: `f${i}.md`, content: "x" }));
+        expect(() => IngestOkfBundleDtoSchema.parse({ files })).toThrow();
+    });
+});
+//# sourceMappingURL=knowledge.test.js.map

package/dist/knowledge.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.test.js","sourceRoot":"","sources":["../src/knowledge.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAEtF,QAAQ,CAAC,mEAAmE,EAAE,GAAG,EAAE;IACjF,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACnF,MAAM,CAAC,GAAG,EAAE,CAAC,0BAA0B,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAC9E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACnD,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACnF,MAAM,CAAC,GAAG,EAAE,CAAC,0BAA0B,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC1E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,GAAG,EAAE,CAAC,0BAA0B,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,6DAA6D,EAAE,GAAG,EAAE;IAC3E,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;QAC1F,MAAM,CAAC,GAAG,EAAE,CAAC,wBAAwB,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACpE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}