A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!
TypeScript agent-skillsaidsh-pluginhacktoberfestjavascriptmcp-serverreactresume-builderself-hostedtypescript
import type { OpenAPI } from "@orpc/openapi";
import { OpenAPIGenerator } from "@orpc/openapi";
import {
JSON_SCHEMA_INPUT_REGISTRY,
JSON_SCHEMA_OUTPUT_REGISTRY,
JSON_SCHEMA_REGISTRY,
ZodToJsonSchemaConverter,
} from "@orpc/zod/zod4";
import { downloadResumePdfProcedure } from "@reactive-resume/api/features/resume/export";
import { restAliases } from "@reactive-resume/api/rest";
import router from "@reactive-resume/api/routers";
import { careerProfileDataSchema } from "@reactive-resume/schema/career";
import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
import { writableResumeDataSchema } from "@reactive-resume/schema/resume/write";
import { searchRegionsSchema } from "@reactive-resume/utils/region";
export const openAPIRouter = {
...router,
rest: restAliases,
resume: {
...router.resume,
downloadPdf: downloadResumePdfProcedure,
},
};
const { $schema: _dialect, ...resumeDataInputSchema } = createResumeDataJsonSchema();
type ResumeDataInputJsonSchema = Parameters<typeof JSON_SCHEMA_INPUT_REGISTRY.add<typeof resumeDataSchema>>[1];
JSON_SCHEMA_INPUT_REGISTRY.add(resumeDataSchema, resumeDataInputSchema as unknown as ResumeDataInputJsonSchema);
JSON_SCHEMA_INPUT_REGISTRY.add(writableResumeDataSchema, resumeDataInputSchema as unknown as ResumeDataInputJsonSchema);
JSON_SCHEMA_REGISTRY.add(searchRegionsSchema.unwrap().unwrap(), { uniqueItems: true });
JSON_SCHEMA_OUTPUT_REGISTRY.add(careerProfileDataSchema, {
required: Object.keys(careerProfileDataSchema.parse({})),
});
const importResumeInputSchema = openAPIRouter.resume.import["~orpc"].inputSchema;
if (importResumeInputSchema) {
JSON_SCHEMA_INPUT_REGISTRY.add(importResumeInputSchema, {
type: "object",
properties: {
data: { $ref: "#/components/schemas/ResumeData" },
},
required: ["data"],
});
}
const openAPIGenerator = new OpenAPIGenerator({
schemaConverters: [
new ZodToJsonSchemaConverter({
interceptors: [
({ options, next }) => {
const [required, schema] = next();
const impossible =
Object.keys(schema).length === 1 &&
typeof schema.not === "object" &&
schema.not !== null &&
Object.keys(schema.not).length === 0;
return options.strategy === "input" && impossible ? [required, {}] : [required, schema];
},
],
}),
],
});
type GenerateOpenApiSpecOptions = {
appUrl: string;
version: string;
};
const healthDependencySchema = {
type: "object",
properties: {
status: { type: "string", enum: ["healthy", "unhealthy"] },
latencyMs: { type: "number" },
error: { type: "string", description: "Generic failure message. Detailed diagnostics are logged on the server." },
},
required: ["status", "latencyMs"],
additionalProperties: true,
} satisfies OpenAPI.SchemaObject;
const healthResponseSchema = {
type: "object",
properties: {
service: { type: "string", enum: ["reactive-resume"] },
version: { type: "string", description: "The running application's build version." },
revision: {
anyOf: [{ type: "string", pattern: "^[a-f0-9]{40}$" }, { enum: [null] }],
description: "The full Git commit embedded in the running Docker image, or null when unknown.",
},
status: { type: "string", enum: ["healthy", "unhealthy"] },
timestamp: { type: "string", format: "date-time" },
uptime: { type: "string" },
database: healthDependencySchema,
storage: healthDependencySchema,
redis: {
...healthDependencySchema,
description: "Present only when REDIS_URL is configured. An unhealthy Redis makes the overall status unhealthy.",
},
},
required: ["service", "version", "revision", "status", "timestamp", "uptime", "database", "storage"],
} satisfies OpenAPI.SchemaObject;
type Procedure = { "~orpc": { handler?: unknown; route: { operationId?: string } } };
function procedures(tree: unknown): Procedure[] {
if (!tree || typeof tree !== "object") return [];
if ("~orpc" in tree) return [tree as Procedure];
return Object.values(tree).flatMap(procedures);
}
/**
* Operations that have a resource-oriented alias in `restAliases`: the alias reuses the same handler under a new
* path, so the original is the legacy spelling. Generated clients see it as deprecated; the route keeps working.
*/
function legacyOperationIds() {
const aliases = procedures(restAliases);
const aliasHandlers = new Set(aliases.map((alias) => alias["~orpc"].handler));
const aliasIds = new Set(aliases.map((alias) => alias["~orpc"].route.operationId));
return new Set(
procedures(router)
.filter((procedure) => aliasHandlers.has(procedure["~orpc"].handler))
.map((procedure) => procedure["~orpc"].route.operationId)
.filter((id): id is string => !!id && !aliasIds.has(id)),
);
}
export async function generateOpenApiSpec({ appUrl, version }: GenerateOpenApiSpecOptions) {
const spec = await openAPIGenerator.generate(openAPIRouter, {
info: {
title: "Reactive Resume",
version,
description:
"Reactive Resume API. Mutations do not support Idempotency-Key. Do not automatically retry POST, PUT, PATCH or DELETE requests after a timeout: first read the resource to determine whether the operation succeeded. Existing enum values and response shapes are retained for compatibility.",
license: { name: "MIT", url: "https://github.com/reactive-resume/reactive-resume/blob/main/LICENSE" },
contact: { name: "Amruth Pillai", email: "[email protected]", url: "https://amruthpillai.com" },
},
servers: [{ url: `${appUrl}/api/openapi` }],
paths: {
"/api/health": {
get: {
operationId: "getHealth",
tags: ["System"],
summary: "Get application health and version",
description: "Checks database and storage availability. Does not require authentication.",
servers: [{ url: appUrl }],
security: [],
responses: {
"200": {
description: "The application and its dependencies are healthy.",
content: { "application/json": { schema: healthResponseSchema } },
},
"503": {
description: "One or more application dependencies are unhealthy.",
content: { "application/json": { schema: healthResponseSchema } },
},
},
},
},
},
externalDocs: { url: "https://docs.rxresu.me", description: "Reactive Resume Documentation" },
commonSchemas: {
ResumeData: { schema: writableResumeDataSchema, strategy: "input" },
},
components: {
securitySchemes: {
bearerAuth: {
type: "http",
scheme: "bearer",
bearerFormat: "JWT",
description: "An OAuth access token issued by this instance for its API/MCP resource.",
},
cookieAuth: {
type: "apiKey",
in: "cookie",
name: "better-auth.session_token",
description:
"Browser session (secure deployments use the __Secure- prefix). Cookie requests must originate from this instance.",
},
apiKey: {
type: "apiKey",
name: "x-api-key",
in: "header",
description: "The API key to authenticate requests.",
},
},
},
security: [{ apiKey: [] }, { bearerAuth: [] }, { cookieAuth: [] }],
filter: ({ contract }) => !contract["~orpc"].route.tags?.includes("Internal"),
});
// Void results have no HTTP body; Zod's impossible JSON schema is not a response payload.
const isVoid = (schema: unknown): boolean => {
if (!schema || typeof schema !== "object") return false;
const value = schema as { not?: object; anyOf?: unknown[] };
return (
(value.not !== undefined && Object.keys(value.not).length === 0) ||
(Array.isArray(value.anyOf) && value.anyOf.every(isVoid))
);
};
const legacy = legacyOperationIds();
for (const [path, item] of Object.entries(spec.paths ?? {})) {
if (!item || path === "/api/health") continue;
for (const method of ["get", "post", "put", "patch", "delete"] as const) {
const operation = item[method];
if (!operation) continue;
if (operation.operationId && legacy.has(operation.operationId)) operation.deprecated = true;
const body = operation.requestBody;
if (body && !("$ref" in body) && body.content["multipart/form-data"]) {
const json = body.content["application/json"]?.schema;
// Application files are optional; existing JSON clients keep sending record fields only.
if ((path === "/applications" || path === "/applications/{id}") && json && "properties" in json) {
delete json.properties?.resumeFile;
delete json.properties?.coverLetterFile;
} else delete body.content["application/json"];
}
operation.responses ??= {};
operation.responses.default = {
description: "Structured API error. See status and code; do not branch on message text.",
content: {
"application/json": {
schema: {
type: "object",
required: ["defined", "code", "status", "message"],
properties: {
defined: { type: "boolean" },
code: { type: "string" },
status: { type: "integer" },
message: { type: "string" },
data: {},
},
},
},
},
};
for (const response of Object.values(operation.responses)) {
if ("$ref" in response) continue;
const schema = response.content?.["application/json"]?.schema;
if (isVoid(schema)) delete response.content;
if (
schema &&
"type" in schema &&
schema.type === "array" &&
operation.parameters?.some((parameter) => "name" in parameter && parameter.name === "limit")
) {
response.headers = {
...response.headers,
"X-Total-Count": { description: "Total matching results before pagination.", schema: { type: "integer" } },
"X-Limit": { description: "Page size, when pagination is requested.", schema: { type: "integer" } },
"X-Offset": {
description: "Zero-based offset, when pagination is requested.",
schema: { type: "integer" },
},
};
}
}
}
}
addCurlSamples(spec);
return spec;
}
type JsonSchema = OpenAPI.SchemaObject | OpenAPI.ReferenceObject;
// Mintlify's generated cURL samples use Bash `\` line continuations, which break when
// pasted into PowerShell or cmd. A custom sample labelled "cURL" replaces that tab only;
// the other generated languages stay as they are.
function addCurlSamples(spec: OpenAPI.Document) {
const resolve = (schema: JsonSchema | undefined): OpenAPI.SchemaObject => {
let current = schema;
while (current && "$ref" in current) {
const name = current.$ref.replace("#/components/schemas/", "");
current = spec.components?.schemas?.[name];
}
return current ?? {};
};
// Placeholder body with required fields only, in the same `<string>` style Mintlify uses.
const example = (schema: JsonSchema | undefined, parents: ReadonlySet<string> = new Set()): unknown => {
const isRef = schema !== undefined && "$ref" in schema;
if (isRef && parents.has(schema.$ref)) return {};
const seen = isRef ? new Set(parents).add(schema.$ref) : parents;
const value = resolve(schema);
if ("const" in value) return value.const;
if (value.enum) return value.enum[0];
const options = value.anyOf ?? value.oneOf;
if (options) return example(options.find((option) => resolve(option).type !== "null") ?? options[0], seen);
if (value.allOf) return Object.assign({}, ...value.allOf.map((part) => example(part, seen)));
const type = Array.isArray(value.type) ? value.type.find((item) => item !== "null") : value.type;
if (type === "object" || value.properties) {
return Object.fromEntries((value.required ?? []).map((key) => [key, example(value.properties?.[key], seen)]));
}
if (type === "array") return [example("items" in value ? value.items : undefined, seen)];
if (type === "integer" || type === "number") return 123;
if (type === "boolean") return true;
return "<string>";
};
for (const [path, item] of Object.entries(spec.paths ?? {})) {
if (!item) continue;
for (const method of ["get", "post", "put", "patch", "delete"] as const) {
const operation = item[method];
if (!operation) continue;
const query = (operation.parameters ?? [])
.filter((parameter): parameter is OpenAPI.ParameterObject => !("$ref" in parameter))
.filter((parameter) => parameter.in === "query" && parameter.required)
.map((parameter) => `${parameter.name}=<${parameter.name}>`)
.join("&");
// `<id>` rather than `{id}`: cURL treats braces in URLs as glob patterns.
const url = `${(operation.servers ?? spec.servers)?.[0]?.url ?? ""}${path.replace(/\{(\w+)\}/g, "<$1>")}${query ? `?${query}` : ""}`;
// Double quotes work in POSIX shells, PowerShell and cmd alike.
const args = method === "get" ? [`"${url}"`] : [`--request ${method.toUpperCase()}`, `"${url}"`];
const security = operation.security ?? spec.security;
if (security?.length) {
args.push(
security.some((requirement) => "apiKey" in requirement)
? `--header "x-api-key: <api-key>"`
: `--cookie "<session-cookie>"`,
);
}
const body = operation.requestBody && !("$ref" in operation.requestBody) ? operation.requestBody.content : {};
const json = body["application/json"];
const form = body["multipart/form-data"];
if (json) {
// Newlines inside a quoted argument are not line continuations, so the body stays readable.
args.push(`--header "Content-Type: application/json"`);
args.push(`--data '${JSON.stringify(example(json.schema), null, 2)}'`);
} else if (form) {
const fields = resolve(form.schema);
for (const key of fields.required ?? []) {
const field = resolve(fields.properties?.[key]);
const value = "contentMediaType" in field ? "@<file>" : example(field);
args.push(`--form "${key}=${typeof value === "string" ? value : JSON.stringify(value)}"`);
}
}
Object.assign(operation, {
"x-codeSamples": [{ lang: "bash", label: "cURL", source: `curl ${args.join(" ")}` }],
});
}
}
}