feat: create structure for backups list

Author: joaotonaco

.changeset/many-ducks-thank.md

@@ -0,0 +1,5 @@
+---
+"@squarecloud/api": patch
+---
+
+New structure for backups with download method. It's used at `backups.list()` method.

src/assertions/backup.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+import { assertAPIObject } from "./common";
+
+const BackupSchema = z.object({
+	name: z.string(),
+	size: z.number(),
+	modified: z.coerce.date(),
+	key: z.string(),
+});
+
+export function assertBackup(
+	value: unknown,
+): asserts value is z.infer<typeof BackupSchema> {
+	assertAPIObject({
+		schema: BackupSchema,
+		value,
+		code: "BACKUP",
+		route: "/apps/{app_id}/backups",
+	});
+}

src/modules/backups.ts

@@ -1,15 +1,14 @@
-import type {
-	APIApplicationBackup,
-	RESTPostAPIApplicationBackupResult,
-} from "@squarecloud/api-types/v2";
+import type { RESTPostAPIApplicationBackupResult } from "@squarecloud/api-types/v2";
 
 import { Routes } from "@/lib/routes";
 import { type BaseApplication, SquareCloudAPIError } from "@/structures";
+import { Backup } from "@/structures/backup";
 
 export class BackupsModule {
 	constructor(public readonly application: BaseApplication) {}
 
-	async list(): Promise<APIApplicationBackup[]> {
+	/** @returns The list of backups (snapshots) */
+	async list(): Promise<Backup[]> {
 		const data = await this.application.client.api.request(
 			Routes.apps.backups(this.application.id),
 		);
@@ -24,10 +23,10 @@ export class BackupsModule {
 		);
 		this.application.cache.set("backups", backups);
 
-		return backups;
+		return backups.map((backup) => new Backup(this.application, backup));
 	}
 
-	/** @returns The generated backup URL */
+	/** @returns The generated backup URL and key */
 	async create(): Promise<RESTPostAPIApplicationBackupResult> {
 		const data = await this.application.client.api.request(
 			Routes.apps.generateBackup(this.application.id),

src/services/api.ts

@@ -11,8 +11,11 @@ import type {
 export class APIService {
 	public readonly baseUrl = "https://api.squarecloud.app";
 	public readonly version: APIVersion<1 | 2> = "v2";
+	public readonly userId: string;
 
-	constructor(protected readonly apiKey: string) {}
+	constructor(protected readonly apiKey: string) {
+		this.userId = apiKey.split("-")[0];
+	}
 
 	async request<T extends APIEndpoint>(
 		...[path, options]: APIRequestArgs<T>

src/structures/backup.ts

@@ -0,0 +1,53 @@
+import type { APIApplicationBackup } from "@squarecloud/api-types/v2";
+
+import { assertBackup } from "@/assertions/backup";
+import type { BaseApplication } from "./application/base";
+
+export class Backup {
+	/** The ID of the application from which you fetched the backups. */
+	applicationId: string;
+
+	/** 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. */
+	key: string;
+
+	/** The URL for downloading this backup */
+	url: string;
+
+	constructor(
+		public readonly application: BaseApplication,
+		data: APIApplicationBackup,
+	) {
+		assertBackup(data);
+		const { name, size, modified, key } = data;
+		const { userId } = application.client.api;
+
+		this.applicationId = name;
+		this.size = size;
+		this.modifiedAt = new Date(modified);
+		this.modifiedTimestamp = this.modifiedAt.getTime();
+		this.key = key;
+		this.url = `https://backups.squarecloud.app/${userId}_${name}.zip?${key}`;
+	}
+
+	/** @returns The downloaded backup buffer */
+	async download(): Promise<Buffer> {
+		const res = await fetch(this.url)
+			.then((res) => res.arrayBuffer())
+			.catch(() => undefined);
+
+		if (!res) {
+			throw new Error("BACKUP_DOWNLOAD_FAILED");
+		}
+
+		return Buffer.from(res);
+	}
+}