@le-space/browser 0.1.23 → 0.1.24

package/index.d.ts

@@ -86,6 +86,43 @@ interface InstanceMessage {
     confirmed?: boolean;
     status?: string;
 }
+interface RootfsRequiredPortForward {
+    port: number;
+    tcp?: boolean;
+    udp?: boolean;
+    purpose?: string;
+}
+interface RootfsManifest {
+    profile?: string;
+    version: string;
+    rootfsInstallStrategy?: 'thin' | 'prebaked' | string;
+    requiresBootstrapNetwork?: boolean;
+    bootstrapSummary?: string;
+    requiredPortForwards?: RootfsRequiredPortForward[];
+    rootfsItemHash: string;
+    rootfsSizeMiB: number;
+    rootfsSourceSizeBytes?: number;
+    createdAt: string;
+    notes?: string;
+}
+interface RootfsManifestState {
+    manifest: RootfsManifest | null;
+    valid: boolean;
+    errors: string[];
+}
+type GatewayProbeStatus = 'reachable' | 'timeout' | 'error' | 'unavailable' | 'unknown';
+interface RootfsResolution {
+    itemHash: string;
+    messageStatus: MessageStatus;
+    messageType: string | null;
+    cid: string | null;
+    receptionTime?: string | null;
+    rejectionErrorCode?: number | null;
+    rejectionReason?: string | null;
+    gatewayUrl: string | null;
+    gatewayStatus: GatewayProbeStatus;
+    gatewayError?: string | null;
+}
 
 declare function fetchWithTimeout(input: RequestInfo | URL, init?: RequestInit, timeoutMs?: number): Promise<Response>;
 
@@ -96,8 +133,17 @@ declare function fetchBalance(address: string, apiHost?: string): Promise<Balanc
 declare function fetchCrns(url?: string): Promise<Crn[]>;
 declare function fetchInstances(address: string, apiHost?: string): Promise<InstanceMessage[]>;
 
-declare const BROWSER_ROOTFS_MODULE = "planned";
+declare const ITEM_HASH_RE: RegExp;
+declare const DEFAULT_ROOTFS_MANIFEST_URL = "./rootfs-manifest.json";
+declare const DEFAULT_IPFS_GATEWAY_BASE_URL = "https://ipfs.aleph.cloud/ipfs/";
+interface LoadRootfsManifestOptions {
+    baseUrl?: string | URL;
+}
+declare function validateRootfsManifest(manifest: RootfsManifest | null): RootfsManifestState;
+declare function loadRootfsManifest(url?: string | URL, options?: LoadRootfsManifestOptions): Promise<RootfsManifestState>;
+declare function verifyRootfsExists(itemHash: string, apiHost?: string): Promise<boolean>;
+declare function resolveRootfsReference(itemHash: string, apiHost?: string, gatewayBaseUrl?: string): Promise<RootfsResolution | null>;
 
 declare const BROWSER_PRICING_MODULE = "planned";
 
-export { BROWSER_PACKAGE_PLAN, BROWSER_PRICING_MODULE, BROWSER_ROOTFS_MODULE, type BalanceResponse, type BrowserExtractionPhase, type BrowserPackagePlan, type Crn, type CrnListResponse, type CrnLocation, type CrnUsage, DEFAULT_ALEPH_API_HOST, DEFAULT_CRN_LIST_URL, type InstanceMessage, type MessageStatus, type PaymentMode, fetchBalance, fetchCrns, fetchInstances, fetchWithTimeout, normalizeMessageStatus };
+export { BROWSER_PACKAGE_PLAN, BROWSER_PRICING_MODULE, type BalanceResponse, type BrowserExtractionPhase, type BrowserPackagePlan, type Crn, type CrnListResponse, type CrnLocation, type CrnUsage, DEFAULT_ALEPH_API_HOST, DEFAULT_CRN_LIST_URL, DEFAULT_IPFS_GATEWAY_BASE_URL, DEFAULT_ROOTFS_MANIFEST_URL, type GatewayProbeStatus, ITEM_HASH_RE, type InstanceMessage, type LoadRootfsManifestOptions, type MessageStatus, type PaymentMode, type RootfsManifest, type RootfsManifestState, type RootfsRequiredPortForward, type RootfsResolution, fetchBalance, fetchCrns, fetchInstances, fetchWithTimeout, loadRootfsManifest, normalizeMessageStatus, resolveRootfsReference, validateRootfsManifest, verifyRootfsExists };

package/index.js

@@ -9,8 +9,8 @@ async function fetchWithTimeout(input, init = {}, timeoutMs = 15e3) {
   const controller = new AbortController();
   const timeout = globalThis.setTimeout(() => controller.abort(), timeoutMs);
   try {
-    if (typeof input === "string" || input instanceof URL) {
-      const url = new URL(String(input), globalThis.location?.href);
+    if (input instanceof URL) {
+      const url = new URL(input.toString());
       url.searchParams.set("_ts", String(Date.now()));
       return await fetch(url, {
         ...init,
@@ -18,6 +18,20 @@ async function fetchWithTimeout(input, init = {}, timeoutMs = 15e3) {
         signal: init.signal ?? controller.signal
       });
     }
+    if (typeof input === "string") {
+      let requestInput = input;
+      try {
+        const url = new URL(input, globalThis.location?.href);
+        url.searchParams.set("_ts", String(Date.now()));
+        requestInput = url;
+      } catch {
+      }
+      return await fetch(requestInput, {
+        ...init,
+        cache: init.cache ?? "no-store",
+        signal: init.signal ?? controller.signal
+      });
+    }
     return await fetch(input, {
       ...init,
       cache: init.cache ?? "no-store",
@@ -77,19 +91,203 @@ async function fetchInstances(address, apiHost = DEFAULT_ALEPH_API_HOST) {
 }
 
 // src/rootfs.ts
-var BROWSER_ROOTFS_MODULE = "planned";
+var ITEM_HASH_RE = /^[a-fA-F0-9]{64}$/u;
+var DEFAULT_ROOTFS_MANIFEST_URL = "./rootfs-manifest.json";
+var DEFAULT_IPFS_GATEWAY_BASE_URL = "https://ipfs.aleph.cloud/ipfs/";
+function resolveManifestUrl(input, baseUrl) {
+  if (input instanceof URL) return input;
+  try {
+    return new URL(input, baseUrl ? String(baseUrl) : globalThis.location?.href);
+  } catch {
+    return input;
+  }
+}
+function validateRootfsManifest(manifest) {
+  const errors = [];
+  if (!manifest) {
+    return { manifest, valid: false, errors: ["Rootfs manifest is missing."] };
+  }
+  if (!manifest.version) errors.push("Rootfs manifest version is missing.");
+  if (manifest.rootfsInstallStrategy != null && manifest.rootfsInstallStrategy !== "thin" && manifest.rootfsInstallStrategy !== "prebaked") {
+    errors.push('Rootfs install strategy must be "thin" or "prebaked" when provided.');
+  }
+  if (manifest.requiresBootstrapNetwork != null && typeof manifest.requiresBootstrapNetwork !== "boolean") {
+    errors.push("Rootfs bootstrap network flag must be a boolean when provided.");
+  }
+  if (manifest.bootstrapSummary != null && !manifest.bootstrapSummary.trim()) {
+    errors.push("Rootfs bootstrap summary must be non-empty when provided.");
+  }
+  if (manifest.requiredPortForwards != null) {
+    if (!Array.isArray(manifest.requiredPortForwards)) {
+      errors.push("Rootfs required port forwards must be an array when provided.");
+    } else {
+      manifest.requiredPortForwards.forEach((entry, index) => {
+        if (!entry || typeof entry !== "object") {
+          errors.push(`Rootfs required port forward #${index + 1} must be an object.`);
+          return;
+        }
+        if (!Number.isInteger(entry.port) || entry.port < 1 || entry.port > 65535) {
+          errors.push(`Rootfs required port forward #${index + 1} must use a TCP/UDP port between 1 and 65535.`);
+        }
+        if (entry.tcp !== true && entry.udp !== true) {
+          errors.push(`Rootfs required port forward #${index + 1} must enable TCP or UDP.`);
+        }
+        if (entry.purpose != null && (typeof entry.purpose !== "string" || !entry.purpose.trim())) {
+          errors.push(`Rootfs required port forward #${index + 1} purpose must be non-empty when provided.`);
+        }
+      });
+    }
+  }
+  if (!ITEM_HASH_RE.test(manifest.rootfsItemHash || "")) {
+    errors.push("Rootfs ItemHash must be a 64 character hex value.");
+  }
+  if (!Number.isInteger(manifest.rootfsSizeMiB) || manifest.rootfsSizeMiB <= 0) {
+    errors.push("Rootfs size must be a positive MiB integer.");
+  }
+  if (manifest.rootfsSourceSizeBytes != null && (!Number.isInteger(manifest.rootfsSourceSizeBytes) || manifest.rootfsSourceSizeBytes <= 0)) {
+    errors.push("Rootfs source size must be a positive byte integer when provided.");
+  }
+  if (!manifest.createdAt || Number.isNaN(new Date(manifest.createdAt).getTime())) {
+    errors.push("Rootfs creation date is missing or invalid.");
+  }
+  return { manifest, valid: errors.length === 0, errors };
+}
+async function loadRootfsManifest(url = DEFAULT_ROOTFS_MANIFEST_URL, options = {}) {
+  const response = await fetchWithTimeout(resolveManifestUrl(url, options.baseUrl), { cache: "no-cache" });
+  if (!response.ok) {
+    throw new Error(`Rootfs manifest request failed: ${response.status}`);
+  }
+  return validateRootfsManifest(await response.json());
+}
+async function verifyRootfsExists(itemHash, apiHost = DEFAULT_ALEPH_API_HOST) {
+  if (!ITEM_HASH_RE.test(itemHash)) return false;
+  const response = await fetchWithTimeout(`${apiHost}/api/v0/messages/${itemHash}`, {
+    method: "GET",
+    cache: "no-cache"
+  });
+  if (response.status === 404) return false;
+  if (!response.ok) throw new Error(`Rootfs lookup failed: ${response.status}`);
+  const payload = await response.json();
+  const firstMessage = Array.isArray(payload.messages) ? payload.messages[0] : void 0;
+  const type = String(payload.type || payload.message?.type || firstMessage?.type || "").toUpperCase();
+  return type === "STORE";
+}
+function normalizeStatus(status) {
+  if (typeof status !== "string") return "unknown";
+  const normalized = status.toLowerCase();
+  if (normalized === "processed" || normalized === "pending" || normalized === "rejected") {
+    return normalized;
+  }
+  return "unknown";
+}
+function parseCidFromPayload(payload) {
+  const firstMessage = Array.isArray(payload.messages) && payload.messages[0] && typeof payload.messages[0] === "object" ? payload.messages[0] : null;
+  const directContent = firstMessage?.content && typeof firstMessage.content === "object" ? firstMessage.content : null;
+  if (typeof directContent?.item_hash === "string") {
+    return directContent.item_hash;
+  }
+  if (typeof firstMessage?.item_content === "string") {
+    try {
+      const itemContent = JSON.parse(firstMessage.item_content);
+      if (typeof itemContent.item_hash === "string") {
+        return itemContent.item_hash;
+      }
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function parseRejectionReason(payload) {
+  const errorCode = typeof payload.error_code === "number" ? payload.error_code : null;
+  const details = payload.details && typeof payload.details === "object" ? payload.details : null;
+  const rawErrors = Array.isArray(details?.errors) ? details.errors : [];
+  const firstError = rawErrors[0] && typeof rawErrors[0] === "object" ? rawErrors[0] : null;
+  if (firstError) {
+    const accountBalance = Number(firstError.account_balance);
+    const requiredBalance = Number(firstError.required_balance);
+    if (Number.isFinite(accountBalance) && Number.isFinite(requiredBalance)) {
+      const shortfall = requiredBalance - accountBalance;
+      return {
+        rejectionErrorCode: errorCode,
+        rejectionReason: shortfall > 0 ? `Rejected by Aleph for insufficient hold balance: ${accountBalance.toFixed(3)} available, ${requiredBalance.toFixed(3)} required, ${shortfall.toFixed(3)} short.` : `Rejected by Aleph for insufficient hold balance: ${accountBalance.toFixed(3)} available, ${requiredBalance.toFixed(3)} required.`
+      };
+    }
+  }
+  return {
+    rejectionErrorCode: errorCode,
+    rejectionReason: errorCode != null ? `Rejected by Aleph (error code ${errorCode}).` : null
+  };
+}
+async function probeGateway(cid, gatewayBaseUrl = DEFAULT_IPFS_GATEWAY_BASE_URL) {
+  const gatewayUrl = new URL(cid, gatewayBaseUrl).toString();
+  try {
+    const response = await fetchWithTimeout(gatewayUrl, { method: "HEAD", cache: "no-store" }, 5e3);
+    return {
+      gatewayUrl,
+      gatewayStatus: response.ok ? "reachable" : "error",
+      gatewayError: response.ok ? null : `Gateway responded with ${response.status}.`
+    };
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("timed out")) {
+      return {
+        gatewayUrl,
+        gatewayStatus: "timeout",
+        gatewayError: error.message
+      };
+    }
+    return {
+      gatewayUrl,
+      gatewayStatus: "unavailable",
+      gatewayError: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function resolveRootfsReference(itemHash, apiHost = DEFAULT_ALEPH_API_HOST, gatewayBaseUrl = DEFAULT_IPFS_GATEWAY_BASE_URL) {
+  if (!ITEM_HASH_RE.test(itemHash)) return null;
+  const response = await fetchWithTimeout(`${apiHost}/api/v0/messages/${itemHash}`, {
+    method: "GET",
+    cache: "no-cache"
+  });
+  if (response.status === 404) return null;
+  if (!response.ok) throw new Error(`Rootfs lookup failed: ${response.status}`);
+  const payload = await response.json();
+  const firstMessage = Array.isArray(payload.messages) && payload.messages[0] && typeof payload.messages[0] === "object" ? payload.messages[0] : null;
+  const messageObject = payload.message && typeof payload.message === "object" ? payload.message : null;
+  const cid = parseCidFromPayload(payload);
+  const rejection = normalizeStatus(payload.status) === "rejected" ? parseRejectionReason(payload) : { rejectionErrorCode: null, rejectionReason: null };
+  const gateway = cid ? await probeGateway(cid, gatewayBaseUrl) : { gatewayUrl: null, gatewayStatus: "unknown", gatewayError: null };
+  return {
+    itemHash,
+    messageStatus: normalizeStatus(payload.status),
+    messageType: String(payload.type || messageObject?.type || firstMessage?.type || "").toUpperCase() || null,
+    cid,
+    receptionTime: typeof payload.reception_time === "string" ? payload.reception_time : null,
+    rejectionErrorCode: rejection.rejectionErrorCode,
+    rejectionReason: rejection.rejectionReason,
+    gatewayUrl: gateway.gatewayUrl,
+    gatewayStatus: gateway.gatewayStatus,
+    gatewayError: gateway.gatewayError
+  };
+}
 
 // src/pricing.ts
 var BROWSER_PRICING_MODULE = "planned";
 export {
   BROWSER_PACKAGE_PLAN,
   BROWSER_PRICING_MODULE,
-  BROWSER_ROOTFS_MODULE,
   DEFAULT_ALEPH_API_HOST,
   DEFAULT_CRN_LIST_URL,
+  DEFAULT_IPFS_GATEWAY_BASE_URL,
+  DEFAULT_ROOTFS_MANIFEST_URL,
+  ITEM_HASH_RE,
   fetchBalance,
   fetchCrns,
   fetchInstances,
   fetchWithTimeout,
-  normalizeMessageStatus
+  loadRootfsManifest,
+  normalizeMessageStatus,
+  resolveRootfsReference,
+  validateRootfsManifest,
+  verifyRootfsExists
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/browser",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Shared browser-safe Aleph deployment and polling helpers.",
   "license": "MIT",
   "type": "module",