@jsonfirst/sdk 1.0.0

package/README.md

@@ -0,0 +1,54 @@
+# @jsonfirst/sdk
+
+Official JavaScript/Node.js SDK for the **JSONFIRST Protocol** — the Universal Intent Protocol for AI governance.
+
+## Installation
+
+```bash
+npm install @jsonfirst/sdk
+```
+
+## Quick Start
+
+```javascript
+const JsonFirst = require('@jsonfirst/sdk');
+
+const client = new JsonFirst({ apiKey: 'YOUR_API_KEY' });
+
+// Parse a natural language intent
+const result = await client.parse('Create a new order for John Smith, 2 units of product A');
+console.log(result);
+
+// Validate a JSONFIRST JSON
+const { valid, errors } = client.validate(result);
+console.log(valid, errors);
+```
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `parse(text, options?)` | Convert natural language to JSONFIRST JSON |
+| `validate(json)` | Validate a JSON against the JSONFIRST spec |
+| `pull(schemaId)` | Fetch a publicly shared schema |
+| `share(outputJson, title?)` | Share a schema and get a public link |
+| `usage()` | Get your account usage stats |
+
+## Options
+
+```javascript
+const client = new JsonFirst({
+  apiKey: 'YOUR_API_KEY',
+  baseUrl: 'https://jsonfirst.io' // optional override
+});
+```
+
+## Links
+
+- [Documentation](https://jsonfirst.io/developers)
+- [Templates](https://jsonfirst.io/templates)
+- [GitHub](https://github.com/jsonfirst/sdk)
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,124 @@
+/**
+ * @jsonfirst/sdk v1.0.0
+ * Official JavaScript/Node.js SDK for the JSONFIRST Protocol
+ *
+ * Usage:
+ *   const JsonFirst = require('@jsonfirst/sdk');
+ *   const client = new JsonFirst({ apiKey: 'YOUR_API_KEY' });
+ *   const result = await client.parse('Create a new order for John Smith');
+ *
+ * Install:
+ *   npm install @jsonfirst/sdk
+ */
+
+(function(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.JsonFirst = factory();
+  }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function() {
+
+  const DEFAULT_BASE_URL = 'https://jsonfirst.io';
+
+  class JsonFirstError extends Error {
+    constructor(message, status, body) {
+      super(message);
+      this.name = 'JsonFirstError';
+      this.status = status;
+      this.body = body;
+    }
+  }
+
+  class JsonFirst {
+    /**
+     * @param {Object} options
+     * @param {string} options.apiKey - Your JSONFIRST API key
+     * @param {string} [options.baseUrl] - Override base URL (default: https://jsonfirst.io)
+     */
+    constructor(options = {}) {
+      if (!options.apiKey) throw new Error('JsonFirst: apiKey is required');
+      this.apiKey = options.apiKey;
+      this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+    }
+
+    _headers() {
+      return {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      };
+    }
+
+    async _request(method, path, body) {
+      const url = `${this.baseUrl}/api${path}`;
+      const res = await fetch(url, {
+        method,
+        headers: this._headers(),
+        body: body ? JSON.stringify(body) : undefined,
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) throw new JsonFirstError(data.detail || 'Request failed', res.status, data);
+      return data;
+    }
+
+    /**
+     * Parse a natural language intent into a JSONFIRST JSON.
+     * @param {string} text - The intent to parse
+     * @param {Object} [options] - Optional params: model, execution_mode
+     * @returns {Promise<Object>} JSONFIRST JSON output
+     */
+    async parse(text, options = {}) {
+      return this._request('POST', '/parse', { input: text, ...options });
+    }
+
+    /**
+     * Pull a publicly shared schema by its share ID.
+     * @param {string} schemaId - The share ID (e.g. "abc123xy")
+     * @returns {Promise<Object>} Schema object
+     */
+    async pull(schemaId) {
+      if (!schemaId) throw new Error('pull: schemaId is required');
+      const res = await fetch(`${this.baseUrl}/api/schemas/public/${schemaId}`);
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) throw new JsonFirstError(data.detail || 'Schema not found', res.status, data);
+      return data;
+    }
+
+    /**
+     * Validate a JSON object against the JSONFIRST spec.
+     * @param {Object} json - The JSON to validate
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate(json) {
+      const errors = [];
+      if (!json || typeof json !== 'object') {
+        return { valid: false, errors: ['Input must be a JSON object'] };
+      }
+      if (json.spec !== 'JSONFIRST') errors.push('Missing or incorrect "spec" field (expected "JSONFIRST")');
+      if (!json.version) errors.push('Missing "version" field');
+      if (!json.jdons || !Array.isArray(json.jdons)) errors.push('Missing "jdons" array');
+      if (!json.execution || typeof json.execution !== 'object') errors.push('Missing "execution" object');
+      return { valid: errors.length === 0, errors };
+    }
+
+    /**
+     * Share a schema output and get a public link.
+     * @param {Object} outputJson - The JSONFIRST JSON to share
+     * @param {string} [title] - Optional title
+     * @returns {Promise<{ share_id: string, url: string }>}
+     */
+    async share(outputJson, title) {
+      return this._request('POST', '/schemas/share', { output_json: outputJson, title: title || 'Shared Schema' });
+    }
+
+    /**
+     * Get your account usage and remaining intents.
+     * @returns {Promise<Object>}
+     */
+    async usage() {
+      return this._request('GET', '/auth/me');
+    }
+  }
+
+  return JsonFirst;
+}));

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@jsonfirst/sdk",
+  "version": "1.0.0",
+  "description": "Official JavaScript/Node.js SDK for the JSONFIRST Protocol — Universal Intent Protocol for AI governance",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node -e \"const sdk = require('.'); const jf = new sdk({apiKey:'test'}); console.log('SDK loaded OK'); const v = jf.validate({spec:'JSONFIRST',version:'2.0',jdons:[],execution:{}}); console.log('validate:', v);\""
+  },
+  "keywords": [
+    "jsonfirst",
+    "json",
+    "ai",
+    "governance",
+    "llm",
+    "intent",
+    "protocol",
+    "sdk",
+    "chatgpt",
+    "claude",
+    "gemini"
+  ],
+  "author": "JSONFIRST <contact@jsonfirst.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsonfirst/sdk"
+  },
+  "homepage": "https://jsonfirst.io",
+  "engines": {
+    "node": ">=14"
+  }
+}