# Required
FILES_HUB_API_KEY=fh_live_your_api_key_here
FILES_HUB_BASE_URL=https://fileshub.zaions.com

# Optional (for mobile apps with restricted API keys)
# FILES_HUB_APP_ID=com.example.myapp

# Files Hub Configuration
# Get your API key from the Files Hub admin panel
FILES_HUB_API_KEY=
FILES_HUB_BASE_URL=
# Optional: For mobile apps with restricted API keys
# FILES_HUB_APP_ID=

npm install @files-hub/sdk
# or
yarn add @files-hub/sdk
# or
pnpm add @files-hub/sdk

import { FilesHubClient } from '@files-hub/sdk';

const client = new FilesHubClient({
  baseUrl: process.env.FILES_HUB_BASE_URL + '/api/v1',
  apiKey: process.env.FILES_HUB_API_KEY,
  // For mobile apps:
  // appId: process.env.FILES_HUB_APP_ID
});

const result = await client.upload(file, {
  visibility: 'public' // or 'private'
});
console.log(result.url);       // URL to access the file
console.log(result.public_id); // Unique identifier

const { data: files, meta } = await client.list({
  page: 1,
  perPage: 20,
  visibility: 'public' // optional filter
});

console.log(`Page ${meta.current_page} of ${meta.last_page}`);
console.log(`Total files: ${meta.total}`);

// Get URL without network request (for public files)
const url = client.getObjectUrl('01HXYZ123ABC');
// Use directly: <img src={url} />

// Download as Blob (for private files or programmatic access)
const blob = await client.download('01HXYZ123ABC');
const objectUrl = URL.createObjectURL(blob);

await client.delete('01HXYZ123ABC');

import {
  isFilesHubError,
  FilesHubAuthError,
  FilesHubNotFoundError,
  FilesHubRateLimitError
} from '@files-hub/sdk';

try {
  await client.upload(file);
} catch (error) {
  if (error instanceof FilesHubAuthError) {
    // 401/403 - Authentication failed
    console.error('Check your API key');
  } else if (error instanceof FilesHubNotFoundError) {
    // 404 - File not found
    console.error('File does not exist');
  } else if (error instanceof FilesHubRateLimitError) {
    // 429 - Rate limited
    console.error('Too many requests, try again later');
  } else if (isFilesHubError(error)) {
    // Other API errors
    console.error('API error:', error.message);
  } else {
    throw error;
  }
}

// hooks/useFilesHub.ts
import { FilesHubClient } from '@files-hub/sdk';
import { useMemo } from 'react';

export function useFilesHub() {
  const client = useMemo(() => new FilesHubClient({
    baseUrl: import.meta.env.VITE_FILES_HUB_BASE_URL + '/api/v1',
    apiKey: import.meta.env.VITE_FILES_HUB_API_KEY
  }), []);

  return client;
}

// components/FileUploader.tsx
import { useFilesHub } from '../hooks/useFilesHub';
import { useState } from 'react';

export function FileUploader() {
  const client = useFilesHub();
  const [uploading, setUploading] = useState(false);
  const [uploadedUrl, setUploadedUrl] = useState<string | null>(null);

  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    setUploading(true);
    try {
      const result = await client.upload(file, { visibility: 'public' });
      setUploadedUrl(result.url);
    } catch (error) {
      console.error('Upload failed:', error);
    } finally {
      setUploading(false);
    }
  };

  return (
    <div>
      <input type="file" onChange={handleUpload} disabled={uploading} />
      {uploadedUrl && <p>Uploaded: {uploadedUrl}</p>}
    </div>
  );
}

interface UploadedObject {
  public_id: string;       // ULID identifier
  project_id: string;      // Project ULID
  visibility: 'public' | 'private';
  mime_type: string | null;
  size_bytes: number;
  url: string;
  created_at?: string;     // ISO 8601 format
}

interface ListedObject {
  public_id: string;
  original_filename: string;
  mime_type: string;
  size_bytes: number;
  visibility: 'public' | 'private';
  url: string;
  created_at: string;
}

interface ListObjectsResponse {
  data: ListedObject[];
  meta: PaginationMeta;
}

interface PaginationMeta {
  current_page: number;
  per_page: number;
  total: number;
  last_page?: number;
}