Migrate users

Export your user data and ensure you have wallet addresses for each user.

Required Data

• walletAddress (required) - The unique blockchain wallet address

Optional Metadata

• externalIdentifier - Your internal user ID (highly recommended)
• displayName - User's display name
• emailAddress - User's email address
• discordUser - Discord username
• discordUserId - Discord user ID
• twitterUser - Twitter/X username
• twitterUserId - Twitter/X user ID
• telegramUsername - Telegram username
• telegramUserId - Telegram user ID
• logoUrl - URL to user's avatar/profile picture

Create a script to process your users in batches. Here's a complete example:

import SnagSolutions from '@snagsolutions/sdk'

const client = new SnagSolutions({
  apiKey: process.env.SNAG_API_KEY,
})

interface YourUser {
  id: string
  walletAddress: string
  name: string
  email: string
  // ... other fields
}

async function migrateUsers(users: YourUser[]) {
  const results = {
    successful: 0,
    failed: 0,
    errors: [] as Array<{ userId: string; error: string }>,
  }

  for (const user of users) {
    try {
      await client.users.createMetadata({
        walletAddress: user.walletAddress,
        externalIdentifier: user.id,
        displayName: user.name,
        emailAddress: user.email,
      })
      
      results.successful++
      console.log(`✓ Migrated user ${user.id}`)
    } catch (error) {
      results.failed++
      results.errors.push({
        userId: user.id,
        error: error.message,
      })
      console.error(`✗ Failed to migrate user ${user.id}:`, error.message)
    }
  }

  return results
}

// Usage
const users = await fetchYourUsers()
const results = await migrateUsers(users)
console.log(`Migration complete: ${results.successful} successful, ${results.failed} failed`)

For large migrations, process users in batches to avoid rate limits and make the process more manageable:

async function migrateInBatches(
  users: YourUser[],
  batchSize: number = 100,
  delayMs: number = 1000
) {
  const totalBatches = Math.ceil(users.length / batchSize)
  
  for (let i = 0; i < totalBatches; i++) {
    const start = i * batchSize
    const end = start + batchSize
    const batch = users.slice(start, end)
    
    console.log(`Processing batch ${i + 1}/${totalBatches}`)
    await migrateUsers(batch)
    
    // Add delay between batches to respect rate limits
    if (i < totalBatches - 1) {
      await new Promise(resolve => setTimeout(resolve, delayMs))
    }
  }
}

After migration, verify that all users were created successfully:

async function verifyMigration(externalIds: string[]) {
  const notFound: string[] = []
  
  for (const externalId of externalIds) {
    try {
      // Query by external identifier
      const users = await client.users.list({
        externalIdentifier: externalId,
      })
      
      if (users.length === 0) {
        notFound.push(externalId)
      }
    } catch (error) {
      console.error(`Error checking user ${externalId}:`, error)
      notFound.push(externalId)
    }
  }
  
  if (notFound.length > 0) {
    console.log(`Missing users: ${notFound.length}`)
    console.log(notFound)
  } else {
    console.log('✓ All users verified successfully')
  }
  
  return notFound
}

Review and retry failed migrations:

async function retryFailed(errors: Array<{ userId: string; error: string }>) {
  console.log(`Retrying ${errors.length} failed migrations...`)
  
  const usersToRetry = await fetchUsersById(errors.map(e => e.userId))
  const results = await migrateUsers(usersToRetry)
  
  return results
}

Common errors and solutions:

• Invalid wallet address - Verify the wallet address format
• Duplicate user - User already exists, use update instead
• Rate limit - Increase delay between batches
• Authentication error - Check your API key