@cloudscaile-eng/platform-ext-utils

Utilities for CloudScaile extensions: environment validation, structured logging, Kafka messaging, and platform HTTP client helpers.

Install

npm install @cloudscaile-eng/platform-ext-utils

Quick start

ESM

import { initExtUtils, logger } from "@cloudscaile-eng/platform-ext-utils";

const utils = await initExtUtils();

logger.info("Extension started");
await utils.produceMessage({ action: "sync" }, "topic");

process.on("SIGINT", async () => {
  await utils.shutdown();
  process.exit(0);
});

CommonJS

const { initExtUtils } = require("@cloudscaile-eng/platform-ext-utils");

(async () => {
  const utils = await initExtUtils();
  await utils.produceMessage({ action: "sync" }, "topic");
})();

API

| Export | Description | |--------|-------------| | initExtUtils(options?) | Validates env, optionally connects Kafka, returns a configured instance | | validateEnv(overrides?) | Explicit environment validation without full init | | logger | Standalone JSON console logger (error, warn, info) | | KafkaService | Low-level Kafka wrapper for advanced use | | platformAxiosInstance(req, platformUrl) | Creates an Axios client for the platform API | | shutdown(instance) | Disconnects Kafka on a given instance |

initExtUtils return value

{
  env: ValidatedEnv;
  secrets: PgSecrets | { PG_DB_REQUIRED: false };
  kafka: KafkaService | null;
  produceMessage(message, routingKey): Promise<void>;
  consumeMessages(callback): Promise<void>;
  platformAxiosInstance(req): AxiosInstance;
  shutdown(): Promise<void>;
}

Environment variables

Required (always)

| Variable | Description | |----------|-------------| | TENANT_NAME | Tenant name for the application | | EXTENSION_NAME | Name of the extension | | MODULE_NAME | Name of the module | | PLATFORM_URL | Base URL for the platform API |

Optional

| Variable | Default | Description | |----------|---------|-------------| | PORT | 8000 | Application port | | PG_DB_REQUIRED | false | Enable PostgreSQL config validation | | KAFKA_REQUIRED | false | Enable Kafka integration |

When PG_DB_REQUIRED=true

| Variable | Description | |----------|-------------| | PG_HOST | PostgreSQL host | | PG_PORT | PostgreSQL port | | PG_DB | Database name | | PG_USERNAME | Database username | | PG_PASSWORD | Database password |

When KAFKA_REQUIRED=true

| Variable | Default | Description | |----------|---------|-------------| | KAFKA_BROKERS | — | Comma-separated broker list | | KAFKA_CLIENT_ID | — | Kafka client ID | | KAFKA_GROUP_ID | cs-platform-group-ext | Consumer group ID | | KAFKA_PRODUCER_TOPIC | cs-platform-producer-topic | Physical Kafka topic for outbound messages | | KAFKA_CONSUMER_TOPIC | cs-platform-consumer-topic | Topic to consume from | | KAFKA_SASL | false | Enable SASL SCRAM-SHA-512 auth | | KAFKA_SASL_USERNAME | — | SASL username (when KAFKA_SASL=true) | | KAFKA_SASL_PASSWORD | — | SASL password (when KAFKA_SASL=true) |

Kafka message format

Messages are published to the fixed KAFKA_PRODUCER_TOPIC. The second argument to produceMessage is a routing key, not the Kafka topic:

{
  "topic": "topic",
  "message": { "action": "sync" }
}

Consumers should parse the envelope and route on topic.

License

Copyright 2026 CloudScaile

Licensed under the Apache License, Version 2.0 — see LICENSE.