@hesohq/sdk 0.4.0 → 0.4.1-dev.24

package/README.md

@@ -0,0 +1,88 @@
+# @hesohq/sdk
+
+**The compliance layer for AI agents, for Node.** Verify heso **Action Receipts**,
+enforce a minimum trust level, gate a Node agent's actions against policy, and push
+receipts to the cloud outbox — with the native verifier bundled (zero crypto in
+TypeScript).
+
+You hold the signing keys. heso's cloud can verify and mirror receipts but can
+**never forge one** — so anyone (a customer, an auditor, a court) can check exactly
+what your agent did, and that it was authorized, without trusting heso at all.
+
+- **Site** · [heso.ca](https://www.heso.ca)
+- **Docs** · [heso.ca/docs](https://www.heso.ca/docs)
+- **Verify a receipt (no account)** · [heso.ca/verify](https://www.heso.ca/verify)
+
+```sh
+npm install @hesohq/sdk      # or: pnpm add @hesohq/sdk   (Node 18+)
+```
+
+The native verifier (`@hesohq/node`) is pulled in automatically — verification runs
+locally and offline. A cloud API key is needed only for the cloud client
+(`pushReceipt`, `pollApproval`, and friends).
+
+## Verify a receipt
+
+```ts
+import { gate } from '@hesohq/sdk'
+
+const result = gate(receipt, { minTrust: 'L1' })
+// → { verdict: 'Valid', trust: 'L1', ... }   re-runs hash + signature math locally
+```
+
+Throw on anything below your bar:
+
+```ts
+import { assertGate } from '@hesohq/sdk'
+
+assertGate(receipt, { minTrust: 'L1' })   // raises unless Valid and ≥ L1
+```
+
+Or branch on the decision:
+
+```ts
+import { isDecisionAllowed } from '@hesohq/sdk'
+import type { ActionReceipt } from '@hesohq/sdk'
+
+if (isDecisionAllowed(receipt)) { /* ... */ }
+```
+
+## Gate a Node agent
+
+```ts
+import { wrap, pushReceipt } from '@hesohq/sdk'
+
+const guarded = wrap(agentClient, {
+  onReceipt: async (receiptJson) => {
+    await pushReceipt(JSON.parse(receiptJson))   // server re-verifies before mirroring
+  },
+})
+```
+
+There are also thin adapters for the **AI SDK** (`aiSdk`) and **Mastra** (`mastra`),
+all built on the same `engine.gate` core.
+
+## Push to the cloud outbox
+
+```ts
+import { configure, pushReceipt } from '@hesohq/sdk'
+
+configure(process.env.HESO_API_KEY!, 'https://api.heso.ca')
+
+const result = await pushReceipt(receipt)   // server re-verifies, then mirrors
+```
+
+`pushReceipts` takes an array for batches. The cloud holds no signing keys — it only
+verifies and mirrors what you've already signed.
+
+## Trust model
+
+heso proves an action was **authorized** under policy, and at L1 that an authorized
+human **approved or blocked** it. It does **not** prove the action's outcome was
+truthful — that's unprovable from the artifact. Trust grades are L0 (operator) and
+L1 (operator + human approver). The receipt format is specified in
+[`ACTION-RECEIPT-1.0`](https://github.com/heso-inc/heso).
+
+---
+
+Proprietary. See [heso.ca](https://www.heso.ca) for licensing and the hosted console.

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@hesohq/sdk",
-  "version": "0.4.0",
-  "description": "HESO Enterprise SDK — thin TypeScript wrapper over @hesohq/core with gating helpers, cloud client, and wire types",
+  "version": "0.4.1-dev.24",
+  "description": "The compliance layer for AI agents (Node) — verify heso Action Receipts, gate agent actions against policy, and push receipts to the cloud.",
+  "homepage": "https://www.heso.ca",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heso-inc/heso.git"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -15,13 +20,14 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
-    "@hesohq/core": "0.4.0"
+    "@hesohq/core": "0.4.1-dev.24"
   },
   "optionalDependencies": {
-    "@hesohq/node": "0.4.0"
+    "@hesohq/node": "0.4.1-dev.24"
   },
   "devDependencies": {
     "typescript": "^5",