@heavybit/pendoadmin-shared-lib 1.0.0 → 1.1.1

package/src/scheduling/event-driven-scheduler.ts

@@ -0,0 +1,87 @@
+// pendoadmin-shared-lib/src/scheduling/event-driven-scheduler.ts
+//
+// Replaces naive setInterval polling with an event-driven pattern
+// that still has a safety-net fallback interval.
+
+import { EventEmitter } from "events";
+
+// ─── Types ──────────────────────────────────────────────
+
+export interface SchedulerOptions {
+  /** Human-readable name for logging (default: "scheduler") */
+  name?: string;
+  /** Safety-net fallback interval in ms (default: 60 000) */
+  fallbackIntervalMs?: number;
+  /** The work function to execute on each trigger */
+  work: () => Promise<void> | void;
+  /** Logger (default: console) */
+  logger?: Pick<Console, "debug" | "info" | "error">;
+}
+
+// ─── Scheduler ──────────────────────────────────────────
+
+export class EventDrivenScheduler extends EventEmitter {
+  private readonly name: string;
+  private readonly fallbackMs: number;
+  private readonly work: () => Promise<void> | void;
+  private readonly logger: Pick<Console, "debug" | "info" | "error">;
+
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private running = false;
+
+  constructor(options: SchedulerOptions) {
+    super();
+    this.name = options.name ?? "scheduler";
+    this.fallbackMs = options.fallbackIntervalMs ?? 60_000;
+    this.work = options.work;
+    this.logger = options.logger ?? console;
+  }
+
+  /** Start the safety-net interval. Does not run work immediately. */
+  start(): void {
+    if (this.timer) return;
+    this.logger.info(`[${this.name}] Started (fallback every ${this.fallbackMs}ms)`);
+    this.timer = setInterval(() => void this.execute(), this.fallbackMs);
+  }
+
+  /** Stop the scheduler and cancel the safety-net interval. */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+      this.logger.info(`[${this.name}] Stopped`);
+    }
+  }
+
+  /**
+   * Trigger work immediately (event-driven).
+   * De-duplicates: if work is already running, the call is silently skipped.
+   */
+  async trigger(): Promise<void> {
+    return this.execute();
+  }
+
+  /** Whether the scheduler is currently executing its work function. */
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  // ─── Internal ─────────────────────────────────────
+
+  private async execute(): Promise<void> {
+    if (this.running) {
+      this.logger.debug(`[${this.name}] Skipped — already running`);
+      return;
+    }
+    this.running = true;
+    try {
+      await this.work();
+      this.emit("done");
+    } catch (err: any) {
+      this.logger.error(`[${this.name}] Error: ${err.message}`);
+      this.emit("error", err);
+    } finally {
+      this.running = false;
+    }
+  }
+}

package/src/scheduling/index.ts

@@ -0,0 +1,2 @@
+export { EventDrivenScheduler } from "./event-driven-scheduler.js";
+export type { SchedulerOptions } from "./event-driven-scheduler.js";

package/src/socket/create-socket-server.ts

@@ -0,0 +1,112 @@
+// pendoadmin-shared-lib/src/socket/create-socket-server.ts
+//
+// Factory that creates a Socket.IO server with company-scoped rooms,
+// authentication, and convenience emitters.
+
+import { Server as HttpServer } from "http";
+import { Server, ServerOptions, Socket } from "socket.io";
+
+// ─── Types ──────────────────────────────────────────────
+
+export interface SocketServerOptions {
+  /** Room prefix used to namespace broadcasts (default: "company") */
+  roomPrefix?: string;
+  /** CORS origin list (default: ["*"]) */
+  corsOrigins?: string[];
+  /** Additional Socket.IO server options */
+  serverOptions?: Partial<ServerOptions>;
+  /** Logger — any object with debug / info / warn / error (default: console) */
+  logger?: Pick<Console, "debug" | "info" | "warn" | "error">;
+  /**
+   * Authenticate the incoming socket.
+   * Return truthy to allow, falsy or throw to reject.
+   * The decoded user should be attached to `socket.data.user`.
+   */
+  authenticate?: (socket: Socket) => Promise<boolean>;
+}
+
+export interface SocketEmitters {
+  /** Raw Socket.IO server instance */
+  io: Server;
+  /** Send to a specific room */
+  emitToRoom: (room: string, event: string, data: unknown) => void;
+  /** Send to a company-scoped room (roomPrefix:companyId) */
+  emitToCompany: (companyId: string | number, event: string, data: unknown) => void;
+  /** Broadcast to all connected clients */
+  emitGlobal: (event: string, data: unknown) => void;
+}
+
+// ─── Factory ────────────────────────────────────────────
+
+export function createSocketServer(
+  httpServer: HttpServer,
+  options: SocketServerOptions = {},
+): SocketEmitters {
+  const {
+    roomPrefix = "company",
+    corsOrigins = ["*"],
+    serverOptions = {},
+    logger = console,
+    authenticate,
+  } = options;
+
+  const io = new Server(httpServer, {
+    cors: { origin: corsOrigins, credentials: true },
+    ...serverOptions,
+  });
+
+  // ─── Authentication middleware ───────────────────────
+
+  if (authenticate) {
+    io.use(async (socket, next) => {
+      try {
+        const ok = await authenticate(socket);
+        if (!ok) return next(new Error("Authentication failed"));
+        next();
+      } catch (err: any) {
+        logger.warn(`[Socket] Auth rejected: ${err.message}`);
+        next(new Error("Authentication failed"));
+      }
+    });
+  }
+
+  // ─── Connection lifecycle ───────────────────────────
+
+  io.on("connection", (socket) => {
+    const userId = socket.data?.user?.id ?? socket.id;
+    logger.debug(`[Socket] Connected: ${userId}`);
+
+    // Auto-join the company room when the client provides a companyId
+    socket.on("join:company", (companyId: string | number) => {
+      const room = `${roomPrefix}:${companyId}`;
+      socket.join(room);
+      logger.debug(`[Socket] ${userId} joined ${room}`);
+    });
+
+    socket.on("leave:company", (companyId: string | number) => {
+      const room = `${roomPrefix}:${companyId}`;
+      socket.leave(room);
+      logger.debug(`[Socket] ${userId} left ${room}`);
+    });
+
+    socket.on("disconnect", (reason) => {
+      logger.debug(`[Socket] Disconnected: ${userId} (${reason})`);
+    });
+  });
+
+  // ─── Emitter helpers ────────────────────────────────
+
+  function emitToRoom(room: string, event: string, data: unknown): void {
+    io.to(room).emit(event, data);
+  }
+
+  function emitToCompany(companyId: string | number, event: string, data: unknown): void {
+    emitToRoom(`${roomPrefix}:${companyId}`, event, data);
+  }
+
+  function emitGlobal(event: string, data: unknown): void {
+    io.emit(event, data);
+  }
+
+  return { io, emitToRoom, emitToCompany, emitGlobal };
+}

package/src/socket/index.ts

@@ -0,0 +1,14 @@
+export {
+  createSocketServer,
+} from "./create-socket-server.js";
+export type {
+  SocketServerOptions,
+  SocketEmitters,
+} from "./create-socket-server.js";
+
+export {
+  BaseSocketGateway,
+} from "./nestjs-socket.module.js";
+export type {
+  NestSocketOptions,
+} from "./nestjs-socket.module.js";

package/src/socket/nestjs-socket.module.ts

@@ -0,0 +1,77 @@
+// pendoadmin-shared-lib/src/socket/nestjs-socket.module.ts
+//
+// Abstract base gateway for NestJS microservices that use Socket.IO.
+// Provides room management and typed emit helpers.
+
+import {
+  WebSocketGateway,
+  OnGatewayConnection,
+  OnGatewayDisconnect,
+  WebSocketServer,
+} from "@nestjs/websockets";
+import { Server, Socket } from "socket.io";
+
+// ─── Types ──────────────────────────────────────────────
+
+export interface NestSocketOptions {
+  /** Room prefix used to namespace broadcasts (default: "company") */
+  roomPrefix?: string;
+  /** Logger — any object with debug / info / warn / error (default: console) */
+  logger?: Pick<Console, "debug" | "info" | "warn" | "error">;
+}
+
+// ─── Base Gateway ───────────────────────────────────────
+
+@WebSocketGateway({ cors: { origin: "*" } })
+export abstract class BaseSocketGateway
+  implements OnGatewayConnection, OnGatewayDisconnect
+{
+  @WebSocketServer()
+  server!: Server;
+
+  protected readonly roomPrefix: string;
+  protected readonly logger: Pick<Console, "debug" | "info" | "warn" | "error">;
+
+  constructor(options: NestSocketOptions = {}) {
+    this.roomPrefix = options.roomPrefix ?? "company";
+    this.logger = options.logger ?? console;
+  }
+
+  // ─── Lifecycle ────────────────────────────────────
+
+  handleConnection(client: Socket): void {
+    const userId = (client as any).data?.user?.id ?? client.id;
+    this.logger.debug(`[WS] Connected: ${userId}`);
+
+    client.on("join:company", (companyId: string | number) => {
+      const room = `${this.roomPrefix}:${companyId}`;
+      client.join(room);
+      this.logger.debug(`[WS] ${userId} joined ${room}`);
+    });
+
+    client.on("leave:company", (companyId: string | number) => {
+      const room = `${this.roomPrefix}:${companyId}`;
+      client.leave(room);
+      this.logger.debug(`[WS] ${userId} left ${room}`);
+    });
+  }
+
+  handleDisconnect(client: Socket): void {
+    const userId = (client as any).data?.user?.id ?? client.id;
+    this.logger.debug(`[WS] Disconnected: ${userId}`);
+  }
+
+  // ─── Emit helpers ─────────────────────────────────
+
+  emitToRoom(room: string, event: string, data: unknown): void {
+    this.server.to(room).emit(event, data);
+  }
+
+  emitToCompany(companyId: string | number, event: string, data: unknown): void {
+    this.emitToRoom(`${this.roomPrefix}:${companyId}`, event, data);
+  }
+
+  emitGlobal(event: string, data: unknown): void {
+    this.server.emit(event, data);
+  }
+}

package/src/tenant/drizzle-tenant.ts

@@ -0,0 +1,51 @@
+// pendoadmin-shared-lib/src/tenant/drizzle-tenant.ts
+//
+// Drizzle ORM helper that builds reusable tenant WHERE clauses.
+
+import { eq, and, SQL } from "drizzle-orm";
+import type { Request, Response, NextFunction } from "express";
+
+// ─── Types ──────────────────────────────────────────────
+
+export interface TenantWhereHelper {
+  /** Standalone tenant filter — e.g. db.select().where(tw.where) */
+  where: SQL;
+  /** Combine tenant filter with additional conditions */
+  and: (...conditions: SQL[]) => SQL;
+}
+
+/**
+ * Create a reusable WHERE helper scoped to a single company.
+ *
+ * @param companyIdColumn - The Drizzle column reference (e.g. `users.companyId`)
+ * @param companyId       - The company / tenant ID value
+ */
+export function createTenantWhere(
+  companyIdColumn: any,
+  companyId: string | number,
+): TenantWhereHelper {
+  const tenantFilter = eq(companyIdColumn, companyId);
+
+  return {
+    where: tenantFilter,
+    and: (...conditions: SQL[]) => and(tenantFilter, ...conditions)!,
+  };
+}
+
+/**
+ * Express middleware that extracts companyId from `req.user` (set by
+ * auth middleware) and attaches a `tenantWhere` helper to the request.
+ *
+ * Usage:
+ *   app.use(tenantMiddleware(schema.users.companyId));
+ *   // Then in handlers: req.tenantWhere.where or req.tenantWhere.and(...)
+ */
+export function tenantMiddleware(companyIdColumn: any) {
+  return (req: Request, _res: Response, next: NextFunction) => {
+    const companyId = (req as any).user?.company_id;
+    if (companyId) {
+      (req as any).tenantWhere = createTenantWhere(companyIdColumn, companyId);
+    }
+    next();
+  };
+}

package/src/tenant/index.ts

@@ -0,0 +1,24 @@
+// Knex tenant scoping
+export { scopedKnex } from "./knex-tenant.js";
+export type { ScopedKnexOptions } from "./knex-tenant.js";
+
+// Drizzle tenant scoping
+export { createTenantWhere, tenantMiddleware } from "./drizzle-tenant.js";
+export type { TenantWhereHelper } from "./drizzle-tenant.js";
+
+// Tenant access control (feature gating)
+export {
+  createTenantAccessControl,
+  knexFeatureResolver,
+  knexCompanyActiveChecker,
+  getFeaturesForPlan,
+  provisionCompanyPlan,
+  clearFeatureCache,
+  invalidateCompanyFeatureCache,
+  DEFAULT_PLANS,
+} from "./tenant-access-control.js";
+export type {
+  Feature,
+  SubscriptionPlan,
+  TenantAccessControlConfig,
+} from "./tenant-access-control.js";

package/src/tenant/knex-tenant.ts

@@ -0,0 +1,59 @@
+// pendoadmin-shared-lib/src/tenant/knex-tenant.ts
+//
+// Proxy-based Knex wrapper that automatically applies
+//   WHERE company_id = ? to every query on the returned builder.
+
+import type { Knex } from "knex";
+
+export interface ScopedKnexOptions {
+  /** Column name for tenant isolation (default: "company_id") */
+  tenantColumn?: string;
+  /** Tables to exclude from automatic scoping */
+  excludeTables?: string[];
+}
+
+/**
+ * Returns a Proxy around `knex` that intercepts table calls and
+ * injects `.where(tenantColumn, companyId)`.
+ */
+export function scopedKnex(
+  knex: Knex,
+  companyId: string | number,
+  options: ScopedKnexOptions = {},
+): Knex {
+  const { tenantColumn = "company_id", excludeTables = [] } = options;
+  const excluded = new Set(excludeTables.map((t) => t.toLowerCase()));
+
+  return new Proxy(knex, {
+    apply(_target, _thisArg, args: [string, ...unknown[]]) {
+      const tableName = args[0];
+      const qb = knex(tableName);
+      if (typeof tableName === "string" && !excluded.has(tableName.toLowerCase())) {
+        return qb.where(`${tableName}.${tenantColumn}`, companyId);
+      }
+      return qb;
+    },
+    get(target, prop, receiver) {
+      if (prop === "raw" || prop === "schema" || prop === "destroy" || prop === "transaction") {
+        return Reflect.get(target, prop, receiver);
+      }
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function" && typeof prop === "string") {
+        return (...args: unknown[]) => {
+          const result = (value as Function).apply(target, args);
+          if (
+            result &&
+            typeof result === "object" &&
+            "where" in result &&
+            typeof args[0] === "string" &&
+            !excluded.has((args[0] as string).toLowerCase())
+          ) {
+            return result.where(`${args[0]}.${tenantColumn}`, companyId);
+          }
+          return result;
+        };
+      }
+      return value;
+    },
+  }) as unknown as Knex;
+}