Experimental & in-flight

@sandwichfarm/encoded-entities

Unofficial NIP-19 encoded entities. This library provides encoding and decoding functions for various Nostr entity types using bech32 encoding.

Installation

npm install @sandwichfarm/encoded-entities nostr-tools

Note: nostr-tools is a peer dependency and must be installed separately.

Supported Entity Types

• nbunksec - NIP-46 bunker connection info (pubkey, local_key, relays, secret)
• nsite - Nostr site resolution info (relays, servers, pubkey)
• nfilter - Single Nostr filter
• nfilters - Multiple Nostr filters
• nfeed - Combination of filters and relays
• nvite - Nostr invite for new users (relays, to_follow, nsite_pubkeys)
• napp - Nostr app info (type, platforms, pubkey, relays, servers)
• nblob - Blob/file reference (hash, servers, pubkey, optional path)

Usage

Import Options

// Import everything
import * as encodedEntities from '@sandwichfarm/encoded-entities';

// Import specific encoders/decoders
import { encodeNbunksec, decodeNbunksec } from '@sandwichfarm/encoded-entities';

// Import entity objects
import { nbunksec, nsite, nfilter, nfilters, nfeed, nvite, napp, nblob } from '@sandwichfarm/encoded-entities';

// Import types
import { BunkerInfo, Site, Feed, Invite, App, Blob } from '@sandwichfarm/encoded-entities';
// NostrFilter is imported from nostr-tools (peer dependency)

nbunksec - Bunker Connection Info

import { nbunksec, encodeNbunksec, decodeNbunksec } from '@sandwichfarm/encoded-entities';

const bunkerInfo = {
  pubkey: 'a'.repeat(64),
  local_key: 'b'.repeat(64),
  relays: ['wss://relay1.example.com', 'wss://relay2.example.com'],
  secret: 'secretkey...'
};

// Using function interface
const encoded = encodeNbunksec(bunkerInfo);
const decoded = decodeNbunksec(encoded);

// Using object interface
const encoded2 = nbunksec.encode(bunkerInfo);
const decoded2 = nbunksec.decode(encoded2);

nsite - Site Resolution Info

import { nsite, encodeNsite, decodeNsite } from '@sandwichfarm/encoded-entities';

const site = {
  relays: ['wss://relay1.example.com', 'wss://relay2.example.com'],
  servers: ['https://server1.example.com', 'https://server2.example.com'],
  pubkey: 'a'.repeat(64)  // hex string
};

const encoded = nsite.encode(site);
const decoded = nsite.decode(encoded);

nfilter - Single Filter

import { nfilter, encodeNfilter, decodeNfilter } from '@sandwichfarm/encoded-entities';

const filter = {
  ids: ['eventid1', 'eventid2'],
  authors: ['pubkey1'],
  kinds: [1, 30023],
  '#e': ['referenced-event-id'],
  '#p': ['referenced-pubkey'],
  '#d': ['identifier'],  // Custom tags supported
  since: 1234567890,
  until: 1234567899,
  limit: 100,
  search: 'search term'
};

const encoded = nfilter.encode(filter);
const decoded = nfilter.decode(encoded);

nfilters - Multiple Filters

import { nfilters, encodeNfilters, decodeNfilters } from '@sandwichfarm/encoded-entities';

const filters = [
  { kinds: [1], authors: ['pubkey1'], limit: 10 },
  { kinds: [30023], '#d': ['identifier'] }
];

const encoded = nfilters.encode(filters);
const decoded = nfilters.decode(encoded);

nfeed - Filters + Relays

import { nfeed, encodeNfeed, decodeNfeed } from '@sandwichfarm/encoded-entities';

const feed = {
  filters: [
    { kinds: [1], limit: 20 },
    { kinds: [30023], authors: ['pubkey1'] }
  ],
  relays: ['wss://relay1.example.com', 'wss://relay2.example.com']
};

const encoded = nfeed.encode(feed);
const decoded = nfeed.decode(encoded);

nvite - Invite for New Users

import { nvite, encodeNvite, decodeNvite } from '@sandwichfarm/encoded-entities';

const invite = {
  relays: ['wss://relay1.example.com', 'wss://relay2.example.com'],
  to_follow: ['pubkey1', 'pubkey2'],  // Pubkeys to follow
  nsite_pubkeys: ['pubkey1', 'pubkey2'],  // Pubkeys of nsite entities
  invitor_pubkey: 'invitor_pubkey_hex',
  invitee_name: 'your boy frank'  // optional
};

const encoded = nvite.encode(invite);
const decoded = nvite.decode(encoded);

napp - App Information

import { napp, encodeNapp, decodeNapp } from '@sandwichfarm/encoded-entities';

const app = {
  type: 'web',  // or 'native'
  platforms: ['ios', 'android', 'macos', 'windows', 'linux'],
  pubkey: 'app_pubkey_hex',
  relays: ['wss://relay1.example.com', 'wss://relay2.example.com'],
  servers: ['https://app.example.com', 'https://api.example.com']
};

const encoded = napp.encode(app);
const decoded = napp.decode(encoded);

nblob - Blob/File Reference

import { nblob, encodeNblob, decodeNblob } from '@sandwichfarm/encoded-entities';

const blob = {
  hash: 'sha256_hash_hex',  // Content hash
  servers: ['https://blob1.example.com', 'https://blob2.example.com'],
  pubkey: 'publisher_pubkey_hex',
  path: '/uploads/document.pdf'  // optional
};

const encoded = nblob.encode(blob);
const decoded = nblob.decode(encoded);

Type Definitions

interface BunkerInfo {
  pubkey: string;      // hex string
  local_key: string;   // hex string
  relays: string[];
  secret?: string;
}

interface Site {
  relays: string[];      // At least one required
  servers: string[];     // At least one required  
  pubkey: string;        // Hex string
}

// NostrFilter type is imported from nostr-tools
// See: https://github.com/nbd-wtf/nostr-tools

interface Feed {
  filters: Filter[];     // Filter type from nostr-tools
  relays: string[];
}

interface Invite {
  relays: string[];
  to_follow: string[];      // Pubkeys to follow
  nsite_pubkeys: string[];  // Pubkeys of nsite entities
  invitor_pubkey: string;   // Hex string
  invitee_name?: string;    // Optional name for invitee
}

interface App {
  type: 'web' | 'native';
  platforms: string[];   // e.g., ['ios', 'android', 'macos', 'windows', 'linux']
  pubkey: string;        // Hex string
  relays: string[];
  servers: string[];
}

interface Blob {
  path?: string;         // Optional file path or identifier
  hash: string;          // Content hash (hex string)
  servers: string[];     // Server URLs where blob is hosted
  pubkey: string;        // Publisher pubkey (hex string)
}

License

MIT