{"_id":"@0xhoneyjar/beacon-schema","name":"@0xhoneyjar/beacon-schema","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@0xhoneyjar/beacon-schema","version":"0.1.0","description":"Sealed Effect Schema for the Freeside MCP federation beacon contract. Cycle C base · Cycle D extends with docs.* additively.","license":"MIT","type":"module","main":"./dist/src/index.js","types":"./dist/src/index.d.ts","exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"}},"bin":{"build-beacon-json":"dist/bin/build-beacon-json.js"},"scripts":{"build":"tsc -b","typecheck":"tsc --noEmit","clean":"rm -rf dist","test":"tsx --test tests/*.test.ts"},"peerDependencies":{"effect":"^3.10.0"},"dependencies":{"yaml":"^2.6.0"},"devDependencies":{"effect":"^3.10.0","tsx":"^4.20.0","typescript":"^5.4.0","@types/node":"^22.0.0"},"publishConfig":{"access":"public"},"_id":"@0xhoneyjar/beacon-schema@0.1.0","gitHead":"d83b6e5badd414efddda61712e9475b0275d6029","_nodeVersion":"23.3.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-8kFQJih9MIiciTXBTeZNwVkuZK97ZVNE9ytVpEk9zxiyn+itfqsF0zatqf6OThkaaFsAiBrthcqff5mIG40T5w==","shasum":"42a4bfcf3e5b0a5eb69da3f006c71db6de5f8396","tarball":"https://registry.npmjs.org/@0xhoneyjar/beacon-schema/-/beacon-schema-0.1.0.tgz","fileCount":23,"unpackedSize":168166,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGAe74dpt5a5GwnhE/ENCJzCl3ye34ZFxwrgip9rRITXAiEAluQUJoSBCZhQRwWfYu7QmqxFIx6hlsJH+AICfkxw1dA="}]},"_npmUser":{"name":"zksoju","email":"underrated@gmail.com"},"directories":{},"maintainers":[{"name":"janitooor","email":"jani@0xhoneyjar.xyz"},{"name":"zerkereth","email":"zerkereth@gmail.com"},{"name":"zksoju","email":"underrated@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/beacon-schema_0.1.0_1777848127264_0.1038048041522932"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T22:42:07.170Z","0.1.0":"2026-05-03T22:42:07.414Z","modified":"2026-05-03T22:42:07.651Z"},"maintainers":[{"name":"janitooor","email":"jani@0xhoneyjar.xyz"},{"name":"zerkereth","email":"zerkereth@gmail.com"},{"name":"zksoju","email":"underrated@gmail.com"}],"description":"Sealed Effect Schema for the Freeside MCP federation beacon contract. Cycle C base · Cycle D extends with docs.* additively.","license":"MIT","readme":"# @0xhoneyjar/beacon-schema\n\nSealed Effect Schema for the Freeside MCP federation **beacon contract**. Workspace package inside `freeside-mcp-gateway/packages/beacon-schema/`.\n\n> Cycle C v0.3 broadcast layer · base shape (`schema_version: \"2\"`).\n> Cycle D extends the `docs.*` block additively (no breaking change · v0.2.0 bump).\n\n## Disambiguation\n\nTwo names look similar — they are not the same thing.\n\n| Name | What | Where | Audience |\n|---|---|---|---|\n| **`construct-beacon`** | Construct in the constructs-network registry · ships SKILLS for AI-content-readability + MCP-codegen authoring (`auditing-content`, `defining-mcp-tools`, `generating-markdown`, `accepting-payments`) | constructs.network | Authors writing a `beacon.yaml` for their MCP construct |\n| **`@0xhoneyjar/beacon-schema`** | npm package · sealed Effect Schema for `BeaconV2Schema` runtime validation + JSON Schema export + `build-beacon-json` CLI | npm registry · gateway monorepo | Gateway implementation + construct build steps + future external integrators |\n\nRead it as: **`construct-beacon` HELPS YOU AUTHOR a beacon.yaml; `@0xhoneyjar/beacon-schema` VALIDATES that your beacon.yaml conforms to the federation contract.**\n\n## Install\n\n```bash\npnpm add -D @0xhoneyjar/beacon-schema\n# requires effect ^3.10.0 as peerDep\n```\n\n## Use · validate a beacon at runtime\n\n```typescript\nimport { BeaconV2Schema, decodeBeacon } from \"@0xhoneyjar/beacon-schema\";\nimport { Effect } from \"effect\";\n\nconst result = await Effect.runPromise(\n  decodeBeacon(JSON.parse(rawBeaconJson))\n);\n// result is a typed BeaconV2 · throws on invalid input\n```\n\n## Use · YAML→JSON adapter (build step)\n\n```bash\nnpx build-beacon-json --in beacon.yaml --out app/.well-known/beacon.json\n```\n\nWired into each construct's `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"build:beacon\": \"build-beacon-json --in beacon.yaml --out app/.well-known/beacon.json\"\n  }\n}\n```\n\nExit codes:\n\n| Code | Meaning |\n|---|---|\n| `0` | Validation passed · JSON written |\n| `1` | Validation failed · ParseError on stderr |\n| `2` | Usage error (missing `--in` / `--out`) |\n\n## Use · JSON Schema export\n\n```typescript\nimport { BeaconV2JsonSchema } from \"@0xhoneyjar/beacon-schema\";\n// canonical JSON Schema · publish at /.well-known/beacon-schema/v2.json\n```\n\n## Schema shape (v2)\n\n```yaml\n# beacon.yaml v2 · minimal\nschema_version: \"2\"\nmcp:\n  shape: data | tool | proxy\n  paths: [stdio, remote-http]\n  remote: { transport: streamable-http, endpoint: ... }    # required if paths includes remote-http\n  auth: { kind: none | api-key, header?, credentials_ref? }\n  capabilities: [tools, resources, prompts, sampling, logging]\n  tools: [...]\n  pricing: { model: free | per-call | subscription | pay-per-call, description }\n  publisher: <org>\n```\n\n### Auth refine rules\n\n| `auth.kind` | `header` | `credentials_ref` |\n|---|---|---|\n| `none` | MUST be omitted | MUST be omitted |\n| `api-key` | REQUIRED | REQUIRED |\n| `jwt`, `oauth` | reserved · v0.3 schema accepts but gateway throws `CredentialResolverNotImplemented` at boot |\n\n### `credentials_ref.key` convention\n\nSCREAMING_SNAKE_CASE only (Railway env-var pattern · max 128 chars).\n\n### `docs:` block\n\nCycle C ships `docs: Schema.optional(Schema.Unknown)` — accepts any docs payload during the transition. Cycle D files an additive PR replacing `Schema.Unknown` with a concrete `DocsBlockSchema` (tagline + example_invocations + assets + changelog_url). See [Cycle D coordination contract](../../grimoires/bonfire/specs/freeside-mcp-federation-docs-dx-sdd-2026-05-03.md).\n\n## Develop\n\n```bash\npnpm install        # from repo root · workspace setup\npnpm typecheck      # tsc --noEmit\npnpm build          # tsc -b → dist/\npnpm test           # tsx --test tests/*.test.ts (14 tests)\n```\n\n## Versioning\n\n| Version | Cycle | Change |\n|---|---|---|\n| `0.1.0` | Cycle C v0.3 (this) | Base BeaconV2Schema · mcp + cli + payment + auth + credentials_ref · docs:Schema.Unknown placeholder |\n| `0.2.0` | Cycle D (planned · additive PR) | Replaces `docs: Schema.Unknown` with `DocsBlockSchema` (tagline + example_invocations + assets + changelog_url) |\n| `1.0.0` | After v0.3 stable | Promote to 1.0 once schema is exercised by 3+ tenants in production |\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-57cdfb4d1f9513cda0795a62d9df2c5c"}