@xrmforge/typegen 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -21,6 +21,7 @@ declare enum ErrorCode {
     META_SOLUTION_NOT_FOUND = "META_3002",
     META_FORM_PARSE_FAILED = "META_3003",
     META_ATTRIBUTE_UNKNOWN_TYPE = "META_3004",
+    META_VERSION_STAMP_EXPIRED = "META_3005",
     GEN_OUTPUT_WRITE_FAILED = "GEN_4001",
     GEN_TEMPLATE_FAILED = "GEN_4002",
     GEN_INVALID_IDENTIFIER = "GEN_4003",
@@ -302,6 +303,8 @@ declare class DataverseHttpClient {
     private readonly maxRateLimitRetries;
     private readonly readOnly;
     private cachedToken;
+    /** Pending token refresh promise (prevents concurrent token requests) */
+    private pendingTokenRefresh;
     private activeConcurrentRequests;
     private readonly waitQueue;
     constructor(options: HttpClientOptions);
@@ -327,6 +330,16 @@ declare class DataverseHttpClient {
      * @param signal - Optional AbortSignal to cancel the request
      */
     getAll<T>(path: string, signal?: AbortSignal): Promise<T[]>;
+    /**
+     * 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
+     */
+    postReadOnly<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T>;
     /**
      * Returns true if this client is in read-only mode (the safe default).
      */
@@ -360,6 +373,8 @@ declare class DataverseHttpClient {
      */
     static escapeODataString(value: string): string;
     private getToken;
+    /** Internal: actually acquire a new token from the credential provider. */
+    private refreshToken;
     /**
      * Execute a request within the concurrency semaphore.
      * The semaphore is acquired ONCE per logical request. Retries happen
@@ -800,9 +815,11 @@ declare class MetadataCache {
     private readonly cacheDir;
     private readonly 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: string);
+    constructor(cacheDir?: string);
     /**
      * Load cached metadata from disk.
      * Returns null if no cache exists, cache is for a different environment,
@@ -837,6 +854,58 @@ declare class MetadataCache {
     exists(): Promise<boolean>;
 }
 
+/**
+ * @xrmforge/typegen - Metadata Change Detector
+ *
+ * Uses the Dataverse RetrieveMetadataChanges action to determine
+ * which entities have changed since the last generation run.
+ * This enables incremental type generation (only re-fetch changed entities).
+ *
+ * @see https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/samples/retrievemetadatachanges
+ */
+
+/** Result of a change detection query */
+interface ChangeDetectionResult {
+    /** Entity logical names that have changed (new or modified) */
+    changedEntityNames: string[];
+    /** Entity logical names that have been deleted */
+    deletedEntityNames: string[];
+    /** New server version stamp (store this for the next run) */
+    newVersionStamp: string;
+}
+/**
+ * Detects metadata changes in Dataverse using RetrieveMetadataChanges.
+ *
+ * Usage:
+ * ```typescript
+ * const detector = new ChangeDetector(httpClient);
+ * const result = await detector.detectChanges(cachedVersionStamp);
+ * // result.changedEntityNames = ['account', 'contact']
+ * // result.newVersionStamp = 'new-stamp-to-cache'
+ * ```
+ */
+declare class ChangeDetector {
+    private readonly http;
+    constructor(http: DataverseHttpClient);
+    /**
+     * 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)
+     */
+    detectChanges(clientVersionStamp: string): Promise<ChangeDetectionResult>;
+    /**
+     * 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
+     */
+    getInitialVersionStamp(): Promise<string>;
+    /** Check if an error is the expired version stamp error (0x80044352) */
+    private isExpiredVersionStampError;
+}
+
 /**
  * @xrmforge/typegen - Label Utilities
  *
@@ -1362,6 +1431,36 @@ declare function generateEntityFieldsEnum(info: EntityTypeInfo, options?: Entity
  */
 declare function generateEntityNavigationProperties(info: EntityTypeInfo, options?: EntityFieldsGeneratorOptions): string;
 
+/**
+ * @xrmforge/typegen - Entity Names Enum Generator
+ *
+ * Generates a single const enum with all entity logical names.
+ * Eliminates raw strings in Xrm.WebApi calls.
+ *
+ * Output pattern:
+ * ```typescript
+ * declare namespace XrmForge {
+ *   const enum EntityNames {
+ *     Account = 'account',
+ *     Contact = 'contact',
+ *     Lead = 'lead',
+ *   }
+ * }
+ * ```
+ */
+interface EntityNamesGeneratorOptions {
+    /** Namespace (default: "XrmForge") */
+    namespace?: string;
+}
+/**
+ * Generate a const enum mapping entity PascalCase names to logical names.
+ *
+ * @param entityNames - Array of entity logical names
+ * @param options - Generator options
+ * @returns TypeScript declaration string
+ */
+declare function generateEntityNamesEnum(entityNames: string[], options?: EntityNamesGeneratorOptions): string;
+
 /**
  * @xrmforge/typegen - Web API Helper Functions
  *
@@ -1781,17 +1880,19 @@ interface GenerateConfig {
     generateOptionSets?: boolean;
     /** Whether to generate Custom API Action/Function executors (default: false) */
     generateActions?: boolean;
+    /** Filter Custom APIs by uniquename prefix (e.g. "markant_"). Only APIs matching the prefix are generated. */
+    actionsFilter?: string;
     /**
      * Whether to use metadata cache for faster re-generation.
-     * @alpha Not yet implemented. Setting this to true will throw a ConfigError.
-     * Planned for v0.2.0.
+     * When enabled, only changed entities are re-fetched from Dataverse
+     * using RetrieveMetadataChanges delta detection.
+     * On first run or expired cache, a full refresh is performed automatically.
      * @defaultValue false
      */
     useCache?: boolean;
     /**
-     * Cache directory for metadata cache.
-     * @alpha Not yet implemented. Ignored until useCache is implemented.
-     * Planned for v0.2.0.
+     * Directory for metadata cache files.
+     * Relative paths are resolved from the current working directory.
      * @defaultValue ".xrmforge/cache"
      */
     cacheDir?: string;
@@ -1816,6 +1917,19 @@ interface GeneratedFile {
     /** Type of generated content */
     type: 'entity' | 'optionset' | 'form' | 'action';
 }
+/** Statistics about cache usage during generation */
+interface CacheStats {
+    /** Whether the cache was used in this run */
+    cacheUsed: boolean;
+    /** Whether this was a full refresh (no prior cache or expired stamp) */
+    fullRefresh: boolean;
+    /** Number of entities loaded from cache (unchanged) */
+    entitiesFromCache: number;
+    /** Number of entities fetched from Dataverse (new or changed) */
+    entitiesFetched: number;
+    /** Number of entities removed (deleted in Dataverse) */
+    entitiesDeleted: number;
+}
 /** Overall result of the generation process */
 interface GenerationResult {
     /** Per-entity results */
@@ -1826,6 +1940,8 @@ interface GenerationResult {
     totalWarnings: number;
     /** Duration in milliseconds */
     durationMs: number;
+    /** Cache statistics (present when useCache was enabled) */
+    cacheStats?: CacheStats;
 }
 
 /**
@@ -1870,9 +1986,24 @@ declare class TypeGenerationOrchestrator {
         signal?: AbortSignal;
     }): Promise<GenerationResult>;
     /**
-     * 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.
+     */
+    private resolveCache;
+    /**
+     * Update the metadata cache after a successful generation run.
+     */
+    private updateCache;
+    /**
+     * Generate all output files for a single entity from its metadata.
+     */
+    private generateEntityFiles;
+    /**
+     * Generate Custom API Action/Function executor files.
      */
-    private processEntity;
+    private generateActions;
     /**
      * Extract picklist attributes with their OptionSet metadata.
      * Maps the raw EntityTypeInfo data to the format expected by the OptionSet generator.
@@ -1880,4 +2011,4 @@ declare class TypeGenerationOrchestrator {
     private getPicklistAttributes;
 }
 
-export { type ActionGeneratorOptions, ApiRequestError, type AttributeMetadata, type AuthConfig, type AuthMethod, AuthenticationError, BindingType, type BoundActionExecutor, type BoundActionWithParamsExecutor, type BoundFunctionExecutor, type ClientCredentialsAuth, ClientState, ClientType, ConfigError, ConsoleLogSink, type CustomApiTypeInfo, DEFAULT_LABEL_CONFIG, DataverseHttpClient, type DateTimeAttributeMetadata, type DecimalAttributeMetadata, type DeviceCodeAuth, DisplayState, type EntityFieldsGeneratorOptions, type EntityGenerationResult, type EntityGeneratorOptions, type EntityMetadata, type EntityTypeInfo, ErrorCode, FastXmlParser, type FormControl, type FormGeneratorOptions, FormNotificationLevel, type FormSection, type FormTab, type GenerateConfig, type GeneratedFile, GenerationError, type GenerationResult, type GroupedCustomApis, type HttpClientOptions, type IntegerAttributeMetadata, type InteractiveAuth, JsonLogSink, type Label, type LabelConfig, type LocalizedLabel, type LogEntry, LogLevel, type LogSink, Logger, type LookupAttributeMetadata, type ManyToManyRelationshipMetadata, MetadataCache, MetadataClient, MetadataError, type MoneyAttributeMetadata, type OneToManyRelationshipMetadata, OperationType, type OptionMetadata, type OptionSetGeneratorOptions, type OptionSetMetadata, type ParameterMeta, type ParameterMetaMap, type ParsedForm, type PicklistAttributeMetadata, RequiredLevel, SaveMode, SilentLogSink, type SolutionComponent, type StateAttributeMetadata, type StatusAttributeMetadata, type StringAttributeMetadata, StructuralProperty, SubmitMode, type SystemFormMetadata, TypeGenerationOrchestrator, type UnboundActionExecutor, type UnboundActionWithParamsExecutor, type UnboundFunctionExecutor, type XmlElement, type XmlParser, XrmForgeError, configureLogging, createBoundAction, createBoundFunction, createCredential, createLogger, createUnboundAction, createUnboundFunction, defaultXmlParser, disambiguateEnumMembers, executeMultiple, executeRequest, extractControlFields, getJSDocLabel as formatDualLabel, generateActionDeclarations, generateActionModule, generateActivityPartyInterface, generateEntityFieldsEnum, generateEntityForms, generateEntityInterface, generateEntityNavigationProperties, generateEntityOptionSets, generateEnumMembers, generateFormInterface, generateOptionSetEnum, getEntityPropertyType, getFormAttributeType, getFormControlType, getFormMockValueType, getJSDocLabel, getLabelLanguagesParam, getPrimaryLabel, getSecondaryLabel, groupCustomApis, isLookupType, isPartyListType, isRateLimitError, isXrmForgeError, labelToIdentifier, parseForm, parseFormattedValue, parseLookup, parseLookups, select, selectExpand, shouldIncludeInEntityInterface, toLookupValueProperty, toPascalCase, toSafeIdentifier, withProgress };
+export { type ActionGeneratorOptions, ApiRequestError, type AttributeMetadata, type AuthConfig, type AuthMethod, AuthenticationError, BindingType, type BoundActionExecutor, type BoundActionWithParamsExecutor, type BoundFunctionExecutor, type CacheStats, type ChangeDetectionResult, ChangeDetector, type ClientCredentialsAuth, ClientState, ClientType, ConfigError, ConsoleLogSink, type CustomApiTypeInfo, DEFAULT_LABEL_CONFIG, DataverseHttpClient, type DateTimeAttributeMetadata, type DecimalAttributeMetadata, type DeviceCodeAuth, DisplayState, type EntityFieldsGeneratorOptions, type EntityGenerationResult, type EntityGeneratorOptions, type EntityMetadata, type EntityNamesGeneratorOptions, type EntityTypeInfo, ErrorCode, FastXmlParser, type FormControl, type FormGeneratorOptions, FormNotificationLevel, type FormSection, type FormTab, type GenerateConfig, type GeneratedFile, GenerationError, type GenerationResult, type GroupedCustomApis, type HttpClientOptions, type IntegerAttributeMetadata, type InteractiveAuth, JsonLogSink, type Label, type LabelConfig, type LocalizedLabel, type LogEntry, LogLevel, type LogSink, Logger, type LookupAttributeMetadata, type ManyToManyRelationshipMetadata, MetadataCache, MetadataClient, MetadataError, type MoneyAttributeMetadata, type OneToManyRelationshipMetadata, OperationType, type OptionMetadata, type OptionSetGeneratorOptions, type OptionSetMetadata, type ParameterMeta, type ParameterMetaMap, type ParsedForm, type PicklistAttributeMetadata, RequiredLevel, SaveMode, SilentLogSink, type SolutionComponent, type StateAttributeMetadata, type StatusAttributeMetadata, type StringAttributeMetadata, StructuralProperty, SubmitMode, type SystemFormMetadata, TypeGenerationOrchestrator, type UnboundActionExecutor, type UnboundActionWithParamsExecutor, type UnboundFunctionExecutor, type XmlElement, type XmlParser, XrmForgeError, configureLogging, createBoundAction, createBoundFunction, createCredential, createLogger, createUnboundAction, createUnboundFunction, defaultXmlParser, disambiguateEnumMembers, executeMultiple, executeRequest, extractControlFields, getJSDocLabel as formatDualLabel, generateActionDeclarations, generateActionModule, generateActivityPartyInterface, generateEntityFieldsEnum, generateEntityForms, generateEntityInterface, generateEntityNamesEnum, generateEntityNavigationProperties, generateEntityOptionSets, generateEnumMembers, generateFormInterface, generateOptionSetEnum, getEntityPropertyType, getFormAttributeType, getFormControlType, getFormMockValueType, getJSDocLabel, getLabelLanguagesParam, getPrimaryLabel, getSecondaryLabel, groupCustomApis, isLookupType, isPartyListType, isRateLimitError, isXrmForgeError, labelToIdentifier, parseForm, parseFormattedValue, parseLookup, parseLookups, select, selectExpand, shouldIncludeInEntityInterface, toLookupValueProperty, toPascalCase, toSafeIdentifier, withProgress };