kontext-sdk 0.2.0 → 0.2.1

package/dist/index.d.mts

@@ -76,6 +76,8 @@ type Chain = 'ethereum' | 'base' | 'polygon' | 'arbitrum' | 'optimism' | 'arc' |
 type Token = 'USDC' | 'USDT' | 'DAI' | 'EURC';
 /** SDK operating mode */
 type KontextMode = 'local' | 'cloud';
+/** Log level for the SDK logger */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 /** Environment configuration */
 type Environment = 'development' | 'staging' | 'production';
 /** Anomaly severity levels */
@@ -106,8 +108,38 @@ interface KontextConfig {
     flushIntervalMs?: number;
     /** Local file output directory for OSS mode */
     localOutputDir?: string;
+    /** Minimum log level for SDK output (default: 'warn', or 'debug' if debug=true) */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
     /** Pluggable storage adapter for persistence (default: in-memory) */
     storage?: StorageAdapter;
+    /**
+     * Optional metadata schema validator. When provided, all metadata passed to
+     * `log()`, `logTransaction()`, and `createTask()` will be validated against
+     * this schema before being recorded.
+     *
+     * Accepts any object with a `parse(data: unknown)` method (e.g., a Zod schema).
+     * Throws on validation failure, passes through on success.
+     *
+     * @example
+     * ```typescript
+     * import { z } from 'zod';
+     *
+     * const kontext = Kontext.init({
+     *   projectId: 'my-app',
+     *   environment: 'production',
+     *   metadataSchema: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])),
+     * });
+     * ```
+     */
+    metadataSchema?: MetadataValidator;
+}
+/**
+ * Interface for metadata validation. Compatible with Zod schemas and any
+ * validator that implements a `parse` method.
+ */
+interface MetadataValidator {
+    /** Validate and return the metadata. Should throw on invalid data. */
+    parse(data: unknown): Record<string, unknown>;
 }
 /** Base action log entry */
 interface ActionLog {
@@ -583,8 +615,8 @@ interface ComplianceCertificate {
     }>;
     /** Reasoning entries (if includeReasoning is true) */
     reasoning: ReasoningEntry[];
-    /** SHA-256 hash of the certificate content for verification */
-    signature: string;
+    /** SHA-256 hash of the certificate content for integrity verification */
+    contentHash: string;
 }
 /** Error codes for Kontext SDK */
 declare enum KontextErrorCode {
@@ -846,6 +878,11 @@ declare class Kontext {
     getConfig(): Omit<KontextConfig, 'apiKey'> & {
         apiKey?: string;
     };
+    /**
+     * Validate metadata against the configured schema, if any.
+     * No-op when metadataSchema is not configured.
+     */
+    private validateMetadata;
     /**
      * Log a generic agent action.
      *
@@ -1164,6 +1201,28 @@ declare class UsdcCompliance {
      * Get the chains supported for USDC compliance monitoring.
      */
     static getSupportedChains(): Chain[];
+    /**
+     * Add new sanctioned addresses at runtime.
+     * Normalizes all addresses to lowercase for consistent matching.
+     * Skips addresses that are already in the list.
+     *
+     * @param addresses - Array of Ethereum addresses to add
+     * @returns The count of newly added addresses (excluding duplicates)
+     */
+    static addSanctionedAddresses(addresses: string[]): number;
+    /**
+     * Replace the entire sanctioned addresses list at runtime.
+     * Clears existing entries and rebuilds from the provided array.
+     *
+     * @param addresses - The new complete list of sanctioned addresses
+     */
+    static replaceSanctionedAddresses(addresses: string[]): void;
+    /**
+     * Get the current number of addresses in the sanctions list.
+     *
+     * @returns The size of the current sanctions list
+     */
+    static getSanctionsListSize(): number;
     private static checkTokenType;
     private static checkChainSupport;
     private static checkAddressFormat;
@@ -2284,10 +2343,12 @@ declare class WebhookManager {
     setActive(webhookId: string, active: boolean): WebhookConfig | undefined;
     /**
      * Get all registered webhooks.
+     * Secrets are redacted to prevent accidental exposure in logs or API responses.
      */
     getWebhooks(): WebhookConfig[];
     /**
      * Get a specific webhook by ID.
+     * The secret is redacted to prevent accidental exposure in logs or API responses.
      */
     getWebhook(webhookId: string): WebhookConfig | undefined;
     /**
@@ -2327,6 +2388,27 @@ declare class WebhookManager {
     private deliverToWebhook;
     private computeSignature;
     private sleep;
+    /**
+     * Verify a webhook signature using constant-time comparison to prevent
+     * timing attacks. Use this in your webhook handler to validate incoming
+     * payloads from Kontext.
+     *
+     * @param payload - The raw JSON payload body (string)
+     * @param signature - The signature from the X-Kontext-Signature header
+     * @param secret - The webhook secret used during registration
+     * @returns Whether the signature is valid
+     *
+     * @example
+     * ```typescript
+     * const isValid = WebhookManager.verifySignature(
+     *   req.body, // raw JSON string
+     *   req.headers['x-kontext-signature'],
+     *   'my-webhook-secret',
+     * );
+     * if (!isValid) return res.status(401).send('Invalid signature');
+     * ```
+     */
+    static verifySignature(payload: string, signature: string, secret: string): boolean;
 }
 
 /** AI operation types recognized by the Vercel AI SDK middleware. */
@@ -2481,38 +2563,23 @@ interface KontextAIContext {
  * ```
  */
 declare function kontextMiddleware(kontext: Kontext, options?: KontextAIOptions): {
-    /**
-     * Logs the AI request parameters before the model is invoked.
-     * Captures the operation type, model ID, tool count, and generation settings.
-     */
-    transformParams: ({ params, type }: {
+    transformParams: (ctx: {
         params: Record<string, unknown>;
         type: string;
     }) => Promise<Record<string, unknown>>;
-    /**
-     * Wraps synchronous generation (`generateText`, `generateObject`).
-     * After the model returns, logs every tool call individually and the
-     * overall response. For financial tools, automatically creates
-     * compliance-tracked transaction records.
-     */
-    wrapGenerate: ({ doGenerate, params, }: {
+    wrapGenerate: (ctx: {
         doGenerate: () => Promise<Record<string, unknown>>;
         params: Record<string, unknown>;
     }) => Promise<Record<string, unknown>>;
-    /**
-     * Wraps streaming generation (`streamText`).
-     * Pipes the response stream through a transform that monitors for
-     * tool call chunks. On stream completion, logs the overall duration
-     * and any tool calls that occurred during the stream.
-     */
-    wrapStream: ({ doStream, params, }: {
+    wrapStream: (ctx: {
         doStream: () => Promise<{
             stream: ReadableStream;
             [key: string]: unknown;
         }>;
         params: Record<string, unknown>;
     }) => Promise<{
-        stream: ReadableStream<any>;
+        [key: string]: unknown;
+        stream: ReadableStream;
     }>;
 };
 /**
@@ -2625,4 +2692,4 @@ declare function withKontext(handler: (req: Request, ctx: KontextAIContext) => P
  */
 declare function extractAmount(args: unknown): number | null;
 
-export { type AIOperationType, type ActionLog, type AddressScreenResult, type AnomalyCallback, type AnomalyDetectionConfig, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type BlockedToolCall, type CCTPAttestationInput, type CCTPHook, type CCTPHookResult, type CCTPMessageStatus, CCTPTransferManager, type CCTPValidationCheck, type CCTPValidationResult, type CCTPVersion, type CTRReport, type Chain, type CircleApiAdapter, type CircleComplianceAdapter, CircleComplianceEngine, type CircleWallet, CircleWalletManager, type CircleWalletOptions, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceCheckSummary, type ComplianceReport, type CompliantTransferInput, type CompliantTransferResult, type ComprehensiveRiskFactor, type ComprehensiveRiskResult, type ConfirmCCTPTransferInput, type ConfirmTaskInput, type CreateKontextAIInput, type CreateKontextAIResult, type CreateTaskInput, type CreateWalletOptions, type CrossChainAuditEntry, type CrossChainTransfer, type DateRange, DigestChain, type DigestLink, type DigestVerification, type DualScreenResult, type Environment, type ExportFormat, type ExportOptions, type ExportResult, type FastTransferValidation, FileStorage, type GasEligibility, type GasEstimate, type GasEstimateInput, type GasSponsorshipLog, type GasStationAdapter, GasStationManager, type GenerateComplianceCertificateInput, type InitiateCCTPTransferInput, type InitiateFastTransferInput, Kontext, type KontextAIContext, type KontextAIOptions, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LogActionInput, type LogReasoningInput, type LogTransactionInput, MemoryStorage, type PrecisionTimestamp, type ReasoningEntry, type RegisterWebhookInput, type ReportOptions, type ReportSubject, type ReportType, type RiskAssessmentInput, type RiskFactor, type SARReport, type SanctionsCheckResult, type ScreenTransactionInput, type StorageAdapter, type Task, type TaskEvidence, type TaskStatus, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, UsdcCompliance, type UsdcComplianceCheck, type WalletBalance, type WalletSet, type WebhookConfig, type WebhookDeliveryResult, type WebhookEventType, WebhookManager, type WebhookPayload, type WebhookRetryConfig, type WithKontextOptions, createKontextAI, extractAmount, kontextMiddleware, kontextWrapModel, verifyExportedChain, withKontext };
+export { type AIOperationType, type ActionLog, type AddressScreenResult, type AnomalyCallback, type AnomalyDetectionConfig, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type BlockedToolCall, type CCTPAttestationInput, type CCTPHook, type CCTPHookResult, type CCTPMessageStatus, CCTPTransferManager, type CCTPValidationCheck, type CCTPValidationResult, type CCTPVersion, type CTRReport, type Chain, type CircleApiAdapter, type CircleComplianceAdapter, CircleComplianceEngine, type CircleWallet, CircleWalletManager, type CircleWalletOptions, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceCheckSummary, type ComplianceReport, type CompliantTransferInput, type CompliantTransferResult, type ComprehensiveRiskFactor, type ComprehensiveRiskResult, type ConfirmCCTPTransferInput, type ConfirmTaskInput, type CreateKontextAIInput, type CreateKontextAIResult, type CreateTaskInput, type CreateWalletOptions, type CrossChainAuditEntry, type CrossChainTransfer, type DateRange, DigestChain, type DigestLink, type DigestVerification, type DualScreenResult, type Environment, type ExportFormat, type ExportOptions, type ExportResult, type FastTransferValidation, FileStorage, type GasEligibility, type GasEstimate, type GasEstimateInput, type GasSponsorshipLog, type GasStationAdapter, GasStationManager, type GenerateComplianceCertificateInput, type InitiateCCTPTransferInput, type InitiateFastTransferInput, Kontext, type KontextAIContext, type KontextAIOptions, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LogActionInput, type LogLevel, type LogReasoningInput, type LogTransactionInput, MemoryStorage, type MetadataValidator, type PrecisionTimestamp, type ReasoningEntry, type RegisterWebhookInput, type ReportOptions, type ReportSubject, type ReportType, type RiskAssessmentInput, type RiskFactor, type SARReport, type SanctionsCheckResult, type ScreenTransactionInput, type StorageAdapter, type Task, type TaskEvidence, type TaskStatus, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, UsdcCompliance, type UsdcComplianceCheck, type WalletBalance, type WalletSet, type WebhookConfig, type WebhookDeliveryResult, type WebhookEventType, WebhookManager, type WebhookPayload, type WebhookRetryConfig, type WithKontextOptions, createKontextAI, extractAmount, kontextMiddleware, kontextWrapModel, verifyExportedChain, withKontext };

package/dist/index.d.ts

@@ -76,6 +76,8 @@ type Chain = 'ethereum' | 'base' | 'polygon' | 'arbitrum' | 'optimism' | 'arc' |
 type Token = 'USDC' | 'USDT' | 'DAI' | 'EURC';
 /** SDK operating mode */
 type KontextMode = 'local' | 'cloud';
+/** Log level for the SDK logger */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 /** Environment configuration */
 type Environment = 'development' | 'staging' | 'production';
 /** Anomaly severity levels */
@@ -106,8 +108,38 @@ interface KontextConfig {
     flushIntervalMs?: number;
     /** Local file output directory for OSS mode */
     localOutputDir?: string;
+    /** Minimum log level for SDK output (default: 'warn', or 'debug' if debug=true) */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
     /** Pluggable storage adapter for persistence (default: in-memory) */
     storage?: StorageAdapter;
+    /**
+     * Optional metadata schema validator. When provided, all metadata passed to
+     * `log()`, `logTransaction()`, and `createTask()` will be validated against
+     * this schema before being recorded.
+     *
+     * Accepts any object with a `parse(data: unknown)` method (e.g., a Zod schema).
+     * Throws on validation failure, passes through on success.
+     *
+     * @example
+     * ```typescript
+     * import { z } from 'zod';
+     *
+     * const kontext = Kontext.init({
+     *   projectId: 'my-app',
+     *   environment: 'production',
+     *   metadataSchema: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])),
+     * });
+     * ```
+     */
+    metadataSchema?: MetadataValidator;
+}
+/**
+ * Interface for metadata validation. Compatible with Zod schemas and any
+ * validator that implements a `parse` method.
+ */
+interface MetadataValidator {
+    /** Validate and return the metadata. Should throw on invalid data. */
+    parse(data: unknown): Record<string, unknown>;
 }
 /** Base action log entry */
 interface ActionLog {
@@ -583,8 +615,8 @@ interface ComplianceCertificate {
     }>;
     /** Reasoning entries (if includeReasoning is true) */
     reasoning: ReasoningEntry[];
-    /** SHA-256 hash of the certificate content for verification */
-    signature: string;
+    /** SHA-256 hash of the certificate content for integrity verification */
+    contentHash: string;
 }
 /** Error codes for Kontext SDK */
 declare enum KontextErrorCode {
@@ -846,6 +878,11 @@ declare class Kontext {
     getConfig(): Omit<KontextConfig, 'apiKey'> & {
         apiKey?: string;
     };
+    /**
+     * Validate metadata against the configured schema, if any.
+     * No-op when metadataSchema is not configured.
+     */
+    private validateMetadata;
     /**
      * Log a generic agent action.
      *
@@ -1164,6 +1201,28 @@ declare class UsdcCompliance {
      * Get the chains supported for USDC compliance monitoring.
      */
     static getSupportedChains(): Chain[];
+    /**
+     * Add new sanctioned addresses at runtime.
+     * Normalizes all addresses to lowercase for consistent matching.
+     * Skips addresses that are already in the list.
+     *
+     * @param addresses - Array of Ethereum addresses to add
+     * @returns The count of newly added addresses (excluding duplicates)
+     */
+    static addSanctionedAddresses(addresses: string[]): number;
+    /**
+     * Replace the entire sanctioned addresses list at runtime.
+     * Clears existing entries and rebuilds from the provided array.
+     *
+     * @param addresses - The new complete list of sanctioned addresses
+     */
+    static replaceSanctionedAddresses(addresses: string[]): void;
+    /**
+     * Get the current number of addresses in the sanctions list.
+     *
+     * @returns The size of the current sanctions list
+     */
+    static getSanctionsListSize(): number;
     private static checkTokenType;
     private static checkChainSupport;
     private static checkAddressFormat;
@@ -2284,10 +2343,12 @@ declare class WebhookManager {
     setActive(webhookId: string, active: boolean): WebhookConfig | undefined;
     /**
      * Get all registered webhooks.
+     * Secrets are redacted to prevent accidental exposure in logs or API responses.
      */
     getWebhooks(): WebhookConfig[];
     /**
      * Get a specific webhook by ID.
+     * The secret is redacted to prevent accidental exposure in logs or API responses.
      */
     getWebhook(webhookId: string): WebhookConfig | undefined;
     /**
@@ -2327,6 +2388,27 @@ declare class WebhookManager {
     private deliverToWebhook;
     private computeSignature;
     private sleep;
+    /**
+     * Verify a webhook signature using constant-time comparison to prevent
+     * timing attacks. Use this in your webhook handler to validate incoming
+     * payloads from Kontext.
+     *
+     * @param payload - The raw JSON payload body (string)
+     * @param signature - The signature from the X-Kontext-Signature header
+     * @param secret - The webhook secret used during registration
+     * @returns Whether the signature is valid
+     *
+     * @example
+     * ```typescript
+     * const isValid = WebhookManager.verifySignature(
+     *   req.body, // raw JSON string
+     *   req.headers['x-kontext-signature'],
+     *   'my-webhook-secret',
+     * );
+     * if (!isValid) return res.status(401).send('Invalid signature');
+     * ```
+     */
+    static verifySignature(payload: string, signature: string, secret: string): boolean;
 }
 
 /** AI operation types recognized by the Vercel AI SDK middleware. */
@@ -2481,38 +2563,23 @@ interface KontextAIContext {
  * ```
  */
 declare function kontextMiddleware(kontext: Kontext, options?: KontextAIOptions): {
-    /**
-     * Logs the AI request parameters before the model is invoked.
-     * Captures the operation type, model ID, tool count, and generation settings.
-     */
-    transformParams: ({ params, type }: {
+    transformParams: (ctx: {
         params: Record<string, unknown>;
         type: string;
     }) => Promise<Record<string, unknown>>;
-    /**
-     * Wraps synchronous generation (`generateText`, `generateObject`).
-     * After the model returns, logs every tool call individually and the
-     * overall response. For financial tools, automatically creates
-     * compliance-tracked transaction records.
-     */
-    wrapGenerate: ({ doGenerate, params, }: {
+    wrapGenerate: (ctx: {
         doGenerate: () => Promise<Record<string, unknown>>;
         params: Record<string, unknown>;
     }) => Promise<Record<string, unknown>>;
-    /**
-     * Wraps streaming generation (`streamText`).
-     * Pipes the response stream through a transform that monitors for
-     * tool call chunks. On stream completion, logs the overall duration
-     * and any tool calls that occurred during the stream.
-     */
-    wrapStream: ({ doStream, params, }: {
+    wrapStream: (ctx: {
         doStream: () => Promise<{
             stream: ReadableStream;
             [key: string]: unknown;
         }>;
         params: Record<string, unknown>;
     }) => Promise<{
-        stream: ReadableStream<any>;
+        [key: string]: unknown;
+        stream: ReadableStream;
     }>;
 };
 /**
@@ -2625,4 +2692,4 @@ declare function withKontext(handler: (req: Request, ctx: KontextAIContext) => P
  */
 declare function extractAmount(args: unknown): number | null;
 
-export { type AIOperationType, type ActionLog, type AddressScreenResult, type AnomalyCallback, type AnomalyDetectionConfig, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type BlockedToolCall, type CCTPAttestationInput, type CCTPHook, type CCTPHookResult, type CCTPMessageStatus, CCTPTransferManager, type CCTPValidationCheck, type CCTPValidationResult, type CCTPVersion, type CTRReport, type Chain, type CircleApiAdapter, type CircleComplianceAdapter, CircleComplianceEngine, type CircleWallet, CircleWalletManager, type CircleWalletOptions, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceCheckSummary, type ComplianceReport, type CompliantTransferInput, type CompliantTransferResult, type ComprehensiveRiskFactor, type ComprehensiveRiskResult, type ConfirmCCTPTransferInput, type ConfirmTaskInput, type CreateKontextAIInput, type CreateKontextAIResult, type CreateTaskInput, type CreateWalletOptions, type CrossChainAuditEntry, type CrossChainTransfer, type DateRange, DigestChain, type DigestLink, type DigestVerification, type DualScreenResult, type Environment, type ExportFormat, type ExportOptions, type ExportResult, type FastTransferValidation, FileStorage, type GasEligibility, type GasEstimate, type GasEstimateInput, type GasSponsorshipLog, type GasStationAdapter, GasStationManager, type GenerateComplianceCertificateInput, type InitiateCCTPTransferInput, type InitiateFastTransferInput, Kontext, type KontextAIContext, type KontextAIOptions, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LogActionInput, type LogReasoningInput, type LogTransactionInput, MemoryStorage, type PrecisionTimestamp, type ReasoningEntry, type RegisterWebhookInput, type ReportOptions, type ReportSubject, type ReportType, type RiskAssessmentInput, type RiskFactor, type SARReport, type SanctionsCheckResult, type ScreenTransactionInput, type StorageAdapter, type Task, type TaskEvidence, type TaskStatus, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, UsdcCompliance, type UsdcComplianceCheck, type WalletBalance, type WalletSet, type WebhookConfig, type WebhookDeliveryResult, type WebhookEventType, WebhookManager, type WebhookPayload, type WebhookRetryConfig, type WithKontextOptions, createKontextAI, extractAmount, kontextMiddleware, kontextWrapModel, verifyExportedChain, withKontext };
+export { type AIOperationType, type ActionLog, type AddressScreenResult, type AnomalyCallback, type AnomalyDetectionConfig, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type BlockedToolCall, type CCTPAttestationInput, type CCTPHook, type CCTPHookResult, type CCTPMessageStatus, CCTPTransferManager, type CCTPValidationCheck, type CCTPValidationResult, type CCTPVersion, type CTRReport, type Chain, type CircleApiAdapter, type CircleComplianceAdapter, CircleComplianceEngine, type CircleWallet, CircleWalletManager, type CircleWalletOptions, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceCheckSummary, type ComplianceReport, type CompliantTransferInput, type CompliantTransferResult, type ComprehensiveRiskFactor, type ComprehensiveRiskResult, type ConfirmCCTPTransferInput, type ConfirmTaskInput, type CreateKontextAIInput, type CreateKontextAIResult, type CreateTaskInput, type CreateWalletOptions, type CrossChainAuditEntry, type CrossChainTransfer, type DateRange, DigestChain, type DigestLink, type DigestVerification, type DualScreenResult, type Environment, type ExportFormat, type ExportOptions, type ExportResult, type FastTransferValidation, FileStorage, type GasEligibility, type GasEstimate, type GasEstimateInput, type GasSponsorshipLog, type GasStationAdapter, GasStationManager, type GenerateComplianceCertificateInput, type InitiateCCTPTransferInput, type InitiateFastTransferInput, Kontext, type KontextAIContext, type KontextAIOptions, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LogActionInput, type LogLevel, type LogReasoningInput, type LogTransactionInput, MemoryStorage, type MetadataValidator, type PrecisionTimestamp, type ReasoningEntry, type RegisterWebhookInput, type ReportOptions, type ReportSubject, type ReportType, type RiskAssessmentInput, type RiskFactor, type SARReport, type SanctionsCheckResult, type ScreenTransactionInput, type StorageAdapter, type Task, type TaskEvidence, type TaskStatus, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, UsdcCompliance, type UsdcComplianceCheck, type WalletBalance, type WalletSet, type WebhookConfig, type WebhookDeliveryResult, type WebhookEventType, WebhookManager, type WebhookPayload, type WebhookRetryConfig, type WithKontextOptions, createKontextAI, extractAmount, kontextMiddleware, kontextWrapModel, verifyExportedChain, withKontext };