@peanut-admin/admin 0.1.0-alpha.11

package/import-export/src/ImportExportPage.vue

@@ -0,0 +1,155 @@
+<script setup lang="ts">
+import { EmptyState, ForbiddenState, ModuleUnavailableState, PageContent, PageHeader, PageToolbar, SessionExpiredState } from '@peanut-admin/admin/shell'
+import { ElButton, ElInput } from 'element-plus'
+import { computed, onMounted, ref } from 'vue'
+import { useImportExportRuntime } from './runtime'
+
+const runtime = useImportExportRuntime(); const state = runtime.state
+const providerKey = ref(''); const inputFileKey = ref(''); const mappingJson = ref('{}')
+const canCreate = computed(runtime.canCreate); const canCancel = computed(runtime.canCancel)
+const statuses = ['queued', 'running', 'cancel_requested', 'succeeded', 'failed', 'cancelled', 'expired'] as const
+const submitImport = async (): Promise<void> => { try { const mapping = JSON.parse(mappingJson.value) as unknown; if (typeof mapping !== 'object' || mapping === null || Array.isArray(mapping)) throw new Error(); await runtime.submitImport(providerKey.value, inputFileKey.value, mapping as Record<string, string>) } catch { /* Runtime validation reports request errors; malformed JSON stays local. */ } }
+onMounted(runtime.load)
+</script>
+
+<template>
+  <PageContent class="import-export-page">
+    <PageHeader>
+      Import / Export<template #actions>
+        <ElButton
+          :loading="state.loading"
+          :disabled="state.mutating"
+          @click="runtime.load"
+        >
+          Reload
+        </ElButton>
+      </template>
+    </PageHeader>
+    <section
+      v-if="canCreate"
+      class="submission"
+      aria-label="Create import or export"
+    >
+      <ElInput
+        v-model="providerKey"
+        placeholder="Registered provider key"
+        aria-label="Provider key"
+      />
+      <ElInput
+        v-model="inputFileKey"
+        placeholder="Private CSV file key"
+        aria-label="Input file key"
+      />
+      <ElInput
+        v-model="mappingJson"
+        type="textarea"
+        placeholder="{&quot;CSV heading&quot;:&quot;column_key&quot;}"
+        aria-label="Column mapping JSON"
+      />
+      <div>
+        <ElButton
+          type="primary"
+          :disabled="state.mutating"
+          @click="submitImport"
+        >
+          Import CSV
+        </ElButton><ElButton
+          :disabled="state.mutating"
+          @click="runtime.submitExport(providerKey)"
+        >
+          Export CSV
+        </ElButton>
+      </div>
+    </section>
+    <PageToolbar label="Operation status">
+      <ElButton
+        v-for="status in statuses"
+        :key="status"
+        :type="state.status === status ? 'primary' : 'default'"
+        @click="runtime.setStatus(status)"
+      >
+        {{ status }}
+      </ElButton>
+    </PageToolbar>
+    <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"
+    >
+      <h2>Unable to complete the import/export 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"
+      role="status"
+    >
+      Loading import/export operations...
+    </div>
+    <EmptyState
+      v-else-if="state.items.length === 0"
+      title="No operations"
+      message="No import/export operations match this status."
+    />
+    <div
+      v-else
+      class="table-wrap"
+    >
+      <table>
+        <thead><tr><th>Provider</th><th>Direction</th><th>Status</th><th>Progress</th><th>Rows</th><th>Expires</th><th>Actions</th></tr></thead><tbody>
+          <tr
+            v-for="operation in state.items"
+            :key="operation.operationKey"
+          >
+            <td>{{ operation.providerKey }}</td><td>{{ operation.direction }}</td><td>{{ operation.status }}</td><td>
+              <progress
+                :value="operation.processedRows"
+                :max="Math.max(operation.totalRows, operation.processedRows, 1)"
+              />
+            </td><td>{{ operation.acceptedRows }} accepted / {{ operation.rejectedRows }} rejected</td><td>{{ operation.retentionUntil }}</td><td>
+              <ElButton
+                v-if="['queued','running'].includes(operation.status)"
+                text
+                :disabled="!canCancel || state.mutating"
+                @click="runtime.cancel(operation)"
+              >
+                Cancel
+              </ElButton><ElButton
+                v-if="operation.resultFileKey"
+                text
+                :disabled="state.mutating"
+                @click="runtime.download(operation.resultFileKey)"
+              >
+                Result
+              </ElButton><ElButton
+                v-if="operation.errorFileKey"
+                text
+                :disabled="state.mutating"
+                @click="runtime.download(operation.errorFileKey)"
+              >
+                Errors
+              </ElButton>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  </PageContent>
+</template>
+
+<style scoped>
+.submission { display: grid; gap: 8px; max-width: 720px; margin-bottom: 16px; }
+.table-wrap { overflow-x: auto; } table { width: 100%; border-collapse: collapse; } th, td { padding: 10px 8px; border-bottom: 1px solid var(--el-border-color); text-align: left; } progress { min-width: 120px; }
+</style>

package/import-export/src/contracts.ts

@@ -0,0 +1,96 @@
+export type ImportExportDirection = 'import' | 'export'
+export type ImportExportStatus = 'queued' | 'running' | 'cancel_requested' | 'succeeded' | 'failed' | 'cancelled' | 'expired'
+
+export interface ImportExportOperation {
+  operationKey: string
+  providerKey: string
+  direction: ImportExportDirection
+  status: ImportExportStatus
+  inputFileKey: string | null
+  resultFileKey: string | null
+  errorFileKey: string | null
+  taskJobKey: string | null
+  schemaRevision: string
+  processedRows: number
+  acceptedRows: number
+  rejectedRows: number
+  totalRows: number
+  revision: number
+  lastErrorCode: string | null
+  retentionUntil: string
+  createdAt: string
+  updatedAt: string
+  completedAt: string | null
+}
+
+export interface ImportExportList { items: ImportExportOperation[]; page: number; pageSize: number; total: number }
+export interface ImportExportTransportResult { status: number; body: unknown; headers: Headers }
+export interface ImportExportTransport {
+  list(status: ImportExportStatus, page: number, pageSize: number, signal: AbortSignal): Promise<ImportExportTransportResult>
+  submitImport(providerKey: string, fileKey: string, mapping: Record<string, string>, idempotencyKey: string, signal: AbortSignal): Promise<ImportExportTransportResult>
+  submitExport(providerKey: string, idempotencyKey: string, signal: AbortSignal): Promise<ImportExportTransportResult>
+  cancel(operationKey: string, revision: number, signal: AbortSignal): Promise<ImportExportTransportResult>
+  download(fileKey: string, signal: AbortSignal): Promise<Response>
+}
+
+const operationPattern = /^iox_[0-9a-f]{32}$/
+const filePattern = /^file_[0-9a-f]{32}$/
+const jobPattern = /^job_[0-9a-f]{32}$/
+const providerPattern = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/
+const revisionPattern = /^[a-z0-9][a-z0-9._-]{0,63}$/
+const errorPattern = /^[A-Z][A-Z0-9_]{2,63}$/
+const datePattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+
+const record = (value: unknown): Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('IMPORT_EXPORT_RESPONSE_INVALID')
+  return value as Record<string, unknown>
+}
+const exact = (value: Record<string, unknown>, keys: readonly string[]): void => {
+  if (Object.keys(value).sort().join('|') !== [...keys].sort().join('|')) throw new Error('IMPORT_EXPORT_RESPONSE_INVALID')
+}
+const nullablePattern = (value: unknown, pattern: RegExp): value is string | null => value === null || (typeof value === 'string' && pattern.test(value))
+const integer = (value: unknown, minimum = 0): value is number => typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum
+
+export const parseOperation = (value: unknown): ImportExportOperation => {
+  const item = record(value)
+  exact(item, ['operation_key', 'provider_key', 'direction', 'format', 'status', 'input_file_key', 'result_file_key', 'error_file_key', 'task_job_key', 'schema_revision', 'mapping', 'processed_rows', 'accepted_rows', 'rejected_rows', 'total_rows', 'revision', 'last_error_code', 'retention_until', 'created_at', 'updated_at', 'completed_at'])
+  if (!operationPattern.test(String(item.operation_key)) || !providerPattern.test(String(item.provider_key))
+    || (item.direction !== 'import' && item.direction !== 'export') || item.format !== 'csv'
+    || !['queued', 'running', 'cancel_requested', 'succeeded', 'failed', 'cancelled', 'expired'].includes(String(item.status))
+    || !nullablePattern(item.input_file_key, filePattern) || !nullablePattern(item.result_file_key, filePattern)
+    || !nullablePattern(item.error_file_key, filePattern) || !nullablePattern(item.task_job_key, jobPattern)
+    || !revisionPattern.test(String(item.schema_revision)) || !integer(item.processed_rows) || !integer(item.accepted_rows)
+    || !integer(item.rejected_rows) || !integer(item.total_rows) || !integer(item.revision, 1)
+    || (item.accepted_rows as number) + (item.rejected_rows as number) > (item.processed_rows as number)
+    || (item.last_error_code !== null && (typeof item.last_error_code !== 'string' || !errorPattern.test(item.last_error_code)))
+    || !datePattern.test(String(item.retention_until)) || !datePattern.test(String(item.created_at)) || !datePattern.test(String(item.updated_at))
+    || (item.completed_at !== null && (typeof item.completed_at !== 'string' || !datePattern.test(item.completed_at)))) {
+    throw new Error('IMPORT_EXPORT_RESPONSE_INVALID')
+  }
+  const terminal = ['succeeded', 'failed', 'cancelled', 'expired'].includes(String(item.status))
+  if ((item.direction === 'import') !== (item.input_file_key !== null) || terminal !== (item.completed_at !== null)) throw new Error('IMPORT_EXPORT_RESPONSE_INVALID')
+  const mapping = record(item.mapping)
+  for (const [source, target] of Object.entries(mapping)) if (source === '' || source.length > 120 || typeof target !== 'string' || !/^[a-z][a-z0-9_]{0,63}$/.test(target)) throw new Error('IMPORT_EXPORT_RESPONSE_INVALID')
+  return {
+    operationKey: item.operation_key as string, providerKey: item.provider_key as string,
+    direction: item.direction as ImportExportDirection, status: item.status as ImportExportStatus,
+    inputFileKey: item.input_file_key as string | null, resultFileKey: item.result_file_key as string | null,
+    errorFileKey: item.error_file_key as string | null, taskJobKey: item.task_job_key as string | null,
+    schemaRevision: item.schema_revision as string, processedRows: item.processed_rows as number,
+    acceptedRows: item.accepted_rows as number, rejectedRows: item.rejected_rows as number,
+    totalRows: item.total_rows as number, revision: item.revision as number,
+    lastErrorCode: item.last_error_code as string | null, retentionUntil: item.retention_until as string,
+    createdAt: item.created_at as string, updatedAt: item.updated_at as string, completedAt: item.completed_at as string | null,
+  }
+}
+
+export const parseOperationResponse = (value: unknown): ImportExportOperation => {
+  const body = record(value); exact(body, ['data', 'meta']); record(body.meta); return parseOperation(body.data)
+}
+export const parseOperationList = (value: unknown): ImportExportList => {
+  const body = record(value); exact(body, ['data', 'meta'])
+  const data = record(body.data); exact(data, ['items']); if (!Array.isArray(data.items)) throw new Error('IMPORT_EXPORT_RESPONSE_INVALID')
+  const meta = record(body.meta); exact(meta, ['request_id', 'page', 'page_size', 'total'])
+  if (typeof meta.request_id !== 'string' || meta.request_id === '' || !integer(meta.page, 1) || !integer(meta.page_size, 1) || !integer(meta.total)) throw new Error('IMPORT_EXPORT_RESPONSE_INVALID')
+  return { items: data.items.map(parseOperation), page: meta.page, pageSize: meta.page_size, total: meta.total }
+}

package/import-export/src/index.ts

@@ -0,0 +1,3 @@
+export * from './contracts'
+export * from './runtime'
+export { default as ImportExportPage } from './ImportExportPage.vue'

package/import-export/src/runtime.ts

@@ -0,0 +1,128 @@
+import { defineAdminModule } from '@peanut-admin/admin/core'
+import type { AdminModuleContribution } from '@peanut-admin/admin/core'
+import { inject, reactive } from 'vue'
+import type { InjectionKey } from 'vue'
+import { parseOperationList, parseOperationResponse } from './contracts'
+import type { ImportExportOperation, ImportExportStatus, ImportExportTransport, ImportExportTransportResult } from './contracts'
+
+export const IMPORT_EXPORT_MODULE_KEY = 'peanut.import-export' as const
+export const IMPORT_EXPORT_ROUTE_NAME = 'peanut.import-export.list' as const
+export const IMPORT_EXPORT_ROUTE_PATH = '/app/import-export' as const
+export const IMPORT_EXPORT_READ_PERMISSION = 'peanut.import-export.read' as const
+export const IMPORT_EXPORT_CREATE_PERMISSION = 'peanut.import-export.create' as const
+export const IMPORT_EXPORT_CANCEL_PERMISSION = 'peanut.import-export.cancel' as const
+export const IMPORT_EXPORT_STORE_KEY = 'peanut.import-export.runtime' as const
+
+export interface ImportExportError { message: string; requestId: string | null; status: number | null }
+export interface ImportExportState {
+  items: ImportExportOperation[]; status: ImportExportStatus; page: number; pageSize: number; total: number
+  loading: boolean; mutating: boolean; error: ImportExportError | null
+}
+export interface ImportExportRuntime {
+  state: ImportExportState
+  canCreate(): boolean
+  canCancel(): boolean
+  load(): Promise<void>
+  setStatus(status: ImportExportStatus): Promise<void>
+  submitImport(providerKey: string, fileKey: string, mapping: Record<string, string>): Promise<void>
+  submitExport(providerKey: string): Promise<void>
+  cancel(operation: ImportExportOperation): Promise<void>
+  download(fileKey: string): Promise<void>
+  dispose(): void
+}
+export interface ImportExportRuntimeOptions {
+  transport: ImportExportTransport
+  canRead(): boolean
+  canCreate(): boolean
+  canCancel(): boolean
+  saveDownload?: (response: Response, fileKey: string, signal: AbortSignal) => Promise<void>
+  idempotencyKey?: () => string
+}
+
+const requestId = (result: ImportExportTransportResult): string | null => {
+  const body = typeof result.body === 'object' && result.body !== null && !Array.isArray(result.body) ? result.body as Record<string, unknown> : {}
+  const value = body.request_id ?? result.headers.get('X-Request-Id')
+  return typeof value === 'string' && value !== '' ? value : null
+}
+const failure = (result: ImportExportTransportResult): ImportExportError => {
+  const body = typeof result.body === 'object' && result.body !== null && !Array.isArray(result.body) ? result.body as Record<string, unknown> : {}
+  return { message: typeof body.detail === 'string' && body.detail !== '' ? body.detail : `Import/export request failed (${result.status}).`, requestId: requestId(result), status: result.status }
+}
+const key = (): string => `web-${crypto.randomUUID()}`
+const save = async (response: Response, fileKey: string, signal: AbortSignal): Promise<void> => {
+  const blob = await response.blob(); if (signal.aborted) throw new DOMException('Aborted', 'AbortError')
+  const url = URL.createObjectURL(blob); const anchor = document.createElement('a')
+  anchor.href = url; anchor.download = `${fileKey}.csv`; anchor.click(); URL.revokeObjectURL(url)
+}
+
+export const createImportExportRuntime = (options: ImportExportRuntimeOptions): ImportExportRuntime => {
+  const state = reactive<ImportExportState>({ items: [], status: 'queued', page: 1, pageSize: 20, total: 0, loading: false, mutating: false, error: null })
+  let disposeEpoch = 0; let readEpoch = 0; let downloadEpoch = 0
+  let readController: AbortController | null = null; let commandController: AbortController | null = null; let downloadController: AbortController | null = null
+  const aborted = (error: unknown): boolean => error instanceof DOMException && error.name === 'AbortError'
+  const load = async (): Promise<void> => {
+    const currentDispose = disposeEpoch; const currentRead = ++readEpoch
+    readController?.abort(); const controller = new AbortController(); readController = controller
+    state.loading = true; state.error = null
+    try {
+      if (!options.canRead()) throw new Error('IMPORT_EXPORT_PERMISSION_DENIED')
+      const status = state.status; const page = state.page; const pageSize = state.pageSize
+      const result = await options.transport.list(status, page, pageSize, controller.signal)
+      if (currentDispose !== disposeEpoch || currentRead !== readEpoch) return
+      if (result.status !== 200) { state.error = failure(result); return }
+      const list = parseOperationList(result.body); state.items = [...list.items]; state.page = list.page; state.pageSize = list.pageSize; state.total = list.total
+    } catch (error) { if (currentDispose === disposeEpoch && currentRead === readEpoch && !aborted(error)) state.error = { message: 'The import/export service could not be reached.', requestId: null, status: null } }
+    finally {
+      if (readController === controller) readController = null
+      if (currentDispose === disposeEpoch && currentRead === readEpoch) state.loading = false
+    }
+  }
+  const mutate = async (operation: (signal: AbortSignal) => Promise<ImportExportTransportResult>): Promise<void> => {
+    if (state.mutating || commandController !== null) return
+    const currentDispose = disposeEpoch; const controller = new AbortController(); commandController = controller
+    state.mutating = true; state.error = null
+    try {
+      const result = await operation(controller.signal); if (currentDispose !== disposeEpoch) return
+      if (result.status !== 201 && result.status !== 200) { state.error = failure(result); return }
+      parseOperationResponse(result.body); await load()
+    } catch (error) { if (currentDispose === disposeEpoch && !aborted(error)) state.error = { message: 'The import/export request could not be completed.', requestId: null, status: null } }
+    finally {
+      if (commandController === controller) commandController = null
+      if (currentDispose === disposeEpoch) state.mutating = false
+    }
+  }
+  return {
+    state, canCreate: options.canCreate, canCancel: options.canCancel, load,
+    async setStatus(status) { state.status = status; state.page = 1; await load() },
+    async submitImport(providerKey, fileKey, mapping) { if (!options.canCreate()) return; await mutate(signal => options.transport.submitImport(providerKey, fileKey, mapping, (options.idempotencyKey ?? key)(), signal)) },
+    async submitExport(providerKey) { if (!options.canCreate()) return; await mutate(signal => options.transport.submitExport(providerKey, (options.idempotencyKey ?? key)(), signal)) },
+    async cancel(operation) { if (!options.canCancel() || !['queued', 'running'].includes(operation.status)) return; await mutate(signal => options.transport.cancel(operation.operationKey, operation.revision, signal)) },
+    async download(fileKey) {
+      const currentDispose = disposeEpoch; const currentDownload = ++downloadEpoch
+      downloadController?.abort(); const controller = new AbortController(); downloadController = controller; state.error = null
+      try {
+        const response = await options.transport.download(fileKey, controller.signal)
+        if (currentDispose !== disposeEpoch || currentDownload !== downloadEpoch) return
+        if (!response.ok) { let body: unknown = null; try { body = await response.json() } catch { body = null }; if (currentDispose === disposeEpoch && currentDownload === downloadEpoch) state.error = failure({ status: response.status, body, headers: response.headers }); return }
+        await (options.saveDownload ?? save)(response, fileKey, controller.signal)
+      } catch (error) { if (currentDispose === disposeEpoch && currentDownload === downloadEpoch && !aborted(error)) state.error = { message: 'The CSV file could not be downloaded.', requestId: null, status: null } }
+      finally { if (downloadController === controller) downloadController = null }
+    },
+    dispose() {
+      disposeEpoch += 1; readEpoch += 1; downloadEpoch += 1
+      readController?.abort(); commandController?.abort(); downloadController?.abort()
+      readController = null; commandController = null; downloadController = null
+      state.items = []; state.status = 'queued'; state.page = 1; state.pageSize = 20; state.total = 0
+      state.loading = false; state.mutating = false; state.error = null
+    },
+  }
+}
+
+export const importExportRuntimeKey: InjectionKey<ImportExportRuntime> = Symbol(IMPORT_EXPORT_STORE_KEY)
+export const useImportExportRuntime = (): ImportExportRuntime => { const runtime = inject(importExportRuntimeKey); if (runtime === undefined) throw new Error('IMPORT_EXPORT_RUNTIME_MISSING'); return runtime }
+export const createImportExportModuleContribution = (runtime: ImportExportRuntime): AdminModuleContribution => defineAdminModule({
+  key: IMPORT_EXPORT_MODULE_KEY,
+  routes: [{ name: IMPORT_EXPORT_ROUTE_NAME, path: IMPORT_EXPORT_ROUTE_PATH, component: async () => ({ default: (await import('./ImportExportPage.vue')).default }), access: { moduleKey: IMPORT_EXPORT_MODULE_KEY, permissionKeys: [IMPORT_EXPORT_READ_PERMISSION] } }],
+  disposeOnTenantChange: true,
+  stores: [{ key: IMPORT_EXPORT_STORE_KEY, dispose: runtime.dispose }],
+})