@roj-ai/client 0.0.2

package/src/platform/rpc-definition.ts

@@ -0,0 +1,57 @@
+/**
+ * Type-safe RPC definition system.
+ * No external dependencies — just TypeScript types + minimal runtime.
+ *
+ * Usage:
+ *   const methods = defineMethods({
+ *     'instances.create': method<CreateInput, CreateOutput>(),
+ *     'sessions.list': method<ListInput, ListOutput>(),
+ *   })
+ */
+
+/** Marker type for a method definition (input → output). */
+export interface MethodDef<I = unknown, O = unknown> {
+	readonly _input: I
+	readonly _output: O
+}
+
+/** Define a method type. Zero runtime cost — just a type marker. */
+export function method<I, O>(): MethodDef<I, O> {
+	return {} as MethodDef<I, O>
+}
+
+/** Define a set of methods. Returns the definition object as-is (typed). */
+export function defineMethods<T extends Record<string, MethodDef>>(methods: T): T {
+	return methods
+}
+
+/** Extract input type from a method name. */
+export type MethodInput<
+	Methods extends Record<string, MethodDef>,
+	M extends keyof Methods,
+> = Methods[M]['_input']
+
+/** Extract output type from a method name. */
+export type MethodOutput<
+	Methods extends Record<string, MethodDef>,
+	M extends keyof Methods,
+> = Methods[M]['_output']
+
+/** RPC request envelope. */
+export interface RpcRequest<M extends string = string> {
+	method: M
+	input: unknown
+}
+
+/** RPC response envelope. */
+export interface RpcResponse<T = unknown> {
+	ok: boolean
+	value?: T
+	error?: RpcError
+}
+
+export interface RpcError {
+	type: string
+	message: string
+	details?: unknown
+}

package/src/platform/rpc-server.ts

@@ -0,0 +1,60 @@
+/**
+ * Type-safe RPC server handler.
+ * Maps method names to handler functions, dispatches incoming requests.
+ *
+ * Usage:
+ *   const router = createRpcRouter(platformMethods, {
+ *     'instances.create': async (input, ctx) => { ... },
+ *     'instances.get': async (input, ctx) => { ... },
+ *   })
+ *   // In Hono route:
+ *   app.post('/rpc', (c) => router.handle(c.req.json(), ctx))
+ */
+import type { MethodDef, MethodInput, MethodOutput, RpcError, RpcRequest, RpcResponse } from './rpc-definition'
+
+export type MethodHandler<
+	Methods extends Record<string, MethodDef>,
+	M extends keyof Methods,
+	Ctx,
+> = (input: MethodInput<Methods, M>, ctx: Ctx) => Promise<MethodOutput<Methods, M>>
+
+export type MethodHandlers<
+	Methods extends Record<string, MethodDef>,
+	Ctx,
+> = {
+	[M in keyof Methods]: MethodHandler<Methods, M, Ctx>
+}
+
+export interface RpcRouter<Ctx> {
+	handle(request: RpcRequest, ctx: Ctx): Promise<RpcResponse>
+}
+
+export function createRpcRouter<
+	Methods extends Record<string, MethodDef>,
+	Ctx,
+>(
+	_methods: Methods,
+	handlers: MethodHandlers<Methods, Ctx>,
+): RpcRouter<Ctx> {
+	return {
+		async handle(request: RpcRequest, ctx: Ctx): Promise<RpcResponse> {
+			const handler = handlers[request.method as keyof Methods]
+			if (!handler) {
+				return {
+					ok: false,
+					error: { type: 'method_not_found', message: `Unknown method: ${request.method}` },
+				}
+			}
+
+			try {
+				const result = await handler(request.input as any, ctx)
+				return { ok: true, value: result }
+			} catch (error) {
+				const rpcError: RpcError = error instanceof Error
+					? { type: 'handler_error', message: error.message }
+					: { type: 'unknown_error', message: String(error) }
+				return { ok: false, error: rpcError }
+			}
+		},
+	}
+}

package/src/platform/sandbox-state.ts

@@ -0,0 +1 @@
+export type SandboxState = 'stopped' | 'starting' | 'running' | 'pausing' | 'paused' | 'failed'

package/src/platform/urls.ts

@@ -0,0 +1,62 @@
+/**
+ * Convert an instance UUID to its full 32-char hex representation (no hyphens, lowercase).
+ */
+export function instanceIdToHex(instanceId: string): string {
+	return instanceId.replace(/-/g, '').toLowerCase()
+}
+
+export interface BuildPreviewUrlOptions {
+	instanceId: string
+	code: string
+	baseDomain: string
+	/** Optional instance token appended as ?token= for auth */
+	token?: string
+	/** Platform URL for path-based preview (used when subdomains aren't available) */
+	platformUrl?: string
+}
+
+/**
+ * Build a dev preview URL for a service running in a roj sandbox.
+ *
+ * Production: https://dev-{slug}-{code}.{baseDomain}/
+ * Local dev:  {platformUrl}/api/v1/instances/{id}/preview/{code}/
+ */
+export function buildPreviewUrl({ instanceId, code, baseDomain, token, platformUrl }: BuildPreviewUrlOptions): string {
+	// Cloudflare quick tunnels are already subdomains — can't nest further
+	if (baseDomain.includes('trycloudflare.com') && platformUrl) {
+		const base = `${platformUrl}/api/v1/instances/${instanceId}/preview/${code}`
+		return token ? `${base}/?token=${encodeURIComponent(token)}` : base
+	}
+
+	// Subdomain-based: dev-{hex}-{code}.{baseDomain}
+	// Works on localhost (*.localhost resolves to 127.0.0.1) and production
+	const hex = instanceIdToHex(instanceId)
+	const protocol = baseDomain.includes('localhost') ? 'http' : 'https'
+	const base = `${protocol}://dev-${hex}-${code}.${baseDomain}`
+	return token ? `${base}/?token=${encodeURIComponent(token)}` : base
+}
+
+export interface BuildWsUrlOptions {
+	platformUrl: string
+	instanceId: string
+	sessionId: string
+	token: string
+}
+
+/**
+ * Build a WebSocket URL for connecting to a roj instance.
+ */
+export function buildWsUrl({ platformUrl, instanceId, sessionId, token }: BuildWsUrlOptions): string {
+	const url = new URL(`/api/v1/instances/${instanceId}/ws`, platformUrl)
+	url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+	url.searchParams.set('token', token)
+	url.searchParams.set('sessionId', sessionId)
+	return url.toString()
+}
+
+/**
+ * Build the RPC base URL for a roj instance.
+ */
+export function buildApiBaseUrl(platformUrl: string, instanceId: string): string {
+	return `${platformUrl}/api/v1/instances/${instanceId}`
+}