@squarecloud/api/lib/structures/backup.d.ts

A NodeJS wrapper for Square Cloud API

import '../api-DbJomjym.js';
import { APIService } from '../services/api.js';
import { Collection } from './collection.js';
import './error.js';
import * as _squarecloud_api_types_v2 from '@squarecloud/api-types/v2';
import { APIApplicationBackup, ApplicationLanguage, APIUserApplication, APIWebsiteApplication, APIApplication, DeploymentState, APIDeployment, ApplicationStatus as ApplicationStatus$1, APIApplicationStatus, APIApplicationStatusAll, APIUserInfo, RESTPostAPIApplicationBackupResult, RESTPostAPIApplicationUploadResult } from '@squarecloud/api-types/v2';
import { ApplicationStatusUsage } from '../types/application.js';
import { BaseCacheService } from '../services/cache/base.js';
import { UserPlan } from '../types/user.js';

/**
 * Represents an application backup (snapshot)
 */
declare class Backup {
    readonly application: BaseApplication;
    /** Size of the backup in bytes. */
    size: number;
    /** Date of the last modification of the backup. */
    modifiedAt: Date;
    /** Date of the last modification of the backup in millisseconds. */
    modifiedTimestamp: number;
    /** AWS access key for the backup. */
    readonly key: string;
    /** The URL for downloading this backup */
    readonly url: string;
    /**
     * Represents an application backup (snapshot)
     *
     * @constructor
     * @param application - The application from which you fetched the backups
     * @param data - The data from this backup
     */
    constructor(application: BaseApplication, data: APIApplicationBackup);
    /**
     * Downloads this backup
     * @returns The downloaded backup bufer
     */
    download(): Promise<Buffer>;
}

declare class TypedEventEmitter<TEvents extends Record<string, any>> {
    private emitter;
    emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArg: TEvents[TEventName]): void;
    on<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void;
    off<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void;
}
interface ClientEvents {
    logsUpdate: [
        application: BaseApplication | Application | WebsiteApplication,
        before: string | undefined,
        after: string
    ];
    backupsUpdate: [
        application: BaseApplication | Application | WebsiteApplication,
        before: Backup[] | undefined,
        after: Backup[]
    ];
    statusUpdate: [
        application: BaseApplication | Application | WebsiteApplication,
        before: ApplicationStatus | undefined,
        after: ApplicationStatus
    ];
    userUpdate: [before: User | undefined, after: User];
}

interface GlobalCache {
    readonly user?: User;
}
declare class GlobalCacheService extends BaseCacheService<GlobalCache> {
    protected cache: GlobalCache;
    get user(): User | undefined;
}

interface ApplicationCache {
    readonly status?: ApplicationStatus;
    readonly backups?: Backup[];
    readonly logs?: string;
}
declare class ApplicationCacheService extends BaseCacheService<ApplicationCache> {
    protected cache: ApplicationCache;
    get status(): ApplicationStatus | undefined;
    get backups(): Backup[] | undefined;
    get logs(): string | undefined;
}

/**
 * Represents the base application from the user endpoint
 */
declare class BaseApplication {
    readonly client: SquareCloudAPI;
    /** The application ID */
    readonly id: string;
    /** The application display name */
    name: string;
    /** The application description */
    description?: string;
    /** The url to manage the application via web */
    url: string;
    /** The application total ram */
    ram: number;
    /** The application current cluster */
    cluster: string;
    /**
     * The application programming language
     *
     * - `javascript`
     * - `typescript`
     * - `python`
     * - `java`
     * - `elixir`
     * - `rust`
     * - `go`
     * - `php`
     * - `dotnet`
     * - `static`
     */
    language: ApplicationLanguage;
    /** Cache service for this application */
    readonly cache: ApplicationCacheService;
    /** Files module for this application */
    readonly files: FilesModule;
    /** Backup module for this application */
    readonly backups: BackupsModule;
    /** Deploys module for this application */
    readonly deploys: DeploysModule;
    /**
     * Represents the base application from the user endpoint
     *
     * @constructor
     * @param client - The client for this application
     * @param data - The data from this application
     */
    constructor(client: SquareCloudAPI, data: APIUserApplication);
    /** @deprecated Use `Application#backups` instead */
    get backup(): BackupsModule;
    /**
     * Fetches this application for full information
     */
    fetch(): Promise<Application>;
    /**
     * Gets the application current status information
     */
    getStatus(): Promise<ApplicationStatus>;
    /**
     * Gets the application current logs
     */
    getLogs(): Promise<string>;
    /**
     * Starts up the application
     * @returns `boolean` for success or fail
     */
    start(): Promise<boolean>;
    /**
     * Stops the application
     * @returns `boolean` for success or fail
     */
    stop(): Promise<boolean>;
    /**
     * Restarts the application
     * @returns `boolean` for success or fail
     */
    restart(): Promise<boolean>;
    /**
     * Deletes your whole application
     * - This action is irreversible.
     *
     * @returns `boolean` for success or fail
     */
    delete(): Promise<boolean>;
    /**
     * Commit files to your application folder
     *
     * - This action is irreversible.
     *
     * - Tip: use this to get an absolute path.
     * ```ts
     * require('path').join(__dirname, 'fileName')
     * ```
     * - Tip 2: use a zip file to commit more than one archive
     *
     * @param file - Buffer or absolute path to the file
     * @param fileName - The file name (e.g.: "index.js")
     * @param restart - Whether the application should be restarted after the commit
     * @returns `true` for success or `false` for fail
     */
    commit(file: string | Buffer, fileName?: string): Promise<boolean>;
}

/**
 * Represents a Square Cloud application
 */
declare class WebsiteApplication extends Application {
    readonly client: SquareCloudAPI;
    /** The application default domain (e.g. example.squareweb.app) */
    domain: string;
    /** The custom configured domain (e.g. yoursite.com) */
    custom?: string;
    /** Network module for this application */
    readonly network: NetworkModule;
    /**
     * Represents a Square Cloud application
     *
     * @constructor
     * @param client - The client for this application
     * @param data - The data from this application
     */
    constructor(client: SquareCloudAPI, data: APIWebsiteApplication);
}

/**
 * Represents a Square Cloud application
 */
declare class Application extends BaseApplication {
    readonly client: SquareCloudAPI;
    /**
     * Represents a Square Cloud application
     *
     * @constructor
     * @param client - The client for this application
     * @param data - The data from this application
     */
    constructor(client: SquareCloudAPI, data: APIApplication);
    isWebsite(): this is WebsiteApplication;
}

/**
 * Represents an application deployment
 */
declare class Deployment {
    readonly application: BaseApplication;
    /** The ID of the deploy. */
    readonly id: `git-${string}`;
    /** The current state of the deploy. */
    state: DeploymentState;
    /** The date the deploy was created. */
    createdAt: Date;
    /** The date the deploy was created in millisseconds. */
    createdTimestamp: number;
    /**
     * Represents an application deployment
     *
     * @constructor
     * @param application - The application from which you fetched the deployment
     * @param data - The data from this deployment
     */
    constructor(application: BaseApplication, data: APIDeployment);
}

/**
 * Represents an application status fetched from status all endpoint
 */
declare class SimpleApplicationStatus<R extends boolean = boolean> {
    readonly client: SquareCloudAPI;
    /** The application's ID this status came from */
    readonly applicationId: string;
    /** Usage statuses for this application */
    usage: R extends true ? Pick<ApplicationStatusUsage, "cpu" | "ram"> : undefined;
    /** Whether the application is running or not */
    running: R;
    /**
     * Represents an application status fetched from status all endpoint
     *
     * @constructor
     * @param client - The client for this status
     * @param data - The data from this status
     */
    constructor(client: SquareCloudAPI, data: APIApplicationStatusAll);
    /**
     * Fetches the full application status
     */
    fetch(): Promise<ApplicationStatus>;
}
/**
 * Represents an application status
 */
declare class ApplicationStatus {
    readonly client: SquareCloudAPI;
    /** The application's ID this status came from */
    readonly applicationId: string;
    /** Usage statuses for this application */
    usage: ApplicationStatusUsage;
    /** Whether the application is running or not */
    running: boolean;
    /**
     * The status of the application
     *
     * - 'exited' (stopped)
     * - 'created' (being created)
     * - 'running'
     * - 'starting'
     * - 'restarting'
     * - 'deleting'
     */
    status: ApplicationStatus$1;
    /** For how long the app is running in millisseconds */
    uptimeTimestamp?: number;
    /** For how long the app is running */
    uptime?: Date;
    /**
     * Represents an application status
     *
     * @constructor
     * @param client - The client for this status
     * @param data - The data from this status
     * @param applicationId - The application ID this status came from
     */
    constructor(client: SquareCloudAPI, data: APIApplicationStatus, applicationId: string);
}

/**
 * Represents a Square Cloud user
 */
declare class User {
    /** The user's id */
    readonly id: string;
    /** The user's display name */
    name: string;
    /** The user's current plan */
    plan: UserPlan;
    /** The user's registered email */
    email: string;
    /** The user's registered applications Collection */
    applications: Collection<string, BaseApplication>;
    /**
     * Represents a Square Cloud user
     *
     * @constructor
     * @param client - The client for this user
     * @param data - The data from this user
     */
    constructor(client: SquareCloudAPI, data: APIUserInfo);
}

declare class BackupsModule {
    readonly application: BaseApplication;
    constructor(application: BaseApplication);
    /**
     * Gets the list of generated backups (snapshots) for this application
     */
    list(): Promise<Backup[]>;
    /**
     * Generates a new backup
     * @returns The generated backup URL and key
     */
    create(): Promise<RESTPostAPIApplicationBackupResult>;
    /**
     * Generates a new backup and downloads it
     * @returns The downloaded backup bufer
     */
    download(): Promise<Buffer>;
}

declare class DeploysModule {
    readonly application: BaseApplication;
    constructor(application: BaseApplication);
    /**
     * Integrates Square Cloud with GitHub webhooks
     *
     * @param accessToken - The access token for your GitHub repository. You can find this in your [GitHub Tokens Classic](https://github.com/settings/tokens/new)
     */
    integrateGithubWebhook(accessToken: string): Promise<string>;
    /**
     * Gets the last 10 deployments of an application from the last 24 hours
     */
    list(): Promise<Deployment[]>;
    /**
     * Gets the current webhook URL
     */
    webhookURL(): Promise<string>;
}

declare class FilesModule {
    readonly application: BaseApplication;
    constructor(application: BaseApplication);
    /**
     * Lists the files inside a directory
     *
     * @param path - The absolute directory path
     */
    list(path?: string): Promise<_squarecloud_api_types_v2.APIListedFile[]>;
    /**
     * Reads the specified file content
     *
     * @param path - The absolute file path
     */
    read(path: string): Promise<Buffer<ArrayBuffer> | undefined>;
    /**
     * Creates a new file
     *
     * @param file - The file content
     * @param fileName - The file name with extension
     * @param path - The absolute file path
     */
    create(file: string | Buffer, fileName: string, path?: string): Promise<boolean>;
    /**
     * Edits an existing file (same as create)
     *
     * @param file - The file content
     * @param path - The absolute file path
     */
    edit(file: string | Buffer, path?: string): Promise<boolean>;
    /**
     * Moves or renames a file
     *
     * @param path - The current absolute file path
     * @param newPath - The new absolute file path
     */
    move(path: string, newPath: string): Promise<boolean>;
    /**
     * Deletes the specified file or directory
     *
     * @param path - The absolute file or directory path
     */
    delete(path: string): Promise<boolean>;
}

declare class NetworkModule {
    readonly application: WebsiteApplication;
    constructor(application: WebsiteApplication);
    /**
     * Integrates your website with a custom domain
     * - Requires [Senior plan](https://squarecloud.app/plans) or higher
     *
     * @param custom - The custom domain you want to use (e.g. yoursite.com)
     */
    setCustomDomain(custom: string): Promise<boolean>;
    /**
     * Gets analytics for a custom domain
     * - Requires [Senior plan](https://squarecloud.app/plans) or higher
     * - Requires the application to have an integrated custom domain
     */
    analytics(): Promise<_squarecloud_api_types_v2.APINetworkAnalytics>;
    /**
     * Get the DNS records for your custom domain.
     */
    dns(): Promise<_squarecloud_api_types_v2.APINetworkDNS[]>;
}

declare class ApplicationsModule {
    readonly client: SquareCloudAPI;
    constructor(client: SquareCloudAPI);
    /**
     * If the ID is provided, it will return an application that you can manage or get information
     * If the ID is not provided, it will return a collection of applications
     *
     * @param applicationId - The application ID, you must own the application
     */
    get(): Promise<Collection<string, BaseApplication>>;
    get(applicationId: string): Promise<BaseApplication>;
    /**
     * Uploads an application
     *
     * @param file - The zip file path or Buffer
     *
     * @returns The uploaded application data
     */
    create(file: string | Buffer): Promise<RESTPostAPIApplicationUploadResult>;
    /**
     * Gets the summary status for all your applications
     */
    statusAll(): Promise<SimpleApplicationStatus[]>;
    /**
     * Returns an application that you can manage or get information
     *
     * @param applicationId - The application ID, you must own the application
     */
    fetch(applicationId: string): Promise<Application>;
}

declare class UserModule {
    readonly client: SquareCloudAPI;
    constructor(client: SquareCloudAPI);
    /**
     * Gets the authenticated user information
     */
    get(): Promise<User>;
}

declare class SquareCloudAPI extends TypedEventEmitter<ClientEvents> {
    static apiInfo: {
        baseUrl: string;
        version: string;
    };
    /** The API service */
    readonly api: APIService;
    /** The applications module */
    readonly applications: ApplicationsModule;
    /** The user module */
    readonly user: UserModule;
    /** The global cache service */
    readonly cache: GlobalCacheService;
    /**
     * Creates an API instance
     *
     * @param apiKey - Your API Token (request at [Square Cloud Dashboard](https://squarecloud.app/dashboard))
     */
    constructor(apiKey: string);
    /** @deprecated Use SquareCloudAPI#user instead. */
    get users(): UserModule;
}

export { type ApplicationCache as A, BaseApplication as B, Backup, type ClientEvents as C, Deployment as D, FilesModule as F, type GlobalCache as G, NetworkModule as N, SimpleApplicationStatus as S, TypedEventEmitter as T, User as U, WebsiteApplication as W, GlobalCacheService as a, ApplicationCacheService as b, Application as c, ApplicationStatus as d, BackupsModule as e, DeploysModule as f, ApplicationsModule as g, UserModule as h, SquareCloudAPI as i };