docs: generate api docs and publish to gh pages (#260)

* docs: generate api docs and publish to gh pages

* Apply suggestion from @Copilot

Co-authored-by: Copilot <[email protected]>

* fix: typedoc warnings are addressed

* fix: correct type exports

---------

Co-authored-by: Copilot <[email protected]>

Author: SgtPooki

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 'lts/*'
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm install --no-progress
+
+      - name: Build TypeScript
+        run: npm run build
+
+      - name: Generate API Documentation
+        run: npm run docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs/api'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -4,6 +4,7 @@ package-lock.json
 boxo/
 kubo/
 dist/
+docs/
 .vite/
 *.car
 test-output/

README.md

@@ -43,17 +43,20 @@ Upload IPFS files directly to Filecoin via the command line. Perfect for develop
 ### GitHub Action
 Automatically publish websites or build artifacts to IPFS and Filecoin as part of your CI/CD pipeline. Ideal for static websites, documentation sites, and automated deployment workflows.
 
-- **Repository**: This repo ([see upload-action/](./upload-action))
+- **Repository**: This repo ([see upload-action/](./upload-action/README.md))
 - **Documentation**:
    - [GitHub Action Walkthrough](https://docs.filecoin.io/builder-cookbook/filecoin-pin/github-action)
 - **Example in Production**: [filecoin-pin-website CI pipeline](https://github.com/filecoin-project/filecoin-pin-website/tree/main/.github/workflows)
 
-### JavaScript "core" Library
-Opinionated JavaScript library with utilities for common functionality across different use cases. Use these modules directly in your Node.js or browser applications.
+### JavaScript Library
+Use Filecoin Pin programmatically in your Node.js or browser applications. The library provides both a high-level API for common use cases and granular core modules for advanced customization.
 
-- **Repository**: This repo (see [`src/core/`](./src/core) and package exports).
-- **Installation**: `npm install filecoin-pin`
-- **Exports**: Core modules for CAR files, payments, Synapse SDK integration, uploads, and UnixFS operations
+- **Repository**: This repo ([filecoin-project/filecoin-pin](https://github.com/filecoin-project/filecoin-pin))
+- **Documentation**:
+  - [API Reference](https://filecoin-project.github.io/filecoin-pin/) (TypeDoc-generated documentation)
+  - High-level API: `import { … } from 'filecoin-pin'` (recommended for most use cases)
+  - Core modules: `import { … } from 'filecoin-pin/core/*'` (CAR files, payments, Synapse SDK, uploads, UnixFS)
+- **Installation**: `npm install --save filecoin-pin`
 
 ### IPFS Pinning Server (Daemon Mode)
 Run a localhost IPFS Pinning Service API server that implements the [IPFS Pinning Service API specification](https://ipfs.github.io/pinning-services-api-spec/). This allows you to use standard IPFS tooling (like `ipfs pin remote`) while storing data on Filecoin.
@@ -69,7 +72,7 @@ Web-based management console for monitoring and managing your Filecoin Pin deplo
 - **Tracking**: See [issue #74](https://github.com/filecoin-project/filecoin-pin/issues/74) for updates.  Please leave a comment about your usecase if this would be particularly beneficial.
 
 ## Documentation
-See [/documentation](/documentation/).
+See [/documentation](/documentation/README.md).
 
 ## Examples
 
@@ -285,10 +288,10 @@ Interested in contributing? Please read our [Contributing Guidelines](CONTRIBUTI
 
 ### Documentation
 
-- **[documentation/](documentation/)** - (Coming Soon) Additional documentation about how filecoin-pin works, design decisions, etc.
+- **[documentation/](documentation/README.md)** - Additional documentation about how filecoin-pin works, design decisions, etc.
 - **[docs.filecoin.io](https://docs.filecoin.io/builder-cookbook/filecoin-pin)** - Filecoin Pin guides and tutorials
 
 
 ## License
 
-Dual-licensed under [MIT](LICENSE-MIT) + [Apache 2.0](LICENSE-APACHE)
+Dual-licensed under [MIT + Apache 2.0](LICENSE.md)

biome.json

@@ -32,7 +32,8 @@
       "!**/__snapshots__",
       "!**/components.d.ts",
       "!**/mockServiceWorker.js",
-      "!**/cars"
+      "!**/cars",
+      "!docs"
     ]
   },
   "vcs": {

package.json

@@ -87,6 +87,7 @@
     "lint": "tsc && biome check --no-errors-on-unmatched --files-ignore-unknown=true .",
     "lint:fix": "biome check --no-errors-on-unmatched --files-ignore-unknown=true --fix .",
     "typecheck": "tsc --noEmit",
+    "docs": "typedoc",
     "prepublishOnly": "npm run build"
   },
   "repository": {
@@ -131,6 +132,7 @@
     "@vitest/coverage-v8": "^4.0.13",
     "playwright-chromium": "^1.56.1",
     "tsx": "^4.20.5",
+    "typedoc": "^0.28.14",
     "typescript": "^5.9.2",
     "vitest": "^4.0.13"
   },

src/core/data-set/get-data-set-pieces.ts

@@ -11,10 +11,10 @@ import { METADATA_KEYS, type StorageContext, type Synapse, WarmStorageService }
 import { isStorageContextWithDataSetId } from './type-guards.js'
 import type {
   DataSetPiecesResult,
+  DataSetWarning,
   GetDataSetPiecesOptions,
   PieceInfo,
   StorageContextWithDataSetId,
-  Warning,
 } from './types.js'
 
 /**
@@ -57,7 +57,7 @@ export async function getDataSetPieces(
   }
 
   const pieces: PieceInfo[] = []
-  const warnings: Warning[] = []
+  const warnings: DataSetWarning[] = []
 
   // Use the async generator to fetch all pieces
   try {
@@ -119,7 +119,7 @@ async function enrichPiecesWithMetadata(
   synapse: Synapse,
   storageContext: StorageContextWithDataSetId,
   pieces: PieceInfo[],
-  warnings: Warning[],
+  warnings: DataSetWarning[],
   logger?: GetDataSetPiecesOptions['logger']
 ): Promise<void> {
   const dataSetId = storageContext.dataSetId

src/core/data-set/types.ts

@@ -38,13 +38,13 @@ export interface DataSetPiecesResult {
   /** Total size of all pieces in bytes (sum of individual piece sizes) */
   totalSizeBytes?: bigint
   /** Non-fatal warnings encountered during retrieval */
-  warnings?: Warning[]
+  warnings?: DataSetWarning[]
 }
 
 /**
  * Structured warning for non-fatal issues
  */
-export interface Warning {
+export interface DataSetWarning {
   /** Machine-readable warning code (e.g., 'METADATA_FETCH_FAILED') */
   code: string
   /** Human-readable warning message */

src/core/payments/index.ts

@@ -375,6 +375,16 @@ export async function checkAllowances(synapse: Synapse): Promise<{
   }
 }
 
+/**
+ * Result of setting maximum allowances for WarmStorage
+ */
+export interface SetMaxAllowancesResult {
+  /** Transaction hash of the allowance update */
+  transactionHash: string
+  /** Updated allowance status after the transaction */
+  currentAllowances: ServiceApprovalStatus
+}
+
 /**
  * Set WarmStorage allowances to maximum
  *
@@ -384,10 +394,7 @@ export async function checkAllowances(synapse: Synapse): Promise<{
  * @param synapse - Initialized Synapse instance
  * @returns Transaction hash and updated allowances
  */
-export async function setMaxAllowances(synapse: Synapse): Promise<{
-  transactionHash: string
-  currentAllowances: ServiceApprovalStatus
-}> {
+export async function setMaxAllowances(synapse: Synapse): Promise<SetMaxAllowancesResult> {
   const warmStorageAddress = synapse.getWarmStorageAddress()
 
   // Set to maximum allowances

src/core/unixfs/car-builder.ts

@@ -18,7 +18,7 @@ import type { Logger } from 'pino'
 import { CARWritingBlockstore } from '../car/index.js'
 
 // Spinner type for progress reporting
-type Spinner = {
+export type Spinner = {
   start(msg: string): void
   stop(msg: string): void
   message(msg: string): void

src/core/utils/types.ts

@@ -1,4 +1,4 @@
-type AnyProgressEvent = { type: string; data?: unknown }
+export type AnyProgressEvent = { type: string; data?: unknown }
 
 export type ProgressEvent<T extends string = string, D = undefined> = D extends undefined
   ? { type: T }