gem-pluck-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wurlelham531-svg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# gem-pluck-sdk
+
+TypeScript SDK for interacting with the **Gem Pluck** smart contract on Stacks blockchain.
+
+Gem Pluck is an on-chain pluck-a-gem dApp with 6 gems (Ruby, Sapphire, Emerald, Topaz, Amethyst, Onyx). Each pluck is recorded on Stacks mainnet (Clarity 4).
+
+## Installation
+
+```bash
+npm install gem-pluck-sdk
+```
+
+## Quick Start
+
+```typescript
+import { GemPluckClient } from "gem-pluck-sdk";
+
+const client = new GemPluckClient({
+  contractAddress: "SP16F6839630K5XX06KE7KVNSNMYBK89912NH6N4C",
+  contractName: "gem-pluck",
+});
+
+// Get count for gem #1 (Ruby)
+const ruby = await client.getGemCount(1);
+console.log(`Ruby: ${ruby.count}`);
+
+// Get all 6 gem counts in parallel
+const all = await client.getAllGemCounts();
+
+// Total plucks across all gems
+const total = await client.getTotalPlucks();
+
+// Per-user stats
+const me = await client.getUserStats("SP...");
+
+// Leaderboard, sorted by count desc
+const board = await client.getLeaderboard();
+
+// Build pluck transaction args (use with @stacks/connect)
+const args = client.getPluckArgs(3); // pluck Emerald
+```
+
+## API
+
+### `new GemPluckClient(config)`
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `contractAddress` | `string` | Deployer's Stacks address |
+| `contractName` | `string` | Contract name |
+| `network` | `"mainnet" \| "testnet"` | Network (default: `"mainnet"`) |
+
+### Methods
+
+| Method | Returns |
+|--------|---------|
+| `getGemCount(gemId)` | `Promise<GemCount>` |
+| `getAllGemCounts()` | `Promise<GemCount[]>` |
+| `getTotalPlucks()` | `Promise<number>` |
+| `getUserStats(address)` | `Promise<UserStats>` |
+| `getLeaderboard()` | `Promise<(GemCount & { name: string })[]>` |
+| `getPluckArgs(gemId)` | Args for `openContractCall` |
+
+### Constants
+
+```typescript
+import { GEMS } from "gem-pluck-sdk";
+// [{ id: 1, name: "Ruby", color: "#e02060" }, ...]
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+import { GemCount, UserStats, GemPluckConfig } from "./types";
+export declare class GemPluckClient {
+    private contractAddress;
+    private contractName;
+    private network;
+    constructor(config: GemPluckConfig);
+    /**
+     * Get the pluck count for a specific gem (1-6).
+     */
+    getGemCount(gemId: number): Promise<GemCount>;
+    /**
+     * Get counts for all six gems in parallel.
+     */
+    getAllGemCounts(): Promise<GemCount[]>;
+    /**
+     * Get total plucks across all gems.
+     */
+    getTotalPlucks(): Promise<number>;
+    /**
+     * Get a user's pluck history (total + last gem).
+     */
+    getUserStats(address: string): Promise<UserStats>;
+    /**
+     * Leaderboard — gems sorted by pluck count (descending), with names.
+     */
+    getLeaderboard(): Promise<(GemCount & {
+        name: string;
+    })[]>;
+    /**
+     * Build the function args needed for a pluck transaction.
+     * Use with @stacks/connect openContractCall().
+     */
+    getPluckArgs(gemId: number): {
+        contractAddress: string;
+        contractName: string;
+        functionName: string;
+        functionArgs: import("@stacks/transactions").UIntCV[];
+    };
+}

package/dist/client.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GemPluckClient = void 0;
+const transactions_1 = require("@stacks/transactions");
+const network_1 = require("@stacks/network");
+const types_1 = require("./types");
+class GemPluckClient {
+    constructor(config) {
+        this.contractAddress = config.contractAddress;
+        this.contractName = config.contractName;
+        this.network =
+            config.network === "testnet" ? new network_1.StacksTestnet() : new network_1.StacksMainnet();
+    }
+    /**
+     * Get the pluck count for a specific gem (1-6).
+     */
+    async getGemCount(gemId) {
+        var _a, _b;
+        if (gemId < 1 || gemId > 6) {
+            throw new Error("Gem ID must be between 1 and 6");
+        }
+        try {
+            const result = await (0, transactions_1.callReadOnlyFunction)({
+                network: this.network,
+                contractAddress: this.contractAddress,
+                contractName: this.contractName,
+                functionName: "get-gem-count",
+                functionArgs: [(0, transactions_1.uintCV)(gemId)],
+                senderAddress: this.contractAddress,
+            });
+            const json = (0, transactions_1.cvToJSON)(result);
+            const count = parseInt((_b = (_a = json.value) !== null && _a !== void 0 ? _a : json) !== null && _b !== void 0 ? _b : "0");
+            return { gemId, count };
+        }
+        catch (_c) {
+            return { gemId, count: 0 };
+        }
+    }
+    /**
+     * Get counts for all six gems in parallel.
+     */
+    async getAllGemCounts() {
+        const promises = Array.from({ length: 6 }, (_, i) => this.getGemCount(i + 1));
+        return Promise.all(promises);
+    }
+    /**
+     * Get total plucks across all gems.
+     */
+    async getTotalPlucks() {
+        var _a, _b;
+        try {
+            const result = await (0, transactions_1.callReadOnlyFunction)({
+                network: this.network,
+                contractAddress: this.contractAddress,
+                contractName: this.contractName,
+                functionName: "total",
+                functionArgs: [],
+                senderAddress: this.contractAddress,
+            });
+            const json = (0, transactions_1.cvToJSON)(result);
+            return parseInt((_b = (_a = json.value) !== null && _a !== void 0 ? _a : json) !== null && _b !== void 0 ? _b : "0");
+        }
+        catch (_c) {
+            return 0;
+        }
+    }
+    /**
+     * Get a user's pluck history (total + last gem).
+     */
+    async getUserStats(address) {
+        var _a, _b, _c, _d;
+        try {
+            const [pluckRes, lastRes] = await Promise.all([
+                (0, transactions_1.callReadOnlyFunction)({
+                    network: this.network,
+                    contractAddress: this.contractAddress,
+                    contractName: this.contractName,
+                    functionName: "get-user-plucks",
+                    functionArgs: [(0, transactions_1.principalCV)(address)],
+                    senderAddress: this.contractAddress,
+                }),
+                (0, transactions_1.callReadOnlyFunction)({
+                    network: this.network,
+                    contractAddress: this.contractAddress,
+                    contractName: this.contractName,
+                    functionName: "get-user-last-gem",
+                    functionArgs: [(0, transactions_1.principalCV)(address)],
+                    senderAddress: this.contractAddress,
+                }),
+            ]);
+            const pluckJson = (0, transactions_1.cvToJSON)(pluckRes);
+            const lastJson = (0, transactions_1.cvToJSON)(lastRes);
+            const totalPlucks = parseInt((_b = (_a = pluckJson.value) !== null && _a !== void 0 ? _a : pluckJson) !== null && _b !== void 0 ? _b : "0");
+            const lastRaw = (_d = (_c = lastJson === null || lastJson === void 0 ? void 0 : lastJson.value) === null || _c === void 0 ? void 0 : _c.value) !== null && _d !== void 0 ? _d : lastJson === null || lastJson === void 0 ? void 0 : lastJson.value;
+            const lastGem = lastRaw && lastRaw !== null && lastRaw !== undefined
+                ? parseInt(lastRaw)
+                : null;
+            return { totalPlucks, lastGem: isNaN(lastGem) ? null : lastGem };
+        }
+        catch (_e) {
+            return { totalPlucks: 0, lastGem: null };
+        }
+    }
+    /**
+     * Leaderboard — gems sorted by pluck count (descending), with names.
+     */
+    async getLeaderboard() {
+        const counts = await this.getAllGemCounts();
+        return counts
+            .map((c) => {
+            var _a, _b;
+            return (Object.assign(Object.assign({}, c), { name: (_b = (_a = types_1.GEMS.find((g) => g.id === c.gemId)) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : `Gem ${c.gemId}` }));
+        })
+            .sort((a, b) => b.count - a.count);
+    }
+    /**
+     * Build the function args needed for a pluck transaction.
+     * Use with @stacks/connect openContractCall().
+     */
+    getPluckArgs(gemId) {
+        if (gemId < 1 || gemId > 6) {
+            throw new Error("Gem ID must be between 1 and 6");
+        }
+        return {
+            contractAddress: this.contractAddress,
+            contractName: this.contractName,
+            functionName: "pluck",
+            functionArgs: [(0, transactions_1.uintCV)(gemId)],
+        };
+    }
+}
+exports.GemPluckClient = GemPluckClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { GemPluckClient } from "./client";
+export { GemCount, UserStats, GemInfo, GemPluckConfig, GEMS } from "./types";

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEMS = exports.GemPluckClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "GemPluckClient", { enumerable: true, get: function () { return client_1.GemPluckClient; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "GEMS", { enumerable: true, get: function () { return types_1.GEMS; } });

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+export interface GemCount {
+    gemId: number;
+    count: number;
+}
+export interface UserStats {
+    totalPlucks: number;
+    lastGem: number | null;
+}
+export interface GemInfo {
+    id: number;
+    name: string;
+    color: string;
+}
+export interface GemPluckConfig {
+    contractAddress: string;
+    contractName: string;
+    network?: "mainnet" | "testnet";
+}
+export declare const GEMS: GemInfo[];

package/dist/types.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEMS = void 0;
+exports.GEMS = [
+    { id: 1, name: "Ruby", color: "#e02060" },
+    { id: 2, name: "Sapphire", color: "#2060e0" },
+    { id: 3, name: "Emerald", color: "#20c060" },
+    { id: 4, name: "Topaz", color: "#e0a020" },
+    { id: 5, name: "Amethyst", color: "#a020e0" },
+    { id: 6, name: "Onyx", color: "#404040" },
+];

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "gem-pluck-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for interacting with the Gem Pluck smart contract on Stacks blockchain",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "stacks",
+    "blockchain",
+    "clarity",
+    "smart-contract",
+    "sdk",
+    "web3",
+    "gems"
+  ],
+  "author": "wurlelham531-svg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wurlelham531-svg/gem-pluck-sdk"
+  },
+  "dependencies": {
+    "@stacks/transactions": "^6.0.0",
+    "@stacks/network": "^6.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}