@khester/create-dynamics-app 2.1.0 → 2.2.0

package/templates/grid-starter/README.md

@@ -0,0 +1,122 @@
+# Grid Starter (Dataverse custom page)
+
+A production-shaped starter for a React app mounted as a **Dynamics 365 custom
+page**, centered on a reusable **grid**. `src/grid/GridPage.tsx` renders an
+[`@dataverse-kit/grid-kit`](../../../grid-kit) `<DataGrid>` over the
+`ServiceFactory` data seam: mock data on localhost, live Dataverse in production.
+
+The grid is **registry-driven** — every column is a `ColumnDef` with a
+`rendererType` (text, currency, `coloredCell` status badge, rating, …). The same
+registry works in a PCF grid and a Grid Customizer. To add or change a cell:
+edit the `columns` array in `GridPage.tsx`; to add a bespoke cell type, call
+`registry.register('myType', { read: MyCell })`.
+
+The data-access seam (`src/core/services`) is owned by this app.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `npm install` | Install dependencies |
+| `npm run dev` | Run in **mock** mode — seeded data, no org needed |
+| `npm run dev:token` | Run against a **live org** — refreshes the token + starts Vite |
+| `npm run auth:token -- --url https://<org>.crm.dynamics.com` | Acquire/refresh a Dataverse token into `.env` (needs `az login`) |
+| `npm run build` | Production build → `dist/` (multi-file) |
+| `npm run build:d365` | Single self-contained `dist/index.html` (the web resource) |
+| `npm run deploy` | Build + upload + **publish** the web resource to your org |
+| `npm test` | Run Vitest (no tests ship by default — add your own; passes with none) |
+| `npm run typecheck` | Type-check (`tsc --noEmit`) |
+| `npm install @khester/reusable-components@latest` | Update the shared component library |
+
+> Requires **Node 18+**. For `dev:token` / `deploy` you also need `az login` and
+> `DYNAMICS_URL` in `.env` (set once via `npm run auth:token -- --url …`).
+
+## Quick start
+
+```bash
+npm install
+npm run dev          # mock mode — a seeded account, no org needed
+```
+
+Open http://localhost:3000. The grid lists the seeded accounts; type in the
+toolbar search to filter, click **Refresh** to reload. Each load logs a
+`[CRUD] READ accounts ok` line; on localhost `window.dumpAppLogs()` in the
+browser console prints the structured log buffer.
+
+A floating **🔧 Dev Tools** panel (bottom-right, localhost only) shows the active
+mode (Mock / Token-proxy / Production) and the `[CRUD]` log buffer. It renders
+nothing once deployed.
+
+## Three runtime modes
+
+`src/core/services/ServiceFactory.ts` picks the data service per environment:
+
+| Mode | When | Service |
+|------|------|---------|
+| **Mock** | `localhost`, no `DYNAMICS_URL` | `MockApiService` (in-memory, seeds a few accounts) |
+| **Token** | `localhost` + `DYNAMICS_URL` set | `FetchApiService` → Vite proxy → real Dataverse |
+| **Production** | deployed in a model-driven app | `XrmApiService` (Web API, session auth) |
+
+### Token mode — test against a real org locally
+
+```bash
+npm run auth:token -- --url https://<org>.crm.dynamics.com   # writes .env via Azure CLI
+npm run dev
+```
+
+The Vite dev server proxies `/api/data/*` to the org and injects the bearer token
+**server-side** — the token never enters the browser bundle. Tokens last ~60 min;
+re-run `npm run auth:token` to refresh (no dev-server restart needed). Requires
+`az login` first. See `env.example` for the variables.
+
+Once `DYNAMICS_URL` is in `.env`, **`npm run dev:token`** refreshes the token and
+starts the dev server in one step:
+
+```bash
+npm run dev:token
+```
+
+## Build & deploy
+
+```bash
+npm run build        # standard multi-file build → dist/
+npm run build:d365   # single self-contained dist/index.html (vite-plugin-singlefile)
+npm run deploy       # build:d365 + upload as an HTML web resource + publish
+```
+
+**`npm run deploy`** refreshes the token, builds the single-file bundle, and
+upserts + publishes it as an HTML web resource via the Dataverse Web API (no PAC
+CLI needed). Set the web-resource name in `.env` first — the prefix must match a
+publisher that exists in your org:
+
+```bash
+# .env
+WEBRESOURCE_NAME=cr1a2_/myapp/index.html   # use YOUR publisher prefix
+# WEBRESOURCE_SOLUTION=MySolution          # optional: add it to an unmanaged solution
+```
+
+Then host it on a model-driven **custom page**, or open it via
+`Xrm.Navigation.navigateTo({ pageType: "webresource", webresourceName: "<name>" })`.
+The page reads an optional record id from the URL (`?id=<guid>`); in production it
+resolves `Xrm` from `window.parent`.
+
+> Some orgs enforce a Content-Security-Policy that blocks inline `<script>`. The
+> single-file bundle is one inline script — if your environment blocks it, use the
+> multi-file `npm run build` output instead.
+
+## Make it your own
+
+The grid lives in `src/grid/GridPage.tsx`:
+
+1. **Change columns** — edit the `columns: ColumnDef[]` array. Each column has a
+   `rendererType` (text, currency, coloredCell, rating, optionset, progress, date,
+   link, toggle, …) plus optional `rendererConfig` and `editorType`.
+2. **Custom cell** — `registry.register('myType', { read: MyCell })`, then set a
+   column's `rendererType` to `'myType'`.
+3. **Map your entity** — adjust `mapAccount` and the column `fieldName`s to your
+   Dataverse attributes, and seed rows in `src/core/services/MockApiService.ts`
+   so `npm run dev` works offline.
+
+```bash
+npm run typecheck    # tsc --noEmit
+```

package/templates/grid-starter/env.example

@@ -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/grid-starter/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+*.log
+.env
+.env.local
+.env.*.local

package/templates/grid-starter/index.html

@@ -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/grid-starter/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "grid-starter-app",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Dataverse React custom page with a grid-kit <DataGrid> (Vite + @dataverse-kit/grid-kit)",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "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",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@dataverse-kit/grid-kit": "^0.1.0",
+    "@khester/dynamics-cell-renderers": "^1.1.0",
+    "@khester/reusable-components": "^0.1.4",
+    "@fluentui/react": "^8.110.10",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.1",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.3",
+    "vite": "^5.4.21",
+    "vite-plugin-singlefile": "^2.0.3",
+    "vitest": "^1.6.0"
+  }
+}

package/templates/grid-starter/src/App.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import { ServiceFactory } from "./core/services/ServiceFactory";
+import { GridPage } from "./grid/GridPage";
+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), []);
+  return (
+    <>
+      <GridPage api={api} />
+      {/* Localhost-only floating dev tools (renders nothing once deployed). */}
+      <DevPanel />
+    </>
+  );
+};
+
+export default App;

package/templates/grid-starter/src/core/services/FetchApiService.ts

@@ -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/grid-starter/src/core/services/IApiService.ts

@@ -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/grid-starter/src/core/services/MockApiService.ts

@@ -0,0 +1,72 @@
+import { IApiService } from "./IApiService";
+import { logCrud } from "./crudLogging";
+
+// A few seeded in-memory accounts so `npm run dev` renders the grid with no org
+// or token. Each carries the extra demo fields the grid columns show (revenue,
+// statuscode, rating). Replace this seed as your page grows.
+const SEED_ACCOUNTS = [
+  { 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", revenue: 1500000, statuscode: "Active", rating: 5 },
+  { accountid: "00000000-0000-0000-0000-000000000002", name: "Fabrikam Inc", accountnumber: "ACC-1002", telephone1: "+1 (206) 555-0140", emailaddress1: "hello@fabrikam.example", websiteurl: "https://fabrikam.example", revenue: 220000, statuscode: "On hold", rating: 3 },
+  { accountid: "00000000-0000-0000-0000-000000000003", name: "Adventure Works", accountnumber: "ACC-1003", telephone1: "+1 (312) 555-0190", emailaddress1: "sales@adventure.example", websiteurl: "https://adventure.example", revenue: 85000, statuscode: "Inactive", rating: 2 },
+  { accountid: "00000000-0000-0000-0000-000000000004", name: "Wingtip Toys", accountnumber: "ACC-1004", telephone1: "+1 (646) 555-0177", emailaddress1: "contact@wingtip.example", websiteurl: "https://wingtip.example", revenue: 640000, statuscode: "Active", rating: 4 },
+];
+
+/**
+ * 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> = Object.fromEntries(
+    SEED_ACCOUNTS.map((a) => [a.accountid, { ...a }]),
+  );
+  private nextId = SEED_ACCOUNTS.length + 1;
+
+  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/grid-starter/src/core/services/ServiceFactory.ts

@@ -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/grid-starter/src/core/services/XrmApiService.ts

@@ -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 "";
+  }
+}