@spritz-finance/api-client 0.4.14 → 0.4.16

package/README.md

@@ -247,6 +247,9 @@ const verificationStatus = userData.verificationStatus
 const verificationUrl = userData.verificationUrl
 const verifiedCountry = userData.verifiedCountry
 const canRetryVerification = userData.canRetryVerification
+
+// Access verification metadata for failed verifications
+const verificationMetadata = userData.verificationMetadata
 ```
 
 #### Method 2: Verification Token (Advanced Integration)
@@ -272,6 +275,44 @@ The verification token method is ideal when you want to:
 
 See the [Plaid Link documentation](https://plaid.com/docs/link/) for detailed integration instructions with the verification token.
 
+### Verification Metadata (Failed Verifications)
+
+When a user's verification fails, Spritz now provides additional metadata to help understand the failure reason and provide better user experience. This metadata is particularly useful for handling duplicate identity scenarios.
+
+#### Understanding Verification Metadata
+
+The verification metadata is available when a verification has failed and includes:
+
+- **`failureReason`**: The specific reason why the verification failed (e.g., `DuplicateIdentity`)
+- **`details.matchedEmail`**: For duplicate identity failures, shows the email of the matched user (only if created through the same integration)
+
+#### Duplicate Identity Handling
+
+When a verification fails due to `DuplicateIdentity`, the system detects that the user has already been verified under a different account. The `matchedEmail` field helps determine:
+
+- **If `matchedEmail` is populated**: The duplicate user was created through your integration
+- **If `matchedEmail` is `null`**: The duplicate user was created through a different integration (e.g., the main Spritz app)
+
+This allows you to provide appropriate guidance to your users:
+
+```typescript
+const userData = await client.user.getCurrentUser()
+
+if (userData.verificationMetadata?.failureReason === 'DuplicateIdentity') {
+  const matchedEmail = userData.verificationMetadata.details.matchedEmail
+  
+  if (matchedEmail) {
+    // User exists within your integration
+    console.log(`This identity is already verified with account: ${matchedEmail}`)
+    // Guide user to use their existing account
+  } else {
+    // User exists in Spritz but not in your integration
+    console.log('This identity is already verified with another Spritz account')
+    // Inform user they need to use their original Spritz account
+  }
+}
+```
+
 ## Payment Flow
 
 ### Basic payment flow
@@ -1090,6 +1131,26 @@ Upon receiving a webhook, your server will get a payload with the following stru
 }
 ```
 
+### Managing webhooks
+
+#### List all webhooks
+
+To retrieve all webhooks configured for your integration:
+
+```typescript
+const webhooks = await client.webhook.list()
+// Returns an array of webhook configurations
+```
+
+#### Delete a webhook
+
+To delete a specific webhook by its ID:
+
+```typescript
+const deletedWebhook = await client.webhook.delete('webhook-id-here')
+// Returns the deleted webhook object
+```
+
 ### Webhook security and signing
 
 Each webhook request is signed using an HMAC SHA256 signature, based on the exact JSON payload sent in the body. This signature is included in the Signature HTTP header of the request.