@jsonfirst/sdk 1.2.0 → 1.4.0

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 +102 -25
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,51 +1,131 @@
1
1
  # @jsonfirst/sdk
2
2
 
3
- Official JavaScript/Node.js SDK for the **JSONFIRST Protocol** — the Universal Intent Protocol for AI governance.
4
-
5
- ## Installation
3
+ **Stop writing brittle prompts.**
4
+ JSONFIRST turns any user input into a structured, validated JSON intent your agent can execute reliably.
6
5
 
7
6
  ```bash
8
7
  npm install @jsonfirst/sdk
9
8
  ```
10
9
 
10
+ ---
11
+
12
+ ## The problem it solves
13
+
14
+ **Without JSONFIRST** — your agent gets this:
15
+
16
+ ```
17
+ "create an order for john, 2 units of product A, ship it fast"
18
+ ```
19
+
20
+ Your code parses free text. Edge cases break it. You write regex. It still breaks.
21
+
22
+ **With JSONFIRST** — your agent gets this:
23
+
24
+ ```json
25
+ {
26
+ "spec": "JSONFIRST",
27
+ "version": "2.0",
28
+ "jdons": [{
29
+ "action": { "normalized": "create" },
30
+ "object": { "type": "order", "customer": "john", "quantity": 2, "product": "product_A" },
31
+ "constraints": { "shipping": "express" },
32
+ "execution": { "parsable": true, "executable": true }
33
+ }]
34
+ }
35
+ ```
36
+
37
+ Structured. Validated. Executable. Every time.
38
+
39
+ ---
40
+
11
41
  ## Quick Start
12
42
 
43
+ **Step 1 — Get your API key at [jsonfirst.com/developers](https://jsonfirst.com/developers)**
44
+
45
+ **Step 2 — Install and parse**
46
+
13
47
  ```javascript
14
48
  const JsonFirst = require('@jsonfirst/sdk');
15
49
 
16
50
  const client = new JsonFirst({ apiKey: 'YOUR_API_KEY' });
17
51
 
18
- // Parse a natural language intent
19
- const result = await client.parse('Create a new order for John Smith, 2 units of product A');
20
- console.log(result);
21
-
22
- // Validate a JSONFIRST JSON
23
- const { valid, errors } = client.validate(result);
24
- console.log(valid, errors);
52
+ const result = await client.parse('Create an order for John, 2 units of product A');
53
+ console.log(result.jdons[0].action.normalized); // "create"
54
+ console.log(result.jdons[0].object); // { type: "order", ... }
25
55
  ```
26
56
 
57
+ ---
58
+
27
59
  ## Methods
28
60
 
29
61
  | Method | Description |
30
62
  |--------|-------------|
31
- | `parse(text, options?)` | Convert natural language to JSONFIRST JSON |
32
- | `validate(json)` | Validate a JSON against the JSONFIRST spec |
63
+ | `parse(text, options?)` | Convert natural language to a validated JSONFIRST JSON |
64
+ | `validate(json)` | Validate a JSON against the JSONFIRST v2 spec |
65
+ | `validateIntent(intent, options?)` | Validate a single JDON intent (confidence, params, executability) |
33
66
  | `pull(schemaId)` | Fetch a publicly shared schema |
34
67
  | `share(outputJson, title?)` | Share a schema and get a public link |
35
- | `usage()` | Get your account usage stats |
68
+ | `usage()` | Get your account usage and remaining intents |
69
+ | `modes()` | List all 22 governance modes with metadata |
70
+ | `modeIds()` | List all 22 mode IDs as an array |
71
+
72
+ ---
73
+
74
+ ## Recoverable Agents — Full Pipeline
75
+
76
+ JSONFIRST closes the full loop: `intent → validation → snapshot → execution → receipt → rollback`
36
77
 
37
- ## Options
78
+ ### 1. Snapshot (before execution)
38
79
 
39
80
  ```javascript
40
- const client = new JsonFirst({
41
- apiKey: 'YOUR_API_KEY',
42
- baseUrl: 'https://jsonfirst.com' // optional override
81
+ const snap = await client.snapshot({
82
+ jdon_id: 'jdon_abc123',
83
+ description: 'before delete user 1234',
84
+ state: { user_id: '1234', status: 'active', balance: 500 },
85
+ rollback_webhook: 'https://yourapp.com/webhooks/rollback' // optional
43
86
  });
87
+ // → { snapshot_id: 'uuid', status: 'AVAILABLE' }
44
88
  ```
45
89
 
90
+ ### 2. Receipt (after execution — verify intent match)
91
+
92
+ ```javascript
93
+ const receipt = await client.receipt({
94
+ jdon_id: 'jdon_abc123',
95
+ output_summary: 'User 1234 deleted from production database',
96
+ mode: 'PRODUCTION_LOCK',
97
+ original_intent: result // the JSONFIRST parse output
98
+ });
99
+ // → { intent_match_score: 0.95, verification_status: 'VERIFIED', drift_detected: false }
100
+ // or → { verification_status: 'INTENT_MISMATCH', flags: ['ROLLBACK_SUGGESTED'] }
101
+ ```
102
+
103
+ ### 3. Rollback (if drift detected)
104
+
105
+ ```javascript
106
+ if (receipt.receipt.flags.includes('ROLLBACK_SUGGESTED')) {
107
+ const rb = await client.rollback({
108
+ snapshot_id: snap.snapshot_id,
109
+ reason: 'INTENT_MISMATCH_DETECTED'
110
+ });
111
+ // → { status: 'ROLLED_BACK', restored_state: { user_id: '1234', ... } }
112
+ // Webhook fired automatically if configured
113
+ }
114
+ ```
115
+
116
+ ---
117
+
46
118
  ## Governance Modes
47
119
 
48
- All 22 modes are available via `JsonFirst.MODES` or `client.modes()`.
120
+ 22 modes ship with this SDK. Pass `execution_mode` to `parse()` to activate.
121
+
122
+ ```javascript
123
+ const result = await client.parse('Delete user 1234', {
124
+ execution_mode: 'GUARDIAN_MODE' // blocks risky actions until confirmed
125
+ });
126
+
127
+ console.log(JsonFirst.MODE_IDS); // all 22 mode IDs
128
+ ```
49
129
 
50
130
  | Mode | Plan | Category |
51
131
  |------|------|----------|
@@ -72,18 +152,15 @@ All 22 modes are available via `JsonFirst.MODES` or `client.modes()`.
72
152
  | `BUSINESS_STRATEGY_EXPERT` | business+ | domain_lock |
73
153
  | `DATA_SCIENCE_EXPERT` | business+ | domain_lock |
74
154
 
75
- ```javascript
76
- // Access modes programmatically
77
- const JsonFirst = require('@jsonfirst/sdk');
78
- console.log(JsonFirst.MODE_IDS); // array of 22 mode IDs
79
- console.log(JsonFirst.MODES['MEDICAL_EXPERT']); // { plan, category, description }
80
- ```
155
+ ---
81
156
 
82
157
  ## Links
83
158
 
159
+ - [Get your API key](https://jsonfirst.com/developers)
84
160
  - [Documentation](https://jsonfirst.com/developers)
85
- - [Templates](https://jsonfirst.com/templates)
161
+ - [LLM Implants](https://www.npmjs.com/package/@jsonfirst/implants)
86
162
  - [GitHub](https://github.com/jsonfirst/sdk)
163
+ - [Protocol spec](https://jsonfirst.com)
87
164
 
88
165
  ## License
89
166
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jsonfirst/sdk",
3
- "version": "1.2.0",
3
+ "version": "1.4.0",
4
4
  "description": "Official JavaScript/Node.js SDK for the JSONFIRST Protocol — Universal Intent Protocol for AI governance",
5
5
  "main": "index.js",
6
6
  "files": [