feat(api): add new clients and dual build (esm/cjs) (#368)

This adds additional clients from proto files.
Further, the package now officially supports ESM
and CommonJS exports.

BREAKING CHANGE: There is no general barrel file
anymore. Please use the exported elements in package.json.
This means, instead of `import .. from '@zitadel/node'` you
should use `... from '@zitadel/node/api'` or `credentials`.

BREAKING CHANGE: the folder "grpc" was renamed to "api"
to reflect other language libraries where the export was
named api. With the new esm like structure, this results in
a cleaner import.

.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
           submodules: true
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
       - run: npm ci
       - run: npm run build
       - name: semantic release

.github/workflows/testing.yml

@@ -14,7 +14,6 @@ jobs:
       fail-fast: true
       matrix:
         version:
-          - 16
           - 18
           - 20
     name: test and build package (node ${{ matrix.version }})
@@ -25,8 +24,7 @@ jobs:
         with:
           node-version: ${{ matrix.version }}
       - run: npm ci
-      - run: npm run build
-      - run: npm test
+      - run: npm run test:ci
 
   test_all:
     if: ${{ always() }}

.gitignore

@@ -1,2 +1,3 @@
 node_modules/
 dist/
+.tshy*/

README.md

@@ -21,6 +21,32 @@ This library does _not_ provide authentication helpers for web applications.
 If you want to use `passport js` and OAuth 2.0 introspection, head over to
 [node-passport-zitadel](https://github.com/buehler/node-passport-zitadel).
 
+## Goals
+
+This is the "client library" for the ZITADEL API. It contains the compiled
+proto files from the original ZITADEL repository and therefore helps to
+access the API and manage ressources. Also, it contains helpers to
+authenticate a given service account against ZITADEL.
+
+To summarize:
+
+- Provide compiled proto clients
+- Manage resources via proto clients (e.g. `OrganizationServiceClient`, `SessionServiceClient`)
+- Allow authentication of a service account (fetch a token that can be sent)
+
+## Non-Goals
+
+In contrast to the goals of this package, this package does _not_ provide
+means to check for authentication of a user. There exists a multitude
+of frameworks that can be used in conjunction with NodeJS. Therefore, you need
+to use specific framework packages to support authentication.
+
+Known packages:
+
+- [Passport.js](https://www.passportjs.org/): [node-passport-zitadel](https://github.com/buehler/node-passport-zitadel)
+- [NextAuth / Auth.js](https://next-auth.js.org): [ZITADEL Provider](https://next-auth.js.org/providers/zitadel)
+- [NestJS](https://nestjs.com/): [NestJS OIDC](https://github.com/5-stones/nest-oidc)
+
 ### Development
 
 To enhance this library or to fix a bug, you need to do the following:

ava.config.js

@@ -1,6 +1,4 @@
-module.exports = {
-  files: ['test/**/*.test.ts'],
+export default {
+  files: ['dist/test/**/*.test.js'],
   verbose: true,
-  extensions: ['ts'],
-  require: ['ts-node/register'],
 };

buf.gen.yaml

@@ -6,7 +6,7 @@ plugins:
   - name: ts
     strategy: all
     path: node_modules/ts-proto/protoc-gen-ts_proto
-    out: src/grpc/generated
+    out: src/api/generated
     opt:
       - oneOf=unions
       - forceLong=long
@@ -15,3 +15,4 @@ plugins:
       - outputServices=nice-grpc
       - outputServices=generic-definitions
       - useExactTypes=false
+      - importSuffix=.js

examples/access-api-with-pat.commonjs.js

@@ -1,4 +1,4 @@
-const { createAccessTokenInterceptor, createAuthClient } = require('@zitadel/node/grpc');
+const { createAccessTokenInterceptor, createAuthClient } = require('@zitadel/node/api');
 
 const apiEndpoint = 'https://zitadel-libraries-l8boqa.zitadel.cloud';
 const personalAccessToken = 'Dp6uT84aVTqYLSMpk-H1-B3SPuqFms-Tz77cgWKlyrY3JxsZcDmb7kZoRK2ixaVNfuqmXfE';

examples/access-api-with-pat.esm.mjs

@@ -1,4 +1,4 @@
-import { createAccessTokenInterceptor, createAuthClient } from '@zitadel/node/grpc';
+import { createAccessTokenInterceptor, createAuthClient } from '@zitadel/node/api';
 
 const apiEndpoint = 'https://zitadel-libraries-l8boqa.zitadel.cloud';
 const personalAccessToken = 'Dp6uT84aVTqYLSMpk-H1-B3SPuqFms-Tz77cgWKlyrY3JxsZcDmb7kZoRK2ixaVNfuqmXfE';