@le-space/browser 0.1.25 → 0.1.27

package/README.md

@@ -13,6 +13,25 @@ The package should stay UI-neutral. It should provide browser-safe helpers, but
 it should not own app-specific Svelte state, prepaid product logic, or wallet
 UX.
 
+## Client Surface
+
+The preferred public entrypoint is a typed browser client factory:
+
+- `createAlephBrowserClient({ apiHost?, crnListUrl? })`
+
+That client should remain small and stable. It currently owns:
+
+- balance lookup
+- CRN listing
+- instance listing
+- message envelope lookup
+- deployment result inspection and polling
+- Aleph message broadcast helpers
+
+Lower-level helper functions remain exported too, but new extractions should
+prefer hanging reusable behavior off the client surface unless there is a good
+reason to keep them as standalone utilities.
+
 ## Planned v1 Scope
 
 The first real extraction wave should cover:
@@ -23,6 +42,7 @@ The first real extraction wave should cover:
   - balance fetch
   - CRN fetch
   - instance listing
+  - typed browser client factory
   - Aleph message broadcast helpers
   - deployment polling and result inspection
   - runtime detail inspection

package/index.d.ts

@@ -5,6 +5,9 @@ interface BrowserPackagePlan {
 }
 declare const BROWSER_PACKAGE_PLAN: BrowserPackagePlan;
 type MessageStatus = 'processed' | 'pending' | 'rejected' | 'unknown';
+type ReferenceStatus = MessageStatus | 'missing';
+type AlephSenderChain = 'ETH';
+type AlephMessageType = 'INSTANCE' | 'FORGET' | 'AGGREGATE';
 interface BalanceResponse {
     address: string;
     balance: string;
@@ -115,6 +118,66 @@ 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 AlephBroadcastMessage {
+    sender: string;
+    chain: AlephSenderChain;
+    signature: string;
+    type: AlephMessageType;
+    item_hash: string;
+    item_type: 'inline';
+    item_content: string;
+    time: number;
+    channel: string;
+}
+interface AlephBroadcastResponse {
+    publication_status?: {
+        status: string;
+        failed?: unknown[];
+    };
+    message_status?: MessageStatus;
+    [key: string]: unknown;
+}
+interface BroadcastResult {
+    response: AlephBroadcastResponse;
+    httpStatus: number;
+}
+interface AlephBrowserClient {
+    apiHost: string;
+    crnListUrl: string;
+    fetchBalance(address: string): Promise<BalanceResponse>;
+    fetchCrns(): Promise<Crn[]>;
+    fetchInstances(address: string): Promise<InstanceMessage[]>;
+    fetchMessageEnvelope(itemHash: string): Promise<AlephMessageEnvelope | null>;
+    inspectDeploymentResult(itemHash: string, rootfsRef?: string): Promise<DeploymentInspectionResult>;
+    waitForDeploymentResult(itemHash: string, rootfsRef?: string, attempts?: number, delayMs?: number): Promise<DeploymentInspectionResult>;
+    broadcastInstanceMessage(message: AlephBroadcastMessage, sync?: boolean): Promise<BroadcastResult>;
+    broadcastAlephMessage(message: AlephBroadcastMessage, sync?: boolean): Promise<BroadcastResult>;
+}
 interface RootfsRequiredPortForward {
     port: number;
     tcp?: boolean;
@@ -161,6 +224,17 @@ 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 function broadcastInstanceMessage(message: AlephBroadcastMessage, apiHost?: string, sync?: boolean): Promise<BroadcastResult>;
+declare function broadcastAlephMessage(message: AlephBroadcastMessage, apiHost?: string, sync?: boolean): Promise<BroadcastResult>;
+
+interface CreateAlephBrowserClientOptions {
+    apiHost?: string;
+    crnListUrl?: string;
+}
+declare function createAlephBrowserClient(options?: CreateAlephBrowserClientOptions): AlephBrowserClient;
 
 declare const ITEM_HASH_RE: RegExp;
 declare const DEFAULT_ROOTFS_MANIFEST_URL = "./rootfs-manifest.json";
@@ -177,4 +251,4 @@ declare const DEFAULT_ALEPH_AGGREGATE_ADDRESS = "0xFba561a84A537fCaa567bb7A2257e
 declare function parseInstancePricing(payload: unknown): InstancePricing;
 declare function fetchInstancePricing(apiHost?: string, aggregateAddress?: string): Promise<PricingState>;
 
-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 };
+export { type AlephBroadcastMessage, type AlephBroadcastResponse, type AlephBrowserClient, type AlephMessageEnvelope, type AlephMessageType, type AlephSenderChain, BROWSER_PACKAGE_PLAN, type BalanceResponse, type BroadcastResult, type BrowserExtractionPhase, type BrowserPackagePlan, type ComputeUnit, type CreateAlephBrowserClientOptions, 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, broadcastAlephMessage, broadcastInstanceMessage, createAlephBrowserClient, fetchBalance, fetchCrns, fetchInstancePricing, fetchInstances, fetchMessageEnvelope, fetchWithTimeout, inspectDeploymentResult, loadRootfsManifest, normalizeMessageStatus, parseInstancePricing, resolveRootfsReference, validateRootfsManifest, verifyRootfsExists, waitForDeploymentResult };

package/index.js

@@ -89,6 +89,175 @@ 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;
+}
+function isInvalidMessageFormatResponse(response, payload) {
+  if (response.status !== 422) return false;
+  const details = payload.details;
+  if (typeof details === "string" && details.includes("InvalidMessageFormat")) return true;
+  if (details && typeof details === "object") {
+    const detailMessage = details.message;
+    if (typeof detailMessage === "string" && detailMessage.includes("InvalidMessageFormat")) return true;
+  }
+  return false;
+}
+async function postBroadcastPayload(body, apiHost) {
+  const rawResponse = await fetchWithTimeout(`${apiHost}/api/v0/messages`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const response = await rawResponse.json().catch(() => ({}));
+  return {
+    response,
+    httpStatus: rawResponse.status,
+    rawResponse
+  };
+}
+async function broadcastInstanceMessage(message, apiHost = DEFAULT_ALEPH_API_HOST, sync = false) {
+  const attempts = [{ sync, message }, { ...message, sync }, { ...message }];
+  for (let index = 0; index < attempts.length; index += 1) {
+    const result = await postBroadcastPayload(attempts[index], apiHost);
+    if (result.rawResponse.ok || result.httpStatus === 202) {
+      return {
+        response: result.response,
+        httpStatus: result.httpStatus
+      };
+    }
+    const canRetry = index < attempts.length - 1 && isInvalidMessageFormatResponse(result.rawResponse, result.response);
+    if (!canRetry) {
+      throw new Error(`Broadcast failed: ${result.httpStatus} ${JSON.stringify(result.response)}`);
+    }
+  }
+  throw new Error("Broadcast failed: no compatible request format was accepted");
+}
+async function broadcastAlephMessage(message, apiHost = DEFAULT_ALEPH_API_HOST, sync = false) {
+  return broadcastInstanceMessage(message, apiHost, sync);
+}
+
+// src/client.ts
+function createAlephBrowserClient(options = {}) {
+  const apiHost = options.apiHost ?? DEFAULT_ALEPH_API_HOST;
+  const crnListUrl = options.crnListUrl ?? DEFAULT_CRN_LIST_URL;
+  return {
+    apiHost,
+    crnListUrl,
+    fetchBalance(address) {
+      return fetchBalance(address, apiHost);
+    },
+    fetchCrns() {
+      return fetchCrns(crnListUrl);
+    },
+    fetchInstances(address) {
+      return fetchInstances(address, apiHost);
+    },
+    fetchMessageEnvelope(itemHash) {
+      return fetchMessageEnvelope(itemHash, apiHost);
+    },
+    inspectDeploymentResult(itemHash, rootfsRef) {
+      return inspectDeploymentResult(itemHash, rootfsRef, apiHost);
+    },
+    waitForDeploymentResult(itemHash, rootfsRef, attempts, delayMs) {
+      return waitForDeploymentResult(itemHash, rootfsRef, apiHost, attempts, delayMs);
+    },
+    broadcastInstanceMessage(message, sync) {
+      return broadcastInstanceMessage(message, apiHost, sync);
+    },
+    broadcastAlephMessage(message, sync) {
+      return broadcastAlephMessage(message, apiHost, sync);
+    }
+  };
+}
 
 // src/rootfs.ts
 var ITEM_HASH_RE = /^[a-fA-F0-9]{64}$/u;
@@ -307,15 +476,21 @@ export {
   DEFAULT_IPFS_GATEWAY_BASE_URL,
   DEFAULT_ROOTFS_MANIFEST_URL,
   ITEM_HASH_RE,
+  broadcastAlephMessage,
+  broadcastInstanceMessage,
+  createAlephBrowserClient,
   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.25",
+  "version": "0.1.27",
   "description": "Shared browser-safe Aleph deployment and polling helpers.",
   "license": "MIT",
   "type": "module",