@le-space/browser 0.1.23 → 0.1.25

package/index.d.ts

@@ -12,6 +12,35 @@ interface BalanceResponse {
     details?: Record<string, string>;
     credit_balance: number;
 }
+interface Price {
+    payg?: string | number | null;
+    holding?: string | number | null;
+    fixed?: string | number | null;
+    credit?: string | number | null;
+}
+interface ComputeUnit {
+    vcpus: number;
+    memory_mib: number;
+    disk_mib: number;
+}
+interface Tier {
+    id: string;
+    compute_units: number;
+    vram?: number | null;
+    model?: string | null;
+}
+interface InstancePricing {
+    price: {
+        storage?: Price;
+        compute_unit?: Price;
+    };
+    compute_unit: ComputeUnit;
+    tiers: Tier[];
+}
+interface PricingState {
+    pricing: InstancePricing | null;
+    fetchedAt: number | null;
+}
 interface CrnUsage {
     cpu?: {
         count?: number;
@@ -86,6 +115,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 +162,19 @@ 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";
+declare const DEFAULT_ALEPH_AGGREGATE_ADDRESS = "0xFba561a84A537fCaa567bb7A2257e7142701ae2A";
+declare function parseInstancePricing(payload: unknown): InstancePricing;
+declare function fetchInstancePricing(apiHost?: string, aggregateAddress?: string): Promise<PricingState>;
 
-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, type BalanceResponse, type BrowserExtractionPhase, type BrowserPackagePlan, type ComputeUnit, type Crn, type CrnListResponse, type CrnLocation, type CrnUsage, DEFAULT_ALEPH_AGGREGATE_ADDRESS, 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 InstancePricing, type LoadRootfsManifestOptions, type MessageStatus, type PaymentMode, type Price, type PricingState, type RootfsManifest, type RootfsManifestState, type RootfsRequiredPortForward, type RootfsResolution, type Tier, fetchBalance, fetchCrns, fetchInstancePricing, fetchInstances, fetchWithTimeout, loadRootfsManifest, normalizeMessageStatus, parseInstancePricing, 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,231 @@ 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";
+var DEFAULT_ALEPH_AGGREGATE_ADDRESS = "0xFba561a84A537fCaa567bb7A2257e7142701ae2A";
+function parseInstancePricing(payload) {
+  const data = payload;
+  const pricing = data.data?.pricing ?? data.pricing;
+  const instance = pricing?.instance;
+  if (!instance?.price?.compute_unit || !instance.compute_unit || !Array.isArray(instance.tiers)) {
+    throw new Error("Aleph pricing aggregate does not contain instance pricing.");
+  }
+  return instance;
+}
+async function fetchInstancePricing(apiHost = DEFAULT_ALEPH_API_HOST, aggregateAddress = DEFAULT_ALEPH_AGGREGATE_ADDRESS) {
+  const response = await fetchWithTimeout(`${apiHost}/api/v0/aggregates/${aggregateAddress}.json?keys=pricing`, {
+    cache: "no-cache"
+  });
+  if (!response.ok) {
+    throw new Error(`Pricing aggregate request failed: ${response.status}`);
+  }
+  const payload = await response.json();
+  const pricingAggregate = payload.data?.pricing;
+  if (!pricingAggregate) {
+    throw new Error("Pricing aggregate response did not include a pricing key.");
+  }
+  return {
+    pricing: parseInstancePricing({ pricing: pricingAggregate }),
+    fetchedAt: Date.now()
+  };
+}
 export {
   BROWSER_PACKAGE_PLAN,
-  BROWSER_PRICING_MODULE,
-  BROWSER_ROOTFS_MODULE,
+  DEFAULT_ALEPH_AGGREGATE_ADDRESS,
   DEFAULT_ALEPH_API_HOST,
   DEFAULT_CRN_LIST_URL,
+  DEFAULT_IPFS_GATEWAY_BASE_URL,
+  DEFAULT_ROOTFS_MANIFEST_URL,
+  ITEM_HASH_RE,
   fetchBalance,
   fetchCrns,
+  fetchInstancePricing,
   fetchInstances,
   fetchWithTimeout,
-  normalizeMessageStatus
+  loadRootfsManifest,
+  normalizeMessageStatus,
+  parseInstancePricing,
+  resolveRootfsReference,
+  validateRootfsManifest,
+  verifyRootfsExists
 };

package/package.json

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