feat: add nip-25 support (#589)

Author: CKodidela

.changeset/nip-25-reactions.md

@@ -0,0 +1,5 @@
+---
+"nostream": minor
+---
+
+Add NIP-25 Reactions support for kind 7 and kind 17 events: reaction utility helpers (`isReactionEvent`, `isExternalContentReactionEvent`, `isLikeReaction`, `isDislikeReaction`, `parseReaction`), schema validation enforcing required `e` tag on kind 7 and required `k`/`i` tags on kind 17, unit tests, and integration tests.

README.md

@@ -56,6 +56,7 @@ NIPs with a relay-specific implementation are listed here.
 - [x] NIP-16: Event Treatment
 - [x] NIP-20: Command Results
 - [x] NIP-22: Event `created_at` Limits
+- [x] NIP-25: Reactions
 - [ ] NIP-26: Delegated Event Signing (REMOVED)
 - [x] NIP-28: Public Chat
 - [x] NIP-33: Parameterized Replaceable Events

package.json

@@ -18,6 +18,7 @@
     17,
     20,
     22,
+    25,
     28,
     33,
     40,

src/@types/event.ts

@@ -49,6 +49,14 @@ export interface DBEvent {
   expires_at?: number
 }
 
+export type ReactionEntry = {
+  targetEventId?: string
+  targetPubkey?: string
+  targetAddress?: string
+  targetKind?: number
+  content: string
+}
+
 export type RelayListEntry = {
   url: string
   marker?: 'read' | 'write'

src/constants/base.ts

@@ -11,6 +11,8 @@ export enum EventKinds {
   SEAL = 13,
   DIRECT_MESSAGE = 14,
   FILE_MESSAGE = 15,
+  // NIP-25: External content reaction
+  EXTERNAL_CONTENT_REACTION = 17,
   REQUEST_TO_VANISH = 62,
   // Channels
   CHANNEL_CREATION = 40,
@@ -64,6 +66,10 @@ export enum EventTags {
   Invoice = 'bolt11',
   // NIP-03: target event kind on an OpenTimestamps attestation
   Kind = 'k',
+  // NIP-25: Reactions
+  Address = 'a',
+  Index = 'i',
+  Emoji = 'emoji',
   // NIP-12: geohash tag for location-based queries
   Geohash = 'g',
   // Marmot Protocol MIP-03: group ID for filtering kind:445 Group Events

src/factories/event-strategy-factory.ts

@@ -49,4 +49,4 @@ export const eventStrategyFactory =
     }
 
     return new DefaultEventStrategy(adapter, eventRepository)
-  }
+  }

src/schemas/event-schema.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 
 import { EventKinds, EventTags } from '../constants/base'
+import { isExternalContentReactionEvent, isReactionEvent } from '../utils/nip25'
 import {
   createdAtSchema,
   geohashSchema,
@@ -39,7 +40,37 @@ export const eventSchema = z
   })
   .strict()
   .superRefine((event, ctx) => {
-    if (event.kind === EventKinds.RELAY_LIST) {
+    if (isReactionEvent(event)) {
+      let hasEventTag = false
+      let hasAddressTag = false
+      for (const tag of event.tags) {
+        if (tag[0] === EventTags.Event && typeof tag[1] === 'string' && tag[1].length > 0) { hasEventTag = true }
+        else if (tag[0] === EventTags.Address && typeof tag[1] === 'string' && tag[1].length > 0) { hasAddressTag = true }
+        if (hasEventTag && hasAddressTag) { break }
+      }
+      if (!hasEventTag && !hasAddressTag) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Reaction event (kind 7) must have at least one e or a tag',
+          path: ['tags'],
+        })
+      }
+    } else if (isExternalContentReactionEvent(event)) {
+      let hasKTag = false
+      let hasITag = false
+      for (const tag of event.tags) {
+        if (tag[0] === EventTags.Kind && tag.length >= 2 && typeof tag[1] === 'string' && tag[1].length > 0) { hasKTag = true }
+        else if (tag[0] === EventTags.Index && tag.length >= 2 && typeof tag[1] === 'string' && tag[1].length > 0) { hasITag = true }
+        if (hasKTag && hasITag) { break }
+      }
+      if (!hasKTag || !hasITag) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'External content reaction event (kind 17) must have k and i tags',
+          path: ['tags'],
+        })
+      }
+    } else if (event.kind === EventKinds.RELAY_LIST) {
       event.tags.forEach((tag, index) => {
         if (tag[0] === EventTags.Relay && !z.string().url().safeParse(tag[1]).success) {
           ctx.addIssue({

src/utils/nip25.ts

@@ -0,0 +1,39 @@
+import { Event, ReactionEntry } from '../@types/event'
+import { EventKinds, EventTags } from '../constants/base'
+
+export const isReactionEvent = (event: { kind?: number }): boolean => event.kind === EventKinds.REACTION
+
+export const isExternalContentReactionEvent = (event: { kind?: number }): boolean =>
+    event.kind === EventKinds.EXTERNAL_CONTENT_REACTION
+
+export const isLikeReaction = (event: { kind?: number; content?: string }): boolean =>
+    isReactionEvent(event) && (event.content === '+' || event.content === '')
+
+export const isDislikeReaction = (event: { kind?: number; content?: string }): boolean =>
+    isReactionEvent(event) && event.content === '-'
+
+export const parseReaction = (event: Event): ReactionEntry => {
+    let lastETag: string[] | undefined
+    let lastPTag: string[] | undefined
+    let lastATag: string[] | undefined
+    let firstKTag: string[] | undefined
+
+    for (const tag of event.tags) {
+        switch (tag[0]) {
+            case EventTags.Event: lastETag = tag; break
+            case EventTags.Pubkey: lastPTag = tag; break
+            case EventTags.Address: lastATag = tag; break
+            case EventTags.Kind: if (!firstKTag) { firstKTag = tag } break
+        }
+    }
+
+    const kTagValue = firstKTag && firstKTag.length > 1 ? firstKTag[1] : undefined
+    const parsedKind = kTagValue !== undefined ? Number(kTagValue) : undefined
+    return {
+        targetEventId: lastETag?.[1],
+        targetPubkey: lastPTag?.[1],
+        targetAddress: lastATag?.[1],
+        targetKind: parsedKind !== undefined && Number.isFinite(parsedKind) ? parsedKind : undefined,
+        content: event.content,
+    }
+}

test/integration/features/nip-25/nip-25.feature

@@ -0,0 +1,24 @@
+Feature: NIP-25 Reactions
+  Scenario: Alice likes Bob's note
+    Given someone called Alice
+    And someone called Bob
+    When Bob sends a text_note event with content "hello world"
+    And Alice reacts to Bob's note with "+"
+    And Alice subscribes to her reaction events
+    Then Alice receives a reaction event with content "+"
+
+  Scenario: Alice dislikes Bob's note
+    Given someone called Alice
+    And someone called Bob
+    When Bob sends a text_note event with content "hello world"
+    And Alice reacts to Bob's note with "-"
+    And Alice subscribes to her reaction events
+    Then Alice receives a reaction event with content "-"
+
+  Scenario: Alice reacts with an emoji
+    Given someone called Alice
+    And someone called Bob
+    When Bob sends a text_note event with content "hello world"
+    And Alice reacts to Bob's note with "🤙"
+    And Alice subscribes to her reaction events
+    Then Alice receives a reaction event with content "🤙"

test/integration/features/nip-25/nip-25.feature.ts

@@ -0,0 +1,49 @@
+import { Then, When, World } from '@cucumber/cucumber'
+import { expect } from 'chai'
+import WebSocket from 'ws'
+import { Event } from '../../../../src/@types/event'
+import { EventKinds } from '../../../../src/constants/base'
+import { createEvent, createSubscription, sendEvent, waitForNextEvent } from '../helpers'
+
+When(/^(\w+) reacts to (\w+)'s note with "([^"]+)"$/, async function (reactor: string, author: string, content: string) {
+    const ws = this.parameters.clients[reactor] as WebSocket
+    const { pubkey, privkey } = this.parameters.identities[reactor]
+    const targetEvent = this.parameters.events[author][this.parameters.events[author].length - 1] as Event
+
+    const event: Event = await createEvent(
+        {
+            pubkey,
+            kind: EventKinds.REACTION,
+            content,
+            tags: [
+                ['e', targetEvent.id],
+                ['p', targetEvent.pubkey],
+            ],
+        },
+        privkey,
+    )
+
+    await sendEvent(ws, event)
+    this.parameters.events[reactor].push(event)
+})
+
+When(/^(\w+) subscribes to (?:her|his|their) reaction events$/, async function (this: World<Record<string, any>>, name: string) {
+    const ws = this.parameters.clients[name] as WebSocket
+    const { pubkey } = this.parameters.identities[name]
+    const subscription = {
+        name: `test-${Math.random()}`,
+        filters: [{ kinds: [EventKinds.REACTION], authors: [pubkey] }],
+    }
+    this.parameters.subscriptions[name].push(subscription)
+
+    await createSubscription(ws, subscription.name, subscription.filters)
+})
+
+Then(/^(\w+) receives a reaction event with content "([^"]+)"$/, async function (name: string, content: string) {
+    const ws = this.parameters.clients[name] as WebSocket
+    const subscription = this.parameters.subscriptions[name][this.parameters.subscriptions[name].length - 1]
+    const receivedEvent = await waitForNextEvent(ws, subscription.name)
+
+    expect(receivedEvent.kind).to.equal(EventKinds.REACTION)
+    expect(receivedEvent.content).to.equal(content)
+})