@peanut-admin/admin 0.1.0-alpha.2

package/file-media/src/FileAssetSelector.vue

@@ -0,0 +1,117 @@
+<script setup lang="ts">
+import { EmptyState } from '@peanut-admin/admin/shell'
+import { ElButton } from 'element-plus'
+import type { AssetCandidate } from './contracts'
+
+withDefaults(defineProps<{
+  items: readonly AssetCandidate[]
+  selectedFileKey?: string | null
+  loading?: boolean
+  error?: string | null
+  disabled?: boolean
+}>(), {
+  selectedFileKey: null,
+  loading: false,
+  error: null,
+  disabled: false,
+})
+
+const emit = defineEmits<{
+  select: [asset: AssetCandidate]
+  retry: []
+}>()
+</script>
+
+<template>
+  <section
+    class="asset-selector"
+    aria-labelledby="asset-selector-title"
+  >
+    <header class="asset-selector__header">
+      <h2 id="asset-selector-title">
+        Media assets
+      </h2>
+      <ElButton
+        :loading="loading"
+        :disabled="disabled"
+        @click="emit('retry')"
+      >
+        Reload
+      </ElButton>
+    </header>
+    <div
+      v-if="error"
+      class="asset-selector__error"
+      role="alert"
+    >
+      <p>{{ error }}</p>
+    </div>
+    <div
+      v-else-if="loading"
+      role="status"
+      class="asset-selector__status"
+    >
+      Loading media assets...
+    </div>
+    <EmptyState
+      v-else-if="items.length === 0"
+      title="No media assets"
+      message="Upload an image before selecting an asset."
+    />
+    <ul
+      v-else
+      class="asset-selector__grid"
+      aria-label="Available media assets"
+    >
+      <li
+        v-for="asset in items"
+        :key="asset.fileKey"
+        class="asset-selector__item"
+      >
+        <button
+          type="button"
+          class="asset-selector__choice"
+          :class="{ 'is-selected': selectedFileKey === asset.fileKey }"
+          :aria-pressed="selectedFileKey === asset.fileKey"
+          :disabled="disabled"
+          @click="emit('select', asset)"
+        >
+          <img
+            v-if="asset.previewUri"
+            :src="asset.previewUri"
+            :alt="asset.originalName"
+            class="asset-selector__preview"
+            loading="lazy"
+            decoding="async"
+            referrerpolicy="no-referrer"
+          >
+          <span
+            v-else
+            class="asset-selector__placeholder"
+            aria-hidden="true"
+          >IMG</span>
+          <span class="asset-selector__name">{{ asset.originalName }}</span>
+          <span class="asset-selector__meta">{{ asset.width }} x {{ asset.height }}</span>
+        </button>
+      </li>
+    </ul>
+  </section>
+</template>
+
+<style scoped>
+.asset-selector { min-width: 0; }
+.asset-selector__header { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin-bottom: 12px; }
+.asset-selector__header h2 { margin: 0; font-size: 16px; letter-spacing: 0; }
+.asset-selector__status, .asset-selector__error { padding: 16px 0; }
+.asset-selector__error { color: var(--el-color-danger); }
+.asset-selector__grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(144px, 1fr)); gap: 12px; padding: 0; margin: 0; list-style: none; }
+.asset-selector__item { min-width: 0; }
+.asset-selector__choice { width: 100%; padding: 8px; border: 1px solid var(--el-border-color); background: var(--el-bg-color); color: inherit; text-align: left; cursor: pointer; }
+.asset-selector__choice.is-selected { border-color: var(--el-color-primary); box-shadow: 0 0 0 1px var(--el-color-primary) inset; }
+.asset-selector__choice:disabled { cursor: not-allowed; opacity: .65; }
+.asset-selector__preview, .asset-selector__placeholder { display: flex; width: 100%; aspect-ratio: 1; object-fit: cover; align-items: center; justify-content: center; background: var(--el-fill-color-light); }
+.asset-selector__placeholder { color: var(--el-text-color-secondary); font-size: 13px; }
+.asset-selector__name, .asset-selector__meta { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.asset-selector__name { margin-top: 8px; font-weight: 600; }
+.asset-selector__meta { margin-top: 2px; color: var(--el-text-color-secondary); font-size: 12px; }
+</style>

package/file-media/src/FileMediaPage.vue

@@ -0,0 +1,158 @@
+<script setup lang="ts">
+import { EmptyState, ForbiddenState, ModuleUnavailableState, PageContent, PageHeader, PageToolbar, SessionExpiredState } from '@peanut-admin/admin/shell'
+import { ElButton } from 'element-plus'
+import { computed, onMounted, ref } from 'vue'
+import FileAssetSelector from './FileAssetSelector.vue'
+import { useFileMediaRuntime } from './runtime'
+
+const runtime = useFileMediaRuntime()
+const state = runtime.state
+const input = ref<HTMLInputElement | null>(null)
+const canCreate = computed(runtime.canCreate)
+const canDelete = computed(runtime.canDelete)
+const selectedAssetKey = ref<string | null>(null)
+
+const upload = async (event: Event): Promise<void> => {
+  const target = event.currentTarget
+  if (!(target instanceof HTMLInputElement) || target.files?.length !== 1) return
+  const file = target.files.item(0)
+  if (file !== null) await runtime.upload(file)
+  target.value = ''
+}
+
+onMounted(() => Promise.all([runtime.load(), runtime.loadAssets()]))
+</script>
+
+<template>
+  <PageContent class="file-media-page">
+    <PageHeader>
+      Files
+      <template #actions>
+        <input
+          ref="input"
+          class="file-input"
+          type="file"
+          aria-label="Choose private file"
+          @change="upload"
+        >
+        <ElButton
+          :disabled="!canCreate || state.mutating"
+          type="primary"
+          @click="input?.click()"
+        >
+          Upload
+        </ElButton>
+        <ElButton
+          :loading="state.loading"
+          :disabled="state.mutating"
+          @click="runtime.load"
+        >
+          Reload
+        </ElButton>
+      </template>
+    </PageHeader>
+    <PageToolbar label="File status">
+      <ElButton
+        :type="state.status === 'ready' ? 'primary' : 'default'"
+        @click="runtime.setStatus('ready')"
+      >
+        Ready
+      </ElButton>
+      <ElButton
+        :type="state.status === 'archived' ? 'primary' : 'default'"
+        @click="runtime.setStatus('archived')"
+      >
+        Archived
+      </ElButton>
+    </PageToolbar>
+
+    <FileAssetSelector
+      :items="state.assets"
+      :selected-file-key="selectedAssetKey"
+      :loading="state.assetsLoading"
+      :error="state.assetsError?.message ?? null"
+      :disabled="state.mutating"
+      @select="selectedAssetKey = $event.fileKey"
+      @retry="runtime.loadAssets"
+    />
+
+    <SessionExpiredState
+      v-if="state.error?.status === 401"
+      :message="state.error.message"
+    />
+    <ForbiddenState
+      v-else-if="state.error?.status === 403"
+      :message="state.error.message"
+    />
+    <ModuleUnavailableState
+      v-else-if="state.error?.status === 503"
+      :message="state.error.message"
+      @action="runtime.load"
+    />
+    <section
+      v-else-if="state.error"
+      role="alert"
+      class="file-state"
+    >
+      <h2>Unable to complete the file request</h2>
+      <p>{{ state.error.message }}</p>
+      <p v-if="state.error.requestId">
+        Request ID: {{ state.error.requestId }}
+      </p>
+    </section>
+    <div
+      v-else-if="state.loading"
+      class="file-state"
+      role="status"
+    >
+      Loading files...
+    </div>
+    <EmptyState
+      v-else-if="state.items.length === 0"
+      title="No files"
+      message="No private files match this status."
+    />
+    <div
+      v-else
+      class="file-table-wrap"
+    >
+      <table class="file-table">
+        <thead><tr><th>Name</th><th>Type</th><th>Size</th><th>Status</th><th>Revision</th><th>Actions</th></tr></thead>
+        <tbody>
+          <tr
+            v-for="file in state.items"
+            :key="file.fileKey"
+          >
+            <td>{{ file.originalName }}</td><td>{{ file.mediaType }}</td><td>{{ file.sizeBytes }}</td>
+            <td>{{ file.status }}</td><td>{{ file.revision }}</td>
+            <td>
+              <ElButton
+                v-if="file.status === 'ready'"
+                text
+                @click="runtime.download(file)"
+              >
+                Download
+              </ElButton>
+              <ElButton
+                v-if="file.status === 'ready'"
+                text
+                :disabled="!canDelete || state.mutating"
+                @click="runtime.archive(file)"
+              >
+                Archive
+              </ElButton>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  </PageContent>
+</template>
+
+<style scoped>
+.file-input { display: none; }
+.file-state { padding: 24px 0; }
+.file-table-wrap { overflow-x: auto; }
+.file-table { width: 100%; border-collapse: collapse; }
+.file-table th, .file-table td { padding: 10px 8px; border-bottom: 1px solid var(--el-border-color); text-align: left; }
+</style>

package/file-media/src/contracts.ts

@@ -0,0 +1,220 @@
+export type FileStatus = 'ready' | 'archived'
+
+export interface FileObject {
+  readonly fileKey: string
+  readonly originalName: string
+  readonly mediaType: string
+  readonly sizeBytes: number
+  readonly sha256: string
+  readonly status: FileStatus
+  readonly revision: number
+  readonly createdAt: string
+  readonly updatedAt: string
+  readonly archivedAt: string | null
+}
+
+export interface FileList {
+  readonly items: readonly FileObject[]
+  readonly page: number
+  readonly pageSize: number
+  readonly total: number
+}
+
+export interface FileTransportResult {
+  readonly body: unknown
+  readonly headers: Headers
+  readonly status: number
+}
+
+export interface FileMediaTransport {
+  list: (status: FileStatus, page: number, pageSize: number, signal: AbortSignal) => Promise<FileTransportResult>
+  assets: (page: number, pageSize: number, signal: AbortSignal) => Promise<FileTransportResult>
+  upload: (file: File, signal: AbortSignal) => Promise<FileTransportResult>
+  download: (fileKey: string, signal: AbortSignal) => Promise<Response>
+  archive: (fileKey: string, etag: string, signal: AbortSignal) => Promise<FileTransportResult>
+}
+
+export interface ImageVariant {
+  readonly variantKey: string
+  readonly width: number
+  readonly height: number
+  readonly mediaType: 'image/jpeg' | 'image/png'
+  readonly deliveryUri: string | null
+}
+
+export interface AssetCandidate {
+  readonly fileKey: string
+  readonly originalName: string
+  readonly mediaType: 'image/jpeg' | 'image/png'
+  readonly width: number
+  readonly height: number
+  readonly previewUri: string | null
+  readonly variants: readonly ImageVariant[]
+}
+
+export interface AssetList {
+  readonly items: readonly AssetCandidate[]
+  readonly page: number
+  readonly pageSize: number
+  readonly total: number
+}
+
+const fileKeyPattern = /^file_[0-9a-f]{32}$/
+const shaPattern = /^[0-9a-f]{64}$/
+
+const record = (value: unknown): Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  return value as Record<string, unknown>
+}
+
+const exactKeys = (value: Record<string, unknown>, keys: readonly string[]): void => {
+  const actual = Object.keys(value).sort()
+  const expected = [...keys].sort()
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  }
+}
+
+const deliveryUri = (value: unknown): string | null => {
+  if (value === null) return null
+  if (typeof value !== 'string' || value === '' || value.length > 2048 || value.includes('#')) {
+    throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  }
+  if (value.startsWith('/')) {
+    if (value.startsWith('//') || !value.startsWith('/api/')) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+    return value
+  }
+  let parsed: URL
+  try { parsed = new URL(value) } catch { throw new Error('FILE_MEDIA_RESPONSE_INVALID') }
+  if (parsed.protocol !== 'https:' || parsed.username !== '' || parsed.password !== '') {
+    throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  }
+  return value
+}
+
+export const parseFileObject = (value: unknown): FileObject => {
+  const item = record(value)
+  exactKeys(item, [
+    'file_key', 'original_name', 'media_type', 'size_bytes', 'sha256', 'status',
+    'revision', 'created_at', 'updated_at', 'archived_at',
+  ])
+  if (
+    typeof item.file_key !== 'string' || !fileKeyPattern.test(item.file_key)
+    || typeof item.original_name !== 'string' || item.original_name === '' || [...item.original_name].length > 255
+    || typeof item.media_type !== 'string' || item.media_type === '' || item.media_type.length > 127
+    || typeof item.size_bytes !== 'number' || !Number.isSafeInteger(item.size_bytes) || item.size_bytes < 1
+    || typeof item.sha256 !== 'string' || !shaPattern.test(item.sha256)
+    || (item.status !== 'ready' && item.status !== 'archived')
+    || typeof item.revision !== 'number' || !Number.isSafeInteger(item.revision) || item.revision < 1
+    || typeof item.created_at !== 'string' || !Number.isFinite(Date.parse(item.created_at))
+    || typeof item.updated_at !== 'string' || !Number.isFinite(Date.parse(item.updated_at))
+    || (item.archived_at !== null && (typeof item.archived_at !== 'string' || !Number.isFinite(Date.parse(item.archived_at))))
+    || (item.status === 'ready') !== (item.archived_at === null)
+  ) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+
+  return {
+    fileKey: item.file_key,
+    originalName: item.original_name,
+    mediaType: item.media_type,
+    sizeBytes: item.size_bytes,
+    sha256: item.sha256,
+    status: item.status,
+    revision: item.revision,
+    createdAt: item.created_at,
+    updatedAt: item.updated_at,
+    archivedAt: item.archived_at,
+  }
+}
+
+export const parseFileResponse = (value: unknown): FileObject => {
+  const body = record(value)
+  exactKeys(body, ['data', 'meta'])
+  record(body.meta)
+  return parseFileObject(body.data)
+}
+
+export const parseFileList = (value: unknown): FileList => {
+  const body = record(value)
+  exactKeys(body, ['data', 'meta'])
+  const data = record(body.data)
+  exactKeys(data, ['items'])
+  const meta = record(body.meta)
+  if (!Array.isArray(data.items)) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  for (const key of ['page', 'page_size', 'total'] as const) {
+    if (typeof meta[key] !== 'number' || !Number.isSafeInteger(meta[key]) || meta[key] < (key === 'total' ? 0 : 1)) {
+      throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+    }
+  }
+  return {
+    items: data.items.map(parseFileObject),
+    page: meta.page as number,
+    pageSize: meta.page_size as number,
+    total: meta.total as number,
+  }
+}
+
+export const parseAssetCandidate = (value: unknown): AssetCandidate => {
+  const item = record(value)
+  exactKeys(item, ['file_key', 'original_name', 'media_type', 'width', 'height', 'preview_uri', 'variants'])
+  if (
+    typeof item.file_key !== 'string' || !fileKeyPattern.test(item.file_key)
+    || typeof item.original_name !== 'string' || item.original_name === '' || [...item.original_name].length > 255
+    || (item.media_type !== 'image/jpeg' && item.media_type !== 'image/png')
+    || typeof item.width !== 'number' || !Number.isSafeInteger(item.width) || item.width < 1 || item.width > 50000
+    || typeof item.height !== 'number' || !Number.isSafeInteger(item.height) || item.height < 1 || item.height > 50000
+    || item.width * item.height > 100_000_000
+    || !Array.isArray(item.variants) || item.variants.length > 16
+  ) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  const keys = new Set<string>()
+  const variants = item.variants.map((value): ImageVariant => {
+    const variant = record(value)
+    exactKeys(variant, ['variant_key', 'width', 'height', 'media_type', 'delivery_uri'])
+    if (
+      typeof variant.variant_key !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(variant.variant_key)
+      || keys.has(variant.variant_key)
+      || typeof variant.width !== 'number' || !Number.isSafeInteger(variant.width) || variant.width < 1 || variant.width > 4096
+      || typeof variant.height !== 'number' || !Number.isSafeInteger(variant.height) || variant.height < 1 || variant.height > 4096
+      || (variant.media_type !== 'image/jpeg' && variant.media_type !== 'image/png')
+    ) throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+    keys.add(variant.variant_key)
+    return {
+      variantKey: variant.variant_key,
+      width: variant.width,
+      height: variant.height,
+      mediaType: variant.media_type,
+      deliveryUri: deliveryUri(variant.delivery_uri),
+    }
+  })
+  return {
+    fileKey: item.file_key,
+    originalName: item.original_name,
+    mediaType: item.media_type,
+    width: item.width,
+    height: item.height,
+    previewUri: deliveryUri(item.preview_uri),
+    variants,
+  }
+}
+
+export const parseAssetList = (value: unknown): AssetList => {
+  const body = record(value)
+  exactKeys(body, ['data', 'meta'])
+  const data = record(body.data)
+  const meta = record(body.meta)
+  exactKeys(data, ['items'])
+  exactKeys(meta, ['request_id', 'page', 'page_size', 'total'])
+  if (!Array.isArray(data.items) || typeof meta.request_id !== 'string' || meta.request_id === '') {
+    throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+  }
+  for (const key of ['page', 'page_size', 'total'] as const) {
+    if (typeof meta[key] !== 'number' || !Number.isSafeInteger(meta[key]) || meta[key] < (key === 'total' ? 0 : 1)) {
+      throw new Error('FILE_MEDIA_RESPONSE_INVALID')
+    }
+  }
+  return {
+    items: data.items.map(parseAssetCandidate),
+    page: meta.page as number,
+    pageSize: meta.page_size as number,
+    total: meta.total as number,
+  }
+}

package/file-media/src/index.ts

@@ -0,0 +1,19 @@
+export const FILE_MEDIA_PACKAGE = '@peanut-admin/admin/file-media' as const
+export const FILE_MEDIA_VERSION = '0.1.0' as const
+export { default as FileAssetSelector } from './FileAssetSelector.vue'
+export { parseAssetCandidate, parseFileList, parseFileObject, parseFileResponse } from './contracts'
+export type { AssetCandidate, AssetList, FileList, FileMediaTransport, FileObject, FileStatus, FileTransportResult, ImageVariant } from './contracts'
+export {
+  createFileMediaModuleContribution,
+  createFileMediaRuntime,
+  FILE_MEDIA_CREATE_PERMISSION,
+  FILE_MEDIA_DELETE_PERMISSION,
+  FILE_MEDIA_MODULE_KEY,
+  FILE_MEDIA_READ_PERMISSION,
+  FILE_MEDIA_ROUTE_NAME,
+  FILE_MEDIA_ROUTE_PATH,
+  FILE_MEDIA_STORE_KEY,
+  fileMediaRuntimeKey,
+  useFileMediaRuntime,
+} from './runtime'
+export type { FileMediaError, FileMediaRuntime, FileMediaRuntimeOptions, FileMediaState } from './runtime'