Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

refactor: extract storage and upload contracts into workspace package

HoshinoSuzumiBot2bf126a0d190
diff --git a/Dockerfile b/Dockerfile
index a18a2b49..bc8cc8e3 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -7,12 +7,14 @@ FROM base AS deps
WORKDIR /usr/src/app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY packages/webgl-image/package.json ./packages/webgl-image/
+COPY packages/contracts/package.json ./packages/contracts/
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
FROM base AS build
WORKDIR /usr/src/app
COPY --from=deps /usr/src/app/node_modules ./node_modules
COPY --from=deps /usr/src/app/packages/webgl-image/node_modules ./packages/webgl-image/node_modules
+COPY --from=deps /usr/src/app/packages/contracts/node_modules ./packages/contracts/node_modules
COPY . .
RUN pnpm exec nuxt prepare
RUN NODE_OPTIONS="--max-old-space-size=4096" pnpm run build:deps
diff --git a/package.json b/package.json
index 5eead955..006a33e9 100644
--- a/package.json
+++ b/package.json
@@ -37,6 +37,7 @@
"dependencies": {
"@aws-sdk/client-s3": "^3.1149.0",
"@aws-sdk/s3-request-presigner": "^3.1149.0",
+ "@chronoframe/contracts": "workspace:*",
"@chronoframe/webgl-image": "workspace:*",
"@iconify/vue": "5.0.3",
"@indoorequal/vue-maplibre-gl": "^8.4.2",
@@ -130,4 +131,4 @@
"sharp"
]
}
-}
\ No newline at end of file
+}
diff --git a/packages/contracts/README.md b/packages/contracts/README.md
new file mode 100644
index 00000000..58e47120
--- /dev/null
+++ b/packages/contracts/README.md
@@ -0,0 +1,17 @@
+# @chronoframe/contracts
+
+Shared, browser-compatible contracts for ChronoFrame distributions. This first
+extraction contains storage configuration schemas and upload plans, preserving
+existing validation, defaults, and optional fields.
+
+Import through `@chronoframe/contracts/storage` or
+`@chronoframe/contracts/upload`. The root application retains compatibility
+exports in `shared/types` while consumers migrate incrementally.
+
+This private workspace package exports TypeScript source, consumed by Nuxt/Vite.
+It requires no separate build step. Check it independently with
+`pnpm --filter @chronoframe/contracts type-check`.
+
+Do not add database models, application aliases, Nuxt auto-imports, Node globals,
+or process-wide services here. Storage configuration contains credentials and is
+not a public API response; existing server-side redaction remains required.
diff --git a/packages/contracts/package.json b/packages/contracts/package.json
new file mode 100644
index 00000000..afa65464
--- /dev/null
+++ b/packages/contracts/package.json
@@ -0,0 +1,20 @@
+{
+ "name": "@chronoframe/contracts",
+ "version": "0.1.0",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts",
+ "./storage": "./src/storage.ts",
+ "./upload": "./src/upload.ts"
+ },
+ "scripts": {
+ "type-check": "tsc --noEmit"
+ },
+ "dependencies": {
+ "zod": "^4.6.6"
+ },
+ "devDependencies": {
+ "typescript": "^5.9.3"
+ }
+}
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
new file mode 100644
index 00000000..27c9e38d
--- /dev/null
+++ b/packages/contracts/src/index.ts
@@ -0,0 +1,2 @@
+export * from './storage.ts'
+export * from './upload.ts'
diff --git a/packages/contracts/src/storage.ts b/packages/contracts/src/storage.ts
new file mode 100644
index 00000000..806c202f
--- /dev/null
+++ b/packages/contracts/src/storage.ts
@@ -0,0 +1,47 @@
+import { z } from 'zod'
+
+export const s3StorageConfigSchema = z.object({
+ provider: z.literal('s3'),
+ bucket: z.string(),
+ region: z.string().default('auto'),
+ endpoint: z.string(),
+ prefix: z.string().default('/photos').optional(),
+ cdnUrl: z.string().optional(),
+ accessKeyId: z.string(),
+ secretAccessKey: z.string(),
+ forcePathStyle: z.boolean().optional(),
+ maxKeys: z.number().optional(),
+})
+
+export const localStorageConfigSchema = z.object({
+ provider: z.literal('local'),
+ basePath: z.string().min(1),
+ baseUrl: z.string().optional(),
+ prefix: z.string().optional(),
+})
+
+export const openListStorageConfigSchema = z.object({
+ provider: z.literal('openlist'),
+ baseUrl: z.string().min(1),
+ rootPath: z.string().min(1),
+ token: z.string().min(1),
+ uploadEndpoint: z.string().default('/api/fs/put').optional(),
+ downloadEndpoint: z.string().optional(),
+ listEndpoint: z.string().optional(),
+ deleteEndpoint: z.string().default('/api/fs/remove').optional(),
+ metaEndpoint: z.string().default('/api/fs/get').optional(),
+ pathField: z.string().default('path').optional(),
+ cdnUrl: z.string().optional(),
+})
+
+export const storageConfigSchema = z.discriminatedUnion('provider', [
+ s3StorageConfigSchema,
+ localStorageConfigSchema,
+ openListStorageConfigSchema,
+])
+
+export type StorageConfig = z.infer<typeof storageConfigSchema>
+
+export type S3StorageConfig = z.infer<typeof s3StorageConfigSchema>
+export type LocalStorageConfig = z.infer<typeof localStorageConfigSchema>
+export type OpenListStorageConfig = z.infer<typeof openListStorageConfigSchema>
diff --git a/packages/contracts/src/upload.ts b/packages/contracts/src/upload.ts
new file mode 100644
index 00000000..2a1a061b
--- /dev/null
+++ b/packages/contracts/src/upload.ts
@@ -0,0 +1,29 @@
+export interface UploadPart {
+ partNumber: number
+ etag: string
+}
+
+export type UploadPlan =
+ | {
+ mode: 'single'
+ url: string
+ method?: 'PUT' | 'POST'
+ headers?: Record<string, string>
+ }
+ | {
+ mode: 'range'
+ url: string
+ partSize: number
+ method?: 'PUT' | 'POST'
+ headers?: Record<string, string>
+ }
+ | {
+ mode: 'chunks'
+ url: string
+ }
+ | {
+ mode: 'multipart'
+ url: string
+ partSize: number
+ partUrls: string[]
+ }
diff --git a/packages/contracts/tsconfig.json b/packages/contracts/tsconfig.json
new file mode 100644
index 00000000..89eb0f7d
--- /dev/null
+++ b/packages/contracts/tsconfig.json
@@ -0,0 +1,14 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "strict": true,
+ "noEmit": true,
+ "allowImportingTsExtensions": true,
+ "types": [],
+ "lib": ["ES2022", "DOM"],
+ "skipLibCheck": true
+ },
+ "include": ["src/**/*.ts"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d09cf733..f1ef95c6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -17,6 +17,9 @@ importers:
'@aws-sdk/s3-request-presigner':
specifier: ^3.1149.0
version: 3.1149.0
+ '@chronoframe/contracts':
+ specifier: workspace:*
+ version: link:packages/contracts
'@chronoframe/webgl-image':
specifier: workspace:*
version: link:packages/webgl-image
@@ -223,6 +226,16 @@ importers:
specifier: 2.0.0-alpha.20
+ packages/contracts:
+ dependencies:
+ zod:
+ specifier: ^4.6.6
+ version: 4.6.6
+ devDependencies:
+ typescript:
+ specifier: ^5.9.3
+ version: 5.9.3
+
packages/webgl-image:
dependencies:
vue:
diff --git a/server/services/storage/index.ts b/server/services/storage/index.ts
index 3ad4d41b..07e1ce40 100644
--- a/server/services/storage/index.ts
+++ b/server/services/storage/index.ts
@@ -5,14 +5,14 @@ export {
localStorageConfigSchema,
openListStorageConfigSchema,
storageConfigSchema,
-} from '~~/shared/types/storage'
+} from '@chronoframe/contracts/storage'
export type {
S3StorageConfig,
LocalStorageConfig,
OpenListStorageConfig,
StorageConfig,
-} from '~~/shared/types/storage'
+} from '@chronoframe/contracts/storage'
export { StorageProviderFactory, StorageManager } from './manager'
diff --git a/server/services/storage/interfaces.ts b/server/services/storage/interfaces.ts
index ad1d023b..38abc2cc 100644
--- a/server/services/storage/interfaces.ts
+++ b/server/services/storage/interfaces.ts
@@ -1,5 +1,5 @@
import type { StorageConfig } from '.'
-import type { UploadPart, UploadPlan } from '../../../shared/types/upload'
+import type { UploadPart, UploadPlan } from '@chronoframe/contracts/upload'
export type DirectUploadSetup =
| Extract<UploadPlan, { mode: 'single' | 'range' }>
diff --git a/shared/types/storage.ts b/shared/types/storage.ts
index 806c202f..d241d1f5 100644
--- a/shared/types/storage.ts
+++ b/shared/types/storage.ts
@@ -1,47 +1,2 @@
-import { z } from 'zod'
-
-export const s3StorageConfigSchema = z.object({
- provider: z.literal('s3'),
- bucket: z.string(),
- region: z.string().default('auto'),
- endpoint: z.string(),
- prefix: z.string().default('/photos').optional(),
- cdnUrl: z.string().optional(),
- accessKeyId: z.string(),
- secretAccessKey: z.string(),
- forcePathStyle: z.boolean().optional(),
- maxKeys: z.number().optional(),
-})
-
-export const localStorageConfigSchema = z.object({
- provider: z.literal('local'),
- basePath: z.string().min(1),
- baseUrl: z.string().optional(),
- prefix: z.string().optional(),
-})
-
-export const openListStorageConfigSchema = z.object({
- provider: z.literal('openlist'),
- baseUrl: z.string().min(1),
- rootPath: z.string().min(1),
- token: z.string().min(1),
- uploadEndpoint: z.string().default('/api/fs/put').optional(),
- downloadEndpoint: z.string().optional(),
- listEndpoint: z.string().optional(),
- deleteEndpoint: z.string().default('/api/fs/remove').optional(),
- metaEndpoint: z.string().default('/api/fs/get').optional(),
- pathField: z.string().default('path').optional(),
- cdnUrl: z.string().optional(),
-})
-
-export const storageConfigSchema = z.discriminatedUnion('provider', [
- s3StorageConfigSchema,
- localStorageConfigSchema,
- openListStorageConfigSchema,
-])
-
-export type StorageConfig = z.infer<typeof storageConfigSchema>
-
-export type S3StorageConfig = z.infer<typeof s3StorageConfigSchema>
-export type LocalStorageConfig = z.infer<typeof localStorageConfigSchema>
-export type OpenListStorageConfig = z.infer<typeof openListStorageConfigSchema>
+// Compatibility entry point for the existing Self-hosted application.
+export * from '@chronoframe/contracts/storage'
diff --git a/shared/types/upload.ts b/shared/types/upload.ts
index 2a1a061b..2739e7f5 100644
--- a/shared/types/upload.ts
+++ b/shared/types/upload.ts
@@ -1,29 +1,2 @@
-export interface UploadPart {
- partNumber: number
- etag: string
-}
-
-export type UploadPlan =
- | {
- mode: 'single'
- url: string
- method?: 'PUT' | 'POST'
- headers?: Record<string, string>
- }
- | {
- mode: 'range'
- url: string
- partSize: number
- method?: 'PUT' | 'POST'
- headers?: Record<string, string>
- }
- | {
- mode: 'chunks'
- url: string
- }
- | {
- mode: 'multipart'
- url: string
- partSize: number
- partUrls: string[]
- }
+// Compatibility entry point for the existing Self-hosted application.
+export * from '@chronoframe/contracts/upload'
diff --git a/tests/storage-contracts.test.ts b/tests/storage-contracts.test.ts
new file mode 100644
index 00000000..7fcc1906
--- /dev/null
+++ b/tests/storage-contracts.test.ts
@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { storageConfigSchema } from '@chronoframe/contracts/storage'
+import { storageConfigSchema as compatibilitySchema } from '../shared/types/storage.ts'
+
+// Exercise the workspace export as a plain Node consumer, outside Nuxt.
+test('Self-hosted compatibility entry uses the shared storage schema', () => {
+ assert.equal(compatibilitySchema, storageConfigSchema)
+ assert.deepEqual(
+ storageConfigSchema.parse({
+ provider: 's3',
+ bucket: 'photos',
+ endpoint: 'https://s3.example.com',
+ accessKeyId: 'test-key',
+ secretAccessKey: 'test-secret',
+ }),
+ {
+ provider: 's3',
+ bucket: 'photos',
+ endpoint: 'https://s3.example.com',
+ accessKeyId: 'test-key',
+ secretAccessKey: 'test-secret',
+ region: 'auto',
+ prefix: '/photos',
+ },
+ )
+})
+
+test('Local and OpenList retain Self-hosted configuration support', () => {
+ assert.deepEqual(
+ storageConfigSchema.parse({ provider: 'local', basePath: '/data/photos' }),
+ { provider: 'local', basePath: '/data/photos' },
+ )
+ const openList = storageConfigSchema.parse({
+ provider: 'openlist',
+ baseUrl: 'https://files.example.com',
+ rootPath: '/photos',
+ token: 'test-token',
+ })
+ assert.equal(openList.provider, 'openlist')
+ if (openList.provider === 'openlist') {
+ assert.equal(openList.uploadEndpoint, '/api/fs/put')
+ assert.equal(openList.deleteEndpoint, '/api/fs/remove')
+ assert.equal(openList.metaEndpoint, '/api/fs/get')
+ assert.equal(openList.pathField, 'path')
+ }
+ assert.equal(
+ storageConfigSchema.safeParse({ provider: 'local', basePath: '' }).success,
+ false,
+ )
+ assert.equal(
+ storageConfigSchema.safeParse({ provider: 'unknown' }).success,
+ false,
+ )
+})