@arke-institute/sdk 0.1.2 → 0.1.3

package/dist/edit/index.cjs

@@ -30,19 +30,37 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/edit/index.ts
 var edit_exports = {};
 __export(edit_exports, {
+  BackendError: () => BackendError,
   CASConflictError: () => CASConflictError,
+  ContentNotFoundError: () => ContentNotFoundError,
+  DEFAULT_RETRY_CONFIG: () => DEFAULT_RETRY_CONFIG,
+  DeleteError: () => DeleteError,
   DiffEngine: () => DiffEngine,
   EditClient: () => EditClient,
   EditError: () => EditError,
   EditSession: () => EditSession,
+  EntityExistsError: () => EntityExistsError,
   EntityNotFoundError: () => EntityNotFoundError,
+  IPFSError: () => IPFSError,
+  MergeError: () => MergeError,
+  NetworkError: () => NetworkError,
   PermissionError: () => PermissionError,
   PromptBuilder: () => PromptBuilder,
   ReprocessError: () => ReprocessError,
+  UndeleteError: () => UndeleteError,
+  UnmergeError: () => UnmergeError,
   ValidationError: () => ValidationError
 });
 module.exports = __toCommonJS(edit_exports);
 
+// src/edit/types.ts
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 10,
+  baseDelay: 100,
+  maxDelay: 5e3,
+  jitterFactor: 0.3
+};
+
 // src/edit/errors.ts
 var EditError = class extends Error {
   constructor(message, code = "UNKNOWN_ERROR", details) {
@@ -53,21 +71,51 @@ var EditError = class extends Error {
   }
 };
 var EntityNotFoundError = class extends EditError {
-  constructor(pi) {
-    super(`Entity not found: ${pi}`, "ENTITY_NOT_FOUND", { pi });
+  constructor(id) {
+    super(`Entity not found: ${id}`, "ENTITY_NOT_FOUND", { id });
     this.name = "EntityNotFoundError";
   }
 };
 var CASConflictError = class extends EditError {
-  constructor(pi, expectedTip, actualTip) {
+  constructor(id, expectedTip, actualTip) {
     super(
-      `CAS conflict: entity ${pi} was modified (expected ${expectedTip}, got ${actualTip})`,
+      `CAS conflict: entity ${id} was modified (expected ${expectedTip}, got ${actualTip})`,
       "CAS_CONFLICT",
-      { pi, expectedTip, actualTip }
+      { id, expectedTip, actualTip }
     );
     this.name = "CASConflictError";
   }
 };
+var EntityExistsError = class extends EditError {
+  constructor(id) {
+    super(`Entity already exists: ${id}`, "ENTITY_EXISTS", { id });
+    this.name = "EntityExistsError";
+  }
+};
+var MergeError = class extends EditError {
+  constructor(message, sourceId, targetId) {
+    super(message, "MERGE_ERROR", { sourceId, targetId });
+    this.name = "MergeError";
+  }
+};
+var UnmergeError = class extends EditError {
+  constructor(message, sourceId, targetId) {
+    super(message, "UNMERGE_ERROR", { sourceId, targetId });
+    this.name = "UnmergeError";
+  }
+};
+var DeleteError = class extends EditError {
+  constructor(message, id) {
+    super(message, "DELETE_ERROR", { id });
+    this.name = "DeleteError";
+  }
+};
+var UndeleteError = class extends EditError {
+  constructor(message, id) {
+    super(message, "UNDELETE_ERROR", { id });
+    this.name = "UndeleteError";
+  }
+};
 var ReprocessError = class extends EditError {
   constructor(message, batchId) {
     super(message, "REPROCESS_ERROR", { batchId });
@@ -81,28 +129,52 @@ var ValidationError = class extends EditError {
   }
 };
 var PermissionError = class extends EditError {
-  constructor(message, pi) {
-    super(message, "PERMISSION_DENIED", { pi });
+  constructor(message, id) {
+    super(message, "PERMISSION_DENIED", { id });
     this.name = "PermissionError";
   }
 };
+var NetworkError = class extends EditError {
+  constructor(message, statusCode) {
+    super(message, "NETWORK_ERROR", { statusCode });
+    this.name = "NetworkError";
+  }
+};
+var ContentNotFoundError = class extends EditError {
+  constructor(cid) {
+    super(`Content not found: ${cid}`, "CONTENT_NOT_FOUND", { cid });
+    this.name = "ContentNotFoundError";
+  }
+};
+var IPFSError = class extends EditError {
+  constructor(message) {
+    super(message, "IPFS_ERROR");
+    this.name = "IPFSError";
+  }
+};
+var BackendError = class extends EditError {
+  constructor(message) {
+    super(message, "BACKEND_ERROR");
+    this.name = "BackendError";
+  }
+};
 
 // src/edit/client.ts
-var DEFAULT_RETRY_OPTIONS = {
-  maxRetries: 5,
-  initialDelayMs: 2e3,
-  // Start with 2s delay (orchestrator needs time to initialize)
-  maxDelayMs: 3e4,
-  // Cap at 30s
-  backoffMultiplier: 2
-  // Double each retry
-};
+var RETRYABLE_STATUS_CODES = [409, 503];
+var RETRYABLE_ERRORS = ["ECONNRESET", "ETIMEDOUT", "fetch failed"];
 var EditClient = class {
   constructor(config) {
     this.gatewayUrl = config.gatewayUrl.replace(/\/$/, "");
     this.authToken = config.authToken;
+    this.network = config.network || "main";
+    this.userId = config.userId;
+    this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...config.retryConfig };
     this.statusUrlTransform = config.statusUrlTransform;
+    this.apiPrefix = config.apiPrefix ?? "/api";
   }
+  // ===========================================================================
+  // Configuration Methods
+  // ===========================================================================
   /**
    * Update the auth token (useful for token refresh)
    */
@@ -110,135 +182,505 @@ var EditClient = class {
     this.authToken = token;
   }
   /**
-   * Sleep for a given number of milliseconds
+   * Set the network (main or test)
+   */
+  setNetwork(network) {
+    this.network = network;
+  }
+  /**
+   * Set the user ID for permission checks
+   */
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  // ===========================================================================
+  // Internal Helpers
+  // ===========================================================================
+  /**
+   * Build URL with API prefix
    */
+  buildUrl(path) {
+    return `${this.gatewayUrl}${this.apiPrefix}${path}`;
+  }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+  getHeaders(contentType = "application/json") {
+    const headers = {};
+    if (contentType) {
+      headers["Content-Type"] = contentType;
+    }
+    if (this.authToken) {
+      headers["Authorization"] = `Bearer ${this.authToken}`;
+    }
+    headers["X-Arke-Network"] = this.network;
+    if (this.userId) {
+      headers["X-User-Id"] = this.userId;
+    }
+    return headers;
+  }
+  calculateDelay(attempt) {
+    const { baseDelay, maxDelay, jitterFactor } = this.retryConfig;
+    const exponentialDelay = baseDelay * Math.pow(2, attempt);
+    const cappedDelay = Math.min(exponentialDelay, maxDelay);
+    const jitter = cappedDelay * jitterFactor * (Math.random() * 2 - 1);
+    return Math.max(0, cappedDelay + jitter);
+  }
+  isRetryableStatus(status) {
+    return RETRYABLE_STATUS_CODES.includes(status);
+  }
+  isRetryableError(error) {
+    const message = error.message.toLowerCase();
+    return RETRYABLE_ERRORS.some((e) => message.includes(e.toLowerCase()));
+  }
   /**
    * Execute a fetch with exponential backoff retry on transient errors
    */
-  async fetchWithRetry(url, options, retryOptions = DEFAULT_RETRY_OPTIONS) {
+  async fetchWithRetry(url, options, context) {
     let lastError = null;
-    let delay = retryOptions.initialDelayMs;
-    for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
       try {
         const response = await fetch(url, options);
-        if (response.status >= 500 && attempt < retryOptions.maxRetries) {
-          lastError = new Error(`Server error: ${response.status} ${response.statusText}`);
+        if (this.isRetryableStatus(response.status) && attempt < this.retryConfig.maxRetries) {
+          const delay = this.calculateDelay(attempt);
+          lastError = new Error(`${context}: ${response.status} ${response.statusText}`);
           await this.sleep(delay);
-          delay = Math.min(delay * retryOptions.backoffMultiplier, retryOptions.maxDelayMs);
           continue;
         }
         return response;
       } catch (error) {
         lastError = error;
-        if (attempt < retryOptions.maxRetries) {
+        if (this.isRetryableError(lastError) && attempt < this.retryConfig.maxRetries) {
+          const delay = this.calculateDelay(attempt);
           await this.sleep(delay);
-          delay = Math.min(delay * retryOptions.backoffMultiplier, retryOptions.maxDelayMs);
+          continue;
         }
+        throw new NetworkError(lastError.message);
       }
     }
-    throw lastError || new Error("Request failed after retries");
+    throw lastError || new NetworkError("Request failed after retries");
   }
-  getHeaders() {
-    const headers = {
-      "Content-Type": "application/json"
+  /**
+   * Handle common error responses and throw appropriate error types
+   */
+  async handleErrorResponse(response, context) {
+    let errorData = {};
+    try {
+      errorData = await response.json();
+    } catch {
+    }
+    const message = errorData.message || `${context}: ${response.statusText}`;
+    const errorCode = errorData.error || "";
+    switch (response.status) {
+      case 400:
+        throw new ValidationError(message);
+      case 403:
+        throw new PermissionError(message);
+      case 404:
+        throw new EntityNotFoundError(message);
+      case 409:
+        if (errorCode === "CAS_FAILURE") {
+          const details = errorData.details;
+          throw new CASConflictError(
+            context,
+            details?.expect || "unknown",
+            details?.actual || "unknown"
+          );
+        }
+        if (errorCode === "CONFLICT") {
+          throw new EntityExistsError(message);
+        }
+        throw new EditError(message, errorCode, errorData.details);
+      case 503:
+        if (errorCode === "IPFS_ERROR") {
+          throw new IPFSError(message);
+        }
+        if (errorCode === "BACKEND_ERROR") {
+          throw new BackendError(message);
+        }
+        throw new NetworkError(message, response.status);
+      default:
+        throw new EditError(message, errorCode || "API_ERROR", { status: response.status });
+    }
+  }
+  // ===========================================================================
+  // Entity CRUD Operations
+  // ===========================================================================
+  /**
+   * Create a new entity
+   */
+  async createEntity(request) {
+    const url = this.buildUrl("/entities");
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      "Create entity"
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, "Create entity");
+    }
+    return response.json();
+  }
+  /**
+   * Get an entity by ID
+   */
+  async getEntity(id) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Get entity ${id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Get entity ${id}`);
+    }
+    return response.json();
+  }
+  /**
+   * List entities with pagination
+   */
+  async listEntities(options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit) params.set("limit", options.limit.toString());
+    if (options.cursor) params.set("cursor", options.cursor);
+    if (options.include_metadata) params.set("include_metadata", "true");
+    const queryString = params.toString();
+    const url = this.buildUrl(`/entities${queryString ? `?${queryString}` : ""}`);
+    const response = await this.fetchWithRetry(url, { headers: this.getHeaders() }, "List entities");
+    if (!response.ok) {
+      await this.handleErrorResponse(response, "List entities");
+    }
+    return response.json();
+  }
+  /**
+   * Update an entity (append new version)
+   */
+  async updateEntity(id, update) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/versions`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(update)
+      },
+      `Update entity ${id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Update entity ${id}`);
+    }
+    return response.json();
+  }
+  // ===========================================================================
+  // Version Operations
+  // ===========================================================================
+  /**
+   * List version history for an entity
+   */
+  async listVersions(id, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit) params.set("limit", options.limit.toString());
+    if (options.cursor) params.set("cursor", options.cursor);
+    const queryString = params.toString();
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/versions${queryString ? `?${queryString}` : ""}`);
+    const response = await this.fetchWithRetry(url, { headers: this.getHeaders() }, `List versions for ${id}`);
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `List versions for ${id}`);
+    }
+    return response.json();
+  }
+  /**
+   * Get a specific version of an entity
+   */
+  async getVersion(id, selector) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/versions/${encodeURIComponent(selector)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Get version ${selector} for ${id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Get version ${selector} for ${id}`);
+    }
+    return response.json();
+  }
+  /**
+   * Resolve an entity ID to its current tip CID (fast lookup)
+   */
+  async resolve(id) {
+    const url = this.buildUrl(`/resolve/${encodeURIComponent(id)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Resolve ${id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Resolve ${id}`);
+    }
+    return response.json();
+  }
+  // ===========================================================================
+  // Hierarchy Operations
+  // ===========================================================================
+  /**
+   * Update parent-child hierarchy relationships
+   */
+  async updateHierarchy(request) {
+    const apiRequest = {
+      parent_pi: request.parent_id,
+      expect_tip: request.expect_tip,
+      add_children: request.add_children,
+      remove_children: request.remove_children,
+      note: request.note
     };
-    if (this.authToken) {
-      headers["Authorization"] = `Bearer ${this.authToken}`;
+    const url = this.buildUrl("/hierarchy");
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(apiRequest)
+      },
+      `Update hierarchy for ${request.parent_id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Update hierarchy for ${request.parent_id}`);
     }
-    return headers;
+    return response.json();
   }
+  // ===========================================================================
+  // Merge Operations
+  // ===========================================================================
   /**
-   * Handle common error responses
+   * Merge source entity into target entity
    */
-  handleErrorResponse(response, context) {
-    if (response.status === 403) {
-      throw new PermissionError(`Permission denied: ${context}`);
+  async mergeEntity(sourceId, request) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(sourceId)}/merge`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      `Merge ${sourceId} into ${request.target_id}`
+    );
+    if (!response.ok) {
+      try {
+        const error = await response.json();
+        throw new MergeError(
+          error.message || `Merge failed: ${response.statusText}`,
+          sourceId,
+          request.target_id
+        );
+      } catch (e) {
+        if (e instanceof MergeError) throw e;
+        await this.handleErrorResponse(response, `Merge ${sourceId}`);
+      }
     }
-    throw new EditError(
-      `${context}: ${response.statusText}`,
-      "API_ERROR",
-      { status: response.status }
+    return response.json();
+  }
+  /**
+   * Unmerge (restore) a previously merged entity
+   */
+  async unmergeEntity(sourceId, request) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(sourceId)}/unmerge`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      `Unmerge ${sourceId}`
     );
+    if (!response.ok) {
+      try {
+        const error = await response.json();
+        throw new UnmergeError(
+          error.message || `Unmerge failed: ${response.statusText}`,
+          sourceId,
+          request.target_id
+        );
+      } catch (e) {
+        if (e instanceof UnmergeError) throw e;
+        await this.handleErrorResponse(response, `Unmerge ${sourceId}`);
+      }
+    }
+    return response.json();
   }
   // ===========================================================================
-  // IPFS Wrapper Operations (via /api/*)
+  // Delete Operations
   // ===========================================================================
   /**
-   * Fetch an entity by PI
+   * Soft delete an entity (creates tombstone, preserves history)
    */
-  async getEntity(pi) {
-    const response = await fetch(`${this.gatewayUrl}/api/entities/${pi}`, {
-      headers: this.getHeaders()
-    });
-    if (response.status === 404) {
-      throw new EntityNotFoundError(pi);
+  async deleteEntity(id, request) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/delete`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      `Delete ${id}`
+    );
+    if (!response.ok) {
+      try {
+        const error = await response.json();
+        throw new DeleteError(error.message || `Delete failed: ${response.statusText}`, id);
+      } catch (e) {
+        if (e instanceof DeleteError) throw e;
+        await this.handleErrorResponse(response, `Delete ${id}`);
+      }
     }
+    return response.json();
+  }
+  /**
+   * Restore a deleted entity
+   */
+  async undeleteEntity(id, request) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/undelete`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      `Undelete ${id}`
+    );
     if (!response.ok) {
-      this.handleErrorResponse(response, `Failed to fetch entity ${pi}`);
+      try {
+        const error = await response.json();
+        throw new UndeleteError(error.message || `Undelete failed: ${response.statusText}`, id);
+      } catch (e) {
+        if (e instanceof UndeleteError) throw e;
+        await this.handleErrorResponse(response, `Undelete ${id}`);
+      }
     }
     return response.json();
   }
+  // ===========================================================================
+  // Content Operations
+  // ===========================================================================
   /**
-   * Fetch content by CID
+   * Upload files to IPFS
    */
-  async getContent(cid) {
-    const response = await fetch(`${this.gatewayUrl}/api/cat/${cid}`, {
-      headers: this.getHeaders()
-    });
+  async upload(files) {
+    let formData;
+    if (files instanceof FormData) {
+      formData = files;
+    } else {
+      formData = new FormData();
+      const fileArray = Array.isArray(files) ? files : [files];
+      for (const file of fileArray) {
+        if (file instanceof File) {
+          formData.append("file", file, file.name);
+        } else {
+          formData.append("file", file, "file");
+        }
+      }
+    }
+    const url = this.buildUrl("/upload");
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(null),
+        // No Content-Type for multipart
+        body: formData
+      },
+      "Upload files"
+    );
     if (!response.ok) {
-      this.handleErrorResponse(response, `Failed to fetch content ${cid}`);
+      await this.handleErrorResponse(response, "Upload files");
     }
-    return response.text();
+    return response.json();
   }
   /**
-   * Upload content and get CID
+   * Upload text content and return CID
    */
   async uploadContent(content, filename) {
-    const formData = new FormData();
     const blob = new Blob([content], { type: "text/plain" });
-    formData.append("file", blob, filename);
-    const headers = {};
-    if (this.authToken) {
-      headers["Authorization"] = `Bearer ${this.authToken}`;
+    const file = new File([blob], filename, { type: "text/plain" });
+    const [result] = await this.upload(file);
+    return result.cid;
+  }
+  /**
+   * Download file content by CID
+   */
+  async getContent(cid) {
+    const url = this.buildUrl(`/cat/${encodeURIComponent(cid)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Get content ${cid}`
+    );
+    if (response.status === 404) {
+      throw new ContentNotFoundError(cid);
     }
-    const response = await fetch(`${this.gatewayUrl}/api/upload`, {
-      method: "POST",
-      headers,
-      body: formData
-    });
     if (!response.ok) {
-      this.handleErrorResponse(response, "Failed to upload content");
+      await this.handleErrorResponse(response, `Get content ${cid}`);
     }
-    const result = await response.json();
-    return result[0].cid;
+    return response.text();
   }
   /**
-   * Update an entity with new components
+   * Download a DAG node (JSON) by CID
    */
-  async updateEntity(pi, update) {
-    const response = await fetch(`${this.gatewayUrl}/api/entities/${pi}/versions`, {
-      method: "POST",
-      headers: this.getHeaders(),
-      body: JSON.stringify({
-        expect_tip: update.expect_tip,
-        components: update.components,
-        components_remove: update.components_remove,
-        note: update.note
-      })
-    });
-    if (response.status === 409) {
-      const entity = await this.getEntity(pi);
-      throw new CASConflictError(
-        pi,
-        update.expect_tip,
-        entity.manifest_cid
-      );
+  async getDag(cid) {
+    const url = this.buildUrl(`/dag/${encodeURIComponent(cid)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Get DAG ${cid}`
+    );
+    if (response.status === 404) {
+      throw new ContentNotFoundError(cid);
     }
     if (!response.ok) {
-      this.handleErrorResponse(response, `Failed to update entity ${pi}`);
+      await this.handleErrorResponse(response, `Get DAG ${cid}`);
+    }
+    return response.json();
+  }
+  // ===========================================================================
+  // Arke Origin Operations
+  // ===========================================================================
+  /**
+   * Get the Arke origin block (genesis entity)
+   */
+  async getArke() {
+    const url = this.buildUrl("/arke");
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      "Get Arke"
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, "Get Arke");
+    }
+    return response.json();
+  }
+  /**
+   * Initialize the Arke origin block (creates if doesn't exist)
+   */
+  async initArke() {
+    const url = this.buildUrl("/arke/init");
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders()
+      },
+      "Init Arke"
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, "Init Arke");
     }
     return response.json();
   }
@@ -249,16 +691,20 @@ var EditClient = class {
    * Trigger reprocessing for an entity
    */
   async reprocess(request) {
-    const response = await fetch(`${this.gatewayUrl}/reprocess/reprocess`, {
-      method: "POST",
-      headers: this.getHeaders(),
-      body: JSON.stringify({
-        pi: request.pi,
-        phases: request.phases,
-        cascade: request.cascade,
-        options: request.options
-      })
-    });
+    const response = await this.fetchWithRetry(
+      `${this.gatewayUrl}/reprocess/reprocess`,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify({
+          pi: request.pi,
+          phases: request.phases,
+          cascade: request.cascade,
+          options: request.options
+        })
+      },
+      `Reprocess ${request.pi}`
+    );
     if (response.status === 403) {
       const error = await response.json().catch(() => ({}));
       throw new PermissionError(
@@ -268,29 +714,23 @@ var EditClient = class {
     }
     if (!response.ok) {
       const error = await response.json().catch(() => ({}));
-      throw new ReprocessError(
-        error.message || `Reprocess failed: ${response.statusText}`,
-        void 0
-      );
+      throw new ReprocessError(error.message || `Reprocess failed: ${response.statusText}`);
     }
     return response.json();
   }
   /**
    * Get reprocessing status by batch ID
-   *
-   * Uses exponential backoff retry to handle transient 500 errors
-   * that occur when the orchestrator is initializing.
-   *
-   * @param statusUrl - The status URL returned from reprocess()
-   * @param isFirstPoll - If true, uses a longer initial delay (orchestrator warmup)
    */
   async getReprocessStatus(statusUrl, isFirstPoll = false) {
-    const retryOptions = isFirstPoll ? { ...DEFAULT_RETRY_OPTIONS, initialDelayMs: 3e3 } : DEFAULT_RETRY_OPTIONS;
     const fetchUrl = this.statusUrlTransform ? this.statusUrlTransform(statusUrl) : statusUrl;
+    const delay = isFirstPoll ? 3e3 : this.retryConfig.baseDelay;
+    if (isFirstPoll) {
+      await this.sleep(delay);
+    }
     const response = await this.fetchWithRetry(
       fetchUrl,
       { headers: this.getHeaders() },
-      retryOptions
+      "Get reprocess status"
     );
     if (!response.ok) {
       throw new EditError(
@@ -301,6 +741,30 @@ var EditClient = class {
     }
     return response.json();
   }
+  // ===========================================================================
+  // Utility Methods
+  // ===========================================================================
+  /**
+   * Execute an operation with automatic CAS retry
+   */
+  async withCAS(id, operation, maxRetries = 3) {
+    let lastError = null;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        const entity = await this.getEntity(id);
+        return await operation(entity);
+      } catch (error) {
+        if (error instanceof CASConflictError && attempt < maxRetries - 1) {
+          lastError = error;
+          const delay = this.calculateDelay(attempt);
+          await this.sleep(delay);
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError || new EditError("withCAS failed after retries");
+  }
 };
 
 // src/edit/diff.ts
@@ -818,10 +1282,10 @@ var EditSession = class {
     const result = {};
     if (!this.entity) return result;
     const entityContext = {
-      pi: this.entity.pi,
+      pi: this.entity.id,
       ver: this.entity.ver,
       parentPi: this.entity.parent_pi,
-      childrenCount: this.entity.children_pi.length,
+      childrenCount: this.entity.children_pi?.length ?? 0,
       currentContent: this.loadedComponents
     };
     for (const component of this.scope.components) {
@@ -843,7 +1307,7 @@ var EditSession = class {
       }
       if (this.scope.cascade) {
         prompt = PromptBuilder.buildCascadePrompt(prompt, {
-          path: [this.entity.pi, this.entity.parent_pi || "root"].filter(Boolean),
+          path: [this.entity.id, this.entity.parent_pi || "root"].filter(Boolean),
           depth: 0,
           stopAtPi: this.scope.stopAtPi
         });
@@ -904,7 +1368,7 @@ var EditSession = class {
           note
         });
         this.result.saved = {
-          pi: version.pi,
+          pi: version.id,
           newVersion: version.ver,
           newTip: version.tip
         };
@@ -1015,15 +1479,25 @@ var EditSession = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BackendError,
   CASConflictError,
+  ContentNotFoundError,
+  DEFAULT_RETRY_CONFIG,
+  DeleteError,
   DiffEngine,
   EditClient,
   EditError,
   EditSession,
+  EntityExistsError,
   EntityNotFoundError,
+  IPFSError,
+  MergeError,
+  NetworkError,
   PermissionError,
   PromptBuilder,
   ReprocessError,
+  UndeleteError,
+  UnmergeError,
   ValidationError
 });
 //# sourceMappingURL=index.cjs.map