@getjack/jack 0.1.23 → 0.1.25

package/templates/ai-chat/src/jack-ai.ts

@@ -0,0 +1,96 @@
+/**
+ * Jack AI Client - Drop-in replacement for Cloudflare AI binding.
+ *
+ * This wrapper provides the same interface as env.AI but routes calls
+ * through jack's binding proxy for metering and quota enforcement.
+ *
+ * Usage in templates:
+ * ```typescript
+ * import { createJackAI } from "./jack-ai";
+ *
+ * interface Env {
+ *   __AI_PROXY: Fetcher;        // Service binding to binding-proxy worker
+ *   __JACK_PROJECT_ID: string;  // Injected by control plane
+ *   __JACK_ORG_ID: string;      // Injected by control plane
+ * }
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const AI = createJackAI(env);
+ *     const result = await AI.run("@cf/meta/llama-3.2-1b-instruct", { messages });
+ *     // Works exactly like env.AI.run()
+ *   }
+ * };
+ * ```
+ *
+ * The wrapper is transparent - it accepts the same parameters as env.AI.run()
+ * and returns the same response types, including streaming.
+ */
+
+interface JackAIEnv {
+	__AI_PROXY: Fetcher;
+	__JACK_PROJECT_ID: string;
+	__JACK_ORG_ID: string;
+}
+
+/**
+ * Creates a Jack AI client that mirrors the Cloudflare AI binding interface.
+ *
+ * @param env - Worker environment with jack proxy bindings
+ * @returns AI-compatible object with run() method
+ */
+export function createJackAI(env: JackAIEnv): {
+	run: <T = unknown>(
+		model: string,
+		inputs: unknown,
+		options?: unknown,
+	) => Promise<T | ReadableStream>;
+} {
+	return {
+		async run<T = unknown>(
+			model: string,
+			inputs: unknown,
+			options?: unknown,
+		): Promise<T | ReadableStream> {
+			const response = await env.__AI_PROXY.fetch("http://internal/ai/run", {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-Jack-Project-ID": env.__JACK_PROJECT_ID,
+					"X-Jack-Org-ID": env.__JACK_ORG_ID,
+				},
+				body: JSON.stringify({ model, inputs, options }),
+			});
+
+			// Handle quota exceeded
+			if (response.status === 429) {
+				const error = await response.json();
+				const quotaError = new Error((error as { message?: string }).message || "AI quota exceeded");
+				(quotaError as Error & { code: string }).code = "AI_QUOTA_EXCEEDED";
+				(quotaError as Error & { resetIn?: number }).resetIn = (error as { resetIn?: number }).resetIn;
+				throw quotaError;
+			}
+
+			// Handle other errors
+			if (!response.ok) {
+				const error = await response.json();
+				throw new Error((error as { error?: string }).error || "AI request failed");
+			}
+
+			// Handle streaming response
+			const contentType = response.headers.get("Content-Type");
+			if (contentType?.includes("text/event-stream")) {
+				return response.body as ReadableStream;
+			}
+
+			// Handle JSON response
+			return response.json() as Promise<T>;
+		},
+	};
+}
+
+/**
+ * Type-safe wrapper that infers return types based on model.
+ * For advanced users who want full type safety.
+ */
+export type JackAI = ReturnType<typeof createJackAI>;

package/templates/semantic-search/.jack.json

@@ -7,18 +7,17 @@
 		"keywords": ["rag", "semantic", "search", "embeddings", "vectorize", "vector", "similarity"],
 		"examples": ["RAG app", "document search", "semantic search", "knowledge base"]
 	},
+	"agentContext": "Local development requires 'wrangler dev --remote' for AI and Vectorize bindings.",
 	"hooks": {
 		"postDeploy": [
 			{ "action": "clipboard", "text": "{{url}}", "message": "URL copied" },
 			{
 				"action": "box",
-				"title": "Semantic Search: {{name}}",
+				"title": "{{name}}",
 				"lines": [
 					"{{url}}",
 					"",
-					"Open in browser to index documents and search!",
-					"",
-					"Note: Local dev requires 'wrangler dev --remote'"
+					"jack open  to view in browser"
 				]
 			}
 		]

package/templates/semantic-search/src/index.ts

@@ -1,10 +1,64 @@
+import { createJackAI, type JackAI } from "./jack-ai";
+import { createJackVectorize, type JackVectorize } from "./jack-vectorize";
+
 interface Env {
-	AI: Ai;
-	VECTORS: VectorizeIndex;
+	// Direct bindings (for local dev with wrangler)
+	AI?: Ai;
+	VECTORS?: VectorizeIndex;
+	// Jack proxy bindings (injected in jack cloud)
+	__AI_PROXY?: Fetcher;
+	__VECTORIZE_PROXY?: Fetcher;
+	__JACK_PROJECT_ID?: string;
+	__JACK_ORG_ID?: string;
+	// Other bindings
 	DB: D1Database;
 	ASSETS: Fetcher;
 }
 
+// Index name must match wrangler.jsonc vectorize config
+const VECTORIZE_INDEX_NAME = "jack-template-vectors";
+
+// Minimal AI interface for embedding generation
+type AIClient = {
+	run: (model: string, inputs: { text: string }) => Promise<{ data: number[][] } | unknown>;
+};
+
+function getAI(env: Env): AIClient {
+	// Prefer jack cloud proxy if available (for metering)
+	if (env.__AI_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+		return createJackAI(env as Required<Pick<Env, "__AI_PROXY" | "__JACK_PROJECT_ID" | "__JACK_ORG_ID">>) as AIClient;
+	}
+	// Fallback to direct binding for local dev
+	if (env.AI) {
+		return env.AI as unknown as AIClient;
+	}
+	throw new Error("No AI binding available");
+}
+
+// Minimal Vectorize interface
+type VectorizeClient = {
+	insert: (vectors: { id: string; values: number[]; metadata?: Record<string, unknown> }[]) => Promise<unknown>;
+	query: (
+		vector: number[],
+		options?: { topK?: number; returnMetadata?: "none" | "indexed" | "all" },
+	) => Promise<{ matches: { id: string; score: number; metadata?: Record<string, unknown> }[] }>;
+};
+
+function getVectorize(env: Env): VectorizeClient {
+	// Prefer jack cloud proxy if available (for metering)
+	if (env.__VECTORIZE_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+		return createJackVectorize(
+			env as Required<Pick<Env, "__VECTORIZE_PROXY" | "__JACK_PROJECT_ID" | "__JACK_ORG_ID">>,
+			VECTORIZE_INDEX_NAME,
+		) as VectorizeClient;
+	}
+	// Fallback to direct binding for local dev
+	if (env.VECTORS) {
+		return env.VECTORS as unknown as VectorizeClient;
+	}
+	throw new Error("No Vectorize binding available");
+}
+
 // Rate limiting: 10 requests per minute per IP
 const RATE_LIMIT = 10;
 const RATE_WINDOW_MS = 60_000;
@@ -29,17 +83,17 @@ function checkRateLimit(ip: string): boolean {
 
 /**
  * Extract embedding vector from AI response
- * Handles union type from @cf/baai/bge-base-en-v1.5
+ * Handles response from @cf/baai/bge-base-en-v1.5
  */
-function getEmbeddingVector(response: Awaited<ReturnType<Ai["run"]>>): number[] | null {
+function getEmbeddingVector(response: unknown): number[] | null {
 	if (
 		response &&
 		typeof response === "object" &&
 		"data" in response &&
-		Array.isArray(response.data) &&
-		response.data.length > 0
+		Array.isArray((response as { data: unknown }).data) &&
+		(response as { data: unknown[] }).data.length > 0
 	) {
-		return response.data[0] as number[];
+		return (response as { data: number[][] }).data[0];
 	}
 	return null;
 }
@@ -72,8 +126,9 @@ export default {
 					return Response.json({ error: "Missing id or content" }, { status: 400 });
 				}
 
-				// Generate embedding using free Cloudflare AI
-				const embedding = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
+				// Generate embedding using Cloudflare AI
+				const ai = getAI(env);
+				const embedding = await ai.run("@cf/baai/bge-base-en-v1.5", {
 					text: content,
 				});
 
@@ -83,7 +138,8 @@ export default {
 				}
 
 				// Store in Vectorize
-				await env.VECTORS.insert([
+				const vectors = getVectorize(env);
+				await vectors.insert([
 					{
 						id,
 						values: embeddingVector,
@@ -117,7 +173,8 @@ export default {
 				}
 
 				// Generate query embedding
-				const embedding = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
+				const ai = getAI(env);
+				const embedding = await ai.run("@cf/baai/bge-base-en-v1.5", {
 					text: query,
 				});
 
@@ -127,7 +184,8 @@ export default {
 				}
 
 				// Search Vectorize
-				const results = await env.VECTORS.query(embeddingVector, {
+				const vectors = getVectorize(env);
+				const results = await vectors.query(embeddingVector, {
 					topK: limit,
 					returnMetadata: "all",
 				});

package/templates/semantic-search/src/jack-ai.ts

@@ -0,0 +1,96 @@
+/**
+ * Jack AI Client - Drop-in replacement for Cloudflare AI binding.
+ *
+ * This wrapper provides the same interface as env.AI but routes calls
+ * through jack's binding proxy for metering and quota enforcement.
+ *
+ * Usage in templates:
+ * ```typescript
+ * import { createJackAI } from "./jack-ai";
+ *
+ * interface Env {
+ *   __AI_PROXY: Fetcher;        // Service binding to binding-proxy worker
+ *   __JACK_PROJECT_ID: string;  // Injected by control plane
+ *   __JACK_ORG_ID: string;      // Injected by control plane
+ * }
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const AI = createJackAI(env);
+ *     const result = await AI.run("@cf/meta/llama-3.2-1b-instruct", { messages });
+ *     // Works exactly like env.AI.run()
+ *   }
+ * };
+ * ```
+ *
+ * The wrapper is transparent - it accepts the same parameters as env.AI.run()
+ * and returns the same response types, including streaming.
+ */
+
+interface JackAIEnv {
+	__AI_PROXY: Fetcher;
+	__JACK_PROJECT_ID: string;
+	__JACK_ORG_ID: string;
+}
+
+/**
+ * Creates a Jack AI client that mirrors the Cloudflare AI binding interface.
+ *
+ * @param env - Worker environment with jack proxy bindings
+ * @returns AI-compatible object with run() method
+ */
+export function createJackAI(env: JackAIEnv): {
+	run: <T = unknown>(
+		model: string,
+		inputs: unknown,
+		options?: unknown,
+	) => Promise<T | ReadableStream>;
+} {
+	return {
+		async run<T = unknown>(
+			model: string,
+			inputs: unknown,
+			options?: unknown,
+		): Promise<T | ReadableStream> {
+			const response = await env.__AI_PROXY.fetch("http://internal/ai/run", {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-Jack-Project-ID": env.__JACK_PROJECT_ID,
+					"X-Jack-Org-ID": env.__JACK_ORG_ID,
+				},
+				body: JSON.stringify({ model, inputs, options }),
+			});
+
+			// Handle quota exceeded
+			if (response.status === 429) {
+				const error = await response.json();
+				const quotaError = new Error((error as { message?: string }).message || "AI quota exceeded");
+				(quotaError as Error & { code: string }).code = "AI_QUOTA_EXCEEDED";
+				(quotaError as Error & { resetIn?: number }).resetIn = (error as { resetIn?: number }).resetIn;
+				throw quotaError;
+			}
+
+			// Handle other errors
+			if (!response.ok) {
+				const error = await response.json();
+				throw new Error((error as { error?: string }).error || "AI request failed");
+			}
+
+			// Handle streaming response
+			const contentType = response.headers.get("Content-Type");
+			if (contentType?.includes("text/event-stream")) {
+				return response.body as ReadableStream;
+			}
+
+			// Handle JSON response
+			return response.json() as Promise<T>;
+		},
+	};
+}
+
+/**
+ * Type-safe wrapper that infers return types based on model.
+ * For advanced users who want full type safety.
+ */
+export type JackAI = ReturnType<typeof createJackAI>;

package/templates/semantic-search/src/jack-vectorize.ts

@@ -0,0 +1,165 @@
+/**
+ * Jack Vectorize Client - Drop-in replacement for Cloudflare Vectorize binding.
+ *
+ * This wrapper provides the same interface as env.VECTORS but routes calls
+ * through jack's binding proxy for metering and quota enforcement.
+ *
+ * Usage in templates:
+ * ```typescript
+ * import { createJackVectorize } from "./jack-vectorize";
+ *
+ * interface Env {
+ *   __VECTORIZE_PROXY: Fetcher;   // Service binding to binding-proxy worker
+ *   __JACK_PROJECT_ID: string;    // Injected by control plane
+ *   __JACK_ORG_ID: string;        // Injected by control plane
+ * }
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const VECTORS = createJackVectorize(env, "my-index");
+ *     const results = await VECTORS.query(vector, { topK: 10 });
+ *     // Works exactly like env.VECTORS.query()
+ *   }
+ * };
+ * ```
+ *
+ * The wrapper is transparent - it accepts the same parameters as the native
+ * VectorizeIndex and returns the same response types.
+ */
+
+interface JackVectorizeEnv {
+	__VECTORIZE_PROXY: Fetcher;
+	__JACK_PROJECT_ID: string;
+	__JACK_ORG_ID: string;
+}
+
+interface VectorizeQueryOptions {
+	topK?: number;
+	filter?: Record<string, unknown>;
+	returnValues?: boolean;
+	returnMetadata?: "none" | "indexed" | "all";
+}
+
+interface VectorizeVector {
+	id: string;
+	values: number[];
+	metadata?: Record<string, unknown>;
+	namespace?: string;
+}
+
+interface VectorizeMatch {
+	id: string;
+	score: number;
+	values?: number[];
+	metadata?: Record<string, unknown>;
+}
+
+interface VectorizeQueryResult {
+	matches: VectorizeMatch[];
+	count: number;
+}
+
+interface VectorizeMutationResult {
+	mutationId: string;
+	count: number;
+	ids: string[];
+}
+
+interface VectorizeIndexDetails {
+	dimensions: number;
+	metric: "cosine" | "euclidean" | "dot-product";
+	vectorCount: number;
+}
+
+/**
+ * Creates a Jack Vectorize client that mirrors the Cloudflare VectorizeIndex interface.
+ *
+ * @param env - Worker environment with jack proxy bindings
+ * @param indexName - Name of the Vectorize index
+ * @returns VectorizeIndex-compatible object
+ */
+export function createJackVectorize(
+	env: JackVectorizeEnv,
+	indexName: string,
+): {
+	query: (vector: number[], options?: VectorizeQueryOptions) => Promise<VectorizeQueryResult>;
+	upsert: (vectors: VectorizeVector[]) => Promise<VectorizeMutationResult>;
+	insert: (vectors: VectorizeVector[]) => Promise<VectorizeMutationResult>;
+	deleteByIds: (ids: string[]) => Promise<VectorizeMutationResult>;
+	getByIds: (ids: string[]) => Promise<VectorizeVector[]>;
+	describe: () => Promise<VectorizeIndexDetails>;
+} {
+	async function proxyRequest<T>(operation: string, params: unknown): Promise<T> {
+		const response = await env.__VECTORIZE_PROXY.fetch("http://internal/vectorize", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"X-Jack-Project-ID": env.__JACK_PROJECT_ID,
+				"X-Jack-Org-ID": env.__JACK_ORG_ID,
+			},
+			body: JSON.stringify({
+				operation,
+				index_name: indexName,
+				params,
+			}),
+		});
+
+		// Handle quota exceeded
+		if (response.status === 429) {
+			const error = (await response.json()) as { message?: string; code?: string; resetIn?: number };
+			const quotaError = new Error(error.message || "Vectorize quota exceeded");
+			(quotaError as Error & { code: string }).code = error.code || "VECTORIZE_QUOTA_EXCEEDED";
+			(quotaError as Error & { resetIn?: number }).resetIn = error.resetIn;
+			throw quotaError;
+		}
+
+		// Handle rate limit
+		if (response.status === 429) {
+			const error = (await response.json()) as { message?: string };
+			throw new Error(error.message || "Rate limit exceeded");
+		}
+
+		// Handle other errors
+		if (!response.ok) {
+			const error = (await response.json()) as { error?: string };
+			throw new Error(error.error || `Vectorize ${operation} failed`);
+		}
+
+		return response.json() as Promise<T>;
+	}
+
+	return {
+		async query(vector: number[], options?: VectorizeQueryOptions): Promise<VectorizeQueryResult> {
+			return proxyRequest<VectorizeQueryResult>("query", {
+				vector,
+				...options,
+			});
+		},
+
+		async upsert(vectors: VectorizeVector[]): Promise<VectorizeMutationResult> {
+			return proxyRequest<VectorizeMutationResult>("upsert", { vectors });
+		},
+
+		async insert(vectors: VectorizeVector[]): Promise<VectorizeMutationResult> {
+			// insert is typically an alias for upsert in Vectorize
+			return proxyRequest<VectorizeMutationResult>("upsert", { vectors });
+		},
+
+		async deleteByIds(ids: string[]): Promise<VectorizeMutationResult> {
+			return proxyRequest<VectorizeMutationResult>("deleteByIds", { ids });
+		},
+
+		async getByIds(ids: string[]): Promise<VectorizeVector[]> {
+			return proxyRequest<VectorizeVector[]>("getByIds", { ids });
+		},
+
+		async describe(): Promise<VectorizeIndexDetails> {
+			return proxyRequest<VectorizeIndexDetails>("describe", {});
+		},
+	};
+}
+
+/**
+ * Type alias for the Jack Vectorize client
+ */
+export type JackVectorize = ReturnType<typeof createJackVectorize>;