@neus/sdk 1.0.0 → 1.0.1

package/errors.js

@@ -1,228 +1,223 @@
-/**
- * NEUS SDK Error Classes
- * @license Apache-2.0
- */
-
-/**
- * Base SDK Error Class
- */
-export class SDKError extends Error {
-  constructor(message, code = 'SDK_ERROR', details = {}) {
-    super(message);
-    this.name = 'SDKError';
-    this.code = code;
-    this.details = details;
-    this.timestamp = Date.now();
-
-    // Ensure proper prototype chain
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, SDKError);
-    }
-  }
-
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      code: this.code,
-      details: this.details,
-      timestamp: this.timestamp
-    };
-  }
-}
-
-/**
- * API-related errors (server responses, HTTP issues)
- */
-export class ApiError extends SDKError {
-  constructor(message, statusCode = 500, code = 'API_ERROR', response = null) {
-    super(message, code);
-    this.name = 'ApiError';
-    this.statusCode = statusCode;
-    this.response = response;
-
-    // Additional classification
-    this.isClientError = statusCode >= 400 && statusCode < 500;
-    this.isServerError = statusCode >= 500;
-    this.isRetryable = this.isServerError || statusCode === 429; // Server errors or rate limit
-  }
-
-  static fromResponse(response, responseData) {
-    const statusCode = response.status;
-    const message =
-      responseData?.error?.message ||
-      responseData?.message ||
-      `API request failed with status ${statusCode}`;
-    const code = responseData?.error?.code || 'API_ERROR';
-
-    return new ApiError(message, statusCode, code, responseData);
-  }
-
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      statusCode: this.statusCode,
-      isClientError: this.isClientError,
-      isServerError: this.isServerError,
-      isRetryable: this.isRetryable
-    };
-  }
-}
-
-/**
- * Client-side validation errors (invalid parameters, missing required fields)
- */
-export class ValidationError extends SDKError {
-  constructor(message, field = null, value = null) {
-    super(message, 'VALIDATION_ERROR');
-    this.name = 'ValidationError';
-    this.field = field;
-    this.value = value;
-    this.isRetryable = false; // Validation errors are not retryable
-  }
-
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      field: this.field,
-      value: this.value,
-      isRetryable: this.isRetryable
-    };
-  }
-}
-
-/**
- * Network-related errors (connectivity, timeouts, DNS issues)
- */
-export class NetworkError extends SDKError {
-  constructor(message, code = 'NETWORK_ERROR', originalError = null) {
-    super(message, code);
-    this.name = 'NetworkError';
-    this.originalError = originalError;
-    this.isRetryable = true; // Network errors are typically retryable
-  }
-
-  static isNetworkError(error) {
-    return (
-      error instanceof NetworkError ||
-      (error.name === 'TypeError' && error.message.includes('fetch')) ||
-      error.name === 'AbortError' ||
-      error.code === 'ENOTFOUND' ||
-      error.code === 'ECONNREFUSED' ||
-      error.code === 'ETIMEDOUT'
-    );
-  }
-
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      isRetryable: this.isRetryable,
-      originalError: this.originalError
-        ? {
-            name: this.originalError.name,
-            message: this.originalError.message,
-            code: this.originalError.code
-          }
-        : null
-    };
-  }
-}
-
-/**
- * Configuration-related errors (missing configuration, invalid settings)
- */
-export class ConfigurationError extends SDKError {
-  constructor(message, configKey = null) {
-    super(message, 'CONFIGURATION_ERROR');
-    this.name = 'ConfigurationError';
-    this.configKey = configKey;
-    this.isRetryable = false; // Config errors require user intervention
-  }
-
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      configKey: this.configKey,
-      isRetryable: this.isRetryable
-    };
-  }
-}
-
-/**
- * Verification-specific errors (verifier failures, invalid proofs)
- */
-export class VerificationError extends SDKError {
-  constructor(message, verifierId = null, code = 'VERIFICATION_ERROR') {
-    super(message, code);
-    this.name = 'VerificationError';
-    this.verifierId = verifierId;
-    this.isRetryable = true; // Some verification errors might be retryable
-  }
-
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      verifierId: this.verifierId,
-      isRetryable: this.isRetryable
-    };
-  }
-}
-
-/**
- * Authentication-related errors (signature validation, wallet connection)
- */
-export class AuthenticationError extends SDKError {
-  constructor(message, code = 'AUTHENTICATION_ERROR') {
-    super(message, code);
-    this.name = 'AuthenticationError';
-    this.isRetryable = false; // Auth errors require user intervention
-  }
-
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      isRetryable: this.isRetryable
-    };
-  }
-}
-
-/**
- * Utility function to create appropriate error from generic error
- */
-export function createErrorFromGeneric(error, context = {}) {
-  if (error instanceof SDKError) {
-    return error;
-  }
-
-  // Network-related errors
-  if (NetworkError.isNetworkError(error)) {
-    return new NetworkError(
-      error.message || 'Network error occurred',
-      error.code || 'NETWORK_ERROR',
-      error
-    );
-  }
-
-  // Timeout errors
-  if (error.name === 'AbortError' || error.message.includes('timeout')) {
-    return new NetworkError('Request timeout', 'TIMEOUT', error);
-  }
-
-  // Generic error wrapper
-  return new SDKError(error.message || 'Unknown error occurred', error.code || 'UNKNOWN_ERROR', {
-    originalError: error,
-    context
-  });
-}
-
-// Export all error classes as default
-export default {
-  SDKError,
-  ApiError,
-  ValidationError,
-  NetworkError,
-  ConfigurationError,
-  VerificationError,
-  AuthenticationError,
-  createErrorFromGeneric
-};
+/**
+ * NEUS SDK Error Classes
+ */
+
+/**
+ * Base SDK Error Class
+ */
+export class SDKError extends Error {
+  constructor(message, code = 'SDK_ERROR', details = {}) {
+    super(message);
+    this.name = 'SDKError';
+    this.code = code;
+    this.details = details;
+    this.timestamp = Date.now();
+    
+    // Ensure proper prototype chain
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, SDKError);
+    }
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details,
+      timestamp: this.timestamp
+    };
+  }
+}
+
+/**
+ * API-related errors (server responses, HTTP issues)
+ */
+export class ApiError extends SDKError {
+  constructor(message, statusCode = 500, code = 'API_ERROR', response = null) {
+    super(message, code);
+    this.name = 'ApiError';
+    this.statusCode = statusCode;
+    this.response = response;
+    
+    // Additional classification
+    this.isClientError = statusCode >= 400 && statusCode < 500;
+    this.isServerError = statusCode >= 500;
+    this.isRetryable = this.isServerError || statusCode === 429; // Server errors or rate limit
+  }
+
+  static fromResponse(response, responseData) {
+    const statusCode = response.status;
+    const message = responseData?.error?.message || 
+                   responseData?.message || 
+                   `API request failed with status ${statusCode}`;
+    const code = responseData?.error?.code || 'API_ERROR';
+    
+    return new ApiError(message, statusCode, code, responseData);
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      statusCode: this.statusCode,
+      isClientError: this.isClientError,
+      isServerError: this.isServerError,
+      isRetryable: this.isRetryable
+    };
+  }
+}
+
+/**
+ * Client-side validation errors (invalid parameters, missing required fields)
+ */
+export class ValidationError extends SDKError {
+  constructor(message, field = null, value = null) {
+    super(message, 'VALIDATION_ERROR');
+    this.name = 'ValidationError';
+    this.field = field;
+    this.value = value;
+    this.isRetryable = false; // Validation errors are not retryable
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      field: this.field,
+      value: this.value,
+      isRetryable: this.isRetryable
+    };
+  }
+}
+
+/**
+ * Network-related errors (connectivity, timeouts, DNS issues)
+ */
+export class NetworkError extends SDKError {
+  constructor(message, code = 'NETWORK_ERROR', originalError = null) {
+    super(message, code);
+    this.name = 'NetworkError';
+    this.originalError = originalError;
+    this.isRetryable = true; // Network errors are typically retryable
+  }
+
+  static isNetworkError(error) {
+    return error instanceof NetworkError ||
+           error.name === 'TypeError' && error.message.includes('fetch') ||
+           error.name === 'AbortError' ||
+           error.code === 'ENOTFOUND' ||
+           error.code === 'ECONNREFUSED' ||
+           error.code === 'ETIMEDOUT';
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      isRetryable: this.isRetryable,
+      originalError: this.originalError ? {
+        name: this.originalError.name,
+        message: this.originalError.message,
+        code: this.originalError.code
+      } : null
+    };
+  }
+}
+
+/**
+ * Configuration-related errors (missing configuration, invalid settings)
+ */
+export class ConfigurationError extends SDKError {
+  constructor(message, configKey = null) {
+    super(message, 'CONFIGURATION_ERROR');
+    this.name = 'ConfigurationError';
+    this.configKey = configKey;
+    this.isRetryable = false; // Config errors require user intervention
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      configKey: this.configKey,
+      isRetryable: this.isRetryable
+    };
+  }
+}
+
+/**
+ * Verification-specific errors (verifier failures, invalid proofs)
+ */
+export class VerificationError extends SDKError {
+  constructor(message, verifierId = null, code = 'VERIFICATION_ERROR') {
+    super(message, code);
+    this.name = 'VerificationError';
+    this.verifierId = verifierId;
+    this.isRetryable = true; // Some verification errors might be retryable
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      verifierId: this.verifierId,
+      isRetryable: this.isRetryable
+    };
+  }
+}
+
+/**
+ * Authentication-related errors (signature validation, wallet connection)
+ */
+export class AuthenticationError extends SDKError {
+  constructor(message, code = 'AUTHENTICATION_ERROR') {
+    super(message, code);
+    this.name = 'AuthenticationError';
+    this.isRetryable = false; // Auth errors require user intervention
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      isRetryable: this.isRetryable
+    };
+  }
+}
+
+/**
+ * Utility function to create appropriate error from generic error
+ */
+export function createErrorFromGeneric(error, context = {}) {
+  if (error instanceof SDKError) {
+    return error;
+  }
+
+  // Network-related errors
+  if (NetworkError.isNetworkError(error)) {
+    return new NetworkError(
+      error.message || 'Network error occurred',
+      error.code || 'NETWORK_ERROR',
+      error
+    );
+  }
+
+  // Timeout errors
+  if (error.name === 'AbortError' || error.message.includes('timeout')) {
+    return new NetworkError('Request timeout', 'TIMEOUT', error);
+  }
+
+  // Generic error wrapper
+  return new SDKError(
+    error.message || 'Unknown error occurred',
+    error.code || 'UNKNOWN_ERROR',
+    { originalError: error, context }
+  );
+}
+
+// Export all error classes as default
+export default {
+  SDKError,
+  ApiError,
+  ValidationError,
+  NetworkError,
+  ConfigurationError,
+  VerificationError,
+  AuthenticationError,
+  createErrorFromGeneric
+};

package/gates.js

@@ -0,0 +1,175 @@
+/**
+ * NEUS SDK Gate Recipes
+ * 
+ * These are EXAMPLES, not defaults.
+ * Pick or copy-paste what fits your use case.
+ * 
+ * @license Apache-2.0
+ */
+
+// Time constants (milliseconds)
+export const HOUR = 60 * 60 * 1000;
+export const DAY = 24 * HOUR;
+export const WEEK = 7 * DAY;
+export const MONTH = 30 * DAY;
+export const YEAR = 365 * DAY;
+
+// ============================================================================
+// RECIPE GATES - Use case specific examples
+// ============================================================================
+
+/**
+ * NFT holder gate
+ * Integrator should add match: { contractAddress: '0x...' } when using
+ */
+export const GATE_NFT_HOLDER = [
+  { verifierId: 'nft-ownership' },
+];
+
+/**
+ * Token holder gate
+ * Integrator should add match: { contractAddress: '0x...', minBalance: '...' }
+ */
+export const GATE_TOKEN_HOLDER = [
+  { verifierId: 'token-holding' },
+];
+
+/**
+ * Contract admin gate: requires recent contract ownership verification
+ * Short TTL (1h) because ownership can transfer (point-in-time proof)
+ */
+export const GATE_CONTRACT_ADMIN = [
+  { verifierId: 'contract-ownership', maxAgeMs: HOUR },
+];
+
+/**
+ * Domain owner gate: requires DNS TXT verification
+ * For verified organization badges, creator platforms
+ */
+export const GATE_DOMAIN_OWNER = [
+  { verifierId: 'ownership-dns-txt' },
+];
+
+/**
+ * Linked wallets gate: requires wallet linking
+ * For multi-wallet identity features
+ */
+export const GATE_LINKED_WALLETS = [
+  { verifierId: 'wallet-link' },
+];
+
+/**
+ * Agent identity gate: requires verified agent identity
+ * For agent/bot verification features
+ */
+export const GATE_AGENT_IDENTITY = [
+  { verifierId: 'agent-identity' },
+];
+
+/**
+ * Agent delegation gate: requires delegation proof
+ * With recommended 7-day TTL for security
+ */
+export const GATE_AGENT_DELEGATION = [
+  { verifierId: 'agent-delegation', maxAgeMs: 7 * DAY },
+];
+
+/**
+ * Content moderation gate: requires a moderation proof for the exact contentHash.
+ * Proof is permanent (policy snapshot); re-run only if your policy/provider requirements change.
+ */
+export const GATE_CONTENT_MODERATION = [
+  { verifierId: 'ai-content-moderation' },
+];
+
+/**
+ * Wallet risk gate: requires wallet risk assessment
+ * Provider-backed risk signal
+ */
+export const GATE_WALLET_RISK = [
+  { verifierId: 'wallet-risk' },
+];
+
+/**
+ * Pseudonym gate: requires pseudonymous identity proof
+ * For anonymous reputation systems
+ */
+export const GATE_PSEUDONYM = [
+  { verifierId: 'ownership-pseudonym' },
+];
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Create a custom gate from verifier IDs
+ * @param {Array<string|Object>} requirements - Array of verifier IDs or requirement objects
+ * @returns {Array} Gate requirements array
+ * 
+ * @example
+ * // Simple: just verifier IDs
+ * const gate = createGate(['nft-ownership', 'token-holding']);
+ * 
+ * // With options
+ * const gate = createGate([
+ *   { verifierId: 'nft-ownership', match: { contractAddress: '0x...' } },
+ *   { verifierId: 'token-holding', maxAgeMs: 7 * DAY },
+ * ]);
+ */
+export function createGate(requirements) {
+  return requirements.map(req => {
+    if (typeof req === 'string') {
+      return { verifierId: req };
+    }
+    return req;
+  });
+}
+
+/**
+ * Combine multiple gates (union of requirements)
+ * @param  {...Array} gates - Gate arrays to combine
+ * @returns {Array} Combined gate requirements
+ * 
+ * @example
+ * const strictGate = combineGates(GATE_NFT_HOLDER, GATE_TOKEN_HOLDER);
+ */
+export function combineGates(...gates) {
+  const combined = [];
+  const seen = new Set();
+  
+  for (const gate of gates) {
+    for (const req of gate) {
+      const key = req.verifierId + JSON.stringify(req.match || {});
+      if (!seen.has(key)) {
+        seen.add(key);
+        combined.push(req);
+      }
+    }
+  }
+  
+  return combined;
+}
+
+export default {
+  // Time constants
+  HOUR,
+  DAY,
+  WEEK,
+  MONTH,
+  YEAR,
+  // Recipe gates
+  GATE_NFT_HOLDER,
+  GATE_TOKEN_HOLDER,
+  GATE_CONTRACT_ADMIN,
+  GATE_DOMAIN_OWNER,
+  GATE_LINKED_WALLETS,
+  GATE_AGENT_IDENTITY,
+  GATE_AGENT_DELEGATION,
+  GATE_CONTENT_MODERATION,
+  GATE_WALLET_RISK,
+  GATE_PSEUDONYM,
+  // Helpers
+  createGate,
+  combineGates,
+};