Pinata Adapter Reference

The Pinata adapter provides drop-in compatibility with the Pinata SDK, allowing you to migrate with minimal code changes.

Overview

Pinner provides two Pinata adapters:

Adapter	SDK Version	Status
`pinataAdapter`	Pinata SDK 2.x	✅ Recommended
`pinataLegacyAdapter`	Pinata SDK 1.x	✅ For legacy code

Installation

SDK Installation

pnpm

pnpm add @lumeweb/pinner

npm

npm install @lumeweb/pinner

yarn

yarn add @lumeweb/pinner

Quick Setup

import { Pinner } from "@lumeweb/pinner";
import { pinataAdapter } from "@lumeweb/pinner";
 
const pinner = new Pinner({ jwt: process.env.PINNER_API_KEY });
const adapter = pinataAdapter(pinner, {
  pinataGateway: "example.mypinata.cloud"
});

For detailed migration steps, see the Migration Guide.

API Reference

Pinata SDK 2.x Adapter

The v2 adapter provides a complete interface matching Pinata SDK 2.x:

interface PinataAdapter {
  config: PinataConfig;
  updateConfig(newConfig: PinataConfig): void;
 
  upload: {
    public: PublicUpload;
    private: PrivateUpload;
  };
 
  files: {
    public: PublicFiles;
    private: PrivateFiles;
  };
 
  gateways: {
    public: PublicGateways;
    private: PrivateGateways;
  };
 
  groups: {
    public: PublicGroups;
    private: PrivateGroups;
  };
 
  analytics: Analytics;
}

Pinata SDK 1.x Legacy Adapter

The legacy adapter provides a complete interface matching Pinata SDK 1.x:

interface PinataLegacyAdapter {
  pinFileToIPFS(file: File, options?: UploadOptions): Promise<UploadResponse>;
  pinJSONToIPFS(data: any, options?: UploadOptions): Promise<UploadResponse>;
  pinByHash(cid: string, options?: UploadOptions): Promise<UploadResponse>;
  pinList(query?: FileListQuery): Promise<FileListResponse>;
  unpin(cid: string): Promise<{ message: string }>;
  hashMetadata(cid: string, metadata: Record<string, string>): Promise<{ message: string }>;
}

API Comparison Tables

Pinata SDK 2.x → Pinner Adapter

Pinata SDK 2.x	Pinner with Adapter	Notes
`pinata.upload.public.file(file)`	`adapter.upload.public.file(file)`	✅ Fully supported
`pinata.upload.public.fileArray(files)`	`adapter.upload.public.fileArray(files)`	✅ Fully supported
`pinata.upload.public.json(data)`	`adapter.upload.public.json(data)`	✅ Fully supported
`pinata.upload.public.base64(data)`	`adapter.upload.public.base64(data)`	✅ Fully supported
`pinata.upload.public.cid(cid)`	`adapter.upload.public.cid(cid)`	✅ Fully supported
`pinata.upload.public.url(url)`	`adapter.upload.public.url(url)`	⚠️ Not supported
`pinata.files.public.list()`	`adapter.files.public.list()`	✅ Fully supported
`pinata.files.public.get(id)`	`adapter.files.public.get(id)`	✅ Fully supported
`pinata.files.public.delete([cid])`	`adapter.files.public.delete([cid])`	✅ Fully supported
`pinata.files.public.deletePinRequest(id)`	`adapter.files.public.deletePinRequest(id)`	✅ Pinner-only method

Pinner Extensions

The following methods extend the standard Pinata SDK interface with Pinner-specific functionality:

Method	Description
`adapter.gateways.public.get(cid)`	Get gateway URL for CID (Pinner extension)

Pinata SDK 1.x → Pinner Legacy Adapter

Pinata SDK 1.x	Pinner with Legacy Adapter
`pinFileToIPFS(file)`	`adapter.pinFileToIPFS(file)`
`pinJSONToIPFS(data)`	`adapter.pinJSONToIPFS(data)`
`pinByHash(cid)`	`adapter.pinByHash(cid)`
`unpin(cid)`	`adapter.unpin(cid)`
`pinList()`	`adapter.pinList()`
`hashMetadata(cid, metadata)`	`adapter.hashMetadata(cid, metadata)`

Configuration

PinataConfig

interface PinataConfig {
  pinataJwt?: string;
  pinataGateway?: string;
  pinataGatewayKey?: string;
  customHeaders?: Record<string, string>;
  endpointUrl?: string;
  uploadUrl?: string;
  legacyUploadUrl?: string;
}

Builder Patterns

Upload Builder

The v2 adapter uses a builder pattern for uploads with chaining:

const upload = await adapter.upload.public.file(file)
  .name("my-file.txt")
  .keyvalues({ project: "demo", version: "1.0" })
  .execute();
 
console.log("CID:", upload.cid);
console.log("Size:", upload.size);

Filter Builder

Use the filter builder to list files with specific criteria:

const files = await adapter.files.public.list()
  .name("my-file")
  .limit(10)
  .order("DESC")
  .all();
 
for (const file of files) {
  console.log(file.name, file.cid);
}

See Code Examples for more detailed usage patterns.

Unsupported Features

The following Pinata SDK features are not currently supported by the adapter:

Feature	Status	Alternative
Private uploads	❌ Not supported	Use Pinner's native API
Groups	❌ Not supported	Use keyvalues metadata instead
Analytics	❌ Not supported	Not available in Pinner
Swap CID	❌ Not supported	Not available in Pinner
Signed URLs	❌ Not supported	Not available in Pinner

For features not supported by the adapter, consider using Pinner's native API which provides more control and capabilities.