@peanut-admin/admin 0.1.0-alpha.2

package/admin-shell/src/states.ts

@@ -0,0 +1,93 @@
+import { ElButton } from 'element-plus'
+import { defineComponent, h } from 'vue'
+import type { PropType } from 'vue'
+
+interface StateDefaults {
+  title: string
+  message: string
+  actionLabel?: string
+}
+
+const createStateComponent = (name: string, state: string, defaults: StateDefaults) => defineComponent({
+  name,
+  props: {
+    title: { type: String, default: defaults.title },
+    message: { type: String, default: defaults.message },
+    requestId: { type: String, default: null },
+    retryAfter: { type: String as PropType<string | null>, default: null },
+    actionLabel: { type: String, default: defaults.actionLabel ?? null },
+    onAction: { type: Function as PropType<() => void>, default: null },
+  },
+  emits: {
+    action: () => true,
+  },
+  setup(props, { emit, slots }) {
+    return () => h('section', {
+      class: ['pa-state', `pa-state--${name.replace(/State$/, '').toLowerCase()}`],
+      'data-state': state,
+      role: 'status',
+      'aria-live': 'polite',
+    }, [
+      h('h2', { class: 'pa-state__title' }, props.title),
+      h('p', { class: 'pa-state__message' }, props.message),
+      props.requestId === null
+        ? null
+        : h('p', { class: 'pa-state__request-id' }, `Request ID: ${props.requestId}`),
+      props.retryAfter === null
+        ? null
+        : h('p', { class: 'pa-state__retry-after' }, `Retry after: ${props.retryAfter}`),
+      slots.default?.(),
+      props.actionLabel === null
+        ? null
+        : h(ElButton, {
+            onClick: () => {
+              emit('action')
+            },
+          }, () => props.actionLabel),
+    ])
+  },
+})
+
+export const EmptyState = createStateComponent('EmptyState', 'empty', {
+  title: 'No data',
+  message: 'There is nothing to display.',
+})
+
+export const ForbiddenState = createStateComponent('ForbiddenState', 'forbidden', {
+  title: 'Access denied',
+  message: 'You do not have permission to view this page.',
+})
+
+export const NotFoundState = createStateComponent('NotFoundState', 'not-found', {
+  title: 'Not found',
+  message: 'The requested resource is unavailable.',
+})
+
+export const ModuleUnavailableState = createStateComponent('ModuleUnavailableState', 'module-unavailable', {
+  title: 'Module unavailable',
+  message: 'This module is currently unavailable.',
+  actionLabel: 'Retry',
+})
+
+export const ConflictState = createStateComponent('ConflictState', 'conflict', {
+  title: 'Content changed',
+  message: 'Reload the latest version before continuing.',
+  actionLabel: 'Reload',
+})
+
+export const RateLimitState = createStateComponent('RateLimitState', 'rate-limit', {
+  title: 'Too many requests',
+  message: 'Wait before trying again.',
+})
+
+export const ServiceUnavailableState = createStateComponent('ServiceUnavailableState', 'service-unavailable', {
+  title: 'Service unavailable',
+  message: 'The service is temporarily unavailable.',
+  actionLabel: 'Retry',
+})
+
+export const SessionExpiredState = createStateComponent('SessionExpiredState', 'session-expired', {
+  title: 'Session expired',
+  message: 'Sign in again to continue.',
+  actionLabel: 'Sign in',
+})

package/admin-shell/src/targets.ts

@@ -0,0 +1,128 @@
+/* eslint-disable vue/one-component-per-file */
+
+import type { TargetCandidate, TypedTarget } from '@peanut-admin/admin/core'
+import { ElOption, ElPagination, ElSelect } from 'element-plus'
+import { computed, defineComponent, h } from 'vue'
+import type { Component, PropType } from 'vue'
+
+const SelectComponent = ElSelect as unknown as Component
+const OptionComponent = ElOption as unknown as Component
+const PaginationComponent = ElPagination as unknown as Component
+
+const targetKey = (target: TypedTarget): string => JSON.stringify([
+  target.target_resource_key,
+  target.target_role,
+  target.target_id,
+])
+
+export const TargetSelector = defineComponent({
+  name: 'TargetSelector',
+  props: {
+    modelValue: {
+      type: Array as PropType<readonly TypedTarget[]>,
+      default: () => [],
+    },
+    candidates: {
+      type: Array as PropType<readonly TargetCandidate[]>,
+      default: () => [],
+    },
+    multiple: { type: Boolean, default: false },
+    loading: { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+    placeholder: { type: String, default: 'Select target' },
+    page: { type: Number, default: 1 },
+    pageSize: { type: Number, default: 20 },
+    total: { type: Number, default: 0 },
+  },
+  emits: {
+    'update:modelValue': (targets: readonly TypedTarget[]) => Array.isArray(targets),
+    search: (query: string) => typeof query === 'string',
+    'page-change': (page: number) => Number.isInteger(page) && page >= 1,
+  },
+  setup(props, { emit }) {
+    const candidateMap = computed(() => new Map(
+      props.candidates.map(candidate => [targetKey(candidate), candidate]),
+    ))
+    const selectedKeys = computed(() => props.modelValue.map(targetKey))
+    const updateSelection = (value: unknown): void => {
+      const values = (Array.isArray(value) ? value : [value]).filter(
+        (candidate): candidate is string => typeof candidate === 'string',
+      )
+      const targets = values.flatMap(key => {
+        const candidate = candidateMap.value.get(key)
+        return candidate === undefined
+          ? []
+          : [{
+              target_resource_key: candidate.target_resource_key,
+              target_role: candidate.target_role,
+              target_id: candidate.target_id,
+            }]
+      })
+      emit('update:modelValue', props.multiple ? targets : targets.slice(0, 1))
+    }
+
+    return () => h('div', { class: 'pa-target-selector' }, [
+      h(SelectComponent, {
+        modelValue: props.multiple ? selectedKeys.value : (selectedKeys.value[0] ?? null),
+        'onUpdate:modelValue': updateSelection,
+        multiple: props.multiple,
+        filterable: true,
+        remote: true,
+        remoteMethod: (query: string) => emit('search', query),
+        loading: props.loading,
+        disabled: props.disabled,
+        placeholder: props.placeholder,
+        class: 'pa-target-selector__select',
+      }, () => props.candidates.map(candidate => h(OptionComponent, {
+        key: targetKey(candidate),
+        value: targetKey(candidate),
+        label: candidate.label,
+      }))),
+      props.total <= props.pageSize
+        ? null
+        : h(PaginationComponent, {
+            class: 'pa-target-selector__pagination',
+            currentPage: props.page,
+            pageSize: props.pageSize,
+            total: props.total,
+            layout: 'prev, pager, next',
+            'onUpdate:currentPage': (page: number) => emit('page-change', page),
+          }),
+    ])
+  },
+})
+
+export type TargetScopeMode = 'zero' | 'single' | 'multiple' | 'aggregate'
+
+export const TargetScopeSummary = defineComponent({
+  name: 'TargetScopeSummary',
+  props: {
+    mode: {
+      type: String as PropType<TargetScopeMode>,
+      required: true,
+    },
+    availableCount: { type: Number, required: true },
+    selectedCount: { type: Number, default: 0 },
+    digest: { type: String, default: null },
+  },
+  setup(props) {
+    const message = computed(() => {
+      switch (props.mode) {
+        case 'zero':
+          return 'No available targets'
+        case 'single':
+          return '1 available target'
+        case 'aggregate':
+          return `Read-only aggregate across ${props.availableCount} targets`
+        default:
+          return `${props.selectedCount} of ${props.availableCount} targets selected`
+      }
+    })
+
+    return () => h('div', {
+      class: ['pa-target-scope-summary', `is-${props.mode}`],
+      role: 'status',
+      'aria-label': 'Target scope',
+    }, message.value)
+  },
+})

package/admin-shell/src/theme.ts

@@ -0,0 +1,15 @@
+export const SHELL_THEME_TOKENS = {
+  headerHeight: '--pa-shell-header-height',
+  sidebarWidth: '--pa-shell-sidebar-width',
+  sidebarCollapsedWidth: '--pa-shell-sidebar-collapsed-width',
+  contentMaxWidth: '--pa-shell-content-max-width',
+  surfaceColor: '--pa-shell-surface-color',
+  borderColor: '--pa-shell-border-color',
+  textColor: '--pa-shell-text-color',
+  mutedTextColor: '--pa-shell-muted-text-color',
+  focusColor: '--pa-shell-focus-color',
+} as const
+
+export type ShellThemeToken = typeof SHELL_THEME_TOKENS[keyof typeof SHELL_THEME_TOKENS]
+
+export type ShellSlotName = 'header' | 'sidebar' | 'breadcrumb' | 'tabs' | 'default'

package/client-core/src/index.ts

@@ -0,0 +1,325 @@
+export type ClientRequestMethod =
+  | 'DELETE'
+  | 'GET'
+  | 'HEAD'
+  | 'OPTIONS'
+  | 'PATCH'
+  | 'POST'
+  | 'PUT'
+
+export interface ClientRequest<TData = unknown> {
+  readonly path: string
+  readonly method?: ClientRequestMethod
+  readonly data?: TData
+  readonly headers?: HeadersInit
+  readonly auth?: boolean
+}
+
+export interface ClientTransportRequest<TData = unknown> {
+  readonly path: string
+  readonly method: ClientRequestMethod
+  readonly data?: TData
+  readonly headers: Headers
+}
+
+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 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 validBaseUrl = (baseUrl: string): URL => {
+  let url: URL
+  try {
+    url = new URL(baseUrl)
+  } catch {
+    throw new ClientRequestError('path', 'CLIENT_BASE_URL_INVALID', 'The client base URL is invalid.')
+  }
+
+  if (
+    !['http:', 'https:'].includes(url.protocol)
+    || url.username !== ''
+    || url.password !== ''
+    || url.search !== ''
+    || url.hash !== ''
+  ) {
+    throw new ClientRequestError('path', 'CLIENT_BASE_URL_INVALID', 'The client base URL is invalid.')
+  }
+
+  return url
+}
+
+export const resolveClientUrl = (baseUrl: string, path: string): string => {
+  assertClientPath(path)
+  const base = validBaseUrl(baseUrl)
+  const basePath = base.pathname.endsWith('/') ? base.pathname : `${base.pathname}/`
+  const root = new URL(base.origin)
+  root.pathname = basePath
+  return new URL(path, root).toString()
+}
+
+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 requestHeaders = (headers: HeadersInit | undefined): Headers => {
+  const result = new Headers(headers)
+  // Headers is case-insensitive and delete removes all values for this name.
+  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: Headers
+    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>
+export type ClientRequestHeaders = HeadersInit

package/client-nuxt/src/index.ts

@@ -0,0 +1,40 @@
+import { resolveClientUrl } from '@peanut-admin/admin/client'
+import type { ClientTransport, ClientTransportRequest } from '@peanut-admin/admin/client'
+
+export interface NuxtClientFetchOptions {
+  readonly method?: string
+  readonly query?: unknown
+  readonly body?: unknown
+  readonly headers?: HeadersInit
+}
+
+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'
+
+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: 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 { 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: Headers): 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)
+  })
+)