vet-data-utils-ts 0.5.9 → 0.5.13

package/README.md

@@ -41,6 +41,25 @@ Current surfaces cover the canonical animal-card DID, veterinary summary
 sections, animal-only emergency data, pseudonymous DigitalTwin search input and
 veterinary assistant intents.
 
+## Veterinary scheduling
+
+`vet-data-utils-ts/scheduling` owns claims-first builders for FHIR R5
+`Location`, `Schedule`, `Slot`, `Appointment` and `AppointmentResponse`.
+`expandVeterinaryAvailability(...)` expands bounded weekly periods into Slots
+and applies weekly or monthly-ordinal exceptions that restrict or extend one or
+more consultation Locations. It converts clinic-local times through an IANA
+time zone, including daylight-saving changes.
+
+The official searchable facts remain resource-qualified flat claims. The
+exported `VeterinarySlotSearchParameters` catalogue identifies the supported
+FHIR R5 Slot query codes; generated resources include `Slot.identifier`,
+`Slot.schedule`, `Slot.status`, `Slot.start`, `Appointment.status`,
+`Appointment.start`, `Appointment.slot` and `Appointment.actor`. Product-only
+facts use the explicit `VeterinaryLocation`, `VeterinarySlot` or
+`VeterinaryAppointment` prefix; a Location photo and the seven-day
+confirmation due time are not presented as official FHIR SearchParameters.
+All builders return only `resourceType`, `id` and `meta.claims`.
+
 FHIR R5 ResearchStudy screens consume the exact 25 resource-specific search
 parameters and the separate associated-party projection from
 `vet-data-utils-ts/research-study`. GW persistence receives only

package/dist/index.d.ts

@@ -16,3 +16,4 @@ export * from './research-study.js';
 export * from './sectors.js';
 export * from './shc.js';
 export * from './veterinary-sections.js';
+export * from './scheduling.js';

package/dist/index.js

@@ -16,3 +16,4 @@ export * from './research-study.js';
 export * from './sectors.js';
 export * from './shc.js';
 export * from './veterinary-sections.js';
+export * from './scheduling.js';

package/dist/organization-application.d.ts

@@ -23,6 +23,7 @@ export type ReusableOrganizationApplication = Readonly<{
     regionalId: boolean;
     subdivisionCode?: string;
     officialLicense?: string;
+    officialPhone?: string;
     legalRepresentative: Readonly<{
         name: string;
         email: string;
@@ -49,3 +50,5 @@ export declare function organizationServiceTypeForParticipationRoles(roles: read
  * object and remain inside the BFF/high-level Node runtime.
  */
 export declare function parseReusableOrganizationApplication(input: unknown): ReusableOrganizationApplication;
+/** Normalizes an optional official organization telephone to E.164 using the selected jurisdiction calling code. */
+export declare function normalizeOptionalOrganizationOfficialPhone(value: unknown, defaultCallingCode: unknown): string | undefined;

package/dist/organization-application.js

@@ -91,6 +91,7 @@ export function parseReusableOrganizationApplication(input) {
         regionalId,
         ...(subdivisionCode ? { subdivisionCode } : {}),
         ...(optional(value.officialLicense) ? { officialLicense: optional(value.officialLicense) } : {}),
+        ...(optional(value.officialPhone) ? { officialPhone: normalizeOptionalOrganizationOfficialPhone(value.officialPhone, value.defaultPhoneCallingCode) } : {}),
         legalRepresentative: Object.freeze({
             name: required(legalRepresentative.name, 'organization_legal_representative_name_required'),
             email: legalEmail,
@@ -99,6 +100,24 @@ export function parseReusableOrganizationApplication(input) {
         participationRoles: Object.freeze([...new Set(selectedRoles)]),
     });
 }
+/** Normalizes an optional official organization telephone to E.164 using the selected jurisdiction calling code. */
+export function normalizeOptionalOrganizationOfficialPhone(value, defaultCallingCode) {
+    const raw = optional(value);
+    if (!raw)
+        return undefined;
+    let compact = raw.replace(/^tel:/i, '').replace(/[\s().-]/g, '');
+    if (compact.startsWith('00'))
+        compact = `+${compact.slice(2)}`;
+    if (!compact.startsWith('+')) {
+        const callingCode = String(defaultCallingCode ?? '').trim().replace(/^00/, '+');
+        if (!/^\+[1-9]\d{0,2}$/.test(callingCode))
+            throw new TypeError('organization_official_phone_calling_code_required');
+        compact = `${callingCode}${compact.replace(/^0/, '')}`;
+    }
+    if (!/^\+[1-9]\d{7,14}$/.test(compact))
+        throw new TypeError('organization_official_phone_invalid');
+    return compact;
+}
 function record(value, error) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new TypeError(error);

package/dist/scheduling.d.ts

@@ -0,0 +1,154 @@
+/** FHIR R5 Slot statuses accepted by veterinary scheduling. */
+export declare const SlotStatuses: Readonly<{
+    readonly Busy: "busy";
+    readonly Free: "free";
+    readonly BusyUnavailable: "busy-unavailable";
+    readonly BusyTentative: "busy-tentative";
+    readonly EnteredInError: "entered-in-error";
+}>;
+/** FHIR R5 AppointmentResponse participant statuses. */
+export declare const AppointmentResponseStatuses: Readonly<{
+    readonly Accepted: "accepted";
+    readonly Declined: "declined";
+    readonly Tentative: "tentative";
+    readonly NeedsAction: "needs-action";
+    readonly EnteredInError: "entered-in-error";
+}>;
+/** FHIR R5 Appointment statuses used by the import and booking flow. */
+export declare const AppointmentStatuses: Readonly<{
+    readonly Proposed: "proposed";
+    readonly Pending: "pending";
+    readonly Booked: "booked";
+    readonly Arrived: "arrived";
+    readonly Fulfilled: "fulfilled";
+    readonly Cancelled: "cancelled";
+    readonly NoShow: "noshow";
+    readonly EnteredInError: "entered-in-error";
+    readonly CheckedIn: "checked-in";
+    readonly Waitlist: "waitlist";
+}>;
+/** Official FHIR R5 Slot resource-specific SearchParameter codes supported by flat claims. */
+export declare const VeterinarySlotSearchParameters: readonly ["identifier", "schedule", "service-category", "service-type", "specialty", "start", "status"];
+/** Governed operational flat claims accepted by GW VET scheduling managers. */
+export declare const VeterinarySchedulingFlatClaimCatalog: Readonly<{
+    readonly Location: readonly string[];
+    readonly Schedule: readonly string[];
+    readonly Slot: readonly string[];
+    readonly Appointment: readonly string[];
+    readonly AppointmentResponse: readonly string[];
+}>;
+export type VeterinarySchedulingResourceType = keyof typeof VeterinarySchedulingFlatClaimCatalog;
+export type VeterinarySchedulingFlatClaimsResource = Readonly<{
+    resourceType: VeterinarySchedulingResourceType;
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, readonly string[]>>;
+    }>;
+}>;
+/** Validates the claims-only wire shape and normalizes scalar builder values to indexed strings. */
+export declare function normalizeVeterinarySchedulingFlatClaimsResource(input: unknown): VeterinarySchedulingFlatClaimsResource;
+export type ClaimsFirstResource = Readonly<{
+    resourceType: string;
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, unknown>>;
+    }>;
+}>;
+/** Builds the claims-first veterinary projection of one physical FHIR R5 Location. */
+export declare function buildVeterinaryLocationResource(input: Readonly<{
+    id: string;
+    organizationReference: string;
+    name: string;
+    description?: string;
+    latitude: number;
+    longitude: number;
+    altitude?: number;
+    characteristicCodes?: readonly string[];
+    photoUrl?: string;
+}>): ClaimsFirstResource;
+/** Builds the claims-first FHIR R5 Schedule joining one practitioner and consultation Location. */
+export declare function buildVeterinaryScheduleResource(input: Readonly<{
+    id: string;
+    name: string;
+    practitionerReference: string;
+    locationReference: string;
+    planningHorizonStart: string;
+    planningHorizonEnd: string;
+}>): ClaimsFirstResource;
+export type VeterinaryAvailabilityPeriod = Readonly<{
+    daysOfWeek: readonly number[];
+    startTime: string;
+    endTime: string;
+    locationReferences: readonly string[];
+}>;
+export type VeterinaryAvailabilityException = Readonly<{
+    effect: 'restrict' | 'expand';
+    recurrence: Readonly<{
+        frequency: 'weekly' | 'monthly';
+        dayOfWeek: number;
+        ordinal?: number;
+    }>;
+    startTime: string;
+    endTime: string;
+    locationReferences: readonly string[];
+}>;
+export type ExpandedVeterinarySlot = Readonly<{
+    localDate: string;
+    localStart: string;
+    localEnd: string;
+    locationReference: string;
+    resource: ClaimsFirstResource;
+}>;
+/** Expands bounded weekly availability into claims-first Slots, applying recurring restrictions or expansions. */
+export declare function expandVeterinaryAvailability(input: Readonly<{
+    scheduleId: string;
+    startDate: string;
+    endDate: string;
+    timeZone: string;
+    slotMinutes: number;
+    periods: readonly VeterinaryAvailabilityPeriod[];
+    exceptions: readonly VeterinaryAvailabilityException[];
+}>): readonly ExpandedVeterinarySlot[];
+/** Builds a claims-first response that confirms, declines or proposes a new appointment time. */
+export declare function buildVeterinaryAppointmentResponseResource(input: Readonly<{
+    id: string;
+    appointmentReference: string;
+    actorReference: string;
+    participantStatus: string;
+    respondedAt?: string;
+    proposedNewTime?: boolean;
+    start?: string;
+    end?: string;
+    notificationRecipientReference?: string;
+    notificationRecipientEmail?: string;
+}>): ClaimsFirstResource;
+/** Builds the FHIR-like Communication that an adapter may render as the additional English clinic email. */
+export declare function buildVeterinaryAppointmentResponseNotificationResource(input: Readonly<{
+    id: string;
+    responseReference: string;
+    appointmentReference: string;
+    senderReference: string;
+    recipientReference: string;
+    participantStatus: string;
+    sentAt: string;
+    language: string;
+}>): ClaimsFirstResource;
+/** Builds a searchable claims-first FHIR R5 Appointment with a seven-day confirmation due time. */
+export declare function buildVeterinaryAppointmentResource(input: Readonly<{
+    id: string;
+    status: string;
+    start: string;
+    end: string;
+    slotReferences: readonly string[];
+    actorReferences: readonly string[];
+    locationReference?: string;
+    confirmationDueAt?: string;
+    userSelected?: boolean;
+}>): ClaimsFirstResource;
+/** Builds the durable web inbox notification when a schedule change displaces an appointment. */
+export declare function buildVeterinaryAppointmentNotificationResource(input: Readonly<{
+    id: string;
+    appointmentReference: string;
+    subjectReference: string;
+    reason: string;
+}>): ClaimsFirstResource;

package/dist/scheduling.js

@@ -0,0 +1,252 @@
+/** FHIR R5 Slot statuses accepted by veterinary scheduling. */
+export const SlotStatuses = Object.freeze({ Busy: 'busy', Free: 'free', BusyUnavailable: 'busy-unavailable', BusyTentative: 'busy-tentative', EnteredInError: 'entered-in-error' });
+/** FHIR R5 AppointmentResponse participant statuses. */
+export const AppointmentResponseStatuses = Object.freeze({ Accepted: 'accepted', Declined: 'declined', Tentative: 'tentative', NeedsAction: 'needs-action', EnteredInError: 'entered-in-error' });
+/** FHIR R5 Appointment statuses used by the import and booking flow. */
+export const AppointmentStatuses = Object.freeze({
+    Proposed: 'proposed', Pending: 'pending', Booked: 'booked', Arrived: 'arrived', Fulfilled: 'fulfilled',
+    Cancelled: 'cancelled', NoShow: 'noshow', EnteredInError: 'entered-in-error', CheckedIn: 'checked-in', Waitlist: 'waitlist',
+});
+/** Official FHIR R5 Slot resource-specific SearchParameter codes supported by flat claims. */
+export const VeterinarySlotSearchParameters = Object.freeze(['identifier', 'schedule', 'service-category', 'service-type', 'specialty', 'start', 'status']);
+/** Governed operational flat claims accepted by GW VET scheduling managers. */
+export const VeterinarySchedulingFlatClaimCatalog = Object.freeze({
+    Location: Object.freeze(['Location.identifier', 'Location.status', 'Location.mode', 'Location.name', 'Location.description', 'Location.position.latitude', 'Location.position.longitude', 'Location.position.altitude', 'Location.managingOrganization', 'Location.characteristic', 'VeterinaryLocation.photoUrl']),
+    Schedule: Object.freeze(['Schedule.identifier', 'Schedule.active', 'Schedule.name', 'Schedule.actor', 'Schedule.planningHorizon.start', 'Schedule.planningHorizon.end']),
+    Slot: Object.freeze(['Slot.identifier', 'Slot.schedule', 'Slot.status', 'Slot.start', 'Slot.end', 'Slot.service-category', 'Slot.service-type', 'Slot.specialty', 'VeterinarySlot.location', 'VeterinarySlot.timeZone']),
+    Appointment: Object.freeze(['Appointment.identifier', 'Appointment.status', 'Appointment.description', 'Appointment.note', 'Appointment.start', 'Appointment.end', 'Appointment.slot', 'Appointment.actor', 'Appointment.location', 'Appointment.user-selected', 'VeterinaryAppointment.confirmationDueAt', 'VeterinaryAppointment.reschedulingReason']),
+    AppointmentResponse: Object.freeze(['AppointmentResponse.identifier', 'AppointmentResponse.appointment', 'AppointmentResponse.actor', 'AppointmentResponse.participantStatus', 'AppointmentResponse.proposedNewTime', 'AppointmentResponse.start', 'AppointmentResponse.end', 'VeterinaryAppointmentResponse.respondedAt', 'VeterinaryAppointmentResponse.recipient', 'VeterinaryAppointmentResponse.recipientEmail']),
+});
+/** Validates the claims-only wire shape and normalizes scalar builder values to indexed strings. */
+export function normalizeVeterinarySchedulingFlatClaimsResource(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new TypeError('veterinary_scheduling_flat_resource_invalid');
+    const value = input;
+    if (typeof value.resourceType !== 'string' || !(value.resourceType in VeterinarySchedulingFlatClaimCatalog) || Object.keys(value).some(key => !['resourceType', 'id', 'meta'].includes(key)))
+        throw new TypeError('veterinary_scheduling_flat_resource_invalid');
+    const id = required(String(value.id || ''), 'veterinary_scheduling_flat_resource_invalid');
+    if (!/^[A-Za-z0-9\-.]{1,64}$/.test(id))
+        throw new TypeError('veterinary_scheduling_flat_resource_invalid');
+    const meta = value.meta;
+    if (!meta || typeof meta !== 'object' || !meta.claims || typeof meta.claims !== 'object' || Array.isArray(meta.claims) || Object.keys(meta).some(key => key !== 'claims'))
+        throw new TypeError('veterinary_scheduling_flat_resource_invalid');
+    const allowed = new Set(VeterinarySchedulingFlatClaimCatalog[value.resourceType]);
+    const claims = {};
+    for (const [name, raw] of Object.entries(meta.claims)) {
+        if (!allowed.has(name))
+            throw new TypeError('veterinary_scheduling_flat_claim_invalid');
+        const values = (Array.isArray(raw) ? raw : [raw]).map(item => String(item).trim());
+        if (!values.length || values.some(item => !item))
+            throw new TypeError('veterinary_scheduling_flat_claim_invalid');
+        claims[name] = Object.freeze([...new Set(values)]);
+    }
+    return Object.freeze({ resourceType: value.resourceType, id, meta: Object.freeze({ claims: Object.freeze(claims) }) });
+}
+const required = (value, code) => { const normalized = value.trim(); if (!normalized)
+    throw new Error(code); return normalized; };
+const datePattern = /^\d{4}-\d{2}-\d{2}$/;
+const timePattern = /^(?:[01]\d|2[0-3]):[0-5]\d$/;
+const assertDate = (value) => { if (!datePattern.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`)))
+    throw new Error('date_invalid'); return value; };
+const assertTime = (value) => { if (!timePattern.test(value))
+    throw new Error('time_invalid'); return value; };
+const claimsResource = (resourceType, id, claims) => Object.freeze({ resourceType, id: required(id, 'resource_id_required'), meta: Object.freeze({ claims: Object.freeze(claims) }) });
+/** Builds the claims-first veterinary projection of one physical FHIR R5 Location. */
+export function buildVeterinaryLocationResource(input) {
+    if (!Number.isFinite(input.latitude) || input.latitude < -90 || input.latitude > 90)
+        throw new Error('location_latitude_invalid');
+    if (!Number.isFinite(input.longitude) || input.longitude < -180 || input.longitude > 180)
+        throw new Error('location_longitude_invalid');
+    if (input.photoUrl) {
+        const parsed = new URL(input.photoUrl);
+        if (parsed.protocol !== 'https:')
+            throw new Error('location_photo_url_invalid');
+    }
+    return claimsResource('Location', input.id, {
+        'Location.status': 'active', 'Location.mode': 'instance', 'Location.name': required(input.name, 'location_name_required'),
+        ...(input.description ? { 'Location.description': input.description.trim() } : {}),
+        'Location.position.latitude': input.latitude, 'Location.position.longitude': input.longitude,
+        ...(input.altitude === undefined ? {} : { 'Location.position.altitude': input.altitude }),
+        'Location.managingOrganization': required(input.organizationReference, 'location_organization_required'),
+        ...(input.characteristicCodes?.length ? { 'Location.characteristic': Object.freeze([...input.characteristicCodes]) } : {}),
+        ...(input.photoUrl ? { 'VeterinaryLocation.photoUrl': input.photoUrl } : {}),
+    });
+}
+/** Builds the claims-first FHIR R5 Schedule joining one practitioner and consultation Location. */
+export function buildVeterinaryScheduleResource(input) {
+    const start = assertDate(input.planningHorizonStart);
+    const end = assertDate(input.planningHorizonEnd);
+    if (start > end)
+        throw new Error('schedule_horizon_invalid');
+    return claimsResource('Schedule', input.id, {
+        'Schedule.active': true, 'Schedule.name': required(input.name, 'schedule_name_required'),
+        'Schedule.actor': Object.freeze([required(input.practitionerReference, 'schedule_practitioner_required'), required(input.locationReference, 'schedule_location_required')]),
+        'Schedule.planningHorizon.start': start, 'Schedule.planningHorizon.end': end,
+    });
+}
+const minutes = (value) => { const [hour, minute] = assertTime(value).split(':').map(Number); return hour * 60 + minute; };
+const timeFromMinutes = (value) => `${String(Math.floor(value / 60)).padStart(2, '0')}:${String(value % 60).padStart(2, '0')}`;
+const dates = (start, end) => { const result = []; const cursor = new Date(`${start}T00:00:00Z`); const last = new Date(`${end}T00:00:00Z`); while (cursor <= last) {
+    result.push(cursor.toISOString().slice(0, 10));
+    cursor.setUTCDate(cursor.getUTCDate() + 1);
+} ; return result; };
+const dateParts = (date) => date.split('-').map(Number);
+const zonedInstant = (date, time, timeZone) => {
+    const [year, month, day] = dateParts(date);
+    const [hour, minute] = time.split(':').map(Number);
+    const desired = Date.UTC(year, month - 1, day, hour, minute);
+    let candidate = desired;
+    const formatter = new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const parts = Object.fromEntries(formatter.formatToParts(new Date(candidate)).map(part => [part.type, part.value]));
+        const observed = Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour), Number(parts.minute));
+        candidate += desired - observed;
+    }
+    return new Date(candidate).toISOString();
+};
+const matchesExceptionDate = (date, recurrence) => { const [, , day] = dateParts(date); const weekday = new Date(`${date}T00:00:00Z`).getUTCDay(); if (weekday !== recurrence.dayOfWeek)
+    return false; return recurrence.frequency === 'weekly' || Math.ceil(day / 7) === recurrence.ordinal; };
+const validateRange = (startTime, endTime, code) => { const start = minutes(startTime); const end = minutes(endTime); if (start >= end)
+    throw new Error(code); return [start, end]; };
+const slotKey = (location, date, start, end) => `${location}|${date}|${start}|${end}`;
+/** Expands bounded weekly availability into claims-first Slots, applying recurring restrictions or expansions. */
+export function expandVeterinaryAvailability(input) {
+    const startDate = assertDate(input.startDate);
+    const endDate = assertDate(input.endDate);
+    if (startDate > endDate)
+        throw new Error('availability_horizon_invalid');
+    if (!Number.isInteger(input.slotMinutes) || input.slotMinutes < 5 || input.slotMinutes > 1440)
+        throw new Error('slot_duration_invalid');
+    try {
+        new Intl.DateTimeFormat('en', { timeZone: input.timeZone }).format();
+    }
+    catch {
+        throw new Error('time_zone_invalid');
+    }
+    const base = new Map();
+    const allDates = dates(startDate, endDate);
+    for (const period of input.periods) {
+        const [start, end] = validateRange(period.startTime, period.endTime, 'availability_period_invalid');
+        if (!period.daysOfWeek.length || period.daysOfWeek.some(day => !Number.isInteger(day) || day < 0 || day > 6))
+            throw new Error('availability_days_invalid');
+        if (!period.locationReferences.length)
+            throw new Error('availability_location_required');
+        for (const date of allDates) {
+            if (!period.daysOfWeek.includes(new Date(`${date}T00:00:00Z`).getUTCDay()))
+                continue;
+            for (const locationReference of period.locationReferences)
+                for (let cursor = start; cursor + input.slotMinutes <= end; cursor += input.slotMinutes) {
+                    const localStart = timeFromMinutes(cursor);
+                    const localEnd = timeFromMinutes(cursor + input.slotMinutes);
+                    base.set(slotKey(locationReference, date, localStart, localEnd), { localDate: date, localStart, localEnd, locationReference });
+                }
+        }
+    }
+    for (const exception of input.exceptions) {
+        const [start, end] = validateRange(exception.startTime, exception.endTime, 'availability_exception_invalid');
+        if (exception.recurrence.dayOfWeek < 0 || exception.recurrence.dayOfWeek > 6 || (exception.recurrence.frequency === 'monthly' && (!Number.isInteger(exception.recurrence.ordinal) || exception.recurrence.ordinal < 1 || exception.recurrence.ordinal > 5)))
+            throw new Error('availability_exception_recurrence_invalid');
+        for (const date of allDates) {
+            if (!matchesExceptionDate(date, exception.recurrence))
+                continue;
+            for (const locationReference of exception.locationReferences)
+                for (let cursor = start; cursor + input.slotMinutes <= end; cursor += input.slotMinutes) {
+                    const localStart = timeFromMinutes(cursor);
+                    const localEnd = timeFromMinutes(cursor + input.slotMinutes);
+                    const key = slotKey(locationReference, date, localStart, localEnd);
+                    if (exception.effect === 'restrict')
+                        base.delete(key);
+                    else
+                        base.set(key, { localDate: date, localStart, localEnd, locationReference });
+                }
+        }
+    }
+    const scheduleReference = `Schedule/${required(input.scheduleId, 'schedule_id_required')}`;
+    return Object.freeze([...base.values()].sort((left, right) => slotKey(left.locationReference, left.localDate, left.localStart, left.localEnd).localeCompare(slotKey(right.locationReference, right.localDate, right.localStart, right.localEnd))).map(slot => {
+        const start = zonedInstant(slot.localDate, slot.localStart, input.timeZone);
+        const end = zonedInstant(slot.localDate, slot.localEnd, input.timeZone);
+        const id = `${input.scheduleId}-${slot.localDate}-${slot.localStart.replace(':', '')}-${slot.locationReference.split('/').at(-1)}`;
+        return Object.freeze({ ...slot, resource: claimsResource('Slot', id, { 'Slot.identifier': id, 'Slot.schedule': scheduleReference, 'Slot.status': SlotStatuses.Free, 'Slot.start': start, 'Slot.end': end, 'VeterinarySlot.location': slot.locationReference, 'VeterinarySlot.timeZone': input.timeZone }) });
+    }));
+}
+/** Builds a claims-first response that confirms, declines or proposes a new appointment time. */
+export function buildVeterinaryAppointmentResponseResource(input) {
+    if (!Object.values(AppointmentResponseStatuses).includes(input.participantStatus))
+        throw new Error('appointment_response_status_invalid');
+    if ((input.start && !input.end) || (!input.start && input.end))
+        throw new Error('appointment_response_time_incomplete');
+    if (input.start && input.end && Date.parse(input.start) >= Date.parse(input.end))
+        throw new Error('appointment_response_time_invalid');
+    const respondedAt = input.respondedAt || new Date().toISOString();
+    if (!Number.isFinite(Date.parse(respondedAt)))
+        throw new Error('appointment_response_responded_at_invalid');
+    const hasRecipientReference = Boolean(input.notificationRecipientReference?.trim());
+    const hasRecipientEmail = Boolean(input.notificationRecipientEmail?.trim());
+    if (hasRecipientReference !== hasRecipientEmail)
+        throw new Error('appointment_response_notification_recipient_incomplete');
+    if (hasRecipientEmail && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(input.notificationRecipientEmail.trim()))
+        throw new Error('appointment_response_notification_email_invalid');
+    return claimsResource('AppointmentResponse', input.id, { 'AppointmentResponse.appointment': required(input.appointmentReference, 'appointment_reference_required'), 'AppointmentResponse.actor': required(input.actorReference, 'appointment_response_actor_required'), 'AppointmentResponse.participantStatus': input.participantStatus, 'VeterinaryAppointmentResponse.respondedAt': new Date(respondedAt).toISOString(), ...(hasRecipientReference ? { 'VeterinaryAppointmentResponse.recipient': input.notificationRecipientReference.trim(), 'VeterinaryAppointmentResponse.recipientEmail': input.notificationRecipientEmail.trim().toLowerCase() } : {}), ...(input.proposedNewTime === undefined ? {} : { 'AppointmentResponse.proposedNewTime': input.proposedNewTime }), ...(input.start ? { 'AppointmentResponse.start': input.start, 'AppointmentResponse.end': input.end } : {}) });
+}
+/** Builds the FHIR-like Communication that an adapter may render as the additional English clinic email. */
+export function buildVeterinaryAppointmentResponseNotificationResource(input) {
+    if (input.language !== 'en')
+        throw new Error('appointment_response_notification_language_unsupported');
+    if (!Object.values(AppointmentResponseStatuses).includes(input.participantStatus))
+        throw new Error('appointment_response_status_invalid');
+    if (!Number.isFinite(Date.parse(input.sentAt)))
+        throw new Error('appointment_response_notification_sent_at_invalid');
+    const statusText = Object.freeze({ accepted: 'accepted', declined: 'declined', tentative: 'tentatively changed', 'needs-action': 'left awaiting action', 'entered-in-error': 'marked as entered in error' });
+    return claimsResource('Communication', input.id, {
+        'Communication.identifier': input.id,
+        'Communication.status': 'completed',
+        'Communication.category': 'http://terminology.hl7.org/CodeSystem/communication-category|notification',
+        'Communication.recipient': required(input.recipientReference, 'appointment_response_notification_recipient_required'),
+        'Communication.sender': required(input.senderReference, 'appointment_response_notification_sender_required'),
+        'Communication.sent': new Date(input.sentAt).toISOString(),
+        'Communication.topic': 'https://vetchain.app/fhir/CodeSystem/communication-topic|appointment-response',
+        'Communication.content-reference': Object.freeze([required(input.responseReference, 'appointment_response_reference_required'), required(input.appointmentReference, 'appointment_reference_required')]),
+        'Communication.text': `The appointment was ${statusText[input.participantStatus]}.`,
+    });
+}
+/** Builds a searchable claims-first FHIR R5 Appointment with a seven-day confirmation due time. */
+export function buildVeterinaryAppointmentResource(input) {
+    if (!Object.values(AppointmentStatuses).includes(input.status))
+        throw new Error('appointment_status_invalid');
+    const start = Date.parse(input.start);
+    const end = Date.parse(input.end);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start >= end)
+        throw new Error('appointment_time_invalid');
+    const userSelected = input.userSelected ?? false;
+    if (!input.slotReferences.length && !userSelected)
+        throw new Error('appointment_slot_required');
+    if (!input.actorReferences.length)
+        throw new Error('appointment_actor_required');
+    const confirmationDueAt = input.confirmationDueAt || new Date(start - 7 * 24 * 60 * 60 * 1000).toISOString();
+    if (!Number.isFinite(Date.parse(confirmationDueAt)) || Date.parse(confirmationDueAt) >= start)
+        throw new Error('appointment_confirmation_due_invalid');
+    return claimsResource('Appointment', input.id, {
+        'Appointment.status': input.status,
+        'Appointment.start': new Date(start).toISOString(),
+        'Appointment.end': new Date(end).toISOString(),
+        ...(input.slotReferences.length ? { 'Appointment.slot': Object.freeze([...input.slotReferences]) } : {}),
+        'Appointment.actor': Object.freeze([...input.actorReferences]),
+        'Appointment.user-selected': userSelected,
+        ...(input.locationReference ? { 'Appointment.location': required(input.locationReference, 'appointment_location_required') } : {}),
+        'VeterinaryAppointment.confirmationDueAt': new Date(confirmationDueAt).toISOString(),
+    });
+}
+/** Builds the durable web inbox notification when a schedule change displaces an appointment. */
+export function buildVeterinaryAppointmentNotificationResource(input) {
+    const id = required(input.id, 'communication_id_required');
+    return claimsResource('Communication', id, {
+        'Communication.identifier': id,
+        'Communication.status': 'preparation',
+        'Communication.category': 'http://terminology.hl7.org/CodeSystem/communication-category|notification',
+        'Communication.subject': required(input.subjectReference, 'communication_subject_required'),
+        'Communication.content-reference': required(input.appointmentReference, 'communication_appointment_required'),
+        'Communication.topic': 'https://vetchain.app/fhir/CodeSystem/communication-topic|appointment-rescheduling-required',
+        'Communication.text': required(input.reason, 'communication_reason_required'),
+        'Communication.content-code': 'https://vetchain.app/fhir/CodeSystem/appointment-action|reschedule',
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.9",
+  "version": "0.5.13",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -83,6 +83,10 @@
     "./assistant": {
       "types": "./dist/assistant.d.ts",
       "default": "./dist/assistant.js"
+    },
+    "./scheduling": {
+      "types": "./dist/scheduling.d.ts",
+      "default": "./dist/scheduling.js"
     }
   },
   "files": [