dataverse-types-gen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edward Tombre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# dataverse-types-gen
+
+Generate TypeScript types and optionset enums from a Microsoft Dataverse / Dynamics 365 environment's `$metadata` endpoint.
+
+For each requested entity the CLI writes:
+
+- An `<entity>.ts` file with an `interface` for the entity, an `<Entity>Bind` interface for `@odata.bind` writes, and imports for related entities
+- A shared `optionsets.ts` file with `enum`s for every picklist/state/status/multiselect option set discovered across the requested entities
+- An `index.ts` barrel re-exporting all generated types
+
+## Installation
+
+```sh
+npm install --save-dev dataverse-types-gen
+# or
+pnpm add -D dataverse-types-gen
+```
+
+## Usage
+
+### 1. Create a config
+
+`dataverse-types.config.json`:
+
+```json
+{
+  "entities": ["account", "contact", "msdyn_workorder"],
+  "outputDir": "src/dataverse-gen"
+}
+```
+
+### 2. Set environment variables
+
+The generator authenticates with Microsoft Entra ID using the client-credentials flow. Provide these via your shell, a `.env` file, or your runner's secret store:
+
+| Variable                 | Description                                                              |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `SERVER_URL`             | Dataverse environment URL, e.g. `https://contoso.crm.dynamics.com`       |
+| `AUTHORITY_URL`          | OAuth authority, e.g. `https://login.microsoftonline.com/<tenant-id>`    |
+| `DYNAMICS_CLIENT_ID`     | Azure AD application (client) ID                                         |
+| `DYNAMICS_CLIENT_SECRET` | Azure AD application client secret                                       |
+
+The app registration must be granted access to the Dataverse environment as an application user with read permission on entity metadata.
+
+### 3. Run it
+
+```sh
+npx dataverse-types-gen
+# or with an explicit config path
+npx dataverse-types-gen --config ./config/dataverse.json
+```
+
+A common pattern is to add it as a script in your `package.json`:
+
+```json
+{
+  "scripts": {
+    "gen:types": "dataverse-types-gen"
+  }
+}
+```
+
+## What gets generated
+
+For `entities: ["account"]` you get:
+
+```
+src/dataverse-gen/
+  account.ts       # export interface Account, export interface AccountBind
+  optionsets.ts    # export enum AccountStatecode, ...
+  index.ts         # re-exports
+```
+
+## How it works
+
+1. Acquires a bearer token via MSAL using client credentials.
+2. Fetches the OData `$metadata` document and parses the EDM schema.
+3. For each requested entity, fetches `EntityDefinitions(...)/Attributes/Microsoft.Dynamics.CRM.<PicklistSubtype>` to enumerate option sets.
+4. Renders one `.ts` file per entity plus a shared `optionsets.ts`.
+
+Inherited properties are flattened from `@BaseType` chains. Navigation properties to entities in your requested set are typed; those outside the set fall back to `unknown` (use `$expand` carefully).
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { generate, loadConfig } from "./generator.js";
+const printUsage = () => {
+    console.log(`Usage: dataverse-types-gen [--config <path>]
+
+Generates TypeScript types and optionset enums from a Microsoft Dataverse
+environment's $metadata endpoint.
+
+Options:
+  --config <path>   Path to config JSON (default: ./dataverse-types.config.json)
+  --help, -h        Show this help
+
+Config JSON shape:
+  {
+    "entities": ["account", "contact", ...],
+    "outputDir": "src/dataverse-gen"
+  }
+
+Environment variables (loaded from .env if present):
+  SERVER_URL              Dataverse environment URL (e.g. https://org.crm.dynamics.com)
+  AUTHORITY_URL           OAuth authority (e.g. https://login.microsoftonline.com/<tenant-id>)
+  DYNAMICS_CLIENT_ID      Azure AD app client ID
+  DYNAMICS_CLIENT_SECRET  Azure AD app client secret
+`);
+};
+const parseArgs = (argv) => {
+    let configPath = "dataverse-types.config.json";
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--help" || a === "-h") {
+            printUsage();
+            process.exit(0);
+        }
+        else if (a === "--config") {
+            const next = argv[i + 1];
+            if (!next) {
+                console.error("Error: --config requires a path argument");
+                process.exit(2);
+            }
+            configPath = next;
+            i++;
+        }
+        else {
+            console.error(`Error: unknown argument '${a}'`);
+            printUsage();
+            process.exit(2);
+        }
+    }
+    return { configPath };
+};
+const main = async () => {
+    const { configPath } = parseArgs(process.argv.slice(2));
+    const config = loadConfig(configPath);
+    await generate({
+        config,
+        regenCommand: `npx dataverse-types-gen --config ${configPath}`
+    });
+};
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/generator.d.ts

@@ -0,0 +1,11 @@
+export interface GenConfig {
+    entities: string[];
+    outputDir: string;
+}
+export declare const loadConfig: (configPath: string) => GenConfig;
+export interface RunOptions {
+    config: GenConfig;
+    regenCommand?: string;
+    log?: (msg: string) => void;
+}
+export declare const generate: ({ config, regenCommand, log }: RunOptions) => Promise<void>;

package/dist/generator.js

@@ -0,0 +1,341 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as MSAL from "@azure/msal-node";
+import { XMLParser } from "fast-xml-parser";
+const arr = (v) => v === undefined ? [] : Array.isArray(v) ? v : [v];
+const requireEnv = (name) => {
+    const v = process.env[name];
+    if (!v)
+        throw new Error(`Missing required environment variable: ${name}`);
+    return v;
+};
+const acquireToken = async () => {
+    const cca = new MSAL.ConfidentialClientApplication({
+        auth: {
+            clientId: requireEnv("DYNAMICS_CLIENT_ID"),
+            clientSecret: requireEnv("DYNAMICS_CLIENT_SECRET"),
+            knownAuthorities: ["login.microsoftonline.com"]
+        }
+    });
+    const result = await cca.acquireTokenByClientCredential({
+        authority: requireEnv("AUTHORITY_URL"),
+        scopes: [`${requireEnv("SERVER_URL")}/.default`]
+    });
+    if (!result?.accessToken) {
+        throw new Error("Failed to acquire access token");
+    }
+    return result.accessToken;
+};
+const fetchMetadata = async (token) => {
+    const url = `${requireEnv("SERVER_URL")}/api/data/v9.2/$metadata`;
+    const res = await fetch(url, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/xml"
+        }
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch $metadata: ${res.status} ${res.statusText}`);
+    }
+    return res.text();
+};
+const PICKLIST_SUBTYPES = [
+    "PicklistAttributeMetadata",
+    "StatusAttributeMetadata",
+    "StateAttributeMetadata",
+    "MultiSelectPicklistAttributeMetadata"
+];
+const fetchPicklistsForEntity = async (token, entityLogicalName) => {
+    const base = `${requireEnv("SERVER_URL")}/api/data/v9.2`;
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+        "OData-Version": "4.0",
+        "OData-MaxVersion": "4.0"
+    };
+    const all = [];
+    for (const subtype of PICKLIST_SUBTYPES) {
+        const url = `${base}/EntityDefinitions(LogicalName='${entityLogicalName}')` +
+            `/Attributes/Microsoft.Dynamics.CRM.${subtype}` +
+            `?$select=LogicalName&$expand=OptionSet($select=Name,IsGlobal,Options)`;
+        const res = await fetch(url, { headers });
+        if (!res.ok) {
+            throw new Error(`Failed to fetch ${subtype} for ${entityLogicalName}: ${res.status} ${res.statusText}`);
+        }
+        const body = (await res.json());
+        all.push(...body.value.filter((a) => a.OptionSet));
+    }
+    return all;
+};
+const englishLabel = (label) => {
+    const en = label.LocalizedLabels?.find((l) => l.LanguageCode === 1033);
+    if (en)
+        return en.Label;
+    if (label.UserLocalizedLabel)
+        return label.UserLocalizedLabel.Label;
+    return null;
+};
+const sanitiseEnumMember = (raw, value) => {
+    let s = raw
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^A-Za-z0-9_]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (s.length === 0)
+        s = `Option_${value}`;
+    if (/^[0-9]/.test(s))
+        s = `_${s}`;
+    return s;
+};
+const enumTypeName = (optionSetName) => optionSetName
+    .split(/[_\s]+/)
+    .filter(Boolean)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join("");
+const HEADER = (cmd) => [
+    `// AUTO-GENERATED by dataverse-types-gen. Do not edit by hand.`,
+    `// Regenerate with: ${cmd}`,
+    ""
+];
+const renderOptionSets = (optionSets, regenCommand) => {
+    const lines = [...HEADER(regenCommand)];
+    for (const [, os] of [...optionSets.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const tname = enumTypeName(os.Name);
+        lines.push(`export enum ${tname} {`);
+        const seenMembers = new Set();
+        for (const opt of os.Options) {
+            const label = englishLabel(opt.Label);
+            const baseMember = label ? sanitiseEnumMember(label, opt.Value) : `Option_${opt.Value}`;
+            let member = baseMember;
+            let i = 2;
+            while (seenMembers.has(member)) {
+                member = `${baseMember}_${i++}`;
+            }
+            seenMembers.add(member);
+            lines.push(`    ${member} = ${opt.Value},`);
+        }
+        lines.push("}");
+        lines.push("");
+    }
+    return lines.join("\n");
+};
+const edmToTs = (edmType, nullable) => {
+    const collection = edmType.startsWith("Collection(") && edmType.endsWith(")");
+    const inner = collection ? edmType.slice(11, -1) : edmType;
+    let ts;
+    switch (inner) {
+        case "Edm.String":
+        case "Edm.Guid":
+        case "Edm.DateTimeOffset":
+        case "Edm.Date":
+        case "Edm.Binary":
+            ts = "string";
+            break;
+        case "Edm.Int32":
+        case "Edm.Int64":
+        case "Edm.Decimal":
+        case "Edm.Double":
+        case "Edm.Single":
+            ts = "number";
+            break;
+        case "Edm.Boolean":
+            ts = "boolean";
+            break;
+        default:
+            ts = "unknown";
+    }
+    if (collection)
+        ts = `${ts}[]`;
+    return nullable ? `${ts} | null` : ts;
+};
+const isPropName = (s) => /^[A-Za-z_][\w]*$/.test(s);
+const quoteKey = (s) => (isPropName(s) ? s : JSON.stringify(s));
+const navTargetEntityName = (fullType, prefixes) => {
+    const collection = fullType.startsWith("Collection(") && fullType.endsWith(")");
+    const inner = collection ? fullType.slice(11, -1) : fullType;
+    let logicalName = inner;
+    for (const ns of prefixes) {
+        const p = `${ns}.`;
+        if (inner.startsWith(p)) {
+            logicalName = inner.slice(p.length);
+            break;
+        }
+    }
+    return { logicalName, collection };
+};
+const tsTypeName = (logicalName) => logicalName.charAt(0).toUpperCase() + logicalName.slice(1);
+const renderEntity = (entity, nsPrefixes, requestedSet, attrEnums, regenCommand) => {
+    const name = entity["@_Name"];
+    const typeName = tsTypeName(name);
+    const props = arr(entity.Property);
+    const navs = arr(entity.NavigationProperty);
+    const imports = new Set();
+    const enumImports = new Set();
+    const lines = [...HEADER(regenCommand)];
+    const navTargets = navs.map((n) => navTargetEntityName(n["@_Type"], nsPrefixes));
+    for (const t of navTargets) {
+        if (requestedSet.has(t.logicalName) && t.logicalName !== name) {
+            imports.add(t.logicalName);
+        }
+    }
+    for (const p of props) {
+        const enumType = attrEnums.get(p["@_Name"]);
+        if (enumType && p["@_Type"] === "Edm.Int32")
+            enumImports.add(enumType);
+    }
+    const importLines = [...imports]
+        .sort()
+        .map((n) => `import type { ${tsTypeName(n)} } from "./${n}";`);
+    if (importLines.length > 0) {
+        lines.push(...importLines, "");
+    }
+    if (enumImports.size > 0) {
+        lines.push(`import type { ${[...enumImports].sort().join(", ")} } from "./optionsets";`, "");
+    }
+    lines.push(`export interface ${typeName} {`);
+    for (const p of props) {
+        const pname = p["@_Name"];
+        const nullable = p["@_Nullable"] !== "false";
+        const enumType = attrEnums.get(pname);
+        const useEnum = enumType && p["@_Type"] === "Edm.Int32";
+        const ts = useEnum
+            ? nullable
+                ? `${enumType} | null`
+                : enumType
+            : edmToTs(p["@_Type"], nullable);
+        lines.push(`    ${quoteKey(pname)}?: ${ts};`);
+    }
+    if (navs.length > 0) {
+        lines.push("");
+        lines.push("    // Navigation properties (use $expand to populate)");
+        for (const n of navs) {
+            const nname = n["@_Name"];
+            const target = navTargetEntityName(n["@_Type"], nsPrefixes);
+            const targetTs = requestedSet.has(target.logicalName)
+                ? tsTypeName(target.logicalName)
+                : "unknown";
+            const ts = target.collection ? `${targetTs}[]` : targetTs;
+            lines.push(`    ${quoteKey(nname)}?: ${ts};`);
+        }
+    }
+    lines.push("}");
+    lines.push("");
+    const singleValueLookups = navs.filter((n) => !navTargetEntityName(n["@_Type"], nsPrefixes).collection);
+    if (singleValueLookups.length > 0) {
+        lines.push(`export interface ${typeName}Bind {`);
+        for (const n of singleValueLookups) {
+            const target = navTargetEntityName(n["@_Type"], nsPrefixes);
+            const bindKey = `${n["@_Name"]}@odata.bind`;
+            lines.push(`    ${quoteKey(bindKey)}?: string; // /<entityset>(<id>) referencing ${target.logicalName}`);
+        }
+        lines.push("}");
+        lines.push("");
+    }
+    return { code: lines.join("\n"), imports, enumImports };
+};
+export const loadConfig = (configPath) => {
+    const resolved = path.resolve(configPath);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Config file not found: ${resolved}`);
+    }
+    const cfg = JSON.parse(fs.readFileSync(resolved, "utf8"));
+    if (!Array.isArray(cfg.entities) || cfg.entities.length === 0) {
+        throw new Error(`Config '${resolved}' must contain a non-empty 'entities' array`);
+    }
+    if (typeof cfg.outputDir !== "string" || !cfg.outputDir) {
+        throw new Error(`Config '${resolved}' must contain a non-empty 'outputDir' string`);
+    }
+    return { entities: cfg.entities, outputDir: cfg.outputDir };
+};
+export const generate = async ({ config, regenCommand = "npx dataverse-types-gen", log = console.log }) => {
+    log(`Fetching $metadata from ${requireEnv("SERVER_URL")}`);
+    const token = await acquireToken();
+    const xml = await fetchMetadata(token);
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        isArray: (name) => ["EntityType", "Property", "NavigationProperty", "EntitySet", "Schema"].includes(name)
+    });
+    const doc = parser.parse(xml);
+    const schemas = arr(doc?.["edmx:Edmx"]?.["edmx:DataServices"]?.Schema);
+    const crmSchema = schemas.find((s) => s["@_Namespace"] === "Microsoft.Dynamics.CRM");
+    if (!crmSchema) {
+        throw new Error("Schema 'Microsoft.Dynamics.CRM' not found in $metadata");
+    }
+    const allEntities = arr(crmSchema.EntityType);
+    const namespace = crmSchema["@_Namespace"];
+    const alias = crmSchema["@_Alias"];
+    const nsPrefixes = [namespace, ...(alias ? [alias] : [])];
+    const byName = new Map();
+    for (const e of allEntities)
+        byName.set(e["@_Name"], e);
+    const requested = new Set(config.entities);
+    const missing = config.entities.filter((n) => !byName.has(n));
+    if (missing.length > 0) {
+        throw new Error(`Entities not found in $metadata: ${missing.join(", ")}`);
+    }
+    const stripNs = (full) => {
+        for (const ns of nsPrefixes) {
+            const p = `${ns}.`;
+            if (full.startsWith(p))
+                return full.slice(p.length);
+        }
+        return full;
+    };
+    const flattenInherited = (e) => {
+        if (!e["@_BaseType"])
+            return e;
+        const base = byName.get(stripNs(e["@_BaseType"]));
+        if (!base)
+            return e;
+        const flatBase = flattenInherited(base);
+        return {
+            ...e,
+            Property: [...arr(flatBase.Property), ...arr(e.Property)],
+            NavigationProperty: [
+                ...arr(flatBase.NavigationProperty),
+                ...arr(e.NavigationProperty)
+            ]
+        };
+    };
+    log(`Fetching OptionSet metadata for ${config.entities.length} entities...`);
+    const picklistsByEntity = new Map();
+    await Promise.all(config.entities.map(async (logicalName) => {
+        const attrs = await fetchPicklistsForEntity(token, logicalName);
+        picklistsByEntity.set(logicalName, attrs);
+    }));
+    const optionSets = new Map();
+    const attrEnumsByEntity = new Map();
+    for (const [entityName, attrs] of picklistsByEntity) {
+        const m = new Map();
+        for (const a of attrs) {
+            const tname = enumTypeName(a.OptionSet.Name);
+            const existing = optionSets.get(a.OptionSet.Name);
+            if (!existing) {
+                optionSets.set(a.OptionSet.Name, a.OptionSet);
+            }
+            m.set(a.LogicalName, tname);
+        }
+        attrEnumsByEntity.set(entityName, m);
+    }
+    const outDir = path.resolve(config.outputDir);
+    fs.mkdirSync(outDir, { recursive: true });
+    const optionSetsCode = renderOptionSets(optionSets, regenCommand);
+    const optionSetsFile = path.join(outDir, "optionsets.ts");
+    fs.writeFileSync(optionSetsFile, optionSetsCode);
+    log(`Wrote ${path.relative(process.cwd(), optionSetsFile)}`);
+    const indexLines = [...HEADER(regenCommand)];
+    for (const logicalName of config.entities) {
+        const entity = flattenInherited(byName.get(logicalName));
+        const attrEnums = attrEnumsByEntity.get(logicalName) ?? new Map();
+        const { code } = renderEntity(entity, nsPrefixes, requested, attrEnums, regenCommand);
+        const file = path.join(outDir, `${logicalName}.ts`);
+        fs.writeFileSync(file, code);
+        log(`Wrote ${path.relative(process.cwd(), file)}`);
+        indexLines.push(`export type { ${tsTypeName(logicalName)} } from "./${logicalName}";`);
+    }
+    indexLines.push(`export * from "./optionsets";`);
+    const indexFile = path.join(outDir, "index.ts");
+    fs.writeFileSync(indexFile, indexLines.join("\n") + "\n");
+    log(`Wrote ${path.relative(process.cwd(), indexFile)}`);
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { generate, loadConfig } from "./generator.js";
+export type { GenConfig, RunOptions } from "./generator.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { generate, loadConfig } from "./generator.js";

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "dataverse-types-gen",
+  "version": "0.1.0",
+  "description": "Generate TypeScript types and optionset enums from a Microsoft Dataverse / Dynamics 365 environment's $metadata.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dr-Wade/dynamics-tools.git",
+    "directory": "packages/dataverse-types-gen"
+  },
+  "homepage": "https://github.com/Dr-Wade/dynamics-tools/tree/main/packages/dataverse-types-gen#readme",
+  "bugs": "https://github.com/Dr-Wade/dynamics-tools/issues",
+  "author": "Edward Tombre",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "dataverse-types-gen": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "dataverse",
+    "dynamics",
+    "dynamics-365",
+    "d365",
+    "types",
+    "typescript",
+    "codegen",
+    "metadata"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^3.6.2",
+    "dotenv": "^17.2.1",
+    "fast-xml-parser": "^5.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.10",
+    "typescript": "^5.8.3"
+  }
+}