@neutrino-io/api-types

Package: @neutrino-io/api-types

Single source of truth for the request/response shapes consumed by Neutrino services. Zod schemas provide runtime validation; the same definitions yield static TypeScript types via z.infer. The package also ships typed openapi-fetch clients generated from each service's OpenAPI export.

// Root barrel
import {
  // schemas
  StackSchema,
  CreateStackSchema,
  ListStacksResponseSchema,
  CreateStackResponseSchema,
  PlatformSchema,
  CreatePlatformSchema,
  ListPlatformsResponseSchema,
  // typed clients
  createRegistryClient,
  createBillingClient,
  createIamClient,
  createProvisioningClient,
  createStackRegistryClient,
  createCliClient,
} from "@neutrino-io/api-types";

Subpath exports

The package publishes three entry points so consumers can avoid pulling the whole barrel:

import { StackSchema } from "@neutrino-io/api-types/stacks";
import { PlatformSchema } from "@neutrino-io/api-types/platforms";

Stack schemas

CreateStackSchema

Request body for POST /platforms/:platformId/stacks.

type CreateStackInput = z.infer<typeof CreateStackSchema>;

StackSchema

A workspace stack as returned by the registry service.

type Stack = z.infer<typeof StackSchema>;

ListStacksResponseSchema

Paginated list response from GET /platforms/:platformId/stacks. Cursor-based pagination — cursor is null on the final page.

{
  data: Stack[]
  cursor: string | null
}

type ListStacksResponse = z.infer<typeof ListStacksResponseSchema>;

CreateStackResponseSchema

Subset of StackSchema returned by POST /platforms/:platformId/stacks.

type CreateStackResponse = z.infer<typeof CreateStackResponseSchema>;

Platform schemas

PlatformSchema

A platform resource as returned by the registry service.

type Platform = z.infer<typeof PlatformSchema>;

CreatePlatformSchema

Request body for creating a platform.

type CreatePlatformInput = z.infer<typeof CreatePlatformSchema>;

ListPlatformsResponseSchema

Paginated list response from GET /platforms. Same cursor-based shape as stacks.

{
  data: Platform[]
  cursor: string | null
}

type ListPlatformsResponse = z.infer<typeof ListPlatformsResponseSchema>;

Inferred TypeScript types

Every schema has a paired z.infer alias so consumers can use the static type without re-running z.infer themselves.

Typed OpenAPI clients

Each Neutrino service exports an OpenAPI document at build time. api-types ships an openapi-fetch client factory per service, typed against that document.

import { createRegistryClient, createIamClient } from "@neutrino-io/api-types";

const registry = createRegistryClient({
  baseUrl: "https://registry.svc.nno.app",
});
const iam = createIamClient({ baseUrl: "https://iam.svc.nno.app" });

// Path autocompletes; response is typed.
const { data, error } = await registry.GET("/api/platforms", {
  params: { query: { limit: 50 } },
});

The typed paths definitions live under @neutrino-io/api-types/dist/generated/<service> (regenerated by pnpm --filter @neutrino-io/api-types generate from each service's OpenAPI export). CI's openapi:check task fails the build if generated types drift from the live OpenAPI documents.