{"_id":"@codebolt/miniapp","_rev":"5-29d5c9abc41a97f870dc5ed1fca52d69","name":"@codebolt/miniapp","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@codebolt/miniapp","version":"0.1.0","_id":"@codebolt/miniapp@0.1.0","maintainers":[{"name":"ravirawatsingh","email":"ravi@arrowai.com"},{"name":"utkarshx","email":"utk.shukla@gmail.com"}],"bin":{"codebolt-miniapp-bundle":"src/bundle-cli.mjs"},"dist":{"shasum":"b7ea97094b1c2bb48ca9f912c12dd6332a9d1093","tarball":"https://registry.npmjs.org/@codebolt/miniapp/-/miniapp-0.1.0.tgz","fileCount":7,"integrity":"sha512-AHEf/nDA3q3MPFlw4Ih3z2gPWD40ZPS73o0LURdxD4BFLlC1bcGsb8JEaqX1bluCKnDQ+w8Ddp7CaqTCyhqJCw==","signatures":[{"sig":"MEYCIQDVeuMncqw4VgIg4w9BiZeC4RyBLp+dk+2Z/zYI/BnGZQIhANgqFfEQCiOC7a5OC6bDSOpi43Ztddrr9U/ZPVKzfj8g","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":40375},"type":"module","exports":{".":"./src/index.ts","./nitro":"./src/nitro.ts","./bundle":"./src/bundle.mjs","./bundle-cli":"./src/bundle-cli.mjs"},"_npmUser":{"name":"utkarshx","email":"utk.shukla@gmail.com"},"deprecated":"Executable mapping was normalized out during publication; use 0.1.1 or newer.","_npmVersion":"11.11.0","description":"`@codebolt/miniapp` is the authoring SDK and Nitro build adapter for CodeBolt MiniApps.","directories":{},"_nodeVersion":"20.18.3","dependencies":{"ajv":"^8.17.1","jiti":"^2.6.1","nitro":"^3.0.260610-beta"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/miniapp_0.1.0_1786700653402_0.08196401332294934","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@codebolt/miniapp","version":"0.1.1","_id":"@codebolt/miniapp@0.1.1","maintainers":[{"name":"ravirawatsingh","email":"ravi@arrowai.com"},{"name":"utkarshx","email":"utk.shukla@gmail.com"}],"bin":{"codebolt-miniapp-bundle":"src/bundle-cli.mjs"},"dist":{"shasum":"1f91224bbee9a82ad6329008a32f8349ba824d61","tarball":"https://registry.npmjs.org/@codebolt/miniapp/-/miniapp-0.1.1.tgz","fileCount":7,"integrity":"sha512-e+TNT2GOubqkzRKqER+WL5tq5The5dxbkH+oBDFdcavYux2Ip3sPIOde9hc0LpweS4EYfZIv+J1LCB4wqtE3zQ==","signatures":[{"sig":"MEUCIQDJRsuLHnqGbPxIZCzqtrdvGncp7HvZpa/GPEiSYjKyvwIgaAV9CjBmvaYh5RTd/1WmnpqVjlxz+jDi8/m6awh2In4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":40391},"type":"module","exports":{".":"./src/index.ts","./nitro":"./src/nitro.ts","./bundle":"./src/bundle.mjs","./bundle-cli":"./src/bundle-cli.mjs"},"_npmUser":{"name":"utkarshx","email":"utk.shukla@gmail.com"},"_npmVersion":"11.11.0","description":"`@codebolt/miniapp` is the authoring SDK and Nitro build adapter for CodeBolt MiniApps.","directories":{},"_nodeVersion":"20.18.3","dependencies":{"ajv":"^8.17.1","jiti":"^2.6.1","nitro":"^3.0.260610-beta"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/miniapp_0.1.1_1786700738187_0.474828597010557","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Strict Nitro consumers fail typecheck; use 0.1.2 or newer."},"0.1.2":{"name":"@codebolt/miniapp","version":"0.1.2","_id":"@codebolt/miniapp@0.1.2","maintainers":[{"name":"ravirawatsingh","email":"ravi@arrowai.com"},{"name":"utkarshx","email":"utk.shukla@gmail.com"}],"bin":{"codebolt-miniapp-bundle":"src/bundle-cli.mjs"},"dist":{"shasum":"b3ab0151f4a6f72a1cfd7f22b479498e754777b9","tarball":"https://registry.npmjs.org/@codebolt/miniapp/-/miniapp-0.1.2.tgz","fileCount":7,"integrity":"sha512-EJNt0ynZVHWTSAs20X5mCDtLhKgSa67uuAIdB3IC2e/Uq6QZ7njIIgpav2klTakdrcy5tjk3Yizku3o+y0TSkQ==","signatures":[{"sig":"MEUCIQCDKxT1WPOE++DCGCT9gyiVVcuTFxyGxO0j/ClzEg363QIgJrI9KtKAsO7k2fz2BQSLNZvgTxa2N2wH/DJVNWaH+8I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":40391},"type":"module","exports":{".":"./src/index.ts","./nitro":"./src/nitro.ts","./bundle":"./src/bundle.mjs","./bundle-cli":"./src/bundle-cli.mjs"},"_npmUser":{"name":"utkarshx","email":"utk.shukla@gmail.com"},"_npmVersion":"11.11.0","description":"`@codebolt/miniapp` is the authoring SDK and Nitro build adapter for CodeBolt MiniApps.","directories":{},"_nodeVersion":"20.18.3","dependencies":{"ajv":"^8.17.1","jiti":"^2.6.1","nitro":"^3.0.260610-beta"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/miniapp_0.1.2_1786702248262_0.3385440326971645","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-08-14T09:44:13.201Z","modified":"2026-08-14T10:13:27.378Z","0.1.0":"2026-08-14T09:44:13.561Z","0.1.1":"2026-08-14T09:45:38.314Z","0.1.2":"2026-08-14T10:10:48.412Z"},"description":"`@codebolt/miniapp` is the authoring SDK and Nitro build adapter for CodeBolt MiniApps.","maintainers":[{"name":"ravirawatsingh","email":"ravi@arrowai.com"},{"name":"utkarshx","email":"utk.shukla@gmail.com"}],"readme":"# @codebolt/miniapp\n\n`@codebolt/miniapp` is the authoring SDK and Nitro build adapter for CodeBolt\nMiniApps.\n\nThe package has three library entry points plus a command-line entry:\n\n```text\n@codebolt/miniapp        # MiniApp author/runtime API\n@codebolt/miniapp/nitro  # Nitro build adapter\n@codebolt/miniapp/bundle # .miniapp archive builder and verifier\ncodebolt-miniapp-bundle  # pack, inspect, and verify commands\n```\n\nUse the root export from MiniApp code, the `./nitro` export only from\n`nitro.config.ts`, and the `./bundle` export only from Node-side build tooling.\n\n## Root Export\n\n```ts\nimport {\n  defineTool,\n  defineCollection,\n  useMiniApp,\n} from \"@codebolt/miniapp\";\n```\n\nThe root export contains the MiniApp definition helpers and runtime context API.\n\n### `defineTool()`\n\nDeclares a CodeBolt tool. It adds `kind: \"tool\"` to the object and preserves the\nmetadata, JSON schemas, and handler.\n\n```ts\nimport { defineTool } from \"@codebolt/miniapp\";\n\nexport default defineTool({\n  name: \"add-lead\",\n  description: \"Store a discovered lead.\",\n  inputSchema: {\n    type: \"object\",\n    additionalProperties: false,\n    required: [\"id\", \"name\", \"company\"],\n    properties: {\n      id: { type: \"string\", minLength: 1 },\n      name: { type: \"string\", minLength: 1 },\n      company: { type: \"string\", minLength: 1 },\n      email: { type: \"string\" },\n    },\n  },\n  async handler(context, input) {\n    return context.db.set(\"leads\", input.id, input);\n  },\n});\n```\n\n`defineTool()` does not register routes or scan files by itself. Tool discovery is\ndone by `codeboltMiniApp()` from `@codebolt/miniapp/nitro`.\n\n### `defineCollection()`\n\nDeclares a collection schema for manifest/catalog metadata.\n\n```ts\nimport { defineCollection } from \"@codebolt/miniapp\";\n\nexport default defineCollection({\n  name: \"leads\",\n  schema: {\n    type: \"object\",\n    required: [\"id\", \"name\", \"company\"],\n    properties: {\n      id: { type: \"string\" },\n      name: { type: \"string\" },\n      company: { type: \"string\" },\n      email: { type: \"string\" },\n    },\n  },\n});\n```\n\n### `useMiniApp()`\n\nReturns the runtime context for API routes and tool handlers.\n\n```ts\nimport { defineHandler } from \"nitro/h3\";\nimport { useMiniApp } from \"@codebolt/miniapp\";\n\nexport default defineHandler((event) => {\n  return useMiniApp(event).db.list(\"leads\");\n});\n```\n\nThe context currently exposes:\n\n```ts\ncontext.miniAppId;\ncontext.installId;\ncontext.workspaceId;\ncontext.principal;\ncontext.db;\ncontext.blob;\ncontext.codebolt.tasks;\n```\n\nFor local CodeBolt hosting, `useMiniApp()` reads the worker-injected runtime\nbridge. For remote Node or Cloudflare output, it reads the execution token from\nthe request and calls the configured CodeBolt Cloud capability endpoint.\n\nPass the Nitro `event` in server routes:\n\n```ts\nexport default defineHandler((event) => useMiniApp(event).db.list(\"leads\"));\n```\n\nRemote serverless requests need the event because the execution token lives in\nthe current request headers. Local host mode can work without an event because\nthe host injects a runtime bridge into the MiniApp worker. Tool handlers usually\ndo not call `useMiniApp()` directly because the CodeBolt tool route creates the\ncontext and passes it to the tool handler.\n\n## Nitro Export\n\n```ts\nimport { codeboltMiniApp, resolveTarget } from \"@codebolt/miniapp/nitro\";\n```\n\nThe Nitro export contains build-time integration code. Keep it out of ordinary\ntool and route files.\n\n### `resolveTarget()`\n\nReturns the Nitro output config for the selected MiniApp target.\n\n```ts\nresolveTarget();          // uses process.env.MINIAPP_TARGET\nresolveTarget(\"local\");   // standard preset, .output\nresolveTarget(\"node\");    // node-server preset, .output-node\nresolveTarget(\"cloudflare\"); // cloudflare-module preset, .output-cloudflare\n```\n\nThe local target uses Nitro's `standard` preset with `serveStatic: false`,\nbecause the CodeBolt host serves static assets itself.\n\n### `codeboltMiniApp()`\n\nRegisters the CodeBolt MiniApp build behavior as a Nitro module.\n\n```ts\nimport { defineConfig } from \"nitro\";\nimport { codeboltMiniApp, resolveTarget } from \"@codebolt/miniapp/nitro\";\n\nexport default defineConfig({\n  ...resolveTarget(),\n  compatibilityDate: \"2026-07-24\",\n  serverDir: \"server\",\n  modules: [\n    codeboltMiniApp({\n      id: \"leads\",\n      title: \"Lead Depository\",\n      version: \"0.1.0\",\n      route: \"/\",\n    }),\n  ],\n});\n```\n\nDuring `nitro build`, `codeboltMiniApp()`:\n\n- scans `server/tools` and `server/collections`\n- loads default-exported MiniApp definitions\n- creates virtual modules for tool lookup and validation\n- registers `POST /__codebolt/tools/:name`\n- emits `.output/codebolt/miniapp.manifest.json`\n\nInput validators are compiled during the build and emitted as standalone\nfunctions. Do not move Ajv compilation back into the request path; Cloudflare\nWorkers reject runtime string-based code generation.\n\nWithout `codeboltMiniApp()`, Nitro can still bundle imports from\n`@codebolt/miniapp`, but CodeBolt tool files will not be discovered, tool routes\nwill not be registered, and no MiniApp manifest will be generated.\n\n## Expected File Layout\n\n```text\nserver/\n  api/\n    leads.get.ts\n  tools/\n    add-lead.ts\n  collections/\n    leads.ts\npublic/\n  index.html\nnitro.config.ts\npackage.json\n```\n\nNitro owns normal API route handling under `server/api`. CodeBolt-specific\ndefinition scanning is limited to `server/tools`, `server/collections`, and\nthe single UI entry declared in `codeboltMiniApp({ title, route })`.\n\n## Package Boundary\n\nThis package intentionally keeps two concepts separate:\n\n- Root export: stable MiniApp authoring/runtime API.\n- `./nitro` export: Nitro-specific build-time adapter.\n- `./bundle` export: Node-side packaging of `cloudflare-module` output into the generic MiniApp Server ABI.\n\n## Cloud Bundle Build\n\nBuild the normal Cloudflare module output, then package it without deploying a separate Worker:\n\n```powershell\n$env:MINIAPP_TARGET='cloudflare'\nnpm run build\nnpx codebolt-miniapp-bundle pack .output-cloudflare --output dist/my-app.miniapp\n```\n\nThe archive contains Nitro's complete module graph, public assets, CodeBolt manifest metadata, checksums, and a generated `codebolt.fetch.v1` adapter. It does not contain a Durable Object class; the shared MiniApp Server injects that lifecycle at install time.\n\nThat allows app code to stay framework-neutral while keeping the current Nitro\nintegration explicit and easy to customize in `nitro.config.ts`.\n\n## Related Docs\n\n- `../../packages/host/README.md`: local host and worker runtime.\n- `../../MINIAPP_PUBLISHING_AND_USAGE.md`: local usage, cloud publishing,\n  portal install flow, and agent tool exposure.\n- `../../examples/leads/README.md`: lead depository example.\n- `../../examples/onboarding/README.md`: onboarding example.\n- `../../skills/create-miniapp/SKILL.md`: agent instructions for authoring new\n  MiniApps.\n","readmeFilename":"README.md"}