@beclab/olaresid 0.1.1 → 0.1.3

package/examples/tag-management.ts

@@ -0,0 +1,534 @@
+/**
+ * Tag Management Example
+ *
+ * This example demonstrates the complete Tag system workflow:
+ * 1. Defining Tag types (simple types, arrays, tuples)
+ * 2. Setting and getting Tag values
+ * 3. Array operations (push, pop, update)
+ * 4. Cross-domain Tag operations
+ *
+ * Prerequisites:
+ * - Set PRIVATE_KEY_OR_MNEMONIC environment variable
+ * - You must own the domain you're operating on
+ *
+ * Run:
+ * export PRIVATE_KEY_OR_MNEMONIC="your private key or mnemonic"
+ * npx ts-node examples/tag-management.ts
+ */
+
+import OlaresID, { TagTypeBuilder } from '../src/index';
+
+// Helper function to wait for blockchain indexing
+async function waitForIndexing(seconds: number = 3) {
+	console.log(`⏳ Waiting ${seconds} seconds for blockchain indexing...`);
+	await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
+
+async function main() {
+	// Initialize OlaresID
+	const olaresId = OlaresID.createTestnet();
+
+	// Get private key or mnemonic from environment
+	const privateKeyOrMnemonic = process.env.PRIVATE_KEY_OR_MNEMONIC;
+	if (!privateKeyOrMnemonic) {
+		console.error(
+			'❌ Error: PRIVATE_KEY_OR_MNEMONIC environment variable not set'
+		);
+		console.log(
+			'Usage: export PRIVATE_KEY_OR_MNEMONIC="your private key or mnemonic"'
+		);
+		process.exit(1);
+	}
+
+	await olaresId.setSigner(privateKeyOrMnemonic);
+	console.log('✅ Signer set successfully\n');
+
+	// Replace with your domain
+	const domainName = process.argv[2];
+	if (!domainName) {
+		console.error('❌ Error: Please provide a domain name');
+		console.log(
+			'Usage: npx ts-node examples/tag-management.ts <domain-name>'
+		);
+		process.exit(1);
+	}
+
+	const domain = olaresId.domain(domainName);
+	const signerAddress = await olaresId.getSigner().getAddress();
+	console.log(`🏷️  Managing Tags for domain: ${domainName}`);
+	console.log(`👤 Signer: ${signerAddress}\n`);
+
+	// ========================================
+	// Part 1: Define Simple Tag Types
+	// ========================================
+	console.log('='.repeat(60));
+	console.log('Part 1: Defining Simple Tag Types');
+	console.log('='.repeat(60));
+
+	// Define "email" tag
+	console.log('📝 Defining "email" tag (type: string)...');
+	try {
+		await domain.defineSimpleTag('email', 'string');
+		console.log('✅ "email" tag defined');
+		await waitForIndexing(3);
+	} catch (error: any) {
+		if (
+			error.message?.includes('RedefinedTag') ||
+			error.message?.includes('already been defined')
+		) {
+			console.log('⚠️  "email" already defined, skipping...');
+		} else {
+			console.error(`❌ Error: ${error.message}`);
+		}
+	}
+
+	// Define "age" tag
+	console.log('📝 Defining "age" tag (type: uint8)...');
+	try {
+		await domain.defineSimpleTag('age', 'uint8');
+		console.log('✅ "age" tag defined');
+		await waitForIndexing(3);
+	} catch (error: any) {
+		if (
+			error.message?.includes('RedefinedTag') ||
+			error.message?.includes('already been defined')
+		) {
+			console.log('⚠️  "age" already defined, skipping...');
+		} else {
+			console.error(`❌ Error: ${error.message}`);
+		}
+	}
+
+	// Define "verified" tag
+	console.log('📝 Defining "verified" tag (type: bool)...');
+	try {
+		await domain.defineSimpleTag('verified', 'bool');
+		console.log('✅ "verified" tag defined');
+		await waitForIndexing(3);
+	} catch (error: any) {
+		if (
+			error.message?.includes('RedefinedTag') ||
+			error.message?.includes('already been defined')
+		) {
+			console.log('⚠️  "verified" already defined, skipping...');
+		} else {
+			console.error(`❌ Error: ${error.message}`);
+		}
+	}
+
+	// Define "wallets" tag
+	console.log('📝 Defining "wallets" tag (type: address[])...');
+	try {
+		await domain.defineSimpleTag('wallets', 'address[]');
+		console.log('✅ "wallets" tag defined\n');
+		await waitForIndexing(3);
+	} catch (error: any) {
+		if (
+			error.message?.includes('RedefinedTag') ||
+			error.message?.includes('already been defined')
+		) {
+			console.log('⚠️  "wallets" already defined, skipping...\n');
+		} else {
+			console.error(`❌ Error: ${error.message}\n`);
+		}
+	}
+
+	// ========================================
+	// Part 2: Define Complex Tag Types
+	// ========================================
+	console.log('='.repeat(60));
+	console.log('Part 2: Defining Complex Tag Types (using TagTypeBuilder)');
+	console.log('='.repeat(60));
+
+	const tagCtx = domain.tag();
+
+	// Define "userInfo" tag
+	console.log('📝 Defining "userInfo" tag (complex tuple)...');
+	try {
+		const userInfoType = TagTypeBuilder.tuple({
+			name: TagTypeBuilder.string(),
+			age: TagTypeBuilder.uint8(),
+			wallets: TagTypeBuilder.addressArray(),
+			verified: TagTypeBuilder.bool()
+		});
+		console.log(`   Type bytes: 0x${userInfoType.getTypeBytes()}`);
+		console.log(
+			`   Field names: ${JSON.stringify(userInfoType.getFieldNames())}`
+		);
+
+		await tagCtx.defineTag('userInfo', userInfoType);
+		console.log('✅ "userInfo" tag defined\n');
+		await waitForIndexing(3);
+	} catch (error: any) {
+		if (
+			error.message?.includes('RedefinedTag') ||
+			error.message?.includes('already been defined')
+		) {
+			console.log('⚠️  "userInfo" already defined, skipping...\n');
+		} else {
+			console.error(`❌ Error: ${error.message}\n`);
+		}
+	}
+
+	// Define "socialLinks" tag
+	console.log('📝 Defining "socialLinks" tag (string array)...');
+	try {
+		const socialLinksType = TagTypeBuilder.stringArray();
+		await tagCtx.defineTag('socialLinks', socialLinksType);
+		console.log('✅ "socialLinks" tag defined\n');
+		await waitForIndexing(3);
+	} catch (error: any) {
+		if (
+			error.message?.includes('RedefinedTag') ||
+			error.message?.includes('already been defined')
+		) {
+			console.log('⚠️  "socialLinks" already defined, skipping...\n');
+		} else {
+			console.error(`❌ Error: ${error.message}\n`);
+		}
+	}
+
+	// ========================================
+	// Part 3: Set Taggers (IMPORTANT!)
+	// ========================================
+	console.log('='.repeat(60));
+	console.log('Part 3: Setting Taggers (Required Before Setting Values)');
+	console.log('='.repeat(60));
+
+	try {
+		console.log('📝 Setting taggers for all defined tags...');
+
+		// Set tagger for simple tags
+		await domain.setTagger('email', signerAddress);
+		console.log('   ✅ Set tagger for "email"');
+		await waitForIndexing(2);
+
+		await domain.setTagger('age', signerAddress);
+		console.log('   ✅ Set tagger for "age"');
+		await waitForIndexing(2);
+
+		await domain.setTagger('verified', signerAddress);
+		console.log('   ✅ Set tagger for "verified"');
+		await waitForIndexing(2);
+
+		await domain.setTagger('wallets', signerAddress);
+		console.log('   ✅ Set tagger for "wallets"');
+		await waitForIndexing(2);
+
+		// Set tagger for complex tags
+		await domain.setTagger('userInfo', signerAddress);
+		console.log('   ✅ Set tagger for "userInfo"');
+		await waitForIndexing(2);
+
+		await domain.setTagger('socialLinks', signerAddress);
+		console.log('   ✅ Set tagger for "socialLinks"\n');
+		await waitForIndexing(2);
+	} catch (error: any) {
+		console.error(`❌ Error setting taggers: ${error.message}\n`);
+	}
+
+	// ========================================
+	// Part 4: Set and Get Tag Values
+	// ========================================
+	console.log('='.repeat(60));
+	console.log('Part 4: Setting and Getting Tag Values');
+	console.log('='.repeat(60));
+
+	try {
+		// Set simple tag values
+		console.log('📝 Setting "email" tag...');
+		await domain.setTag('email', 'alice@example.com');
+		console.log('✅ "email" tag set');
+		await waitForIndexing(3);
+
+		console.log('📝 Setting "age" tag...');
+		await domain.setTag('age', 30);
+		console.log('✅ "age" tag set');
+		await waitForIndexing(3);
+
+		console.log('📝 Setting "verified" tag...');
+		await domain.setTag('verified', true);
+		console.log('✅ "verified" tag set\n');
+		await waitForIndexing(3);
+
+		// Get tag values
+		console.log('📖 Reading tag values...');
+		const email = await domain.getTag('email');
+		const age = await domain.getTag('age');
+		const verified = await domain.getTag('verified');
+
+		console.log(`   email: ${email}`);
+		console.log(`   age: ${age}`);
+		console.log(`   verified: ${verified}\n`);
+	} catch (error: any) {
+		console.error(`❌ Error with simple tags: ${error.message}\n`);
+	}
+
+	// ========================================
+	// Part 5: Array Operations
+	// ========================================
+	console.log('='.repeat(60));
+	console.log('Part 5: Array Operations');
+	console.log('='.repeat(60));
+
+	try {
+		const tagCtx = domain.tag();
+
+		// Initialize array with setTag first (required before push operations)
+		console.log('📝 Initializing "socialLinks" array...');
+		await tagCtx.setTag(domainName, 'socialLinks', [
+			'https://twitter.com/alice',
+			'https://github.com/alice',
+			'https://linkedin.com/in/alice'
+		]);
+		console.log('✅ Social links initialized with 3 items\n');
+		await waitForIndexing(3);
+
+		// Get array length
+		const length = await tagCtx.getArrayLength(domainName, 'socialLinks');
+		console.log(`📊 Social links count: ${length}`);
+
+		// Get all array elements
+		console.log('📖 Reading all social links:');
+		for (let i = 0; i < length; i++) {
+			const link = await tagCtx.getElement(domainName, 'socialLinks', [
+				i
+			]);
+			console.log(`   [${i}] ${link}`);
+		}
+		console.log();
+
+		// Test push operation (add a new element)
+		console.log('📝 Adding a new social link (push)...');
+		try {
+			await tagCtx.pushElement(
+				domainName,
+				'socialLinks',
+				'https://discord.gg/alice'
+			);
+			console.log('✅ Added Discord link');
+			await waitForIndexing(3);
+
+			const afterPush = await tagCtx.getArrayLength(
+				domainName,
+				'socialLinks'
+			);
+			console.log(`📊 Social links count after push: ${afterPush}\n`);
+			const link = await tagCtx.getElement(domainName, 'socialLinks', [
+				afterPush - 1
+			]);
+			console.log(`   [${afterPush - 1}] ${link}`);
+		} catch (error: any) {
+			console.log(`⚠️  Push operation failed: ${error.message}\n`);
+		}
+
+		// Update an element
+		console.log('📝 Updating first social link...');
+		await tagCtx.updateElement(
+			domainName,
+			'socialLinks',
+			[0],
+			'https://x.com/alice'
+		);
+		console.log('✅ First link updated\n');
+		await waitForIndexing(3);
+		const link = await tagCtx.getElement(domainName, 'socialLinks', [0]);
+		console.log(`   [0] ${link}`);
+
+		// Pop an element (remove last)
+		console.log('📝 Removing last social link (pop)...');
+		try {
+			await tagCtx.popElement(domainName, 'socialLinks');
+			console.log('✅ Last link removed');
+			await waitForIndexing(3);
+
+			const afterPop = await tagCtx.getArrayLength(
+				domainName,
+				'socialLinks'
+			);
+			console.log(`📊 Social links count after pop: ${afterPop}\n`);
+		} catch (error: any) {
+			console.log(`⚠️  Pop operation failed: ${error.message}\n`);
+		}
+
+		// Verify final state
+		const finalLength = await tagCtx.getArrayLength(
+			domainName,
+			'socialLinks'
+		);
+		console.log(`📊 Final social links count: ${finalLength}`);
+		console.log('📖 Current social links:');
+		for (let i = 0; i < finalLength; i++) {
+			const link = await tagCtx.getElement(domainName, 'socialLinks', [
+				i
+			]);
+			console.log(`   [${i}] ${link}`);
+		}
+		console.log();
+	} catch (error: any) {
+		console.error(`❌ Error with array operations: ${error.message}\n`);
+	}
+
+	// ========================================
+	// Part 6: Complex Tuple Values
+	// ========================================
+	console.log('='.repeat(60));
+	console.log('Part 6: Complex Tuple Values');
+	console.log('='.repeat(60));
+
+	try {
+		const tagCtx = domain.tag();
+
+		// Set tuple value using object notation (automatic conversion!)
+		console.log('📝 Setting "userInfo" tuple...');
+		console.log('   Using object notation (no fieldNames needed)');
+		await tagCtx.setTag(domainName, 'userInfo', {
+			name: 'Alice Johnson',
+			age: 30,
+			wallets: [
+				'0x1111111111111111111111111111111111111111',
+				'0x2222222222222222222222222222222222222222'
+			],
+			verified: true
+		});
+		console.log('✅ "userInfo" tuple set');
+		await waitForIndexing(3);
+
+		// Get tuple value
+		console.log('📖 Reading "userInfo" tuple...');
+		const userInfo = await tagCtx.getTag(domainName, 'userInfo');
+		console.log('   User Info (raw):');
+		console.log(
+			`     ${JSON.stringify(userInfo, (_, v) =>
+				typeof v === 'bigint' ? v.toString() : v
+			)}`
+		);
+		console.log(
+			`   Type: ${typeof userInfo}, IsArray: ${Array.isArray(userInfo)}`
+		);
+
+		// The returned data is directly the tuple array: [field1, field2, field3, field4]
+		// No need to access [0], it's already the tuple data
+		console.log('   User Info (parsed):');
+		console.log(`     name: ${userInfo[0]}`);
+		console.log(`     age: ${userInfo[1]}`);
+		console.log(`     wallets: ${JSON.stringify(userInfo[2])}`);
+		console.log(`     verified: ${userInfo[3]}\n`);
+
+		// Update a specific field in the tuple
+		console.log('🔄 Updating "age" field in "userInfo" tuple...');
+		console.log(`   Current age: ${userInfo[1]}`);
+
+		// To update a single field, we need to read the entire tuple, modify it, and set it back
+		const updatedUserInfo = {
+			name: userInfo[0], // Keep existing name
+			age: 31, // Update age
+			wallets: userInfo[2], // Keep existing wallets
+			verified: userInfo[3] // Keep existing verified status
+		};
+
+		await tagCtx.setTag(domainName, 'userInfo', updatedUserInfo);
+		console.log('✅ "age" field updated to 31');
+		await waitForIndexing(3);
+
+		// Verify the update
+		const updatedInfo = await tagCtx.getTag(domainName, 'userInfo');
+		console.log('📖 Updated User Info:');
+		console.log(
+			`     ${JSON.stringify(updatedInfo, (_, v) =>
+				typeof v === 'bigint' ? v.toString() : v
+			)}\n`
+		);
+	} catch (error: any) {
+		console.error(`❌ Error with tuple values: ${error.message}\n`);
+	}
+
+	// ========================================
+	// Part 7: Get All Tags
+	// ========================================
+	console.log('='.repeat(60));
+	console.log('Part 7: Get All Tags');
+	console.log('='.repeat(60));
+
+	try {
+		console.log('📖 Getting all tags for domain...');
+		const allTags = await domain.getAllTags();
+		console.log(`✅ Found ${allTags.length} tags:\n`);
+
+		for (const tag of allTags) {
+			console.log(`   Tag: "${tag.name}"`);
+			if (typeof tag.value === 'object' && tag.value !== null) {
+				console.log(
+					`     Value: ${JSON.stringify(tag.value, (_, v) =>
+						typeof v === 'bigint' ? v.toString() : v
+					)}`
+				);
+			} else {
+				console.log(`     Value: ${tag.value}`);
+			}
+		}
+		console.log();
+
+		console.log('📖 Getting all defined tag types...');
+		const definedTags = await domain.getDefinedTags();
+		console.log(`✅ Found ${definedTags.length} defined tag types:`);
+		for (const tagName of definedTags) {
+			console.log(`   - ${tagName}`);
+		}
+		console.log();
+	} catch (error: any) {
+		console.error(`❌ Error getting all tags: ${error.message}\n`);
+	}
+
+	// ========================================
+	// Part 8: Remove Tags
+	// ========================================
+	console.log('='.repeat(60));
+	console.log('Part 8: Remove Tags (Cleanup)');
+	console.log('='.repeat(60));
+
+	console.log('📝 Attempting to remove "verified" tag value...');
+	try {
+		// Note: removeTag() removes the tag VALUE from the storage
+		// The tag DEFINITION (type) remains and can be reused
+		// TagInvalidOp error occurs if the tag has no value to remove
+		await domain.removeTag('verified');
+		console.log('✅ "verified" tag value removed');
+		await waitForIndexing(3);
+
+		// Verify removal
+		const verified = await domain.getTag('verified');
+		console.log(`   Verification: verified = ${verified} (should be null)`);
+
+		// Check if tag definition still exists
+		const definedTags = await domain.getDefinedTags();
+		const stillDefined = definedTags.includes('verified');
+		console.log(
+			`   Tag definition still exists: ${stillDefined} (should be true)`
+		);
+		console.log('   💡 You can set a new value for this tag later\n');
+	} catch (error: any) {
+		if (
+			error.message?.includes('TagInvalidOp') ||
+			error.message?.includes('Invalid tag operation')
+		) {
+			console.log('⚠️  Tag removal failed: Tag has no value to remove');
+			console.log('   This happens when:');
+			console.log('   - The tag was never set');
+			console.log('   - The tag was already removed');
+			console.log('   - Running this example multiple times\n');
+		} else {
+			console.error(`❌ Error removing tag: ${error.message}\n`);
+		}
+	}
+
+	console.log('='.repeat(60));
+	console.log('✅ Tag Management Example Completed');
+	console.log('='.repeat(60));
+}
+
+// Run the example
+main().catch((error) => {
+	console.error('❌ Fatal error:', error);
+	process.exit(1);
+});