File Uploads

/**
 * Create a new file upload
 * @param args - File upload creation parameters
 * @returns Promise resolving to file upload object
 */
fileUploads.create(args: CreateFileUploadParameters): Promise<CreateFileUploadResponse>;

interface CreateFileUploadParameters {
  /** Name of the file */
  name: string;
  /** MIME type of the file */
  file_type: string;
  /** Size of the file in bytes */
  file_size: number;
  /** Parent page for the file */
  parent?: {
    type: "page_id";
    page_id: string;
  };
}

type CreateFileUploadResponse = FileUploadObjectResponse;

// Create file upload for image
const fileUpload = await notion.fileUploads.create({
  name: "screenshot.png",
  file_type: "image/png",
  file_size: 1024768, // Size in bytes
  parent: { type: "page_id", page_id: "page-id" },
});

console.log(fileUpload.upload_url); // URL to upload file data
console.log(fileUpload.file.url); // Final file URL after upload

/**
 * Send file data to an upload
 * @param args - File upload send parameters
 * @returns Promise resolving to upload response
 */
fileUploads.send(args: SendFileUploadParameters): Promise<SendFileUploadResponse>;

interface SendFileUploadParameters {
  /** ID of the file upload */
  file_upload_id: string;
  /** File data to upload */
  file: Blob | Buffer | string;
}

type SendFileUploadResponse = {
  object: "file_upload";
  id: string;
  status: "pending" | "processing" | "complete" | "failed";
};

// Send file data (browser)
const fileInput = document.getElementById('file') as HTMLInputElement;
const file = fileInput.files?.[0];

if (file) {
  const sendResponse = await notion.fileUploads.send({
    file_upload_id: fileUpload.id,
    file: file,
  });
}

// Send file data (Node.js)
import fs from 'fs';

const fileBuffer = fs.readFileSync('path/to/file.png');
const sendResponse = await notion.fileUploads.send({
  file_upload_id: fileUpload.id,
  file: fileBuffer,
});

/**
 * Complete a file upload
 * @param args - File upload completion parameters
 * @returns Promise resolving to completed upload
 */
fileUploads.complete(args: CompleteFileUploadParameters): Promise<CompleteFileUploadResponse>;

interface CompleteFileUploadParameters {
  /** ID of the file upload to complete */
  file_upload_id: string;
}

type CompleteFileUploadResponse = FileUploadObjectResponse;

// Complete the upload process
const completedUpload = await notion.fileUploads.complete({
  file_upload_id: fileUpload.id,
});

console.log(completedUpload.status); // Should be "complete"
console.log(completedUpload.file.url); // Final accessible file URL

/**
 * Retrieve a file upload by ID
 * @param args - File upload retrieval parameters
 * @returns Promise resolving to file upload object
 */
fileUploads.retrieve(args: GetFileUploadParameters): Promise<GetFileUploadResponse>;

interface GetFileUploadParameters {
  /** ID of the file upload to retrieve */
  file_upload_id: string;
}

type GetFileUploadResponse = FileUploadObjectResponse;

// Check upload status
const uploadStatus = await notion.fileUploads.retrieve({
  file_upload_id: "upload-id",
});

console.log(uploadStatus.status); // "pending", "processing", "complete", or "failed"

if (uploadStatus.status === "complete") {
  console.log("File uploaded successfully:", uploadStatus.file.url);
} else if (uploadStatus.status === "failed") {
  console.log("Upload failed");
}

/**
 * List file uploads
 * @param args - File upload list parameters
 * @returns Promise resolving to list of file uploads
 */
fileUploads.list(args: ListFileUploadsParameters): Promise<ListFileUploadsResponse>;

interface ListFileUploadsParameters {
  /** Pagination cursor */
  start_cursor?: string;
  /** Page size (max 100) */
  page_size?: number;
}

type ListFileUploadsResponse = {
  object: "list";
  results: FileUploadObjectResponse[];
  next_cursor: string | null;
  has_more: boolean;
  type: "file_upload";
  file_upload: Record<string, unknown>;
};

// List recent file uploads
const uploads = await notion.fileUploads.list({
  page_size: 50,
});

uploads.results.forEach(upload => {
  console.log(`${upload.name}: ${upload.status}`);
});

// Paginated listing
const uploadsPage = await notion.fileUploads.list({
  start_cursor: "cursor-token",
  page_size: 25,
});

// Complete file upload workflow
async function uploadFile(file: File, pageId: string) {
  // 1. Create upload
  const fileUpload = await notion.fileUploads.create({
    name: file.name,
    file_type: file.type,
    file_size: file.size,
    parent: { type: "page_id", page_id: pageId },
  });

  // 2. Send file data
  await notion.fileUploads.send({
    file_upload_id: fileUpload.id,
    file: file,
  });

  // 3. Complete upload
  const completedUpload = await notion.fileUploads.complete({
    file_upload_id: fileUpload.id,
  });

  return completedUpload.file.url; // Final file URL
}

interface FileUploadObjectResponse {
  object: "file_upload";
  id: string;
  created_time: string;
  name: string;
  file_type: string;
  file_size: number;
  status: "pending" | "processing" | "complete" | "failed";
  upload_url?: string;
  file: {
    url: string;
    expiry_time: string;
  };
  parent?: {
    type: "page_id";
    page_id: string;
  };
}