@peanut-admin/admin 0.1.0-alpha.11

package/client-core/src/index.ts

@@ -0,0 +1,415 @@
+export type ClientRequestMethod =
+  | 'DELETE'
+  | 'GET'
+  | 'HEAD'
+  | 'OPTIONS'
+  | 'PATCH'
+  | 'POST'
+  | 'PUT'
+
+export interface ClientHeaderSource {
+  forEach: (callback: (value: string, key: string) => void) => void
+}
+
+export type ClientRequestHeaders =
+  | Readonly<Record<string, string>>
+  | ReadonlyArray<readonly [string, string]>
+  | ClientHeaderSource
+
+export interface ClientHeaders extends ClientHeaderSource {
+  delete: (name: string) => void
+  get: (name: string) => string | null
+  has: (name: string) => boolean
+  set: (name: string, value: string) => void
+}
+
+export interface ClientRequest<TData = unknown> {
+  readonly path: string
+  readonly method?: ClientRequestMethod
+  readonly data?: TData
+  readonly headers?: ClientRequestHeaders
+  readonly auth?: boolean
+}
+
+export interface ClientTransportRequest<TData = unknown> {
+  readonly path: string
+  readonly method: ClientRequestMethod
+  readonly data?: TData
+  readonly headers: ClientHeaders
+}
+
+export type ClientTransport = (request: ClientTransportRequest) => Promise<unknown>
+
+export interface ClientSession {
+  accessToken: () => string | null | undefined
+  clear: () => void | Promise<void>
+}
+
+export interface ClientDecodeSuccess<TData = unknown> {
+  readonly kind: 'success'
+  readonly data: TData
+}
+
+export interface ClientDecodeUnauthorized {
+  readonly kind: 'unauthorized'
+  readonly code?: string
+  readonly message?: string
+}
+
+export interface ClientDecodeBusiness {
+  readonly kind: 'business'
+  readonly code?: string
+  readonly message?: string
+}
+
+export type ClientDecodeResult<TData = unknown> =
+  | ClientDecodeSuccess<TData>
+  | ClientDecodeUnauthorized
+  | ClientDecodeBusiness
+
+export type ClientDecoder<TData = unknown> = (
+  response: unknown,
+  request: ClientTransportRequest,
+) => ClientDecodeResult<TData> | Promise<ClientDecodeResult<TData>>
+
+export type ClientRequestErrorKind =
+  | 'business'
+  | 'decoder'
+  | 'path'
+  | 'session'
+  | 'transport'
+  | 'unauthorized'
+
+export class ClientRequestError extends Error {
+  readonly kind: ClientRequestErrorKind
+  readonly code: string
+
+  constructor(kind: ClientRequestErrorKind, code: string, message: string) {
+    super(message)
+    this.name = 'ClientRequestError'
+    this.kind = kind
+    this.code = code
+  }
+}
+
+export interface ClientHooks {
+  readonly unauthorized?: (error: ClientRequestError) => void | Promise<void>
+  readonly businessError?: (error: ClientRequestError) => void | Promise<void>
+}
+
+export interface ClientOptions {
+  readonly transport: ClientTransport
+  readonly session: ClientSession
+  readonly decoder: ClientDecoder
+  readonly hooks?: ClientHooks
+}
+
+export interface Client {
+  request: <TData = unknown>(request: ClientRequest) => Promise<TData>
+}
+
+const pathControlCharacters = /[\u0000-\u001f\u007f]/
+const controlCharacters = /[\u0000-\u001f\u007f]/g
+const encodedUnsafePathSegment = /%(?:2e|2f|5c)/i
+const absolutePath = /^[A-Za-z][A-Za-z0-9+.-]*:/
+const httpBaseUrl = /^(https?):\/\/([^/?#]+)(\/[^?#]*)?$/i
+const validHeaderName = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/
+const invalidHeaderValue = /[\u0000\r\n]/
+const safeCode = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/
+const defaultUnauthorizedCode = 'CLIENT_UNAUTHORIZED'
+const defaultBusinessCode = 'CLIENT_BUSINESS_ERROR'
+const genericUnauthorizedMessage = 'Authentication is required.'
+const genericBusinessMessage = 'The request was rejected.'
+
+const invalidPath = (): ClientRequestError => (
+  new ClientRequestError('path', 'CLIENT_PATH_INVALID', 'The request path is invalid.')
+)
+
+const isRecord = (value: unknown): value is Record<string, unknown> => (
+  typeof value === 'object' && value !== null
+)
+
+const assertClientPath = (path: string): void => {
+  if (
+    typeof path !== 'string'
+    || path === ''
+    || path.trim() !== path
+    || path.startsWith('//')
+    || absolutePath.test(path)
+    || path.includes('\\')
+    || pathControlCharacters.test(path)
+    || encodedUnsafePathSegment.test(path)
+  ) {
+    throw invalidPath()
+  }
+
+  const pathname = path.split(/[?#]/u, 1)[0] ?? ''
+  if (pathname === '' || pathname.split('/').some(segment => segment === '.' || segment === '..')) {
+    throw invalidPath()
+  }
+}
+
+const invalidBaseUrl = (): ClientRequestError => (
+  new ClientRequestError('path', 'CLIENT_BASE_URL_INVALID', 'The client base URL is invalid.')
+)
+
+const validBaseUrl = (baseUrl: string): { origin: string; pathname: string } => {
+  if (
+    typeof baseUrl !== 'string'
+    || baseUrl.trim() !== baseUrl
+    || pathControlCharacters.test(baseUrl)
+    || baseUrl.includes('\\')
+  ) {
+    throw invalidBaseUrl()
+  }
+
+  const match = httpBaseUrl.exec(baseUrl)
+  const protocol = match?.[1]
+  const authority = match?.[2]
+  const pathname = match?.[3] ?? '/'
+  if (
+    protocol === undefined
+    || authority === undefined
+    || authority === ''
+    || authority.includes('@')
+    || /\s/.test(authority)
+    || encodedUnsafePathSegment.test(pathname)
+    || pathname.split('/').some(segment => segment === '.' || segment === '..')
+  ) {
+    throw invalidBaseUrl()
+  }
+
+  return {
+    origin: `${protocol.toLowerCase()}://${authority}`,
+    pathname,
+  }
+}
+
+export const resolveClientUrl = (baseUrl: string, path: string): string => {
+  assertClientPath(path)
+  const base = validBaseUrl(baseUrl)
+  const basePath = base.pathname.endsWith('/') ? base.pathname : `${base.pathname}/`
+  return path.startsWith('/')
+    ? `${base.origin}${path}`
+    : `${base.origin}${basePath}${path}`
+}
+
+const safeMessage = (value: unknown, fallback: string): string => {
+  if (typeof value !== 'string' || value.trim() === '') return fallback
+  const normalized = value.replace(controlCharacters, ' ').trim()
+  return normalized === '' ? fallback : normalized.slice(0, 512)
+}
+
+const safeErrorCode = (value: unknown, fallback: string): string => (
+  typeof value === 'string' && safeCode.test(value) ? value : fallback
+)
+
+const decodeKind = (value: unknown): string | null => {
+  if (!isRecord(value)) return null
+  const candidate = value.kind
+  return typeof candidate === 'string' ? candidate : null
+}
+
+const isDecodedResult = (value: unknown): value is ClientDecodeResult => {
+  const kind = decodeKind(value)
+  if (kind === 'success') return isRecord(value) && 'data' in value
+  if (kind === 'unauthorized' || kind === 'business') return isRecord(value)
+  return false
+}
+
+const normalizedDecodedResult = (value: ClientDecodeResult): ClientDecodeResult => {
+  const kind = decodeKind(value)
+  if (kind === 'success') return { kind: 'success', data: (value as ClientDecodeSuccess).data }
+  if (kind === 'unauthorized') {
+    const result = value as ClientDecodeUnauthorized
+    return {
+      kind: 'unauthorized',
+      code: safeErrorCode(result.code, defaultUnauthorizedCode),
+      message: safeMessage(result.message, genericUnauthorizedMessage),
+    }
+  }
+
+  const result = value as ClientDecodeBusiness
+  return {
+    kind: 'business',
+    code: safeErrorCode(result.code, defaultBusinessCode),
+    message: safeMessage(result.message, genericBusinessMessage),
+  }
+}
+
+const isHeaderSource = (value: unknown): value is ClientHeaderSource => (
+  typeof value === 'object'
+  && value !== null
+  && typeof (value as { forEach?: unknown }).forEach === 'function'
+)
+
+class PortableClientHeaders implements ClientHeaders {
+  private readonly values = new Map<string, string>()
+
+  constructor(headers?: ClientRequestHeaders) {
+    if (headers === undefined) return
+
+    if (Array.isArray(headers)) {
+      for (const entry of headers) {
+        if (!Array.isArray(entry) || entry.length !== 2) throw new TypeError('invalid header entry')
+        this.set(entry[0], entry[1])
+      }
+      return
+    }
+
+    if (isHeaderSource(headers)) {
+      headers.forEach((value, key) => this.set(key, value))
+      return
+    }
+
+    if (typeof headers === 'object' && headers !== null) {
+      for (const [key, value] of Object.entries(headers)) this.set(key, value)
+      return
+    }
+
+    throw new TypeError('invalid headers')
+  }
+
+  delete(name: string): void {
+    this.values.delete(name.toLowerCase())
+  }
+
+  get(name: string): string | null {
+    return this.values.get(name.toLowerCase()) ?? null
+  }
+
+  has(name: string): boolean {
+    return this.values.has(name.toLowerCase())
+  }
+
+  set(name: string, value: string): void {
+    if (!validHeaderName.test(name) || typeof value !== 'string' || invalidHeaderValue.test(value)) {
+      throw new TypeError('invalid header')
+    }
+    this.values.set(name.toLowerCase(), value.trim())
+  }
+
+  forEach(callback: (value: string, key: string) => void): void {
+    this.values.forEach((value, key) => callback(value, key))
+  }
+}
+
+const requestHeaders = (headers: ClientRequestHeaders | undefined): ClientHeaders => {
+  const result = new PortableClientHeaders(headers)
+  // Header names are normalized, so delete removes every caller spelling.
+  result.delete('Authorization')
+  return result
+}
+
+const methodOf = (method: ClientRequestMethod | undefined): ClientRequestMethod => (
+  (method ?? 'GET').toUpperCase() as ClientRequestMethod
+)
+
+const requestError = (kind: ClientRequestErrorKind, code: string, message: string): ClientRequestError => (
+  new ClientRequestError(kind, safeErrorCode(code, `CLIENT_${kind.toUpperCase()}_ERROR`), safeMessage(message, 'The request could not be completed.'))
+)
+
+export const createClient = (options: ClientOptions): Client => {
+  let unauthorizedHandling: Promise<void> | null = null
+
+  const invokeUnauthorized = async (error: ClientRequestError): Promise<void> => {
+    if (unauthorizedHandling === null) {
+      unauthorizedHandling = (async () => {
+        try {
+          await options.session.clear()
+        } catch {
+          throw requestError('session', 'CLIENT_SESSION_CLEAR_ERROR', 'The client session could not be cleared.')
+        }
+        try {
+          await options.hooks?.unauthorized?.(error)
+        } catch {
+          // Hook failures cannot turn an unauthorized response into success.
+        }
+      })().finally(() => {
+        unauthorizedHandling = null
+      })
+    }
+
+    await unauthorizedHandling
+  }
+
+  const request = async <TData = unknown>(input: ClientRequest): Promise<TData> => {
+    try {
+      assertClientPath(input.path)
+    } catch (error) {
+      if (error instanceof ClientRequestError) throw error
+      throw invalidPath()
+    }
+
+    const method = methodOf(input.method)
+    let headers: ClientHeaders
+    try {
+      headers = requestHeaders(input.headers)
+    } catch {
+      throw requestError('path', 'CLIENT_HEADERS_INVALID', 'The request headers are invalid.')
+    }
+
+    if (input.auth !== false) {
+      let token: string | null | undefined
+      try {
+        token = options.session.accessToken()
+      } catch {
+        throw requestError('session', 'CLIENT_SESSION_ERROR', 'The client session is unavailable.')
+      }
+      if (typeof token === 'string' && token !== '') headers.set('Authorization', `Bearer ${token}`)
+    }
+
+    const transportRequest: ClientTransportRequest = {
+      path: input.path,
+      method,
+      ...(input.data !== undefined ? { data: input.data } : {}),
+      headers,
+    }
+
+    let response: unknown
+    try {
+      response = await options.transport(transportRequest)
+    } catch {
+      throw requestError('transport', 'CLIENT_TRANSPORT_ERROR', 'The request could not be completed.')
+    }
+
+    let decoded: ClientDecodeResult
+    try {
+      decoded = await options.decoder(response, transportRequest)
+      if (!isDecodedResult(decoded)) throw new Error('invalid decoder result')
+      decoded = normalizedDecodedResult(decoded)
+    } catch {
+      throw requestError('decoder', 'CLIENT_DECODER_INVALID', 'The response could not be understood.')
+    }
+
+    if (decoded.kind === 'success') return decoded.data as TData
+
+    if (decoded.kind === 'unauthorized') {
+      const error = new ClientRequestError(
+        'unauthorized',
+        safeErrorCode(decoded.code, defaultUnauthorizedCode),
+        safeMessage(decoded.message, genericUnauthorizedMessage),
+      )
+      await invokeUnauthorized(error)
+      throw error
+    }
+
+    const error = new ClientRequestError(
+      'business',
+      safeErrorCode(decoded.code, defaultBusinessCode),
+      safeMessage(decoded.message, genericBusinessMessage),
+    )
+    try {
+      await options.hooks?.businessError?.(error)
+    } catch {
+      // Hook failures remain attached to this stable business failure path.
+    }
+    throw error
+  }
+
+  return { request }
+}
+
+export type ClientResult<TData = unknown> = ClientDecodeResult<TData>
+export type ClientRequestResult<TData = unknown> = Promise<TData>
+export type ClientHook = (error: ClientRequestError) => void | Promise<void>

package/client-nuxt/src/index.ts

@@ -0,0 +1,48 @@
+import { resolveClientUrl } from '@peanut-admin/admin/client'
+import type { ClientHeaders, ClientTransport, ClientTransportRequest } from '@peanut-admin/admin/client'
+
+export interface NuxtClientFetchOptions {
+  readonly method?: string
+  readonly query?: unknown
+  readonly body?: unknown
+  readonly headers?: Record<string, string>
+}
+
+export type NuxtClientFetch = (
+  url: string,
+  options?: NuxtClientFetchOptions,
+) => Promise<unknown>
+
+export interface NuxtClientTransportOptions {
+  readonly baseUrl: string
+  readonly $fetch: NuxtClientFetch
+}
+
+const isQueryMethod = (method: string): boolean => method === 'GET' || method === 'DELETE'
+
+const headersRecord = (headers: ClientHeaders): Record<string, string> => {
+  const result: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    result[key] = value
+  })
+  return result
+}
+
+export const createNuxtClientTransport = (
+  options: NuxtClientTransportOptions,
+): ClientTransport => {
+  return async (request: ClientTransportRequest): Promise<unknown> => {
+    const method = request.method.toUpperCase()
+    const url = resolveClientUrl(options.baseUrl, request.path)
+    const fetchOptions: NuxtClientFetchOptions = {
+      method,
+      headers: headersRecord(request.headers),
+      ...(request.data !== undefined
+        ? isQueryMethod(method)
+          ? { query: request.data }
+          : { body: request.data }
+        : {}),
+    }
+    return options.$fetch(url, fetchOptions)
+  }
+}

package/client-uniapp/src/index.ts

@@ -0,0 +1,50 @@
+import { resolveClientUrl } from '@peanut-admin/admin/client'
+import type { ClientHeaders, ClientTransport, ClientTransportRequest } from '@peanut-admin/admin/client'
+
+export interface UniAppClientResponse {
+  readonly data: unknown
+}
+
+export interface UniAppClientRequestOptions {
+  readonly url: string
+  readonly method: string
+  readonly data?: unknown
+  readonly header: Record<string, string>
+  readonly success?: (response: UniAppClientResponse) => void
+  readonly fail?: (error: unknown) => void
+}
+
+export type UniAppClientRequest = (
+  options: UniAppClientRequestOptions,
+) => void
+
+export interface UniAppClientTransportOptions {
+  readonly baseUrl: string
+  readonly request: UniAppClientRequest
+}
+
+const headersRecord = (headers: ClientHeaders): Record<string, string> => {
+  const result: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    result[key] = value
+  })
+  return result
+}
+
+export const createUniAppClientTransport = (
+  options: UniAppClientTransportOptions,
+): ClientTransport => async (request: ClientTransportRequest): Promise<unknown> => (
+  new Promise<unknown>((resolve, reject) => {
+    const method = request.method.toUpperCase()
+    const requestOptions: UniAppClientRequestOptions = {
+      url: resolveClientUrl(options.baseUrl, request.path),
+      method,
+      ...(request.data !== undefined ? { data: request.data } : {}),
+      header: headersRecord(request.headers),
+      success: response => resolve(response.data),
+      fail: error => reject(error),
+    }
+
+    options.request(requestOptions)
+  })
+)

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>