@knpkv/jira-cli 1.1.1 → 1.2.0

package/src/commands/issueAttachment.ts

@@ -0,0 +1,146 @@
+/**
+ * `jira issue attachment` resource commands.
+ *
+ * @internal
+ */
+import { renderAttachmentMarkdown } from "@knpkv/atlassian-common/attachments"
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Option from "effect/Option"
+import { Argument as Args, Command, Flag as Options } from "effect/unstable/cli"
+import { AttachmentService } from "../AttachmentService.js"
+import { insertJiraAttachmentReference } from "../internal/attachmentInsertion.js"
+import { JiraApiError, WriteError } from "../JiraCliError.js"
+
+const issueArg = Args.string("issue").pipe(
+  Args.withDescription("Issue key or id, for example PROJ-123")
+)
+
+const fileArg = Args.string("file").pipe(
+  Args.withDescription("Local file to upload")
+)
+
+const documentOption = Options.file("document").pipe(
+  Options.withDescription("Local Jira Markdown document containing the attachment placeholder"),
+  Options.optional
+)
+
+const noInsertOption = Options.boolean("no-insert").pipe(
+  Options.withDescription("Only upload and print the Attachment Reference")
+)
+
+const dryRunOption = Options.boolean("dry-run").pipe(
+  Options.withAlias("n"),
+  Options.withDescription("Validate local insertion input without uploading")
+)
+
+const jsonOption = Options.boolean("json").pipe(
+  Options.withDescription("Write exactly one JSON value to stdout")
+)
+
+const readDocument = (documentPath: string) =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    return yield* fs.readFileString(documentPath).pipe(
+      Effect.mapError((cause) =>
+        new WriteError({ path: documentPath, message: "Failed to read Jira Markdown document", cause })
+      )
+    )
+  })
+
+const writeDocument = (documentPath: string, content: string) =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    return yield* fs.writeFileString(documentPath, content).pipe(
+      Effect.mapError((cause) =>
+        new WriteError({ path: documentPath, message: "Failed to write Jira Markdown document", cause })
+      )
+    )
+  })
+
+const fileExists = (filePath: string) =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    return yield* fs.exists(filePath).pipe(
+      Effect.mapError((cause) => new WriteError({ path: filePath, message: "Failed to check attachment file", cause }))
+    )
+  })
+
+const uploadCommand = Command.make(
+  "upload",
+  {
+    issue: issueArg,
+    file: fileArg,
+    document: documentOption,
+    noInsert: noInsertOption,
+    dryRun: dryRunOption,
+    json: jsonOption
+  },
+  ({ document, dryRun, file, issue, json, noInsert }) =>
+    Effect.gen(function*() {
+      const documentPath = Option.isSome(document) ? document.value : null
+      const shouldInsert = !noInsert && documentPath !== null
+      const documentInput = shouldInsert
+        ? { path: documentPath, content: yield* readDocument(documentPath) }
+        : null
+
+      if (documentInput !== null) {
+        const matches = countPlaceholderMatches(documentInput.content, file)
+        if (matches !== 1) {
+          return yield* Effect.fail(
+            new JiraApiError({ message: `Expected exactly one attachment placeholder for ${file}, found ${matches}` })
+          )
+        }
+      }
+
+      if (dryRun) {
+        const exists = yield* fileExists(file)
+        if (!exists) {
+          return yield* Effect.fail(new JiraApiError({ message: `Attachment file does not exist: ${file}` }))
+        }
+        const result = { dryRun: true, issue, file, insert: shouldInsert }
+        yield* Console.log(json ? JSON.stringify(result) : `Dry run: ${file} can be uploaded to ${issue}`)
+        return
+      }
+
+      const service = yield* AttachmentService
+      const attachment = yield* service.uploadToIssue(issue, { filePath: file })
+      let inserted = false
+
+      if (documentInput !== null) {
+        const result = insertJiraAttachmentReference(documentInput.content, file, attachment)
+        if (result.replacements !== 1) {
+          return yield* Effect.fail(
+            new JiraApiError({
+              message:
+                `Uploaded attachment ${attachment.id}, but expected exactly one local placeholder for ${file}; found ${result.replacements}`
+            })
+          )
+        }
+        yield* writeDocument(documentInput.path, result.content)
+        inserted = true
+      }
+
+      if (json) {
+        yield* Console.log(JSON.stringify({ attachment, inserted }))
+      } else {
+        yield* Console.log(renderAttachmentMarkdown(attachment))
+        if (inserted) yield* Console.log(`Inserted into ${documentPath}`)
+      }
+    })
+).pipe(Command.withDescription("Remote write: upload a local file as a Jira issue attachment"))
+
+export const attachmentCommand = Command.make(
+  "attachment",
+  {},
+  () => Console.log("Usage: jira issue attachment upload <issue> <file>")
+).pipe(
+  Command.withDescription("Jira issue attachment commands"),
+  Command.withSubcommands([uploadCommand])
+)
+
+const countPlaceholderMatches = (content: string, placeholderPath: string): number => {
+  const escapedPath = placeholderPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return [...content.matchAll(new RegExp(`!?\\[[^\\]]*\\]\\(${escapedPath}\\)`, "g"))].length
+}

package/src/commands/layers.ts

@@ -16,6 +16,7 @@ import * as NodeServices from "@effect/platform-node/NodeServices"
 import { JiraApiClient, JiraApiConfig } from "@knpkv/jira-api-client"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
+import { AttachmentService, layer as AttachmentServiceLayer } from "../AttachmentService.js"
 import { IssueService, layer as IssueServiceLayer, SiteUrl } from "../IssueService.js"
 import { JiraAuth, layer as JiraAuthLayer } from "../JiraAuth.js"
 import { layer as MarkdownWriterLayer, MarkdownWriter } from "../MarkdownWriter.js"
@@ -31,6 +32,13 @@ const DummyIssueServiceLayer = Layer.succeed(
   })
 )
 
+const DummyAttachmentServiceLayer = Layer.succeed(
+  AttachmentService,
+  AttachmentService.of({
+    uploadToIssue: () => Effect.die(new Error("Not configured - run 'jira auth login' first"))
+  })
+)
+
 const DummyMarkdownWriterLayer = Layer.succeed(
   MarkdownWriter,
   MarkdownWriter.of({
@@ -82,10 +90,10 @@ const JiraConfigLive = Layer.unwrap(
     return Layer.succeed(JiraApiConfig, {
       baseUrl: "",
       auth: {
-        type: "oauth2" as const,
+        type: "oauth2",
         accessToken,
         cloudId
-      }
+      } satisfies { readonly type: "oauth2"; readonly accessToken: typeof accessToken; readonly cloudId: string }
     })
   })
 )
@@ -110,6 +118,7 @@ const SiteUrlLive = Layer.unwrap(
  * @category Layers
  */
 export const AppLayer = MarkdownWriterLayer.pipe(
+  Layer.provideMerge(AttachmentServiceLayer),
   Layer.provideMerge(IssueServiceLayer),
   Layer.provideMerge(VersionServiceLayer),
   Layer.provideMerge(SiteUrlLive),
@@ -125,6 +134,7 @@ export const AppLayer = MarkdownWriterLayer.pipe(
  * @category Layers
  */
 export const AuthOnlyLayer = DummyIssueServiceLayer.pipe(
+  Layer.provideMerge(DummyAttachmentServiceLayer),
   Layer.provideMerge(DummyMarkdownWriterLayer),
   Layer.provideMerge(DummyVersionServiceLayer),
   Layer.provideMerge(AuthLive),
@@ -138,6 +148,7 @@ export const AuthOnlyLayer = DummyIssueServiceLayer.pipe(
  * @category Layers
  */
 export const MinimalLayer = DummyIssueServiceLayer.pipe(
+  Layer.provideMerge(DummyAttachmentServiceLayer),
   Layer.provideMerge(DummyMarkdownWriterLayer),
   Layer.provideMerge(DummyVersionServiceLayer),
   Layer.provideMerge(DummyJiraAuthLayer),
@@ -157,6 +168,12 @@ export const getLayerType = (args: ReadonlyArray<string>): "full" | "auth" | "mi
   if (cmd === "auth") {
     return "auth"
   }
+  if (
+    cmd === "issue" && args[1] === "attachment" && args[2] === "upload" &&
+    (args.includes("--dry-run") || args.includes("-n"))
+  ) {
+    return "minimal"
+  }
   if (!cmd || cmd === "skills" || cmd === "--help" || cmd === "-h" || cmd === "--version") {
     return "minimal"
   }

package/src/commands/search.ts

@@ -38,7 +38,7 @@ const outputDirOption = Options.directory("output-dir").pipe(
 const formatOption = Options.choice("format", ["multi", "single"]).pipe(
   Options.withAlias("f"),
   Options.withDescription("Output format: multi (one file per issue) or single (combined file)"),
-  Options.withDefault("multi" as const)
+  Options.withDefault("multi")
 )
 
 const maxResultsOption = Options.integer("max-results").pipe(

package/src/index.ts

@@ -4,6 +4,12 @@
  * @module
  */
 
+export {
+  AttachmentService,
+  type AttachmentServiceShape,
+  layer as AttachmentServiceLayer,
+  type UploadAttachmentInput
+} from "./AttachmentService.js"
 export {
   type Attachment,
   type Comment,

package/src/internal/attachmentInsertion.ts

@@ -0,0 +1,44 @@
+/**
+ * Local Attachment Insertion helpers for Jira Markdown files.
+ *
+ * @internal
+ */
+import { renderAttachmentMarkdown, replaceAttachmentPlaceholder } from "@knpkv/atlassian-common/attachments"
+import type { Attachment } from "../IssueService.js"
+
+export interface InsertAttachmentResult {
+  readonly content: string
+  readonly replacements: number
+}
+
+export const renderJiraAttachmentReference = (
+  attachment: Attachment,
+  options?: { readonly label?: string | null | undefined }
+): string =>
+  renderAttachmentMarkdown({
+    id: attachment.id,
+    filename: attachment.filename,
+    url: attachment.url,
+    mediaType: attachment.mediaType,
+    size: attachment.size
+  }, {
+    label: options?.label,
+    metadata: `<!-- jiraAttachment: ${
+      JSON.stringify({
+        jiraAttachmentId: attachment.id,
+        mediaType: attachment.mediaType,
+        size: attachment.size
+      })
+    } -->`
+  })
+
+export const insertJiraAttachmentReference = (
+  content: string,
+  placeholderPath: string,
+  attachment: Attachment
+): InsertAttachmentResult =>
+  replaceAttachmentPlaceholder(
+    content,
+    placeholderPath,
+    ({ label }) => renderJiraAttachmentReference(attachment, { label })
+  )

package/src/internal/frontmatter.ts

@@ -8,6 +8,7 @@
  *
  * @internal
  */
+import { isPreviewableAttachment } from "@knpkv/atlassian-common/attachments"
 import matter from "gray-matter"
 import * as yaml from "js-yaml"
 import type { Issue } from "../IssueService.js"
@@ -21,7 +22,10 @@ import type { Issue } from "../IssueService.js"
  * @internal
  */
 const yamlEngine = {
-  parse: (str: string): object => (yaml.load(str) as object) ?? {},
+  parse: (str: string): object => {
+    const parsed = yaml.load(str)
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+  },
   stringify: (data: object): string => yaml.dump(data)
 }
 
@@ -114,9 +118,19 @@ export const buildMarkdownContent = (issue: Issue): string => {
     parts.push("## Attachments")
     parts.push("")
     for (const attachment of issue.attachments) {
-      parts.push(`- [${attachment.filename}](${attachment.url})`)
+      const reference = isPreviewableAttachment(attachment)
+        ? `![${attachment.filename}](${attachment.url})`
+        : `[${attachment.filename}](${attachment.url})`
+      parts.push(`<!-- jiraAttachment: ${
+        JSON.stringify({
+          jiraAttachmentId: attachment.id,
+          mediaType: attachment.mediaType,
+          size: attachment.size
+        })
+      } -->`)
+      parts.push(reference)
+      parts.push("")
     }
-    parts.push("")
   }
 
   // Comments

package/src/internal/sync/baseline.ts

@@ -15,13 +15,13 @@ export const parseSyncBaseline = (
 ): Effect.Effect<SyncBaseline, SyncWorkspaceError | SyncValidationError> =>
   Effect.gen(function*() {
     const raw = yield* Effect.try({
-      try: () => JSON.parse(content) as unknown,
+      try: (): unknown => JSON.parse(content),
       catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse Sync Baseline JSON", path, cause })
     })
-    return yield* Schema.decodeUnknownEffect(SyncBaselineSchema)(raw).pipe(
-      Effect.map((baseline) => baseline as SyncBaseline),
+    const baseline: SyncBaseline = yield* Schema.decodeUnknownEffect(SyncBaselineSchema)(raw).pipe(
       Effect.mapError((cause) => new SyncValidationError({ message: "Invalid Sync Baseline", path, cause }))
     )
+    return baseline
   })
 
 export const serializeSyncBaseline = (baseline: SyncBaseline): string => `${JSON.stringify(baseline, null, 2)}\n`

package/src/internal/sync/changes.ts

@@ -47,7 +47,7 @@ export const compareIssueFields = (input: CompareIssueFieldsInput): CompareIssue
   ])
 
   for (const name of customFieldNames) {
-    const field = `customFields.${name}` as const
+    const field: SyncFieldPath = `customFields.${name}`
     const baseline = input.baseline.customFields[name]?.value
     const jira = input.jira.customFields[name]?.value
     const document = input.document.customFields[name]?.value

package/src/internal/sync/config.ts

@@ -19,8 +19,7 @@ export const parseWorkspaceConfig = (
       try: () => yaml.load(content) ?? {},
       catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse workspace config YAML", path, cause })
     })
-    const config = yield* Schema.decodeUnknownEffect(WorkspaceConfigSchema)(raw).pipe(
-      Effect.map((config) => config as WorkspaceConfig),
+    const config: WorkspaceConfig = yield* Schema.decodeUnknownEffect(WorkspaceConfigSchema)(raw).pipe(
       Effect.mapError((cause) =>
         new SyncValidationError({ message: "Invalid Jira Markdown Sync workspace config", path, cause })
       )

package/src/internal/sync/document.ts

@@ -3,6 +3,7 @@
  *
  * @internal
  */
+import { isPreviewableAttachment } from "@knpkv/atlassian-common/attachments"
 import matter from "gray-matter"
 import * as yaml from "js-yaml"
 import { SyncValidationError } from "../../JiraCliError.js"
@@ -11,11 +12,25 @@ import type {
   AttachmentReference,
   CommentDraft,
   IssueDocument,
-  IssueDocumentFrontMatter
+  IssueDocumentFrontMatter,
+  UserFieldValue
 } from "./types.js"
 
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const isStringArray = (value: unknown): value is ReadonlyArray<string> =>
+  Array.isArray(value) && value.every((item) => typeof item === "string")
+
+const isFrontMatterCustomFields = (
+  value: unknown
+): value is IssueDocumentFrontMatter["customFields"] => isRecord(value)
+
 const yamlEngine = {
-  parse: (str: string): object => (yaml.load(str) as object) ?? {},
+  parse: (str: string): object => {
+    const value = yaml.load(str)
+    return isRecord(value) ? value : {}
+  },
   stringify: (data: object): string => yaml.dump(data)
 }
 
@@ -78,40 +93,41 @@ const section = (name: string, content: string): string => {
 const parseFrontMatter = (path: string, data: Record<string, unknown>): IssueDocumentFrontMatter => {
   const requiredString = (key: string): string => {
     const value = data[key]
-    if (typeof value !== "string") fail(path, `Missing or invalid front matter field "${key}"`)
-    return value as string
+    if (typeof value === "string") return value
+    return fail(path, `Missing or invalid front matter field "${key}"`)
   }
 
   const nullableString = (key: string): string | null => {
     const value = data[key]
     if (value === null || value === undefined) return null
-    if (typeof value !== "string") fail(path, `Invalid front matter field "${key}"`)
-    return value as string
+    if (typeof value === "string") return value
+    return fail(path, `Invalid front matter field "${key}"`)
   }
 
-  const userValue = (key: string) => {
+  const userValue = (key: string): UserFieldValue | null => {
     const value = data[key]
     if (value === null || value === undefined) return null
-    if (typeof value !== "object") fail(path, `Invalid user field "${key}"`)
-    const record = value as Record<string, unknown>
-    if (typeof record["accountId"] !== "string" || typeof record["displayName"] !== "string") {
-      fail(path, `Invalid user field "${key}"`)
-    }
-    return {
-      accountId: record["accountId"] as string,
-      displayName: record["displayName"] as string
+    const record = isRecord(value) ? value : fail(path, `Invalid user field "${key}"`)
+    const accountId = record["accountId"]
+    const displayName = record["displayName"]
+    if (typeof accountId === "string" && typeof displayName === "string") {
+      return {
+        accountId,
+        displayName
+      }
     }
+    return fail(path, `Invalid user field "${key}"`)
   }
 
   const labels = data["labels"]
-  if (!Array.isArray(labels) || labels.some((label) => typeof label !== "string")) {
-    fail(path, `Missing or invalid front matter field "labels"`)
-  }
+  const parsedLabels = isStringArray(labels)
+    ? labels
+    : fail(path, `Missing or invalid front matter field "labels"`)
 
   const customFields = data["customFields"]
-  if (customFields === null || typeof customFields !== "object" || Array.isArray(customFields)) {
-    fail(path, `Missing or invalid front matter field "customFields"`)
-  }
+  const parsedCustomFields = isFrontMatterCustomFields(customFields)
+    ? customFields
+    : fail(path, `Missing or invalid front matter field "customFields"`)
 
   return {
     issueId: requiredString("issueId"),
@@ -122,8 +138,8 @@ const parseFrontMatter = (path: string, data: Record<string, unknown>): IssueDoc
     priority: nullableString("priority"),
     assignee: userValue("assignee"),
     reporter: userValue("reporter"),
-    labels: labels as ReadonlyArray<string>,
-    customFields: customFields as IssueDocumentFrontMatter["customFields"]
+    labels: parsedLabels,
+    customFields: parsedCustomFields
   }
 }
 
@@ -180,13 +196,68 @@ const parseAcceptedComments = (content: string): ReadonlyArray<AcceptedComment>
 }
 
 const serializeAttachments = (attachments: ReadonlyArray<AttachmentReference>): string =>
-  attachments.map((attachment) => `- [${attachment.filename}](${attachment.url})`).join("\n")
+  attachments.map((attachment) => {
+    const metadata = {
+      jiraAttachmentId: attachment.id,
+      mediaType: attachment.mediaType,
+      size: attachment.size
+    }
+    const reference = isPreviewableAttachment(attachment)
+      ? `![${attachment.filename}](${attachment.url})`
+      : `[${attachment.filename}](${attachment.url})`
+    return `<!-- jiraAttachment: ${JSON.stringify(metadata)} -->\n${reference}`
+  }).join("\n\n")
 
-const parseAttachments = (content: string): ReadonlyArray<AttachmentReference> =>
-  content.split(/\r?\n/).flatMap((line) => {
-    const match = /^- \[(.+)]\((.+)\)$/.exec(line.trim())
-    return match?.[1] && match[2] ? [{ filename: match[1], url: match[2] }] : []
-  })
+const parseAttachments = (content: string): ReadonlyArray<AttachmentReference> => {
+  const lines = content.split(/\r?\n/)
+  const attachments: Array<AttachmentReference> = []
+  let pendingMetadata: Partial<Pick<AttachmentReference, "id" | "mediaType" | "size">> = {}
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim()
+    if (line.length === 0) continue
+
+    const metadataMatch = /^<!--\s*jiraAttachment:\s*(\{.*})\s*-->$/.exec(line)
+    if (metadataMatch?.[1]) {
+      pendingMetadata = parseAttachmentMetadata(metadataMatch[1])
+      continue
+    }
+
+    const markdownMatch = /^(?:-\s*)?!?\[(.+)]\((.+)\)$/.exec(line)
+    if (markdownMatch?.[1] && markdownMatch[2]) {
+      attachments.push({
+        id: pendingMetadata.id ?? "",
+        filename: markdownMatch[1],
+        url: markdownMatch[2],
+        mediaType: pendingMetadata.mediaType ?? null,
+        size: pendingMetadata.size ?? null
+      })
+      pendingMetadata = {}
+    }
+  }
+
+  return attachments
+}
+
+const parseAttachmentMetadata = (
+  raw: string
+): Partial<Pick<AttachmentReference, "id" | "mediaType" | "size">> => {
+  try {
+    const parsed = JSON.parse(raw)
+    if (!isRecord(parsed)) return {}
+    return {
+      id: typeof parsed["jiraAttachmentId"] === "string"
+        ? parsed["jiraAttachmentId"]
+        : typeof parsed["id"] === "string"
+        ? parsed["id"]
+        : "",
+      mediaType: typeof parsed["mediaType"] === "string" ? parsed["mediaType"] : null,
+      size: typeof parsed["size"] === "number" ? parsed["size"] : null
+    }
+  } catch {
+    return {}
+  }
+}
 
 const trimOuterBlankLines = (lines: ReadonlyArray<string>): ReadonlyArray<string> => {
   let start = 0

package/src/internal/sync/manifest.ts

@@ -21,7 +21,7 @@ export const parseSyncManifest = (
 ): Effect.Effect<SyncManifest, SyncWorkspaceError | SyncValidationError> =>
   Effect.gen(function*() {
     const raw = yield* Effect.try({
-      try: () => JSON.parse(content) as unknown,
+      try: (): unknown => JSON.parse(content),
       catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse Sync Manifest JSON", path, cause })
     })
     return yield* Schema.decodeUnknownEffect(SyncManifestSchema)(raw).pipe(

package/src/internal/sync/schemas.ts

@@ -12,6 +12,7 @@ const SiteUrl = Schema.String.pipe(
 )
 
 const NonEmptyString = Schema.String.pipe(Schema.check(Schema.isMinLength(1)))
+const FilenameModes: readonly ["convention", "custom"] = ["convention", "custom"]
 
 export const FieldShapeSchema = Schema.Literals(FIELD_SHAPES)
 
@@ -23,7 +24,7 @@ export const RequestedCustomFieldSchema = Schema.Struct({
 })
 
 export const WorkspaceConfigSchema = Schema.Struct({
-  version: Schema.Literal(1).pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(1 as const))),
+  version: Schema.Literal(1).pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(1))),
   siteUrl: SiteUrl,
   documentsDir: NonEmptyString.pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed("issues"))),
   customFields: Schema.Array(RequestedCustomFieldSchema).pipe(
@@ -35,7 +36,7 @@ export const ManifestIssueSchema = Schema.Struct({
   issueId: NonEmptyString,
   issueKey: NonEmptyString,
   documentPath: NonEmptyString,
-  filenameMode: Schema.Literals(["convention", "custom"] as const)
+  filenameMode: Schema.Literals(FilenameModes)
 })
 
 export const SyncManifestSchema = Schema.Struct({

package/src/internal/sync/types.ts

@@ -4,7 +4,18 @@
  * @internal
  */
 
-export const FIELD_SHAPES = [
+export type FieldShape =
+  | "text"
+  | "multilineText"
+  | "number"
+  | "boolean"
+  | "date"
+  | "singleSelect"
+  | "multiSelect"
+  | "user"
+  | "cascadingSelect"
+
+export const FIELD_SHAPES: ReadonlyArray<FieldShape> = [
   "text",
   "multilineText",
   "number",
@@ -14,9 +25,7 @@ export const FIELD_SHAPES = [
   "multiSelect",
   "user",
   "cascadingSelect"
-] as const
-
-export type FieldShape = typeof FIELD_SHAPES[number]
+]
 
 export interface RequestedCustomField {
   readonly displayName: string
@@ -123,8 +132,11 @@ export interface AcceptedComment {
 }
 
 export interface AttachmentReference {
+  readonly id: string
   readonly filename: string
   readonly url: string
+  readonly mediaType: string | null
+  readonly size: number | null
 }
 
 export interface IssueDocument {