kontext-sdk 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -178,7 +178,7 @@ declare class FileStorage implements StorageAdapter {
 /** Supported blockchain networks */
 type Chain = 'ethereum' | 'base' | 'polygon' | 'arbitrum' | 'optimism' | 'arc' | 'avalanche' | 'solana';
 /** Supported stablecoin tokens */
-type Token = 'USDC' | 'USDT' | 'DAI' | 'EURC';
+type Token = 'USDC' | 'USDT' | 'DAI' | 'EURC' | 'USDP' | 'USDG';
 /** SDK operating mode */
 type KontextMode = 'local' | 'cloud';
 /** Log level for the SDK logger */
@@ -373,19 +373,19 @@ interface LogActionInput {
     /** Arbitrary metadata */
     metadata?: Record<string, unknown>;
 }
-/** Input for logging a cryptocurrency transaction */
+/** Input for logging a transaction (crypto or general payment) */
 interface LogTransactionInput {
-    /** On-chain transaction hash */
-    txHash: string;
-    /** Blockchain network */
-    chain: Chain;
+    /** On-chain transaction hash (required for crypto, optional for general payments) */
+    txHash?: string;
+    /** Blockchain network (required for crypto, optional for general payments) */
+    chain?: Chain;
     /** Transaction amount (string to preserve decimal precision) */
     amount: string;
-    /** Token being transferred */
-    token: Token;
-    /** Sender address */
+    /** Token being transferred (required for crypto, optional for general payments) */
+    token?: Token;
+    /** Sender address or entity name */
     from: string;
-    /** Recipient address */
+    /** Recipient address or entity name */
     to: string;
     /** ID of the agent initiating the transaction */
     agentId: string;
@@ -395,17 +395,28 @@ interface LogTransactionInput {
     correlationId?: string;
     /** Additional transaction metadata */
     metadata?: Record<string, unknown>;
+    /** Currency code for general payments (e.g., 'USD', 'EUR'). Inferred from token for crypto. */
+    currency?: string;
+    /** Payment method (e.g., 'wire', 'ach', 'card', 'crypto') */
+    paymentMethod?: string;
+    /** External payment reference (invoice ID, wire reference, etc.) */
+    paymentReference?: string;
 }
 /** Stored transaction record */
 interface TransactionRecord extends ActionLog {
     type: 'transaction';
-    txHash: string;
-    chain: Chain;
+    txHash?: string;
+    chain?: Chain;
     amount: string;
-    token: Token;
+    token?: Token;
     from: string;
     to: string;
+    currency?: string;
+    paymentMethod?: string;
+    paymentReference?: string;
 }
+/** Check whether a transaction input has all crypto-specific fields */
+declare function isCryptoTransaction(input: LogTransactionInput): boolean;
 /** Input for creating a new tracked task */
 interface CreateTaskInput {
     /** Human-readable task description */
@@ -612,8 +623,8 @@ interface TrustFactor {
 }
 /** Transaction evaluation result */
 interface TransactionEvaluation {
-    /** Transaction hash */
-    txHash: string;
+    /** Transaction hash (present for crypto transactions) */
+    txHash?: string;
     /** Risk score (0-100, higher = more risky) */
     riskScore: number;
     /** Risk level */
@@ -946,6 +957,16 @@ declare class DigestChain {
      * This can be embedded in outgoing messages as proof of the entire action history.
      */
     getTerminalDigest(): string;
+    /**
+     * Restore the terminal digest from persisted state.
+     * Called after loading actions from storage so that new actions
+     * chain correctly from the last stored digest instead of genesis.
+     *
+     * Does NOT reconstruct the links array — in-memory verification
+     * via verify() will not work after restore. Use the stored action
+     * digest/priorDigest fields for cross-process chain verification.
+     */
+    restoreTerminalDigest(digest: string): void;
     /**
      * Get the number of links in the chain.
      */
@@ -1346,6 +1367,8 @@ declare class Kontext {
     /**
      * Restore state from the attached storage adapter.
      * Loads previously persisted actions, transactions, tasks, and anomalies.
+     * Also restores the digest chain's terminal digest so that new actions
+     * chain correctly across process boundaries.
      * No-op if no storage adapter is configured.
      */
     restore(): Promise<void>;
@@ -1581,7 +1604,7 @@ declare class Kontext {
      * and cryptographically verifies the digest chain integrity.
      *
      * The certificate includes: action/transaction/reasoning counts, digest chain
-     * verification status (Patent US 12,463,819 B1), the agent's current trust
+     * verification status (patented), the agent's current trust
      * score, and an overall compliance status. A SHA-256 content hash of the
      * certificate itself is included for tamper-evidence.
      *
@@ -1665,148 +1688,6 @@ declare class Kontext {
     destroy(): Promise<void>;
 }
 
-interface FirestoreStorageConfig {
-    /** GCP project ID — use "Kontext" for the Kontext production project */
-    gcpProjectId: string;
-    /**
-     * The user/tenant ID that owns these logs. Required for data isolation.
-     * Use a stable identifier: Stripe customer ID, your auth system's user ID,
-     * or a deterministic hash of the API key.
-     */
-    userId: string;
-    /**
-     * OAuth2 access token for the Firestore REST API.
-     * On GCP (Cloud Run, GCE, GKE): omit — the adapter will fetch a token
-     * from the GCP metadata server automatically.
-     * For local dev or other environments: pass a token from Application Default
-     * Credentials (`gcloud auth print-access-token`).
-     */
-    accessToken?: string;
-    /**
-     * Firestore database ID. Defaults to '(default)'.
-     * Change only if you created a named database in the GCP console.
-     */
-    databaseId?: string;
-    /**
-     * Whether to write each record as an individual Firestore document
-     * in addition to the bulk flush writes. Enables real-time querying
-     * per-action, per-session, per-agent.
-     * @default true
-     */
-    writeDocumentsIndividually?: boolean;
-    /**
-     * Custom Firestore REST base URL. Override for testing or emulator use.
-     * @default 'https://firestore.googleapis.com'
-     */
-    firestoreBaseUrl?: string;
-}
-/**
- * Persistent, hierarchical Firestore storage adapter for Kontext audit logs.
- *
- * Stores compliance logs by user → project → agent → session, enabling
- * regulatory-grade queries: "show me all transactions agent X made in
- * session Y" or "export all logs for user Z".
- *
- * Works as a drop-in replacement for FileStorage:
- *
- * @example
- * ```typescript
- * import { Kontext, FirestoreStorageAdapter } from 'kontext-sdk';
- *
- * const ctx = Kontext.init({
- *   projectId: 'treasury-agent',
- *   environment: 'production',
- *   storage: new FirestoreStorageAdapter({
- *     gcpProjectId: 'Kontext',
- *     userId: 'user-abc123',
- *   }),
- * });
- *
- * // After this, all verify(), log(), logReasoning() calls are
- * // persisted to Firestore at:
- * // users/user-abc123/projects/treasury-agent/agents/{agentId}/sessions/{sessionId}/...
- * ```
- */
-declare class FirestoreStorageAdapter implements StorageAdapter {
-    private readonly config;
-    /** In-memory cache for load() — avoids re-fetching on every store.restore() */
-    private cache;
-    /** Token cache: avoid metadata server round-trips on every write */
-    private cachedToken;
-    private tokenExpiresAt;
-    constructor(config: FirestoreStorageConfig);
-    /**
-     * Save data under a Kontext storage key.
-     *
-     * The flat key space (kontext:actions, kontext:transactions, etc.) is mapped
-     * to structured Firestore paths. List data (actions, transactions) is written
-     * as individual documents under sub-collections for queryability.
-     */
-    save(key: string, data: unknown): Promise<void>;
-    /**
-     * Load data for a Kontext storage key.
-     * Returns cached data if available (populated by save()).
-     * Falls back to Firestore fetch for cold starts.
-     */
-    load(key: string): Promise<unknown | null>;
-    delete(key: string): Promise<void>;
-    list(prefix?: string): Promise<string[]>;
-    /**
-     * Write a single action log to its canonical Firestore path.
-     * Called by the SDK when `writeDocumentsIndividually` is true.
-     *
-     * Path: users/{userId}/projects/{projectId}/agents/{agentId}/sessions/{sessionId}/actions/{actionId}
-     */
-    writeAction(action: ActionLog): Promise<void>;
-    /**
-     * Write a single transaction record to its canonical Firestore path.
-     *
-     * Path: users/{userId}/projects/{projectId}/agents/{agentId}/sessions/{sessionId}/transactions/{txId}
-     */
-    writeTransaction(tx: TransactionRecord): Promise<void>;
-    /**
-     * Write a single task to its canonical Firestore path.
-     *
-     * Path: users/{userId}/projects/{projectId}/tasks/{taskId}
-     */
-    writeTask(task: Task): Promise<void>;
-    private get basePath();
-    private actionPath;
-    private transactionPath;
-    private taskPath;
-    private anomalyPath;
-    private keyToPath;
-    private saveActionList;
-    private saveTransactionList;
-    private saveTaskList;
-    private saveAnomalyList;
-    private loadActionList;
-    private loadTransactionList;
-    private loadTaskList;
-    private loadAnomalyList;
-    private firestoreBase;
-    /** Save an arbitrary JS object as a Firestore document at the given path. */
-    private saveDocument;
-    /** Load a document at the given Firestore path. Returns null if not found. */
-    private loadDocument;
-    /** Delete a document at the given Firestore path. */
-    private deleteDocument;
-    /**
-     * List all documents in a collection and deserialize them.
-     * Used for tasks (simple flat collection).
-     */
-    private queryCollection;
-    /**
-     * Run a Firestore collection group query to fetch documents across all
-     * nested sub-collections with the given name (e.g., 'actions' across all
-     * agents and sessions).
-     *
-     * Scoped to the user's project root to prevent cross-tenant reads.
-     */
-    private queryCollectionGroup;
-    private getToken;
-}
-
 /** Features gated by plan tier */
 type GatedFeature = 'advanced-anomaly-rules' | 'sar-ctr-reports' | 'webhooks' | 'ofac-screening' | 'csv-export' | 'multi-chain' | 'cftc-compliance' | 'circle-wallets' | 'circle-compliance' | 'gas-station' | 'cctp-transfers' | 'approval-policies' | 'unified-screening' | 'blocklist-manager' | 'kya-identity' | 'kya-behavioral';
 /**
@@ -1941,6 +1822,21 @@ declare class UsdcCompliance {
     private static generateRecommendations;
 }
 
+declare class PaymentCompliance {
+    /**
+     * Run compliance checks on a general payment.
+     *
+     * @param input - Payment to evaluate
+     * @returns UsdcComplianceCheck with pass/fail results and recommendations
+     */
+    static checkPayment(input: LogTransactionInput): UsdcComplianceCheck;
+    private static checkAmountValid;
+    private static checkEntityScreening;
+    private static checkEnhancedDueDiligence;
+    private static checkReportingThreshold;
+    private static generateRecommendations;
+}
+
 /**
  * In-memory data store for the Kontext SDK.
  * Holds all action logs, transactions, tasks, and anomaly events.
@@ -2286,4 +2182,4 @@ declare class AnomalyDetector {
     private notifyCallbacks;
 }
 
-export { type ActionLog, type AgentData, type AnomalyCallback, type AnomalyDetectionConfig, AnomalyDetector, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type Chain, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceReport, type ConfirmTaskInput, ConsoleExporter, type CreateTaskInput, type DateRange, DigestChain, type DigestLink, type DigestVerification, type Environment, type EventExporter, type ExportFormat, type ExportOptions, type ExportResult, type ExporterResult, type FeatureFlag, type FeatureFlagConfig, FeatureFlagManager, FileStorage, FirestoreStorageAdapter, type FirestoreStorageConfig, type FlagPlanTargeting, type FlagScope, type FlagTargeting, type GatedFeature, type GenerateComplianceCertificateInput, JsonFileExporter, Kontext, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LimitEvent, type LogActionInput, type LogLevel, type LogReasoningInput, type LogTransactionInput, MemoryStorage, type MetadataValidator, NoopExporter, PLAN_LIMITS, type PlanConfig, PlanManager, type PlanTier, type PlanUsage, type PrecisionTimestamp, type ReasoningEntry, type ReportOptions, type ReportType, type RiskFactor, type SanctionsCheckResult, type StorageAdapter, type Task, type TaskEvidence, type TaskStatus, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, TrustScorer, UsdcCompliance, type UsdcComplianceCheck, type VerifyInput, type VerifyResult, isFeatureAvailable, requirePlan, verifyExportedChain };
+export { type ActionLog, type AgentData, type AnomalyCallback, type AnomalyDetectionConfig, AnomalyDetector, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type Chain, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceReport, type ConfirmTaskInput, ConsoleExporter, type CreateTaskInput, type DateRange, DigestChain, type DigestLink, type DigestVerification, type Environment, type EventExporter, type ExportFormat, type ExportOptions, type ExportResult, type ExporterResult, type FeatureFlag, type FeatureFlagConfig, FeatureFlagManager, FileStorage, type FlagPlanTargeting, type FlagScope, type FlagTargeting, type GatedFeature, type GenerateComplianceCertificateInput, JsonFileExporter, Kontext, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LimitEvent, type LogActionInput, type LogLevel, type LogReasoningInput, type LogTransactionInput, MemoryStorage, type MetadataValidator, NoopExporter, PLAN_LIMITS, PaymentCompliance, type PlanConfig, PlanManager, type PlanTier, type PlanUsage, type PrecisionTimestamp, type ReasoningEntry, type ReportOptions, type ReportType, type RiskFactor, type SanctionsCheckResult, type StorageAdapter, type Task, type TaskEvidence, type TaskStatus, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, TrustScorer, UsdcCompliance, type UsdcComplianceCheck, type VerifyInput, type VerifyResult, isCryptoTransaction, isFeatureAvailable, requirePlan, verifyExportedChain };