{"_id":"@buildnimbus/sdk","name":"@buildnimbus/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@buildnimbus/sdk","version":"0.1.0","description":"Token-gated access for any React app. Wallet ownership → verification → access.","license":"MIT","type":"module","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"}},"sideEffects":false,"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run build"},"peerDependencies":{"react":">=18"},"devDependencies":{"@types/react":"^18.3.0","react":"^18.3.0","tsup":"^8.0.0","typescript":"^5.5.0"},"keywords":["solana","token-gating","web3","access-control","nimbus"],"repository":{"type":"git","url":"git+https://github.com/NIMBUS_ORG/nimbus-sdk.git"},"homepage":"https://github.com/NIMBUS_ORG/nimbus-sdk#readme","bugs":{"url":"https://github.com/NIMBUS_ORG/nimbus-sdk/issues"},"publishConfig":{"access":"public"},"gitHead":"1e753b56a4a409e546af6be7d137d67321b4b10a","_id":"@buildnimbus/sdk@0.1.0","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-GmX98l7t3w5Q2UMnz864rLZvB0QkoEDEzfFwGG/EoaESF41l0m9o3ofA+ExF/ysG9C9k5MlxHQP/tvPbd2PZWw==","shasum":"f5e8ac5ececa8d5248d09ef6828e727c09e9a6be","tarball":"https://registry.npmjs.org/@buildnimbus/sdk/-/sdk-0.1.0.tgz","fileCount":9,"unpackedSize":214042,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAF2ZPPNm96qRk+aJyFCNXMiiDy3UNyfbWW1+cPcoVQWAiBH/cx83YICc2iWstGCVBptPliWXSqJhBedYT3QDmbGuQ=="}]},"_npmUser":{"name":"nicksands","email":"nicksanders41@gmail.com"},"directories":{},"maintainers":[{"name":"nicksands","email":"nicksanders41@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1781574955892_0.45376672733052925"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-16T01:55:55.647Z","0.1.0":"2026-06-16T01:55:56.040Z","modified":"2026-06-16T01:55:56.280Z"},"maintainers":[{"name":"nicksands","email":"nicksanders41@gmail.com"}],"description":"Token-gated access for any React app. Wallet ownership → verification → access.","homepage":"https://github.com/NIMBUS_ORG/nimbus-sdk#readme","keywords":["solana","token-gating","web3","access-control","nimbus"],"repository":{"type":"git","url":"git+https://github.com/NIMBUS_ORG/nimbus-sdk.git"},"bugs":{"url":"https://github.com/NIMBUS_ORG/nimbus-sdk/issues"},"license":"MIT","readme":"# @buildnimbus/sdk\n\nToken-gated access for any React app.\n\n```\nWallet ownership → token verification → access → participation\n```\n\nAll verification is **server-side** via the Nimbus API. The SDK never makes\nblockchain calls and never trusts client-reported balances.\n\n---\n\n## Install\n\n**From npm (coming soon):**\n\n```bash\nnpm install @buildnimbus/sdk\n```\n\n**Local development (SDK not yet published):**\n\n```bash\nnpm install C:\\Users\\Curtis\\dev\\nimbus-sdk\n```\n\nImport from `@buildnimbus/sdk` — the same name whether you installed from npm\nor a local path.\n\nZero runtime dependencies. React >=18 peer dependency only.\n\n**Windows PowerShell:** if `npm` or `npx` fails because `.ps1` shims are\nblocked by execution policy, use `npm.cmd` and `npx.cmd` instead.\n\n---\n\n## Quickstart\n\n```tsx\nimport { NimbusProvider, NimbusGate, useNimbusAccess } from \"@buildnimbus/sdk\";\n\n// 1. Wrap your app\n\n {children}\n\n\n// 2. Gate any component\n\n \n\n\n// 3. Gate a word\nPROMO50\n\n// 4. Hook for custom UI\nconst { hasAccess, balance, tier, isLoading, error } = useNimbusAccess({ community: \"bonk\" });\n```\n\n---\n\n## Next.js App Router setup\n\n**Step 1 — Config file**\n\n```ts\n// app/nimbus.config.ts\nimport { defineConfig } from \"@buildnimbus/sdk\";\nimport type { NimbusConfig, NimbusChain, NimbusProviderProps } from \"@buildnimbus/sdk\";\n\nexport default defineConfig({\n communities: {\n myToken: { mint: \"YOUR_TOKEN_MINT_HERE\", chain: \"solana\" },\n },\n tiers: {\n basic: { community: \"myToken\", minimum: 100 },\n premium: { community: \"myToken\", minimum: 500 },\n },\n});\n```\n\n**Step 2 — Provider wrapper**\n\n```tsx\n// app/providers.tsx\n\"use client\";\nimport { NimbusProvider } from \"@buildnimbus/sdk\";\nimport nimbusConfig from \"./nimbus.config\";\n\nexport function Providers({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n```\n\n**Step 3 — Root layout**\n\n```tsx\n// app/layout.tsx\nimport { Providers } from \"./providers\";\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n {children}\n \n \n );\n}\n```\n\n**Step 4 — Gate a page**\n\n`` carries its own `\"use client\"` and can be imported directly into\na Server Component. Pages that call hooks directly must be Client Components:\n\n```tsx\n// app/picks/page.tsx — Server Component, no hooks\nimport { NimbusGate } from \"@buildnimbus/sdk\";\n\nexport default function PicksPage() {\n return (\n
\n

Free content for everyone.

\n \n

Basic tier — visible to holders of 100+.

\n \n \n

Premium — visible to holders of 500+.

\n \n
\n );\n}\n```\n\n```tsx\n// app/dashboard/page.tsx — Client Component, uses a hook directly\n\"use client\";\nimport { useNimbusAccess } from \"@buildnimbus/sdk\";\n\nexport default function Dashboard() {\n const { hasAccess, balance, tier } = useNimbusAccess({ community: \"myToken\" });\n return 
{JSON.stringify({ hasAccess, balance, tier }, null, 2)}
;\n}\n```\n\n---\n\n## Gate styles\n\nThree visual modes for the locked state. Omitting `style` defaults to `\"block\"`.\n\n```tsx\n// Block — content removed from the DOM entirely (default, most secure)\n\n \n\n\n// Fade — content faded, but present in the DOM\nPROMO50\n\n// Blur — content blurred, but present in the DOM\n\n \n\n```\n\n> **SECURITY — fade and blur are teaser UX, not protection.** Both modes render\n> the real content into the DOM for every visitor. A non-holder can read a\n> fade/blur-gated string straight out of page source. Never use fade or blur on\n> truly secret data — fetch secrets from a server route that re-verifies access\n> before returning the payload.\n\nCustom fallback for any style:\n\n```tsx\n}>\n premium content\n\n```\n\nDirect mint check (no config needed):\n\n```tsx\n\n

Holder-only content

\n\n```\n\n---\n\n## Tiers\n\n`useNimbusTier` returns the single highest tier the wallet satisfies, or\n`\"none\"`. Because it returns immediately on first render, show a loading state\nto avoid flashing the fallback branch at a valid holder:\n\n```tsx\nimport { NimbusTier, useNimbusTier } from \"@buildnimbus/sdk\";\n\n// Hook — useful for conditional logic\nconst tier = useNimbusTier({ community: \"bonk\" });\n// Returns: \"whale\" | \"holder\" | \"none\"\n// Note: returns \"none\" on the initial render before the API responds.\n// Use isLoading from useNimbusAccess if you need to distinguish loading from no-access.\n\n// Component — renders exactly one branch\n\n Whale content\n Holder content\n Not a holder yet — join to unlock.\n\n```\n\nResolution selects the **highest** satisfied tier — a wallet with 1,000,000\nbalance satisfies both `holder` and `whale` and renders the `whale` branch.\n\n> `.Match` and `.None` must be **direct children** of `` — they\n> read access state from the parent context and will throw if used outside it.\n> Do not wrap them in intermediate elements. Exactly one branch renders at a\n> time; all others return null.\n\n---\n\n## Wallets\n\nThe SDK bundles no wallet library. Three paths:\n\n**Path 1 — Your app already manages wallets** (wagmi, Solana Wallet Adapter,\nPrivy) — pass the address down:\n\n```tsx\n// wagmi\nconst { address } = useAccount();\n\n\n// Solana Wallet Adapter\nconst { publicKey } = useWallet();\n\n\n// Privy\nconst { user } = usePrivy();\n\n```\n\n**Path 2 — No wallet setup** — the SDK detects injected providers\n(`window.solana`, `window.ethereum`) automatically.\n\n**Path 3 — Local testing with a dev wallet override:**\n\n```tsx\n// Use an env var, never a hardcoded address. Remove before shipping to production.\nconst devWallet =\n process.env.NODE_ENV === \"development\"\n ? (process.env.NEXT_PUBLIC_NIMBUS_TEST_WALLET ?? null)\n : null;\n\n// Spread the wallet prop — never pass wallet={{ address: null }}.\n// Passing a null address is treated as an active override and permanently\n// locks everyone out. Omit the prop entirely when no override exists.\n\n```\n\nAdd `NEXT_PUBLIC_NIMBUS_TEST_WALLET=YOUR_HOLDER_WALLET` to `.env.local`.\n\nThis pattern only applies under `next dev`. Running `next build` + `next start`\ndisables the override intentionally — production requires a real connected\nwallet.\n\n`useNimbusWallet()` exposes the current wallet state:\n\n```tsx\nimport { useNimbusWallet } from \"@buildnimbus/sdk\";\n\nconst { address, connected, chain } = useNimbusWallet();\n// address: string | null — base58 / hex address, or null when disconnected\n// connected: boolean — note: `connected`, NOT `isConnected`\n// chain: NimbusChain | null — active chain, or null when disconnected\n//\n// This is the complete return interface.\n// Import WalletState for the full type: import type { WalletState } from \"@buildnimbus/sdk\";\n```\n\nWhen a wallet is connected or a `wallet` override is active, `NimbusButton`\ndisplays the truncated active address instead of the connect label.\n\nThe SDK currently verifies against mainnet only. Use the dev wallet override\npattern for local testing. Devnet and testnet support is on the roadmap.\n\n---\n\n## Wall and Button\n\n`` is a ready-made locked-state card. It takes **no children** —\nit self-renders its message and a truncated wallet address. In the disconnected\nstate it also shows a \"No wallet detected\" banner. Use it as a gate fallback:\n\n```tsx\n}>\n \n\n```\n\n`` renders a connect button and manages the wallet popup. It\ntakes **no children**. When connected or overridden, it shows the truncated\nactive address:\n\n```tsx\n\n```\n\nBoth accept a standard React `style` object for CSS theming. See Troubleshooting\nfor why `style` on these components is CSS, not a gate style.\n\n---\n\n## Config\n\n`defineConfig` provides autocomplete and compile-time shape validation. Change a\nthreshold in the config file and every `` on the site\nupdates automatically.\n\n```ts\n// nimbus.config.ts\nimport { defineConfig } from \"@buildnimbus/sdk\";\n\nexport default defineConfig({\n communities: {\n bonk: { mint: \"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263\", chain: \"solana\" },\n },\n tiers: {\n whale: { community: \"bonk\", minimum: 1000000 },\n holder: { community: \"bonk\", minimum: 1 },\n },\n});\n```\n\n```tsx\nimport nimbusConfig from \"../nimbus.config\";\n\n\n```\n\n**Multiple providers** — you can mount more than one `NimbusProvider` (nested\nor side-by-side). Each scopes its own context and config. The verification cache\nis keyed by wallet + mint + minimum, so identical checks across providers\ndedupe.\n\n**Inline config** — when passing a config object literal directly (not via\n`defineConfig`), narrow `chain` so TypeScript accepts it:\n\n```tsx\nconst inlineConfig = {\n communities: {\n alpha: { mint: \"...\", chain: \"solana\" as const },\n },\n tiers: { /* ... */ },\n};\n\n\n```\n\nWithout `as const`, `chain: \"solana\"` widens to `string` and fails with\n`Type 'string' is not assignable to type 'NimbusChain | undefined'`. The\nalternative is to always use `defineConfig`, which infers the type correctly.\n\n---\n\n## Behavior notes\n\n- **Fails closed.** Loading, errors, disconnected wallets, and misconfigured\n gates render the locked state — never the content.\n- **Cached.** Results cache for 30s client-side; concurrent identical checks\n share one request.\n- **`clearCache()`** (named export, synchronous, returns `void`) evicts the\n client cache. It does **not** re-run gates or hooks that are already mounted.\n The next fresh access check (a new mount or a new query) will miss the cache\n and re-verify. To force on-screen gates to re-verify immediately, remount the\n subtree by bumping a React `key` after calling `clearCache()`.\n\n To display measured re-verify latency, place the hook inside the keyed subtree\n and time the `isLoading` true→false transition:\n\n ```tsx\n import { useEffect, useRef, useState } from \"react\";\n import { clearCache, useNimbusAccess } from \"@buildnimbus/sdk\";\n\n function AccessProbe({ onSettled }: { onSettled: (ms: number) => void }) {\n const { isLoading } = useNimbusAccess({ community: \"myToken\" });\n const start = useRef(performance.now());\n\n useEffect(() => {\n if (!isLoading) onSettled(Math.round(performance.now() - start.current));\n }, [isLoading, onSettled]);\n\n return null;\n }\n\n export function CacheControls() {\n const [nonce, setNonce] = useState(0);\n const [elapsed, setElapsed] = useState(null);\n\n function refresh() {\n clearCache();\n setNonce((n) => n + 1); // remounts AccessProbe → fresh verify\n }\n\n return (\n
\n \n {elapsed !== null &&

Re-verified in {elapsed}ms

}\n
\n \n {/* gate content here */}\n
\n
\n );\n }\n ```\n\n Typical cache-miss latency is ~150–200ms.\n\n- **Client-side gating hides UI, it does not protect data.** Anything truly\n secret must be fetched from a server route that re-verifies access before\n returning the payload.\n\n**Under the hood**, each gate or hook issues:\n\n```\nGET {apiUrl}/api/check-access\n ?wallet={address}&mint={mint}&minimum={n}\n &network=mainnet&gate_type=token&gate_mode=token_amount\n-> 200 { \"hasAccess\": boolean, \"balance\": number }\n```\n\nWith only a `community` query (no `tier`/`minimum`), the SDK uses `minimum=1`.\n`balance` and `hasAccess` come from the API; `tier` is derived client-side from\nyour config thresholds (the highest tier the balance satisfies, or `\"none\"`).\n\n---\n\n## Common mistakes\n\n```tsx\n// Bad: checking balances in the browser yourself.\nif (walletBalance >= 100) { showContent(); }\n// Good: let the SDK verify server-side.\n\n\n// Bad: gating truly secret data by hiding components alone.\n{ hasAccess && }\n// Good: fetch secrets from a server route that re-verifies.\n\n// Bad: hardcoding a wallet override in production.\nwallet={{ address: \"6J8eyph...\" }}\n// Good: use the env var pattern — dev only.\n\n// Bad: passing wallet={{ address: null }}.\n// This treats null as an active override and locks everyone out.\n// Good: omit the wallet prop entirely when no override exists.\n{...(devWallet ? { wallet: { address: devWallet } } : {})}\n```\n\n---\n\n## Types\n\nAll primary TypeScript types are exported from `@buildnimbus/sdk`:\n\n```tsx\nimport type {\n NimbusConfig, // full config shape for defineConfig / NimbusProvider\n NimbusChain, // \"solana\" | \"base\" | \"ethereum\" | \"polygon\"\n NimbusProviderProps, // props for NimbusProvider\n NimbusGateProps, // props for NimbusGate\n NimbusWallProps, // props for NimbusWall\n NimbusButtonProps, // props for NimbusButton\n NimbusTierProps, // props for NimbusTier\n TierMatchProps, // props for NimbusTier.Match\n WalletState, // return shape of useNimbusWallet\n AccessQuery, // params accepted by useNimbusAccess\n AccessResult, // { hasAccess, balance } from the API\n AccessState, // full return shape of useNimbusAccess\n CommunityConfig, // shape of a single community in defineConfig\n TierConfig, // shape of a single tier in defineConfig\n} from \"@buildnimbus/sdk\";\n```\n\n`detectChain` and `EVM_CHAIN_IDS` are also exported as runtime values.\n\n`EVM_CHAIN_IDS` maps chain names to their network IDs:\n\n```ts\n{ ethereum: 1, base: 8453, polygon: 137 }\n```\n\n---\n\n## Phase status\n\n- [x] Phase 1 — `NimbusProvider`, `useNimbusWallet`, `useNimbusAccess`, ``\n- [x] Phase 2 — `useNimbusTier`, `` (+ `.Match` / `.None`), ``, ``\n- [x] Phase 3 — fade/blur gate styles (content in DOM by design — teaser UX, not protection)\n- [x] Phase 4 — config system (`defineConfig` + import pattern)\n- [ ] Phase 5 — Pantheon swap\n- [x] Phase 6 — publish-ready (LICENSE, metadata, prepublish pipeline; awaiting `npm publish`)\n\n---\n\n## Troubleshooting\n\n**\"useContext/useState only works in Client Components\" in Next.js App Router**\n— fixed in 0.1.0 via build banner. All SDK components carry `\"use client\"` in\nthe bundle, so importing `` directly into a Server Component works.\nPages that call hooks directly must add `\"use client\"` at the top. If you see\nthis error on an older build, rebuild the package.\n\n**Gate always locked / `hasAccess` always false** — check in order: (1) is\n`` wrapping the tree? A missing provider throws; a\nwrong `apiUrl` fails closed. (2) Is a wallet connected or passed via the\n`wallet` prop? No wallet = locked by design. (3) Open the Network tab — a CORS\nerror means the API host hasn't allowed your origin.\n\n**Import errors after updating a locally-linked package** — restart your dev\nserver and your editor's TypeScript server. Local-path installs are symlinks;\nboth tools cache aggressively.\n\n**`Type '\"blur\"' has no properties in common with type 'Properties...'` when\nstyling NimbusWall or NimbusButton** — the `style` prop means two different\nthings in this SDK: on `` it selects the gate style\n(`\"block\" | \"fade\" | \"blur\"`); on `` and `` it is\nthe standard React CSS style object for theming. Gate styles only exist on\n`NimbusGate`.\n\n**`Type '\"\"' is not assignable to type 'NimbusChain'`** — editor autocomplete\ntends to insert `chain=\"\"`. An empty string is not a chain; pass a real value\n(`\"solana\"`, `\"base\"`, `\"ethereum\"`, `\"polygon\"`) or omit the prop and let\ndetection/config decide.\n\n**Gates permanently locked in production after testing** — you likely left\n`wallet={{ address: devWallet }}` in your provider with `devWallet` evaluating\nto `null`. Passing any `wallet` prop (even null) disables injected-wallet\ndetection. Use the spread pattern so the prop is omitted entirely when null:\n`{...(devWallet ? { wallet: { address: devWallet } } : {})}`.\n\n---\n\n## Build\n\n```bash\nnpm install\nnpm run build # tsup -> dist/ (ESM + CJS + types)\nnpm run typecheck\n```\n\n**Consumer apps:** `create-next-app` does not add a typecheck script. Add this\nto your app's `package.json` scripts:\n\n```json\n\"typecheck\": \"tsc --noEmit\"\n```","readmeFilename":"README.md","_rev":"1-7b878f2dd670a867f7392c183a98045c"}