NIP-89: 應用推薦

概述

NIP-89 定義了應用推薦系統，讓用戶可以推薦處理特定事件類型的應用程式， 同時讓應用開發者可以聲明他們的應用支援哪些事件類型。這建立了一個去中心化的應用發現機制。

事件類型

應用資訊事件（Kind 31990）

應用開發者發布此事件，聲明應用可以處理哪些事件類型：

推薦事件（Kind 31989）

用戶發布此事件，推薦處理特定事件類型的應用：

使用範例

應用聲明支援的事件類型

{
  "kind": 31990,
  "tags": [
    ["d", "calendar-app-v1"],
    ["k", "31922"],
    ["k", "31923"],
    ["k", "31925"],
    ["web", "https://calendar.nostr.app/<bech32>"],
    ["web", "https://calendar.nostr.app/<bech32>", "nevent"],
    ["web", "https://calendar.nostr.app/<bech32>", "naddr"],
    ["ios", "nostrcalendar://open/<bech32>"],
    ["android", "intent://open/<bech32>#Intent;scheme=nostrcalendar;end"]
  ],
  "content": "{\"name\":\"Nostr Calendar\",\"display_name\":\"Nostr 日曆\",\"picture\":\"https://calendar.nostr.app/icon.png\",\"about\":\"管理你的 Nostr 日曆活動\"}"
}

長文閱讀器應用

{
  "kind": 31990,
  "tags": [
    ["d", "habla-reader"],
    ["k", "30023"],
    ["web", "https://habla.news/a/<bech32>", "naddr"],
    ["web", "https://habla.news/<bech32>"]
  ],
  "content": "{\"name\":\"Habla\",\"display_name\":\"Habla\",\"picture\":\"https://habla.news/logo.png\",\"about\":\"Nostr 長文閱讀與寫作平台\"}"
}

用戶推薦日曆應用

{
  "kind": 31989,
  "tags": [
    ["d", "31923"],
    ["a", "31990:<app-pubkey>:calendar-app-v1", "wss://relay.example.com", "web"]
  ],
  "content": "推薦使用這個日曆應用處理活動事件"
}

推薦多個應用

{
  "kind": 31989,
  "tags": [
    ["d", "30023"],
    ["a", "31990:<habla-pubkey>:habla-reader", "wss://relay.example.com", "web"],
    ["a", "31990:<yakihonne-pubkey>:yakihonne", "wss://relay.example.com", "web"],
    ["a", "31990:<blogstack-pubkey>:blogstack", "wss://relay.example.com", "web"]
  ],
  "content": "我推薦的長文閱讀應用"
}

TypeScript 實作

import { finalizeEvent, generateSecretKey, getPublicKey, nip19 } from 'nostr-tools'

type Platform = 'web' | 'ios' | 'android'

interface HandlerUrl {
  platform: Platform
  url: string
  nip19Type?: string  // nevent, naddr, npub, etc.
}

interface AppMetadata {
  name: string
  display_name?: string
  picture?: string
  about?: string
}

interface HandlerOptions {
  identifier: string
  supportedKinds: number[]
  handlers: HandlerUrl[]
  metadata?: AppMetadata
}

// 創建應用資訊事件（開發者用）
function createHandlerEvent(
  options: HandlerOptions,
  secretKey: Uint8Array
): object {
  const tags: string[][] = [
    ['d', options.identifier],
  ]

  // 添加支援的 kinds
  for (const kind of options.supportedKinds) {
    tags.push(['k', kind.toString()])
  }

  // 添加處理器 URLs
  for (const handler of options.handlers) {
    const tag = [handler.platform, handler.url]
    if (handler.nip19Type) {
      tag.push(handler.nip19Type)
    }
    tags.push(tag)
  }

  const event = {
    kind: 31990,
    created_at: Math.floor(Date.now() / 1000),
    tags,
    content: options.metadata ? JSON.stringify(options.metadata) : '',
  }

  return finalizeEvent(event, secretKey)
}

// 創建推薦事件（用戶用）
function createRecommendation(
  eventKind: number,
  recommendations: { pubkey: string; identifier: string; relay?: string; platform?: Platform }[],
  secretKey: Uint8Array,
  comment?: string
): object {
  const tags: string[][] = [
    ['d', eventKind.toString()],
  ]

  for (const rec of recommendations) {
    const aTag = `31990:${rec.pubkey}:${rec.identifier}`
    const tag = ['a', aTag]
    if (rec.relay) tag.push(rec.relay)
    else if (rec.platform) tag.push('')
    if (rec.platform) tag.push(rec.platform)
    tags.push(tag)
  }

  const event = {
    kind: 31989,
    created_at: Math.floor(Date.now() / 1000),
    tags,
    content: comment || '',
  }

  return finalizeEvent(event, secretKey)
}

// 生成處理 URL
function buildHandlerUrl(
  template: string,
  eventId: string,
  eventPubkey: string,
  eventKind: number,
  relays: string[] = []
): string {
  // 根據 kind 選擇適當的 NIP-19 編碼
  let bech32: string

  if (eventKind >= 30000 && eventKind < 40000) {
    // 可定址事件使用 naddr
    bech32 = nip19.naddrEncode({
      kind: eventKind,
      pubkey: eventPubkey,
      identifier: eventId,
      relays,
    })
  } else {
    // 一般事件使用 nevent
    bech32 = nip19.neventEncode({
      id: eventId,
      author: eventPubkey,
      relays,
    })
  }

  return template.replace('<bech32>', bech32)
}

// 使用範例 - 開發者發布應用資訊
const appSk = generateSecretKey()
const appPk = getPublicKey(appSk)

const handlerEvent = createHandlerEvent({
  identifier: 'my-calendar-app',
  supportedKinds: [31922, 31923, 31925],
  handlers: [
    { platform: 'web', url: 'https://mycalendar.app/<bech32>' },
    { platform: 'web', url: 'https://mycalendar.app/event/<bech32>', nip19Type: 'nevent' },
    { platform: 'ios', url: 'mycalendar://open/<bech32>' },
  ],
  metadata: {
    name: 'MyCalendar',
    display_name: '我的日曆',
    picture: 'https://mycalendar.app/icon.png',
    about: '一個簡單的 Nostr 日曆應用',
  },
}, appSk)

// 使用範例 - 用戶推薦應用
const userSk = generateSecretKey()

const recommendation = createRecommendation(
  31923,  // 推薦處理時間活動的應用
  [
    { pubkey: appPk, identifier: 'my-calendar-app', relay: 'wss://relay.example.com', platform: 'web' }
  ],
  userSk,
  '這個日曆應用非常好用！'
)

console.log('Handler event:', handlerEvent)
console.log('Recommendation:', recommendation)

查詢應用處理器

import { SimplePool } from 'nostr-tools'

const pool = new SimplePool()
const relays = ['wss://relay.example.com']

// 查詢支援特定事件類型的應用
async function getHandlersForKind(kind: number) {
  const handlers = await pool.querySync(relays, {
    kinds: [31990],
    '#k': [kind.toString()],
  })
  return handlers
}

// 查詢用戶推薦的應用
async function getRecommendationsForKind(kind: number) {
  const recommendations = await pool.querySync(relays, {
    kinds: [31989],
    '#d': [kind.toString()],
  })
  return recommendations
}

// 查詢關注者推薦的應用
async function getFollowingRecommendations(
  kind: number,
  followingPubkeys: string[]
) {
  const recommendations = await pool.querySync(relays, {
    kinds: [31989],
    authors: followingPubkeys,
    '#d': [kind.toString()],
  })
  return recommendations
}

// 解析應用處理器
function parseHandler(event: any) {
  const identifier = event.tags.find((t: string[]) => t[0] === 'd')?.[1]

  const supportedKinds = event.tags
    .filter((t: string[]) => t[0] === 'k')
    .map((t: string[]) => parseInt(t[1]))

  const handlers: { platform: string; url: string; nip19Type?: string }[] = []
  for (const tag of event.tags) {
    if (['web', 'ios', 'android'].includes(tag[0])) {
      handlers.push({
        platform: tag[0],
        url: tag[1],
        nip19Type: tag[2],
      })
    }
  }

  // 解析 metadata
  let metadata = null
  if (event.content) {
    try {
      metadata = JSON.parse(event.content)
    } catch {}
  }

  return {
    pubkey: event.pubkey,
    identifier,
    supportedKinds,
    handlers,
    metadata,
  }
}

// 解析推薦
function parseRecommendation(event: any) {
  const targetKind = event.tags.find((t: string[]) => t[0] === 'd')?.[1]

  const recommendations = event.tags
    .filter((t: string[]) => t[0] === 'a')
    .map((t: string[]) => {
      const [kind, pubkey, identifier] = t[1].split(':')
      return {
        handlerKind: parseInt(kind),
        pubkey,
        identifier,
        relay: t[2] || undefined,
        platform: t[3] || undefined,
      }
    })

  return {
    recommenderPubkey: event.pubkey,
    targetKind: parseInt(targetKind),
    recommendations,
    comment: event.content,
  }
}

// 選擇最佳處理器
function selectBestHandler(
  handlers: ReturnType<typeof parseHandler>[],
  platform: 'web' | 'ios' | 'android',
  nip19Type?: string
) {
  for (const handler of handlers) {
    const matchingHandler = handler.handlers.find(h => {
      if (h.platform !== platform) return false
      if (nip19Type && h.nip19Type && h.nip19Type !== nip19Type) return false
      return true
    })
    if (matchingHandler) {
      return { handler, url: matchingHandler.url }
    }
  }
  return null
}

// 使用範例
const calendarHandlers = await getHandlersForKind(31923)
console.log('日曆應用:', calendarHandlers.map(h => parseHandler(h)))

// 從關注者獲取推薦
const myFollowing = ['pubkey1', 'pubkey2']
const recommendations = await getFollowingRecommendations(31923, myFollowing)
console.log('關注者推薦:', recommendations.map(r => parseRecommendation(r)))

應用場景

工作流程

最佳實踐

相關 NIP

總結