@usecontextlayer/sdk 0.12.1

package/README.md

@@ -0,0 +1,57 @@
+# @usecontextlayer/sdk
+
+Tools for ContextLayer React Router apps. In local development, calls execute through the ContextLayer platform using your assigned Composio Platform connections.
+
+Create an app with `npx @usecontextlayer/cli init my-app`. The CLI installs this package and configures a development-only Cloudflare Worker and native service binding. Use the generated app's normal `pnpm dev` command. First-party `@usecontextlayer/*` packages are exempt from pnpm's release-age policy in generated projects.
+
+## Local login and assignment
+
+Run `ctx login` to save your ContextLayer login. Declare `work-email` as an individual Gmail requirement in `public/slate.json`, then use `ctx connections list` to find your connection and `ctx connection local assign work-email <connection_id>` to assign it. Run local commands from the app root.
+
+When `pnpm dev` starts, `contextlayer(env)` from `@usecontextlayer/sdk/vite` configures the Cloudflare Vite plugin and calls the CLI-owned `getLocalToolsBindings` helper. This Node helper reads the AppID from Git origin and obtains a current access token using the same saved login as the CLI. Only the AppID, platform URL, and access token enter the local Tools Worker. The refresh token stays in `~/.contextlayer/auth.json`; the Composio project key stays on the platform. Restart `pnpm dev` when the access token expires.
+
+## A loader that reads Gmail
+
+The first argument is the connection requirement slug in `public/slate.json`, such as `work-email`. The platform resolves it using the app and signed-in user:
+
+```ts
+import { toolsContext } from "@usecontextlayer/sdk"
+import type { LoaderFunctionArgs } from "react-router"
+
+export async function loader({ context }: LoaderFunctionArgs) {
+  return context.get(toolsContext).call("work-email", "GMAIL_FETCH_EMAILS", {
+    max_results: 5,
+    label_ids: ["INBOX"],
+    include_payload: false,
+    verbose: false,
+  })
+}
+```
+
+Calls return `{ data, logId }`. Validate the tool-specific `data` in your loader. The complete [Gmail example](examples/gmail.tsx) validates the response with Zod and renders a message list. Copy it to `app/routes/home.tsx` in a generated app and assign your Gmail connection to `work-email`.
+
+## Runtime ownership
+
+The package root exports the `Tools` interface and `toolsContext`. `@usecontextlayer/sdk/local` exports the local `Tools` Worker entrypoint. `@usecontextlayer/sdk/worker` exports `createApp`, which creates the React Router request handler and supplies `toolsContext` from the local binding or production request props. `@usecontextlayer/sdk/vite` owns the `contextlayer` integration. The CLI package owns the Node startup helper and saved-login handling. The generated application supplies its virtual server-build import, mode, and development flag through thin Worker wiring, and composes Vite plugins. The Cloudflare Vite plugin runs the auxiliary Worker only in development; production bundles exclude it and its service binding.
+
+The platform execution API is implemented; deployed viewer integration is not yet implemented. The packaged request handler reserves `ctx.props.tools` for that later path. Local access-token bindings are not included in production builds.
+
+## Vite configuration
+
+ContextLayer's Vite integration for Cloudflare React Router apps. Compose it with the app's React Router and Tailwind plugins:
+
+```ts
+import { contextlayer } from "@usecontextlayer/sdk/vite"
+import { reactRouter } from "@react-router/dev/vite"
+import tailwindcss from "@tailwindcss/vite"
+import { defineConfig } from "vite"
+
+export default defineConfig((env) => ({
+  plugins: [contextlayer(env), tailwindcss(), reactRouter()],
+  resolve: { tsconfigPaths: true },
+}))
+```
+
+This integration supplies the Cloudflare plugin; do not add a second instance. It uses the generated `workers/local-tools/wrangler.jsonc` to start the local Tools Worker and provides its development-only service binding. At development startup, the CLI reads the app's Git origin and saved ContextLayer login. Production builds exclude local credentials and the auxiliary Worker.
+
+The app retains its routes, `public/slate.json`, and thin Worker/configuration files. `@usecontextlayer/sdk/worker` owns the React Router request handler and Tools context setup.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+//#region index.d.ts
+export interface Tools {
+  call(slug: string, toolSlug: string, args: Record<string, unknown>): Promise<{
+    data: unknown;
+    logId: string;
+  }>;
+}
+export declare const toolsContext: import("react-router").RouterContext<Tools>;
+//#endregion
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../index.ts"],"mappings":";iBAEiB;EAChB,KACC,cACA,kBACA,MAAM,0BACJ;IAAU;IAAe;;;qBAGhB,qCAAY,cAAA"}

package/dist/index.js

@@ -0,0 +1,7 @@
+import { createContext } from "react-router";
+//#region index.ts
+const toolsContext = createContext();
+//#endregion
+export { toolsContext };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../index.ts"],"sourcesContent":["import { createContext } from \"react-router\"\n\nexport interface Tools {\n\tcall(\n\t\tslug: string,\n\t\ttoolSlug: string,\n\t\targs: Record<string, unknown>,\n\t): Promise<{ data: unknown; logId: string }>\n}\n\nexport const toolsContext = createContext<Tools>()\n"],"mappings":";;AAUA,MAAa,eAAe,cAAqB"}

package/dist/local.d.ts

@@ -0,0 +1,20 @@
+import { Tools as Tools$1 } from "./index.js";
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { z } from "zod";
+//#region env.d.ts
+declare const schema: z.ZodObject<{
+  CTX_ACCESS_TOKEN: z.ZodString;
+  CTX_APP_ID: z.ZodUUID;
+  CTX_PLATFORM_URL: z.ZodURL;
+}, z.core.$strip>;
+type Bindings = z.input<typeof schema>;
+//#endregion
+//#region local.d.ts
+export declare class Tools extends WorkerEntrypoint<Bindings> implements Tools$1 {
+  call(slug: string, toolSlug: string, args: Record<string, unknown>): Promise<{
+    data: Record<string, unknown>;
+    logId: string;
+  }>;
+}
+//#endregion
+//# sourceMappingURL=local.d.ts.map

package/dist/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","names":[],"sources":["../env.ts","../local.ts"],"mappings":";;;;cAEM,QAAM,EAAA;;;;GAIV,EAAA,KAAA;KACU,WAAW,EAAE,aAAa;;;qBCIzB,cAAc,iBAAiB,qBAAqB;EAC1D,KAAK,cAAc,kBAAkB,MAAM,0BAAuB"}

package/dist/local.js

@@ -0,0 +1,44 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { z } from "zod";
+//#region env.ts
+const schema = z.object({
+	CTX_ACCESS_TOKEN: z.string().min(1),
+	CTX_APP_ID: z.uuid(),
+	CTX_PLATFORM_URL: z.url()
+});
+const parseEnv = (bindings) => schema.parse(bindings);
+//#endregion
+//#region local.ts
+const execution = z.object({
+	data: z.record(z.string(), z.unknown()),
+	error: z.string().nullable(),
+	logId: z.string()
+});
+var Tools = class extends WorkerEntrypoint {
+	async call(slug, toolSlug, args) {
+		const env = parseEnv(this.env);
+		const response = await fetch(new URL(`/api/apps/${env.CTX_APP_ID}/tools/call`, env.CTX_PLATFORM_URL), {
+			body: JSON.stringify({
+				arguments: args,
+				slug,
+				tool: toolSlug
+			}),
+			headers: {
+				authorization: `Bearer ${env.CTX_ACCESS_TOKEN}`,
+				"content-type": "application/json"
+			},
+			method: "POST"
+		});
+		if (!response.ok) throw new Error(`Tool call failed: HTTP ${response.status}`);
+		const result = execution.parse(await response.json());
+		if (result.error !== null) throw new Error(`${result.error} (log: ${result.logId})`);
+		return {
+			data: result.data,
+			logId: result.logId
+		};
+	}
+};
+//#endregion
+export { Tools };
+
+//# sourceMappingURL=local.js.map

package/dist/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","names":[],"sources":["../env.ts","../local.ts"],"sourcesContent":["import { z } from \"zod\"\n\nconst schema = z.object({\n\tCTX_ACCESS_TOKEN: z.string().min(1),\n\tCTX_APP_ID: z.uuid(),\n\tCTX_PLATFORM_URL: z.url(),\n})\nexport type Bindings = z.input<typeof schema>\nexport const parseEnv = (bindings: Bindings) => schema.parse(bindings)\n","import { WorkerEntrypoint } from \"cloudflare:workers\"\nimport { z } from \"zod\"\nimport { type Bindings, parseEnv } from \"@/env\"\nimport type { Tools as ToolsContract } from \"@/index\"\n\nconst execution = z.object({\n\tdata: z.record(z.string(), z.unknown()),\n\terror: z.string().nullable(),\n\tlogId: z.string(),\n})\n\nexport class Tools extends WorkerEntrypoint<Bindings> implements ToolsContract {\n\tasync call(slug: string, toolSlug: string, args: Record<string, unknown>) {\n\t\tconst env = parseEnv(this.env)\n\t\tconst response = await fetch(\n\t\t\tnew URL(`/api/apps/${env.CTX_APP_ID}/tools/call`, env.CTX_PLATFORM_URL),\n\t\t\t{\n\t\t\t\tbody: JSON.stringify({ arguments: args, slug, tool: toolSlug }),\n\t\t\t\theaders: {\n\t\t\t\t\tauthorization: `Bearer ${env.CTX_ACCESS_TOKEN}`,\n\t\t\t\t\t\"content-type\": \"application/json\",\n\t\t\t\t},\n\t\t\t\tmethod: \"POST\",\n\t\t\t},\n\t\t)\n\t\tif (!response.ok) throw new Error(`Tool call failed: HTTP ${response.status}`)\n\t\tconst result = execution.parse(await response.json())\n\t\tif (result.error !== null) throw new Error(`${result.error} (log: ${result.logId})`)\n\t\treturn { data: result.data, logId: result.logId }\n\t}\n}\n"],"mappings":";;;AAEA,MAAM,SAAS,EAAE,OAAO;CACvB,kBAAkB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CAClC,YAAY,EAAE,KAAK;CACnB,kBAAkB,EAAE,IAAI;AACzB,CAAC;AAED,MAAa,YAAY,aAAuB,OAAO,MAAM,QAAQ;;;ACHrE,MAAM,YAAY,EAAE,OAAO;CAC1B,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC;CACtC,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS;CAC3B,OAAO,EAAE,OAAO;AACjB,CAAC;AAED,IAAa,QAAb,cAA2B,iBAAoD;CAC9E,MAAM,KAAK,MAAc,UAAkB,MAA+B;EACzE,MAAM,MAAM,SAAS,KAAK,GAAG;EAC7B,MAAM,WAAW,MAAM,MACtB,IAAI,IAAI,aAAa,IAAI,WAAW,cAAc,IAAI,gBAAgB,GACtE;GACC,MAAM,KAAK,UAAU;IAAE,WAAW;IAAM;IAAM,MAAM;GAAS,CAAC;GAC9D,SAAS;IACR,eAAe,UAAU,IAAI;IAC7B,gBAAgB;GACjB;GACA,QAAQ;EACT,CACD;EACA,IAAI,CAAC,SAAS,IAAI,MAAM,IAAI,MAAM,0BAA0B,SAAS,QAAQ;EAC7E,MAAM,SAAS,UAAU,MAAM,MAAM,SAAS,KAAK,CAAC;EACpD,IAAI,OAAO,UAAU,MAAM,MAAM,IAAI,MAAM,GAAG,OAAO,MAAM,SAAS,OAAO,MAAM,EAAE;EACnF,OAAO;GAAE,MAAM,OAAO;GAAM,OAAO,OAAO;EAAM;CACjD;AACD"}

package/dist/vite.d.ts

@@ -0,0 +1,5 @@
+import { ConfigEnv } from "vite";
+//#region vite.d.ts
+export declare function contextlayer({ command }: ConfigEnv): Promise<import("vite").Plugin<any>[]>;
+//#endregion
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","names":[],"sources":["../vite.ts"],"mappings":";;wBAIsB,eAAe,WAAW,YAAS,uBAAA"}

package/dist/vite.js

@@ -0,0 +1,22 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { getLocalToolsBindings } from "@usecontextlayer/cli/vite";
+//#region vite.ts
+async function contextlayer({ command }) {
+	return cloudflare({
+		auxiliaryWorkers: [{
+			config: command === "serve" ? { vars: await getLocalToolsBindings() } : {},
+			configPath: "workers/local-tools/wrangler.jsonc",
+			devOnly: true
+		}],
+		config: command === "serve" ? { services: [{
+			binding: "TOOLS",
+			entrypoint: "Tools",
+			service: "ctx-local-tools"
+		}] } : {},
+		viteEnvironment: { name: "ssr" }
+	});
+}
+//#endregion
+export { contextlayer };
+
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","names":[],"sources":["../vite.ts"],"sourcesContent":["import { cloudflare } from \"@cloudflare/vite-plugin\"\nimport { getLocalToolsBindings } from \"@usecontextlayer/cli/vite\"\nimport type { ConfigEnv } from \"vite\"\n\nexport async function contextlayer({ command }: ConfigEnv) {\n\treturn cloudflare({\n\t\tauxiliaryWorkers: [\n\t\t\t{\n\t\t\t\tconfig: command === \"serve\" ? { vars: await getLocalToolsBindings() } : {},\n\t\t\t\tconfigPath: \"workers/local-tools/wrangler.jsonc\",\n\t\t\t\tdevOnly: true,\n\t\t\t},\n\t\t],\n\t\tconfig:\n\t\t\tcommand === \"serve\"\n\t\t\t\t? {\n\t\t\t\t\t\tservices: [\n\t\t\t\t\t\t\t{ binding: \"TOOLS\", entrypoint: \"Tools\", service: \"ctx-local-tools\" },\n\t\t\t\t\t\t],\n\t\t\t\t\t}\n\t\t\t\t: {},\n\t\tviteEnvironment: { name: \"ssr\" },\n\t})\n}\n"],"mappings":";;;AAIA,eAAsB,aAAa,EAAE,WAAsB;CAC1D,OAAO,WAAW;EACjB,kBAAkB,CACjB;GACC,QAAQ,YAAY,UAAU,EAAE,MAAM,MAAM,sBAAsB,EAAE,IAAI,CAAC;GACzE,YAAY;GACZ,SAAS;EACV,CACD;EACA,QACC,YAAY,UACT,EACA,UAAU,CACT;GAAE,SAAS;GAAS,YAAY;GAAS,SAAS;EAAkB,CACrE,EACD,IACC,CAAC;EACL,iBAAiB,EAAE,MAAM,MAAM;CAChC,CAAC;AACF"}

package/dist/worker.d.ts

@@ -0,0 +1,16 @@
+import { Tools } from "./index.js";
+import { createRequestHandler } from "react-router";
+//#region worker.d.ts
+export declare function createApp({ build, mode, development }: {
+  build: Parameters<typeof createRequestHandler>[0];
+  mode: string;
+  development: boolean;
+}): {
+  fetch(request: Request, env: {
+    TOOLS: Tools;
+  }, ctx: ExecutionContext<{
+    tools: Tools;
+  }>): Promise<Response>;
+};
+//#endregion
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","names":[],"sources":["../worker.ts"],"mappings":";;;wBAGgB,YACf,OACA,MACA;EAEA,OAAO,kBAAkB;EACzB;EACA;;EAIO,MAAK,SACD,SAAO;IACT,OAAO;KAAO,KAChB;IAAmB,OAAO;OAAQ,QAAA"}

package/dist/worker.js

@@ -0,0 +1,15 @@
+import { toolsContext } from "./index.js";
+import { RouterContextProvider, createRequestHandler } from "react-router";
+//#region worker.ts
+function createApp({ build, mode, development }) {
+	const requestHandler = createRequestHandler(build, mode);
+	return { async fetch(request, env, ctx) {
+		const context = new RouterContextProvider();
+		context.set(toolsContext, development ? env.TOOLS : ctx.props.tools);
+		return requestHandler(request, context);
+	} };
+}
+//#endregion
+export { createApp };
+
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","names":[],"sources":["../worker.ts"],"sourcesContent":["import { createRequestHandler, RouterContextProvider } from \"react-router\"\nimport { type Tools, toolsContext } from \"@/index\"\n\nexport function createApp({\n\tbuild,\n\tmode,\n\tdevelopment,\n}: {\n\tbuild: Parameters<typeof createRequestHandler>[0]\n\tmode: string\n\tdevelopment: boolean\n}) {\n\tconst requestHandler = createRequestHandler(build, mode)\n\treturn {\n\t\tasync fetch(\n\t\t\trequest: Request,\n\t\t\tenv: { TOOLS: Tools },\n\t\t\tctx: ExecutionContext<{ tools: Tools }>,\n\t\t) {\n\t\t\tconst context = new RouterContextProvider()\n\t\t\tcontext.set(toolsContext, development ? env.TOOLS : ctx.props.tools)\n\t\t\treturn requestHandler(request, context)\n\t\t},\n\t}\n}\n"],"mappings":";;;AAGA,SAAgB,UAAU,EACzB,OACA,MACA,eAKE;CACF,MAAM,iBAAiB,qBAAqB,OAAO,IAAI;CACvD,OAAO,EACN,MAAM,MACL,SACA,KACA,KACC;EACD,MAAM,UAAU,IAAI,sBAAsB;EAC1C,QAAQ,IAAI,cAAc,cAAc,IAAI,QAAQ,IAAI,MAAM,KAAK;EACnE,OAAO,eAAe,SAAS,OAAO;CACvC,EACD;AACD"}

package/examples/gmail.tsx

@@ -0,0 +1,55 @@
+import { toolsContext } from "@usecontextlayer/sdk"
+import { type LoaderFunctionArgs, useLoaderData } from "react-router"
+import { z } from "zod"
+
+const inbox = z.object({
+	messages: z.array(
+		z.object({
+			messageId: z.string(),
+			messageTimestamp: z.string(),
+			sender: z.string(),
+			subject: z.string(),
+		}),
+	),
+})
+
+export async function loader({ context }: LoaderFunctionArgs) {
+	const result = await context
+		.get(toolsContext)
+		.call("work-email", "GMAIL_FETCH_EMAILS", {
+			include_payload: false,
+			label_ids: ["INBOX"],
+			max_results: 5,
+			verbose: false,
+		})
+	return { logId: result.logId, messages: inbox.parse(result.data).messages }
+}
+
+export default function Home() {
+	const loaderData = useLoaderData<typeof loader>()
+	return (
+		<main className="mx-auto max-w-3xl p-8">
+			<h1 className="text-2xl font-semibold">Your Gmail inbox</h1>
+			<p className="mt-2 text-sm text-gray-500">
+				Fetched by this page's server loader through your assigned Gmail connection.
+			</p>
+			<ul className="mt-6 divide-y divide-gray-200">
+				{loaderData.messages.map((message) => (
+					<li
+						key={message.messageId}
+						className="py-4"
+					>
+						<h2 className="font-medium">{message.subject}</h2>
+						<p className="mt-1 text-sm text-gray-500">{message.sender}</p>
+						<time
+							className="text-xs text-gray-500"
+							dateTime={message.messageTimestamp}
+						>
+							{message.messageTimestamp}
+						</time>
+					</li>
+				))}
+			</ul>
+		</main>
+	)
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@usecontextlayer/cli": "0.12.1"
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "^1.62.4",
+    "@cloudflare/workers-types": "^5.20261001.1",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.0.0",
+    "react-router": "^8.4.0",
+    "tsdown": "latest",
+    "typescript": "latest",
+    "vite": "^8.3.2"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./local": {
+      "import": "./dist/local.js",
+      "types": "./dist/local.d.ts"
+    },
+    "./vite": {
+      "import": "./dist/vite.js",
+      "types": "./dist/vite.d.ts"
+    },
+    "./worker": {
+      "import": "./dist/worker.js",
+      "types": "./dist/worker.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "examples"
+  ],
+  "name": "@usecontextlayer/sdk",
+  "peerDependencies": {
+    "@cloudflare/vite-plugin": "^1.62.4",
+    "react-router": "^8.4.0",
+    "vite": "^8.3.2"
+  },
+  "type": "module",
+  "version": "0.12.1",
+  "scripts": {
+    "build": "tsdown",
+    "dev:watch": "tsdown --watch",
+    "tsc": "tsc -b tsconfig.json"
+  }
+}