{"_id":"@cobranza-apps/mfe-events","_rev":"5-75e094476d0d09b327380df281f7775b","name":"@cobranza-apps/mfe-events","dist-tags":{"latest":"0.6.0"},"versions":{"0.3.2":{"name":"@cobranza-apps/mfe-events","version":"0.3.2","_id":"@cobranza-apps/mfe-events@0.3.2","maintainers":[{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"}],"dist":{"shasum":"a7b57547e0b2a759f6b67eb69132bb63a2c4081c","tarball":"https://registry.npmjs.org/@cobranza-apps/mfe-events/-/mfe-events-0.3.2.tgz","fileCount":50,"integrity":"sha512-cxjcriUXfZb3xB735G+hfPEdAQkIwZIZ5xpPnAegAiee4ERJaXrOLSlhtm4fmn3gIqTYZV9A2tZs4J1GZOAEPw==","signatures":[{"sig":"MEUCIQDazoApJxqH82dKXlN2gRaPSpMPXqqilu/tTUAzp4FSPQIgcLUmyptt8MiuSJIUaGhRpdLjk2J9QuyNgK6rsZhO+vo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":93050},"main":"./dist/public-api.js","type":"module","types":"./dist/public-api.d.ts","module":"./dist/public-api.js","engines":{"node":">=22.22.3"},"exports":{".":{"types":"./dist/public-api.d.ts","import":"./dist/public-api.js","default":"./dist/public-api.js"}},"gitHead":"4d807b95379d67f13deb04d4ad7de69be8ea91d5","scripts":{"test":"vitest run","build":"tsc","clean":"rimraf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"},"_npmVersion":"10.9.8","description":"Typed event contracts and helpers for communication between the Cobranza Company Back-office Shell and its micro-frontends.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.3","dependencies":{"class-validator":"0.15.1","reflect-metadata":"0.2.2","class-transformer":"0.5.1"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"4.1.10","typescript":"^5.8.0"},"_npmOperationalInternal":{"tmp":"tmp/mfe-events_0.3.2_1785626218765_0.996454038295326","host":"s3://npm-registry-packages-npm-production"}},"0.3.3":{"name":"@cobranza-apps/mfe-events","version":"0.3.3","_id":"@cobranza-apps/mfe-events@0.3.3","maintainers":[{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"}],"dist":{"shasum":"a39214da5fb017151b2a16e16942abc31c90673b","tarball":"https://registry.npmjs.org/@cobranza-apps/mfe-events/-/mfe-events-0.3.3.tgz","fileCount":49,"integrity":"sha512-zZvksWCdwBRmQ1/0Ufj0LrTkA/94m19OUF/yDfUWADvx4rTZSMqkEDQlT6+lgdayP5cs3kza16Ik/yxwYzBGYg==","signatures":[{"sig":"MEYCIQC5gm3yONIhhlgH9s37IQD7Oux/WZVgWkHyrfyVKx7SawIhAOuXHagUMFHg7/GMlJL7EzO11N+jLR1QVCc3GT/TBgUN","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":91468},"main":"./dist/public-api.js","type":"module","types":"./dist/public-api.d.ts","module":"./dist/public-api.js","engines":{"node":">=22.22.3"},"exports":{".":{"types":"./dist/public-api.d.ts","import":"./dist/public-api.js","default":"./dist/public-api.js"}},"gitHead":"582a5a9a7ccef8abcb5c323825c9d65fe88c4577","scripts":{"test":"vitest run","build":"tsc","clean":"rimraf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"},"_npmVersion":"10.9.8","description":"Typed event contracts and helpers for communication between the Cobranza Company Back-office Shell and its micro-frontends.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.3","dependencies":{"class-validator":"0.15.1","reflect-metadata":"0.2.2","class-transformer":"0.5.1"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"4.1.10","typescript":"^5.8.0"},"_npmOperationalInternal":{"tmp":"tmp/mfe-events_0.3.3_1785626341856_0.16633471933832444","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@cobranza-apps/mfe-events","version":"0.4.0","_id":"@cobranza-apps/mfe-events@0.4.0","maintainers":[{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"}],"dist":{"shasum":"c22d76383a98184e9520ca1e7725ce0bb452aeaa","tarball":"https://registry.npmjs.org/@cobranza-apps/mfe-events/-/mfe-events-0.4.0.tgz","fileCount":50,"integrity":"sha512-qm0kj+y157ti+Y6ldJIJ1BbP/x8hfSTdbDDKLnWf5m9icP9ZecD7iJ2aO/zT6olzM3N7X5ZNbJvrJvtTVj6caw==","signatures":[{"sig":"MEQCIBAGxYw3e+TqUiKgI2CG9zNeNYM7D2owlHA3XWFV2N7vAiAKIpPMiXK3cQuQKhD/pRkXYxk9KqWOhrU6hjrDEASsdA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":97790},"main":"./dist/public-api.js","type":"module","types":"./dist/public-api.d.ts","module":"./dist/public-api.js","engines":{"node":">=22.22.3"},"exports":{".":{"types":"./dist/public-api.d.ts","import":"./dist/public-api.js","default":"./dist/public-api.js"}},"gitHead":"cb93c7f3e678e3770ea1277851843220bc5c11bc","scripts":{"test":"vitest run","build":"tsc","clean":"rimraf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"},"_npmVersion":"10.9.8","description":"Typed event contracts and helpers for communication between the Cobranza Company Back-office Shell and its micro-frontends.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.3","dependencies":{"class-validator":"0.15.1","reflect-metadata":"0.2.2","class-transformer":"0.5.1"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"4.1.10","typescript":"^5.8.0"},"_npmOperationalInternal":{"tmp":"tmp/mfe-events_0.4.0_1786233101417_0.1920367490751249","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@cobranza-apps/mfe-events","version":"0.5.0","_id":"@cobranza-apps/mfe-events@0.5.0","maintainers":[{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"}],"dist":{"shasum":"37974a9b90f78d30cc3ae368f21a29806c798201","tarball":"https://registry.npmjs.org/@cobranza-apps/mfe-events/-/mfe-events-0.5.0.tgz","fileCount":53,"integrity":"sha512-mkjsxB6a+pmNpikS4Jrl7c0xN8SyLlXaXP15XGUPc0nxKFYx20h16P+zwgQdlp6s7YO6WigaIo5zFg25GZzIPg==","signatures":[{"sig":"MEQCIC7Slh9gcQWUWtjKWjKUzvJo5lfiTgrwethT88bEkUgJAiA5Gps3Igrxhw3MZq5HoZBAIOZx/r59O8ZQC3wrSNQ67w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":111252},"main":"./dist/public-api.js","type":"module","types":"./dist/public-api.d.ts","module":"./dist/public-api.js","engines":{"node":">=22.22.3"},"exports":{".":{"types":"./dist/public-api.d.ts","import":"./dist/public-api.js","default":"./dist/public-api.js"}},"gitHead":"0c58a1a3f65215d4e03bfc6b257193fc87e23504","scripts":{"test":"vitest run","build":"tsc","clean":"rimraf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"},"_npmVersion":"10.9.8","description":"Typed event contracts and helpers for communication between the Cobranza Company Back-office Shell and its micro-frontends.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.3","dependencies":{"class-validator":"0.15.1","class-transformer":"0.5.1"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^6.0.1","vitest":"4.1.10","typescript":"^5.8.0","reflect-metadata":"0.2.2"},"peerDependencies":{"reflect-metadata":"^0.1.12 || ^0.2.0"},"peerDependenciesMeta":{"reflect-metadata":{"optional":false}},"_npmOperationalInternal":{"tmp":"tmp/mfe-events_0.5.0_1787070772664_0.2466179884881865","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@cobranza-apps/mfe-events","version":"0.6.0","description":"Typed event contracts and helpers for communication between the Cobranza Company Back-office Shell and its micro-frontends.","type":"module","sideEffects":false,"main":"./dist/public-api.js","module":"./dist/public-api.js","types":"./dist/public-api.d.ts","exports":{".":{"types":"./dist/public-api.d.ts","import":"./dist/public-api.js","default":"./dist/public-api.js"}},"engines":{"node":">=22.22.3"},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","clean":"rimraf dist","test":"vitest run","test:watch":"vitest"},"dependencies":{"class-transformer":"0.5.1","class-validator":"0.15.1"},"peerDependencies":{"reflect-metadata":"^0.1.12 || ^0.2.0"},"peerDependenciesMeta":{"reflect-metadata":{"optional":false}},"devDependencies":{"reflect-metadata":"0.2.2","typescript":"^5.8.0","rimraf":"^6.0.1","vitest":"4.1.10"},"_id":"@cobranza-apps/mfe-events@0.6.0","gitHead":"01dbbcaf4f375591769d562a98631a71c1011c9c","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-5/apLi5u8ycl+icfuQJtnRN5mlFh9zcdejT2NTD+orbrxf5mf/4F4knmyyPadIPA36a2Yszb00NJb1pEd1y+qA==","shasum":"c285d1189aff9cce23641d8b3b83976616e353fc","tarball":"https://registry.npmjs.org/@cobranza-apps/mfe-events/-/mfe-events-0.6.0.tgz","fileCount":53,"unpackedSize":118895,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCZ5OHT7I23M6dtmJby02S2WqknlsYW2pRuwlrI+n47fQIhAOvy4XicjMrFbBrYYoEDxkXj2GpaQ58SUfDqIHdPwO3r"}]},"_npmUser":{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"},"directories":{},"maintainers":[{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mfe-events_0.6.0_1787682163636_0.59656484964532"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-01T23:16:58.638Z","modified":"2026-08-25T18:22:43.984Z","0.3.2":"2026-08-01T23:16:58.906Z","0.3.3":"2026-08-01T23:19:02.001Z","0.4.0":"2026-08-08T23:51:41.569Z","0.5.0":"2026-08-18T16:32:52.914Z","0.6.0":"2026-08-25T18:22:43.800Z"},"description":"Typed event contracts and helpers for communication between the Cobranza Company Back-office Shell and its micro-frontends.","maintainers":[{"name":"kazuyakuza","email":"kazuya_otaku.clan@hotmail.com"}],"readme":"# @cobranza-apps/mfe-events\n\nTypeScript contract library for Shell–MFE communication.\n\n## Table of Contents\n\n- [Purpose](#purpose)\n- [Installation](#installation)\n- [Runtime Setup](#runtime-setup)\n- [Quick Usage](#quick-usage)\n- [Event Catalog](#event-catalog)\n- [Design Principles](#design-principles)\n- [Tech Stack](#tech-stack)\n- [Development Scripts](#development-scripts)\n- [Documentation](#documentation)\n- [Development & Contributing (for AI Agents)](#development--contributing-for-ai-agents)\n- [Related Packages](#related-packages)\n\n## Purpose\n\n- Named event constants: `MFE_EVENTS`, `SHELL_EVENTS` with stable `mfe:` / `shell:` prefixes.\n- Strongly typed payload interfaces and `EventMap` types for type-safe dispatch and listen.\n- Thin type-level + runtime helpers over the browser `CustomEvent` / `window` APIs:\n  `createMfeEvent`, `createShellEvent`, `isMfeEvent`, `isShellEvent`.\n- JSDoc + copy-paste usage examples on every public export.\n- Does NOT provide: an event bus or RxJS subjects, Angular services/components/DI, workspace layout logic, BFF/API communication, UI chrome (owned by `@cobranza-apps/ui`), or DOM manipulation by MFEs outside their own container.\n- Core rule: MFEs dispatch `mfe:*`; only the Shell listens. The Shell pushes info to MFEs via Angular Inputs and/or `shell:*` events.\n\n## Installation\n\n> Package manager and registry are not yet finalized (see `.agent/project-info/tech.md`). Once published, install with the adopted manager:\n\n```bash\n# npm\nnpm install @cobranza-apps/mfe-events\n\n# pnpm\npnpm add @cobranza-apps/mfe-events\n```\n\nNo Angular peer dependency is required. TypeScript 5.x and a modern browser `CustomEvent`/`window` API are the only runtime expectations.\n\n## Runtime Setup\n\n`@cobranza-apps/mfe-events` uses `class-validator` decorators internally. The library **does not bundle `reflect-metadata`** — you must load it in your application entry. The correct loading strategy depends on your environment.\n\n### Angular Projects (with esbuild / Vite / Native Federation)\n\nAdd `reflect-metadata` as a global script in `angular.json` (or equivalent builder config):\n\n```json\n{\n  \"projects\": {\n    \"shell\": {\n      \"architect\": {\n        \"build\": {\n          \"options\": {\n            \"scripts\": [\n              \"node_modules/reflect-metadata/Reflect.js\"\n            ]\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nDo **not** use `import 'reflect-metadata';` in `src/main.ts` — it will fail in ESM environments because `reflect-metadata` is CommonJS-only and ESM module shims cannot resolve the specifier.\n\n### Node.js / Test Environments\n\nImport the polyfill directly in your test setup file:\n\n```ts\n// test-setup.ts\nimport 'reflect-metadata';\n```\n\nOr configure your test runner (Vitest, Jest) to load it before specs — see [docs/examples/vitest-setup.md](docs/examples/vitest-setup.md) and [docs/examples/jest-setup.md](docs/examples/jest-setup.md).\n\n### Why Two Different Ways?\n\n`reflect-metadata` is a CommonJS package. ESM module shims (used by Native Federation, Vite dev server) cannot resolve CommonJS specifiers. The Angular application builder's `scripts` array loads it as a traditional global script before bootstrap, which works in all browser environments. In Node/test runners the CommonJS package resolves natively, so a direct `import` is fine.\n\n> Concrete copy-paste examples: [docs/examples/angular-setup.md](docs/examples/angular-setup.md).\n> Common errors and fixes: [docs/troubleshooting.md](docs/troubleshooting.md).\n\n## Quick Usage\n\n**MFE dispatch (from the MFE side):**\n\n```ts\nimport {\n  MFE_EVENTS,\n  SCHEMA_VERSION,\n  dispatchMfeEvent,\n  type UpdateHeaderPayload,\n} from '@cobranza-apps/mfe-events';\n\nconst detail: UpdateHeaderPayload = {\n  moduleType: 'clients',\n  instanceId: myInstanceId,\n  status: 'dirty',\n  title: 'Clientes — sin guardar',\n  schemaVersion: SCHEMA_VERSION,\n};\n\ndispatchMfeEvent(MFE_EVENTS.UPDATE_HEADER, detail);\n```\n\n**Shell listen (from the Shell side):**\n\n```ts\nimport { MFE_EVENTS, isMfeEvent } from '@cobranza-apps/mfe-events';\n\nwindow.addEventListener(MFE_EVENTS.REQUEST_FULLSCREEN, (event: Event) => {\n  if (!isMfeEvent(event, MFE_EVENTS.REQUEST_FULLSCREEN)) return;\n  const { moduleType, instanceId } = event.detail;\n  // Shell navigates to fullscreen for this instance\n});\n```\n\nFull examples (Shell→MFE broadcast + filter, multi-instance handling) live in [docs/USAGE.md](docs/USAGE.md).\n\n## Event Catalog\n\n### MFE -> Shell\n\n| Constant | Event name | Purpose |\n| --- | --- | --- |\n| `REQUEST_ADD_MODULE` | `mfe:request-add-module` | Ask the Shell to add a new module instance to the workbench |\n| `REQUEST_FULLSCREEN` | `mfe:request-fullscreen` | Ask the Shell to switch this instance to fullscreen |\n| `REQUEST_REMOVE` | `mfe:request-remove` | Ask the Shell to remove this instance from the workbench |\n| `UPDATE_HEADER` | `mfe:update-header` | MFE updates its own header chrome (title, status) |\n| `SHOW_NOTIFICATION` | `mfe:show-notification` | Ask the Shell to show a global toast/notification |\n| `MODULE_READY` | `mfe:module-ready` | MFE finished mounting and is ready |\n| `MODULE_ERROR` | `mfe:module-error` | Unrecoverable load/init error for this instance |\n| `UPDATE_MIN_HEIGHT` | `mfe:update-min-height` | MFE declares/updates the minimum usable height (px) for this instance; layout preference only — Shell may grant more space |\n\n### Shell -> MFE\n\n| Constant | Event name | Purpose |\n| --- | --- | --- |\n| `MODULE_STATE` | `shell:module-state` | Notify size / collapse / fullscreen / pixel dimensions and optional drag-and-drop state for this instance |\n| `THEME_CHANGED` | `shell:theme-changed` | Theme token set changed |\n| `VISIBILITY_CHANGED` | `shell:visibility-changed` | Instance became visible or hidden |\n\n### Naming rules\n\n- MFE → Shell: prefix `mfe:`; Shell → MFE: prefix `shell:`.\n- kebab-case after the prefix.\n- No company/domain segment, no version suffix in the name.\n\n### Deferred (not in v1)\n\n- `WORKSPACE_CONTEXT` (sibling instances list)\n- Auth / session / token events\n- Domain-specific events (`mfe:client:*`, etc.)\n- Notification actions (button that fires another event)\n\n## Design Principles\n\n- **Typed first.** Every event has a typed payload; no `detail: any`.\n- **Serializable only.** Payloads are plain JSON-serializable data (no functions, DOM nodes, class instances).\n- **Stable names.** Event name strings never change for a given meaning; evolve via optional new fields + package major version.\n- **Many focused events** over a few overloaded ones that keep growing props.\n- **Shell is the only listener of `mfe:*` events.** MFEs do not listen to each other.\n- **Broadcast + filter.** `shell:*` events are dispatched on `window`; each MFE instance filters by `instanceId` (and usually `moduleType`).\n- **Multi-instance aware.** The same `moduleType` can appear multiple times; almost every payload carries `moduleType` + `instanceId`.\n\n## Tech Stack\n\n| Item | Choice | Notes |\n| --- | --- | --- |\n| Language | TypeScript 5.x | Angular 22 ecosystem |\n| Module format | ESM + typings | publishable package |\n| Angular | Not a dependency | types + thin helpers only |\n| Runtime | Browser `CustomEvent` + `window` | no Node runtime at consumer side |\n| Node | 22.22.3 (`.nvmrc`) | dev toolchain |\n| Build | `tsc` | plain TypeScript compiler; no bundler needed for a types + thin-helpers library |\n| Testing | Vitest or Jest (helpers) + `tsc --noEmit` (types) | no browser/E2E |\n| Docs | JSDoc + README + `docs/USAGE.md` | no Storybook |\n\n## Development Scripts\n\n| Script | Command | Purpose |\n| --- | --- | --- |\n| `npm run build` | `tsc` | Compile sources to `dist/` (`.js` + `.d.ts`) |\n| `npm run typecheck` | `tsc --noEmit` | Type-check without emitting output |\n| `npm run clean` | `rimraf dist` | Remove the `dist/` directory |\n\n## Documentation\n\n- [Quick Usage](#quick-usage) (above) — minimal dispatch + listen.\n- [Runtime Setup](#runtime-setup) (above) — loading `reflect-metadata` per environment.\n- Copy-paste examples (broadcast, filtering, multi-instance): [docs/USAGE.md](docs/USAGE.md).\n- Consumer setup examples (Angular / Vitest / Jest): [docs/examples/](docs/examples/).\n- [Anti-patterns](docs/anti-patterns.md) — what NOT to do and why.\n- [Troubleshooting](docs/troubleshooting.md) — `reflect-metadata` errors and fixes.\n- JSDoc on every public export (event constants, payload interfaces, type maps, helpers).\n- Project knowledge base: [`.agent/project-info/`](.agent/project-info/).\n\n## Development & Contributing (for AI Agents)\n\nThis repo is maintained AI-agent-first via the Kilo Code critical workflow — read [`AGENTS.md`](AGENTS.md) before any change and follow [`.kilo/commands/critical-workflow.md`](.kilo/commands/critical-workflow.md); rules, project structure, and plans live in [`.kilo/rules/`](.kilo/rules/), [`.agent/project-structure.md`](.agent/project-structure.md), and [`.kilo/plans/`](.kilo/plans/).\n\n## Related Packages\n\n| Package | Relationship |\n| --- | --- |\n| `@cobranza-apps/ui` | Owns `ModuleHeader`/`ModuleContainer` visuals and the `ModuleStatus` union (keep values in sync). Does NOT dispatch these events. |\n| `@cobranza-apps/entities` | Domain models. Not imported by `mfe-events`; payloads stay generic. |\n| Shell | Sole `mfe:*` listener; owns workbench state, fullscreen URL, notification host. |\n| Individual MFEs | Dispatch `mfe:*`; filter `shell:*` by `instanceId`. |\n\n<!-- DO NOT DELETE NEXT SECTION -->\n\n## Important Note for AI Agents\n\nAll agents working on this project MUST adhere to the workflows and rules outlined in [AI Agent Onboarding document](AGENTS.md).\n\nBefore starting any task:\n\n1. **Review `AGENTS.md`**: it is the primary source of instructions for agents.\n2. **Follow Workflows**: follow the procedures defined in `.agent/WORKFLOWS.md`, especially the `.kilo/commands/critical-workflow.md`.\n\n<!-- END DO NOT DELETE -->\n","readmeFilename":"README.md"}