smritea-sdk 0.1.0

package/README.md

@@ -0,0 +1,209 @@
+# smritea SDK — TypeScript / Node.js
+
+TypeScript SDK for the [smritea](https://smritea.ai) AI memory system.
+
+**[Get a free API key →](https://smritea.ai)**
+
+---
+
+## Installation
+
+```bash
+npm install smritea-sdk
+```
+
+Requires Node.js 18+. Ships as ESM + CJS with bundled type declarations.
+
+---
+
+## Get your API key
+
+1. Sign up at **[smritea.ai](https://smritea.ai)** — free account, no credit card required
+2. Create an app in the dashboard and copy your API key (`sk-...`) and App ID (`app_...`)
+3. Export them as environment variables:
+
+```bash
+export SMRITEA_API_KEY="sk-..."
+export SMRITEA_APP_ID="app_..."
+```
+
+---
+
+## Quickstart
+
+```typescript
+import { SmriteaClient } from 'smritea-sdk';
+
+const client = new SmriteaClient({
+  apiKey: process.env.SMRITEA_API_KEY!,
+  appId: process.env.SMRITEA_APP_ID!,
+});
+
+// Store something about a user
+await client.add('Alice is a vegetarian and loves hiking', { userId: 'alice' });
+
+// Retrieve it later in a different session
+const results = await client.search("What are Alice's food preferences?", { userId: 'alice' });
+for (const r of results) {
+  console.log(r.score?.toFixed(2), r.content);
+}
+```
+
+---
+
+## Constructor
+
+```typescript
+import { SmriteaClient } from 'smritea-sdk';
+
+const client = new SmriteaClient({
+  apiKey: 'sk-...',                       // required
+  appId: 'app_...',                       // required
+  baseUrl: 'https://api.smritea.ai',      // optional, default shown
+});
+```
+
+---
+
+## Methods
+
+All methods are async and return Promises.
+
+### `add` — Store a memory
+
+```typescript
+const memory = await client.add('User prefers concise replies', {
+  userId: 'alice',
+  metadata: { source: 'chat' },
+  conversationId: 'conv_123',
+});
+console.log(memory.id); // mem_...
+```
+
+`userId` is a shorthand — sets `actorId` and forces `actorType="user"`. For agent or system memories use `actorId` + `actorType` directly.
+
+| Option | Default | Description |
+|---|---|---|
+| `userId` | `undefined` | Shorthand: actorId + actorType="user" |
+| `actorId` | `undefined` | Explicit actor ID |
+| `actorType` | `"user"` | `"user"` \| `"agent"` \| `"system"` |
+| `actorName` | `undefined` | Display name |
+| `metadata` | `undefined` | Arbitrary key-value object |
+| `conversationId` | `undefined` | Conversation context |
+
+---
+
+### `search` — Semantic search
+
+```typescript
+const results = await client.search('dietary restrictions', {
+  userId: 'alice',
+  limit: 5,
+  method: 'deep_search',  // "quick_search" | "deep_search" | "context_aware_search"
+  threshold: 0.7,          // min relevance score 0.0–1.0
+});
+results.forEach(r => console.log(r.score, r.content));
+```
+
+Results are ordered by relevance (descending). Each result exposes `score` (0.0–1.0) and all `Memory` fields directly.
+
+| Search method | When to use |
+|---|---|
+| `quick_search` | Low-latency, keyword + vector hybrid |
+| `deep_search` | Higher recall, traverses the memory graph |
+| `context_aware_search` | Reranks results using conversation context |
+
+| Option | Default | Description |
+|---|---|---|
+| `userId` | `undefined` | Filter to this user's memories |
+| `actorId` | `undefined` | Filter by actor ID |
+| `actorType` | `undefined` | Filter by actor type |
+| `limit` | app default | Max results to return |
+| `method` | app default | Search strategy |
+| `threshold` | `undefined` | Min relevance score 0.0–1.0 |
+| `graphDepth` | `undefined` | Graph traversal depth override |
+| `conversationId` | `undefined` | Conversation context |
+
+---
+
+### `get` — Retrieve a memory by ID
+
+```typescript
+const memory = await client.get('mem_abc123');
+console.log(memory.content, memory.createdAt);
+// Throws SmriteaNotFoundError if the ID does not exist
+```
+
+---
+
+### `delete` — Delete a memory by ID
+
+```typescript
+await client.delete('mem_abc123');
+// Throws SmriteaNotFoundError if the ID does not exist
+```
+
+---
+
+### `get_all` — List all memories
+
+> **Not yet implemented.** There is no `get_all` method in the TypeScript SDK.
+> Use `search()` with a broad query as a workaround:
+
+```typescript
+const results = await client.search('', { userId: 'alice', limit: 100 });
+```
+
+---
+
+## Error handling
+
+```typescript
+import {
+  SmriteaAuthError,
+  SmriteaNotFoundError,
+  SmriteaRateLimitError,
+  SmriteaQuotaError,
+  SmriteaValidationError,
+  SmriteaError,
+} from 'smritea-sdk';
+
+try {
+  await client.delete('mem_unknown');
+} catch (e) {
+  if (e instanceof SmriteaNotFoundError) console.log('Memory not found');
+  if (e instanceof SmriteaRateLimitError) console.log(`Retry after ${e.retryAfter}s`);
+  if (e instanceof SmriteaAuthError) console.log('Invalid API key');
+  if (e instanceof SmriteaQuotaError) console.log('Plan quota exceeded');
+}
+```
+
+| Exception | HTTP | When |
+|---|---|---|
+| `SmriteaAuthError` | 401 | Invalid or missing API key |
+| `SmriteaValidationError` | 400 | Invalid request parameters |
+| `SmriteaNotFoundError` | 404 | Memory ID does not exist |
+| `SmriteaQuotaError` | 402 | Organisation quota exceeded |
+| `SmriteaRateLimitError` | 429 | Rate limit hit — check `.retryAfter` |
+| `SmriteaError` | other | Unexpected server error |
+
+---
+
+## `Memory` type reference
+
+All fields use `camelCase`.
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Memory ID (`mem_...`) |
+| `appId` | `string` | App this memory belongs to |
+| `content` | `string` | Memory text |
+| `actorId` | `string` | Actor who owns this memory |
+| `actorType` | `string` | `"user"` \| `"agent"` \| `"system"` |
+| `actorName` | `string?` | Display name |
+| `metadata` | `object?` | Arbitrary key-value pairs |
+| `conversationId` | `string?` | Conversation context |
+| `activeFrom` | `string` | ISO 8601 — when memory becomes valid |
+| `activeTo` | `string?` | ISO 8601 — when memory expires |
+| `createdAt` | `string` | ISO 8601 creation timestamp |
+| `updatedAt` | `string` | ISO 8601 last update timestamp |

package/dist/index.d.mts

@@ -0,0 +1,291 @@
+/**
+ * smritea SDK API
+ * Public SDK API for smritea AI memory system — programmatic memory operations via API key
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * Contact: support@smritea.ai
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ *
+ * @export
+ * @interface CommondtoRelativeStandingConfig
+ */
+interface CommondtoRelativeStandingConfig {
+    /**
+     * DecayFactor modulates the temporal decay rate: effectiveRate = baseRate × decay_factor.
+     * 0 = no decay (pinned), 0.2 = light, 1.0 = standard, 3.0+ = aggressive.
+     * @type {number}
+     * @memberof CommondtoRelativeStandingConfig
+     */
+    decayFactor?: number;
+    /**
+     * DecayFunction selects the temporal decay algorithm.
+     * Defaults to "exponential". Options: exponential, gaussian, linear.
+     * @type {string}
+     * @memberof CommondtoRelativeStandingConfig
+     */
+    decayFunction?: CommondtoRelativeStandingConfigDecayFunctionEnum;
+    /**
+     * Importance is the memory importance score (0-1, default 1.0).
+     * Used as a ranking signal in RRF reranking — higher importance = better rank.
+     * @type {number}
+     * @memberof CommondtoRelativeStandingConfig
+     */
+    importance?: number;
+}
+/**
+ * @export
+ */
+declare const CommondtoRelativeStandingConfigDecayFunctionEnum: {
+    readonly Exponential: "exponential";
+    readonly Gaussian: "gaussian";
+    readonly Linear: "linear";
+};
+type CommondtoRelativeStandingConfigDecayFunctionEnum = typeof CommondtoRelativeStandingConfigDecayFunctionEnum[keyof typeof CommondtoRelativeStandingConfigDecayFunctionEnum];
+
+/**
+ * smritea SDK API
+ * Public SDK API for smritea AI memory system — programmatic memory operations via API key
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * Contact: support@smritea.ai
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+/**
+ *
+ * @export
+ * @interface MemoryMemoryResponse
+ */
+interface MemoryMemoryResponse {
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    activeFrom?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    activeTo?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    actorId?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    actorName?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    actorType?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    appId?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    content?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    conversationId?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    conversationMessageId?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    createdAt?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    id?: string;
+    /**
+     *
+     * @type {object}
+     * @memberof MemoryMemoryResponse
+     */
+    metadata?: object;
+    /**
+     *
+     * @type {CommondtoRelativeStandingConfig}
+     * @memberof MemoryMemoryResponse
+     */
+    relativeStanding?: CommondtoRelativeStandingConfig;
+    /**
+     *
+     * @type {string}
+     * @memberof MemoryMemoryResponse
+     */
+    updatedAt?: string;
+}
+
+/**
+ * smritea SDK API
+ * Public SDK API for smritea AI memory system — programmatic memory operations via API key
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * Contact: support@smritea.ai
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+/**
+ *
+ * @export
+ * @interface MemorySearchMemoryResponse
+ */
+interface MemorySearchMemoryResponse {
+    /**
+     *
+     * @type {MemoryMemoryResponse}
+     * @memberof MemorySearchMemoryResponse
+     */
+    memory?: MemoryMemoryResponse;
+    /**
+     *
+     * @type {number}
+     * @memberof MemorySearchMemoryResponse
+     */
+    score?: number;
+}
+
+/**
+ * Public-facing types for the smritea TypeScript SDK.
+ *
+ * Memory and SearchResult are re-exported directly from the auto-generated SDK
+ * so that the type contract matches the API exactly. Field names are camelCase
+ * as produced by the openapi-generator TypeScript mapper.
+ */
+
+interface AddMemoryOptions {
+    /** Shorthand: sets actor_id and actor_type="user". Takes precedence if actorId also set. */
+    userId?: string;
+    /** Explicit actor ID. Use when actor_type is not "user". */
+    actorId?: string;
+    actorType?: string;
+    actorName?: string;
+    metadata?: Record<string, unknown>;
+    conversationId?: string;
+}
+interface SearchOptions {
+    /** Shorthand: sets actor_id and actor_type="user" filter. */
+    userId?: string;
+    actorId?: string;
+    actorType?: string;
+    limit?: number;
+    method?: string;
+    threshold?: number;
+    graphDepth?: number;
+    conversationId?: string;
+}
+interface SmriteaClientConfig {
+    apiKey: string;
+    appId: string;
+    /** Override API base URL. Defaults to https://api.smritea.ai */
+    baseUrl?: string;
+    /**
+     * Automatic retries on HTTP 429. Uses Retry-After header when the server
+     * provides one, otherwise exponential backoff with jitter (capped at 30 s).
+     * Set to 0 to disable. Default: 2.
+     */
+    maxRetries?: number;
+}
+
+declare class SmriteaClient {
+    private readonly appId;
+    private readonly api;
+    private readonly maxRetries;
+    constructor(config: SmriteaClientConfig);
+    add(content: string, options?: AddMemoryOptions): Promise<MemoryMemoryResponse>;
+    search(query: string, options?: SearchOptions): Promise<MemorySearchMemoryResponse[]>;
+    get(memoryId: string): Promise<MemoryMemoryResponse>;
+    delete(memoryId: string): Promise<void>;
+    /**
+     * Execute fn, retrying on HTTP 429 up to maxRetries times.
+     *
+     * Sleep strategy per attempt:
+     * 1. Retry-After header value (seconds), capped at 30 s.
+     * 2. Exponential backoff (1 s, 2 s, 4 s, …) with ±25 % jitter, capped at 30 s.
+     *
+     * After all retries are exhausted the 429 is re-raised as SmriteaRateLimitError
+     * with retryAfter populated from the final response header if available.
+     */
+    private withRetry;
+    /** Calculate sleep duration in milliseconds for a retry attempt. */
+    private retryDelayMs;
+    /** Extract the Retry-After header value in seconds, or undefined. */
+    private parseRetryAfter;
+    private handleError;
+}
+
+/**
+ * Error classes for the smritea TypeScript SDK.
+ * Each maps to an HTTP status code returned by the API.
+ */
+declare class SmriteaError extends Error {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/** HTTP 401 -- invalid or missing API key. */
+declare class SmriteaAuthError extends SmriteaError {
+    constructor(message: string, statusCode?: number);
+}
+/** HTTP 404 -- memory not found. */
+declare class SmriteaNotFoundError extends SmriteaError {
+    constructor(message: string, statusCode?: number);
+}
+/** HTTP 400 -- request validation failed. */
+declare class SmriteaValidationError extends SmriteaError {
+    constructor(message: string, statusCode?: number);
+}
+/** HTTP 402 -- quota exceeded for this organization. */
+declare class SmriteaQuotaError extends SmriteaError {
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * HTTP 429 -- rate limit exceeded after all retries are exhausted.
+ *
+ * `retryAfter` is the value from the server's Retry-After header (seconds),
+ * if provided. This is informational — the SDK already waited this long
+ * during its automatic retry attempts.
+ */
+declare class SmriteaRateLimitError extends SmriteaError {
+    retryAfter?: number;
+    constructor(message: string, statusCode?: number, retryAfter?: number);
+}
+
+export { type AddMemoryOptions, type MemoryMemoryResponse as Memory, type SearchOptions, type MemorySearchMemoryResponse as SearchResult, SmriteaAuthError, SmriteaClient, type SmriteaClientConfig, SmriteaError, SmriteaNotFoundError, SmriteaQuotaError, SmriteaRateLimitError, SmriteaValidationError };