@agentimprint/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,329 @@
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl: string);
+    private buildUrl;
+    private request;
+    private throwError;
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, requiresAuth?: boolean): Promise<T>;
+    post<T>(path: string, body?: unknown, requiresAuth?: boolean): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+
+interface Organization {
+    uuid: string;
+    name: string;
+    slug: string;
+    tier: string;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface OrganizationWithKey extends Organization {
+    apiKey: string;
+}
+interface Agent {
+    uuid: string;
+    name: string;
+    model_family: string;
+    core_purpose: string;
+    creator_identifier: string;
+    fingerprint: string;
+    version: string;
+    capabilities: string[];
+    meta: Record<string, unknown>;
+    is_active: boolean;
+    organization_uuid: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateAgentParams {
+    name: string;
+    model_family: string;
+    core_purpose: string;
+    creator_identifier: string;
+    version?: string;
+    capabilities?: string[];
+    meta?: Record<string, unknown>;
+}
+interface DiscoverResult {
+    uuid: string;
+    name: string;
+    fingerprint: string;
+    model_family: string;
+    organization_uuid: string;
+    created_at: string;
+}
+interface GenerateKeyResult {
+    key: string;
+}
+interface SplitKeyParams {
+    shares: number;
+    threshold: number;
+}
+interface SplitKeyResult {
+    shares: string[];
+}
+interface RecoverKeyResult {
+    key: string;
+}
+interface Vault {
+    uuid: string;
+    name: string;
+    description: string | null;
+    agent_uuid: string;
+    organization_uuid: string;
+    encryption_algorithm: string;
+    compression_enabled: boolean;
+    entry_count: number;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateVaultParams {
+    name: string;
+    agent_uuid: string;
+    description?: string;
+    encryption_algorithm?: string;
+    compression_enabled?: boolean;
+}
+interface VaultStats {
+    vault_uuid: string;
+    entry_count: number;
+    total_size_bytes: number;
+    encrypted_count: number;
+    unencrypted_count: number;
+    namespaces: string[];
+    created_at: string;
+    last_updated_at: string | null;
+}
+interface VaultExport {
+    vault: Vault;
+    entries: Entry[];
+    exported_at: string;
+}
+interface ImportResult {
+    imported: number;
+    skipped: number;
+    errors: string[];
+}
+interface MerkleInfo {
+    vault_uuid: string;
+    root_hash: string;
+    entry_count: number;
+    computed_at: string;
+}
+interface VerifyResult {
+    valid: boolean;
+    vault_uuid: string;
+    root_hash: string;
+    mismatched_entries: string[];
+    verified_at: string;
+}
+interface Snapshot {
+    uuid: string;
+    vault_uuid: string;
+    root_hash: string;
+    entry_count: number;
+    metadata: Record<string, unknown>;
+    created_at: string;
+}
+type EntryType = 'lesson' | 'heuristic' | 'fact' | 'preference' | 'pattern' | 'relationship' | 'negative' | 'procedural';
+interface Entry {
+    uuid: string;
+    vault_uuid: string;
+    entry_type: EntryType;
+    content: Record<string, unknown>;
+    provenance: Record<string, unknown> | null;
+    confidence: number;
+    domain: string | null;
+    tags: string[];
+    is_encrypted: boolean;
+    pii_flags: string[] | null;
+    tombstoned_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateEntryParams {
+    entry_type: EntryType;
+    content: Record<string, unknown>;
+    provenance?: Record<string, unknown>;
+    confidence?: number;
+    domain?: string;
+    tags?: string[];
+    is_encrypted?: boolean;
+    pii_flags?: string[];
+}
+interface UpdateEntryParams {
+    content?: Record<string, unknown>;
+    provenance?: Record<string, unknown>;
+    confidence?: number;
+    domain?: string;
+    tags?: string[];
+    pii_flags?: string[];
+}
+interface ListEntriesParams {
+    type?: EntryType;
+    domain?: string;
+    tag?: string;
+    q?: string;
+    include_tombstoned?: boolean;
+    page?: number;
+    per_page?: number;
+}
+interface PaginatedEntries {
+    entries: Entry[];
+    pagination: {
+        total: number;
+        per_page: number;
+        current_page: number;
+        last_page: number;
+    };
+}
+interface BulkResult {
+    imported: string[];
+    failed: Array<{
+        index: number;
+        errors: Record<string, string[]>;
+    }>;
+    summary: {
+        total: number;
+        imported: number;
+        failed: number;
+    };
+}
+interface EncryptedPayload {
+    ciphertext: string;
+    iv: string;
+    tag: string;
+    algorithm: string;
+}
+interface FingerprintComponents {
+    model_family: string;
+    core_purpose: string;
+    creator_identifier: string;
+}
+interface ImprintClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+
+declare class AgentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateAgentParams): Promise<Agent>;
+    list(): Promise<Agent[]>;
+    get(uuid: string): Promise<Agent>;
+    discover(fingerprint: string): Promise<DiscoverResult>;
+    generateKey(uuid: string): Promise<GenerateKeyResult>;
+    splitKey(uuid: string, params: SplitKeyParams): Promise<SplitKeyResult>;
+    recoverKey(uuid: string, shares: string[]): Promise<RecoverKeyResult>;
+}
+
+declare class EntriesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(vaultUuid: string, params?: ListEntriesParams): Promise<PaginatedEntries>;
+    create(vaultUuid: string, entry: CreateEntryParams): Promise<Entry>;
+    createBulk(vaultUuid: string, entries: CreateEntryParams[]): Promise<BulkResult>;
+    get(vaultUuid: string, entryUuid: string): Promise<Entry>;
+    update(vaultUuid: string, entryUuid: string, data: UpdateEntryParams): Promise<Entry>;
+    delete(vaultUuid: string, entryUuid: string): Promise<void>;
+}
+
+declare class OrganizationsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(name: string): Promise<OrganizationWithKey>;
+    get(uuid: string): Promise<Organization>;
+}
+
+declare class VaultsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateVaultParams): Promise<Vault>;
+    list(): Promise<Vault[]>;
+    get(uuid: string): Promise<Vault>;
+    stats(uuid: string): Promise<VaultStats>;
+    export(uuid: string): Promise<VaultExport>;
+    import(uuid: string, data: VaultExport): Promise<ImportResult>;
+    merkle(uuid: string): Promise<MerkleInfo>;
+    verify(uuid: string): Promise<VerifyResult>;
+    snapshot(uuid: string): Promise<Snapshot>;
+    snapshots(uuid: string): Promise<Snapshot[]>;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.agentimprint.io";
+/**
+ * ImprintClient — main entry point for the Agent Imprint SDK.
+ *
+ * @example
+ * ```ts
+ * const client = new ImprintClient({ apiKey: 'your-api-key' });
+ * const agents = await client.agents.list();
+ * ```
+ */
+declare class ImprintClient {
+    readonly organizations: OrganizationsResource;
+    readonly agents: AgentsResource;
+    readonly vaults: VaultsResource;
+    readonly entries: EntriesResource;
+    private readonly http;
+    /**
+     * Public discovery — check if an agent fingerprint exists (no auth required).
+     * Uses the unauthenticated /api/v1/discover endpoint.
+     */
+    static probe(fingerprint: string, baseUrl?: string): Promise<{
+        exists: boolean;
+    }>;
+    constructor(config: ImprintClientConfig);
+}
+
+declare class ImprintApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown, code?: string);
+}
+declare class ImprintValidationError extends ImprintApiError {
+    readonly errors: Record<string, string[]>;
+    constructor(message: string, errors: Record<string, string[]>, body?: unknown);
+}
+declare class ImprintAuthError extends ImprintApiError {
+    constructor(message?: string, body?: unknown);
+}
+declare class ImprintNotFoundError extends ImprintApiError {
+    constructor(message?: string, body?: unknown);
+}
+
+/**
+ * Compute a deterministic agent fingerprint that matches the server-side algorithm.
+ *
+ * Algorithm: sha256(model_family + sha256(core_purpose) + creator_identifier)
+ */
+declare function computeFingerprint(params: FingerprintComponents): Promise<string>;
+
+/**
+ * Generate a cryptographically secure random 256-bit key (64 hex chars).
+ */
+declare function generateKey(): string;
+/**
+ * Derive a vault-specific key from a master key and vault UUID.
+ */
+declare function deriveVaultKey(masterKey: string, vaultUuid: string): Promise<string>;
+/**
+ * Derive an entry-specific key from a vault key and entry UUID.
+ */
+declare function deriveEntryKey(vaultKey: string, entryUuid: string): Promise<string>;
+/**
+ * Encrypt a JSON-serializable object with AES-256-GCM.
+ * Returns an EncryptedPayload with ciphertext, iv, and tag (all hex-encoded).
+ */
+declare function encrypt(keyHex: string, data: object): Promise<EncryptedPayload>;
+/**
+ * Decrypt an EncryptedPayload back to the original object.
+ */
+declare function decrypt(keyHex: string, payload: EncryptedPayload): Promise<object>;
+
+export { type Agent, type BulkResult, type CreateAgentParams, type CreateEntryParams, type CreateVaultParams, DEFAULT_BASE_URL, type DiscoverResult, type EncryptedPayload, type Entry, type FingerprintComponents, type GenerateKeyResult, type ImportResult, ImprintApiError, ImprintAuthError, ImprintClient, type ImprintClientConfig, ImprintNotFoundError, ImprintValidationError, type ListEntriesParams, type MerkleInfo, type Organization, type OrganizationWithKey, type PaginatedEntries, type RecoverKeyResult, type Snapshot, type SplitKeyParams, type SplitKeyResult, type UpdateEntryParams, type Vault, type VaultExport, type VaultStats, type VerifyResult, computeFingerprint, decrypt, deriveEntryKey, deriveVaultKey, encrypt, generateKey };

package/dist/index.d.ts

@@ -0,0 +1,329 @@
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl: string);
+    private buildUrl;
+    private request;
+    private throwError;
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, requiresAuth?: boolean): Promise<T>;
+    post<T>(path: string, body?: unknown, requiresAuth?: boolean): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+
+interface Organization {
+    uuid: string;
+    name: string;
+    slug: string;
+    tier: string;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface OrganizationWithKey extends Organization {
+    apiKey: string;
+}
+interface Agent {
+    uuid: string;
+    name: string;
+    model_family: string;
+    core_purpose: string;
+    creator_identifier: string;
+    fingerprint: string;
+    version: string;
+    capabilities: string[];
+    meta: Record<string, unknown>;
+    is_active: boolean;
+    organization_uuid: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateAgentParams {
+    name: string;
+    model_family: string;
+    core_purpose: string;
+    creator_identifier: string;
+    version?: string;
+    capabilities?: string[];
+    meta?: Record<string, unknown>;
+}
+interface DiscoverResult {
+    uuid: string;
+    name: string;
+    fingerprint: string;
+    model_family: string;
+    organization_uuid: string;
+    created_at: string;
+}
+interface GenerateKeyResult {
+    key: string;
+}
+interface SplitKeyParams {
+    shares: number;
+    threshold: number;
+}
+interface SplitKeyResult {
+    shares: string[];
+}
+interface RecoverKeyResult {
+    key: string;
+}
+interface Vault {
+    uuid: string;
+    name: string;
+    description: string | null;
+    agent_uuid: string;
+    organization_uuid: string;
+    encryption_algorithm: string;
+    compression_enabled: boolean;
+    entry_count: number;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateVaultParams {
+    name: string;
+    agent_uuid: string;
+    description?: string;
+    encryption_algorithm?: string;
+    compression_enabled?: boolean;
+}
+interface VaultStats {
+    vault_uuid: string;
+    entry_count: number;
+    total_size_bytes: number;
+    encrypted_count: number;
+    unencrypted_count: number;
+    namespaces: string[];
+    created_at: string;
+    last_updated_at: string | null;
+}
+interface VaultExport {
+    vault: Vault;
+    entries: Entry[];
+    exported_at: string;
+}
+interface ImportResult {
+    imported: number;
+    skipped: number;
+    errors: string[];
+}
+interface MerkleInfo {
+    vault_uuid: string;
+    root_hash: string;
+    entry_count: number;
+    computed_at: string;
+}
+interface VerifyResult {
+    valid: boolean;
+    vault_uuid: string;
+    root_hash: string;
+    mismatched_entries: string[];
+    verified_at: string;
+}
+interface Snapshot {
+    uuid: string;
+    vault_uuid: string;
+    root_hash: string;
+    entry_count: number;
+    metadata: Record<string, unknown>;
+    created_at: string;
+}
+type EntryType = 'lesson' | 'heuristic' | 'fact' | 'preference' | 'pattern' | 'relationship' | 'negative' | 'procedural';
+interface Entry {
+    uuid: string;
+    vault_uuid: string;
+    entry_type: EntryType;
+    content: Record<string, unknown>;
+    provenance: Record<string, unknown> | null;
+    confidence: number;
+    domain: string | null;
+    tags: string[];
+    is_encrypted: boolean;
+    pii_flags: string[] | null;
+    tombstoned_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateEntryParams {
+    entry_type: EntryType;
+    content: Record<string, unknown>;
+    provenance?: Record<string, unknown>;
+    confidence?: number;
+    domain?: string;
+    tags?: string[];
+    is_encrypted?: boolean;
+    pii_flags?: string[];
+}
+interface UpdateEntryParams {
+    content?: Record<string, unknown>;
+    provenance?: Record<string, unknown>;
+    confidence?: number;
+    domain?: string;
+    tags?: string[];
+    pii_flags?: string[];
+}
+interface ListEntriesParams {
+    type?: EntryType;
+    domain?: string;
+    tag?: string;
+    q?: string;
+    include_tombstoned?: boolean;
+    page?: number;
+    per_page?: number;
+}
+interface PaginatedEntries {
+    entries: Entry[];
+    pagination: {
+        total: number;
+        per_page: number;
+        current_page: number;
+        last_page: number;
+    };
+}
+interface BulkResult {
+    imported: string[];
+    failed: Array<{
+        index: number;
+        errors: Record<string, string[]>;
+    }>;
+    summary: {
+        total: number;
+        imported: number;
+        failed: number;
+    };
+}
+interface EncryptedPayload {
+    ciphertext: string;
+    iv: string;
+    tag: string;
+    algorithm: string;
+}
+interface FingerprintComponents {
+    model_family: string;
+    core_purpose: string;
+    creator_identifier: string;
+}
+interface ImprintClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+
+declare class AgentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateAgentParams): Promise<Agent>;
+    list(): Promise<Agent[]>;
+    get(uuid: string): Promise<Agent>;
+    discover(fingerprint: string): Promise<DiscoverResult>;
+    generateKey(uuid: string): Promise<GenerateKeyResult>;
+    splitKey(uuid: string, params: SplitKeyParams): Promise<SplitKeyResult>;
+    recoverKey(uuid: string, shares: string[]): Promise<RecoverKeyResult>;
+}
+
+declare class EntriesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(vaultUuid: string, params?: ListEntriesParams): Promise<PaginatedEntries>;
+    create(vaultUuid: string, entry: CreateEntryParams): Promise<Entry>;
+    createBulk(vaultUuid: string, entries: CreateEntryParams[]): Promise<BulkResult>;
+    get(vaultUuid: string, entryUuid: string): Promise<Entry>;
+    update(vaultUuid: string, entryUuid: string, data: UpdateEntryParams): Promise<Entry>;
+    delete(vaultUuid: string, entryUuid: string): Promise<void>;
+}
+
+declare class OrganizationsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(name: string): Promise<OrganizationWithKey>;
+    get(uuid: string): Promise<Organization>;
+}
+
+declare class VaultsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateVaultParams): Promise<Vault>;
+    list(): Promise<Vault[]>;
+    get(uuid: string): Promise<Vault>;
+    stats(uuid: string): Promise<VaultStats>;
+    export(uuid: string): Promise<VaultExport>;
+    import(uuid: string, data: VaultExport): Promise<ImportResult>;
+    merkle(uuid: string): Promise<MerkleInfo>;
+    verify(uuid: string): Promise<VerifyResult>;
+    snapshot(uuid: string): Promise<Snapshot>;
+    snapshots(uuid: string): Promise<Snapshot[]>;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.agentimprint.io";
+/**
+ * ImprintClient — main entry point for the Agent Imprint SDK.
+ *
+ * @example
+ * ```ts
+ * const client = new ImprintClient({ apiKey: 'your-api-key' });
+ * const agents = await client.agents.list();
+ * ```
+ */
+declare class ImprintClient {
+    readonly organizations: OrganizationsResource;
+    readonly agents: AgentsResource;
+    readonly vaults: VaultsResource;
+    readonly entries: EntriesResource;
+    private readonly http;
+    /**
+     * Public discovery — check if an agent fingerprint exists (no auth required).
+     * Uses the unauthenticated /api/v1/discover endpoint.
+     */
+    static probe(fingerprint: string, baseUrl?: string): Promise<{
+        exists: boolean;
+    }>;
+    constructor(config: ImprintClientConfig);
+}
+
+declare class ImprintApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown, code?: string);
+}
+declare class ImprintValidationError extends ImprintApiError {
+    readonly errors: Record<string, string[]>;
+    constructor(message: string, errors: Record<string, string[]>, body?: unknown);
+}
+declare class ImprintAuthError extends ImprintApiError {
+    constructor(message?: string, body?: unknown);
+}
+declare class ImprintNotFoundError extends ImprintApiError {
+    constructor(message?: string, body?: unknown);
+}
+
+/**
+ * Compute a deterministic agent fingerprint that matches the server-side algorithm.
+ *
+ * Algorithm: sha256(model_family + sha256(core_purpose) + creator_identifier)
+ */
+declare function computeFingerprint(params: FingerprintComponents): Promise<string>;
+
+/**
+ * Generate a cryptographically secure random 256-bit key (64 hex chars).
+ */
+declare function generateKey(): string;
+/**
+ * Derive a vault-specific key from a master key and vault UUID.
+ */
+declare function deriveVaultKey(masterKey: string, vaultUuid: string): Promise<string>;
+/**
+ * Derive an entry-specific key from a vault key and entry UUID.
+ */
+declare function deriveEntryKey(vaultKey: string, entryUuid: string): Promise<string>;
+/**
+ * Encrypt a JSON-serializable object with AES-256-GCM.
+ * Returns an EncryptedPayload with ciphertext, iv, and tag (all hex-encoded).
+ */
+declare function encrypt(keyHex: string, data: object): Promise<EncryptedPayload>;
+/**
+ * Decrypt an EncryptedPayload back to the original object.
+ */
+declare function decrypt(keyHex: string, payload: EncryptedPayload): Promise<object>;
+
+export { type Agent, type BulkResult, type CreateAgentParams, type CreateEntryParams, type CreateVaultParams, DEFAULT_BASE_URL, type DiscoverResult, type EncryptedPayload, type Entry, type FingerprintComponents, type GenerateKeyResult, type ImportResult, ImprintApiError, ImprintAuthError, ImprintClient, type ImprintClientConfig, ImprintNotFoundError, ImprintValidationError, type ListEntriesParams, type MerkleInfo, type Organization, type OrganizationWithKey, type PaginatedEntries, type RecoverKeyResult, type Snapshot, type SplitKeyParams, type SplitKeyResult, type UpdateEntryParams, type Vault, type VaultExport, type VaultStats, type VerifyResult, computeFingerprint, decrypt, deriveEntryKey, deriveVaultKey, encrypt, generateKey };