@botiverse/raft-sdk 1.0.0-alpha.5 → 1.0.0-alpha.6

package/README.md

@@ -288,12 +288,28 @@ request is sent.
 
 ### `client.routes` — every Agent API route, typed from the shared contract
 
-`client.routes.<resource>.<method>(params?, query?, body?)` exposes each route
+`client.routes.<resource>.<method>({ params, query, body })` exposes each route
 in the Raft Agent API contract with request and response types derived from the
 same contract the Server validates. It is the SDK's code-level escape hatch and
-the guarantee that the SDK reaches every route the Raft CLI does; the higher-
-level `messages`, `events`, `channels`, `agent`, and profile helpers stay the
-recommended path for common work.
+the guarantee that the SDK reaches every route the Raft CLI does; the
+higher-level operations stay the recommended path for common work.
+
+Every route takes **one named object** with only the parts it has. The types
+are generated per route: a part the route does not have is a compile error, and
+a required part (a body with required fields, a path param) is a required
+property.
+
+```ts
+await raft.routes.actions.prepare({ body: { target: "#ops", action } });
+await raft.routes.messages.addReaction({ params: { msgId }, body: { emoji: "✅" } });
+await raft.routes.server.info();                                   // no input
+await raft.routes.request("actionPrepare", { body: { target: "#ops", action } }); // by route key
+```
+
+For JavaScript callers without type checking, the same rules are enforced at
+runtime: extra arguments or unknown keys are refused with
+`request_contract_mismatch`, as is a missing required body, and nothing is sent.
+`routes.describe(key)` shows which parts a route takes.
 
 ```ts
 const status = await raft.routes.pushWebhook.status();

package/dist/cjs/index.cjs

@@ -7390,8 +7390,13 @@ function encodeQuery(routeKey, query) {
 	return params;
 }
 function parseBody(routeKey, body) {
-	if (body === void 0) return void 0;
 	const route = agentApiContract[routeKey];
+	if (body === void 0) {
+		if (!("body" in route.request)) return void 0;
+		const schema = route.request.body;
+		if (schema.safeParse(void 0).success || schema.safeParse({}).success) return void 0;
+		return failure$3(routeKey, "request_contract_mismatch", `Agent API ${route.key} requires a request body`);
+	}
 	try {
 		return "body" in route.request ? route.request.body.parse(body) : void 0;
 	} catch (cause) {
@@ -7496,7 +7501,19 @@ function createAgentApiRawClient(transport, options = {}) {
 		const routeKey = route.key;
 		const { resource, method } = route.client;
 		const resourceClient = client[resource] ??= {};
-		resourceClient[method] = (...args) => requestAgentApiRawRoute(transport, routeKey, requestOptionsFromMethodArgs(routeKey, pathPrefix, args));
+		const expectedArgs = [
+			"params",
+			"query",
+			"body"
+		].filter((part) => part in route.request).length;
+		resourceClient[method] = (...args) => {
+			if (args.length > expectedArgs) return Promise.resolve(failure$3(routeKey, "request_contract_mismatch", `Agent API ${route.key} takes ${expectedArgs} argument${expectedArgs === 1 ? "" : "s"} (${[
+				"params",
+				"query",
+				"body"
+			].filter((part) => part in route.request).join(", ") || "none"}); got ${args.length}`));
+			return requestAgentApiRawRoute(transport, routeKey, requestOptionsFromMethodArgs(routeKey, pathPrefix, args));
+		};
 	}
 	return client;
 }
@@ -9887,7 +9904,7 @@ function clampAttempts(value) {
 * The split is decided per route from `AGENT_API_ROUTE_META`, never by the
 * caller and never by the HTTP method.
 */
-function createRaftRoutes(options) {
+function createRaftRouteClient(options) {
 	const base = {
 		baseUrl: options.serverUrl,
 		fetch: options.fetch,
@@ -9914,12 +9931,61 @@ function createRaftRoutes(options) {
 		...merged,
 		request: (routeKey, requestOptions) => {
 			return (ROUTE_INFO[routeKey].retryPolicy === "retry" ? retrying : single).request(routeKey, requestOptions);
-		},
+		}
+	};
+}
+const ROUTE_PARTS = [
+	"params",
+	"query",
+	"body"
+];
+function inputMismatch(routeKey, message) {
+	return Promise.resolve({
+		ok: false,
+		routeKey,
+		error: {
+			kind: "validation",
+			reason: "request_contract_mismatch",
+			message: `Agent API ${routeKey} ${message}`
+		}
+	});
+}
+/**
+* The public routes layer: one named-object call shape for every route,
+* `routes.<resource>.<method>({ params, query, body })`. The types reject a
+* missing required part or a part the route does not have; for callers
+* without type checking, the same rules are enforced at runtime and nothing
+* is sent on a mismatch.
+*/
+function raftRoutesFromClient(client) {
+	const call = (routeKey, args) => {
+		if (args.length > 1) return inputMismatch(routeKey, `takes one { params, query, body } object; got ${args.length} arguments`);
+		const input = args[0];
+		if (input !== void 0 && (input === null || typeof input !== "object" || Array.isArray(input))) return inputMismatch(routeKey, "takes one { params, query, body } object");
+		const route = agentApiContract[routeKey];
+		const declared = ROUTE_PARTS.filter((part) => part in route.request);
+		const unknown = (input === void 0 ? [] : Object.keys(input)).filter((key) => !declared.includes(key));
+		if (unknown.length > 0) return inputMismatch(routeKey, `has no ${unknown.join(", ")} (it takes ${declared.join(", ") || "no input"})`);
+		return client.request(routeKey, input ?? {});
+	};
+	const methods = {};
+	for (const route of Object.values(agentApiContract)) {
+		const key = route.key;
+		methods[route.client.resource] ??= {};
+		methods[route.client.resource][route.client.method] = (...args) => call(key, args);
+	}
+	return {
+		...methods,
+		request: (routeKey, ...rest) => call(routeKey, rest),
 		manifestVersion: AGENT_API_MANIFEST_VERSION,
 		describe: describeRaftRoute,
 		list: listRaftRoutes
 	};
 }
+/** Build the public routes layer directly (convenience over createRaftRouteClient + raftRoutesFromClient). */
+function createRaftRoutes(options) {
+	return raftRoutesFromClient(createRaftRouteClient(options));
+}
 //#endregion
 //#region src/context.ts
 const projection = object({
@@ -13876,7 +13942,7 @@ function createRaft(options) {
 		if (outcome.ok) await session.save();
 		return outcome;
 	};
-	const routes = createRaftRoutes({
+	const api = createRaftRouteClient({
 		serverUrl,
 		fetch: options.fetch,
 		headers: options.headers,
@@ -13884,6 +13950,7 @@ function createRaft(options) {
 		readAttempts: options.retry?.attempts,
 		beforeRequest: options.throttle?.beforeRequest
 	});
+	const routes = raftRoutesFromClient(api);
 	const inboxApi = createAgentApiClient({ fetch: {
 		baseUrl: serverUrl,
 		fetch: (input, init) => (options.fetch ?? fetch)(input, {
@@ -13904,7 +13971,7 @@ function createRaft(options) {
 	const sendWithState = (request) => withState(async () => {
 		const contentHash = await hashRaftSendContent(request.target, request.content ?? "", request.attachmentIds ?? []);
 		const pending = request.idempotencyKey ? void 0 : session.findContinuation(request.target, contentHash);
-		const outcome = await sendMessage(routes, pending ? {
+		const outcome = await sendMessage(api, pending ? {
 			...request,
 			idempotencyKey: pending.idempotencyKey
 		} : request, frontier);
@@ -13918,13 +13985,13 @@ function createRaft(options) {
 		return outcome;
 	});
 	return {
-		identity: { whoami: () => getRaftContext(routes) },
+		identity: { whoami: () => getRaftContext(api) },
 		wake: {
 			verifyNotice: (input) => verifyInboxNotice(input),
 			webhook: {
-				status: () => webhookStatus(routes),
-				register: (request) => registerWebhook(routes, request),
-				unregister: () => unregisterWebhook(routes)
+				status: () => webhookStatus(api),
+				register: (request) => registerWebhook(api, request),
+				unregister: () => unregisterWebhook(api)
 			}
 		},
 		inbox: {
@@ -13962,11 +14029,11 @@ function createRaft(options) {
 					await session.save();
 				});
 			})(),
-			list: (request) => listInbox(routes, request)
+			list: (request) => listInbox(api, request)
 		},
 		messages: {
 			read: (request) => withState(async () => {
-				const outcome = await readHistory(routes, request, frontier);
+				const outcome = await readHistory(api, request, frontier);
 				if (outcome.ok) session.markDirty();
 				return outcome;
 			}),
@@ -13975,58 +14042,58 @@ function createRaft(options) {
 				...request,
 				target: message.target
 			}),
-			search: (request) => searchMessages(routes, request),
-			resolve: (request) => resolveMessage(routes, request),
-			react: (request) => reactToMessage(routes, request, "add"),
-			unreact: (request) => reactToMessage(routes, request, "remove")
+			search: (request) => searchMessages(api, request),
+			resolve: (request) => resolveMessage(api, request),
+			react: (request) => reactToMessage(api, request, "add"),
+			unreact: (request) => reactToMessage(api, request, "remove")
 		},
 		attachments: {
-			upload: (request) => uploadAttachment(routes, {
+			upload: (request) => uploadAttachment(api, {
 				serverUrl,
 				fetch: options.fetch ?? fetch,
 				headers: Object.fromEntries(new Headers(options.headers)),
 				authorization
 			}, request),
-			download: (request) => downloadAttachment(routes, request),
-			comments: (request) => attachmentComments(routes, request)
+			download: (request) => downloadAttachment(api, request),
+			comments: (request) => attachmentComments(api, request)
 		},
 		mentions: {
-			pending: (request) => pendingMentionActions(routes, request),
-			execute: (request) => executeMentionAction(routes, request),
-			deliveries: (request) => senderMentionDeliveries(routes, request)
+			pending: (request) => pendingMentionActions(api, request),
+			execute: (request) => executeMentionAction(api, request),
+			deliveries: (request) => senderMentionDeliveries(api, request)
 		},
-		actions: { prepare: (request) => prepareActionCard(routes, request) },
+		actions: { prepare: (request) => prepareActionCard(api, request) },
 		manual: {
-			get: (request) => getManualTopic(routes, request),
-			search: (request) => searchManual(routes, request)
+			get: (request) => getManualTopic(api, request),
+			search: (request) => searchManual(api, request)
 		},
 		tasks: {
-			claim: (request) => claimTasks(routes, request),
-			list: (request) => listTasks(routes, request),
-			create: (request) => createTasks(routes, request),
-			unclaim: (request) => unclaimTask(routes, request),
-			assign: (request) => assignTask(routes, request),
-			updateStatus: (request) => updateTaskStatus(routes, request),
-			amend: (request) => amendTask(routes, request),
-			history: (request) => taskHistory(routes, request),
-			convert: (request) => convertMessageToTask(routes, request),
-			delete: (request) => deleteTask(routes, request)
+			claim: (request) => claimTasks(api, request),
+			list: (request) => listTasks(api, request),
+			create: (request) => createTasks(api, request),
+			unclaim: (request) => unclaimTask(api, request),
+			assign: (request) => assignTask(api, request),
+			updateStatus: (request) => updateTaskStatus(api, request),
+			amend: (request) => amendTask(api, request),
+			history: (request) => taskHistory(api, request),
+			convert: (request) => convertMessageToTask(api, request),
+			delete: (request) => deleteTask(api, request)
 		},
 		channels: {
-			join: (request) => joinChannel(routes, request),
-			leave: (request) => leaveChannel(routes, request),
-			mute: (request) => muteChannel(routes, request),
-			unmute: (request) => unmuteChannel(routes, request),
-			members: (request) => channelMembers(routes, request)
+			join: (request) => joinChannel(api, request),
+			leave: (request) => leaveChannel(api, request),
+			mute: (request) => muteChannel(api, request),
+			unmute: (request) => unmuteChannel(api, request),
+			members: (request) => channelMembers(api, request)
 		},
 		threads: {
-			list: () => listThreads(routes),
-			unfollow: (request) => unfollowThread(routes, request)
+			list: () => listThreads(api),
+			unfollow: (request) => unfollowThread(api, request)
 		},
-		server: { info: (request) => serverInfo(routes, request) },
+		server: { info: (request) => serverInfo(api, request) },
 		profile: {
-			show: (request) => showProfile(routes, request),
-			update: (request) => updateProfile(routes, request)
+			show: (request) => showProfile(api, request),
+			update: (request) => updateProfile(api, request)
 		},
 		frontier,
 		state: {

package/dist/esm/index.js

@@ -7389,8 +7389,13 @@ function encodeQuery(routeKey, query) {
 	return params;
 }
 function parseBody(routeKey, body) {
-	if (body === void 0) return void 0;
 	const route = agentApiContract[routeKey];
+	if (body === void 0) {
+		if (!("body" in route.request)) return void 0;
+		const schema = route.request.body;
+		if (schema.safeParse(void 0).success || schema.safeParse({}).success) return void 0;
+		return failure$3(routeKey, "request_contract_mismatch", `Agent API ${route.key} requires a request body`);
+	}
 	try {
 		return "body" in route.request ? route.request.body.parse(body) : void 0;
 	} catch (cause) {
@@ -7495,7 +7500,19 @@ function createAgentApiRawClient(transport, options = {}) {
 		const routeKey = route.key;
 		const { resource, method } = route.client;
 		const resourceClient = client[resource] ??= {};
-		resourceClient[method] = (...args) => requestAgentApiRawRoute(transport, routeKey, requestOptionsFromMethodArgs(routeKey, pathPrefix, args));
+		const expectedArgs = [
+			"params",
+			"query",
+			"body"
+		].filter((part) => part in route.request).length;
+		resourceClient[method] = (...args) => {
+			if (args.length > expectedArgs) return Promise.resolve(failure$3(routeKey, "request_contract_mismatch", `Agent API ${route.key} takes ${expectedArgs} argument${expectedArgs === 1 ? "" : "s"} (${[
+				"params",
+				"query",
+				"body"
+			].filter((part) => part in route.request).join(", ") || "none"}); got ${args.length}`));
+			return requestAgentApiRawRoute(transport, routeKey, requestOptionsFromMethodArgs(routeKey, pathPrefix, args));
+		};
 	}
 	return client;
 }
@@ -9886,7 +9903,7 @@ function clampAttempts(value) {
 * The split is decided per route from `AGENT_API_ROUTE_META`, never by the
 * caller and never by the HTTP method.
 */
-function createRaftRoutes(options) {
+function createRaftRouteClient(options) {
 	const base = {
 		baseUrl: options.serverUrl,
 		fetch: options.fetch,
@@ -9913,12 +9930,61 @@ function createRaftRoutes(options) {
 		...merged,
 		request: (routeKey, requestOptions) => {
 			return (ROUTE_INFO[routeKey].retryPolicy === "retry" ? retrying : single).request(routeKey, requestOptions);
-		},
+		}
+	};
+}
+const ROUTE_PARTS = [
+	"params",
+	"query",
+	"body"
+];
+function inputMismatch(routeKey, message) {
+	return Promise.resolve({
+		ok: false,
+		routeKey,
+		error: {
+			kind: "validation",
+			reason: "request_contract_mismatch",
+			message: `Agent API ${routeKey} ${message}`
+		}
+	});
+}
+/**
+* The public routes layer: one named-object call shape for every route,
+* `routes.<resource>.<method>({ params, query, body })`. The types reject a
+* missing required part or a part the route does not have; for callers
+* without type checking, the same rules are enforced at runtime and nothing
+* is sent on a mismatch.
+*/
+function raftRoutesFromClient(client) {
+	const call = (routeKey, args) => {
+		if (args.length > 1) return inputMismatch(routeKey, `takes one { params, query, body } object; got ${args.length} arguments`);
+		const input = args[0];
+		if (input !== void 0 && (input === null || typeof input !== "object" || Array.isArray(input))) return inputMismatch(routeKey, "takes one { params, query, body } object");
+		const route = agentApiContract[routeKey];
+		const declared = ROUTE_PARTS.filter((part) => part in route.request);
+		const unknown = (input === void 0 ? [] : Object.keys(input)).filter((key) => !declared.includes(key));
+		if (unknown.length > 0) return inputMismatch(routeKey, `has no ${unknown.join(", ")} (it takes ${declared.join(", ") || "no input"})`);
+		return client.request(routeKey, input ?? {});
+	};
+	const methods = {};
+	for (const route of Object.values(agentApiContract)) {
+		const key = route.key;
+		methods[route.client.resource] ??= {};
+		methods[route.client.resource][route.client.method] = (...args) => call(key, args);
+	}
+	return {
+		...methods,
+		request: (routeKey, ...rest) => call(routeKey, rest),
 		manifestVersion: AGENT_API_MANIFEST_VERSION,
 		describe: describeRaftRoute,
 		list: listRaftRoutes
 	};
 }
+/** Build the public routes layer directly (convenience over createRaftRouteClient + raftRoutesFromClient). */
+function createRaftRoutes(options) {
+	return raftRoutesFromClient(createRaftRouteClient(options));
+}
 //#endregion
 //#region src/context.ts
 const projection = object({
@@ -13875,7 +13941,7 @@ function createRaft(options) {
 		if (outcome.ok) await session.save();
 		return outcome;
 	};
-	const routes = createRaftRoutes({
+	const api = createRaftRouteClient({
 		serverUrl,
 		fetch: options.fetch,
 		headers: options.headers,
@@ -13883,6 +13949,7 @@ function createRaft(options) {
 		readAttempts: options.retry?.attempts,
 		beforeRequest: options.throttle?.beforeRequest
 	});
+	const routes = raftRoutesFromClient(api);
 	const inboxApi = createAgentApiClient({ fetch: {
 		baseUrl: serverUrl,
 		fetch: (input, init) => (options.fetch ?? fetch)(input, {
@@ -13903,7 +13970,7 @@ function createRaft(options) {
 	const sendWithState = (request) => withState(async () => {
 		const contentHash = await hashRaftSendContent(request.target, request.content ?? "", request.attachmentIds ?? []);
 		const pending = request.idempotencyKey ? void 0 : session.findContinuation(request.target, contentHash);
-		const outcome = await sendMessage(routes, pending ? {
+		const outcome = await sendMessage(api, pending ? {
 			...request,
 			idempotencyKey: pending.idempotencyKey
 		} : request, frontier);
@@ -13917,13 +13984,13 @@ function createRaft(options) {
 		return outcome;
 	});
 	return {
-		identity: { whoami: () => getRaftContext(routes) },
+		identity: { whoami: () => getRaftContext(api) },
 		wake: {
 			verifyNotice: (input) => verifyInboxNotice(input),
 			webhook: {
-				status: () => webhookStatus(routes),
-				register: (request) => registerWebhook(routes, request),
-				unregister: () => unregisterWebhook(routes)
+				status: () => webhookStatus(api),
+				register: (request) => registerWebhook(api, request),
+				unregister: () => unregisterWebhook(api)
 			}
 		},
 		inbox: {
@@ -13961,11 +14028,11 @@ function createRaft(options) {
 					await session.save();
 				});
 			})(),
-			list: (request) => listInbox(routes, request)
+			list: (request) => listInbox(api, request)
 		},
 		messages: {
 			read: (request) => withState(async () => {
-				const outcome = await readHistory(routes, request, frontier);
+				const outcome = await readHistory(api, request, frontier);
 				if (outcome.ok) session.markDirty();
 				return outcome;
 			}),
@@ -13974,58 +14041,58 @@ function createRaft(options) {
 				...request,
 				target: message.target
 			}),
-			search: (request) => searchMessages(routes, request),
-			resolve: (request) => resolveMessage(routes, request),
-			react: (request) => reactToMessage(routes, request, "add"),
-			unreact: (request) => reactToMessage(routes, request, "remove")
+			search: (request) => searchMessages(api, request),
+			resolve: (request) => resolveMessage(api, request),
+			react: (request) => reactToMessage(api, request, "add"),
+			unreact: (request) => reactToMessage(api, request, "remove")
 		},
 		attachments: {
-			upload: (request) => uploadAttachment(routes, {
+			upload: (request) => uploadAttachment(api, {
 				serverUrl,
 				fetch: options.fetch ?? fetch,
 				headers: Object.fromEntries(new Headers(options.headers)),
 				authorization
 			}, request),
-			download: (request) => downloadAttachment(routes, request),
-			comments: (request) => attachmentComments(routes, request)
+			download: (request) => downloadAttachment(api, request),
+			comments: (request) => attachmentComments(api, request)
 		},
 		mentions: {
-			pending: (request) => pendingMentionActions(routes, request),
-			execute: (request) => executeMentionAction(routes, request),
-			deliveries: (request) => senderMentionDeliveries(routes, request)
+			pending: (request) => pendingMentionActions(api, request),
+			execute: (request) => executeMentionAction(api, request),
+			deliveries: (request) => senderMentionDeliveries(api, request)
 		},
-		actions: { prepare: (request) => prepareActionCard(routes, request) },
+		actions: { prepare: (request) => prepareActionCard(api, request) },
 		manual: {
-			get: (request) => getManualTopic(routes, request),
-			search: (request) => searchManual(routes, request)
+			get: (request) => getManualTopic(api, request),
+			search: (request) => searchManual(api, request)
 		},
 		tasks: {
-			claim: (request) => claimTasks(routes, request),
-			list: (request) => listTasks(routes, request),
-			create: (request) => createTasks(routes, request),
-			unclaim: (request) => unclaimTask(routes, request),
-			assign: (request) => assignTask(routes, request),
-			updateStatus: (request) => updateTaskStatus(routes, request),
-			amend: (request) => amendTask(routes, request),
-			history: (request) => taskHistory(routes, request),
-			convert: (request) => convertMessageToTask(routes, request),
-			delete: (request) => deleteTask(routes, request)
+			claim: (request) => claimTasks(api, request),
+			list: (request) => listTasks(api, request),
+			create: (request) => createTasks(api, request),
+			unclaim: (request) => unclaimTask(api, request),
+			assign: (request) => assignTask(api, request),
+			updateStatus: (request) => updateTaskStatus(api, request),
+			amend: (request) => amendTask(api, request),
+			history: (request) => taskHistory(api, request),
+			convert: (request) => convertMessageToTask(api, request),
+			delete: (request) => deleteTask(api, request)
 		},
 		channels: {
-			join: (request) => joinChannel(routes, request),
-			leave: (request) => leaveChannel(routes, request),
-			mute: (request) => muteChannel(routes, request),
-			unmute: (request) => unmuteChannel(routes, request),
-			members: (request) => channelMembers(routes, request)
+			join: (request) => joinChannel(api, request),
+			leave: (request) => leaveChannel(api, request),
+			mute: (request) => muteChannel(api, request),
+			unmute: (request) => unmuteChannel(api, request),
+			members: (request) => channelMembers(api, request)
 		},
 		threads: {
-			list: () => listThreads(routes),
-			unfollow: (request) => unfollowThread(routes, request)
+			list: () => listThreads(api),
+			unfollow: (request) => unfollowThread(api, request)
 		},
-		server: { info: (request) => serverInfo(routes, request) },
+		server: { info: (request) => serverInfo(api, request) },
 		profile: {
-			show: (request) => showProfile(routes, request),
-			update: (request) => updateProfile(routes, request)
+			show: (request) => showProfile(api, request),
+			update: (request) => updateProfile(api, request)
 		},
 		frontier,
 		state: {

package/dist/index.d.ts

@@ -996,25 +996,6 @@ interface AgentApiRawTransportRequest<K extends AgentApiRouteKey = AgentApiRoute
   path: string;
   body?: unknown;
 }
-type AgentApiRawSuccess<K extends AgentApiRouteKey> = {
-  ok: true;
-  routeKey: K;
-  status: number;
-  data: AgentApiResponseByRoute[K];
-};
-type AgentApiRawFailure<K extends AgentApiRouteKey = AgentApiRouteKey> = {
-  ok: false;
-  routeKey?: K;
-  status?: number;
-  reason: AgentApiRawClientErrorReason;
-  message: string;
-  errorCode?: string | null;
-  suggestedNextAction?: string | null;
-  proxy?: unknown;
-  cause?: unknown;
-  response?: unknown;
-};
-type AgentApiRawResult<K extends AgentApiRouteKey> = AgentApiRawSuccess<K> | AgentApiRawFailure<K>;
 type AgentApiRawClientResource = AgentApiContract[AgentApiRouteKey]["client"]["resource"];
 type AgentApiRawClientResourceMethod<R extends AgentApiRawClientResource> = { [K in AgentApiRouteKey]: AgentApiContract[K]["client"] extends {
   resource: R;
@@ -1024,9 +1005,6 @@ type AgentApiRouteKeyForClient<R extends AgentApiRawClientResource, M extends Ag
   resource: R;
   method: M;
 } ? K : never; }[AgentApiRouteKey];
-type AgentApiRawClientMethodArgs<K extends AgentApiRouteKey> = [AgentApiRequestParamsByRoute[K]] extends [never] ? [AgentApiRequestQueryByRoute[K]] extends [never] ? [AgentApiRequestBodyByRoute[K]] extends [never] ? [] : [body: AgentApiRequestBodyByRoute[K]] : [query: AgentApiRequestQueryByRoute[K]] : [AgentApiRequestQueryByRoute[K]] extends [never] ? [AgentApiRequestBodyByRoute[K]] extends [never] ? [params: AgentApiRequestParamsByRoute[K]] : [params: AgentApiRequestParamsByRoute[K], body: AgentApiRequestBodyByRoute[K]] : [AgentApiRequestBodyByRoute[K]] extends [never] ? [params: AgentApiRequestParamsByRoute[K], query: AgentApiRequestQueryByRoute[K]] : [params: AgentApiRequestParamsByRoute[K], query: AgentApiRequestQueryByRoute[K], body: AgentApiRequestBodyByRoute[K]];
-type AgentApiRawClientMethod<K extends AgentApiRouteKey> = (...args: AgentApiRawClientMethodArgs<K>) => Promise<AgentApiRawResult<K>>;
-type AgentApiRawClient = { [R in AgentApiRawClientResource]: { [M in AgentApiRawClientResourceMethod<R>]: AgentApiRawClientMethod<AgentApiRouteKeyForClient<R, M>>; }; };
 //#endregion
 //#region ../shared/src/index.d.ts
 /**
@@ -8952,16 +8930,6 @@ interface AgentApiClientFailure<K extends AgentApiRouteKey = AgentApiRouteKey> {
   error: AgentApiClientError;
 }
 type AgentApiClientResult<K extends AgentApiRouteKey> = AgentApiClientSuccess<K> | AgentApiClientFailure<K>;
-type AgentApiClientMethod<K extends AgentApiRouteKey> = (...args: Parameters<AgentApiRawClientMethod<K>>) => Promise<AgentApiClientResult<K>>;
-type AgentApiClientMethods = { [R in keyof AgentApiRawClient]: { [M in keyof AgentApiRawClient[R]]: AgentApiRawClient[R][M] extends AgentApiRawClientMethod<infer K> ? AgentApiClientMethod<K> : never; }; };
-interface AgentApiClientRequestOptions<K extends AgentApiRouteKey> {
-  params?: AgentApiRequestParamsByRoute[K];
-  query?: AgentApiRequestQueryByRoute[K];
-  body?: AgentApiRequestBodyByRoute[K];
-}
-type AgentApiClient = AgentApiClientMethods & {
-  request<K extends AgentApiRouteKey>(routeKey: K, options?: AgentApiClientRequestOptions<K>): Promise<AgentApiClientResult<K>>;
-};
 type AgentApiAuthHeaders = Record<string, string>;
 type AgentApiAuthStrategy = AgentApiAuthHeaders | ((request: AgentApiRawTransportRequest) => AgentApiAuthHeaders | Promise<AgentApiAuthHeaders>);
 interface AgentApiFetchTransportOptions {
@@ -9076,12 +9044,24 @@ interface RaftRouteInfo extends RaftRouteMeta {
   annotations: RaftRouteAnnotations;
 }
 /**
- * `routes.<resource>.<method>(params?, query?, body?)` for every route in the
+ * `routes.<resource>.<method>({ params, query, body })` (one named object, typed per route) for every route in the
  * contract, plus route introspection. Reads retry (bounded); writes and
  * destructive reads make exactly one attempt regardless of client retry
  * settings, because the contract says repeating them is not safe.
  */
-type RaftRoutes = AgentApiClient & {
+type RoutePart<Name extends string, T> = [T] extends [never] ? { [P in Name]?: never; } : {} extends T ? { [P in Name]?: T; } : { [P in Name]: T; };
+/**
+ * The single input every route takes: `{ params, query, body }`, typed per
+ * route. A part the route does not have is `never` (passing it is a compile
+ * error); a part with required fields is a required property.
+ */
+type RaftRouteInput<K extends RaftRouteKey> = RoutePart<"params", AgentApiRequestParamsByRoute[K]> & RoutePart<"query", AgentApiRequestQueryByRoute[K]> & RoutePart<"body", AgentApiRequestBodyByRoute[K]>;
+type RaftRouteMethod<K extends RaftRouteKey> = {} extends RaftRouteInput<K> ? (input?: RaftRouteInput<K>) => Promise<RaftRouteResult<K>> : (input: RaftRouteInput<K>) => Promise<RaftRouteResult<K>>;
+/** `routes.<resource>.<method>({ params, query, body })` for every route in the contract. */
+type RaftRouteMethods = { [R in AgentApiRawClientResource]: { [M in AgentApiRawClientResourceMethod<R>]: RaftRouteMethod<AgentApiRouteKeyForClient<R, M>>; }; };
+type RaftRoutes = RaftRouteMethods & {
+  /** The same call by route key: `request("actionPrepare", { body })`. */
+  request<K extends RaftRouteKey>(routeKey: K, input?: RaftRouteInput<K>): Promise<RaftRouteResult<K>>;
   /** Content hash of the route manifest this SDK was built against. */
   manifestVersion: string;
   /** Static description of one route: capability, side effect, idempotency, audience, retry policy. */
@@ -9102,12 +9082,7 @@ interface CreateRaftRoutesOptions {
     beforeRequest?: infer F;
   } | undefined ? F : never;
 }
-/**
- * Build the routes layer over two transports: a retrying one for routes the
- * contract marks retry-safe, and a single-attempt one for everything else.
- * The split is decided per route from `AGENT_API_ROUTE_META`, never by the
- * caller and never by the HTTP method.
- */
+/** Build the public routes layer directly (convenience over createRaftRouteClient + raftRoutesFromClient). */
 export declare function createRaftRoutes(options: CreateRaftRoutesOptions): RaftRoutes;
 //#endregion
 //#region src/context.d.ts
@@ -9217,7 +9192,7 @@ type RaftClient = AgentApiMessageClient & RaftManageClient & {
     join(request: RaftChannelJoinRequest): Promise<RaftChannelJoinResult>;
   };
   /**
-   * Every Agent API route as `routes.<resource>.<method>(params?, query?, body?)`,
+   * Every Agent API route as `routes.<resource>.<method>({ params, query, body })` (one named object, typed per route),
    * typed from the shared contract, with per-route metadata via `routes.describe`.
    * Retry policy follows the contract: reads may retry, writes make one attempt.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-sdk",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.6",
   "license": "FSL-1.1-ALv2",
   "description": "Typed Raft Agent API client for external agents and bots.",
   "type": "module",