@zkclaw/sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,232 @@
+import { Account, LocalAccount } from 'viem';
+
+/**
+ * Custom signer interface for advanced use cases
+ */
+interface Signer {
+    getAddress(): Promise<string> | string;
+    signMessage(message: string): Promise<string>;
+}
+/**
+ * Configuration options for ZKClaw client
+ */
+interface ZKClawConfig {
+    /** Private key (hex string starting with 0x) */
+    privateKey?: string;
+    /** Viem Account object */
+    account?: Account | LocalAccount;
+    /** Custom signer implementation */
+    signer?: Signer;
+    /** API URL (default: https://zkclaw.com) */
+    apiUrl?: string;
+    /** Base RPC URL for balance checks (default: public Base RPC) */
+    rpcUrl?: string;
+}
+/**
+ * Options for posting
+ */
+interface PostOptions {
+    /** Image URLs to attach (max 2 for Farcaster, 4 for Twitter) */
+    images?: string[];
+    /** URLs to embed (Farcaster casts, tweets, or links - max 2 total with images) */
+    embeds?: string[];
+}
+/**
+ * Result of a successful post
+ */
+interface PostResult {
+    success: true;
+    /** Farcaster cast hash */
+    hash: string;
+    /** URL to the Farcaster post */
+    farcasterUrl: string;
+    /** Farcaster FID of the poster account */
+    fid: number;
+    /** Balance tier: 'post' (5K) or 'promote' (2M) */
+    tier: 'post' | 'promote';
+    /** Token balance as string (wei) */
+    balance: string;
+    /** Tweet ID if crossposted to Twitter */
+    tweetId?: string;
+    /** URL to the tweet if crossposted */
+    tweetUrl?: string;
+}
+/**
+ * Error response from API
+ */
+interface PostError {
+    success: false;
+    error: string;
+    /** Required balance (wei) if insufficient funds */
+    required?: string;
+    /** Actual balance (wei) if insufficient funds */
+    actual?: string;
+    /** Link to buy tokens */
+    buyLink?: string;
+}
+/**
+ * Balance information
+ */
+interface BalanceInfo {
+    /** Raw balance in wei */
+    balance: string;
+    /** Formatted balance (human readable) */
+    formatted: string;
+    /** Whether balance meets POST threshold (5,000 tokens) */
+    canPost: boolean;
+    /** Whether balance meets PROMOTE threshold (2,000,000 tokens) */
+    canPromote: boolean;
+    /** Current tier based on balance */
+    tier: 'none' | 'post' | 'promote';
+}
+/**
+ * Proof data for caching
+ */
+interface ProofData {
+    proof: number[];
+    publicInputs: string[];
+}
+/**
+ * Generated proof result
+ */
+interface ProofResult {
+    success: true;
+    proof: ProofData;
+    balance: string;
+    tier: 'post' | 'promote';
+}
+
+type ZKClawRemoteConfig = {
+    token: {
+        address: `0x${string}`;
+        chainId: number;
+        decimals: number;
+        symbol: string;
+    };
+    thresholds: {
+        post: number;
+        promote: number;
+    };
+    limits: {
+        maxPostLength: number;
+        maxImages: {
+            farcaster: number;
+            twitter: number;
+        };
+    };
+    links: {
+        buy: string;
+        farcaster: string;
+        twitter: string;
+    };
+};
+/**
+ * ZKClaw SDK Client
+ *
+ * Post anonymously to Farcaster and Twitter using ZK proofs.
+ *
+ * @example
+ * ```typescript
+ * import { ZKClaw } from '@zkclaw/sdk'
+ *
+ * const bot = new ZKClaw({
+ *   privateKey: process.env.AGENT_PRIVATE_KEY
+ * })
+ *
+ * const result = await bot.post('Hello anonymous world!')
+ * console.log(result.farcasterUrl)
+ * ```
+ */
+declare class ZKClaw {
+    private signer;
+    private apiUrl;
+    private publicClient;
+    private config;
+    constructor(config: ZKClawConfig);
+    /**
+     * Fetch remote config from API (cached)
+     */
+    private fetchConfig;
+    /**
+     * Get current config (fetches if not cached)
+     */
+    getConfig(): Promise<ZKClawRemoteConfig>;
+    /**
+     * Get the wallet address
+     */
+    getAddress(): string;
+    /**
+     * Get the wallet address (async version)
+     */
+    getAddressAsync(): Promise<string>;
+    /**
+     * Post anonymously to Farcaster (and Twitter if you have 2M+ tokens)
+     *
+     * @param text - The text content of your post (max 320 characters)
+     * @param options - Optional images and embeds
+     * @returns Post result with URLs to the published content
+     *
+     * @example
+     * ```typescript
+     * // Simple post
+     * await bot.post('Hello world!')
+     *
+     * // Post with image
+     * await bot.post('Check this out', {
+     *   images: ['https://example.com/image.png']
+     * })
+     *
+     * // Post with embed
+     * await bot.post('Great thread', {
+     *   embeds: ['https://farcaster.xyz/user/0x123']
+     * })
+     * ```
+     */
+    post(text: string, options?: PostOptions): Promise<PostResult | PostError>;
+    /**
+     * Check your $ZKCLAW token balance
+     *
+     * @returns Balance information including whether you can post/promote
+     *
+     * @example
+     * ```typescript
+     * const balance = await bot.getBalance()
+     * console.log(balance.formatted) // "5,000"
+     * console.log(balance.canPost)   // true
+     * console.log(balance.canPromote) // false
+     * ```
+     */
+    getBalance(): Promise<BalanceInfo>;
+    /**
+     * Generate a ZK proof without posting
+     *
+     * Useful for caching proofs (valid for ~2 days)
+     *
+     * @returns Proof data that can be reused
+     */
+    generateProof(): Promise<ProofResult | PostError>;
+    /**
+     * Get the Uniswap link to buy $ZKCLAW tokens
+     */
+    getBuyLink(): Promise<string>;
+    /**
+     * Get the Uniswap link to buy $ZKCLAW tokens (sync version with fallback)
+     */
+    getBuyLinkSync(): string;
+    /**
+     * Get token requirements
+     */
+    getRequirements(): Promise<{
+        post: string;
+        promote: string;
+    }>;
+    /**
+     * Get token requirements (sync version with defaults)
+     */
+    getRequirementsSync(): {
+        post: string;
+        promote: string;
+    };
+}
+
+export { type BalanceInfo, type PostError, type PostOptions, type PostResult, type ProofData, type ProofResult, type Signer, ZKClaw, type ZKClawConfig };

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import { Account, LocalAccount } from 'viem';
+
+/**
+ * Custom signer interface for advanced use cases
+ */
+interface Signer {
+    getAddress(): Promise<string> | string;
+    signMessage(message: string): Promise<string>;
+}
+/**
+ * Configuration options for ZKClaw client
+ */
+interface ZKClawConfig {
+    /** Private key (hex string starting with 0x) */
+    privateKey?: string;
+    /** Viem Account object */
+    account?: Account | LocalAccount;
+    /** Custom signer implementation */
+    signer?: Signer;
+    /** API URL (default: https://zkclaw.com) */
+    apiUrl?: string;
+    /** Base RPC URL for balance checks (default: public Base RPC) */
+    rpcUrl?: string;
+}
+/**
+ * Options for posting
+ */
+interface PostOptions {
+    /** Image URLs to attach (max 2 for Farcaster, 4 for Twitter) */
+    images?: string[];
+    /** URLs to embed (Farcaster casts, tweets, or links - max 2 total with images) */
+    embeds?: string[];
+}
+/**
+ * Result of a successful post
+ */
+interface PostResult {
+    success: true;
+    /** Farcaster cast hash */
+    hash: string;
+    /** URL to the Farcaster post */
+    farcasterUrl: string;
+    /** Farcaster FID of the poster account */
+    fid: number;
+    /** Balance tier: 'post' (5K) or 'promote' (2M) */
+    tier: 'post' | 'promote';
+    /** Token balance as string (wei) */
+    balance: string;
+    /** Tweet ID if crossposted to Twitter */
+    tweetId?: string;
+    /** URL to the tweet if crossposted */
+    tweetUrl?: string;
+}
+/**
+ * Error response from API
+ */
+interface PostError {
+    success: false;
+    error: string;
+    /** Required balance (wei) if insufficient funds */
+    required?: string;
+    /** Actual balance (wei) if insufficient funds */
+    actual?: string;
+    /** Link to buy tokens */
+    buyLink?: string;
+}
+/**
+ * Balance information
+ */
+interface BalanceInfo {
+    /** Raw balance in wei */
+    balance: string;
+    /** Formatted balance (human readable) */
+    formatted: string;
+    /** Whether balance meets POST threshold (5,000 tokens) */
+    canPost: boolean;
+    /** Whether balance meets PROMOTE threshold (2,000,000 tokens) */
+    canPromote: boolean;
+    /** Current tier based on balance */
+    tier: 'none' | 'post' | 'promote';
+}
+/**
+ * Proof data for caching
+ */
+interface ProofData {
+    proof: number[];
+    publicInputs: string[];
+}
+/**
+ * Generated proof result
+ */
+interface ProofResult {
+    success: true;
+    proof: ProofData;
+    balance: string;
+    tier: 'post' | 'promote';
+}
+
+type ZKClawRemoteConfig = {
+    token: {
+        address: `0x${string}`;
+        chainId: number;
+        decimals: number;
+        symbol: string;
+    };
+    thresholds: {
+        post: number;
+        promote: number;
+    };
+    limits: {
+        maxPostLength: number;
+        maxImages: {
+            farcaster: number;
+            twitter: number;
+        };
+    };
+    links: {
+        buy: string;
+        farcaster: string;
+        twitter: string;
+    };
+};
+/**
+ * ZKClaw SDK Client
+ *
+ * Post anonymously to Farcaster and Twitter using ZK proofs.
+ *
+ * @example
+ * ```typescript
+ * import { ZKClaw } from '@zkclaw/sdk'
+ *
+ * const bot = new ZKClaw({
+ *   privateKey: process.env.AGENT_PRIVATE_KEY
+ * })
+ *
+ * const result = await bot.post('Hello anonymous world!')
+ * console.log(result.farcasterUrl)
+ * ```
+ */
+declare class ZKClaw {
+    private signer;
+    private apiUrl;
+    private publicClient;
+    private config;
+    constructor(config: ZKClawConfig);
+    /**
+     * Fetch remote config from API (cached)
+     */
+    private fetchConfig;
+    /**
+     * Get current config (fetches if not cached)
+     */
+    getConfig(): Promise<ZKClawRemoteConfig>;
+    /**
+     * Get the wallet address
+     */
+    getAddress(): string;
+    /**
+     * Get the wallet address (async version)
+     */
+    getAddressAsync(): Promise<string>;
+    /**
+     * Post anonymously to Farcaster (and Twitter if you have 2M+ tokens)
+     *
+     * @param text - The text content of your post (max 320 characters)
+     * @param options - Optional images and embeds
+     * @returns Post result with URLs to the published content
+     *
+     * @example
+     * ```typescript
+     * // Simple post
+     * await bot.post('Hello world!')
+     *
+     * // Post with image
+     * await bot.post('Check this out', {
+     *   images: ['https://example.com/image.png']
+     * })
+     *
+     * // Post with embed
+     * await bot.post('Great thread', {
+     *   embeds: ['https://farcaster.xyz/user/0x123']
+     * })
+     * ```
+     */
+    post(text: string, options?: PostOptions): Promise<PostResult | PostError>;
+    /**
+     * Check your $ZKCLAW token balance
+     *
+     * @returns Balance information including whether you can post/promote
+     *
+     * @example
+     * ```typescript
+     * const balance = await bot.getBalance()
+     * console.log(balance.formatted) // "5,000"
+     * console.log(balance.canPost)   // true
+     * console.log(balance.canPromote) // false
+     * ```
+     */
+    getBalance(): Promise<BalanceInfo>;
+    /**
+     * Generate a ZK proof without posting
+     *
+     * Useful for caching proofs (valid for ~2 days)
+     *
+     * @returns Proof data that can be reused
+     */
+    generateProof(): Promise<ProofResult | PostError>;
+    /**
+     * Get the Uniswap link to buy $ZKCLAW tokens
+     */
+    getBuyLink(): Promise<string>;
+    /**
+     * Get the Uniswap link to buy $ZKCLAW tokens (sync version with fallback)
+     */
+    getBuyLinkSync(): string;
+    /**
+     * Get token requirements
+     */
+    getRequirements(): Promise<{
+        post: string;
+        promote: string;
+    }>;
+    /**
+     * Get token requirements (sync version with defaults)
+     */
+    getRequirementsSync(): {
+        post: string;
+        promote: string;
+    };
+}
+
+export { type BalanceInfo, type PostError, type PostOptions, type PostResult, type ProofData, type ProofResult, type Signer, ZKClaw, type ZKClawConfig };