@broxium/apps-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import type { DynamicModule, Type } from "@nestjs/common";
+export declare const BRODOX_SHARED = "BRODOX_SHARED";
+export declare type BusHandler = (params: unknown, context: BusCallContext) => Promise<unknown>;
+export interface BusCallContext {
+    callerSlug: string;
+    tenantId?: number;
+}
+export interface AppBusAdapter {
+    /**
+     * Register a named function that other apps can call.
+     * Call this inside onApplicationBootstrap so the service is fully initialized.
+     *
+     * @param event  unique name within this app (e.g. 'send-sms')
+     * @param handler function to run when this event is called
+     */
+    defineEvent(event: string, handler: BusHandler): void;
+    /**
+     * Call a named function on another app.
+     * If the target app is idle (evicted), it will be automatically re-mounted first.
+     *
+     * @param targetSlug  the slug of the app to call (e.g. 'quicksms')
+     * @param event       the event name registered in that app
+     * @param params      any data to pass to the handler
+     */
+    call(targetSlug: string, event: string, params?: unknown): Promise<unknown>;
+}
+export interface CacheHelper {
+    get<T>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    forget(key: string): Promise<void>;
+    remember<T>(key: string, ttl: number, fn: () => Promise<T>): Promise<T>;
+}
+export interface BrodoxSharedContainer {
+    /**
+     * Resolve any registered resource by key.
+     * Throws if the key is not registered.
+     *
+     * @example
+     *   const redis = shared.resolve<Redis>('redis');
+     *   const myDb  = shared.resolve<PrismaClient>('prisma:brodox');
+     */
+    resolve<T>(key: string): T;
+    /**
+     * Check if a resource is registered before resolving.
+     */
+    has(key: string): boolean;
+    cache: CacheHelper;
+    bus: AppBusAdapter;
+}
+export interface BrodoxAppManifest {
+    slug: string;
+    name: string;
+    description: string;
+    version: string;
+    module: Type<unknown> | DynamicModule | ((shared: BrodoxSharedContainer) => Type<unknown> | DynamicModule);
+    requires?: string[];
+}
+/** Type-safe helper — just enables IDE autocomplete for the manifest. */
+export declare function defineApp(m: BrodoxAppManifest): BrodoxAppManifest;

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineApp = exports.BRODOX_SHARED = void 0;
+// ─────────────────────────────────────────────────────────────────────────────
+// INJECT TOKEN
+// Sub-apps use this to receive the shared container from the core.
+// Usage inside a sub-app service:
+//   constructor(@Inject(BRODOX_SHARED) private readonly shared: BrodoxSharedContainer) {}
+// ─────────────────────────────────────────────────────────────────────────────
+exports.BRODOX_SHARED = "BRODOX_SHARED";
+/** Type-safe helper — just enables IDE autocomplete for the manifest. */
+function defineApp(m) {
+    return m;
+}
+exports.defineApp = defineApp;

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@broxium/apps-sdk",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "ioredis": "^5.10.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+import type { DynamicModule, Type } from "@nestjs/common";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// INJECT TOKEN
+// Sub-apps use this to receive the shared container from the core.
+// Usage inside a sub-app service:
+//   constructor(@Inject(BRODOX_SHARED) private readonly shared: BrodoxSharedContainer) {}
+// ─────────────────────────────────────────────────────────────────────────────
+export const BRODOX_SHARED = "BRODOX_SHARED";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BUS SYSTEM
+// Allows one sub-app to call another sub-app's named functions.
+// The target app is automatically woken up (lazy-mounted) if it was sleeping.
+//
+// DEFINE (inside the target app's onApplicationBootstrap):
+//   shared.bus.defineEvent('send-sms', async (opts) => { return smsSvc.send(opts); });
+//
+// CALL (from any app or from the core):
+//   const result = await shared.bus.call('quicksms', 'send-sms', { phone: '...', msg: '...' });
+// ─────────────────────────────────────────────────────────────────────────────
+export type BusHandler = (
+  params: unknown,
+  context: BusCallContext,
+) => Promise<unknown>;
+
+export interface BusCallContext {
+  callerSlug: string; // who is calling
+  tenantId?: number; // the current tenant (if any)
+}
+
+export interface AppBusAdapter {
+  /**
+   * Register a named function that other apps can call.
+   * Call this inside onApplicationBootstrap so the service is fully initialized.
+   *
+   * @param event  unique name within this app (e.g. 'send-sms')
+   * @param handler function to run when this event is called
+   */
+  defineEvent(event: string, handler: BusHandler): void;
+
+  /**
+   * Call a named function on another app.
+   * If the target app is idle (evicted), it will be automatically re-mounted first.
+   *
+   * @param targetSlug  the slug of the app to call (e.g. 'quicksms')
+   * @param event       the event name registered in that app
+   * @param params      any data to pass to the handler
+   */
+  call(targetSlug: string, event: string, params?: unknown): Promise<unknown>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SHARED CONTAINER
+// This is the single bag of shared resources every sub-app receives.
+// The core registers resources here; sub-apps read them.
+//
+// Built-in keys the core always provides:
+//   resolve<Redis>('redis')       → shared ioredis client
+//   resolve<CacheHelper>('cache') → cache wrapper (remember, get, set, forget)
+//   resolve<any>('prisma:brodox') → shared Prisma client (when you wire it)
+//   resolve<any>('prisma:substores')
+//
+// You can register ANYTHING: functions, class instances, Prisma clients, RabbitMQ...
+//   (from main.ts or SharedResourcesProvider.onModuleInit)
+//   shared.register('rabbitmq', rabbitMQClient);
+//   shared.register('stripe',   stripeClient);
+// ─────────────────────────────────────────────────────────────────────────────
+export interface CacheHelper {
+  get<T>(key: string): Promise<T | null>;
+  set(key: string, value: unknown, ttl?: number): Promise<void>;
+  forget(key: string): Promise<void>;
+  remember<T>(key: string, ttl: number, fn: () => Promise<T>): Promise<T>;
+}
+
+export interface BrodoxSharedContainer {
+  /**
+   * Resolve any registered resource by key.
+   * Throws if the key is not registered.
+   *
+   * @example
+   *   const redis = shared.resolve<Redis>('redis');
+   *   const myDb  = shared.resolve<PrismaClient>('prisma:brodox');
+   */
+  resolve<T>(key: string): T;
+
+  /**
+   * Check if a resource is registered before resolving.
+   */
+  has(key: string): boolean;
+
+  // Convenient direct references (most apps only need these two)
+  cache: CacheHelper;
+  bus: AppBusAdapter;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// APP MANIFEST
+// Every app's dist/index.js must export a manifest of this shape.
+//
+// The module field can be:
+//   - A static NestJS module class: module: PosProModule
+//   - A factory that receives shared resources: module: (s) => PosProModule.withShared(s)
+//
+// Use the factory form so your app gets DB/Redis/bus from the core.
+// ─────────────────────────────────────────────────────────────────────────────
+export interface BrodoxAppManifest {
+  slug: string;
+  name: string;
+  description: string;
+  version: string;
+  module:
+    | Type<unknown>
+    | DynamicModule
+    | ((shared: BrodoxSharedContainer) => Type<unknown> | DynamicModule);
+  requires?: string[]; // optional: list of resource keys this app needs from core
+}
+
+/** Type-safe helper — just enables IDE autocomplete for the manifest. */
+export function defineApp(m: BrodoxAppManifest): BrodoxAppManifest {
+  return m;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es2021",
+    "module": "commonjs",
+    "outDir": "./dist",
+    "declaration": true,
+    "strict": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}