number-guess-sdk 1.0.0

package/README.md

@@ -0,0 +1,32 @@
+# number-guess-sdk
+
+TypeScript SDK bundled inside the Number Guess app repository for interacting with the Number Guess contract on Stacks.
+
+## Installation
+
+```bash
+npm install number-guess-sdk
+```
+
+## Usage
+
+```ts
+import { getLeaderboard, getTotalGuesses, createGuessCall } from "number-guess-sdk";
+
+const total = await getTotalGuesses();
+const leaderboard = await getLeaderboard();
+const tx = createGuessCall(42);
+```
+
+## License
+
+MIT
+## Core Methods
+
+- `getTotalGuesses()`
+- `getTotalWins()`
+- `getUserGuesses(address)`
+- `getUserWins(address)`
+- `getUserLastGuess(address)`
+- `getUserLastTarget(address)`
+- `createGuessCall(value)`

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+import type { NumberGuessConfig, LeaderEntry, ReadOnlyResponse, GuessCall } from "./types";
+export declare const DEFAULT_CONFIG: Required<NumberGuessConfig>;
+export declare function callReadOnly(functionName: string, args?: string[], config?: NumberGuessConfig): Promise<ReadOnlyResponse>;
+export declare function getTotalGuesses(config?: NumberGuessConfig): Promise<number>;
+export declare function getTotalWins(config?: NumberGuessConfig): Promise<number>;
+export declare function getUserGuesses(userAddress: string, config?: NumberGuessConfig): Promise<number>;
+export declare function getUserWins(userAddress: string, config?: NumberGuessConfig): Promise<number>;
+export declare function getUserLastGuess(userAddress: string, config?: NumberGuessConfig): Promise<number>;
+export declare function getUserLastTarget(userAddress: string, config?: NumberGuessConfig): Promise<number>;
+export declare function getLeaderboard(config?: NumberGuessConfig): Promise<LeaderEntry[]>;
+export declare function createGuessCall(value: number, config?: NumberGuessConfig): GuessCall;
+export declare class NumberGuessClient {
+    private readonly config;
+    constructor(config?: NumberGuessConfig);
+    getTotalGuesses(): Promise<number>;
+    getTotalWins(): Promise<number>;
+    getUserGuesses(userAddress: string): Promise<number>;
+    getUserWins(userAddress: string): Promise<number>;
+    getUserLastGuess(userAddress: string): Promise<number>;
+    getUserLastTarget(userAddress: string): Promise<number>;
+    getLeaderboard(): Promise<LeaderEntry[]>;
+    createGuessCall(value: number): GuessCall;
+}

package/dist/client.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NumberGuessClient = exports.DEFAULT_CONFIG = void 0;
+exports.callReadOnly = callReadOnly;
+exports.getTotalGuesses = getTotalGuesses;
+exports.getTotalWins = getTotalWins;
+exports.getUserGuesses = getUserGuesses;
+exports.getUserWins = getUserWins;
+exports.getUserLastGuess = getUserLastGuess;
+exports.getUserLastTarget = getUserLastTarget;
+exports.getLeaderboard = getLeaderboard;
+exports.createGuessCall = createGuessCall;
+const network_1 = require("@stacks/network");
+const transactions_1 = require("@stacks/transactions");
+exports.DEFAULT_CONFIG = {
+    contractAddress: "SP1Q7YR67R6WGP28NXDJD1WZ11REPAAXRJJ3V6RKM",
+    contractName: "number-guess",
+    apiBase: "https://api.mainnet.hiro.so",
+    network: network_1.STACKS_MAINNET,
+};
+function resolveConfig(overrides = {}) {
+    return { ...exports.DEFAULT_CONFIG, ...overrides };
+}
+function serializeCvToHex(cv) {
+    const serialized = (0, transactions_1.serializeCV)(cv);
+    if (typeof serialized === "string") {
+        return serialized.startsWith("0x") ? serialized : `0x${serialized}`;
+    }
+    return `0x${Buffer.from(serialized).toString("hex")}`;
+}
+function extractNumericValue(result) {
+    const clarityValue = (0, transactions_1.hexToCV)(result);
+    const parsed = (0, transactions_1.cvToValue)(clarityValue, true);
+    return Number(parsed && typeof parsed === "object" && "value" in parsed
+        ? parsed.value ?? 0
+        : parsed ?? 0);
+}
+function normalizeLeaderboardValue(raw) {
+    const entries = Array.isArray(raw) ? raw : [];
+    return entries
+        .map(item => {
+        const entry = item && typeof item === "object" && "value" in item
+            ? item.value
+            : item;
+        const record = entry;
+        return {
+            who: String(record?.who && typeof record.who === "object" ? record.who.value ?? "" : record?.who ?? ""),
+            wins: Number(record?.wins && typeof record.wins === "object"
+                ? record.wins.value ?? 0
+                : record?.wins ?? 0),
+        };
+    })
+        .filter(entry => entry.who && entry.wins > 0);
+}
+async function callReadOnly(functionName, args = [], config = {}) {
+    const resolved = resolveConfig(config);
+    const response = await fetch(`${resolved.apiBase}/v2/contracts/call-read/${resolved.contractAddress}/${resolved.contractName}/${functionName}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            sender: resolved.contractAddress,
+            arguments: args,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Read-only call failed with status ${response.status}`);
+    }
+    return response.json();
+}
+async function getTotalGuesses(config = {}) {
+    const data = await callReadOnly("get-total-guesses", [], config);
+    return data.okay && data.result ? extractNumericValue(data.result) : 0;
+}
+async function getTotalWins(config = {}) {
+    const data = await callReadOnly("get-total-wins", [], config);
+    return data.okay && data.result ? extractNumericValue(data.result) : 0;
+}
+async function getUserGuesses(userAddress, config = {}) {
+    const principalArg = serializeCvToHex((0, transactions_1.principalCV)(userAddress));
+    const data = await callReadOnly("get-user-guesses", [principalArg], config);
+    return data.okay && data.result ? extractNumericValue(data.result) : 0;
+}
+async function getUserWins(userAddress, config = {}) {
+    const principalArg = serializeCvToHex((0, transactions_1.principalCV)(userAddress));
+    const data = await callReadOnly("get-user-wins", [principalArg], config);
+    return data.okay && data.result ? extractNumericValue(data.result) : 0;
+}
+async function getUserLastGuess(userAddress, config = {}) {
+    const principalArg = serializeCvToHex((0, transactions_1.principalCV)(userAddress));
+    const data = await callReadOnly("get-user-last-guess", [principalArg], config);
+    return data.okay && data.result ? extractNumericValue(data.result) : 0;
+}
+async function getUserLastTarget(userAddress, config = {}) {
+    const principalArg = serializeCvToHex((0, transactions_1.principalCV)(userAddress));
+    const data = await callReadOnly("get-user-last-target", [principalArg], config);
+    return data.okay && data.result ? extractNumericValue(data.result) : 0;
+}
+async function getLeaderboard(config = {}) {
+    const data = await callReadOnly("get-leaderboard", [], config);
+    if (!data.okay || !data.result) {
+        return [];
+    }
+    const clarityValue = (0, transactions_1.hexToCV)(data.result);
+    const parsed = (0, transactions_1.cvToValue)(clarityValue, true);
+    return normalizeLeaderboardValue(parsed);
+}
+function createGuessCall(value, config = {}) {
+    const resolved = resolveConfig(config);
+    return {
+        contractAddress: resolved.contractAddress,
+        contractName: resolved.contractName,
+        functionName: "guess",
+        functionArgs: [(0, transactions_1.uintCV)(Math.max(1, Math.min(100, Math.floor(value))))],
+        postConditionMode: transactions_1.PostConditionMode.Deny,
+        postConditions: [],
+        network: resolved.network,
+    };
+}
+class NumberGuessClient {
+    constructor(config = {}) {
+        this.config = resolveConfig(config);
+    }
+    getTotalGuesses() {
+        return getTotalGuesses(this.config);
+    }
+    getTotalWins() {
+        return getTotalWins(this.config);
+    }
+    getUserGuesses(userAddress) {
+        return getUserGuesses(userAddress, this.config);
+    }
+    getUserWins(userAddress) {
+        return getUserWins(userAddress, this.config);
+    }
+    getUserLastGuess(userAddress) {
+        return getUserLastGuess(userAddress, this.config);
+    }
+    getUserLastTarget(userAddress) {
+        return getUserLastTarget(userAddress, this.config);
+    }
+    getLeaderboard() {
+        return getLeaderboard(this.config);
+    }
+    createGuessCall(value) {
+        return createGuessCall(value, this.config);
+    }
+}
+exports.NumberGuessClient = NumberGuessClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { NumberGuessConfig, LeaderEntry, ReadOnlyResponse, GuessCall } from "./types";
+export { DEFAULT_CONFIG, NumberGuessClient, callReadOnly, getTotalGuesses, getTotalWins, getUserGuesses, getUserWins, getUserLastGuess, getUserLastTarget, getLeaderboard, createGuessCall, } from "./client";

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGuessCall = exports.getLeaderboard = exports.getUserLastTarget = exports.getUserLastGuess = exports.getUserWins = exports.getUserGuesses = exports.getTotalWins = exports.getTotalGuesses = exports.callReadOnly = exports.NumberGuessClient = exports.DEFAULT_CONFIG = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "DEFAULT_CONFIG", { enumerable: true, get: function () { return client_1.DEFAULT_CONFIG; } });
+Object.defineProperty(exports, "NumberGuessClient", { enumerable: true, get: function () { return client_1.NumberGuessClient; } });
+Object.defineProperty(exports, "callReadOnly", { enumerable: true, get: function () { return client_1.callReadOnly; } });
+Object.defineProperty(exports, "getTotalGuesses", { enumerable: true, get: function () { return client_1.getTotalGuesses; } });
+Object.defineProperty(exports, "getTotalWins", { enumerable: true, get: function () { return client_1.getTotalWins; } });
+Object.defineProperty(exports, "getUserGuesses", { enumerable: true, get: function () { return client_1.getUserGuesses; } });
+Object.defineProperty(exports, "getUserWins", { enumerable: true, get: function () { return client_1.getUserWins; } });
+Object.defineProperty(exports, "getUserLastGuess", { enumerable: true, get: function () { return client_1.getUserLastGuess; } });
+Object.defineProperty(exports, "getUserLastTarget", { enumerable: true, get: function () { return client_1.getUserLastTarget; } });
+Object.defineProperty(exports, "getLeaderboard", { enumerable: true, get: function () { return client_1.getLeaderboard; } });
+Object.defineProperty(exports, "createGuessCall", { enumerable: true, get: function () { return client_1.createGuessCall; } });

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+import type { StacksNetwork } from "@stacks/network";
+import type { ClarityValue, PostCondition, PostConditionMode } from "@stacks/transactions";
+export interface NumberGuessConfig {
+    contractAddress?: string;
+    contractName?: string;
+    apiBase?: string;
+    network?: StacksNetwork;
+}
+export interface LeaderEntry {
+    who: string;
+    wins: number;
+}
+export interface ReadOnlyResponse {
+    okay?: boolean;
+    result?: string;
+    cause?: string;
+}
+export interface GuessCall {
+    contractAddress: string;
+    contractName: string;
+    functionName: "guess";
+    functionArgs: ClarityValue[];
+    postConditionMode: PostConditionMode;
+    postConditions: PostCondition[];
+    network: StacksNetwork;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "number-guess-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for interacting with the Number Guess smart contract on Stacks blockchain",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "stacks",
+    "blockchain",
+    "number-guess",
+    "guessing-game",
+    "sdk",
+    "smart-contract",
+    "web3",
+    "dapp",
+    "stacks-blockchain",
+    "typescript",
+    "on-chain",
+    "prediction-game",
+    "number-game"
+  ],
+  "author": "brventonbeshers-ship-it",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brventonbeshers-ship-it/number-guess.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/brventonbeshers-ship-it/number-guess/issues"
+  },
+  "homepage": "https://github.com/brventonbeshers-ship-it/number-guess/tree/main/sdk#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@stacks/network": "^7.3.1",
+    "@stacks/transactions": "^7.3.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}