Data Upload and Chunking

/**
 * Get a resumable uploader for large transactions
 * @param upload - Transaction, serialized uploader, or transaction ID
 * @param data - Optional data buffer for new uploads
 * @returns Promise resolving to TransactionUploader instance
 */
getUploader(
  upload: Transaction | SerializedUploader | string,
  data?: Uint8Array | ArrayBuffer
): Promise<TransactionUploader>;

import Arweave from "arweave";

const arweave = Arweave.init();
const key = await arweave.wallets.generate();

// Large data upload
const largeData = new Uint8Array(1024 * 1024); // 1MB of data
const transaction = await arweave.createTransaction({ data: largeData }, key);
await arweave.transactions.sign(transaction, key);

const uploader = await arweave.transactions.getUploader(transaction);

// Upload with progress monitoring
while (!uploader.isComplete) {
  await uploader.uploadChunk();
  console.log(`Progress: ${uploader.pctComplete}%`);
}

/**
 * Upload data with async generator for progress tracking
 * @param upload - Transaction, serialized uploader, or transaction ID  
 * @param data - Data to upload
 * @returns Async generator yielding TransactionUploader instances
 */
upload(
  upload: Transaction | SerializedUploader | string, 
  data: Uint8Array
): AsyncGenerator<TransactionUploader>;

const largeData = new Uint8Array(5 * 1024 * 1024); // 5MB
const transaction = await arweave.createTransaction({ data: largeData }, key);
await arweave.transactions.sign(transaction, key);

// Upload with generator
for await (const uploader of arweave.transactions.upload(transaction, largeData)) {
  console.log(`Uploaded ${uploader.uploadedChunks}/${uploader.totalChunks} chunks`);
  console.log(`Progress: ${uploader.pctComplete}%`);
}

/**
 * Get transaction offset information
 * @param id - Transaction ID
 * @returns Promise resolving to offset response
 */
getTransactionOffset(id: string): Promise<TransactionOffsetResponse>;

const offsetInfo = await arweave.chunks.getTransactionOffset("transaction-id");
console.log(`Transaction size: ${offsetInfo.size}`);
console.log(`Transaction offset: ${offsetInfo.offset}`);

/**
 * Get chunk at specific offset
 * @param offset - Chunk offset as string, number, or BigInt
 * @returns Promise resolving to chunk response
 */
getChunk(offset: string | number | BigInt): Promise<TransactionChunkResponse>;

const chunk = await arweave.chunks.getChunk(12345);
console.log("Chunk data:", chunk.chunk);
console.log("Data path:", chunk.data_path);

/**
 * Get chunk data as Uint8Array
 * @param offset - Chunk offset
 * @returns Promise resolving to chunk data
 */
getChunkData(offset: string | number | BigInt): Promise<Uint8Array>;

const chunkData = await arweave.chunks.getChunkData(12345);
console.log("Raw chunk data:", chunkData);

/**
 * Calculate first chunk offset
 * @param offsetResponse - Transaction offset response
 * @returns First chunk offset as number
 */
firstChunkOffset(offsetResponse: TransactionOffsetResponse): number;

/**
 * Download all chunks for a transaction
 * @param id - Transaction ID
 * @returns Promise resolving to complete data
 */
downloadChunkedData(id: string): Promise<Uint8Array>;

// Download complete data for a large transaction
const fullData = await arweave.chunks.downloadChunkedData("transaction-id");
console.log("Downloaded data size:", fullData.length);

// Convert to string if it's text data
const textData = new TextDecoder().decode(fullData);
console.log("Text content:", textData);

class TransactionUploader {
  /** Transaction data being uploaded */
  data: Uint8Array;
  /** Last HTTP response status code */
  lastResponseStatus: number;
  /** Last error message if any */
  lastResponseError: string;
  /** Whether upload is complete */
  readonly isComplete: boolean;
  /** Total number of chunks */
  readonly totalChunks: number;
  /** Number of uploaded chunks */
  readonly uploadedChunks: number;
  /** Upload percentage complete (0-100) */
  readonly pctComplete: number;
}

/**
 * Upload the next chunk or a specific chunk
 * @param chunkIndex - Optional specific chunk index to upload
 */
uploadChunk(chunkIndex?: number): Promise<void>;

/**
 * Serialize uploader state for resuming later
 * @returns Serialized uploader state
 */
toJSON(): SerializedUploader;

/**
 * Restore uploader from serialized state
 * @param api - API instance
 * @param serialized - Serialized uploader state
 * @param data - Transaction data
 * @returns Promise resolving to restored uploader
 */
static fromSerialized(
  api: Api, 
  serialized: SerializedUploader, 
  data: Uint8Array
): Promise<TransactionUploader>;

/**
 * Create uploader from transaction ID
 * @param api - API instance
 * @param id - Transaction ID
 * @returns Promise resolving to serialized uploader
 */
static fromTransactionId(api: Api, id: string): Promise<SerializedUploader>;

// Resume an upload
const serializedState = localStorage.getItem("upload-state");
if (serializedState) {
  const parsed = JSON.parse(serializedState);
  const uploader = await TransactionUploader.fromSerialized(
    arweave.api,
    parsed,
    originalData
  );
  
  // Continue upload
  while (!uploader.isComplete) {
    await uploader.uploadChunk();
    // Save state for resuming
    localStorage.setItem("upload-state", JSON.stringify(uploader.toJSON()));
  }
}

interface TransactionOffsetResponse {
  /** Transaction data size in bytes */
  size: string;
  /** Transaction offset in the weave */
  offset: string;
}

interface TransactionChunkResponse {
  /** Base64url encoded chunk data */
  chunk: string;
  /** Merkle path proof for the chunk */
  data_path: string;
  /** Transaction path proof */
  tx_path: string;
}

interface SerializedUploader {
  /** Current chunk index being processed */
  chunkIndex: number;
  /** Whether transaction has been posted to network */
  txPosted: boolean;
  /** Transaction data object */
  transaction: object;
  /** Timestamp of last request completion */
  lastRequestTimeEnd: number;
  /** Last HTTP response status */
  lastResponseStatus: number;
  /** Last error message */
  lastResponseError: string;
}

interface Api {
  /** API configuration */
  config: ApiConfig;
  /** HTTP GET method constant */
  METHOD_GET: string;
  /** HTTP POST method constant */
  METHOD_POST: string;
  /** Make HTTP GET request */
  get(endpoint: string, config?: object): Promise<any>;
  /** Make HTTP POST request */
  post(endpoint: string, body?: any, config?: object): Promise<any>;
}

/** Maximum chunk size in bytes (256 KB) */
const MAX_CHUNK_SIZE: number = 262144;

/** Minimum chunk size in bytes (32 KB) */
const MIN_CHUNK_SIZE: number = 32768;