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 "@universal/release";

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

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

Configuration API​

import { ConfigManager } from "@universal/release";

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

Version Management API​

import { VersionManager } from "@universal/release";

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 "@universal/release";

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.