/ 
Net-Nostr-1.003000
/ Net::Nostr::Metadata

NAME

Net::Nostr::Metadata - NIP-24 Extra Metadata Fields and Tags

SYNOPSIS

use Net::Nostr::Metadata;

# Create a profile metadata event (kind 0)
my $event = Net::Nostr::Metadata->to_event(
    pubkey       => $hex_pubkey,
    name         => 'alice',
    display_name => 'Alice in Wonderland',
    about        => 'Nostr enthusiast',
    picture      => 'https://example.com/avatar.jpg',
    website      => 'https://alice.example.com',
    banner       => 'https://example.com/banner.jpg',
    bot          => JSON::false,
    birthday     => { year => 1990, month => 6, day => 15 },
);

# Parse metadata from an event
my $meta = Net::Nostr::Metadata->from_event($event);
say $meta->name;          # alice
say $meta->display_name;  # Alice in Wonderland

# Validate
Net::Nostr::Metadata->validate($event);

# Standard tag helpers
my $tag = Net::Nostr::Metadata->hashtag_tag('NoStr');  # ['t', 'nostr']
my $url = Net::Nostr::Metadata->url_tag('https://example.com');
my $title = Net::Nostr::Metadata->title_tag('My Event');
my $ext = Net::Nostr::Metadata->external_id_tag('github:torvalds');

DESCRIPTION

Implements NIP-24 (Extra Metadata Fields and Tags). Provides a builder and parser for kind 0 metadata events with the extra fields defined by this NIP, plus standard tag helper methods.

Kind 0 is a replaceable event. The content is a stringified JSON object containing the user's profile metadata. NIP-01 defines name, about, and picture. This NIP adds:

  • display_name - an alternative, bigger name with richer characters

  • website - a web URL related to the event author

  • banner - a URL to a wide (~1024x768) background image

  • bot - a boolean indicating automated content

  • birthday - an object with optional year, month, day fields

name should always be set regardless of display_name.

Deprecated fields

When parsing, the deprecated displayName field is mapped to display_name, and username is mapped to name. The canonical field takes precedence if both are present. These deprecated fields are never emitted by "to_event".

Standard tags

NIP-24 defines standard tag meanings across event kinds:

  • t - hashtag (value MUST be lowercase)

  • r - a web URL the event refers to

  • title - name of sets, calendar/live events, or listings

  • i - external ID (see NIP-73)

CONSTRUCTOR

new

my $meta = Net::Nostr::Metadata->new(
    name         => 'alice',
    display_name => 'Alice',
);

Creates a new Net::Nostr::Metadata object. All fields are optional. Croaks on unknown arguments. Typically returned by "from_event".

CLASS METHODS

to_event

my $event = Net::Nostr::Metadata->to_event(
    pubkey       => $hex_pubkey,          # required
    name         => 'alice',              # recommended
    display_name => 'Alice',              # optional
    about        => 'Hello',              # optional
    picture      => 'https://...',        # optional
    website      => 'https://...',        # optional
    banner       => 'https://...',        # optional
    bot          => JSON::true,           # optional
    birthday     => { year => 1990 },     # optional
    created_at   => time(),               # optional
);

Creates a kind 0 metadata Net::Nostr::Event. The metadata fields are serialized as a JSON object in the event content. Only provided fields are included in the JSON. Any remaining arguments are passed through to "new" in Net::Nostr::Event.

from_event

my $meta = Net::Nostr::Metadata->from_event($event);

Parses a kind 0 event into a Net::Nostr::Metadata object. Returns undef if the event kind is not 0. Handles deprecated field names (displayName -> display_name, username -> name). Unknown fields in the JSON are silently ignored (other NIPs define additional fields like nip05, lud16, etc.).

validate

Net::Nostr::Metadata->validate($event);

Validates a kind 0 metadata event. Croaks if the kind is not 0 or the content is not valid JSON. Returns 1 on success.

hashtag_tag

my $tag = Net::Nostr::Metadata->hashtag_tag('NoStr');  # ['t', 'nostr']

Returns a t tag arrayref. The value is lowercased per the spec requirement that hashtag values MUST be lowercase.

url_tag

my $tag = Net::Nostr::Metadata->url_tag('https://example.com');

Returns an r tag arrayref for a web URL the event refers to.

title_tag

my $tag = Net::Nostr::Metadata->title_tag('My Event');

Returns a title tag arrayref.

external_id_tag

my $tag = Net::Nostr::Metadata->external_id_tag('github:torvalds');

Returns an i tag arrayref for an external ID the event refers to. See NIP-73 for external ID formats.

ACCESSORS

name

The user's name (NIP-01). Should always be set.

display_name

An alternative, bigger name with richer characters than name.

about

A description of the user.

picture

A URL to the user's avatar image.

website

A web URL related to the user.

A URL to a wide (~1024x768) background image for the profile.

bot

A boolean (JSON::true/JSON::false) indicating the content is entirely or partially automated.

birthday

A hashref with optional year, month, and day keys representing the user's birth date. Each field MAY be omitted.

SEE ALSO

NIP-24, Net::Nostr, Net::Nostr::Event