vesant-sdk 1.5.2 → 1.6.0

package/dist/{client-B8pFrXx_.d.ts → client-Bd9a5o0C.d.ts}

@@ -295,6 +295,8 @@ interface LocationVerification {
     geofence_evaluation?: GeofenceEvaluation;
     device_trust?: DeviceTrustResult;
     record_id: string;
+    /** Whether GPS verification is required for this event type (based on tenant config) */
+    gps_required?: boolean;
 }
 interface ComplianceCheckResponse {
     jurisdiction?: JurisdictionConfig;

package/dist/{client-BZxzOidG.d.mts → client-C4g596fI.d.mts}

@@ -295,6 +295,8 @@ interface LocationVerification {
     geofence_evaluation?: GeofenceEvaluation;
     device_trust?: DeviceTrustResult;
     record_id: string;
+    /** Whether GPS verification is required for this event type (based on tenant config) */
+    gps_required?: boolean;
 }
 interface ComplianceCheckResponse {
     jurisdiction?: JurisdictionConfig;

package/dist/compliance/index.d.mts

@@ -1,5 +1,5 @@
-import { D as DeviceFingerprintRequest, L as LocationVerification, T as LocationRequest, G as GeolocationClient, Y as LocationRequestFilters, Z as LocationRequestListResponse } from '../client-BZxzOidG.mjs';
-export { W as CreateLocationRequestRequest, a0 as LocationCaptureRequest, a2 as LocationCaptureResponse, S as LocationRequestChannel, X as LocationRequestResult, R as LocationRequestStatus, a1 as LocationShareInfo, _ as ResendLocationRequestRequest } from '../client-BZxzOidG.mjs';
+import { D as DeviceFingerprintRequest, L as LocationVerification, k as ValidateCipherTextResponse, T as LocationRequest, G as GeolocationClient, Y as LocationRequestFilters, Z as LocationRequestListResponse } from '../client-C4g596fI.mjs';
+export { W as CreateLocationRequestRequest, a0 as LocationCaptureRequest, a2 as LocationCaptureResponse, S as LocationRequestChannel, X as LocationRequestResult, R as LocationRequestStatus, a1 as LocationShareInfo, _ as ResendLocationRequestRequest } from '../client-C4g596fI.mjs';
 import { RiskProfileClient } from '../risk-profile/index.mjs';
 import { V as VesantConfig, R as RequestOptions } from '../client-CIon-bGS.mjs';
 import { C as CustomerProfile } from '../types-1RzYeSal.mjs';
@@ -15,6 +15,7 @@ interface RegistrationVerificationRequest {
     entityType?: EntityType;
     ipAddress: string;
     deviceFingerprint?: DeviceFingerprintRequest;
+    cipherText?: string;
     metadata?: Record<string, unknown>;
 }
 interface RegistrationVerificationResponse {
@@ -25,11 +26,13 @@ interface RegistrationVerificationResponse {
     requiresEDD: boolean;
     blockReasons: string[];
     processingTime: number;
+    cipherTextValidation?: ValidateCipherTextResponse;
 }
 interface LoginVerificationRequest {
     customerId: string;
     ipAddress: string;
     deviceFingerprint?: DeviceFingerprintRequest;
+    cipherText?: string;
     metadata?: Record<string, unknown>;
 }
 interface LoginVerificationResponse {
@@ -39,6 +42,7 @@ interface LoginVerificationResponse {
     requiresStepUp: boolean;
     blockReasons: string[];
     processingTime: number;
+    cipherTextValidation?: ValidateCipherTextResponse;
 }
 interface TransactionVerificationRequest {
     customerId: string;
@@ -47,6 +51,7 @@ interface TransactionVerificationRequest {
     currency: string;
     transactionType?: 'deposit' | 'withdrawal' | 'bet' | 'transfer' | 'payout';
     deviceFingerprint?: DeviceFingerprintRequest;
+    cipherText?: string;
     metadata?: Record<string, unknown>;
 }
 interface TransactionVerificationResponse {
@@ -57,6 +62,7 @@ interface TransactionVerificationResponse {
     requiresApproval: boolean;
     blockReasons: string[];
     processingTime: number;
+    cipherTextValidation?: ValidateCipherTextResponse;
 }
 interface TransactionRiskResult {
     score: number;
@@ -70,6 +76,7 @@ interface EventVerificationRequest {
     ipAddress: string;
     eventType: string;
     deviceFingerprint?: DeviceFingerprintRequest;
+    cipherText?: string;
     metadata?: Record<string, unknown>;
 }
 interface EventVerificationResponse {
@@ -77,6 +84,7 @@ interface EventVerificationResponse {
     geolocation: LocationVerification;
     blockReasons: string[];
     processingTime: number;
+    cipherTextValidation?: ValidateCipherTextResponse;
 }
 interface CurrencyRates {
     [currency: string]: number;
@@ -264,6 +272,11 @@ declare class ComplianceClient {
     verifyEvent(request: EventVerificationRequest, requestOptions?: RequestOptions): Promise<EventVerificationResponse>;
     private shouldUpdateProfile;
     private createProfileFromGeo;
+    /**
+     * Execute cipherText validation with graceful degradation.
+     * Returns undefined if cipherText is not provided or validation fails.
+     */
+    private executeCipherTextValidation;
     private calculateTransactionRisk;
     private checkJurisdictionLimits;
     private normalizeToUSD;

package/dist/compliance/index.d.ts

@@ -1,5 +1,5 @@
-import { D as DeviceFingerprintRequest, L as LocationVerification, T as LocationRequest, G as GeolocationClient, Y as LocationRequestFilters, Z as LocationRequestListResponse } from '../client-B8pFrXx_.js';
-export { W as CreateLocationRequestRequest, a0 as LocationCaptureRequest, a2 as LocationCaptureResponse, S as LocationRequestChannel, X as LocationRequestResult, R as LocationRequestStatus, a1 as LocationShareInfo, _ as ResendLocationRequestRequest } from '../client-B8pFrXx_.js';
+import { D as DeviceFingerprintRequest, L as LocationVerification, k as ValidateCipherTextResponse, T as LocationRequest, G as GeolocationClient, Y as LocationRequestFilters, Z as LocationRequestListResponse } from '../client-Bd9a5o0C.js';
+export { W as CreateLocationRequestRequest, a0 as LocationCaptureRequest, a2 as LocationCaptureResponse, S as LocationRequestChannel, X as LocationRequestResult, R as LocationRequestStatus, a1 as LocationShareInfo, _ as ResendLocationRequestRequest } from '../client-Bd9a5o0C.js';
 import { RiskProfileClient } from '../risk-profile/index.js';
 import { V as VesantConfig, R as RequestOptions } from '../client-CIon-bGS.js';
 import { C as CustomerProfile } from '../types-X5Md_dD_.js';
@@ -15,6 +15,7 @@ interface RegistrationVerificationRequest {
     entityType?: EntityType;
     ipAddress: string;
     deviceFingerprint?: DeviceFingerprintRequest;
+    cipherText?: string;
     metadata?: Record<string, unknown>;
 }
 interface RegistrationVerificationResponse {
@@ -25,11 +26,13 @@ interface RegistrationVerificationResponse {
     requiresEDD: boolean;
     blockReasons: string[];
     processingTime: number;
+    cipherTextValidation?: ValidateCipherTextResponse;
 }
 interface LoginVerificationRequest {
     customerId: string;
     ipAddress: string;
     deviceFingerprint?: DeviceFingerprintRequest;
+    cipherText?: string;
     metadata?: Record<string, unknown>;
 }
 interface LoginVerificationResponse {
@@ -39,6 +42,7 @@ interface LoginVerificationResponse {
     requiresStepUp: boolean;
     blockReasons: string[];
     processingTime: number;
+    cipherTextValidation?: ValidateCipherTextResponse;
 }
 interface TransactionVerificationRequest {
     customerId: string;
@@ -47,6 +51,7 @@ interface TransactionVerificationRequest {
     currency: string;
     transactionType?: 'deposit' | 'withdrawal' | 'bet' | 'transfer' | 'payout';
     deviceFingerprint?: DeviceFingerprintRequest;
+    cipherText?: string;
     metadata?: Record<string, unknown>;
 }
 interface TransactionVerificationResponse {
@@ -57,6 +62,7 @@ interface TransactionVerificationResponse {
     requiresApproval: boolean;
     blockReasons: string[];
     processingTime: number;
+    cipherTextValidation?: ValidateCipherTextResponse;
 }
 interface TransactionRiskResult {
     score: number;
@@ -70,6 +76,7 @@ interface EventVerificationRequest {
     ipAddress: string;
     eventType: string;
     deviceFingerprint?: DeviceFingerprintRequest;
+    cipherText?: string;
     metadata?: Record<string, unknown>;
 }
 interface EventVerificationResponse {
@@ -77,6 +84,7 @@ interface EventVerificationResponse {
     geolocation: LocationVerification;
     blockReasons: string[];
     processingTime: number;
+    cipherTextValidation?: ValidateCipherTextResponse;
 }
 interface CurrencyRates {
     [currency: string]: number;
@@ -264,6 +272,11 @@ declare class ComplianceClient {
     verifyEvent(request: EventVerificationRequest, requestOptions?: RequestOptions): Promise<EventVerificationResponse>;
     private shouldUpdateProfile;
     private createProfileFromGeo;
+    /**
+     * Execute cipherText validation with graceful degradation.
+     * Returns undefined if cipherText is not provided or validation fails.
+     */
+    private executeCipherTextValidation;
     private calculateTransactionRisk;
     private checkJurisdictionLimits;
     private normalizeToUSD;

package/dist/compliance/index.js

@@ -224,7 +224,7 @@ function createConsoleLogger() {
 }
 
 // src/core/version.ts
-var SDK_VERSION = "1.5.2";
+var SDK_VERSION = "1.6.0";
 
 // src/shared/browser-utils.ts
 function generateUUID() {
@@ -1440,17 +1440,34 @@ var ComplianceClient = class {
     const startTime = Date.now();
     this.validateRegistrationRequest(request);
     let geoVerification = null;
+    let cipherTextResult;
     try {
       if (this.config.debug) {
         this.logger.debug("Starting registration verification", { customerId: request.customerId });
       }
-      geoVerification = await this.geoClient.verifyIP({
-        ip_address: request.ipAddress,
-        user_id: request.customerId,
-        event_type: "registration",
-        device_fingerprint: request.deviceFingerprint
-      }, requestOptions);
-      const blockReasons = this.evaluateRegistrationBlock(geoVerification);
+      const customerData = request.cipherText ? {
+        full_name: request.fullName,
+        email: request.emailAddress,
+        phone: request.phoneNumber,
+        date_of_birth: request.dateOfBirth
+      } : void 0;
+      [cipherTextResult, geoVerification] = await Promise.all([
+        this.executeCipherTextValidation(
+          request.cipherText,
+          request.customerId,
+          "registration",
+          request.ipAddress,
+          customerData,
+          requestOptions
+        ),
+        this.geoClient.verifyIP({
+          ip_address: request.ipAddress,
+          user_id: request.customerId,
+          event_type: "registration",
+          device_fingerprint: request.deviceFingerprint
+        }, requestOptions)
+      ]);
+      const blockReasons = this.evaluateRegistrationBlock(geoVerification, cipherTextResult);
       if (blockReasons.length > 0) {
         if (this.config.debug) {
           this.logger.debug("Registration blocked at geo stage", { blockReasons });
@@ -1462,7 +1479,8 @@ var ComplianceClient = class {
           requiresKYC: false,
           requiresEDD: false,
           blockReasons,
-          processingTime: Date.now() - startTime
+          processingTime: Date.now() - startTime,
+          cipherTextValidation: cipherTextResult
         };
       }
       const profile = await this.riskClient.createProfile({
@@ -1497,7 +1515,8 @@ var ComplianceClient = class {
         requiresKYC,
         requiresEDD,
         blockReasons: [],
-        processingTime: Date.now() - startTime
+        processingTime: Date.now() - startTime,
+        cipherTextValidation: cipherTextResult
       };
     } catch (error) {
       if (this.config.debug) {
@@ -1525,7 +1544,7 @@ var ComplianceClient = class {
    * @param geoVerification - Geolocation verification result
    * @returns Array of block reasons (empty if allowed)
    */
-  evaluateRegistrationBlock(geoVerification) {
+  evaluateRegistrationBlock(geoVerification, cipherTextResult) {
     const blockReasons = [];
     if (geoVerification.is_blocked) {
       blockReasons.push(...geoVerification.risk_reasons);
@@ -1559,6 +1578,20 @@ var ComplianceClient = class {
         blockReasons.push("critical_risk_level");
       }
     }
+    if (cipherTextResult) {
+      if (!cipherTextResult.valid) {
+        blockReasons.push("ciphertext_validation_failed");
+      }
+      if (cipherTextResult.risk?.is_blocked) {
+        blockReasons.push(...cipherTextResult.risk.block_reasons || []);
+      }
+      if (cipherTextResult.risk?.location_mismatch) {
+        blockReasons.push("gps_ip_location_mismatch");
+      }
+    }
+    if (geoVerification.gps_required && !cipherTextResult) {
+      blockReasons.push("gps_verification_required");
+    }
     return [...new Set(blockReasons)];
   }
   /**
@@ -1689,7 +1722,15 @@ var ComplianceClient = class {
       if (this.config.debug) {
         this.logger.debug("Starting login verification", { customerId: request.customerId });
       }
-      const [geoVerification, profileResult] = await Promise.all([
+      const [cipherTextResult, geoVerification, profileResult] = await Promise.all([
+        this.executeCipherTextValidation(
+          request.cipherText,
+          request.customerId,
+          "login",
+          request.ipAddress,
+          void 0,
+          requestOptions
+        ),
         this.geoClient.verifyIP({
           ip_address: request.ipAddress,
           user_id: request.customerId,
@@ -1698,10 +1739,23 @@ var ComplianceClient = class {
         }, requestOptions),
         this.riskClient.getProfile(request.customerId, requestOptions).catch(() => null)
       ]);
+      const loginBlockReasons = this.getBlockReasons(geoVerification, profileResult || {}, cipherTextResult);
+      const isBlocked = !geoVerification.is_compliant || geoVerification.is_blocked || !!cipherTextResult?.risk?.is_blocked || cipherTextResult?.valid === false || geoVerification.gps_required && !cipherTextResult;
+      if (isBlocked && !profileResult) {
+        return {
+          allowed: false,
+          geolocation: geoVerification,
+          profile: null,
+          requiresStepUp: false,
+          blockReasons: loginBlockReasons,
+          processingTime: Date.now() - startTime,
+          cipherTextValidation: cipherTextResult
+        };
+      }
       let profile;
       if (profileResult) {
         profile = profileResult;
-        if (this.shouldUpdateProfile(profile, geoVerification.location.city)) {
+        if (!isBlocked && this.shouldUpdateProfile(profile, geoVerification.location.city)) {
           profile = await this.riskClient.updateProfile(profile.id, {
             last_recorded_activity: (/* @__PURE__ */ new Date()).toISOString(),
             location: `${geoVerification.location.city}, ${geoVerification.location.country}`,
@@ -1714,15 +1768,15 @@ var ComplianceClient = class {
         }
         profile = await this.createProfileFromGeo(request.customerId, geoVerification);
       }
-      const isAllowed = geoVerification.is_compliant && !geoVerification.is_blocked && profile.customer_status !== "suspended";
-      const requiresStepUp = geoVerification.risk_level === "high" || geoVerification.risk_level === "critical";
+      const requiresStepUp = geoVerification.risk_level === "high" || geoVerification.risk_level === "critical" || cipherTextResult?.risk?.location_mismatch === true;
       return {
-        allowed: isAllowed,
+        allowed: !isBlocked && profile.customer_status !== "suspended",
         geolocation: geoVerification,
         profile,
         requiresStepUp,
-        blockReasons: this.getBlockReasons(geoVerification, profile),
-        processingTime: Date.now() - startTime
+        blockReasons: isBlocked || profile.customer_status === "suspended" ? this.getBlockReasons(geoVerification, profile, cipherTextResult) : [],
+        processingTime: Date.now() - startTime,
+        cipherTextValidation: cipherTextResult
       };
     } catch (error) {
       throw new ComplianceError("Login verification failed", error instanceof Error ? error.message : void 0);
@@ -1769,27 +1823,55 @@ var ComplianceClient = class {
           currency: request.currency
         });
       }
-      const [geoVerification, profile] = await Promise.all([
+      const [cipherTextResult, geoVerification, profileResult] = await Promise.all([
+        this.executeCipherTextValidation(
+          request.cipherText,
+          request.customerId,
+          "transaction",
+          request.ipAddress,
+          void 0,
+          requestOptions
+        ),
         this.geoClient.verifyIP({
           ip_address: request.ipAddress,
           user_id: request.customerId,
           event_type: "transaction",
           device_fingerprint: request.deviceFingerprint
         }, requestOptions),
-        this.riskClient.getProfile(request.customerId, requestOptions)
+        this.riskClient.getProfile(request.customerId, requestOptions).catch(() => null)
       ]);
+      const geoBlocked = !geoVerification.is_compliant || geoVerification.is_blocked || !!cipherTextResult?.risk?.is_blocked || cipherTextResult?.valid === false || geoVerification.gps_required && !cipherTextResult;
+      if (geoBlocked && !profileResult) {
+        return {
+          allowed: false,
+          geolocation: geoVerification,
+          profile: null,
+          transactionRisk: { score: 0, level: "low", factors: [], allowed: false, requiresManualReview: false },
+          requiresApproval: false,
+          blockReasons: this.getTransactionBlockReasons(
+            geoVerification,
+            { score: 0, level: "low", factors: [], allowed: false, requiresManualReview: false },
+            true,
+            cipherTextResult
+          ),
+          processingTime: Date.now() - startTime,
+          cipherTextValidation: cipherTextResult
+        };
+      }
+      const profile = profileResult;
       const transactionRisk = this.calculateTransactionRisk(
         request.amount,
         request.currency,
         geoVerification,
-        profile
+        profile,
+        cipherTextResult
       );
       const jurisdictionAllowed = this.checkJurisdictionLimits(
         request.amount,
         request.currency,
         geoVerification.jurisdiction
       );
-      const isAllowed = geoVerification.is_compliant && !geoVerification.is_blocked && jurisdictionAllowed && transactionRisk.allowed;
+      const isAllowed = !geoBlocked && jurisdictionAllowed && transactionRisk.allowed && profile.customer_status !== "suspended";
       return {
         allowed: isAllowed,
         geolocation: geoVerification,
@@ -1799,9 +1881,11 @@ var ComplianceClient = class {
         blockReasons: this.getTransactionBlockReasons(
           geoVerification,
           transactionRisk,
-          jurisdictionAllowed
+          jurisdictionAllowed,
+          cipherTextResult
         ),
-        processingTime: Date.now() - startTime
+        processingTime: Date.now() - startTime,
+        cipherTextValidation: cipherTextResult
       };
     } catch (error) {
       throw new ComplianceError("Transaction verification failed", error instanceof Error ? error.message : void 0);
@@ -1816,12 +1900,22 @@ var ComplianceClient = class {
   async verifyEvent(request, requestOptions) {
     const startTime = Date.now();
     this.validateEventRequest(request);
-    const geoVerification = await this.geoClient.verifyIP({
-      ip_address: request.ipAddress,
-      user_id: request.customerId,
-      event_type: request.eventType,
-      device_fingerprint: request.deviceFingerprint
-    }, requestOptions);
+    const [cipherTextResult, geoVerification] = await Promise.all([
+      this.executeCipherTextValidation(
+        request.cipherText,
+        request.customerId,
+        request.eventType,
+        request.ipAddress,
+        void 0,
+        requestOptions
+      ),
+      this.geoClient.verifyIP({
+        ip_address: request.ipAddress,
+        user_id: request.customerId,
+        event_type: request.eventType,
+        device_fingerprint: request.deviceFingerprint
+      }, requestOptions)
+    ]);
     if (this.config.autoCreateProfiles) {
       try {
         const profile = await this.riskClient.getProfile(request.customerId, requestOptions);
@@ -1834,11 +1928,26 @@ var ComplianceClient = class {
         }
       }
     }
+    const cipherTextBlocked = cipherTextResult ? !cipherTextResult.valid || cipherTextResult.risk?.is_blocked === true : false;
+    const blockReasons = [...geoVerification.risk_reasons];
+    if (cipherTextResult) {
+      if (!cipherTextResult.valid) {
+        blockReasons.push("ciphertext_validation_failed");
+      }
+      if (cipherTextResult.risk?.is_blocked) {
+        blockReasons.push(...cipherTextResult.risk.block_reasons || []);
+      }
+    }
+    const gpsBlocked = geoVerification.gps_required && !cipherTextResult;
+    if (gpsBlocked) {
+      blockReasons.push("gps_verification_required");
+    }
     return {
-      allowed: geoVerification.is_compliant && !geoVerification.is_blocked,
+      allowed: geoVerification.is_compliant && !geoVerification.is_blocked && !cipherTextBlocked && !gpsBlocked,
       geolocation: geoVerification,
-      blockReasons: geoVerification.risk_reasons,
-      processingTime: Date.now() - startTime
+      blockReasons: [...new Set(blockReasons)],
+      processingTime: Date.now() - startTime,
+      cipherTextValidation: cipherTextResult
     };
   }
   // ============================================================================
@@ -1867,7 +1976,29 @@ var ComplianceClient = class {
       kyc_status: "pending"
     });
   }
-  calculateTransactionRisk(amount, currency, geoVerification, profile) {
+  /**
+   * Execute cipherText validation with graceful degradation.
+   * Returns undefined if cipherText is not provided or validation fails.
+   */
+  async executeCipherTextValidation(cipherText, userId, eventType, ipAddress, customerData, requestOptions) {
+    if (!cipherText) return void 0;
+    try {
+      return await this.geoClient.validateCipherText(
+        cipherText,
+        userId,
+        eventType,
+        ipAddress,
+        customerData,
+        requestOptions
+      );
+    } catch (err) {
+      this.logger.warn("CipherText validation failed, proceeding with IP-only", {
+        error: err instanceof Error ? err.message : "Unknown error"
+      });
+      return void 0;
+    }
+  }
+  calculateTransactionRisk(amount, currency, geoVerification, profile, cipherTextResult) {
     if (!this._currencyRatesCustomized && !this._currencyRatesWarned) {
       this._currencyRatesWarned = true;
       this.logger.warn(
@@ -1900,6 +2031,15 @@ var ComplianceClient = class {
       riskScore += 50;
       factors.push("account_suspended");
     }
+    if (cipherTextResult) {
+      if (cipherTextResult.risk?.location_mismatch) {
+        riskScore += 20;
+        factors.push("gps_ip_location_mismatch");
+      }
+      if (cipherTextResult.risk?.score) {
+        riskScore += cipherTextResult.risk.score * 0.2;
+      }
+    }
     return {
       score: Math.min(riskScore, 100),
       level: this.getRiskLevel(riskScore),
@@ -1925,7 +2065,7 @@ var ComplianceClient = class {
     if (score >= 40) return "medium";
     return "low";
   }
-  getBlockReasons(geoVerification, profile) {
+  getBlockReasons(geoVerification, profile, cipherTextResult) {
     const reasons = [];
     if (geoVerification.is_blocked) {
       reasons.push(...geoVerification.risk_reasons);
@@ -1936,9 +2076,20 @@ var ComplianceClient = class {
     if (profile.has_sanctions) {
       reasons.push("sanctions_match");
     }
-    return reasons;
+    if (cipherTextResult) {
+      if (!cipherTextResult.valid) {
+        reasons.push("ciphertext_validation_failed");
+      }
+      if (cipherTextResult.risk?.is_blocked) {
+        reasons.push(...cipherTextResult.risk.block_reasons || []);
+      }
+    }
+    if (geoVerification.gps_required && !cipherTextResult) {
+      reasons.push("gps_verification_required");
+    }
+    return [...new Set(reasons)];
   }
-  getTransactionBlockReasons(geoVerification, transactionRisk, jurisdictionAllowed) {
+  getTransactionBlockReasons(geoVerification, transactionRisk, jurisdictionAllowed, cipherTextResult) {
     const reasons = [];
     if (!geoVerification.is_compliant) {
       reasons.push("non_compliant_jurisdiction");
@@ -1949,7 +2100,18 @@ var ComplianceClient = class {
     if (!transactionRisk.allowed) {
       reasons.push(...transactionRisk.factors);
     }
-    return reasons;
+    if (cipherTextResult) {
+      if (!cipherTextResult.valid) {
+        reasons.push("ciphertext_validation_failed");
+      }
+      if (cipherTextResult.risk?.is_blocked) {
+        reasons.push(...cipherTextResult.risk.block_reasons || []);
+      }
+    }
+    if (geoVerification.gps_required && !cipherTextResult) {
+      reasons.push("gps_verification_required");
+    }
+    return [...new Set(reasons)];
   }
   // ============================================================================
   // Location Request Methods