@efa-one/sdk 1.10.1 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +52 -48
  2. package/frontend/ipc.d.ts +15 -0
  3. package/frontend/ipc.js +22 -0
  4. package/package.json +7 -2
package/README.md CHANGED
@@ -1,43 +1,43 @@
1
1
  # @efa-one/sdk
2
2
 
3
- Offizielles SDK zum Bauen von **efa-one-Apps**. Es ist die verbindliche
4
- Integrationsschicht, die jede App einbettet, um ein First-Class-Bürger der
5
- Plattform zu sein: Auth gegen den Kernel, Clients zu den Plattform-Services und
6
- das Frontend-IPC-/i18n-Toolkit für die iframe-Einbettung.
3
+ Official SDK for building **efa-one apps**. It is the integration layer every app
4
+ embeds to become a first-class citizen of the platform: authentication against the
5
+ kernel, clients for the platform services, and the frontend IPC / i18n toolkit for
6
+ iframe embedding.
7
7
 
8
- ## Zwei Entry-Points
8
+ ## Two entry points
9
9
 
10
- Das SDK ist gemischt server-/browserseitig und daher in zwei Sub-Pfade getrennt,
11
- damit `express` nicht ins Frontend und `react` nicht ins Backend leakt:
10
+ The SDK is a mix of server- and browser-side code, so it is split into two
11
+ sub-paths — this keeps `express` out of the frontend and `react` out of the backend:
12
12
 
13
- | Import | Läuft in | Enthält |
13
+ | Import | Runs in | Contains |
14
14
  |---|---|---|
15
- | `@efa-one/sdk/backend` | Node/Express | Auth + Token-Exchange (`requireAuth`, `createExchangeRouter`, `requireInternalOrAuth` …), Health-Router, Service-Discovery + Gateway-Client (`serviceClient`, `resolveService`), Clients für Audit/Reporting/Mail/Notifications, Permission-Auflösung/-Registrierung (`getUserPermissions`, `registerPermissions`, `checkPermission`), Capability-Registry (`registerApiMetadata`), Backend-i18n |
16
- | `@efa-one/sdk/frontend` | Browser/React | postMessage-IPC (`sendDeclareAppInfo`, `sendAtStart`, `navigateToApp`, `notifyRouteChange` …), react-i18next-Factory (`initI18n`), `DevHeader` |
15
+ | `@efa-one/sdk/backend` | Node/Express | Auth + token exchange (`requireAuth`, `createExchangeRouter`, `requireInternalOrAuth` …), health router, service discovery + gateway client (`serviceClient`, `resolveService`), clients for audit/reporting/mail/notifications, permission resolution/registration (`getUserPermissions`, `registerPermissions`, `checkPermission`), capability registry (`registerApiMetadata`), backend i18n |
16
+ | `@efa-one/sdk/frontend` | Browser/React | postMessage IPC (`sendDeclareAppInfo`, `sendAtStart`, `navigateToApp`, `notifyRouteChange` …), react-i18next factory (`initI18n`), `DevHeader` |
17
17
 
18
- Jedes Einzelmodul ist zusätzlich direkt erreichbar, z. B.
19
- `@efa-one/sdk/backend/auth` oder `@efa-one/sdk/frontend/ipc`.
18
+ Every individual module is also reachable directly, e.g.
19
+ `@efa-one/sdk/backend/auth` or `@efa-one/sdk/frontend/ipc`.
20
20
 
21
- > **Hinweis zu Legacy-Präfixen:** Einige plattform-interne Identifier (postMessage-
22
- > Nachrichtentypen, Env-Variablen-Namen, JWT-`iss`) tragen noch technische
23
- > Legacy-Präfixe aus einer früheren Namensgebung. Diese sind Teil des Draht-
24
- > Protokolls zwischen App und Kernel und werden gemeinsam mit dem Kernel in einem
25
- > koordinierten Schritt migriert — nicht einseitig im SDK.
21
+ > **Note on legacy prefixes:** Some platform-internal identifiers (postMessage
22
+ > message types, environment variable names, JWT `iss`) still carry technical
23
+ > legacy prefixes from an earlier naming. These are part of the wire protocol
24
+ > between app and kernel and are migrated together with the kernel in one
25
+ > coordinated step — not unilaterally in the SDK.
26
26
 
27
27
  ## Installation
28
28
 
29
29
  ```bash
30
- # im Backend-Projekt der App
30
+ # in the app's backend project
31
31
  npm install @efa-one/sdk express pg jsonwebtoken
32
32
 
33
- # im Frontend-Projekt der App
33
+ # in the app's frontend project
34
34
  npm install @efa-one/sdk react i18next i18next-http-backend react-i18next
35
35
  ```
36
36
 
37
- Die Runtime-Bibliotheken sind **optionale Peer-Dependencies** — installiere nur die
38
- zum genutzten Entry-Point passenden. Das SDK selbst bündelt sie nicht.
37
+ The runtime libraries are **optional peer dependencies** — install only the ones
38
+ matching the entry point you use. The SDK itself does not bundle them.
39
39
 
40
- ## Verwendung
40
+ ## Usage
41
41
 
42
42
  ```ts
43
43
  // Backend
@@ -54,44 +54,48 @@ import { initI18n, sendDeclareAppInfo, DevHeader } from '@efa-one/sdk/frontend';
54
54
  sendDeclareAppInfo({ appName: 'efa-chat', version: __APP_VERSION__ });
55
55
  ```
56
56
 
57
- ## Build
57
+ ## Build your first app
58
58
 
59
- Reines `tsc`, kein Bundler. Zwei Targets:
59
+ This repo ships a ready-to-copy app scaffold under [`template/`](./template) — the fastest
60
+ path to a working efa-app. It already wires up auth, health, service discovery,
61
+ audit/reporting, IPC and i18n against this SDK, so you write business logic only. No extra
62
+ tooling (and no Claude Code) required — clone the repo, then:
60
63
 
61
64
  ```bash
62
- npm install # devDeps + Peer-Libs zum Typecheck
63
- npm run build # backend/ (CJS) + frontend/ (ESM), je mit .d.ts
64
- npm run typecheck # nur Typprüfung, kein Emit
65
+ cp -R template efa-myapp
66
+ cd efa-myapp && rm -rf .git && git init
67
+ npm --prefix backend install && npm --prefix frontend install
68
+ docker compose up -d --build
65
69
  ```
66
70
 
67
- - `backend/` — CommonJS (`module: commonjs`)
68
- - `frontend/` — ESM (`module: esnext`, `moduleResolution: bundler`), via
69
- `frontend/package.json` als `{"type":"module"}` markiert; App-Bundler (Vite)
70
- konsumieren es direkt.
71
-
72
- Das flache Output-Layout (`backend/` + `frontend/` im Paket-Root) ist bewusst so
73
- gewählt, damit Consumer mit `moduleResolution: node` (node10) die Subpath-Importe
74
- physisch auflösen — ohne dass sie ihre tsconfig anpassen müssen.
71
+ See [`template/README.md`](./template/README.md) for the full walkthrough — stack variants
72
+ (3-container/PostgreSQL vs. single-container/SQLite), the intake questions, permission
73
+ registration, and the README chapters every app must keep.
75
74
 
76
- ## Publish
75
+ ## Build the SDK itself
77
76
 
78
- Public auf npmjs unter dem Scope `@efa-one` (`publishConfig.access = "public"` ist
79
- gesetzt):
77
+ Plain `tsc`, no bundler. Two targets:
80
78
 
81
79
  ```bash
82
- npm login # Account muss Mitglied der @efa-one-Org sein
83
- npm publish # baut via prepublishOnly automatisch neu
80
+ npm install # devDeps + peer libs for the typecheck
81
+ npm run build # backend/ (CJS) + frontend/ (ESM), each with .d.ts
82
+ npm run typecheck # type check only, no emit
84
83
  ```
85
84
 
86
- `npm install` durch Apps/CI/Docker braucht **keine** Credentials — nur der
87
- Publish-Schritt.
85
+ - `backend/` — CommonJS (`module: commonjs`)
86
+ - `frontend/` — ESM (`module: esnext`, `moduleResolution: bundler`), marked via
87
+ `frontend/package.json` as `{"type":"module"}`; app bundlers (Vite) consume it
88
+ directly.
89
+
90
+ The flat output layout (`backend/` + `frontend/` at the package root) is a
91
+ deliberate choice so that consumers using `moduleResolution: node` (node10) can
92
+ resolve the subpath imports physically — without having to change their tsconfig.
88
93
 
89
- ## Versionierung
94
+ ## Versioning
90
95
 
91
- SemVer. Template-Migration = `npm version` + publish; App-Update =
92
- `npm update @efa-one/sdk`.
96
+ SemVer. Consuming apps pull new versions with `npm update @efa-one/sdk`.
93
97
 
94
- ## Lizenz
98
+ ## License
95
99
 
96
- [Apache-2.0](./LICENSE) — permissiv mit Patent-Grant, damit Kunden und Partner ohne
97
- Reibung efa-one-Apps bauen können.
100
+ [Apache-2.0](./LICENSE) — permissive with a patent grant, so customers and partners
101
+ can build efa-one apps without friction.
package/frontend/ipc.d.ts CHANGED
@@ -5,6 +5,21 @@ export declare function sendDeclareAppInfo(payload: {
5
5
  appName: string;
6
6
  version: string;
7
7
  }): void;
8
+ export declare function appInfoDeclareFromAuth(info: {
9
+ appName: string;
10
+ version: string;
11
+ }, data: unknown): {
12
+ type: 'CONVERGE_DECLARE_APP_INFO';
13
+ payload: {
14
+ appName: string;
15
+ version: string;
16
+ serviceKey: string;
17
+ };
18
+ } | null;
19
+ export declare function registerAppInfo(info: {
20
+ appName: string;
21
+ version: string;
22
+ }): () => void;
8
23
  export declare function navigateToApp(serviceKey: string, options?: {
9
24
  path?: string;
10
25
  }): void;
package/frontend/ipc.js CHANGED
@@ -27,6 +27,28 @@ export function sendDeclareAppInfo(payload) {
27
27
  return;
28
28
  window.parent.postMessage({ type: 'CONVERGE_DECLARE_APP_INFO', payload }, getParentOrigin());
29
29
  }
30
+ export function appInfoDeclareFromAuth(info, data) {
31
+ const d = data;
32
+ if (!d || d.type !== 'CONVERGE_AUTH' || typeof d.serviceKey !== 'string')
33
+ return null;
34
+ return {
35
+ type: 'CONVERGE_DECLARE_APP_INFO',
36
+ payload: { appName: info.appName, version: info.version, serviceKey: d.serviceKey },
37
+ };
38
+ }
39
+ export function registerAppInfo(info) {
40
+ if (!isEmbedded())
41
+ return () => { };
42
+ const handler = (event) => {
43
+ if (!isFromPlatformParent(event))
44
+ return;
45
+ const message = appInfoDeclareFromAuth(info, event.data);
46
+ if (message)
47
+ window.parent.postMessage(message, getParentOrigin());
48
+ };
49
+ window.addEventListener('message', handler);
50
+ return () => window.removeEventListener('message', handler);
51
+ }
30
52
  export function navigateToApp(serviceKey, options) {
31
53
  if (!isEmbedded())
32
54
  return;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@efa-one/sdk",
3
- "version": "1.10.1",
3
+ "version": "1.11.0",
4
4
  "description": "Offizielles SDK für efa-one-Apps: Auth/Session, Service-Discovery, Gateway-Client, Audit/Reporting/Mail/Notifications, Permission- und Capability-Registrierung sowie das Frontend-IPC-/i18n-Toolkit.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "commonjs",
@@ -38,6 +38,7 @@
38
38
  "build:frontend": "tsc -p tsconfig.frontend.json && node -e \"require('fs').writeFileSync('frontend/package.json', JSON.stringify({type:'module'}))\"",
39
39
  "build": "npm run clean && npm run build:backend && npm run build:frontend",
40
40
  "typecheck": "tsc -p tsconfig.backend.json --noEmit && tsc -p tsconfig.frontend.json --noEmit",
41
+ "test": "vitest run",
41
42
  "prepublishOnly": "npm run build"
42
43
  },
43
44
  "publishConfig": {
@@ -78,9 +79,11 @@
78
79
  "devDependencies": {
79
80
  "@types/express": "^4.17.21",
80
81
  "@types/jsonwebtoken": "^9.0.6",
82
+ "cookie-parser": "^1.4.6",
81
83
  "@types/node": "^20.14.0",
82
84
  "@types/pg": "^8.11.0",
83
85
  "@types/react": "^18.2.46",
86
+ "@types/supertest": "^7.2.0",
84
87
  "express": "^4.19.2",
85
88
  "i18next": "^23.11.0",
86
89
  "i18next-http-backend": "^2.7.3",
@@ -88,7 +91,9 @@
88
91
  "pg": "^8.12.0",
89
92
  "react": "^18.2.0",
90
93
  "react-i18next": "^13.5.0",
91
- "typescript": "7.0.2"
94
+ "supertest": "^7.2.2",
95
+ "typescript": "7.0.2",
96
+ "vitest": "^4.1.4"
92
97
  },
93
98
  "engines": {
94
99
  "node": ">=20"