@edirect/dynamics

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

• 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

pnpm add @edirect/dynamics
# or
npm install @edirect/dynamics

Setup

1. Set environment variables

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
[email protected]  # required for password grant
DYNAMICS_PASSWORD=your-dynamics-password           # required for password grant
DYNAMICS_RESOURCE=https://yourorg.crm.dynamics.com
DYNAMICS_ENABLED=true

2. Register DynamicsModule in your AppModule

import { Module } from '@nestjs/common';
import { DynamicsModule } from '@edirect/dynamics';

@Module({
  imports: [DynamicsModule],
})
export class AppModule {}

3. Inject and use DynamicsService

import { Injectable } from '@nestjs/common';
import { DynamicsService } from '@edirect/dynamics';

@Injectable()
export class PolicySyncService {
  constructor(private readonly dynamics: DynamicsService) {}

  // 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

| 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)