Skip to main content

API Overview

Universal Release provides both a CLI and a programmatic API for release automation.

CLI API​

The command-line interface provides the primary way to interact with Universal Release.

Core Commands​

# Publishing
release publish [options]
release publish --ecosystem <ecosystem>
release publish --dry-run
release publish --tag <tag>

# Version Management
release version
release version --bump <major|minor|patch>
release version --set <version>
release version --detect

# Secrets Management
release secrets set <key>
release secrets get <key>
release secrets delete <key>
release secrets export <key>

# Validation
release validate
release validate --ecosystem <ecosystem>

# Configuration
release config --validate
release config --show

Programmatic API​

You can also use Universal Release as a library in your TypeScript/JavaScript projects.

Basic Example​

import { ReleaseOrchestrator } from '@kjanat/releaser';

const orchestrator = new ReleaseOrchestrator({
configPath: '.release.yaml',
dryRun: false,
});

// Publish package
await orchestrator.publish({
ecosystem: 'npm',
tag: 'latest',
});

Configuration API​

import { ConfigManager } from '@kjanat/releaser';

const config = await ConfigManager.load('.release.yaml');
console.log(config.ecosystems.npm);

Version Management API​

import { VersionManager } from '@kjanat/releaser';

const vm = new VersionManager();

// Bump version
const newVersion = vm.bump('1.0.0', 'minor'); // '1.1.0'

// Parse version
const parsed = vm.parse('1.2.3-beta.1');

// Compare versions
const isGreater = vm.compare('2.0.0', '1.9.9'); // 1

Adapter API​

Create custom ecosystem adapters by implementing the PackageManagerAdapter interface.

Adapter Interface​

interface PackageManagerAdapter {
// Detection
canHandle(packagePath: string): Promise<boolean>;

// Version management
readVersion(packagePath: string): Promise<string>;
writeVersion(packagePath: string, version: string): Promise<void>;

// Metadata
getPackageInfo(packagePath: string): Promise<PackageInfo>;

// Validation
validate(packagePath: string, config: EcosystemConfig): Promise<ValidationResult>;

// Publishing
publish(packagePath: string, config: PublishConfig): Promise<PublishResult>;
verify(packageName: string, version: string): Promise<boolean>;

// Rollback
rollback(packageName: string, version: string, strategy: RollbackStrategy): Promise<void>;
}

Custom Adapter Example​

import { PackageManagerAdapter } from '@kjanat/releaser';

export class MyCustomAdapter implements PackageManagerAdapter {
async canHandle(packagePath: string): Promise<boolean> {
// Check if this adapter can handle the package
const manifestPath = path.join(packagePath, 'my-manifest.json');
return await fs.exists(manifestPath);
}

async readVersion(packagePath: string): Promise<string> {
// Read version from manifest
const manifest = await fs.readJSON(path.join(packagePath, 'my-manifest.json'));
return manifest.version;
}

// Implement other methods...
}

Next Steps​

Explore the other documentation sections to learn more about Universal Release.