xmatter 0.0.0 → 0.10.3

package/client.d.ts

@@ -0,0 +1,43 @@
+import type { Frontmatter } from "./schema.js";
+export type { Frontmatter };
+export declare class XmatterClient {
+    private readonly namespace;
+    private readonly baseUrl;
+    private readonly cache;
+    constructor(namespace: string, baseUrl?: string | URL, cacheSize?: number);
+    /**
+     * Fetch `/{namespace}/{chainId}/{prefix}/index.txt` and return the entries.
+     * Returns full addresses if <=256 matches, otherwise returns next-byte sub-prefixes.
+     * Results are cached with TTL from the response Cache-Control header.
+     */
+    getIndex(chainId: string, prefix: string): Promise<string[]>;
+    /**
+     * Check if an address exists by walking the index prefix tree in 2-byte steps.
+     * Fetches progressively longer prefixes until entries resolve to full addresses,
+     * then checks for an exact match.
+     */
+    has(chainId: string, address: string): Promise<boolean>;
+    /**
+     * Fetch `/{namespace}/{chainId}/{address}/frontmatter.json` which returns
+     * parsed YAML frontmatter from the address's README.md.
+     * Checks existence via the index first to avoid unnecessary requests.
+     */
+    getFrontmatter(chainId: string, address: string): Promise<Frontmatter | undefined>;
+    /**
+     * Build the URL for `/{namespace}/{chainId}/{address}/icon` which serves
+     * the original image (svg/png/jpg) if <25KB, otherwise converts to 256x256 WebP.
+     * Checks existence via the index first, returning undefined for missing addresses.
+     */
+    getIconUrl(chainId: string, address: string): Promise<URL | undefined>;
+    /**
+     * Build the URL for `/{namespace}/{chainId}/{address}/icon.webp` which always
+     * converts the original icon (svg/png/jpg) to 256x256 WebP.
+     * Checks existence via the index first, returning undefined for missing addresses.
+     */
+    getIconWebpUrl(chainId: string, address: string): Promise<URL | undefined>;
+}
+export declare class XmatterError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+//# sourceMappingURL=client.d.ts.map

package/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;gBAEvC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,GAAG,GAA2B,EAAE,SAAS,GAAE,MAAa;IAMtG;;;;OAIG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBlE;;;;OAIG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB7D;;;;OAIG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAWxF;;;;OAIG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC;IAK5E;;;;OAIG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC;CAIjF;AAOD,qBAAa,YAAa,SAAQ,KAAK;aAEnB,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;CAIlB"}

package/client.js

@@ -0,0 +1,97 @@
+import { LRUCache } from "lru-cache";
+export class XmatterClient {
+    namespace;
+    baseUrl;
+    cache;
+    constructor(namespace, baseUrl = "https://xmatter.org", cacheSize = 4096) {
+        this.namespace = namespace;
+        this.baseUrl = new URL(baseUrl);
+        this.cache = new LRUCache({ max: cacheSize });
+    }
+    /**
+     * Fetch `/{namespace}/{chainId}/{prefix}/index.txt` and return the entries.
+     * Returns full addresses if <=256 matches, otherwise returns next-byte sub-prefixes.
+     * Results are cached with TTL from the response Cache-Control header.
+     */
+    async getIndex(chainId, prefix) {
+        const key = `${chainId}/${prefix.toLowerCase()}`;
+        const cached = this.cache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const res = await fetch(new URL(`/${this.namespace}/${chainId}/${prefix}/index.txt`, this.baseUrl));
+        if (!res.ok) {
+            throw new XmatterError(res.status, await res.text());
+        }
+        const text = await res.text();
+        const entries = text === "" ? [] : text.split("\n");
+        const ttl = parseMaxAge(res.headers.get("cache-control"));
+        this.cache.set(key, entries, { ttl });
+        return entries;
+    }
+    /**
+     * Check if an address exists by walking the index prefix tree in 2-byte steps.
+     * Fetches progressively longer prefixes until entries resolve to full addresses,
+     * then checks for an exact match.
+     */
+    async has(chainId, address) {
+        const lower = address.toLowerCase();
+        for (let len = 2; len < lower.length; len += 2) {
+            const prefix = lower.slice(0, len);
+            const entries = await this.getIndex(chainId, prefix);
+            if (entries.length === 0)
+                return false;
+            const first = entries[0].toLowerCase();
+            if (first.length === 42) {
+                return entries.some((e) => e.toLowerCase() === lower);
+            }
+        }
+        return false;
+    }
+    /**
+     * Fetch `/{namespace}/{chainId}/{address}/frontmatter.json` which returns
+     * parsed YAML frontmatter from the address's README.md.
+     * Checks existence via the index first to avoid unnecessary requests.
+     */
+    async getFrontmatter(chainId, address) {
+        if (!(await this.has(chainId, address)))
+            return undefined;
+        const res = await fetch(new URL(`/${this.namespace}/${chainId}/${address}/frontmatter.json`, this.baseUrl));
+        if (res.status === 404)
+            return undefined;
+        if (!res.ok) {
+            throw new XmatterError(res.status, await res.text());
+        }
+        return res.json();
+    }
+    /**
+     * Build the URL for `/{namespace}/{chainId}/{address}/icon` which serves
+     * the original image (svg/png/jpg) if <25KB, otherwise converts to 256x256 WebP.
+     * Checks existence via the index first, returning undefined for missing addresses.
+     */
+    async getIconUrl(chainId, address) {
+        if (!(await this.has(chainId, address)))
+            return undefined;
+        return new URL(`/${this.namespace}/${chainId}/${address}/icon`, this.baseUrl);
+    }
+    /**
+     * Build the URL for `/{namespace}/{chainId}/{address}/icon.webp` which always
+     * converts the original icon (svg/png/jpg) to 256x256 WebP.
+     * Checks existence via the index first, returning undefined for missing addresses.
+     */
+    async getIconWebpUrl(chainId, address) {
+        if (!(await this.has(chainId, address)))
+            return undefined;
+        return new URL(`/${this.namespace}/${chainId}/${address}/icon.webp`, this.baseUrl);
+    }
+}
+function parseMaxAge(header) {
+    const match = header?.match(/max-age=(\d+)/);
+    return match ? parseInt(match[1], 10) * 1000 : 30 * 60 * 1000;
+}
+export class XmatterError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}

package/next/client.d.ts

@@ -0,0 +1,20 @@
+import { type ImageProps } from "next/image";
+import { type ReactNode } from "react";
+export type XmatterIconProps = {
+    namespace: string;
+    chainId: string;
+    address: string;
+    fallback: ReactNode;
+    baseUrl?: string;
+} & Omit<ImageProps, "src" | "onError">;
+export type IconWithFallbackProps = {
+    fallback: ReactNode;
+} & Omit<ImageProps, "onError">;
+export declare function IconWithFallback({ fallback, ...props }: IconWithFallbackProps): ReactNode;
+export declare function XmatterIcon({ namespace, chainId, address, fallback, baseUrl, ...props }: XmatterIconProps): ReactNode;
+export declare const RemotePattern: {
+    readonly protocol: "https";
+    readonly hostname: "xmatter.org";
+    readonly pathname: "/*/*/*/icon";
+};
+//# sourceMappingURL=client.d.ts.map

package/next/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["client.tsx"],"names":[],"mappings":"AAEA,OAAc,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,OAAO,CAAC;AAEjD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC;AAExC,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAEhC,wBAAgB,gBAAgB,CAAC,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,qBAAqB,GAAG,SAAS,CAQzF;AAED,wBAAgB,WAAW,CAAC,EAC1B,SAAS,EACT,OAAO,EACP,OAAO,EACP,QAAQ,EACR,OAA+B,EAC/B,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CAE9B;AAED,eAAO,MAAM,aAAa;;;;CAIhB,CAAC"}

package/next/client.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import Image from "next/image";
+import { useState } from "react";
+export function IconWithFallback({ fallback, ...props }) {
+    const [error, setError] = useState(false);
+    if (error) {
+        return fallback;
+    }
+    return _jsx(Image, { onError: () => setError(true), ...props });
+}
+export function XmatterIcon({ namespace, chainId, address, fallback, baseUrl = "https://xmatter.org", ...props }) {
+    return _jsx(IconWithFallback, { src: `${baseUrl}/${namespace}/${chainId}/${address}/icon`, fallback: fallback, ...props });
+}
+export const RemotePattern = {
+    protocol: "https",
+    hostname: "xmatter.org",
+    pathname: "/*/*/*/icon",
+};

package/next/server.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import type { XmatterClient } from "../client.js";
+import { type IconWithFallbackProps } from "./client.js";
+export type XmatterIconProps = {
+    client: XmatterClient;
+    chainId: string;
+    address: string;
+} & Omit<IconWithFallbackProps, "src">;
+export declare function XmatterIcon({ client, chainId, address, fallback, ...props }: XmatterIconProps): Promise<ReactNode>;
+//# sourceMappingURL=server.d.ts.map

package/next/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["server.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAC;AAEvC,wBAAsB,WAAW,CAAC,EAChC,MAAM,EACN,OAAO,EACP,OAAO,EACP,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAOvC"}

package/next/server.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { IconWithFallback } from "./client.js";
+export async function XmatterIcon({ client, chainId, address, fallback, ...props }) {
+    const url = await client.getIconUrl(chainId, address);
+    if (!url) {
+        return fallback;
+    }
+    return _jsx(IconWithFallback, { src: url.toString(), fallback: fallback, ...props });
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "xmatter",
-  "version": "0.0.0",
+  "version": "0.10.3",
   "private": false,
-  "files": []
-}
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fuxingloh/xmatter",
+    "directory": "packages/xmatter"
+  },
+  "type": "module",
+  "files": [
+    "**/*.d.ts",
+    "**/*.d.ts.map",
+    "**/*.js"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "tsc --build --clean"
+  },
+  "lint-staged": {
+    "*": [
+      "prettier --write --ignore-unknown"
+    ]
+  },
+  "dependencies": {
+    "lru-cache": "^11.2.5",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/react": "^19"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  }
+}

package/schema.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+export declare const FrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    provenance: z.ZodString;
+    standards: z.ZodArray<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    links: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodURL;
+    }, z.core.$strip>>>;
+    symbol: z.ZodOptional<z.ZodString>;
+    decimals: z.ZodOptional<z.ZodNumber>;
+    icon: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const XmatterSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        provenance: z.ZodString;
+        standards: z.ZodArray<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        links: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodURL;
+        }, z.core.$strip>>>;
+        symbol: z.ZodOptional<z.ZodString>;
+        decimals: z.ZodOptional<z.ZodNumber>;
+        icon: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    content: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Frontmatter = z.infer<typeof FrontmatterSchema>;
+export type XmatterFile = z.infer<typeof XmatterSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBA8B5B,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;iBAGxB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/schema.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+export const FrontmatterSchema = z.object({
+    name: z
+        .string()
+        .min(1)
+        .regex(/^(?!\s)(?!.*\s$).*$/)
+        .describe("Name of the token"),
+    description: z.string().optional(),
+    provenance: z.string().describe("Where did this entry come from?"),
+    standards: z.array(z.string()),
+    tags: z.array(z.string()).optional(),
+    links: z
+        .array(z.object({
+        name: z.string(),
+        url: z.url(),
+    }))
+        .optional(),
+    symbol: z
+        .string()
+        .min(1)
+        .regex(/^(?!\s)(?!.*\s$).*$/)
+        .optional(),
+    decimals: z.number().int().min(0).max(256).optional(),
+    icon: z.string().optional().describe("Primary icon for this entry."),
+    color: z
+        .string()
+        .regex(/^#[0-9a-f]{6}$/i)
+        .optional()
+        .describe("Primary color for this entry based on its icon."),
+});
+export const XmatterSchema = z.object({
+    data: FrontmatterSchema,
+    content: z.string().optional(),
+});