@thezelijah/majik-service

v1.0.2

Published

8 days ago

Majik Service is a fully-featured class representing a service in the Majik system, designed for financial management, cost tracking, and capacity planning. It provides utilities for computing revenue, profit, margins, COS (Cost of Service), and net incom

Majik Service

Majik Service is a fully-featured class representing a service in the Majik system, designed for financial management, cost tracking, and capacity planning. It provides utilities for computing revenue, profit, margins, COS (Cost of Service), and net income on a per-month basis. Chainable setter methods make it easy to construct and update services fluently.

Live Demo

Click the image to try Majik Service inside Majik Runway's revenue stream.

Click the image to try Majik Service inside Price Genie.

✨ Overview

MajikService manages:

Metadata: name, category, type, description, SKU, photos, rate.
Settings: status, visibility, system flags.
Finance: revenue, income, profit, cos.
Capacity Plan: Monthly availability, adjustments, generation, recomputation.
Cost of Service: Detailed breakdown of labor, materials, and other costs.
Serialization/Deserialization: Convert to/from JSON with full monetary support via MajikMoney.

Full API Docs

📦 Installation

npm i @thezelijah/majik-service @thezelijah/majik-money@latest

Usage

Create a Service Instance

import { MajikService } from "@thezelijah/majik-service";
import { MajikMoney } from "@/SDK/tools/finance/majik-money";
import { ServiceType, RateUnit } from "@/SDK/tools/business/majik-service/enums";

const service = MajikService.initialize(
  "Video Editing",
  ServiceType.TIME_BASED,
  { amount: MajikMoney.fromMajor(50, "PHP"), unit: RateUnit.PER_HOUR },
  "Post-production services",
  "VIDEDIT001"
);

Defaults: status → ACTIVE visibility → PRIVATE Empty COS, empty capacity plan

Example Usage

import { MajikService } from "@thezelijah/majik-service";
import { MajikMoney } from "@thezelijah/majik-money";
import { ServiceType, RateUnit, CapacityPeriodResizeMode } from "@thezelijah/majik-service/enums";

// Initialize a new service
const videoEditing = MajikService.initialize(
  "Video Editing",
  ServiceType.TIME_BASED,
  { amount: MajikMoney.fromMajor(50, "PHP"), unit: RateUnit.PER_HOUR },
  "Professional post-production video editing",
  "VIDEDIT001"
)
  .setDescriptionHTML("<p>High-quality video editing for content creators.</p>")
  .setDescriptionSEO("Video editing service for YouTube, ads, and films")
  .addCOS("Editor Labor", MajikMoney.fromMajor(20, "PHP"), 1, "hour")
  .addCOS("Software License", MajikMoney.fromMajor(5, "PHP"), 1, "month")
  .generateCapacityPlan(12, 160) // 12 months, 160 hours per month
  .recomputeCapacityPeriod("2025-01", "2025-12", CapacityPeriodResizeMode.DISTRIBUTE);

// Query total capacity
console.log("Total Capacity:", videoEditing.totalCapacity); // 12 months * 160 hours = 1920

// Compute revenue and profit for a specific month
const month = "2025-06";
console.log(`${month} Revenue:`, videoEditing.getRevenue(month).value.toFormat());
console.log(`${month} COS:`, videoEditing.getCOS(month).value.toFormat());
console.log(`${month} Profit:`, videoEditing.getProfit(month).value.toFormat());
console.log(`${month} Margin:`, videoEditing.getMargin(month).toFixed(2) + "%");

// Serialize service for storage or API
const json = videoEditing.toJSON();

// Deserialize back into a functional service
const restoredService = MajikService.parseFromJSON(json);
console.log("Restored Service Name:", restoredService.metadata.description.text);

// Reduce capacity after usage
restoredService.reduceCapacity("2025-06", 10);
console.log("Remaining Capacity for June:", restoredService.capacityPlan.find(c => c.month === "2025-06")?.capacity);

Metadata Helpers

Chainable methods to update service metadata:

| Method | Description | | ---------------------------------- | ------------------------------ | | setName(name: string) | Updates service name and slug | | setCategory(category: string) | Updates category | | setType(type: ServiceType) | Updates service type | | setRate(rate: ServiceRate) | Updates billing rate | | setDescriptionText(text: string) | Updates plain text description | | setDescriptionHTML(html: string) | Updates HTML description | | setDescriptionSEO(text: string) | Updates SEO text | | setPhotos(urls: string[]) | Sets photo URLs |

COS Management

Manage the Cost of Service per item:

| Method | Description | | ------------------------------------------ | --------------------------------------- | | addCOS(name, unitCost, quantity?, unit?) | Add a new COS item | | pushCOS(item: COSItem) | Push an externally constructed COS item | | updateCOS(id, updates) | Update an existing COS item | | removeCOS(id) | Remove COS item by ID | | setCOS(items: COSItem[]) | Replace entire COS array | | clearCOS() | Remove all COS items |

Capacity Management

Manage monthly capacity and service plan:

| Method | Description | | --------------------------------------------------------------- | -------------------------------------- | | addCapacity(month: YYYYMM, capacity, adjustment?) | Add a monthly capacity entry | | updateCapacityUnits(month, units) | Update units for a month | | updateCapacityAdjustment(month, adjustment?) | Update adjustment | | removeCapacity(month) | Remove a month from the plan | | clearCapacity() | Remove all capacity entries | | generateCapacityPlan(months, amount, growthRate?, startDate?) | Auto-generate a monthly plan | | normalizeCapacityUnits(amount) | Normalize all months to the same units | | recomputeCapacityPeriod(start, end, mode?) | Resize or redistribute capacity plan |

Capacity plan queries:

totalCapacity → total units across all months
averageMonthlyCapacity → average per month
maxCapacityMonth / minCapacityMonth → highest/lowest monthly capacity

Finance Computation

| Method | Description | | ------------------- | --------------------------------------------- | | getRevenue(month) | Returns gross revenue for the specified month | | getProfit(month) | Returns profit for the specified month | | getCOS(month) | Returns total cost of service for month | | getMargin(month) | Returns margin ratio |

Calculates revenue, costs, and profits per month or across all months.

grossRevenue, grossCost, grossProfit → totals across capacity plan
netRevenue(month, discounts?, returns?, allowances?) → net per month
netProfit(month, operatingExpenses?, taxes?, discounts?, returns?, allowances?) → net profit per month
getRevenue(month), getCOS(month), getProfit(month), getMargin(month) → month-specific
averageMonthlyRevenue, averageMonthlyProfit → averages

All computations use MajikMoney and respect currency.

Utilities

validateSelf(throwError?: boolean) → validates all required fields
finalize() → converts to JSON with auto-generated ID
toJSON() → serialize with proper MajikMoney handling
parseFromJSON(json: string | object) → reconstruct a MajikService instance

Use Cases

MajikService is designed for applications that require structured, financial-aware service management. Typical use cases include:

Service-Based Businesses

Track per-hour or per-project billing.
Compute revenue, COS, and profit per month.
Generate capacity plans for workforce or resources.

Financial Analysis & Reporting

Monthly revenue, net income, and profit margin snapshots.
Integrate with accounting modules for forecasting.

Resource & Capacity Planning

Plan availability for staff, studios, or equipment.
Adjust capacity with recomputeCapacityPeriod or normalizeCapacityUnits.

Data Serialization & Integration

Export to JSON for APIs or database storage.
Deserialize JSON into functional service instances.

Best Practices

To maximize reliability, maintainability, and performance:

Use Chainable Setters

Always modify products via setter methods (setRate, addCOS, setCapacity) to ensure timestamps and finance recalculations are handled automatically.

Validate Before Finalization

Call validateSelf(true) before exporting or persisting the product to ensure all required fields are properly set.

Maintain Currency Consistency

All monetary operations use MajikMoney. Avoid mixing currencies; setter methods validate against product Rate currency.

Leverage Supply Plan Utilities

Use generateCapacityPlan, normalizeCapacityUnits, or recomputeCapacityPeriod to programmatically manage monthly supply rather than manually modifying arrays.

Keep COS Accurate

Always ensure unitCost and subtotal calculations are correct. Prefer addCOS or pushCOS instead of direct array mutation.

Minimize Finance Recomputations for Bulk Updates

When performing bulk updates to COS or supply, consider batching changes and calling recomputeFinance once at the end to avoid repeated expensive calculations.

Use Snapshots for Reporting

Use getMonthlySnapshot(month) for consistent monthly financial reporting and dashboards.

Error Handling

All setters throw on invalid input. Wrap critical updates in try/catch to handle edge cases gracefully.

Serialization & Deserialization

Use toJSON / finalize for exporting, and parseFromJSON for reconstruction. Avoid manually modifying the serialized object to prevent integrity issues.

Conclusion

MajikService provides a robust, chainable, financial-first approach to service management, suitable for enterprise-grade applications with detailed revenue, COS, and capacity planning needs.

Contributing

Contributions, bug reports, and suggestions are welcome! Feel free to fork and open a pull request.

License

ISC — free for personal and commercial use.

Author

Made with 💙 by @thezelijah

About the Developer

Developer: Josef Elijah Fabian
GitHub: https://github.com/jedlsf
Project Repository: https://github.com/jedlsf/majik-service

Contact

Business Email: [email protected]
Official Website: https://www.thezelijah.world