ofsc-utility 1.0.20 → 1.0.22

package/dist/events/index.d.ts

@@ -1,9 +1,44 @@
 type AnyObject = {
     [key: string]: any;
 };
+/**
+ * Recursively flattens an object into a single-level object with
+ * underscore-separated keys.
+ *
+ * Example: { a: { b: 1 } } -> { "a_b": 1 }
+ *
+ * Usage: exported helper used when callers need a flat row-style
+ * representation (e.g., CSV export). Not used internally in this
+ * module but available for other modules to import.
+ *
+ * @param obj - The object to flatten.
+ * @param parentKey - Internal recursion prefix (do not pass normally).
+ * @param result - Internal accumulator (do not pass normally).
+ * @returns The flattened object.
+ */
 export declare function flattenObject(obj: AnyObject, parentKey?: string, result?: AnyObject): AnyObject;
 export declare function downloadAllEventsOfDay(clientId: string, clientSecret: string, instanceUrl: string, subscriptionId: string, sinceDate: string, onlyData: boolean): Promise<any[]>;
 export declare function downloadAllEventsOfDayCSV(clientId: string, clientSecret: string, instanceUrl: string, subscriptionId: string, sinceDate: string, onlyData: boolean): Promise<any[]>;
+/**
+ * Generate a deterministic SHA-256 hash for an event item.
+ *
+ * This uses a stable stringification of the selected fields so that
+ * object property ordering does not change the resulting hash. Useful
+ * for deduplication or consistent event identity across runs.
+ *
+ * @param item - Object containing `eventType`, `activityId`, `time`, and `activityChanges`.
+ * @returns Hex-encoded SHA-256 hash string representing the event.
+ */
+export declare function generateHash(item: {
+    eventType: string;
+    activityId: string | number;
+    time: string;
+    activityChanges: unknown;
+    inventoryChanges?: unknown;
+    resourceDetails: {
+        resourceId: string | number;
+    };
+}): string;
 /**
  *  Events of last two minutes
  * @param clientId

package/dist/events/index.js

@@ -6,11 +6,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.flattenObject = flattenObject;
 exports.downloadAllEventsOfDay = downloadAllEventsOfDay;
 exports.downloadAllEventsOfDayCSV = downloadAllEventsOfDayCSV;
+exports.generateHash = generateHash;
 exports.downloadAllEventsOfDLastTwoMinutes = downloadAllEventsOfDLastTwoMinutes;
+const node_crypto_1 = __importDefault(require("node:crypto"));
 const path_1 = __importDefault(require("path"));
 const index_1 = require("../oauthTokenService/index");
 const utilities_1 = require("../utilities");
 const index_2 = require("../utilities/index");
+/**
+ * Recursively flattens an object into a single-level object with
+ * underscore-separated keys.
+ *
+ * Example: { a: { b: 1 } } -> { "a_b": 1 }
+ *
+ * Usage: exported helper used when callers need a flat row-style
+ * representation (e.g., CSV export). Not used internally in this
+ * module but available for other modules to import.
+ *
+ * @param obj - The object to flatten.
+ * @param parentKey - Internal recursion prefix (do not pass normally).
+ * @param result - Internal accumulator (do not pass normally).
+ * @returns The flattened object.
+ */
 function flattenObject(obj, parentKey = "", result = {}) {
     for (const key in obj) {
         const newKey = parentKey ? `${parentKey}_${key}` : key;
@@ -25,6 +42,21 @@ function flattenObject(obj, parentKey = "", result = {}) {
     }
     return result;
 }
+/**
+ * Fetch a single page of events via `fetchWithRetry` and return the
+ * received token and typed `EventResponse` data.
+ *
+ * This is a small wrapper around `fetchWithRetry` that normalizes the
+ * response shape for the callers in this module. It is used by both
+ * `downloadAllEventsOfDayCSV` and `downloadAllEventsOfDLastTwoMinutes`.
+ *
+ * @param url - Full URL for the events endpoint page.
+ * @param token - Current OAuth token (may be refreshed by fetchWithRetry).
+ * @param clientId - OAuth client id used by `fetchWithRetry` if token refresh needed.
+ * @param clientSecret - OAuth client secret used by `fetchWithRetry`.
+ * @param instanceUrl - Instance host used by `fetchWithRetry`.
+ * @returns Object with `token` (possibly refreshed) and `data` typed as `EventResponse`.
+ */
 async function fetchEventsPage(url, token, clientId, clientSecret, instanceUrl) {
     const res = await (0, utilities_1.fetchWithRetry)(url, clientId, clientSecret, instanceUrl, token);
     return {
@@ -32,6 +64,17 @@ async function fetchEventsPage(url, token, clientId, clientSecret, instanceUrl)
         data: res.data
     };
 }
+/**
+ * Return the next calendar day in `YYYY-MM-DD` format for a given
+ * `YYYY-MM-DD` input string.
+ *
+ * Usage: used by `processEventItems` to detect when fetched event
+ * pages cross into the following day, allowing the downloader to stop
+ * collecting events for the requested date.
+ *
+ * @param dateString - Date string in `YYYY-MM-DD` form.
+ * @returns Date string for the next day in `YYYY-MM-DD`.
+ */
 function getNextDay(dateString) {
     // Parse manually to avoid timezone issues
     const [year, month, day] = dateString.split('-').map(Number);
@@ -43,6 +86,25 @@ function getNextDay(dateString) {
     const d = pad(date.getDate());
     return `${y}-${m}-${d}`;
 }
+/**
+ * Process an array of event items and push them into `output` while
+ * enforcing a date boundary.
+ *
+ * Behavior:
+ * - If an event's `time` indicates it belongs to the next calendar
+ *   day (based on `sinceDate`) the function logs and returns `false`
+ *   to signal the caller to stop pagination.
+ * - Otherwise, it extracts `activityId` from `activityDetails` and
+ *   pushes a top-level object into `output`.
+ *
+ * Usage: called from `downloadAllEventsOfDayCSV` during page
+ * iteration to accumulate events for the requested date.
+ *
+ * @param items - Event items from a page response.
+ * @param sinceDate - The starting date (YYYY-MM-DD) used to detect day boundaries.
+ * @param output - Accumulator array to receive processed events.
+ * @returns `true` to continue pagination, `false` to stop.
+ */
 function processEventItems(items, sinceDate, output) {
     for (const item of items) {
         const eventTime = item.time;
@@ -59,10 +121,37 @@ function processEventItems(items, sinceDate, output) {
 }
 async function downloadAllEventsOfDay(clientId, clientSecret, instanceUrl, subscriptionId, sinceDate, onlyData) {
     console.log("Downloading events...OnlyData:", onlyData);
+    // Convenience wrapper: returns the same data as
+    // `downloadAllEventsOfDayCSV` but kept as a separate exported
+    // function for readability and future extension.
     let data = await downloadAllEventsOfDayCSV(clientId, clientSecret, instanceUrl, subscriptionId, sinceDate, onlyData);
     return data;
 }
 async function downloadAllEventsOfDayCSV(clientId, clientSecret, instanceUrl, subscriptionId, sinceDate, onlyData) {
+    /**
+     * Download all events for a specific calendar day and return them as an
+     * array. Internally handles pagination and will stop when pages cross
+     * into the next day.
+     *
+     * Key behaviors and usage:
+     * - Builds an initial request for the given `sinceDate` and pages
+     *   through results using `fetchEventsPage`.
+     * - Uses `processEventItems` to add items to the `events` array and
+     *   stop when the date boundary is reached.
+     * - If `onlyData` is false the collected events are saved to a CSV on
+     *   disk via `saveCsv`.
+     *
+     * Called by: `downloadAllEventsOfDay` (simple wrapper) and can be
+     * imported directly by other modules that need the raw event list.
+     *
+     * @param clientId - OAuth client id for token operations.
+     * @param clientSecret - OAuth client secret for token operations.
+     * @param instanceUrl - Instance host used to construct the endpoint.
+     * @param subscriptionId - Events subscription id to fetch.
+     * @param sinceDate - Date string in `YYYY-MM-DD` to fetch events for.
+     * @param onlyData - When true, skip saving CSV to disk and return data only.
+     * @returns Array of event objects collected for the requested date.
+     */
     // All collected events
     const events = [];
     // Build initial request URL
@@ -126,6 +215,52 @@ async function downloadAllEventsOfDayCSV(clientId, clientSecret, instanceUrl, su
     }
     return events;
 }
+/**
+ * Deterministically stringify a value for stable hashing.
+ *
+ * - Sorts object keys so property order does not affect output.
+ * - Recursively processes arrays and objects.
+ * - Falls back to `JSON.stringify` for primitive values.
+ *
+ * This is used by `generateHash` to produce a stable representation
+ * of event payloads before hashing.
+ *
+ * @param value - The value to stringify (object, array, or primitive).
+ * @returns A deterministic string representation of `value`.
+ */
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        return `{${Object.keys(value)
+            .sort()
+            .map(key => `"${key}":${stableStringify(value[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * Generate a deterministic SHA-256 hash for an event item.
+ *
+ * This uses a stable stringification of the selected fields so that
+ * object property ordering does not change the resulting hash. Useful
+ * for deduplication or consistent event identity across runs.
+ *
+ * @param item - Object containing `eventType`, `activityId`, `time`, and `activityChanges`.
+ * @returns Hex-encoded SHA-256 hash string representing the event.
+ */
+function generateHash(item) {
+    return node_crypto_1.default
+        .createHash("sha256")
+        .update(stableStringify({
+        eventType: item.eventType,
+        activityId: item.activityId || item.resourceDetails.resourceId,
+        time: item.time,
+        activityChanges: item.activityChanges || item.inventoryChanges || {},
+    }))
+        .digest("hex");
+}
 /**
  *  Events of last two minutes
  * @param clientId
@@ -135,6 +270,25 @@ async function downloadAllEventsOfDayCSV(clientId, clientSecret, instanceUrl, su
  * @returns
  */
 async function downloadAllEventsOfDLastTwoMinutes(clientId, clientSecret, instanceUrl, subscriptionId) {
+    /**
+     * Download events from the last ~180 seconds and return them as an
+     * array.
+     *
+     * Differences from `downloadAllEventsOfDayCSV`:
+     * - The `since` timestamp is computed using `getTimeBefore180SecondsAlt`.
+     * - Validates the generated timestamp with `validateDateTimeStrict`.
+     * - For each fetched item, this function attaches a `uniqueId` field
+     *   generated by `generateHash` (used for deduplication or tracing).
+     *
+     * Usage: lightweight polling helper to retrieve recent events for
+     * short-lived processing or monitoring.
+     *
+     * @param clientId - OAuth client id.
+     * @param clientSecret - OAuth client secret.
+     * @param instanceUrl - Instance host.
+     * @param subscriptionId - Subscription id for events.
+     * @returns Array of recent event objects.
+     */
     // All collected events
     const events = [];
     const since = (0, index_2.getTimeBefore180SecondsAlt)();
@@ -173,8 +327,8 @@ async function downloadAllEventsOfDLastTwoMinutes(clientId, clientSecret, instan
         // Prevent infinite looping
         if (nextPage === lastSeenPage) {
             repeatedPageCount++;
-            if (repeatedPageCount > 10) {
-                console.warn("⚠️ Pagination repeating same page more than 10 times. Stopping.");
+            if (repeatedPageCount > 15) {
+                console.warn("⚠️ Pagination repeating same page more than 15 times. Stopping.");
                 break;
             }
         }
@@ -188,6 +342,9 @@ async function downloadAllEventsOfDLastTwoMinutes(clientId, clientSecret, instan
             break;
         }
         for (let k of page.items) {
+            k["uniqueId"] = generateHash(k);
+            k["Change"] = k.activityChanges || k.inventoryChanges || {};
+            k["Id"] = k.activityId || k.resourceDetails?.resourceId || '-';
             events.push(k);
         }
     }

package/dist/events/scripts/fetch-events-example.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Example script to fetch events using the `src/events` helpers.
+ *
+ * This copy lives under `src/` so `tsc` will emit it into `dist/scripts/`.
+ *
+ * Environment variables:
+ * - CLIENT_ID
+ * - CLIENT_SECRET
+ * - INSTANCE_URL (host portion, e.g. example-instance)
+ * - SUBSCRIPTION_ID
+ * - SINCE_DATE (optional) - YYYY-MM-DD to fetch a full day's events
+ * - ONLY_DATA (optional) - when "true", skip saving CSV in downloader
+ *
+ compile + run:
+ *   tsc && node dist/events/scripts/fetch-events-example.js
+ */
+export {};

package/dist/events/scripts/fetch-events-example.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Example script to fetch events using the `src/events` helpers.
+ *
+ * This copy lives under `src/` so `tsc` will emit it into `dist/scripts/`.
+ *
+ * Environment variables:
+ * - CLIENT_ID
+ * - CLIENT_SECRET
+ * - INSTANCE_URL (host portion, e.g. example-instance)
+ * - SUBSCRIPTION_ID
+ * - SINCE_DATE (optional) - YYYY-MM-DD to fetch a full day's events
+ * - ONLY_DATA (optional) - when "true", skip saving CSV in downloader
+ *
+ compile + run:
+ *   tsc && node dist/events/scripts/fetch-events-example.js
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const __1 = require("..");
+const clientId = process.env.CLIENT_ID;
+const clientSecret = process.env.CLIENT_SECRET;
+const instanceUrl = process.env.INSTANCE_URL;
+const subscriptionId = process.env.SUBSCRIPTION_ID;
+if (!clientId || !clientSecret || !instanceUrl || !subscriptionId) {
+    console.error("Missing required env vars: CLIENT_ID, CLIENT_SECRET, INSTANCE_URL, SUBSCRIPTION_ID");
+    process.exit(1);
+}
+(async () => {
+    try {
+        if (process.env.SINCE_DATE) {
+            const sinceDate = process.env.SINCE_DATE;
+            const onlyData = process.env.ONLY_DATA === "true";
+            console.log(`Fetching events for day ${sinceDate}...`);
+            const events = await (0, __1.downloadAllEventsOfDayCSV)(clientId, clientSecret, instanceUrl, subscriptionId, sinceDate, onlyData);
+            console.log(`Fetched ${events.length} events for ${sinceDate}`);
+            if (events.length > 0)
+                console.log("Sample:", events[0]);
+        }
+        else {
+            console.log("Fetching events from last ~180 seconds...");
+            const recent = await (0, __1.downloadAllEventsOfDLastTwoMinutes)(clientId, clientSecret, instanceUrl, subscriptionId);
+            console.log(`Fetched ${recent.length} recent events`);
+            if (recent.length > 0)
+                console.log("Sample:", recent[0]);
+        }
+    }
+    catch (err) {
+        console.error("Error fetching events:", err);
+        process.exit(2);
+    }
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofsc-utility",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "A wrapper for Oracle Field Service REST API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,10 +45,11 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "dotenv": "^17.4.2",
     "node-fetch": "^2.7.0",
     "tslib": "^2.8.1",
     "xlsx": "^0.18.5",
     "xlsx-js-style": "^1.2.0",
     "xmldom": "^0.6.0"
   }
-}
+}