{"_id":"@bondi-labs/integration-sdk","_rev":"3-d747c49c80eed5f5aec98657b4bc20dc","name":"@bondi-labs/integration-sdk","dist-tags":{"latest":"0.0.3"},"versions":{"0.0.1":{"name":"@bondi-labs/integration-sdk","version":"0.0.1","keywords":["bondi","automation","integration","sdk","nestjs","webhook","hmac"],"author":{"name":"Bondi","email":"support@heybondi.com"},"license":"MIT","_id":"@bondi-labs/integration-sdk@0.0.1","maintainers":[{"name":"baraktu","email":"barak@heybondi.com"}],"homepage":"https://heybondi.com","bugs":{"url":"https://github.com/heybondi/monorepo/issues"},"bin":{"bondi":"cli/bin.js"},"dist":{"shasum":"ae0860ec24ecdbb145adee91719b727a2742e477","tarball":"https://registry.npmjs.org/@bondi-labs/integration-sdk/-/integration-sdk-0.0.1.tgz","fileCount":28,"integrity":"sha512-R+Ob6+Kw0ZWty81mImuEWAZtnD5UH2mOUAE2+t5sLq02MHagb2MYRNTjJxkD/FjWpgLTWPnKu6LgvusB1KC8AA==","signatures":[{"sig":"MEYCIQCSPIi2EsrMN3VQD0IZX5836rcC/rxzB8XmeoYxTbZyHgIhAOONV8lPcQx1kuAFl/oFSNHuuuwyDNKtwir2nTBFltIC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":717735},"main":"./core/index.js","type":"commonjs","types":"./core/index.d.ts","module":"./core/index.mjs","engines":{"node":">=18"},"exports":{"./cli":{"types":"./cli/index.d.ts","import":"./cli/index.mjs","require":"./cli/index.js"},"./core":{"types":"./core/index.d.ts","import":"./core/index.mjs","require":"./core/index.js"},"./nestjs":{"types":"./nestjs/index.d.ts","import":"./nestjs/index.mjs","require":"./nestjs/index.js"},"./package.json":"./package.json"},"gitHead":"b270079b4d17a2914f4ee9d564d5b93c37a6cb0d","_npmUser":{"name":"baraktu","email":"barak@heybondi.com"},"repository":{"url":"git+https://github.com/heybondi/monorepo.git","type":"git","directory":"packages/public-sdks/integration-sdk"},"_npmVersion":"11.7.0","description":"Bondi integration SDK — define triggers and actions for the Bondi automation engine.","directories":{},"sideEffects":false,"_nodeVersion":"20.18.1","dependencies":{"zod":"^3.23.8","zod-to-json-schema":"^3.23.5"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"zod":"^3.0.0","@nestjs/core":"^10.0.0","@nestjs/common":"^10.0.0"},"peerDependenciesMeta":{"@nestjs/core":{"optional":true},"@nestjs/common":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/integration-sdk_0.0.1_1777226191197_0.30532380709588325","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@bondi-labs/integration-sdk","version":"0.0.2","keywords":["bondi","automation","integration","sdk","nestjs","webhook","hmac"],"author":{"name":"Bondi","email":"support@heybondi.com"},"license":"MIT","_id":"@bondi-labs/integration-sdk@0.0.2","maintainers":[{"name":"baraktu","email":"barak@heybondi.com"}],"homepage":"https://heybondi.com","bugs":{"url":"https://github.com/bondi-labs-inc/integration-sdk/issues"},"bin":{"bondi":"cli/bin.js"},"dist":{"shasum":"ed652af22b3cff2f9512e3017c04f895da950d7f","tarball":"https://registry.npmjs.org/@bondi-labs/integration-sdk/-/integration-sdk-0.0.2.tgz","fileCount":29,"integrity":"sha512-42BYGZVFHeh/71EXXxMOYa98NxSDOLjSS4sc4hi0Ifqa8VA9H972DI+DYhFBgHF1ln/ZVEXunlG0Drh+C+cw2A==","signatures":[{"sig":"MEYCIQCI3ic7VZMj7j7XCfmjCbXUEzHSOy4WvmY949BapOYAHwIhAPRM7dD0ajmkxYeQHFTKDrXrksKtbCjb36oVmlRTlGLt","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":887723},"main":"./core/index.js","type":"commonjs","types":"./core/index.d.ts","module":"./core/index.mjs","engines":{"node":">=18"},"exports":{"./cli":{"types":"./cli/index.d.ts","import":"./cli/index.mjs","require":"./cli/index.js"},"./core":{"types":"./core/index.d.ts","import":"./core/index.mjs","require":"./core/index.js"},"./nestjs":{"types":"./nestjs/index.d.ts","import":"./nestjs/index.mjs","require":"./nestjs/index.js"},"./package.json":"./package.json"},"gitHead":"18865ae3c83a0fea6e52fa6ed73b3aa927bbfb1c","_npmUser":{"name":"baraktu","email":"barak@heybondi.com"},"repository":{"url":"git+https://github.com/bondi-labs-inc/integration-sdk.git","type":"git"},"_npmVersion":"11.7.0","description":"Bondi integration SDK — define triggers and actions for the Bondi automation engine.","directories":{},"sideEffects":false,"_nodeVersion":"20.18.1","dependencies":{"zod":"^3.23.8","zod-to-json-schema":"^3.23.5"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"zod":"^3.0.0","@nestjs/core":"^10.0.0","@nestjs/common":"^10.0.0"},"peerDependenciesMeta":{"@nestjs/core":{"optional":true},"@nestjs/common":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/integration-sdk_0.0.2_1777228030199_0.057558614628642424","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@bondi-labs/integration-sdk","version":"0.0.3","description":"Bondi integration SDK — define triggers and actions for the Bondi automation engine.","license":"MIT","author":{"name":"Bondi","email":"support@heybondi.com"},"homepage":"https://heybondi.com","repository":{"type":"git","url":"git+https://github.com/bondi-labs-inc/integration-sdk.git"},"bugs":{"url":"https://github.com/bondi-labs-inc/integration-sdk/issues"},"keywords":["bondi","automation","integration","sdk","nestjs","webhook","hmac"],"engines":{"node":">=18"},"type":"commonjs","main":"./core/index.js","module":"./core/index.mjs","types":"./core/index.d.ts","exports":{"./core":{"types":"./core/index.d.ts","import":"./core/index.mjs","require":"./core/index.js"},"./nestjs":{"types":"./nestjs/index.d.ts","import":"./nestjs/index.mjs","require":"./nestjs/index.js"},"./cli":{"types":"./cli/index.d.ts","import":"./cli/index.mjs","require":"./cli/index.js"},"./express":{"types":"./express/index.d.ts","import":"./express/index.mjs","require":"./express/index.js"},"./fastify":{"types":"./fastify/index.d.ts","import":"./fastify/index.mjs","require":"./fastify/index.js"},"./web":{"types":"./web/index.d.ts","import":"./web/index.mjs","require":"./web/index.js"},"./package.json":"./package.json"},"bin":{"bondi":"cli/bin.js"},"dependencies":{"zod":"^3.23.8","zod-to-json-schema":"^3.23.5"},"peerDependencies":{"@nestjs/common":"^10.0.0","@nestjs/core":"^10.0.0","express":"^4.0.0 || ^5.0.0","fastify":"^4.0.0 || ^5.0.0","reflect-metadata":"^0.2.0","zod":"^3.0.0"},"peerDependenciesMeta":{"@nestjs/common":{"optional":true},"@nestjs/core":{"optional":true},"express":{"optional":true},"fastify":{"optional":true},"reflect-metadata":{"optional":true}},"publishConfig":{"access":"public"},"sideEffects":false,"_id":"@bondi-labs/integration-sdk@0.0.3","gitHead":"ffcfad7af9b72f87a74beb313bcac62a902edf28","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-0iS5+G2M7r7Fp1kzjLcDa8ApSdxFo8FyJk2Po8T3U33kwZtw40Qxdu9wSPTISfr3RoP1go74Ml1r28GhPwY+GQ==","shasum":"a8ffd4492402eb8209a4a40016c52596da2f2019","tarball":"https://registry.npmjs.org/@bondi-labs/integration-sdk/-/integration-sdk-0.0.3.tgz","fileCount":52,"unpackedSize":621362,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC8uJhCdgKZpavIt4JBDB4KVGys4ywXBCTZf2ik2i2j2QIhAI0Fuvh8rmj/Ib/MQNZJhUhtQ/bxeDUA/rTWgci4Lin4"}]},"_npmUser":{"name":"baraktu","email":"barak@heybondi.com"},"directories":{},"maintainers":[{"name":"baraktu","email":"barak@heybondi.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/integration-sdk_0.0.3_1777243402132_0.6259258414242628"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T17:56:31.112Z","modified":"2026-04-26T22:43:22.423Z","0.0.1":"2026-04-26T17:56:31.368Z","0.0.2":"2026-04-26T18:27:10.434Z","0.0.3":"2026-04-26T22:43:22.290Z"},"bugs":{"url":"https://github.com/bondi-labs-inc/integration-sdk/issues"},"author":{"name":"Bondi","email":"support@heybondi.com"},"license":"MIT","homepage":"https://heybondi.com","keywords":["bondi","automation","integration","sdk","nestjs","webhook","hmac"],"repository":{"type":"git","url":"git+https://github.com/bondi-labs-inc/integration-sdk.git"},"description":"Bondi integration SDK — define triggers and actions for the Bondi automation engine.","maintainers":[{"name":"baraktu","email":"barak@heybondi.com"}],"readme":"# @bondi-labs/integration-sdk\n\n[![npm version](https://img.shields.io/npm/v/@bondi-labs/integration-sdk.svg)](https://www.npmjs.com/package/@bondi-labs/integration-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Types](https://img.shields.io/npm/types/@bondi-labs/integration-sdk.svg)](https://www.npmjs.com/package/@bondi-labs/integration-sdk)\n[![Bundle size](https://img.shields.io/bundlephobia/minzip/@bondi-labs/integration-sdk)](https://bundlephobia.com/package/@bondi-labs/integration-sdk)\n\nDefine triggers and actions for the [Bondi](https://heybondi.com) automation engine — bring your own API into Bondi workflows.\n\n| Resource | Link |\n|---|---|\n| 📚 **API Reference** | [integration-sdk.heybondi.com](https://integration-sdk.heybondi.com/) |\n| 🚀 **Examples** | [github.com/bondi-labs-inc/integration-sdk-examples](https://github.com/bondi-labs-inc/integration-sdk-examples) |\n| 📝 **Changelog** | [CHANGELOG.md](./CHANGELOG.md) |\n| 🐛 **Issues** | [github.com/bondi-labs-inc/integration-sdk/issues](https://github.com/bondi-labs-inc/integration-sdk/issues) |\n\n## Install\n\n```bash\nnpm install @bondi-labs/integration-sdk\n```\n\n## Quickstart\n\n```bash\n# 1. Authenticate and create an integration in your workspace.\nnpx bondi init\n\n# 2. Define your integration in code.\n# 3. Sync the definition to Bondi.\nnpx bondi sync\n```\n\n`npx bondi init` opens your browser for authentication, then writes:\n\n```ini\nBONDI_WORKSPACE_ID=ws-...\nBONDI_INTEGRATION_TOKEN=bnd_tok_...\n```\n\n(`BONDI_API_URL` defaults to `https://automation.heybondi.com` and only needs to be set when targeting a non-prod Bondi deployment.)\n\n## Core API\n\n```ts\nimport {\n  defineIntegration,\n  defineAction,\n  defineTrigger,\n  createBondiClient,\n} from \"@bondi-labs/integration-sdk/core\";\nimport { z } from \"zod\";\n\nconst contactCreated = defineTrigger({\n  name: \"contact.created\",\n  label: \"Contact Created\",\n  payload: z.object({ id: z.string(), email: z.string().email() }),\n});\n\nconst myCRM = defineIntegration({\n  name: \"My CRM\",\n  slug: \"my-crm\",\n  baseUrl: \"https://api.mycrm.com/v1\",\n  services: [\n    {\n      name: \"contacts\",\n      label: \"Contacts\",\n      actions: [\n        defineAction({\n          name: \"createContact\",\n          label: \"Create Contact\",\n          method: \"POST\",\n          endpoint: \"/contacts\",\n          body: z.object({ name: z.string(), email: z.string() }),\n          response: z.object({ id: z.string() }),\n        }),\n      ],\n      triggers: [contactCreated],\n    },\n  ],\n});\n\nexport default myCRM; // CLI sync reads `default` export\n\n// Runtime — emit events from your app\nconst client = createBondiClient({\n  workspaceId: process.env.BONDI_WORKSPACE_ID,\n  token: process.env.BONDI_INTEGRATION_TOKEN,\n});\nconst bondi = client.bind(myCRM);\n\nbondi.triggers[\"contact.created\"].emit({ id: \"123\", email: \"john@example.com\" });\n```\n\n`emit()` is fire-and-forget. Use `emitAndWait()` to await acknowledgement, or pass `onEmitError` to the client config to capture failures.\n\n## NestJS adapter\n\n```ts\nimport {\n  BondiModule,\n  BondiTrigger,\n  BondiTriggerBase,\n  BondiService,\n  BondiAction,\n  BondiGuard,\n} from \"@bondi-labs/integration-sdk/nestjs\";\nimport { Module, Controller, Injectable, Post, Body, UseGuards } from \"@nestjs/common\";\nimport { z } from \"zod\";\n\nconst contactPayload = z.object({ id: z.string(), email: z.string() });\n\n@BondiTrigger({ name: \"contact.created\", label: \"Contact Created\", payload: contactPayload })\nexport class ContactCreatedTrigger extends BondiTriggerBase<typeof contactPayload> {}\n\n@Injectable()\nexport class ContactsService {\n  constructor(private contactCreated: ContactCreatedTrigger) {}\n  create(dto: { id: string; email: string }) {\n    this.contactCreated.emit(dto); // type-safe via Zod\n  }\n}\n\n@BondiService({ name: \"contacts\", label: \"Contacts\" })\n@Controller(\"contacts\")\nexport class ContactsController {\n  @UseGuards(BondiGuard)\n  @BondiAction({ name: \"createContact\", label: \"Create Contact\" })\n  @Post()\n  async create(@Body() dto: unknown) {\n    /* ... */\n  }\n}\n\n@Module({\n  imports: [\n    BondiModule.forRoot({\n      integration: { name: \"My CRM\", slug: \"my-crm\", category: \"crm\" },\n      triggers: [ContactCreatedTrigger],\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n`BondiModule.forRoot` reads `BONDI_*` env vars by default. To override, pass values directly:\n\n```ts\nBondiModule.forRoot({\n  integration: { /* ... */ },\n  workspaceId: \"ws-abc-123\",                            // hard-coded\n  token: { envKey: \"MY_BONDI_TOKEN\" },                  // custom env var\n  apiUrl: () => configService.get(\"BONDI_API_URL\"),     // factory\n})\n```\n\n## Verifying webhook signatures\n\nWhen Bondi calls your `BondiAction` endpoints, requests are signed with HMAC-SHA256 over `{timestamp}.{action}.{rawBody}`. Use the framework adapter that fits your stack — they handle raw-body capture, signature verification, body parsing, and end-to-end Zod typing in one call:\n\n| Framework | Import | Helper |\n|---|---|---|\n| NestJS | `@bondi-labs/integration-sdk/nestjs` | `BondiGuard` |\n| Express | `@bondi-labs/integration-sdk/express` | `actionHandler`, `bondiExpressMiddleware` |\n| Fastify | `@bondi-labs/integration-sdk/fastify` | `actionHandler`, `bondiFastifyVerifier` |\n| Cloudflare Workers / Next.js / Hono / Bun / Deno | `@bondi-labs/integration-sdk/web` | `withAction`, `withBondiVerification` |\n\nFor non-Node stacks the algorithm is short — here's the Python equivalent:\n\n```python\nimport hmac, hashlib, time\n\ndef verify_bondi(headers, raw_body, token):\n    ts     = headers[\"x-bondi-timestamp\"]\n    action = headers[\"x-bondi-action\"]\n    sig    = headers[\"x-bondi-signature\"]\n    if abs(time.time() - int(ts)) > 300:\n        return False\n    expected = hmac.new(token.encode(), f\"{ts}.{action}.{raw_body}\".encode(), hashlib.sha256).hexdigest()\n    return hmac.compare_digest(sig.removeprefix(\"sha256=\"), expected)\n```\n\n## Environment variables\n\n| Var | Description |\n|---|---|\n| `BONDI_WORKSPACE_ID` | Your workspace ID |\n| `BONDI_INTEGRATION_TOKEN` | HMAC signing key — never sent over the wire |\n| `BONDI_API_URL` | Optional override — defaults to `https://automation.heybondi.com`. Set when targeting a non-prod Bondi deployment. |\n\n## Guides\n\n| Topic | Link |\n|---|---|\n| Getting started — NestJS | [docs/getting-started/nestjs.md](./docs/getting-started/nestjs.md) |\n| Getting started — plain Node / Express | [docs/getting-started/plain-node.md](./docs/getting-started/plain-node.md) |\n| Verifying webhooks (Python, Go, Ruby) | [docs/guides/webhook-verification.md](./docs/guides/webhook-verification.md) |\n| Error handling, retries, dry-run | [docs/guides/error-handling.md](./docs/guides/error-handling.md) |\n| Token rotation | [docs/guides/token-rotation.md](./docs/guides/token-rotation.md) |\n| `internalMode` (Bondi-only) | [docs/guides/internal-mode.md](./docs/guides/internal-mode.md) |\n| HTTP header reference | [docs/reference/headers.md](./docs/reference/headers.md) |\n\n## Support\n\n- 🐛 Bug reports & feature requests: [GitHub Issues](https://github.com/bondi-labs-inc/integration-sdk/issues)\n- 💬 Questions: [support@heybondi.com](mailto:support@heybondi.com)\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","readmeFilename":"README.md"}