filecoin-pin
Version:
Bridge IPFS content to Filecoin Onchain Cloud using familiar tools
268 lines • 9.15 kB
TypeScript
import { type ProviderInfo, type StorageContext, type StorageContextCallbacks, Synapse, type SynapseOptions, type TelemetryConfig } from '@filoz/synapse-sdk';
import { type Signer } from 'ethers';
import type { Logger } from 'pino';
export * from './constants.js';
/**
* Complete application configuration interface
* This is the main config interface that can be imported by CLI and other consumers
*/
export interface Config {
port: number;
host: string;
privateKey: string | undefined;
rpcUrl: string;
databasePath: string;
carStoragePath: string;
logLevel: string;
warmStorageAddress: string | undefined;
}
/**
* Common options for all Synapse configurations
*/
interface BaseSynapseConfig extends Omit<SynapseOptions, 'withCDN' | 'warmStorageAddress' | 'telemetry'> {
/** RPC endpoint for the target Filecoin network. Defaults to calibration. */
rpcUrl?: string | undefined;
/** Optional override for WarmStorage contract address */
warmStorageAddress?: string | undefined;
withCDN?: boolean | undefined;
/** Default metadata to apply when creating or reusing datasets */
dataSetMetadata?: Record<string, string>;
/**
* Telemetry configuration.
* Defaults to enabled unless explicitly disabled.
* @example
* {
* sentryInitOptions: {
* enabled: false, // if want to disable telemetry.
* },
* sentrySetTags: {
* appName: "${your-app-name}",
* },
* }
*/
telemetry?: TelemetryConfig;
}
/**
* Standard authentication with private key
*/
export interface PrivateKeyConfig extends BaseSynapseConfig {
privateKey: string;
}
/**
* Session key authentication with wallet address and session key
*/
export interface SessionKeyConfig extends BaseSynapseConfig {
walletAddress: string;
sessionKey: string;
}
/**
* Signer-based authentication with ethers Signer
*/
export interface SignerConfig extends BaseSynapseConfig {
signer: Signer;
/** Target Filecoin network (required for signer mode to determine default RPC) */
network: 'mainnet' | 'calibration';
}
/**
* Configuration for Synapse initialization
*
* Supports three authentication modes:
* 1. Standard: privateKey only
* 2. Session Key: walletAddress + sessionKey
* 3. Signer: ethers Signer instance
*/
export type SynapseSetupConfig = PrivateKeyConfig | SessionKeyConfig | SignerConfig;
/**
* Structured service object containing the fully initialized Synapse SDK and
* its storage context
*/
export interface SynapseService {
synapse: Synapse;
storage: StorageContext;
providerInfo: ProviderInfo;
}
/**
* Dataset selection options for multi-tenant scenarios.
*
* This is a curated subset of Synapse SDK options focused on the common
* use cases for filecoin-pin.
*/
export interface DatasetOptions {
/**
* Create a new dataset even if one exists for this wallet.
*
* Set to `true` when you want each user to have their own dataset
* despite sharing the same wallet (e.g., multi-tenant websites and org/enterprise services using the same wallet).
*
* @default false
*/
createNew?: boolean;
/**
* Connect to a specific dataset by ID.
*
* Use this to reconnect to a user's existing dataset after retrieving
* the ID from localStorage or a database.
*
* Takes precedence over `createNew` if both are provided.
*/
useExisting?: number;
/**
* Custom metadata to attach to the dataset.
*
* Note: If `useExisting` is provided, metadata is ignored since you're
* connecting to an existing dataset.
*/
metadata?: Record<string, string>;
}
/**
* Options for creating a storage context.
*/
export interface CreateStorageContextOptions {
/**
* Dataset selection options.
*/
dataset?: DatasetOptions;
/**
* Progress callbacks for tracking creation.
*/
callbacks?: StorageContextCallbacks;
/**
* Override provider selection by address.
* Takes precedence over providerId if both are specified.
*/
providerAddress?: string;
/**
* Override provider selection by ID.
*/
providerId?: number;
/**
* Optional logger instance for detailed operation tracking and progress callbacks.
* If not provided, logging will be skipped.
*/
logger?: Partial<Logger> | undefined;
}
/**
* Reset the service instances (for testing)
*/
export declare function resetSynapseService(): void;
/**
* Check if Synapse is using session key authentication
*
* Session key authentication uses an AddressOnlySigner which cannot sign transactions.
* Payment operations (deposits, allowances) must be done by the owner wallet separately.
*
* Uses a Symbol to reliably detect AddressOnlySigner even across module boundaries.
*
* @param synapse - Initialized Synapse instance
* @returns true if using session key authentication, false otherwise
*/
export declare function isSessionKeyMode(synapse: Synapse): boolean;
/**
* Initialize the Synapse SDK without creating storage context
*
* Supports three authentication modes:
* - Standard: privateKey only
* - Session Key: walletAddress + sessionKey
* - Signer: ethers Signer instance
*
* @param config - Application configuration with authentication credentials
* @param logger - Logger instance for detailed operation tracking
* @returns Initialized Synapse instance
*/
export declare function initializeSynapse(config: Partial<SynapseSetupConfig>, logger: Logger): Promise<Synapse>;
/**
* Create storage context for an initialized Synapse instance
*
* This creates a storage context with comprehensive callbacks for tracking
* the data set creation and provider selection process. This is primarily
* a wrapper around the Synapse SDK's storage context creation, adding logging
* and progress callbacks for better observability.
*
* @param synapse - Initialized Synapse instance
* @param logger - Logger instance for detailed operation tracking
* @param options - Optional configuration for dataset selection and callbacks
* @returns Storage context and provider information
*
* @example
* ```typescript
* // Create a new dataset (multi-user scenario)
* const { storage } = await createStorageContext(synapse, {
* logger,
* dataset: { createNew: true }
* })
*
* // Connect to existing dataset
* const { storage } = await createStorageContext(synapse, {
* logger,
* dataset: { useExisting: 123 }
* })
*
* // Default behavior (reuse wallet's dataset)
* const { storage } = await createStorageContext(synapse, { logger })
* ```
*/
export declare function createStorageContext(synapse: Synapse, options?: CreateStorageContextOptions): Promise<{
storage: StorageContext;
providerInfo: ProviderInfo;
}>;
/**
* Set up complete Synapse service with SDK and storage context
*
* This function demonstrates the complete setup flow for Synapse:
* 1. Validates required configuration (private key)
* 2. Creates Synapse instance with network configuration
* 3. Creates a storage context with comprehensive callbacks
* 4. Returns a service object for application use
*
* Our wrapping of Synapse initialization and storage context creation is
* primarily to handle our custom configuration needs and add detailed logging
* and progress tracking.
*
* @param config - Application configuration with privateKey and RPC URL
* @param logger - Logger instance for detailed operation tracking
* @param options - Optional dataset selection and callbacks
* @returns SynapseService with initialized Synapse and storage context
*
* @example
* ```typescript
* // Standard setup (reuses wallet's dataset)
* const service = await setupSynapse(config, logger)
*
* // Create new dataset for multi-user scenario
* const service = await setupSynapse(config, logger, {
* dataset: { createNew: true }
* })
*
* // Connect to specific dataset
* const service = await setupSynapse(config, logger, {
* dataset: { useExisting: 123 }
* })
* ```
*/
export declare function setupSynapse(config: SynapseSetupConfig, logger: Logger, options?: CreateStorageContextOptions): Promise<SynapseService>;
/**
* Get default storage context configuration for consistent data set creation
*
* @param overrides - Optional overrides to merge with defaults
* @returns Storage context configuration with defaults
*/
export declare function getDefaultStorageContextConfig(overrides?: any): any;
/**
* Clean up a WebSocket provider connection
* This is important for allowing the Node.js process to exit cleanly
*
* @param provider - The provider to clean up
*/
export declare function cleanupProvider(provider: any): Promise<void>;
/**
* Clean up WebSocket providers and other resources
*
* Call this when CLI commands are finishing to ensure proper cleanup
* and allow the process to terminate
*/
export declare function cleanupSynapseService(): Promise<void>;
/**
* Get the initialized Synapse service
*/
export declare function getSynapseService(): SynapseService | null;
//# sourceMappingURL=index.d.ts.map