Publishing System

/**
 * Publish artifacts with specified files and configuration
 * @param args - Publishing arguments including files and policy
 * @returns Promise resolving when publishing completes
 */
function publish(args: {
  /** Array of file paths to publish */
  files: string[];
  /** Application version for release matching */
  version: string | undefined;
  /** Path to configuration file */
  configurationFilePath: string | undefined;
  /** Publishing policy */
  policy: PublishPolicy;
}): Promise<any>;

/**
 * Publish artifacts with advanced options and custom configuration
 * @param uploadOptions - File and architecture specifications
 * @param buildVersion - Override build version
 * @param configurationFilePath - Custom config file path
 * @param publishConfiguration - Inline publish configuration
 * @param publishOptions - Publishing behavior options
 * @returns Promise resolving to upload tasks or null on failure
 */
function publishArtifactsWithOptions(
  uploadOptions: Array<{file: string; arch: string | null}>,
  buildVersion?: string,
  configurationFilePath?: string,
  publishConfiguration?: PublishConfiguration,
  publishOptions?: PublishOptions
): Promise<Array<UploadTask> | null>;

/**
 * Publishing policy determining when to publish
 */
type PublishPolicy = "onTag" | "onTagOrDraft" | "always" | "never";

import { publish, publishArtifactsWithOptions } from "electron-builder";

// Basic publishing
await publish({
  files: ["dist/MyApp-1.0.0.dmg", "dist/MyApp Setup 1.0.0.exe"],
  version: "1.0.0",
  configurationFilePath: undefined,
  policy: "onTagOrDraft"
});

// Advanced publishing with specific architecture
await publishArtifactsWithOptions([
  { file: "dist/MyApp-1.0.0-x64.dmg", arch: "x64" },
  { file: "dist/MyApp-1.0.0-arm64.dmg", arch: "arm64" }
], "1.0.0");

/**
 * Manager coordinating artifact publishing across providers
 */
class PublishManager {
  constructor(packager: Packager, options: PublishOptions, cancellationToken?: CancellationToken);
  
  /** Whether publishing is enabled */
  readonly isPublish: boolean;
  
  /** Get global publish configurations from build config */
  getGlobalPublishConfigurations(): Promise<Array<PublishConfiguration> | null>;
  
  /** Schedule upload task for specific publish configuration */
  scheduleUpload(
    publishConfig: PublishConfiguration, 
    uploadTask: UploadTask, 
    appInfo: AppInfo
  ): Promise<any>;
  
  /** Wait for all scheduled uploads to complete */
  awaitTasks(): Promise<Array<string>>;
  
  /** Cancel all pending upload tasks */
  cancelTasks(): void;
}

/**
 * Publishing behavior options
 */
interface PublishOptions {
  /** Publishing policy */
  publish?: PublishPolicy | null;
  /** Publisher-specific options */
  publisherOptions?: any;
}

/**
 * Individual file upload task
 */
interface UploadTask {
  /** Path to file being uploaded */
  file: string;
  /** Target architecture for the file */
  arch: Arch | null;
  /** Safe filename for publishing (no special characters) */
  safeArtifactName?: string;
  /** Update information for auto-updater */
  updateInfo?: any;
}

/**
 * Base publish configuration
 */
interface PublishConfiguration {
  /** Publisher provider name */
  provider: string;
  /** Update channel name */
  channel?: string | null;
  /** Additional provider-specific options */
  [key: string]: any;
}

/**
 * GitHub Releases publisher configuration
 */
interface GithubOptions extends PublishConfiguration {
  provider: "github";
  /** Repository owner */
  owner?: string;
  /** Repository name */
  repo?: string;
  /** GitHub token (usually from environment) */
  token?: string;
  /** Use v-prefixed tags */
  vPrefixedTagName?: boolean;
  /** Release as draft */
  draft?: boolean;
  /** Release as prerelease */
  prerelease?: boolean;
  /** Private repository */
  private?: boolean;
  /** GitHub API URL for enterprise */
  host?: string;
  /** Release name template */
  releaseName?: string;
  /** Release body/notes */
  releaseNotes?: string;
}

/**
 * AWS S3 publisher configuration
 */
interface S3Options extends PublishConfiguration {
  provider: "s3";
  /** S3 bucket name */
  bucket: string;
  /** AWS region */
  region?: string;
  /** S3 ACL */
  acl?: "private" | "public-read" | "public-read-write" | "authenticated-read";
  /** S3 object key prefix */
  path?: string;
  /** Custom endpoint URL */
  endpoint?: string;
  /** Access key ID */
  accessKeyId?: string;
  /** Secret access key */
  secretAccessKey?: string;
  /** Session token */
  sessionToken?: string;
}

/**
 * DigitalOcean Spaces publisher configuration
 */
interface SpacesOptions extends PublishConfiguration {
  provider: "spaces";
  /** Spaces name */
  name: string;
  /** Spaces region */
  region: string;
  /** Spaces ACL */
  acl?: "private" | "public-read";
  /** Object key prefix */
  path?: string;
  /** Access key ID */
  accessKeyId?: string;
  /** Secret access key */
  secretAccessKey?: string;
}

/**
 * Generic HTTP publisher configuration
 */
interface GenericServerOptions extends PublishConfiguration {
  provider: "generic";
  /** Base URL for downloads */
  url: string;
  /** Update channel */
  channel?: string;
  /** Whether to use multiple range requests */
  useMultipleRangeRequest?: boolean;
}

import { Configuration, GithubOptions, S3Options } from "electron-builder";

const config: Configuration = {
  // Multiple publish providers
  publish: [
    {
      provider: "github",
      owner: "myorg",
      repo: "myapp",
      draft: false,
      prerelease: false
    } as GithubOptions,
    {
      provider: "s3",
      bucket: "myapp-releases",
      region: "us-east-1",
      acl: "public-read",
      path: "releases/"
    } as S3Options
  ]
};

/**
 * Abstract base class for all publishers
 */
abstract class Publisher {
  constructor(context: PublishContext, version: string);
  
  /** Upload single file */
  abstract upload(task: UploadTask): Promise<any>;
  
  /** Upload multiple files */
  uploadMultiple(tasks: Array<UploadTask>): Promise<any>;
  
  /** Get upload URL for file */
  abstract toString(): string;
}

/**
 * GitHub Releases publisher
 */
class GitHubPublisher extends Publisher {
  constructor(context: PublishContext, options: GithubOptions, version: string, isPublishOptionGuessed?: boolean);
  
  /** Upload artifact to GitHub release */
  upload(task: UploadTask): Promise<any>;
  
  /** Delete release tag */
  deleteRelease(): Promise<any>;
  
  /** Get release info */
  getRelease(): Promise<any>;
  
  /** Create or update release */
  createOrUpdateRelease(): Promise<any>;
}

/**
 * S3 publisher for AWS S3
 */
class S3Publisher extends Publisher {
  constructor(context: PublishContext, options: S3Options);
  
  /** Upload artifact to S3 bucket */
  upload(task: UploadTask): Promise<any>;
}

/**
 * DigitalOcean Spaces publisher
 */
class SpacesPublisher extends Publisher {
  constructor(context: PublishContext, options: SpacesOptions);
  
  /** Upload artifact to Spaces */
  upload(task: UploadTask): Promise<any>;
}

/**
 * Publishing execution context
 */
interface PublishContext {
  /** Cancellation token */
  cancellationToken: CancellationToken;
  /** Progress callback for upload tracking */
  progress?: ProgressCallback | null;
}

/**
 * Upload progress callback
 */
type ProgressCallback = (transferred: number, total: number) => void;

/**
 * Progress information during uploads
 */
interface ProgressInfo {
  /** Total bytes to transfer */
  total: number;
  /** Bytes transferred in this update */
  delta: number;
  /** Total bytes transferred so far */
  transferred: number;
  /** Completion percentage (0-100) */
  percent: number;
  /** Transfer rate in bytes per second */
  bytesPerSecond: number;
}

/**
 * Update information for auto-updater
 */
interface UpdateInfo {
  /** Application version */
  version: string;
  /** Release notes */
  releaseNotes?: string | Array<ReleaseNoteInfo> | null;
  /** Release name */
  releaseName?: string | null;
  /** Release date */
  releaseDate: string;
  /** Update files */
  files: Array<UpdateFileInfo>;
  /** Download path */
  path: string;
  /** File hash for integrity */
  sha256: string;
  /** File hash (deprecated, use sha256) */
  sha512?: string;
}

/**
 * Update file information
 */
interface UpdateFileInfo {
  /** File URL */
  url: string;
  /** File size in bytes */
  size: number;
  /** File SHA-256 hash */
  sha256: string;
  /** File SHA-512 hash (deprecated) */
  sha512?: string;
}

/**
 * Release note information
 */
interface ReleaseNoteInfo {
  /** Version for this release note */
  version: string;
  /** Release note content */
  note: string | null;
}

// Publishing with environment-based authentication
const config = {
  publish: {
    provider: "github",
    // Token automatically read from GH_TOKEN or GITHUB_TOKEN
    owner: "myorg",
    repo: "myapp"
  }
};

// CI/CD integration
if (process.env.CI && process.env.GITHUB_REF?.startsWith('refs/tags/')) {
  await build({
    config,
    publish: "onTag"
  });
}

/**
 * HTTP error during publishing
 */
class HttpError extends Error {
  readonly statusCode: number;
  readonly statusMessage?: string;
  readonly headers?: any;
}

/**
 * Cancellation error for interrupted uploads
 */
class CancellationError extends Error {
  readonly name: "CancellationError";
}