@z3rno/sdk 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,396 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas and inferred TypeScript types for the Z3rno API.
+ */
+
+declare const MemoryType: z.ZodEnum<["working", "episodic", "semantic", "procedural"]>;
+type MemoryType = z.infer<typeof MemoryType>;
+declare const RelationshipType: z.ZodEnum<["derived_from", "contradicts", "supports", "supersedes", "related_to", "caused_by"]>;
+type RelationshipType = z.infer<typeof RelationshipType>;
+declare const StoreMemoryRequest: z.ZodObject<{
+    agentId: z.ZodString;
+    content: z.ZodString;
+    memoryType: z.ZodDefault<z.ZodEnum<["working", "episodic", "semantic", "procedural"]>>;
+    userId: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    relationships: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        targetMemoryId: z.ZodString;
+        relationshipType: z.ZodEnum<["derived_from", "contradicts", "supports", "supersedes", "related_to", "caused_by"]>;
+        weight: z.ZodDefault<z.ZodNumber>;
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        metadata: Record<string, unknown>;
+        targetMemoryId: string;
+        relationshipType: "derived_from" | "contradicts" | "supports" | "supersedes" | "related_to" | "caused_by";
+        weight: number;
+    }, {
+        targetMemoryId: string;
+        relationshipType: "derived_from" | "contradicts" | "supports" | "supersedes" | "related_to" | "caused_by";
+        metadata?: Record<string, unknown> | undefined;
+        weight?: number | undefined;
+    }>, "many">>;
+    ttlSeconds: z.ZodOptional<z.ZodNumber>;
+    importance: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    agentId: string;
+    content: string;
+    memoryType: "working" | "episodic" | "semantic" | "procedural";
+    metadata: Record<string, unknown>;
+    relationships: {
+        metadata: Record<string, unknown>;
+        targetMemoryId: string;
+        relationshipType: "derived_from" | "contradicts" | "supports" | "supersedes" | "related_to" | "caused_by";
+        weight: number;
+    }[];
+    userId?: string | undefined;
+    ttlSeconds?: number | undefined;
+    importance?: number | undefined;
+}, {
+    agentId: string;
+    content: string;
+    memoryType?: "working" | "episodic" | "semantic" | "procedural" | undefined;
+    userId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    relationships?: {
+        targetMemoryId: string;
+        relationshipType: "derived_from" | "contradicts" | "supports" | "supersedes" | "related_to" | "caused_by";
+        metadata?: Record<string, unknown> | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    ttlSeconds?: number | undefined;
+    importance?: number | undefined;
+}>;
+type StoreMemoryRequest = z.infer<typeof StoreMemoryRequest>;
+declare const MemoryResponse: z.ZodObject<{
+    id: z.ZodString;
+    agent_id: z.ZodString;
+    content: z.ZodString;
+    memory_type: z.ZodString;
+    importance_score: z.ZodNumber;
+    recall_count: z.ZodNumber;
+    embedding_model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    metadata: Record<string, unknown>;
+    id: string;
+    agent_id: string;
+    memory_type: string;
+    importance_score: number;
+    recall_count: number;
+    created_at: string;
+    embedding_model?: string | null | undefined;
+}, {
+    content: string;
+    id: string;
+    agent_id: string;
+    memory_type: string;
+    importance_score: number;
+    recall_count: number;
+    created_at: string;
+    metadata?: Record<string, unknown> | undefined;
+    embedding_model?: string | null | undefined;
+}>;
+type MemoryResponse = z.infer<typeof MemoryResponse>;
+declare const RecallResultItem: z.ZodObject<{
+    memory_id: z.ZodString;
+    content: z.ZodString;
+    summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    memory_type: z.ZodString;
+    similarity_score: z.ZodNumber;
+    importance_score: z.ZodNumber;
+    relevance_score: z.ZodNumber;
+    recall_count: z.ZodNumber;
+    created_at: z.ZodString;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    metadata: Record<string, unknown>;
+    memory_type: string;
+    importance_score: number;
+    recall_count: number;
+    created_at: string;
+    memory_id: string;
+    similarity_score: number;
+    relevance_score: number;
+    summary?: string | null | undefined;
+}, {
+    content: string;
+    memory_type: string;
+    importance_score: number;
+    recall_count: number;
+    created_at: string;
+    memory_id: string;
+    similarity_score: number;
+    relevance_score: number;
+    metadata?: Record<string, unknown> | undefined;
+    summary?: string | null | undefined;
+}>;
+type RecallResultItem = z.infer<typeof RecallResultItem>;
+declare const RecallResponse: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        memory_id: z.ZodString;
+        content: z.ZodString;
+        summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        memory_type: z.ZodString;
+        similarity_score: z.ZodNumber;
+        importance_score: z.ZodNumber;
+        relevance_score: z.ZodNumber;
+        recall_count: z.ZodNumber;
+        created_at: z.ZodString;
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        metadata: Record<string, unknown>;
+        memory_type: string;
+        importance_score: number;
+        recall_count: number;
+        created_at: string;
+        memory_id: string;
+        similarity_score: number;
+        relevance_score: number;
+        summary?: string | null | undefined;
+    }, {
+        content: string;
+        memory_type: string;
+        importance_score: number;
+        recall_count: number;
+        created_at: string;
+        memory_id: string;
+        similarity_score: number;
+        relevance_score: number;
+        metadata?: Record<string, unknown> | undefined;
+        summary?: string | null | undefined;
+    }>, "many">;
+    total: z.ZodNumber;
+    query: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    results: {
+        content: string;
+        metadata: Record<string, unknown>;
+        memory_type: string;
+        importance_score: number;
+        recall_count: number;
+        created_at: string;
+        memory_id: string;
+        similarity_score: number;
+        relevance_score: number;
+        summary?: string | null | undefined;
+    }[];
+    total: number;
+    query?: string | null | undefined;
+}, {
+    results: {
+        content: string;
+        memory_type: string;
+        importance_score: number;
+        recall_count: number;
+        created_at: string;
+        memory_id: string;
+        similarity_score: number;
+        relevance_score: number;
+        metadata?: Record<string, unknown> | undefined;
+        summary?: string | null | undefined;
+    }[];
+    total: number;
+    query?: string | null | undefined;
+}>;
+type RecallResponse = z.infer<typeof RecallResponse>;
+declare const ForgetResponse: z.ZodObject<{
+    deleted_count: z.ZodNumber;
+    hard_deleted: z.ZodBoolean;
+    cascade_count: z.ZodNumber;
+    memory_ids: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    deleted_count: number;
+    hard_deleted: boolean;
+    cascade_count: number;
+    memory_ids: string[];
+}, {
+    deleted_count: number;
+    hard_deleted: boolean;
+    cascade_count: number;
+    memory_ids: string[];
+}>;
+type ForgetResponse = z.infer<typeof ForgetResponse>;
+declare const AuditEntry: z.ZodObject<{
+    id: z.ZodNumber;
+    agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    user_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    operation: z.ZodString;
+    memory_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    memory_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    details: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    ip_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: number;
+    created_at: string;
+    operation: string;
+    details: Record<string, unknown>;
+    agent_id?: string | null | undefined;
+    memory_type?: string | null | undefined;
+    memory_id?: string | null | undefined;
+    user_id?: string | null | undefined;
+    ip_address?: string | null | undefined;
+}, {
+    id: number;
+    created_at: string;
+    operation: string;
+    agent_id?: string | null | undefined;
+    memory_type?: string | null | undefined;
+    memory_id?: string | null | undefined;
+    user_id?: string | null | undefined;
+    details?: Record<string, unknown> | undefined;
+    ip_address?: string | null | undefined;
+}>;
+type AuditEntry = z.infer<typeof AuditEntry>;
+declare const AuditPageResponse: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        user_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        operation: z.ZodString;
+        memory_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        memory_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        details: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        ip_address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        created_at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: number;
+        created_at: string;
+        operation: string;
+        details: Record<string, unknown>;
+        agent_id?: string | null | undefined;
+        memory_type?: string | null | undefined;
+        memory_id?: string | null | undefined;
+        user_id?: string | null | undefined;
+        ip_address?: string | null | undefined;
+    }, {
+        id: number;
+        created_at: string;
+        operation: string;
+        agent_id?: string | null | undefined;
+        memory_type?: string | null | undefined;
+        memory_id?: string | null | undefined;
+        user_id?: string | null | undefined;
+        details?: Record<string, unknown> | undefined;
+        ip_address?: string | null | undefined;
+    }>, "many">;
+    total: z.ZodNumber;
+    page: z.ZodNumber;
+    page_size: z.ZodNumber;
+    has_next: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    entries: {
+        id: number;
+        created_at: string;
+        operation: string;
+        details: Record<string, unknown>;
+        agent_id?: string | null | undefined;
+        memory_type?: string | null | undefined;
+        memory_id?: string | null | undefined;
+        user_id?: string | null | undefined;
+        ip_address?: string | null | undefined;
+    }[];
+    total: number;
+    page: number;
+    page_size: number;
+    has_next: boolean;
+}, {
+    entries: {
+        id: number;
+        created_at: string;
+        operation: string;
+        agent_id?: string | null | undefined;
+        memory_type?: string | null | undefined;
+        memory_id?: string | null | undefined;
+        user_id?: string | null | undefined;
+        details?: Record<string, unknown> | undefined;
+        ip_address?: string | null | undefined;
+    }[];
+    total: number;
+    page: number;
+    page_size: number;
+    has_next: boolean;
+}>;
+type AuditPageResponse = z.infer<typeof AuditPageResponse>;
+
+/**
+ * Z3rno TypeScript SDK client.
+ *
+ * Thin fetch wrapper — no database drivers, no embedding providers.
+ *
+ * @example
+ * ```ts
+ * const client = new Z3rnoClient({ baseUrl: "http://localhost:8000", apiKey: "z3rno_sk_..." });
+ * const memory = await client.store({ agentId: "agent-1", content: "User prefers dark mode" });
+ * const results = await client.recall({ agentId: "agent-1", query: "user preferences" });
+ * await client.forget({ agentId: "agent-1", memoryId: memory.id });
+ * ```
+ */
+
+interface Z3rnoClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+declare class Z3rnoClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    constructor(config: Z3rnoClientConfig);
+    store(request: StoreMemoryRequest): Promise<MemoryResponse>;
+    recall(params: {
+        agentId: string;
+        query?: string;
+        memoryType?: string;
+        filters?: Record<string, unknown>;
+        topK?: number;
+        similarityThreshold?: number;
+    }): Promise<RecallResponse>;
+    forget(params: {
+        agentId: string;
+        memoryId?: string;
+        memoryIds?: string[];
+        hardDelete?: boolean;
+        cascade?: boolean;
+        reason?: string;
+    }): Promise<ForgetResponse>;
+    audit(params?: {
+        agentId?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<AuditPageResponse>;
+    private request;
+    private handleResponse;
+}
+
+/**
+ * Z3rno SDK error hierarchy.
+ */
+declare class Z3rnoError extends Error {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+declare class AuthenticationError extends Z3rnoError {
+    constructor(message: string);
+}
+declare class RateLimitError extends Z3rnoError {
+    retryAfter: number;
+    constructor(message: string, retryAfter?: number);
+}
+declare class ValidationError extends Z3rnoError {
+    constructor(message: string, statusCode?: number);
+}
+declare class NotFoundError extends Z3rnoError {
+    constructor(message: string);
+}
+declare class ServerError extends Z3rnoError {
+    constructor(message: string, statusCode?: number);
+}
+
+export { AuditEntry, AuditPageResponse, AuthenticationError, ForgetResponse, MemoryResponse, MemoryType, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RelationshipType, ServerError, StoreMemoryRequest, ValidationError, Z3rnoClient, type Z3rnoClientConfig, Z3rnoError };

package/dist/index.js

@@ -0,0 +1,276 @@
+import { z } from 'zod';
+
+// src/errors.ts
+var Z3rnoError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "Z3rnoError";
+    this.statusCode = statusCode;
+  }
+};
+var AuthenticationError = class extends Z3rnoError {
+  constructor(message) {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends Z3rnoError {
+  retryAfter;
+  constructor(message, retryAfter = 60) {
+    super(message, 429);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ValidationError = class extends Z3rnoError {
+  constructor(message, statusCode = 400) {
+    super(message, statusCode);
+    this.name = "ValidationError";
+  }
+};
+var NotFoundError = class extends Z3rnoError {
+  constructor(message) {
+    super(message, 404);
+    this.name = "NotFoundError";
+  }
+};
+var ServerError = class extends Z3rnoError {
+  constructor(message, statusCode = 500) {
+    super(message, statusCode);
+    this.name = "ServerError";
+  }
+};
+var MemoryType = z.enum([
+  "working",
+  "episodic",
+  "semantic",
+  "procedural"
+]);
+var RelationshipType = z.enum([
+  "derived_from",
+  "contradicts",
+  "supports",
+  "supersedes",
+  "related_to",
+  "caused_by"
+]);
+z.object({
+  agentId: z.string().uuid(),
+  content: z.string().min(1).max(1e5),
+  memoryType: MemoryType.default("episodic"),
+  userId: z.string().uuid().optional(),
+  metadata: z.record(z.unknown()).default({}),
+  relationships: z.array(
+    z.object({
+      targetMemoryId: z.string().uuid(),
+      relationshipType: RelationshipType,
+      weight: z.number().min(0).max(1).default(1),
+      metadata: z.record(z.unknown()).default({})
+    })
+  ).default([]),
+  ttlSeconds: z.number().int().positive().optional(),
+  importance: z.number().min(0).max(1).optional()
+});
+z.object({
+  agentId: z.string().uuid(),
+  query: z.string().optional(),
+  memoryType: z.string().optional(),
+  filters: z.record(z.unknown()).optional(),
+  topK: z.number().int().min(1).max(100).default(10),
+  similarityThreshold: z.number().min(0).max(1).default(0),
+  asOf: z.string().datetime().optional(),
+  includeDeleted: z.boolean().default(false)
+});
+z.object({
+  agentId: z.string().uuid(),
+  memoryId: z.string().uuid().optional(),
+  memoryIds: z.array(z.string().uuid()).optional(),
+  hardDelete: z.boolean().default(false),
+  cascade: z.boolean().default(false),
+  reason: z.string().optional()
+});
+var MemoryResponse = z.object({
+  id: z.string(),
+  agent_id: z.string(),
+  content: z.string(),
+  memory_type: z.string(),
+  importance_score: z.number(),
+  recall_count: z.number(),
+  embedding_model: z.string().nullable().optional(),
+  created_at: z.string(),
+  metadata: z.record(z.unknown()).default({})
+});
+var RecallResultItem = z.object({
+  memory_id: z.string(),
+  content: z.string(),
+  summary: z.string().nullable().optional(),
+  memory_type: z.string(),
+  similarity_score: z.number(),
+  importance_score: z.number(),
+  relevance_score: z.number(),
+  recall_count: z.number(),
+  created_at: z.string(),
+  metadata: z.record(z.unknown()).default({})
+});
+var RecallResponse = z.object({
+  results: z.array(RecallResultItem),
+  total: z.number(),
+  query: z.string().nullable().optional()
+});
+var ForgetResponse = z.object({
+  deleted_count: z.number(),
+  hard_deleted: z.boolean(),
+  cascade_count: z.number(),
+  memory_ids: z.array(z.string())
+});
+var AuditEntry = z.object({
+  id: z.number(),
+  agent_id: z.string().nullable().optional(),
+  user_id: z.string().nullable().optional(),
+  operation: z.string(),
+  memory_id: z.string().nullable().optional(),
+  memory_type: z.string().nullable().optional(),
+  details: z.record(z.unknown()).default({}),
+  ip_address: z.string().nullable().optional(),
+  created_at: z.string()
+});
+var AuditPageResponse = z.object({
+  entries: z.array(AuditEntry),
+  total: z.number(),
+  page: z.number(),
+  page_size: z.number(),
+  has_next: z.boolean()
+});
+
+// src/client.ts
+var Z3rnoClient = class {
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? 3e4;
+  }
+  // --- Store ---
+  async store(request) {
+    const body = {
+      agent_id: request.agentId,
+      content: request.content,
+      memory_type: request.memoryType,
+      user_id: request.userId,
+      metadata: request.metadata,
+      relationships: request.relationships?.map((r) => ({
+        target_memory_id: r.targetMemoryId,
+        relationship_type: r.relationshipType,
+        weight: r.weight,
+        metadata: r.metadata
+      })),
+      ttl_seconds: request.ttlSeconds,
+      importance: request.importance
+    };
+    const resp = await this.request("POST", "/v1/memories", body);
+    return MemoryResponse.parse(resp);
+  }
+  // --- Recall ---
+  async recall(params) {
+    const body = {
+      agent_id: params.agentId,
+      query: params.query,
+      memory_type: params.memoryType,
+      filters: params.filters,
+      top_k: params.topK ?? 10,
+      similarity_threshold: params.similarityThreshold ?? 0
+    };
+    const resp = await this.request("POST", "/v1/memories/recall", body);
+    return RecallResponse.parse(resp);
+  }
+  // --- Forget ---
+  async forget(params) {
+    const body = {
+      agent_id: params.agentId,
+      memory_id: params.memoryId,
+      memory_ids: params.memoryIds,
+      hard_delete: params.hardDelete ?? false,
+      cascade: params.cascade ?? false,
+      reason: params.reason
+    };
+    const resp = await this.request("POST", "/v1/memories/forget", body);
+    return ForgetResponse.parse(resp);
+  }
+  // --- Audit ---
+  async audit(params) {
+    const searchParams = new URLSearchParams();
+    if (params?.agentId) searchParams.set("agent_id", params.agentId);
+    if (params?.page) searchParams.set("page", String(params.page));
+    if (params?.pageSize)
+      searchParams.set("page_size", String(params.pageSize));
+    const query = searchParams.toString();
+    const path = query ? `/v1/audit?${query}` : "/v1/audit";
+    const resp = await this.request("GET", path);
+    return AuditPageResponse.parse(resp);
+  }
+  // --- HTTP layer ---
+  async request(method, path, body) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "@z3rno/sdk/0.0.1"
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      return this.handleResponse(response);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Z3rnoError) throw error;
+      throw new Z3rnoError(`Request failed: ${String(error)}`);
+    }
+  }
+  async handleResponse(resp) {
+    if (resp.ok) {
+      return resp.json();
+    }
+    let detail = resp.statusText;
+    try {
+      const body = await resp.json();
+      detail = String(body.detail ?? body.error ?? resp.statusText);
+    } catch {
+    }
+    switch (resp.status) {
+      case 401:
+        throw new AuthenticationError(`Authentication failed: ${detail}`);
+      case 404:
+        throw new NotFoundError(`Not found: ${detail}`);
+      case 429: {
+        const retryAfter = parseInt(
+          resp.headers.get("Retry-After") ?? "60",
+          10
+        );
+        throw new RateLimitError(`Rate limit exceeded: ${detail}`, retryAfter);
+      }
+      case 400:
+      case 422:
+        throw new ValidationError(detail, resp.status);
+      default:
+        if (resp.status >= 500) {
+          throw new ServerError(`Server error: ${detail}`, resp.status);
+        }
+        throw new Z3rnoError(
+          `Unexpected error (${resp.status}): ${detail}`,
+          resp.status
+        );
+    }
+  }
+};
+
+export { AuditEntry, AuditPageResponse, AuthenticationError, ForgetResponse, MemoryResponse, MemoryType, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RelationshipType, ServerError, ValidationError, Z3rnoClient, Z3rnoError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map