@ahtmljs/schema 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +80 -0
  2. package/package.json +33 -4
package/README.md ADDED
@@ -0,0 +1,80 @@
1
+ # @ahtmljs/schema
2
+
3
+ Types, runtime validator, JSON + token-optimal compact text formatters,
4
+ structural diff, and snapshot builder DSL for **[AHTML](https://github.com/DibbayajyotiRoy/AHTML)**
5
+ — the HTML of the agent web.
6
+
7
+ ```bash
8
+ npm install @ahtmljs/schema
9
+ ```
10
+
11
+ ## What this package gives you
12
+
13
+ - **TypeScript types** for `Snapshot`, six entity primitives (`Product`,
14
+ `Document`, `Task`, `Profile`, `Dataset`, `Conversation`), `Action`,
15
+ `Policy`, `Provenance`, `Links`, `SnapshotDiff`.
16
+ - **`snapshot()` builder DSL** — fluent API to compose a typed snapshot.
17
+ - **Zero-dependency runtime validator** that returns a list of structured
18
+ issues with `path` + `severity`.
19
+ - **Two serializations**:
20
+ - `toJson(s)` / `fromJson(text)` — canonical JSON, deterministic, signable.
21
+ - `toCompact(s)` / `fromCompact(text)` — token-optimal text, round-trips losslessly.
22
+ - **`diff(prev, next)` / `applyDiff(prev, d)`** — structural snapshot diffing.
23
+ - **`computeEtag(s)`** — content-addressed weak ETag.
24
+ - **JSON Schema 2020-12 spec** at `./src/schema.json`.
25
+
26
+ ## Quickstart
27
+
28
+ ```ts
29
+ import { snapshot, toCompact, toJson, validate } from '@ahtmljs/schema';
30
+
31
+ const snap = snapshot('https://shop.com/products/mbp-14', 'product_detail')
32
+ .ttl(60)
33
+ .policy({ agents_welcome: true, license: 'MIT', rate_limit: '100/min' })
34
+ .add({
35
+ id: 'product:mbp-14',
36
+ type: 'product',
37
+ name: 'MacBook Pro 14"',
38
+ price: { amount: 1999, currency: 'USD' },
39
+ stock: { status: 'in_stock', quantity: 42 },
40
+ })
41
+ .action({
42
+ id: 'purchase',
43
+ target: 'product:mbp-14',
44
+ category: 'transact',
45
+ execute_url: '/api/checkout',
46
+ auth: 'required',
47
+ cost: { amount: 1999, currency: 'USD', category: 'purchase' },
48
+ reversible: { reversible: true, window: 'P30D', policy: 'full_refund' },
49
+ side_effects: ['charge_card', 'email_buyer', 'decrement_stock'],
50
+ confirmation: 'required',
51
+ })
52
+ .build();
53
+
54
+ console.log(toCompact(snap)); // token-optimal text — default for LLM agents
55
+ console.log(toJson(snap)); // canonical JSON — sign-able
56
+
57
+ const issues = validate(snap);
58
+ if (issues.some((i) => i.severity === 'error')) throw new Error('invalid');
59
+ ```
60
+
61
+ ## What is AHTML?
62
+
63
+ AHTML turns any website into an MCP server, an OpenAPI provider, a
64
+ JSON-LD source, and a token-optimal semantic snapshot — from one plugin.
65
+ This package is the schema underneath. Most users want
66
+ [`@ahtmljs/next`](https://www.npmjs.com/package/@ahtmljs/next) (the
67
+ Next.js plugin) or [`@ahtmljs/agent`](https://www.npmjs.com/package/@ahtmljs/agent)
68
+ (the client SDK).
69
+
70
+ ## Documentation
71
+
72
+ - **Repository:** [`DibbayajyotiRoy/AHTML`](https://github.com/DibbayajyotiRoy/AHTML)
73
+ - **Spec:** [`SPEC.md`](https://github.com/DibbayajyotiRoy/AHTML/blob/main/SPEC.md)
74
+ - **Plan / roadmap:** [`PLAN.md`](https://github.com/DibbayajyotiRoy/AHTML/blob/main/PLAN.md)
75
+ - **For AI assistants:** [`docs/agents.md`](https://github.com/DibbayajyotiRoy/AHTML/blob/main/docs/agents.md)
76
+ - **Comparison vs MCP / llms.txt / schema.org / OpenAPI:** [`docs/compare.md`](https://github.com/DibbayajyotiRoy/AHTML/blob/main/docs/compare.md)
77
+
78
+ ## License
79
+
80
+ MIT
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@ahtmljs/schema",
3
- "version": "0.1.0",
4
- "description": "AHTML semantic snapshot schema — types, validator, builder, and dual-format serializers (JSON + token-optimal compact text).",
3
+ "version": "0.1.1",
4
+ "description": "AHTML semantic snapshot schema — types, validator, builder, and dual-format serializers (JSON + token-optimal compact text). The agent-readable contract layer for the web.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
7
7
  "types": "./dist/index.d.ts",
@@ -12,12 +12,41 @@
12
12
  },
13
13
  "./schema.json": "./src/schema.json"
14
14
  },
15
- "files": ["dist", "src/schema.json"],
15
+ "files": ["dist", "src/schema.json", "README.md"],
16
16
  "publishConfig": { "access": "public" },
17
17
  "scripts": {
18
18
  "build": "tsc -p tsconfig.json",
19
19
  "dev": "tsc -p tsconfig.json --watch"
20
20
  },
21
- "keywords": ["ahtml", "agent", "semantic-web", "ai", "llm", "crawler", "mcp"],
21
+ "repository": {
22
+ "type": "git",
23
+ "url": "git+https://github.com/DibbayajyotiRoy/AHTML.git",
24
+ "directory": "packages/schema"
25
+ },
26
+ "homepage": "https://github.com/DibbayajyotiRoy/AHTML#readme",
27
+ "bugs": {
28
+ "url": "https://github.com/DibbayajyotiRoy/AHTML/issues",
29
+ "email": "rdibbayajyoti@gmail.com"
30
+ },
31
+ "author": {
32
+ "name": "Dibbayajyoti Roy",
33
+ "email": "rdibbayajyoti@gmail.com",
34
+ "url": "https://github.com/DibbayajyotiRoy"
35
+ },
36
+ "keywords": [
37
+ "ahtml",
38
+ "agent",
39
+ "agent-web",
40
+ "semantic-web",
41
+ "ai",
42
+ "llm",
43
+ "crawler",
44
+ "mcp",
45
+ "model-context-protocol",
46
+ "llms-txt",
47
+ "json-ld",
48
+ "schema",
49
+ "openapi"
50
+ ],
22
51
  "license": "MIT"
23
52
  }