filecoin-pin/dist/core/upload/index.d.ts

Bridge IPFS content to Filecoin Onchain Cloud using familiar tools

import type { Synapse } from '@filoz/synapse-sdk';
import type { CID } from 'multiformats/cid';
import type { Logger } from 'pino';
import { checkFILBalance, checkUSDFCBalance, type PaymentCapacityCheck } from '../payments/index.js';
import { type SynapseService } from '../synapse/index.js';
import type { ProgressEvent, ProgressEventHandler } from '../utils/types.js';
import { type ValidateIPNIProgressEvents, type WaitForIpniProviderResultsOptions } from '../utils/validate-ipni-advertisement.js';
import { type SynapseUploadResult, type UploadProgressEvents } from './synapse.js';
export type { SynapseUploadOptions, SynapseUploadResult, UploadProgressEvents } from './synapse.js';
export { getDownloadURL, getServiceURL, uploadToSynapse } from './synapse.js';
/**
 * Options for evaluating whether an upload can proceed.
 */
export type UploadReadinessProgressEvents = ProgressEvent<'checking-balances'> | ProgressEvent<'checking-allowances'> | ProgressEvent<'configuring-allowances'> | ProgressEvent<'allowances-configured', {
    transactionHash?: string;
}> | ProgressEvent<'validating-capacity'>;
export interface UploadReadinessOptions {
    /** Initialized Synapse instance. */
    synapse: Synapse;
    /** Size of the CAR file (bytes). */
    fileSize: number;
    /**
     * Automatically configure allowances when they are missing.
     * Defaults to `true` to match current CLI/action behaviour.
     */
    autoConfigureAllowances?: boolean;
    /** Optional callback for progress updates. */
    onProgress?: ProgressEventHandler<UploadReadinessProgressEvents>;
}
/**
 * Result of the payment readiness check prior to upload.
 */
export interface UploadReadinessResult {
    /** Overall status of the readiness check. */
    status: 'ready' | 'blocked';
    /** Gas + USDFC validation outcome. */
    validation: {
        isValid: boolean;
        errorMessage?: string;
        helpMessage?: string;
    };
    /** FIL/gas balance status. */
    filStatus: Awaited<ReturnType<typeof checkFILBalance>>;
    /** Wallet USDFC balance. */
    walletUsdfcBalance: Awaited<ReturnType<typeof checkUSDFCBalance>>;
    /** Allowance update information. */
    allowances: {
        needsUpdate: boolean;
        updated: boolean;
        transactionHash?: string | undefined;
    };
    /** Capacity check from Synapse (present even when blocked). */
    capacity?: PaymentCapacityCheck;
    /** Suggestions returned by the capacity check. */
    suggestions: string[];
}
/**
 * Check readiness for uploading a CAR file.
 *
 * This performs the same validation chain previously used by the CLI/action:
 * 1. Ensure basic wallet requirements (FIL for gas, USDFC balance)
 * 2. Confirm or configure WarmStorage allowances
 * 3. Validate that the current deposit can cover the upload
 *
 * The function only mutates state when `autoConfigureAllowances` is enabled
 * (default), in which case it will call {@link setMaxAllowances} as needed.
 *
 * **Session Key Authentication**: When using session key authentication,
 * `autoConfigureAllowances` is automatically disabled since payment operations
 * require the owner wallet to sign. Allowances must be configured separately
 * by the owner wallet before uploads can proceed.
 */
export declare function checkUploadReadiness(options: UploadReadinessOptions): Promise<UploadReadinessResult>;
export interface UploadExecutionOptions {
    /** Logger used for structured upload events. */
    logger: Logger;
    /** Optional identifier to help correlate logs. */
    contextId?: string;
    /** Optional umbrella onProgress receiving child progress events. */
    onProgress?: ProgressEventHandler<(UploadProgressEvents | ValidateIPNIProgressEvents) & {}>;
    /** Optional metadata to associate with the upload. */
    pieceMetadata?: Record<string, string>;
    /**
     * Optional IPNI validation behaviour. When enabled (default), the upload flow will wait for the IPFS Root CID to be announced to IPNI.
     */
    ipniValidation?: {
        /**
         * Enable the IPNI validation wait.
         *
         * @default: true
         */
        enabled?: boolean;
    } & Omit<WaitForIpniProviderResultsOptions, 'onProgress'>;
}
export interface UploadExecutionResult extends SynapseUploadResult {
    /** Active network derived from the Synapse instance. */
    network: string;
    /** Transaction hash from the piece-addition step (if available). */
    transactionHash?: string | undefined;
    /**
     * True if the IPFS Root CID was observed on filecoinpin.contact (IPNI).
     *
     * You should block any displaying, or attempting to access, of IPFS download URLs unless the IPNI validation is successful.
     */
    ipniValidated: boolean;
}
/**
 * Execute the upload to Synapse, returning the same structured data used by the
 * CLI and GitHub Action.
 */
export declare function executeUpload(synapseService: SynapseService, carData: Uint8Array, rootCid: CID, options: UploadExecutionOptions): Promise<UploadExecutionResult>;
//# sourceMappingURL=index.d.ts.map