@oobe-protocol-labs/synapse-client-sdk 1.2.2 → 2.0.0

package/dist/cjs/ai/sap/validator.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @module ai/sap/validator
+ * @description SAP — Deep validation engine for agent registration & updates.
+ *
+ * Goes far beyond the basic name/description length checks: validates
+ * capability ID format, pricing consistency, wallet pubkey format,
+ * URL structure, duplicate detection, and cross-field coherence.
+ *
+ * Can operate in **strict** mode (throws on first error) or **lenient**
+ * mode (collects all issues and returns a report).
+ *
+ * @example
+ * ```ts
+ * import { SAPValidator } from '@oobe-protocol-labs/synapse-client-sdk/ai/sap';
+ *
+ * const validator = new SAPValidator({ strict: false });
+ * const report = validator.validateRegistration({
+ *   walletPubkey: 'ABC...',
+ *   name: 'My Agent',
+ *   description: 'Tools',
+ *   capabilities: [{ id: 'bad_format' }],  // ← will flag this
+ *   pricing: [{ tierId: '', pricePerCall: 0n, rateLimit: -1, ... }],
+ * });
+ *
+ * if (!report.valid) {
+ *   console.error(report.errors);   // detailed error list
+ *   console.warn(report.warnings);  // non-fatal suggestions
+ * }
+ * ```
+ *
+ * @since 1.4.0
+ */
+import type { RegisterAgentParams, UpdateAgentParams, AgentCapability, AgentPricingOnChain } from './types';
+import { SAPCapabilityRegistry } from './registry';
+/**
+ * @description Severity of a validation finding.
+ * @since 1.4.0
+ */
+export type ValidationSeverity = 'error' | 'warning' | 'info';
+/**
+ * @description A single validation finding.
+ * @since 1.4.0
+ */
+export interface ValidationIssue {
+    /** Severity level. */
+    severity: ValidationSeverity;
+    /** Machine-readable error code. */
+    code: string;
+    /** Human-readable message. */
+    message: string;
+    /** The field path that triggered the issue (e.g. `"capabilities[2].id"`). */
+    field?: string;
+    /** The offending value. */
+    value?: unknown;
+}
+/**
+ * @description Complete validation report.
+ * @since 1.4.0
+ */
+export interface ValidationReport {
+    /** `true` if zero errors (warnings/info are OK). */
+    valid: boolean;
+    /** Error-severity issues (block registration). */
+    errors: ValidationIssue[];
+    /** Warning-severity issues (allow but flag). */
+    warnings: ValidationIssue[];
+    /** Informational notes. */
+    info: ValidationIssue[];
+    /** Total time spent validating (ms). */
+    durationMs: number;
+}
+/**
+ * @description Error thrown in strict mode when validation fails.
+ * @since 1.4.0
+ */
+export declare class SAPValidationError extends Error {
+    readonly code: string;
+    readonly issues: ValidationIssue[];
+    constructor(message: string, code: string, issues: ValidationIssue[]);
+}
+/**
+ * @description Validator configuration.
+ * @since 1.4.0
+ */
+export interface SAPValidatorConfig {
+    /** Throw on first error (default: `false` → collect all). */
+    strict?: boolean;
+    /** Capability registry for validating capability IDs. If omitted, uses default. */
+    registry?: SAPCapabilityRegistry;
+    /** Allow unrecognised capability IDs (default: `true` — warn but don't error). */
+    allowUnknownCapabilities?: boolean;
+    /** Maximum number of capabilities per agent (default: 50). */
+    maxCapabilities?: number;
+    /** Maximum number of pricing tiers per agent (default: 10). */
+    maxPricingTiers?: number;
+}
+/**
+ * @description Deep validation engine for SAP agent data.
+ *
+ * Checks performed:
+ * - **Wallet pubkey**: Base58, 32–44 chars, valid character set
+ * - **Name**: Non-empty, ≤ 64 UTF-8 bytes, no control characters
+ * - **Description**: Non-empty, ≤ 512 UTF-8 bytes
+ * - **Capabilities**: `protocol:method` format, no duplicates, max count,
+ *   registry check (known vs unknown)
+ * - **Pricing**: Non-empty tierId, positive pricePerCall, rateLimit > 0,
+ *   maxCallsPerSession ≥ 0, valid tokenType, no duplicate tiers,
+ *   SPL requires tokenMint
+ * - **x402 Endpoint**: Must be HTTPS, valid URL structure
+ * - **Cross-field**: At least one capability for each pricing tier's
+ *   implied protocol (warning)
+ *
+ * @since 1.4.0
+ */
+export declare class SAPValidator {
+    private readonly config;
+    constructor(config?: SAPValidatorConfig);
+    /**
+     * @description Validate a full registration payload.
+     * @param {RegisterAgentParams} params - Registration parameters
+     * @returns {ValidationReport}
+     * @throws {SAPValidationError} In strict mode, on first error
+     * @since 1.4.0
+     */
+    validateRegistration(params: RegisterAgentParams): ValidationReport;
+    /**
+     * @description Validate an update payload.
+     * Only validates fields that are present (non-undefined).
+     * @param {UpdateAgentParams} params - Update parameters
+     * @returns {ValidationReport}
+     * @throws {SAPValidationError} In strict mode, on first error
+     * @since 1.4.0
+     */
+    validateUpdate(params: UpdateAgentParams): ValidationReport;
+    /**
+     * @description Validate a single capability entry.
+     * @param {AgentCapability} cap - Capability to validate
+     * @returns {ValidationReport}
+     * @since 1.4.0
+     */
+    validateCapability(cap: AgentCapability): ValidationReport;
+    /**
+     * @description Validate a single pricing tier.
+     * @param {AgentPricingOnChain} tier - Pricing tier to validate
+     * @returns {ValidationReport}
+     * @since 1.4.0
+     */
+    validatePricingTier(tier: AgentPricingOnChain): ValidationReport;
+    private validateWalletPubkey;
+    private validateName;
+    private validateDescription;
+    private validateCapabilities;
+    private checkCapability;
+    private validatePricing;
+    private checkPricingTier;
+    private validateX402Endpoint;
+    private validateCrossField;
+    private buildReport;
+}
+//# sourceMappingURL=validator.d.ts.map

package/dist/cjs/ai/sap/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../../src/ai/sap/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACpB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAMnD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,kDAAkD;IAClD,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,2BAA2B;IAC3B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,eAAe,EAAE;gBAFzC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,eAAe,EAAE;CAK5C;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,kFAAkF;IAClF,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAsBD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAE1C,MAAM,CAAC,EAAE,kBAAkB;IAYvC;;;;;;OAMG;IACH,oBAAoB,CAAC,MAAM,EAAE,mBAAmB,GAAG,gBAAgB;IAmCnE;;;;;;;OAOG;IACH,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB;IAe3D;;;;;OAKG;IACH,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,gBAAgB;IAO1D;;;;;OAKG;IACH,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,gBAAgB;IAShE,OAAO,CAAC,oBAAoB;IAmC5B,OAAO,CAAC,YAAY;IA2DpB,OAAO,CAAC,mBAAmB;IAoC3B,OAAO,CAAC,oBAAoB;IAoE5B,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,eAAe;IAsCvB,OAAO,CAAC,gBAAgB;IAgHxB,OAAO,CAAC,oBAAoB;IAgD5B,OAAO,CAAC,kBAAkB;IAsC1B,OAAO,CAAC,WAAW;CAyBpB"}