refactor: migrate NIP-58 badges to nip88Polls-style sub-package structure

Restructures the flat nip58Badges package into sub-packages following
the established nip88Polls pattern with proper tag classes, TagArrayExt,
and TagArrayBuilderExt for each event type:

- definition/ - BadgeDefinitionEvent (kind 30009) with NameTag, ImageTag,
  DescriptionTag, ThumbTag supporting dimensions per spec
- award/ - BadgeAwardEvent (kind 8) with build() method
- profiles/ - BadgeProfilesEvent (kind 30008) with AcceptedBadge tag
  for proper paired a+e tag parsing per NIP-58 spec

Adds build() companion methods to all three event types and full
spec compliance including image/thumb dimension support.

https://claude.ai/code/session_019Uvxfa7jJbjeprLxECoJ8s

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/award/BadgeAwardEvent.kt

@@ -18,20 +18,21 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip58Badges
+package com.vitorpamplona.quartz.nip58Badges.award
 
 import androidx.compose.runtime.Immutable
 import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
+import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
 import com.vitorpamplona.quartz.nip01Core.hints.AddressHintProvider
 import com.vitorpamplona.quartz.nip01Core.hints.EventHintProvider
 import com.vitorpamplona.quartz.nip01Core.hints.PubKeyHintProvider
+import com.vitorpamplona.quartz.nip01Core.signers.eventTemplate
 import com.vitorpamplona.quartz.nip01Core.tags.aTag.ATag
-import com.vitorpamplona.quartz.nip01Core.tags.aTag.taggedAddresses
 import com.vitorpamplona.quartz.nip01Core.tags.events.ETag
 import com.vitorpamplona.quartz.nip01Core.tags.people.PTag
-import com.vitorpamplona.quartz.nip01Core.tags.people.taggedUserIds
-import com.vitorpamplona.quartz.nip01Core.tags.people.taggedUsers
+import com.vitorpamplona.quartz.nip31Alts.alt
+import com.vitorpamplona.quartz.utils.TimeUtils
 
 @Immutable
 class BadgeAwardEvent(
@@ -57,14 +58,26 @@ class BadgeAwardEvent(
 
     override fun linkedAddressIds() = tags.mapNotNull(ATag::parseAddressId)
 
-    fun awardees() = taggedUsers()
+    fun awardees() = tags.awardees()
 
-    fun awardeeIds() = taggedUserIds()
+    fun awardeeIds() = tags.awardeeIds()
 
-    fun awardDefinition() = taggedAddresses()
+    fun awardDefinition() = tags.awardDefinitions()
 
     companion object {
         const val KIND = 8
-        const val ALT = "Badge award"
+        const val ALT_DESCRIPTION = "Badge award"
+
+        fun build(
+            awardDefinition: ATag,
+            awardees: List<PTag>,
+            createdAt: Long = TimeUtils.now(),
+            initializer: TagArrayBuilder<BadgeAwardEvent>.() -> Unit = {},
+        ) = eventTemplate(KIND, "", createdAt) {
+            alt(ALT_DESCRIPTION)
+            awardDefinition(awardDefinition)
+            awardees(awardees)
+            initializer()
+        }
     }
 }

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/award/TagArrayBuilderExt.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.award
+
+import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
+import com.vitorpamplona.quartz.nip01Core.tags.aTag.ATag
+import com.vitorpamplona.quartz.nip01Core.tags.aTag.aTag
+import com.vitorpamplona.quartz.nip01Core.tags.people.PTag
+import com.vitorpamplona.quartz.nip01Core.tags.people.pTag
+import com.vitorpamplona.quartz.nip01Core.tags.people.pTags
+
+fun TagArrayBuilder<BadgeAwardEvent>.awardDefinition(tag: ATag) = aTag(tag)
+
+fun TagArrayBuilder<BadgeAwardEvent>.awardees(tags: List<PTag>) = pTags(tags)
+
+fun TagArrayBuilder<BadgeAwardEvent>.awardee(tag: PTag) = pTag(tag)

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/award/TagArrayExt.kt

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.award
+
+import com.vitorpamplona.quartz.nip01Core.core.TagArray
+import com.vitorpamplona.quartz.nip01Core.tags.aTag.taggedAddresses
+import com.vitorpamplona.quartz.nip01Core.tags.people.taggedUserIds
+import com.vitorpamplona.quartz.nip01Core.tags.people.taggedUsers
+
+fun TagArray.awardees() = taggedUsers()
+
+fun TagArray.awardeeIds() = taggedUserIds()
+
+fun TagArray.awardDefinitions() = taggedAddresses()

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/definition/BadgeDefinitionEvent.kt

@@ -0,0 +1,101 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.definition
+
+import androidx.compose.runtime.Immutable
+import com.vitorpamplona.quartz.nip01Core.core.BaseAddressableEvent
+import com.vitorpamplona.quartz.nip01Core.core.HexKey
+import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
+import com.vitorpamplona.quartz.nip01Core.signers.eventTemplate
+import com.vitorpamplona.quartz.nip01Core.tags.dTag.dTag
+import com.vitorpamplona.quartz.nip31Alts.alt
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.ImageTag
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.ThumbTag
+import com.vitorpamplona.quartz.nip94FileMetadata.tags.DimensionTag
+import com.vitorpamplona.quartz.utils.TimeUtils
+
+@Immutable
+class BadgeDefinitionEvent(
+    id: HexKey,
+    pubKey: HexKey,
+    createdAt: Long,
+    tags: Array<Array<String>>,
+    content: String,
+    sig: HexKey,
+) : BaseAddressableEvent(id, pubKey, createdAt, KIND, tags, content, sig) {
+    fun name() = tags.badgeName()
+
+    fun image() = tags.badgeImageUrl()
+
+    fun imageWithDimensions() = tags.badgeImage()
+
+    fun description() = tags.badgeDescription()
+
+    fun thumb() = tags.badgeThumbUrl()
+
+    fun thumbs() = tags.badgeThumbs()
+
+    companion object {
+        const val KIND = 30009
+        const val ALT_DESCRIPTION = "Badge definition"
+
+        fun build(
+            badgeId: String,
+            name: String? = null,
+            image: ImageTag? = null,
+            description: String? = null,
+            thumbs: List<ThumbTag> = emptyList(),
+            createdAt: Long = TimeUtils.now(),
+            initializer: TagArrayBuilder<BadgeDefinitionEvent>.() -> Unit = {},
+        ) = eventTemplate(KIND, "", createdAt) {
+            dTag(badgeId)
+            alt(ALT_DESCRIPTION)
+            name?.let { name(it) }
+            image?.let { image(it.url, it.dimensions) }
+            description?.let { description(it) }
+            if (thumbs.isNotEmpty()) {
+                thumbs(thumbs)
+            }
+            initializer()
+        }
+
+        fun build(
+            badgeId: String,
+            name: String? = null,
+            imageUrl: String? = null,
+            imageDimensions: DimensionTag? = null,
+            description: String? = null,
+            thumbs: List<ThumbTag> = emptyList(),
+            createdAt: Long = TimeUtils.now(),
+            initializer: TagArrayBuilder<BadgeDefinitionEvent>.() -> Unit = {},
+        ) = eventTemplate(KIND, "", createdAt) {
+            dTag(badgeId)
+            alt(ALT_DESCRIPTION)
+            name?.let { name(it) }
+            imageUrl?.let { image(it, imageDimensions) }
+            description?.let { description(it) }
+            if (thumbs.isNotEmpty()) {
+                thumbs(thumbs)
+            }
+            initializer()
+        }
+    }
+}

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/definition/TagArrayBuilderExt.kt

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.definition
+
+import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.DescriptionTag
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.ImageTag
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.NameTag
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.ThumbTag
+import com.vitorpamplona.quartz.nip94FileMetadata.tags.DimensionTag
+
+fun TagArrayBuilder<BadgeDefinitionEvent>.name(name: String) = addUnique(NameTag.assemble(name))
+
+fun TagArrayBuilder<BadgeDefinitionEvent>.image(
+    url: String,
+    dimensions: DimensionTag? = null,
+) = addUnique(ImageTag.assemble(url, dimensions))
+
+fun TagArrayBuilder<BadgeDefinitionEvent>.description(description: String) = addUnique(DescriptionTag.assemble(description))
+
+fun TagArrayBuilder<BadgeDefinitionEvent>.thumb(
+    url: String,
+    dimensions: DimensionTag? = null,
+) = add(ThumbTag.assemble(url, dimensions))
+
+fun TagArrayBuilder<BadgeDefinitionEvent>.thumbs(thumbs: List<ThumbTag>) = addAll(ThumbTag.assemble(thumbs))

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/definition/TagArrayExt.kt

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.definition
+
+import com.vitorpamplona.quartz.nip01Core.core.TagArray
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.DescriptionTag
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.ImageTag
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.NameTag
+import com.vitorpamplona.quartz.nip58Badges.definition.tags.ThumbTag
+
+fun TagArray.badgeName() = firstNotNullOfOrNull(NameTag::parse)
+
+fun TagArray.badgeImage() = firstNotNullOfOrNull(ImageTag::parse)
+
+fun TagArray.badgeImageUrl() = firstNotNullOfOrNull(ImageTag::parseUrl)
+
+fun TagArray.badgeDescription() = firstNotNullOfOrNull(DescriptionTag::parse)
+
+fun TagArray.badgeThumbs() = mapNotNull(ThumbTag::parse)
+
+fun TagArray.badgeThumbUrl() = firstNotNullOfOrNull(ThumbTag::parseUrl)

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/definition/tags/DescriptionTag.kt

@@ -18,31 +18,22 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip58Badges
+package com.vitorpamplona.quartz.nip58Badges.definition.tags
 
-import androidx.compose.runtime.Immutable
-import com.vitorpamplona.quartz.nip01Core.core.BaseAddressableEvent
-import com.vitorpamplona.quartz.nip01Core.core.HexKey
-
-@Immutable
-class BadgeDefinitionEvent(
-    id: HexKey,
-    pubKey: HexKey,
-    createdAt: Long,
-    tags: Array<Array<String>>,
-    content: String,
-    sig: HexKey,
-) : BaseAddressableEvent(id, pubKey, createdAt, KIND, tags, content, sig) {
-    fun name() = tags.firstOrNull { it.size > 1 && it[0] == "name" }?.get(1)
-
-    fun thumb() = tags.firstOrNull { it.size > 1 && it[0] == "thumb" }?.get(1)
-
-    fun image() = tags.firstOrNull { it.size > 1 && it[0] == "image" }?.get(1)
-
-    fun description() = tags.firstOrNull { it.size > 1 && it[0] == "description" }?.get(1)
+import com.vitorpamplona.quartz.nip01Core.core.has
+import com.vitorpamplona.quartz.utils.ensure
 
+class DescriptionTag {
     companion object {
-        const val KIND = 30009
-        const val ALT = "Badge definition"
+        const val TAG_NAME = "description"
+
+        fun parse(tag: Array<String>): String? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            ensure(tag[1].isNotEmpty()) { return null }
+            return tag[1]
+        }
+
+        fun assemble(description: String) = arrayOf(TAG_NAME, description)
     }
 }

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/definition/tags/ImageTag.kt

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.definition.tags
+
+import com.vitorpamplona.quartz.nip01Core.core.has
+import com.vitorpamplona.quartz.nip94FileMetadata.tags.DimensionTag
+import com.vitorpamplona.quartz.utils.arrayOfNotNull
+import com.vitorpamplona.quartz.utils.ensure
+
+class ImageTag(
+    val url: String,
+    val dimensions: DimensionTag? = null,
+) {
+    companion object {
+        const val TAG_NAME = "image"
+
+        fun parse(tag: Array<String>): ImageTag? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            ensure(tag[1].isNotEmpty()) { return null }
+            val dims = tag.getOrNull(2)?.let { DimensionTag.parse(it) }
+            return ImageTag(tag[1], dims)
+        }
+
+        fun parseUrl(tag: Array<String>): String? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            ensure(tag[1].isNotEmpty()) { return null }
+            return tag[1]
+        }
+
+        fun assemble(
+            url: String,
+            dimensions: DimensionTag? = null,
+        ) = arrayOfNotNull(TAG_NAME, url, dimensions?.toString())
+
+        fun assemble(image: ImageTag) = assemble(image.url, image.dimensions)
+    }
+}

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/definition/tags/NameTag.kt

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.definition.tags
+
+import com.vitorpamplona.quartz.nip01Core.core.has
+import com.vitorpamplona.quartz.utils.ensure
+
+class NameTag {
+    companion object {
+        const val TAG_NAME = "name"
+
+        fun parse(tag: Array<String>): String? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            ensure(tag[1].isNotEmpty()) { return null }
+            return tag[1]
+        }
+
+        fun assemble(name: String) = arrayOf(TAG_NAME, name)
+    }
+}

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/definition/tags/ThumbTag.kt

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.definition.tags
+
+import com.vitorpamplona.quartz.nip01Core.core.has
+import com.vitorpamplona.quartz.nip94FileMetadata.tags.DimensionTag
+import com.vitorpamplona.quartz.utils.arrayOfNotNull
+import com.vitorpamplona.quartz.utils.ensure
+
+class ThumbTag(
+    val url: String,
+    val dimensions: DimensionTag? = null,
+) {
+    companion object {
+        const val TAG_NAME = "thumb"
+
+        fun parse(tag: Array<String>): ThumbTag? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            ensure(tag[1].isNotEmpty()) { return null }
+            val dims = tag.getOrNull(2)?.let { DimensionTag.parse(it) }
+            return ThumbTag(tag[1], dims)
+        }
+
+        fun parseUrl(tag: Array<String>): String? {
+            ensure(tag.has(1)) { return null }
+            ensure(tag[0] == TAG_NAME) { return null }
+            ensure(tag[1].isNotEmpty()) { return null }
+            return tag[1]
+        }
+
+        fun assemble(
+            url: String,
+            dimensions: DimensionTag? = null,
+        ) = arrayOfNotNull(TAG_NAME, url, dimensions?.toString())
+
+        fun assemble(thumb: ThumbTag) = assemble(thumb.url, thumb.dimensions)
+
+        fun assemble(thumbs: List<ThumbTag>) = thumbs.map { assemble(it) }
+    }
+}

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/profiles/BadgeProfilesEvent.kt

@@ -18,20 +18,24 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip58Badges
+package com.vitorpamplona.quartz.nip58Badges.profiles
 
 import androidx.compose.runtime.Immutable
 import com.vitorpamplona.quartz.nip01Core.core.Address
 import com.vitorpamplona.quartz.nip01Core.core.BaseAddressableEvent
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
+import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
 import com.vitorpamplona.quartz.nip01Core.hints.AddressHintProvider
 import com.vitorpamplona.quartz.nip01Core.hints.EventHintProvider
 import com.vitorpamplona.quartz.nip01Core.hints.PubKeyHintProvider
+import com.vitorpamplona.quartz.nip01Core.signers.eventTemplate
 import com.vitorpamplona.quartz.nip01Core.tags.aTag.ATag
-import com.vitorpamplona.quartz.nip01Core.tags.aTag.taggedAddresses
+import com.vitorpamplona.quartz.nip01Core.tags.dTag.dTag
 import com.vitorpamplona.quartz.nip01Core.tags.events.ETag
-import com.vitorpamplona.quartz.nip01Core.tags.events.taggedEvents
 import com.vitorpamplona.quartz.nip01Core.tags.people.PTag
+import com.vitorpamplona.quartz.nip31Alts.alt
+import com.vitorpamplona.quartz.nip58Badges.profiles.tags.AcceptedBadge
+import com.vitorpamplona.quartz.utils.TimeUtils
 
 @Immutable
 class BadgeProfilesEvent(
@@ -57,17 +61,32 @@ class BadgeProfilesEvent(
 
     override fun linkedAddressIds() = tags.mapNotNull(ATag::parseAddressId)
 
-    fun badgeAwardEvents() = taggedEvents()
+    fun acceptedBadges() = tags.acceptedBadges()
 
-    fun badgeAwardDefinitions() = taggedAddresses()
+    fun badgeAwardEvents() = tags.badgeAwardEvents()
+
+    fun badgeAwardDefinitions() = tags.badgeAwardDefinitions()
 
     companion object {
         const val KIND = 30008
         private const val STANDARD_D_TAG = "profile_badges"
-        private const val ALT = "List of accepted badges by the author"
+        const val ALT_DESCRIPTION = "List of accepted badges by the author"
 
         fun createAddress(pubKey: HexKey): Address = Address(KIND, pubKey, STANDARD_D_TAG)
 
         fun createAddressTag(pubKey: HexKey): ATag = ATag(KIND, pubKey, STANDARD_D_TAG, null)
+
+        fun build(
+            acceptedBadges: List<AcceptedBadge> = emptyList(),
+            createdAt: Long = TimeUtils.now(),
+            initializer: TagArrayBuilder<BadgeProfilesEvent>.() -> Unit = {},
+        ) = eventTemplate(KIND, "", createdAt) {
+            dTag(STANDARD_D_TAG)
+            alt(ALT_DESCRIPTION)
+            if (acceptedBadges.isNotEmpty()) {
+                acceptedBadges(acceptedBadges)
+            }
+            initializer()
+        }
     }
 }

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/profiles/TagArrayBuilderExt.kt

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.profiles
+
+import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
+import com.vitorpamplona.quartz.nip58Badges.profiles.tags.AcceptedBadge
+
+fun TagArrayBuilder<BadgeProfilesEvent>.acceptedBadges(badges: List<AcceptedBadge>) = addAll(AcceptedBadge.assemble(badges))

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/profiles/TagArrayExt.kt

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.profiles
+
+import com.vitorpamplona.quartz.nip01Core.core.TagArray
+import com.vitorpamplona.quartz.nip01Core.tags.aTag.taggedAddresses
+import com.vitorpamplona.quartz.nip01Core.tags.events.taggedEvents
+import com.vitorpamplona.quartz.nip58Badges.profiles.tags.AcceptedBadge
+
+fun TagArray.acceptedBadges() = AcceptedBadge.parseAll(this)
+
+fun TagArray.badgeAwardEvents() = taggedEvents()
+
+fun TagArray.badgeAwardDefinitions() = taggedAddresses()

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip58Badges/profiles/tags/AcceptedBadge.kt

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip58Badges.profiles.tags
+
+import androidx.compose.runtime.Stable
+import com.vitorpamplona.quartz.nip01Core.core.TagArray
+import com.vitorpamplona.quartz.nip01Core.tags.aTag.ATag
+import com.vitorpamplona.quartz.nip01Core.tags.events.ETag
+
+/**
+ * Represents a paired `a` (badge definition) and `e` (badge award) tag
+ * as specified in NIP-58 Profile Badges.
+ *
+ * Clients SHOULD ignore unpaired `a` or `e` tags.
+ */
+@Stable
+class AcceptedBadge(
+    val badgeDefinition: ATag,
+    val badgeAward: ETag,
+) {
+    companion object {
+        /**
+         * Parses ordered consecutive pairs of `a` and `e` tags from a tag array.
+         * Tags must appear as sequential pairs: `a`, `e`, `a`, `e`, ...
+         * Unpaired tags are ignored per the spec.
+         */
+        fun parseAll(tags: TagArray): List<AcceptedBadge> {
+            val result = mutableListOf<AcceptedBadge>()
+            var i = 0
+            while (i < tags.size - 1) {
+                val aTag = ATag.parse(tags[i])
+                if (aTag != null) {
+                    val eTag = ETag.parse(tags[i + 1])
+                    if (eTag != null) {
+                        result.add(AcceptedBadge(aTag, eTag))
+                        i += 2
+                        continue
+                    }
+                }
+                i++
+            }
+            return result
+        }
+
+        fun assemble(badges: List<AcceptedBadge>): List<Array<String>> =
+            badges.flatMap { badge ->
+                listOf(
+                    badge.badgeDefinition.toATagArray(),
+                    badge.badgeAward.toTagArray(),
+                )
+            }
+    }
+}

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/EventFactory.kt

@@ -139,9 +139,9 @@ import com.vitorpamplona.quartz.nip56Reports.ReportEvent
 import com.vitorpamplona.quartz.nip57Zaps.LnZapEvent
 import com.vitorpamplona.quartz.nip57Zaps.LnZapPrivateEvent
 import com.vitorpamplona.quartz.nip57Zaps.LnZapRequestEvent
-import com.vitorpamplona.quartz.nip58Badges.BadgeAwardEvent
-import com.vitorpamplona.quartz.nip58Badges.BadgeDefinitionEvent
-import com.vitorpamplona.quartz.nip58Badges.BadgeProfilesEvent
+import com.vitorpamplona.quartz.nip58Badges.award.BadgeAwardEvent
+import com.vitorpamplona.quartz.nip58Badges.definition.BadgeDefinitionEvent
+import com.vitorpamplona.quartz.nip58Badges.profiles.BadgeProfilesEvent
 import com.vitorpamplona.quartz.nip59Giftwrap.seals.SealedRumorEvent
 import com.vitorpamplona.quartz.nip59Giftwrap.wraps.GiftWrapEvent
 import com.vitorpamplona.quartz.nip5aStaticWebsites.NamedSiteEvent