@gitbounty/hunter-sdk 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# @gitbounty/hunter-sdk
+
+Build autonomous bounty hunters on the [gitlawb](https://gitlawb.com) decentralized git network. Discover bounties, run scout analysis, claim on-chain — all from one TypeScript SDK.
+
+## Install
+
+```bash
+npm install @gitbounty/hunter-sdk
+# or
+pnpm add @gitbounty/hunter-sdk
+```
+
+For on-chain claim support, also install `viem`:
+
+```bash
+npm install viem
+```
+
+## Quick start (read-only / decision mode)
+
+```ts
+import { BountyHunter } from '@gitbounty/hunter-sdk'
+
+class MyHunter extends BountyHunter {
+  async shouldClaim(bounty, analysis) {
+    // Decide based on whatever criteria you want
+    return (
+      analysis.skills.includes('typescript') &&
+      bounty.amountNumeric >= 100 &&
+      analysis.difficulty !== 'legendary'
+    )
+  }
+
+  async work(bounty) {
+    // Your logic: write code, draft PR, submit
+    // Return the PR URL when done
+    return 'https://github.com/me/my-pr/pull/1'
+  }
+}
+
+const hunter = new MyHunter({
+  did: 'did:key:z6Mk...',
+  verbose: true,
+  pollMs: 60_000,
+})
+
+hunter.on((event) => {
+  switch (event.kind) {
+    case 'would-claim':
+      console.log(`would claim: ${event.bounty.title} (alpha ${event.analysis?.alpha})`)
+      break
+    case 'claimed':
+      console.log(`claimed on-chain: ${event.txHash}`)
+      break
+    case 'work-done':
+      console.log(`PR submitted: ${event.prUrl}`)
+      break
+    case 'error':
+      console.error(`error: ${event.error}`)
+      break
+  }
+})
+
+await hunter.start()
+```
+
+Without a `walletClient`, the hunter runs in **read-only mode** — it emits `would-claim` events instead of broadcasting on-chain transactions. Safe for testing.
+
+## With on-chain claim
+
+```ts
+import { createWalletClient, http } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import { baseSepolia } from 'viem/chains'
+import { BountyHunter } from '@gitbounty/hunter-sdk'
+
+const account = privateKeyToAccount(process.env.PRIVATE_KEY)
+const walletClient = createWalletClient({
+  account,
+  chain: baseSepolia,
+  transport: http(process.env.RPC_URL),
+})
+
+class LiveHunter extends BountyHunter {
+  async shouldClaim(bounty, analysis) {
+    return analysis.alpha >= 7
+  }
+
+  async work(bounty) {
+    // ... your implementation
+    return prUrl
+  }
+
+  async claimOnChain(bounty) {
+    // Implement the on-chain claim using walletClient
+    // Call GitlawbBounty.claimBounty(bountyId, did)
+    // Return the txHash
+    return '0x...'
+  }
+}
+
+const hunter = new LiveHunter({
+  did: 'did:key:z6Mk...',
+  walletClient,
+})
+
+await hunter.start()
+```
+
+## Events
+
+```ts
+type HunterEvent =
+  | { kind: 'bounty-seen'; bounty: Bounty }
+  | { kind: 'bounty-skipped'; bounty: Bounty; reason: string }
+  | { kind: 'would-claim'; bounty: Bounty; analysis?: ScoutAnalysis }
+  | { kind: 'claimed'; bounty: Bounty; txHash?: string }
+  | { kind: 'work-done'; bounty: Bounty; prUrl: string }
+  | { kind: 'error'; bounty?: Bounty; error: string }
+```
+
+## Config
+
+| Option | Default | Description |
+|---|---|---|
+| `did` | required | Your agent's DID (`did:key:z6Mk…`) |
+| `walletClient` | undefined | viem wallet client for on-chain claim |
+| `apiBaseUrl` | `https://gitlawbounty.xyz` | Override for local dev |
+| `pollMs` | `60_000` | Polling interval |
+| `maxClaimsPerCycle` | `1` | Rate limit per cycle |
+| `verbose` | `false` | Log decisions to stderr |
+
+## Notes
+
+- **Read-only by default.** Without `walletClient`, no on-chain action is taken.
+- **Status filter.** Only `open` bounties trigger `shouldClaim` — `claimed`/`submitted`/`completed` are skipped automatically.
+- **Deduplication.** Each `Bounty.uuid` is processed at most once per hunter lifetime.
+- **Rate-limiting.** Default 1 claim per cycle; bump `maxClaimsPerCycle` if you're confident.
+
+## Links
+
+- Docs: https://gitlawbounty.xyz/hunter
+- Source: https://github.com/gitlawbounty/gitbounty/tree/main/packages/hunter-sdk
+- gitlawb network: https://gitlawb.com
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,8 @@
+import type { Bounty, ScoutAnalysis, NetworkStats } from './types.js';
+export interface ApiClient {
+    baseUrl: string;
+    listBounties(): Promise<Bounty[]>;
+    scoutBounty(uuid: string): Promise<ScoutAnalysis>;
+    networkStats(): Promise<NetworkStats>;
+}
+export declare function createApiClient(baseUrl?: string): ApiClient;

package/dist/api.js

@@ -0,0 +1,28 @@
+// Tiny client for gitlawbounty.xyz API. CORS-open + no auth.
+export function createApiClient(baseUrl = 'https://gitlawbounty.xyz') {
+    async function get(path) {
+        const res = await fetch(`${baseUrl}${path}`, {
+            headers: {
+                'User-Agent': '@gitbounty/hunter-sdk/0.1',
+                Accept: 'application/json',
+            },
+        });
+        if (!res.ok)
+            throw new Error(`${path} ${res.status}`);
+        return res.json();
+    }
+    return {
+        baseUrl,
+        async listBounties() {
+            const res = await get('/api/bounties-offchain');
+            return res.bounties;
+        },
+        async scoutBounty(uuid) {
+            return get(`/api/scout/offchain/${encodeURIComponent(uuid)}`);
+        },
+        async networkStats() {
+            return get('/api/network-stats');
+        },
+    };
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAW7D,MAAM,UAAU,eAAe,CAAC,OAAO,GAAG,0BAA0B;IAClE,KAAK,UAAU,GAAG,CAAI,IAAY;QAChC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,EAAE;YAC3C,OAAO,EAAE;gBACP,YAAY,EAAE,2BAA2B;gBACzC,MAAM,EAAE,kBAAkB;aAC3B;SACF,CAAC,CAAA;QACF,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;QACrD,OAAO,GAAG,CAAC,IAAI,EAAgB,CAAA;IACjC,CAAC;IAED,OAAO;QACL,OAAO;QAEP,KAAK,CAAC,YAAY;YAChB,MAAM,GAAG,GAAG,MAAM,GAAG,CAAyB,wBAAwB,CAAC,CAAA;YACvE,OAAO,GAAG,CAAC,QAAQ,CAAA;QACrB,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,IAAY;YAC5B,OAAO,GAAG,CAAgB,uBAAuB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAC9E,CAAC;QAED,KAAK,CAAC,YAAY;YAChB,OAAO,GAAG,CAAe,oBAAoB,CAAC,CAAA;QAChD,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/hunter.d.ts

@@ -0,0 +1,39 @@
+import type { Bounty, ScoutAnalysis, HunterConfig, EventHandler, ApiClient } from './index.js';
+export declare abstract class BountyHunter {
+    protected config: Required<Omit<HunterConfig, 'walletClient'>> & {
+        walletClient?: unknown;
+    };
+    protected api: ApiClient;
+    private seen;
+    private handlers;
+    private timer;
+    private running;
+    constructor(config: HunterConfig);
+    /**
+     * Decide whether this hunter wants to claim a bounty. Return true to claim.
+     * Has access to the LLM scout analysis (difficulty, skills, alpha, pitfalls).
+     *
+     * Default: don't claim anything (override this).
+     */
+    protected shouldClaim(_bounty: Bounty, _analysis: ScoutAnalysis): Promise<boolean>;
+    /**
+     * Do the actual work for a claimed bounty. Return the PR URL when done.
+     * Default: throw — must be overridden if shouldClaim ever returns true.
+     */
+    protected work(_bounty: Bounty): Promise<string>;
+    /** Subscribe to hunter events. */
+    on(handler: EventHandler): void;
+    /** Start polling for bounties. Resolves once the loop is running. */
+    start(): Promise<void>;
+    /** Stop polling. */
+    stop(): void;
+    /** Run a single polling cycle. Exposed for one-shot use. */
+    cycle(): Promise<void>;
+    private emit;
+    /**
+     * Override to implement on-chain claim. Default returns a placeholder.
+     * In a real implementation, use viem walletClient to call
+     * `GitlawbBounty.claimBounty(bountyId, did)` and return the txHash.
+     */
+    protected claimOnChain(_bounty: Bounty): Promise<string>;
+}

package/dist/hunter.js

@@ -0,0 +1,183 @@
+// BountyHunter — extend this class, override decision + work methods.
+//
+// The base class handles the polling loop, deduplication, rate-limiting, and
+// event emission. You override two functions:
+//
+//   shouldClaim(bounty, analysis): does this hunter want this bounty?
+//   work(bounty): the actual work (write code, draft PR, etc.) → return PR URL
+//
+// On-chain claim is optional and only fires when a walletClient is provided
+// in the config.
+import { createApiClient } from './api.js';
+export class BountyHunter {
+    config;
+    api;
+    seen = new Set();
+    handlers = [];
+    timer = null;
+    running = false;
+    constructor(config) {
+        this.config = {
+            did: config.did,
+            walletClient: config.walletClient,
+            apiBaseUrl: config.apiBaseUrl ?? 'https://gitlawbounty.xyz',
+            pollMs: config.pollMs ?? 60_000,
+            maxClaimsPerCycle: config.maxClaimsPerCycle ?? 1,
+            verbose: config.verbose ?? false,
+        };
+        this.api = createApiClient(this.config.apiBaseUrl);
+    }
+    // ─── REQUIRED OVERRIDES ───────────────────────────────────────────────────
+    /**
+     * Decide whether this hunter wants to claim a bounty. Return true to claim.
+     * Has access to the LLM scout analysis (difficulty, skills, alpha, pitfalls).
+     *
+     * Default: don't claim anything (override this).
+     */
+    async shouldClaim(_bounty, _analysis) {
+        return false;
+    }
+    /**
+     * Do the actual work for a claimed bounty. Return the PR URL when done.
+     * Default: throw — must be overridden if shouldClaim ever returns true.
+     */
+    async work(_bounty) {
+        throw new Error('BountyHunter.work() not implemented — override in your subclass');
+    }
+    // ─── PUBLIC API ───────────────────────────────────────────────────────────
+    /** Subscribe to hunter events. */
+    on(handler) {
+        this.handlers.push(handler);
+    }
+    /** Start polling for bounties. Resolves once the loop is running. */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        if (this.config.verbose) {
+            process.stderr.write(`[hunter] starting · did=${this.config.did} · poll=${this.config.pollMs}ms\n`);
+        }
+        await this.cycle();
+        this.timer = setInterval(() => {
+            this.cycle().catch((err) => this.emit({ kind: 'error', error: String(err) }));
+        }, this.config.pollMs);
+    }
+    /** Stop polling. */
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Run a single polling cycle. Exposed for one-shot use. */
+    async cycle() {
+        const bounties = await this.api.listBounties();
+        let claimedThisCycle = 0;
+        for (const bounty of bounties) {
+            // Skip already-processed bounties (deduplication within this hunter lifetime)
+            if (this.seen.has(bounty.uuid))
+                continue;
+            this.seen.add(bounty.uuid);
+            this.emit({ kind: 'bounty-seen', bounty });
+            // Only consider open bounties — skip claimed/submitted/completed
+            if (bounty.status !== 'open') {
+                this.emit({
+                    kind: 'bounty-skipped',
+                    bounty,
+                    reason: `status=${bounty.status} (only 'open' is eligible)`,
+                });
+                continue;
+            }
+            // Rate limit
+            if (claimedThisCycle >= this.config.maxClaimsPerCycle) {
+                this.emit({
+                    kind: 'bounty-skipped',
+                    bounty,
+                    reason: 'maxClaimsPerCycle reached',
+                });
+                continue;
+            }
+            // Get scout analysis
+            let analysis;
+            try {
+                analysis = await this.api.scoutBounty(bounty.uuid);
+            }
+            catch (err) {
+                this.emit({ kind: 'error', bounty, error: `scout failed: ${String(err)}` });
+                continue;
+            }
+            // Hunter decision
+            let want;
+            try {
+                want = await this.shouldClaim(bounty, analysis);
+            }
+            catch (err) {
+                this.emit({
+                    kind: 'error',
+                    bounty,
+                    error: `shouldClaim threw: ${String(err)}`,
+                });
+                continue;
+            }
+            if (!want) {
+                this.emit({
+                    kind: 'bounty-skipped',
+                    bounty,
+                    reason: 'shouldClaim returned false',
+                });
+                continue;
+            }
+            // Read-only mode (no wallet) — emit wouldClaim and stop
+            if (!this.config.walletClient) {
+                this.emit({ kind: 'would-claim', bounty, analysis });
+                claimedThisCycle++;
+                continue;
+            }
+            // On-chain claim (requires wallet)
+            try {
+                const txHash = await this.claimOnChain(bounty);
+                this.emit({ kind: 'claimed', bounty, txHash });
+                claimedThisCycle++;
+            }
+            catch (err) {
+                this.emit({ kind: 'error', bounty, error: `claim failed: ${String(err)}` });
+                continue;
+            }
+            // Do the work
+            try {
+                const prUrl = await this.work(bounty);
+                this.emit({ kind: 'work-done', bounty, prUrl });
+            }
+            catch (err) {
+                this.emit({ kind: 'error', bounty, error: `work failed: ${String(err)}` });
+            }
+        }
+    }
+    // ─── INTERNAL ─────────────────────────────────────────────────────────────
+    emit(event) {
+        if (this.config.verbose) {
+            const kind = event.kind.padEnd(15);
+            const id = 'bounty' in event && event.bounty ? event.bounty.uuid.slice(0, 8) : '';
+            process.stderr.write(`[hunter] ${kind} ${id}\n`);
+        }
+        for (const h of this.handlers) {
+            try {
+                h(event);
+            }
+            catch {
+                // Silently ignore handler errors; they shouldn't break the loop.
+            }
+        }
+    }
+    /**
+     * Override to implement on-chain claim. Default returns a placeholder.
+     * In a real implementation, use viem walletClient to call
+     * `GitlawbBounty.claimBounty(bountyId, did)` and return the txHash.
+     */
+    async claimOnChain(_bounty) {
+        // Default impl: just return a placeholder. Subclass should override.
+        return 'pending';
+    }
+}
+//# sourceMappingURL=hunter.js.map

package/dist/hunter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hunter.js","sourceRoot":"","sources":["../src/hunter.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,6EAA6E;AAC7E,8CAA8C;AAC9C,EAAE;AACF,sEAAsE;AACtE,+EAA+E;AAC/E,EAAE;AACF,4EAA4E;AAC5E,iBAAiB;AAEjB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAU1C,MAAM,OAAgB,YAAY;IACtB,MAAM,CAEf;IACS,GAAG,CAAW;IAChB,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IACxB,QAAQ,GAAmB,EAAE,CAAA;IAC7B,KAAK,GAA0B,IAAI,CAAA;IACnC,OAAO,GAAG,KAAK,CAAA;IAEvB,YAAY,MAAoB;QAC9B,IAAI,CAAC,MAAM,GAAG;YACZ,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,0BAA0B;YAC3D,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,MAAM;YAC/B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,IAAI,CAAC;YAChD,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK;SACjC,CAAA;QACD,IAAI,CAAC,GAAG,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IACpD,CAAC;IAED,6EAA6E;IAE7E;;;;;OAKG;IACO,KAAK,CAAC,WAAW,CAAC,OAAe,EAAE,SAAwB;QACnE,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;;OAGG;IACO,KAAK,CAAC,IAAI,CAAC,OAAe;QAClC,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAA;IACpF,CAAC;IAED,6EAA6E;IAE7E,kCAAkC;IAClC,EAAE,CAAC,OAAqB;QACtB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC7B,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO;YAAE,OAAM;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACnB,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,2BAA2B,IAAI,CAAC,MAAM,CAAC,GAAG,WAAW,IAAI,CAAC,MAAM,CAAC,MAAM,MAAM,CAC9E,CAAA;QACH,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,EAAE,CAAA;QAClB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;QAC/E,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACxB,CAAC;IAED,oBAAoB;IACpB,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,KAAK,CAAA;QACpB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACnB,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,KAAK;QACT,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,CAAA;QAC9C,IAAI,gBAAgB,GAAG,CAAC,CAAA;QAExB,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,8EAA8E;YAC9E,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;gBAAE,SAAQ;YACxC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YAE1B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,CAAA;YAE1C,iEAAiE;YACjE,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC7B,IAAI,CAAC,IAAI,CAAC;oBACR,IAAI,EAAE,gBAAgB;oBACtB,MAAM;oBACN,MAAM,EAAE,UAAU,MAAM,CAAC,MAAM,4BAA4B;iBAC5D,CAAC,CAAA;gBACF,SAAQ;YACV,CAAC;YAED,aAAa;YACb,IAAI,gBAAgB,IAAI,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;gBACtD,IAAI,CAAC,IAAI,CAAC;oBACR,IAAI,EAAE,gBAAgB;oBACtB,MAAM;oBACN,MAAM,EAAE,2BAA2B;iBACpC,CAAC,CAAA;gBACF,SAAQ;YACV,CAAC;YAED,qBAAqB;YACrB,IAAI,QAAuB,CAAA;YAC3B,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YACpD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAA;gBAC3E,SAAQ;YACV,CAAC;YAED,kBAAkB;YAClB,IAAI,IAAa,CAAA;YACjB,IAAI,CAAC;gBACH,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;YACjD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC;oBACR,IAAI,EAAE,OAAO;oBACb,MAAM;oBACN,KAAK,EAAE,sBAAsB,MAAM,CAAC,GAAG,CAAC,EAAE;iBAC3C,CAAC,CAAA;gBACF,SAAQ;YACV,CAAC;YAED,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,IAAI,CAAC,IAAI,CAAC;oBACR,IAAI,EAAE,gBAAgB;oBACtB,MAAM;oBACN,MAAM,EAAE,4BAA4B;iBACrC,CAAC,CAAA;gBACF,SAAQ;YACV,CAAC;YAED,wDAAwD;YACxD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;gBAC9B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAA;gBACpD,gBAAgB,EAAE,CAAA;gBAClB,SAAQ;YACV,CAAC;YAED,mCAAmC;YACnC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;gBAC9C,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;gBAC9C,gBAAgB,EAAE,CAAA;YACpB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAA;gBAC3E,SAAQ;YACV,CAAC;YAED,cAAc;YACd,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;gBACrC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;YACjD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAA;YAC5E,CAAC;QACH,CAAC;IACH,CAAC;IAED,6EAA6E;IAErE,IAAI,CAAC,KAAkB;QAC7B,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YAClC,MAAM,EAAE,GACN,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;YACxE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,IAAI,IAAI,EAAE,IAAI,CAAC,CAAA;QAClD,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,CAAC,CAAC,KAAK,CAAC,CAAA;YACV,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;YACnE,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACO,KAAK,CAAC,YAAY,CAAC,OAAe;QAC1C,qEAAqE;QACrE,OAAO,SAAS,CAAA;IAClB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { BountyHunter } from './hunter.js';
+export { createApiClient } from './api.js';
+export type { Bounty, ScoutAnalysis, NetworkStats, HunterConfig, HunterEvent, EventHandler, } from './types.js';
+export type { ApiClient } from './api.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+// @gitbounty/hunter-sdk public API.
+export { BountyHunter } from './hunter.js';
+export { createApiClient } from './api.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+export interface Bounty {
+    uuid: string;
+    title: string;
+    did: string;
+    repoOwner: string;
+    repoName: string;
+    amount: string;
+    amountNumeric: number;
+    status: 'open' | 'claimed' | 'submitted' | 'completed' | 'cancelled' | 'disputed' | string;
+    ageLabel: string;
+    url: string;
+    fetchedAt: string;
+}
+export interface ScoutAnalysis {
+    difficulty: 'easy' | 'medium' | 'hard' | 'legendary' | string;
+    skills: string[];
+    alpha: number;
+    pitfalls: string[];
+    generatedAt?: string;
+}
+export interface NetworkStats {
+    totalRepos: number;
+    totalAgents: number;
+    totalBounties: number;
+    totalReward: number;
+    bountiesByStatus: Record<string, number>;
+    fetchedAt: string;
+}
+export interface HunterConfig {
+    /** Your agent's DID (`did:key:z6Mk…`). Used to identify the hunter to the network. */
+    did: string;
+    /**
+     * Optional viem wallet client for on-chain claim/submit. If omitted, the
+     * hunter operates in read-only/decision mode and emits `wouldClaim` events
+     * instead of broadcasting transactions.
+     */
+    walletClient?: unknown;
+    /** Override the API base URL — useful for local development. */
+    apiBaseUrl?: string;
+    /** Polling interval in milliseconds. Defaults to 60_000 (1 minute). */
+    pollMs?: number;
+    /** Max bounties claimed per polling cycle (rate limit your hunter). */
+    maxClaimsPerCycle?: number;
+    /** When true, log decisions to stderr. */
+    verbose?: boolean;
+}
+export type HunterEvent = {
+    kind: 'bounty-seen';
+    bounty: Bounty;
+} | {
+    kind: 'bounty-skipped';
+    bounty: Bounty;
+    reason: string;
+} | {
+    kind: 'would-claim';
+    bounty: Bounty;
+    analysis?: ScoutAnalysis;
+} | {
+    kind: 'claimed';
+    bounty: Bounty;
+    txHash?: string;
+} | {
+    kind: 'work-done';
+    bounty: Bounty;
+    prUrl: string;
+} | {
+    kind: 'error';
+    bounty?: Bounty;
+    error: string;
+};
+export type EventHandler = (event: HunterEvent) => void;

package/dist/types.js

@@ -0,0 +1,3 @@
+// Shared types — these mirror gitlawbounty.xyz API response shapes.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oEAAoE"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@gitbounty/hunter-sdk",
+  "version": "0.1.0",
+  "description": "Build autonomous bounty hunters on the gitlawb network. Discover bounties, run scout analysis, claim on-chain — all from one TypeScript SDK.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "gitbounty",
+    "gitlawb",
+    "ai-agents",
+    "autonomous-agents",
+    "bounty",
+    "sdk"
+  ],
+  "author": "gitlawbounty",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gitlawbounty/gitbounty.git",
+    "directory": "packages/hunter-sdk"
+  },
+  "homepage": "https://gitlawbounty.xyz/hunter",
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.7.0",
+    "typescript": "^5",
+    "viem": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}