@roj-ai/client 0.0.2

package/dist/api/client.d.ts

@@ -0,0 +1,18 @@
+import { RpcClient, RpcError } from '@roj-ai/shared/rpc';
+import type { Result, RpcErrorInfo, RpcInput, RpcMethodName, RpcOutput } from '@roj-ai/shared/rpc';
+export { RpcClient, RpcError };
+export type { RpcErrorInfo };
+export interface ApiClient {
+    call<M extends RpcMethodName>(method: M, input: RpcInput<M>): Promise<Result<RpcOutput<M>, RpcErrorInfo>>;
+    uploadFile(sessionId: string, file: File): Promise<{
+        uploadId: string;
+        status: 'ready' | 'failed';
+        extractedContent?: string;
+    }>;
+}
+export declare function configureApiBaseUrl(url: string): void;
+export declare function getApiBaseUrl(): string;
+export declare function configureProjectId(projectId: string | null): void;
+export declare function createApiClient(baseUrl?: string): ApiClient;
+export declare const api: ApiClient;
+export declare function useApiError(error: unknown): string | null;

package/dist/api/unwrap.d.ts

@@ -0,0 +1,2 @@
+import type { Result, RpcErrorInfo } from '@roj-ai/shared/rpc';
+export declare function unwrap<T>(result: Result<T, RpcErrorInfo>): T;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @roj-ai/client
+ *
+ * Vanilla TypeScript client for the roj agent server. No React — React hooks
+ * and chat components live in `@roj-ai/client-react`.
+ */
+export { api, configureApiBaseUrl, createApiClient, getApiBaseUrl, configureProjectId, RpcClient, RpcError, useApiError, } from './api/client';
+export type { ApiClient } from './api/client';
+export { unwrap } from './api/unwrap';

package/dist/platform/errors.d.ts

@@ -0,0 +1,6 @@
+import type { RpcError } from './rpc-definition';
+export declare class RojApiError extends Error {
+    readonly error: RpcError;
+    readonly type: string;
+    constructor(error: RpcError);
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @roj-ai/client/platform
+ *
+ * Client SDK for the roj platform REST API. Works against both the full
+ * platform (Cloudflare worker) and the standalone server.
+ */
+export { defineMethods, method } from './rpc-definition';
+export type { MethodDef, MethodInput, MethodOutput, RpcRequest, RpcResponse, RpcError } from './rpc-definition';
+export { createRpcClient } from './rpc-client';
+export type { RpcClient, RpcClientOptions, RpcResult } from './rpc-client';
+export { createRpcRouter } from './rpc-server';
+export type { RpcRouter, MethodHandler, MethodHandlers } from './rpc-server';
+export { platformMethods } from './methods';
+export type { PlatformMethods, PlatformMethodName } from './methods';
+export type * from './methods';
+export { instanceMethods } from './instance-methods';
+export type { InstanceMethods, InstanceMethodName } from './instance-methods';
+export type * from './instance-methods';
+export type { SandboxState } from './sandbox-state';
+export { buildPreviewUrl, buildWsUrl, buildApiBaseUrl, instanceIdToHex } from './urls';
+export type { BuildPreviewUrlOptions, BuildWsUrlOptions } from './urls';
+export { createRojClient } from './rest-client';
+export type { RojClient, RojClientOptions } from './rest-client';
+export { RojApiError } from './errors';

package/dist/platform/instance-methods.d.ts

@@ -0,0 +1,94 @@
+import type { PublishSessionOutput, GetAgentLogsOutput } from './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;
+}
+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;
+}
+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;
+}
+export interface InstanceOkOutput {
+    ok: boolean;
+}
+export declare const instanceMethods: {
+    createSandbox: import("./rpc-definition").MethodDef<InstanceCreateSandboxInput, InstanceCreateSandboxOutput>;
+    pauseSandbox: import("./rpc-definition").MethodDef<InstancePauseSandboxInput, InstanceOkOutput>;
+    resumeSandbox: import("./rpc-definition").MethodDef<InstanceResumeSandboxInput, InstanceOkOutput>;
+    terminateSandbox: import("./rpc-definition").MethodDef<InstanceTerminateSandboxInput, InstanceOkOutput>;
+    restartAgent: import("./rpc-definition").MethodDef<InstanceRestartAgentInput, InstanceOkOutput>;
+    getAgentLogs: import("./rpc-definition").MethodDef<InstanceGetAgentLogsInput, GetAgentLogsOutput>;
+    execInSandbox: import("./rpc-definition").MethodDef<InstanceExecInSandboxInput, InstanceExecInSandboxOutput>;
+    validateSandboxToken: import("./rpc-definition").MethodDef<InstanceValidateSandboxTokenInput, InstanceValidateSandboxTokenOutput>;
+    createSession: import("./rpc-definition").MethodDef<InstanceCreateSessionInput, InstanceCreateSessionOutput>;
+    listSessions: import("./rpc-definition").MethodDef<InstanceListSessionsInput, InstanceListSessionsOutput>;
+    publishSession: import("./rpc-definition").MethodDef<InstancePublishSessionInput, PublishSessionOutput>;
+    getServiceUrl: import("./rpc-definition").MethodDef<InstanceGetServiceUrlInput, InstanceGetServiceUrlOutput>;
+    getServiceUrls: import("./rpc-definition").MethodDef<InstanceGetServiceUrlsInput, InstanceGetServiceUrlsOutput>;
+    ensureSandbox: import("./rpc-definition").MethodDef<{}, InstanceEnsureSandboxOutput>;
+};
+export type InstanceMethods = typeof instanceMethods;
+export type InstanceMethodName = keyof InstanceMethods;

package/dist/platform/methods.d.ts

@@ -0,0 +1,260 @@
+import type { SandboxState } from './sandbox-state';
+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;
+}
+export interface CreateSessionInput {
+    instanceId: string;
+    presetId: string;
+    blocking?: boolean;
+    origin?: string;
+    expiresIn?: number;
+}
+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;
+}
+export interface CreateInstanceTokenInput {
+    instanceId: string;
+    origin?: string;
+    expiresIn?: number;
+    meta?: Record<string, unknown>;
+}
+export interface CreateInstanceTokenOutput {
+    token: string;
+    expiresAt: string;
+}
+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;
+}
+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;
+}
+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;
+}
+export interface GetServiceUrlInput {
+    instanceId: string;
+    sessionId: string;
+    serviceType: string;
+}
+export interface GetServiceUrlOutput {
+    url: string | null;
+}
+export declare const platformMethods: {
+    'instances.create': import("./rpc-definition").MethodDef<CreateInstanceInput, CreateInstanceOutput>;
+    'instances.get': import("./rpc-definition").MethodDef<GetInstanceInput, GetInstanceOutput>;
+    'instances.list': import("./rpc-definition").MethodDef<ListInstancesInput, ListInstancesOutput>;
+    'instances.status': import("./rpc-definition").MethodDef<GetInstanceStatusInput, GetInstanceStatusOutput>;
+    'instances.archive': import("./rpc-definition").MethodDef<ArchiveInstanceInput, ArchiveInstanceOutput>;
+    'sessions.create': import("./rpc-definition").MethodDef<CreateSessionInput, CreateSessionOutput>;
+    'sessions.list': import("./rpc-definition").MethodDef<ListSessionsInput, ListSessionsOutput>;
+    'sessions.publish': import("./rpc-definition").MethodDef<PublishSessionInput, PublishSessionOutput>;
+    'tokens.create': import("./rpc-definition").MethodDef<CreateInstanceTokenInput, CreateInstanceTokenOutput>;
+    'services.getUrl': import("./rpc-definition").MethodDef<GetServiceUrlInput, GetServiceUrlOutput>;
+    'bundles.list': import("./rpc-definition").MethodDef<ListBundlesInput, ListBundlesOutput>;
+    'bundles.delete': import("./rpc-definition").MethodDef<DeleteBundleInput, DeleteBundleOutput>;
+    'resources.create': import("./rpc-definition").MethodDef<CreateResourceInput, CreateResourceOutput>;
+    'resources.addRevision': import("./rpc-definition").MethodDef<AddResourceRevisionInput, AddResourceRevisionOutput>;
+    'resources.get': import("./rpc-definition").MethodDef<GetResourceInput, GetResourceOutput>;
+    'resources.list': import("./rpc-definition").MethodDef<ListResourcesInput, ListResourcesOutput>;
+    'resources.delete': import("./rpc-definition").MethodDef<DeleteResourceInput, DeleteResourceOutput>;
+};
+export type PlatformMethods = typeof platformMethods;
+export type PlatformMethodName = keyof PlatformMethods;

package/dist/platform/rest-client.d.ts

@@ -0,0 +1,49 @@
+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';
+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 declare function createRojClient(options: RojClientOptions): RojClient;

package/dist/platform/rpc-client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 } 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 declare function createRpcClient<Methods extends Record<string, MethodDef>>(baseUrl: string, options?: RpcClientOptions): RpcClient<Methods>;

package/dist/platform/rpc-definition.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare function method<I, O>(): MethodDef<I, O>;
+/** Define a set of methods. Returns the definition object as-is (typed). */
+export declare function defineMethods<T extends Record<string, MethodDef>>(methods: T): T;
+/** 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/dist/platform/rpc-server.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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, 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 declare function createRpcRouter<Methods extends Record<string, MethodDef>, Ctx>(_methods: Methods, handlers: MethodHandlers<Methods, Ctx>): RpcRouter<Ctx>;

package/dist/platform/sandbox-state.d.ts

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

package/dist/platform/urls.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Convert an instance UUID to its full 32-char hex representation (no hyphens, lowercase).
+ */
+export declare function instanceIdToHex(instanceId: string): string;
+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 declare function buildPreviewUrl({ instanceId, code, baseDomain, token, platformUrl }: BuildPreviewUrlOptions): string;
+export interface BuildWsUrlOptions {
+    platformUrl: string;
+    instanceId: string;
+    sessionId: string;
+    token: string;
+}
+/**
+ * Build a WebSocket URL for connecting to a roj instance.
+ */
+export declare function buildWsUrl({ platformUrl, instanceId, sessionId, token }: BuildWsUrlOptions): string;
+/**
+ * Build the RPC base URL for a roj instance.
+ */
+export declare function buildApiBaseUrl(platformUrl: string, instanceId: string): string;