@xrmforge/typegen 0.6.0 → 0.7.1

package/docs/architektur/11-agent-md.md

@@ -0,0 +1,38 @@
+# 11. AGENT.md System
+
+## 11.1 Zweck
+
+Die AGENT.md ist eine generierte Datei, die KI-Coding-Assistenten (Claude, ChatGPT, Copilot, Cursor) beibringt, wie sie optimale D365-Formularskripte mit XrmForge schreiben. Sie wird von `xrmforge init` erzeugt und im Projektstamm abgelegt.
+
+## 11.2 Inhaltsstruktur
+
+1. **Package-Übersicht** - Was jedes @xrmforge-Package tut
+2. **10 Regeln: Immer** - Fields Enum, OptionSet Enum, FormContext-Cast, EntityNames, parseLookup, select, createFormMock, Modul-Exports, Tabs/Sections Enums, Fehlerbehandlung
+3. **Regeln: Niemals** - Rohe Strings, Magic Numbers, Xrm.Page, synchrone XHR, eval, window-Zuweisungen
+4. **Vorher/Nachher-Beispiele** - Feldzugriff, OptionSet-Vergleich, Testen
+5. **Pattern-Erkennungstabelle** - Zuordnung von Legacy-Pattern zu XrmForge-Ersetzung
+6. **OptionSet-Enum-Erstellungsanleitung** - Wie man Enums aus Magic Numbers in Legacy-Code erstellt
+7. **Testen mit setupXrmMock** - Globales Xrm-Mock-Pattern
+8. **Build-Befehle** - xrmforge build, Watch-Modus
+9. **@types/xrm-Fallstricke** - Bekannte Probleme und Workarounds
+10. **Dateistruktur** - Erwartetes Projektlayout
+
+## 11.3 Template-System
+
+Die AGENT.md ist als `src/scaffold/templates/AGENT.md` im devkit-Package gespeichert und wird zur Scaffolding-Zeit über `template-loader.ts` geladen. Es ist keine Variablenersetzung nötig (die Datei ist statisch).
+
+## 11.4 Ergebnisse des KI-Vergleichstests
+
+Fünf KI-Modelle wurden beim Konvertieren von Legacy-D365-JavaScript (account.js + lm_helper.js, 1.288 Zeilen) zu TypeScript mit XrmForge getestet:
+
+| Rang | Modell | Punkte | Werkzeug | Stärke |
+|------|--------|--------|----------|--------|
+| 1 | Claude Opus 4.6 | 42/50 | Claude Code | Meiste Tests (62), beste Codestruktur |
+| 2 | Claude Sonnet 4.6 | 41/50 | Claude Code | Meiste Bugs gefunden (5), bester DI-Ansatz |
+| 3 | Cursor Composer 2 | 35/50 | Cursor IDE | Hat select() Node-API-Problem erkannt |
+| 4 | ChatGPT GPT-4o | 30/50 | ChatGPT Web | Funktional, aber weniger XrmForge-spezifisch |
+| 5 | MS Copilot | 12/50 | Browser-Chat | Kein Workspace-Zugriff, hat AGENT.md nie gesehen |
+
+**Kriterien (11, maximal 5 Punkte je = 55 max):** Fields-Enum-Nutzung, OptionSet-Enums, FormContext-Typisierung, XrmForge-Helpers, Modul-Exports, Tests vorhanden, Testqualität, Fehlerbehandlung, Codequalität, gefundene Bugs, Dokumentation.
+
+**Zentrale Erkenntnis:** Keine KI hat konsistent `@xrmforge/typegen/helpers`-Imports (select, parseLookup) verwendet. Dies bleibt die grösste Adoptionslücke.

package/docs/architektur/12-xrm-fallstricke.md

@@ -0,0 +1,14 @@
+# 12. @types/xrm-Fallstricke
+
+Bekannte Probleme bei der Arbeit mit `@types/xrm`:
+
+| Problem | Falsch | Richtig |
+|---------|--------|---------|
+| Form-Interface | `interface extends Xrm.FormContext` | `extends Omit<Xrm.FormContext, 'getAttribute' \| 'getControl'>` |
+| AlertDialogResponse | `Xrm.Navigation.AlertDialogResponse` | `Xrm.Async.PromiseLike<void>` (Typ existiert nicht) |
+| ConfirmDialogResponse | `Xrm.Navigation.ConfirmDialogResponse` | `Xrm.Navigation.ConfirmResult` (Typ existiert nicht) |
+| setNotification | `setNotification(message)` | `setNotification(message, uniqueId)` (erfordert 2 Argumente) |
+| openFile | `openFile({ fileName, ... })` | Muss `fileSize`-Eigenschaft in FileDetails enthalten |
+| SubmitMode | `Xrm.Attributes.SubmitMode` | `Xrm.SubmitMode` |
+| const enum in .d.ts | `const enum` in `.d.ts`-Dateien | Reguläres `enum` in `.ts`-Dateien verwenden (vitest kann const enums aus .d.ts nicht importieren) |
+| Grid.refresh() | `grid.refresh()` | `(grid as any).refresh()` (nicht typisiert in @types/xrm) |

package/docs/architektur/13-helpers.md

@@ -0,0 +1,50 @@
+# 13. @xrmforge/helpers Package
+
+## 13.1 Problem
+
+Der bisherige Ansatz nutzte einen `/helpers`-Subpath-Export auf `@xrmforge/typegen`. Das war verwirrend, weil typegen ein Node.js-Codegenerierungstool ist, während die Helpers browsersichere Laufzeitfunktionen sind. Der Subpath `@xrmforge/typegen/helpers` war nicht intuitiv und KI-Coding-Assistenten haben ihn durchgängig nicht gefunden.
+
+## 13.2 Lösung
+
+Ein eigenständiges `@xrmforge/helpers`-Package bündelt allen browsersicheren Laufzeitcode. Keine Node.js-Abhängigkeiten. Klarer, auffindbarer Import-Pfad:
+
+```typescript
+// Import vom dedizierten helpers-Package
+import { select, parseLookup, typedForm } from '@xrmforge/helpers';
+```
+
+## 13.3 Exports
+
+**Web-API-Helpers:**
+- `select(...fields: string[]): string` - Erstellt `?$select=field1,field2`
+- `selectExpand(fields: string[], expand: string): string` - Erstellt `?$select=...&$expand=...`
+- `parseLookup(response: Record<string, unknown>, fieldName: string): LookupValue | null` - Parst `_fieldname_value` mit OData-Annotationen
+- `parseLookups(response: Record<string, unknown>, fieldName: string): LookupValue[]` - Multi-Value-Lookup-Parsing
+- `parseFormattedValue(response: Record<string, unknown>, fieldName: string): string | null` - Extrahiert `@OData.Community.Display.V1.FormattedValue`
+
+**Xrm-Konstanten (8 const enums):**
+- DisplayState, FormNotificationLevel, RequiredLevel, SubmitMode, SaveMode, ClientType, ClientState, OperationType
+
+**typedForm()-Proxy:**
+- `typedForm<TForm>(formContext)` - Gibt einen Proxy zurück, bei dem `form.name` an `getAttribute('name')` delegiert
+- GET-Trap: Property-Zugriff delegiert an getAttribute(); `$context` gibt den rohen FormContext zurück; `$control(name)` gibt getControl() zurück
+- SET-Trap: Wirft TypeError und erzwingt die Verwendung von `.setValue()`
+- HAS-Trap: Prüft, ob ein Attribut auf dem Formular existiert
+
+**Action/Function-Laufzeit:**
+- `createBoundAction(entityName, actionName)` - Erstellt einen gebundenen Action-Executor
+- `executeRequest(request)` - Führt einen Organization Request über Xrm.WebApi.online.execute aus
+- `withProgress(message, fn)` - Umhüllt eine asynchrone Operation mit Xrm.Utility.showProgressIndicator
+
+## 13.4 Migration
+
+Der alte Import-Pfad `@xrmforge/typegen/helpers` wurde entfernt. Alle Imports aktualisieren:
+
+```typescript
+// Alt (entfernt)
+import { select } from '@xrmforge/typegen/helpers';
+import { typedForm } from '@xrmforge/formhelpers';
+
+// Neu
+import { select, typedForm } from '@xrmforge/helpers';
+```

package/docs/architektur/14-showcases.md

@@ -0,0 +1,21 @@
+# 14. Showcases
+
+## 14.1 Markant WebResources (Produktions-Showcase)
+
+Befindet sich im XrmForge-Workspace-Repository unter `docs/07_showcase/markant-webresources/`.
+
+- **30 WebResources** in `src/forms/` (Account, Contact, Opportunity, Lead, Quote, Email, Task usw.)
+- **1 gemeinsame Bibliothek** (DSGVO-Aufbewahrungsfristen-UI)
+- **9 Testdateien** mit 59 Tests
+- **79 generierte Typings:** 25 Form-Interfaces, 28 Entity-Interfaces, 22 OptionSet-Dateien, 4 Action-Executors
+- **esbuild-Build** über xrmforge.config.json (32 Einträge)
+- **Deploy-Skript** (deploy.mjs) mit @azure/identity-Authentifizierung, inkrementellem Deployment, Hash-basierter Änderungserkennung
+- **27 Entitäten, 236 OptionSet-Enums, 95 Form-Interfaces, 7 Custom-API-Executors**
+
+## 14.2 LMApp WebResources (KI-Vergleichs-Showcase)
+
+Erstellt während der KI-Vergleichstests (Session 9). 18 Legacy-JavaScript-Formularskripte (~8.400 Zeilen) zu TypeScript mit XrmForge-Patterns konvertiert.
+
+- **19 WebResources** mit Fields Enums, EntityNames, OptionSet Enums
+- **84 Tests** in 8 Testdateien
+- **XrmForge-optimiert:** Alle 10 AGENT.md-Regeln angewendet (FormContext-Cast, Fields Enum, EntityNames, OptionSet Enums, gemeinsames getLookupObject, Tab Enums)

package/docs/architektur/15-ci-cd.md

@@ -0,0 +1,49 @@
+# 15. CI/CD
+
+## 15.1 GitHub Actions CI (`.github/workflows/ci.yml`)
+
+**Auslöser:** Push auf main, Pull Requests gegen main.
+
+**Matrix:** Node 20, Node 22 auf ubuntu-latest.
+
+**Schritte:**
+1. Checkout
+2. pnpm einrichten (aus packageManager-Feld)
+3. Node.js einrichten (Matrix-Version)
+4. `pnpm install --frozen-lockfile`
+5. `pnpm lint`
+6. `pnpm -r exec tsc --noEmit` (Typecheck aller Packages)
+7. `pnpm build`
+8. `pnpm test`
+9. Coverage (nur Node 22): `npx vitest run --coverage` in typegen
+
+## 15.2 Release-Workflow (`.github/workflows/release.yml`)
+
+**Auslöser:** Nach erfolgreicher CI bei Push auf main.
+
+**Schritte:**
+1. Checkout, pnpm einrichten, Node 22 einrichten
+2. `pnpm install --frozen-lockfile`
+3. `pnpm build`
+4. Changesets-Action: erstellt Release-PR oder veröffentlicht auf npm
+
+**Publish-Befehl:** `pnpm release` = `turbo run build && changeset publish`
+
+## 15.3 Turbo-Pipeline
+
+```
+build:      dependsOn: [^build], outputs: [dist/**]
+test:       dependsOn: [build]
+typecheck:  dependsOn: [^build]
+lint:       (keine Abhängigkeiten)
+dev:        cache: false, persistent: true
+clean:      cache: false
+```
+
+## 15.4 Changesets
+
+Konfiguriert für öffentlichen npm-Zugriff, automatische Aktualisierung interner Abhängigkeiten auf Patch-Ebene. Veröffentlichung erfordert NPM_TOKEN Secret.
+
+## 15.5 Veröffentlichungsreihenfolge
+
+Aufgrund interner Abhängigkeiten: zuerst typegen, dann devkit, dann cli. Es muss `pnpm publish` verwendet werden (nicht `npm publish`), um `workspace:*`-Referenzen in echte Versionen aufzulösen.

package/docs/architektur/16-technische-schulden.md

@@ -0,0 +1,17 @@
+# 16. Technische Schulden
+
+## 16.1 Bekannte Probleme
+
+| Problem | Status | Priorität |
+|---------|--------|-----------|
+| parseLookup/select wird von KI-Assistenten nicht übernommen | Offen | Hoch |
+| release.yml doppelte Ausführungen (CI löst Release aus, Release löst CI erneut aus) | Offen | Niedrig |
+| Keine Integrationstests gegen Live-Dataverse | Offen (OE-4) | Mittel |
+| @xrmforge/webapi hat keine Action/Function-Unterstützung | Akzeptiert | Niedrig |
+| devDependency-Versionen im generierten package.json sind auf alte Versionen fixiert | Offen | Niedrig |
+
+## 16.2 Akzeptierte Einschränkungen
+
+- **const-enum-Einschränkung:** Kann zur Laufzeit von Test-Frameworks nicht aus `.d.ts`-Dateien importiert werden. Workaround: `.ts`-Dateien mit regulärem `enum` für manuelle Typings verwenden.
+- **Grid.refresh() erfordert `as any`:** Nicht typisiert in @types/xrm.
+- **Eine Solution pro Entität:** Wenn eine Entität in mehreren Solutions vorkommt, wird sie nur einmal generiert.

package/docs/architektur/17-roadmap.md

@@ -0,0 +1,25 @@
+# 17. Roadmap
+
+## 17.1 Nächste Schritte (Prioritätsreihenfolge)
+
+1. **parseLookup/select-Adoption** - AGENT.md-Beispiele verbessern, damit KI-Assistenten konsistent `/helpers`-Imports verwenden
+2. **LMApp-Showcase-Neugenerierung** - Mit aktuellen Releases (testing@0.2.0, devkit@0.4.0 mit verbesserter AGENT.md)
+3. **KI-Battle Runde 3** - Sonnet vs. Opus erneut testen nach Verbesserungen, um Fortschritt zu messen
+4. **Dokumentationswebsite** - xrmforge.dev oder xrmforge.io (OE-3)
+
+## 17.2 Offene Entscheidungen
+
+| ID | Entscheidung | Status |
+|----|--------------|--------|
+| OE-1 | npm-Scope-Verfügbarkeit (@xrmforge) | Offen |
+| OE-2 | GitHub-Org vs. persönliches Repo | Entschieden: persönlich (juergenbeck/XrmForge) |
+| OE-3 | Dokumentationsdomain (xrmforge.dev oder .io) | Offen |
+| OE-4 | Dataverse-Testumgebung für Integrationstests | Offen |
+| OE-5 | Publisher-Prefix und Solution-Name für PCF/WebResource-Tests | Offen |
+
+## 17.3 Zukünftige Möglichkeiten
+
+- Relationship-Names const enum (OE-7, niedrige Priorität)
+- @xrmforge/webapi mit Action/Function-Unterstützung (DataverseHttpClient wiederverwenden)
+- Plugin-System für benutzerdefinierte Generatoren und Typ-Zuordnungen
+- Serverseitige Generierung (Custom API in Dataverse)

package/docs/architektur/18-designprinzipien.md

@@ -0,0 +1,22 @@
+# 18. Designprinzipien
+
+Die 18 Designprinzipien, die die gesamte XrmForge-Entwicklung bestimmen:
+
+1. **Erweitern, nicht ersetzen** - Typen bauen auf @types/xrm auf, überschreiben sie nie.
+2. **TypeScript durchgängig** - 100% TypeScript-nativ. Kein .NET, kein ADAL.
+3. **Code muss bauen** - Jeder Arbeitsschritt endet mit grünem Build + Tests.
+4. **Recherche vor Geschwindigkeit** - Untersuchen, vergleichen, entscheiden, dann implementieren. Niemals raten.
+5. **Kein Modul ohne Grundlagen** - Fehlerbehandlung, Logging, Unit-Tests, JSDoc auf allen öffentlichen APIs.
+6. **Monorepo-Disziplin** - Jedes Package eigenständig, keine zirkulären Abhängigkeiten, Barrel-Exports.
+7. **Enterprise-Resilienz** - Retry + exponentielles Backoff, Rate-Limit-Erkennung, Token-Caching, Read-only als Standard.
+8. **esbuild-first, webpack-kompatibel** - Standard: esbuild (schnell). webpack bleibt unterstützt. IIFE-Output für D365.
+9. **Nur MSAL-Authentifizierung** - Ausschliesslich @azure/identity (kein Legacy-ADAL). Drei Flows: Client Credentials, Browser, Device Code.
+10. **Review erforderlich** - Nach jedem Schritt sofortiges kritisches Review (6 Dimensionen). Nicht fragen, ob Review gewünscht ist.
+11. **Session-State erforderlich** - session-state.md aktualisiert, Changelog geschrieben, offene Fragen erfasst.
+12. **Keine halben Sachen** - Jeder Schritt vollständig abgeschlossen: grüner Build + Tests + Review vor dem nächsten Schritt.
+13. **Fundierte Architekturentscheidungen** - Recherchieren, vergleichen, mit Pro/Contra empfehlen, Entscheidung einholen, persistieren.
+14. **Abstraktion statt Vendor-Lock-in** - Externe Abhängigkeiten hinter Interfaces (Parser, Auth, Bundler).
+15. **Zweisprachige Labels** - Primärsprache (1033/Englisch) für Bezeichner, Sekundärsprache in JSDoc. Deutsche Umlaute transliteriert.
+16. **Review mit Recherche und Live-Verifikation** - Internetrecherche, Live-D365-Verifikation, Produktionscode-Prüfungen, Quellen zitieren.
+17. **Aufschub hinterfragen** - "Später"-Check: Wird es schwieriger? API-Vertrag? Echter Aufwand? Technische Gründe?
+18. **Read-only als Standard für Dataverse-Zugriff** - DataverseHttpClient ist standardmässig readOnly: true. Schreibzugriff ist ein explizites Opt-in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xrmforge/typegen",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "TypeScript declaration generator for Dynamics 365 / Dataverse",
   "keywords": [
     "dynamics-365",
@@ -29,15 +29,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    },
-    "./helpers": {
-      "types": "./dist/helpers.d.ts",
-      "import": "./dist/helpers.js",
-      "default": "./dist/helpers.js"
     }
   },
   "files": [
     "dist",
+    "docs",
     "MIGRATION.md"
   ],
   "sideEffects": false,
@@ -59,12 +55,12 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/copy-docs.mjs",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist docs"
   }
 }

package/dist/helpers.d.ts

@@ -1,203 +0,0 @@
-/**
- * @xrmforge/typegen - Web API Helper Functions
- *
- * Lightweight utility functions for building OData query strings
- * with type-safe field names from generated Fields enums.
- *
- * Zero runtime overhead when used with const enums (values are inlined).
- *
- * @example
- * ```typescript
- * import { select } from '@xrmforge/typegen';
- *
- * Xrm.WebApi.retrieveRecord(ref.entityType, ref.id, select(
- *   AccountFields.Name,
- *   AccountFields.WebsiteUrl,
- *   AccountFields.Address1Line1,
- * ));
- * ```
- */
-/**
- * Build an OData $select query string from field names.
- *
- * @param fields - Field names (use generated Fields enum for type safety)
- * @returns OData query string (e.g. "?$select=name,websiteurl,address1_line1")
- */
-declare function select(...fields: string[]): string;
-/**
- * Parse a lookup field from a Dataverse Web API response into a LookupValue.
- *
- * Dataverse returns lookups as `_fieldname_value` with OData annotations:
- * - `_fieldname_value` (GUID)
- * - `_fieldname_value@OData.Community.Display.V1.FormattedValue` (display name)
- * - `_fieldname_value@Microsoft.Dynamics.CRM.lookuplogicalname` (entity type)
- *
- * This function extracts all three into an `Xrm.LookupValue` object.
- *
- * @param response - The raw Web API response object
- * @param navigationProperty - Navigation property name (use NavigationProperties enum for type safety)
- * @returns Xrm.LookupValue or null if the lookup is empty
- *
- * @example
- * ```typescript
- * // Mit NavigationProperties-Enum (empfohlen, keine Raw-Strings):
- * parseLookup(result, AccountNav.Country);
- *
- * // Oder mit Navigation Property Name direkt:
- * parseLookup(result, 'markant_address1_countryid');
- * ```
- */
-declare function parseLookup(response: Record<string, unknown>, navigationProperty: string): {
-    id: string;
-    name: string;
-    entityType: string;
-} | null;
-/**
- * Parse multiple lookup fields from a Dataverse Web API response at once.
- *
- * @param response - The raw Web API response object
- * @param navigationProperties - Navigation property names to parse
- * @returns Map of navigation property name to LookupValue (null entries omitted)
- *
- * @example
- * ```typescript
- * const lookups = parseLookups(result, ['markant_address1_countryid', 'parentaccountid']);
- * formContext.getAttribute(Fields.Country).setValue(
- *   lookups.markant_address1_countryid ? [lookups.markant_address1_countryid] : null
- * );
- * ```
- */
-declare function parseLookups(response: Record<string, unknown>, navigationProperties: string[]): Record<string, {
-    id: string;
-    name: string;
-    entityType: string;
-} | null>;
-/**
- * Get the formatted (display) value of any field from a Web API response.
- *
- * Works for OptionSets, Lookups, DateTimes, Money, and other formatted fields.
- *
- * @param response - The raw Web API response object
- * @param fieldName - The field logical name (e.g. "statecode", "createdon")
- * @returns The formatted string value, or null if not available
- *
- * @example
- * ```typescript
- * const status = parseFormattedValue(result, 'statecode');
- * // "Active" (statt 0)
- * ```
- */
-declare function parseFormattedValue(response: Record<string, unknown>, fieldName: string): string | null;
-/**
- * Build an OData $select and $expand query string.
- *
- * @param fields - Field names to select
- * @param expand - Navigation property to expand (optional)
- * @returns OData query string
- *
- * @example
- * ```typescript
- * Xrm.WebApi.retrieveRecord("account", id, selectExpand(
- *   [AccountFields.Name, AccountFields.WebsiteUrl],
- *   "primarycontactid($select=fullname,emailaddress1)"
- * ));
- * ```
- */
-declare function selectExpand(fields: string[], expand: string): string;
-
-/**
- * @xrmforge/typegen - Xrm API Constants
- *
- * Const enums for all common Xrm string/number constants.
- * Eliminates raw strings in D365 form scripts.
- *
- * @types/xrm defines these as string literal types for compile-time checking,
- * but does NOT provide runtime constants (XrmEnum is not available at runtime).
- * These const enums are erased at compile time (zero runtime overhead).
- *
- * @example
- * ```typescript
- * // Statt Raw-String:
- * if (tab.getDisplayState() === 'expanded') { ... }
- *
- * // Mit XrmForge-Konstante:
- * if (tab.getDisplayState() === XrmConstants.DisplayState.Expanded) { ... }
- * ```
- */
-/** Tab/Section display state */
-declare const enum DisplayState {
-    Expanded = "expanded",
-    Collapsed = "collapsed"
-}
-/** Form notification level (formContext.ui.setFormNotification) */
-declare const enum FormNotificationLevel {
-    Error = "ERROR",
-    Warning = "WARNING",
-    Info = "INFO"
-}
-/** Attribute required level (attribute.setRequiredLevel) */
-declare const enum RequiredLevel {
-    None = "none",
-    Required = "required",
-    Recommended = "recommended"
-}
-/** Attribute submit mode (attribute.setSubmitMode) */
-declare const enum SubmitMode {
-    Always = "always",
-    Never = "never",
-    Dirty = "dirty"
-}
-/** Save mode (eventArgs.getSaveMode()) */
-declare const enum SaveMode {
-    Save = 1,
-    SaveAndClose = 2,
-    Deactivate = 5,
-    Reactivate = 6,
-    Send = 7,
-    Disqualify = 15,
-    Qualify = 16,
-    Assign = 47,
-    SaveAsCompleted = 58,
-    SaveAndNew = 59,
-    AutoSave = 70
-}
-/** Client type (Xrm.Utility.getGlobalContext().client.getClient()) */
-declare const enum ClientType {
-    Web = "Web",
-    Outlook = "Outlook",
-    Mobile = "Mobile"
-}
-/** Client state (Xrm.Utility.getGlobalContext().client.getClientState()) */
-declare const enum ClientState {
-    Online = "Online",
-    Offline = "Offline"
-}
-/** Operation type for Xrm.WebApi.execute getMetadata().operationType */
-declare const enum OperationType {
-    /** Custom Action or OOB Action (POST) */
-    Action = 0,
-    /** Custom Function or OOB Function (GET) */
-    Function = 1,
-    /** CRUD operation (Create, Retrieve, Update, Delete) */
-    CRUD = 2
-}
-/** Structural property for getMetadata().parameterTypes[].structuralProperty */
-declare const enum StructuralProperty {
-    Unknown = 0,
-    PrimitiveType = 1,
-    ComplexType = 2,
-    EnumerationType = 3,
-    Collection = 4,
-    EntityType = 5
-}
-/** Binding type for Custom API definitions */
-declare const enum BindingType {
-    /** Nicht an eine Entity gebunden (global aufrufbar) */
-    Global = 0,
-    /** An einen einzelnen Entity-Datensatz gebunden */
-    Entity = 1,
-    /** An eine Entity-Collection gebunden */
-    EntityCollection = 2
-}
-
-export { BindingType, ClientState, ClientType, DisplayState, FormNotificationLevel, OperationType, RequiredLevel, SaveMode, StructuralProperty, SubmitMode, parseFormattedValue, parseLookup, parseLookups, select, selectExpand };

package/dist/helpers.js

@@ -1,120 +0,0 @@
-// src/generators/webapi-helpers.ts
-function select(...fields) {
-  if (fields.length === 0) return "";
-  return `?$select=${fields.join(",")}`;
-}
-function parseLookup(response, navigationProperty) {
-  const key = `_${navigationProperty}_value`;
-  const id = response[key];
-  if (!id) return null;
-  return {
-    id,
-    name: response[`${key}@OData.Community.Display.V1.FormattedValue`] ?? "",
-    entityType: response[`${key}@Microsoft.Dynamics.CRM.lookuplogicalname`] ?? ""
-  };
-}
-function parseLookups(response, navigationProperties) {
-  const result = {};
-  for (const prop of navigationProperties) {
-    result[prop] = parseLookup(response, prop);
-  }
-  return result;
-}
-function parseFormattedValue(response, fieldName) {
-  return response[`${fieldName}@OData.Community.Display.V1.FormattedValue`] ?? null;
-}
-function selectExpand(fields, expand) {
-  const parts = [];
-  if (fields.length > 0) parts.push(`$select=${fields.join(",")}`);
-  if (expand) parts.push(`$expand=${expand}`);
-  return parts.length > 0 ? `?${parts.join("&")}` : "";
-}
-
-// src/generators/xrm-constants.ts
-var DisplayState = /* @__PURE__ */ ((DisplayState2) => {
-  DisplayState2["Expanded"] = "expanded";
-  DisplayState2["Collapsed"] = "collapsed";
-  return DisplayState2;
-})(DisplayState || {});
-var FormNotificationLevel = /* @__PURE__ */ ((FormNotificationLevel2) => {
-  FormNotificationLevel2["Error"] = "ERROR";
-  FormNotificationLevel2["Warning"] = "WARNING";
-  FormNotificationLevel2["Info"] = "INFO";
-  return FormNotificationLevel2;
-})(FormNotificationLevel || {});
-var RequiredLevel = /* @__PURE__ */ ((RequiredLevel2) => {
-  RequiredLevel2["None"] = "none";
-  RequiredLevel2["Required"] = "required";
-  RequiredLevel2["Recommended"] = "recommended";
-  return RequiredLevel2;
-})(RequiredLevel || {});
-var SubmitMode = /* @__PURE__ */ ((SubmitMode2) => {
-  SubmitMode2["Always"] = "always";
-  SubmitMode2["Never"] = "never";
-  SubmitMode2["Dirty"] = "dirty";
-  return SubmitMode2;
-})(SubmitMode || {});
-var SaveMode = /* @__PURE__ */ ((SaveMode2) => {
-  SaveMode2[SaveMode2["Save"] = 1] = "Save";
-  SaveMode2[SaveMode2["SaveAndClose"] = 2] = "SaveAndClose";
-  SaveMode2[SaveMode2["Deactivate"] = 5] = "Deactivate";
-  SaveMode2[SaveMode2["Reactivate"] = 6] = "Reactivate";
-  SaveMode2[SaveMode2["Send"] = 7] = "Send";
-  SaveMode2[SaveMode2["Disqualify"] = 15] = "Disqualify";
-  SaveMode2[SaveMode2["Qualify"] = 16] = "Qualify";
-  SaveMode2[SaveMode2["Assign"] = 47] = "Assign";
-  SaveMode2[SaveMode2["SaveAsCompleted"] = 58] = "SaveAsCompleted";
-  SaveMode2[SaveMode2["SaveAndNew"] = 59] = "SaveAndNew";
-  SaveMode2[SaveMode2["AutoSave"] = 70] = "AutoSave";
-  return SaveMode2;
-})(SaveMode || {});
-var ClientType = /* @__PURE__ */ ((ClientType2) => {
-  ClientType2["Web"] = "Web";
-  ClientType2["Outlook"] = "Outlook";
-  ClientType2["Mobile"] = "Mobile";
-  return ClientType2;
-})(ClientType || {});
-var ClientState = /* @__PURE__ */ ((ClientState2) => {
-  ClientState2["Online"] = "Online";
-  ClientState2["Offline"] = "Offline";
-  return ClientState2;
-})(ClientState || {});
-var OperationType = /* @__PURE__ */ ((OperationType2) => {
-  OperationType2[OperationType2["Action"] = 0] = "Action";
-  OperationType2[OperationType2["Function"] = 1] = "Function";
-  OperationType2[OperationType2["CRUD"] = 2] = "CRUD";
-  return OperationType2;
-})(OperationType || {});
-var StructuralProperty = /* @__PURE__ */ ((StructuralProperty2) => {
-  StructuralProperty2[StructuralProperty2["Unknown"] = 0] = "Unknown";
-  StructuralProperty2[StructuralProperty2["PrimitiveType"] = 1] = "PrimitiveType";
-  StructuralProperty2[StructuralProperty2["ComplexType"] = 2] = "ComplexType";
-  StructuralProperty2[StructuralProperty2["EnumerationType"] = 3] = "EnumerationType";
-  StructuralProperty2[StructuralProperty2["Collection"] = 4] = "Collection";
-  StructuralProperty2[StructuralProperty2["EntityType"] = 5] = "EntityType";
-  return StructuralProperty2;
-})(StructuralProperty || {});
-var BindingType = /* @__PURE__ */ ((BindingType2) => {
-  BindingType2[BindingType2["Global"] = 0] = "Global";
-  BindingType2[BindingType2["Entity"] = 1] = "Entity";
-  BindingType2[BindingType2["EntityCollection"] = 2] = "EntityCollection";
-  return BindingType2;
-})(BindingType || {});
-export {
-  BindingType,
-  ClientState,
-  ClientType,
-  DisplayState,
-  FormNotificationLevel,
-  OperationType,
-  RequiredLevel,
-  SaveMode,
-  StructuralProperty,
-  SubmitMode,
-  parseFormattedValue,
-  parseLookup,
-  parseLookups,
-  select,
-  selectExpand
-};
-//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/generators/webapi-helpers.ts","../src/generators/xrm-constants.ts"],"sourcesContent":["/**\r\n * @xrmforge/typegen - Web API Helper Functions\r\n *\r\n * Lightweight utility functions for building OData query strings\r\n * with type-safe field names from generated Fields enums.\r\n *\r\n * Zero runtime overhead when used with const enums (values are inlined).\r\n *\r\n * @example\r\n * ```typescript\r\n * import { select } from '@xrmforge/typegen';\r\n *\r\n * Xrm.WebApi.retrieveRecord(ref.entityType, ref.id, select(\r\n *   AccountFields.Name,\r\n *   AccountFields.WebsiteUrl,\r\n *   AccountFields.Address1Line1,\r\n * ));\r\n * ```\r\n */\r\n\r\n/**\r\n * Build an OData $select query string from field names.\r\n *\r\n * @param fields - Field names (use generated Fields enum for type safety)\r\n * @returns OData query string (e.g. \"?$select=name,websiteurl,address1_line1\")\r\n */\r\nexport function select(...fields: string[]): string {\r\n  if (fields.length === 0) return '';\r\n  return `?$select=${fields.join(',')}`;\r\n}\r\n\r\n/**\r\n * Parse a lookup field from a Dataverse Web API response into a LookupValue.\r\n *\r\n * Dataverse returns lookups as `_fieldname_value` with OData annotations:\r\n * - `_fieldname_value` (GUID)\r\n * - `_fieldname_value@OData.Community.Display.V1.FormattedValue` (display name)\r\n * - `_fieldname_value@Microsoft.Dynamics.CRM.lookuplogicalname` (entity type)\r\n *\r\n * This function extracts all three into an `Xrm.LookupValue` object.\r\n *\r\n * @param response - The raw Web API response object\r\n * @param navigationProperty - Navigation property name (use NavigationProperties enum for type safety)\r\n * @returns Xrm.LookupValue or null if the lookup is empty\r\n *\r\n * @example\r\n * ```typescript\r\n * // Mit NavigationProperties-Enum (empfohlen, keine Raw-Strings):\r\n * parseLookup(result, AccountNav.Country);\r\n *\r\n * // Oder mit Navigation Property Name direkt:\r\n * parseLookup(result, 'markant_address1_countryid');\r\n * ```\r\n */\r\nexport function parseLookup(\r\n  response: Record<string, unknown>,\r\n  navigationProperty: string,\r\n): { id: string; name: string; entityType: string } | null {\r\n  const key = `_${navigationProperty}_value`;\r\n  const id = response[key] as string | undefined;\r\n  if (!id) return null;\r\n\r\n  return {\r\n    id,\r\n    name: (response[`${key}@OData.Community.Display.V1.FormattedValue`] as string) ?? '',\r\n    entityType: (response[`${key}@Microsoft.Dynamics.CRM.lookuplogicalname`] as string) ?? '',\r\n  };\r\n}\r\n\r\n/**\r\n * Parse multiple lookup fields from a Dataverse Web API response at once.\r\n *\r\n * @param response - The raw Web API response object\r\n * @param navigationProperties - Navigation property names to parse\r\n * @returns Map of navigation property name to LookupValue (null entries omitted)\r\n *\r\n * @example\r\n * ```typescript\r\n * const lookups = parseLookups(result, ['markant_address1_countryid', 'parentaccountid']);\r\n * formContext.getAttribute(Fields.Country).setValue(\r\n *   lookups.markant_address1_countryid ? [lookups.markant_address1_countryid] : null\r\n * );\r\n * ```\r\n */\r\nexport function parseLookups(\r\n  response: Record<string, unknown>,\r\n  navigationProperties: string[],\r\n): Record<string, { id: string; name: string; entityType: string } | null> {\r\n  const result: Record<string, { id: string; name: string; entityType: string } | null> = {};\r\n  for (const prop of navigationProperties) {\r\n    result[prop] = parseLookup(response, prop);\r\n  }\r\n  return result;\r\n}\r\n\r\n/**\r\n * Get the formatted (display) value of any field from a Web API response.\r\n *\r\n * Works for OptionSets, Lookups, DateTimes, Money, and other formatted fields.\r\n *\r\n * @param response - The raw Web API response object\r\n * @param fieldName - The field logical name (e.g. \"statecode\", \"createdon\")\r\n * @returns The formatted string value, or null if not available\r\n *\r\n * @example\r\n * ```typescript\r\n * const status = parseFormattedValue(result, 'statecode');\r\n * // \"Active\" (statt 0)\r\n * ```\r\n */\r\nexport function parseFormattedValue(\r\n  response: Record<string, unknown>,\r\n  fieldName: string,\r\n): string | null {\r\n  return (response[`${fieldName}@OData.Community.Display.V1.FormattedValue`] as string) ?? null;\r\n}\r\n\r\n/**\r\n * Build an OData $select and $expand query string.\r\n *\r\n * @param fields - Field names to select\r\n * @param expand - Navigation property to expand (optional)\r\n * @returns OData query string\r\n *\r\n * @example\r\n * ```typescript\r\n * Xrm.WebApi.retrieveRecord(\"account\", id, selectExpand(\r\n *   [AccountFields.Name, AccountFields.WebsiteUrl],\r\n *   \"primarycontactid($select=fullname,emailaddress1)\"\r\n * ));\r\n * ```\r\n */\r\nexport function selectExpand(fields: string[], expand: string): string {\r\n  const parts: string[] = [];\r\n  if (fields.length > 0) parts.push(`$select=${fields.join(',')}`);\r\n  if (expand) parts.push(`$expand=${expand}`);\r\n  return parts.length > 0 ? `?${parts.join('&')}` : '';\r\n}\r\n","/**\r\n * @xrmforge/typegen - Xrm API Constants\r\n *\r\n * Const enums for all common Xrm string/number constants.\r\n * Eliminates raw strings in D365 form scripts.\r\n *\r\n * @types/xrm defines these as string literal types for compile-time checking,\r\n * but does NOT provide runtime constants (XrmEnum is not available at runtime).\r\n * These const enums are erased at compile time (zero runtime overhead).\r\n *\r\n * @example\r\n * ```typescript\r\n * // Statt Raw-String:\r\n * if (tab.getDisplayState() === 'expanded') { ... }\r\n *\r\n * // Mit XrmForge-Konstante:\r\n * if (tab.getDisplayState() === XrmConstants.DisplayState.Expanded) { ... }\r\n * ```\r\n */\r\n\r\n/** Tab/Section display state */\r\nexport const enum DisplayState {\r\n  Expanded = 'expanded',\r\n  Collapsed = 'collapsed',\r\n}\r\n\r\n// FormType: verwende XrmEnum.FormType aus @types/xrm (dort bereits als const enum definiert)\r\n\r\n/** Form notification level (formContext.ui.setFormNotification) */\r\nexport const enum FormNotificationLevel {\r\n  Error = 'ERROR',\r\n  Warning = 'WARNING',\r\n  Info = 'INFO',\r\n}\r\n\r\n/** Attribute required level (attribute.setRequiredLevel) */\r\nexport const enum RequiredLevel {\r\n  None = 'none',\r\n  Required = 'required',\r\n  Recommended = 'recommended',\r\n}\r\n\r\n/** Attribute submit mode (attribute.setSubmitMode) */\r\nexport const enum SubmitMode {\r\n  Always = 'always',\r\n  Never = 'never',\r\n  Dirty = 'dirty',\r\n}\r\n\r\n/** Save mode (eventArgs.getSaveMode()) */\r\nexport const enum SaveMode {\r\n  Save = 1,\r\n  SaveAndClose = 2,\r\n  Deactivate = 5,\r\n  Reactivate = 6,\r\n  Send = 7,\r\n  Disqualify = 15,\r\n  Qualify = 16,\r\n  Assign = 47,\r\n  SaveAsCompleted = 58,\r\n  SaveAndNew = 59,\r\n  AutoSave = 70,\r\n}\r\n\r\n/** Client type (Xrm.Utility.getGlobalContext().client.getClient()) */\r\nexport const enum ClientType {\r\n  Web = 'Web',\r\n  Outlook = 'Outlook',\r\n  Mobile = 'Mobile',\r\n}\r\n\r\n/** Client state (Xrm.Utility.getGlobalContext().client.getClientState()) */\r\nexport const enum ClientState {\r\n  Online = 'Online',\r\n  Offline = 'Offline',\r\n}\r\n\r\n// ─── WebApi Execute Constants ───────────────────────────────────────────────\r\n\r\n/** Operation type for Xrm.WebApi.execute getMetadata().operationType */\r\nexport const enum OperationType {\r\n  /** Custom Action or OOB Action (POST) */\r\n  Action = 0,\r\n  /** Custom Function or OOB Function (GET) */\r\n  Function = 1,\r\n  /** CRUD operation (Create, Retrieve, Update, Delete) */\r\n  CRUD = 2,\r\n}\r\n\r\n/** Structural property for getMetadata().parameterTypes[].structuralProperty */\r\nexport const enum StructuralProperty {\r\n  Unknown = 0,\r\n  PrimitiveType = 1,\r\n  ComplexType = 2,\r\n  EnumerationType = 3,\r\n  Collection = 4,\r\n  EntityType = 5,\r\n}\r\n\r\n/** Binding type for Custom API definitions */\r\nexport const enum BindingType {\r\n  /** Nicht an eine Entity gebunden (global aufrufbar) */\r\n  Global = 0,\r\n  /** An einen einzelnen Entity-Datensatz gebunden */\r\n  Entity = 1,\r\n  /** An eine Entity-Collection gebunden */\r\n  EntityCollection = 2,\r\n}\r\n"],"mappings":"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","names":["DisplayState","FormNotificationLevel","RequiredLevel","SubmitMode","SaveMode","ClientType","ClientState","OperationType","StructuralProperty","BindingType"]}