adds OpenAPI spec generation scripts

.spectral.yaml

@@ -0,0 +1,2 @@
+extends:
+  - spectral:oas

package.json

@@ -15,7 +15,10 @@
     "pretest": "./node_modules/.bin/tsc -p tsconfig-test.json",
     "test": "NODE_ENV=TEST ./node_modules/.bin/mocha --exit --timeout 100000 ./test-dist/test/index.js",
     "lint": "eslint src",
-    "lint:fix": "eslint src --fix"
+    "lint:fix": "eslint src --fix",
+    "generate:openapi": "npx ts-node --project scripts/tsconfig.scripts.json scripts/generate-openapi.ts",
+    "validate:openapi": "npx ts-node --project scripts/tsconfig.scripts.json scripts/validate-openapi.ts",
+    "lint:openapi": "npx @stoplight/spectral-cli lint openapi.yaml"
   },
   "repository": {
     "type": "git",
@@ -34,6 +37,7 @@
   "homepage": "https://github.com/MethodFi/method-node#readme",
   "devDependencies": {
     "@types/chai": "^4.3.1",
+    "@types/js-yaml": "^4.0.9",
     "@types/mocha": "^9.1.1",
     "@types/node": "^17.0.45",
     "chai": "^4.3.6",
@@ -43,6 +47,7 @@
     "eslint-config-airbnb": "^19.0.4",
     "eslint-plugin-flowtype": "^8.0.3",
     "eslint-plugin-import": "^2.26.0",
+    "js-yaml": "^4.1.0",
     "mocha": "^9.2.2",
     "rollup": "^2.70.2",
     "rollup-plugin-dts": "^4.2.1",

scripts/README.md

@@ -0,0 +1,103 @@
+# OpenAPI Specification Scripts
+
+This directory contains scripts for generating and validating the OpenAPI 3.0 specification from the Method Node.js SDK.
+
+## Scripts
+
+### generate-openapi.ts
+
+Generates an OpenAPI 3.0.3 specification by parsing the TypeScript SDK source files.
+
+**Usage:**
+```bash
+npm run generate:openapi
+```
+
+**Output:**
+- `openapi.yaml` - YAML format specification
+- `openapi.json` - JSON format specification
+
+**What it does:**
+1. Parses all `types.ts` files in `src/resources/` to extract TypeScript interfaces
+2. Converts TypeScript types to OpenAPI schemas (handling nullables, arrays, enums, etc.)
+3. Generates path definitions for all API endpoints based on SDK resource structure
+4. Outputs both YAML and JSON versions of the specification
+
+### validate-openapi.ts
+
+Validates the generated OpenAPI spec against the SDK source to ensure they match.
+
+**Usage:**
+```bash
+npm run validate:openapi
+```
+
+**What it validates:**
+- All expected API paths are present in the spec
+- HTTP methods match the SDK implementation
+- Schema properties match SDK interface definitions
+- Required vs optional field alignment
+
+## Linting
+
+The OpenAPI spec can be linted using Spectral for style and correctness:
+
+```bash
+npm run lint:openapi
+```
+
+This uses the `.spectral.yaml` configuration in the project root.
+
+## Workflow
+
+1. **Generate** the spec after SDK changes:
+   ```bash
+   npm run generate:openapi
+   ```
+
+2. **Validate** the spec matches the SDK:
+   ```bash
+   npm run validate:openapi
+   ```
+
+3. **Lint** for style issues:
+   ```bash
+   npm run lint:openapi
+   ```
+
+## Using the Generated Spec
+
+The generated OpenAPI specification can be used with code generators to create clients in other languages:
+
+```bash
+# Generate a Kotlin client
+npx @openapitools/openapi-generator-cli generate \
+  -i openapi.yaml \
+  -g kotlin \
+  -o ./generated/kotlin-client
+
+# Generate a Java client
+npx @openapitools/openapi-generator-cli generate \
+  -i openapi.yaml \
+  -g java \
+  -o ./generated/java-client
+```
+
+See [OpenAPI Generator](https://openapi-generator.tech/docs/generators) for all available generators.
+
+## Type Mapping
+
+| TypeScript | OpenAPI |
+|------------|---------|
+| `string` | `type: string` |
+| `number` | `type: number` |
+| `boolean` | `type: boolean` |
+| `string \| null` | `type: string, nullable: true` |
+| `T[]` | `type: array, items: {$ref: T}` |
+| `interface I{...}` | `$ref: '#/components/schemas/...'` |
+| `keyof typeof X` | `enum: [...]` |
+| Optional `prop?:` | Not in `required` array |
+
+## Configuration
+
+The scripts use their own TypeScript configuration in `tsconfig.scripts.json` to avoid conflicts with the main SDK build configuration.