ACXV API Schema

JSON Schema bundle for ACXV API request, response, parameter, and WebSocket frame shapes.

The published artifact is a single schema.json file. Endpoint entries live under x-endpoints; reusable schemas live under $defs.

Usage

npm install @nicholaspai/acxv-api-schema

TypeScript

Read the endpoint schema directly:

import schema from "@nicholaspai/acxv-api-schema";

type JsonSchemaRef = { $ref: string };

const submit = schema["x-endpoints"]["POST /submit"];
const requestSchema = submit.requestBody.content["application/json"]
  .schema as JsonSchemaRef;
const responseSchema = submit.responses["200"].content["application/json"]
  .schema as JsonSchemaRef;

console.log(requestSchema.$ref); // "#/$defs/SubmitOrderRequest"
console.log(responseSchema.$ref); // "#/$defs/SubmitOrderResponse"

Generate TypeScript types with json-schema-to-typescript:

npm install -D json-schema-to-typescript
npx json2ts \
  --unreachableDefinitions \
  -i node_modules/@nicholaspai/acxv-api-schema/schema.json \
  -o src/acxv-schema.d.ts

import type {
  SubmitOrderRequest,
  SubmitOrderResponse,
} from "./acxv-schema";

async function submitOrder(body: SubmitOrderRequest): Promise<SubmitOrderResponse> {
  const response = await fetch("https://api.example.com/submit", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.ACXV_API_KEY ?? "",
    },
    body: JSON.stringify(body),
  });

  return (await response.json()) as SubmitOrderResponse;
}

Generate endpoint-aware TypeScript types with openapi-typescript:

npm install -D openapi-typescript tsx
npx tsx scripts/build-acxv-openapi.ts
npx openapi-typescript src/acxv-openapi.json -o src/acxv-openapi.d.ts

// scripts/build-acxv-openapi.ts
import { writeFileSync } from "node:fs";
import { createRequire } from "node:module";

const require = createRequire(import.meta.url);
const schema = require("@nicholaspai/acxv-api-schema") as {
  apiVersion: string;
  $defs: Record<string, unknown>;
};

function rewriteRefs(value: unknown): unknown {
  if (Array.isArray(value)) {
    return value.map(rewriteRefs);
  }
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value).map(([key, child]) => [
        key,
        key === "$ref" && typeof child === "string"
          ? child.replace("#/$defs/", "#/components/schemas/")
          : rewriteRefs(child),
      ]),
    );
  }
  return value;
}

writeFileSync(
  "src/acxv-openapi.json",
  JSON.stringify(
    {
      openapi: "3.1.0",
      info: { title: "ACXV API", version: schema.apiVersion },
      paths: {
        "/submit": {
          post: {
            requestBody: {
              required: true,
              content: {
                "application/json": {
                  schema: { $ref: "#/components/schemas/SubmitOrderRequest" },
                },
              },
            },
            responses: {
              200: {
                description: "OK",
                content: {
                  "application/json": {
                    schema: { $ref: "#/components/schemas/SubmitOrderResponse" },
                  },
                },
              },
            },
          },
        },
      },
      components: { schemas: rewriteRefs(schema.$defs) },
    },
    null,
    2,
  ),
);

import type { paths } from "./acxv-openapi";

type SubmitRequest =
  paths["/submit"]["post"]["requestBody"]["content"]["application/json"];
type SubmitResponse =
  paths["/submit"]["post"]["responses"][200]["content"]["application/json"];

async function submitOrder(body: SubmitRequest): Promise<SubmitResponse> {
  const response = await fetch("https://api.example.com/submit", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.ACXV_API_KEY ?? "",
    },
    body: JSON.stringify(body),
  });

  return (await response.json()) as SubmitResponse;
}