{"_id":"@cognizhi/heeczer-sdk","name":"@cognizhi/heeczer-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@cognizhi/heeczer-sdk","version":"0.1.0","description":"JavaScript/TypeScript client for the ai-heeczer ingestion service.","license":"MIT","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.build.json","test":"vitest run","typecheck":"tsc -p tsconfig.json --noEmit"},"engines":{"node":">=20"},"devDependencies":{"typescript":"^5.6.0","vitest":"^2.1.0"},"gitHead":"03afaf206fc0c08d40d100966c72169dc074d1d9","_id":"@cognizhi/heeczer-sdk@0.1.0","_nodeVersion":"22.17.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-gfI5QkLynDT/xSGvD2o0BQuEvGRJlkWdFv6z15RYjlslWdvGKvTP5fYb4VBv5yel/HiWoy0DR0yewrtglkI/PQ==","shasum":"465498863d6453f75ee757d5be4f354c45234cf2","tarball":"https://registry.npmjs.org/@cognizhi/heeczer-sdk/-/heeczer-sdk-0.1.0.tgz","fileCount":4,"unpackedSize":12677,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC0BqM6qgZ7gqlwgDFV2TNXdj0tAEfXAT0+q0WnqOjPvwIgVDRw9vjLhOvmimxk2oJC3Zatx2CrvLzG62CGOiDzo4U="}]},"_npmUser":{"name":"cognitionseed","email":"cognytiq@hotmail.com"},"directories":{},"maintainers":[{"name":"cognitionseed","email":"cognytiq@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/heeczer-sdk_0.1.0_1776950175679_0.8069350783546152"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-23T13:16:15.589Z","0.1.0":"2026-04-23T13:16:15.849Z","modified":"2026-04-23T13:16:16.054Z"},"maintainers":[{"name":"cognitionseed","email":"cognytiq@hotmail.com"}],"description":"JavaScript/TypeScript client for the ai-heeczer ingestion service.","license":"MIT","readme":"# @cognizhi/heeczer-sdk\n\nJavaScript / TypeScript client for the [ai-heeczer](https://github.com/cognizhi/ai-heeczer) ingestion service.\n\n> ⚠️ Pre-1.0 surface. The HTTP envelope contract (envelope_version `1`) is\n> stable; the typed wrapper API may evolve until we ship `1.0.0`.\n\n## Install\n\n> **Pre-release.** `@cognizhi/heeczer-sdk` is not on the npm registry yet (see\n> plan 0012). Until then, install from source via the runnable example\n> below.\n\n```bash\npnpm add @cognizhi/heeczer-sdk\n```\n\nRequires Node.js ≥ 20 (the SDK uses the global `fetch`).\n\n## Usage\n\n```ts\nimport { HeeczerClient } from \"@cognizhi/heeczer-sdk\";\n\nconst client = new HeeczerClient({\n  baseUrl: \"https://ingest.example.com\",\n  apiKey: process.env.HEECZER_API_KEY,\n});\n\nconst { score } = await client.ingestEvent({\n  workspaceId: \"ws_default\",\n  event: canonicalEvent, // see core/schema/event.v1.json\n});\n\nconsole.log(score.final_estimated_minutes, score.confidence_band);\n```\n\n## Error handling\n\nEvery client method throws `HeeczerApiError` on a non-2xx response. The error\nexposes the closed `kind` enum from the ingestion service's envelope:\n\n```ts\nimport { HeeczerApiError } from \"@cognizhi/heeczer-sdk\";\n\ntry {\n  await client.ingestEvent({ workspaceId: \"ws\", event: badEvent });\n} catch (err) {\n  if (err instanceof HeeczerApiError && err.kind === \"schema\") {\n    // …\n  }\n}\n```\n\n## Configuration\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `baseUrl` | `string` | required | Base URL of the ingestion service. Trailing slash is stripped. |\n| `apiKey` | `string \\| undefined` | `undefined` | Sent as `x-heeczer-api-key`. |\n| `fetch` | `typeof fetch` | `globalThis.fetch` | Inject a custom `fetch` (e.g. `undici.fetch`, mocks in tests). |\n\n## Methods\n\n| Method | HTTP | Returns |\n| --- | --- | --- |\n| `healthz()` | `GET /healthz` | `Promise<boolean>` |\n| `version()` | `GET /v1/version` | `Promise<VersionResponse>` |\n| `ingestEvent({ workspaceId, event })` | `POST /v1/events` | `Promise<IngestEventResponse>` |\n| `testScorePipeline({ event, profile?, tierSet?, tierOverride? })` | `POST /v1/test/score-pipeline` | `Promise<{ ok: true; envelope_version: \"1\"; score: ScoreResult }>` (gated by the test-orchestration feature flag) |\n\n## Error kinds\n\n`HeeczerApiError.kind` is a closed string union mirroring the ingestion\nservice envelope:\n\n| Kind | When |\n| --- | --- |\n| `schema` | Event failed canonical schema validation. |\n| `bad_request` | Malformed JSON or missing top-level fields. |\n| `scoring` | Engine rejected a normalized event (e.g. unknown tier id). |\n| `storage` | Persistence layer error. |\n| `not_found` | Read endpoint did not find the resource. |\n| `forbidden` | Auth or RBAC denied the request. |\n| `feature_disabled` | Endpoint exists but the feature flag is off. |\n| `unknown` | Non-JSON 5xx body; the raw text is in `message`. |\n\n## Runnable example\n\nSee [`examples/node/quickstart.mjs`](../../examples/node/quickstart.mjs)\nand the cross-language index in [`examples/README.md`](../../examples/README.md).\n\n## Common patterns\n\n**Validate locally before sending** (avoids a network round-trip on bad\nevents). The schema is JSON Schema Draft 2020-12; any compliant library\nworks — example with `ajv`:\n\n```ts\nimport Ajv from \"ajv/dist/2020\";\nimport { readFileSync } from \"fs\";\n\nconst schema = JSON.parse(readFileSync(\"core/schema/event.v1.json\", \"utf8\"));\nconst validate = new Ajv().compile(schema);\nif (!validate(event)) throw new Error(new Ajv().errorsText(validate.errors));\n```\n\n**Surface schema field errors from the service:**\n\n```ts\ntry {\n  await client.ingestEvent({ workspaceId: \"ws\", event });\n} catch (err) {\n  if (err instanceof HeeczerApiError && err.kind === \"schema\") {\n    // err.message contains the field-level detail from the server envelope.\n    console.error(\"schema rejection:\", err.message);\n  }\n}\n```\n\n**Batching note.** `POST /v1/events:batch` (single-transaction,\npartial-success semantics) is planned but not yet shipped — see\n[plan 0004](../../docs/plan/0004-ingestion-service.md). Until then,\nsend events sequentially or in parallel with `Promise.allSettled()`.\n\n## Contract\n\nThe SDK speaks `envelope_version: \"1\"` to the ingestion service, which\nmirrors the C ABI envelope contract documented in\n[ADR-0011](../../docs/adr/0011-c-abi-envelope.md). Additive fields land\nwithout breaking the typed surface (the `ScoreResult` interface keeps an\nopen index signature).\n\n## License\n\nMIT.\n","readmeFilename":"README.md","_rev":"1-bed6aee0d3d42a35abd2557158620bdc"}