@khester/dataverse-codegen 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+import { AttributeMetadata, EntityMetadata, IDataverseClient } from '@dynamics-ui-kit/api-client';
+import { AttributeMetadataInput, EntityMetadataInput } from '@dynamics-ui-kit/entity-gen';
+
+/**
+ * Adapter: raw Dataverse metadata (from @dynamics-ui-kit/api-client) →
+ * the `EntityMetadataInput` shape consumed by @dynamics-ui-kit/entity-gen.
+ *
+ * The two shapes are intentionally field-compatible (both PascalCase
+ * Dataverse-style), so this is largely a structural passthrough. It exists
+ * as an explicit seam so the codegen tools never depend on the api-client's
+ * concrete types and so we can validate/normalize in one place.
+ */
+
+declare function toAttributeMetadataInput(attr: AttributeMetadata): AttributeMetadataInput;
+declare function toEntityMetadataInput(entity: EntityMetadata, attributes: AttributeMetadata[]): EntityMetadataInput;
+
+/**
+ * Minimal Dataverse metadata HTTP helper for the codegen tools.
+ *
+ * Used for typed-cast attribute queries the api-client doesn't expose
+ * (scalar detail like MaxLength/Precision). Honors 429/503 throttling with
+ * `Retry-After` backoff, and follows `@odata.nextLink` (metadataGetAll) so
+ * wide results aren't truncated. Uses the global `fetch` (Node 18+).
+ */
+interface MetadataHttp {
+    /** Org base URL, e.g. https://org.crm.dynamics.com */
+    baseUrl: string;
+    token: string;
+    /** Web API version. Default 9.2. */
+    apiVersion?: string;
+}
+/** GET a single metadata resource (relative path), with retry/backoff. */
+declare function metadataGet<T = unknown>(http: MetadataHttp, relativePath: string, maxRetries?: number): Promise<T>;
+/**
+ * GET a metadata collection (relative path), following `@odata.nextLink` and
+ * concatenating every page's `value`. Use for queries that can exceed the
+ * server page cap (e.g. typed-cast attribute lists on very wide entities).
+ */
+declare function metadataGetAll<T = unknown>(http: MetadataHttp, relativePath: string, maxRetries?: number): Promise<T[]>;
+
+/**
+ * fetchEntityMetadata — compose a complete `EntityMetadataInput` for one
+ * entity from a live org, fixing the gap entity-gen's own CLI has (it calls
+ * a non-existent `client.getEntityMetadata`).
+ *
+ * = getEntityDefinitions(LogicalName eq '<e>')[0] + getAttributeMetadata('<e>')
+ *   → toEntityMetadataInput()
+ *   → (optional) typed-cast scalar augmentation (MaxLength/Precision/...)
+ */
+
+interface FetchEntityMetadataOptions {
+    /**
+     * Optional extra OData filter ANDed onto the attribute query. The api-client
+     * always restricts to readable attributes (`IsValidForRead eq true`), so
+     * generated constants/models cover the readable attribute surface.
+     */
+    attributeFilter?: string;
+    /**
+     * When provided, fetch type-specific scalar detail (MaxLength, Precision,
+     * Min/MaxValue, Format, DateTimeBehavior) via typed-cast queries and merge
+     * it in. Best-effort — failures are logged and skipped.
+     */
+    augment?: MetadataHttp;
+}
+declare function fetchEntityMetadata(client: IDataverseClient, logicalName: string, options?: FetchEntityMetadataOptions): Promise<EntityMetadataInput>;
+
+/**
+ * Typed-cast attribute augmentation.
+ *
+ * The api-client's `getAttributeMetadata` returns the base attribute shape;
+ * scalar detail (MaxLength, Precision, Min/MaxValue, Format, DateTimeBehavior)
+ * lives on type-specific subtypes and is only returned via a typed cast on the
+ * EntityDefinitions Attributes navigation, e.g.:
+ *
+ *   EntityDefinitions(LogicalName='x')/Attributes/Microsoft.Dynamics.CRM.StringAttributeMetadata
+ *     ?$select=LogicalName,MaxLength,Format
+ *
+ * This fills those fields in so generated constants carry full JSDoc detail.
+ * Best-effort: a failed cast query is skipped (codegen still succeeds, just
+ * with thinner comments for that type).
+ */
+
+interface ScalarDetail {
+    LogicalName: string;
+    MaxLength?: number;
+    MinValue?: number;
+    MaxValue?: number;
+    Precision?: number;
+    Format?: string;
+    DateTimeBehavior?: {
+        Value: string;
+    };
+}
+type MetadataGetter = (http: MetadataHttp, path: string) => Promise<{
+    value: ScalarDetail[];
+}>;
+/**
+ * Merge fetched scalar detail into the attribute list (in place). Only fills
+ * fields that are currently unset, so an explicit value from the base fetch
+ * always wins. Pure — exported for testing.
+ */
+declare function mergeScalarDetail(attrs: AttributeMetadataInput[], details: ScalarDetail[]): void;
+declare function augmentScalarDetail(http: MetadataHttp, logicalName: string, attrs: AttributeMetadataInput[], get?: MetadataGetter): Promise<void>;
+
+/**
+ * Non-destructive file writing — the foundational safety guarantee.
+ *
+ * Client `src/models/*` etc. are frequently hand-customized. Commands MUST
+ * NOT clobber existing files silently. `safeWrite`:
+ *   - refuses to overwrite an existing file unless `force`
+ *   - supports `dryRun` (report only) and `diff` (print a unified-ish diff)
+ *   - creates parent dirs as needed
+ */
+type WriteResult = 'created' | 'overwritten' | 'skipped-exists' | 'unchanged' | 'dry-run';
+interface SafeWriteOptions {
+    force?: boolean;
+    dryRun?: boolean;
+    diff?: boolean;
+}
+declare function safeWrite(path: string, content: string, opts?: SafeWriteOptions): WriteResult;
+
+/**
+ * Connection resolution — build an IDataverseClient from CLI flags / env,
+ * tolerant of the env-var prefixes client projects actually use
+ * (VITE_/REACT_APP_/bare DYNAMICS_), with Azure CLI as the token fallback.
+ *
+ * Token precedence: --token > env (.env / process.env) > Azure CLI (az).
+ * Use --token (or env) for cross-tenant client orgs where you don't have
+ * `az login` to the client's tenant.
+ */
+
+interface ConnectionOptions {
+    url?: string;
+    token?: string;
+    envFile?: string;
+}
+interface ResolvedConnection {
+    client: IDataverseClient;
+    url: string;
+    /** The resolved bearer token — used for typed-cast metadata HTTP the client doesn't expose. */
+    token: string;
+    tokenSource: 'flag' | 'env' | 'azure-cli';
+}
+declare function resolveConnection(opts: ConnectionOptions): ResolvedConnection;
+
+/**
+ * Parent-lookup (many-to-one) <link-entity> derivation for model retrieve
+ * scaffolds. Shared by the `models` and `design` commands.
+ */
+
+interface RetrieveLink {
+    entity: string;
+    from: string;
+    to: string;
+    alias: string;
+}
+/**
+ * Derive parent-lookup joins from relationship metadata to pre-fill a model's
+ * `retrieveWithRelated()` scaffold. Parent lookups are relationships where THIS
+ * entity is the referencing (many) side — Dataverse reports both navigations as
+ * `OneToManyRelationship`, so we identify by `ReferencingEntity`, not type.
+ *
+ * Best-effort: returns `[]` (with a console warning) when relationships can't
+ * be fetched, so callers still emit a TODO scaffold.
+ */
+declare function deriveParentLookupLinks(client: IDataverseClient, entity: EntityMetadataInput): Promise<RetrieveLink[]>;
+
+/** Discriminator the form designer writes into every exported design file. */
+declare const FORM_DESIGN_KIND = "dynamics-ui-kit.form-design";
+interface DesignControl {
+    type?: string;
+    name?: string;
+    properties?: {
+        entityName?: unknown;
+    } & Record<string, unknown>;
+    dataBinding?: {
+        attributeLogicalName?: unknown;
+        lookupTargets?: unknown;
+    };
+}
+interface DesignCell {
+    control?: DesignControl | null;
+}
+interface DesignRow {
+    cells?: DesignCell[];
+}
+interface DesignSection {
+    rows?: DesignRow[];
+}
+interface DesignTab {
+    sections?: DesignSection[];
+}
+interface DesignForm {
+    name?: string;
+    type?: string;
+    settings?: {
+        dataSources?: Array<{
+            entityName?: unknown;
+        }>;
+    };
+    sections?: DesignSection[];
+    tabs?: DesignTab[];
+}
+interface FormDesignFile {
+    kind?: string;
+    schemaVersion?: number;
+    name?: string;
+    forms?: DesignForm[];
+}
+/** A Dataverse entity discovered in the design, with where it came from. */
+interface EntityRef {
+    logicalName: string;
+    /** Human-readable provenance, for reporting (e.g. `form "Contact" (target)`). */
+    sources: string[];
+}
+interface CollectResult {
+    entities: EntityRef[];
+    /** Entity-name candidates rejected by the logical-name allowlist. */
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+}
+/**
+ * Parse + validate an exported design file. Throws on invalid JSON, an
+ * unexpected `kind`, or a missing `forms` array.
+ */
+declare function parseDesignFile(raw: string): FormDesignFile;
+/**
+ * Walk every form and collect the Dataverse entities it references:
+ *   - each form's target entity (`settings.dataSources[0].entityName`),
+ *   - subgrid controls' `properties.entityName`,
+ *   - lookup controls' `dataBinding.lookupTargets`.
+ *
+ * Names are normalized to lowercase and validated against the Dataverse
+ * logical-name rule; invalid candidates are reported in `skipped`, never
+ * generated (they'd otherwise inject into metadata OData queries).
+ */
+declare function collectEntities(design: FormDesignFile): CollectResult;
+
+export { type CollectResult, type ConnectionOptions, type EntityRef, FORM_DESIGN_KIND, type FetchEntityMetadataOptions, type FormDesignFile, type MetadataGetter, type MetadataHttp, type ResolvedConnection, type RetrieveLink, type SafeWriteOptions, type WriteResult, augmentScalarDetail, collectEntities, deriveParentLookupLinks, fetchEntityMetadata, mergeScalarDetail, metadataGet, metadataGetAll, parseDesignFile, resolveConnection, safeWrite, toAttributeMetadataInput, toEntityMetadataInput };