Majik Notification

Majik Notification is a lightweight, framework-agnostic notification model designed for modern applications.
It works seamlessly across web apps, mobile apps, desktop apps, backend services, and edge environments.

Built as part of the Majikah ecosystem (and powering Majik Message), it provides a clean, JSON-safe way to create, manage, serialize, and react to notifications — without coupling your app to any UI framework or delivery mechanism.

---

• Majik Notification
  • Features
  • Installation
  • Usage
    • Creating a Notification
    • Initializing a Notification for a User
    • Metadata
      • Supported Metadata Fields
    • Actions (Event Triggers)
    • Updating Notification State
      • Mark as Read
      • Mark as Unread
      • Check Read State
    • Accessing Actions
    • Serialization (Saving & Sending)
      • Example JSON
    • Parsing & Hydration
  • Best Practices
  • What This Package Does NOT Do
  • Use Cases
  • Contributing
  • License
  • Author
  • About the Developer
  • Contact

---

Features

• Cross-platform (Web, Mobile, Desktop, Backend, Edge)
• Framework-agnostic (React, Vue, Electron, Workers, etc.)
• JSON-safe serialization for APIs, databases, and queues
• Action-based events (trigger app logic without embedding functions)
• Extensible metadata for future-proofing
• Read / unread state handling
• Type-safe with full TypeScript support
• Auto-generated IDs (optional)

---

Installation

npm install @thezelijah/majik-notification

---

Usage

import { MajikNotification } from "@thezelijah/majik-notification";

Creating a Notification

const notification = new MajikNotification({
  type: "message",
  userID: "user_123",
  message: "You received a new message",
});

If no id is provided, one is auto-generated.

Initializing a Notification for a User

const notification = new MajikNotification({
  type: "security",
  userID: currentUser.id,
  message: "New device signed in",
  metadata: {
    priority: "high",
    user: {
      id: "system",
      name: "Majikah Security",
    },
  },
});

Each notification always belongs to one user (userID).

Metadata

metadata: {
  priority: "normal",
  user: {
    id: "user_456",
    name: "Zef",
    photo: "https://thezelijah.world/avatar.png",
  },
  body: {
    title: "New Message",
    externalURL: "/messages/123",
  },
  references: ["message_123", "conversation_456"],
}

Supported Metadata Fields

Field	Purpose
priority	UI or delivery importance
user	Sender or related user info
body	UI display hints
references	IDs related to the event
actions	Triggerable actions
*	Any custom app-specific data

Actions (Event Triggers)

Actions are data-only descriptors that map to runtime behavior.

metadata: {
  actions: [
    {
      label: "Open Conversation",
      action: "open-conversation",
      url: "/messages/123"
    }
  ]
}

⚠️ Actions are not functions. They are resolved at runtime via an action registry or handler system.

This keeps notifications:

• Serializable
• Secure
• Portable across environments

Updating Notification State

Mark as Read

notification.markAsRead();

Mark as Unread

notification.markAsUnread();

Check Read State

if (notification.isRead()) {
  // do something
}

Accessing Actions

actions.forEach(action => {
  console.log(action.label, action.action);
});

// or use getActions

myNotification.getActions()

Serialization (Saving & Sending)

const json = notification.toJSON();

This output is safe for:

• Databases
• APIs
• Realtime channels
• Message queues

Example JSON

{
  "id": "notif_abc123",
  "type": "message",
  "userID": "user_123",
  "message": "You received a new message",
  "readAt": null,
  "timestamp": "2026-01-25T12:34:56.000Z",
  "metadata": {
    "priority": "normal"
  }
}

Parsing & Hydration

const notification = MajikNotification.fromJSON(json);

Supports:

• Plain objects
• JSON strings
• Stored DB records
• API payloads

Invalid or malformed dates are safely handled.

---

Best Practices

• Store notifications as JSON
• Bind action handlers at app startu
• Use references for deep-linking
• Avoid embedding business logic in metadata
• Treat notifications as immutable events + mutable state

---

What This Package Does NOT Do

• ❌ Push notifications

• ❌ Email delivery

• ❌ UI rendering

• ❌ Action execution logic

This is intentional — Majik Notification is a core domain primitive, not a UI or transport layer.

---

Use Cases

• In-app notifications
• Messaging alerts
• Security warnings
• System updates
• Social interactions
• Billing events
• Desktop & Electron apps
• Edge & serverless environments

---

Contributing

If you want to contribute or help extend support to more platforms, reach out via email. All contributions are welcome!

---

License

Apache-2.0 — 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-notification

---

Contact

• Business Email: business@thezelijah.world
• Official Website: https://www.thezelijah.world