@devpablocristo/modules-scheduling 0.4.0

package/src/client.ts

@@ -0,0 +1,300 @@
+import type {
+  AvailabilityRule,
+  BlockedRange,
+  BlockedRangePayload,
+  Booking,
+  Branch,
+  CreateBookingPayload,
+  DashboardStats,
+  DayAgendaItem,
+  ListBlockedRangesQuery,
+  ListBookingsFilter,
+  PublicAvailabilityQuery,
+  PublicAvailabilitySlot,
+  PublicBusinessInfo,
+  PublicBookPayload,
+  PublicBooking,
+  PublicMyBookingsQuery,
+  PublicQueuePosition,
+  PublicQueueSummary,
+  PublicQueueTicket,
+  PublicQueueTicketPayload,
+  PublicService,
+  PublicWaitlistEntry,
+  PublicWaitlistPayload,
+  Queue,
+  QueuePosition,
+  QueueTicket,
+  RescheduleBookingPayload,
+  Resource,
+  Service,
+  SlotQuery,
+  TimeSlot,
+  WaitlistEntry,
+  SchedulingTransport,
+} from './types';
+
+export type SchedulingClient = ReturnType<typeof createSchedulingClient>;
+export type PublicSchedulingClient = ReturnType<typeof createPublicSchedulingClient>;
+
+function appendParam(params: URLSearchParams, key: string, value: string | number | boolean | null | undefined) {
+  if (value === undefined || value === null || value === '') {
+    return;
+  }
+  params.set(key, String(value));
+}
+
+function queryString(values: Record<string, string | number | boolean | null | undefined>): string {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(values)) {
+    appendParam(params, key, value);
+  }
+  const serialized = params.toString();
+  return serialized ? `?${serialized}` : '';
+}
+
+export function createSchedulingClient(request: SchedulingTransport) {
+  return {
+    listBranches() {
+      return request<{ items: Branch[] }>('/v1/scheduling/branches').then((response) => response.items ?? []);
+    },
+    listServices() {
+      return request<{ items: Service[] }>('/v1/scheduling/services').then((response) => response.items ?? []);
+    },
+    listResources(branchId?: string | null) {
+      return request<{ items: Resource[] }>(`/v1/scheduling/resources${queryString({ branch_id: branchId })}`).then(
+        (response) => response.items ?? [],
+      );
+    },
+    listAvailabilityRules(branchId?: string | null, resourceId?: string | null) {
+      return request<{ items: AvailabilityRule[] }>(
+        `/v1/scheduling/availability-rules${queryString({ branch_id: branchId, resource_id: resourceId })}`,
+      ).then((response) => response.items ?? []);
+    },
+    listBlockedRanges(query: ListBlockedRangesQuery = {}) {
+      return request<{ items: BlockedRange[] }>(
+        `/v1/scheduling/blocked-ranges${queryString({
+          branch_id: query.branchId,
+          resource_id: query.resourceId,
+          date: query.date,
+        })}`,
+      ).then((response) => response.items ?? []);
+    },
+    createBlockedRange(payload: BlockedRangePayload) {
+      return request<BlockedRange>('/v1/scheduling/blocked-ranges', { method: 'POST', body: payload });
+    },
+    updateBlockedRange(id: string, payload: BlockedRangePayload) {
+      return request<BlockedRange>(`/v1/scheduling/blocked-ranges/${id}`, { method: 'PATCH', body: payload });
+    },
+    deleteBlockedRange(id: string) {
+      return request<void>(`/v1/scheduling/blocked-ranges/${id}`, { method: 'DELETE' });
+    },
+    listSlots(query: SlotQuery) {
+      return request<{ items: TimeSlot[] }>(
+        `/v1/scheduling/slots${queryString({
+          branch_id: query.branchId,
+          service_id: query.serviceId,
+          resource_id: query.resourceId,
+          date: query.date,
+        })}`,
+      ).then((response) => response.items ?? []);
+    },
+    listBookings(filter: ListBookingsFilter = {}) {
+      return request<{ items: Booking[] }>(
+        `/v1/scheduling/bookings${queryString({
+          branch_id: filter.branchId,
+          date: filter.date,
+          status: filter.status,
+          limit: filter.limit ?? 200,
+        })}`,
+      ).then((response) => response.items ?? []);
+    },
+    getBooking(id: string) {
+      return request<Booking>(`/v1/scheduling/bookings/${id}`);
+    },
+    createBooking(payload: CreateBookingPayload) {
+      return request<Booking>('/v1/scheduling/bookings', { method: 'POST', body: payload });
+    },
+    confirmBooking(id: string) {
+      return request<Booking>(`/v1/scheduling/bookings/${id}/confirm`, { method: 'POST', body: {} });
+    },
+    cancelBooking(id: string, reason?: string) {
+      return request<Booking>(`/v1/scheduling/bookings/${id}/cancel`, {
+        method: 'POST',
+        body: { reason: reason ?? '' },
+      });
+    },
+    checkInBooking(id: string) {
+      return request<Booking>(`/v1/scheduling/bookings/${id}/check-in`, { method: 'POST', body: {} });
+    },
+    startService(id: string) {
+      return request<Booking>(`/v1/scheduling/bookings/${id}/start-service`, { method: 'POST', body: {} });
+    },
+    completeBooking(id: string) {
+      return request<Booking>(`/v1/scheduling/bookings/${id}/complete`, { method: 'POST', body: {} });
+    },
+    markBookingNoShow(id: string, reason?: string) {
+      return request<Booking>(`/v1/scheduling/bookings/${id}/no-show`, {
+        method: 'POST',
+        body: { reason: reason ?? '' },
+      });
+    },
+    rescheduleBooking(id: string, payload: RescheduleBookingPayload) {
+      return request<Booking>(`/v1/scheduling/bookings/${id}/reschedule`, { method: 'POST', body: payload });
+    },
+    listWaitlist(branchId?: string | null, serviceId?: string | null, status?: string, limit = 100) {
+      return request<{ items: WaitlistEntry[] }>(
+        `/v1/scheduling/waitlist${queryString({
+          branch_id: branchId,
+          service_id: serviceId,
+          status,
+          limit,
+        })}`,
+      ).then((response) => response.items ?? []);
+    },
+    listQueues(branchId?: string | null) {
+      return request<{ items: Queue[] }>(`/v1/scheduling/queues${queryString({ branch_id: branchId })}`).then(
+        (response) => response.items ?? [],
+      );
+    },
+    createQueueTicket(queueId: string, payload: {
+      customer_name: string;
+      customer_phone: string;
+      customer_email?: string;
+      priority?: number;
+      notes?: string;
+    }) {
+      return request<QueueTicket>(`/v1/scheduling/queues/${queueId}/tickets`, { method: 'POST', body: payload });
+    },
+    getQueuePosition(queueId: string, ticketId: string) {
+      return request<QueuePosition>(`/v1/scheduling/queues/${queueId}/tickets/${ticketId}/position`);
+    },
+    pauseQueue(queueId: string) {
+      return request<Queue>(`/v1/scheduling/queues/${queueId}/pause`, { method: 'POST', body: {} });
+    },
+    reopenQueue(queueId: string) {
+      return request<Queue>(`/v1/scheduling/queues/${queueId}/reopen`, { method: 'POST', body: {} });
+    },
+    closeQueue(queueId: string) {
+      return request<Queue>(`/v1/scheduling/queues/${queueId}/close`, { method: 'POST', body: {} });
+    },
+    callNext(queueId: string, payload?: { serving_resource_id?: string; operator_user_id?: string }) {
+      return request<QueueTicket>(`/v1/scheduling/queues/${queueId}/next`, {
+        method: 'POST',
+        body: payload ?? {},
+      });
+    },
+    serveTicket(queueId: string, ticketId: string, payload?: { serving_resource_id?: string; operator_user_id?: string }) {
+      return request<QueueTicket>(`/v1/scheduling/queues/${queueId}/tickets/${ticketId}/serve`, {
+        method: 'POST',
+        body: payload ?? {},
+      });
+    },
+    completeTicket(queueId: string, ticketId: string, payload?: { serving_resource_id?: string; operator_user_id?: string }) {
+      return request<QueueTicket>(`/v1/scheduling/queues/${queueId}/tickets/${ticketId}/complete`, {
+        method: 'POST',
+        body: payload ?? {},
+      });
+    },
+    markTicketNoShow(queueId: string, ticketId: string) {
+      return request<QueueTicket>(`/v1/scheduling/queues/${queueId}/tickets/${ticketId}/no-show`, {
+        method: 'POST',
+        body: {},
+      });
+    },
+    cancelTicket(queueId: string, ticketId: string) {
+      return request<QueueTicket>(`/v1/scheduling/queues/${queueId}/tickets/${ticketId}/cancel`, {
+        method: 'POST',
+        body: {},
+      });
+    },
+    returnTicketToWaiting(queueId: string, ticketId: string) {
+      return request<QueueTicket>(`/v1/scheduling/queues/${queueId}/tickets/${ticketId}/return-to-waiting`, {
+        method: 'POST',
+        body: {},
+      });
+    },
+    getDashboard(branchId: string | null | undefined, day: string) {
+      return request<DashboardStats>(`/v1/scheduling/dashboard${queryString({ branch_id: branchId, day })}`);
+    },
+    getDayAgenda(branchId: string | null | undefined, day: string) {
+      return request<{ items: DayAgendaItem[] }>(`/v1/scheduling/day${queryString({ branch_id: branchId, day })}`).then(
+        (response) => response.items ?? [],
+      );
+    },
+  };
+}
+
+export function createPublicSchedulingClient(request: SchedulingTransport) {
+  return {
+    getBusinessInfo(orgId: string) {
+      return request<PublicBusinessInfo>(`/v1/public/${orgId}/info`).then((response) => ({
+        ...response,
+        scheduling_enabled:
+          typeof response.scheduling_enabled === 'boolean'
+            ? response.scheduling_enabled
+            : Boolean(response.appointments_enabled),
+        appointments_enabled:
+          typeof response.scheduling_enabled === 'boolean'
+            ? response.scheduling_enabled
+            : Boolean(response.appointments_enabled),
+      }));
+    },
+    listServices(orgId: string) {
+      return request<{ items: PublicService[] }>(`/v1/public/${orgId}/scheduling/services`).then(
+        (response) => response.items ?? [],
+      );
+    },
+    getAvailability(orgId: string, query: PublicAvailabilityQuery) {
+      return request<{ slots?: PublicAvailabilitySlot[] }>(
+        `/v1/public/${orgId}/scheduling/availability${queryString({
+          branch_id: query.branchId,
+          service_id: query.serviceId,
+          resource_id: query.resourceId,
+          date: query.date,
+          duration: query.duration,
+        })}`,
+      ).then((response) => response.slots ?? []);
+    },
+    book(orgId: string, payload: PublicBookPayload) {
+      return request<PublicBooking>(`/v1/public/${orgId}/scheduling/book`, { method: 'POST', body: payload });
+    },
+    listMyBookings(orgId: string, query: PublicMyBookingsQuery) {
+      return request<{ items: PublicBooking[] }>(
+        `/v1/public/${orgId}/scheduling/my-bookings${queryString({ phone: query.phone, limit: query.limit ?? 20 })}`,
+      ).then((response) => response.items ?? []);
+    },
+    listQueues(orgId: string, branchId?: string | null) {
+      return request<{ items: PublicQueueSummary[] }>(
+        `/v1/public/${orgId}/scheduling/queues${queryString({ branch_id: branchId })}`,
+      ).then((response) => response.items ?? []);
+    },
+    createQueueTicket(orgId: string, queueId: string, payload: PublicQueueTicketPayload) {
+      return request<PublicQueueTicket>(`/v1/public/${orgId}/scheduling/queues/${queueId}/tickets`, {
+        method: 'POST',
+        body: payload,
+      });
+    },
+    getQueuePosition(orgId: string, queueId: string, ticketId: string) {
+      return request<PublicQueuePosition>(`/v1/public/${orgId}/scheduling/queues/${queueId}/tickets/${ticketId}/position`);
+    },
+    joinWaitlist(orgId: string, payload: PublicWaitlistPayload) {
+      return request<PublicWaitlistEntry>(`/v1/public/${orgId}/scheduling/waitlist`, {
+        method: 'POST',
+        body: payload,
+      });
+    },
+    confirmBooking(orgId: string, token: string) {
+      return request<PublicBooking>(`/v1/public/${orgId}/scheduling/bookings/actions/confirm`, {
+        method: 'POST',
+        body: { token },
+      });
+    },
+    cancelBooking(orgId: string, token: string, reason?: string) {
+      return request<PublicBooking>(`/v1/public/${orgId}/scheduling/bookings/actions/cancel`, {
+        method: 'POST',
+        body: { token, reason: reason ?? '' },
+      });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+export {
+  SchedulingCalendar,
+  schedulingCalendarCopyPresets,
+  type SchedulingCalendarProps,
+} from './SchedulingCalendarBoard';
+export {
+  QueueOperatorBoard,
+  queueOperatorBoardCopyPresets,
+  type QueueOperatorBoardProps,
+} from './QueueOperatorBoard';
+export {
+  PublicSchedulingFlow,
+  publicSchedulingFlowCopyPresets,
+  type PublicSchedulingFlowProps,
+} from './PublicSchedulingFlow';
+export {
+  SchedulingDaySummary,
+  schedulingDaySummaryCopyPresets,
+  type SchedulingDaySummaryProps,
+} from './SchedulingDaySummary';
+export {
+  createSchedulingClient,
+  createPublicSchedulingClient,
+  type PublicSchedulingClient,
+  type SchedulingClient,
+} from './client';
+export {
+  formatSchedulingClock,
+  formatSchedulingCompactClock,
+  formatSchedulingDateOnly,
+  formatSchedulingDateTime,
+  formatSchedulingWeekdayNarrow,
+  resolveSchedulingCopyLocale,
+} from './locale';
+export type { SchedulingCopyLocale } from './locale';
+export type {
+  Booking,
+  Branch,
+  CreateBookingPayload,
+  DashboardStats,
+  DayAgendaItem,
+  PublicAvailabilityQuery,
+  PublicAvailabilitySlot,
+  PublicBusinessInfo,
+  PublicBookPayload,
+  PublicBooking,
+  PublicQueuePosition,
+  PublicQueueSummary,
+  PublicQueueTicket,
+  PublicQueueTicketPayload,
+  PublicService,
+  PublicWaitlistEntry,
+  PublicWaitlistPayload,
+  Queue,
+  QueuePosition,
+  QueueTicket,
+  Resource,
+  PublicSchedulingFlowCopy,
+  QueueOperatorBoardCopy,
+  SchedulingCalendarCopy,
+  SchedulingRequestOptions,
+  SchedulingTransport,
+  Service,
+  TimeSlot,
+  WaitlistEntry,
+} from './types';

package/src/locale.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import {
+  formatSchedulingClock,
+  formatSchedulingCompactClock,
+  formatSchedulingDateOnly,
+  formatSchedulingDateTime,
+  formatSchedulingWeekdayNarrow,
+  resolveSchedulingCopyLocale,
+} from './locale';
+
+describe('scheduling locale helpers', () => {
+  it('resolves regional locales to the supported copy presets', () => {
+    expect(resolveSchedulingCopyLocale('es-AR')).toBe('es');
+    expect(resolveSchedulingCopyLocale('en-US')).toBe('en');
+    expect(resolveSchedulingCopyLocale(undefined)).toBe('en');
+  });
+
+  it('formats date and time values with the provided locale', () => {
+    expect(formatSchedulingClock('2099-12-01T10:00:00Z', 'es-AR')).not.toBe(formatSchedulingClock('2099-12-01T10:00:00Z', 'en-US'));
+    expect(formatSchedulingCompactClock('2099-12-01T10:00:00Z', 'es-AR')).toMatch(/\d{2}:\d{2}/);
+    expect(formatSchedulingDateTime('2099-12-01T10:00:00Z', 'es-AR')).toMatch(/\d{1,2}\/\d{1,2}\/\d{4}/);
+    expect(formatSchedulingDateTime('2099-12-01T10:00:00Z', 'en-US')).toMatch(/dec/i);
+    expect(formatSchedulingDateTime('invalid-date', 'es-AR')).toBe('invalid-date');
+  });
+
+  it('formats YYYY-MM-DD for display without exposing raw ISO date', () => {
+    expect(formatSchedulingDateOnly('2099-04-08', 'es-AR')).toMatch(/\d{1,2}\/\d{1,2}\/\d{4}/);
+    expect(formatSchedulingDateOnly('2099-04-08', 'es-AR')).not.toContain('2099-04');
+    expect(formatSchedulingDateOnly('not-a-date', 'es-AR')).toBe('not-a-date');
+  });
+
+  it('formats weekday picks with the provided locale', () => {
+    expect(formatSchedulingWeekdayNarrow(1, 'es-AR')).not.toBe('');
+    expect(formatSchedulingWeekdayNarrow(1, 'en-US')).not.toBe('');
+  });
+});

package/src/locale.ts

@@ -0,0 +1,91 @@
+export type SchedulingCopyLocale = 'en' | 'es';
+
+export function resolveSchedulingCopyLocale(locale: string | undefined): SchedulingCopyLocale {
+  return locale?.toLowerCase().startsWith('es') ? 'es' : 'en';
+}
+
+function isValidDate(value: Date): boolean {
+  return !Number.isNaN(value.getTime());
+}
+
+export function formatSchedulingDateTime(value: string | null | undefined, locale: string | undefined): string {
+  if (!value) {
+    return '—';
+  }
+
+  const parsed = new Date(value);
+  if (!isValidDate(parsed)) {
+    return String(value);
+  }
+
+  // Español: fecha numérica día/mes/año (LATAM) + hora; inglés: mes abreviado.
+  if (resolveSchedulingCopyLocale(locale) === 'es') {
+    return new Intl.DateTimeFormat(locale, {
+      weekday: 'short',
+      day: '2-digit',
+      month: '2-digit',
+      year: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+    }).format(parsed);
+  }
+
+  return new Intl.DateTimeFormat(locale, {
+    weekday: 'short',
+    day: '2-digit',
+    month: 'short',
+    hour: '2-digit',
+    minute: '2-digit',
+  }).format(parsed);
+}
+
+/** Convierte `YYYY-MM-DD` (valor de input type=date) a fecha local legible (p. ej. dd/mm/yyyy en es-AR). */
+export function formatSchedulingDateOnly(ymd: string, locale: string | undefined): string {
+  const trimmed = ymd.trim();
+  const parts = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+  if (!parts) {
+    return trimmed;
+  }
+  const year = Number(parts[1]);
+  const month = Number(parts[2]);
+  const day = Number(parts[3]);
+  if (!year || month < 1 || month > 12 || day < 1 || day > 31) {
+    return trimmed;
+  }
+  const parsed = new Date(Date.UTC(year, month - 1, day, 12, 0, 0));
+  if (!isValidDate(parsed)) {
+    return trimmed;
+  }
+  return new Intl.DateTimeFormat(locale, {
+    day: '2-digit',
+    month: '2-digit',
+    year: 'numeric',
+  }).format(parsed);
+}
+
+export function formatSchedulingClock(value: string, locale: string | undefined): string {
+  const parsed = new Date(value);
+  if (!isValidDate(parsed)) {
+    return value;
+  }
+
+  return new Intl.DateTimeFormat(locale, { hour: '2-digit', minute: '2-digit' }).format(parsed);
+}
+
+export function formatSchedulingCompactClock(value: string, locale: string | undefined): string {
+  const parsed = new Date(value);
+  if (!isValidDate(parsed)) {
+    return value;
+  }
+
+  return new Intl.DateTimeFormat(locale, {
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).format(parsed);
+}
+
+export function formatSchedulingWeekdayNarrow(weekday: number, locale: string | undefined): string {
+  const date = new Date(Date.UTC(2026, 0, 4 + weekday));
+  return new Intl.DateTimeFormat(locale, { weekday: 'narrow' }).format(date);
+}

package/src/next.ts

@@ -0,0 +1,66 @@
+export {
+  SchedulingCalendar,
+  schedulingCalendarCopyPresets,
+  type SchedulingCalendarProps,
+} from './SchedulingCalendarBoard';
+export {
+  QueueOperatorBoard,
+  queueOperatorBoardCopyPresets,
+  type QueueOperatorBoardProps,
+} from './QueueOperatorBoard';
+export {
+  PublicSchedulingFlow,
+  publicSchedulingFlowCopyPresets,
+  type PublicSchedulingFlowProps,
+} from './PublicSchedulingFlow';
+export {
+  SchedulingDaySummary,
+  schedulingDaySummaryCopyPresets,
+  type SchedulingDaySummaryProps,
+} from './SchedulingDaySummary';
+export {
+  createSchedulingClient,
+  createPublicSchedulingClient,
+  type PublicSchedulingClient,
+  type SchedulingClient,
+} from './client';
+export {
+  formatSchedulingClock,
+  formatSchedulingCompactClock,
+  formatSchedulingDateOnly,
+  formatSchedulingDateTime,
+  formatSchedulingWeekdayNarrow,
+  resolveSchedulingCopyLocale,
+} from './locale';
+export type { SchedulingCopyLocale } from './locale';
+export type {
+  Booking,
+  Branch,
+  CreateBookingPayload,
+  DashboardStats,
+  DayAgendaItem,
+  PublicAvailabilityQuery,
+  PublicAvailabilitySlot,
+  PublicBusinessInfo,
+  PublicBookPayload,
+  PublicBooking,
+  PublicQueuePosition,
+  PublicQueueSummary,
+  PublicQueueTicket,
+  PublicQueueTicketPayload,
+  PublicService,
+  PublicWaitlistEntry,
+  PublicWaitlistPayload,
+  Queue,
+  QueuePosition,
+  QueueTicket,
+  Resource,
+  PublicSchedulingFlowCopy,
+  QueueOperatorBoardCopy,
+  SchedulingCalendarCopy,
+  SchedulingRequestOptions,
+  SchedulingTransport,
+  Service,
+  TimeSlot,
+  WaitlistEntry,
+} from './types';