korely-memory 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,305 @@
+/**
+ * Response shapes from the Korely REST API. Field names match the JSON the API
+ * returns (the same shapes documented in the API reference), so what you see in
+ * the docs is what you get on the object. Interfaces are open: a server that
+ * returns extra fields never breaks an old client.
+ */
+/** A chat message, accepted by `add()` as an alternative to a plain string. */
+interface Message {
+    role?: string;
+    content?: string | null;
+}
+interface Fact {
+    id?: string;
+    subject?: string;
+    predicate?: string;
+    object?: string;
+    predicate_family?: string;
+    subject_type?: string;
+    predicate_raw?: string;
+    object_is_literal?: boolean;
+    confidence?: number;
+    user_id?: string;
+    agent_id?: string;
+    valid_from?: string;
+    invalid_at?: string;
+    invalidated_by?: string;
+    /** Write-shape only: ids this fact superseded (from add()/addFactTriple()). */
+    invalidated?: string[];
+    source_memory_id?: string;
+    created_at?: string;
+}
+interface Memory {
+    id?: string;
+    content?: string;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    metadata?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+    /** Facts extracted from this memory on the write path. */
+    facts?: Fact[];
+}
+interface SearchHit {
+    id?: string;
+    score?: number;
+    snippet?: string;
+    user_id?: string;
+    agent_id?: string;
+    metadata?: Record<string, unknown>;
+}
+interface MemoryPage {
+    memories: Memory[];
+    total: number;
+}
+interface DeleteReceipt {
+    id?: string;
+    status?: string;
+    facts_invalidated?: number;
+    audit_id?: string;
+}
+interface BulkReceipt {
+    user_id?: string;
+    memories_forgotten?: number;
+    facts_invalidated?: number;
+    audit_id?: string;
+}
+interface Context {
+    context: string;
+    tokens: number;
+    sources: string[];
+}
+interface BatchJob {
+    id?: string;
+    status?: string;
+    received?: number;
+    imported?: number;
+    failed?: number;
+    errors?: unknown[];
+}
+interface Profile {
+    user_id?: string;
+    as_of?: string | null;
+    /** The end user's own facts first, then the rest. */
+    facts: Fact[];
+    /** Facts grouped by predicate family. */
+    by_family: Record<string, Fact[]>;
+    total: number;
+    /** True when `total` exceeds the facts returned (the profile is capped at 200). */
+    truncated: boolean;
+}
+type HistoryEventType = "created" | "updated" | "fact_extracted" | "fact_invalidated" | "deleted";
+interface HistoryEvent {
+    event?: HistoryEventType;
+    at?: string;
+    /** "subject predicate object" — set on fact events. */
+    fact?: string;
+    fact_id?: string;
+}
+interface MemoryHistory {
+    id?: string;
+    events: HistoryEvent[];
+}
+interface UserScope {
+    user_id?: string;
+    memories: number;
+    facts: number;
+    last_active?: string;
+}
+interface UsersPage {
+    users: UserScope[];
+    total: number;
+}
+interface AddOptions {
+    agent_id?: string;
+    user_id?: string;
+    run_id?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SearchOptions {
+    user_id?: string;
+    agent_id?: string;
+    limit?: number;
+}
+interface ListOptions {
+    user_id?: string;
+    agent_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface UpdateOptions {
+    content: string;
+    /** Optimistic concurrency: rejects (StaleWriteError) if it doesn't match. */
+    expected_updated_at?: string;
+}
+interface UsersOptions {
+    agent_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface GetFactsOptions {
+    subject?: string;
+    /** Matches the subject OR object side. */
+    entity?: string;
+    predicate?: string;
+    predicate_family?: string;
+    include_invalidated?: boolean;
+    /** ISO date — point-in-time validity ("what was true on 2026-06-01"). */
+    as_of?: string;
+    user_id?: string;
+    agent_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface AddFactTripleOptions {
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    subject_type?: string;
+    object_is_literal?: boolean;
+    confidence?: number;
+    /** ISO date — for a historical fact. */
+    valid_from?: string;
+}
+interface GetProfileOptions {
+    user_id: string;
+    agent_id?: string;
+    /** ISO date — the profile as it stood on that date. */
+    as_of?: string;
+}
+interface GetContextOptions {
+    query: string;
+    user_id?: string;
+    agent_id?: string;
+    token_budget?: number;
+}
+
+declare const VERSION = "0.1.0";
+interface KorelyOptions {
+    /** Your `kor_live_...` key. Falls back to the KORELY_API_KEY env var. */
+    apiKey?: string;
+    /** EU only for now (data stored and processed in the EU). */
+    region?: "eu";
+    /** Override the base URL (mainly for testing). */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Inject a fetch implementation (mainly for testing / older runtimes). */
+    fetch?: typeof fetch;
+}
+declare class Korely {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    private readonly fetchImpl;
+    constructor(opts?: KorelyOptions);
+    private request;
+    private raise;
+    /**
+     * POST /v1/memories — store a memory; resolves to it with extracted facts.
+     * `content` is a string, or a list of chat messages (role/content), joined
+     * into one block before sending.
+     */
+    add(content: string | Message[], opts?: AddOptions): Promise<Memory>;
+    /** POST /v1/memories/search — hybrid retrieval, ranked by score. */
+    search(query: string, opts?: SearchOptions): Promise<SearchHit[]>;
+    /** GET /v1/memories — list a scope, newest first. */
+    getAll(opts?: ListOptions): Promise<MemoryPage>;
+    /** GET /v1/memories/:id — full content, metadata, extracted facts. */
+    get(memoryId: string): Promise<Memory>;
+    /**
+     * PATCH /v1/memories/:id — re-runs extraction. Pass `expected_updated_at`
+     * for optimistic concurrency (throws StaleWriteError instead of clobbering).
+     */
+    update(memoryId: string, opts: UpdateOptions): Promise<Memory>;
+    /** DELETE /v1/memories/:id — forget one memory (audited invalidation). */
+    delete(memoryId: string): Promise<DeleteReceipt>;
+    /**
+     * DELETE /v1/users/:user_id/memories — forget every memory + fact for one
+     * end user in a single call.
+     */
+    deleteAll(opts: {
+        user_id: string;
+    }): Promise<BulkReceipt>;
+    /**
+     * GET /v1/memories/:id/history — the lifecycle timeline of a memory:
+     * created / updated / deleted, plus every typed fact it produced.
+     */
+    history(memoryId: string): Promise<MemoryHistory>;
+    /**
+     * GET /v1/users — the end users you've stored data for (distinct user_id
+     * namespaces), each with active memory + fact counts and last-active time.
+     */
+    users(opts?: UsersOptions): Promise<UsersPage>;
+    /**
+     * GET /v1/facts — typed (subject, predicate, object) triples with bi-temporal
+     * validity. Pass `as_of` (ISO date) for a point-in-time query.
+     */
+    getFacts(opts?: GetFactsOptions): Promise<Fact[]>;
+    /**
+     * POST /v1/facts — write a typed (subject, predicate, object) triple directly,
+     * skipping extraction. The server runs the contradiction check; the fact is
+     * bi-temporal (pass `valid_from` for a historical fact). Resolves to the
+     * written Fact, with `invalidated` listing any fact ids it superseded.
+     */
+    addFactTriple(subject: string, predicate: string, object: string, opts?: AddFactTripleOptions): Promise<Fact>;
+    /**
+     * GET /v1/profile — the assembled profile of one end user: the active typed
+     * facts known about them, the end user's own facts first, grouped by family.
+     * Pass `as_of` (ISO date) for the point-in-time profile.
+     */
+    getProfile(opts: GetProfileOptions): Promise<Profile>;
+    /**
+     * GET /v1/context — one call that assembles a prompt-ready context block
+     * (profile + relevant facts + memories) within a token budget.
+     */
+    getContext(opts: GetContextOptions): Promise<Context>;
+    /** POST /v1/batch — bulk import (up to 500 memory objects), async. */
+    batch(memories: Array<Record<string, unknown>>): Promise<BatchJob>;
+    /** GET /v1/batch/:id — poll an import job. */
+    batchStatus(jobId: string): Promise<BatchJob>;
+}
+
+/**
+ * Typed errors mapping 1:1 onto the REST error codes. Every error subclasses
+ * KorelyError, so a caller can catch everything with one `catch`.
+ */
+interface KorelyErrorOptions {
+    status?: number;
+    code?: string;
+}
+declare class KorelyError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 401 — missing, malformed, or revoked API key. */
+declare class AuthenticationError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 403 — the key lacks the scope required for this call. */
+declare class NamespaceForbiddenError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 404 — memory or fact id does not exist, or was forgotten. */
+declare class NotFoundError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 409 — update() with an expected_updated_at older than the record. */
+declare class StaleWriteError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 429 — past the soft cap. `retryAfter` is in seconds when the server sent it. */
+declare class QuotaExceededError extends KorelyError {
+    readonly retryAfter?: number;
+    constructor(message?: string, opts?: KorelyErrorOptions & {
+        retryAfter?: number;
+    });
+}
+/** Any other non-2xx response (validation 422, server 5xx, …). */
+declare class APIError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+
+export { APIError, type AddFactTripleOptions, type AddOptions, AuthenticationError, type BatchJob, type BulkReceipt, type Context, type DeleteReceipt, type Fact, type GetContextOptions, type GetFactsOptions, type GetProfileOptions, type HistoryEvent, type HistoryEventType, Korely, KorelyError, type KorelyOptions, type ListOptions, type Memory, type MemoryHistory, type MemoryPage, type Message, NamespaceForbiddenError, NotFoundError, type Profile, QuotaExceededError, type SearchHit, type SearchOptions, StaleWriteError, type UpdateOptions, type UserScope, type UsersOptions, type UsersPage, VERSION };

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Response shapes from the Korely REST API. Field names match the JSON the API
+ * returns (the same shapes documented in the API reference), so what you see in
+ * the docs is what you get on the object. Interfaces are open: a server that
+ * returns extra fields never breaks an old client.
+ */
+/** A chat message, accepted by `add()` as an alternative to a plain string. */
+interface Message {
+    role?: string;
+    content?: string | null;
+}
+interface Fact {
+    id?: string;
+    subject?: string;
+    predicate?: string;
+    object?: string;
+    predicate_family?: string;
+    subject_type?: string;
+    predicate_raw?: string;
+    object_is_literal?: boolean;
+    confidence?: number;
+    user_id?: string;
+    agent_id?: string;
+    valid_from?: string;
+    invalid_at?: string;
+    invalidated_by?: string;
+    /** Write-shape only: ids this fact superseded (from add()/addFactTriple()). */
+    invalidated?: string[];
+    source_memory_id?: string;
+    created_at?: string;
+}
+interface Memory {
+    id?: string;
+    content?: string;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    metadata?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+    /** Facts extracted from this memory on the write path. */
+    facts?: Fact[];
+}
+interface SearchHit {
+    id?: string;
+    score?: number;
+    snippet?: string;
+    user_id?: string;
+    agent_id?: string;
+    metadata?: Record<string, unknown>;
+}
+interface MemoryPage {
+    memories: Memory[];
+    total: number;
+}
+interface DeleteReceipt {
+    id?: string;
+    status?: string;
+    facts_invalidated?: number;
+    audit_id?: string;
+}
+interface BulkReceipt {
+    user_id?: string;
+    memories_forgotten?: number;
+    facts_invalidated?: number;
+    audit_id?: string;
+}
+interface Context {
+    context: string;
+    tokens: number;
+    sources: string[];
+}
+interface BatchJob {
+    id?: string;
+    status?: string;
+    received?: number;
+    imported?: number;
+    failed?: number;
+    errors?: unknown[];
+}
+interface Profile {
+    user_id?: string;
+    as_of?: string | null;
+    /** The end user's own facts first, then the rest. */
+    facts: Fact[];
+    /** Facts grouped by predicate family. */
+    by_family: Record<string, Fact[]>;
+    total: number;
+    /** True when `total` exceeds the facts returned (the profile is capped at 200). */
+    truncated: boolean;
+}
+type HistoryEventType = "created" | "updated" | "fact_extracted" | "fact_invalidated" | "deleted";
+interface HistoryEvent {
+    event?: HistoryEventType;
+    at?: string;
+    /** "subject predicate object" — set on fact events. */
+    fact?: string;
+    fact_id?: string;
+}
+interface MemoryHistory {
+    id?: string;
+    events: HistoryEvent[];
+}
+interface UserScope {
+    user_id?: string;
+    memories: number;
+    facts: number;
+    last_active?: string;
+}
+interface UsersPage {
+    users: UserScope[];
+    total: number;
+}
+interface AddOptions {
+    agent_id?: string;
+    user_id?: string;
+    run_id?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SearchOptions {
+    user_id?: string;
+    agent_id?: string;
+    limit?: number;
+}
+interface ListOptions {
+    user_id?: string;
+    agent_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface UpdateOptions {
+    content: string;
+    /** Optimistic concurrency: rejects (StaleWriteError) if it doesn't match. */
+    expected_updated_at?: string;
+}
+interface UsersOptions {
+    agent_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface GetFactsOptions {
+    subject?: string;
+    /** Matches the subject OR object side. */
+    entity?: string;
+    predicate?: string;
+    predicate_family?: string;
+    include_invalidated?: boolean;
+    /** ISO date — point-in-time validity ("what was true on 2026-06-01"). */
+    as_of?: string;
+    user_id?: string;
+    agent_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface AddFactTripleOptions {
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    subject_type?: string;
+    object_is_literal?: boolean;
+    confidence?: number;
+    /** ISO date — for a historical fact. */
+    valid_from?: string;
+}
+interface GetProfileOptions {
+    user_id: string;
+    agent_id?: string;
+    /** ISO date — the profile as it stood on that date. */
+    as_of?: string;
+}
+interface GetContextOptions {
+    query: string;
+    user_id?: string;
+    agent_id?: string;
+    token_budget?: number;
+}
+
+declare const VERSION = "0.1.0";
+interface KorelyOptions {
+    /** Your `kor_live_...` key. Falls back to the KORELY_API_KEY env var. */
+    apiKey?: string;
+    /** EU only for now (data stored and processed in the EU). */
+    region?: "eu";
+    /** Override the base URL (mainly for testing). */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Inject a fetch implementation (mainly for testing / older runtimes). */
+    fetch?: typeof fetch;
+}
+declare class Korely {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    private readonly fetchImpl;
+    constructor(opts?: KorelyOptions);
+    private request;
+    private raise;
+    /**
+     * POST /v1/memories — store a memory; resolves to it with extracted facts.
+     * `content` is a string, or a list of chat messages (role/content), joined
+     * into one block before sending.
+     */
+    add(content: string | Message[], opts?: AddOptions): Promise<Memory>;
+    /** POST /v1/memories/search — hybrid retrieval, ranked by score. */
+    search(query: string, opts?: SearchOptions): Promise<SearchHit[]>;
+    /** GET /v1/memories — list a scope, newest first. */
+    getAll(opts?: ListOptions): Promise<MemoryPage>;
+    /** GET /v1/memories/:id — full content, metadata, extracted facts. */
+    get(memoryId: string): Promise<Memory>;
+    /**
+     * PATCH /v1/memories/:id — re-runs extraction. Pass `expected_updated_at`
+     * for optimistic concurrency (throws StaleWriteError instead of clobbering).
+     */
+    update(memoryId: string, opts: UpdateOptions): Promise<Memory>;
+    /** DELETE /v1/memories/:id — forget one memory (audited invalidation). */
+    delete(memoryId: string): Promise<DeleteReceipt>;
+    /**
+     * DELETE /v1/users/:user_id/memories — forget every memory + fact for one
+     * end user in a single call.
+     */
+    deleteAll(opts: {
+        user_id: string;
+    }): Promise<BulkReceipt>;
+    /**
+     * GET /v1/memories/:id/history — the lifecycle timeline of a memory:
+     * created / updated / deleted, plus every typed fact it produced.
+     */
+    history(memoryId: string): Promise<MemoryHistory>;
+    /**
+     * GET /v1/users — the end users you've stored data for (distinct user_id
+     * namespaces), each with active memory + fact counts and last-active time.
+     */
+    users(opts?: UsersOptions): Promise<UsersPage>;
+    /**
+     * GET /v1/facts — typed (subject, predicate, object) triples with bi-temporal
+     * validity. Pass `as_of` (ISO date) for a point-in-time query.
+     */
+    getFacts(opts?: GetFactsOptions): Promise<Fact[]>;
+    /**
+     * POST /v1/facts — write a typed (subject, predicate, object) triple directly,
+     * skipping extraction. The server runs the contradiction check; the fact is
+     * bi-temporal (pass `valid_from` for a historical fact). Resolves to the
+     * written Fact, with `invalidated` listing any fact ids it superseded.
+     */
+    addFactTriple(subject: string, predicate: string, object: string, opts?: AddFactTripleOptions): Promise<Fact>;
+    /**
+     * GET /v1/profile — the assembled profile of one end user: the active typed
+     * facts known about them, the end user's own facts first, grouped by family.
+     * Pass `as_of` (ISO date) for the point-in-time profile.
+     */
+    getProfile(opts: GetProfileOptions): Promise<Profile>;
+    /**
+     * GET /v1/context — one call that assembles a prompt-ready context block
+     * (profile + relevant facts + memories) within a token budget.
+     */
+    getContext(opts: GetContextOptions): Promise<Context>;
+    /** POST /v1/batch — bulk import (up to 500 memory objects), async. */
+    batch(memories: Array<Record<string, unknown>>): Promise<BatchJob>;
+    /** GET /v1/batch/:id — poll an import job. */
+    batchStatus(jobId: string): Promise<BatchJob>;
+}
+
+/**
+ * Typed errors mapping 1:1 onto the REST error codes. Every error subclasses
+ * KorelyError, so a caller can catch everything with one `catch`.
+ */
+interface KorelyErrorOptions {
+    status?: number;
+    code?: string;
+}
+declare class KorelyError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 401 — missing, malformed, or revoked API key. */
+declare class AuthenticationError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 403 — the key lacks the scope required for this call. */
+declare class NamespaceForbiddenError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 404 — memory or fact id does not exist, or was forgotten. */
+declare class NotFoundError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 409 — update() with an expected_updated_at older than the record. */
+declare class StaleWriteError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+/** 429 — past the soft cap. `retryAfter` is in seconds when the server sent it. */
+declare class QuotaExceededError extends KorelyError {
+    readonly retryAfter?: number;
+    constructor(message?: string, opts?: KorelyErrorOptions & {
+        retryAfter?: number;
+    });
+}
+/** Any other non-2xx response (validation 422, server 5xx, …). */
+declare class APIError extends KorelyError {
+    constructor(message?: string, opts?: KorelyErrorOptions);
+}
+
+export { APIError, type AddFactTripleOptions, type AddOptions, AuthenticationError, type BatchJob, type BulkReceipt, type Context, type DeleteReceipt, type Fact, type GetContextOptions, type GetFactsOptions, type GetProfileOptions, type HistoryEvent, type HistoryEventType, Korely, KorelyError, type KorelyOptions, type ListOptions, type Memory, type MemoryHistory, type MemoryPage, type Message, NamespaceForbiddenError, NotFoundError, type Profile, QuotaExceededError, type SearchHit, type SearchOptions, StaleWriteError, type UpdateOptions, type UserScope, type UsersOptions, type UsersPage, VERSION };