@xrmforge/typegen 0.3.0 → 0.4.0

package/dist/index.js

@@ -13,6 +13,7 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["META_SOLUTION_NOT_FOUND"] = "META_3002";
   ErrorCode2["META_FORM_PARSE_FAILED"] = "META_3003";
   ErrorCode2["META_ATTRIBUTE_UNKNOWN_TYPE"] = "META_3004";
+  ErrorCode2["META_VERSION_STAMP_EXPIRED"] = "META_3005";
   ErrorCode2["GEN_OUTPUT_WRITE_FAILED"] = "GEN_4001";
   ErrorCode2["GEN_TEMPLATE_FAILED"] = "GEN_4002";
   ErrorCode2["GEN_INVALID_IDENTIFIER"] = "GEN_4003";
@@ -331,6 +332,8 @@ var DataverseHttpClient = class {
   maxRateLimitRetries;
   readOnly;
   cachedToken = null;
+  /** Pending token refresh promise (prevents concurrent token requests) */
+  pendingTokenRefresh = null;
   // Semaphore for concurrency control (non-recursive)
   activeConcurrentRequests = 0;
   waitQueue = [];
@@ -401,6 +404,28 @@ var DataverseHttpClient = class {
     }
     return allResults;
   }
+  /**
+   * Execute a POST request that is semantically a read operation.
+   * Used for Dataverse actions like RetrieveMetadataChanges that require POST
+   * but do not modify data. Allowed even in read-only mode.
+   *
+   * @param path - API path (relative to apiUrl)
+   * @param body - JSON body to send
+   * @param signal - Optional AbortSignal to cancel the request
+   */
+  async postReadOnly(path2, body, signal) {
+    const ALLOWED_PATHS = ["/RetrieveMetadataChanges"];
+    const normalizedPath = path2.startsWith("/") ? path2 : `/${path2}`;
+    if (!ALLOWED_PATHS.some((p) => normalizedPath.startsWith(p))) {
+      throw new ApiRequestError(
+        "API_2001" /* API_REQUEST_FAILED */,
+        `postReadOnly is only allowed for safe read operations: ${ALLOWED_PATHS.join(", ")}. Got: "${normalizedPath}"`,
+        { path: normalizedPath }
+      );
+    }
+    const url = this.resolveUrl(path2);
+    return this.executeWithConcurrency(url, signal, "POST", body);
+  }
   // ─── Read-Only Enforcement ─────────────────────────────────────────────
   /**
    * Returns true if this client is in read-only mode (the safe default).
@@ -471,6 +496,18 @@ var DataverseHttpClient = class {
     if (this.cachedToken && this.cachedToken.expiresAt - Date.now() > TOKEN_BUFFER_MS) {
       return this.cachedToken.token;
     }
+    if (this.pendingTokenRefresh) {
+      return this.pendingTokenRefresh;
+    }
+    this.pendingTokenRefresh = this.refreshToken();
+    try {
+      return await this.pendingTokenRefresh;
+    } finally {
+      this.pendingTokenRefresh = null;
+    }
+  }
+  /** Internal: actually acquire a new token from the credential provider. */
+  async refreshToken() {
     log2.debug("Requesting new access token");
     const scope = `${this.baseUrl}/.default`;
     let tokenResponse;
@@ -508,10 +545,10 @@ var DataverseHttpClient = class {
    * The semaphore is acquired ONCE per logical request. Retries happen
    * INSIDE the semaphore to avoid the recursive slot exhaustion bug.
    */
-  async executeWithConcurrency(url, signal) {
+  async executeWithConcurrency(url, signal, method = "GET", requestBody) {
     await this.acquireSlot();
     try {
-      return await this.executeWithRetry(url, 1, 0, signal);
+      return await this.executeWithRetry(url, 1, 0, signal, method, requestBody);
     } finally {
       this.releaseSlot();
     }
@@ -521,10 +558,10 @@ var DataverseHttpClient = class {
       this.activeConcurrentRequests++;
       return Promise.resolve();
     }
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       this.waitQueue.push(() => {
         this.activeConcurrentRequests++;
-        resolve();
+        resolve2();
       });
     });
   }
@@ -534,7 +571,7 @@ var DataverseHttpClient = class {
     if (next) next();
   }
   // ─── Retry Logic (runs INSIDE a single concurrency slot) ─────────────────
-  async executeWithRetry(url, attempt, rateLimitRetries = 0, signal) {
+  async executeWithRetry(url, attempt, rateLimitRetries = 0, signal, method = "GET", requestBody) {
     if (signal?.aborted) {
       throw new ApiRequestError(
         "API_2001" /* API_REQUEST_FAILED */,
@@ -549,17 +586,21 @@ var DataverseHttpClient = class {
     signal?.addEventListener("abort", onUserAbort, { once: true });
     let response;
     try {
-      log2.debug(`GET ${url}`, { attempt });
+      log2.debug(`${method} ${url}`, { attempt });
+      const headers = {
+        Authorization: `Bearer ${token}`,
+        "OData-MaxVersion": "4.0",
+        "OData-Version": "4.0",
+        Accept: "application/json",
+        Prefer: 'odata.include-annotations="*"'
+      };
+      if (method === "POST") {
+        headers["Content-Type"] = "application/json";
+      }
       response = await fetch(url, {
-        method: "GET",
-        // Explicit: never rely on default
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "OData-MaxVersion": "4.0",
-          "OData-Version": "4.0",
-          Accept: "application/json",
-          Prefer: 'odata.include-annotations="*"'
-        },
+        method,
+        headers,
+        body: requestBody !== void 0 ? JSON.stringify(requestBody) : void 0,
         signal: controller.signal
       });
     } catch (fetchError) {
@@ -579,7 +620,7 @@ var DataverseHttpClient = class {
             url
           });
           await this.sleep(delay);
-          return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal);
+          return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal, method, requestBody);
         }
         throw new ApiRequestError(
           "API_2005" /* API_TIMEOUT */,
@@ -594,7 +635,7 @@ var DataverseHttpClient = class {
           error: fetchError instanceof Error ? fetchError.message : String(fetchError)
         });
         await this.sleep(delay);
-        return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal);
+        return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal, method, requestBody);
       }
       throw new ApiRequestError(
         "API_2001" /* API_REQUEST_FAILED */,
@@ -609,12 +650,12 @@ var DataverseHttpClient = class {
       signal?.removeEventListener("abort", onUserAbort);
     }
     if (!response.ok) {
-      return this.handleHttpError(response, url, attempt, rateLimitRetries, signal);
+      return this.handleHttpError(response, url, attempt, rateLimitRetries, signal, method, requestBody);
     }
-    log2.debug(`GET ${url} -> ${response.status}`, { attempt });
+    log2.debug(`${method} ${url} -> ${response.status}`, { attempt });
     return response.json();
   }
-  async handleHttpError(response, url, attempt, rateLimitRetries, signal) {
+  async handleHttpError(response, url, attempt, rateLimitRetries, signal, method = "GET", requestBody) {
     const body = await response.text();
     if (response.status === 429) {
       if (rateLimitRetries >= this.maxRateLimitRetries) {
@@ -631,12 +672,12 @@ var DataverseHttpClient = class {
         retryAfterHeader
       });
       await this.sleep(retryAfterMs);
-      return this.executeWithRetry(url, attempt, rateLimitRetries + 1, signal);
+      return this.executeWithRetry(url, attempt, rateLimitRetries + 1, signal, method, requestBody);
     }
     if (response.status === 401 && attempt === 1) {
       log2.warn("HTTP 401 received, clearing token cache and retrying");
       this.cachedToken = null;
-      return this.executeWithRetry(url, attempt + 1, 0, signal);
+      return this.executeWithRetry(url, attempt + 1, 0, signal, method, requestBody);
     }
     if (response.status >= 500 && attempt <= this.maxRetries) {
       const delay = this.calculateBackoff(attempt);
@@ -644,7 +685,7 @@ var DataverseHttpClient = class {
         `Server error ${response.status}, retrying in ${delay}ms (${attempt}/${this.maxRetries})`
       );
       await this.sleep(delay);
-      return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal);
+      return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal, method, requestBody);
     }
     const errorCode = response.status === 401 ? "API_2004" /* API_UNAUTHORIZED */ : response.status === 404 ? "API_2003" /* API_NOT_FOUND */ : "API_2001" /* API_REQUEST_FAILED */;
     throw new ApiRequestError(
@@ -667,7 +708,7 @@ var DataverseHttpClient = class {
     return Math.min(exponential + jitter, MAX_BACKOFF_MS);
   }
   sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return new Promise((resolve2) => setTimeout(resolve2, ms));
   }
 };
 
@@ -1243,10 +1284,12 @@ var MetadataCache = class {
   cacheDir;
   cacheFilePath;
   /**
-   * @param projectRoot - Root directory of the project (where .xrmforge/ will be created)
+   * @param cacheDir - Directory where cache files are stored.
+   *   Can be an absolute path or relative to cwd.
+   *   Defaults to ".xrmforge/cache" when constructed without argument.
    */
-  constructor(projectRoot) {
-    this.cacheDir = path.join(projectRoot, CACHE_DIR);
+  constructor(cacheDir = CACHE_DIR) {
+    this.cacheDir = path.resolve(cacheDir);
     this.cacheFilePath = path.join(this.cacheDir, CACHE_FILE);
   }
   /**
@@ -1362,6 +1405,105 @@ var MetadataCache = class {
   }
 };
 
+// src/metadata/change-detector.ts
+var log6 = createLogger("change-detector");
+var EXPIRED_VERSION_STAMP_ERROR = "0x80044352";
+var ChangeDetector = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Detect which entities have changed since the given version stamp.
+   *
+   * @param clientVersionStamp - The ServerVersionStamp from the last run (from cache)
+   * @returns Changed entity names, deleted entity names, and new version stamp
+   * @throws {MetadataError} with META_VERSION_STAMP_EXPIRED if stamp is too old (>90 days)
+   */
+  async detectChanges(clientVersionStamp) {
+    log6.info("Detecting metadata changes since last run");
+    const requestBody = {
+      Query: {
+        Criteria: {
+          FilterOperator: "And",
+          Conditions: []
+        },
+        Properties: {
+          AllProperties: false,
+          PropertyNames: ["LogicalName"]
+        }
+      },
+      ClientVersionStamp: clientVersionStamp,
+      DeletedMetadataFilters: "Entity"
+    };
+    let response;
+    try {
+      response = await this.http.postReadOnly(
+        "/RetrieveMetadataChanges",
+        requestBody
+      );
+    } catch (error) {
+      if (this.isExpiredVersionStampError(error)) {
+        throw new MetadataError(
+          "META_3005" /* META_VERSION_STAMP_EXPIRED */,
+          "Cached version stamp has expired (>90 days). A full metadata refresh is required.",
+          { clientVersionStamp }
+        );
+      }
+      throw error;
+    }
+    const changedEntityNames = (response.EntityMetadata ?? []).filter((e) => e.HasChanged !== false).map((e) => e.LogicalName).filter(Boolean);
+    const deletedEntityNames = [];
+    if (response.DeletedMetadata?.Keys) {
+      log6.info(`${response.DeletedMetadata.Keys.length} entity metadata IDs were deleted`);
+    }
+    const newVersionStamp = response.ServerVersionStamp;
+    log6.info(`Change detection complete: ${changedEntityNames.length} changed, ${deletedEntityNames.length} deleted`, {
+      changedEntityNames: changedEntityNames.length <= 10 ? changedEntityNames : `${changedEntityNames.length} entities`,
+      newVersionStamp: newVersionStamp.substring(0, 20) + "..."
+    });
+    return {
+      changedEntityNames,
+      deletedEntityNames,
+      newVersionStamp
+    };
+  }
+  /**
+   * Perform an initial metadata query to get the first ServerVersionStamp.
+   * This is used on the very first run (no cache exists).
+   *
+   * @returns The initial server version stamp
+   */
+  async getInitialVersionStamp() {
+    log6.info("Fetching initial server version stamp");
+    const requestBody = {
+      Query: {
+        Criteria: {
+          FilterOperator: "And",
+          Conditions: []
+        },
+        Properties: {
+          AllProperties: false,
+          PropertyNames: ["LogicalName"]
+        }
+      }
+    };
+    const response = await this.http.postReadOnly(
+      "/RetrieveMetadataChanges",
+      requestBody
+    );
+    log6.info("Initial version stamp acquired");
+    return response.ServerVersionStamp;
+  }
+  /** Check if an error is the expired version stamp error (0x80044352) */
+  isExpiredVersionStampError(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    const errorRecord = error;
+    const contextBody = errorRecord?.context ? String(errorRecord.context["responseBody"] ?? "") : "";
+    const combined = msg + contextBody;
+    return combined.includes(EXPIRED_VERSION_STAMP_ERROR) || combined.includes("ExpiredVersionStamp");
+  }
+};
+
 // src/metadata/labels.ts
 var DEFAULT_LABEL_CONFIG = {
   primaryLanguage: 1033
@@ -1455,10 +1597,12 @@ function getLabelLanguagesParam(config) {
 }
 
 // src/generators/type-mapping.ts
+var log7 = createLogger("type-mapping");
 function getEntityPropertyType(attributeType, isLookup = false) {
   if (isLookup) return "string";
   const mapping = ENTITY_TYPE_MAP[attributeType];
   if (mapping) return mapping;
+  log7.warn(`Unmapped AttributeType "${attributeType}" falling back to "unknown"`);
   return "unknown";
 }
 var ENTITY_TYPE_MAP = {
@@ -1497,6 +1641,7 @@ var ENTITY_TYPE_MAP = {
 function getFormAttributeType(attributeType) {
   const mapping = FORM_ATTRIBUTE_TYPE_MAP[attributeType];
   if (mapping) return mapping;
+  log7.warn(`Unmapped form AttributeType "${attributeType}" falling back to generic Attribute`);
   return "Xrm.Attributes.Attribute";
 }
 var FORM_ATTRIBUTE_TYPE_MAP = {
@@ -2380,6 +2525,7 @@ function createBoundAction(operationName, entityLogicalName, paramMeta) {
 }
 function createUnboundAction(operationName, paramMeta) {
   return {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- return type varies (Response or parsed JSON)
     async execute(params) {
       const req = buildUnboundRequest(
         operationName,
@@ -2664,7 +2810,7 @@ function groupCustomApis(apis) {
 }
 
 // src/orchestrator/file-writer.ts
-import { mkdir, writeFile, readFile } from "fs/promises";
+import { mkdir, writeFile, readFile, unlink } from "fs/promises";
 import { join as join2, dirname } from "path";
 async function writeGeneratedFile(outputDir, file) {
   const absolutePath = join2(outputDir, file.relativePath);
@@ -2696,6 +2842,24 @@ async function writeAllFiles(outputDir, files) {
   }
   return result;
 }
+async function deleteOrphanedFiles(outputDir, deletedEntityNames) {
+  let deleted = 0;
+  const subdirs = ["entities", "optionsets", "forms"];
+  for (const entityName of deletedEntityNames) {
+    for (const subdir of subdirs) {
+      const filePath = join2(outputDir, subdir, `${entityName}.d.ts`);
+      try {
+        await unlink(filePath);
+        deleted++;
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+    }
+  }
+  return deleted;
+}
 var GENERATED_HEADER = `// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 // This file was generated by @xrmforge/typegen. Do not edit manually.
 // Re-run 'xrmforge generate' to update.
@@ -2742,11 +2906,6 @@ var TypeGenerationOrchestrator = class {
   constructor(credential, config, logger) {
     this.credential = credential;
     this.logger = logger ?? createLogger("orchestrator");
-    if (config.useCache) {
-      throw new Error(
-        "Metadata caching is not yet implemented (planned for v0.2.0). Remove the useCache option or set it to false."
-      );
-    }
     this.config = {
       environmentUrl: config.environmentUrl,
       entities: [...config.entities],
@@ -2781,7 +2940,8 @@ var TypeGenerationOrchestrator = class {
     }
     this.logger.info("Starting type generation", {
       entities: this.config.entities,
-      outputDir: this.config.outputDir
+      outputDir: this.config.outputDir,
+      useCache: this.config.useCache
     });
     const httpClient = new DataverseHttpClient({
       environmentUrl: this.config.environmentUrl,
@@ -2804,80 +2964,71 @@ var TypeGenerationOrchestrator = class {
         durationMs: Date.now() - startTime
       };
     }
-    this.logger.info(`Processing ${this.config.entities.length} entities in parallel`);
-    const settled = await Promise.allSettled(
-      this.config.entities.map((entityName) => {
-        if (signal?.aborted) {
-          return Promise.reject(new Error("Generation aborted"));
+    let cacheStats;
+    const entitiesToFetch = new Set(this.config.entities);
+    const cachedEntityInfos = {};
+    let cache;
+    let newVersionStamp = null;
+    const deletedEntityNames = [];
+    if (this.config.useCache) {
+      const cacheResult = await this.resolveCache(httpClient, entitiesToFetch);
+      cache = cacheResult.cache;
+      newVersionStamp = cacheResult.newVersionStamp;
+      cacheStats = cacheResult.stats;
+      for (const [name, info] of Object.entries(cacheResult.cachedEntities)) {
+        cachedEntityInfos[name] = info;
+        entitiesToFetch.delete(name);
+      }
+      deletedEntityNames.push(...cacheResult.deletedEntityNames);
+    }
+    const fetchList = [...entitiesToFetch];
+    const failedEntities = /* @__PURE__ */ new Map();
+    if (fetchList.length > 0) {
+      this.logger.info(`Fetching ${fetchList.length} entities from Dataverse`);
+      const settled = await Promise.allSettled(
+        fetchList.map((entityName) => {
+          if (signal?.aborted) {
+            return Promise.reject(new Error("Generation aborted"));
+          }
+          return metadataClient.getEntityTypeInfo(entityName).then((info) => {
+            this.logger.info(`Fetched entity: ${entityName}`);
+            return { entityName, info };
+          });
+        })
+      );
+      for (let i = 0; i < settled.length; i++) {
+        const outcome = settled[i];
+        const entityName = fetchList[i];
+        if (outcome.status === "fulfilled") {
+          cachedEntityInfos[outcome.value.entityName] = outcome.value.info;
+        } else {
+          const errorMsg = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+          this.logger.error(`Failed to fetch entity: ${entityName}`, { error: outcome.reason });
+          failedEntities.set(entityName, errorMsg);
         }
-        return this.processEntity(entityName, metadataClient).then((result) => {
-          this.logger.info(`Completed entity: ${entityName} (${result.files.length} files)`);
-          return result;
-        });
-      })
-    );
-    for (let i = 0; i < settled.length; i++) {
-      const outcome = settled[i];
-      const entityName = this.config.entities[i];
-      if (outcome.status === "fulfilled") {
-        entityResults.push(outcome.value);
-        allFiles.push(...outcome.value.files);
-      } else {
-        const errorMsg = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
-        this.logger.error(`Failed to process entity: ${entityName}`, { error: outcome.reason });
+      }
+    }
+    this.logger.info(`Generating types for ${this.config.entities.length - failedEntities.size} entities`);
+    for (const entityName of this.config.entities) {
+      if (signal?.aborted) break;
+      if (failedEntities.has(entityName)) {
         entityResults.push({
           entityLogicalName: entityName,
           files: [],
-          warnings: [`Failed to process: ${errorMsg}`]
+          warnings: [`Failed to process: ${failedEntities.get(entityName)}`]
         });
+        continue;
       }
+      const entityInfo = cachedEntityInfos[entityName];
+      if (!entityInfo) continue;
+      const result = this.generateEntityFiles(entityName, entityInfo);
+      this.logger.info(`Generated entity: ${entityName} (${result.files.length} files)`);
+      entityResults.push(result);
+      allFiles.push(...result.files);
     }
     if (this.config.generateActions && !signal?.aborted) {
-      this.logger.info("Fetching Custom APIs...");
-      let customApis = await metadataClient.getCustomApis();
-      if (this.config.actionsFilter) {
-        const prefix = this.config.actionsFilter.toLowerCase();
-        const before = customApis.length;
-        customApis = customApis.filter((api) => api.api.uniquename.toLowerCase().startsWith(prefix));
-        this.logger.info(`Filtered Custom APIs by prefix "${this.config.actionsFilter}": ${before} -> ${customApis.length}`);
-      }
-      if (customApis.length > 0) {
-        const importPath = "@xrmforge/typegen";
-        const grouped = groupCustomApis(customApis);
-        for (const [key, apis] of grouped.actions) {
-          const entityName = key === "global" ? void 0 : key;
-          const declarations = generateActionDeclarations(apis, false, entityName, { importPath });
-          const module = generateActionModule(apis, false, { importPath });
-          allFiles.push({
-            relativePath: `actions/${key}.d.ts`,
-            content: addGeneratedHeader(declarations),
-            type: "action"
-          });
-          allFiles.push({
-            relativePath: `actions/${key}.ts`,
-            content: addGeneratedHeader(module),
-            type: "action"
-          });
-        }
-        for (const [key, apis] of grouped.functions) {
-          const entityName = key === "global" ? void 0 : key;
-          const declarations = generateActionDeclarations(apis, true, entityName, { importPath });
-          const module = generateActionModule(apis, true, { importPath });
-          allFiles.push({
-            relativePath: `functions/${key}.d.ts`,
-            content: addGeneratedHeader(declarations),
-            type: "action"
-          });
-          allFiles.push({
-            relativePath: `functions/${key}.ts`,
-            content: addGeneratedHeader(module),
-            type: "action"
-          });
-        }
-        this.logger.info(`Generated ${grouped.actions.size} action groups, ${grouped.functions.size} function groups`);
-      } else {
-        this.logger.info("No Custom APIs found");
-      }
+      const actionFiles = await this.generateActions(metadataClient);
+      allFiles.push(...actionFiles);
     }
     if (this.config.entities.length > 0) {
       const entityNamesContent = generateEntityNamesEnum(this.config.entities, {
@@ -2899,6 +3050,15 @@ var TypeGenerationOrchestrator = class {
       allFiles.push(indexFile);
     }
     const writeResult = await writeAllFiles(this.config.outputDir, allFiles);
+    if (deletedEntityNames.length > 0) {
+      const deleted = await deleteOrphanedFiles(this.config.outputDir, deletedEntityNames);
+      if (deleted > 0) {
+        this.logger.info(`Deleted ${deleted} orphaned files for removed entities`);
+      }
+    }
+    if (this.config.useCache && cache) {
+      await this.updateCache(cache, cachedEntityInfos, deletedEntityNames, newVersionStamp);
+    }
     const durationMs = Date.now() - startTime;
     const entityWarnings = entityResults.reduce((sum, r) => sum + r.warnings.length, 0);
     const totalWarnings = entityWarnings + writeResult.warnings.length;
@@ -2911,22 +3071,129 @@ var TypeGenerationOrchestrator = class {
       filesUnchanged: writeResult.unchanged,
       totalFiles: allFiles.length,
       totalWarnings,
-      durationMs
+      durationMs,
+      cacheUsed: cacheStats?.cacheUsed ?? false
     });
     return {
       entities: entityResults,
       totalFiles: allFiles.length,
       totalWarnings,
-      durationMs
+      durationMs,
+      cacheStats
     };
   }
   /**
-   * Process a single entity: fetch metadata, generate all output files.
+   * Resolve the cache: load existing cache, detect changes, determine which
+   * entities need to be fetched vs. can be served from cache.
+   *
+   * On any failure (corrupt cache, expired stamp), falls back to full refresh.
    */
-  async processEntity(entityName, metadataClient) {
+  async resolveCache(httpClient, requestedEntities) {
+    const cache = new MetadataCache(this.config.cacheDir);
+    const changeDetector = new ChangeDetector(httpClient);
+    let cacheData;
+    try {
+      cacheData = await cache.load(this.config.environmentUrl);
+    } catch {
+      this.logger.warn("Failed to load metadata cache, performing full refresh");
+      cacheData = null;
+    }
+    if (!cacheData || !cacheData.manifest.serverVersionStamp) {
+      this.logger.info("No valid cache found, performing full metadata refresh");
+      const stamp = await changeDetector.getInitialVersionStamp();
+      return {
+        cache,
+        cachedEntities: {},
+        deletedEntityNames: [],
+        newVersionStamp: stamp,
+        stats: {
+          cacheUsed: true,
+          fullRefresh: true,
+          entitiesFromCache: 0,
+          entitiesFetched: requestedEntities.size,
+          entitiesDeleted: 0
+        }
+      };
+    }
+    let changeResult;
+    try {
+      changeResult = await changeDetector.detectChanges(cacheData.manifest.serverVersionStamp);
+    } catch (error) {
+      const isExpired = error instanceof Error && error.message.includes("META_3005" /* META_VERSION_STAMP_EXPIRED */);
+      if (isExpired) {
+        this.logger.warn("Cache version stamp expired (>90 days), performing full refresh");
+      } else {
+        this.logger.warn("Change detection failed, performing full refresh", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+      const stamp = await changeDetector.getInitialVersionStamp();
+      return {
+        cache,
+        cachedEntities: {},
+        deletedEntityNames: [],
+        newVersionStamp: stamp,
+        stats: {
+          cacheUsed: true,
+          fullRefresh: true,
+          entitiesFromCache: 0,
+          entitiesFetched: requestedEntities.size,
+          entitiesDeleted: 0
+        }
+      };
+    }
+    const changedSet = new Set(changeResult.changedEntityNames);
+    const cachedEntities = {};
+    let entitiesFromCache = 0;
+    let entitiesFetched = 0;
+    for (const entityName of requestedEntities) {
+      if (changedSet.has(entityName) || !cacheData.entityTypeInfos[entityName]) {
+        entitiesFetched++;
+      } else {
+        cachedEntities[entityName] = cacheData.entityTypeInfos[entityName];
+        entitiesFromCache++;
+      }
+    }
+    const deletedEntityNames = changeResult.deletedEntityNames.filter(
+      (name) => requestedEntities.has(name)
+    );
+    this.logger.info(`Cache delta: ${entitiesFromCache} from cache, ${entitiesFetched} to fetch, ${deletedEntityNames.length} deleted`);
+    return {
+      cache,
+      cachedEntities,
+      deletedEntityNames,
+      newVersionStamp: changeResult.newVersionStamp,
+      stats: {
+        cacheUsed: true,
+        fullRefresh: false,
+        entitiesFromCache,
+        entitiesFetched,
+        entitiesDeleted: deletedEntityNames.length
+      }
+    };
+  }
+  /**
+   * Update the metadata cache after a successful generation run.
+   */
+  async updateCache(cache, entityTypeInfos, deletedEntityNames, newVersionStamp) {
+    try {
+      if (deletedEntityNames.length > 0) {
+        await cache.removeEntities(this.config.environmentUrl, deletedEntityNames, newVersionStamp);
+      }
+      await cache.save(this.config.environmentUrl, entityTypeInfos, newVersionStamp);
+      this.logger.info("Metadata cache updated");
+    } catch (error) {
+      this.logger.warn("Failed to update metadata cache", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  /**
+   * Generate all output files for a single entity from its metadata.
+   */
+  generateEntityFiles(entityName, entityInfo) {
     const warnings = [];
     const files = [];
-    const entityInfo = await metadataClient.getEntityTypeInfo(entityName);
     if (this.config.generateEntities) {
       const entityContent = generateEntityInterface(entityInfo, {
         labelConfig: this.config.labelConfig,
@@ -2982,6 +3249,58 @@ var TypeGenerationOrchestrator = class {
     }
     return { entityLogicalName: entityName, files, warnings };
   }
+  /**
+   * Generate Custom API Action/Function executor files.
+   */
+  async generateActions(metadataClient) {
+    const files = [];
+    this.logger.info("Fetching Custom APIs...");
+    let customApis = await metadataClient.getCustomApis();
+    if (this.config.actionsFilter) {
+      const prefix = this.config.actionsFilter.toLowerCase();
+      const before = customApis.length;
+      customApis = customApis.filter((api) => api.api.uniquename.toLowerCase().startsWith(prefix));
+      this.logger.info(`Filtered Custom APIs by prefix "${this.config.actionsFilter}": ${before} -> ${customApis.length}`);
+    }
+    if (customApis.length > 0) {
+      const importPath = "@xrmforge/typegen";
+      const grouped = groupCustomApis(customApis);
+      for (const [key, apis] of grouped.actions) {
+        const entityName = key === "global" ? void 0 : key;
+        const declarations = generateActionDeclarations(apis, false, entityName, { importPath });
+        const module = generateActionModule(apis, false, { importPath });
+        files.push({
+          relativePath: `actions/${key}.d.ts`,
+          content: addGeneratedHeader(declarations),
+          type: "action"
+        });
+        files.push({
+          relativePath: `actions/${key}.ts`,
+          content: addGeneratedHeader(module),
+          type: "action"
+        });
+      }
+      for (const [key, apis] of grouped.functions) {
+        const entityName = key === "global" ? void 0 : key;
+        const declarations = generateActionDeclarations(apis, true, entityName, { importPath });
+        const module = generateActionModule(apis, true, { importPath });
+        files.push({
+          relativePath: `functions/${key}.d.ts`,
+          content: addGeneratedHeader(declarations),
+          type: "action"
+        });
+        files.push({
+          relativePath: `functions/${key}.ts`,
+          content: addGeneratedHeader(module),
+          type: "action"
+        });
+      }
+      this.logger.info(`Generated ${grouped.actions.size} action groups, ${grouped.functions.size} function groups`);
+    } else {
+      this.logger.info("No Custom APIs found");
+    }
+    return files;
+  }
   /**
    * Extract picklist attributes with their OptionSet metadata.
    * Maps the raw EntityTypeInfo data to the format expected by the OptionSet generator.
@@ -3016,6 +3335,7 @@ export {
   ApiRequestError,
   AuthenticationError,
   BindingType,
+  ChangeDetector,
   ClientState,
   ClientType,
   ConfigError,