@wasto/sdk 1.0.3

package/src/opening-hours/format.ts

@@ -0,0 +1,99 @@
+import type { OpeningHours, OpeningHoursRule, TimeSlot, Weekday, WeeklyHoursRow } from './types';
+import { WEEKDAYS } from './types';
+import { WEEKDAY_LABELS_FR, WEEKDAY_LABELS_FR_SHORT } from './constants';
+import { convertUtcToLocal } from './convert';
+import { formatTimeDisplay, parseTimeMinutes } from './time';
+
+function formatSlots(slots: TimeSlot[]): string {
+  return slots
+    .map((s) => `${formatTimeDisplay(s.open)}–${formatTimeDisplay(s.close)}`)
+    .join(', ');
+}
+
+function compressDayRanges(days: Weekday[]): string[] {
+  if (days.length === 0) return [];
+  const order = new Map(WEEKDAYS.map((d, i) => [d, i]));
+  const sorted = [...days].sort((a, b) => (order.get(a) ?? 0) - (order.get(b) ?? 0));
+  const ranges: string[] = [];
+  let start = sorted[0];
+  let prev = sorted[0];
+  let prevIdx = order.get(prev) ?? 0;
+
+  const flush = (from: Weekday, to: Weekday) => {
+    if (from === to) {
+      ranges.push(WEEKDAY_LABELS_FR_SHORT[from]);
+    } else {
+      ranges.push(`${WEEKDAY_LABELS_FR_SHORT[from]}–${WEEKDAY_LABELS_FR_SHORT[to]}`);
+    }
+  };
+
+  for (let i = 1; i < sorted.length; i++) {
+    const day = sorted[i];
+    const idx = order.get(day) ?? 0;
+    if (idx === prevIdx + 1) {
+      prev = day;
+      prevIdx = idx;
+    } else {
+      flush(start, prev);
+      start = day;
+      prev = day;
+      prevIdx = idx;
+    }
+  }
+  flush(start, prev);
+  return ranges;
+}
+
+function formatRulesSummary(rules: OpeningHoursRule[]): string {
+  const parts: string[] = [];
+  for (const rule of rules) {
+    if (!rule.days.length || !rule.slots.length) continue;
+    const dayPart = compressDayRanges(rule.days).join(', ');
+    const slotPart = formatSlots(rule.slots);
+    parts.push(`${dayPart} ${slotPart}`);
+  }
+  return parts.join(' · ');
+}
+
+/** Formate un résumé court à partir d'horaires (UTC ou locaux selon le contenu passé). */
+export function formatOpeningHoursSummary(
+  hours: OpeningHours | { rules: OpeningHoursRule[] },
+  timeZone?: string,
+): string {
+  const rules =
+    'storage' in hours && hours.storage === 'utc' && timeZone
+      ? convertUtcToLocal(hours as OpeningHours, timeZone).rules
+      : hours.rules;
+  return formatRulesSummary(rules);
+}
+
+export function formatOpeningHoursWeekly(
+  hours: OpeningHours,
+  timeZone?: string,
+): WeeklyHoursRow[] {
+  const rules =
+    timeZone != null ? convertUtcToLocal(hours, timeZone).rules : hours.rules;
+
+  const byDay = new Map<Weekday, TimeSlot[]>();
+  for (const rule of rules) {
+    for (const day of rule.days) {
+      const existing = byDay.get(day) ?? [];
+      byDay.set(day, [...existing, ...rule.slots]);
+    }
+  }
+
+  return WEEKDAYS.map((day) => {
+    const slots = byDay.get(day) ?? [];
+    return {
+      day,
+      label: WEEKDAY_LABELS_FR[day],
+      closed: slots.length === 0,
+      slots,
+    };
+  });
+}
+
+export function formatWeeklyRow(row: WeeklyHoursRow): string {
+  if (row.closed) return 'Fermé';
+  return formatSlots(row.slots);
+}

package/src/opening-hours/index.ts

@@ -0,0 +1,9 @@
+export * from './types';
+export * from './constants';
+export * from './time';
+export * from './timezone';
+export * from './validate';
+export * from './convert';
+export * from './format';
+export * from './resolve';
+export * from './is-open-now';

package/src/opening-hours/is-open-now.ts

@@ -0,0 +1,38 @@
+import type { OpeningHours } from './types';
+import { parseTimeMinutes, weekdayFromUtcDate } from './time';
+import { utcDateIso } from './timezone';
+
+export function isOpenNow(
+  hours: OpeningHours,
+  at: Date = new Date(),
+): boolean {
+  const dateIso = utcDateIso(at);
+  const exceptions = hours.exceptions ?? [];
+  for (const exc of exceptions) {
+    if (exc.date !== dateIso) continue;
+    if (exc.closed) return false;
+    return isWithinSlots(exc.slots, at);
+  }
+
+  const weekday = weekdayFromUtcDate(at);
+  const rules = hours.rules.filter((r) => r.days.includes(weekday));
+  for (const rule of rules) {
+    if (isWithinSlots(rule.slots, at)) return true;
+  }
+  return false;
+}
+
+function isWithinSlots(slots: { open: string; close: string }[], at: Date): boolean {
+  const nowMin = at.getUTCHours() * 60 + at.getUTCMinutes();
+  for (const slot of slots) {
+    const open = parseTimeMinutes(slot.open);
+    const close = parseTimeMinutes(slot.close);
+    if (open == null || close == null) continue;
+    if (nowMin >= open && nowMin < close) return true;
+  }
+  return false;
+}
+
+export function openNowLabel(hours: OpeningHours, at?: Date): 'Ouvert' | 'Fermé' {
+  return isOpenNow(hours, at) ? 'Ouvert' : 'Fermé';
+}

package/src/opening-hours/resolve.ts

@@ -0,0 +1,71 @@
+import type { HoursInputMode, OpeningHours } from './types';
+import { convertUtcToLocal } from './convert';
+import { formatOpeningHoursSummary } from './format';
+import { getBrowserTimeZone } from './timezone';
+
+export type RecyclingPointHoursSource = {
+  hours?: string | null;
+  details?: Record<string, unknown> | null;
+};
+
+export function resolveHoursMode(
+  details?: Record<string, unknown> | null,
+): HoursInputMode {
+  if (!details) return 'text';
+  const mode = details.hoursMode;
+  if (mode === 'structured' || mode === 'text') return mode;
+  if (details.openingHours != null) return 'structured';
+  return 'text';
+}
+
+export function resolveOpeningHoursUtc(
+  point: RecyclingPointHoursSource,
+): OpeningHours | null {
+  const details = point.details;
+  if (!details || resolveHoursMode(details) !== 'structured') return null;
+  const raw = details.openingHours;
+  if (!raw || typeof raw !== 'object') return null;
+  return raw as OpeningHours;
+}
+
+export function resolveOpeningHoursLocal(
+  point: RecyclingPointHoursSource,
+  timeZone?: string,
+): { rules: OpeningHours['rules']; exceptions?: OpeningHours['exceptions'] } | null {
+  const utc = resolveOpeningHoursUtc(point);
+  if (!utc) return null;
+  const tz = timeZone ?? getBrowserTimeZone();
+  return convertUtcToLocal(utc, tz);
+}
+
+export function resolveHoursText(point: RecyclingPointHoursSource): string | null {
+  const details = point.details;
+  if (resolveHoursMode(details) === 'text') {
+    const fromDetails = details?.hours;
+    if (typeof fromDetails === 'string' && fromDetails.trim()) return fromDetails.trim();
+    if (typeof point.hours === 'string' && point.hours.trim()) return point.hours.trim();
+    return null;
+  }
+  return null;
+}
+
+/** Texte d'affichage des horaires (structuré converti ou texte libre). */
+export function resolveHoursDisplay(
+  point: RecyclingPointHoursSource,
+  timeZone?: string,
+): string | null {
+  const text = resolveHoursText(point);
+  if (text) return text;
+  const utc = resolveOpeningHoursUtc(point);
+  if (!utc) {
+    if (typeof point.hours === 'string' && point.hours.trim()) return point.hours.trim();
+    return null;
+  }
+  const tz = timeZone ?? getBrowserTimeZone();
+  const summary = formatOpeningHoursSummary(utc, tz);
+  return summary || null;
+}
+
+export function resolveHoursModeFromPoint(point: RecyclingPointHoursSource): HoursInputMode {
+  return resolveHoursMode(point.details ?? undefined);
+}

package/src/opening-hours/time.ts

@@ -0,0 +1,74 @@
+import { WEEKDAYS, type TimeSlot, type Weekday } from './types';
+import { WEEKDAY_INDEX, WEEKDAY_REF_DATES } from './constants';
+
+const TIME_RE = /^([01]\d|2[0-3]):([0-5]\d)$/;
+
+export function parseTimeMinutes(value: string): number | null {
+  const m = TIME_RE.exec(value.trim());
+  if (!m) return null;
+  return Number(m[1]) * 60 + Number(m[2]);
+}
+
+export function formatTimeMinutes(totalMinutes: number): string {
+  const normalized = ((totalMinutes % (24 * 60)) + 24 * 60) % (24 * 60);
+  const h = Math.floor(normalized / 60);
+  const min = normalized % 60;
+  return `${String(h).padStart(2, '0')}:${String(min).padStart(2, '0')}`;
+}
+
+export function formatTimeDisplay(value: string): string {
+  const minutes = parseTimeMinutes(value);
+  if (minutes == null) return value;
+  const h = Math.floor(minutes / 60);
+  const min = minutes % 60;
+  return min === 0 ? `${h}h` : `${h}h${String(min).padStart(2, '0')}`;
+}
+
+export function slotsOverlap(a: TimeSlot, b: TimeSlot): boolean {
+  const aOpen = parseTimeMinutes(a.open);
+  const aClose = parseTimeMinutes(a.close);
+  const bOpen = parseTimeMinutes(b.open);
+  const bClose = parseTimeMinutes(b.close);
+  if (aOpen == null || aClose == null || bOpen == null || bClose == null) return false;
+  if (aClose <= aOpen || bClose <= bOpen) return false;
+  return aOpen < bClose && bOpen < aClose;
+}
+
+export function sortSlots(slots: TimeSlot[]): TimeSlot[] {
+  return [...slots].sort(
+    (a, b) => (parseTimeMinutes(a.open) ?? 0) - (parseTimeMinutes(b.open) ?? 0),
+  );
+}
+
+export function nextWeekday(day: Weekday): Weekday {
+  const idx = (WEEKDAY_INDEX[day] + 1) % 7;
+  return WEEKDAYS[idx];
+}
+
+export function addDaysToIsoDate(isoDate: string, days: number): string {
+  const [y, mo, d] = isoDate.split('-').map(Number);
+  const dt = new Date(Date.UTC(y, mo - 1, d + days));
+  return dt.toISOString().slice(0, 10);
+}
+
+export function weekdayFromUtcDate(date: Date): Weekday {
+  const jsDay = date.getUTCDay();
+  const map: Weekday[] = [
+    'sunday',
+    'monday',
+    'tuesday',
+    'wednesday',
+    'thursday',
+    'friday',
+    'saturday',
+  ];
+  return map[jsDay];
+}
+
+export function utcHhmmFromDate(date: Date): string {
+  return formatTimeMinutes(date.getUTCHours() * 60 + date.getUTCMinutes());
+}
+
+export function refDateForWeekday(day: Weekday): string {
+  return WEEKDAY_REF_DATES[day];
+}

package/src/opening-hours/timezone.ts

@@ -0,0 +1,34 @@
+/** Offset du fuseau IANA en minutes (positif = en avance sur UTC) à un instant donné. */
+export function getTimezoneOffsetMinutes(timeZone: string, at: Date): number {
+  const utc = new Date(at.toLocaleString('en-US', { timeZone: 'UTC' }));
+  const zoned = new Date(at.toLocaleString('en-US', { timeZone }));
+  return (zoned.getTime() - utc.getTime()) / 60_000;
+}
+
+/** Convertit une date/heure locale (dans timeZone) en instant UTC. */
+export function localDateTimeToUtc(
+  dateIso: string,
+  time: string,
+  timeZone: string,
+): Date {
+  const [y, mo, d] = dateIso.split('-').map(Number);
+  const [h, mi] = time.split(':').map(Number);
+  let utcMs = Date.UTC(y, mo - 1, d, h, mi, 0);
+  for (let i = 0; i < 2; i++) {
+    const offset = getTimezoneOffsetMinutes(timeZone, new Date(utcMs));
+    utcMs = Date.UTC(y, mo - 1, d, h, mi, 0) - offset * 60_000;
+  }
+  return new Date(utcMs);
+}
+
+export function getBrowserTimeZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+  } catch {
+    return 'UTC';
+  }
+}
+
+export function utcDateIso(at: Date): string {
+  return at.toISOString().slice(0, 10);
+}

package/src/opening-hours/types.ts

@@ -0,0 +1,53 @@
+export const WEEKDAYS = [
+  'monday',
+  'tuesday',
+  'wednesday',
+  'thursday',
+  'friday',
+  'saturday',
+  'sunday',
+] as const;
+
+export type Weekday = (typeof WEEKDAYS)[number];
+
+export type TimeSlot = { open: string; close: string };
+
+export type OpeningHoursRule = { days: Weekday[]; slots: TimeSlot[] };
+
+export type OpeningHoursExceptionClosed = {
+  date: string;
+  closed: true;
+  label?: string;
+};
+
+export type OpeningHoursExceptionOpen = {
+  date: string;
+  closed: false;
+  slots: TimeSlot[];
+  label?: string;
+};
+
+export type OpeningHoursException =
+  | OpeningHoursExceptionClosed
+  | OpeningHoursExceptionOpen;
+
+/** Horaires structurés persistés en UTC+0 */
+export type OpeningHours = {
+  version: 1;
+  storage: 'utc';
+  rules: OpeningHoursRule[];
+  exceptions?: OpeningHoursException[];
+};
+
+export type HoursInputMode = 'structured' | 'text';
+
+export type WeeklyHoursRow = {
+  day: Weekday;
+  label: string;
+  closed: boolean;
+  slots: TimeSlot[];
+};
+
+export type OpeningHoursValidationResult =
+  | { ok: true; value: OpeningHours }
+  | { ok: false; errors: string[] };

package/src/opening-hours/validate.ts

@@ -0,0 +1,182 @@
+import {
+  WEEKDAYS,
+  type OpeningHours,
+  type OpeningHoursException,
+  type OpeningHoursRule,
+  type OpeningHoursValidationResult,
+  type TimeSlot,
+  type Weekday,
+} from './types';
+import { parseTimeMinutes, slotsOverlap, sortSlots } from './time';
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function validateTimeSlot(slot: unknown, path: string, errors: string[]): slot is TimeSlot {
+  if (!isPlainObject(slot)) {
+    errors.push(`${path} : créneau invalide`);
+    return false;
+  }
+  const open = slot.open;
+  const close = slot.close;
+  if (typeof open !== 'string' || parseTimeMinutes(open) == null) {
+    errors.push(`${path}.open : heure invalide (HH:mm)`);
+    return false;
+  }
+  if (typeof close !== 'string' || parseTimeMinutes(close) == null) {
+    errors.push(`${path}.close : heure invalide (HH:mm)`);
+    return false;
+  }
+  const openMin = parseTimeMinutes(open)!;
+  const closeMin = parseTimeMinutes(close)!;
+  if (closeMin <= openMin) {
+    errors.push(`${path} : l'heure de fermeture doit être après l'ouverture (UTC)`);
+    return false;
+  }
+  return true;
+}
+
+function validateRule(rule: unknown, index: number, errors: string[]): rule is OpeningHoursRule {
+  if (!isPlainObject(rule)) {
+    errors.push(`rules[${index}] : règle invalide`);
+    return false;
+  }
+  if (!Array.isArray(rule.days) || rule.days.length === 0) {
+    errors.push(`rules[${index}].days : au moins un jour requis`);
+    return false;
+  }
+  for (const day of rule.days) {
+    if (typeof day !== 'string' || !WEEKDAYS.includes(day as Weekday)) {
+      errors.push(`rules[${index}].days : jour invalide (${String(day)})`);
+    }
+  }
+  if (!Array.isArray(rule.slots) || rule.slots.length === 0) {
+    errors.push(`rules[${index}].slots : au moins un créneau requis`);
+    return false;
+  }
+  const slots: TimeSlot[] = [];
+  rule.slots.forEach((slot, slotIndex) => {
+    if (validateTimeSlot(slot, `rules[${index}].slots[${slotIndex}]`, errors)) {
+      slots.push(slot);
+    }
+  });
+  const sorted = sortSlots(slots);
+  for (let i = 0; i < sorted.length - 1; i++) {
+    if (slotsOverlap(sorted[i], sorted[i + 1])) {
+      errors.push(`rules[${index}].slots : créneaux qui se chevauchent`);
+      break;
+    }
+  }
+  return errors.length === 0;
+}
+
+function validateException(
+  exc: unknown,
+  index: number,
+  errors: string[],
+): exc is OpeningHoursException {
+  if (!isPlainObject(exc)) {
+    errors.push(`exceptions[${index}] : exception invalide`);
+    return false;
+  }
+  if (typeof exc.date !== 'string' || !DATE_RE.test(exc.date)) {
+    errors.push(`exceptions[${index}].date : date invalide (YYYY-MM-DD)`);
+    return false;
+  }
+  if (exc.closed === true) return true;
+  if (exc.closed === false) {
+    if (!Array.isArray(exc.slots) || exc.slots.length === 0) {
+      errors.push(`exceptions[${index}].slots : requis si non fermé`);
+      return false;
+    }
+    exc.slots.forEach((slot, slotIndex) => {
+      validateTimeSlot(slot, `exceptions[${index}].slots[${slotIndex}]`, errors);
+    });
+    return true;
+  }
+  errors.push(`exceptions[${index}].closed : booléen requis`);
+  return false;
+}
+
+export function validateOpeningHours(input: unknown): OpeningHoursValidationResult {
+  const errors: string[] = [];
+  if (!isPlainObject(input)) {
+    return { ok: false, errors: ['Horaires : objet attendu'] };
+  }
+  if (input.version !== 1) {
+    errors.push('version : doit être 1');
+  }
+  if (input.storage !== 'utc') {
+    errors.push('storage : doit être "utc"');
+  }
+  if (!Array.isArray(input.rules)) {
+    errors.push('rules : tableau attendu');
+    return { ok: false, errors };
+  }
+  input.rules.forEach((rule, index) => validateRule(rule, index, errors));
+
+  const daySet = new Set<Weekday>();
+  if (Array.isArray(input.rules)) {
+    for (const rule of input.rules) {
+      if (!isPlainObject(rule) || !Array.isArray(rule.days)) continue;
+      for (const day of rule.days) {
+        if (typeof day === 'string' && WEEKDAYS.includes(day as Weekday)) {
+          const wd = day as Weekday;
+          if (daySet.has(wd)) {
+            errors.push(`rules : le jour ${wd} apparaît dans plusieurs règles`);
+          }
+          daySet.add(wd);
+        }
+      }
+    }
+  }
+
+  if (input.exceptions != null) {
+    if (!Array.isArray(input.exceptions)) {
+      errors.push('exceptions : tableau attendu');
+    } else {
+      input.exceptions.forEach((exc, index) => validateException(exc, index, errors));
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+
+  return {
+    ok: true,
+    value: {
+      version: 1,
+      storage: 'utc',
+      rules: (input.rules as OpeningHoursRule[]).map((r) => ({
+        days: [...r.days],
+        slots: sortSlots([...r.slots]),
+      })),
+      exceptions: input.exceptions as OpeningHoursException[] | undefined,
+    },
+  };
+}
+
+/** Valide des horaires saisis en heure locale (même structure, sans storage/version). */
+export function validateLocalOpeningHours(input: {
+  rules: OpeningHoursRule[];
+  exceptions?: OpeningHoursException[];
+}): OpeningHoursValidationResult {
+  return validateOpeningHours({
+    version: 1,
+    storage: 'utc',
+    rules: input.rules,
+    exceptions: input.exceptions,
+  });
+}
+
+export function createEmptyOpeningHours(): OpeningHours {
+  return { version: 1, storage: 'utc', rules: [] };
+}
+
+export function createEmptyLocalRules(): OpeningHoursRule[] {
+  return [];
+}