{"_id":"@chaitin-ai/octobus-sdk","_rev":"4-8e8e36ac540db2d025da39fe6087043d","name":"@chaitin-ai/octobus-sdk","dist-tags":{"latest":"0.6.1"},"versions":{"0.5.0":{"name":"@chaitin-ai/octobus-sdk","version":"0.5.0","keywords":["octobus","sdk","grpc","protobuf","service-package"],"license":"LGPL-3.0-only","_id":"@chaitin-ai/octobus-sdk@0.5.0","maintainers":[{"name":"mentats","email":"innomentats@gmail.com"}],"homepage":"https://github.com/chaitin/OctoBus#readme","bugs":{"url":"https://github.com/chaitin/OctoBus/issues"},"bin":{"octobus-sdk":"dist/cli.js"},"dist":{"shasum":"83af17cb1bd5568f44aaa8285aee50494b05158a","tarball":"https://registry.npmjs.org/@chaitin-ai/octobus-sdk/-/octobus-sdk-0.5.0.tgz","fileCount":37,"integrity":"sha512-FaO9foqE7/7Ppl4V4dwuWJzgvoxr7VCiYHj74AcxuhKtb2SCSqp8KsIehJAc2pI+SMRP2ECFSloF3Z9Q9o8v1A==","signatures":[{"sig":"MEUCIQChmP/aNnC56olvCFNDkOyvlNrx/39mJNG+yxkWtScfCwIgDhwL6MKshLwrmuOlE8Gme3eYdWozN57GWtCSjWyAOJM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":177881},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"da3ff23f2e4cfefbd9a4a4315a884afed06e8c3e","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"mentats","email":"innomentats@gmail.com"},"repository":{"url":"git+https://github.com/chaitin/OctoBus.git","type":"git","directory":"sdk"},"_npmVersion":"11.6.2","description":"TypeScript SDK for OctoBus Node.js service packages.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"yaml":"^2.9.0","commander":"^15.0.0","@grpc/grpc-js":"^1.14.4","@bufbuild/protobuf":"^2.12.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.8","typescript":"^6.0.3","@types/node":"^25.9.3","@vitest/coverage-v8":"^4.1.8"},"_npmOperationalInternal":{"tmp":"tmp/octobus-sdk_0.5.0_1781455535869_0.6950585694893283","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@chaitin-ai/octobus-sdk","version":"0.6.0","keywords":["octobus","sdk","grpc","protobuf","service-package"],"license":"LGPL-3.0-only","_id":"@chaitin-ai/octobus-sdk@0.6.0","maintainers":[{"name":"mentats","email":"innomentats@gmail.com"}],"homepage":"https://github.com/chaitin/OctoBus#readme","bugs":{"url":"https://github.com/chaitin/OctoBus/issues"},"bin":{"octobus-sdk":"dist/cli.js"},"dist":{"shasum":"e102b00307c14cd916456acfdcf83b4a75cc06c9","tarball":"https://registry.npmjs.org/@chaitin-ai/octobus-sdk/-/octobus-sdk-0.6.0.tgz","fileCount":39,"integrity":"sha512-FK1uRNQwfKDB68YhX2upOVzAYLBOgNANR69j9eRpkwKlerd2Mry6is3R13Xkdm8ejqctIFqlV6YpezRIKIMOPg==","signatures":[{"sig":"MEYCIQCUVOTeA2unrcDD8cq7xVnJXwKxYobS4uRfAXD+Owid+wIhALAUtHLnDPbv5FIK/KcFMtjKQ7F++OZBCIbZJ5pq+7y6","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaitin-ai%2foctobus-sdk@0.6.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":192358},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"d3ec46f7c33d59d8469b4533fead8afe7e9d386a","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"mentats","email":"innomentats@gmail.com"},"repository":{"url":"git+https://github.com/chaitin/OctoBus.git","type":"git","directory":"sdk"},"_npmVersion":"10.9.8","description":"TypeScript SDK for OctoBus Node.js service packages.","directories":{},"_nodeVersion":"22.23.0","dependencies":{"yaml":"^2.9.0","undici":"^7.16.0","commander":"^15.0.0","@grpc/grpc-js":"^1.14.4","@bufbuild/protobuf":"^2.12.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.8","typescript":"^6.0.3","@types/node":"^25.9.3","@vitest/coverage-v8":"^4.1.8"},"_npmOperationalInternal":{"tmp":"tmp/octobus-sdk_0.6.0_1782825763882_0.5980492130771617","host":"s3://npm-registry-packages-npm-production"}},"0.6.1":{"name":"@chaitin-ai/octobus-sdk","version":"0.6.1","description":"TypeScript SDK for OctoBus Node.js service packages.","license":"LGPL-3.0-only","type":"module","main":"dist/index.js","types":"dist/index.d.ts","repository":{"type":"git","url":"git+https://github.com/chaitin/OctoBus.git","directory":"sdk"},"homepage":"https://github.com/chaitin/OctoBus#readme","bugs":{"url":"https://github.com/chaitin/OctoBus/issues"},"keywords":["octobus","sdk","grpc","protobuf","service-package"],"bin":{"octobus-sdk":"dist/cli.js"},"engines":{"node":">=20"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"dependencies":{"@bufbuild/protobuf":"^2.12.0","@grpc/grpc-js":"^1.14.4","commander":"^15.0.0","undici":"^7.16.0","yaml":"^2.9.0"},"devDependencies":{"@types/node":"^25.9.3","@vitest/coverage-v8":"^4.1.8","typescript":"^6.0.3","vitest":"^4.1.8"},"gitHead":"ff55c26eb293b1972a120813468671256d050a7e","_id":"@chaitin-ai/octobus-sdk@0.6.1","_nodeVersion":"24.20.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-aOhj7IuOa7RHWKlZBPVoCY1Sd6SDclmO9V7Nx5huXG9pWwVN8TuO01478yUx8uaot46VGf8+Lnh3O/XChHMCwQ==","shasum":"a6a452c00bf2c41533bcfb4c5e2da55915098ed1","tarball":"https://registry.npmjs.org/@chaitin-ai/octobus-sdk/-/octobus-sdk-0.6.1.tgz","fileCount":39,"unpackedSize":201981,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chaitin-ai%2foctobus-sdk@0.6.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBA93O76/jlvB9bFI6qjTR6LqpC3+Z1gzFunDm2KZGa4AiB6dFlSbX/mnlHG7N1RXIeKNrfJMfMH8huRLRBIaRMocQ=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:651cfb9f-7f66-4147-ae70-7c1446469c5f"}},"directories":{},"maintainers":[{"name":"mentats","email":"innomentats@gmail.com"},{"name":"eetoc","email":"chuan.wang@chaitin.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/octobus-sdk_0.6.1_1789465763995_0.27224005495567694"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-14T16:45:35.674Z","modified":"2026-09-15T09:49:24.446Z","0.5.0":"2026-06-14T16:45:36.023Z","0.6.0":"2026-06-30T13:22:44.001Z","0.6.1":"2026-09-15T09:49:24.121Z"},"bugs":{"url":"https://github.com/chaitin/OctoBus/issues"},"license":"LGPL-3.0-only","homepage":"https://github.com/chaitin/OctoBus#readme","keywords":["octobus","sdk","grpc","protobuf","service-package"],"repository":{"type":"git","url":"git+https://github.com/chaitin/OctoBus.git","directory":"sdk"},"description":"TypeScript SDK for OctoBus Node.js service packages.","maintainers":[{"name":"mentats","email":"innomentats@gmail.com"},{"name":"eetoc","email":"chuan.wang@chaitin.com"}],"readme":"# @chaitin-ai/octobus-sdk\n\nTypeScript SDK for OctoBus Node.js service packages.\n\n## Quick Start\n\nCreate a minimal service package scaffold:\n\n```bash\nnpx @chaitin-ai/octobus-sdk bootstrap \\\n  --name @acme/echo-service \\\n  --out ./echo-service\n```\n\nFor packages that need to run in an OctoBus environment without npm registry access, include production dependencies in the generated package:\n\n```bash\nnpx @chaitin-ai/octobus-sdk bootstrap \\\n  --name @acme/echo-service \\\n  --out ./echo-service \\\n  --bundle-deps\n```\n\nOr create a package manually with `service.json`, `package.json bin`, proto files, and a runtime entry:\n\n```json\n{\n  \"schema\": \"chaitin.octobus.service.v1\",\n  \"name\": \"calculator\",\n  \"proto\": {\n    \"roots\": [\"proto\"],\n    \"files\": [\"proto/calculator.proto\"]\n  },\n  \"configSchema\": \"config.schema.json\",\n  \"secretSchema\": \"secret.schema.json\"\n}\n```\n\n```json\n{\n  \"type\": \"module\",\n  \"bin\": {\n    \"calculator\": \"bin/calculator.js\"\n  },\n  \"dependencies\": {\n    \"@chaitin-ai/octobus-sdk\": \"^0.6.1\"\n  }\n}\n```\n\nUse a semver range for published service packages instead of `latest`, so OctoBus imports remain reproducible.\n\n```js\n#!/usr/bin/env node\n\nimport { defineService, grpcInvalidArgumentError, runServiceMain } from \"@chaitin-ai/octobus-sdk\";\n\nconst service = defineService({\n  handlers: {\n    \"calculator.v1.CalculatorService/Add\": (ctx) => {\n      const { left, right } = ctx.request;\n      if (left < 0 || right < 0) {\n        throw grpcInvalidArgumentError(\"inputs must be non-negative\");\n      }\n      return {\n        result: left + right,\n        requestId: ctx.getMetadata(\"x-request-id\") || \"\",\n      };\n    },\n  },\n});\n\nrunServiceMain(service);\n```\n\n`service.json` must not define `id` or `entry`. OctoBus assigns service ids during import, and the runtime entry is resolved from the distribution package root `package.json bin`. For a multi-service package, `service.json.name` must match the root `bin` object key for that service.\n\n## Local Development\n\nValidate package shape and proto loading:\n\n```bash\nnpx @chaitin-ai/octobus-sdk bootstrap --name @acme/echo-service --out ./echo-service\nnpx @chaitin-ai/octobus-sdk validate\nnpx @chaitin-ai/octobus-sdk inspect\nnpx @chaitin-ai/octobus-sdk inspect --yaml\nnpx @chaitin-ai/octobus-sdk inspect --config-schema\nnpx @chaitin-ai/octobus-sdk inspect --secret-schema --yaml\nnpx @chaitin-ai/octobus-sdk client-stub --transport connect > connect-client.js\nnpx @chaitin-ai/octobus-sdk client-stub --transport grpc > grpc-client.js\nnpx @chaitin-ai/octobus-sdk client-package \\\n  --transport connect \\\n  --name @acme/calculator-client \\\n  --out ./calculator-client\n```\n\nRun the service entry directly for a local gRPC server:\n\n```bash\nnode bin/calculator.js --runtime dev --port 50051 --config-json '{}'\n```\n\nPrint package schema files from the service entry when using the package as an `npx` command or local executable:\n\n```bash\nnode bin/calculator.js --runtime inspect --config-schema\nnode bin/calculator.js --runtime inspect --secret-schema\n```\n\nUse the package as a local CLI. When no `--runtime` prefix is present, `runServiceMain(service)` treats argv as business CLI commands generated from implemented unary gRPC methods:\n\n```bash\nnode bin/calculator.js --help\nnode bin/calculator.js add \\\n  --data-json '{\"left\":1,\"right\":2}' \\\n  --config-json '{}'\n```\n\nMethod help prints that command's JSON contract:\n\n```bash\nnode bin/calculator.js add --help\n```\n\nOctoBus itself calls `--runtime serve` for long-running instances and `--runtime invoke` for on-demand instances. These runtime commands are implemented by `runService` / `runServiceMain`.\n\nFor repeated local CLI or `--runtime dev` calls, provide config and secret through\n`OCTOBUS_SERVICE_CONTEXT` instead of repeating long flags:\n\n```bash\nOCTOBUS_SERVICE_CONTEXT='{\"config\":{\"label\":\"local\"},\"secret\":{\"apiToken\":\"dev-token\"}}' \\\nnode bin/calculator.js add --data-json '{\"left\":1,\"right\":2}'\n```\n\nThe SDK also reads `OCTOBUS_SERVICE_CONTEXT` from `.env` in the current working\ndirectory. Only that key is read; other `.env` entries are not injected. The\nvalue must be a JSON object with optional `config` and `secret` fields. Fields\nfrom the real environment override `.env`, and either source overrides the\nmatching `--config*` or `--secret*` CLI option independently. This context is\nnot used by `--runtime serve`, `--runtime invoke`, inspect, client generation,\nor the `octobus-sdk` developer CLI.\n\n## Connect RPC Client Stub\n\nThe SDK can build a Connect RPC client from a service package's protobuf descriptor. It calls OctoBus Connect JSON endpoints for the package's unary methods:\n\n```js\nimport { createConnectRpcStub } from \"@chaitin-ai/octobus-sdk\";\n\nconst client = createConnectRpcStub({\n  baseUrl: \"http://127.0.0.1:9000\",\n  capsetId: \"dev\",\n  instanceId: \"calculator-test\",\n});\n\nconst result = await client.services[\"calculator.v1.CalculatorService\"].Add({\n  left: 1,\n  right: 2,\n});\n```\n\nYou can also print a small ESM wrapper for the current service package:\n\n```bash\nnpx @chaitin-ai/octobus-sdk client-stub --transport connect --factory createCalculatorClient\n```\n\nThe generated wrapper exposes service aliases such as `CalculatorService.Add(...)` while delegating protobuf JSON conversion and HTTP calls to `createConnectRpcStub`.\n\nTo generate a complete npm client package that can be copied into a consumer project without the original service package or `protoc`:\n\n```bash\nnpx @chaitin-ai/octobus-sdk client-package \\\n  --transport connect \\\n  --name @acme/calculator-client \\\n  --out ./calculator-client \\\n  --factory createCalculatorClient\n```\n\nThe generated package contains `package.json`, `README.md`, `index.js`, `index.d.ts`, and descriptor assets under `descriptors/`. The generated `index.js` loads `descriptors/descriptor.pb` and `descriptors/service.json` relative to `import.meta.url`, then exposes aliases such as `client.CalculatorService.Add(...)`.\n\nBy default `client-package` only writes the package directory and dependency metadata. Use `--bundle-deps` to run `npm install --omit=dev` and mark runtime dependencies as bundled, or `--publish` to run `npm publish` in the generated directory with the current npm configuration.\n\n## gRPC Client Stub\n\nFor Node.js callers that need native gRPC, the SDK can print a small Promise-style wrapper for the current package:\n\n```bash\nnpx @chaitin-ai/octobus-sdk client-stub --transport grpc --factory createCalculatorGrpcClient > calculator-grpc-client.js\n```\n\nThe generated wrapper exposes service methods without requiring callers to pass method names as strings:\n\n```js\nimport { createCalculatorGrpcClient } from \"./calculator-grpc-client.js\";\n\nconst client = createCalculatorGrpcClient({\n  address: \"127.0.0.1:9000\",\n  capsetId: \"dev\",\n  serviceId: \"calculator\",\n  instanceId: \"calculator-test\",\n});\n\nconst result = await client.services[\"calculator.v1.CalculatorService\"].Add({\n  left: 1,\n  right: 2,\n});\n\nclient.close();\n```\n\nThe client injects OctoBus routing metadata when `capsetId`, `serviceId`, or `instanceId` are provided. Additional metadata can be supplied on the client or per call:\n\n```js\nawait client.CalculatorService.Add(\n  { left: 1, right: 2 },\n  { metadata: { \"x-request-id\": \"req-123\" } },\n);\n```\n\nThe generated wrapper exposes Promise methods such as `CalculatorService.Add(...)`, plus `raw` gRPC clients for callers that need `@grpc/grpc-js` directly.\n\nYou can also generate a descriptor-backed npm package:\n\n```bash\nnpx @chaitin-ai/octobus-sdk client-package \\\n  --transport grpc \\\n  --name @acme/calculator-grpc-client \\\n  --out ./calculator-grpc-client\n```\n\nThe gRPC generated package includes `@grpc/grpc-js` as a dependency and emits wrapper signatures for unary, server-streaming, client-streaming, and bidirectional-streaming methods based on the service definitions. Runtime streaming support is provided by `createGrpcStub`.\n\n## Handler Context\n\nHandlers receive:\n\n- `request`: decoded protobuf request object.\n- `metadata`: gRPC metadata with OctoBus control headers stripped. The SDK strips `x-octobus-*` control metadata and preserves `x-octobus-ext-*` business extension metadata such as `x-octobus-ext-username`.\n- `config` and `secret`: instance JSON values.\n- `method`: full method name, for example `calculator.v1.CalculatorService/Add`.\n- `serviceId`, `instanceId`, `workdir`, and `packageDir`: runtime identity and paths.\n- `getMetadata(name)` and `getMetadataAll(name)`: convenient metadata accessors.\n\n`--runtime serve` / `--runtime dev` support unary, server-streaming, client-streaming, and bidirectional-streaming handlers. `--runtime invoke` and the generated business CLI used without `--runtime` only support unary methods; streaming methods are reported by `validateService` and are not exposed as local CLI commands.\n\n## Errors\n\nThrow `GrpcError` or helper constructors to return specific gRPC status codes:\n\n```js\nimport { grpcNotFoundError, grpcPermissionDeniedError, grpcStatus, GrpcError } from \"@chaitin-ai/octobus-sdk\";\n\nthrow grpcNotFoundError(\"resource missing\");\nthrow grpcPermissionDeniedError(\"token rejected\");\nthrow new GrpcError(grpcStatus.UNAVAILABLE, \"upstream unavailable\");\n```\n\nOrdinary thrown errors are mapped to `INTERNAL`.\n\n## Install\n\n```bash\nnpm install @chaitin-ai/octobus-sdk\n```\n\nFor global CLI usage:\n\n```bash\nnpm install -g @chaitin-ai/octobus-sdk\n```\n\nThe package is published to npmjs under the existing `@chaitin-ai` scope.\n\n## Publish\n\nSDK releases are published to npmjs by the GitHub Actions workflow when a GitHub Release is published. The Release tag must use the `sdk-v<version>` format, and `<version>` must match `sdk/package.json.version` exactly. Repository administrators must configure the GitHub secret `NPM_TOKEN` with permission to publish `@chaitin-ai/octobus-sdk`.\n\n```bash\nnpm version 0.1.1 --prefix sdk --no-git-tag-version\ngit add sdk/package.json sdk/package-lock.json\ngit commit -m \"Release SDK 0.1.1\"\ngit tag sdk-v0.1.1\ngit push origin main sdk-v0.1.1\n```\n\nAfter pushing the tag, create and publish the GitHub Release for `sdk-v0.1.1`. Stable versions publish with npm's default `latest` dist-tag. Prerelease versions publish with the `next` dist-tag. Tags that do not match `sdk-v<version>` or do not match `sdk/package.json.version` fail before publishing.\n","readmeFilename":"README.md"}