@helia/interface 0.0.0-97da23e → 0.0.0-a3a7c9c

package/dist/src/blocks.d.ts

@@ -0,0 +1,19 @@
+import type { ProgressEvent, ProgressOptions } from 'progress-events';
+import type { CID } from 'multiformats/cid';
+import type { BitswapNotifyProgressEvents, BitswapWantProgressEvents } from 'ipfs-bitswap';
+import type { Blockstore } from 'interface-blockstore';
+export interface Pair {
+    cid: CID;
+    block: Uint8Array;
+}
+export type HasBlockProgressEvents = ProgressEvent<'blocks:put:duplicate', CID> | ProgressEvent<'blocks:put:bitswap:notify', CID> | ProgressEvent<'blocks:put:blockstore:put', CID> | BitswapNotifyProgressEvents;
+export type PutBlockProgressEvents = ProgressEvent<'blocks:put:duplicate', CID> | ProgressEvent<'blocks:put:bitswap:notify', CID> | ProgressEvent<'blocks:put:blockstore:put', CID> | BitswapNotifyProgressEvents;
+export type PutManyBlocksProgressEvents = ProgressEvent<'blocks:put-many:duplicate', CID> | ProgressEvent<'blocks:put-many:bitswap:notify', CID> | ProgressEvent<'blocks:put-many:blockstore:put-many'> | BitswapNotifyProgressEvents;
+export type GetBlockProgressEvents = ProgressEvent<'blocks:get:bitswap:want', CID> | ProgressEvent<'blocks:get:blockstore:get', CID> | ProgressEvent<'blocks:get:blockstore:put', CID> | BitswapWantProgressEvents;
+export type GetManyBlocksProgressEvents = ProgressEvent<'blocks:get-many:blockstore:get-many'> | ProgressEvent<'blocks:get-many:bitswap:want', CID> | ProgressEvent<'blocks:get-many:blockstore:put', CID> | BitswapWantProgressEvents;
+export type GetAllBlocksProgressEvents = ProgressEvent<'blocks:get-all:blockstore:get-many'>;
+export type DeleteBlockProgressEvents = ProgressEvent<'blocks:delete:blockstore:delete', CID>;
+export type DeleteManyBlocksProgressEvents = ProgressEvent<'blocks:delete-many:blockstore:delete-many'>;
+export interface Blocks extends Blockstore<ProgressOptions<HasBlockProgressEvents>, ProgressOptions<PutBlockProgressEvents>, ProgressOptions<PutManyBlocksProgressEvents>, ProgressOptions<GetBlockProgressEvents>, ProgressOptions<GetManyBlocksProgressEvents>, ProgressOptions<GetAllBlocksProgressEvents>, ProgressOptions<DeleteBlockProgressEvents>, ProgressOptions<DeleteManyBlocksProgressEvents>> {
+}
+//# sourceMappingURL=blocks.d.ts.map

package/dist/src/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/blocks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAA;AAC1F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,MAAM,WAAW,IAAI;IACnB,GAAG,EAAE,GAAG,CAAA;IACR,KAAK,EAAE,UAAU,CAAA;CAClB;AAED,MAAM,MAAM,sBAAsB,GAChC,aAAa,CAAC,sBAAsB,EAAE,GAAG,CAAC,GAC1C,aAAa,CAAC,2BAA2B,EAAE,GAAG,CAAC,GAC/C,aAAa,CAAC,2BAA2B,EAAE,GAAG,CAAC,GAC/C,2BAA2B,CAAA;AAE7B,MAAM,MAAM,sBAAsB,GAChC,aAAa,CAAC,sBAAsB,EAAE,GAAG,CAAC,GAC1C,aAAa,CAAC,2BAA2B,EAAE,GAAG,CAAC,GAC/C,aAAa,CAAC,2BAA2B,EAAE,GAAG,CAAC,GAC/C,2BAA2B,CAAA;AAE7B,MAAM,MAAM,2BAA2B,GACrC,aAAa,CAAC,2BAA2B,EAAE,GAAG,CAAC,GAC/C,aAAa,CAAC,gCAAgC,EAAE,GAAG,CAAC,GACpD,aAAa,CAAC,qCAAqC,CAAC,GACpD,2BAA2B,CAAA;AAE7B,MAAM,MAAM,sBAAsB,GAChC,aAAa,CAAC,yBAAyB,EAAE,GAAG,CAAC,GAC7C,aAAa,CAAC,2BAA2B,EAAE,GAAG,CAAC,GAC/C,aAAa,CAAC,2BAA2B,EAAE,GAAG,CAAC,GAC/C,yBAAyB,CAAA;AAE3B,MAAM,MAAM,2BAA2B,GACrC,aAAa,CAAC,qCAAqC,CAAC,GACpD,aAAa,CAAC,8BAA8B,EAAE,GAAG,CAAC,GAClD,aAAa,CAAC,gCAAgC,EAAE,GAAG,CAAC,GACpD,yBAAyB,CAAA;AAE3B,MAAM,MAAM,0BAA0B,GACpC,aAAa,CAAC,oCAAoC,CAAC,CAAA;AAErD,MAAM,MAAM,yBAAyB,GACnC,aAAa,CAAC,iCAAiC,EAAE,GAAG,CAAC,CAAA;AAEvD,MAAM,MAAM,8BAA8B,GACxC,aAAa,CAAC,2CAA2C,CAAC,CAAA;AAE5D,MAAM,WAAW,MAAO,SAAQ,UAAU,CAAC,eAAe,CAAC,sBAAsB,CAAC,EAClF,eAAe,CAAC,sBAAsB,CAAC,EAAE,eAAe,CAAC,2BAA2B,CAAC,EACrF,eAAe,CAAC,sBAAsB,CAAC,EAAE,eAAe,CAAC,2BAA2B,CAAC,EAAE,eAAe,CAAC,0BAA0B,CAAC,EAClI,eAAe,CAAC,yBAAyB,CAAC,EAAE,eAAe,CAAC,8BAA8B,CAAC,CAC1F;CAEA"}

package/dist/src/blocks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=blocks.js.map

package/dist/src/blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.js","sourceRoot":"","sources":["../../src/blocks.ts"],"names":[],"mappings":""}

package/dist/src/index.d.ts

@@ -14,11 +14,14 @@
  * ```
  */
 import type { Libp2p } from '@libp2p/interface-libp2p';
-import type { Blockstore } from 'interface-blockstore';
 import type { AbortOptions } from '@libp2p/interfaces';
 import type { PeerId } from '@libp2p/interface-peer-id';
-import type { Multiaddr } from '@multiformats/multiaddr';
 import type { Datastore } from 'interface-datastore';
+import type { Pins } from './pins.js';
+import type { ProgressEvent, ProgressOptions } from 'progress-events';
+import type { CID } from 'multiformats/cid';
+import type { Blocks } from './blocks.js';
+export type { Await, AwaitIterable } from 'interface-store';
 /**
  * The API presented by a Helia node.
  */
@@ -30,26 +33,15 @@ export interface Helia {
     /**
      * Where the blocks are stored
      */
-    blockstore: Blockstore;
+    blockstore: Blocks;
     /**
      * A key/value store
      */
     datastore: Datastore;
     /**
-     * Returns information about this node
-     *
-     * @example
-     *
-     * ```typescript
-     * import { createHelia } from 'helia'
-     *
-     * const node = await createHelia()
-     * const id = await node.info()
-     * console.info(id)
-     * // { peerId: PeerId(12D3Foo), ... }
-     * ```
+     * Pinning operations for blocks in the blockstore
      */
-    info: (options?: InfoOptions) => Promise<InfoResponse>;
+    pins: Pins;
     /**
      * Starts the Helia node
      */
@@ -58,6 +50,13 @@ export interface Helia {
      * Stops the Helia node
      */
     stop: () => Promise<void>;
+    /**
+     * Remove any unpinned blocks from the blockstore
+     */
+    gc: (options?: GCOptions) => Promise<void>;
+}
+export type GcEvents = ProgressEvent<'helia:gc:deleted', CID> | ProgressEvent<'helia:gc:error', Error>;
+export interface GCOptions extends AbortOptions, ProgressOptions<GcEvents> {
 }
 export interface InfoOptions extends AbortOptions {
     /**
@@ -66,30 +65,4 @@ export interface InfoOptions extends AbortOptions {
      */
     peerId?: PeerId;
 }
-export interface InfoResponse {
-    /**
-     * The ID of the peer this info is about
-     */
-    peerId: PeerId;
-    /**
-     * The multiaddrs the peer is listening on
-     */
-    multiaddrs: Multiaddr[];
-    /**
-     * The peer's reported agent version
-     */
-    agentVersion: string;
-    /**
-     * The peer's reported protocol version
-     */
-    protocolVersion: string;
-    /**
-     * The protocols the peer supports
-     */
-    protocols: string[];
-    /**
-     * The status of the node
-     */
-    status: 'running' | 'stopped';
-}
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,UAAU,EAAE,UAAU,CAAA;IAEtB;;OAEG;IACH,SAAS,EAAE,SAAS,CAAA;IAEpB;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;IAEtD;;OAEG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1B;;OAEG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,UAAU,EAAE,SAAS,EAAE,CAAA;IAEvB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAA;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,EAAE,CAAA;IAEnB;;OAEG;IACH,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;CAC9B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAE3D;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,SAAS,EAAE,SAAS,CAAA;IAEpB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAA;IAEV;;OAEG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1B;;OAEG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzB;;OAEG;IACH,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C;AAED,MAAM,MAAM,QAAQ,GAClB,aAAa,CAAC,kBAAkB,EAAE,GAAG,CAAC,GACtC,aAAa,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAA;AAExC,MAAM,WAAW,SAAU,SAAQ,YAAY,EAAE,eAAe,CAAC,QAAQ,CAAC;CAEzE;AAED,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB"}

package/dist/src/pins.d.ts

@@ -0,0 +1,48 @@
+import type { AbortOptions } from '@libp2p/interfaces';
+import type { CID } from 'multiformats/cid';
+import type { ProgressEvent, ProgressOptions } from 'progress-events';
+export type PinType = 'recursive' | 'direct' | 'indirect';
+export interface Pin {
+    cid: CID;
+    depth: number;
+    metadata: Record<string, any>;
+}
+export type AddPinEvents = ProgressEvent<'helia:pin:add', unknown>;
+export interface AddOptions extends AbortOptions, ProgressOptions<AddPinEvents> {
+    /**
+     * How deeply to pin the DAG, defaults to Infinity
+     */
+    depth?: number;
+    /**
+     * Optional user-defined metadata to store with the pin
+     */
+    metadata?: Record<string, string | number | boolean>;
+}
+export interface RmOptions extends AbortOptions {
+}
+export interface LsOptions extends AbortOptions {
+    cid?: CID;
+}
+export interface IsPinnedOptions extends AbortOptions {
+}
+export interface Pins {
+    /**
+     * Pin a block in the blockstore. It will not be deleted
+     * when garbage collection is run.
+     */
+    add: (cid: CID, options?: AddOptions) => Promise<Pin>;
+    /**
+     * Unpin the block that corresponds to the passed CID. The block will
+     * be deleted when garbage collection is run.
+     */
+    rm: (cid: CID, options?: RmOptions) => Promise<Pin>;
+    /**
+     * List all blocks that have been pinned.
+     */
+    ls: (options?: LsOptions) => AsyncGenerator<Pin, void, undefined>;
+    /**
+     * Return true if the passed CID is pinned
+     */
+    isPinned: (cid: CID, options?: IsPinnedOptions) => Promise<boolean>;
+}
+//# sourceMappingURL=pins.d.ts.map

package/dist/src/pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../../src/pins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAErE,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAA;AAEzD,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,GAAG,CAAA;IACR,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC9B;AAED,MAAM,MAAM,YAAY,GACtB,aAAa,CAAC,eAAe,EAAE,OAAO,CAAC,CAAA;AAEzC,MAAM,WAAW,UAAW,SAAQ,YAAY,EAAE,eAAe,CAAC,YAAY,CAAC;IAC7E;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CACrD;AAED,MAAM,WAAW,SAAU,SAAQ,YAAY;CAE9C;AAED,MAAM,WAAW,SAAU,SAAQ,YAAY;IAC7C,GAAG,CAAC,EAAE,GAAG,CAAA;CACV;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;CAEpD;AAED,MAAM,WAAW,IAAI;IACnB;;;OAGG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;IAErD;;;OAGG;IACH,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;IAEnD;;OAEG;IACH,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;IAEjE;;OAEG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACpE"}

package/dist/src/pins.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pins.js.map

package/dist/src/pins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.js","sourceRoot":"","sources":["../../src/pins.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helia/interface",
-  "version": "0.0.0-97da23e",
+  "version": "0.0.0-a3a7c9c",
   "description": "The Helia API",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/ipfs/helia/tree/master/packages/interface#readme",
@@ -47,9 +47,13 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     },
-    "./errors": {
-      "types": "./dist/src/errors.d.ts",
-      "import": "./dist/src/errors.js"
+    "./blocks": {
+      "types": "./dist/src/blocks.d.ts",
+      "import": "./dist/src/blocks.js"
+    },
+    "./pins": {
+      "types": "./dist/src/pins.d.ts",
+      "import": "./dist/src/pins.js"
     }
   },
   "eslintConfig": {
@@ -154,9 +158,12 @@
     "@libp2p/interface-libp2p": "^1.1.0",
     "@libp2p/interface-peer-id": "^2.0.1",
     "@libp2p/interfaces": "^3.3.1",
-    "@multiformats/multiaddr": "^11.1.5",
-    "interface-blockstore": "^4.0.1",
-    "interface-datastore": "^7.0.3"
+    "interface-blockstore": "^5.0.0",
+    "interface-datastore": "^8.0.0",
+    "interface-store": "^4.0.0",
+    "ipfs-bitswap": "^17.0.0",
+    "multiformats": "^11.0.1",
+    "progress-events": "^1.0.0"
   },
   "devDependencies": {
     "aegir": "^38.1.0"

package/src/blocks.ts

@@ -0,0 +1,56 @@
+import type { ProgressEvent, ProgressOptions } from 'progress-events'
+import type { CID } from 'multiformats/cid'
+import type { BitswapNotifyProgressEvents, BitswapWantProgressEvents } from 'ipfs-bitswap'
+import type { Blockstore } from 'interface-blockstore'
+
+export interface Pair {
+  cid: CID
+  block: Uint8Array
+}
+
+export type HasBlockProgressEvents =
+  ProgressEvent<'blocks:put:duplicate', CID> |
+  ProgressEvent<'blocks:put:bitswap:notify', CID> |
+  ProgressEvent<'blocks:put:blockstore:put', CID> |
+  BitswapNotifyProgressEvents
+
+export type PutBlockProgressEvents =
+  ProgressEvent<'blocks:put:duplicate', CID> |
+  ProgressEvent<'blocks:put:bitswap:notify', CID> |
+  ProgressEvent<'blocks:put:blockstore:put', CID> |
+  BitswapNotifyProgressEvents
+
+export type PutManyBlocksProgressEvents =
+  ProgressEvent<'blocks:put-many:duplicate', CID> |
+  ProgressEvent<'blocks:put-many:bitswap:notify', CID> |
+  ProgressEvent<'blocks:put-many:blockstore:put-many'> |
+  BitswapNotifyProgressEvents
+
+export type GetBlockProgressEvents =
+  ProgressEvent<'blocks:get:bitswap:want', CID> |
+  ProgressEvent<'blocks:get:blockstore:get', CID> |
+  ProgressEvent<'blocks:get:blockstore:put', CID> |
+  BitswapWantProgressEvents
+
+export type GetManyBlocksProgressEvents =
+  ProgressEvent<'blocks:get-many:blockstore:get-many'> |
+  ProgressEvent<'blocks:get-many:bitswap:want', CID> |
+  ProgressEvent<'blocks:get-many:blockstore:put', CID> |
+  BitswapWantProgressEvents
+
+export type GetAllBlocksProgressEvents =
+  ProgressEvent<'blocks:get-all:blockstore:get-many'>
+
+export type DeleteBlockProgressEvents =
+  ProgressEvent<'blocks:delete:blockstore:delete', CID>
+
+export type DeleteManyBlocksProgressEvents =
+  ProgressEvent<'blocks:delete-many:blockstore:delete-many'>
+
+export interface Blocks extends Blockstore<ProgressOptions<HasBlockProgressEvents>,
+ProgressOptions<PutBlockProgressEvents>, ProgressOptions<PutManyBlocksProgressEvents>,
+ProgressOptions<GetBlockProgressEvents>, ProgressOptions<GetManyBlocksProgressEvents>, ProgressOptions<GetAllBlocksProgressEvents>,
+ProgressOptions<DeleteBlockProgressEvents>, ProgressOptions<DeleteManyBlocksProgressEvents>
+> {
+
+}

package/src/index.ts

@@ -15,11 +15,15 @@
  */
 
 import type { Libp2p } from '@libp2p/interface-libp2p'
-import type { Blockstore } from 'interface-blockstore'
 import type { AbortOptions } from '@libp2p/interfaces'
 import type { PeerId } from '@libp2p/interface-peer-id'
-import type { Multiaddr } from '@multiformats/multiaddr'
 import type { Datastore } from 'interface-datastore'
+import type { Pins } from './pins.js'
+import type { ProgressEvent, ProgressOptions } from 'progress-events'
+import type { CID } from 'multiformats/cid'
+import type { Blocks } from './blocks.js'
+
+export type { Await, AwaitIterable } from 'interface-store'
 
 /**
  * The API presented by a Helia node.
@@ -33,7 +37,7 @@ export interface Helia {
   /**
    * Where the blocks are stored
    */
-  blockstore: Blockstore
+  blockstore: Blocks
 
   /**
    * A key/value store
@@ -41,20 +45,9 @@ export interface Helia {
   datastore: Datastore
 
   /**
-   * Returns information about this node
-   *
-   * @example
-   *
-   * ```typescript
-   * import { createHelia } from 'helia'
-   *
-   * const node = await createHelia()
-   * const id = await node.info()
-   * console.info(id)
-   * // { peerId: PeerId(12D3Foo), ... }
-   * ```
+   * Pinning operations for blocks in the blockstore
    */
-  info: (options?: InfoOptions) => Promise<InfoResponse>
+  pins: Pins
 
   /**
    * Starts the Helia node
@@ -65,44 +58,25 @@ export interface Helia {
    * Stops the Helia node
    */
   stop: () => Promise<void>
-}
 
-export interface InfoOptions extends AbortOptions {
   /**
-   * If passed, return information about this PeerId, defaults
-   * to the ID of the current node.
+   * Remove any unpinned blocks from the blockstore
    */
-  peerId?: PeerId
+  gc: (options?: GCOptions) => Promise<void>
 }
 
-export interface InfoResponse {
-  /**
-   * The ID of the peer this info is about
-   */
-  peerId: PeerId
+export type GcEvents =
+  ProgressEvent<'helia:gc:deleted', CID> |
+  ProgressEvent<'helia:gc:error', Error>
 
-  /**
-   * The multiaddrs the peer is listening on
-   */
-  multiaddrs: Multiaddr[]
+export interface GCOptions extends AbortOptions, ProgressOptions<GcEvents> {
 
-  /**
-   * The peer's reported agent version
-   */
-  agentVersion: string
-
-  /**
-   * The peer's reported protocol version
-   */
-  protocolVersion: string
-
-  /**
-   * The protocols the peer supports
-   */
-  protocols: string[]
+}
 
+export interface InfoOptions extends AbortOptions {
   /**
-   * The status of the node
+   * If passed, return information about this PeerId, defaults
+   * to the ID of the current node.
    */
-  status: 'running' | 'stopped'
+  peerId?: PeerId
 }

package/src/pins.ts

@@ -0,0 +1,62 @@
+import type { AbortOptions } from '@libp2p/interfaces'
+import type { CID } from 'multiformats/cid'
+import type { ProgressEvent, ProgressOptions } from 'progress-events'
+
+export type PinType = 'recursive' | 'direct' | 'indirect'
+
+export interface Pin {
+  cid: CID
+  depth: number
+  metadata: Record<string, any>
+}
+
+export type AddPinEvents =
+  ProgressEvent<'helia:pin:add', unknown>
+
+export interface AddOptions extends AbortOptions, ProgressOptions<AddPinEvents> {
+  /**
+   * How deeply to pin the DAG, defaults to Infinity
+   */
+  depth?: number
+
+  /**
+   * Optional user-defined metadata to store with the pin
+   */
+  metadata?: Record<string, string | number | boolean>
+}
+
+export interface RmOptions extends AbortOptions {
+
+}
+
+export interface LsOptions extends AbortOptions {
+  cid?: CID
+}
+
+export interface IsPinnedOptions extends AbortOptions {
+
+}
+
+export interface Pins {
+  /**
+   * Pin a block in the blockstore. It will not be deleted
+   * when garbage collection is run.
+   */
+  add: (cid: CID, options?: AddOptions) => Promise<Pin>
+
+  /**
+   * Unpin the block that corresponds to the passed CID. The block will
+   * be deleted when garbage collection is run.
+   */
+  rm: (cid: CID, options?: RmOptions) => Promise<Pin>
+
+  /**
+   * List all blocks that have been pinned.
+   */
+  ls: (options?: LsOptions) => AsyncGenerator<Pin, void, undefined>
+
+  /**
+   * Return true if the passed CID is pinned
+   */
+  isPinned: (cid: CID, options?: IsPinnedOptions) => Promise<boolean>
+}