{"_id":"@carbonads/sdk","_rev":"6-864cbf431c2c96633ee5bf87c03aecdc","name":"@carbonads/sdk","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"@carbonads/sdk","version":"0.1.0","keywords":["carbon-ads","ads","cli","terminal","ink","sdk"],"author":{"name":"BuySellAds"},"license":"MIT","_id":"@carbonads/sdk@0.1.0","maintainers":[{"name":"sayzlim","email":"sayz@buysellads.com"}],"homepage":"https://github.com/buysellads/carbon-sdk#readme","bugs":{"url":"https://github.com/buysellads/carbon-sdk/issues"},"dist":{"shasum":"db70d647f904645cee4e4e8b67fd6235a6818ccb","tarball":"https://registry.npmjs.org/@carbonads/sdk/-/sdk-0.1.0.tgz","fileCount":12,"integrity":"sha512-6436VRKN2CmQRTuobef6sE/z6Ae3H9Na4sPY+Vk1zhmkCSAaI74gQiG029KtLUqsifej3FEnl7gQ3JeAU7oeBQ==","signatures":[{"sig":"MEYCIQDgTwKptUQ78WrzoifbFUGd4rnElwm2KO5CxNfL9rDREwIhALkKwm3wUHOovAjd/fIduQPrc5z07rgYzHzfjVenXJLI","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28322},"type":"module","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./ink":{"types":"./dist/ink/index.d.ts","import":"./dist/ink/index.js"}},"gitHead":"59708af95ebcc3acfd0da4004b9c95cef1af228e","scripts":{"dev":"tsup --watch","build":"tsup","test:ink":"node --import tsx test/ink.tsx","test:fetch":"node test/fetch.js"},"_npmUser":{"name":"sayzlim","email":"sayz@buysellads.com"},"repository":{"url":"git+https://github.com/buysellads/carbon-sdk.git","type":"git"},"_npmVersion":"11.11.0","description":"Carbon Ads SDK — ad components for terminal and web apps","directories":{},"_nodeVersion":"24.14.1","_hasShrinkwrap":false,"devDependencies":{"ink":"^6.8.0","tsx":"^4.19.0","tsup":"^8.4.0","react":"^19.1.0","typescript":"^5.7.0","@types/node":"^22.0.0","@types/react":"^19.0.0"},"peerDependencies":{"ink":">=6.0.0","react":">=19.0.0"},"peerDependenciesMeta":{"ink":{"optional":true},"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1775020278597_0.2483228431550455","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@carbonads/sdk","version":"0.1.1","keywords":["carbon-ads","ads","cli","terminal","ink","sdk"],"author":{"name":"BuySellAds"},"license":"MIT","_id":"@carbonads/sdk@0.1.1","maintainers":[{"name":"sayzlim","email":"sayz@buysellads.com"}],"homepage":"https://github.com/buysellads/carbon-sdk#readme","bugs":{"url":"https://github.com/buysellads/carbon-sdk/issues"},"dist":{"shasum":"8481bafc61c8f3e03f5abbb5699d2a2cd0482948","tarball":"https://registry.npmjs.org/@carbonads/sdk/-/sdk-0.1.1.tgz","fileCount":12,"integrity":"sha512-Nn4xdHDyI2q6MwbeW1Uip6CLF6p4pf+ABYtpuPTCPfg+JpoDjzkEHatGOuWScDuhGDjeiiUps+eBlBSaLEMRyQ==","signatures":[{"sig":"MEQCIFjr1/zamcpHVrX7n/+fxfNcB8YlJ7Yvobw0x25ce6XPAiBnYkV0I/AbME/1xw20egmW4pHKM9KJYXTRF/k32YnvDA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30369},"type":"module","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./ink":{"types":"./dist/ink/index.d.ts","import":"./dist/ink/index.js"}},"gitHead":"96cabacfe4e8d6d8c3f4c6b5d74fe06359a5584f","scripts":{"dev":"tsup --watch","lint":"eslint .","build":"tsup","format":"prettier --write .","test:ink":"node --import tsx test/ink.tsx","test:fetch":"node test/fetch.js","format:check":"prettier --check ."},"_npmUser":{"name":"sayzlim","email":"sayz@buysellads.com"},"repository":{"url":"git+https://github.com/buysellads/carbon-sdk.git","type":"git"},"_npmVersion":"11.11.0","description":"Carbon Ads SDK — ad components for terminal and web apps","directories":{},"_nodeVersion":"24.14.1","_hasShrinkwrap":false,"devDependencies":{"ink":"^6.8.0","tsx":"^4.19.0","tsup":"^8.4.0","react":"^19.1.0","eslint":"^9.39.4","prettier":"^3.8.1","@eslint/js":"^9.39.4","typescript":"^5.7.0","@types/node":"^22.0.0","@types/react":"^19.0.0","typescript-eslint":"^8.58.0","eslint-config-prettier":"^10.1.8","eslint-plugin-react-hooks":"^7.0.1"},"peerDependencies":{"ink":">=6.0.0","react":">=19.0.0"},"peerDependenciesMeta":{"ink":{"optional":true},"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.1_1775022772277_0.21785096618166366","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@carbonads/sdk","version":"0.2.0","keywords":["carbon-ads","ads","cli","terminal","ink","sdk"],"author":{"name":"BuySellAds"},"license":"MIT","_id":"@carbonads/sdk@0.2.0","maintainers":[{"name":"sayzlim","email":"sayz@buysellads.com"}],"homepage":"https://github.com/buysellads/carbon-sdk#readme","bugs":{"url":"https://github.com/buysellads/carbon-sdk/issues"},"dist":{"shasum":"b1fc82a23f677d88c4a2d95cef09e3a3096124a5","tarball":"https://registry.npmjs.org/@carbonads/sdk/-/sdk-0.2.0.tgz","fileCount":12,"integrity":"sha512-Np5WL+sy7TwIb3RrwqJGiiu6L6b5ZdENkJWMyxGnGuCYkc9xIeZb4J3Fho7I3BjnfhAUe9WUvm8bGBMU9Bmg4A==","signatures":[{"sig":"MEQCIFIE1Y+g5dhjgm/YKHbOaQTMyeQgbKpE9RR1IJNFpBPZAiB/touq+sV+8QBGxxrZIY91PG65+gpNbACi0FryEfFg8w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49029},"type":"module","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./ink":{"types":"./dist/ink/index.d.ts","import":"./dist/ink/index.js"}},"gitHead":"63be87c17037e73f6fd11d4c0af53b9000a48deb","scripts":{"dev":"tsup --watch","lint":"eslint .","build":"tsup","format":"prettier --write .","test:ink":"node --import tsx test/ink.tsx","test:fetch":"node test/fetch.js","format:check":"prettier --check .","prepublishOnly":"tsup","test:ink:no-ads":"node --import tsx test/ink.tsx --no-ads","test:ink:house-ads":"node --import tsx test/ink.tsx --house-ads"},"_npmUser":{"name":"sayzlim","email":"sayz@buysellads.com"},"repository":{"url":"git+https://github.com/buysellads/carbon-sdk.git","type":"git"},"_npmVersion":"11.11.0","description":"Carbon Ads SDK — ad components for terminal and web apps","directories":{},"_nodeVersion":"24.14.1","_hasShrinkwrap":false,"devDependencies":{"ink":"^6.8.0","tsx":"^4.19.0","tsup":"^8.4.0","react":"^19.1.0","eslint":"^9.39.4","prettier":"^3.8.1","@eslint/js":"^9.39.4","typescript":"^5.7.0","@types/node":"^22.0.0","@types/react":"^19.0.0","ink-text-input":"^6.0.0","typescript-eslint":"^8.58.0","eslint-config-prettier":"^10.1.8","eslint-plugin-react-hooks":"^7.0.1"},"peerDependencies":{"ink":">=6.0.0","react":">=19.0.0"},"peerDependenciesMeta":{"ink":{"optional":true},"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1775108771998_0.9616095377108969","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@carbonads/sdk","version":"0.2.1","keywords":["carbon-ads","ads","cli","terminal","ink","sdk"],"author":{"name":"BuySellAds"},"license":"MIT","_id":"@carbonads/sdk@0.2.1","maintainers":[{"name":"todd.garland","email":"todd.garland@gmail.com"},{"name":"sayzlim","email":"sayz@buysellads.com"}],"homepage":"https://github.com/buysellads/carbon-sdk#readme","bugs":{"url":"https://github.com/buysellads/carbon-sdk/issues"},"dist":{"shasum":"ace2b3eff65da7290df84f710346cc2d5824fe78","tarball":"https://registry.npmjs.org/@carbonads/sdk/-/sdk-0.2.1.tgz","fileCount":12,"integrity":"sha512-J1+PmVHKCPNfPcvFIaFSXRuCiz31h99nSZU4SpwK4O9Dode12VDyS4WD01bqBpX7gOITSry2gQMHAfeqz5c5Mw==","signatures":[{"sig":"MEUCIQDKEW7FYKWTUUi44dyKDj3DfOzHUUb2zB47jnnhvR91WQIgPZJ9acDiX9zfjQ1w8P9TzquWqavJpVcyudiYaDYrsis=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":52215},"type":"module","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./ink":{"types":"./dist/ink/index.d.ts","import":"./dist/ink/index.js"}},"gitHead":"3e0d11a781e897a86cdfb4600449a3fc8fc2809e","scripts":{"dev":"tsup --watch","lint":"eslint .","build":"tsup","format":"prettier --write .","test:ink":"node --import tsx test/ink.tsx","test:fetch":"node test/fetch.js","format:check":"prettier --check .","prepublishOnly":"tsup","test:ink:no-ads":"node --import tsx test/ink.tsx --no-ads","test:ink:house-ads":"node --import tsx test/ink.tsx --house-ads"},"_npmUser":{"name":"sayzlim","email":"sayz@buysellads.com"},"repository":{"url":"git+https://github.com/buysellads/carbon-sdk.git","type":"git"},"_npmVersion":"11.11.0","description":"Carbon Ads SDK — ad components for terminal and web apps","directories":{},"_nodeVersion":"24.14.1","_hasShrinkwrap":false,"devDependencies":{"ink":"^6.8.0","tsx":"^4.19.0","tsup":"^8.4.0","react":"^19.1.0","eslint":"^9.39.4","prettier":"^3.8.1","@eslint/js":"^9.39.4","typescript":"^5.7.0","@types/node":"^22.0.0","@types/react":"^19.0.0","ink-text-input":"^6.0.0","typescript-eslint":"^8.58.0","eslint-config-prettier":"^10.1.8","eslint-plugin-react-hooks":"^7.0.1"},"peerDependencies":{"ink":">=6.0.0","react":">=19.0.0"},"peerDependenciesMeta":{"ink":{"optional":true},"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.1_1776046869199_0.6669153168630388","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@carbonads/sdk","version":"0.2.2","description":"Carbon Ads SDK — ad components for terminal and web apps","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./ink":{"types":"./dist/ink/index.d.ts","import":"./dist/ink/index.js"}},"peerDependencies":{"ink":">=6.0.0","react":">=19.0.0"},"peerDependenciesMeta":{"ink":{"optional":true},"react":{"optional":true}},"devDependencies":{"@eslint/js":"^9.39.4","@types/node":"^22.0.0","@types/react":"^19.0.0","eslint":"^9.39.4","eslint-config-prettier":"^10.1.8","eslint-plugin-react-hooks":"^7.0.1","ink":"^6.8.0","ink-text-input":"^6.0.0","prettier":"^3.8.1","react":"^19.1.0","tsup":"^8.4.0","tsx":"^4.19.0","typescript":"^5.7.0","typescript-eslint":"^8.58.0"},"engines":{"node":">=18.0.0"},"author":{"name":"BuySellAds"},"license":"MIT","homepage":"https://github.com/buysellads/carbon-sdk#readme","repository":{"type":"git","url":"git+https://github.com/buysellads/carbon-sdk.git"},"bugs":{"url":"https://github.com/buysellads/carbon-sdk/issues"},"keywords":["carbon-ads","ads","cli","terminal","ink","sdk"],"scripts":{"build":"tsup","dev":"tsup --watch","lint":"eslint .","format":"prettier --write .","format:check":"prettier --check .","test:fetch":"node test/fetch.js","test:ink":"node --import tsx test/ink.tsx","test:ink:house-ads":"node --import tsx test/ink.tsx --house-ads","test:ink:no-ads":"node --import tsx test/ink.tsx --no-ads"},"_id":"@carbonads/sdk@0.2.2","_integrity":"sha512-+8tD1Ft5ewo5vKNMXYWmdQwhSnmuF+DEbu+qQ9x5bYJ/e4JKMCzZ823vdIoT1MMHPRF6XfRALlsY3dn6IJEanQ==","_resolved":"/private/var/folders/8r/1y40cb4x1c51hqpnw03yqk640000gn/T/99b2be2943e84db18ca79e23ceeea169/carbonads-sdk-0.2.2.tgz","_from":"file:carbonads-sdk-0.2.2.tgz","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-+8tD1Ft5ewo5vKNMXYWmdQwhSnmuF+DEbu+qQ9x5bYJ/e4JKMCzZ823vdIoT1MMHPRF6XfRALlsY3dn6IJEanQ==","shasum":"326dc5c1280bdc43a1a9928475d0a08112808b0e","tarball":"https://registry.npmjs.org/@carbonads/sdk/-/sdk-0.2.2.tgz","fileCount":12,"unpackedSize":51826,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCBOUUfDxUxATfMGxS7mgM8VAp1/1TcZ7wOK/RqUC/GpQIgYX3M3/2CZiSOfOKZxqvyHKt+1VWQkrrc7/jLLAmZfCY="}]},"_npmUser":{"name":"sayzlim","email":"sayz@buysellads.com"},"directories":{},"maintainers":[{"name":"todd.garland","email":"todd.garland@gmail.com"},{"name":"sayzlim","email":"sayz@buysellads.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.2.2_1776239230248_0.5944279444338672"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-01T05:11:18.401Z","modified":"2026-04-15T07:47:10.540Z","0.1.0":"2026-04-01T05:11:18.741Z","0.1.1":"2026-04-01T05:52:52.425Z","0.2.0":"2026-04-02T05:46:12.143Z","0.2.1":"2026-04-13T02:21:09.365Z","0.2.2":"2026-04-15T07:47:10.405Z"},"bugs":{"url":"https://github.com/buysellads/carbon-sdk/issues"},"author":{"name":"BuySellAds"},"license":"MIT","homepage":"https://github.com/buysellads/carbon-sdk#readme","keywords":["carbon-ads","ads","cli","terminal","ink","sdk"],"repository":{"type":"git","url":"git+https://github.com/buysellads/carbon-sdk.git"},"description":"Carbon Ads SDK — ad components for terminal and web apps","maintainers":[{"name":"todd.garland","email":"todd.garland@gmail.com"},{"name":"sayzlim","email":"sayz@buysellads.com"}],"readme":"# @carbonads/sdk\n\nCarbon Ads SDK for terminal and web apps. Reach developers where they work.\n\n## Quick Start\n\n```bash\nnpm install @carbonads/sdk ink react\n```\n\n```tsx\nimport { render } from \"ink\";\nimport { CarbonAd } from \"@carbonads/sdk/ink\";\n\nrender(<CarbonAd interactionId=\"main\" />);\n```\n\nRun it — a demo ad renders in your terminal immediately.\n\n## Get Your Zone Key\n\nThe demo key is for testing only. To serve real ads and earn revenue:\n\n1. Apply at **https://www.carbonads.net/join**\n2. Receive your zone key\n3. Pass it to the component:\n\n```tsx\n<CarbonAd serve=\"YOUR_ZONE_KEY\" placement=\"your-app\" interactionId=\"main\" />\n```\n\n## Usage\n\n### Ink Component (terminal apps)\n\nUse `<CarbonAd />` inside any Ink application. Every ad needs an `interactionId` — it tells the SDK when to fetch a new ad.\n\nFor single-run tools, use a static value:\n\n```tsx\nimport React from \"react\";\nimport { render, Box } from \"ink\";\nimport { CarbonAd } from \"@carbonads/sdk/ink\";\n\nfunction App() {\n  return (\n    <Box flexDirection=\"column\">\n      {/* your app content */}\n      <CarbonAd\n        serve=\"YOUR_ZONE_KEY\"\n        placement=\"your-app\"\n        interactionId=\"main\"\n      />\n    </Box>\n  );\n}\n\nrender(<App />);\n```\n\nFor interactive apps (chat UIs, REPLs, multi-step wizards), pass a value that changes at natural breakpoints — a new conversation, command, or session. The SDK enforces a 30-second minimum display window, so rapid changes keep the current ad.\n\n```tsx\n<CarbonAd serve=\"YOUR_ZONE_KEY\" interactionId={conversationId} />\n```\n\n### Fallback Ads\n\nProvide a `fallback` to show your own house ad while loading and when no paid ad is available. A skeleton placeholder matching the fallback's shape is shown during the fetch.\n\n```tsx\n<CarbonAd\n  serve=\"YOUR_ZONE_KEY\"\n  interactionId={conversationId}\n  fallback={{\n    company: \"Acme CLI\",\n    description: \"Build faster with our developer toolkit for the terminal.\",\n    companyTagline: \"Dev tools for the terminal\",\n    callToAction: \"Learn More\",\n    link: \"https://acme.dev\",\n  }}\n/>\n```\n\n### Standalone (no Ink app needed)\n\nRender an ad to the terminal as a one-liner:\n\n```ts\nimport { renderCarbonAd } from \"@carbonads/sdk/ink\";\n\nawait renderCarbonAd({ serve: \"YOUR_ZONE_KEY\", placement: \"your-app\" });\n```\n\n### Core API (custom integrations)\n\nFetch ad data directly for custom rendering:\n\n```ts\nimport { fetchAd } from \"@carbonads/sdk\";\n\nconst ad = await fetchAd({\n  serve: \"YOUR_ZONE_KEY\",\n  placement: \"your-app\",\n});\n\nif (ad) {\n  console.log(ad.company, ad.description, ad.callToAction);\n}\n```\n\n### Styling the Box\n\nCustomize the ad container's width and border color with the `style` prop:\n\n```tsx\n<CarbonAd\n  serve=\"YOUR_ZONE_KEY\"\n  interactionId=\"main\"\n  style={{ width: 60, borderColor: \"gray\" }}\n/>\n```\n\nThis also works with the standalone helper:\n\n```ts\nawait renderCarbonAd({\n  serve: \"YOUR_ZONE_KEY\",\n  style: { width: 60, borderColor: \"cyan\" },\n});\n```\n\n## Props\n\n| Prop            | Type               | Default      | Description                                                          |\n| --------------- | ------------------ | ------------ | -------------------------------------------------------------------- |\n| `serve`         | `string`           | Demo key     | Your zone key from Carbon Ads                                        |\n| `placement`     | `string`           | `\"demo\"`     | Placement identifier                                                 |\n| `interactionId` | `string \\| number` | **required** | When this changes, a new ad may be fetched if enough time has passed |\n| `fallback`      | `CarbonAdFallback` | —            | House ad shown during loading and when no paid ad is available       |\n| `style`         | `CarbonBoxStyle`   | —            | Style overrides for the box container (see below)                    |\n\n### `CarbonBoxStyle`\n\n| Key           | Type     | Default    | Description                               |\n| ------------- | -------- | ---------- | ----------------------------------------- |\n| `width`       | `number` | `78`       | Fixed column count for the ad box         |\n| `borderColor` | `string` | Dim (gray) | Border color (any Ink/chalk color string) |\n\n#### Why a fixed-width default?\n\nThe box defaults to **78 columns** rather than stretching to fill its parent. This is deliberate: a full-bleed box reflows into more visual rows when the terminal is resized narrower, which exposes an upstream Ink rendering bug that leaves stale fragments on screen (see [Known Limitations](#known-limitations) below). A fixed width that fits any modern terminal (≥80 cols is effectively universal) sidesteps the problem for the common case — the box simply doesn't reflow when the user resizes the window.\n\nIf you need a different size — for instance, to match a constrained parent container, or because your users are on narrower terminals — pass your own `width`:\n\n```tsx\n<CarbonAd serve=\"YOUR_ZONE_KEY\" interactionId=\"main\" style={{ width: 60 }} />\n```\n\n## Known Limitations\n\n### Ghost fragments when shrinking the terminal\n\nDragging the terminal window **narrower than the box width** while an ad is on screen can leave stale line fragments above the ad. Growing the terminal is unaffected, and the next render cycle clears the fragments.\n\nThis is an upstream Ink issue, not specific to this SDK — any Ink-rendered content is affected the same way. The root cause is that terminals which soft-wrap on resize (iTerm2, kitty, Windows Terminal) end up displaying more visual rows than Ink tracked when it emitted the frame, so Ink's erase pass under-clears. Terminals that don't reflow on resize (xterm and similar) are not affected.\n\nThe [default fixed width](#why-a-fixed-width-default) (78 cols) is the primary mitigation — as long as the terminal stays wider than the box, no reflow can happen. You'll only see the artifact if the terminal is dragged narrower than the configured `style.width`.\n\nThe Ink maintainers [explicitly declined](https://github.com/vadimdemedes/ink/pull/916) to patch this because no reliable way exists to detect whether the host terminal reflows, so any fix regresses the other camp. Tracked in [vadimdemedes/ink#907](https://github.com/vadimdemedes/ink/issues/907) and documented in [vadimdemedes/ink#920](https://github.com/vadimdemedes/ink/pull/920).\n\n## Requirements\n\n- Node.js >= 18\n- `ink` >= 6.0.0\n- `react` >= 19.0.0\n\n## Development\n\nThis project uses [pnpm](https://pnpm.io/) as its package manager.\n\n```bash\npnpm install     # install dependencies\npnpm build       # build to dist/\npnpm dev         # build in watch mode\npnpm lint        # run ESLint\npnpm format      # format with Prettier\n```\n\n### Testing\n\n```bash\npnpm test:fetch  # test core API (requires build)\npnpm test:ink    # test Ink component (requires build)\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}