@typespec/http-specs 0.1.0-alpha.9 → 0.1.0-dev.0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@typespec/http-specs",
-  "version": "0.1.0-alpha.9",
+  "displayName": "Http Specs",
+  "version": "0.1.0-dev.0",
   "description": "Spec scenarios and mock apis",
   "main": "dist/index.js",
   "type": "module",
@@ -11,6 +12,9 @@
     "type": "git",
     "url": "git+https://github.com/microsoft/typespec.git"
   },
+  "spector": {
+    "sourceUrl": "https://github.com/microsoft/typespec/tree/main/packages/http-specs/specs/{scenarioPath}"
+  },
   "author": "Microsoft",
   "license": "MIT",
   "bugs": {
@@ -18,39 +22,46 @@
   },
   "homepage": "https://github.com/microsoft/typespec#readme",
   "dependencies": {
-    "@typespec/spec-api": "~0.1.0-alpha.1",
-    "@typespec/spector": "~0.1.0-alpha.7"
+    "@typespec/spec-api": "^0.1.0-alpha.13 || >= 0.1.0-dev.0",
+    "@typespec/spector": "^0.1.0-alpha.24 || >= 0.1.0-dev.0",
+    "deep-equal": "^2.2.0"
   },
   "devDependencies": {
-    "@types/multer": "^1.4.10",
-    "@types/node": "~22.10.10",
+    "@types/deep-equal": "^1.0.1",
+    "@types/multer": "^2.0.0",
+    "@types/node": "~25.3.0",
+    "@typespec/json-schema": "^1.10.0 || >= 1.11.0-dev.0",
+    "@typespec/openapi": "^1.10.0 || >= 1.11.0-dev.0",
+    "@typespec/openapi3": "^1.10.0 || >= 1.11.0-dev.0",
     "concurrently": "^9.1.2",
-    "rimraf": "~6.0.1",
-    "typescript": "~5.7.3",
-    "@typespec/openapi": "~0.65.0",
-    "@typespec/openapi3": "~0.65.0"
+    "rimraf": "~6.1.3",
+    "typescript": "~5.9.3"
   },
   "peerDependencies": {
-    "@typespec/compiler": "~0.65.0",
-    "@typespec/http": "~0.65.0",
-    "@typespec/rest": "~0.65.0",
-    "@typespec/versioning": "~0.65.0",
-    "@typespec/xml": "~0.65.0"
+    "@typespec/compiler": "^1.10.0 || >= 1.11.0-dev.0",
+    "@typespec/http": "^1.10.0 || >= 1.11.0-dev.0",
+    "@typespec/rest": "^0.80.0 || >= 0.81.0-dev.0",
+    "@typespec/versioning": "^0.80.0 || >= 0.81.0-dev.0",
+    "@typespec/xml": "^0.80.0 || >= 0.81.0-dev.0"
   },
   "scripts": {
     "watch": "tsc -p ./tsconfig.build.json --watch",
-    "build": "tsc -p ./tsconfig.build.json",
+    "build": "tsc -p ./tsconfig.build.json && pnpm validate-scenarios && pnpm build:smoke",
     "clean": "rimraf dist/ temp/",
-    "test:e2e": "pnpm validate-scenarios  && pnpm validate-mock-apis && pnpm validate-client-server",
+    "test:e2e": "pnpm validate-mock-apis && pnpm validate-client-server",
+    "validate:all": "pnpm build && pnpm regen-docs && pnpm test:e2e",
+    "ci": "prettier specs --write && pnpm validate:all",
     "validate-scenarios": "tsp-spector validate-scenarios ./specs",
     "generate-scenarios-summary": "tsp-spector generate-scenarios-summary ./specs",
     "regen-docs": "pnpm generate-scenarios-summary",
-    "upload-manifest": "tsp-spector upload-manifest ./specs --setName @typespec/http-specs --containerName manifests-typespec  --storageAccountName typespec",
+    "upload-manifest": "tsp-spector upload-manifest ./specs --containerName coverages  --storageAccountName typespec --manifestName http-specs",
     "upload-coverage": "tsp-spector upload-coverage --generatorName @typespec/http-specs --generatorVersion 0.1.0-alpha.4 --containerName coverages --generatorMode standard --storageAccountName typespec",
     "validate-mock-apis": "tsp-spector validate-mock-apis ./specs",
     "check-scenario-coverage": "tsp-spector check-coverage ./specs",
-    "validate-client-server": "concurrently \"tsp-spector server start ./specs\" \"npm run client\" && tsp-spector server stop",
-    "client": "tsp-spector server-test ./specs",
+    "validate-client-server": "concurrently \"tsp-spector server start ./specs\" \"pnpm knock\"; tsp-spector server stop",
+    "build:smoke": "tsp compile smoke/petstore --warn-as-error --no-emit && tsp compile smoke/todoapp --warn-as-error --no-emit",
+    "client": "pnpm knock",
+    "knock": "tsp-spector knock ./specs",
     "serve": "tsp-spector serve ./specs",
     "test": "echo \"Error: no test specified\""
   }

package/smoke/petstore/main.tsp

@@ -0,0 +1,96 @@
+import "@typespec/rest";
+import "@typespec/openapi";
+
+@service(#{ title: "Pet Store Service" })
+namespace PetStore;
+
+using TypeSpec.Http;
+using TypeSpec.Rest;
+using TypeSpec.Rest.Resource;
+
+@error
+model PetStoreError {
+  code: int32;
+  message: string;
+}
+
+@resource("pets")
+model Pet {
+  @key("petId")
+  id: int32;
+
+  name: string;
+  tag?: string;
+
+  @minValue(0)
+  @maxValue(20)
+  age: int32;
+
+  ownerId: int64;
+}
+
+@resource("toys")
+@parentResource(Pet)
+model Toy {
+  @key("toyId")
+  id: int64;
+
+  petId: int64;
+  name: string;
+}
+
+@resource("owners")
+model Owner {
+  @key("ownerId")
+  id: int64;
+
+  name: string;
+  age: int32;
+}
+
+@resource("checkups")
+model Checkup {
+  @key("checkupId")
+  id: int32;
+
+  vetName: string;
+  notes: string;
+}
+
+@segment("insurance")
+model Insurance {
+  provider: string;
+  premium: int32;
+  deductible: int32;
+}
+
+interface Pets extends ResourceOperations<Pet, PetStoreError> {}
+
+interface PetCheckups
+  extends ExtensionResourceCreateOrUpdate<Checkup, Pet, PetStoreError>,
+    ExtensionResourceList<Checkup, Pet, PetStoreError> {}
+
+interface PetInsurance extends SingletonResourceOperations<Insurance, Pet, PetStoreError> {}
+
+interface Toys extends ResourceRead<Toy, PetStoreError> {
+  @autoRoute
+  @listsResource(Toy)
+  list(
+    ...ParentKeysOf<Toy>,
+    @query nameFilter: string,
+  ): CollectionWithNextLink<Toy> | PetStoreError;
+}
+
+interface ToyInsurance extends SingletonResourceOperations<Insurance, Toy, PetStoreError> {}
+
+interface Checkups
+  extends ResourceCreateOrUpdate<Checkup, PetStoreError>,
+    ResourceList<Checkup, PetStoreError> {}
+
+interface Owners extends ResourceOperations<Owner, PetStoreError> {}
+
+interface OwnerCheckups
+  extends ExtensionResourceCreateOrUpdate<Checkup, Owner, PetStoreError>,
+    ExtensionResourceList<Checkup, Owner, PetStoreError> {}
+
+interface OwnerInsurance extends SingletonResourceOperations<Insurance, Owner, PetStoreError> {}

package/smoke/todoapp/main.tsp

@@ -0,0 +1,293 @@
+import "@typespec/http";
+import "@typespec/rest";
+import "@typespec/openapi";
+import "@typespec/json-schema";
+using Http;
+using JsonSchema;
+
+@service(#{ title: "Todo App" })
+@useAuth(BearerAuth | ApiKeyAuth<ApiKeyLocation.cookie, "session-id">)
+@jsonSchema
+namespace Todo;
+
+@jsonSchema
+model User {
+  /** An autogenerated unique id for the user */
+  @key
+  @visibility(Lifecycle.Read)
+  id: safeint;
+
+  /** The user's username */
+  @minLength(2)
+  @maxLength(50)
+  username: string;
+
+  /** The user's email address */
+  // @format("email") - crashes emitters for now
+  email: string;
+
+  /**
+   * The user's password, provided when creating a user
+   * but is otherwise not visible (and hashed by the backend)
+   */
+  @visibility(Lifecycle.Create)
+  password: string;
+
+  /** Whether the user is validated. Never visible to the API. */
+  @invisible(Lifecycle) validated: boolean;
+}
+
+@jsonSchema
+model TodoItem {
+  /** The item's unique id */
+  @visibility(Lifecycle.Read) @key id: safeint;
+
+  /** The item's title */
+  @maxLength(255)
+  title: string;
+
+  /** User that created the todo */
+  @visibility(Lifecycle.Read) createdBy: User.id;
+
+  /** User that the todo is assigned to */
+  assignedTo?: User.id;
+
+  /** A longer description of the todo item in markdown format */
+  description?: string;
+
+  /** The status of the todo item */
+  status: "NotStarted" | "InProgress" | "Completed";
+
+  /** When the todo item was created. */
+  @visibility(Lifecycle.Read) createdAt: utcDateTime;
+
+  /** When the todo item was last updated */
+  @visibility(Lifecycle.Read) updatedAt: utcDateTime;
+
+  /** When the todo item was marked as completed */
+  @visibility(Lifecycle.Read) completedAt?: utcDateTime;
+
+  // Want the read form to be normalized to TodoLabelRecord[], but can't
+  // https://github.com/microsoft/typespec/issues/2926
+  labels?: TodoLabels;
+
+  // hack to get a different schema for create
+  // (fastify glue doesn't support readonly)
+  @visibility(Lifecycle.Create) _dummy?: string;
+}
+
+model ToDoItemMultipartRequest {
+  item: HttpPart<TodoItem>;
+  attachments?: HttpPart<File>[];
+}
+
+model FileAttachmentMultipartRequest {
+  contents: HttpPart<File>;
+}
+
+@jsonSchema
+union TodoLabels {
+  string,
+  string[],
+  TodoLabelRecord,
+  TodoLabelRecord[],
+}
+
+@jsonSchema
+model TodoLabelRecord {
+  name: string;
+
+  @pattern("^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$")
+  color?: string;
+}
+
+@jsonSchema
+model TodoAttachment {
+  /** The file name of the attachment */
+  @maxLength(255)
+  filename: string;
+
+  /** The media type of the attachment */
+  mediaType: string;
+
+  /** The contents of the file */
+  contents: bytes;
+}
+
+@jsonSchema
+@error
+model ApiError {
+  /** A machine readable error code */
+  code: string;
+
+  /** A human readable message */
+  // https://github.com/microsoft/OpenAPI/blob/main/extensions/x-ms-primary-error-message.md
+  @OpenAPI.extension("x-ms-primary-error-message", true)
+  message: string;
+}
+
+/**
+ * Something is wrong with you.
+ */
+model Standard4XXResponse extends ApiError {
+  @minValue(400)
+  @maxValue(499)
+  @statusCode
+  statusCode: int32;
+}
+
+/**
+ * Something is wrong with me.
+ */
+model Standard5XXResponse extends ApiError {
+  @minValue(500)
+  @maxValue(599)
+  @statusCode
+  statusCode: int32;
+}
+
+alias WithStandardErrors<T> = T | Standard4XXResponse | Standard5XXResponse;
+
+@useAuth(NoAuth)
+namespace Users {
+  // would prefer to extend
+  // https://github.com/microsoft/typespec/issues/2922
+
+  model UserCreatedResponse {
+    ...User;
+    ...OkResponse;
+
+    /** The token to use to construct the validate email address url */
+    token: string;
+  }
+
+  /** The user already exists */
+  model UserExistsResponse extends ApiError {
+    ...ConflictResponse;
+    code: "user-exists";
+  }
+
+  /** The user is invalid (e.g. forgot to enter email address) */
+  model InvalidUserResponse extends ApiError {
+    @statusCode statusCode: 422;
+    code: "invalid-user";
+  }
+
+  @route("/users")
+  @post
+  op create(
+    @body user: User,
+  ): WithStandardErrors<UserCreatedResponse | UserExistsResponse | InvalidUserResponse>;
+}
+
+@route("items")
+namespace TodoItems {
+  model PaginationControls {
+    /** The limit to the number of items */
+    @query limit?: int32 = 50;
+
+    /** The offset to start paginating at */
+    @query offset?: int32 = 0;
+  }
+
+  model TodoPage {
+    /** The items in the page */
+    @pageItems items: TodoItem[];
+
+    /** The number of items returned in this page */
+    pageSize: int32;
+
+    /** The total number of items */
+    totalSize: int32;
+
+    ...PaginationControls;
+
+    /** A link to the previous page, if it exists */
+    @prevLink
+    prevLink?: url;
+
+    /** A link to the next page, if it exists */
+    @nextLink
+    nextLink?: url;
+  }
+
+  // deeply annoying that I have to copy/paste this...
+  model TodoItemPatch {
+    /** The item's title */
+    title?: TodoItem.title;
+
+    /** User that the todo is assigned to */
+    assignedTo?: TodoItem.assignedTo | null;
+
+    /** A longer description of the todo item in markdown format */
+    description?: TodoItem.description | null;
+
+    /** The status of the todo item */
+    status?: "NotStarted" | "InProgress" | "Completed";
+  }
+
+  model InvalidTodoItem extends ApiError {
+    @statusCode statusCode: 422;
+  }
+
+  @error
+  model NotFoundErrorResponse {
+    @statusCode statusCode: 404;
+    code: "not-found";
+  }
+
+  //@friendlyName("{name}List", T)
+  model Page<T> {
+    @pageItems items: T[];
+  }
+
+  @list op list(...PaginationControls): WithStandardErrors<TodoPage>;
+
+  @sharedRoute
+  @post
+  op createJson(
+    @header contentType: "application/json",
+    item: TodoItem,
+    attachments?: TodoAttachment[],
+  ): WithStandardErrors<TodoItem | InvalidTodoItem>;
+
+  @sharedRoute
+  @post
+  op createForm(
+    @header contentType: "multipart/form-data",
+    @multipartBody body: ToDoItemMultipartRequest,
+  ): WithStandardErrors<TodoItem | InvalidTodoItem>;
+
+  @get op get(@path id: TodoItem.id): TodoItem | NotFoundErrorResponse;
+  @patch op update(
+    @header contentType: "application/merge-patch+json",
+    @path id: TodoItem.id,
+    @body patch: TodoItemPatch,
+  ): TodoItem;
+  @delete op delete(
+    @path id: TodoItem.id,
+  ): WithStandardErrors<NoContentResponse | NotFoundErrorResponse>;
+
+  @route("{itemId}/attachments")
+  namespace Attachments {
+    @list op list(
+      @path itemId: TodoItem.id,
+    ): WithStandardErrors<Page<TodoAttachment> | NotFoundErrorResponse>;
+
+    @sharedRoute
+    @post
+    op createJsonAttachment(
+      @header contentType: "application/json",
+      @path itemId: TodoItem.id,
+      @body contents: TodoAttachment,
+    ): WithStandardErrors<NoContentResponse | NotFoundErrorResponse>;
+
+    @sharedRoute
+    @post
+    op createFileAttachment(
+      @header contentType: "multipart/form-data",
+      @path itemId: TodoItem.id,
+      @multipartBody body: FileAttachmentMultipartRequest,
+    ): WithStandardErrors<NoContentResponse | NotFoundErrorResponse>;
+  }
+}