{"_id":"@dmystical-coder/fundstacks-headless-sdk","_rev":"3-6c37229775adcafd76b517dcac1eefe7","name":"@dmystical-coder/fundstacks-headless-sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@dmystical-coder/fundstacks-headless-sdk","version":"0.1.0","keywords":["fundraising","sdk","web3","headless","stacks","clarity"],"license":"MIT","_id":"@dmystical-coder/fundstacks-headless-sdk@0.1.0","maintainers":[{"name":"dmystical-coder","email":"dmystical.coder@gmail.com"}],"dist":{"shasum":"a6758f8a022305019cda50a16f0c20b2bd1aea3a","tarball":"https://registry.npmjs.org/@dmystical-coder/fundstacks-headless-sdk/-/fundstacks-headless-sdk-0.1.0.tgz","fileCount":9,"integrity":"sha512-wguepphFZYJLiZlISx7IIrUXgFhrMlH0d9Mn3tH5JD5td1KKhUNcA9KRp5OLtlWdV39IOlh+MLGz6FGkZuYrQQ==","signatures":[{"sig":"MEUCIB2S+8kYrMxj+DMzMmuviB8WExksfLl4DTKc2zgEgKTMAiEAjeSJvoBjYulRIofy6rZWhx4B5P8AxgOWlpLVyuBPmnI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23911},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"2312f8d8612427b1866869e68ad9e8bbce21b36b","scripts":{"lint":"eslint . --ext .ts","test":"vitest run --pool=threads","build":"tsup","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"dmystical-coder","email":"dmystical.coder@gmail.com"},"_npmVersion":"11.6.2","description":"Headless TypeScript SDK for FundStacks donation flows.","directories":{},"_nodeVersion":"22.22.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","eslint":"^8.57.1","vitest":"^3.2.4","typescript":"^5.9.3","@types/node":"^24.7.2","@typescript-eslint/parser":"^8.44.0","@typescript-eslint/eslint-plugin":"^8.44.0"},"_npmOperationalInternal":{"tmp":"tmp/fundstacks-headless-sdk_0.1.0_1776833812283_0.693956198684011","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@dmystical-coder/fundstacks-headless-sdk","version":"0.1.1","keywords":["fundraising","sdk","web3","headless","stacks","clarity"],"license":"MIT","_id":"@dmystical-coder/fundstacks-headless-sdk@0.1.1","maintainers":[{"name":"dmystical-coder","email":"dmystical.coder@gmail.com"}],"homepage":"https://github.com/dmystical-coder/fundstacks-headless-sdk#readme","bugs":{"url":"https://github.com/dmystical-coder/fundstacks-headless-sdk/issues"},"dist":{"shasum":"3e7cd708b432282b8a1e0372280f21b82a8e6e45","tarball":"https://registry.npmjs.org/@dmystical-coder/fundstacks-headless-sdk/-/fundstacks-headless-sdk-0.1.1.tgz","fileCount":9,"integrity":"sha512-Tsz+Fpse/JOCnt9IK0czLeLRWUYLLuHuIxjzjHPivJF6QXs43zPoAq4+GtfyEfhppIkZC1RRL3vipJBVByHrIg==","signatures":[{"sig":"MEUCIGbB0hVHpd9aPxakSgE7DKUTcVhkr3GiZTJM0IEp3k0TAiEA4xb8ULr4VuTxsOv4KsZoNKXIU6BIbxoWK9sIT17csqg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24546},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"ccb03e00c3e74e88dd8d034789648dd7f81cae28","scripts":{"lint":"eslint . --ext .ts","test":"vitest run --pool=threads","build":"tsup","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"dmystical-coder","email":"dmystical.coder@gmail.com"},"repository":{"url":"git+https://github.com/dmystical-coder/fundstacks-headless-sdk.git","type":"git"},"_npmVersion":"11.6.2","description":"Headless TypeScript SDK for FundStacks donation flows.","directories":{},"_nodeVersion":"22.22.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","eslint":"^8.57.1","vitest":"^3.2.4","typescript":"^5.9.3","@types/node":"^24.7.2","@typescript-eslint/parser":"^8.44.0","@typescript-eslint/eslint-plugin":"^8.44.0"},"_npmOperationalInternal":{"tmp":"tmp/fundstacks-headless-sdk_0.1.1_1776836863775_0.32824710463539564","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@dmystical-coder/fundstacks-headless-sdk","version":"0.2.0","description":"Headless TypeScript SDK for FundStacks donation flows.","type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"clean":"rm -rf dist","build":"tsup","lint":"eslint . --ext .ts","test":"vitest run --pool=threads","prepublishOnly":"npm run clean && npm run build"},"keywords":["fundraising","sdk","web3","headless","stacks","clarity"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/dmystical-coder/fundstacks-headless-sdk.git"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"engines":{"node":">=18"},"dependencies":{},"devDependencies":{"@types/node":"^24.7.2","@typescript-eslint/eslint-plugin":"^8.44.0","@typescript-eslint/parser":"^8.44.0","eslint":"^8.57.1","tsup":"^8.5.0","typescript":"^5.9.3","vitest":"^3.2.4"},"gitHead":"851e81fee406c8054fcb543f93d332ffcb129a64","_id":"@dmystical-coder/fundstacks-headless-sdk@0.2.0","bugs":{"url":"https://github.com/dmystical-coder/fundstacks-headless-sdk/issues"},"homepage":"https://github.com/dmystical-coder/fundstacks-headless-sdk#readme","_nodeVersion":"24.11.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-hN6LukblnXkR+gknw6o+lEdfeqhe4YQfB3+zk9ACuMXXN4aCaB8MbTnNpUZ4Lyig2Nh4PrioQ++YZ4Sflk2rlg==","shasum":"cd25e67e819992902a27e9464ab5322812682b62","tarball":"https://registry.npmjs.org/@dmystical-coder/fundstacks-headless-sdk/-/fundstacks-headless-sdk-0.2.0.tgz","fileCount":10,"unpackedSize":43774,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFA0sr6DKqrp9B5ebUJrSFowZBk1J4ri/nI2i8AT7ZzzAiBq1ZtcYpTCevbd5OGIWaXwU3NAOhuVENvv41WqBnx9fw=="}]},"_npmUser":{"name":"dmystical-coder","email":"dmystical.coder@gmail.com"},"directories":{},"maintainers":[{"name":"dmystical-coder","email":"dmystical.coder@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fundstacks-headless-sdk_0.2.0_1777045214313_0.7181934287106231"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-22T04:56:52.139Z","modified":"2026-04-24T15:40:14.567Z","0.1.0":"2026-04-22T04:56:52.429Z","0.1.1":"2026-04-22T05:47:43.912Z","0.2.0":"2026-04-24T15:40:14.458Z"},"bugs":{"url":"https://github.com/dmystical-coder/fundstacks-headless-sdk/issues"},"license":"MIT","homepage":"https://github.com/dmystical-coder/fundstacks-headless-sdk#readme","keywords":["fundraising","sdk","web3","headless","stacks","clarity"],"repository":{"type":"git","url":"git+https://github.com/dmystical-coder/fundstacks-headless-sdk.git"},"description":"Headless TypeScript SDK for FundStacks donation flows.","maintainers":[{"name":"dmystical-coder","email":"dmystical.coder@gmail.com"}],"readme":"# @dmystical-coder/fundstacks-headless-sdk\n\n[![npm version](https://img.shields.io/npm/v/%40dmystical-coder%2Ffundstacks-headless-sdk)](https://www.npmjs.com/package/@dmystical-coder/fundstacks-headless-sdk)\n[![npm monthly downloads](https://img.shields.io/npm/dm/%40dmystical-coder%2Ffundstacks-headless-sdk)](https://www.npmjs.com/package/@dmystical-coder/fundstacks-headless-sdk)\n[![npm total downloads](https://img.shields.io/npm/dt/%40dmystical-coder%2Ffundstacks-headless-sdk)](https://www.npmjs.com/package/@dmystical-coder/fundstacks-headless-sdk)\n\nHeadless TypeScript SDK for FundStacks donation flows.\n\nThis package provides framework-agnostic primitives to build and execute Stacks contract-call donations (`donate-stx` / `donate-sbtc`) without coupling to React, wallet UI, or a specific app runtime.\n\n## Installation\n\n```bash\nnpm install @dmystical-coder/fundstacks-headless-sdk\n```\n\n## Changelog\n\nVersion history and release notes: [CHANGELOG.md](./CHANGELOG.md).\n\n## Quick Start\n\n`donate()` needs a **wallet client** that can submit a contract call (e.g. from [Leather](https://leather.io/) / [Stacks Connect](https://github.com/hirosystems/connect)). The snippet below uses a minimal stub so the example is copy-pasteable; replace it with your real adapter.\n\n```ts\nimport { createClient, donate } from \"@dmystical-coder/fundstacks-headless-sdk\";\n\nconst walletClient = {\n  callContract: async (options) => {\n    // Delegate to your wallet / @stacks/connect openContractCall, then return the tx id.\n    return { txid: \"0x...\" };\n  }\n};\n\nconst client = createClient({\n  contractAddress: \"ST000000000000000000002AMW42H\",\n  contractName: \"fundraising\",\n  network: \"testnet\",\n  walletClient\n});\n\n// Amounts: STX in micro-STX (µSTX); sBTC in satoshis — see Units below.\nconst txId = await donate(client, {\n  campaignId: 42n,\n  amount: 1_000_000n,\n  asset: \"stx\",\n  senderAddress: \"ST2J8EVYHP2JXQ6XEAH2V7W4N19WQQ9Q0DXM1ANQG\"\n});\n```\n\n### Wallet adapter\n\nImplement `WalletClient.callContract` so it forwards `options` from `buildDonateTx` / `donate` to your signing flow and resolves with the broadcast transaction id (string or `{ txid }` / `{ txId }`). The exact mapping to `@stacks/transactions` / Connect is app-specific; see [Stacks transaction building](https://github.com/hirosystems/stacks.js) for low-level assembly.\n\n## Units\n\n- **`asset: \"stx\"`** — `amount` is in **micro-STX** (µSTX, 1 STX = 1_000_000 µSTX), matching typical Stacks STX post-conditions.\n- **`asset: \"sbtc\"`** — `amount` is in **satoshis** (sats), per the fundraising contract’s sBTC path.\n\n## Build unsigned donation transaction\n\nUse this when your app signs or broadcasts outside the SDK:\n\n```ts\nimport { buildDonateTx } from \"@dmystical-coder/fundstacks-headless-sdk\";\n\nconst txOptions = buildDonateTx(client, {\n  campaignId: 42,\n  amount: 1_000_000n,\n  asset: \"stx\",\n  senderAddress: \"ST2J8EVYHP2JXQ6XEAH2V7W4N19WQQ9Q0DXM1ANQG\"\n});\n```\n\n## API\n\n- `createClient(config)`  \n  Create a reusable SDK client with contract/network/signer settings. Optional: `sbtcAsset` (default SIP-010 id for sBTC donations), `strictTxId` (see below).\n- `buildDonateTx(client, input)`  \n  Build headless Stacks contract-call donation options.\n- `donate(client, input, options?)`  \n  Execute donation through `walletClient.callContract`. Returns the transaction id string, or **`undefined`** if the wallet resolves with no id (e.g. `void`, `{}`, or missing `txid` / `txId`). Set **`strictTxId: true`** on the client or on `donate(..., { strictTxId: true })` to throw `FundstacksError` with code `MISSING_TX_ID` instead.\n- `defaultSbtcAssetForNetwork(network)`  \n  Returns the documented default `sbtc-token` contract id for `mainnet` / `testnet`, or `undefined` for other networks.\n- `DONATE_FUNCTIONS`  \n  Function names used by the donation builders.\n- `FundstacksError`  \n  Thrown for validation and strict tx-id failures (subclass of `Error` with a `code` string).\n\n| `code` | When |\n| --- | --- |\n| `INVALID_UINT_STRING` | `amount` or `campaignId` could not be parsed as a non-negative integer (e.g. invalid string, unsupported float). |\n| `INVALID_AMOUNT` | Parsed `amount` is zero or negative. |\n| `INVALID_CAMPAIGN_ID` | Parsed `campaignId` is less than 1. |\n| `MISSING_SBTC_ASSET` | `asset === \"sbtc\"` but no SIP-010 asset id was resolved (set `sbtcAsset` on the client or input, or use `mainnet` / `testnet` for built-in defaults). |\n| `MISSING_TX_ID` | `strictTxId` is enabled and the wallet returned no transaction id. |\n\n### sBTC asset resolution\n\nFor sBTC donations, the FT post-condition needs a SIP-010 contract id string. Resolution order: `input.sbtcAsset` → `client.sbtcAsset` → `defaultSbtcAssetForNetwork(client.network)` for `mainnet` and `testnet` only (see [Stacks sBTC / Clarinet mapping](https://docs.stacks.co/clarinet/integrations/sbtc)). Override per call when your deployment uses a different token.\n\n## Compatibility\n\n- Node.js `>=18`\n- Built output includes both ESM and CJS bundles, plus TypeScript declarations.\n\n## Development\n\n```bash\nnpm install\nnpm run lint\nnpm test\nnpm run build\n```\n\nCI runs on every push and pull request to `main` (lint, test, build) using Node.js 18.x and 20.x — see [.github/workflows/ci.yml](.github/workflows/ci.yml).\n\n## Roadmap\n\n- Add typed read helpers for campaign state\n- Add create/withdraw/refund transaction builders\n- Add typed wallet adapters for `@stacks/connect`\n\n## License\n\nMIT\n","readmeFilename":"README.md"}