{"_id":"@clipin/convex-credits","_rev":"2-4375cbe8a35f93f2da75c2d706674f04","name":"@clipin/convex-credits","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@clipin/convex-credits","version":"1.0.0","keywords":["convex","convex-component","credits","ledger","billing","ai","reservations"],"author":{"name":"Denis Ciccale"},"license":"Apache-2.0","_id":"@clipin/convex-credits@1.0.0","maintainers":[{"name":"denis","email":"dciccale@gmail.com"}],"homepage":"https://convex-credits.vercel.app","bugs":{"url":"https://github.com/clipinfit/convex-credits/issues"},"dist":{"shasum":"a1085d85a809dd00e1a0ce1289ce827c3f25ccdd","tarball":"https://registry.npmjs.org/@clipin/convex-credits/-/convex-credits-1.0.0.tgz","fileCount":50,"integrity":"sha512-RHmSgGI6rgjZOxuC2nm1TFSUujXEHTZWyH57S7ZSdk9QNhlRJ8Ny8uI+0ioBgfCCDFnABmu3L6TNAPnBE/I/cQ==","signatures":[{"sig":"MEYCIQD/KxG8+DePxQ5fP+1fkzp2VTsOq9c8k0yTooSmaZ0COgIhAO6Loyb7CCQLBHG2QIl9xk6h03pqaihLvw/9g8Bjc325","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":197694},"main":"./dist/client/index.js","type":"module","types":"./dist/client/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/client/index.d.ts","default":"./dist/client/index.js"},"./test":"./src/test.ts","./package.json":"./package.json","./convex.config":{"types":"./dist/component/convex.config.d.ts","default":"./dist/component/convex.config.js"},"./convex.config.js":{"types":"./dist/component/convex.config.d.ts","default":"./dist/component/convex.config.js"},"./_generated/component.js":{"types":"./dist/component/_generated/component.d.ts"}},"gitHead":"3b7a838681442d7111e3d5529a3c30d1f3ce9995","scripts":{"dev":"tsc -p tsconfig.build.json --watch","lint":"biome check src scripts","test":"vitest run","build":"tsc -p tsconfig.build.json","format":"biome format --write src scripts","prepack":"npm run build","typecheck":"tsc --noEmit","pack:check":"node scripts/check-package.mjs && node scripts/check-install.mjs"},"_npmUser":{"name":"denis","email":"dciccale@gmail.com"},"repository":{"url":"git+https://github.com/clipinfit/convex-credits.git","type":"git","directory":"packages/convex-credits"},"_npmVersion":"11.19.0","description":"Transactional credits for Convex background jobs: reserve, complete, release, refund, and reconcile.","directories":{},"_nodeVersion":"26.7.0","dependencies":{"convex-helpers":"0.1.120"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"8.2.1","convex":"1.42.1","vitest":"4.1.10","typescript":"5.9.3","@types/node":"^22.0.0","convex-test":"0.0.54","@biomejs/biome":"2.5.1","@edge-runtime/vm":"5.0.0"},"peerDependencies":{"convex":">=1.42.1 <2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/convex-credits_1.0.0_1788876490853_0.3187067118083158","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@clipin/convex-credits","version":"1.0.1","description":"Transactional credits for Convex background jobs: reserve, complete, release, refund, and reconcile.","license":"Apache-2.0","homepage":"https://convex-credits.vercel.app","bugs":{"url":"https://github.com/clipinfit/convex-credits/issues"},"type":"module","main":"./dist/client/index.js","types":"./dist/client/index.d.ts","exports":{"./package.json":"./package.json",".":{"types":"./dist/client/index.d.ts","default":"./dist/client/index.js"},"./test":"./src/test.ts","./_generated/component.js":{"types":"./dist/component/_generated/component.d.ts"},"./convex.config":{"types":"./dist/component/convex.config.d.ts","default":"./dist/component/convex.config.js"},"./convex.config.js":{"types":"./dist/component/convex.config.d.ts","default":"./dist/component/convex.config.js"}},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.build.json","dev":"tsc -p tsconfig.build.json --watch","typecheck":"tsc --noEmit","test":"vitest run","lint":"biome check src scripts","format":"biome format --write src scripts","prepack":"npm run build","pack:check":"node scripts/check-package.mjs && node scripts/check-install.mjs"},"peerDependencies":{"convex":">=1.42.1 <2.0.0","vite":">=5.0.0 <9.0.0"},"devDependencies":{"@biomejs/biome":"2.5.1","@edge-runtime/vm":"5.0.0","@types/node":"^22.0.0","convex":"1.42.1","convex-test":"0.0.54","typescript":"5.9.3","vite":"8.2.1","vitest":"4.1.10"},"repository":{"type":"git","url":"git+https://github.com/clipinfit/convex-credits.git","directory":"packages/convex-credits"},"keywords":["convex","convex-component","credits","ledger","billing","ai","reservations"],"author":{"name":"Denis Ciccale"},"engines":{"node":">=20"},"dependencies":{"convex-helpers":"0.1.120"},"peerDependenciesMeta":{"vite":{"optional":true}},"gitHead":"593393039e97d1faafe8925eb85834cd5a6fad02","_id":"@clipin/convex-credits@1.0.1","_nodeVersion":"26.7.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-KqBK9YwVzdIag0auodenJ7/TvP72MRJqKoeyi6q0AhG6eDOaZHwd0VR/yfcAzF6gI1cx6Tj/mGA3RmuxhTR58A==","shasum":"4d0a89e677d31ca8359bd72904f53f060d4a0482","tarball":"https://registry.npmjs.org/@clipin/convex-credits/-/convex-credits-1.0.1.tgz","fileCount":50,"unpackedSize":198142,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDseFw/UrxTK3caOR4CD4sd18whDnukc8FRjfInQKdFWAiEAmT1V3PrQfq4ri10CToqM5ooNRYqiIAaboY72VkYIdK0="}]},"_npmUser":{"name":"denis","email":"dciccale@gmail.com"},"directories":{},"maintainers":[{"name":"denis","email":"dciccale@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/convex-credits_1.0.1_1788878108750_0.9668467295783225"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-08T14:08:10.619Z","modified":"2026-09-08T14:35:09.113Z","1.0.0":"2026-09-08T14:08:10.993Z","1.0.1":"2026-09-08T14:35:08.884Z"},"bugs":{"url":"https://github.com/clipinfit/convex-credits/issues"},"author":{"name":"Denis Ciccale"},"license":"Apache-2.0","homepage":"https://convex-credits.vercel.app","keywords":["convex","convex-component","credits","ledger","billing","ai","reservations"],"repository":{"type":"git","url":"git+https://github.com/clipinfit/convex-credits.git","directory":"packages/convex-credits"},"description":"Transactional credits for Convex background jobs: reserve, complete, release, refund, and reconcile.","maintainers":[{"name":"denis","email":"dciccale@gmail.com"}],"readme":"# Convex Credits\n\nA Convex component for credit balances and background-job charges, maintained by CLIPIN.\n\nReserve credits before work starts. Complete after success. Release after failure. Refund completed work when needed. The component stores one debit per job and keeps completion state separate from credit movements.\n\nInstall with `npm install @clipin/convex-credits convex`. Version 1.0 provides the account, charge, and import APIs documented below.\n\n## Integration\n\n```ts\nimport { defineApp } from \"convex/server\";\nimport credits from \"@clipin/convex-credits/convex.config.js\";\nconst app = defineApp();\napp.use(credits);\nexport default app;\n```\n\n```ts\nimport { Credits } from \"@clipin/convex-credits\";\nimport { components } from \"./_generated/api\";\nconst credits = new Credits(components.credits);\n\nconst charge = await credits.reserve(ctx, {\n  owner: authenticatedAccountId,\n  amount: 10,\n  key: JSON.stringify([authenticatedAccountId, \"reserve\", requestId]),\n  reason: \"Image generation\",\n  reference: jobId,\n});\n\n// In a later mutation, after the job succeeds:\nawait credits.complete(ctx, {\n  chargeId: charge.chargeId,\n  key: JSON.stringify([charge.chargeId, \"complete\"]),\n});\n```\n\nThe host owns authentication, pricing, payment verification, and external job execution. Call the component from a host mutation to commit both sets of database writes together.\n\n## Rules\n\n- Amounts are positive safe integers. Available balances cannot become negative.\n- Every write requires an operation key. Identical retries return their original result.\n- Reusing a key with different arguments fails.\n- Completion and release are mutually exclusive.\n- Partial refunds cannot exceed the completed charge.\n- Transfers update both accounts atomically.\n- Namespaces isolate accounts, charges, and operation keys.\n- Imports preserve source timestamps and pending charges. Activation requires matching balances and counts.\n- Credit history uses cursor pagination. The component does not delete history or expire keys automatically.\n\n[Documentation](https://convex-credits.vercel.app/docs) · [Source](https://github.com/clipinfit/convex-credits)\n\n## Development\n\nFrom the repository root, run `bun install`, `bun run test`, `bun run typecheck`, and `bun run build`.\n\nUse `@clipin/convex-credits/test` to register the component in `convex-test`.\n\n## License\n\nApache-2.0. Copyright 2026 Denis Ciccale.\n","readmeFilename":"README.md"}