@cemiar/cemiarlink-sdk

Unified SDK for accessing CemiarLink API services. This package consolidates multiple legacy services into a single, consistent SDK.

This package replaces the following legacy libraries:

| Legacy Package | Replaced By | |----------------|-------------| | cemiar-mail-service | MailService | | cemiar-admin-service | AdminService | | cemiar-epic-service | EpicService | | cemiar-epic-service-common | EpicService |

Installation

npm install @cemiar/cemiarlink-sdk

When working inside this monorepo, you can add it via a file reference:

npm install @cemiar/cemiarlink-sdk@file:../packages/cemiar-cemiarlink-sdk

Usage

MailService

import { MailService } from "@cemiar/cemiarlink-sdk";

const mailService = new MailService(
    process.env.CEMIARLINK_MAIL_URL,
    { Authorization: `Bearer ${token}` },
    "[email protected]",  // Gmail user (optional)
    "app-password"      // Gmail app password (optional)
);

// Get email folders
const folders = await mailService.getEmailFolders();

// Get email message IDs with filter
const messageIds = await mailService.getEmailMessageIds({
    labelIds: "UNREAD",
    q: "from:[email protected]"
});

// Retrieve email reports for a specific date
const reports = await mailService.getEmailReports(new Date(), {
    includeRead: false,
    skipRead: false,
    subfolders: ["INBOX"]
});

// Send an email via Nodemailer
await mailService.sendMail(
    "Subject",
    "Plain text content",
    "<h1>HTML content</h1>",
    ["[email protected]"],
    [{ filename: "attachment.pdf", content: buffer }],
    ["[email protected]"]
);

// Delete an email
await mailService.deleteEmail(emailId);

AdminService

import { AdminService } from "@cemiar/cemiarlink-sdk";

const adminService = new AdminService(
    process.env.CEMIARLINK_ADMIN_URL,
    { Authorization: `Bearer ${token}` },
    "task-id" // Optional task ID
);

// Update Cemiar task status
await adminService.updateCemiarTask("success");

// PDF operations
const pdfResponse = await adminService.pdfReader("route", "insurer", { base64: fileBase64 });
const comparison = await adminService.pdfCompare(payload, "v2");
const comparisonExcel = await adminService.pdfCompareExcel(payload, "v2");

// Text extraction
const textPages = await adminService.getPdfText(fileBase64, "engine", "1");

// Table extraction from PDF
const tables = await adminService.extractTableFromBase64({ base64: fileBase64 });

// Insurer extraction
const insurer = await adminService.extractInsurerFromBase64({ base64: fileBase64 });

// Azure OCR
const ocrResults = await adminService.azureOCRExtraction({ base64: fileBase64 });

// Document classification
const classification = await adminService.classifyDocument("insurer", fileBase64);

// Send SMS via Kimoby
await adminService.sendTextMessage("Hello!", "+15551234567", "John Doe", "enterprise");

// Send email notification
await adminService.sendNotification({
    to: "[email protected]",
    subject: "Notification",
    body: "Content"
});

// Send email via AWS SES
const result = await adminService.sendEmailAws({
    to: ["[email protected]"],
    subject: "Subject",
    html: "<p>Content</p>"
});

// Service Bus messages
await adminService.sendMessagesToQueue("queue-name", { messages: [...] });

// Report management
const reportData = await adminService.getReportData<MyType>("2024-01-15", "Report", 0);
await adminService.createReport(data, headers, "report.xlsx");
await adminService.removeReportFiles("2024-01-15", "Report");

// Counter management
const counter = await adminService.getCounter("task-id");
await adminService.updateCounter("counter-id", 42);

EpicService

import { EpicService } from "@cemiar/cemiarlink-sdk";

const epicService = new EpicService(
    process.env.CEMIARLINK_EPIC_URL,
    { Authorization: `Bearer ${token}` }
);

// Activities
const activities = await epicService.getActivities({ clientId: "123" });
const activity = await epicService.getActivity("activity-id");
const newActivityId = await epicService.createActivity({ /* payload */ });
await epicService.updateActivity("activity-id", { /* payload */ });
await epicService.copyActivity("activity-id", { /* payload */ });

// Attachments
const attachments = await epicService.getAttachments({ policyId: "123" });
const attachment = await epicService.getAttachment("attachment-id");
const content = await epicService.getAttachmentContent("attachment-id");
await epicService.createAttachment({ /* payload */ });
await epicService.updateAttachment("attachment-id", { /* payload */ });
await epicService.deleteAttachment("attachment-id");

// Policies (V1)
const policies = await epicService.getPolicies({ clientId: "123" });
const policy = await epicService.getPolicy("policy-id");
await epicService.createPolicy({ /* payload */ });
await epicService.updatePolicy("policy-id", { /* payload */ });
await epicService.renewPolicy("policy-id", { /* payload */ });
await epicService.issuePolicy("policy-id", { /* payload */ });
await epicService.cancelPolicy("policy-id", { /* payload */ });
await epicService.endorsePolicy("policy-id", { /* payload */ });

// Policies (V2 - recommended)
const policiesV2 = await epicService.getPoliciesV2({ clientId: "123" });
const policyV2 = await epicService.getPolicyV2("policy-id");
await epicService.createPolicyV2({ /* payload */ });
await epicService.updatePolicyV2("policy-id", { /* payload */ });
await epicService.renewPolicyV2({ /* payload */ });
await epicService.issuePolicyV2({ /* payload */ });
await epicService.cancelPolicyV2({ /* payload */ });
await epicService.endorseExistingLinePolicyV2({ /* payload */ });
await epicService.issueEndorsementPolicyV2({ /* payload */ });
await epicService.issueCancellationPolicyV2({ /* payload */ });
const renewalStages = await epicService.getPolicyV2RenewalStages([1, 2, 3]);

// Customers
const customers = await epicService.getCustomers({ name: "John" });
const customer = await epicService.getCustomer("client-id");
await epicService.createCustomer({ /* payload */ });
await epicService.updateCustomer("client-id", { /* payload */ });

// Contacts
const contacts = await epicService.getContacts({ clientId: "123" });
const contact = await epicService.getContact("contact-id", {});
await epicService.createContact({ /* payload */ });
await epicService.updateContact("contact-id", "accountType", { /* payload */ });

// Transactions
const transactions = await epicService.getTransactions({ policyId: "123" });
const transaction = await epicService.getTransaction("transaction-id");
await epicService.createTransaction({ /* payload */ });
await epicService.createPaymentTransaction({ /* payload */ });
await epicService.updateTransaction("transaction-id", { /* payload */ });
await epicService.financeTransaction("transaction-id", { /* payload */ });
await epicService.reverseTransaction("transaction-id", { /* payload */ });
await epicService.transactionApplyCreditsToDebits("transaction-id", { /* payload */ });

// Employees
const employees = await epicService.getEmployees({});
const employee = await epicService.getEmployee("employee-id");
const employeesV2 = await epicService.getEmployeesV2({});
const employeeV2 = await epicService.getEmployeeV2(123);
await epicService.createEmployee({ /* payload */ });
await epicService.updateEmployee(123, { /* payload */ });

// Companies
const companies = await epicService.getCompanies({});
const company = await epicService.getCompany("company-id");

// Receipts
const receipts = await epicService.getReceipts({});
const receipt = await epicService.getReceipt("receipt-id");
await epicService.createReceipt({ /* payload */ });
await epicService.updateReceipt("receipt-id", { /* payload */ });
await epicService.receiptApplyCreditsToDebits("receipt-id", { /* payload */ });

// Claims
const claims = await epicService.getClaims({});
const claim = await epicService.getClaim("claim-id");

// Opportunities
const opportunities = await epicService.getOpportunities({});
const opportunity = await epicService.getOpportunity("opportunity-id");
await epicService.createOpportunity({ /* payload */ });
await epicService.updateOpportunity("opportunity-id", { /* payload */ });

// Vehicles & Drivers
const personalVehicles = await epicService.getPersonalAutoVehicles({});
const personalDrivers = await epicService.getPersonalAutoDrivers({});
const commercialVehicles = await epicService.getCommercialAutoVehicles({});
const commercialDrivers = await epicService.getCommercialAutoDrivers({});

// Policy Lines
const lines = await epicService.getPolicyLines({});
const line = await epicService.getPolicyLine("line-id");
await epicService.createPolicyLine({ /* payload */ });
await epicService.updatePolicyLine("line-id", { /* payload */ });

// Commissions
const commission = await epicService.getCommission("commission-id");
const commissions = await epicService.getCommissions("commission-id", {});

// Lookups
const lookups = await epicService.getLookUp({ type: "coverageType" });

// Habitationals
const habitationals = await epicService.getHabitationals({});

// Additional Interests
const additionalInterests = await epicService.getAdditionalInterests({});

// Journal Entries
const journalEntries = await epicService.getJournalEntries({});
const journalEntry = await epicService.getJournalEntry("journal-id");
await epicService.createJournalEntry({ /* payload */ });
await epicService.updateJournalEntry("journal-id", { /* payload */ });

// General Ledger Banks
const banks = await epicService.getGeneralLedgerReconcileBanks({});
const bank = await epicService.getGeneralLedgerReconcileBank("bank-id");
await epicService.createGeneralLedgerReconcileBank({ /* payload */ });
await epicService.updateGeneralLedgerBank("bank-id", { /* payload */ });

// Payable Contracts
const contracts = await epicService.getPayableContracts({});
const contract = await epicService.getPayableContract("contract-id", {});

// Sub-services
const mcsResult = await epicService.multiCarrierSchedule.getSchedules({});
const dbcResult = await epicService.directBillCommission.getCommissions({});

GoogleAdsService

import { GoogleAdsService } from "@cemiar/cemiarlink-sdk";

const googleAdsService = new GoogleAdsService(
    process.env.CEMIARLINK_BASE_URL,
    { Authorization: `Bearer ${token}` }
);

// Upload offline conversions
const uploadResult = await googleAdsService.uploadConversions("enterprise", [
    {
        gclid: "click-id",
        conversion_action: "conversion-action-name",
        conversion_date_time: "2024-01-15 10:30:00+00:00",
        conversion_value: 100.00,
        currency_code: "CAD"
    }
]);

// Upload conversion adjustments
const adjustmentResult = await googleAdsService.uploadConversionAdjustments("enterprise", [
    { /* adjustment payload */ }
]);

SharepointService

import { SharepointService } from "@cemiar/cemiarlink-sdk";

const sharepointService = new SharepointService(
    process.env.CEMIARLINK_BASE_URL,
    { Authorization: `Bearer ${token}` }
);

// Find a file
const fileInfo = await sharepointService.findFile({
    connection: { siteId: "site-id", driveId: "drive-id" },
    path: "/folder/subfolder",
    fileName: "document.pdf"
});

// Download a file by ID
const buffer = await sharepointService.downloadFileById("file-id", {
    siteId: "site-id",
    driveId: "drive-id"
});

// Find and download in one call
const result = await sharepointService.findAndDownload({
    connection: { siteId: "site-id", driveId: "drive-id" },
    path: "/folder",
    fileName: "report.xlsx"
});
if (result) {
    console.log(result.fileName, result.fileId, result.webUrl);
    fs.writeFileSync(result.fileName, result.buffer);
}

Migration Guide

From cemiar-mail-service

- import MailService from "cemiar-mail-service";
+ import { MailService } from "@cemiar/cemiarlink-sdk";

// Constructor signature remains the same
const mailService = new MailService(mailUrl, headers, user, password);

// All methods have the same signatures:
// ✅ getEmailFolders()
// ✅ getEmailMessageIds(filter)
// ✅ updateEmailMetadata(mailId, payload)
// ✅ getEmailReport(to, subjectType, options)
// ✅ getEmailReports(date, options)
// ✅ getTransactionWatchList(to, subjectType)
// ✅ deleteEmail(id)
// ✅ sendMail(subject, text, html, to, attachments, cc)

From cemiar-admin-service

- import AdminService from "cemiar-admin-service";
+ import { AdminService } from "@cemiar/cemiarlink-sdk";

// Constructor signature remains the same
const adminService = new AdminService(adminUrl, headers, taskId);

// All methods have the same signatures:
// ✅ updateCemiarTask(status)
// ✅ pdfReader(route, issuingCompany, payload)
// ✅ pdfCompare(payload, apiVersion)
// ✅ pdfCompareExcel(payload, apiVersion)
// ✅ extractTableFromBase64(payload)
// ✅ extractInsurerFromBase64(payload)
// ✅ extractVehicles(payload)
// ✅ azureOCRExtraction(payload)
// ✅ sendTextMessage(message, phoneNumber, name, enterprise)
// ✅ getModuleConfig()
// ✅ getReportData(date, fileName, sheetNumber)
// ✅ getTestData(fileName, sheetNumber)
// ✅ saveTestResult(result, fileName)
// ✅ removeReportFiles(date, fileName)
// ✅ unSyncFiles()
// ✅ createReport(sheatData, headers, name)
// ✅ getPrimacoFlashPaymentLink(request, enterprise) - deprecated
// ✅ getCounter(taskId)
// ✅ updateCounter(counterId, numberOfRequest)
// ✅ classifyDocument(insurer, fileContentBase64)
// ✅ sendMessagesToQueue(queue, messages)
// ✅ sendNotification(notification)
// ✅ sendEmailAws(emailBody)

// New method in cemiarlink-sdk:
// ➕ getPdfText(fileContentBase64, engine?, page?)

From cemiar-epic-service

- import EpicService from "cemiar-epic-service";
+ import { EpicService } from "@cemiar/cemiarlink-sdk";

// Constructor signature remains the same
const epicService = new EpicService(epicUrl, headers);

// All existing methods are preserved with same signatures:
// ✅ getActivity(activityId)
// ✅ getActivities(queryParams)
// ✅ updateActivity(activityId, payload)
// ✅ createActivity(payload)
// ✅ getAttachments(queryParams)
// ✅ getAttachment(attachmentId)
// ✅ updateAttachment(attachmentId, payload)
// ✅ createAttachment(payload)
// ✅ getAttachmentContent(attachmentId)
// ✅ deleteAttachment(attachmentId)
// ✅ getPolicies(queryParams)
// ✅ getPolicy(id)
// ✅ createPolicy(payload)
// ✅ updatePolicy(id, payload)
// ✅ renewPolicy(id, payload)
// ✅ issuePolicy(id, payload)
// ✅ cancelPolicy(id, payload)
// ✅ getEmployee(id)
// ✅ getEmployees(queryParams)
// ✅ getLookUp(queryParams)
// ✅ getContact(id, queryParams)
// ✅ getContacts(queryParams)
// ✅ createContact(payload)
// ✅ updateContact(id, accountType, payload)
// ✅ getTransactions(queryParams)
// ✅ getTransaction(transactionId)
// ✅ financeTransaction(transactionId, payload)
// ✅ reverseTransaction(transactionId, payload)
// ✅ transactionApplyCreditsToDebits(transactionId, payload)
// ✅ updateTransaction(transactionId, payload)
// ✅ createTransaction(payload)
// ✅ createPaymentTransaction(payload)
// ✅ getCompany(companyId)
// ✅ getCompanies(queryParams)
// ✅ getCustomers(queryParams)
// ✅ getCustomer(clientId)
// ✅ updateCustomer(clientId, payload)
// ✅ createCustomer(payload)
// ✅ getHabitationals(queryParams)
// ✅ getCommissions(commissionId, queryParams)
// ✅ getCommission(commissionId)
// ✅ getOpportunity(opportunityId)
// ✅ getOpportunities(queryParams)
// ✅ updateOpportunity(opportunityId, payload)
// ✅ createOpportunity(payload)
// ✅ getClaim(claimId)
// ✅ getClaims(queryParams)
// ✅ getPolicyLines(queryParams)
// ✅ createPolicyLine(policyLine)
// ✅ getDirectBillCommission(commissionId) → via epicService.directBillCommission
// ✅ getDirectBillCommissions(queryParams) → via epicService.directBillCommission
// ✅ updateDirectBillCommission(commissionId, payload) → via epicService.directBillCommission
// ✅ getReceipts(queryParams)
// ✅ getReceipt(receiptId)
// ✅ updateReceipt(receiptId, payload)
// ✅ createReceipt(payload)
// ✅ receiptApplyCreditsToDebits(receiptId, payload)

// Renamed methods:
- epicService.getPersonalVehicles(queryParams)
+ epicService.getPersonalAutoVehicles(queryParams)

From cemiar-epic-service-common

- import EpicService from "cemiar-epic-service-common";
+ import { EpicService } from "@cemiar/cemiarlink-sdk";

// Constructor signature remains the same
const epicService = new EpicService(epicUrl, headers);

// All methods from cemiar-epic-service-common are preserved:
// ✅ All V1 methods (see cemiar-epic-service above)

// V2 Policy methods:
// ✅ getPoliciesV2(queryParams)
// ✅ getPolicyV2(id)
// ✅ createPolicyV2(payload)
// ✅ updatePolicyV2(id, payload)
// ✅ renewPolicyV2(payload)
// ✅ endorseExistingLinePolicyV2(payload)
// ✅ cancelPolicyV2(payload)
// ✅ issuePolicyV2(payload)
// ✅ issueEndorsementPolicyV2(payload)
// ✅ issueCancellationPolicyV2(payload)
// ✅ getPolicyV2RenewalStages(ids)

// V2 Employee methods:
// ✅ getEmployeeV2(id)
// ✅ getEmployeesV2(queryParams)
// ✅ createEmployee(payload)
// ✅ updateEmployee(id, payload)

// Sub-services:
// ✅ epicService.multiCarrierSchedule.*
// ✅ epicService.directBillCommission.*

// Removed/changed:
- epicService.job.* // JobEpicService not included

// New methods in cemiarlink-sdk:
// ➕ endorsePolicy(id, payload)
// ➕ copyActivity(id, payload)
// ➕ getPolicyLine(lineId)
// ➕ updatePolicyLine(lineId, payload)
// ➕ getPersonalAutoDrivers(queryParams)
// ➕ getCommercialAutoVehicles(queryParams)
// ➕ getCommercialAutoDrivers(queryParams)
// ➕ getPayableContracts(queryParams)
// ➕ getPayableContract(payableContractId, queryParams)
// ➕ getGeneralLedgerReconcileBanks(queryParams)
// ➕ getGeneralLedgerReconcileBank(bankId)
// ➕ createGeneralLedgerReconcileBank(payload)
// ➕ updateGeneralLedgerBank(bankId, payload)
// ➕ getAdditionalInterests(queryParams)
// ➕ getJournalEntry(journalEntryId)
// ➕ getJournalEntries(queryParams)
// ➕ createJournalEntry(payload)
// ➕ updateJournalEntry(journalEntryId, payload)

Quick Migration Steps

1. Update package.json:

{
  "dependencies": {
-   "cemiar-mail-service": "^1.0.48",
-   "cemiar-admin-service": "^1.0.61",
-   "cemiar-epic-service": "^1.0.98",
-   "cemiar-epic-service-common": "^1.0.140",
+   "@cemiar/cemiarlink-sdk": "^1.0.0"
  }
}

2. Update imports:

- import MailService from "cemiar-mail-service";
- import AdminService from "cemiar-admin-service";
- import EpicService from "cemiar-epic-service";
- import EpicService from "cemiar-epic-service-common";
+ import { MailService, AdminService, EpicService } from "@cemiar/cemiarlink-sdk";

3. Install and test:

npm install
npm run build
npm test

Models

All TypeScript models are exported and organized by service:

import {
    // Admin models
    PdfReaderBody,
    PdfReaderResponse,
    ClassificationResult,
    Email,
    EmailAws,
    SendMailResult,
    Counter,
    BusMessagePayload,
    
    // Epic models
    Activity,
    Attachment,
    Policy,
    PolicyV2,
    Customer,
    Contact,
    Transaction,
    Employee,
    Company,
    Receipt,
    Claim,
    Opportunity,
    Vehicle,
    Driver,
    Commission,
    JournalEntry,
    
    // Mail models
    EmailReport,
    EmailAttachment,
    GMailFolder,
    TransactionWatch,
    
    // Google Ads models
    GoogleAdsConversion,
    GoogleAdsConversionUploadResponse,
    
    // Sharepoint models
    SharepointFileInfo,
    SharepointDownloadResult
} from "@cemiar/cemiarlink-sdk";

// Or use namespaced imports
import { Models } from "@cemiar/cemiarlink-sdk";
const activity: Models.EpicModels.Activity = { /* ... */ };

Exceptions

import { EpicException, MissingInfo, NotProcessYet } from "@cemiar/cemiarlink-sdk";

try {
    await epicService.getPolicy("invalid-id");
} catch (error) {
    if (error instanceof EpicException) {
        console.error("Epic API error:", error.message);
    }
}

Environment Variables

| Variable | Description | |----------|-------------| | CEMIARLINK_BASE_URL | Base CemiarLink API URL | | CEMIARLINK_MAIL_URL | Mail service URL | | CEMIARLINK_ADMIN_URL | Admin service URL | | CEMIARLINK_EPIC_URL | Epic service URL |

Building

cd cemiar-cemiarlink-sdk
npm install
npm run build        # Linux/Mac
npm run buildWindows # Windows

Output will be generated under dist/.