npm - @khester/create-dynamics-app - Versions diffs - 2.1.0 → 2.2.0 - Mend

@khester/create-dynamics-app 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (121) hide show

package/templates/react-custom-page/env.example ADDED Viewed

@@ -0,0 +1,16 @@
+# Token-proxy dev mode — run `npm run dev` against a real Dataverse org.
+#
+# Preferred: run `npm run auth:token -- --url https://<org>.crm.dynamics.com`,
+# which acquires a token via the Azure CLI and writes both values to .env.
+# Or copy this file to .env and fill them in manually.
+#
+# When DYNAMICS_URL is set, the Vite dev server proxies /api/data/* to the org
+# and injects DYNAMICS_TOKEN as the bearer (server-side — never in the bundle).
+DYNAMICS_URL=https://your-org.crm.dynamics.com
+DYNAMICS_TOKEN=
+# `npm run deploy` — the HTML web-resource unique name. The prefix (before `_`)
+# MUST be a publisher prefix that exists in your org (e.g. cr1a2_ / new_).
+WEBRESOURCE_NAME=new_/your-app/index.html
+# Optional: add the web resource to this unmanaged solution (unique name).
+WEBRESOURCE_SOLUTION=

package/templates/react-custom-page/gitignore CHANGED Viewed

@@ -3,3 +3,4 @@ dist/
 *.log
 .env
 .env.local
+.env.*.local

package/templates/react-custom-page/index.html ADDED Viewed

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Dynamics Custom Page</title>
+    <style>
+      /* App canvas behind the form — matches the Dynamics model-driven background. */
+      body { margin: 0; min-height: 100vh; background: #fafafa; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

package/templates/react-custom-page/package.json CHANGED Viewed

@@ -1,65 +1,37 @@
 {
   "name": "react-custom-page-app",
-  "version": "1.0.0",
-  "description": "Dynamics 365 React Custom Page app built with Dynamics UI Kit",
-  "main": "dist/index.js",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Minimal Dataverse React custom page (Vite + @khester/reusable-components)",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
-    "build": "webpack --mode=production",
-    "build:dev": "node scripts/custom-build.js --dev",
-    "build:prod": "node scripts/custom-build.js",
-    "build:d365": "node scripts/custom-build.js",
-    "dev": "webpack serve --mode=development",
-    "start": "webpack serve --mode=development",
-    "serve": "serve -s dist -l 62874",
+    "dev": "vite",
+    "dev:token": "npm run auth:token && npm run dev",
+    "build": "tsc && vite build",
+    "build:d365": "tsc && vite build --mode d365",
+    "deploy": "npm run auth:token && npm run build:d365 && node tools/deploy/deploy-webresource.cjs",
+    "preview": "vite preview",
     "typecheck": "tsc --noEmit",
-    "clean": "rimraf dist",
-    "lint": "eslint src --ext .ts,.tsx",
-    "lint:fix": "eslint src --ext .ts,.tsx --fix",
-    "quality": "npm run lint && npm run typecheck",
-    "quality:fix": "npm run lint:fix && npm run typecheck",
-    "validate": "npm run quality && npm run build:prod",
-    "test:build": "npm run clean && npm run build:dev && npm run build:prod",
-    "test:serve": "npm run build:prod && npm run serve",
-    "precommit": "npm run quality",
-    "prepublishOnly": "npm run validate",
-    "metadata:pull": "node tools/metadata-sync/index.js pull",
-    "metadata:generate": "node tools/metadata-sync/index.js generate",
-    "metadata:validate": "node tools/metadata-sync/index.js validate",
-    "metadata:sync": "node tools/metadata-sync/index.js sync"
+    "test": "vitest run",
+    "clean": "rimraf dist"
   },
   "dependencies": {
-    "@khester/dynamics-ui-api-client": "^1.0.0",
-    "@khester/dynamics-ui-components": "^1.0.0",
+    "@fluentui/react": "^8.110.10",
+    "@khester/reusable-components": "0.1.3",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@dataverse-kit/dataverse-codegen": "^0.1.0",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
-    "commander": "^11.1.0",
-    "css-loader": "^6.8.1",
-    "eslint": "^8.57.0",
-    "html-webpack-plugin": "^5.5.3",
+    "@vitejs/plugin-react": "^4.2.1",
     "rimraf": "^5.0.5",
-    "serve": "^14.2.1",
-    "style-loader": "^3.3.3",
-    "ts-loader": "^9.5.1",
     "typescript": "^5.3.3",
-    "webpack": "^5.89.0",
-    "webpack-cli": "^5.1.4",
-    "webpack-dev-server": "^4.15.1"
-  },
-  "browserslist": {
-    "production": [
-      ">0.2%",
-      "not dead",
-      "not op_mini all"
-    ],
-    "development": [
-      "last 1 chrome version",
-      "last 1 firefox version",
-      "last 1 safari version"
-    ]
+    "vite": "^5.4.21",
+    "vite-plugin-singlefile": "^2.0.3",
+    "vitest": "^1.6.0"
   }
 }

package/templates/react-custom-page/src/App.tsx ADDED Viewed

@@ -0,0 +1,26 @@
+import React from "react";
+import { ServiceFactory } from "./core/services/ServiceFactory";
+import { resolveRecordId } from "./core/recordContext";
+import { ExamplePage } from "./example/ExamplePage";
+import { DevPanel } from "./dev-tools/DevPanel";
+// Domain-free shell. The Xrm context exists only when this bundle is hosted
+// inside a model-driven app (the custom page runs in an iframe, so Xrm lives on
+// window.parent). ServiceFactory uses it for production mode; on localhost it is
+// undefined and the factory returns the mock or token-proxy service instead.
+const Xrm: any = (window as any).parent?.Xrm ?? (window as any).Xrm;
+export const App: React.FC = () => {
+  const api = React.useMemo(() => ServiceFactory.createApiService(Xrm), []);
+  // Which record to load — from ?id= / ?data= / the hosting form's record.
+  const recordId = React.useMemo(() => resolveRecordId(Xrm), []);
+  return (
+    <>
+      <ExamplePage api={api} recordId={recordId} />
+      {/* Localhost-only floating dev tools (renders nothing once deployed). */}
+      <DevPanel />
+    </>
+  );
+};
+export default App;

package/templates/react-custom-page/src/core/recordContext.test.ts ADDED Viewed

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { idFromDataParam } from "./recordContext";
+const GUID = "8025328c-a265-f111-a826-000d3a37b308";
+describe("idFromDataParam", () => {
+  it("reads a bare guid", () => {
+    expect(idFromDataParam(GUID)).toBe(GUID);
+  });
+  it("reads an `id=<guid>` query string", () => {
+    expect(idFromDataParam(`id=${GUID}`)).toBe(GUID);
+  });
+  it("reads JSON { id }", () => {
+    expect(idFromDataParam(JSON.stringify({ id: GUID }))).toBe(GUID);
+  });
+  it("reads JSON { selectedItems: [id] } (import_weights/navigateTo shape)", () => {
+    expect(idFromDataParam(JSON.stringify({ selectedItems: [GUID] }))).toBe(GUID);
+  });
+  it("reads a bare JSON string", () => {
+    expect(idFromDataParam(JSON.stringify(GUID))).toBe(GUID);
+  });
+  it("returns undefined for unrecognized data", () => {
+    expect(idFromDataParam("foo=bar")).toBeUndefined();
+  });
+});

package/templates/react-custom-page/src/core/recordContext.ts ADDED Viewed

@@ -0,0 +1,51 @@
+// Resolves which record this page should load, from however it was opened:
+//   1. ?id=<guid>                      — a direct link / the dev-tools panel
+//   2. ?data=<payload>                 — the Xrm.Navigation.navigateTo `data` arg
+//                                        (JSON {id}/{selectedItems:[id]}, "id=<guid>", or a bare guid)
+//   3. Xrm.Page.data.entity.getId()    — the form the web resource is hosted on
+// Returns undefined when none apply (mock mode just serves its seeded record).
+const stripBraces = (s: string) => s.replace(/[{}]/g, "").trim();
+/** Pull a record id out of a navigateTo `data` parameter value. Pure/testable. */
+export function idFromDataParam(data: string): string | undefined {
+  try {
+    const parsed = JSON.parse(data);
+    if (typeof parsed === "string") return parsed;
+    if (parsed && typeof parsed.id === "string") return parsed.id;
+    if (Array.isArray(parsed?.selectedItems) && parsed.selectedItems.length) {
+      return String(parsed.selectedItems[0]);
+    }
+  } catch {
+    // Not JSON — fall through to query-string / bare-guid handling.
+  }
+  const inner = new URLSearchParams(data).get("id");
+  if (inner) return inner;
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(stripBraces(data))) {
+    return stripBraces(data);
+  }
+  return undefined;
+}
+/** Resolve the record id from the URL or the hosting form context. */
+export function resolveRecordId(Xrm?: any): string | undefined {
+  const params = new URLSearchParams(window.location.search);
+  const direct = params.get("id");
+  if (direct) return stripBraces(direct);
+  const data = params.get("data");
+  if (data) {
+    const fromData = idFromDataParam(data);
+    if (fromData) return stripBraces(fromData);
+  }
+  try {
+    const id = Xrm?.Page?.data?.entity?.getId?.();
+    if (id) return stripBraces(id);
+  } catch {
+    // No form context (e.g. opened standalone) — leave undefined.
+  }
+  return undefined;
+}

package/templates/react-custom-page/src/core/services/FetchApiService.ts ADDED Viewed

@@ -0,0 +1,117 @@
+import { IApiService } from "./IApiService";
+import { logCrud } from "./crudLogging";
+import { logger } from "@khester/reusable-components";
+/**
+ * Dev API service for token-proxy mode (`npm run dev` with DYNAMICS_URL set).
+ * Requests go to the SAME-ORIGIN path /api/data/v9.2/... and the Vite dev proxy
+ * (vite.config.ts) injects the `Authorization: Bearer` header server-side — the
+ * token is never read by, or bundled into, the client.
+ */
+export class FetchApiService implements IApiService {
+  constructor(private baseUrl = "") {}
+  private headers(): HeadersInit {
+    return {
+      "Content-Type": "application/json; charset=utf-8",
+      Accept: "application/json",
+      "OData-Version": "4.0",
+      "OData-MaxVersion": "4.0",
+      Prefer: 'odata.include-annotations="*"',
+    };
+  }
+  retrieveMultipleRecords(
+    entity: string,
+    fetchXml: string,
+  ): Promise<{ entities: any[] }> {
+    return logCrud(
+      { op: "READ", entity, resultCount: (r) => r?.entities?.length },
+      async () => {
+        const url = `${this.baseUrl}/api/data/v9.2/${entity}?fetchXml=${encodeURIComponent(fetchXml)}`;
+        const response = await fetch(url, { method: "GET", headers: this.headers() });
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          throw new Error(`API error ${response.status}: ${response.statusText}${body ? ` — ${body}` : ""}`);
+        }
+        const data = await response.json();
+        return { entities: data.value ?? [] };
+      },
+    );
+  }
+  createRecord(entity: string, record: any): Promise<any> {
+    return logCrud({ op: "CREATE", entity, resultId: (r) => r?.id }, async () => {
+      const url = `${this.baseUrl}/api/data/v9.2/${entity}`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(record),
+      });
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Create failed ${response.status}: ${body}`);
+      }
+      const entityId = response.headers.get("OData-EntityId");
+      const match = entityId ? /\(([^)]+)\)/.exec(entityId) : null;
+      return match ? { id: match[1] } : response.json().catch(() => ({}));
+    });
+  }
+  updateRecord(entity: string, id: string, record: any): Promise<any> {
+    return logCrud({ op: "UPDATE", entity, id }, async () => {
+      const cleanId = id.replace(/[{}]/g, "");
+      const url = `${this.baseUrl}/api/data/v9.2/${entity}(${cleanId})`;
+      const response = await fetch(url, {
+        method: "PATCH",
+        headers: this.headers(),
+        body: JSON.stringify(record),
+      });
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Update failed ${response.status}: ${body}`);
+      }
+      return { success: true };
+    });
+  }
+  deleteRecord(entity: string, id: string): Promise<void> {
+    return logCrud({ op: "DELETE", entity, id }, async () => {
+      const cleanId = id.replace(/[{}]/g, "");
+      const url = `${this.baseUrl}/api/data/v9.2/${entity}(${cleanId})`;
+      const response = await fetch(url, { method: "DELETE", headers: this.headers() });
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Delete failed ${response.status}: ${body}`);
+      }
+    });
+  }
+  executeRequest(requestName: string, requestData: any): Promise<any> {
+    return logCrud({ op: "EXECUTE", entity: requestName }, async () => {
+      const url = `${this.baseUrl}/api/data/v9.2/${requestName}`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(requestData),
+      });
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Execute failed ${response.status}: ${body}`);
+      }
+      return response.json().catch(() => ({}));
+    });
+  }
+  async uploadFile(file: File): Promise<string> {
+    logger.warn("uploadFile not implemented", {
+      source: "FetchApiService",
+      data: { file: file.name },
+    });
+    return "";
+  }
+  async associateRecord(): Promise<void> {
+    logger.warn("associateRecord not implemented", { source: "FetchApiService" });
+  }
+}

package/templates/react-custom-page/src/core/services/IApiService.ts ADDED Viewed

@@ -0,0 +1,37 @@
+// The single data-access contract for the page. Three implementations satisfy
+// it — MockApiService (offline), FetchApiService (token-proxy dev), and
+// XrmApiService (production) — and ServiceFactory picks one per environment.
+//
+// Entities are addressed by their Web API ENTITY SET name (plural, e.g.
+// "accounts"), used consistently for reads and writes across all three services.
+export interface IApiService {
+  /** Update a record. `record` contains only the changed attributes. */
+  updateRecord(entity: string, id: string, record: any): Promise<any>;
+  /** Create a record; resolves to `{ id }`. */
+  createRecord(entity: string, record: any): Promise<any>;
+  /** Delete a record. */
+  deleteRecord(entity: string, id: string): Promise<void>;
+  /** Retrieve records via a FetchXML query. */
+  retrieveMultipleRecords(
+    entity: string,
+    fetchXml: string,
+  ): Promise<{ entities: any[] }>;
+  /** Execute a custom API / unbound function or action. */
+  executeRequest(requestName: string, requestData: any): Promise<any>;
+  /** Upload a file and return its URL. */
+  uploadFile(file: File): Promise<string>;
+  /** Associate two records via a relationship. */
+  associateRecord(
+    entityName: string,
+    entityId: string,
+    relationshipName: string,
+    relatedEntityName: string,
+    relatedEntityId: string,
+  ): Promise<void>;
+}

package/templates/react-custom-page/src/core/services/MockApiService.ts ADDED Viewed

@@ -0,0 +1,73 @@
+import { IApiService } from "./IApiService";
+import { logCrud } from "./crudLogging";
+// One seeded in-memory account so `npm run dev` renders and saves with no org
+// or token. Replace this seed (and add more entity sets) as your page grows.
+const SEED_ACCOUNT = {
+  accountid: "00000000-0000-0000-0000-000000000001",
+  name: "Contoso Ltd",
+  accountnumber: "ACC-1001",
+  telephone1: "+1 (425) 555-0100",
+  emailaddress1: "info@contoso.example",
+  websiteurl: "https://contoso.example",
+};
+/**
+ * Default mock used on localhost when no token URL is configured. Operations are
+ * routed through `logCrud`, so a starter page shows the same `[CRUD] …` console
+ * lines (and populates `window.dumpAppLogs()`) as a real service.
+ */
+export class MockApiService implements IApiService {
+  private accounts: Record<string, any> = {
+    [SEED_ACCOUNT.accountid]: { ...SEED_ACCOUNT },
+  };
+  private nextId = 2;
+  retrieveMultipleRecords(entity: string): Promise<{ entities: any[] }> {
+    return logCrud(
+      { op: "READ", entity, resultCount: (r) => r?.entities?.length },
+      async () => ({
+        entities: entity === "accounts" ? Object.values(this.accounts) : [],
+      }),
+    );
+  }
+  updateRecord(entity: string, id: string, record: any): Promise<any> {
+    return logCrud({ op: "UPDATE", entity, id }, async () => {
+      const key = id.replace(/[{}]/g, "");
+      if (this.accounts[key]) {
+        this.accounts[key] = { ...this.accounts[key], ...record };
+      }
+      return { success: true };
+    });
+  }
+  createRecord(entity: string, record: any): Promise<any> {
+    return logCrud({ op: "CREATE", entity, resultId: (r) => r?.id }, async () => {
+      const id = `00000000-0000-0000-0000-${String(this.nextId++).padStart(12, "0")}`;
+      if (entity === "accounts") this.accounts[id] = { accountid: id, ...record };
+      return { id };
+    });
+  }
+  deleteRecord(entity: string, id: string): Promise<void> {
+    return logCrud({ op: "DELETE", entity, id }, async () => {
+      delete this.accounts[id.replace(/[{}]/g, "")];
+    });
+  }
+  executeRequest(requestName: string): Promise<any> {
+    return logCrud({ op: "EXECUTE", entity: requestName }, async () => ({}));
+  }
+  async uploadFile(): Promise<string> {
+    return "";
+  }
+  associateRecord(entityName: string, entityId: string): Promise<void> {
+    return logCrud(
+      { op: "ASSOCIATE", entity: entityName, id: entityId },
+      async () => undefined,
+    );
+  }
+}

package/templates/react-custom-page/src/core/services/ServiceFactory.ts ADDED Viewed

@@ -0,0 +1,58 @@
+import { IApiService } from "./IApiService";
+import { MockApiService } from "./MockApiService";
+import { XrmApiService } from "./XrmApiService";
+import { FetchApiService } from "./FetchApiService";
+import { logger } from "@khester/reusable-components";
+/**
+ * Single decision point for which IApiService the page talks to.
+ *
+ * Priority:
+ *   1. localhost + VITE_USE_PROXY → FetchApiService (real Dataverse via the Vite proxy)
+ *   2. localhost (no proxy)       → injected mock, or MockApiService by default
+ *   3. deployed + Xrm context     → XrmApiService
+ */
+export class ServiceFactory {
+  public static isMockEnvironment: boolean =
+    window.location.hostname === "localhost" ||
+    window.location.hostname === "127.0.0.1";
+  /**
+   * Token-proxy dev mode. `vite.config.ts` sets `import.meta.env.VITE_USE_PROXY`
+   * to a boolean — true when DYNAMICS_URL is configured — and proxies
+   * /api/data/* to Dataverse with a server-side bearer token. Truthiness check
+   * (NOT `=== 'true'`): the `define` value is a real boolean, not a string.
+   */
+  public static isTokenMode = !!import.meta.env.VITE_USE_PROXY;
+  /**
+   * @param Xrm        The Xrm context (required when deployed). Resolve it from
+   *                   `window.parent?.Xrm ?? window.Xrm` in App.tsx.
+   * @param createMock Optional factory for a domain-specific mock. Used ONLY in
+   *                   mock mode (after the token-mode check), so a token session
+   *                   still talks to the real org. Defaults to MockApiService.
+   */
+  public static createApiService(
+    Xrm?: any,
+    createMock?: () => IApiService,
+  ): IApiService {
+    if (ServiceFactory.isMockEnvironment && ServiceFactory.isTokenMode) {
+      logger.info("Token mode — using FetchApiService via proxy", {
+        source: "ServiceFactory",
+      });
+      return new FetchApiService();
+    }
+    if (ServiceFactory.isMockEnvironment) {
+      logger.info("Mock mode — using MockApiService", {
+        source: "ServiceFactory",
+      });
+      return (createMock ?? (() => new MockApiService()))();
+    }
+    if (!Xrm) {
+      throw new Error("Xrm object is required in a non-mock environment.");
+    }
+    return new XrmApiService(Xrm);
+  }
+}

package/templates/react-custom-page/src/core/services/XrmApiService.ts ADDED Viewed

@@ -0,0 +1,135 @@
+import { IApiService } from "./IApiService";
+import { logCrud } from "./crudLogging";
+import { logger } from "@khester/reusable-components";
+/**
+ * Production API service for a model-driven custom page. Every call hits the
+ * Dataverse Web API on the same origin (the hosting org authenticates the
+ * request via its session), addressing entities by their SET name (e.g.
+ * "accounts") so reads and writes use one consistent identifier.
+ */
+export class XrmApiService implements IApiService {
+  private Xrm: any;
+  constructor(Xrm: any) {
+    if (!Xrm) throw new Error("Xrm object is required");
+    this.Xrm = Xrm;
+  }
+  private clientUrl(): string {
+    return this.Xrm.Page.context.getClientUrl();
+  }
+  private headers(): HeadersInit {
+    return {
+      "OData-MaxVersion": "4.0",
+      "OData-Version": "4.0",
+      "Content-Type": "application/json; charset=utf-8",
+      Accept: "application/json",
+      Prefer: 'odata.include-annotations="*"',
+    };
+  }
+  retrieveMultipleRecords(
+    entity: string,
+    fetchXml: string,
+  ): Promise<{ entities: any[] }> {
+    return logCrud(
+      { op: "READ", entity, resultCount: (r) => r?.entities?.length },
+      async () => {
+        const url = `${this.clientUrl()}/api/data/v9.2/${entity}?fetchXml=${encodeURIComponent(fetchXml)}`;
+        const response = await fetch(url, { method: "GET", headers: this.headers() });
+        if (!response.ok) throw await response.json();
+        const data = await response.json();
+        return { entities: data.value ?? [] };
+      },
+    );
+  }
+  createRecord(entity: string, record: any): Promise<any> {
+    return logCrud({ op: "CREATE", entity, resultId: (r) => r?.id }, async () => {
+      const url = `${this.clientUrl()}/api/data/v9.2/${entity}`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(record),
+      });
+      if (!response.ok) throw await response.json();
+      const uri = response.headers.get("OData-EntityId");
+      const match = uri ? /\(([^)]+)\)/.exec(uri) : null;
+      return { id: match ? match[1] : null };
+    });
+  }
+  updateRecord(entity: string, id: string, record: any): Promise<any> {
+    return logCrud({ op: "UPDATE", entity, id }, async () => {
+      const cleanId = id.replace(/[{}]/g, "");
+      const url = `${this.clientUrl()}/api/data/v9.2/${entity}(${cleanId})`;
+      const response = await fetch(url, {
+        method: "PATCH",
+        headers: this.headers(),
+        body: JSON.stringify(record),
+      });
+      if (!response.ok) throw await response.json();
+      return { success: true };
+    });
+  }
+  deleteRecord(entity: string, id: string): Promise<void> {
+    return logCrud({ op: "DELETE", entity, id }, async () => {
+      const cleanId = id.replace(/[{}]/g, "");
+      const url = `${this.clientUrl()}/api/data/v9.2/${entity}(${cleanId})`;
+      const response = await fetch(url, { method: "DELETE", headers: this.headers() });
+      if (!response.ok) throw await response.json();
+    });
+  }
+  executeRequest(requestName: string, requestData: any): Promise<any> {
+    return logCrud({ op: "EXECUTE", entity: requestName }, async () => {
+      const { getMetadata: _getMetadata, ...payload } = requestData ?? {};
+      const url = `${this.clientUrl()}/api/data/v9.2/${requestName}`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(payload),
+      });
+      if (!response.ok) throw await response.json();
+      const text = await response.text();
+      return text ? JSON.parse(text) : null;
+    });
+  }
+  async associateRecord(
+    entityName: string,
+    entityId: string,
+    relationshipName: string,
+    relatedEntityName: string,
+    relatedEntityId: string,
+  ): Promise<void> {
+    return logCrud(
+      { op: "ASSOCIATE", entity: entityName, id: entityId },
+      async () => {
+        const url = `${this.clientUrl()}/api/data/v9.2/${entityName}(${entityId})/${relationshipName}/$ref`;
+        const response = await fetch(url, {
+          method: "POST",
+          headers: this.headers(),
+          body: JSON.stringify({
+            "@odata.id": `${this.clientUrl()}/api/data/v9.2/${relatedEntityName}(${relatedEntityId})`,
+          }),
+        });
+        if (!response.ok) {
+          throw new Error(`associateRecord failed (${response.status})`);
+        }
+      },
+    );
+  }
+  async uploadFile(file: File): Promise<string> {
+    // Stub — wire up to your file/notes/blob strategy as needed.
+    logger.warn("uploadFile not implemented", {
+      source: "XrmApiService",
+      data: { file: file.name },
+    });
+    return "";
+  }
+}