alacritty-theme-switch
Version:
CLI utility for switching Alacritty color themes
166 lines • 7.47 kB
TypeScript
import { Result, type ResultAsync } from "neverthrow";
import { type FilePath } from "../../utils/fs-utils.js";
import { Theme } from "../theme.js";
import { FileDownloadError, GitHubApiError, InvalidRepositoryUrlError } from "./errors.js";
/**
* GitHub client for fetching Alacritty themes from a remote repository.
*
* This client provides methods to list and download TOML theme files from a GitHub repository.
* It uses GitHub's REST API v3 for listing files, but downloads content directly from
* raw.githubusercontent.com to avoid API rate limits.
*
* API rate limits (only applies to listing):
* - Without authentication: 60 requests per hour
* - With authentication: 5000 requests per hour
*
* Raw content downloads are not subject to API rate limits.
*
* Note: This class is not exported directly. Use the `createGitHubClient` factory function
* to create instances with proper error handling.
*
* @internal
*/
declare class GitHubClient {
#private;
/**
* Creates a new GitHub client for the specified repository.
*
* This constructor assumes that the owner and repo values are well-formed.
* Use the `createGitHubClient` factory function for URL parsing and validation.
*
* @param owner - GitHub repository owner
* @param repo - GitHub repository name
* @param ref - Git reference (branch, tag, or commit SHA) to use for downloads (default: "master")
* @param token - Optional GitHub personal access token for authentication
*
* @internal
*/
constructor(owner: string, repo: string, ref?: string, token?: string);
/**
* Lists all TOML theme files in the repository.
*
* This method fetches the repository tree recursively and filters for files
* with a .toml extension. The returned themes have their path set to the
* remote path in the repository.
*
* @returns A ResultAsync containing an array of themes or an error
*/
listThemes(): ResultAsync<Theme[], GitHubApiError>;
/**
* Downloads a single theme file from the repository to the specified output directory.
*
* This method fetches the file content directly from raw.githubusercontent.com,
* which is not subject to GitHub API rate limits. The file will be saved with
* its original filename in the output directory. If the output directory doesn't
* exist, it will be created.
*
* @param remotePath - Path to the theme file in the repository (e.g., "themes/monokai_pro.toml")
* @param outputPath - Local directory path where the theme should be saved
* @returns A ResultAsync containing the downloaded theme with local path or an error
*
* @example
* const client = new GitHubClient("https://github.com/alacritty/alacritty-theme");
* const result = await client.downloadTheme(
* "themes/monokai_pro.toml",
* "./my-themes"
* )
*
* if (result.isOk()) {
* console.log(`Downloaded theme to: ${result.data.path}`);
* } else {
* console.error("Download failed:", result.error);
* }
*/
downloadTheme(remotePath: string, outputPath: FilePath): ResultAsync<Theme, import("../../utils/fs-errors.js").DirectoryNotAccessibleError | import("../../utils/fs-errors.js").WriteError | import("../../utils/toml-errors.js").TomlParseError | FileDownloadError>;
/**
* Downloads all TOML theme files from the repository to the specified output directory.
*
* This method downloads each theme file sequentially from raw.githubusercontent.com, which is not
* subject to API rate limits. It also downloads the repository's LICENSE file to preserve
* proper attribution, naming it uniquely to avoid conflicts when downloading from multiple
* repositories.
*
* If the output directory doesn't exist, it will be created.
*
* @param themes - Array of themes to download (typically obtained from listThemes())
* @param outputPath - Local directory path where themes should be saved
* @param onProgress - Optional callback to report download progress
* @returns A ResultAsync containing an array of downloaded themes with local paths or an error
*
* @example
* ```typescript
* const client = new GitHubClient("https://github.com/alacritty/alacritty-theme");
* const themesResult = await client.listThemes()
*
* if (themesResult.isOk()) {
* const result = await client.downloadAllThemes(themesResult.data, "./my-themes")
*
* if (result.isOk()) {
* console.log(`Downloaded ${result.data.length} themes`);
* result.data.forEach(theme => {
* console.log(` - ${theme.label}`);
* });
* } else {
* console.error("Download failed:", result.error);
* }
* }
* ```
*
* @example With progress callback
* ```typescript
* const client = new GitHubClient("https://github.com/alacritty/alacritty-theme");
* const themesResult = await client.listThemes()
*
* if (themesResult.isOk()) {
* const result = await client.downloadAllThemes(
* themesResult.data,
* "./my-themes",
* (current, total) => {
* console.log(`Progress: ${current}/${total}`);
* }
* )
* }
* ```
*/
downloadAllThemes(themes: Theme[], outputPath: FilePath, onProgress?: (current: number, total: number) => void): ResultAsync<Theme[], import("../../utils/fs-errors.js").DirectoryNotAccessibleError | import("../../utils/fs-errors.js").WriteError | import("../../utils/toml-errors.js").TomlParseError | FileDownloadError>;
}
/**
* Creates a new GitHub client for the specified repository.
*
* This factory function parses the repository URL and returns a Result containing
* either a GitHubClient instance or an error if the URL format is invalid.
*
* The client will automatically use a GitHub token from the GITHUB_TOKEN environment
* variable if available, which increases the API rate limit from 60 to 5000 requests/hour.
* Note that only the listing operation uses the API; downloads fetch directly from
* raw.githubusercontent.com and are not subject to rate limits.
*
* @param repositoryUrl - GitHub repository URL in one of the following formats:
* - https://github.com/owner/repo
* - https://github.com/owner/repo.git
* - git@github.com:owner/repo.git
* @param ref - Git reference (branch, tag, or commit SHA) to use for downloads (default: "master")
* @param token - Optional GitHub personal access token. If not provided, will check GITHUB_TOKEN env var
*
* @returns A Result containing the GitHubClient instance or an InvalidRepositoryUrlError
*
* @example
* import { createGitHubClient } from "./github/client.ts";
*
* const clientResult = createGitHubClient("https://github.com/alacritty/alacritty-theme");
*
* if (clientResult.isOk()) {
* const client = clientResult.data;
*
* // List all themes in the repository
* const themesResult = await client.listThemes()
* if (themesResult.isOk()) {
* console.log(`Found ${themesResult.data.length} themes`);
* }
* } else {
* console.error("Invalid repository URL:", clientResult.error);
* }
*/
export declare function createGitHubClient(repositoryUrl: string, ref?: string, token?: string): Result<GitHubClient, InvalidRepositoryUrlError>;
export {};
//# sourceMappingURL=client.d.ts.map