@chillwhales/lsp3 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chillwhales contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @chillwhales/lsp3
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+LSP3 Universal Profile Metadata — schemas, types, and utilities for reading and validating profile metadata on LUKSO.
+
+## Install
+
+```bash
+pnpm add @chillwhales/lsp3
+```
+
+## Usage
+
+```typescript
+import {
+  lsp3ProfileSchema,
+  getProfileDisplayName,
+  getProfileImageUrl,
+} from "@chillwhales/lsp3";
+
+// Validate raw profile metadata fetched from IPFS / on-chain
+const raw = {
+  name: "Alice",
+  description: "Builder on LUKSO",
+  tags: ["developer"],
+  links: [{ title: "Website", url: "https://alice.dev" }],
+  avatar: [],
+  profileImage: [{ url: "ipfs://QmImg...", width: 256, height: 256 }],
+  backgroundImage: [],
+};
+
+const profile = lsp3ProfileSchema.parse(raw);
+
+// Extract display-ready values
+const name = getProfileDisplayName(profile); // "Alice"
+const imageUrl = getProfileImageUrl(profile, (url) =>
+  url.replace("ipfs://", "https://api.universalprofile.cloud/ipfs/"),
+);
+```
+
+> **Spec:** [LSP-3 Universal Profile Metadata](https://docs.lukso.tech/standards/universal-profile/lsp3-profile-metadata)
+
+## API
+
+Types are exported and available in your editor via TypeScript IntelliSense.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,321 @@
+import { z } from 'zod';
+import * as _chillwhales_lsp2 from '@chillwhales/lsp2';
+import { ImageSize } from '@chillwhales/lsp2';
+
+/**
+ * LSP3 Profile metadata schema
+ * Full metadata structure for Universal Profiles
+ */
+declare const lsp3ProfileSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    tags: z.ZodArray<z.ZodString, "many">;
+    links: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        title: string;
+    }, {
+        url: string;
+        title: string;
+    }>, "many">;
+    avatar: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        fileType: z.ZodString;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }, {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }>, "many">;
+    profileImage: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }>, "many">;
+    backgroundImage: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string | null;
+    description: string | null;
+    tags: string[];
+    links: {
+        url: string;
+        title: string;
+    }[];
+    avatar: {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }[];
+    profileImage: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+    backgroundImage: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+}, {
+    name: string | null;
+    description: string | null;
+    tags: string[];
+    links: {
+        url: string;
+        title: string;
+    }[];
+    avatar: {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }[];
+    profileImage: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+    backgroundImage: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+}>;
+
+/**
+ * LSP3 Type Guards
+ *
+ * Runtime type guards for LSP3 schemas.
+ */
+
+/**
+ * Type guard for LSP3 profile schema
+ */
+declare function isLsp3ProfileSchema(obj: unknown): obj is z.infer<typeof lsp3ProfileSchema>;
+
+/**
+ * LSP3 Inferred Types
+ *
+ * TypeScript types inferred from LSP3 Zod schemas.
+ */
+
+type LSP3Profile = z.infer<typeof lsp3ProfileSchema>;
+
+/**
+ * LSP3 Universal Profile Metadata Utilities
+ *
+ * Pure functions for working with LSP3 profile metadata.
+ */
+
+/**
+ * Extract profile image URL from Universal Profile metadata.
+ * Uses the `profileImage` field and optionally finds the closest image to target dimensions.
+ *
+ * @param metadata - Universal Profile metadata (expects a `profileImage` array)
+ * @param parseUrl - Function to parse/transform the URL (e.g., IPFS parsing)
+ * @param options - Optional target dimensions { width, height }
+ * @returns Parsed URL from `metadata.profileImage` or undefined if no image
+ *
+ * @example
+ * ```typescript
+ * // Get first available profile image
+ * getProfileImageUrl(profile, parseIpfsUrl)
+ *
+ * // Get profile image closest to 64x64
+ * getProfileImageUrl(profile, parseIpfsUrl, { width: 64, height: 64 })
+ * ```
+ */
+declare function getProfileImageUrl(metadata: LSP3Profile, parseUrl: (url: string) => string, options?: Partial<ImageSize>): string | undefined;
+/**
+ * Get display name for Universal Profile.
+ * Falls back to 'Anonymous' if no name.
+ *
+ * @param metadata - Universal Profile metadata
+ * @returns Display name string
+ */
+declare function getProfileDisplayName(metadata: LSP3Profile): string;
+
+export { getProfileDisplayName, getProfileImageUrl, isLsp3ProfileSchema, lsp3ProfileSchema };
+export type { LSP3Profile };

package/dist/index.d.ts

@@ -0,0 +1,321 @@
+import { z } from 'zod';
+import * as _chillwhales_lsp2 from '@chillwhales/lsp2';
+import { ImageSize } from '@chillwhales/lsp2';
+
+/**
+ * LSP3 Profile metadata schema
+ * Full metadata structure for Universal Profiles
+ */
+declare const lsp3ProfileSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    tags: z.ZodArray<z.ZodString, "many">;
+    links: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        title: string;
+    }, {
+        url: string;
+        title: string;
+    }>, "many">;
+    avatar: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        fileType: z.ZodString;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }, {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }>, "many">;
+    profileImage: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }>, "many">;
+    backgroundImage: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        verification: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            data: z.ZodString;
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES, _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8]>;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        }>, z.ZodObject<{
+            method: z.ZodEnum<[_chillwhales_lsp2.VERIFICATION_METHODS.ECDSA]>;
+            data: z.ZodString;
+            source: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }, {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }, {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string | null;
+    description: string | null;
+    tags: string[];
+    links: {
+        url: string;
+        title: string;
+    }[];
+    avatar: {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }[];
+    profileImage: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+    backgroundImage: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+}, {
+    name: string | null;
+    description: string | null;
+    tags: string[];
+    links: {
+        url: string;
+        title: string;
+    }[];
+    avatar: {
+        url: string;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+        fileType: string;
+    }[];
+    profileImage: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+    backgroundImage: {
+        url: string;
+        width: number;
+        height: number;
+        verification: {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_UTF8 | _chillwhales_lsp2.VERIFICATION_METHODS.HASH_KECCAK256_BYTES;
+            data: string;
+        } | {
+            method: _chillwhales_lsp2.VERIFICATION_METHODS.ECDSA;
+            data: string;
+            source: string;
+        };
+    }[];
+}>;
+
+/**
+ * LSP3 Type Guards
+ *
+ * Runtime type guards for LSP3 schemas.
+ */
+
+/**
+ * Type guard for LSP3 profile schema
+ */
+declare function isLsp3ProfileSchema(obj: unknown): obj is z.infer<typeof lsp3ProfileSchema>;
+
+/**
+ * LSP3 Inferred Types
+ *
+ * TypeScript types inferred from LSP3 Zod schemas.
+ */
+
+type LSP3Profile = z.infer<typeof lsp3ProfileSchema>;
+
+/**
+ * LSP3 Universal Profile Metadata Utilities
+ *
+ * Pure functions for working with LSP3 profile metadata.
+ */
+
+/**
+ * Extract profile image URL from Universal Profile metadata.
+ * Uses the `profileImage` field and optionally finds the closest image to target dimensions.
+ *
+ * @param metadata - Universal Profile metadata (expects a `profileImage` array)
+ * @param parseUrl - Function to parse/transform the URL (e.g., IPFS parsing)
+ * @param options - Optional target dimensions { width, height }
+ * @returns Parsed URL from `metadata.profileImage` or undefined if no image
+ *
+ * @example
+ * ```typescript
+ * // Get first available profile image
+ * getProfileImageUrl(profile, parseIpfsUrl)
+ *
+ * // Get profile image closest to 64x64
+ * getProfileImageUrl(profile, parseIpfsUrl, { width: 64, height: 64 })
+ * ```
+ */
+declare function getProfileImageUrl(metadata: LSP3Profile, parseUrl: (url: string) => string, options?: Partial<ImageSize>): string | undefined;
+/**
+ * Get display name for Universal Profile.
+ * Falls back to 'Anonymous' if no name.
+ *
+ * @param metadata - Universal Profile metadata
+ * @returns Display name string
+ */
+declare function getProfileDisplayName(metadata: LSP3Profile): string;
+
+export { getProfileDisplayName, getProfileImageUrl, isLsp3ProfileSchema, lsp3ProfileSchema };
+export type { LSP3Profile };

package/dist/index.mjs

@@ -0,0 +1,36 @@
+import { imageSchema, assetSchema, linkSchema, tagSchema, findBestImage } from '@chillwhales/lsp2';
+import { z } from 'zod';
+
+const lsp3ProfileSchema = z.object({
+  name: z.string({
+    invalid_type_error: "Name must be a string"
+  }).nullable(),
+  description: z.string({
+    invalid_type_error: "Description must be a string"
+  }).nullable(),
+  tags: z.array(tagSchema, {
+    invalid_type_error: "Invalid value, not an array"
+  }),
+  links: z.array(linkSchema),
+  avatar: z.array(assetSchema),
+  profileImage: z.array(imageSchema),
+  backgroundImage: z.array(imageSchema)
+});
+
+function isLsp3ProfileSchema(obj) {
+  const { success } = lsp3ProfileSchema.safeParse(obj);
+  return success;
+}
+
+function getProfileImageUrl(metadata, parseUrl, options) {
+  const profileImage = findBestImage(metadata.profileImage, options);
+  if (profileImage?.url) {
+    return parseUrl(profileImage.url);
+  }
+  return void 0;
+}
+function getProfileDisplayName(metadata) {
+  return metadata.name || "Anonymous";
+}
+
+export { getProfileDisplayName, getProfileImageUrl, isLsp3ProfileSchema, lsp3ProfileSchema };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@chillwhales/lsp3",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "LSP3 Universal Profile Metadata — schemas, types, and utilities for profile metadata on LUKSO",
+  "author": "b00ste",
+  "license": "MIT",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chillwhales/LSPs.git",
+    "directory": "packages/lsp3"
+  },
+  "keywords": [
+    "chillwhales",
+    "lukso",
+    "lsp",
+    "lsp3",
+    "universal-profile",
+    "profile-metadata"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "zod": "^3.24.1",
+    "@chillwhales/lsp2": "0.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "unbuild": "^3.6.1",
+    "vitest": "^4.0.17",
+    "@chillwhales/config": "0.0.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "unbuild --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}