appointment-scheduler

Automated appointment management for beauty salons, clinics, studios, and photo booths. Handles booking requests, calendar sync, conflict detection, reminder...

Security Scan

The package appears to do what it says: local appointment management with optional Google Calendar sync; code, files, and instructions are coherent with the stated purpose, with only minor packaging/installation mismatches to note.

Purpose & Capability

Name/description match the included scripts and README: booking, conflict detection, reminders, no-show tracking, waitlist, and calendar sync are implemented. The Google Calendar OAuth flow is documented and the code expects OAuth credential/token files in ~/.secrets, which is appropriate for calendar integration.

Instruction Scope

SKILL.md and README instruct running local Node scripts that read/write data under the user's home (~/.openclaw/workspace and ~/.secrets). The runtime instructions do not ask the agent to read unrelated system files, contact unknown endpoints, or exfiltrate arbitrary data. Reminder outputs are printed as JSON for the host agent to hand to a message tool (as documented).

Install Mechanism

Registry metadata lists no install spec (instruction-only), but the bundle includes code and a package.json; README instructs running npm install in the scripts directory. That means installing npm packages (chrono-node, googleapis) from the public registry is required to use the scripts — moderate risk relative to an instruction-only skill but not unexpected for a Node-based tool. No downloads from untrusted URLs or extract steps were observed.

Credentials

The skill declares no required env vars, which is accurate, but it expects and documents local credential/config files (e.g., ~/.secrets/google-calendar-credentials.json and ~/.secrets/google-calendar-token.json, plus ~/.openclaw workspace config and data). Those file accesses are proportional to calendar sync and local data storage, but users should be aware Google OAuth credentials/tokens will be read from the home directory if calendar sync is enabled.

Persistence & Privilege

Skill does not request elevated privileges and does not set always:true. It writes its own config and data under ~/.openclaw/workspace and saves tokens under ~/.secrets — behaviour consistent with a local scheduler. It does not modify other skills or system-wide agent configurations.

Assessment

This package appears to implement an on-disk Node-based appointment scheduler. Before installing or running: 1) Note the registry entry omitted an install spec even though package.json exists — run npm install only in a trusted environment and inspect package-lock.json (it references chrono-node and googleapis). 2) If you enable calendar sync, you'll need to place OAuth credentials/tokens in ~/.secrets — treat those files as sensitive. 3) The scripts read/write data under ~/.openclaw and ~/.secrets; back up any existing files and consider filesystem permissions. 4) If you don't need Google sync or certain features (reminders, waitlist), disable/uninstall the related scripts. 5) The source owner is unknown in the registry metadata; if you require higher assurance, request an upstream repository or signed release, or review the included code yourself before use.

Automated appointment management system for service businesses.

Features

1. 예약 접수 — Parse booking requests from DM/KakaoTalk/phone (text-converted)
2. 캘린더 등록 — Auto-sync with Google Calendar / Naver Calendar
3. 충돌 감지 — Prevent double-booking
4. 리마인더 — Auto-notify customers 1 day before + 2 hours before
5. 노쇼 관리 — Track no-shows and flag repeat offenders
6. 대기 명단 — Auto-waitlist when fully booked + auto-notify on cancellation

Target Use Cases

• 미용실 (Beauty Salons)
• 병원 (Clinics)
• 스튜디오 (Studios)
• 포토부스 MUFI (Photo Booths)

Quick Start

1. Initialize Configuration

node <skill-dir>/scripts/init-config.js

This creates config/appointment-scheduler.json with:

• Business hours
• Service duration defaults
• Calendar connection settings
• Reminder timing preferences
• No-show policy

2. Process Incoming Request

From text message:

node <skill-dir>/scripts/parse-booking.js --text "내일 오후 3시에 컷 예약 가능할까요? - 김철수 010-1234-5678"

From conversation context:

"고객이 예약 요청했어요: [message content]"

The skill will:

1. Parse date/time, service type, customer name, contact
2. Check calendar for conflicts
3. If available → book + confirm
4. If conflict → suggest alternatives or add to waitlist

3. Manual Booking

node <skill-dir>/scripts/book.js \
  --date "2026-02-20" \
  --time "15:00" \
  --duration 60 \
  --service "컷" \
  --customer "김철수" \
  --phone "010-1234-5678"

4. Check Schedule

# Today's appointments
node <skill-dir>/scripts/check-schedule.js --date today

# Specific date
node <skill-dir>/scripts/check-schedule.js --date 2026-02-20

# This week
node <skill-dir>/scripts/check-schedule.js --week

5. Send Reminders

Manual trigger:

node <skill-dir>/scripts/send-reminders.js

Auto-trigger via cron:

# Daily at 9:00 AM - send 1-day-before reminders
0 9 * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type day-before

# Hourly - send 2-hour-before reminders
0 * * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type hour-before

6. Handle No-Shows

# Mark customer as no-show
node <skill-dir>/scripts/mark-noshow.js --booking-id abc123

# Check no-show stats
node <skill-dir>/scripts/noshow-report.js

# Flag repeat offenders (3+ no-shows)
node <skill-dir>/scripts/noshow-report.js --flag-repeat

7. Waitlist Management

# Add to waitlist
node <skill-dir>/scripts/waitlist.js add \
  --date "2026-02-20" \
  --time "15:00" \
  --customer "이영희" \
  --phone "010-9999-8888"

# Check waitlist
node <skill-dir>/scripts/waitlist.js list --date 2026-02-20

# Notify waitlist on cancellation
node <skill-dir>/scripts/waitlist.js notify --booking-id abc123

Data Storage

Location: workspace/data/appointments/

data/appointments/
  bookings/
    2026-02-20.json          # Daily booking records
  waitlist/
    2026-02-20.json          # Daily waitlist
  noshow/
    history.json             # No-show records
    flagged-customers.json   # Repeat offenders
  reminders/
    sent.json                # Reminder delivery log

Calendar Integration

Google Calendar

1. Enable Google Calendar API
2. Download OAuth credentials → save as ~/.secrets/google-calendar-credentials.json
3. First run will prompt browser auth
4. Refresh token saved to ~/.secrets/google-calendar-token.json

Sync script:

node <skill-dir>/scripts/sync-google-calendar.js

Naver Calendar

Uses Naver Calendar API (if available) or browser automation fallback.

Config: Add Naver account to config/appointment-scheduler.json

Booking Request Parsing

The parser handles natural language like:

• "내일 오후 3시 컷 예약"
• "2월 20일 15:00 펌 가능할까요"
• "다음주 월요일 오전 컷+염색"
• "3시에 포토부스 예약 - 김철수 010-1234-5678"

Extracted fields:

• Date (relative or absolute)
• Time
• Service type
• Customer name
• Contact (phone/email/username)
• Special notes

Conflict Detection

Before confirming:

1. Check existing bookings in date/time slot
2. Calculate service duration overlap
3. If conflict → suggest nearest available slot
4. If fully booked → offer waitlist

Buffer time: Configurable in config (default: 10 min between appointments)

Reminder System

Default timing:

• 1 day before at 9:00 AM — "내일 오후 3시 예약 있습니다"
• 2 hours before — "2시간 후 예약 있습니다"

Delivery channels (auto-detect from customer contact):

• Phone → SMS (via message tool)
• Instagram → DM
• KakaoTalk → Message

Customization: Edit timing in config/appointment-scheduler.json

No-Show Management

Tracking:

• Mark as no-show if customer doesn't show up within 15 min grace period
• Record in noshow/history.json
• Count per customer

Auto-flag policy (default):

• 3+ no-shows → flag customer
• Flagged customers require deposit for future bookings

Query:

# Check customer history
node <skill-dir>/scripts/noshow-report.js --customer "김철수"

# Monthly stats
node <skill-dir>/scripts/noshow-report.js --month 2026-02

Waitlist Auto-Notify

When a booking is cancelled:

1. Find waitlist entries for same date/time
2. Auto-send notification: "예약 자리가 났습니다! 원하시면 예약 가능합니다"
3. First-come-first-served → confirm via reply
4. Auto-book if confirmed within 30 min

Voice Integration

Supports phone call → text → booking flow:

1. Receive call transcript (via STT tool)
2. Parse booking request
3. Confirm availability
4. Send SMS confirmation

Hook Integration

pre-hook: Before booking → check business hours, service availability post-hook: After booking → send confirmation, update calendar, log event conflict-hook: On conflict → trigger alternative suggestion or waitlist flow

Event Bus Integration

Location: events/appointment-YYYY-MM-DD.json

{
  "timestamp": "2026-02-18T15:30:00Z",
  "event": "booking_created",
  "booking_id": "abc123",
  "customer": "김철수",
  "date": "2026-02-20",
  "time": "15:00",
  "service": "컷"
}

Cron Setup

Recommended cron jobs:

# Send day-before reminders at 9 AM
0 9 * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type day-before

# Send 2-hour reminders every hour
0 * * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type hour-before

# Sync calendar every 30 min
*/30 * * * * node /path/to/skills/appointment-scheduler/scripts/sync-google-calendar.js

# Daily no-show report at 8 PM
0 20 * * * node /path/to/skills/appointment-scheduler/scripts/noshow-report.js --daily

Configuration Template

Location: config/appointment-scheduler.json

{
  "business_name": "MUFI 포토부스",
  "business_hours": {
    "monday": { "open": "10:00", "close": "20:00" },
    "tuesday": { "open": "10:00", "close": "20:00" },
    "wednesday": { "open": "10:00", "close": "20:00" },
    "thursday": { "open": "10:00", "close": "20:00" },
    "friday": { "open": "10:00", "close": "22:00" },
    "saturday": { "open": "10:00", "close": "22:00" },
    "sunday": { "open": "12:00", "close": "18:00" }
  },
  "services": {
    "포토촬영": { "duration": 30, "buffer": 10 },
    "컷": { "duration": 60, "buffer": 10 },
    "펌": { "duration": 120, "buffer": 15 },
    "염색": { "duration": 90, "buffer": 15 }
  },
  "reminders": {
    "day_before": { "enabled": true, "time": "09:00" },
    "hour_before": { "enabled": true, "hours": 2 }
  },
  "noshow_policy": {
    "grace_period_min": 15,
    "flag_threshold": 3,
    "require_deposit_when_flagged": true
  },
  "calendar": {
    "google": {
      "enabled": true,
      "calendar_id": "primary"
    },
    "naver": {
      "enabled": false
    }
  }
}

Troubleshooting

Issue	Solution
예약 파싱 실패	Check parse-booking.js output, add custom patterns
캘린더 동기화 에러	Verify OAuth credentials, check token expiry
리마인더 미발송	Check cron job status, verify message tool config
중복 예약 발생	Ensure conflict detection enabled, check buffer time
대기 명단 알림 실패	Check customer contact info, verify message channel

Advanced Usage

Custom Service Types

Edit config/appointment-scheduler.json:

"services": {
  "신규서비스": { "duration": 45, "buffer": 10 }
}

Block Off Time

# Mark time slot as unavailable
node <skill-dir>/scripts/block-time.js \
  --date "2026-02-20" \
  --start "12:00" \
  --end "13:00" \
  --reason "점심시간"

Bulk Import

# Import from CSV
node <skill-dir>/scripts/import-bookings.js --file bookings.csv

Export Reports

# Monthly booking report
node <skill-dir>/scripts/export-report.js --month 2026-02 --format json

# No-show analysis
node <skill-dir>/scripts/noshow-report.js --month 2026-02 --export csv

Learned Lessons

• Natural language parsing accuracy: ~85% for Korean date/time expressions
• Reminder delivery rate: 95%+ via Instagram DM, 80%+ via SMS
• No-show rate reduced by 40% after implementing 1-day-before reminders
• Waitlist auto-notify increases booking fill rate by 25%

---

🐧 Built by 무펭이 — 무펭이즘(Mupengism) 생태계 스킬