Add blueprint API (#4)

* Add Usage

* Add test fixture

* Add @seamapi/types

* Export blueprint API

* Remove todo module

* Update describe

README.md

@@ -9,16 +9,30 @@ Build tools for the Seam API using this blueprint.
 
 TODO
 
+## Motivation
+
+TODO
+
 ## Installation
 
 Add this as a dependency to your project using [npm] with
 
 ```
-$ npm install @seamapi/blueprint
+$ npm install --save-dev @seamapi/blueprint
 ```
 
 [npm]: https://www.npmjs.com/
 
+## Usage
+
+```ts
+import { createBlueprint } from '@seamapi/blueprint'
+import * as types from '@seamapi/types'
+
+const blueprint = createBlueprint(types)
+console.log(JSON.stringify(blueprint)
+```
+
 ## Development and Testing
 
 ### Quickstart

examples/blueprint.ts

@@ -0,0 +1,24 @@
+import type { Builder, Command, Describe, Handler } from 'landlubber'
+
+import { createBlueprint, type TypesModule } from '@seamapi/blueprint'
+
+interface Options {
+  moduleName: string
+}
+
+export const command: Command = 'blueprint [moduleName]'
+
+export const describe: Describe = 'Create a blueprint from a module'
+
+export const builder: Builder = {
+  moduleName: {
+    type: 'string',
+    default: '@seamapi/types/connect',
+    describe: 'Module name or path to import',
+  },
+}
+
+export const handler: Handler<Options> = async ({ moduleName, logger }) => {
+  const types = (await import(moduleName)) as TypesModule
+  logger.info({ data: createBlueprint(types) }, 'blueprint')
+}

examples/index.ts

@@ -2,8 +2,8 @@
 
 import landlubber from 'landlubber'
 
-import * as todo from './todo.js'
+import * as blueprint from './blueprint.js'
 
-const commands = [todo]
+const commands = [blueprint]
 
 await landlubber(commands).parse()

package.json

@@ -68,6 +68,7 @@
     "npm": ">= 9.0.0"
   },
   "devDependencies": {
+    "@seamapi/types": "1.184.0",
     "@types/node": "^20.8.10",
     "ava": "^6.0.1",
     "c8": "^10.1.2",
@@ -83,6 +84,7 @@
     "tsc-alias": "^1.8.2",
     "tsup": "^8.0.1",
     "tsx": "^4.6.2",
-    "typescript": "~5.3.3"
+    "typescript": "~5.3.3",
+    "zod": "^3.23.8"
   }
 }

src/lib/blueprint.ts

@@ -0,0 +1,15 @@
+import type { Openapi } from './openapi.js'
+
+export interface Blueprint {
+  name: string
+}
+
+export interface TypesModule {
+  openapi: Openapi
+}
+
+export const createBlueprint = ({ openapi }: TypesModule): Blueprint => {
+  return {
+    name: openapi.info.title,
+  }
+}

src/lib/index.ts

@@ -1 +1,5 @@
-export { todo } from './todo.js'
+export {
+  type Blueprint,
+  createBlueprint,
+  type TypesModule,
+} from './blueprint.js'

src/lib/openapi.ts

@@ -0,0 +1,5 @@
+export interface Openapi {
+  info: {
+    title: string
+  }
+}

test/blueprint.test.ts

@@ -0,0 +1,10 @@
+import test from 'ava'
+
+import { createBlueprint } from '@seamapi/blueprint'
+
+import * as types from './fixtures/types/index.js'
+
+test('createBlueprint', (t) => {
+  const blueprint = createBlueprint(types)
+  t.snapshot(blueprint, 'blueprint')
+})

test/fixtures/types/index.ts

@@ -0,0 +1,8 @@
+import * as schemas from './schemas.js'
+
+export { schemas }
+
+export * from './model-types.js'
+export { default as openapi } from './openapi.js'
+export * from './route-schemas.js'
+export * from './route-types.js'

test/fixtures/types/model-types.ts

@@ -0,0 +1,5 @@
+import type { z } from 'zod'
+
+import type { foo } from './schemas.js'
+
+export type Foo = z.infer<typeof foo>

test/fixtures/types/openapi.ts

@@ -0,0 +1,79 @@
+export default {
+  openapi: '3.0.0',
+  info: { title: 'Foo', version: '1.0.0' },
+  servers: [{ url: 'https://example.com' }],
+  tags: [{ description: 'foos', name: '/foos' }],
+  components: {
+    schemas: {
+      foo: {
+        type: 'object',
+        properties: {
+          foo_id: {
+            description: 'Foo id',
+            format: 'uuid',
+            type: 'string',
+          },
+          name: {
+            description: 'Foo name',
+            type: 'string',
+          },
+        },
+        required: ['foo_id', 'name'],
+      },
+    },
+  },
+  paths: {
+    '/foos/get': {
+      get: {
+        operationId: 'foosGetGet',
+        responses: {
+          200: {
+            content: {
+              'application/json': {
+                schema: {
+                  properties: {
+                    ok: { type: 'boolean' },
+                    foo: { $ref: '#/components/schemas/foo' },
+                  },
+                  required: ['foo', 'ok'],
+                  type: 'object',
+                },
+              },
+            },
+            description: 'OK',
+          },
+          400: { description: 'Bad Request' },
+          401: { description: 'Unauthorized' },
+        },
+        security: [],
+        summary: '/foos/get',
+        tags: ['/foos'],
+      },
+      post: {
+        operationId: 'foosGetPost',
+        responses: {
+          200: {
+            content: {
+              'application/json': {
+                schema: {
+                  properties: {
+                    ok: { type: 'boolean' },
+                    foo: { $ref: '#/components/schemas/foo' },
+                  },
+                  required: ['foo', 'ok'],
+                  type: 'object',
+                },
+              },
+            },
+            description: 'OK',
+          },
+          400: { description: 'Bad Request' },
+          401: { description: 'Unauthorized' },
+        },
+        security: [],
+        summary: '/foos/get',
+        tags: ['/foos'],
+      },
+    },
+  },
+}

test/fixtures/types/route-schemas.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod'
+
+import * as schemas from './schemas.js'
+
+export const routes = {
+  '/foos/get': {
+    auth: 'none',
+    methods: ['GET', 'POST'],
+    jsonResponse: z.object({
+      foo: schemas.foo,
+    }),
+  },
+} as const

test/fixtures/types/route-specs.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod'
+
+import * as schemas from './schemas.js'
+
+export const routes = {
+  '/foos/get': {
+    auth: 'none',
+    methods: ['GET', 'POST'],
+    jsonResponse: z.object({
+      foo: schemas.foo,
+    }),
+  },
+} as const

test/fixtures/types/route-types.ts

@@ -0,0 +1,25 @@
+export interface Routes {
+  '/foos/get': {
+    route: '/foos/get'
+    method: 'GET' | 'POST'
+    queryParams: Record<string, unknown>
+    jsonBody: Record<string, unknown>
+    commonParams: Record<string, unknown>
+    formData: Record<string, unknown>
+    jsonResponse: {
+      foo: {
+        foo_id: string
+        name: string
+      }
+    }
+  }
+}
+
+export type RouteResponse<Path extends keyof Routes> =
+  Routes[Path]['jsonResponse']
+
+export type RouteRequestBody<Path extends keyof Routes> =
+  Routes[Path]['jsonBody'] & Routes[Path]['commonParams']
+
+export type RouteRequestParams<Path extends keyof Routes> =
+  Routes[Path]['queryParams'] & Routes[Path]['commonParams']

test/fixtures/types/schemas.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod'
+
+export const foo = z.object({
+  foo_id: z.string().uuid(),
+  name: z.string(),
+})

test/seamapi-blueprint.test.ts

@@ -0,0 +1,9 @@
+import { openapi } from '@seamapi/types/connect'
+import test from 'ava'
+
+import { createBlueprint } from '@seamapi/blueprint'
+
+test('createBlueprint', (t) => {
+  const blueprint = createBlueprint({ openapi })
+  t.snapshot(blueprint, 'blueprint')
+})

test/snapshots/blueprint.test.ts.md

@@ -0,0 +1,13 @@
+# Snapshot report for `test/blueprint.test.ts`
+
+The actual snapshot is saved in `blueprint.test.ts.snap`.
+
+Generated by [AVA](https://avajs.dev).
+
+## createBlueprint
+
+> blueprint
+
+    {
+      name: 'Foo',
+    }