@keemakr/agent-sdk 0.9.0 → 0.10.0

package/dist/client.d.ts

@@ -13,6 +13,26 @@ export declare class MemoryConflictError extends Error {
     current: MemoryEntry | null;
     constructor(current: MemoryEntry | null);
 }
+/**
+ * A conditional record write (`ifVersion`) lost the race — another agent wrote
+ * the record first. `current` is the record as it now stands (null when it was
+ * deleted concurrently). Re-read, re-derive, retry.
+ */
+export declare class RecordConflictError extends Error {
+    status: 409;
+    current: RecordEntry | null;
+    constructor(current: RecordEntry | null);
+}
+/**
+ * The record didn't match the field spec the entry declared for the collection
+ * — core validates every write server-side against what the tenant consented
+ * to at install. `issues` lists the exact mismatches.
+ */
+export declare class RecordValidationError extends Error {
+    status: 422;
+    issues: string[];
+    constructor(issues: string[]);
+}
 export interface KeeContext {
     session?: {
         auth?: {
@@ -106,6 +126,51 @@ export interface KeeKb {
         k?: number;
     }): Promise<KBHit[]>;
 }
+/** One stored typed record. */
+export interface RecordEntry {
+    collection: string;
+    record_id: string;
+    data: Record<string, unknown>;
+    written_by_agent: string | null;
+    /** Monotonic write counter — pass as `ifVersion` for compare-and-swap writes. */
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Typed record collections — the structured counterpart to memory (leads,
+ * tickets, anything row-shaped). A collection must be declared in the entry's
+ * entry.json as a kind:'records' dependency (collection + field spec); the
+ * tenant consents at install, and the grant then carries the per-collection
+ * `records:<collection>:read` / `records:<collection>:write` scopes. Core
+ * validates every write against the declared spec — a mismatch throws
+ * RecordValidationError with the exact issues. TENANT-SHARED like memory.
+ */
+export interface KeeRecords {
+    /**
+     * Write a record. When the spec declares an upsertKey, the record id derives
+     * from that field's value — saving the same lead email twice updates one
+     * record (idempotent). Pass `id` to address a specific record (PUT), and
+     * `ifVersion` (from a prior get/list) for compare-and-swap: throws
+     * RecordConflictError when another agent wrote it in between.
+     */
+    upsert(collection: string, data: Record<string, unknown>, opts?: {
+        id?: string;
+        ifVersion?: number;
+    }): Promise<RecordEntry>;
+    /** Read one record, or null if absent. */
+    get(collection: string, id: string): Promise<RecordEntry | null>;
+    /** List a collection page by page (keyset cursor — pass back `nextCursor`). */
+    list(collection: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        records: RecordEntry[];
+        nextCursor: string | null;
+    }>;
+    /** Delete one record. Returns whether it existed. */
+    delete(collection: string, id: string): Promise<boolean>;
+}
 /** Platform registry tools (Shape B) — defined in core, run server-side. */
 export interface KeeTools {
     /** List the registry tools this grant is entitled to. */
@@ -125,6 +190,7 @@ export interface Kee {
         get(provider: string): KeeConnection;
     };
     memory: KeeMemory;
+    records: KeeRecords;
     kb: KeeKb;
     tools: KeeTools;
 }

package/dist/client.js

@@ -31,6 +31,34 @@ export class MemoryConflictError extends Error {
         this.current = current;
     }
 }
+/**
+ * A conditional record write (`ifVersion`) lost the race — another agent wrote
+ * the record first. `current` is the record as it now stands (null when it was
+ * deleted concurrently). Re-read, re-derive, retry.
+ */
+export class RecordConflictError extends Error {
+    status = 409;
+    current;
+    constructor(current) {
+        super('record version conflict — the record changed since it was read');
+        this.name = 'RecordConflictError';
+        this.current = current;
+    }
+}
+/**
+ * The record didn't match the field spec the entry declared for the collection
+ * — core validates every write server-side against what the tenant consented
+ * to at install. `issues` lists the exact mismatches.
+ */
+export class RecordValidationError extends Error {
+    status = 422;
+    issues;
+    constructor(issues) {
+        super(`record does not match the declared spec: ${issues.join('; ')}`);
+        this.name = 'RecordValidationError';
+        this.issues = issues;
+    }
+}
 function readGrant(ctx) {
     const attrs = ctx?.session?.auth?.current?.attributes ?? {};
     const token = typeof attrs.grant_token === 'string' ? attrs.grant_token : undefined;
@@ -193,6 +221,59 @@ export function useKee(ctx) {
             return json.hits ?? [];
         },
     };
+    // Shared 409/422 mapping for record writes (POST to the collection or PUT to
+    // a specific id) — typed errors the agent's model can act on.
+    const recordWrite = async (path, method, body) => {
+        try {
+            const json = (await capabilityFetch(grant, path, body, method));
+            return json.entry;
+        }
+        catch (e) {
+            const err = e;
+            const body409 = err.body;
+            if (err.status === 409 && body409?.error === 'version_conflict') {
+                throw new RecordConflictError(body409.entry ?? null);
+            }
+            if (err.status === 422 && body409?.issues) {
+                throw new RecordValidationError(body409.issues);
+            }
+            throw e;
+        }
+    };
+    const records = {
+        async upsert(collection, data, opts) {
+            const payload = { data, expected_version: opts?.ifVersion };
+            if (opts?.id) {
+                return recordWrite(`records/${enc(collection)}/${enc(opts.id)}`, 'PUT', payload);
+            }
+            return recordWrite(`records/${enc(collection)}`, 'POST', payload);
+        },
+        async get(collection, id) {
+            try {
+                const json = (await capabilityFetch(grant, `records/${enc(collection)}/${enc(id)}`, undefined, 'GET'));
+                return json.entry ?? null;
+            }
+            catch (e) {
+                if (e.status === 404)
+                    return null;
+                throw e;
+            }
+        },
+        async list(collection, opts) {
+            const qs = new URLSearchParams();
+            if (opts?.limit)
+                qs.set('limit', String(opts.limit));
+            if (opts?.cursor)
+                qs.set('cursor', opts.cursor);
+            const suffix = qs.size ? `?${qs}` : '';
+            const json = (await capabilityFetch(grant, `records/${enc(collection)}${suffix}`, undefined, 'GET'));
+            return { records: json.records ?? [], nextCursor: json.next_cursor ?? null };
+        },
+        async delete(collection, id) {
+            const json = (await capabilityFetch(grant, `records/${enc(collection)}/${enc(id)}`, undefined, 'DELETE'));
+            return !!json.deleted;
+        },
+    };
     const kb = {
         async search(query, opts) {
             const json = (await capabilityFetch(grant, 'kb/retrieve', {
@@ -214,5 +295,13 @@ export function useKee(ctx) {
             return json.result;
         },
     };
-    return { tenantId: grant.tenantId, scopes: grant.scopes, connections, memory, kb, tools };
+    return {
+        tenantId: grant.tenantId,
+        scopes: grant.scopes,
+        connections,
+        memory,
+        records,
+        kb,
+        tools,
+    };
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { grantAuth } from './grant-auth.js';
 export { verifyGrant, type VerifiedGrant } from './verify-grant.js';
-export { useKee, MemoryConflictError, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeKb, type KBHit, type KeeTools, type MemoryEntry, type MemorySearchHit, } from './client.js';
+export { useKee, MemoryConflictError, RecordConflictError, RecordValidationError, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeRecords, type KeeKb, type KBHit, type KeeTools, type MemoryEntry, type MemorySearchHit, type RecordEntry, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';
 export { refreshGrant, REFRESH_THRESHOLD_SECONDS } from './refresh.js';

package/dist/index.js

@@ -10,6 +10,6 @@
 //   const r = await kee.connections.hunter.call('email-finder', { domain, first_name, last_name });
 export { grantAuth } from './grant-auth.js';
 export { verifyGrant } from './verify-grant.js';
-export { useKee, MemoryConflictError, } from './client.js';
+export { useKee, MemoryConflictError, RecordConflictError, RecordValidationError, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';
 export { refreshGrant, REFRESH_THRESHOLD_SECONDS } from './refresh.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/agent-sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "The floor for keemakr marketplace agents: verify the capability grant and reach tenant connections, memory, and shared platform tools through keemakr-core — without holding raw secrets or resolving the tenant yourself.",
   "license": "MIT",
   "type": "module",