@rinse-dental/open-dental 4.0.2 → 4.1.0

package/README.md

@@ -298,6 +298,36 @@ await benefits.deleteBenefit(benefitNum);
 
 ---
 
+## Date Utilities
+
+Open Dental returns dates and datetimes **without timezone information** — they reflect the local clock of the Open Dental server. Use `toISO` to convert these to ISO 8601 UTC strings before storing or comparing them in your application.
+
+```ts
+import { toISO } from '@rinse-dental/open-dental';
+
+// Datetime string — "yyyy-MM-dd HH:mm:ss"
+toISO("2021-08-05 02:00:00", "America/Los_Angeles");
+// => "2021-08-05T09:00:00.000Z"  (PDT, UTC-7)
+
+// Date-only string — interpreted as midnight in the given timezone
+toISO("2021-08-05", "America/Los_Angeles");
+// => "2021-08-05T07:00:00.000Z"  (PDT, UTC-7)
+```
+
+Pass an [IANA timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) matching your Open Dental server's configured timezone. DST transitions are handled automatically. Strings that don't match either format are returned unchanged.
+
+**Typical usage after an API call:**
+
+```ts
+const appt = await OpenDental.Appointments().getAppointment(12345);
+const TZ = "America/Los_Angeles";
+
+const startISO = toISO(appt.AptDateTime, TZ);
+const endISO   = toISO(appt.AptDateTimeEnd, TZ);
+```
+
+---
+
 ## API Documentation (`Docs/`)
 
 This package includes the full Open Dental API reference documentation in the `Docs/` folder, enriched with database schema mappings and field-level notes for every endpoint. These markdown files are optimized for AI-assisted development.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { OpenDental } from "./openDental";
 export * as Transformers from './transformers';
+export { toISO } from "./utils/dateUtils";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -33,7 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Transformers = exports.OpenDental = void 0;
+exports.toISO = exports.Transformers = exports.OpenDental = void 0;
 var openDental_1 = require("./openDental");
 Object.defineProperty(exports, "OpenDental", { enumerable: true, get: function () { return openDental_1.OpenDental; } });
 exports.Transformers = __importStar(require("./transformers"));
+var dateUtils_1 = require("./utils/dateUtils");
+Object.defineProperty(exports, "toISO", { enumerable: true, get: function () { return dateUtils_1.toISO; } });

package/dist/utils/dateUtils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Converts an Open Dental date or datetime string to an ISO 8601 UTC string,
+ * interpreting the input as being in the given IANA timezone.
+ *
+ * Open Dental returns dates without timezone information. The server stores
+ * times in its local timezone (configured at the practice level). Pass that
+ * timezone here so the conversion to UTC is correct, including DST transitions.
+ *
+ * @param {string} value - A date string in "yyyy-MM-dd" or "yyyy-MM-dd HH:mm:ss" format.
+ * @param {string} timezone - IANA timezone name (e.g. "America/Los_Angeles").
+ * @returns {string} ISO 8601 UTC string (e.g. "2021-08-05T09:00:00.000Z"),
+ *   or the original value unchanged if it does not match a recognised format.
+ *
+ * @example
+ * // Datetime (server in PST, offset -8 in winter / -7 in summer)
+ * toISO("2021-08-05 02:00:00", "America/Los_Angeles");
+ * // => "2021-08-05T09:00:00.000Z"  (PDT, UTC-7)
+ *
+ * @example
+ * // Date-only — interpreted as midnight in the given timezone
+ * toISO("2021-08-05", "America/Los_Angeles");
+ * // => "2021-08-05T07:00:00.000Z"  (PDT, UTC-7)
+ */
+export declare function toISO(value: string, timezone: string): string;
+//# sourceMappingURL=dateUtils.d.ts.map

package/dist/utils/dateUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dateUtils.d.ts","sourceRoot":"","sources":["../../src/utils/dateUtils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU7D"}

package/dist/utils/dateUtils.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toISO = toISO;
+const moment_timezone_1 = __importDefault(require("moment-timezone"));
+/**
+ * Converts an Open Dental date or datetime string to an ISO 8601 UTC string,
+ * interpreting the input as being in the given IANA timezone.
+ *
+ * Open Dental returns dates without timezone information. The server stores
+ * times in its local timezone (configured at the practice level). Pass that
+ * timezone here so the conversion to UTC is correct, including DST transitions.
+ *
+ * @param {string} value - A date string in "yyyy-MM-dd" or "yyyy-MM-dd HH:mm:ss" format.
+ * @param {string} timezone - IANA timezone name (e.g. "America/Los_Angeles").
+ * @returns {string} ISO 8601 UTC string (e.g. "2021-08-05T09:00:00.000Z"),
+ *   or the original value unchanged if it does not match a recognised format.
+ *
+ * @example
+ * // Datetime (server in PST, offset -8 in winter / -7 in summer)
+ * toISO("2021-08-05 02:00:00", "America/Los_Angeles");
+ * // => "2021-08-05T09:00:00.000Z"  (PDT, UTC-7)
+ *
+ * @example
+ * // Date-only — interpreted as midnight in the given timezone
+ * toISO("2021-08-05", "America/Los_Angeles");
+ * // => "2021-08-05T07:00:00.000Z"  (PDT, UTC-7)
+ */
+function toISO(value, timezone) {
+    if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value)) {
+        return moment_timezone_1.default.tz(value, "YYYY-MM-DD HH:mm:ss", timezone).toISOString();
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return moment_timezone_1.default.tz(value, "YYYY-MM-DD", timezone).startOf("day").toISOString();
+    }
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rinse-dental/open-dental",
-    "version": "4.0.2",
+    "version": "4.1.0",
     "description": "A TypeScript library for easily accessing Open Dental APIs.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",