@xstbot/cdn-arsy

Client SDK ringan berbasis Promise untuk berinteraksi dengan API CDN Uploader. Kompatibel secara penuh untuk penggunaan di sisi Node.js maupun Browser.

Library ini didesain dengan pola RPC (Remote Procedure Call) pintar, sehingga secara otomatis menangani berbagai skenario pengunggahan (Single & Multipart) melalui satu pintu endpoint di backend Anda.

Instalasi

Gunakan npm untuk menginstal library:

```bash npm install @xstbot/cdn-arsy ```

Cara Penggunaan

Inisialisasi

Anda hanya perlu memasukkan URL domain utama aplikasi/API. Library ini akan secara otomatis mengarahkan ke endpoint yang tepat (otomatis menambahkan /api/v1 di belakang layar).

```javascript import { ArsyUploader } from '@xstbot/cdn-arsy';

const uploader = new ArsyUploader({ // Cukup masukkan domain utama Anda baseURL: 'https://url-website-cdn.com' }); ```

1. Single Upload (Untuk file berukuran standar hingga 5 GB)

Menginisialisasi sesi transmisi tunggal untuk payload biner. Sistem akan merespons dengan Presigned URL untuk Anda melakukan upload langsung.

```javascript async function getUploadUrl() { try { const response = await uploader.requestSingleUploadUrl({ originalName: "foto_profil.jpg", contentType: "image/jpeg", fileSize: 102400, folder: "images/users" // Opsional: untuk custom folder. });

console.log("URL Presigned:", response.uploadUrl);
console.log("URL Publik File Nanti:", response.publicUrl);

// Lanjutkan dengan melakukan PUT request ke uploadUrl menggunakan file biner Anda
// fetch(response.uploadUrl, { method: "PUT", body: fileBiner Anda });

} catch (error) { console.error("Gagal mendapatkan URL:", error.message); } } ```

2. Multipart Upload (Untuk File Besar)

Library ini menyediakan fungsi startMultipartUpload dan completeMultipartUpload untuk mengunggah file dalam bentuk pecahan (chunks/parts).

```javascript async function processLargeUpload() { try { // A. Mulai Sesi Multipart const startRes = await uploader.startMultipartUpload({ originalName: "video-besar.mp4", contentType: "video/mp4", totalParts: 5, // Jumlah pecahan file Anda folder: "media/videos" // Opsional });

console.log("Upload ID:", startRes.uploadId);

// B. Lakukan proses PUT request ke masing-masing URL part yang ada di `startRes.parts`
// (Proses pengunggahan biner tidak dicakup library ini dan harus ditangani di frontend)
// Contoh response parts: [{ partNumber: 1, url: "..." }, { partNumber: 2, url: "..." }]

// C. Selesaikan Multipart & Validasi ETag
const completeRes = await uploader.completeMultipartUpload({
  objectKey: startRes.objectKey,
  uploadId: startRes.uploadId,
  completedParts: [
    { PartNumber: 1, ETag: "hash_etag_part_1" },
    { PartNumber: 2, ETag: "hash_etag_part_2" }
    // ... lanjutkan sesuai jumlah part
  ]
});

console.log("Upload Selesai! URL Publik:", completeRes.publicUrl);

} catch (error) { console.error("Gagal memproses multipart:", error.message); } } ```

3. Hapus File (Delete Asset)

Menghapus file secara permanen dari seluruh node jaringan CDN.

```javascript async function removeAsset() { try { // Masukkan objectKey (path file lengkap) const response = await uploader.deleteFile("images/users/foto_profil.jpg"); console.log("Status penghapusan:", response.success); } catch (error) { console.error("Gagal menghapus:", error.message); } } ```

4. Cek Keberadaan File (Exists)

Fungsi utilitas untuk mengecek apakah sebuah file eksis di dalam CDN. Berguna untuk memvalidasi overwrite atau mengambil metadata (Content-Length, tipe file, dll) sebelum diunduh.

```javascript async function checkFile() { try { const response = await uploader.checkExists("images/users/foto_profil.jpg"); if (response.exists) { console.log("File Ditemukan!", response.metadata); } else { console.log("File tidak ditemukan."); } } catch (error) { console.error("Gagal mengecek:", error.message); } } ```