@le-space/browser 0.1.24 → 0.1.26

package/index.d.ts

@@ -5,6 +5,7 @@ interface BrowserPackagePlan {
 }
 declare const BROWSER_PACKAGE_PLAN: BrowserPackagePlan;
 type MessageStatus = 'processed' | 'pending' | 'rejected' | 'unknown';
+type ReferenceStatus = MessageStatus | 'missing';
 interface BalanceResponse {
     address: string;
     balance: string;
@@ -12,6 +13,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 +116,31 @@ interface InstanceMessage {
     confirmed?: boolean;
     status?: string;
 }
+interface AlephMessageEnvelope {
+    status?: unknown;
+    type?: unknown;
+    error_code?: unknown;
+    details?: unknown;
+    message?: {
+        type?: unknown;
+    } | null;
+    messages?: Array<{
+        type?: unknown;
+    }> | null;
+    [key: string]: unknown;
+}
+interface MessageReference {
+    itemHash: string;
+    status: ReferenceStatus;
+    type: string | null;
+}
+interface DeploymentInspectionResult {
+    status: MessageStatus;
+    errorCode: number | null;
+    details: Record<string, unknown> | null;
+    rejectionReason: string | null;
+    references: MessageReference[];
+}
 interface RootfsRequiredPortForward {
     port: number;
     tcp?: boolean;
@@ -132,6 +187,9 @@ declare function normalizeMessageStatus(status: unknown): MessageStatus;
 declare function fetchBalance(address: string, apiHost?: string): Promise<BalanceResponse>;
 declare function fetchCrns(url?: string): Promise<Crn[]>;
 declare function fetchInstances(address: string, apiHost?: string): Promise<InstanceMessage[]>;
+declare function fetchMessageEnvelope(itemHash: string, apiHost?: string): Promise<AlephMessageEnvelope | null>;
+declare function inspectDeploymentResult(itemHash: string, rootfsRef?: string, apiHost?: string): Promise<DeploymentInspectionResult>;
+declare function waitForDeploymentResult(itemHash: string, rootfsRef?: string, apiHost?: string, attempts?: number, delayMs?: number): Promise<DeploymentInspectionResult>;
 
 declare const ITEM_HASH_RE: RegExp;
 declare const DEFAULT_ROOTFS_MANIFEST_URL = "./rootfs-manifest.json";
@@ -144,6 +202,8 @@ declare function loadRootfsManifest(url?: string | URL, options?: LoadRootfsMani
 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, 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 };
+export { type AlephMessageEnvelope, 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 DeploymentInspectionResult, type GatewayProbeStatus, ITEM_HASH_RE, type InstanceMessage, type InstancePricing, type LoadRootfsManifestOptions, type MessageReference, type MessageStatus, type PaymentMode, type Price, type PricingState, type ReferenceStatus, type RootfsManifest, type RootfsManifestState, type RootfsRequiredPortForward, type RootfsResolution, type Tier, fetchBalance, fetchCrns, fetchInstancePricing, fetchInstances, fetchMessageEnvelope, fetchWithTimeout, inspectDeploymentResult, loadRootfsManifest, normalizeMessageStatus, parseInstancePricing, resolveRootfsReference, validateRootfsManifest, verifyRootfsExists, waitForDeploymentResult };

package/index.js

@@ -89,6 +89,98 @@ async function fetchInstances(address, apiHost = DEFAULT_ALEPH_API_HOST) {
     status: typeof message.status === "string" && message.status.trim() ? message.status : message.confirmed ? "processed" : message.status
   }));
 }
+function messageTypeFromEnvelope(payload) {
+  if (!payload) return null;
+  const type = payload.type ?? payload.message?.type ?? (Array.isArray(payload.messages) ? payload.messages[0]?.type : void 0);
+  return typeof type === "string" ? type.toUpperCase() : null;
+}
+function extractReferenceHashes(details) {
+  if (!details || typeof details !== "object" || !("errors" in details)) return [];
+  const errors = details.errors;
+  if (!Array.isArray(errors)) return [];
+  return errors.filter((value) => typeof value === "string");
+}
+function describeRejectedDeployment(payload, references, rootfsRef) {
+  const errorCode = typeof payload.error_code === "number" ? payload.error_code : null;
+  const pendingReferences = references.filter((reference) => reference.status === "pending");
+  const missingReferences = references.filter((reference) => reference.status === "missing");
+  const rootfsReference = references.find((reference) => reference.itemHash === rootfsRef);
+  if (rootfsReference?.status === "pending") {
+    return `Aleph rejected this deployment because the referenced rootfs STORE message ${rootfsReference.itemHash} is still pending and cannot yet be used by an instance. Wait for that STORE message to process, then deploy again.`;
+  }
+  if (pendingReferences.length > 0) {
+    return `Aleph rejected this deployment because referenced message(s) are still pending: ${pendingReferences.map((reference) => reference.itemHash).join(", ")}.`;
+  }
+  if (missingReferences.length > 0) {
+    return `Aleph rejected this deployment because referenced message(s) were not found on Aleph: ${missingReferences.map((reference) => reference.itemHash).join(", ")}.`;
+  }
+  const referencedHashes = extractReferenceHashes(payload.details);
+  if (referencedHashes.length > 0) {
+    return `Aleph rejected this deployment${errorCode ? ` (error ${errorCode})` : ""}. Referenced message(s): ${referencedHashes.join(", ")}.`;
+  }
+  return `Aleph rejected this deployment${errorCode ? ` (error ${errorCode})` : ""}.`;
+}
+async function fetchMessageEnvelope(itemHash, apiHost = DEFAULT_ALEPH_API_HOST) {
+  const response = await fetchWithTimeout(`${apiHost}/api/v0/messages/${itemHash}`, {
+    cache: "no-cache"
+  });
+  if (response.status === 404) return null;
+  if (!response.ok) throw new Error(`Message lookup failed: ${response.status}`);
+  return await response.json();
+}
+async function fetchReference(itemHash, apiHost) {
+  const payload = await fetchMessageEnvelope(itemHash, apiHost);
+  if (!payload) {
+    return {
+      itemHash,
+      status: "missing",
+      type: null
+    };
+  }
+  return {
+    itemHash,
+    status: normalizeMessageStatus(payload.status),
+    type: messageTypeFromEnvelope(payload)
+  };
+}
+async function inspectDeploymentResult(itemHash, rootfsRef, apiHost = DEFAULT_ALEPH_API_HOST) {
+  const payload = await fetchMessageEnvelope(itemHash, apiHost);
+  if (!payload) {
+    return {
+      status: "unknown",
+      errorCode: null,
+      details: null,
+      rejectionReason: `Deployment message ${itemHash} was not found on Aleph.`,
+      references: []
+    };
+  }
+  const relatedHashes = new Set(rootfsRef ? [rootfsRef] : []);
+  for (const referenceHash of extractReferenceHashes(payload.details)) {
+    relatedHashes.add(referenceHash);
+  }
+  const references = await Promise.all(Array.from(relatedHashes).map((hash) => fetchReference(hash, apiHost)));
+  const status = normalizeMessageStatus(payload.status);
+  const errorCode = typeof payload.error_code === "number" ? payload.error_code : null;
+  const details = payload.details && typeof payload.details === "object" ? payload.details : null;
+  return {
+    status,
+    errorCode,
+    details,
+    rejectionReason: status === "rejected" ? describeRejectedDeployment(payload, references, rootfsRef) : null,
+    references
+  };
+}
+async function waitForDeploymentResult(itemHash, rootfsRef, apiHost = DEFAULT_ALEPH_API_HOST, attempts = 15, delayMs = 2e3) {
+  let lastResult = await inspectDeploymentResult(itemHash, rootfsRef, apiHost);
+  for (let attempt = 1; attempt < attempts; attempt += 1) {
+    if (lastResult.status === "processed" || lastResult.status === "rejected") {
+      return lastResult;
+    }
+    await new Promise((resolve) => globalThis.setTimeout(resolve, delayMs));
+    lastResult = await inspectDeploymentResult(itemHash, rootfsRef, apiHost);
+  }
+  return lastResult;
+}
 
 // src/rootfs.ts
 var ITEM_HASH_RE = /^[a-fA-F0-9]{64}$/u;
@@ -272,10 +364,36 @@ async function resolveRootfsReference(itemHash, apiHost = DEFAULT_ALEPH_API_HOST
 }
 
 // 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,
+  DEFAULT_ALEPH_AGGREGATE_ADDRESS,
   DEFAULT_ALEPH_API_HOST,
   DEFAULT_CRN_LIST_URL,
   DEFAULT_IPFS_GATEWAY_BASE_URL,
@@ -283,11 +401,16 @@ export {
   ITEM_HASH_RE,
   fetchBalance,
   fetchCrns,
+  fetchInstancePricing,
   fetchInstances,
+  fetchMessageEnvelope,
   fetchWithTimeout,
+  inspectDeploymentResult,
   loadRootfsManifest,
   normalizeMessageStatus,
+  parseInstancePricing,
   resolveRootfsReference,
   validateRootfsManifest,
-  verifyRootfsExists
+  verifyRootfsExists,
+  waitForDeploymentResult
 };

package/package.json

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