@chillwhales/lsp4 0.1.1 → 0.2.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import * as _chillwhales_lsp2 from '@chillwhales/lsp2';
 import { Image } from '@chillwhales/lsp2';
+import { ImageSize } from '@chillwhales/utils';
 import { z } from 'zod';
 
 /**
@@ -376,6 +377,20 @@ declare const lsp4MetadataSchema: z.ZodObject<{
 
 type LSP4Attribute = z.infer<typeof attributesSchema>;
 type LSP4Metadata = z.infer<typeof lsp4MetadataSchema>;
+/**
+ * Extended NFT metadata with optional token identification fields.
+ *
+ * Adds `tokenName`, `tokenIdFormat`, and `formattedTokenId` on top of
+ * standard LSP4 metadata for use with `getNftDisplayName`.
+ */
+interface NftMetadata extends LSP4Metadata {
+    /** Token collection name (e.g., "CoolCats") */
+    tokenName?: string;
+    /** Format of the token ID (e.g., "NUMBER", "STRING") */
+    tokenIdFormat?: string;
+    /** Pre-formatted token ID for display */
+    formattedTokenId?: string;
+}
 
 /**
  * LSP4 Digital Asset Metadata Utilities
@@ -415,6 +430,63 @@ declare function getImageUrl(options: {
  * @returns Display name string
  */
 declare function getAssetDisplayName(metadata: LSP4Metadata): string;
+/**
+ * Extract avatar image URL from Digital Asset metadata.
+ * Prefers icon, falls back to images. Optionally finds the closest image
+ * to target dimensions.
+ *
+ * @param metadata - Digital Asset (LSP7/LSP8) metadata
+ * @param parseUrl - Function to parse/transform the URL (e.g., IPFS gateway resolution)
+ * @param options - Optional target dimensions `{ width, height }`
+ * @returns Parsed URL or undefined if no image found
+ *
+ * @example
+ * ```typescript
+ * // Get first available image (prefers icon)
+ * getAssetImageUrl(asset, parseIpfsUrl)
+ *
+ * // Get image closest to 128×128
+ * getAssetImageUrl(asset, parseIpfsUrl, { width: 128, height: 128 })
+ * ```
+ */
+declare function getAssetImageUrl(metadata: LSP4Metadata, parseUrl: (url: string) => string, options?: Partial<ImageSize>): string | undefined;
+/**
+ * Extract avatar image URL from NFT metadata.
+ * Prefers images (usually more detailed), falls back to icon.
+ * Optionally finds the closest image to target dimensions.
+ *
+ * @param metadata - NFT (LSP8 token) metadata
+ * @param parseUrl - Function to parse/transform the URL (e.g., IPFS gateway resolution)
+ * @param options - Optional target dimensions `{ width, height }`
+ * @returns Parsed URL or undefined if no image found
+ *
+ * @example
+ * ```typescript
+ * // Get first available image (prefers full images)
+ * getNftImageUrl(nft, parseIpfsUrl)
+ *
+ * // Get image closest to 256×256
+ * getNftImageUrl(nft, parseIpfsUrl, { width: 256, height: 256 })
+ * ```
+ */
+declare function getNftImageUrl(metadata: LSP4Metadata, parseUrl: (url: string) => string, options?: Partial<ImageSize>): string | undefined;
+/**
+ * Get display name for NFT (LSP8 token).
+ * Includes token ID formatting (e.g., "TokenName #123").
+ *
+ * @param metadata - NFT metadata with optional token info
+ * @returns Display name string, possibly with token ID suffix
+ *
+ * @example
+ * ```typescript
+ * getNftDisplayName({ tokenName: "CoolCats", tokenIdFormat: "NUMBER", formattedTokenId: "42" })
+ * // => "CoolCats #42"
+ *
+ * getNftDisplayName({ tokenName: "Art" })
+ * // => "Art"
+ * ```
+ */
+declare function getNftDisplayName(metadata: NftMetadata): string;
 
 /**
  * LSP4 Type Guards
@@ -431,5 +503,5 @@ declare function isAttributesSchema(obj: unknown): obj is z.infer<typeof attribu
  */
 declare function isLsp4MetadataSchema(obj: unknown): obj is z.infer<typeof lsp4MetadataSchema>;
 
-export { attributesSchema, getAssetDisplayName, getImageUrl, isAttributesSchema, isLsp4MetadataSchema, lsp4MetadataSchema };
-export type { LSP4Attribute, LSP4Metadata };
+export { attributesSchema, getAssetDisplayName, getAssetImageUrl, getImageUrl, getNftDisplayName, getNftImageUrl, isAttributesSchema, isLsp4MetadataSchema, lsp4MetadataSchema };
+export type { LSP4Attribute, LSP4Metadata, NftMetadata };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _chillwhales_lsp2 from '@chillwhales/lsp2';
 import { Image } from '@chillwhales/lsp2';
+import { ImageSize } from '@chillwhales/utils';
 import { z } from 'zod';
 
 /**
@@ -376,6 +377,20 @@ declare const lsp4MetadataSchema: z.ZodObject<{
 
 type LSP4Attribute = z.infer<typeof attributesSchema>;
 type LSP4Metadata = z.infer<typeof lsp4MetadataSchema>;
+/**
+ * Extended NFT metadata with optional token identification fields.
+ *
+ * Adds `tokenName`, `tokenIdFormat`, and `formattedTokenId` on top of
+ * standard LSP4 metadata for use with `getNftDisplayName`.
+ */
+interface NftMetadata extends LSP4Metadata {
+    /** Token collection name (e.g., "CoolCats") */
+    tokenName?: string;
+    /** Format of the token ID (e.g., "NUMBER", "STRING") */
+    tokenIdFormat?: string;
+    /** Pre-formatted token ID for display */
+    formattedTokenId?: string;
+}
 
 /**
  * LSP4 Digital Asset Metadata Utilities
@@ -415,6 +430,63 @@ declare function getImageUrl(options: {
  * @returns Display name string
  */
 declare function getAssetDisplayName(metadata: LSP4Metadata): string;
+/**
+ * Extract avatar image URL from Digital Asset metadata.
+ * Prefers icon, falls back to images. Optionally finds the closest image
+ * to target dimensions.
+ *
+ * @param metadata - Digital Asset (LSP7/LSP8) metadata
+ * @param parseUrl - Function to parse/transform the URL (e.g., IPFS gateway resolution)
+ * @param options - Optional target dimensions `{ width, height }`
+ * @returns Parsed URL or undefined if no image found
+ *
+ * @example
+ * ```typescript
+ * // Get first available image (prefers icon)
+ * getAssetImageUrl(asset, parseIpfsUrl)
+ *
+ * // Get image closest to 128×128
+ * getAssetImageUrl(asset, parseIpfsUrl, { width: 128, height: 128 })
+ * ```
+ */
+declare function getAssetImageUrl(metadata: LSP4Metadata, parseUrl: (url: string) => string, options?: Partial<ImageSize>): string | undefined;
+/**
+ * Extract avatar image URL from NFT metadata.
+ * Prefers images (usually more detailed), falls back to icon.
+ * Optionally finds the closest image to target dimensions.
+ *
+ * @param metadata - NFT (LSP8 token) metadata
+ * @param parseUrl - Function to parse/transform the URL (e.g., IPFS gateway resolution)
+ * @param options - Optional target dimensions `{ width, height }`
+ * @returns Parsed URL or undefined if no image found
+ *
+ * @example
+ * ```typescript
+ * // Get first available image (prefers full images)
+ * getNftImageUrl(nft, parseIpfsUrl)
+ *
+ * // Get image closest to 256×256
+ * getNftImageUrl(nft, parseIpfsUrl, { width: 256, height: 256 })
+ * ```
+ */
+declare function getNftImageUrl(metadata: LSP4Metadata, parseUrl: (url: string) => string, options?: Partial<ImageSize>): string | undefined;
+/**
+ * Get display name for NFT (LSP8 token).
+ * Includes token ID formatting (e.g., "TokenName #123").
+ *
+ * @param metadata - NFT metadata with optional token info
+ * @returns Display name string, possibly with token ID suffix
+ *
+ * @example
+ * ```typescript
+ * getNftDisplayName({ tokenName: "CoolCats", tokenIdFormat: "NUMBER", formattedTokenId: "42" })
+ * // => "CoolCats #42"
+ *
+ * getNftDisplayName({ tokenName: "Art" })
+ * // => "Art"
+ * ```
+ */
+declare function getNftDisplayName(metadata: NftMetadata): string;
 
 /**
  * LSP4 Type Guards
@@ -431,5 +503,5 @@ declare function isAttributesSchema(obj: unknown): obj is z.infer<typeof attribu
  */
 declare function isLsp4MetadataSchema(obj: unknown): obj is z.infer<typeof lsp4MetadataSchema>;
 
-export { attributesSchema, getAssetDisplayName, getImageUrl, isAttributesSchema, isLsp4MetadataSchema, lsp4MetadataSchema };
-export type { LSP4Attribute, LSP4Metadata };
+export { attributesSchema, getAssetDisplayName, getAssetImageUrl, getImageUrl, getNftDisplayName, getNftImageUrl, isAttributesSchema, isLsp4MetadataSchema, lsp4MetadataSchema };
+export type { LSP4Attribute, LSP4Metadata, NftMetadata };

package/dist/index.mjs

@@ -1,5 +1,5 @@
+import { findBestImage, isNumeric } from '@chillwhales/utils';
 import { assetSchema, imageSchema, linkSchema } from '@chillwhales/lsp2';
-import { isNumeric } from '@chillwhales/utils';
 import { z } from 'zod';
 
 function getImageUrl(options) {
@@ -17,6 +17,40 @@ function getImageUrl(options) {
 function getAssetDisplayName(metadata) {
   return metadata.name || "Digital Asset";
 }
+function getAssetImageUrl(metadata, parseUrl, options) {
+  const icon = findBestImage(metadata.icon, options);
+  if (icon?.url) {
+    return parseUrl(icon.url);
+  }
+  const allImages = metadata.images?.flat();
+  const image = findBestImage(allImages, options);
+  if (image?.url) {
+    return parseUrl(image.url);
+  }
+  return void 0;
+}
+function getNftImageUrl(metadata, parseUrl, options) {
+  const allImages = metadata.images?.flat();
+  const image = findBestImage(allImages, options);
+  if (image?.url) {
+    return parseUrl(image.url);
+  }
+  const icon = findBestImage(metadata.icon, options);
+  if (icon?.url) {
+    return parseUrl(icon.url);
+  }
+  return void 0;
+}
+function getNftDisplayName(metadata) {
+  const baseName = metadata.tokenName || "NFT";
+  if (metadata.tokenIdFormat === "NUMBER" && metadata.formattedTokenId) {
+    return `${baseName} #${metadata.formattedTokenId}`;
+  }
+  if (metadata.formattedTokenId) {
+    return `${baseName} ${metadata.formattedTokenId}`;
+  }
+  return baseName;
+}
 
 const attributesSchema = z.discriminatedUnion("type", [
   z.object({
@@ -61,4 +95,4 @@ function isLsp4MetadataSchema(obj) {
   return success;
 }
 
-export { attributesSchema, getAssetDisplayName, getImageUrl, isAttributesSchema, isLsp4MetadataSchema, lsp4MetadataSchema };
+export { attributesSchema, getAssetDisplayName, getAssetImageUrl, getImageUrl, getNftDisplayName, getNftImageUrl, isAttributesSchema, isLsp4MetadataSchema, lsp4MetadataSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chillwhales/lsp4",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "LSP4 Digital Asset Metadata — schemas, types, and utilities for LSP7/LSP8 token metadata on LUKSO",
   "author": "b00ste",
@@ -38,8 +38,8 @@
   "sideEffects": false,
   "dependencies": {
     "zod": "^3.24.1",
-    "@chillwhales/lsp2": "0.1.1",
-    "@chillwhales/utils": "0.1.1"
+    "@chillwhales/lsp2": "0.2.0",
+    "@chillwhales/utils": "0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3",