deskforge 1.0.0

package/packages/notifications/dist/users.js

@@ -0,0 +1,87 @@
+"use strict";
+// users.ts
+// The Users selector system.
+// Used to pick recipients for Push, SMS, and Email.
+// Same selector works across all notification channels.
+// Mirrors the familiar WhatsApp/Facebook contact selection.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Users = void 0;
+exports.registerUser = registerUser;
+exports.unregisterUser = unregisterUser;
+exports.getAllUsers = getAllUsers;
+// Internal user registry
+// Populated by Auth system when users log in
+const userRegistry = new Map();
+// Registers a user in the registry
+// Called by the Auth system automatically
+function registerUser(user) {
+    userRegistry.set(user.id, user);
+}
+// Removes a user from the registry
+function unregisterUser(userId) {
+    userRegistry.delete(userId);
+}
+// Returns all registered users as array
+function getAllUsers() {
+    return Array.from(userRegistry.values());
+}
+// Selects one or more users by ID
+// Most common selector — used after ContactPicker
+function select(id) {
+    const ids = Array.isArray(id) ? id : [id];
+    const users = ids
+        .map(i => userRegistry.get(i))
+        .filter((u) => u !== undefined);
+    return { users, type: 'select' };
+}
+// Selects all registered users
+// Used for broadcasts
+function all() {
+    return {
+        users: getAllUsers(),
+        type: 'all'
+    };
+}
+// Selects users matching a property value
+// e.g. Users.where({ role: 'admin' })
+function where(criteria) {
+    const users = getAllUsers().filter(user => {
+        return Object.keys(criteria).every(key => {
+            return user[key] ===
+                criteria[key];
+        });
+    });
+    return { users, type: 'where' };
+}
+// Selects users belonging to a named group
+function group(groupName) {
+    const users = getAllUsers().filter(user => user.groups?.includes(groupName) ?? false);
+    return { users, type: 'group' };
+}
+// Selects all currently online users
+function online() {
+    const users = getAllUsers().filter(u => u.status === 'online');
+    return { users, type: 'online' };
+}
+// Selects all currently offline users
+function offline() {
+    const users = getAllUsers().filter(u => u.status === 'offline');
+    return { users, type: 'offline' };
+}
+// Selects everyone except the specified user
+function except(userId) {
+    const users = getAllUsers().filter(u => u.id !== userId);
+    return { users, type: 'select' };
+}
+// All selectors in one object
+const Users = {
+    select,
+    all,
+    where,
+    group,
+    online,
+    offline,
+    except,
+};
+exports.Users = Users;
+//# sourceMappingURL=users.js.map

package/packages/notifications/dist/users.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.js","sourceRoot":"","sources":["../src/users.ts"],"names":[],"mappings":"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"}

package/packages/notifications/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@deskforge/notifications",
+  "version": "1.0.0",
+  "description": "DeskForge notifications — Notify, Push, SMS, Email, Toast",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deskforge/deskforge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/deskforge/deskforge/issues"
+  },
+  "homepage": "https://github.com/deskforge/deskforge#readme",
+  "dependencies": {
+    "better-sqlite3": "^12.11.1"
+  }
+}

package/packages/notifications/src/alert.ts

@@ -0,0 +1,133 @@
+// alert.ts
+// In-app persistent alert banners.
+// Unlike Toast — Alert stays visible until dismissed.
+// Used for important state like offline mode or errors.
+// Rendered by Skia inside the component tree.
+
+// Alert severity levels
+type AlertType = 'success' | 'error' | 'warning' | 'info'
+
+// An alert configuration
+interface AlertConfig {
+  // Alert message
+  message: string
+
+  // Visual style
+  type: AlertType
+
+  // Whether user can close it
+  dismissible?: boolean
+
+  // Optional action button
+  action?: {
+    label:   string
+    onClick: () => void
+  }
+}
+
+import { NotificationStorage } from './storage'
+
+// Active alerts currently showing
+const activeAlerts: Map<string, AlertConfig> = new Map()
+
+// Listeners notified when alerts change
+const alertListeners: Set<() => void> = new Set()
+
+// Notifies all listeners
+function notifyListeners(): void {
+  alertListeners.forEach(l => l())
+}
+
+// Generates an alert ID
+function alertId(): string {
+  return 'alert_' + Math.random().toString(16).slice(2, 8)
+}
+
+// Shows a persistent alert
+// Returns ID for later dismissal
+function show(config: AlertConfig): string {
+  const id = alertId()
+  activeAlerts.set(id, config)
+  NotificationStorage.save({
+    id,
+    channel: 'alert',
+    type: config.type,
+    message: config.message,
+    payload: JSON.stringify({ dismissible: config.dismissible, action: config.action }),
+    createdAt: new Date().toISOString(),
+    expiresAt: null,
+    dismissed: false,
+  })
+  notifyListeners()
+  return id
+}
+
+// Dismisses a specific alert by ID
+function dismiss(id: string): void {
+  activeAlerts.delete(id)
+  NotificationStorage.dismiss(id)
+  notifyListeners()
+}
+
+// Dismisses all active alerts
+function dismissAll(): void {
+  activeAlerts.clear()
+  NotificationStorage.clearChannel('alert')
+  notifyListeners()
+}
+
+// Returns all active alerts
+function getActiveAlerts(): Map<string, AlertConfig> {
+  return activeAlerts
+}
+
+// Registers change listener
+function onAlertChange(listener: () => void): () => void {
+  alertListeners.add(listener)
+  return () => alertListeners.delete(listener)
+}
+
+function update(id: string, config: Partial<AlertConfig>): void {
+  const existing = activeAlerts.get(id)
+  if (!existing) return
+
+  const updated: AlertConfig = {
+    ...existing,
+    ...config,
+  }
+
+  activeAlerts.set(id, updated)
+  NotificationStorage.save({
+    id,
+    channel: 'alert',
+    type: updated.type,
+    message: updated.message,
+    payload: JSON.stringify({ dismissible: updated.dismissible, action: updated.action }),
+    createdAt: new Date().toISOString(),
+    expiresAt: null,
+    dismissed: false,
+  })
+  notifyListeners()
+}
+
+function countActiveAlerts(): number {
+  return activeAlerts.size
+}
+
+function getAlerts(): Array<{ id: string; alert: AlertConfig }> {
+  return Array.from(activeAlerts.entries()).map(([id, alert]) => ({ id, alert }))
+}
+
+const Alert = {
+  show,
+  update,
+  dismiss,
+  dismissAll,
+  getActiveAlerts,
+  getAlerts,
+  countActiveAlerts,
+  onAlertChange,
+}
+
+export type { AlertType, AlertConfig }
+export { Alert }

package/packages/notifications/src/email.ts

@@ -0,0 +1,127 @@
+// email.ts
+// Email notifications via your own SMTP server.
+// No SendGrid account. No Mailgun subscription.
+// Point to your own SMTP — Gmail, your VPS, anything.
+// DeskForge never sees your emails.
+
+import type { DFRecipientSet } from './users'
+
+// SMTP server configuration
+interface EmailConnectConfig {
+  // SMTP server hostname
+  host: string
+
+  // SMTP port — usually 587 for TLS or 465 for SSL
+  port?: number
+
+  // Your email address
+  user: string
+
+  // Your email password or app password
+  pass: string
+
+  // Whether to use secure connection
+  secure?: boolean
+}
+
+// An email to send
+interface EmailPayload {
+  // Recipients from Users selector or raw emails
+  to: DFRecipientSet | string | string[]
+
+  // Email subject line
+  subject: string
+
+  // Plain text body
+  body?: string
+
+  // HTML body — used if provided instead of body
+  html?: string
+
+  // Optional CC recipients
+  cc?: string[]
+
+  // Optional BCC recipients
+  bcc?: string[]
+
+  // Email attachments
+  attachments?: Array<{
+    filename: string
+    path:     string
+  }>
+}
+
+// An email template call
+interface EmailTemplatePayload {
+  // Template name
+  template: string
+
+  // Recipients
+  to: DFRecipientSet | string
+
+  // Data passed to the template
+  data: Record<string, unknown>
+}
+
+// Email connection state
+interface EmailState {
+  config: EmailConnectConfig | null
+}
+
+// Global email state
+const emailState: EmailState = {
+  config: null,
+}
+
+// Connects to an SMTP server
+// Must be called before send()
+function connect(config: EmailConnectConfig): void {
+  emailState.config = config
+  console.log('[DeskForge Email] Connected to', config.host)
+}
+
+// Sends an email to one or more recipients
+async function send(payload: EmailPayload): Promise<void> {
+  if (!emailState.config) {
+    console.error('[DeskForge Email] Not connected')
+    return
+  }
+
+  console.log('[DeskForge Email] Sending', payload)
+}
+
+// Sends an email using a named template
+// Templates are .html files in your project
+async function template(
+  payload: EmailTemplatePayload
+): Promise<void> {
+  if (!emailState.config) {
+    console.error('[DeskForge Email] Not connected')
+    return
+  }
+
+  console.log('[DeskForge Email] Template', payload)
+}
+
+// Returns current connection status
+function status(): { connected: boolean; host: string | null } {
+  return {
+    connected: emailState.config !== null,
+    host:      emailState.config?.host ?? null,
+  }
+}
+
+// All email functions in one object
+const Email = {
+  connect,
+  send,
+  template,
+  status,
+}
+
+export type {
+  EmailConnectConfig,
+  EmailPayload,
+  EmailTemplatePayload,
+}
+export { Email }

package/packages/notifications/src/index.ts

@@ -0,0 +1,44 @@
+// index.ts
+// Public door into the notifications package.
+// Import everything from here.
+
+// User recipient selector
+export * from './users'
+
+// OS native notifications
+export * from './notify'
+
+// WebSocket push notifications
+export * from './push'
+
+// SMS gateway
+export * from './sms'
+
+// SMTP email
+export * from './email'
+
+// In-app ephemeral toasts
+export * from './toast'
+
+// In-app persistent alerts
+export * from './alert'
+
+// Persistent notification storage
+export * from './storage'
+
+// Notification convenience namespace
+import * as ToastModule from './toast'
+import * as AlertModule from './alert'
+import * as NotifyModule from './notify'
+import * as PushModule from './push'
+import * as SMSModule from './sms'
+import * as EmailModule from './email'
+
+export const Notifications = {
+  Toast: ToastModule.Toast,
+  Alert: AlertModule.Alert,
+  Notify: NotifyModule.Notify,
+  Push: PushModule.Push,
+  SMS: SMSModule.SMS,
+  Email: EmailModule.Email,
+}

package/packages/notifications/src/notify.ts

@@ -0,0 +1,126 @@
+// notify.ts
+// OS native notifications.
+// Talks directly to the OS notification system.
+// Win32 Toast on Windows, NSNotification on macOS,
+// libnotify on Linux, UNNotification on iOS,
+// NotificationManager on Android.
+// Zero configuration. Zero third-party accounts.
+
+// Configuration for an OS notification
+interface NotifyConfig {
+  // Main notification title
+  title: string
+
+  // Notification body message
+  body: string
+
+  // Path to icon image
+  icon?: string
+
+  // Action buttons shown on the notification
+  actions?: Array<{
+    label:   string
+    onClick: () => void
+  }>
+
+  // Play a sound when notification appears
+  sound?: 'default' | string
+
+  // Stay visible until dismissed
+  persistent?: boolean
+}
+
+// Configuration for a scheduled notification
+interface ScheduleConfig extends NotifyConfig {
+  // Delay before showing e.g. '5m', '1h', '2d'
+  delay?: string
+
+  // Exact time to show e.g. '09:00'
+  at?: string
+
+  // Repeat interval e.g. 'daily', 'weekly'
+  repeat?: 'daily' | 'weekly' | 'monthly'
+}
+
+// Configuration for a progress notification
+interface ProgressConfig {
+  // Notification title
+  title: string
+
+  // Total steps or percentage max
+  total: number
+
+  // Current progress value
+  current: number
+}
+
+// Internal notification queue
+const scheduledNotifications: Map<string, ScheduleConfig> =
+  new Map()
+
+// Sends an OS native notification immediately
+// The actual OS call happens in the Sovereign layer
+function send(
+  title:   string,
+  body:    string,
+  options?: Partial<NotifyConfig>
+): void {
+  const config: NotifyConfig = {
+    title,
+    body,
+    ...options,
+  }
+
+  // In production this calls the native OS notification API
+  // via the Sovereign layer bridge
+  console.log('[DeskForge Notify]', config)
+}
+
+// Schedules a notification for a future time
+// Returns an ID that can be used to cancel it
+function schedule(
+  title:   string,
+  options: Omit<ScheduleConfig, 'title' | 'body'> & { body?: string }
+): string {
+  const id = 'notif_' + Math.random().toString(16).slice(2, 8)
+
+  const config: ScheduleConfig = {
+    title,
+    body: options.body ?? '',
+    ...options,
+  }
+
+  scheduledNotifications.set(id, config)
+
+  // In production this registers with the OS scheduler
+  console.log('[DeskForge Schedule]', id, config)
+
+  return id
+}
+
+// Cancels a scheduled notification by ID
+function cancel(id: string): void {
+  scheduledNotifications.delete(id)
+  console.log('[DeskForge Cancel]', id)
+}
+
+// Shows a notification with a progress bar
+// Call again with updated current to update the bar
+function progress(
+  title:   string,
+  config:  Omit<ProgressConfig, 'title'>
+): void {
+  const full: ProgressConfig = { title, ...config }
+  console.log('[DeskForge Progress]', full)
+}
+
+// All notify functions in one object
+const Notify = {
+  send,
+  schedule,
+  cancel,
+  progress,
+}
+
+export type { NotifyConfig, ScheduleConfig, ProgressConfig }
+export { Notify, send, schedule, cancel, progress }

package/packages/notifications/src/push.ts

@@ -0,0 +1,145 @@
+// push.ts
+// WebSocket-based push notifications.
+// Connects to YOUR server — no Firebase, no OneSignal.
+// Developer runs their own WebSocket server.
+// Use: npm deskforge generate push-server
+// to get a ready-to-run push server for free.
+
+import type { DFRecipientSet } from './users'
+
+// Configuration for connecting to push server
+interface PushConnectConfig {
+  // Your WebSocket server URL
+  // e.g. 'ws://192.168.1.5:8080' or 'wss://myserver.com'
+  server: string
+
+  // Optional reconnect settings
+  reconnect?: {
+    enabled:  boolean
+    maxRetries: number
+    delay:    number  // milliseconds between retries
+  }
+}
+
+// A push notification payload
+interface PushPayload {
+  // Who receives this notification
+  to: DFRecipientSet
+
+  // Notification title
+  title: string
+
+  // Notification body
+  body: string
+
+  // Extra data passed to onTap handler
+  // e.g. { screen: 'chat', chatId: 5 }
+  data?: Record<string, unknown>
+}
+
+// An incoming push notification
+interface IncomingPush {
+  title:     string
+  body:      string
+  data?:     Record<string, unknown>
+  timestamp: number
+  from?:     string
+}
+
+// Push connection state
+interface PushState {
+  socket:     WebSocket | null
+  connected:  boolean
+  config:     PushConnectConfig | null
+  onReceive:  ((notif: IncomingPush) => void) | null
+  onTap:      ((notif: IncomingPush) => void) | null
+}
+
+// Global push state
+const pushState: PushState = {
+  socket:    null,
+  connected: false,
+  config:    null,
+  onReceive: null,
+  onTap:     null,
+}
+
+// Connects to your WebSocket push server
+function connect(config: PushConnectConfig): void {
+  pushState.config = config
+
+  // In production this creates a real WebSocket connection
+  // For now we log the intent
+  console.log('[DeskForge Push] Connecting to', config.server)
+
+  pushState.connected = true
+}
+
+// Registers this device with a user ID
+// Server uses this to route messages to this device
+function register(options: { userId: string }): void {
+  console.log('[DeskForge Push] Registering', options.userId)
+}
+
+// Sends a push notification to recipients
+// Routes through your WebSocket server
+async function send(payload: PushPayload): Promise<void> {
+  if (!pushState.connected) {
+    console.error('[DeskForge Push] Not connected')
+    return
+  }
+
+  console.log('[DeskForge Push] Sending', payload)
+}
+
+// Sends to all registered users
+async function broadcast(options: {
+  title: string
+  body:  string
+  data?: Record<string, unknown>
+}): Promise<void> {
+  console.log('[DeskForge Push] Broadcasting', options)
+}
+
+// Registers handler for incoming notifications
+function onReceive(
+  handler: (notif: IncomingPush) => void
+): void {
+  pushState.onReceive = handler
+}
+
+// Registers handler for when user taps a notification
+function onTap(
+  handler: (notif: IncomingPush) => void
+): void {
+  pushState.onTap = handler
+}
+
+// Disconnects from push server
+function disconnect(): void {
+  pushState.connected = false
+  pushState.socket    = null
+  console.log('[DeskForge Push] Disconnected')
+}
+
+// Reconnects after losing connection
+function reconnect(): void {
+  if (pushState.config) {
+    connect(pushState.config)
+  }
+}
+
+// All push functions in one object
+const Push = {
+  connect,
+  register,
+  send,
+  broadcast,
+  onReceive,
+  onTap,
+  disconnect,
+  reconnect,
+}
+
+export type { PushConnectConfig, PushPayload, IncomingPush }
+export { Push }