@edirect/dynamics 11.0.50 → 11.0.52

package/dist/README.md

@@ -1,68 +1,137 @@
 # @edirect/dynamics
 
-Dynamics integration module for Edirect applications. Provides services and utilities to interact with Microsoft Dynamics APIs, including authentication, data posting, and configuration.
+Microsoft Dynamics 365 integration module for eDirect NestJS applications. Handles OAuth2 token acquisition (password grant and client credentials), automatic token refresh, and provides `get`, `post`, and `patch` methods for Dynamics API calls.
 
 ## Features
 
-- Handles OAuth2 authentication with Dynamics
-- Provides service for posting and retrieving data
-- Integrates with NestJS and Edirect config modules
+- OAuth2 `password` grant and `client_credentials` grant support
+- Automatic token caching and refresh (falls back to full re-auth on refresh failure)
+- `get`, `post`, `patch` HTTP methods with automatic Bearer token injection
+- `DYNAMICS_ENABLED` flag to safely disable all Dynamics calls without removing code
+- NestJS module — integrates with `@edirect/config`
 
 ## Installation
 
-```bash
+```sh
+pnpm add @edirect/dynamics
+# or
 npm install @edirect/dynamics
 ```
 
-## Usage
+## Setup
 
-Add the following environment variables to your .env file:
+### 1. Set environment variables
 
 ```env
-DYNAMICS_TOKEN_URL="https://login.windows.net/YOUR_TENANT/oauth2/token"
-DYNAMICS_CLIENT_ID="YOUR_CLIENT_ID"
-DYNAMICS_USER_NAME="YOUR_USER_NAME"
-DYNAMICS_PASSWORD="YOUR_DYNAMICS_PASSWORD"
-DYNAMICS_RESOURCE="YOUR_RESOURCE_URL"
-DYNAMICS_ENABLED="true/false"
+DYNAMICS_TOKEN_URL=https://login.windows.net/YOUR_TENANT_ID/oauth2/token
+DYNAMICS_CLIENT_ID=your-client-id
+DYNAMICS_CLIENT_SECRET=your-client-secret       # required for client_credentials grant
+DYNAMICS_USER_NAME=service@yourorg.onmicrosoft.com  # required for password grant
+DYNAMICS_PASSWORD=your-dynamics-password           # required for password grant
+DYNAMICS_RESOURCE=https://yourorg.crm.dynamics.com
+DYNAMICS_ENABLED=true
 ```
 
-Import and register the module in your app:
+### 2. Register `DynamicsModule` in your AppModule
 
-```typescript
+```ts
 import { Module } from '@nestjs/common';
 import { DynamicsModule } from '@edirect/dynamics';
 
 @Module({
   imports: [DynamicsModule],
-  ...
 })
 export class AppModule {}
 ```
 
-Use the service in your controllers:
+### 3. Inject and use `DynamicsService`
 
-```typescript
-import { Controller } from '@nestjs/common';
+```ts
+import { Injectable } from '@nestjs/common';
 import { DynamicsService } from '@edirect/dynamics';
 
-@Controller('cats')
-export class CatsController {
-  constructor(private readonly dynamicsService: DynamicsService) {}
+@Injectable()
+export class PolicySyncService {
+  constructor(private readonly dynamics: DynamicsService) {}
 
-  postSomethingToDynamics(): Promise<any> {
-    return this.dynamicsService.post('YOUR_URL', {
-      YOUR_ATTRIBUTE: 'YOUR_VALUE',
-    });
+  // POST using password grant (default)
+  async createContact(data: object): Promise<object | null> {
+    return this.dynamics.post(
+      'https://yourorg.crm.dynamics.com/api/data/v9.2/contacts',
+      data,
+    );
+  }
+
+  // PATCH using password grant
+  async updateContact(id: string, data: object): Promise<object | null> {
+    return this.dynamics.patch(
+      `https://yourorg.crm.dynamics.com/api/data/v9.2/contacts(${id})`,
+      data,
+    );
+  }
+
+  // GET using client_credentials grant
+  async getAccounts(): Promise<object | null> {
+    return this.dynamics.get(
+      'https://yourorg.crm.dynamics.com/api/data/v9.2/accounts',
+      {},
+      'client_credentials',
+    );
   }
 }
 ```
 
+## API
+
+### `DynamicsService`
+
+#### `get(url, options?, grantType?): Promise<object | null>`
+
+Performs a GET request to the Dynamics API. Returns `null` if `DYNAMICS_ENABLED` is `false`.
+
+| Parameter   | Type                                 | Default      | Description                      |
+| ----------- | ------------------------------------ | ------------ | -------------------------------- |
+| `url`       | `string`                             | —            | Full Dynamics API endpoint URL   |
+| `options`   | `AxiosRequestConfig`                 | —            | Additional Axios request options |
+| `grantType` | `'password' \| 'client_credentials'` | `'password'` | OAuth2 grant type to use         |
+
+#### `post(url, data, options?, grantType?): Promise<object | null>`
+
+Performs a POST request. Returns `null` if `DYNAMICS_ENABLED` is `false`.
+
+#### `patch(url, data, options?, grantType?): Promise<object | null>`
+
+Performs a PATCH request. Returns `null` if `DYNAMICS_ENABLED` is `false`.
+
+#### `getAccessToken(): Promise<ITokenSet>`
+
+Acquires a token using the `password` grant. Automatically refreshes if expired.
+
+#### `getAccessTokenByClientCredentials(): Promise<ITokenSet>`
+
+Acquires a token using `client_credentials` grant.
+
+#### `getRefreshToken(): Promise<ITokenSet>`
+
+Refreshes the current token. Falls back to `getAccessToken()` on failure.
+
 ## Environment Variables
 
-- `DYNAMICS_TOKEN_URL`: OAuth2 token endpoint for Dynamics
-- `DYNAMICS_CLIENT_ID`: Client ID for authentication
-- `DYNAMICS_USER_NAME`: Username for Dynamics
-- `DYNAMICS_PASSWORD`: Password for Dynamics
-- `DYNAMICS_RESOURCE`: Resource URL for Dynamics API
-- `DYNAMICS_ENABLED`: Enable/disable Dynamics integration
+| Variable                 | Description                                                       | Required For         |
+| ------------------------ | ----------------------------------------------------------------- | -------------------- |
+| `DYNAMICS_TOKEN_URL`     | Azure AD OAuth2 token endpoint                                    | All grant types      |
+| `DYNAMICS_CLIENT_ID`     | Application client ID                                             | All grant types      |
+| `DYNAMICS_CLIENT_SECRET` | Client secret                                                     | `client_credentials` |
+| `DYNAMICS_USER_NAME`     | Service account username                                          | `password`           |
+| `DYNAMICS_PASSWORD`      | Service account password                                          | `password`           |
+| `DYNAMICS_RESOURCE`      | Dynamics CRM resource URL                                         | All grant types      |
+| `DYNAMICS_ENABLED`       | Set to `'true'` to enable; any other value disables all API calls | All                  |
+
+## Token Flow
+
+```
+1. First call → acquire token (password or client_credentials)
+2. Subsequent calls → if token not expired, use refresh_token grant
+3. If refresh fails → fall back to full re-authentication
+4. Token is cached in memory (service singleton)
+```

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edirect/dynamics",
-  "version": "11.0.46",
+  "version": "11.0.52",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "exports": {
@@ -16,18 +16,18 @@
     "dist"
   ],
   "dependencies": {
-    "@edirect/config": "^11.0.46",
+    "@edirect/config": "^11.0.52",
     "@nestjs/axios": "^4.0.1",
-    "@nestjs/common": "^11.1.12",
-    "axios": "^1.13.3",
+    "@nestjs/common": "^11.1.17",
+    "axios": "^1.13.6",
     "lodash": "^4.17.23",
     "tslib": "^2.8.1"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
     "@types/jest": "30.0.0",
-    "@types/lodash": "4.17.23",
-    "@types/node": "^25.0.10"
+    "@types/lodash": "4.17.24",
+    "@types/node": "^25.4.0"
   },
   "type": "commonjs"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edirect/dynamics",
-  "version": "11.0.50",
+  "version": "11.0.52",
   "packageScope": "@edirect",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
@@ -18,11 +18,11 @@
   ],
   "dependencies": {
     "@nestjs/axios": "^4.0.1",
-    "@nestjs/common": "^11.1.16",
+    "@nestjs/common": "^11.1.17",
     "axios": "^1.13.6",
     "lodash": "^4.17.23",
     "tslib": "^2.8.1",
-    "@edirect/config": "11.0.50"
+    "@edirect/config": "11.0.52"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",