main.tsp

import "@typespec/http";
import "@typespec/rest";
import "@typespec/openapi3";
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("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("create")
  password: string;

  /** Whether the user is validated. Never visible to the API. */
  @visibility("none") validated: boolean;
}

@jsonSchema
model TodoItem {
  /** The item's unique id */
  @visibility("read") @key id: safeint;

  /** The item's title */
  @maxLength(255)
  title: string;

  /** User that created the todo */
  @visibility("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("read") createdAt: utcDateTime;

  /** When the todo item was last updated */
  @visibility("read") updatedAt: utcDateTime;

  /** When the todo item was makred as completed */
  @visibility("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("create") _dummy?: string;
}

@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;
}

union TodoAttachment {
  file: TodoFileAttachment,
  url: TodoUrlAttachment,
}

@jsonSchema
model TodoUrlAttachment {
  /** A description of the URL */
  description: string;

  /** The url */
  url: url;
}

@jsonSchema
model TodoFileAttachment {
  /** 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[];

    pagination: {
      /** 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?: url;

      /** A link to the next page, if it exists */
      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;
  }

  model Page<T> {
    @pageItems items: T[];
  }

  @list op list(...PaginationControls): WithStandardErrors<TodoPage>;

  @post
  op create(
    @header contentType: "application/json",
    item: TodoItem,
    attachments?: TodoAttachment[],
  ): WithStandardErrors<TodoItem | InvalidTodoItem>;

  @get op get(@path id: TodoItem.id): TodoItem | NotFoundResponse;
  @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 | NotFoundResponse>;

  @route("{itemId}/attachments")
  namespace Attachments {
    @list op list(
      @path itemId: TodoItem.id,
    ): WithStandardErrors<Page<TodoAttachment> | NotFoundResponse>;

    @sharedRoute
    @post
    op createAttachment(
      @path itemId: TodoItem.id,
      @body contents: TodoAttachment,
    ): WithStandardErrors<NoContentResponse | NotFoundResponse>;
  }
}