SDK: Types

This page is auto-generated from TypeDoc. Do not edit directly. To update, modify the TypeScript source in @lumeweb/pinner and run pnpm generate:sdk.

Interfaces

`PinataLegacyAdapter`

Pinata 1.x Legacy Adapter Interface

Matches Pinata SDK 1.x API exactly

Property	Type	Description
`pinFileToIPFS`	`void`	Upload a file to IPFS
`pinJSONToIPFS`	`void`	Upload JSON data to IPFS
`pinByHash`	`void`	Pin content by CID
`pinList`	`void`	List pinned files
`unpin`	`void`	Unpin content by CID
`hashMetadata`	`void`	Update pin metadata
`createSignedURL`	`void`	Create signed URL for private IPFS files
`pinJobs`	`void`	Get pin jobs
`topUsageAnalytics`	`void`	Get top usage analytics
`dateIntervalAnalytics`	`void`	Get date interval analytics
`swapCid`	`void`	Swap CID
`swapHistory`	`void`	Get swap history

`PinataUploadBuilder`

Upload builder interface

Property	Type	Description
`name`	`void`
`keyvalues`	`void`
`execute`	`void`

`PinataFilterFiles`

Filter files builder interface

Property	Type	Description
`name`	`void`
`group`	`void`
`cid`	`void`
`mimeType`	`void`
`order`	`void`
`limit`	`void`
`cidPending`	`void`
`keyvalues`	`void`
`noGroup`	`void`
`pageToken`	`void`
`then`	`void`
`all`	`void`
`[asyncIterator]`	`void`

`PinataFilterQueue`

Filter queue builder interface

Property	Type	Description
`cid`	`void`
`status`	`void`
`pageLimit`	`void`
`pageToken`	`void`
`sort`	`void`
`then`	`void`
`all`	`void`
`[asyncIterator]`	`void`

`PinataFilterGroups`

Filter groups builder interface

Property	Type	Description
`name`	`void`
`limit`	`void`
`pageToken`	`void`
`isPublic`	`void`
`then`	`void`
`all`	`void`
`[asyncIterator]`	`void`

`PinataPublicUpload`

Public upload interface

Property	Type	Description
`file`	`void`
`fileArray`	`void`
`base64`	`void`
`url`	`void`
`json`	`void`
`cid`	`void`
`createSignedURL`	`void`

`PinataPrivateUpload`

Private upload interface

Property	Type	Description
`file`	`void`
`fileArray`	`void`
`base64`	`void`
`url`	`void`
`json`	`void`
`cid`	`void`
`createSignedURL`	`void`

`PinataPublicFiles`

Public files interface

Property	Type	Description
`list`	`void`
`get`	`void`
`delete`	`void`
`update`	`void`
`addSwap`	`void`
`getSwapHistory`	`void`
`deleteSwap`	`void`
`queue`	`void`
`deletePinRequest`	`void`

`PinataPrivateFiles`

Private files interface

Property	Type	Description
`list`	`void`
`get`	`void`
`delete`	`void`
`update`	`void`
`addSwap`	`void`
`getSwapHistory`	`void`
`deleteSwap`	`void`
`queue`	`void`
`deletePinRequest`	`void`

`PinataPublicGateways`

Public gateways interface

Property	Type	Description
`get`	`void`
`convert`	`void`

`PinataPrivateGateways`

Private gateways interface

Property	Type	Description
`get`	`void`
`createAccessLink`	`void`

`PinataPublicGroups`

Public groups interface

Property	Type	Description
`create`	`void`
`list`	`void`
`get`	`void`
`addFiles`	`void`
`removeFiles`	`void`
`update`	`void`
`delete`	`void`

`PinataPrivateGroups`

Private groups interface

Property	Type	Description
`create`	`void`
`list`	`void`
`get`	`void`
`addFiles`	`void`
`removeFiles`	`void`
`update`	`void`
`delete`	`void`

`PinataAnalytics`

Analytics interface

Property	Type	Description
`requests`	`void`
`bandwidth`	`void`

`PinataAdapter`

Pinata 2.x Adapter Interface

Matches Pinata SDK 2.x API exactly

Property	Type	Description
`config`	`PinataV2Config`	Configuration
`updateConfig`	`void`	Update the adapter configuration
`upload`	`object`	Upload with public/private separation
`files`	`object`	Files with public/private separation
`gateways`	`object`	Gateways with public/private separation
`groups`	`object`	Groups with public/private separation
`analytics`	`PinataAnalytics`	Analytics (no public/private)

`IpnsClientOptions`

Property	Type	Description
`signal`	`AbortSignal`	optional

`WebsitesClientOptions`

Property	Type	Description
`signal`	`AbortSignal`	optional

`WatchOptions`

Property	Type	Description
`interval`	`number`	optional
`timeout`	`number`	optional

`SSLCallbacks`

Property	Type	Description
`onReady`	`object`	optional
`onError`	`object`	optional
`onStatus`	`object`	optional

`SSLWatcher`

Property	Type	Description
`start`	`void`
`stop`	`void`

`SSLError`

Property	Type	Description
`type`	`timeout` \| `error`
`details`	`string`	optional

`UnstorageBlockstoreOptions`

Property	Type	Description
`storage`	`Storage<StorageValue>`	Unstorage instance to use (bypasses driver creation) optional
`prefix`	`string`	Key prefix for blockstore keys optional
`driver`	`Driver<any, any>`	Unstorage driver name or instance optional
`base`	`string`	Base path for storage driver optional
`datastorePrefix`	`string`	Prefix for datastore keys (defaults to prefix) optional

`PinnerConfig`

Property	Type	Description
`jwt`	`string`	JWT authentication token. Required for all API operations.
`endpoint`	`string`	API endpoint URL. Defaults to the official pinning service. optional
`gateway`	`string`	IPFS gateway URL for content retrieval. optional
`allowedFileTypes`	`string[]`	Allowed MIME types for upload. If undefined, all types allowed. optional
`fetch`	`object`	Custom fetch implementation. optional
`datastore`	`Datastore<object, object, object, object, object, object, object, object, object, object>`	Custom datastore instance for Helia.
If provided, this datastore will be used directly without creating one from storage.
Highest priority - takes precedence over storage and datastoreName. optional
`storage`	`Storage<StorageValue>`	Custom storage instance for both Helia blockstore and datastore.
If provided, this storage will be used instead of creating default storage.
The storage instance must implement the unstorage Storage interface.
Used when datastore is not provided. optional
`datastoreName`	`string`	Custom base name for Helia storage.
Passed as the base option to both blockstore and datastore storage instances.
Only used when neither datastore nor storage are provided. optional
`timeout`	`number`	Upload request timeout in milliseconds.
Applied to XHR uploads. TUS does not expose a timeout option. optional
`retries`	`number`	Number of retry attempts for failed uploads.
Applied to XHR uploads (TUS uses retryDelays instead). optional

`AbortOptions`

Options that can be passed to abort async operations

Property	Type	Description
`signal`	`AbortSignal`	AbortSignal to cancel the operation optional

`RemoteAddOptions`

Allows passing extra options accepted by the remote pinning service

Property	Type	Description
`signal`	`AbortSignal`	AbortSignal to cancel the operation optional
`name`	`string`	Name for the pin or filter optional
`metadata`	`Record<string, string>`	Key-value metadata to attach to the pin optional
`origins`	`string[]`	Origin addresses for the pinned content optional

`RemoteLsOptions`

Allows passing extra options accepted by the remote pinning service

Property	Type	Description
`signal`	`AbortSignal`	AbortSignal to cancel the operation optional
`name`	`string`	Name for the pin or filter optional
`status`	`Status[]`	Current status (queued, pinning, pinned, failed) optional
`limit`	`number`	Maximum number of results per page optional
`cursor`	`string`	Pagination cursor for listing results optional

`RemotePin`

Includes extra metadata supported by the remote pinning service

Property	Type	Description
`cid`	`CID`	IPFS Content Identifier
`name`	`string`	Name for the pin or filter optional
`status`	`Status`	Current status (queued, pinning, pinned, failed)
`created`	`Date`	ISO timestamp of creation
`size`	`number`	Size in bytes optional
`metadata`	`Record<string, string>`	Key-value metadata to attach to the pin optional

`RemotePins`

Extends the Pins interface with remote pinning-specific arguments and return

types (e.g. metadata as Record<string, string> and pins with an added

.status property)

Property	Type	Description
`add`	`void`	Pin a block in the blockstore. It will not be deleted
when garbage collection is run.
`ls`	`void`	List all blocks that have been pinned.
`isPinned`	`void`	Return true if the passed CID is pinned
`get`	`void`	Return pin details
`setMetadata`	`void`	Update pin metadata
`rm`	`void`	Remove a pin. The block may be deleted when garbage collection is run.
`rmByRequestId`	`void`	Remove a pin by request ID. The block may be deleted when garbage collection is run.

`UploadResult`

Property	Type	Description
`id`	`string`	Unique identifier for this upload operation.
`cid`	`string`	IPFS Content Identifier for the uploaded content.
Undefined when the CID is not yet available (e.g. TUS uploads where
the CID is assigned asynchronously — poll GET /api/upload/result/{id}). optional
`name`	`string`	User-provided or auto-generated name for the content.
`size`	`number`	Total size in bytes.
`mimeType`	`string`	MIME type of the content.
`createdAt`	`Date`	ISO timestamp when content was created.
`numberOfFiles`	`number`	Number of files (1 for single file, N for directory).
`keyvalues`	`Record<string, string>`	Custom key-value metadata. optional
`isDirectory`	`boolean`	Whether this upload is a directory. optional
`isCarFile`	`boolean`	Whether this upload is already a valid CAR file.
If true, the upload system will skip CAR preprocessing and upload the file as-is.
Useful for passthrough of pre-generated CAR files. optional
`operationId`	`number`	Portal operation ID for tracking the pinning operation.
Can be used with waitForOperation() to wait for the operation to complete. optional
`[UploadResultSymbol]`	`true`	Symbol brand for type checking - used to identify UploadResult objects optional

`UploadOptions`

Property	Type	Description
`name`	`string`	Name for the uploaded content. optional
`keyvalues`	`Record<string, string>`	Custom key-value metadata. optional
`onProgress`	`object`	Progress callback invoked during upload. optional
`onComplete`	`object`	Callback invoked when upload completes successfully. optional
`onError`	`object`	Callback invoked when upload fails. optional
`signal`	`AbortSignal`	AbortSignal for cancellation. optional
`size`	`number`	Optional size override for the upload input.
Useful for ReadableStream inputs where size detection is difficult. optional
`isDirectory`	`boolean`	Whether this upload is a directory. optional
`isCarFile`	`boolean`	Whether this upload is already a valid CAR file.
If true, the upload system will skip CAR preprocessing and upload the file as-is.
Useful for passthrough of pre-generated CAR files. optional
`waitForOperation`	`boolean`	Whether to wait for the pinning operation to complete/fail.
When true, the upload will block until the operation reaches a settled state
(completed, failed, or error). Default is false (upload only). optional
`operationPollingOptions`	`any`	Polling options for waiting on operation completion.
Only used when waitForOperation is true. optional

`UploadProgress`

Property	Type	Description
`percentage`	`number`	Percentage complete (0-100).
`bytesUploaded`	`number`	Number of bytes uploaded.
`bytesTotal`	`number`	Total bytes to upload.
`speed`	`number`	Upload speed in bytes per second. optional
`eta`	`number`	Estimated time remaining in seconds. optional

`UploadOperation`

Property	Type	Description
`cancel`	`void`	Cancel the ongoing upload.
`pause`	`void`	Pause the upload (TUS only).
`resume`	`void`	Resume a paused upload (TUS only).
`result`	`Promise<UploadResult>`	Promise that resolves when upload completes.
`progress`	`Readonly<UploadProgress>`	Current progress.

`PinnerUploadBuilder`

Builder interface for Pinner upload API.

Supports chaining name/keyvalues and returns UploadOperation with controls.

Property	Type	Description
`name`	`void`	Set the name for the upload.
`keyvalues`	`void`	Set custom key-value metadata.
`waitForOperation`	`void`	Whether to wait for the pinning operation to complete/fail.
When true, the upload will block until the operation reaches a settled state.
`operationPollingOptions`	`void`	Set polling options for waiting on operation completion.
Only used when waitForOperation is true.
`pin`	`void`	Start the upload and return UploadOperation with controls.

`UploadBuilderNamespace`

Pinner upload builder namespace.

Provides fluent API for file, JSON, Base64, and URL uploads.

Property	Type	Description
`file`	`void`	Upload a file.
Returns a builder for chaining name/keyvalues.
`json`	`void`	Upload JSON data (encoded as JSON file).
Returns a builder for chaining name/keyvalues.
`base64`	`void`	Upload Base64 encoded content (decoded and uploaded as file).
Returns a builder for chaining name/keyvalues.
`url`	`void`	Upload content from a URL (fetched and uploaded as file).
Returns a builder for chaining name/keyvalues.
`csv`	`void`	Upload CSV data (string, array of objects, or array of arrays).
Returns a builder for chaining name/keyvalues.
`raw`	`void`	Upload raw CAR data without preprocessing.
Useful for passthrough of pre-generated CAR files.
Returns a builder for chaining name/keyvalues.
`text`	`void`	Upload text content (encoded as text file).
Returns a builder for chaining name/keyvalues.
`content`	`void`

`CarPreprocessOptions`

Property	Type	Description
`name`	`string`	Name for the pin or filter optional
`onProgress`	`object`	Progress callback for preprocessing optional
`signal`	`AbortSignal`	AbortSignal to cancel the operation optional

`CarPreprocessResult`

Property	Type	Description
`carStream`	`ReadableStream<Uint8Array<ArrayBufferLike>>`	Preprocessed CAR data as a readable stream
`rootCid`	`string`	Root CID of the CAR file
`size`	`bigint`	Size in bytes

Interfaces

PinataLegacyAdapter

PinataUploadBuilder

PinataFilterFiles

PinataFilterQueue

PinataFilterGroups

PinataPublicUpload

PinataPrivateUpload

PinataPublicFiles

PinataPrivateFiles

PinataPublicGateways

PinataPrivateGateways

PinataPublicGroups

PinataPrivateGroups

PinataAnalytics

PinataAdapter

IpnsClientOptions

WebsitesClientOptions

WatchOptions

SSLCallbacks

SSLWatcher

SSLError

UnstorageBlockstoreOptions

PinnerConfig

AbortOptions

RemoteAddOptions

RemoteLsOptions

RemotePin

RemotePins

UploadResult

UploadOptions

UploadProgress

UploadOperation

PinnerUploadBuilder

UploadBuilderNamespace

CarPreprocessOptions

CarPreprocessResult

Type Aliases

FileManagerItemResponse

BlockMetaResponse

InfoResponse

PinStatusResponse

PinStatusResponseInfo

PinRequest

PinRequestMeta

PinResultsResponse

ErrorResponse

Multiaddr

PostUploadResponse

UploadResultResponse

Component

GatewayWebsiteResponse

GatewayWebsiteStatusResponse

GetBlockMetaBatchRequest

IPNSKeyRequest

IPNSKeyListResponseResponse

IPNSKeyListResponse

IPNSRepublishResponse

IPNSKeyResponse

IPNSPublishRequest

IPNSPublishResponse

IPNSResolveResponse

PostApiUploadBody

SSLStatusUpdateRequest

WebsiteItemResponse

WebsiteRequest

WebsiteResponse

WebsiteItem

WebsiteUpdateRequest

WebsiteConfigResponse

SSLStatusInfo

WebsiteValidateResponse

`PinataLegacyAdapter`

`PinataUploadBuilder`

`PinataFilterFiles`

`PinataFilterQueue`

`PinataFilterGroups`

`PinataPublicUpload`

`PinataPrivateUpload`

`PinataPublicFiles`

`PinataPrivateFiles`

`PinataPublicGateways`

`PinataPrivateGateways`

`PinataPublicGroups`

`PinataPrivateGroups`

`PinataAnalytics`

`PinataAdapter`

`IpnsClientOptions`

`WebsitesClientOptions`

`WatchOptions`

`SSLCallbacks`

`SSLWatcher`

`SSLError`

`UnstorageBlockstoreOptions`

`PinnerConfig`

`AbortOptions`

`RemoteAddOptions`

`RemoteLsOptions`

`RemotePin`

`RemotePins`

`UploadResult`

`UploadOptions`

`UploadProgress`

`UploadOperation`

`PinnerUploadBuilder`

`UploadBuilderNamespace`

`CarPreprocessOptions`

`CarPreprocessResult`

`FileManagerItemResponse`

`BlockMetaResponse`

`InfoResponse`

`PinStatusResponse`

`PinStatusResponseInfo`

`PinRequest`

`PinRequestMeta`

`PinResultsResponse`

`ErrorResponse`

`Multiaddr`

`PostUploadResponse`

`UploadResultResponse`

`Component`

`GatewayWebsiteResponse`

`GatewayWebsiteStatusResponse`

`GetBlockMetaBatchRequest`

`IPNSKeyRequest`

`IPNSKeyListResponseResponse`

`IPNSKeyListResponse`

`IPNSRepublishResponse`

`IPNSKeyResponse`

`IPNSPublishRequest`

`IPNSPublishResponse`

`IPNSResolveResponse`

`PostApiUploadBody`

`SSLStatusUpdateRequest`

`WebsiteItemResponse`

`WebsiteRequest`

`WebsiteResponse`

`WebsiteItem`

`WebsiteUpdateRequest`

`WebsiteConfigResponse`

`SSLStatusInfo`

`WebsiteValidateResponse`