sd-park-pass-ntfy/README.md

Library Availability Monitor

A Node.js service that monitors San Diego libraries for parking pass availability and sends notifications via ntfy when passes become available at the desired branch.

Features

• 📚 Monitors specific library book availability via BiblioCommons API
• 📱 Sends push notifications via ntfy when new books become available
• ⏰ Polls hourly and tracks availability changes
• 🔄 Graceful error handling and recovery
• 🧪 Comprehensive testing suite
• 🎭 Mock testing capabilities
• 🚀 Easy deployment to Linux servers

Setup

Prerequisites

• Node.js 18+
• npm
• SSH access to deployment server (optional)

Installation

1. Clone or download this repository

2. Install dependencies:

   npm install
   

3. Configure your ntfy settings in index.js:

   const CONFIG = {
       NTFY_TOPIC: 'your-topic-name',
       NTFY_SERVER: 'https://ntfy.sh', // or your own server
       // ... other settings
   };
   

Usage

Running the Monitor

# Start the monitor
npm start

# Development mode with auto-restart
npm run dev

Testing

# Run all tests
npm test

# Validate against real API response example
npm run validate

# Interactive mock testing
npm run mock

# Simulate availability changes
node mock.js test 3  # Simulate 3 available books
node mock.js notify  # Send test notification
node mock.js status  # Show current state
node mock.js reset   # Reset state file

Deployment

The included deployment script uploads and manages the service on a remote Linux server:

# Deploy to configured server
npm run deploy

# Or run directly
./deploy.sh

Deployment Setup

1. Configure SSH access to your server as 'linode' in ~/.ssh/config:

   Host linode
       HostName your-server-ip
       User your-username
       IdentityFile ~/.ssh/your-key
   

2. The deployment script will:

   • Upload files to /opt/sd-park-pass-ntfy
   • Install dependencies
   • Create and start a systemd service
   • Enable auto-start on boot

Configuration

Main Configuration (index.js)

const CONFIG = {
    API_URL: 'https://gateway.bibliocommons.com/v2/libraries/sandiego/bibs/S161C1805116/availability',
    BRANCH_NAME: 'Rancho Penasquitos',
    NTFY_TOPIC: 'sdparkpass',
    NTFY_SERVER: 'https://ntfy.sh',
    POLL_INTERVAL: '0 * * * *', // Every hour
    // ...
};

Systemd Service

The service runs as user nobody for security and includes:

• Automatic restart on failure
• Proper logging via journald
• Security hardening
• Environment isolation

View logs:

sudo journalctl -u sd-park-pass-ntfy -f

API Response Format

The monitor expects BiblioCommons API responses in this format:

{
  "entities": {
    "bibItems": {
      "1805116|31336107103179||76": {
        "collection": "Adult - Circulation Desk",
        "callNumber": "CA STATE LIBRARY PARKS PASS HIKING BACKPACK",
        "itemId": "1805116|31336107103179||76",
        "branch": {
          "name": "Rancho Penasquitos",
          "code": "29"
        },
        "availability": {
          "status": "AVAILABLE",
          "statusType": "AVAILABLE",
          "libraryStatus": "Available"
        },
        "branchName": "Rancho Penasquitos",
        "dueDate": null
      }
    }
  }
}

The monitor looks for:

• Items with branchName containing "Rancho Penasquitos"
• Items with availability.statusType NOT equal to "UNAVAILABLE"
• Available status types include: "AVAILABLE", "RECENTLY_RETURNED"

State Management

The monitor tracks availability in last_availability.json:

{
  "availabilityCount": 2,
  "lastUpdated": "2025-07-13T10:00:00.000Z",
  "previousCount": 1,
  "branch": "Rancho Penasquitos",
  "apiUrl": "https://..."
}

Notification Types

• 📚 High Priority: New books became available
• ⚠️ Low Priority: Errors or status changes
• 🔴 Service Events: Start/stop notifications

Troubleshooting

Common Issues

1. No notifications received:

   • Check ntfy topic subscription on your phone
   • Verify NTFY_SERVER and NTFY_TOPIC settings
   • Test with node mock.js notify

2. API errors:

   • Check network connectivity
   • Verify API URL is still valid
   • Monitor rate limiting

3. Service not starting:

   • Check file permissions
   • Review systemd logs: journalctl -u sd-park-pass-ntfy
   • Ensure Node.js is installed on server

Mock Testing

Use the mock script to verify functionality:

# Interactive mode
node mock.js

# Commands in interactive mode:
> test 5     # Simulate 5 available books
> notify     # Send test notification  
> status     # Show current state
> reset      # Clear state file
> quit       # Exit

Files

• index.js - Main application
• test.js - Test suite
• mock.js - Mock testing script
• validate-real-response.js - Validates parsing against real API response
• deploy.sh - Deployment script
• sd-park-pass-ntfy.service - Systemd service file
• test-config.js - Test configuration and mock data
• example-response.json - Real API response example for reference

License

ISC