@roj-ai/client 0.0.2

package/src/platform/instance-methods.ts

@@ -0,0 +1,153 @@
+/**
+ * Instance-scoped RPC method definitions.
+ *
+ * These methods are called from the SPA via POST /api/v1/instances/:id/rpc
+ * with instance token or cookie auth. The instance is already resolved by the route,
+ * so inputs do NOT contain instanceId.
+ *
+ * Shared between worker (server) and client SDK.
+ */
+import { defineMethods, method } from './rpc-definition'
+import type { PublishSessionOutput, GetAgentLogsOutput } from './methods'
+
+// ============================================================================
+// Sandbox methods
+// ============================================================================
+
+export type InstanceCreateSandboxInput = {}
+export interface InstanceCreateSandboxOutput {
+	sandboxId: string
+}
+
+export interface InstancePauseSandboxInput {
+	sandboxId: string
+}
+
+export type InstanceResumeSandboxInput = {}
+
+export interface InstanceTerminateSandboxInput {
+	sandboxId: string
+}
+
+export interface InstanceRestartAgentInput {
+	sandboxId: string
+}
+
+export interface InstanceGetAgentLogsInput {
+	sandboxId: string
+	lines?: number
+}
+
+export interface InstanceExecInSandboxInput {
+	command: string
+}
+
+export interface InstanceExecInSandboxOutput {
+	stdout: string
+	stderr: string
+	success: boolean
+}
+
+export interface InstanceValidateSandboxTokenInput {
+	sandboxId: string
+	token: string
+}
+
+export interface InstanceValidateSandboxTokenOutput {
+	value: boolean
+}
+
+// ============================================================================
+// Session methods
+// ============================================================================
+
+export interface InstanceCreateSessionInput {
+	presetId: string
+}
+
+export interface InstanceCreateSessionOutput {
+	sessionId: string
+}
+
+export type InstanceListSessionsInput = {}
+export interface InstanceListSessionsOutput {
+	sessions: Array<{
+		id: string
+		presetId: string | null
+		status: string
+		createdAt: number
+	}>
+}
+
+export interface InstancePublishSessionInput {
+	sessionId: string
+}
+
+// ============================================================================
+// Service methods
+// ============================================================================
+
+export interface InstanceGetServiceUrlInput {
+	sessionId: string
+	serviceType: string
+}
+
+export interface InstanceGetServiceUrlOutput {
+	url: string | null
+}
+
+export interface InstanceGetServiceUrlsInput {
+	sessionId: string
+}
+
+export interface InstanceGetServiceUrlsOutput {
+	services: Array<{
+		serviceType: string
+		code: string
+		port: number
+	}>
+}
+
+export interface InstanceEnsureSandboxOutput {
+	sandboxId: string
+	state: string
+}
+
+// ============================================================================
+// Shared output for void actions
+// ============================================================================
+
+export interface InstanceOkOutput {
+	ok: boolean
+}
+
+// ============================================================================
+// Method registry
+// ============================================================================
+
+export const instanceMethods = defineMethods({
+	// Sandbox
+	createSandbox: method<InstanceCreateSandboxInput, InstanceCreateSandboxOutput>(),
+	pauseSandbox: method<InstancePauseSandboxInput, InstanceOkOutput>(),
+	resumeSandbox: method<InstanceResumeSandboxInput, InstanceOkOutput>(),
+	terminateSandbox: method<InstanceTerminateSandboxInput, InstanceOkOutput>(),
+	restartAgent: method<InstanceRestartAgentInput, InstanceOkOutput>(),
+	getAgentLogs: method<InstanceGetAgentLogsInput, GetAgentLogsOutput>(),
+	execInSandbox: method<InstanceExecInSandboxInput, InstanceExecInSandboxOutput>(),
+	validateSandboxToken: method<InstanceValidateSandboxTokenInput, InstanceValidateSandboxTokenOutput>(),
+
+	// Sessions
+	createSession: method<InstanceCreateSessionInput, InstanceCreateSessionOutput>(),
+	listSessions: method<InstanceListSessionsInput, InstanceListSessionsOutput>(),
+	publishSession: method<InstancePublishSessionInput, PublishSessionOutput>(),
+
+	// Services
+	getServiceUrl: method<InstanceGetServiceUrlInput, InstanceGetServiceUrlOutput>(),
+	getServiceUrls: method<InstanceGetServiceUrlsInput, InstanceGetServiceUrlsOutput>(),
+
+	// Idempotent sandbox access
+	ensureSandbox: method<{}, InstanceEnsureSandboxOutput>(),
+})
+
+export type InstanceMethods = typeof instanceMethods
+export type InstanceMethodName = keyof InstanceMethods

package/src/platform/methods.ts

@@ -0,0 +1,343 @@
+/**
+ * Platform RPC method definitions.
+ *
+ * Single source of truth for all platform API method types.
+ * Shared between worker (server) and client SDK.
+ */
+import { defineMethods, method } from './rpc-definition'
+import type { SandboxState } from './sandbox-state'
+
+// ============================================================================
+// Instance methods
+// ============================================================================
+
+export interface CreateInstanceInput {
+	templateSlug: string
+	bundleSlug?: string
+	bundleRevisionId?: string
+	name: string
+	vcsType?: 'github' | 'gitLocal' | 'none'
+	metadata?: Record<string, unknown>
+	autoCreateSession?: {
+		presetId: string
+		blocking?: boolean
+		initialPrompt?: string
+		resourceIds?: string[]
+		fileIds?: string[]
+	}
+}
+
+export interface CreateInstanceOutput {
+	instanceId: string
+	status: 'created' | 'initializing' | 'ready'
+	sessionId?: string
+	wsToken?: string
+}
+
+export interface GetInstanceInput {
+	instanceId: string
+}
+
+export interface GetInstanceOutput {
+	instanceId: string
+	name: string
+	status: string
+	templateSlug: string
+	bundleSlug: string
+	bundleRevisionId: string
+	vcsType: string
+	metadata: Record<string, unknown> | null
+	createdAt: string
+}
+
+export interface GetInstanceStatusInput {
+	instanceId: string
+}
+
+export interface GetInstanceStatusOutput {
+	instanceId: string
+	status: string
+	sandbox: {
+		state: SandboxState
+		e2bId?: string
+		lastActivityAt?: string
+	} | null
+	sessions: Array<{
+		id: string
+		presetId: string | null
+		status: string
+		createdAt: string
+	}>
+	lifecycleEvents: Array<{
+		event: string
+		detail?: string
+		createdAt: string
+	}>
+	serviceUrls: Array<{
+		code: string
+		sessionId: string | null
+		serviceType: string | null
+		port: number
+	}>
+}
+
+export interface ArchiveInstanceInput {
+	instanceId: string
+}
+
+export interface ArchiveInstanceOutput {
+	ok: boolean
+}
+
+export interface ListInstancesInput {
+	limit?: number
+	offset?: number
+}
+
+export interface ListInstancesOutput {
+	instances: GetInstanceOutput[]
+	total: number
+}
+
+// ============================================================================
+// Session methods
+// ============================================================================
+
+export interface CreateSessionInput {
+	instanceId: string
+	presetId: string
+	blocking?: boolean
+	origin?: string
+	expiresIn?: number // token TTL in seconds (default 24h, max 7d)
+}
+
+export interface CreateSessionOutput {
+	sessionId: string
+	status: 'creating' | 'active'
+	wsToken?: string
+}
+
+export interface ListSessionsInput {
+	instanceId: string
+}
+
+export interface ListSessionsOutput {
+	sessions: Array<{
+		id: string
+		presetId: string | null
+		status: string
+		createdAt: string
+	}>
+}
+
+export interface PublishSessionInput {
+	instanceId: string
+	sessionId: string
+}
+
+export interface PublishSessionOutput {
+	ok: boolean
+	pushed: boolean
+	commitSha?: string
+	error?: string
+}
+
+// ============================================================================
+// Token methods
+// ============================================================================
+
+export interface CreateInstanceTokenInput {
+	instanceId: string
+	origin?: string
+	expiresIn?: number // token TTL in seconds (default 24h, max 7d)
+	meta?: Record<string, unknown> // custom claims propagated to plugin method caller context
+}
+
+export interface CreateInstanceTokenOutput {
+	token: string
+	expiresAt: string
+}
+
+// ============================================================================
+// Bundle methods
+// ============================================================================
+
+export interface ListBundlesInput {
+	limit?: number
+	offset?: number
+}
+
+export interface ListBundlesOutput {
+	bundles: Array<{
+		id: string
+		slug: string
+		name: string | null
+		description: string | null
+		latestRevision: { id: string; version: string | null; r2Key: string; createdAt: string } | null
+		createdAt: string
+	}>
+}
+
+export interface DeleteBundleInput {
+	bundleId?: string
+	bundleSlug?: string
+}
+
+export interface DeleteBundleOutput {
+	ok: boolean
+}
+
+// ============================================================================
+// Resource methods
+// ============================================================================
+
+export interface CreateResourceInput {
+	slug: string
+	name?: string
+	description?: string
+	fileId: string
+	label?: string
+}
+
+export interface CreateResourceOutput {
+	resourceId: string
+	revisionId: string
+}
+
+export interface AddResourceRevisionInput {
+	resourceId?: string
+	resourceSlug?: string
+	fileId: string
+	label?: string
+}
+
+export interface AddResourceRevisionOutput {
+	revisionId: string
+}
+
+export interface GetResourceInput {
+	resourceId?: string
+	resourceSlug?: string
+}
+
+export interface GetResourceOutput {
+	id: string
+	slug: string
+	name: string | null
+	description: string | null
+	latestRevision: {
+		id: string
+		label: string | null
+		file: { id: string; filename: string; mimeType: string; size: number }
+		createdAt: string
+	} | null
+	createdAt: string
+}
+
+export interface ListResourcesInput {
+	limit?: number
+	offset?: number
+}
+
+export interface ListResourcesOutput {
+	resources: GetResourceOutput[]
+}
+
+export interface DeleteResourceInput {
+	resourceId: string
+}
+
+export interface DeleteResourceOutput {
+	ok: boolean
+}
+
+// ============================================================================
+// Sandbox methods (admin/debug)
+// ============================================================================
+
+export interface PauseSandboxInput {
+	instanceId: string
+	sandboxId: string
+}
+
+export interface ResumeSandboxInput {
+	instanceId: string
+	sandboxId: string
+}
+
+export interface TerminateSandboxInput {
+	instanceId: string
+	sandboxId: string
+}
+
+export interface RestartAgentInput {
+	instanceId: string
+	sandboxId: string
+}
+
+export interface GetAgentLogsInput {
+	instanceId: string
+	sandboxId: string
+	lines?: number
+}
+
+export interface GetAgentLogsOutput {
+	logs: string
+	truncated: boolean
+}
+
+export interface SandboxActionOutput {
+	ok: boolean
+}
+
+// ============================================================================
+// Services
+// ============================================================================
+
+export interface GetServiceUrlInput {
+	instanceId: string
+	sessionId: string
+	serviceType: string
+}
+
+export interface GetServiceUrlOutput {
+	url: string | null
+}
+
+// ============================================================================
+// Method registry
+// ============================================================================
+
+export const platformMethods = defineMethods({
+	// Instances
+	'instances.create': method<CreateInstanceInput, CreateInstanceOutput>(),
+	'instances.get': method<GetInstanceInput, GetInstanceOutput>(),
+	'instances.list': method<ListInstancesInput, ListInstancesOutput>(),
+	'instances.status': method<GetInstanceStatusInput, GetInstanceStatusOutput>(),
+	'instances.archive': method<ArchiveInstanceInput, ArchiveInstanceOutput>(),
+
+	// Sessions
+	'sessions.create': method<CreateSessionInput, CreateSessionOutput>(),
+	'sessions.list': method<ListSessionsInput, ListSessionsOutput>(),
+	'sessions.publish': method<PublishSessionInput, PublishSessionOutput>(),
+
+	// Tokens
+	'tokens.create': method<CreateInstanceTokenInput, CreateInstanceTokenOutput>(),
+
+	// Services
+	'services.getUrl': method<GetServiceUrlInput, GetServiceUrlOutput>(),
+
+	// Bundles
+	'bundles.list': method<ListBundlesInput, ListBundlesOutput>(),
+	'bundles.delete': method<DeleteBundleInput, DeleteBundleOutput>(),
+
+	// Resources
+	'resources.create': method<CreateResourceInput, CreateResourceOutput>(),
+	'resources.addRevision': method<AddResourceRevisionInput, AddResourceRevisionOutput>(),
+	'resources.get': method<GetResourceInput, GetResourceOutput>(),
+	'resources.list': method<ListResourcesInput, ListResourcesOutput>(),
+	'resources.delete': method<DeleteResourceInput, DeleteResourceOutput>(),
+})
+
+export type PlatformMethods = typeof platformMethods
+export type PlatformMethodName = keyof PlatformMethods

package/src/platform/rest-client.ts

@@ -0,0 +1,131 @@
+import { createRpcClient } from './rpc-client'
+import type { MethodInput, MethodOutput } from './rpc-definition'
+import type { PlatformMethods, PlatformMethodName } from './methods'
+import type {
+	CreateInstanceInput,
+	CreateInstanceOutput,
+	GetInstanceOutput,
+	GetInstanceStatusOutput,
+	ListInstancesInput,
+	ListInstancesOutput,
+	ArchiveInstanceOutput,
+	CreateSessionInput,
+	CreateSessionOutput,
+	ListSessionsOutput,
+	PublishSessionInput,
+	PublishSessionOutput,
+	CreateInstanceTokenInput,
+	CreateInstanceTokenOutput,
+	ListBundlesInput,
+	ListBundlesOutput,
+	DeleteBundleOutput,
+	CreateResourceInput,
+	CreateResourceOutput,
+	AddResourceRevisionInput,
+	AddResourceRevisionOutput,
+	GetResourceInput,
+	GetResourceOutput,
+	ListResourcesInput,
+	ListResourcesOutput,
+	DeleteResourceOutput,
+} from './methods'
+import { RojApiError } from './errors'
+
+export interface RojClientOptions {
+	/** Platform URL (e.g. https://roj.example.com) */
+	url: string
+	/** Platform API key */
+	apiKey: string
+}
+
+export interface RojClient {
+	instances: {
+		create(input: CreateInstanceInput): Promise<CreateInstanceOutput>
+		get(instanceId: string): Promise<GetInstanceOutput>
+		getStatus(instanceId: string): Promise<GetInstanceStatusOutput>
+		list(input?: ListInstancesInput): Promise<ListInstancesOutput>
+		archive(instanceId: string): Promise<ArchiveInstanceOutput>
+	}
+	sessions: {
+		create(input: CreateSessionInput): Promise<CreateSessionOutput>
+		list(instanceId: string): Promise<ListSessionsOutput>
+		publish(input: PublishSessionInput): Promise<PublishSessionOutput>
+	}
+	tokens: {
+		create(input: CreateInstanceTokenInput): Promise<CreateInstanceTokenOutput>
+	}
+	bundles: {
+		list(input?: ListBundlesInput): Promise<ListBundlesOutput>
+		delete(input: { bundleId?: string; bundleSlug?: string }): Promise<DeleteBundleOutput>
+	}
+	files: {
+		upload(file: File | Blob, filename?: string): Promise<{ ok: true; fileId: string; filename: string; mimeType: string; size: number; r2Key: string }>
+	}
+	resources: {
+		create(input: CreateResourceInput): Promise<CreateResourceOutput>
+		addRevision(input: AddResourceRevisionInput): Promise<AddResourceRevisionOutput>
+		get(input: GetResourceInput): Promise<GetResourceOutput>
+		list(input?: ListResourcesInput): Promise<ListResourcesOutput>
+		delete(resourceId: string): Promise<DeleteResourceOutput>
+	}
+}
+
+export function createRojClient(options: RojClientOptions): RojClient {
+	const rpc = createRpcClient<PlatformMethods>(`${options.url}/api/v1`, {
+		headers: { Authorization: `Bearer ${options.apiKey}` },
+	})
+
+	async function call<M extends PlatformMethodName>(
+		method: M,
+		input: MethodInput<PlatformMethods, M>,
+	): Promise<MethodOutput<PlatformMethods, M>> {
+		const result = await rpc.call(method, input)
+		if (!result.ok) throw new RojApiError(result.error)
+		return result.value
+	}
+
+	return {
+		instances: {
+			create: (input) => call('instances.create', input),
+			get: (instanceId) => call('instances.get', { instanceId }),
+			getStatus: (instanceId) => call('instances.status', { instanceId }),
+			list: (input) => call('instances.list', input ?? {}),
+			archive: (instanceId) => call('instances.archive', { instanceId }),
+		},
+		sessions: {
+			create: (input) => call('sessions.create', input),
+			list: (instanceId) => call('sessions.list', { instanceId }),
+			publish: (input) => call('sessions.publish', input),
+		},
+		tokens: {
+			create: (input) => call('tokens.create', input),
+		},
+		bundles: {
+			list: (input) => call('bundles.list', input ?? {}),
+			delete: (input) => call('bundles.delete', input),
+		},
+		files: {
+			upload: async (file, filename) => {
+				const formData = new FormData()
+				formData.append('file', file, filename)
+				const response = await fetch(`${options.url}/api/v1/files/upload`, {
+					method: 'POST',
+					headers: { Authorization: `Bearer ${options.apiKey}` },
+					body: formData,
+				})
+				if (!response.ok) {
+					const body = await response.json().catch(() => ({ message: response.statusText }))
+					throw new RojApiError({ type: 'http_error', message: body.error ?? body.message ?? response.statusText })
+				}
+				return response.json()
+			},
+		},
+		resources: {
+			create: (input) => call('resources.create', input),
+			addRevision: (input) => call('resources.addRevision', input),
+			get: (input) => call('resources.get', input),
+			list: (input) => call('resources.list', input ?? {}),
+			delete: (resourceId) => call('resources.delete', { resourceId }),
+		},
+	}
+}

package/src/platform/rpc-client.ts

@@ -0,0 +1,67 @@
+/**
+ * Type-safe RPC client.
+ * Mirrors the method definitions for compile-time safety.
+ *
+ * Usage:
+ *   const client = createRpcClient<PlatformMethods>('https://api.roj.cloud/rpc', {
+ *     headers: { Authorization: `Bearer ${apiKey}` },
+ *   })
+ *   const result = await client.call('instances.create', { ... })
+ */
+import type { MethodDef, MethodInput, MethodOutput, RpcError, RpcResponse } from './rpc-definition'
+
+export interface RpcClientOptions {
+	headers?: Record<string, string>
+	credentials?: RequestCredentials
+}
+
+export interface RpcClient<Methods extends Record<string, MethodDef>> {
+	call<M extends string & keyof Methods>(
+		method: M,
+		input: MethodInput<Methods, M>,
+	): Promise<RpcResult<MethodOutput<Methods, M>>>
+}
+
+export type RpcResult<T> =
+	| { ok: true; value: T }
+	| { ok: false; error: RpcError }
+
+export function createRpcClient<Methods extends Record<string, MethodDef>>(
+	baseUrl: string,
+	options?: RpcClientOptions,
+): RpcClient<Methods> {
+	return {
+		async call<M extends string & keyof Methods>(
+			method: M,
+			input: MethodInput<Methods, M>,
+		): Promise<RpcResult<MethodOutput<Methods, M>>> {
+			const response = await fetch(`${baseUrl}/rpc`, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					...options?.headers,
+				},
+				credentials: options?.credentials,
+				body: JSON.stringify({ method, input }),
+			})
+
+			const data = (await response.json()) as RpcResponse
+
+			if (!response.ok) {
+				return {
+					ok: false,
+					error: data.error ?? { type: 'transport_error', message: `HTTP ${response.status}` },
+				}
+			}
+
+			if (data.ok) {
+				return { ok: true, value: data.value as MethodOutput<Methods, M> }
+			}
+
+			return {
+				ok: false,
+				error: data.error ?? { type: 'unknown_error', message: 'Unknown error' },
+			}
+		},
+	}
+}