@flinkk/hotel-management

A comprehensive Flinkk Shop.js plugin for hotel management, providing advanced pricing, inventory management, and booking capabilities for hospitality businesses.

Features

🏨 Core Hotel Management

• Date-based Inventory Management: Track room availability with date ranges, check-in/check-out times
• Advanced Pricing System: Flexible pricing with breakdowns, markups, commissions, and margins
• Variant Pricing Calendar: Visual calendar interface for managing room rates
• Reservation Management: Handle bookings, allocations, and cancellations

💰 Pricing & Revenue Management

• Price Breakdown Module: Detailed cost analysis with gross cost, markup, net price, and selling price
• Commission Tracking: Built-in commission and margin percentage calculations
• Dynamic Pricing: Date-based pricing with calendar view management
• Metadata Support: Flexible pricing metadata for custom business rules

📅 Inventory & Availability

• Date-based Inventory Levels: Track availability by specific date ranges
• Multiple Status Types: Support for capacity, reserved, allocated, canceled, on_hold, and maintenance statuses
• Cart Integration: Seamless integration with Flinkk Shop's cart system
• Expiration Management: Handle temporary reservations with expiration times

🎛️ Admin Interface

• Pricing Calendar View: Interactive calendar for managing room rates
• Variant Pricing Manager: Comprehensive pricing management interface
• Variant Selector: Easy room/variant selection tools
• Custom Admin Routes: Dedicated admin pages for hotel management

Installation

From GitHub Packages

Since this package is published to GitHub Packages, you need to configure npm first:

1. Configure npm for GitHub Packages: Create or update your .npmrc file in your project root:

   @flinkk:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

2. Install the package:

   npm install @flinkk/hotel-management

   or

   yarn add @flinkk/hotel-management

Local Development with Yalc

For local development and testing

1. Go to your project repo and run

    npx flinkk plugin:add @flinkk/hotel-management

   This will update your package.json with "@flinkk/hotel-management": "file:.yalc/@flinkk/hotel-management"

2. Open a new terminal and Go to Src/plugins/hotel-management and run:

   npx flinkk plugin:develop

   This will build the plugin and watch for changes.

3. Start the application locally: Now in the existing terminal, run yarn dev

4. Remove Package link when done: Discard your changes in package.json once done

Configuration

Add the plugin to your flinkk-config.js:

const plugins = [
  // ... other plugins
  {
    resolve: "@flinkk/hotel-management",
    options: {
      // Plugin configuration options
    },
  },
]

module.exports = defineConfig({
  // ... other config
  plugins,
})

Usage

Setting up Date-based Inventory

The plugin extends Flinkk Shop's inventory system with date-based availability:

// Example: Creating date inventory levels
const inventoryLevel = {
  inventory_item_id: "inv_123",
  product_variant_id: "variant_456",
  from_date: "2024-01-01T00:00:00Z",
  to_date: "2024-01-02T00:00:00Z",
  check_in_time: "15:00",
  check_out_time: "11:00",
  available_quantity: 5,
  status: "capacity"
}

Managing Price Breakdowns

Create detailed pricing structures with cost analysis:

// Example: Price breakdown with markup and commission
const priceBreakdown = {
  gross_cost: 10000, // $100.00 in cents
  markup_fixed: 2000, // $20.00 fixed markup
  markup_percent: 15, // 15% markup
  commission_percent: 10, // 10% commission
  margin_percent: 25, // 25% margin
  net_price: 12000, // $120.00
  selling_price: 15000 // $150.00
}

Admin Components

The plugin provides React components for the admin interface:

import { VariantPricingManager } from "@flinkk/hotel-management/admin/components"
import { VariantPricingCalendarView } from "@flinkk/hotel-management/admin/components"

// Use in your admin customizations
<VariantPricingManager variantId="variant_123" />
<VariantPricingCalendarView />

API Routes

Admin Routes

• GET /admin/price-breakdown - Retrieve price breakdowns
• POST /admin/price-breakdown - Create price breakdown
• GET /admin/variants/[id]/pricing - Get variant pricing
• POST /admin/variants/[id]/pricing - Update variant pricing

Store Routes

• GET /store/plugin - Plugin information
• Additional store routes for customer-facing functionality

Database Models

PriceBreakdown

Extends Flinkk Shop pricing with detailed cost analysis:

• gross_cost: Base cost in cents
• markup_fixed: Fixed markup amount
• markup_percent: Percentage markup (0-100)
• commission_percent: Commission percentage
• margin_percent: Profit margin percentage
• net_price: Net price after calculations
• selling_price: Final selling price

InventoryDateLevel

Date-based inventory management:

• inventory_item_id: Reference to inventory item
• from_date/to_date: Availability date range
• check_in_time/check_out_time: Hotel-specific times
• available_quantity: Available units
• status: Inventory status (capacity, reserved, etc.)
• cart_id/order_id: Booking references

Workflows

The plugin includes automated workflows:

• Date Inventory Level Creation: Automatically create inventory levels for date ranges
• Variant Inventory Management: Handle variant-specific inventory operations
• Price Calculation Workflows: Automated pricing calculations

Development

Local Development Workflow

1. Make changes to the plugin source code
2. Build the plugin:

   npm run build

3. Push to yalc (if using yalc for local testing):

   yalc push

4. Test in your Flinkk Shop application

Publishing

Prerequisites

• Access to the @flinkk GitHub organization
• GitHub Personal Access Token with write:packages permission
• Proper .npmrc configuration

Publishing Steps

1. Update version in package.json:

   npm version patch  # or minor/major

2. Build the plugin:

   npm run build

3. Publish to GitHub Packages:

   npm publish

Publishing Checklist

• [ ] Update version number
• [ ] Update CHANGELOG.md
• [ ] Build successfully
• [ ] All tests pass
• [ ] Documentation is up to date
• [ ] Publish to GitHub Packages
• [ ] Create GitHub release
• [ ] Tag the release

Requirements

• Node.js: >= 20
• Flinkk Shop: Compatible with Flinkk Shop v2.x
• Database: PostgreSQL (for date/time operations)

Dependencies

Peer Dependencies

• @flinkk/shop: Flinkk Shop core framework
• @flinkk/admin-sdk: Admin interface SDK
• @flinkk/ui: UI components
• @mikro-orm/core: Database ORM
• @mikro-orm/postgresql: PostgreSQL adapter

Troubleshooting

GitHub Packages Authentication

If you encounter authentication issues:

1. Generate a GitHub Personal Access Token:

   • Go to GitHub Settings > Developer settings > Personal access tokens
   • Generate a token with read:packages and write:packages permissions

2. Update your .npmrc:

   @flinkk:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE

3. Login to npm:

   npm login --registry=https://npm.pkg.github.com

Yalc Issues

If yalc linking doesn't work:

1. Clear yalc cache:

   yalc installations clean @flinkk/hotel-management

2. Republish:

   yalc publish --force

3. Re-add to project:

   yalc remove @flinkk/hotel-management
   yalc add @flinkk/hotel-management

Built with ❤️ for the hospitality industry