@universis/delivr-compat

@universis/delivr-compat should be installed only for supporting node.js versions prior to 18. Otherwise use the latest version of @universis/delivr

This package provides a push notification service for the Universis platform. It allows you to send push notifications to users of your application, and manage their subscriptions.

Installation

@universis/delivr-compat can run as a standalone service or be integrated into your existing application. To install it, run the following command:

npm i @universis/delivr-compat

Docker Installation

You can also run @universis/delivr-compat using Docker. To do this, use the following command:

docker run -d -p 8080:80 --name delivr 

or using docker compose:

services:
  delivr:
    image: registry3.it.auth.gr/universis-delivr:latest
    container_name: delivr
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - delivr_data:/opt/universis/delivr/
    restart: always

volumes:
  delivr_data:
    external: false

docker compose up -d

Configuration

The configuration file is located at /opt/universis/delivr/config/app.production.json. You can modify it to set up your database connection, push notification settings, and other options.

{
    "$schema": "https://themost-framework.github.io/express/schemas/applicationConfiguration.json",
    "services": [
        {
            "serviceType": "@universis/keycloak#KeycloakTokenIntrospectionStrategy",
            "strategyType": "@universis/keycloak#JwtTokenIntrospectionStrategy"
        },
        {
            "serviceType": "@universis/janitor#OAuth2ClientService",
            "strategyType": "@universis/keycloak#KeycloakClientService"
        }
    ],
    "settings": {
        "universis": {
            "delivr": {
                "subject": "<delivr service address e.g. https://delivr.universis.io>",
                "publicKey": "<VAPID public key>",
                "privateKey": "<VAPID private key>"
            }
        },
        "auth": {
            "unattendedExecutionAccount": "x86YUdc5am7N==",
            "issuer_uri": "<OIDC issuer URI e.g https://login.universis.io/auth/realms/universis/>",
            "server_uri": "<OIDC server URI e.g. https://login.universis.io/auth/realms/universis/protocol/openid-connect/>",
            "client_id": "<OIDC client ID with client credentials grant access e.g. delivr with client scope https://universis.io/delivr/push/send>",
            "client_secret": "<OIDC client secret>"
        }
    },
    "adapterTypes": [
        {
            "name": "SQLite Data Adapter",
            "invariantName": "sqlite",
            "type": "@themost/sqlite"
        }
    ],
    "adapters": [
        {
            "name": "service",
            "invariantName": "sqlite",
            "default": true,
            "options": {
                "database": ":memory:"
            }
        }
    ]
}

PushClientService

Universis API Server and other applications can use the PushClientService to send push notifications to users. The service provides methods for sending notifications, managing subscriptions, and retrieving notification history. PushClientService can be registered under the services section of the application configuration as follows:

{
    "services": [
        {
            "serviceType": "@universis/delivr-compat#PushClientService"
        }
    ]
}

It requires the host setting to be defined under settings/universis/delivr section of the application configuration, which should point to the address of the Delivr service.

{
    "settings": {
        "universis": {
            "delivr": {
                "host": "<delivr service address e.g. https://delivr.universis.io>"
            }
        }
    }
}

Important note: PushClientService is designed to be used by server-side applications to send push notifications to users using /services/push/send endpoint of the @universis/delivr-compat service. The instance of the service should follow authentication and authorization requirements of the delivr service, which typically involves using client credentials grant to obtain an access token from the OIDC provider configured in the delivr service. That means that the OIDC client used by the Universis API Server or other application should have the appropriate client scope (e.g. https://universis.io/delivr/push/send) to be able to send push notifications through the delivr service. and also be registered in the OIDC provider (e.g. Keycloak) with client credentials grant enabled.

PushServiceProxy

Universis API Server can be configured to use @universis/delivr-compat as a push notification service by registering PushServiceProxy service proxy.

{
    "services": [
        {
            "serviceType": "@universis/delivr-compat#PushServiceProxy"
        }
    ]
}

This will allow the API Server to forward push notification requests to @universis/delivr-compat, which will handle the actual sending of notifications to users.

The end-users will access the push notification service through the API Server using /services/push/subscribe endpoint.

The application configuration should include @universis/delivr-compat host under settings/universis/delivr section:

{
    "settings": {
        "universis": {
            "delivr": {
                "host": "<delivr service address e.g. https://delivr.universis.io>"
            }
        }
    }
}