@michelangelo-ai/rpc 0.3.0-nightly.20260701

package/__tests__/handlers.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { getRpcHandlers } from '../handlers';
+
+const mockGetServices = vi.hoisted(() => vi.fn());
+vi.mock('../services', () => ({ getServices: mockGetServices }));
+
+const createPipelineRun = vi.fn().mockResolvedValue({});
+const updatePipelineRun = vi.fn().mockResolvedValue({});
+const updateTriggerRun = vi.fn().mockResolvedValue({});
+
+mockGetServices.mockResolvedValue(
+  new Proxy({} as Record<string, Record<string, unknown>>, {
+    get(_, serviceName: string) {
+      if (serviceName === 'PipelineRunService') {
+        return { createPipelineRun, updatePipelineRun };
+      }
+      if (serviceName === 'TriggerRunService') {
+        return { updateTriggerRun };
+      }
+      return new Proxy({}, { get: () => vi.fn().mockResolvedValue({}) });
+    },
+  })
+);
+
+describe('rpc handlers — mutation envelope wrapping', () => {
+  it('CreatePipelineRun wraps the bare record in a pipelineRun envelope', async () => {
+    const handlers = await getRpcHandlers();
+    const record = { metadata: { name: 'test-run' } };
+    await handlers.CreatePipelineRun(record as never);
+
+    expect(createPipelineRun).toHaveBeenCalledWith({ pipelineRun: record });
+  });
+
+  it('UpdatePipelineRun wraps the bare record in a pipelineRun envelope', async () => {
+    const handlers = await getRpcHandlers();
+    const record = { metadata: { name: 'updated-run' } };
+    await handlers.UpdatePipelineRun(record as never);
+
+    expect(updatePipelineRun).toHaveBeenCalledWith({ pipelineRun: record });
+  });
+
+  it('UpdateTriggerRun wraps the bare record in a triggerRun envelope', async () => {
+    const handlers = await getRpcHandlers();
+    const record = { metadata: { name: 'kill-target' } };
+    await handlers.UpdateTriggerRun(record as never);
+
+    expect(updateTriggerRun).toHaveBeenCalledWith({ triggerRun: record });
+  });
+});

package/__tests__/request.test.ts

@@ -0,0 +1,52 @@
+import { expect, it, vi } from 'vitest';
+
+import { request } from '../request';
+
+vi.mock('../handlers', () => ({
+  getRpcHandlers: vi.fn(),
+}));
+
+const { getRpcHandlers } = await import('../handlers');
+const mockGetRpcHandlers = getRpcHandlers as ReturnType<typeof vi.fn>;
+
+function mockHandler(response: unknown) {
+  mockGetRpcHandlers.mockResolvedValue({
+    GetPipelineRun: vi.fn().mockResolvedValue(response),
+  });
+}
+
+it('strips $typeName and $unknown from response', async () => {
+  mockHandler({ $typeName: 'foo.Bar', $unknown: [], name: 'test' });
+
+  expect(await request('GetPipelineRun', {} as never)).toEqual({ name: 'test' });
+});
+
+it('recursively strips protobuf internals from nested objects', async () => {
+  mockHandler({
+    $typeName: 'outer',
+    nested: { $typeName: 'inner', value: 1 },
+  });
+
+  expect(await request('GetPipelineRun', {} as never)).toEqual({ nested: { value: 1 } });
+});
+
+it('preserves Uint8Array fields without corrupting them into plain objects', async () => {
+  const bytes = new Uint8Array([1, 2, 3]);
+  mockHandler({ $typeName: 'foo.Any', typeUrl: 'type.googleapis.com/foo', value: bytes });
+
+  const result = await request('GetPipelineRun', {} as never);
+
+  expect((result as { value: Uint8Array }).value).toBeInstanceOf(Uint8Array);
+  expect((result as { value: Uint8Array }).value).toEqual(bytes);
+});
+
+it('handles arrays containing objects with protobuf internals', async () => {
+  mockHandler({
+    items: [
+      { $typeName: 'foo', x: 1 },
+      { $typeName: 'bar', x: 2 },
+    ],
+  });
+
+  expect(await request('GetPipelineRun', {} as never)).toEqual({ items: [{ x: 1 }, { x: 2 }] });
+});

package/__tests__/runtime-config.test.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getRuntimeConfig } from '../runtime-config';
+
+// Mock fetch globally
+global.fetch = vi.fn();
+const mockFetch = fetch as ReturnType<typeof vi.fn>;
+
+// Mock window.location
+Object.defineProperty(global, 'window', {
+  value: { location: { hostname: 'localhost' } },
+  writable: true,
+});
+
+describe('getApiConfig', () => {
+  beforeEach(() => {
+    mockFetch.mockClear();
+  });
+
+  it('should return apiBaseUrl from config.json when fetch succeeds', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ apiBaseUrl: 'http://production-envoy:8081' }),
+    } as Response);
+
+    const result = await getRuntimeConfig();
+
+    expect(result.apiBaseUrl).toBe('http://production-envoy:8081');
+    expect(mockFetch).toHaveBeenCalledWith('/config.json');
+  });
+
+  it('should throw error when fetch fails with network error', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('Network error'));
+
+    await expect(getRuntimeConfig()).rejects.toThrow(
+      'Failed to load runtime configuration. Check that config.json is properly mounted.'
+    );
+  });
+
+  it('should throw error when config.json returns 404', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 404,
+    } as Response);
+
+    await expect(getRuntimeConfig()).rejects.toThrow(
+      'Failed to load runtime configuration. Check that config.json is properly mounted.'
+    );
+  });
+
+  it('should throw error when config.json returns 500', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+    } as Response);
+
+    await expect(getRuntimeConfig()).rejects.toThrow(
+      'Failed to load runtime configuration. Check that config.json is properly mounted.'
+    );
+  });
+
+  it('should throw specific error when JSON parsing fails', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.reject(new SyntaxError('Unexpected token')),
+    } as Response);
+
+    await expect(getRuntimeConfig()).rejects.toThrow(
+      'Failed to load runtime configuration. Check that config.json contains valid JSON.'
+    );
+  });
+
+  it('should throw specific error when apiBaseUrl field is missing', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ someOtherField: 'value' }),
+    } as Response);
+
+    await expect(getRuntimeConfig()).rejects.toThrow(
+      'Failed to load runtime configuration. Check that config.json contains apiBaseUrl field.'
+    );
+  });
+
+  it('should throw specific error for network connectivity issues', async () => {
+    mockFetch.mockRejectedValueOnce(new TypeError('Failed to fetch'));
+
+    await expect(getRuntimeConfig()).rejects.toThrow(
+      'Failed to load runtime configuration. Check network connectivity.'
+    );
+  });
+});

package/__tests__/services.test.ts

@@ -0,0 +1,47 @@
+import { expect, it, vi } from 'vitest';
+
+import { request } from '../request';
+
+// Bypass the /config.json fetch — we only care about the RPC transport layer.
+vi.mock('../runtime-config', () => ({
+  getRuntimeConfig: () => Promise.resolve({ apiBaseUrl: 'http://test' }),
+}));
+
+// The real createConnectTransport (JSON mode) calls response.json() and decodes
+// it with fromJson(..., jsonOptions). If jsonOptions.registry doesn't include
+// TypedStructSchema, fromJson throws on the @type URL — so removing the registry
+// from services.ts breaks this test.
+global.fetch = vi.fn().mockResolvedValue({
+  status: 200,
+  headers: new Headers({ 'content-type': 'application/json' }),
+  json: () =>
+    Promise.resolve({
+      pipelineRunList: {
+        items: [
+          {
+            status: {
+              details: [
+                {
+                  '@type': 'type.googleapis.com/michelangelo.api.TypedStruct',
+                  typeUrl: 'type.googleapis.com/michelangelo.UniFlowConf',
+                  value: {},
+                },
+              ],
+            },
+          },
+        ],
+      },
+    }),
+});
+
+it('decodes a ListPipelineRun response containing a TypedStruct Any field', async () => {
+  const result = await request('ListPipelineRun', {} as never);
+  const details = (
+    result as unknown as { pipelineRunList: { items: { status: { details: unknown[] } }[] } }
+  ).pipelineRunList.items[0].status.details;
+
+  // The Any is decoded to { typeUrl, value: Uint8Array } by the registry.
+  // Without TypedStructSchema in the registry, fromJson throws before reaching here.
+  expect(details[0]).toMatchObject({ typeUrl: 'type.googleapis.com/michelangelo.api.TypedStruct' });
+  expect((details[0] as { value: unknown }).value).toBeInstanceOf(Uint8Array);
+});

package/handlers.ts

@@ -0,0 +1,68 @@
+import { getServices } from './services';
+
+import type { PipelineRun } from './gen/michelangelo/api/v2/pipeline_run_pb';
+import type { TriggerRun } from './gen/michelangelo/api/v2/trigger_run_pb';
+import type { ExtractUnaryRpc } from './types';
+
+let handlersPromise: Promise<Awaited<ReturnType<typeof createHandlers>>> | null = null;
+
+async function createHandlers() {
+  const services = await getServices();
+
+  return {
+    ListDeployment: services.DeploymentService.listDeployment as ExtractUnaryRpc<
+      typeof services.DeploymentService.listDeployment
+    >,
+    GetDeployment: services.DeploymentService.getDeployment as ExtractUnaryRpc<
+      typeof services.DeploymentService.getDeployment
+    >,
+    ListInferenceServer: services.InferenceServerService.listInferenceServer as ExtractUnaryRpc<
+      typeof services.InferenceServerService.listInferenceServer
+    >,
+    GetInferenceServer: services.InferenceServerService.getInferenceServer as ExtractUnaryRpc<
+      typeof services.InferenceServerService.getInferenceServer
+    >,
+    ListProject: services.ProjectService.listProject as ExtractUnaryRpc<
+      typeof services.ProjectService.listProject
+    >,
+    GetProject: services.ProjectService.getProject as ExtractUnaryRpc<
+      typeof services.ProjectService.getProject
+    >,
+    GetPipeline: services.PipelineService.getPipeline as ExtractUnaryRpc<
+      typeof services.PipelineService.getPipeline
+    >,
+    ListPipeline: services.PipelineService.listPipeline as ExtractUnaryRpc<
+      typeof services.PipelineService.listPipeline
+    >,
+    ListPipelineRun: services.PipelineRunService.listPipelineRun as ExtractUnaryRpc<
+      typeof services.PipelineRunService.listPipelineRun
+    >,
+    GetPipelineRun: services.PipelineRunService.getPipelineRun as ExtractUnaryRpc<
+      typeof services.PipelineRunService.getPipelineRun
+    >,
+    ListTriggerRun: services.TriggerRunService.listTriggerRun as ExtractUnaryRpc<
+      typeof services.TriggerRunService.listTriggerRun
+    >,
+    GetTriggerRun: services.TriggerRunService.getTriggerRun as ExtractUnaryRpc<
+      typeof services.TriggerRunService.getTriggerRun
+    >,
+    UpdateTriggerRun: (record: TriggerRun) =>
+      services.TriggerRunService.updateTriggerRun({ triggerRun: record }),
+    CreatePipelineRun: (record: PipelineRun) =>
+      services.PipelineRunService.createPipelineRun({ pipelineRun: record }),
+    UpdatePipelineRun: (record: PipelineRun) =>
+      services.PipelineRunService.updatePipelineRun({ pipelineRun: record }),
+    ListModel: services.ModelService.listModel as ExtractUnaryRpc<
+      typeof services.ModelService.listModel
+    >,
+  } as const;
+}
+
+/** Gets the RPC handlers, initializing them with runtime configuration on first call. */
+export async function getRpcHandlers() {
+  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+  if (!handlersPromise) {
+    handlersPromise = createHandlers();
+  }
+  return handlersPromise;
+}

package/index.ts

@@ -0,0 +1,34 @@
+// Export all files from gen/michelangelo/api
+export * from './gen/michelangelo/api/conditions_pb';
+export * from './gen/michelangelo/api/list_pb';
+export * from './gen/michelangelo/api/options_pb';
+export * from './gen/michelangelo/api/typed_struct_pb';
+
+// Export all files from gen/michelangelo/api/v2
+export * from './gen/michelangelo/api/v2/git_pb';
+export * from './gen/michelangelo/api/v2/groupversion_info_pb';
+export * from './gen/michelangelo/api/v2/job_pb';
+export * from './gen/michelangelo/api/v2/model_pb';
+export * from './gen/michelangelo/api/v2/model_svc_pb';
+export * from './gen/michelangelo/api/v2/notification_pb';
+export * from './gen/michelangelo/api/v2/parameter_pb';
+export * from './gen/michelangelo/api/v2/pipeline_pb';
+export * from './gen/michelangelo/api/v2/pipeline_run_pb';
+export * from './gen/michelangelo/api/v2/pipeline_run_svc_pb';
+export * from './gen/michelangelo/api/v2/pipeline_svc_pb';
+export * from './gen/michelangelo/api/v2/pod_pb';
+export * from './gen/michelangelo/api/v2/project_pb';
+export * from './gen/michelangelo/api/v2/project_svc_pb';
+export * from './gen/michelangelo/api/v2/ray_cluster_pb';
+export * from './gen/michelangelo/api/v2/ray_cluster_svc_pb';
+export * from './gen/michelangelo/api/v2/ray_job_pb';
+export * from './gen/michelangelo/api/v2/ray_job_svc_pb';
+export * from './gen/michelangelo/api/v2/schema_pb';
+export * from './gen/michelangelo/api/v2/spark_job_pb';
+export * from './gen/michelangelo/api/v2/spark_job_svc_pb';
+export * from './gen/michelangelo/api/v2/trigger_run_pb';
+export * from './gen/michelangelo/api/v2/trigger_run_svc_pb';
+export * from './gen/michelangelo/api/v2/user_pb';
+
+export { request } from './request';
+export { normalizeConnectError } from './normalize-connect-error';

package/normalize-connect-error.ts

@@ -0,0 +1,82 @@
+import { ConnectError } from '@connectrpc/connect';
+import { ApplicationError, GrpcStatusCode } from '@michelangelo-ai/core';
+
+import type { ErrorNormalizer } from '@michelangelo-ai/core';
+
+/**
+ * Normalizes Connect RPC errors to ApplicationError format
+ *
+ * @param error - The error to normalize
+ * @returns ApplicationError if it's a Connect error, null otherwise
+ *
+ * @example
+ * ```ts
+ * // Usage in error provider
+ * const errorProvider = (
+ *   <ErrorProvider normalizeError={normalizeConnectError}>
+ *     {children}
+ *   </ErrorProvider>
+ * );
+ * ```
+ */
+export const normalizeConnectError: ErrorNormalizer = (error: unknown): ApplicationError | null => {
+  if (!(error instanceof ConnectError)) {
+    return null;
+  }
+
+  return new ApplicationError(error.message, mapConnectCodeToGrpc(error.code), {
+    source: 'connect-rpc',
+    meta: {
+      connectErrorName: error.name,
+      details: error.details,
+      metadata: error.metadata,
+    },
+    cause: error.cause ?? error,
+  });
+};
+
+/**
+ * Maps Connect RPC status codes to gRPC status codes
+ * Connect uses the same numeric codes as gRPC
+ */
+function mapConnectCodeToGrpc(code: number): GrpcStatusCode {
+  // Connect uses the same numeric codes as gRPC, so we can map directly
+  switch (code) {
+    case 0:
+      return GrpcStatusCode.OK;
+    case 1:
+      return GrpcStatusCode.CANCELLED;
+    case 2:
+      return GrpcStatusCode.UNKNOWN;
+    case 3:
+      return GrpcStatusCode.INVALID_ARGUMENT;
+    case 4:
+      return GrpcStatusCode.DEADLINE_EXCEEDED;
+    case 5:
+      return GrpcStatusCode.NOT_FOUND;
+    case 6:
+      return GrpcStatusCode.ALREADY_EXISTS;
+    case 7:
+      return GrpcStatusCode.PERMISSION_DENIED;
+    case 8:
+      return GrpcStatusCode.RESOURCE_EXHAUSTED;
+    case 9:
+      return GrpcStatusCode.FAILED_PRECONDITION;
+    case 10:
+      return GrpcStatusCode.ABORTED;
+    case 11:
+      return GrpcStatusCode.OUT_OF_RANGE;
+    case 12:
+      return GrpcStatusCode.UNIMPLEMENTED;
+    case 13:
+      return GrpcStatusCode.INTERNAL;
+    case 14:
+      return GrpcStatusCode.UNAVAILABLE;
+    case 15:
+      return GrpcStatusCode.DATA_LOSS;
+    case 16:
+      return GrpcStatusCode.UNAUTHENTICATED;
+    default:
+      return GrpcStatusCode.UNKNOWN;
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@michelangelo-ai/rpc",
+  "license": "Apache-2.0",
+  "type": "module",
+  "version": "0.3.0-nightly.20260701",
+  "scripts": {
+    "build": "vite build",
+    "test": "cd ../../ && yarn test:rpc"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.4.1",
+    "vite": "6.2.0"
+  },
+  "dependencies": {
+    "@connectrpc/connect": "^2.0.2",
+    "@connectrpc/connect-web": "^2.0.2",
+    "@michelangelo-ai/core": "*"
+  },
+  "exports": {
+    ".": {
+      "default": "./index.ts"
+    }
+  },
+  "imports": {
+    "#rpc/*": "./"
+  }
+}

package/request.ts

@@ -0,0 +1,45 @@
+import { getRpcHandlers } from './handlers';
+
+import type { OmitTypeName, RpcHandlerType } from './types';
+
+/**
+ * Makes a gRPC-web request to the Michelangelo API.
+ *
+ * Responses are decoded into plain objects — protobuf internals ($typeName, $unknown)
+ * are stripped recursively.
+ *
+ * @param rpcId - The ID of the RPC handler to call.
+ * @param args - The arguments to pass to the RPC handler.
+ * @returns A promise that resolves to the RPC response as a plain object.
+ *
+ * @example
+ * ```ts
+ * const response = await request('ListProject', { /* project list args *\/ });
+ *
+ * // response is of type ListProjectResponse
+ * ```
+ */
+export async function request<RpcId extends keyof RpcHandlerType>(
+  rpcId: RpcId,
+  args: OmitTypeName<Parameters<RpcHandlerType[RpcId]>[0]>
+): Promise<OmitTypeName<Awaited<ReturnType<RpcHandlerType[RpcId]>>>> {
+  const handlers = await getRpcHandlers();
+  const handler = handlers[rpcId] as (a: unknown) => Promise<unknown>;
+  const response = (await handler(args)) as Awaited<ReturnType<RpcHandlerType[RpcId]>>;
+  return toPlainObject(response) as OmitTypeName<Awaited<ReturnType<RpcHandlerType[RpcId]>>>;
+}
+
+// Recursively strips protobuf internals ($typeName, $unknown) from a response,
+// returning a plain object tree that is safe to spread and reconstruct into new requests.
+function toPlainObject(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (value instanceof Uint8Array) return value; // preserve bytes fields (e.g. google.protobuf.Any.value)
+  if (Array.isArray(value)) return value.map(toPlainObject);
+
+  const result: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+    if (key === '$typeName' || key === '$unknown') continue;
+    result[key] = toPlainObject(val);
+  }
+  return result;
+}

package/runtime-config.ts

@@ -0,0 +1,44 @@
+import type { RuntimeConfig } from './types';
+
+// Fetches runtime configuration from /config.json.
+export async function getRuntimeConfig(): Promise<RuntimeConfig> {
+  let response: Response;
+  try {
+    response = await fetch('/config.json');
+  } catch (error) {
+    if (error instanceof TypeError && error.message.includes('fetch')) {
+      console.error(`Config network error: ${error.message}`);
+      throw createConfigError('Check network connectivity.', { cause: error });
+    }
+    console.error(
+      `Config fetch error: ${error instanceof Error ? error.message : 'Unknown error'}`
+    );
+    throw createConfigError('Check that config.json is properly mounted.', { cause: error });
+  }
+
+  if (!response.ok) {
+    console.error(`Config fetch failed: ${response.status} ${response.statusText}`);
+    throw createConfigError('Check that config.json is properly mounted.', { cause: response });
+  }
+
+  let config: RuntimeConfig;
+  try {
+    config = (await response.json()) as RuntimeConfig;
+  } catch (error) {
+    console.error(
+      `Config JSON parsing failed: ${error instanceof Error ? error.message : 'Invalid JSON'}`
+    );
+    throw createConfigError('Check that config.json contains valid JSON.', { cause: error });
+  }
+
+  if (!config.apiBaseUrl) {
+    console.error('Config missing apiBaseUrl field', JSON.stringify(config));
+    throw createConfigError('Check that config.json contains apiBaseUrl field.');
+  }
+
+  return config;
+}
+
+function createConfigError(reason: string, options?: ErrorOptions): Error {
+  return new Error(`Failed to load runtime configuration. ${reason}`, options);
+}

package/services.ts

@@ -0,0 +1,62 @@
+import { createRegistry } from '@bufbuild/protobuf';
+import { createClient } from '@connectrpc/connect';
+import { createConnectTransport } from '@connectrpc/connect-web';
+
+import { TypedStructSchema } from './gen/michelangelo/api/typed_struct_pb';
+import { DeploymentService } from './gen/michelangelo/api/v2/deployment_svc_pb';
+import { InferenceServerService } from './gen/michelangelo/api/v2/inference_server_svc_pb';
+import { ModelService } from './gen/michelangelo/api/v2/model_svc_pb';
+import { PipelineRunService } from './gen/michelangelo/api/v2/pipeline_run_svc_pb';
+import { PipelineService } from './gen/michelangelo/api/v2/pipeline_svc_pb';
+import { ProjectService } from './gen/michelangelo/api/v2/project_svc_pb';
+import { TriggerRunService } from './gen/michelangelo/api/v2/trigger_run_svc_pb';
+import { getRuntimeConfig } from './runtime-config';
+
+const typeRegistry = createRegistry(TypedStructSchema);
+
+import type { Interceptor } from '@connectrpc/connect';
+import type { Services } from './types';
+
+// This interceptor is used to set the headers for the RPC request to
+// be compatible with the Michelangelo API yarpc server.
+const callerInterceptor: Interceptor = (next) => async (req) => {
+  req.header.set('context-Ttl-Ms', '10000');
+  req.header.set('grpc-timeout', '1000000m');
+  req.header.set('Rpc-Caller', 'ma-studio');
+  req.header.set('Rpc-Service', 'ma-apiserver');
+
+  return await next(req);
+};
+
+let servicesPromise: Promise<Services> | null = null;
+
+async function createServices(): Promise<Services> {
+  const { apiBaseUrl } = await getRuntimeConfig();
+
+  const transport = createConnectTransport({
+    baseUrl: apiBaseUrl,
+    interceptors: [callerInterceptor],
+    jsonOptions: { registry: typeRegistry },
+  });
+
+  return {
+    DeploymentService: createClient(DeploymentService, transport),
+    InferenceServerService: createClient(InferenceServerService, transport),
+    ProjectService: createClient(ProjectService, transport),
+    PipelineService: createClient(PipelineService, transport),
+    PipelineRunService: createClient(PipelineRunService, transport),
+    TriggerRunService: createClient(TriggerRunService, transport),
+    ModelService: createClient(ModelService, transport),
+  } as const;
+}
+
+/**
+ * Gets the RPC services, initializing them with runtime configuration on first call.
+ */
+export async function getServices(): Promise<Services> {
+  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+  if (!servicesPromise) {
+    servicesPromise = createServices();
+  }
+  return servicesPromise;
+}

package/transformations/common.ts

@@ -0,0 +1,40 @@
+import type { ExtractEntityFromResponse, HasTypeName } from './types';
+
+/**
+ * Extracts the main entity from a response
+ *
+ * @example
+ * ```ts
+ * type MyResponse = {
+ *   $typeName: 'michelangelo.api.v2.GetProjectResponse';
+ *   project: Project;
+ * }
+ *
+ * expect(extractEntityFromResponse(myResponse)).toEqual(myResponse.project)    ;
+ *
+ * // If the response is not a valid response, it will throw an error
+ * type MyResponse = {
+ *   $typeName: 'some.other.api.v1.SomeOtherResponse';
+ *   someOtherEntity: SomeOtherEntity;
+ * }
+ *
+ * expect(extractEntityFromResponse(myResponse)).toThrowError(
+ *   'Entity name someOtherEntity not found in response'
+ * );
+ * ```
+ */
+export function extractEntityFromResponse<T extends HasTypeName>(
+  response: T
+): ExtractEntityFromResponse<T> {
+  const typeName = response.$typeName;
+  const entityName = typeName
+    .replace(/^michelangelo\.api\.v2\.(Get|Create|Update)/, '')
+    .replace(/Response$/, '')
+    .toLowerCase();
+
+  if (entityName in response) {
+    return response[entityName] as ExtractEntityFromResponse<T>;
+  }
+
+  throw new Error(`Entity name ${entityName} not found in response`);
+}

package/transformations/guards.ts

@@ -0,0 +1,20 @@
+import type { HasTypeName } from './types';
+
+/**
+ * Type predicate to check if an object has a $typeName property
+ */
+export function hasTypeName(value: unknown): value is HasTypeName {
+  return typeof value === 'object' && value !== null && '$typeName' in value;
+}
+
+/**
+ * Type guard to check if a response is an entity response (Get, Create, or Update)
+ */
+export function isSingularResponse<T>(value: T): value is T & HasTypeName {
+  return (
+    hasTypeName(value) &&
+    (value.$typeName.startsWith('michelangelo.api.v2.Get') ||
+      value.$typeName.startsWith('michelangelo.api.v2.Create') ||
+      value.$typeName.startsWith('michelangelo.api.v2.Update'))
+  );
+}

package/transformations/types.ts

@@ -0,0 +1,123 @@
+/**
+ * @description
+ * Type for objects that have a $typeName property. $typeName is added by the `@bufbuild/protobuf` library.
+ * This type is used to identify the associated protobuf message type.
+ *
+ * @example
+ * ```ts
+ * type GetProjectResponse = {
+ *   $typeName: 'michelangelo.api.v2.GetProjectResponse';
+ *   project: Project;
+ * };
+ * ```
+ */
+export type HasTypeName = {
+  $typeName: string;
+};
+
+/**
+ * @description
+ * Singular endpoints are endpoints that return a single entity.
+ *
+ * @example
+ * ```ts
+ * type GetProjectResponse = {
+ *   $typeName: 'michelangelo.api.v2.GetProjectResponse';
+ *   project: Project;
+ * };
+ */
+type SingularEndpoint = 'Get' | 'Create' | 'Update';
+
+/**
+ * @description
+ * Delete endpoint is the endpoint that deletes an entity.
+ */
+type DeleteEndpoint = 'Delete';
+
+/**
+ * @description
+ * List endpoint is the endpoint that returns a list of entities.
+ */
+type ListEndpoint = 'List';
+
+/**
+ * @description
+ * Type for the endpoint part of the $typeName property.
+ *
+ * @example
+ * ```ts
+ * // Endpoint can be used in a type guard to check if a response typeName
+ * // belongs to a known endpoint
+ * type IsProjectResponse<T extends string> =
+ *   T extends `michelangelo.api.v2.${Endpoint}ProjectResponse` ? true : false;
+ *
+ * type IsProjectResponseResult = IsProjectResponse<'michelangelo.api.v2.GetProjectResponse'>;
+ * // => true -- Get is not a known endpoint
+ *
+ * type IsProjectResponseResult = IsProjectResponse<'michelangelo.api.v2.RetryProjectResponse'>;
+ * // => false -- Retry is not a known endpoint
+ * ```
+ */
+type Endpoint = SingularEndpoint | ListEndpoint | DeleteEndpoint;
+
+/**
+ * @description
+ * Extracts the lowercased entity name from an absolute path to the response protobuf message.
+ * The resulting entity name should be used as the key to access the entity from the response object.
+ *
+ * @remarks
+ * This assumes that the response protobuf message is in the `michelangelo.api.v2` namespace.
+ *
+ * @example
+ * ```ts
+ * type GetProjectResponse = {
+ *   $typeName: 'michelangelo.api.v2.GetProjectResponse';
+ *   project: Project;
+ * };
+ *
+ * ExtractEntityName<'michelangelo.api.v2.GetProjectResponse'>;
+ * // => 'project'
+ *
+ * ExtractEntityName<'some.other.protobuf.GetProjectResponse'>;
+ * // => never
+ * ```
+ */
+type ExtractEntityName<T extends string> =
+  T extends `michelangelo.api.v2.${Endpoint}${infer Entity}Response` ? Lowercase<Entity> : never;
+
+/**
+ * @description
+ * Extracts the inner entity from a protobuf response message.
+ *
+ * @example
+ * ```ts
+ * type GetProjectResponse = {
+ *   $typeName: 'michelangelo.api.v2.GetProjectResponse';
+ *   project: Project;
+ * };
+ *
+ * ExtractEntityFromResponse<GetProjectResponse>;
+ * // => Project
+ *
+ * type ListProjectsResponse = {
+ *   $typeName: 'michelangelo.api.v2.ListProjectsResponse';
+ *   projects: Project[];
+ * };
+ *
+ * ExtractEntityFromResponse<ListProjectsResponse>;
+ * // => Project[]
+ *
+ * type SomeOtherResponse  = {
+ *   $typeName: 'some.other.protobuf.SomeOtherResponse';
+ *   someField: string;
+ * };
+ *
+ * ExtractEntityFromResponse<SomeOtherResponse>;
+ * // => SomeOtherResponse
+ * ```
+ */
+export type ExtractEntityFromResponse<T> = T extends HasTypeName
+  ? T extends Partial<Record<ExtractEntityName<T['$typeName']>, infer E>>
+    ? E
+    : T
+  : T;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["."],
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "moduleResolution": "bundler",
+    "noEmit": false,
+    "jsx": "react-jsx",
+    "outDir": "dist",
+    "rootDir": "."
+  }
+}

package/types.ts

@@ -0,0 +1,84 @@
+import type { Message } from '@bufbuild/protobuf';
+import type { createClient } from '@connectrpc/connect';
+import type { DeploymentService } from './gen/michelangelo/api/v2/deployment_svc_pb';
+import type { InferenceServerService } from './gen/michelangelo/api/v2/inference_server_svc_pb';
+import type { ModelService } from './gen/michelangelo/api/v2/model_svc_pb';
+import type { PipelineRunService } from './gen/michelangelo/api/v2/pipeline_run_svc_pb';
+import type { PipelineService } from './gen/michelangelo/api/v2/pipeline_svc_pb';
+import type { ProjectService } from './gen/michelangelo/api/v2/project_svc_pb';
+import type { TriggerRunService } from './gen/michelangelo/api/v2/trigger_run_svc_pb';
+import type { getRpcHandlers } from './handlers';
+
+export interface RuntimeConfig {
+  apiBaseUrl: string;
+}
+
+export type Services = {
+  DeploymentService: ReturnType<typeof createClient<typeof DeploymentService>>;
+  InferenceServerService: ReturnType<typeof createClient<typeof InferenceServerService>>;
+  ProjectService: ReturnType<typeof createClient<typeof ProjectService>>;
+  PipelineService: ReturnType<typeof createClient<typeof PipelineService>>;
+  PipelineRunService: ReturnType<typeof createClient<typeof PipelineRunService>>;
+  TriggerRunService: ReturnType<typeof createClient<typeof TriggerRunService>>;
+  ModelService: ReturnType<typeof createClient<typeof ModelService>>;
+};
+
+/**
+ * @see {@link getRpcHandlers}
+ */
+export type RpcHandlerType = Awaited<ReturnType<typeof getRpcHandlers>>;
+
+/**
+ * @description
+ * Extracts the unary-unary function type from the RPC handler type.
+ *
+ * @remarks
+ * The Connect Client type generates a type that includes unary-unary, unary-server-streaming,
+ * unary-client-streaming, and unary-bidi-streaming functions.  We want to extract the
+ * unary-unary function type from the RPC handler type.
+ *
+ * @example
+ * ```ts
+ * getProject: (args: { projectId: string }) => Promise<Project> | AsyncIterable<Project>;
+ * ExtractUnaryRpc<getProject>
+ * // => (args: { projectId: string }) => Promise<Project>
+ * ```
+ */
+export type ExtractUnaryRpc<T> = T extends (args: Record<string, unknown>) => Promise<infer R>
+  ? (args: Record<string, unknown>) => Promise<R>
+  : never;
+
+/**
+ * @description
+ * Removes the `$typeName` and `$unknown` properties from a message. These are properties
+ * that are added by the protobuf-es library. We don't need them for our RPC calls.
+ *
+ * @example
+ * ```ts
+ * type MyMessage = {
+ *   $typeName: string;
+ *   $unknown: unknown;
+ *   myField: string;
+ * };
+ *
+ * type MyMessageWithoutTypeName = OmitTypeName<MyMessage>;
+ * const message: MyMessageWithoutTypeName = { myField: 'hello' };
+ * ```
+ *
+ * @see https://github.com/bufbuild/protobuf-es/issues/1016
+ */
+export type OmitTypeName<T> = {
+  [P in keyof T as P extends '$typeName' | '$unknown' ? never : P]: Recurse<T[P]>;
+};
+
+type Recurse<F> = F extends (infer U)[]
+  ? Recurse<U>[]
+  : F extends Message
+    ? OmitTypeName<F>
+    : F extends { case: infer C extends string; value: infer V extends Message }
+      ? { case: C; value: OmitTypeName<V> }
+      : F extends Record<string, infer V extends Message>
+        ? Record<string, OmitTypeName<V>>
+        : F extends Record<number, infer V extends Message>
+          ? Record<number, OmitTypeName<V>>
+          : F;

package/vite.config.ts

@@ -0,0 +1,25 @@
+import react from '@vitejs/plugin-react';
+import path from 'path';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: path.resolve(__dirname, 'index.ts'),
+      name: 'MichelangeloRpc',
+      formats: ['es'],
+    },
+    rollupOptions: {
+      external: [
+        'react',
+        '@bufbuild/protobuf',
+        '@connectrpc/connect',
+        '@connectrpc/connect-web',
+        '@tanstack/react-query',
+      ],
+    },
+    outDir: 'dist',
+    emptyOutDir: true,
+  },
+  plugins: [react()],
+});