@zburn/core/README.md

Core utilities for the ZBURN ecosystem.

# ZBURN Core Utilities

---


**ZBURN Core Utilities** is your essential toolkit for bridging the gap between traditional Web2 deployments and the decentralized Web3 world. This package provides robust functionalities for deploying your web projects to IPFS, ensuring persistence through distributed pinning, and making them seamlessly accessible via Cloudflare.

Whether you're looking for a one-click deployment for your CI/CD pipeline or granular control over each step, ZBURN offers the flexibility you need.

---


## 🚀 Features

- **IPFS Deployment:** Easily deploy your local project folders to the InterPlanetary File System (IPFS).
- **Distributed Pinning:** Automatically pin your content across multiple IPFS pinning services (like 4EVERLAND and your custom ZBURN gateway) to ensure high availability and persistence.
- **Gateway Stimulation:** Accelerate content propagation by "stimulating" various public IPFS gateways, making your content discoverable faster.
- **Cloudflare Integration:**
  - **DNSLink Updates:** Automatically update your Cloudflare `_dnslink` TXT records.
  - **KV Namespace Updates:** Update Cloudflare Workers KV Namespaces with the latest CID.
- **Flexible CLI:** Use a simple command-line interface for quick deployments or detailed control.
- **Programmatic API:** Integrate ZBURN's functionalities directly into your Node.js scripts.

---


## 📦 Installation

To get started with ZBURN, install the core package via npm:

```bash
npm install @zburn/core
```

---


## ⚙️ Configuration (`.zburnrc.json`)

ZBURN uses a `.zburnrc.json` file in your project's root directory to manage all your deployment settings.

```json
{
  "pin_gateways": [
    {
      "urlTemplate": "https://api.4everland.dev/pins",
      "method": "POST",
      "auth": {
        "type": "Bearer",
        "tokenEnvVar": "EVERPIN_ACCESS_TOKEN"
      },
      "headers": {
        "Content-Type": "application/json"
      },
      "bodyTemplate": {
        "cid": "{{cid}}",
        "name": "pin-{{cid}}"
      }
    },
    {
      "urlTemplate": "https://gateway.zburn.xyz/ipfs/{{cid}}",
      "method": "GET"
    }
  ],
  "stimulate_gateways": [
    "https://w3s.link/ipfs/",
    "https://cloudflare-ipfs.com/ipfs/",
    "https://gateway.pinata.cloud/ipfs/",
    "https://dweb.link/ipfs/",
    "https://gateway.zburn.xyz/ipfs/"
  ],
  "pin_env_var": {
    "EVERPIN_ACCESS_TOKEN": "XXX"
  },
  "cloudflare": {
    "apiToken": "XXXX-XXXX-XXXX-XX",
    "accountId": "XXXX",
    "zoneId": "XXXX",
    "worker": {
      "kvNameSpace": "MY_AMAZING_KVNAMESPACE",
      "kvKey": "MY_AMAZING_KV_KEY"
    },
    "dnsLink": {
      "domain": "my-amazing-website.com",
      "subdomain": "_dnslink",
      "ttl": 300
    }
  }
}
```

---


## 🖥️ Usage

### Command-Line Interface (CLI)

```bash
npx zburn deploy <folder>
```

Example:

```bash
npx zburn deploy ./dist
```

#### IPFS Only Deployment

```bash
npx zburn deploy ipfs ./build
```

#### Cloudflare Only Update

```bash
npx zburn deploy cloudflare QmYtRpU6s3t5q7k8m9n0p1q2r3s4t5u6v7w8x9y0z
```

#### Help

```bash
npx zburn help
```

---


## 📚 Programmatic Usage

```js
const zburn = require('@zburn/core');

async function myCustomDeployment() {
  try {
    const cid = await zburn.ipfs.deploy('./my-project/build');
    console.log(\`Deployed to IPFS with CID: \${cid}\`);

    const finalCid = await zburn.deployFull('./another-project/dist');
    console.log(\`Full deployment completed with CID: \${finalCid}\`);
  } catch (error) {
    console.error("Deployment failed:", error);
  }
}

myCustomDeployment();
```

---


## 🔑 Getting Your Configuration Data

### 4EVERLAND Access Token (EVERPIN_ACCESS_TOKEN)

1. Go to [4everland.org](https://4everland.org) and log in.
2. Generate or copy an API token.
3. Set it as an environment variable:

```bash
export EVERPIN_ACCESS_TOKEN="YOUR_TOKEN_HERE"
```

---


### Cloudflare API Configuration

- **Account ID** and **Zone ID** from the Cloudflare dashboard.
- **API Token**: Create a custom token with permissions for DNS and Workers KV.
- **Worker Script Name**, **KV Namespace**, and **KV Key** from Workers dashboard.
- **DNSLink** setup: `_dnslink.my-amazing-website.com`

---


## 📘 License

MIT

---


If you'd like to follow ZBURN updates or just say thanks, follow us on X: https://x.com/ZBURN_X