/ 
Net-Nostr-1.003000
/ Net::Nostr::FileMetadata

NAME

Net::Nostr::FileMetadata - NIP-94 File Metadata events

SYNOPSIS

use Net::Nostr::FileMetadata;

# Build a kind 1063 file metadata event
my $event = Net::Nostr::FileMetadata->to_event(
    pubkey   => $pubkey,
    content  => 'A scenic photo',
    url      => 'https://example.com/photo.jpg',
    m        => 'image/jpeg',
    x        => $sha256_hex,
    ox       => $original_sha256_hex,
    dim      => '1920x1080',
    alt      => 'A scenic photo',
    blurhash => 'eVF$^OI',
    fallback => ['https://alt.example.com/photo.jpg'],
);

# Parse file metadata from a kind 1063 event
my $fm = Net::Nostr::FileMetadata->from_event($event);
say $fm->url;       # https://example.com/photo.jpg
say $fm->m;         # image/jpeg
say $fm->dim;       # 1920x1080
say $fm->alt;       # A scenic photo

# Validate a file metadata event
Net::Nostr::FileMetadata->validate($event);

DESCRIPTION

Implements NIP-94 (File Metadata). Provides methods to build kind 1063 file metadata events, parse them, and validate their structure.

Kind 1063 events describe shared files with metadata tags. The content field holds a description or caption. Required tags are url, m (MIME type), x (SHA-256 hash of the file), and ox (SHA-256 hash of the original file before any server transformations).

Optional tags include size, dim, magnet, i, blurhash, thumb, image, summary, alt, fallback (zero or more), and service.

CONSTRUCTOR

new

my $fm = Net::Nostr::FileMetadata->new(
    url  => 'https://example.com/photo.jpg',
    m    => 'image/jpeg',
    x    => $sha256_hex,
    ox   => $original_sha256_hex,
);

Creates a new Net::Nostr::FileMetadata object. All fields are optional. fallback defaults to []. Croaks on unknown arguments. Typically returned by "from_event"; calling new directly is useful for testing.

CLASS METHODS

to_event

my $event = Net::Nostr::FileMetadata->to_event(
    pubkey     => $hex_pubkey,
    content    => 'A scenic photo',
    url        => 'https://example.com/photo.jpg',
    m          => 'image/jpeg',
    x          => $sha256_hex,
    ox         => $original_sha256_hex,
    size       => '1048576',
    dim        => '1920x1080',
    magnet     => 'magnet:?xt=urn:btih:abc',
    i          => 'infohash',
    blurhash   => 'eVF$^OI',
    thumb      => 'https://example.com/thumb.jpg',
    thumb_hash => $thumb_sha256_hex,
    image      => 'https://example.com/preview.jpg',
    image_hash => $preview_sha256_hex,
    summary    => 'excerpt text',
    alt        => 'accessibility description',
    fallback   => ['https://alt.example.com/photo.jpg'],
    service    => 'nip96',
    extra_tags => [['t', 'photo']],
    created_at => time(),
);

Creates a kind 1063 Net::Nostr::Event. url, m, x, and ox are required. x and ox must be 64-character lowercase hex (SHA-256). m must be a lowercase MIME type containing a slash. dim, if provided, must be in <width>x<height> format.

thumb and image accept an optional hash via thumb_hash and image_hash. fallback accepts an arrayref of URLs. extra_tags allows injecting additional tags.

Any remaining arguments (pubkey, content, created_at) are passed through to "new" in Net::Nostr::Event.

from_event

my $fm = Net::Nostr::FileMetadata->from_event($event);

Parses a kind 1063 event into a Net::Nostr::FileMetadata object. Returns undef if the event is not kind 1063.

my $fm = Net::Nostr::FileMetadata->from_event($event);
say $fm->url;
say $fm->m;
say $fm->size;

validate

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

Validates that an event is a well-formed NIP-94 file metadata event. Croaks if the kind is not 1063 or if any required tag (url, m, x, ox) is missing. Returns 1 on success.

eval { Net::Nostr::FileMetadata->validate($event) };
warn "Invalid: $@" if $@;

ACCESSORS

url

File URL.

m

MIME type (e.g. 'image/jpeg'). Must be lowercase.

x

SHA-256 hex hash of the file.

ox

SHA-256 hex hash of the original file before server transformations.

size

File size in bytes (string).

dim

Dimensions in <width>x<height> format (e.g. '1920x1080').

magnet

Magnet URI.

i

Torrent infohash.

blurhash

Blurhash string for loading placeholder.

thumb

Thumbnail URL (same aspect ratio as original).

thumb_hash

SHA-256 hex hash of the thumbnail.

image

Preview image URL (same dimensions as original).

image_hash

SHA-256 hex hash of the preview image.

summary

Text excerpt.

alt

Accessibility description.

fallback

Arrayref of fallback file source URLs.

service

Service type serving the file (e.g. NIP-96).

SEE ALSO

NIP-94, Net::Nostr::MediaAttachment, Net::Nostr, Net::Nostr::Event