clanker-sdk 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# Clanker SDK
+
+A lightweight TypeScript SDK for interacting with the Clanker API. This SDK provides a simple interface for token deployment, fee estimation, and reward tracking.
+
+## Installation
+
+```bash
+npm install clanker-sdk
+```
+
+## Quick Start
+
+```typescript
+import { ClankerSDK } from 'clanker-sdk';
+
+// Initialize the SDK with your API key
+const clanker = new ClankerSDK('your_api_key_here');
+
+// Deploy a new token
+const newToken = await clanker.deployToken({
+  name: "My Token",
+  symbol: "MTK",
+  image: "https://example.com/token-image.png",
+  requestorAddress: "0x1234567890abcdef1234567890abcdef12345678",
+});
+```
+
+## Features
+
+- 🚀 Deploy tokens with ease
+- 💰 Track uncollected fees and rewards
+- 🔄 Manage token splits
+- 📊 Query deployed tokens and pool information
+
+## Examples
+
+The SDK comes with several example scripts demonstrating common use cases:
+
+### Token Deployment
+```bash
+# Run the token deployment example
+npm run example:deploy
+```
+
+### Rewards and Fees
+```bash
+# Run the rewards and fees example
+npm run example:rewards
+```
+
+Check out the `examples` directory for the complete source code of these examples.
+
+## API Reference
+
+### `deployToken(options)`
+Deploy a new token with basic configuration.
+
+```typescript
+const token = await clanker.deployToken({
+  name: "Community Token",
+  symbol: "CMTY",
+  image: "https://example.com/token.png",
+  requestorAddress: "0x...",
+});
+```
+
+### `deployTokenWithSplits(options)`
+Deploy a token with custom split configuration.
+
+```typescript
+const token = await clanker.deployTokenWithSplits({
+  name: "Creator Token",
+  symbol: "CRTR",
+  image: "https://example.com/token.png",
+  requestorAddress: "0x...",
+  splitAddress: "0x...",
+});
+```
+
+### `getEstimatedUncollectedFees(contractAddress)`
+Get estimated uncollected fees for a contract.
+
+```typescript
+const fees = await clanker.getEstimatedUncollectedFees("0x...");
+```
+
+### `fetchDeployedByAddress(address, page?)`
+Fetch all tokens deployed by a specific address.
+
+```typescript
+const tokens = await clanker.fetchDeployedByAddress("0x...");
+```
+
+### `getEstimatedRewardsByPoolAddress(poolAddress)`
+Get estimated rewards for a specific pool.
+
+```typescript
+const rewards = await clanker.getEstimatedRewardsByPoolAddress("0x...");
+```
+
+### `getClankerByAddress(address)`
+Fetch details about a specific Clanker by contract address.
+
+```typescript
+const clanker = await clanker.getClankerByAddress("0x...");
+```
+
+## Development
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Build the SDK:
+   ```bash
+   npm run build
+   ```
+4. Run tests:
+   ```bash
+   npm test
+   ```
+5. Run examples:
+   ```bash
+   # Set your API key
+   export CLANKER_API_KEY=your_api_key_here
+   
+   # Run examples
+   npm run example:deploy
+   npm run example:rewards
+   ```
+
+## Error Handling
+
+The SDK includes built-in error handling and validation:
+
+```typescript
+try {
+  await clanker.deployToken({...});
+} catch (error) {
+  if (error instanceof ClankerError) {
+    console.error('API Error:', error.message);
+    console.error('Status:', error.status);
+    console.error('Code:', error.code);
+  }
+}
+```
+
+## License
+
+ISC 

package/dist/index.d.mts

@@ -0,0 +1,70 @@
+interface Token {
+    chainId: number;
+    address: string;
+    symbol: string;
+    decimals: number;
+    name: string;
+}
+interface DeployTokenOptions {
+    name: string;
+    symbol: string;
+    image: string;
+    requestorAddress: string;
+    requestKey?: string;
+}
+interface DeployTokenWithSplitsOptions extends DeployTokenOptions {
+    splitAddress: string;
+}
+interface UncollectedFeesResponse {
+    lockerAddress: string;
+    lpNftId: number;
+    token0UncollectedRewards: string;
+    token1UncollectedRewards: string;
+    token0: Token;
+    token1: Token;
+}
+interface DeployedToken {
+    id: number;
+    created_at: string;
+    tx_hash: string;
+    requestor_fid: number;
+    contract_address: string;
+    name: string;
+    symbol: string;
+    img_url: string | null;
+    pool_address: string;
+    cast_hash: string;
+    type: string;
+    pair: string;
+}
+interface DeployedTokensResponse {
+    data: DeployedToken[];
+    hasMore: boolean;
+    total: number;
+}
+interface EstimatedRewardsResponse {
+    userRewards: number;
+}
+declare class ClankerError extends Error {
+    readonly code?: string | undefined;
+    readonly status?: number | undefined;
+    readonly details?: any | undefined;
+    constructor(message: string, code?: string | undefined, status?: number | undefined, details?: any | undefined);
+}
+
+declare class ClankerSDK {
+    private readonly api;
+    private readonly baseURL;
+    constructor(apiKey: string);
+    getEstimatedUncollectedFees(contractAddress: string): Promise<UncollectedFeesResponse>;
+    deployToken(options: DeployTokenOptions): Promise<DeployedToken>;
+    deployTokenWithSplits(options: DeployTokenWithSplitsOptions): Promise<DeployedToken>;
+    fetchDeployedByAddress(address: string, page?: number): Promise<DeployedTokensResponse>;
+    getEstimatedRewardsByPoolAddress(poolAddress: string): Promise<EstimatedRewardsResponse>;
+    getClankerByAddress(address: string): Promise<DeployedToken>;
+    private generateRequestKey;
+    private isValidAddress;
+    private validateDeployOptions;
+}
+
+export { ClankerError, ClankerSDK, type DeployTokenOptions, type DeployTokenWithSplitsOptions, type DeployedToken, type DeployedTokensResponse, type EstimatedRewardsResponse, type Token, type UncollectedFeesResponse, ClankerSDK as default };

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+interface Token {
+    chainId: number;
+    address: string;
+    symbol: string;
+    decimals: number;
+    name: string;
+}
+interface DeployTokenOptions {
+    name: string;
+    symbol: string;
+    image: string;
+    requestorAddress: string;
+    requestKey?: string;
+}
+interface DeployTokenWithSplitsOptions extends DeployTokenOptions {
+    splitAddress: string;
+}
+interface UncollectedFeesResponse {
+    lockerAddress: string;
+    lpNftId: number;
+    token0UncollectedRewards: string;
+    token1UncollectedRewards: string;
+    token0: Token;
+    token1: Token;
+}
+interface DeployedToken {
+    id: number;
+    created_at: string;
+    tx_hash: string;
+    requestor_fid: number;
+    contract_address: string;
+    name: string;
+    symbol: string;
+    img_url: string | null;
+    pool_address: string;
+    cast_hash: string;
+    type: string;
+    pair: string;
+}
+interface DeployedTokensResponse {
+    data: DeployedToken[];
+    hasMore: boolean;
+    total: number;
+}
+interface EstimatedRewardsResponse {
+    userRewards: number;
+}
+declare class ClankerError extends Error {
+    readonly code?: string | undefined;
+    readonly status?: number | undefined;
+    readonly details?: any | undefined;
+    constructor(message: string, code?: string | undefined, status?: number | undefined, details?: any | undefined);
+}
+
+declare class ClankerSDK {
+    private readonly api;
+    private readonly baseURL;
+    constructor(apiKey: string);
+    getEstimatedUncollectedFees(contractAddress: string): Promise<UncollectedFeesResponse>;
+    deployToken(options: DeployTokenOptions): Promise<DeployedToken>;
+    deployTokenWithSplits(options: DeployTokenWithSplitsOptions): Promise<DeployedToken>;
+    fetchDeployedByAddress(address: string, page?: number): Promise<DeployedTokensResponse>;
+    getEstimatedRewardsByPoolAddress(poolAddress: string): Promise<EstimatedRewardsResponse>;
+    getClankerByAddress(address: string): Promise<DeployedToken>;
+    private generateRequestKey;
+    private isValidAddress;
+    private validateDeployOptions;
+}
+
+export { ClankerError, ClankerSDK, type DeployTokenOptions, type DeployTokenWithSplitsOptions, type DeployedToken, type DeployedTokensResponse, type EstimatedRewardsResponse, type Token, type UncollectedFeesResponse, ClankerSDK as default };

package/dist/index.js

@@ -0,0 +1,173 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ClankerError: () => ClankerError,
+  ClankerSDK: () => ClankerSDK,
+  default: () => ClankerSDK
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/ClankerSDK.ts
+var import_axios = __toESM(require("axios"));
+
+// src/types.ts
+var ClankerError = class extends Error {
+  constructor(message, code, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.name = "ClankerError";
+  }
+};
+
+// src/ClankerSDK.ts
+var ClankerSDK = class {
+  constructor(apiKey) {
+    this.baseURL = "https://www.clanker.world/api";
+    if (!apiKey) {
+      throw new ClankerError("API key is required");
+    }
+    this.api = import_axios.default.create({
+      baseURL: this.baseURL,
+      headers: {
+        "x-api-key": apiKey,
+        "Content-Type": "application/json"
+      }
+    });
+    this.api.interceptors.response.use(
+      (response) => response,
+      (error) => {
+        if (error.response) {
+          throw new ClankerError(
+            error.response.data?.message || "API request failed",
+            error.response.data?.code,
+            error.response.status,
+            error.response.data
+          );
+        }
+        throw new ClankerError("Network error occurred");
+      }
+    );
+  }
+  // Get estimated uncollected fees
+  async getEstimatedUncollectedFees(contractAddress) {
+    if (!this.isValidAddress(contractAddress)) {
+      throw new ClankerError("Invalid contract address format");
+    }
+    const response = await this.api.get(`/get-estimated-uncollected-fees/${contractAddress}`);
+    return response.data;
+  }
+  // Deploy a new token
+  async deployToken(options) {
+    this.validateDeployOptions(options);
+    const requestKey = options.requestKey || this.generateRequestKey();
+    const response = await this.api.post("/tokens/deploy", {
+      ...options,
+      requestKey
+    });
+    return response.data;
+  }
+  // Deploy token with splits
+  async deployTokenWithSplits(options) {
+    this.validateDeployOptions(options);
+    if (!this.isValidAddress(options.splitAddress)) {
+      throw new ClankerError("Invalid split address format");
+    }
+    const requestKey = options.requestKey || this.generateRequestKey();
+    const response = await this.api.post("/tokens/deploy/with-splits", {
+      ...options,
+      requestKey
+    });
+    return response.data;
+  }
+  // Fetch clankers deployed by address
+  async fetchDeployedByAddress(address, page = 1) {
+    if (!this.isValidAddress(address)) {
+      throw new ClankerError("Invalid address format");
+    }
+    if (page < 1) {
+      throw new ClankerError("Page number must be greater than 0");
+    }
+    const response = await this.api.get(`/tokens/fetch-deployed-by-address`, {
+      params: { address, page }
+    });
+    return response.data;
+  }
+  // Get estimated rewards by pool address
+  async getEstimatedRewardsByPoolAddress(poolAddress) {
+    if (!this.isValidAddress(poolAddress)) {
+      throw new ClankerError("Invalid pool address format");
+    }
+    const response = await this.api.get(`/tokens/estimate-rewards-by-pool-address`, {
+      params: { poolAddress }
+    });
+    return response.data;
+  }
+  // Fetch clanker by contract address
+  async getClankerByAddress(address) {
+    if (!this.isValidAddress(address)) {
+      throw new ClankerError("Invalid address format");
+    }
+    const response = await this.api.get(`/get-clanker-by-address`, {
+      params: { address }
+    });
+    return response.data;
+  }
+  // Utility function to generate request key
+  generateRequestKey() {
+    return Array.from(crypto.getRandomValues(new Uint8Array(16))).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  // Validation utilities
+  isValidAddress(address) {
+    return /^0x[a-fA-F0-9]{40}$/.test(address);
+  }
+  validateDeployOptions(options) {
+    if (!options.name || options.name.length < 1) {
+      throw new ClankerError("Token name is required");
+    }
+    if (!options.symbol || options.symbol.length < 1) {
+      throw new ClankerError("Token symbol is required");
+    }
+    if (!this.isValidAddress(options.requestorAddress)) {
+      throw new ClankerError("Invalid requestor address format");
+    }
+    if (options.requestKey && options.requestKey.length !== 32) {
+      throw new ClankerError("Request key must be 32 characters long");
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ClankerError,
+  ClankerSDK
+});

package/dist/index.mjs

@@ -0,0 +1,135 @@
+// src/ClankerSDK.ts
+import axios from "axios";
+
+// src/types.ts
+var ClankerError = class extends Error {
+  constructor(message, code, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.name = "ClankerError";
+  }
+};
+
+// src/ClankerSDK.ts
+var ClankerSDK = class {
+  constructor(apiKey) {
+    this.baseURL = "https://www.clanker.world/api";
+    if (!apiKey) {
+      throw new ClankerError("API key is required");
+    }
+    this.api = axios.create({
+      baseURL: this.baseURL,
+      headers: {
+        "x-api-key": apiKey,
+        "Content-Type": "application/json"
+      }
+    });
+    this.api.interceptors.response.use(
+      (response) => response,
+      (error) => {
+        if (error.response) {
+          throw new ClankerError(
+            error.response.data?.message || "API request failed",
+            error.response.data?.code,
+            error.response.status,
+            error.response.data
+          );
+        }
+        throw new ClankerError("Network error occurred");
+      }
+    );
+  }
+  // Get estimated uncollected fees
+  async getEstimatedUncollectedFees(contractAddress) {
+    if (!this.isValidAddress(contractAddress)) {
+      throw new ClankerError("Invalid contract address format");
+    }
+    const response = await this.api.get(`/get-estimated-uncollected-fees/${contractAddress}`);
+    return response.data;
+  }
+  // Deploy a new token
+  async deployToken(options) {
+    this.validateDeployOptions(options);
+    const requestKey = options.requestKey || this.generateRequestKey();
+    const response = await this.api.post("/tokens/deploy", {
+      ...options,
+      requestKey
+    });
+    return response.data;
+  }
+  // Deploy token with splits
+  async deployTokenWithSplits(options) {
+    this.validateDeployOptions(options);
+    if (!this.isValidAddress(options.splitAddress)) {
+      throw new ClankerError("Invalid split address format");
+    }
+    const requestKey = options.requestKey || this.generateRequestKey();
+    const response = await this.api.post("/tokens/deploy/with-splits", {
+      ...options,
+      requestKey
+    });
+    return response.data;
+  }
+  // Fetch clankers deployed by address
+  async fetchDeployedByAddress(address, page = 1) {
+    if (!this.isValidAddress(address)) {
+      throw new ClankerError("Invalid address format");
+    }
+    if (page < 1) {
+      throw new ClankerError("Page number must be greater than 0");
+    }
+    const response = await this.api.get(`/tokens/fetch-deployed-by-address`, {
+      params: { address, page }
+    });
+    return response.data;
+  }
+  // Get estimated rewards by pool address
+  async getEstimatedRewardsByPoolAddress(poolAddress) {
+    if (!this.isValidAddress(poolAddress)) {
+      throw new ClankerError("Invalid pool address format");
+    }
+    const response = await this.api.get(`/tokens/estimate-rewards-by-pool-address`, {
+      params: { poolAddress }
+    });
+    return response.data;
+  }
+  // Fetch clanker by contract address
+  async getClankerByAddress(address) {
+    if (!this.isValidAddress(address)) {
+      throw new ClankerError("Invalid address format");
+    }
+    const response = await this.api.get(`/get-clanker-by-address`, {
+      params: { address }
+    });
+    return response.data;
+  }
+  // Utility function to generate request key
+  generateRequestKey() {
+    return Array.from(crypto.getRandomValues(new Uint8Array(16))).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  // Validation utilities
+  isValidAddress(address) {
+    return /^0x[a-fA-F0-9]{40}$/.test(address);
+  }
+  validateDeployOptions(options) {
+    if (!options.name || options.name.length < 1) {
+      throw new ClankerError("Token name is required");
+    }
+    if (!options.symbol || options.symbol.length < 1) {
+      throw new ClankerError("Token symbol is required");
+    }
+    if (!this.isValidAddress(options.requestorAddress)) {
+      throw new ClankerError("Invalid requestor address format");
+    }
+    if (options.requestKey && options.requestKey.length !== 32) {
+      throw new ClankerError("Request key must be 32 characters long");
+    }
+  }
+};
+export {
+  ClankerError,
+  ClankerSDK,
+  ClankerSDK as default
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "clanker-sdk",
+  "version": "1.0.0",
+  "description": "A lightweight TypeScript SDK for interacting with the Clanker API",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "jest",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepare": "npm run build",
+    "example:deploy": "ts-node examples/token-deployment.ts",
+    "example:rewards": "ts-node examples/rewards-and-fees.ts",
+    "example": "npm run example:deploy && npm run example:rewards"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clanker-devco/sdk"
+  },
+  "keywords": [
+    "clanker",
+    "api",
+    "sdk",
+    "typescript",
+    "blockchain",
+    "tokens",
+    "web3"
+  ],
+  "author": "Clanker Team",
+  "license": "ISC",
+  "dependencies": {
+    "axios": "^1.6.7"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.19",
+    "@typescript-eslint/eslint-plugin": "^7.0.1",
+    "@typescript-eslint/parser": "^7.0.1",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.5",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.0.2",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}