@seizn/spring 0.1.0

package/README.md

@@ -0,0 +1,198 @@
+# @seizn/spring
+
+Semantic Memory SDK for AI Applications. Store, search, and retrieve memories with automatic embedding and vector similarity search.
+
+## Installation
+
+```bash
+npm install @seizn/spring
+# or
+yarn add @seizn/spring
+# or
+pnpm add @seizn/spring
+```
+
+## Quick Start
+
+```typescript
+import { SpringClient } from '@seizn/spring';
+
+const spring = new SpringClient({
+  apiKey: process.env.SEIZN_API_KEY!,
+  namespace: 'my-app',
+});
+
+// Store a memory
+await spring.remember('User prefers dark mode');
+
+// Search memories
+const memories = await spring.recall('UI preferences');
+console.log(memories);
+```
+
+## Features
+
+- **Semantic Search**: Vector-based similarity search with automatic embedding
+- **Hybrid Search**: Combine vector and keyword search for better results
+- **Memory Types**: Organize memories by type (fact, preference, experience, etc.)
+- **Namespaces**: Isolate memories by namespace for multi-tenant apps
+- **Bulk Operations**: Add multiple memories in a single request
+- **Export/Import**: Backup and restore memories
+
+## API Reference
+
+### Configuration
+
+```typescript
+const spring = new SpringClient({
+  apiKey: 'szn_...',           // Required: Your Seizn API key
+  namespace: 'default',        // Optional: Default namespace
+  baseUrl: 'https://seizn.com/api',  // Optional: API base URL
+  timeout: 30000,              // Optional: Request timeout (ms)
+  retries: 3,                  // Optional: Max retry attempts
+  onError: (error) => {},      // Optional: Error callback
+});
+```
+
+### Core Methods
+
+#### `add(request)` - Add a memory
+
+```typescript
+const memory = await spring.add({
+  content: 'User prefers dark mode',
+  memory_type: 'preference',   // fact | preference | experience | relationship | instruction | conversation
+  tags: ['ui', 'settings'],
+  namespace: 'my-app',
+});
+```
+
+#### `search(query)` - Search memories
+
+```typescript
+// Simple search
+const results = await spring.search('UI preferences');
+
+// Advanced search
+const results = await spring.search({
+  query: 'UI preferences',
+  limit: 10,
+  threshold: 0.7,
+  mode: 'hybrid',  // vector | hybrid | keyword
+  tags: ['ui'],
+});
+```
+
+#### `get(id)` - Get a memory by ID
+
+```typescript
+const memory = await spring.get('mem_123');
+```
+
+#### `update(id, request)` - Update a memory
+
+```typescript
+const memory = await spring.update('mem_123', {
+  content: 'User prefers light mode',
+  tags: ['ui', 'settings', 'updated'],
+});
+```
+
+#### `delete(ids)` - Delete memories
+
+```typescript
+await spring.delete('mem_123');
+// or delete multiple
+await spring.delete(['mem_123', 'mem_456']);
+```
+
+### Shortcuts
+
+```typescript
+// remember = add with type 'fact'
+await spring.remember('Important fact');
+
+// recall = search and return results array
+const memories = await spring.recall('query', 5);
+
+// forget = delete
+await spring.forget('mem_123');
+```
+
+### Bulk Operations
+
+```typescript
+const result = await spring.bulkAdd([
+  { content: 'Memory 1', memory_type: 'fact' },
+  { content: 'Memory 2', memory_type: 'preference' },
+]);
+console.log(`Added: ${result.added}, Failed: ${result.failed}`);
+```
+
+### Export/Import
+
+```typescript
+// Export all memories
+const backup = await spring.export();
+
+// Export specific namespace
+const backup = await spring.export({ namespace: 'my-app' });
+
+// Import memories
+const result = await spring.import(backup);
+console.log(`Imported: ${result.imported}, Skipped: ${result.skipped}`);
+```
+
+### Analytics
+
+```typescript
+const stats = await spring.stats();
+console.log(`Total memories: ${stats.totalMemories}`);
+console.log(`Storage used: ${stats.storageUsedMb} MB`);
+```
+
+## Error Handling
+
+```typescript
+import { SpringClient, SpringError } from '@seizn/spring';
+
+const spring = new SpringClient({
+  apiKey: 'szn_...',
+  onError: (error: SpringError) => {
+    console.error(`Error [${error.code}]: ${error.message}`);
+  },
+});
+
+try {
+  await spring.search('query');
+} catch (error) {
+  if ((error as SpringError).code === 'RATE_LIMITED') {
+    // Handle rate limiting
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  Memory,
+  MemoryType,
+  MemoryScope,
+  SearchMode,
+  SpringClientConfig,
+  SpringError,
+} from '@seizn/spring';
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Documentation](https://docs.seizn.com/spring)
+- [API Reference](https://docs.seizn.com/api-reference)
+- [GitHub](https://github.com/iruhana/seizn)

package/dist/index.d.mts

@@ -0,0 +1,224 @@
+/**
+ * Seizn Spring (Memory Layer) - Core Types
+ *
+ * Type definitions for the Spring Memory SDK.
+ * These types define the wire format for SDK consumers.
+ */
+type MemoryType = 'fact' | 'preference' | 'experience' | 'relationship' | 'instruction' | 'conversation';
+type MemoryScope = 'user' | 'session' | 'global' | 'project';
+interface Memory {
+    id: string;
+    content: string;
+    memoryType: MemoryType;
+    tags: string[];
+    namespace: string;
+    scope: MemoryScope;
+    sessionId?: string;
+    agentId?: string;
+    source: string;
+    confidence: number;
+    importance: number;
+    createdAt: string;
+    updatedAt?: string;
+    accessCount?: number;
+    lastAccessedAt?: string;
+}
+interface MemorySearchResult extends Memory {
+    similarity: number;
+    combinedScore?: number;
+    keywordScore?: number;
+}
+interface AddMemoryRequest {
+    content: string;
+    memory_type?: MemoryType;
+    tags?: string[];
+    namespace?: string;
+    scope?: MemoryScope;
+    session_id?: string;
+    agent_id?: string;
+    source?: string;
+}
+interface AddMemoryResponse {
+    success: boolean;
+    memory: Memory;
+}
+type SearchMode = 'vector' | 'hybrid' | 'keyword';
+interface SearchMemoriesRequest {
+    query: string;
+    limit?: number;
+    threshold?: number;
+    namespace?: string;
+    mode?: SearchMode;
+    tags?: string[];
+}
+interface SearchMemoriesResponse {
+    success: boolean;
+    mode: SearchMode;
+    results: MemorySearchResult[];
+    count: number;
+}
+interface UpdateMemoryRequest {
+    content?: string;
+    memory_type?: MemoryType;
+    tags?: string[];
+    namespace?: string;
+    importance?: number;
+}
+interface UpdateMemoryResponse {
+    success: boolean;
+    memory: Memory;
+}
+interface DeleteMemoriesRequest {
+    ids: string[];
+}
+interface DeleteMemoriesResponse {
+    success: boolean;
+    deleted: number;
+}
+interface MemoryExport {
+    version: '1.0';
+    exportedAt: string;
+    userId: string;
+    namespace?: string;
+    memories: Memory[];
+    count: number;
+}
+interface MemoryImportResult {
+    success: boolean;
+    imported: number;
+    skipped: number;
+    errors: string[];
+}
+interface SpringClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    namespace?: string;
+    timeout?: number;
+    retries?: number;
+    onError?: (error: SpringError) => void;
+}
+interface SpringError {
+    code: string;
+    message: string;
+    status?: number;
+    details?: Record<string, unknown>;
+}
+interface BulkAddRequest {
+    memories: AddMemoryRequest[];
+}
+interface BulkAddResponse {
+    success: boolean;
+    added: number;
+    failed: number;
+    errors?: Array<{
+        index: number;
+        error: string;
+    }>;
+}
+interface MemoryStats {
+    totalMemories: number;
+    byType: Record<MemoryType, number>;
+    byNamespace: Record<string, number>;
+    recentAccessCount: number;
+    storageUsedMb: number;
+}
+interface MemoryUsage {
+    period: 'day' | 'week' | 'month';
+    searches: number;
+    additions: number;
+    deletions: number;
+    embeddingTokens: number;
+}
+
+/**
+ * Seizn Spring SDK Client
+ *
+ * TypeScript/JavaScript SDK for the Spring Memory API.
+ * Provides a simple interface for memory operations.
+ *
+ * @example
+ * ```typescript
+ * import { SpringClient } from '@seizn/spring';
+ *
+ * const spring = new SpringClient({
+ *   apiKey: 'szn_...',
+ *   namespace: 'my-app',
+ * });
+ *
+ * // Add a memory
+ * await spring.add({
+ *   content: 'User prefers dark mode',
+ *   memory_type: 'preference',
+ * });
+ *
+ * // Search memories
+ * const results = await spring.search('UI preferences');
+ * ```
+ */
+
+declare class SpringClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly namespace;
+    private readonly timeout;
+    private readonly retries;
+    private readonly onError?;
+    constructor(config: SpringClientConfig);
+    /**
+     * Add a new memory
+     */
+    add(request: AddMemoryRequest): Promise<Memory>;
+    /**
+     * Search for memories
+     */
+    search(queryOrRequest: string | SearchMemoriesRequest): Promise<SearchMemoriesResponse>;
+    /**
+     * Get a memory by ID
+     */
+    get(id: string): Promise<Memory>;
+    /**
+     * Update a memory
+     */
+    update(id: string, request: UpdateMemoryRequest): Promise<Memory>;
+    /**
+     * Delete memories by IDs
+     */
+    delete(ids: string | string[]): Promise<number>;
+    /**
+     * Add multiple memories at once
+     */
+    bulkAdd(memories: AddMemoryRequest[]): Promise<BulkAddResponse>;
+    /**
+     * Export memories
+     */
+    export(options?: {
+        namespace?: string;
+    }): Promise<MemoryExport>;
+    /**
+     * Import memories from export
+     */
+    import(data: MemoryExport): Promise<MemoryImportResult>;
+    /**
+     * Get memory statistics
+     */
+    stats(): Promise<MemoryStats>;
+    /**
+     * Quick remember - shorthand for adding a fact
+     */
+    remember(content: string, tags?: string[]): Promise<Memory>;
+    /**
+     * Quick recall - shorthand for searching
+     */
+    recall(query: string, limit?: number): Promise<Memory[]>;
+    /**
+     * Forget - shorthand for deleting
+     */
+    forget(ids: string | string[]): Promise<number>;
+    private request;
+}
+/**
+ * Create a Spring client instance
+ */
+declare function createSpringClient(config: SpringClientConfig): SpringClient;
+
+export { type AddMemoryRequest, type AddMemoryResponse, type BulkAddRequest, type BulkAddResponse, type DeleteMemoriesRequest, type DeleteMemoriesResponse, type Memory, type MemoryExport, type MemoryImportResult, type MemoryScope, type MemorySearchResult, type MemoryStats, type MemoryType, type MemoryUsage, type SearchMemoriesRequest, type SearchMemoriesResponse, type SearchMode, SpringClient, type SpringClientConfig, type SpringError, type UpdateMemoryRequest, type UpdateMemoryResponse, createSpringClient };

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Seizn Spring (Memory Layer) - Core Types
+ *
+ * Type definitions for the Spring Memory SDK.
+ * These types define the wire format for SDK consumers.
+ */
+type MemoryType = 'fact' | 'preference' | 'experience' | 'relationship' | 'instruction' | 'conversation';
+type MemoryScope = 'user' | 'session' | 'global' | 'project';
+interface Memory {
+    id: string;
+    content: string;
+    memoryType: MemoryType;
+    tags: string[];
+    namespace: string;
+    scope: MemoryScope;
+    sessionId?: string;
+    agentId?: string;
+    source: string;
+    confidence: number;
+    importance: number;
+    createdAt: string;
+    updatedAt?: string;
+    accessCount?: number;
+    lastAccessedAt?: string;
+}
+interface MemorySearchResult extends Memory {
+    similarity: number;
+    combinedScore?: number;
+    keywordScore?: number;
+}
+interface AddMemoryRequest {
+    content: string;
+    memory_type?: MemoryType;
+    tags?: string[];
+    namespace?: string;
+    scope?: MemoryScope;
+    session_id?: string;
+    agent_id?: string;
+    source?: string;
+}
+interface AddMemoryResponse {
+    success: boolean;
+    memory: Memory;
+}
+type SearchMode = 'vector' | 'hybrid' | 'keyword';
+interface SearchMemoriesRequest {
+    query: string;
+    limit?: number;
+    threshold?: number;
+    namespace?: string;
+    mode?: SearchMode;
+    tags?: string[];
+}
+interface SearchMemoriesResponse {
+    success: boolean;
+    mode: SearchMode;
+    results: MemorySearchResult[];
+    count: number;
+}
+interface UpdateMemoryRequest {
+    content?: string;
+    memory_type?: MemoryType;
+    tags?: string[];
+    namespace?: string;
+    importance?: number;
+}
+interface UpdateMemoryResponse {
+    success: boolean;
+    memory: Memory;
+}
+interface DeleteMemoriesRequest {
+    ids: string[];
+}
+interface DeleteMemoriesResponse {
+    success: boolean;
+    deleted: number;
+}
+interface MemoryExport {
+    version: '1.0';
+    exportedAt: string;
+    userId: string;
+    namespace?: string;
+    memories: Memory[];
+    count: number;
+}
+interface MemoryImportResult {
+    success: boolean;
+    imported: number;
+    skipped: number;
+    errors: string[];
+}
+interface SpringClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    namespace?: string;
+    timeout?: number;
+    retries?: number;
+    onError?: (error: SpringError) => void;
+}
+interface SpringError {
+    code: string;
+    message: string;
+    status?: number;
+    details?: Record<string, unknown>;
+}
+interface BulkAddRequest {
+    memories: AddMemoryRequest[];
+}
+interface BulkAddResponse {
+    success: boolean;
+    added: number;
+    failed: number;
+    errors?: Array<{
+        index: number;
+        error: string;
+    }>;
+}
+interface MemoryStats {
+    totalMemories: number;
+    byType: Record<MemoryType, number>;
+    byNamespace: Record<string, number>;
+    recentAccessCount: number;
+    storageUsedMb: number;
+}
+interface MemoryUsage {
+    period: 'day' | 'week' | 'month';
+    searches: number;
+    additions: number;
+    deletions: number;
+    embeddingTokens: number;
+}
+
+/**
+ * Seizn Spring SDK Client
+ *
+ * TypeScript/JavaScript SDK for the Spring Memory API.
+ * Provides a simple interface for memory operations.
+ *
+ * @example
+ * ```typescript
+ * import { SpringClient } from '@seizn/spring';
+ *
+ * const spring = new SpringClient({
+ *   apiKey: 'szn_...',
+ *   namespace: 'my-app',
+ * });
+ *
+ * // Add a memory
+ * await spring.add({
+ *   content: 'User prefers dark mode',
+ *   memory_type: 'preference',
+ * });
+ *
+ * // Search memories
+ * const results = await spring.search('UI preferences');
+ * ```
+ */
+
+declare class SpringClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly namespace;
+    private readonly timeout;
+    private readonly retries;
+    private readonly onError?;
+    constructor(config: SpringClientConfig);
+    /**
+     * Add a new memory
+     */
+    add(request: AddMemoryRequest): Promise<Memory>;
+    /**
+     * Search for memories
+     */
+    search(queryOrRequest: string | SearchMemoriesRequest): Promise<SearchMemoriesResponse>;
+    /**
+     * Get a memory by ID
+     */
+    get(id: string): Promise<Memory>;
+    /**
+     * Update a memory
+     */
+    update(id: string, request: UpdateMemoryRequest): Promise<Memory>;
+    /**
+     * Delete memories by IDs
+     */
+    delete(ids: string | string[]): Promise<number>;
+    /**
+     * Add multiple memories at once
+     */
+    bulkAdd(memories: AddMemoryRequest[]): Promise<BulkAddResponse>;
+    /**
+     * Export memories
+     */
+    export(options?: {
+        namespace?: string;
+    }): Promise<MemoryExport>;
+    /**
+     * Import memories from export
+     */
+    import(data: MemoryExport): Promise<MemoryImportResult>;
+    /**
+     * Get memory statistics
+     */
+    stats(): Promise<MemoryStats>;
+    /**
+     * Quick remember - shorthand for adding a fact
+     */
+    remember(content: string, tags?: string[]): Promise<Memory>;
+    /**
+     * Quick recall - shorthand for searching
+     */
+    recall(query: string, limit?: number): Promise<Memory[]>;
+    /**
+     * Forget - shorthand for deleting
+     */
+    forget(ids: string | string[]): Promise<number>;
+    private request;
+}
+/**
+ * Create a Spring client instance
+ */
+declare function createSpringClient(config: SpringClientConfig): SpringClient;
+
+export { type AddMemoryRequest, type AddMemoryResponse, type BulkAddRequest, type BulkAddResponse, type DeleteMemoriesRequest, type DeleteMemoriesResponse, type Memory, type MemoryExport, type MemoryImportResult, type MemoryScope, type MemorySearchResult, type MemoryStats, type MemoryType, type MemoryUsage, type SearchMemoriesRequest, type SearchMemoriesResponse, type SearchMode, SpringClient, type SpringClientConfig, type SpringError, type UpdateMemoryRequest, type UpdateMemoryResponse, createSpringClient };

package/dist/index.js

@@ -0,0 +1,255 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SpringClient: () => SpringClient,
+  createSpringClient: () => createSpringClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://seizn.com/api";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_RETRIES = 3;
+var SpringClient = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.namespace = config.namespace ?? "default";
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.retries = config.retries ?? DEFAULT_RETRIES;
+    this.onError = config.onError;
+  }
+  // ============================================
+  // Core Operations
+  // ============================================
+  /**
+   * Add a new memory
+   */
+  async add(request) {
+    const response = await this.request("/memories", {
+      method: "POST",
+      body: {
+        ...request,
+        namespace: request.namespace ?? this.namespace
+      }
+    });
+    return response.memory;
+  }
+  /**
+   * Search for memories
+   */
+  async search(queryOrRequest) {
+    const params = typeof queryOrRequest === "string" ? { query: queryOrRequest } : queryOrRequest;
+    const searchParams = new URLSearchParams({
+      query: params.query,
+      limit: String(params.limit ?? 10),
+      threshold: String(params.threshold ?? 0.7),
+      namespace: params.namespace ?? this.namespace,
+      mode: params.mode ?? "vector"
+    });
+    if (params.tags?.length) {
+      searchParams.set("tags", params.tags.join(","));
+    }
+    return this.request(`/memories?${searchParams}`);
+  }
+  /**
+   * Get a memory by ID
+   */
+  async get(id) {
+    const response = await this.request(
+      `/memories/${id}`
+    );
+    return response.memory;
+  }
+  /**
+   * Update a memory
+   */
+  async update(id, request) {
+    const response = await this.request(`/memories/${id}`, {
+      method: "PUT",
+      body: request
+    });
+    return response.memory;
+  }
+  /**
+   * Delete memories by IDs
+   */
+  async delete(ids) {
+    const idsArray = Array.isArray(ids) ? ids : [ids];
+    const response = await this.request(
+      `/memories?ids=${idsArray.join(",")}`,
+      { method: "DELETE" }
+    );
+    return response.deleted;
+  }
+  // ============================================
+  // Bulk Operations
+  // ============================================
+  /**
+   * Add multiple memories at once
+   */
+  async bulkAdd(memories) {
+    const request = {
+      memories: memories.map((m) => ({
+        ...m,
+        namespace: m.namespace ?? this.namespace
+      }))
+    };
+    return this.request("/memories/bulk", {
+      method: "POST",
+      body: request
+    });
+  }
+  // ============================================
+  // Export/Import
+  // ============================================
+  /**
+   * Export memories
+   */
+  async export(options) {
+    const params = new URLSearchParams();
+    if (options?.namespace) {
+      params.set("namespace", options.namespace);
+    }
+    const queryString = params.toString();
+    return this.request(
+      `/memories/export${queryString ? `?${queryString}` : ""}`
+    );
+  }
+  /**
+   * Import memories from export
+   */
+  async import(data) {
+    return this.request("/memories/import", {
+      method: "POST",
+      body: data
+    });
+  }
+  // ============================================
+  // Analytics
+  // ============================================
+  /**
+   * Get memory statistics
+   */
+  async stats() {
+    return this.request("/memories/stats");
+  }
+  // ============================================
+  // Helpers
+  // ============================================
+  /**
+   * Quick remember - shorthand for adding a fact
+   */
+  async remember(content, tags) {
+    return this.add({
+      content,
+      memory_type: "fact",
+      tags
+    });
+  }
+  /**
+   * Quick recall - shorthand for searching
+   */
+  async recall(query, limit = 5) {
+    const response = await this.search({ query, limit });
+    return response.results;
+  }
+  /**
+   * Forget - shorthand for deleting
+   */
+  async forget(ids) {
+    return this.delete(ids);
+  }
+  // ============================================
+  // Internal
+  // ============================================
+  async request(path, options) {
+    const url = `${this.baseUrl}${path}`;
+    const method = options?.method ?? "GET";
+    let lastError = null;
+    for (let attempt = 0; attempt < this.retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const response = await fetch(url, {
+          method,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json"
+          },
+          body: options?.body ? JSON.stringify(options.body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          const error = {
+            code: errorData.code ?? "REQUEST_FAILED",
+            message: errorData.error ?? errorData.message ?? `Request failed with status ${response.status}`,
+            status: response.status,
+            details: errorData
+          };
+          if (response.status >= 400 && response.status < 500) {
+            this.onError?.(error);
+            throw error;
+          }
+          lastError = error;
+          continue;
+        }
+        return response.json();
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          lastError = {
+            code: "TIMEOUT",
+            message: `Request timed out after ${this.timeout}ms`
+          };
+        } else if (error.code) {
+          throw error;
+        } else {
+          lastError = {
+            code: "NETWORK_ERROR",
+            message: error instanceof Error ? error.message : "Network error"
+          };
+        }
+        if (attempt < this.retries - 1) {
+          await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 1e3));
+        }
+      }
+    }
+    if (lastError) {
+      this.onError?.(lastError);
+      throw lastError;
+    }
+    throw { code: "UNKNOWN", message: "Unknown error" };
+  }
+};
+function createSpringClient(config) {
+  return new SpringClient(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SpringClient,
+  createSpringClient
+});

package/dist/index.mjs

@@ -0,0 +1,227 @@
+// src/client.ts
+var DEFAULT_BASE_URL = "https://seizn.com/api";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_RETRIES = 3;
+var SpringClient = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.namespace = config.namespace ?? "default";
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.retries = config.retries ?? DEFAULT_RETRIES;
+    this.onError = config.onError;
+  }
+  // ============================================
+  // Core Operations
+  // ============================================
+  /**
+   * Add a new memory
+   */
+  async add(request) {
+    const response = await this.request("/memories", {
+      method: "POST",
+      body: {
+        ...request,
+        namespace: request.namespace ?? this.namespace
+      }
+    });
+    return response.memory;
+  }
+  /**
+   * Search for memories
+   */
+  async search(queryOrRequest) {
+    const params = typeof queryOrRequest === "string" ? { query: queryOrRequest } : queryOrRequest;
+    const searchParams = new URLSearchParams({
+      query: params.query,
+      limit: String(params.limit ?? 10),
+      threshold: String(params.threshold ?? 0.7),
+      namespace: params.namespace ?? this.namespace,
+      mode: params.mode ?? "vector"
+    });
+    if (params.tags?.length) {
+      searchParams.set("tags", params.tags.join(","));
+    }
+    return this.request(`/memories?${searchParams}`);
+  }
+  /**
+   * Get a memory by ID
+   */
+  async get(id) {
+    const response = await this.request(
+      `/memories/${id}`
+    );
+    return response.memory;
+  }
+  /**
+   * Update a memory
+   */
+  async update(id, request) {
+    const response = await this.request(`/memories/${id}`, {
+      method: "PUT",
+      body: request
+    });
+    return response.memory;
+  }
+  /**
+   * Delete memories by IDs
+   */
+  async delete(ids) {
+    const idsArray = Array.isArray(ids) ? ids : [ids];
+    const response = await this.request(
+      `/memories?ids=${idsArray.join(",")}`,
+      { method: "DELETE" }
+    );
+    return response.deleted;
+  }
+  // ============================================
+  // Bulk Operations
+  // ============================================
+  /**
+   * Add multiple memories at once
+   */
+  async bulkAdd(memories) {
+    const request = {
+      memories: memories.map((m) => ({
+        ...m,
+        namespace: m.namespace ?? this.namespace
+      }))
+    };
+    return this.request("/memories/bulk", {
+      method: "POST",
+      body: request
+    });
+  }
+  // ============================================
+  // Export/Import
+  // ============================================
+  /**
+   * Export memories
+   */
+  async export(options) {
+    const params = new URLSearchParams();
+    if (options?.namespace) {
+      params.set("namespace", options.namespace);
+    }
+    const queryString = params.toString();
+    return this.request(
+      `/memories/export${queryString ? `?${queryString}` : ""}`
+    );
+  }
+  /**
+   * Import memories from export
+   */
+  async import(data) {
+    return this.request("/memories/import", {
+      method: "POST",
+      body: data
+    });
+  }
+  // ============================================
+  // Analytics
+  // ============================================
+  /**
+   * Get memory statistics
+   */
+  async stats() {
+    return this.request("/memories/stats");
+  }
+  // ============================================
+  // Helpers
+  // ============================================
+  /**
+   * Quick remember - shorthand for adding a fact
+   */
+  async remember(content, tags) {
+    return this.add({
+      content,
+      memory_type: "fact",
+      tags
+    });
+  }
+  /**
+   * Quick recall - shorthand for searching
+   */
+  async recall(query, limit = 5) {
+    const response = await this.search({ query, limit });
+    return response.results;
+  }
+  /**
+   * Forget - shorthand for deleting
+   */
+  async forget(ids) {
+    return this.delete(ids);
+  }
+  // ============================================
+  // Internal
+  // ============================================
+  async request(path, options) {
+    const url = `${this.baseUrl}${path}`;
+    const method = options?.method ?? "GET";
+    let lastError = null;
+    for (let attempt = 0; attempt < this.retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const response = await fetch(url, {
+          method,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json"
+          },
+          body: options?.body ? JSON.stringify(options.body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          const error = {
+            code: errorData.code ?? "REQUEST_FAILED",
+            message: errorData.error ?? errorData.message ?? `Request failed with status ${response.status}`,
+            status: response.status,
+            details: errorData
+          };
+          if (response.status >= 400 && response.status < 500) {
+            this.onError?.(error);
+            throw error;
+          }
+          lastError = error;
+          continue;
+        }
+        return response.json();
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          lastError = {
+            code: "TIMEOUT",
+            message: `Request timed out after ${this.timeout}ms`
+          };
+        } else if (error.code) {
+          throw error;
+        } else {
+          lastError = {
+            code: "NETWORK_ERROR",
+            message: error instanceof Error ? error.message : "Network error"
+          };
+        }
+        if (attempt < this.retries - 1) {
+          await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 1e3));
+        }
+      }
+    }
+    if (lastError) {
+      this.onError?.(lastError);
+      throw lastError;
+    }
+    throw { code: "UNKNOWN", message: "Unknown error" };
+  }
+};
+function createSpringClient(config) {
+  return new SpringClient(config);
+}
+export {
+  SpringClient,
+  createSpringClient
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@seizn/spring",
+  "version": "0.1.0",
+  "description": "Seizn Spring - Semantic Memory SDK for AI Applications",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "seizn",
+    "spring",
+    "ai",
+    "memory",
+    "semantic-search",
+    "vector-database",
+    "llm",
+    "embeddings"
+  ],
+  "author": "Seizn <support@seizn.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iruhana/seizn.git",
+    "directory": "packages/spring-sdk"
+  },
+  "homepage": "https://docs.seizn.com/spring",
+  "bugs": {
+    "url": "https://github.com/iruhana/seizn/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}