@ckbfs/api 1.2.4 → 1.3.0

package/src/index.ts

@@ -7,10 +7,10 @@ import {
 } from './utils/checksum';
 import {
   createCKBFSCell,
-  createPublishTransaction,
-  createAppendTransaction,
-  publishCKBFS,
-  appendCKBFS,
+  createPublishTransaction as utilCreatePublishTransaction,
+  createAppendTransaction as utilCreateAppendTransaction,
+  publishCKBFS as utilPublishCKBFS,
+  appendCKBFS as utilAppendCKBFS,
   CKBFSCellOptions,
   PublishOptions,
   AppendOptions
@@ -56,6 +56,10 @@ import {
   getCKBFSScriptConfig,
   CKBFSScriptConfig
 } from './utils/constants';
+import { ensureHexPrefix } from './utils/transaction';
+
+// Helper to encode string to Uint8Array
+const textEncoder = new TextEncoder();
 
 /**
  * Custom options for file publishing and appending
@@ -70,6 +74,19 @@ export interface FileOptions {
   useTypeID?: boolean;
 }
 
+/**
+ * Options required when publishing content directly (string or Uint8Array)
+ */
+export type PublishContentOptions = Omit<FileOptions, 'capacity' | 'contentType' | 'filename'> & 
+  Required<Pick<FileOptions, 'contentType' | 'filename'>> & 
+  { capacity?: bigint };
+
+/**
+ * Options required when appending content directly (string or Uint8Array)
+ */
+export type AppendContentOptions = Omit<FileOptions, 'contentType' | 'filename' | 'capacity'> & 
+  { capacity?: bigint };
+
 /**
  * Configuration options for the CKBFS SDK
  */
@@ -176,8 +193,8 @@ export class CKBFS {
     const pathParts = filePath.split(/[\\\/]/);
     const filename = options.filename || pathParts[pathParts.length - 1];
     
-    // Create and sign the transaction
-    const tx = await publishCKBFS(this.signer, {
+    // Create and sign the transaction using the utility function
+    const tx = await utilPublishCKBFS(this.signer, {
       contentChunks,
       contentType,
       filename,
@@ -189,16 +206,53 @@ export class CKBFS {
       useTypeID: options.useTypeID !== undefined ? options.useTypeID : this.useTypeID
     });
 
-    console.log('tx', tx.stringify());
+    console.log('Publish file tx:', tx.stringify());
     
     // Send the transaction
     const txHash = await this.signer.sendTransaction(tx);
     
-    return txHash;
+    return ensureHexPrefix(txHash);
+  }
+
+  /**
+   * Publishes content (string or Uint8Array) directly to CKBFS
+   * @param content The content string or byte array to publish
+   * @param options Options for publishing the content (contentType and filename are required)
+   * @returns Promise resolving to the transaction hash
+   */
+  async publishContent(content: string | Uint8Array, options: PublishContentOptions): Promise<string> {
+    const contentBytes = typeof content === 'string' ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    const lock = await this.getLock();
+
+    // Use provided contentType and filename (required)
+    const { contentType, filename } = options;
+
+    const tx = await utilPublishCKBFS(this.signer, {
+      contentChunks,
+      contentType,
+      filename,
+      lock,
+      capacity: options.capacity,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version,
+      useTypeID: options.useTypeID !== undefined ? options.useTypeID : this.useTypeID
+    });
+
+    console.log('Publish content tx:', tx.stringify());
+
+    const txHash = await this.signer.sendTransaction(tx);
+    return ensureHexPrefix(txHash);
   }
   
   /**
-   * Appends content to an existing CKBFS file
+   * Appends content from a file to an existing CKBFS file
    * @param filePath The path to the file containing the content to append
    * @param ckbfsCell The CKBFS cell to append to
    * @param options Additional options for the append operation
@@ -217,19 +271,55 @@ export class CKBFS {
       contentChunks.push(fileContent.slice(i, i + this.chunkSize));
     }
     
-    // Create and sign the transaction
-    const tx = await appendCKBFS(this.signer, {
+    // Create and sign the transaction using the utility function
+    const tx = await utilAppendCKBFS(this.signer, {
       ckbfsCell,
       contentChunks,
       feeRate: options.feeRate,
       network: options.network || this.network,
       version: options.version || this.version
     });
+
+    console.log('Append file tx:', tx.stringify());
     
     // Send the transaction
     const txHash = await this.signer.sendTransaction(tx);
     
-    return txHash;
+    return ensureHexPrefix(txHash);
+  }
+
+  /**
+   * Appends content (string or Uint8Array) directly to an existing CKBFS file
+   * @param content The content string or byte array to append
+   * @param ckbfsCell The CKBFS cell to append to
+   * @param options Additional options for the append operation
+   * @returns Promise resolving to the transaction hash
+   */
+  async appendContent(
+    content: string | Uint8Array,
+    ckbfsCell: AppendOptions['ckbfsCell'],
+    options: AppendContentOptions = {}
+  ): Promise<string> {
+    const contentBytes = typeof content === 'string' ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    const tx = await utilAppendCKBFS(this.signer, {
+      ckbfsCell,
+      contentChunks,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version
+      // No useTypeID option for append
+    });
+
+    console.log('Append content tx:', tx.stringify());
+
+    const txHash = await this.signer.sendTransaction(tx);
+    return ensureHexPrefix(txHash);
   }
   
   /**
@@ -257,8 +347,40 @@ export class CKBFS {
     const pathParts = filePath.split(/[\\\/]/);
     const filename = options.filename || pathParts[pathParts.length - 1];
     
-    // Create the transaction
-    return createPublishTransaction(this.signer, {
+    // Create the transaction using the utility function
+    return utilCreatePublishTransaction(this.signer, {
+      contentChunks,
+      contentType,
+      filename,
+      lock,
+      capacity: options.capacity,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version,
+      useTypeID: options.useTypeID !== undefined ? options.useTypeID : this.useTypeID
+    });
+  }
+
+  /**
+   * Creates a new transaction for publishing content (string or Uint8Array) directly, but doesn't sign or send it
+   * @param content The content string or byte array to publish
+   * @param options Options for publishing the content (contentType and filename are required)
+   * @returns Promise resolving to the unsigned transaction
+   */
+  async createPublishContentTransaction(content: string | Uint8Array, options: PublishContentOptions): Promise<Transaction> {
+    const contentBytes = typeof content === 'string' ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    const lock = await this.getLock();
+
+    // Use provided contentType and filename (required)
+    const { contentType, filename } = options;
+
+    return utilCreatePublishTransaction(this.signer, {
       contentChunks,
       contentType,
       filename,
@@ -272,7 +394,7 @@ export class CKBFS {
   }
   
   /**
-   * Creates a new transaction for appending content but doesn't sign or send it
+   * Creates a new transaction for appending content from a file but doesn't sign or send it
    * @param filePath The path to the file containing the content to append
    * @param ckbfsCell The CKBFS cell to append to
    * @param options Additional options for the append operation
@@ -291,13 +413,42 @@ export class CKBFS {
       contentChunks.push(fileContent.slice(i, i + this.chunkSize));
     }
     
-    // Create the transaction
-    return createAppendTransaction(this.signer, {
+    // Create the transaction using the utility function
+    return utilCreateAppendTransaction(this.signer, {
+      ckbfsCell,
+      contentChunks,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version
+    });
+  }
+
+  /**
+   * Creates a new transaction for appending content (string or Uint8Array) directly, but doesn't sign or send it
+   * @param content The content string or byte array to append
+   * @param ckbfsCell The CKBFS cell to append to
+   * @param options Additional options for the append operation
+   * @returns Promise resolving to the unsigned transaction
+   */
+  async createAppendContentTransaction(
+    content: string | Uint8Array,
+    ckbfsCell: AppendOptions['ckbfsCell'],
+    options: AppendContentOptions = {}
+  ): Promise<Transaction> {
+    const contentBytes = typeof content === 'string' ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    return utilCreateAppendTransaction(this.signer, {
       ckbfsCell,
       contentChunks,
       feeRate: options.feeRate,
       network: options.network || this.network,
       version: options.version || this.version
+      // No useTypeID option for append
     });
   }
 }
@@ -310,12 +461,12 @@ export {
   updateChecksum,
   verifyWitnessChecksum,
   
-  // Transaction utilities
+  // Transaction utilities (Exporting original names from transaction.ts)
   createCKBFSCell,
-  createPublishTransaction,
-  createAppendTransaction,
-  publishCKBFS,
-  appendCKBFS,
+  utilCreatePublishTransaction as createPublishTransaction,
+  utilCreateAppendTransaction as createAppendTransaction,
+  utilPublishCKBFS as publishCKBFS,
+  utilAppendCKBFS as appendCKBFS,
   
   // File utilities
   readFile,

package/src/utils/transaction.ts

@@ -57,7 +57,7 @@ export interface AppendOptions {
  * @param value The string to ensure is hex prefixed
  * @returns A hex prefixed string
  */
-function ensureHexPrefix(value: string): `0x${string}` {
+export function ensureHexPrefix(value: string): `0x${string}` {
   if (value.startsWith('0x')) {
     return value as `0x${string}`;
   }

package/.cursor/rules/typescript.mdc

@@ -1,49 +0,0 @@
----
-description: 
-globs: 
-alwaysApply: true
----
-
-  You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI and Tailwind.
-  
-  Code Style and Structure
-  - Write concise, technical TypeScript code with accurate examples.
-  - Use functional and declarative programming patterns; avoid classes.
-  - Prefer iteration and modularization over code duplication.
-  - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
-  - Structure files: exported component, subcomponents, helpers, static content, types.
-  
-  Naming Conventions
-  - Use lowercase with dashes for directories (e.g., components/auth-wizard).
-  - Favor named exports for components.
-  
-  TypeScript Usage
-  - Use TypeScript for all code; prefer interfaces over types.
-  - Avoid enums; use maps instead.
-  - Use functional components with TypeScript interfaces.
-  
-  Syntax and Formatting
-  - Use the "function" keyword for pure functions.
-  - Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
-  - Use declarative JSX.
-  
-  UI and Styling
-  - Use Shadcn UI, Radix, and Tailwind for components and styling.
-  - Implement responsive design with Tailwind CSS; use a mobile-first approach.
-  
-  Performance Optimization
-  - Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC).
-  - Wrap client components in Suspense with fallback.
-  - Use dynamic loading for non-critical components.
-  - Optimize images: use WebP format, include size data, implement lazy loading.
-  
-  Key Conventions
-  - Use 'nuqs' for URL search parameter state management.
-  - Optimize Web Vitals (LCP, CLS, FID).
-  - Limit 'use client':
-    - Favor server components and Next.js SSR.
-    - Use only for Web API access in small components.
-    - Avoid for data fetching or state management.
-  
-  Follow Next.js docs for Data Fetching, Rendering, and Routing.
-  

package/ABC.LOGS

@@ -1 +0,0 @@
-MINT,TO:ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqdpallzwnhe64rqnqmev7hf98yrmh4yzucgdw7qwGIVE_NAME,NEW_NAME:NERVAPE_COOKIE

package/README.md

@@ -1,138 +0,0 @@
-# CKBFS API SDK
-
-A JavaScript/TypeScript SDK for the CKBFS (Cell Knowledge Base File System) protocol on Nervos CKB.
-
-## Overview
-
-CKBFS is a protocol designed to describe a witnesses-based file storage system on Nervos CKB Network. With CKBFS, you can:
-
-- Store files on Nervos CKB Network
-- Publish large files that may exceed block size limitation (~500kb), across multiple blocks
-- Maintain simple indexing and retrieval
-
-This SDK provides a simple way to interact with the CKBFS protocol, allowing you to:
-
-- Read and write files to CKB
-- Calculate and verify Adler32 checksums
-- Create, manage, and update CKBFS cells
-- Handle witnesses creation and verification
-- Create and send CKB transactions for file operations
-
-## Installation
-
-```bash
-npm install ckbfs-api
-```
-
-## Basic Usage
-
-```typescript
-import { CKBFS } from 'ckbfs-api';
-
-// Initialize the SDK with your private key
-const privateKey = process.env.CKB_PRIVATE_KEY;
-const ckbfs = new CKBFS(privateKey);
-
-// Publish a file to CKBFS
-async function publishExample() {
-  const txHash = await ckbfs.publishFile('path/to/your/file.txt');
-  console.log(`File published with transaction: ${txHash}`);
-}
-
-// Append content to an existing CKBFS file
-async function appendExample(ckbfsCell) {
-  const txHash = await ckbfs.appendFile('path/to/more/content.txt', ckbfsCell);
-  console.log(`Content appended with transaction: ${txHash}`);
-}
-```
-
-## Advanced Usage
-
-The SDK provides utility functions for more granular control:
-
-### Working with Files
-
-```typescript
-import { readFileAsUint8Array, splitFileIntoChunks } from 'ckbfs-api';
-
-// Read a file
-const fileContent = readFileAsUint8Array('path/to/file.txt');
-
-// Split a file into chunks (e.g., for large files)
-const chunks = splitFileIntoChunks('path/to/large/file.bin', 30 * 1024); // 30KB chunks
-```
-
-### Checksum Operations
-
-```typescript
-import { calculateChecksum, verifyChecksum } from 'ckbfs-api';
-
-// Calculate Adler32 checksum
-const content = new TextEncoder().encode('Hello CKBFS');
-const checksum = await calculateChecksum(content);
-
-// Verify checksum
-const isValid = await verifyChecksum(content, checksum);
-```
-
-### Transaction Utilities
-
-```typescript
-import { createPublishTransaction, createAppendTransaction } from 'ckbfs-api';
-
-// Create a transaction without signing or sending
-const tx = await ckbfs.createPublishTransaction('path/to/file.txt');
-
-// Customize the transaction before signing
-// ... modify tx ...
-
-// Sign and send manually
-const signedTx = await signer.signTransaction(tx);
-const txHash = await client.sendTransaction(signedTx);
-```
-
-## Examples
-
-The SDK comes with several examples demonstrating how to use it:
-
-### Running Examples
-
-```bash
-# Show available examples
-npm run example
-
-# Run the publish file example
-npm run example:publish
-
-# Run the append file example (requires a transaction hash)
-npm run example:append -- --txhash=0x123456...
-# OR
-PUBLISH_TX_HASH=0x123456... npm run example:append
-
-# Run the retrieve file example (download a file from blockchain)
-npm run example:retrieve -- --txhash=0x123456... --output=./downloaded-file.txt
-# OR
-CKBFS_TX_HASH=0x123456... npm run example:retrieve
-```
-
-### Example Files
-
-- `examples/publish.ts` - Shows how to publish a file to CKBFS
-- `examples/append.ts` - Shows how to append to a previously published file
-- `examples/retrieve.ts` - Shows how to retrieve a complete file from the blockchain
-
-To run the examples, first set your CKB private key:
-
-```bash
-export CKB_PRIVATE_KEY=your_private_key_here
-```
-
-Note: The append example requires a valid transaction hash from a previously published file. You can either provide it via command line argument or environment variable.
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## License
-
-This project is licensed under the MIT License - see the LICENSE file for details.