@galliun/sofi-sdk/README.md

SDK for interacting with the Galliun SocialFi protocol

# Galliun SoFi SDK

A TypeScript SDK for interacting with the Galliun SoFi protocol on the Sui blockchain.

## Installation

```bash
npm install @galliun/sofi-sdk
```

## Requirements

- Node.js >= 16
- Sui version >= 1.21.2

## Usage

First, initialize the SDK with your package ID and network:

```typescript
import { SoFiClient } from '@galliun/sofi-sdk';

const sdk = new SoFiClient({
	packageId: 'YOUR_PACKAGE_ID',
	network: 'mainnet', // or 'testnet', 'devnet'
});
```

### Profile Management

```typescript
// Create a profile
const createProfileTx = await sdk.profileManager.createProfile(
	signer,
	'username',
	'Display Name',
	'Bio',
	'profile_picture_url',
	'background_picture_url',
);

// Update profile
const updateProfileTx = await sdk.profileManager.updateProfile(
	signer,
	profileId,
	'New Display Name',
	'New Bio',
	'new_profile_picture_url',
	'new_background_picture_url',
);

// Follow/Unfollow
const followTx = await sdk.profileManager.followProfile(myProfileId, targetProfileId);
const unfollowTx = await sdk.profileManager.unfollowProfile(myProfileId, targetProfileId);
```

### Goal Management

```typescript
// Create a goal
const createGoalTx = await sdk.goalManager.createGoal(
	profileId,
	'SUI',
	BigInt(1000000), // amount in smallest unit
	'Goal description',
	false, // overFund
	BigInt(Date.now() + 86400000), // expires in 24h
);

// Pay a goal
const payGoalTx = await sdk.goalManager.payGoal(goalId, coinObjectId, BigInt(100000));

// Claim a goal
const claimGoalTx = await sdk.goalManager.claimGoal(goalId);

// Cancel a goal
const cancelGoalTx = await sdk.goalManager.cancelGoal(goalId);
```

### Tip Management

```typescript
// Create a tip
const createTipTx = await sdk.tipManager.createTip(
	profileId,
	coin,
	recipientAddress,
	'SUI',
	BigInt(1000000),
	'Tip description',
);

// Claim a tip
const claimTipTx = await sdk.tipManager.claimTip(tipId);

// Cancel a tip
const cancelTipTx = await sdk.tipManager.cancelTip(tipId);
```

### Query Methods

```typescript
// Get single object details
const profile = await sdk.profileMnager.getProfileById(profileId);
const goal = await sdk.profileMnager.getGoal(goalId);
const tip = await sdk.profileMnager.getTip(tipId);
```

## Transaction Execution

All methods that modify state return a `Transaction` that needs to be signed and executed:

```typescript
import { Transaction } from '@mysten/sui/transactions';

// Create the transaction
const tx = await sdk.createProfile(/* ... */);

// Sign and execute the transaction using your preferred wallet or signer
const result = await wallet.signAndExecuteTransactionBlock({
	transactionBlock: tx,
});
```

## Error Handling

All methods may throw errors if:

- The network is unavailable
- The contract call fails
- Invalid parameters are provided
- The user lacks necessary permissions

Always wrap calls in try-catch blocks and handle errors appropriately.

## Data Types

The SDK uses the following main types:

```typescript
interface Profile {
	id: string;
	owner: string;
	username: string;
	displayName: string;
	bio: string;
	profilePicture: string;
	backgroundPicture: string;
	points: string;
	links: ProfileLink[];
	followers: string[];
	following: string[];
	acceptTips: boolean;
}

interface Goal {
	id: string;
	profile: string;
	creator: string;
	coinType: string;
	amount: bigint;
	status: GoalStatus;
	totalPaymentsMade: bigint;
	totalAmountPaid: bigint;
	totalAmountClaimed: bigint;
	totalFeeAmount: bigint;
	totalAmountRefunded: bigint;
	description: string;
	expiresAt?: bigint;
	overFund: boolean;
}

interface Tip {
	id: string;
	creator: string;
	recipient: string;
	profile: string;
	coinType: string;
	amount: bigint;
	status: TipStatus;
	totalAmountPaid: bigint;
	totalAmountClaimed: bigint;
	totalFeeAmount: bigint;
	totalAmountRefunded: bigint;
	description: string;
}
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.