@ziqx/drive Skill

This skill provides comprehensive instructions on how to use the @ziqx/drive package for managing file uploads to Ziqx Drive. It handles both server-side signed URL generation and client-side direct uploads.

Overview

@ziqx/drive is split into two main components:

1. ZDrive (Server-side): Used to securely generate signed upload URLs using your Drive credentials.
2. ZDriveClient (Client-side): Used in the browser to upload files directly to the signed URLs and perform image processing (like resizing) before upload.

---

Installation

npm install @ziqx/drive

---

Technical Implementation

1. Server-side: Generating Signed URLs

To allow a client to upload a file directly to Ziqx Drive, you must first generate a signed URL on your server. This prevents exposing your ZDRIVE_SECRET to the client.

API Reference: ZDrive

• constructor(driveKey: string, driveSecret: string)
• generatePutUrl(fileName: string): Promise<SignUrlResponse>

Logic Flow

1. Initialize ZDrive with your credentials.
2. Call generatePutUrl with the intended filename.
3. Return the url to the client.

---

2. Client-side: Uploading Files

The client uses the signed URL to perform a multipart/form-data POST request directly to Ziqx Drive.

API Reference: ZDriveClient

• uploadFile(uploadUrl: string, file: File): Promise<UploadResponse>
• resizeImage(file: File, maxWidth?: number, quality?: number): Promise<File> (Browser only)

Logic Flow

1. Obtain the signed URL from your server.
2. (Optional) Resize the image using ZDriveClient.resizeImage.
3. Call uploadFile with the signed URL and the File object.

---

Next.js Implementation Guide

This is the recommended pattern for Next.js applications using Server Actions.

A. Server Action (actions/drive.ts)

Create a server action to securely generate the signed URL.

"use server";

import { ENV } from "@/constants/envs";
import { ZDrive } from "@ziqx/drive";

/**
 * Generates a signed upload URL for Ziqx Drive.
 * This should ALWAYS be called from the server to protect credentials.
 */
export async function generateSignedUrl(fileName: string) {
  // Initialize with drive credentials from environment variables
  const drive = new ZDrive(ENV.ZDRIVE_KEY!, ENV.ZDRIVE_SECRET!);

  const signed = await drive.generatePutUrl(fileName);

  if (signed.success && signed.url) {
    return signed.url;
  } else {
    console.error("❌ Error generating URL:", signed.message);
    return null;
  }
}

B. Client Component Usage

Use ZDriveClient in your frontend components to handle the actual upload process.

"use client";

import { ZDriveClient } from "@ziqx/drive";
import { generateSignedUrl } from "@/actions/drive";

// ... inside your component

const handleUpload = async (options: any) => {
  const { file, onSuccess, onError } = options;
  const client = new ZDriveClient();

  try {
    // 1. Get signed URL from the server action
    const signedUrl = await generateSignedUrl(file.name);
    if (!signedUrl) throw new Error("Failed to get signed URL");

    // 2. Upload to Ziqx Drive directly from the browser
    const uploadRes = await client.uploadFile(signedUrl, file);

    if (!uploadRes.success || !uploadRes.filename) {
      throw new Error("Upload to ZDrive failed");
    }

    // 3. Handle success
    onSuccess(uploadRes.filename);
  } catch (err) {
    console.error("Upload Error:", err);
    onError(new Error("Upload failed"));
  }
};

---

Best Practices for AI Agents

1. Always use Environment Variables: Never hardcode driveKey or driveSecret. Ensure they are stored in .env and accessed via process.env or a config constants file.
2. Server vs Client separation: Remind the developer that ZDrive is for server-side (Node.js/Server Actions/API Routes) and ZDriveClient is for client-side (Browser). ZDriveClient uses browser-native FormData and fetch.
3. File Naming: When generating a signed URL, ensure the filename passed to generatePutUrl matches or is appropriate for the file being uploaded.
4. Error Handling: Always check for signed.success on the server and uploadRes.success on the client.
5. Image Optimization: If the user is uploading images, suggest using client.resizeImage(file, 1024, 0.8) before calling uploadFile to save bandwidth and storage.

---

Examples

Simple Client-side Upload Logic

const signedUrl = await generateSignedUrl(file.name);
if (!signedUrl) throw new Error("Failed to get signed URL");

// Upload to Object Storage
const client = new ZDriveClient();
const uploadRes = await client.uploadFile(signedUrl, file);

if (!uploadRes.success || !uploadRes.filename)
  throw new Error("Upload to ZDrive failed");

console.log("Uploaded filename:", uploadRes.filename);