@arpixel/api-contract 0.1.0

package/dist/generator/api.js

@@ -0,0 +1,106 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { loadOpenApi } from "../openapi/loader.js";
+const METHODS = [
+    "get", "post", "put", "patch", "delete", "head", "options"
+];
+function pascalCase(value) {
+    return value
+        .replace(/[^a-zA-Z0-9]+(.)?/g, (_, c) => c ? c.toUpperCase() : "")
+        .replace(/^[a-z]/, c => c.toUpperCase());
+}
+function methodName(path, method, operationId) {
+    if (operationId)
+        return operationId;
+    const parts = path
+        .split("/")
+        .filter(Boolean)
+        .map(part => part.startsWith("{") ? `By${pascalCase(part.slice(1, -1))}` : pascalCase(part));
+    return `${method}${parts.join("") || "Root"}`;
+}
+function schemaType(refOrSchema) {
+    if (!refOrSchema || typeof refOrSchema !== "object")
+        return "unknown";
+    const schema = refOrSchema;
+    if (typeof schema.$ref === "string") {
+        const match = schema.$ref.match(/^#\/components\/schemas\/(.+)$/);
+        if (match)
+            return match[1];
+    }
+    if (typeof schema.type === "string") {
+        switch (schema.type) {
+            case "string": return "string";
+            case "integer":
+            case "number": return "number";
+            case "boolean": return "boolean";
+            case "array": return `${schemaType(schema.items)}[]`;
+            case "object": return "Record<string, unknown>";
+        }
+    }
+    return "unknown";
+}
+function responseType(operation) {
+    const responses = operation.responses;
+    if (!responses)
+        return "unknown";
+    const preferred = ["200", "201", "202", "204", "default"];
+    const status = preferred.find(code => responses[code]) ?? Object.keys(responses)[0];
+    if (!status)
+        return "unknown";
+    const response = responses[status];
+    if (status === "204")
+        return "void";
+    const content = response.content;
+    if (!content)
+        return "void";
+    const media = content["application/json"] ?? content[Object.keys(content)[0]];
+    const schema = media?.schema;
+    return schemaType(schema);
+}
+function parameterType(parameter) {
+    return schemaType(parameter.schema);
+}
+export async function generateApi(inputPath, outputPath, typesImport = "./types.js") {
+    const document = await loadOpenApi(inputPath);
+    const paths = document.paths ?? {};
+    const lines = [
+        "/* eslint-disable */",
+        "// Generated by api-contract. Do not edit manually.",
+        `import type * as ApiTypes from "${typesImport}";`,
+        "",
+        "export interface ApiMethods {"
+    ];
+    for (const [path, rawPathItem] of Object.entries(paths)) {
+        if (!rawPathItem || typeof rawPathItem !== "object")
+            continue;
+        const pathItem = rawPathItem;
+        const pathParameters = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
+        for (const method of METHODS) {
+            const rawOperation = pathItem[method];
+            if (!rawOperation || typeof rawOperation !== "object")
+                continue;
+            const operation = rawOperation;
+            const name = methodName(path, method, typeof operation.operationId === "string" ? operation.operationId : undefined);
+            const parameters = [
+                ...pathParameters,
+                ...(Array.isArray(operation.parameters) ? operation.parameters : [])
+            ];
+            const args = parameters
+                .filter(p => typeof p === "object")
+                .map(p => {
+                const param = p;
+                const paramName = String(param.name ?? "param");
+                const required = Boolean(param.required);
+                const type = parameterType(param);
+                return `${paramName}${required ? "" : "?"}: ${type}`;
+            });
+            const result = responseType(operation);
+            lines.push(`  ${name}(${args.join(", ")}): Promise<${result}>;`);
+        }
+    }
+    lines.push("}", "");
+    lines.push("// ApiTypes is imported to keep the generated contract connected to the generated OpenAPI types.");
+    lines.push("export type OpenApiTypes = typeof ApiTypes;");
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, lines.join("\n"), "utf8");
+}

package/dist/generator/typescript.d.ts

@@ -0,0 +1 @@
+export declare function generateTypes(inputPath: string, outputPath: string): Promise<void>;

package/dist/generator/typescript.js

@@ -0,0 +1,14 @@
+import openapiTS, { astToString } from "openapi-typescript";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { loadOpenApi } from "../openapi/loader.js";
+export async function generateTypes(inputPath, outputPath) {
+    const document = await loadOpenApi(inputPath);
+    const ast = await openapiTS(document, {
+        alphabetize: true,
+        enum: true
+    });
+    const output = astToString(ast);
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, output, "utf8");
+}

package/dist/openapi/loader.d.ts

@@ -0,0 +1,2 @@
+export type OpenApiDocument = Record<string, unknown>;
+export declare function loadOpenApi(filePath: string): Promise<OpenApiDocument>;

package/dist/openapi/loader.js

@@ -0,0 +1,4 @@
+import SwaggerParser from "@apidevtools/swagger-parser";
+export async function loadOpenApi(filePath) {
+    return SwaggerParser.validate(filePath);
+}

package/dist/types/diff.d.ts

@@ -0,0 +1,161 @@
+export type ChangeType = "ENDPOINT_ADDED" | "ENDPOINT_REMOVED" | "ENDPOINT_MODIFIED" | "PARAMETER_ADDED" | "PARAMETER_REMOVED" | "PARAMETER_TYPE_CHANGED" | "PARAMETER_REQUIRED_CHANGED" | "SCHEMA_ADDED" | "SCHEMA_REMOVED" | "SCHEMA_TYPE_CHANGED" | "PROPERTY_ADDED" | "PROPERTY_REMOVED" | "PROPERTY_TYPE_CHANGED" | "PROPERTY_REQUIRED_CHANGED" | "ENUM_VALUE_ADDED" | "ENUM_VALUE_REMOVED" | "REQUEST_BODY_ADDED" | "REQUEST_BODY_REMOVED" | "REQUEST_BODY_CHANGED" | "RESPONSE_ADDED" | "RESPONSE_REMOVED" | "RESPONSE_CHANGED";
+export interface DiffSummary {
+    added: number;
+    removed: number;
+    modified: number;
+    breaking: number;
+}
+export interface EndpointChangeBase {
+    location: string;
+    path: string;
+    method: string;
+    detail: string;
+    breaking: boolean;
+}
+export interface EndpointAddedChange extends EndpointChangeBase {
+    type: "ENDPOINT_ADDED";
+}
+export interface EndpointRemovedChange extends EndpointChangeBase {
+    type: "ENDPOINT_REMOVED";
+}
+export interface EndpointModifiedChange extends EndpointChangeBase {
+    type: "ENDPOINT_MODIFIED";
+    from: unknown;
+    to: unknown;
+}
+export interface ParameterChangeBase extends EndpointChangeBase {
+    parameter: string;
+}
+export interface ParameterAddedChange extends ParameterChangeBase {
+    type: "PARAMETER_ADDED";
+    to: {
+        required: boolean;
+    };
+}
+export interface ParameterRemovedChange extends ParameterChangeBase {
+    type: "PARAMETER_REMOVED";
+    from: {
+        required: boolean;
+    };
+}
+export interface ParameterTypeChangedChange extends ParameterChangeBase {
+    type: "PARAMETER_TYPE_CHANGED";
+    from: string;
+    to: string;
+}
+export interface ParameterRequiredChangedChange extends ParameterChangeBase {
+    type: "PARAMETER_REQUIRED_CHANGED";
+    from: "required" | "optional";
+    to: "required" | "optional";
+}
+export interface SchemaAddedChange {
+    type: "SCHEMA_ADDED";
+    schema: string;
+    location: string;
+    detail: string;
+    breaking: boolean;
+}
+export interface SchemaRemovedChange {
+    type: "SCHEMA_REMOVED";
+    schema: string;
+    location: string;
+    detail: string;
+    breaking: boolean;
+}
+export interface SchemaTypeChangedChange {
+    type: "SCHEMA_TYPE_CHANGED";
+    schema: string;
+    location: string;
+    from: string;
+    to: string;
+    detail: string;
+    breaking: boolean;
+}
+export interface PropertyChangeBase {
+    schema: string;
+    property: string;
+    location: string;
+    detail: string;
+    breaking: boolean;
+}
+export interface PropertyAddedChange extends PropertyChangeBase {
+    type: "PROPERTY_ADDED";
+    required: boolean;
+}
+export interface PropertyRemovedChange extends PropertyChangeBase {
+    type: "PROPERTY_REMOVED";
+    from: "required" | "optional";
+}
+export interface PropertyTypeChangedChange extends PropertyChangeBase {
+    type: "PROPERTY_TYPE_CHANGED";
+    from: string;
+    to: string;
+}
+export interface PropertyRequiredChangedChange extends PropertyChangeBase {
+    type: "PROPERTY_REQUIRED_CHANGED";
+    from: "required" | "optional";
+    to: "required" | "optional";
+}
+export interface EnumValueAddedChange {
+    type: "ENUM_VALUE_ADDED";
+    schema: string;
+    location: string;
+    value: unknown;
+    detail: string;
+    breaking: boolean;
+}
+export interface EnumValueRemovedChange {
+    type: "ENUM_VALUE_REMOVED";
+    schema: string;
+    location: string;
+    from: unknown;
+    detail: string;
+    breaking: boolean;
+}
+export interface RequestBodyChangeBase {
+    path: string;
+    method: string;
+    location: string;
+    detail: string;
+    breaking: boolean;
+}
+export interface RequestBodyAddedChange extends RequestBodyChangeBase {
+    type: "REQUEST_BODY_ADDED";
+    to: string;
+}
+export interface RequestBodyRemovedChange extends RequestBodyChangeBase {
+    type: "REQUEST_BODY_REMOVED";
+    from: string;
+}
+export interface RequestBodyChangedChange extends RequestBodyChangeBase {
+    type: "REQUEST_BODY_CHANGED";
+    from: string;
+    to: string;
+}
+export interface ResponseChangeBase {
+    path: string;
+    method: string;
+    status: string;
+    location: string;
+    detail: string;
+    breaking: boolean;
+}
+export interface ResponseAddedChange extends ResponseChangeBase {
+    type: "RESPONSE_ADDED";
+    to: string;
+}
+export interface ResponseRemovedChange extends ResponseChangeBase {
+    type: "RESPONSE_REMOVED";
+    from: string;
+}
+export interface ResponseChangedChange extends ResponseChangeBase {
+    type: "RESPONSE_CHANGED";
+    from: string;
+    to: string;
+}
+export type ContractChange = EndpointAddedChange | EndpointRemovedChange | EndpointModifiedChange | ParameterAddedChange | ParameterRemovedChange | ParameterTypeChangedChange | ParameterRequiredChangedChange | SchemaAddedChange | SchemaRemovedChange | SchemaTypeChangedChange | PropertyAddedChange | PropertyRemovedChange | PropertyTypeChangedChange | PropertyRequiredChangedChange | EnumValueAddedChange | EnumValueRemovedChange | RequestBodyAddedChange | RequestBodyRemovedChange | RequestBodyChangedChange | ResponseAddedChange | ResponseRemovedChange | ResponseChangedChange;
+export interface DiffResult {
+    version: "1";
+    summary: DiffSummary;
+    changes: ContractChange[];
+}

package/dist/types/diff.js

@@ -0,0 +1 @@
+export {};

package/integrations/vscode/api-contract-generate.agent.md

@@ -0,0 +1,161 @@
+---
+
+name: API Contract Generate
+description: Generate TypeScript API contract files from an OpenAPI specification using the api-contract CLI.
+-------------------------------------------------------------------------------------------------------------
+
+# API Contract Generate Agent
+
+You generate TypeScript API contract files from an OpenAPI specification using the `api-contract` CLI.
+
+## Responsibility
+
+Your job is to:
+
+1. Identify the user's OpenAPI input.
+2. Identify the user's requested output directory, if provided.
+3. Run the deterministic `api-contract generate` command.
+4. Verify the generated files.
+5. Report the result.
+
+The `api-contract` CLI owns the actual generation logic.
+
+Do not manually generate TypeScript from OpenAPI.
+
+---
+
+## Input
+
+The user may provide:
+
+* an attached OpenAPI file
+* a repository OpenAPI file
+* an explicit OpenAPI path
+
+Example:
+
+> Generate types for this openapi.yaml file and output to `src/api/generated-types`.
+
+Use the supplied OpenAPI file.
+
+---
+
+## Output Directory
+
+If the user specifies an output directory:
+
+```text
+<user-specified-directory>
+```
+
+use it exactly.
+
+Example:
+
+```text
+src/api/generated-types
+```
+
+Run:
+
+```bash
+api-contract generate <openapi-file> --output src/api/generated-types
+```
+
+If no output directory is specified, invoke the CLI without an output option:
+
+```bash
+api-contract generate <openapi-file>
+```
+
+The CLI resolves the default output relative to the current working directory:
+
+```text
+api-contract/generated/
+├── types.ts
+└── api.ts
+```
+
+Do not manually add `--output api-contract/generated` in this case.
+
+---
+
+## Execution
+
+When the user specifies an output directory, use:
+
+```bash
+api-contract generate <openapi-file> --output <output-directory>
+```
+
+When no output directory is specified, use:
+
+```bash
+api-contract generate <openapi-file>
+```
+
+The CLI is responsible for:
+
+* OpenAPI parsing
+* validation
+* TypeScript generation
+* writing generated files
+
+Do not reproduce or modify this logic in the agent.
+
+---
+
+## Verification
+
+After generation, verify that the output contains:
+
+```text
+types.ts
+api.ts
+```
+
+Confirm that the generated files contain TypeScript output corresponding to the supplied OpenAPI specification.
+
+Do not modify generated files manually.
+
+---
+
+## Modification Policy
+
+This agent is allowed to create or replace generated contract files because generation is its explicit purpose.
+
+It must not:
+
+* modify handwritten application code
+* modify unrelated files
+* silently choose a different output directory
+* manually edit generated output
+
+If the user explicitly requests application-code integration after generation, that should be treated as a separate task.
+
+---
+
+## Response
+
+Return:
+
+# API Contract Generation
+
+## Input
+
+* OpenAPI: `<path>`
+
+## Output
+
+* Directory: `<path>`
+
+## Generated
+
+* `<path>/types.ts`
+* `<path>/api.ts`
+
+## Result
+
+Briefly state whether generation succeeded.
+
+Keep the response concise.

package/integrations/vscode/api-contract-generate.prompt.md

@@ -0,0 +1,172 @@
+---
+
+description: Generate TypeScript API contract files from an OpenAPI specification
+agent: agent
+------------
+
+# API Contract Generate
+
+Generate TypeScript API contract files from an OpenAPI specification using the `api-contract` CLI.
+
+The user may provide:
+
+* an OpenAPI file
+* an output directory
+
+## Core Principle
+
+The `api-contract` CLI performs the actual OpenAPI-to-TypeScript generation.
+
+The agent is responsible for:
+
+* identifying the OpenAPI input
+* determining the requested output location
+* invoking `api-contract generate`
+* verifying the generated files
+* reporting the result
+
+Do not manually generate TypeScript from the OpenAPI specification.
+
+---
+
+## Input
+
+The user may provide an OpenAPI file and an optional output directory.
+
+Example:
+
+```text
+Generate types for this openapi.yaml file and output to src/api/generated-types.
+```
+
+The OpenAPI file may be:
+
+* a repository file
+* an attached file
+* an explicitly provided path
+
+---
+
+## Output Location
+
+### User-specified output
+
+If the user specifies an output directory, use that directory exactly.
+
+Example:
+
+```text
+src/api/generated-types
+```
+
+Run:
+
+```bash
+api-contract generate <openapi-file> --output src/api/generated-types
+```
+
+Do not substitute another directory unless the requested location is invalid or inaccessible.
+
+### Default output
+
+If the user does not specify an output directory, invoke the CLI without an output option:
+
+```bash
+api-contract generate <openapi-file>
+```
+
+The CLI resolves the default output relative to the current working directory:
+
+```text
+api-contract/generated/
+├── types.ts
+└── api.ts
+```
+
+---
+
+## Workflow
+
+### 1. Identify the OpenAPI file
+
+Determine the OpenAPI specification from the user's request.
+
+If the user attached a file, use that file.
+
+If the user provides a repository path, use that path.
+
+If multiple possible OpenAPI files exist and the intended file cannot be determined, ask the user rather than guessing.
+
+### 2. Determine the output directory
+
+Use the user-specified output directory when provided.
+
+Otherwise let the CLI determine the default output location by omitting `--output`.
+
+### 3. Generate
+
+If the user specified an output directory, run:
+
+```bash
+api-contract generate <openapi-file> --output <output-directory>
+```
+
+Otherwise run:
+
+```bash
+api-contract generate <openapi-file>
+```
+
+Do not manually reproduce the generation logic.
+
+### 4. Verify
+
+After generation, verify that the expected files exist:
+
+```text
+types.ts
+api.ts
+```
+
+Inspect the generated output enough to confirm that it contains TypeScript generated from the supplied OpenAPI specification.
+
+### 5. Handle existing output
+
+If the output directory already contains generated files, the CLI may replace them.
+
+Do not modify unrelated files.
+
+Do not modify handwritten application code.
+
+### 6. Report
+
+Provide:
+
+#### Generation Summary
+
+* OpenAPI input
+* output directory
+* command executed
+* generated files
+
+#### Result
+
+Confirm whether generation succeeded.
+
+#### Generated Files
+
+List the generated files using repository-relative paths where possible.
+
+---
+
+## Important Rules
+
+* Always use `api-contract generate`.
+* Never manually generate the TypeScript output.
+* Respect a user-specified output directory exactly.
+* Let the CLI default to `api-contract/generated/` relative to the current working directory when no output directory is provided.
+* Do not modify application code.
+* Do not modify unrelated files.
+* Do not introduce an LLM/API dependency into `api-contract`.
+* If the OpenAPI input cannot be identified, ask the user.
+* If the requested output location cannot be used, explain the problem instead of silently choosing another location.