@jsonfirst/sdk 1.1.0 → 1.3.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 (3) hide show
  1. package/README.md +87 -18
  2. package/index.js +50 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,53 +1,122 @@
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 |
36
71
 
37
- ## Options
72
+ ---
73
+
74
+ ## Governance Modes
75
+
76
+ 22 modes ship with this SDK. Pass `execution_mode` to `parse()` to activate.
38
77
 
39
78
  ```javascript
40
- const client = new JsonFirst({
41
- apiKey: 'YOUR_API_KEY',
42
- baseUrl: 'https://jsonfirst.com' // optional override
79
+ const result = await client.parse('Delete user 1234', {
80
+ execution_mode: 'GUARDIAN_MODE' // blocks risky actions until confirmed
43
81
  });
82
+
83
+ console.log(JsonFirst.MODE_IDS); // all 22 mode IDs
44
84
  ```
45
85
 
86
+ | Mode | Plan | Category |
87
+ |------|------|----------|
88
+ | `ANTI_CREDIT_WASTE_V2` | free+ | efficiency |
89
+ | `EXPRESS_ROUTE` | explorer+ | speed |
90
+ | `STRICT_PROTOCOL` | explorer+ | compliance |
91
+ | `PERFORMANCE_MAX` | explorer+ | performance |
92
+ | `GUARDIAN_MODE` | explorer+ | safety |
93
+ | `FINANCE_ALGO` | explorer+ | finance |
94
+ | `ETHICAL_LOCK` | explorer+ | ethics |
95
+ | `SCOPE_LIMITER` | pro+ | governance |
96
+ | `SAFE_DEPLOY` | pro+ | deployment |
97
+ | `STANDARD_DEPLOY` | pro+ | deployment |
98
+ | `FAST_BUILD` | pro+ | build |
99
+ | `PRODUCTION_LOCK` | pro+ | deployment |
100
+ | `MEDICAL_EXPERT` | business+ | domain_lock |
101
+ | `LEGAL_EXPERT` | business+ | domain_lock |
102
+ | `FINANCE_EXPERT` | business+ | domain_lock |
103
+ | `CYBERSECURITY_EXPERT` | business+ | domain_lock |
104
+ | `SOFTWARE_ENGINEERING_EXPERT` | business+ | domain_lock |
105
+ | `AI_RESEARCH_EXPERT` | business+ | domain_lock |
106
+ | `NEWS_ANALYSIS_EXPERT` | business+ | domain_lock |
107
+ | `SCIENTIFIC_RESEARCH_EXPERT` | business+ | domain_lock |
108
+ | `BUSINESS_STRATEGY_EXPERT` | business+ | domain_lock |
109
+ | `DATA_SCIENCE_EXPERT` | business+ | domain_lock |
110
+
111
+ ---
112
+
46
113
  ## Links
47
114
 
115
+ - [Get your API key](https://jsonfirst.com/developers)
48
116
  - [Documentation](https://jsonfirst.com/developers)
49
- - [Templates](https://jsonfirst.com/templates)
117
+ - [LLM Implants](https://www.npmjs.com/package/@jsonfirst/implants)
50
118
  - [GitHub](https://github.com/jsonfirst/sdk)
119
+ - [Protocol spec](https://jsonfirst.com)
51
120
 
52
121
  ## License
53
122
 
package/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @jsonfirst/sdk v1.0.0
2
+ * @jsonfirst/sdk v1.2.0
3
3
  * Official JavaScript/Node.js SDK for the JSONFIRST Protocol
4
4
  *
5
5
  * Usage:
@@ -21,6 +21,36 @@
21
21
 
22
22
  const DEFAULT_BASE_URL = 'https://jsonfirst.com';
23
23
 
24
+ // All 22 governance modes
25
+ const MODES = {
26
+ // Base modes (all plans)
27
+ ANTI_CREDIT_WASTE_V2: { plan: 'free+', category: 'efficiency', description: 'Anti-token-waste enforcement. Minimal, direct, single-pass.' },
28
+ EXPRESS_ROUTE: { plan: 'explorer+', category: 'speed', description: 'Ultra-low latency routing. Fastest path to response.' },
29
+ STRICT_PROTOCOL: { plan: 'explorer+', category: 'compliance', description: 'Enforces strict JSONFIRST spec compliance on all outputs.' },
30
+ PERFORMANCE_MAX: { plan: 'explorer+', category: 'performance', description: 'Maximum throughput. Optimized for high-volume workloads.' },
31
+ GUARDIAN_MODE: { plan: 'explorer+', category: 'safety', description: 'Safety lock. Blocks risky actions until explicit confirmation.' },
32
+ FINANCE_ALGO: { plan: 'explorer+', category: 'finance', description: 'Financial computation mode. Precision over speed.' },
33
+ ETHICAL_LOCK: { plan: 'explorer+', category: 'ethics', description: 'Ethics enforcement. Refuses harmful or biased outputs.' },
34
+ SCOPE_LIMITER: { plan: 'pro+', category: 'governance', description: 'Restricts agent scope to explicitly defined boundaries.' },
35
+ SAFE_DEPLOY: { plan: 'pro+', category: 'deployment', description: 'Deployment gating. Requires validation before any deploy.' },
36
+ STANDARD_DEPLOY: { plan: 'pro+', category: 'deployment', description: 'Standard deployment flow with audit trail.' },
37
+ FAST_BUILD: { plan: 'pro+', category: 'build', description: 'Accelerated build mode. Speed-first, reduced validation.' },
38
+ PRODUCTION_LOCK: { plan: 'pro+', category: 'deployment', description: 'Production environment lock. No destructive actions.' },
39
+ // Domain Lock modes (business/enterprise)
40
+ MEDICAL_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to medicine. Refuses off-domain queries.' },
41
+ LEGAL_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to law and legal compliance.' },
42
+ FINANCE_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to financial analysis and accounting.' },
43
+ CYBERSECURITY_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to cybersecurity and threat analysis.' },
44
+ SOFTWARE_ENGINEERING_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to software engineering and architecture.' },
45
+ AI_RESEARCH_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to AI/ML research and model analysis.' },
46
+ NEWS_ANALYSIS_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to news analysis and geopolitics.' },
47
+ SCIENTIFIC_RESEARCH_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to scientific research and methodology.' },
48
+ BUSINESS_STRATEGY_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to business strategy and market analysis.' },
49
+ DATA_SCIENCE_EXPERT: { plan: 'business+', category: 'domain_lock', description: 'Domain-locked to data science and analytics.' },
50
+ };
51
+
52
+ const MODE_IDS = Object.keys(MODES);
53
+
24
54
  class JsonFirstError extends Error {
25
55
  constructor(message, status, body) {
26
56
  super(message);
@@ -171,7 +201,26 @@
171
201
  async usage() {
172
202
  return this._request('GET', '/auth/me');
173
203
  }
204
+
205
+ /**
206
+ * List all 22 governance modes with their metadata.
207
+ * @returns {Object} modes map
208
+ */
209
+ modes() {
210
+ return MODES;
211
+ }
212
+
213
+ /**
214
+ * List all mode IDs.
215
+ * @returns {string[]}
216
+ */
217
+ modeIds() {
218
+ return MODE_IDS.slice();
219
+ }
174
220
  }
175
221
 
222
+ JsonFirst.MODES = MODES;
223
+ JsonFirst.MODE_IDS = MODE_IDS;
224
+
176
225
  return JsonFirst;
177
226
  }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jsonfirst/sdk",
3
- "version": "1.1.0",
3
+ "version": "1.3.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": [