@contentrain/query 5.1.1 → 5.1.3

package/README.md

@@ -2,9 +2,16 @@
 
 [![npm version](https://img.shields.io/npm/v/%40contentrain%2Fquery?label=%40contentrain%2Fquery)](https://www.npmjs.com/package/@contentrain/query)
 [![GitHub source](https://img.shields.io/badge/source-Contentrain%2Fai-181717?logo=github)](https://github.com/Contentrain/ai/tree/main/packages/sdk/js)
+[![Docs](https://img.shields.io/badge/docs-ai.contentrain.io-0f172a)](https://ai.contentrain.io/packages/sdk)
 
 **Optional** type-safe generated query SDK for Contentrain.
 
+Start here:
+
+- [2-minute product demo](https://ai.contentrain.io/demo)
+- [SDK docs](https://ai.contentrain.io/packages/sdk)
+- [Framework integration guide](https://ai.contentrain.io/guides/frameworks)
+
 Contentrain stores content as plain JSON and Markdown in a git-backed `.contentrain/` directory. Any platform that reads JSON can consume this content directly. This package adds a TypeScript convenience layer that turns content models into a generated JS/TS client with:
 
 - exact TypeScript types from your models
@@ -97,14 +104,25 @@ For collection models.
 Supported methods:
 
 - `locale(lang)`
-- `where(field, value)`
+- `where(field, value)` — equality shorthand
+- `where(field, op, value)` — operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`
 - `sort(field, order?)`
 - `limit(n)`
 - `offset(n)`
 - `include(...fields)`
+- `count()`
 - `first()`
 - `all()`
 
+Where operator examples:
+
+```ts
+query('plans').where('slug', 'ne', 'free').all()
+query('plans').where('price', 'gte', 10).where('price', 'lte', 50).all()
+query('starters').where('framework', 'in', ['nuxt', 'next']).all()
+query('blog').where('title', 'contains', 'Guide').count()
+```
+
 ### `singleton(model)`
 
 For singleton models.
@@ -132,9 +150,11 @@ For markdown/document models.
 Supported methods:
 
 - `locale(lang)`
-- `where(field, value)`
+- `where(field, value)` — equality shorthand
+- `where(field, op, value)` — same operators as `query()`
 - `include(...fields)`
 - `bySlug(slug)`
+- `count()`
 - `first()`
 - `all()`
 
@@ -169,13 +189,14 @@ const posts = client.query('blog-post').locale('en').all()
 
 Public root exports:
 
-- `QueryBuilder`
-- `SingletonAccessor`
-- `DictionaryAccessor`
-- `DocumentQuery`
+- `QueryBuilder`, `SingletonAccessor`, `DictionaryAccessor`, `DocumentQuery` — runtime classes
 - `createContentrainClient` — local generated client loader
 - `createContentrain` — CDN client factory
+- `MediaAccessor` — CDN media manifest reader
+- `FormsClient` — CDN forms API client
+- `ConversationClient` — Conversation API client
 - `ContentrainError` — HTTP error class for CDN mode
+- `applyWhere` — shared where filter helper
 
 ## CDN Transport
 
@@ -209,7 +230,88 @@ const filtered = await client.collection('faq')
   .all()
 ```
 
-CDN also exposes metadata endpoints:
+CDN collection queries support `count()` and entry metadata:
+
+```ts
+const total = await client.collection('faq').locale('en').count()
+
+// Enrich entries with _meta (status, publish_at, expire_at)
+const posts = await client.collection('blog')
+  .locale('en')
+  .withMeta()
+  .all()
+// posts[0]._meta → { status: 'published', publish_at: '...', ... }
+```
+
+### Media
+
+Access the media manifest and resolve asset variant URLs:
+
+```ts
+const media = client.media()
+const assets = await media.list()           // All assets with paths
+const asset  = await media.asset('hero.jpg') // Single asset
+
+// Resolve variant URL
+const thumbUrl = media.url(asset, 'thumb')  // Full CDN URL
+const original = media.url(asset)           // Original URL
+
+// Asset metadata
+asset.meta.width      // 1920
+asset.meta.blurhash   // 'LEHV6nWB...'
+asset.meta.alt        // 'Hero image'
+```
+
+### Forms
+
+Fetch form schema and submit data from external sites:
+
+```ts
+const form = client.form()
+
+// Get form field configuration
+const config = await form.config('contact')
+// config.fields → [{ id: 'name', type: 'string', required: true }, ...]
+
+// Submit form data
+const result = await form.submit('contact', {
+  name: 'Alice',
+  email: 'alice@example.com',
+  message: 'Hello!',
+}, { captchaToken: 'tok_xxx' })
+// result → { success: true, message: 'Thank you!' }
+```
+
+### Conversation API
+
+Send messages to the AI content agent and manage conversation history:
+
+```ts
+const conv = client.conversation()
+
+// Send a message — returns complete response with tool results
+const response = await conv.send('Create a new blog post about Vue 4')
+response.conversationId   // 'conv-abc123'
+response.message          // 'I created the blog post...'
+response.toolResults      // [{ id: 't-1', name: 'save_content', result: {...} }]
+response.usage            // { inputTokens: 150, outputTokens: 80 }
+
+// Continue a conversation
+const followUp = await conv.send('Now translate it to Turkish', {
+  conversationId: response.conversationId,
+})
+
+// Provide UI context
+await conv.send('Update the hero section', {
+  context: { activeModelId: 'hero', activeLocale: 'en' },
+})
+
+// Fetch conversation history
+const history = await conv.history('conv-abc123', { limit: 50 })
+history.messages  // [{ id, role, content, createdAt }, ...]
+```
+
+### Metadata Endpoints
 
 ```ts
 const manifest = await client.manifest()
@@ -270,7 +372,7 @@ Generator entry:
 
 CDN transport:
 
-- `@contentrain/query/cdn` — CDN client with `HttpTransport`, async query classes
+- `@contentrain/query/cdn` — CDN client with `HttpTransport`, async query classes, `MediaAccessor`, `FormsClient`, `ConversationClient`
 
 ## 🧠 Design Constraints
 

package/dist/cdn/index.cjs

@@ -1,9 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_cdn = require("../cdn-C8uXJe3A.cjs");
+const require_cdn = require("../cdn-5ycdk2ET.cjs");
 exports.CdnCollectionQuery = require_cdn.CdnCollectionQuery;
 exports.CdnDictionaryAccessor = require_cdn.CdnDictionaryAccessor;
 exports.CdnDocumentQuery = require_cdn.CdnDocumentQuery;
 exports.CdnSingletonAccessor = require_cdn.CdnSingletonAccessor;
 exports.ContentrainError = require_cdn.ContentrainError;
+exports.ConversationClient = require_cdn.ConversationClient;
+exports.FormsClient = require_cdn.FormsClient;
 exports.HttpTransport = require_cdn.HttpTransport;
+exports.MediaAccessor = require_cdn.MediaAccessor;
 exports.createContentrain = require_cdn.createContentrain;

package/dist/cdn/index.d.cts

@@ -1,2 +1,2 @@
-import { a as CdnDocumentQuery, c as CdnCollectionQuery, d as DictionaryDataSource, f as DocumentDataSource, i as ContentrainError, l as HttpTransport, n as ContentrainCDNConfig, o as CdnDictionaryAccessor, p as SingletonDataSource, r as createContentrain, s as CdnSingletonAccessor, t as ContentrainCDNClient, u as CollectionDataSource } from "../index-Xjd0isXU.cjs";
-export { CdnCollectionQuery, CdnDictionaryAccessor, CdnDocumentQuery, CdnSingletonAccessor, CollectionDataSource, ContentrainCDNClient, ContentrainCDNConfig, ContentrainError, DictionaryDataSource, DocumentDataSource, HttpTransport, SingletonDataSource, createContentrain };
+import { C as CdnDocumentQuery, E as CdnCollectionQuery, F as SingletonDataSource, M as CollectionDataSource, N as DictionaryDataSource, P as DocumentDataSource, S as MediaManifest, T as CdnSingletonAccessor, _ as FormsClient, a as ConversationClient, b as MediaAsset, c as ConversationHistory, d as ConversationSendOptions, f as ConversationToolResult, g as FormSubmitResult, h as FormFieldConfig, i as ContentrainError, j as HttpTransport, l as ConversationMessage, m as FormConfig, n as ContentrainCDNConfig, o as ConversationClientConfig, p as ConversationUsage, r as createContentrain, s as ConversationContext, t as ContentrainCDNClient, u as ConversationResponse, v as FormsClientConfig, w as CdnDictionaryAccessor, x as MediaAssetMeta, y as MediaAccessor } from "../index-BChs94uA.cjs";
+export { CdnCollectionQuery, CdnDictionaryAccessor, CdnDocumentQuery, CdnSingletonAccessor, CollectionDataSource, ContentrainCDNClient, ContentrainCDNConfig, ContentrainError, ConversationClient, ConversationClientConfig, ConversationContext, ConversationHistory, ConversationMessage, ConversationResponse, ConversationSendOptions, ConversationToolResult, ConversationUsage, DictionaryDataSource, DocumentDataSource, FormConfig, FormFieldConfig, FormSubmitResult, FormsClient, FormsClientConfig, HttpTransport, MediaAccessor, MediaAsset, MediaAssetMeta, MediaManifest, SingletonDataSource, createContentrain };

package/dist/cdn/index.d.mts

@@ -1,2 +1,2 @@
-import { a as CdnDocumentQuery, c as CdnCollectionQuery, d as DictionaryDataSource, f as DocumentDataSource, i as ContentrainError, l as HttpTransport, n as ContentrainCDNConfig, o as CdnDictionaryAccessor, p as SingletonDataSource, r as createContentrain, s as CdnSingletonAccessor, t as ContentrainCDNClient, u as CollectionDataSource } from "../index-D5zB3y75.mjs";
-export { CdnCollectionQuery, CdnDictionaryAccessor, CdnDocumentQuery, CdnSingletonAccessor, CollectionDataSource, ContentrainCDNClient, ContentrainCDNConfig, ContentrainError, DictionaryDataSource, DocumentDataSource, HttpTransport, SingletonDataSource, createContentrain };
+import { C as CdnDocumentQuery, E as CdnCollectionQuery, F as SingletonDataSource, M as CollectionDataSource, N as DictionaryDataSource, P as DocumentDataSource, S as MediaManifest, T as CdnSingletonAccessor, _ as FormsClient, a as ConversationClient, b as MediaAsset, c as ConversationHistory, d as ConversationSendOptions, f as ConversationToolResult, g as FormSubmitResult, h as FormFieldConfig, i as ContentrainError, j as HttpTransport, l as ConversationMessage, m as FormConfig, n as ContentrainCDNConfig, o as ConversationClientConfig, p as ConversationUsage, r as createContentrain, s as ConversationContext, t as ContentrainCDNClient, u as ConversationResponse, v as FormsClientConfig, w as CdnDictionaryAccessor, x as MediaAssetMeta, y as MediaAccessor } from "../index-CsCpovuB.mjs";
+export { CdnCollectionQuery, CdnDictionaryAccessor, CdnDocumentQuery, CdnSingletonAccessor, CollectionDataSource, ContentrainCDNClient, ContentrainCDNConfig, ContentrainError, ConversationClient, ConversationClientConfig, ConversationContext, ConversationHistory, ConversationMessage, ConversationResponse, ConversationSendOptions, ConversationToolResult, ConversationUsage, DictionaryDataSource, DocumentDataSource, FormConfig, FormFieldConfig, FormSubmitResult, FormsClient, FormsClientConfig, HttpTransport, MediaAccessor, MediaAsset, MediaAssetMeta, MediaManifest, SingletonDataSource, createContentrain };

package/dist/cdn/index.mjs

@@ -1,2 +1,2 @@
-import { a as CdnCollectionQuery, i as CdnSingletonAccessor, n as CdnDocumentQuery, o as HttpTransport, r as CdnDictionaryAccessor, s as ContentrainError, t as createContentrain } from "../cdn-D66-Npqt.mjs";
-export { CdnCollectionQuery, CdnDictionaryAccessor, CdnDocumentQuery, CdnSingletonAccessor, ContentrainError, HttpTransport, createContentrain };
+import { a as CdnDocumentQuery, c as CdnCollectionQuery, i as MediaAccessor, l as HttpTransport, n as ConversationClient, o as CdnDictionaryAccessor, r as FormsClient, s as CdnSingletonAccessor, t as createContentrain, u as ContentrainError } from "../cdn-SOuikUcY.mjs";
+export { CdnCollectionQuery, CdnDictionaryAccessor, CdnDocumentQuery, CdnSingletonAccessor, ContentrainError, ConversationClient, FormsClient, HttpTransport, MediaAccessor, createContentrain };

package/dist/{cdn-C8uXJe3A.cjs → cdn-5ycdk2ET.cjs}

@@ -1,3 +1,24 @@
+//#region src/shared/where.ts
+function applyWhere(item, clause) {
+	const val = item[clause.field];
+	switch (clause.op) {
+		case "eq":
+			if (Array.isArray(val)) return val.includes(clause.value);
+			return val === clause.value;
+		case "ne": return val !== clause.value;
+		case "gt": return val > clause.value;
+		case "gte": return val >= clause.value;
+		case "lt": return val < clause.value;
+		case "lte": return val <= clause.value;
+		case "in": return Array.isArray(clause.value) && clause.value.includes(val);
+		case "contains":
+			if (typeof val === "string") return val.includes(clause.value);
+			if (Array.isArray(val)) return val.includes(clause.value);
+			return false;
+		default: return true;
+	}
+}
+//#endregion
 //#region src/cdn/errors.ts
 var ContentrainError = class extends Error {
 	constructor(status, message) {
@@ -18,6 +39,9 @@ var HttpTransport = class {
 		this._projectId = config.projectId;
 		this._apiKey = config.apiKey;
 	}
+	buildUrl(path) {
+		return `${this._baseUrl}/${this._projectId}/${path}`;
+	}
 	async fetch(path) {
 		const url = `${this._baseUrl}/${this._projectId}/${path}`;
 		const cached = this._cache.get(path);
@@ -75,6 +99,7 @@ var CdnCollectionQuery = class {
 	_limit = null;
 	_offset = 0;
 	_includes = [];
+	_withMeta = false;
 	constructor(transport, modelId, defaultLocale) {
 		this._transport = transport;
 		this._source = transport.collection(modelId);
@@ -110,9 +135,13 @@ var CdnCollectionQuery = class {
 		this._includes.push(...fields);
 		return this;
 	}
+	withMeta() {
+		this._withMeta = true;
+		return this;
+	}
 	async all() {
 		let items = await this._source.getAll(this._locale);
-		for (const clause of this._filters) items = items.filter((item) => applyWhere$1(item, clause));
+		for (const clause of this._filters) items = items.filter((item) => applyWhere(item, clause));
 		if (this._sortField) {
 			const field = this._sortField;
 			const dir = this._sortOrder === "asc" ? 1 : -1;
@@ -132,8 +161,12 @@ var CdnCollectionQuery = class {
 			items = items.slice(this._offset, end);
 		}
 		if (this._includes.length > 0) items = await this._resolveIncludes(items);
+		if (this._withMeta) items = await this._enrichMeta(items);
 		return items;
 	}
+	async count() {
+		return (await this.all()).length;
+	}
 	async first() {
 		return (await this.all())[0];
 	}
@@ -173,24 +206,24 @@ var CdnCollectionQuery = class {
 			return resolved;
 		});
 	}
-};
-function applyWhere$1(item, clause) {
-	const val = item[clause.field];
-	switch (clause.op) {
-		case "eq": return val === clause.value;
-		case "ne": return val !== clause.value;
-		case "gt": return val > clause.value;
-		case "gte": return val >= clause.value;
-		case "lt": return val < clause.value;
-		case "lte": return val <= clause.value;
-		case "in": return Array.isArray(clause.value) && clause.value.includes(val);
-		case "contains":
-			if (typeof val === "string") return val.includes(clause.value);
-			if (Array.isArray(val)) return val.includes(clause.value);
-			return false;
-		default: return true;
+	async _enrichMeta(items) {
+		let metaMap = {};
+		try {
+			metaMap = await this._transport.fetch(`meta/${this._modelId}/${this._locale}.json`);
+		} catch {
+			return items;
+		}
+		return items.map((item) => {
+			const id = item.id;
+			const meta = id ? metaMap[id] : void 0;
+			if (meta) return {
+				...item,
+				_meta: meta
+			};
+			return item;
+		});
 	}
-}
+};
 //#endregion
 //#region src/cdn/singleton-accessor.ts
 var CdnSingletonAccessor = class {
@@ -263,6 +296,9 @@ var CdnDocumentQuery = class {
 		for (const clause of this._filters) items = items.filter((item) => applyWhere(item, clause));
 		return items;
 	}
+	async count() {
+		return (await this.all()).length;
+	}
 	async first() {
 		return (await this.all())[0];
 	}
@@ -270,23 +306,108 @@ var CdnDocumentQuery = class {
 		return this._source.getBySlug(slug, this._locale);
 	}
 };
-function applyWhere(item, clause) {
-	const val = item[clause.field];
-	switch (clause.op) {
-		case "eq": return val === clause.value;
-		case "ne": return val !== clause.value;
-		case "gt": return val > clause.value;
-		case "gte": return val >= clause.value;
-		case "lt": return val < clause.value;
-		case "lte": return val <= clause.value;
-		case "in": return Array.isArray(clause.value) && clause.value.includes(val);
-		case "contains":
-			if (typeof val === "string") return val.includes(clause.value);
-			if (Array.isArray(val)) return val.includes(clause.value);
-			return false;
-		default: return true;
+//#endregion
+//#region src/cdn/media-accessor.ts
+var MediaAccessor = class {
+	_transport;
+	_manifest = null;
+	constructor(transport) {
+		this._transport = transport;
 	}
-}
+	async manifest() {
+		if (!this._manifest) this._manifest = await this._transport.fetch("_media_manifest.json");
+		return this._manifest;
+	}
+	async assets() {
+		return (await this.manifest()).assets;
+	}
+	async asset(path) {
+		return (await this.assets())[path] ?? null;
+	}
+	async list() {
+		const all = await this.assets();
+		return Object.entries(all).map(([path, asset]) => Object.assign({ path }, asset));
+	}
+	resolve(asset, variant) {
+		if (variant && asset.variants[variant]) return asset.variants[variant];
+		return asset.original;
+	}
+	url(asset, variant) {
+		const path = this.resolve(asset, variant);
+		return this._transport.buildUrl(path);
+	}
+};
+//#endregion
+//#region src/cdn/forms-client.ts
+var FormsClient = class {
+	_baseUrl;
+	_projectId;
+	_apiKey;
+	constructor(config) {
+		this._baseUrl = config.baseUrl.replace(/\/+$/, "");
+		this._projectId = config.projectId;
+		this._apiKey = config.apiKey;
+	}
+	async config(modelId) {
+		const url = `${this._baseUrl}/${this._projectId}/${modelId}/config`;
+		const headers = {};
+		if (this._apiKey) headers["Authorization"] = `Bearer ${this._apiKey}`;
+		const res = await globalThis.fetch(url, { headers });
+		if (!res.ok) throw new ContentrainError(res.status, await res.text());
+		return await res.json();
+	}
+	async submit(modelId, data, options) {
+		const url = `${this._baseUrl}/${this._projectId}/${modelId}/submit`;
+		const headers = { "Content-Type": "application/json" };
+		if (this._apiKey) headers["Authorization"] = `Bearer ${this._apiKey}`;
+		const body = { ...data };
+		if (options?.captchaToken) body["cf-turnstile-response"] = options.captchaToken;
+		const res = await globalThis.fetch(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body)
+		});
+		const result = await res.json();
+		if (!res.ok && !result.errors) throw new ContentrainError(res.status, result.message ?? "Form submission failed");
+		return result;
+	}
+};
+//#endregion
+//#region src/cdn/conversation-client.ts
+var ConversationClient = class {
+	_baseUrl;
+	_projectId;
+	_apiKey;
+	constructor(config) {
+		this._baseUrl = config.baseUrl.replace(/\/+$/, "");
+		this._projectId = config.projectId;
+		this._apiKey = config.apiKey;
+	}
+	async send(message, options) {
+		const url = `${this._baseUrl}/${this._projectId}/message`;
+		const body = { message };
+		if (options?.conversationId) body.conversationId = options.conversationId;
+		if (options?.context) body.context = options.context;
+		const res = await globalThis.fetch(url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"Authorization": `Bearer ${this._apiKey}`
+			},
+			body: JSON.stringify(body)
+		});
+		if (!res.ok) throw new ContentrainError(res.status, await res.text());
+		return await res.json();
+	}
+	async history(conversationId, options) {
+		const params = new URLSearchParams({ conversationId });
+		if (options?.limit) params.set("limit", String(options.limit));
+		const url = `${this._baseUrl}/${this._projectId}/history?${params}`;
+		const res = await globalThis.fetch(url, { headers: { "Authorization": `Bearer ${this._apiKey}` } });
+		if (!res.ok) throw new ContentrainError(res.status, await res.text());
+		return await res.json();
+	}
+};
 //#endregion
 //#region src/cdn/index.ts
 function createContentrain(config) {
@@ -301,6 +422,17 @@ function createContentrain(config) {
 		singleton: (modelId) => new CdnSingletonAccessor(transport.singleton(modelId), defaultLocale),
 		dictionary: (modelId) => new CdnDictionaryAccessor(transport.dictionary(modelId), defaultLocale),
 		document: (modelId) => new CdnDocumentQuery(transport.document(modelId), defaultLocale),
+		media: () => new MediaAccessor(transport),
+		form: () => new FormsClient({
+			baseUrl: (config.baseUrl ?? "https://studio.contentrain.io/api/cdn/v1").replace("/cdn/v1", "/forms/v1"),
+			projectId: config.projectId,
+			apiKey: config.apiKey
+		}),
+		conversation: () => new ConversationClient({
+			baseUrl: (config.baseUrl ?? "https://studio.contentrain.io/api/cdn/v1").replace("/cdn/v1", "/conversation/v1"),
+			projectId: config.projectId,
+			apiKey: config.apiKey
+		}),
 		manifest: () => transport.fetch("_manifest.json"),
 		models: () => transport.fetch("models/_index.json"),
 		model: (id) => transport.fetch(`models/${id}.json`)
@@ -337,12 +469,36 @@ Object.defineProperty(exports, "ContentrainError", {
 		return ContentrainError;
 	}
 });
+Object.defineProperty(exports, "ConversationClient", {
+	enumerable: true,
+	get: function() {
+		return ConversationClient;
+	}
+});
+Object.defineProperty(exports, "FormsClient", {
+	enumerable: true,
+	get: function() {
+		return FormsClient;
+	}
+});
 Object.defineProperty(exports, "HttpTransport", {
 	enumerable: true,
 	get: function() {
 		return HttpTransport;
 	}
 });
+Object.defineProperty(exports, "MediaAccessor", {
+	enumerable: true,
+	get: function() {
+		return MediaAccessor;
+	}
+});
+Object.defineProperty(exports, "applyWhere", {
+	enumerable: true,
+	get: function() {
+		return applyWhere;
+	}
+});
 Object.defineProperty(exports, "createContentrain", {
 	enumerable: true,
 	get: function() {