@jsonfirst/sdk

Stop writing brittle prompts. JSONFIRST turns any user input into a structured, validated JSON intent your agent can execute reliably.

npm install @jsonfirst/sdk

---

The problem it solves

Without JSONFIRST — your agent gets this:

"create an order for john, 2 units of product A, ship it fast"

Your code parses free text. Edge cases break it. You write regex. It still breaks.

With JSONFIRST — your agent gets this:

{
  "spec": "JSONFIRST",
  "version": "2.0",
  "jdons": [{
    "action": { "normalized": "create" },
    "object": { "type": "order", "customer": "john", "quantity": 2, "product": "product_A" },
    "constraints": { "shipping": "express" },
    "execution": { "parsable": true, "executable": true }
  }]
}

Structured. Validated. Executable. Every time.

---

Quick Start

Step 1 — Get your API key at jsonfirst.com/developers

Step 2 — Install and parse

const JsonFirst = require('@jsonfirst/sdk');

const client = new JsonFirst({ apiKey: 'YOUR_API_KEY' });

const result = await client.parse('Create an order for John, 2 units of product A');
console.log(result.jdons[0].action.normalized); // "create"
console.log(result.jdons[0].object);            // { type: "order", ... }

---

Methods

Method	Description
parse(text, options?)	Convert natural language to a validated JSONFIRST JSON
validate(json)	Validate a JSON against the JSONFIRST v2 spec
validateIntent(intent, options?)	Validate a single JDON intent (confidence, params, executability)
pull(schemaId)	Fetch a publicly shared schema
share(outputJson, title?)	Share a schema and get a public link
usage()	Get your account usage and remaining intents
modes()	List all 22 governance modes with metadata
modeIds()	List all 22 mode IDs as an array

---

Recoverable Agents — Full Pipeline

JSONFIRST closes the full loop: intent → validation → snapshot → execution → receipt → rollback

1. Snapshot (before execution)

const snap = await client.snapshot({
  jdon_id: 'jdon_abc123',
  description: 'before delete user 1234',
  state: { user_id: '1234', status: 'active', balance: 500 },
  rollback_webhook: 'https://yourapp.com/webhooks/rollback' // optional
});
// → { snapshot_id: 'uuid', status: 'AVAILABLE' }

2. Receipt (after execution — verify intent match)

const receipt = await client.receipt({
  jdon_id: 'jdon_abc123',
  output_summary: 'User 1234 deleted from production database',
  mode: 'PRODUCTION_LOCK',
  original_intent: result  // the JSONFIRST parse output
});
// → { intent_match_score: 0.95, verification_status: 'VERIFIED', drift_detected: false }
// or → { verification_status: 'INTENT_MISMATCH', flags: ['ROLLBACK_SUGGESTED'] }

3. Rollback (if drift detected)

if (receipt.receipt.flags.includes('ROLLBACK_SUGGESTED')) {
  const rb = await client.rollback({
    snapshot_id: snap.snapshot_id,
    reason: 'INTENT_MISMATCH_DETECTED'
  });
  // → { status: 'ROLLED_BACK', restored_state: { user_id: '1234', ... } }
  // Webhook fired automatically if configured
}

---

Governance Modes

22 modes ship with this SDK. Pass execution_mode to parse() to activate.

const result = await client.parse('Delete user 1234', {
  execution_mode: 'GUARDIAN_MODE' // blocks risky actions until confirmed
});

console.log(JsonFirst.MODE_IDS); // all 22 mode IDs

Mode	Plan	Category
ANTI_CREDIT_WASTE_V2	free+	efficiency
EXPRESS_ROUTE	explorer+	speed
STRICT_PROTOCOL	explorer+	compliance
PERFORMANCE_MAX	explorer+	performance
GUARDIAN_MODE	explorer+	safety
FINANCE_ALGO	explorer+	finance
ETHICAL_LOCK	explorer+	ethics
SCOPE_LIMITER	pro+	governance
SAFE_DEPLOY	pro+	deployment
STANDARD_DEPLOY	pro+	deployment
FAST_BUILD	pro+	build
PRODUCTION_LOCK	pro+	deployment
MEDICAL_EXPERT	business+	domain_lock
LEGAL_EXPERT	business+	domain_lock
FINANCE_EXPERT	business+	domain_lock
CYBERSECURITY_EXPERT	business+	domain_lock
SOFTWARE_ENGINEERING_EXPERT	business+	domain_lock
AI_RESEARCH_EXPERT	business+	domain_lock
NEWS_ANALYSIS_EXPERT	business+	domain_lock
SCIENTIFIC_RESEARCH_EXPERT	business+	domain_lock
BUSINESS_STRATEGY_EXPERT	business+	domain_lock
DATA_SCIENCE_EXPERT	business+	domain_lock

---

Links

• Get your API key
• Documentation
• LLM Implants
• GitHub
• Protocol spec

License

MIT