@highlightxyz/sdk 0.3.0 → 0.5.0

package/lib/v1/media.d.ts

@@ -1,4 +1,138 @@
-import { type MediaAsset, StorageRole } from "./gen/types.gen.js";
+import { type MediaAsset, type MediaStorageLocation, StorageRole } from "./gen/types.gen.js";
+export declare const MEDIA_IMAGE_VARIANT_QUERY_PARAMETER = "v";
+export declare const MEDIA_IMAGE_MAX_INPUT_BYTES = 20000000;
+export type MediaHashSource = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+/**
+ * Compute the upload contract's canonical SHA-256 without collecting the
+ * complete file in memory. Browser callers pass `File.stream()`; Node callers
+ * can pass `createReadStream(path)` directly.
+ */
+export declare const sha256MediaContent: (source: MediaHashSource, options?: {
+    signal?: AbortSignal | undefined;
+    onProgress?: ((bytesHashed: number) => void) | undefined;
+} | undefined) => Promise<`sha256:${string}`>;
+export type MediaImageVariantDefinition = {
+    queryValue: string;
+    width: number;
+    height?: number;
+    fit: "cover" | "scale-down";
+    quality: number;
+    responsive: boolean;
+};
+/**
+ * Public, versioned image transformation contract shared by the delivery
+ * Worker and SDK consumers. Existing query values and dimensions are immutable;
+ * a changed transform must use a new query value.
+ */
+export declare const MEDIA_IMAGE_VARIANTS: {
+    readonly avatar: {
+        readonly queryValue: "avatar-v1";
+        readonly width: 256;
+        readonly height: 256;
+        readonly fit: "cover";
+        readonly quality: 75;
+        readonly responsive: false;
+    };
+    readonly thumb: {
+        readonly queryValue: "thumb-v1";
+        readonly width: 240;
+        readonly height: 240;
+        readonly fit: "cover";
+        readonly quality: 75;
+        readonly responsive: false;
+    };
+    readonly small: {
+        readonly queryValue: "small-v1";
+        readonly width: 320;
+        readonly fit: "scale-down";
+        readonly quality: 78;
+        readonly responsive: true;
+    };
+    readonly card: {
+        readonly queryValue: "card-v1";
+        readonly width: 640;
+        readonly height: 640;
+        readonly fit: "cover";
+        readonly quality: 80;
+        readonly responsive: false;
+    };
+    readonly preview: {
+        readonly queryValue: "preview-v1";
+        readonly width: 960;
+        readonly fit: "scale-down";
+        readonly quality: 82;
+        readonly responsive: true;
+    };
+    readonly hero: {
+        readonly queryValue: "hero-v1";
+        readonly width: 1600;
+        readonly fit: "scale-down";
+        readonly quality: 85;
+        readonly responsive: true;
+    };
+    readonly og: {
+        readonly queryValue: "og-v1";
+        readonly width: 1200;
+        readonly height: 630;
+        readonly fit: "cover";
+        readonly quality: 85;
+        readonly responsive: false;
+    };
+    readonly full: {
+        readonly queryValue: "full-v1";
+        readonly width: 4096;
+        readonly fit: "scale-down";
+        readonly quality: 90;
+        readonly responsive: true;
+    };
+};
+export type MediaImageVariant = keyof typeof MEDIA_IMAGE_VARIANTS;
+export declare const RESPONSIVE_MEDIA_IMAGE_VARIANTS: readonly ["small", "preview", "hero", "full"];
+export declare const isMediaImageContentType: (value: string | null | undefined) => boolean;
+export declare const mediaImageVariantFromQuery: (value: string) => MediaImageVariantDefinition | null;
+export declare const mediaImageVariantUrl: (sourceUrl: string, variant: "avatar" | "card" | "full" | "hero" | "og" | "preview" | "small" | "thumb") => string;
+export declare const responsiveMediaImageVariants: (target: "avatar" | "card" | "full" | "hero" | "og" | "preview" | "small" | "thumb") => readonly ("avatar" | "card" | "full" | "hero" | "og" | "preview" | "small" | "thumb")[];
+/**
+ * True only for public URLs owned by Highlight's image-capable delivery
+ * Worker. The localhost forms mirror the Worker's explicit development
+ * namespaces.
+ */
+export declare const isHighlightMediaDeliveryUrl: (value: string, hosts?: MediaDeliveryHosts) => boolean;
+/**
+ * Client-side preflight for requesting a named image variant. A zero file size
+ * is currently the legacy importer's "unknown" sentinel; the delivery Worker
+ * still validates the actual R2 Content-Length before invoking Images.
+ */
+export declare const isMediaImageTransformable: (media: MediaAsset, source: Pick<MediaStorageLocation, "provider"> & {
+    url: string;
+}, hosts?: MediaDeliveryHosts) => boolean;
+/**
+ * Public hosts used to turn a storage location into a URL. Fetch them from
+ * `config.mediaHosts` so a deployment can move a host without every consumer
+ * shipping a new SDK; the defaults below are production and exist only so
+ * simple consumers work without a config round-trip.
+ */
+export type MediaDeliveryHosts = {
+    assets: string;
+    metadata: string;
+    legacyAssets: string;
+    arweaveGateway: string;
+    ipfsGateway: string;
+};
+export declare const DEFAULT_MEDIA_DELIVERY_HOSTS: MediaDeliveryHosts;
+/**
+ * The URL to fetch a media location from.
+ *
+ * R2 URLs are composed from the asset's own identity — a File is `/{mediaId}`,
+ * a directory child is `/{parentId}/{path}` — never by parsing the storage key.
+ * That is why a stored key can change shape without any URL changing, and why
+ * assets written under older key layouts resolve identically.
+ *
+ * This answers "what should the browser fetch right now". It is deliberately
+ * not the backend's `artifactUri`, which answers "what immutable URI do we bake
+ * into an on-chain document" — Archive-first and permanent.
+ */
+export declare const mediaUrl: (media: Pick<MediaAsset, "id" | "kind" | "parentId" | "path">, location: Pick<MediaStorageLocation, "provider" | "reference">, hosts?: MediaDeliveryHosts) => string | null;
 /**
  * Resolve the preferred public URL for a media asset. Replaces the old
  * `MediaAsset.url` field — the preference is now explicit and opt-in rather
@@ -9,6 +143,7 @@ import { type MediaAsset, StorageRole } from "./gen/types.gen.js";
  */
 export declare const resolveMediaUrl: (media: MediaAsset | null | undefined, options?: {
     prefer?: StorageRole[] | StorageRole | undefined;
+    hosts?: MediaDeliveryHosts | undefined;
 } | undefined) => string | null;
 /**
  * Resolve the renderable URL for a generative code bundle (a Directory media
@@ -27,5 +162,6 @@ export declare const resolveMediaUrl: (media: MediaAsset | null | undefined, opt
 export declare const resolveRenderUrl: (media: MediaAsset | null | undefined, options?: {
     entryPath?: string | undefined;
     params?: Record<string, string> | undefined;
+    hosts?: MediaDeliveryHosts | undefined;
 } | undefined) => string | null;
 //# sourceMappingURL=media.d.ts.map

package/lib/v1/media.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../src/v1/media.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,UAAU,EAGf,WAAW,EACZ,MAAM,oBAAoB,CAAC;AAwB5B;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;+BAW3B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB;;;+BAuB5B,CAAC"}
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../src/v1/media.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,oBAAoB,EAIzB,WAAW,EACZ,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,mCAAmC,MAAM,CAAC;AACvD,eAAO,MAAM,2BAA2B,WAAa,CAAC;AAEtD,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;AAKrF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;6CAkC9B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,OAAO,GAAG,YAAY,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D+B,CAAC;AAEjE,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAElE,eAAO,MAAM,+BAA+B,+CAKK,CAAC;AAclD,eAAO,MAAM,uBAAuB,+CAGnC,CAAC;AAEF,eAAO,MAAM,0BAA0B,uDAItC,CAAC;AAEF,eAAO,MAAM,oBAAoB,oHAOhC,CAAC;AAEF,eAAO,MAAM,4BAA4B,iLAQxC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,wDAmBvC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;yCAgBrC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,kBAM1C,CAAC;AAIF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,6KA2BpB,CAAC;AAwBF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;+BAY3B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB;;;;+BA0B5B,CAAC"}

package/lib/v1/media.js

@@ -1,11 +1,241 @@
 // Hand-written media URL helpers (not generated — do not place under ./gen).
 //
-// The backend resolves each storage location to an absolute `url` (it owns the
-// host config + R2 key layout). These helpers do the *selection & composition*
-// on top of those resolved per-location URLs: picking a location by role and,
-// for bundle directories, addressing the entry file. They never parse a
-// `reference` or know anything about deployment hosts.
-import { LocationStatus, StorageRole, } from "./gen/types.gen.js";
+// The API returns storage locations as `provider` + `reference`; turning those
+// into a URL is the consumer's job, and this is where it happens. A location's
+// URL is composed from the asset's own identity, so the backend's storage key
+// layout is invisible here and assets written under older layouts resolve
+// identically.
+//
+// These helpers answer "what should the client fetch right now" — Origin-first,
+// with the caller free to layer gateway failover on top. The backend's
+// `artifactUri` answers a different question ("what immutable URI do we bake
+// into an on-chain document") and is deliberately not shared with this path.
+import { sha256 } from "@noble/hashes/sha2";
+import { bytesToHex } from "@noble/hashes/utils";
+import { LocationStatus, MediaKind, StorageProvider, StorageRole, } from "./gen/types.gen.js";
+export const MEDIA_IMAGE_VARIANT_QUERY_PARAMETER = "v";
+export const MEDIA_IMAGE_MAX_INPUT_BYTES = 20_000_000;
+const isReadableStream = (source) => "getReader" in source;
+/**
+ * Compute the upload contract's canonical SHA-256 without collecting the
+ * complete file in memory. Browser callers pass `File.stream()`; Node callers
+ * can pass `createReadStream(path)` directly.
+ */
+export const sha256MediaContent = async (source, options) => {
+    const hasher = sha256.create();
+    let bytesHashed = 0;
+    const update = (chunk) => {
+        if (options?.signal?.aborted) {
+            throw new DOMException("Hashing aborted.", "AbortError");
+        }
+        hasher.update(chunk);
+        bytesHashed += chunk.byteLength;
+        options?.onProgress?.(bytesHashed);
+    };
+    if (isReadableStream(source)) {
+        const reader = source.getReader();
+        try {
+            while (true) {
+                const result = await reader.read();
+                if (result.done)
+                    break;
+                update(result.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    else {
+        for await (const chunk of source)
+            update(chunk);
+    }
+    return `sha256:${bytesToHex(hasher.digest())}`;
+};
+/**
+ * Public, versioned image transformation contract shared by the delivery
+ * Worker and SDK consumers. Existing query values and dimensions are immutable;
+ * a changed transform must use a new query value.
+ */
+export const MEDIA_IMAGE_VARIANTS = {
+    avatar: {
+        queryValue: "avatar-v1",
+        width: 256,
+        height: 256,
+        fit: "cover",
+        quality: 75,
+        responsive: false,
+    },
+    thumb: {
+        queryValue: "thumb-v1",
+        width: 240,
+        height: 240,
+        fit: "cover",
+        quality: 75,
+        responsive: false,
+    },
+    small: {
+        queryValue: "small-v1",
+        width: 320,
+        fit: "scale-down",
+        quality: 78,
+        responsive: true,
+    },
+    card: {
+        queryValue: "card-v1",
+        width: 640,
+        height: 640,
+        fit: "cover",
+        quality: 80,
+        responsive: false,
+    },
+    preview: {
+        queryValue: "preview-v1",
+        width: 960,
+        fit: "scale-down",
+        quality: 82,
+        responsive: true,
+    },
+    hero: {
+        queryValue: "hero-v1",
+        width: 1600,
+        fit: "scale-down",
+        quality: 85,
+        responsive: true,
+    },
+    og: {
+        queryValue: "og-v1",
+        width: 1200,
+        height: 630,
+        fit: "cover",
+        quality: 85,
+        responsive: false,
+    },
+    full: {
+        queryValue: "full-v1",
+        width: 4096,
+        fit: "scale-down",
+        quality: 90,
+        responsive: true,
+    },
+};
+export const RESPONSIVE_MEDIA_IMAGE_VARIANTS = [
+    "small",
+    "preview",
+    "hero",
+    "full",
+];
+const SUPPORTED_IMAGE_CONTENT_TYPES = new Set([
+    "image/avif",
+    "image/gif",
+    "image/heic",
+    "image/heif",
+    "image/jpeg",
+    "image/jpg",
+    "image/png",
+    "image/webp",
+]);
+const MODERN_ASSET_PATH = /^\/[0-9a-fA-F-]+(?:\/.*)?$/;
+export const isMediaImageContentType = (value) => {
+    const contentType = value?.split(";")[0]?.trim().toLowerCase();
+    return contentType !== undefined && SUPPORTED_IMAGE_CONTENT_TYPES.has(contentType);
+};
+export const mediaImageVariantFromQuery = (value) => {
+    return (Object.values(MEDIA_IMAGE_VARIANTS).find((variant) => variant.queryValue === value) ?? null);
+};
+export const mediaImageVariantUrl = (sourceUrl, variant) => {
+    const url = new URL(sourceUrl);
+    url.searchParams.set(MEDIA_IMAGE_VARIANT_QUERY_PARAMETER, MEDIA_IMAGE_VARIANTS[variant].queryValue);
+    return url.toString();
+};
+export const responsiveMediaImageVariants = (target) => {
+    const targetDefinition = MEDIA_IMAGE_VARIANTS[target];
+    if (!targetDefinition.responsive)
+        return [];
+    return RESPONSIVE_MEDIA_IMAGE_VARIANTS.filter((variant) => MEDIA_IMAGE_VARIANTS[variant].width <= targetDefinition.width);
+};
+/**
+ * True only for public URLs owned by Highlight's image-capable delivery
+ * Worker. The localhost forms mirror the Worker's explicit development
+ * namespaces.
+ */
+export const isHighlightMediaDeliveryUrl = (value, hosts = DEFAULT_MEDIA_DELIVERY_HOSTS) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return false;
+    if (value.startsWith(`${hosts.assets}/`)) {
+        return MODERN_ASSET_PATH.test(value.slice(hosts.assets.length));
+    }
+    if (value.startsWith(`${hosts.legacyAssets}/`)) {
+        return value.slice(hosts.legacyAssets.length).startsWith("/main/");
+    }
+    return false;
+};
+/**
+ * Client-side preflight for requesting a named image variant. A zero file size
+ * is currently the legacy importer's "unknown" sentinel; the delivery Worker
+ * still validates the actual R2 Content-Length before invoking Images.
+ */
+export const isMediaImageTransformable = (media, source, hosts = DEFAULT_MEDIA_DELIVERY_HOSTS) => {
+    const sizeIsEligible = media.fileSize === null ||
+        media.fileSize === 0 ||
+        media.fileSize <= MEDIA_IMAGE_MAX_INPUT_BYTES;
+    return (source.provider === StorageProvider.R2 &&
+        media.kind === MediaKind.File &&
+        isMediaImageContentType(media.mimeType) &&
+        sizeIsEligible &&
+        isHighlightMediaDeliveryUrl(source.url, hosts));
+};
+export const DEFAULT_MEDIA_DELIVERY_HOSTS = {
+    assets: "https://assets.highlight.xyz",
+    metadata: "https://metadata.highlight.xyz",
+    legacyAssets: "https://highlight-creator-assets.highlight.xyz",
+    arweaveGateway: "https://arweave.net",
+    ipfsGateway: "https://ipfs.io",
+};
+const LEGACY_REFERENCE = /^main\//;
+/**
+ * The URL to fetch a media location from.
+ *
+ * R2 URLs are composed from the asset's own identity — a File is `/{mediaId}`,
+ * a directory child is `/{parentId}/{path}` — never by parsing the storage key.
+ * That is why a stored key can change shape without any URL changing, and why
+ * assets written under older key layouts resolve identically.
+ *
+ * This answers "what should the browser fetch right now". It is deliberately
+ * not the backend's `artifactUri`, which answers "what immutable URI do we bake
+ * into an on-chain document" — Archive-first and permanent.
+ */
+export const mediaUrl = (media, location, hosts = DEFAULT_MEDIA_DELIVERY_HOSTS) => {
+    switch (location.provider) {
+        case StorageProvider.R2: {
+            // Legacy keys are the one case where the key *is* the public path.
+            if (LEGACY_REFERENCE.test(location.reference)) {
+                return `${hosts.legacyAssets}/${location.reference}`;
+            }
+            if (media.parentId && media.path) {
+                return `${hosts.assets}/${media.parentId}/${media.path}`;
+            }
+            return media.kind === MediaKind.Directory
+                ? `${hosts.assets}/${media.id}/`
+                : `${hosts.assets}/${media.id}`;
+        }
+        case StorageProvider.Arweave:
+            return `${hosts.arweaveGateway}/${location.reference}`;
+        case StorageProvider.Ipfs:
+            return `${hosts.ipfsGateway}/ipfs/${location.reference.replace(/^ipfs:\/\//, "").replace(/^\//, "")}`;
+        case StorageProvider.External:
+            return location.reference;
+        default:
+            return null;
+    }
+};
 const DEFAULT_PREFERENCE = [
     StorageRole.Archive,
     StorageRole.Origin,
@@ -15,7 +245,7 @@ const DEFAULT_PREFERENCE = [
 const DEFAULT_BUNDLE_ENTRY = "index.html";
 const pickLocation = (media, preference) => {
     for (const role of preference) {
-        const location = media.locations.find((l) => l.role === role && l.status === LocationStatus.Succeeded && l.url !== null);
+        const location = media.locations.find((l) => l.role === role && l.status === LocationStatus.Succeeded);
         if (location)
             return location;
     }
@@ -37,7 +267,8 @@ export const resolveMediaUrl = (media, options) => {
             ? options.prefer
             : [options.prefer]
         : DEFAULT_PREFERENCE;
-    return pickLocation(media, preference)?.url ?? null;
+    const location = pickLocation(media, preference);
+    return location ? mediaUrl(media, location, options?.hosts) : null;
 };
 /**
  * Resolve the renderable URL for a generative code bundle (a Directory media
@@ -54,7 +285,10 @@ export const resolveMediaUrl = (media, options) => {
  * meaningful.
  */
 export const resolveRenderUrl = (media, options) => {
-    const base = resolveMediaUrl(media, { prefer: [StorageRole.Origin, StorageRole.Mirror] });
+    const base = resolveMediaUrl(media, {
+        prefer: [StorageRole.Origin, StorageRole.Mirror],
+        hosts: options?.hosts,
+    });
     if (!base)
         return null;
     // Resolve the entry as a child of the directory base. `new URL(entry, base)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highlightxyz/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Official TypeScript SDK for the Highlight API",
   "keywords": [
     "ethereum",
@@ -39,6 +39,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@noble/hashes": "^1.8.0"
+  },
   "main": "./lib/index.js",
   "module": "./lib/index.js",
   "types": "./lib/index.d.ts"