GLog SDKs — install & use

Official client libraries that wrap the GLog HTTP API so a service emits an audit event in one call (auto token/refresh, request building, typed helpers). They live in this repository under sdk/ and are published to the GitLab Package Registry of the GLog project (git.esempla.systems/govtech/gstack/glog).

SDK	Language	Package	Registry	Source
Java	Java 11+	systems.esempla.glog:glog-sdk-java	GitLab Maven ✅ published	sdk/java
Node	Node 18+	@esempla/glog-sdk	GitLab npm ✅ published	sdk/js
PHP	PHP 8.0+	esempla/glog-sdk	GitLab Composer	sdk/php

A runnable Node example is in examples/node-demo.

Both are thin wrappers over the documented HTTP API — anything an SDK does can be done with a plain request (see the integration guide).

The GLog project id in GitLab is 574, the govtech/gstack group id is 1087 — the registry URLs below use them directly.

---

Java SDK

The Java SDK is a Maven artifact, so it works from Maven, Gradle, or any tool that reads a Maven repository.

1. Point your build at the GitLab Maven registry

Maven — pom.xml:

<repositories>
  <repository>
    <id>gitlab-glog</id>
    <url>https://git.esempla.systems/api/v4/projects/574/packages/maven</url>
  </repository>
</repositories>

<dependency>
  <groupId>systems.esempla.glog</groupId>
  <artifactId>glog-sdk-java</artifactId>
  <version>0.1.0</version>
</dependency>

Gradle — build.gradle:

repositories {
  maven {
    url "https://git.esempla.systems/api/v4/projects/574/packages/maven"
    name "GitLab"
    credentials(HttpHeaderCredentials) {
      name = "Deploy-Token"                 // or "Private-Token" / "Job-Token"
      value = providers.gradleProperty("gitlabToken").get()
    }
    authentication { header(HttpHeaderAuthentication) }
  }
}
dependencies { implementation "systems.esempla.glog:glog-sdk-java:0.1.0" }

2. Authenticate to the registry

The registry is private. For Maven, put a token in ~/.m2/settings.xml:

<settings>
  <servers>
    <server>
      <id>gitlab-glog</id>
      <configuration>
        <httpHeaders>
          <property><name>Deploy-Token</name><value>YOUR_DEPLOY_TOKEN</value></property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

Use a Deploy Token (Project → Settings → Repository → Deploy tokens, scope read_package_registry) or a Personal Access Token.

3. Use it

GLogClient glog = GLogClient.builder()
    .baseUrl("https://glog.gstack.esempla.systems")
    .tenant("demo")
    // Auth is required. Client-credentials against Keycloak (service client with audit:write):
    .tokenSupplier(new KeycloakTokenSupplier(
        "https://sso.gstack.esempla.systems/realms/interdictii", "glog-ingest", secret))
    .build();

glog.auditAsync(AuditEvent.of("gpay", "PAYMENT", "CREATE")   // fire-and-forget, never throws
    .operation("PAYMENT_PROCESS").status(Status.SUCCESS)
    .objectAffected("pay-5521").correlationId("corr-1001")
    .detail("amount", 1250));

audit(...) is the synchronous variant (throws GLogException); getById(id) and search(from, to, objectType, page, size) read events back. Full details: sdk/java/README.md.

---

Node SDK

1. Point npm at the GitLab npm registry

.npmrc (next to your package.json):

@esempla:registry=https://git.esempla.systems/api/v4/projects/574/packages/npm/
//git.esempla.systems/api/v4/projects/574/packages/npm/:_authToken=${GITLAB_TOKEN}

Then (with GITLAB_TOKEN = a Deploy/Personal token, read_package_registry):

npm install @esempla/glog-sdk

2. Use it

const { GLogClient, keycloakTokenProvider } = require('@esempla/glog-sdk');

// Auth is required. Client-credentials against Keycloak (service client with audit:write):
const glog = new GLogClient({
  baseUrl: 'https://glog.gstack.esempla.systems',
  tenant: 'demo',
  tokenProvider: keycloakTokenProvider({
    issuer: 'https://sso.gstack.esempla.systems/realms/interdictii',
    clientId: 'glog-ingest',
    clientSecret: process.env.GLOG_CLIENT_SECRET,
  }),
});

await glog.tryAudit({                                    // best-effort, never throws
  service: 'gpay', objectType: 'PAYMENT', actionType: 'CREATE',
  operation: 'PAYMENT_PROCESS', status: 'SUCCESS',
  correlationId: 'corr-1001', details: { amount: 1250 },
});

audit(...) throws on failure; getById(id) and search({ from, to, objectType, page, size }) read events back. Runnable example: examples/node-demo. Full details: sdk/js/README.md.

---

PHP SDK

1. Point Composer at the GitLab Composer registry

composer.json:

{
  "repositories": [
    { "type": "composer", "url": "https://git.esempla.systems/api/v4/group/1087/-/packages/composer/packages.json" }
  ],
  "require": { "esempla/glog-sdk": "^0.1" }
}

2. Authenticate to the registry

auth.json (next to composer.json, or global):

{
  "gitlab-token": { "git.esempla.systems": "YOUR_DEPLOY_OR_PERSONAL_TOKEN" }
}

Then:

composer require esempla/glog-sdk

3. Use it

use Esempla\GLog\Client;
use Esempla\GLog\AuditEvent;

// Auth is required. Client-credentials against Keycloak (service client with audit:write):
$glog = new Client(
    baseUrl: 'https://glog.gstack.esempla.systems',
    tenant: 'demo',
    tokenProvider: new Esempla\GLog\KeycloakTokenProvider(
        'https://sso.gstack.esempla.systems/realms/interdictii', 'glog-ingest', $secret));

$glog->tryAudit(AuditEvent::of('gpay', 'PAYMENT', 'CREATE')   // best-effort, never throws
    ->operation('PAYMENT_PROCESS')->status('SUCCESS')
    ->objectAffected('pay-5521')->correlationId('corr-1001')
    ->detail('amount', 1250));

audit(...) throws on failure; getById($id) and search($from, $to, ...) read events back. Full details: sdk/php/README.md.

---

Common notes

• Defaults filled for you: tenantId and eventTimestamp are set from the client config / current time if you don’t provide them.
• Auth (REQUIRED — the live demo now runs the dualauth profile): every call needs a bearer token; tokenless requests get 401. Pass a Keycloak client-credentials provider (the SDK acquires and refreshes the token automatically) or a static token. Your tenant must equal the token’s tenant claim (else 403).
  • Ingest (write) needs audit:write — that’s what a service client like glog-ingest carries. See auth-and-integrations.md for how to create it (confidential client + default audit:write scope + tenant mapper).
  • Reading (getById / search) needs audit:read. A write-only ingest client will get 403 on reads — use a token that also has audit:read (e.g. a human ROLE_ADMIN/ROLE_USER token, or add an audit:read scope to the client).
• Best-effort: prefer the non-throwing variants (auditAsync / tryAudit) on the hot path so auditing can never break your business logic.
• correlationId: set the same value across services handling one flow to get GLog’s correlated cross-service view.

Versioning & publishing (manual)

SDK versions track the GLog API (0.x while the API is pre-1.0). Publishing is done manually by a maintainer with a GitLab token that has write_package_registry scope (a Deploy Token or PAT).

Java → GitLab Maven registry. Add a publish-settings.xml:

<settings><servers><server>
  <id>gitlab-maven</id>
  <configuration><httpHeaders>
    <property><name>Private-Token</name><value>YOUR_TOKEN</value></property>
  </httpHeaders></configuration>
</server></servers></settings>

Then deploy (fill the numeric project id):

mvn -f sdk/java/pom.xml -s publish-settings.xml deploy \
  -Dgitlab.api.url=https://git.esempla.systems/api/v4 \
  -Dgitlab.project.id=574

PHP → GitLab Composer registry. After tagging the release commit, register it:

curl --header "PRIVATE-TOKEN: YOUR_TOKEN" \
  --data tag=<TAG> \
  "https://git.esempla.systems/api/v4/projects/574/packages/composer"

The Composer registry reads composer.json from the tagged ref’s root. Since this monorepo keeps the SDK under sdk/php, publish the PHP package from a repo/subtree split whose root is the SDK (or move sdk/php to its own repo) — the SDK code itself is unchanged either way.