Browser Client API

Complete API reference for the browser Zapdos client. Only available in browser environments.

Client Creation

import { createBrowserClient } from "zapdos-js";

const client = createBrowserClient({
  baseUrl: "https://api.zapdoslabs.com", // Optional, defaults to this
  verbose: false, // Optional, enables debug logging
});

Upload Methods

upload(signedUrls, files, callbacks?)

Upload files using signed URLs from your backend:

// Single file upload
const result = await client.upload(signedUrl, file, callbacks);

// Multiple file upload
const results = await client.upload(signedUrlArray, fileArray, callbacks);

Parameters:

• signedUrls - String or array of signed URLs from your backend
• files - File or File[] objects from input elements
• callbacks - Optional upload callbacks

Example:

const fileInput = document.querySelector("#file-input");
const files = Array.from(fileInput.files);

// Get signed URLs from your backend
const signedUrls = await getSignedUrlsFromBackend(files.length);

const result = await client.upload(signedUrls, files, {
  onProgress: ({ file_index, value }) => {
    console.log(`File ${file_index}: ${value}%`);
  },
  onCompleted: ({ object_id, file_index }) => {
    console.log(`Upload completed: ${object_id}`);
  },
});

Upload Callbacks

The browser client supports the same callback interface as the backend client:

{
  onProgress: ({ file_index, value }) => {
    // Progress from 0-100
  },

  onStored: ({ file_index }) => {
    // File stored successfully
  },

  onCompleted: ({ object_id, file_index }) => {
    // Upload completed, object created
  },

  onFailed: ({ message, file_index }) => {
    // Upload failed
  },

  // Job status callbacks
  job: {
    onIndexingStarted: ({ object_id, job_id }) => {},
    onIndexingCompleted: ({ object_id, job_id }) => {},
    onIndexingFailed: ({ object_id, job_id }) => {},
    onTranscription: ({ object_id, job_id }) => {},
  }
}

File Input Handling

Getting Files from Input

// Single file
const fileInput = document.querySelector("#single-file");
const file = fileInput.files[0];

// Multiple files
const multiFileInput = document.querySelector("#multi-file");
const files = Array.from(multiFileInput.files);

File Type Validation

function validateFiles(files) {
  const allowedTypes = [
    "video/mp4",
    "video/avi",
    "video/mov",
    "image/jpeg",
    "image/png",
  ];

  return files.filter((file) => {
    if (!allowedTypes.includes(file.type)) {
      console.warn(`Unsupported file type: ${file.type}`);
      return false;
    }
    return true;
  });
}

const validFiles = validateFiles(Array.from(fileInput.files));

Integration Patterns

React Integration

import { useState } from "react";
import { createBrowserClient } from "zapdos-js";

function FileUploader() {
  const [uploading, setUploading] = useState(false);
  const [progress, setProgress] = useState({});
  const client = createBrowserClient();

  const handleUpload = async (files) => {
    setUploading(true);

    try {
      // Get signed URLs from your backend
      const signedUrls = await fetchSignedUrls(files.length);

      await client.upload(signedUrls, files, {
        onProgress: ({ file_index, value }) => {
          setProgress((prev) => ({ ...prev, [file_index]: value }));
        },
        onCompleted: ({ object_id }) => {
          console.log("Upload completed:", object_id);
        },
      });
    } catch (error) {
      console.error("Upload failed:", error);
    } finally {
      setUploading(false);
    }
  };

  return (
    <input
      type="file"
      multiple
      onChange={(e) => handleUpload(Array.from(e.target.files))}
      disabled={uploading}
    />
  );
}

Vue Integration

<template>
  <div>
    <input type="file" multiple @change="handleUpload" :disabled="uploading" />
    <div v-for="(progress, index) in uploadProgress" :key="index">
      File {{ index }}: {{ progress }}%
    </div>
  </div>
</template>

<script>
import { createBrowserClient } from "zapdos-js";

export default {
  data() {
    return {
      uploading: false,
      uploadProgress: {},
      client: createBrowserClient(),
    };
  },
  methods: {
    async handleUpload(event) {
      const files = Array.from(event.target.files);
      this.uploading = true;

      try {
        const signedUrls = await this.getSignedUrls(files.length);

        await this.client.upload(signedUrls, files, {
          onProgress: ({ file_index, value }) => {
            this.$set(this.uploadProgress, file_index, value);
          },
        });
      } catch (error) {
        console.error("Upload failed:", error);
      } finally {
        this.uploading = false;
      }
    },

    async getSignedUrls(count) {
      // Call your backend API
      const response = await fetch("/api/upload-urls", {
        method: "POST",
        body: JSON.stringify({ quantity: count }),
      });
      return response.json();
    },
  },
};
</script>

Error Handling

Handle upload errors gracefully:

const result = await client.upload(signedUrls, files, {
  onFailed: ({ message, file_index }) => {
    showError(`File ${file_index} failed: ${message}`);
  },
});

// Note: Browser uploads don't return result objects like backend client
// Use callbacks for success/error handling

Limitations

The browser client is limited compared to the backend client:

• No direct API access - Must use signed URLs from your backend
• No querying - Cannot fetch data directly (use your backend)
• No downloads - Cannot download files directly
• No WebSocket - Cannot connect to WebSocket directly
• No search - Cannot search content directly

Security

• Never expose API keys in browser code
• Always validate files on both client and server
• Use signed URLs with appropriate expiration times
• Implement rate limiting on your backend endpoints