npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@ondewo/survey-client-angular

v2.1.1

Published

ONDEWO Survey (SURVEY) Client library for Angular

Readme

Overview

@ondewo/survey-client-angular is a compiled version of the ONDEWO SURVEY API using the ONDEWO PROTO COMPILER. Here you can find the SURVEY API documentation.

ONDEWO APIs use Protocol Buffers version 3 (proto3) as their Interface Definition Language (IDL) to define the API interface and the structure of the payload messages. The same interface definition is used for gRPC versions of the API in all languages.

Setup

Using NPM:

npm i --save @ondewo/survey-client-angular

Using GitHub:

git clone https://github.com/ondewo/ondewo-survey-client-angular.git ## Clone repository
cd ondewo-survey-client-angular                                      ## Change into repo-directoy
make setup_developer_environment_locally                          ## Install dependencies

Authentication (Keycloak bearer token)

The client attaches the current Keycloak access token as an authorization: Bearer <token> credential to every gRPC-web (and HTTP) request. Wire it up once at application bootstrap — supply a TokenProvider (or the ready-made KeycloakTokenProvider) and register the interceptors:

import {
  authHttpInterceptor,
  KEYCLOAK_TOKEN_PROVIDER_CONFIG,
  KeycloakTokenProvider,
  KeycloakTokenProviderConfig,
  provideOndewoSurveyAuth
} from "@ondewo/survey-client-angular";
import { provideHttpClient, withInterceptors } from "@angular/common/http";

bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: KEYCLOAK_TOKEN_PROVIDER_CONFIG,
      useValue: {
        keycloakUrl: "https://auth.example.com/auth",
        realm: "ondewo-ccai-platform",
        clientId: "ondewo-nlu-cai-sdk-public",
        username: "[email protected]",
        password: "…"
      } satisfies KeycloakTokenProviderConfig
    },
    provideOndewoSurveyAuth(KeycloakTokenProvider),
    provideHttpClient(withInterceptors([authHttpInterceptor]))
  ]
});

Once the providers are registered, injected clients such as SurveysClient are authenticated automatically — no per-call token handling is required.

The built-in KeycloakTokenProvider

For a technical user the built-in KeycloakTokenProvider logs in against the public SDK Keycloak client (no client_secret is ever sent) and keeps the access token fresh. It behaves exactly like the token provider of every other ONDEWO client SDK. Supply its configuration under KEYCLOAK_TOKEN_provideOndewoSurveyAuthR_CONFIG and register it with provideOndewoSurveyAuth(KeycloakTokenProvider):

import { provideHttpClient, withInterceptors } from "@angular/common/http";
import {
  authHttpInterceptor,
  KEYCLOAK_TOKEN_provideOndewoSurveyAuthR_CONFIG,
  KeycloakTokenProvider,
  KeycloakTokenProviderConfig,
  provideOndewoSurveyAuth
} from "@ondewo/survey-client-angular";

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(withInterceptors([authHttpInterceptor])),
    {
      provide: KEYCLOAK_TOKEN_provideOndewoSurveyAuthR_CONFIG,
      useValue: {
        keycloakUrl: "https://keycloak.example.com",
        realm: "ondewo",
        clientId: "ondewo-nlu-cai-sdk-public",
        refreshToken: offlineTokenFromYourSecretStore // or: username + password
      } satisfies KeycloakTokenProviderConfig
    },
    provideOndewoSurveyAuth(KeycloakTokenProvider)
  ]
});

A handed-off Keycloak offline token (refreshToken) is what a fleet of clients sharing one technical user should use: start-up is then one refresh_token grant, and a refused token is never answered with a password login (Keycloak's brute-force detection counts failed password logins, not refresh grants). A username + password pair performs one grant_type=password login with scope=offline_access instead; it only works for a 2FA-exempt technical user. offlineToken is still accepted as a deprecated alias of refreshToken.

keycloakUrl, realm and clientId are all-or-nothing: all three empty means "no Keycloak" (no login, no authorization header), any other partial set is rejected. With Keycloak configured, password or refreshToken is mandatory. tokenExpirationInS bounds the auto-refresh when the session must not outlive a fixed window; keycloakVerifySsl is accepted for parity with the other SDKs but cannot change a browser's TLS verification. Every string rendering of the provider shows a set secret as ***REDACTED***.

The refresh runs REFRESH_SKEW_IN_S (30 s) before expiry; a failed refresh is retried after a jittered backoff (5 s, doubling to 300 s) and never ends the refresh loop. While it fails, getToken() keeps serving the still-valid token, and only a token that has expired and cannot be refreshed is reported as a KeycloakAuthenticationError. A request issued while the first login is still in flight waits for it instead of going out unauthenticated. One WARNING is logged per failed attempt and one INFO on recovery (through the optional logger, default the console), never with a credential. Providers with the same credentials on the same HttpClient share one login. The framework-free core is exported as KeycloakTokenSession for use outside Angular DI.

Credentials that are only known after bootstrap are supplied with await tokenProvider.configure(config); without a config the provider stays idle. await tokenProvider.whenReady() waits for the first login (e.g. in an APP_INITIALIZER), and after the server answered UNAUTHENTICATED, await tokenProvider.ensureFreshToken({ force: true }) renews the token (single-flight, honouring a running backoff; a refresh never falls back to a password login).

KeycloakTokenError, the error name of earlier releases, is kept as a deprecated alias: it is the very class KeycloakAuthenticationError, so instanceof checks written against either name keep matching.

Package structure

npm
├── api
│   ├── google
│   │   └── api
│   │       ├── annotations.pb.d.ts
│   │       └── http.pb.d.ts
│   └── ondewo
│       └── survey
│           ├── fhir.pbconf.d.ts
│           ├── fhir.pb.d.ts
│           ├── fhir.pbsc.d.ts
│           ├── survey.pbconf.d.ts
│           ├── survey.pb.d.ts
│           └── survey.pbsc.d.ts
├── esm2022
│   ├── api
│   │   ├── google
│   │   │   └── api
│   │   │       ├── annotations.pb.mjs
│   │   │       └── http.pb.mjs
│   │   └── ondewo
│   │       └── survey
│   │           ├── fhir.pbconf.mjs
│   │           ├── fhir.pb.mjs
│   │           ├── fhir.pbsc.mjs
│   │           ├── survey.pbconf.mjs
│   │           ├── survey.pb.mjs
│   │           └── survey.pbsc.mjs
│   ├── ondewo-survey-client-angular.mjs
│   └── public-api.mjs
├── fesm2022
│   ├── ondewo-survey-client-angular.mjs
│   └── ondewo-survey-client-angular.mjs.map
├── ondewo-survey-api
│   └── README.md
├── index.d.ts
├── LICENSE
├── package.json
├── public-api.d.ts
└── README.md

TLS, mutual TLS and certificates

gRPC encrypts with TLS; in this library the transport is gRPC-web over the browser's fetch/XHR, so TLS means an https:// endpoint (an Envoy or other gRPC-web proxy in front of the ONDEWO server). The browser owns the handshake: it verifies the server against its own (OS / browser) trust store, and it presents a client certificate only from its own certificate store. Application code can neither add a CA nor attach a client identity, so this package takes no certificate or key. buildGrpcWebHost builds the endpoint URL from the same host / port / useSecureChannel fields every ONDEWO SDK uses:

| Mode | useSecureChannel | Where the certificates live | | --- | --- | --- | | Plaintext (not for production) | false | none; http://, logged with console.warn naming host:port | | TLS, public CA (system roots) | true (default) | nothing to do: the browser trusts the server certificate | | TLS, private / custom CA | true (default) | the CA (ca.pem) imported into the OS / browser trust store of every client machine | | Mutual TLS | true (default) | the proxy requests a client certificate; the browser offers one from the user's certificate store |

For mutual TLS without certificates on the client machines, let the gRPC-web proxy (Envoy) terminate the browser's TLS and use mutual TLS on its upstream connection to the ONDEWO server.

import { GrpcCoreModule } from "@ngx-grpc/core";
import { GrpcWebClientModule } from "@ngx-grpc/grpc-web-client";
import { buildGrpcWebHost } from "@ondewo/survey-client-angular";

@NgModule({
  imports: [
    GrpcCoreModule.forRoot(),
    GrpcWebClientModule.forRoot({
      settings: { host: buildGrpcWebHost({ host: "survey.example.com", port: 443 }) } // https://survey.example.com:443
    })
  ]
})
export class AppModule {}

Rules the code enforces (GrpcWebEndpointError, whose message names the field, never its value):

  • useSecureChannel defaults to true (https://). false gives http:// and a console.warn naming host:port.
  • grpcCert, grpcClientCert, grpcClientKey (and the snake_case spellings of the other SDKs' configs) are refused when non-empty, instead of being silently dropped: never ship a private key or certificate in a browser bundle. Empty strings / null count as unset (plain TLS).
  • A bare IPv6 literal is bracketed (::1 → https://[::1]:8443); a bracketed host is left alone. A host with a scheme (https://survey.example.com/grpc) is used as given; then port must be omitted, and an http:// URL together with useSecureChannel: true is refused. A host:port string is refused; use port.
  • The certificate's subject alternative names (SAN) must match the host in the URL; a browser has no ssl_target_name_override.

Outside a browser (Node.js services, tests, CLIs) use @ondewo/survey-client-nodejs: it takes the CA and the client certificate / key as PEM content and implements mutual TLS in code. This package runs only in a browser (Angular, gRPC-web) and has no Node.js transport.

A test PKI with openssl

A CA, a server certificate with SANs, and a client certificate with the clientAuth extended key usage. For tests only: the keys are unencrypted.

openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 365 \
  -subj "/CN=Test CA" -keyout ca.key -out ca.pem

printf 'subjectAltName=DNS:localhost,IP:127.0.0.1\nextendedKeyUsage=serverAuth\n' > server.ext
openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
  -subj "/CN=localhost" -keyout server.key -out server.csr
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 \
  -extfile server.ext -out server.pem

printf 'extendedKeyUsage=clientAuth\n' > client.ext
openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
  -subj "/CN=my-client" -keyout client.key -out client.csr
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 \
  -extfile client.ext -out client.pem

# the browser imports a client identity as PKCS#12
openssl pkcs12 -export -in client.pem -inkey client.key -certfile ca.pem -out client.p12

chmod 600 *.key *.p12
openssl verify -CAfile ca.pem server.pem client.pem

The gRPC-web proxy serves server.pem / server.key and, for mutual TLS, trusts ca.pem for its clients (Envoy: require_client_certificate: true with validation_context.trusted_ca). The browser machine imports ca.pem as a trusted root and, for mutual TLS, client.p12 as a personal certificate.

TLS security notes

  • No secret is part of the endpoint config, so nothing in it needs redacting, and this package never logs a config.
  • A private key in a web application is readable by anyone who loads the page. Keep client identities in the browser's certificate store (or a smart card), never in environment.ts, assets/ or the bundle.
  • A page served over https:// cannot call an http:// endpoint (mixed content); use plaintext only for local development with the page itself on http://localhost.

TLS troubleshooting

The browser reports a failed handshake to gRPC-web as status UNAVAILABLE / UNKNOWN with little detail; the cause is in the browser's developer tools (Network tab / console):

  • net::ERR_CERT_AUTHORITY_INVALID: the server certificate is signed by a CA the browser does not trust. Import the CA into the OS / browser trust store, or serve a certificate from a public CA.
  • net::ERR_CERT_COMMON_NAME_INVALID: the host in the URL is not in the certificate's SAN. Connect by the name in the SAN, or reissue the certificate with the host (IP: SAN for an address).
  • net::ERR_BAD_SSL_CLIENT_AUTH_CERT / ERR_SSL_CLIENT_AUTH_CERT_NEEDED: the proxy requires a client certificate and the browser has none (or one the proxy's CA did not sign). Import the user's .p12, and check that the proxy trusts its CA.
  • Mixed content / blocked request: the page is on https:// and the endpoint on http://; use useSecureChannel: true.
  • CORS error: not a TLS problem; the gRPC-web proxy must allow the page's origin and the grpc-web headers.