@byline/host-tanstack-start 0.9.3

package/src/server-fns/collections/get.ts

@@ -0,0 +1,233 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import {
+  BylineError,
+  buildRelationSummaryPopulateMap,
+  ERR_NOT_FOUND,
+  ErrorCodes,
+  getCollectionAdminConfig,
+  getCollectionDefinition,
+  getCollectionSchemasForPath,
+  getLogger,
+  getServerConfig,
+  type PopulateSpec,
+} from '@byline/core'
+
+import { ensureCollection } from '../../integrations/api-utils.js'
+import { getAdminBylineClient } from '../../integrations/byline-client.js'
+import { serialise } from './utils'
+
+// ---------------------------------------------------------------------------
+// Get document (current version, with optional published-version metadata)
+// ---------------------------------------------------------------------------
+
+const getDocumentFn = createServerFn({ method: 'GET' })
+  .inputValidator(
+    (input: {
+      collection: string
+      id: string
+      locale?: string
+      depth?: number
+      populateRelations?: boolean
+    }) => input
+  )
+  .handler(async ({ data }) => {
+    const { collection: path, id, locale, depth, populateRelations } = data
+    const logger = getLogger()
+    const config = await ensureCollection(path)
+    if (!config) {
+      throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: { collectionPath: path },
+      }).log(logger)
+    }
+
+    const client = getAdminBylineClient()
+    const handle = client.collection(path)
+
+    // Determine populate strategy. The admin API-preview path passes an
+    // explicit `depth > 0` and uses `'*'` to walk every relation with the
+    // full document projection — useful for the debug/preview UI but
+    // wasteful elsewhere. The admin edit loader sets `populateRelations`
+    // to auto-build a depth-1 projection from the schema's relation
+    // fields, so each target gets just its picker columns + useAsTitle
+    // and relation-summary tiles render on first paint without per-tile
+    // fetches.
+    const populateRequested = typeof depth === 'number' && depth > 0
+    const autoRelationsActive = !populateRequested && populateRelations === true
+
+    let populate: PopulateSpec | undefined
+    let resolvedDepth: number | undefined
+    if (populateRequested) {
+      populate = '*'
+      resolvedDepth = depth
+    } else if (autoRelationsActive) {
+      const populateMap = buildRelationSummaryPopulateMap(
+        config.definition.fields,
+        (targetPath) => ({
+          def: getCollectionDefinition(targetPath),
+          admin: getCollectionAdminConfig(targetPath),
+        })
+      )
+      if (Object.keys(populateMap).length > 0) {
+        populate = populateMap
+        resolvedDepth = 1
+      }
+    }
+
+    const document = await handle.findById(id, {
+      locale: locale ?? 'en',
+      populate,
+      depth: resolvedDepth,
+      status: 'any',
+    })
+
+    if (!document) {
+      throw ERR_NOT_FOUND({
+        message: 'Document not found',
+        details: { documentId: id, collectionPath: path },
+      }).log(logger)
+    }
+
+    const serialised = serialise(document)
+
+    // Skip the strict per-locale Zod parse when:
+    //   - locale === 'all' (fields are locale-keyed objects, not per-locale values)
+    //   - populated (the tree now contains nested populated documents that
+    //     don't match the raw relation-ref shape the schema expects —
+    //     applies equally to the depth-based preview path and the
+    //     admin-edit relation-summary path)
+    const populatedTree = populateRequested || autoRelationsActive
+    const parsed =
+      locale === 'all' || populatedTree
+        ? (serialised as Record<string, any>)
+        : (() => {
+            const { get } = getCollectionSchemasForPath(path)
+            return get.parse(serialised)
+          })()
+
+    // If the current version is not published, check whether a separate
+    // published version exists so the UI can show a "published is live"
+    // badge. This is admin-bespoke metadata — `db.queries.documents.*` is
+    // the documented escape hatch for it. Reshaped to camelCase to match
+    // the surrounding ClientDocument shape.
+    let publishedVersion: Record<string, any> | null = null
+    if ((parsed as any).status !== 'published') {
+      const pv = await getServerConfig().db.queries.documents.getPublishedVersion({
+        collection_id: config.collection.id,
+        document_id: id,
+      })
+      publishedVersion = pv
+        ? serialise({
+            id: pv.document_id,
+            versionId: pv.document_version_id,
+            status: pv.status,
+            createdAt: pv.created_at,
+            updatedAt: pv.updated_at,
+          })
+        : null
+    }
+
+    return { ...(parsed as Record<string, any>), _publishedVersion: publishedVersion }
+  })
+
+// ---------------------------------------------------------------------------
+// Get document by specific version ID (for history / diff views)
+// ---------------------------------------------------------------------------
+
+const getDocumentByVersionFn = createServerFn({ method: 'GET' })
+  .inputValidator((input: { collection: string; versionId: string; locale?: string }) => input)
+  .handler(async ({ data }) => {
+    const { collection: path, versionId, locale } = data
+    const resolvedLocale = locale ?? 'all'
+
+    const logger = getLogger()
+    const config = await ensureCollection(path)
+    if (!config) {
+      throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: { collectionPath: path },
+      }).log(logger)
+    }
+
+    const document = await getAdminBylineClient()
+      .collection(path)
+      .findByVersion(versionId, { locale: resolvedLocale })
+
+    if (!document) {
+      throw ERR_NOT_FOUND({
+        message: 'Document version not found',
+        details: { documentVersionId: versionId, collectionPath: path },
+      }).log(logger)
+    }
+
+    const serialised = serialise(document)
+
+    // When fetching all locales the storage layer returns localized fields as
+    // locale-keyed objects — skip Zod validation in that case (same rationale
+    // as getDocumentFn). For a specific locale, parse for runtime safety.
+    if (resolvedLocale === 'all') {
+      return serialised as Record<string, any>
+    }
+
+    // Parse through the same Zod schema used by getDocumentFn so that key
+    // ordering and datetime formats are normalised identically on both sides
+    // of the diff — otherwise identical content renders as changed.
+    const { get } = getCollectionSchemasForPath(path)
+    return get.parse(serialised) as Record<string, any>
+  })
+
+/**
+ * Fetch a single document by ID. Returns `null` when the document is not found
+ * so callers can degrade gracefully (e.g. `notFound()`).
+ *
+ * When `depth > 0` is supplied, relation leaves are populated before the
+ * response is returned — this is the hook that powers the admin
+ * API-preview Depth selector. The returned tree then contains nested
+ * shaped `ClientDocument`s at relation sites instead of bare
+ * `{target_document_id, target_collection_id}` refs.
+ */
+export async function getCollectionDocument(
+  collection: string,
+  id: string,
+  locale?: string,
+  depth?: number,
+  populateRelations?: boolean
+) {
+  try {
+    return await getDocumentFn({
+      data: { collection, id, locale, depth, populateRelations },
+    })
+  } catch (err) {
+    if (err instanceof BylineError && err.code === ErrorCodes.NOT_FOUND) return null
+    throw err
+  }
+}
+
+/**
+ * Fetch a specific historical version of a document. Returns `null` when the
+ * version is not found.
+ */
+export async function getCollectionDocumentVersion(
+  collection: string,
+  _documentId: string,
+  versionId: string,
+  locale?: string
+) {
+  try {
+    return await getDocumentByVersionFn({
+      data: { collection, versionId, locale },
+    })
+  } catch (err) {
+    if (err instanceof BylineError && err.code === ErrorCodes.NOT_FOUND) return null
+    throw err
+  }
+}

package/src/server-fns/collections/history.ts

@@ -0,0 +1,73 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import { ERR_NOT_FOUND, getCollectionSchemasForPath, getLogger } from '@byline/core'
+
+import { ensureCollection } from '../../integrations/api-utils.js'
+import { getAdminBylineClient } from '../../integrations/byline-client.js'
+import { serialise } from './utils'
+
+// ---------------------------------------------------------------------------
+// Shared param types
+// ---------------------------------------------------------------------------
+
+export interface HistorySearchParams {
+  page?: number
+  page_size?: number
+  order?: string
+  desc?: boolean
+  locale?: string
+}
+
+// ---------------------------------------------------------------------------
+// Get document version history
+// ---------------------------------------------------------------------------
+
+export const getCollectionDocumentHistory = createServerFn({ method: 'GET' })
+  .inputValidator((input: { collection: string; id: string; params: HistorySearchParams }) => input)
+  .handler(async ({ data }) => {
+    const { collection: path, id, params } = data
+    const config = await ensureCollection(path)
+    if (!config) {
+      throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: { collectionPath: path },
+      }).log(getLogger())
+    }
+
+    // Routes through CollectionHandle.history so the access gate
+    // (`beforeRead` via `findById`) is applied consistently with the rest
+    // of the read pipeline. When the actor's predicate excludes the
+    // document, history returns an empty result rather than leaking
+    // version metadata.
+    const result = await getAdminBylineClient()
+      .collection(path)
+      .history(id, {
+        locale: params.locale ?? 'en',
+        page: params.page,
+        pageSize: params.page_size,
+        order: params.order,
+        desc: params.desc,
+      })
+
+    const serialised = serialise(result)
+    const { history } = getCollectionSchemasForPath(path)
+
+    // When locale is 'all' the storage layer returns localized fields as
+    // locale-keyed objects which don't conform to the typed Zod schema — skip
+    // validation in that case, same as getCollectionDocument. Cast through
+    // the inferred Zod type so both branches share one return shape; the
+    // runtime contents are structurally compatible.
+    if (params.locale === 'all') {
+      return serialised as unknown as ReturnType<typeof history.parse>
+    }
+
+    return history.parse(serialised)
+  })

package/src/server-fns/collections/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Barrel re-exports for admin collection operations.
+ *
+ * Each module is self-contained: it defines the TanStack Start server
+ * function and exports a clean public API.
+ */
+
+export * from './create'
+export * from './delete'
+export * from './get'
+export * from './history'
+export * from './list'
+export * from './stats'
+export * from './status'
+export * from './update'
+export * from './upload'

package/src/server-fns/collections/list.ts

@@ -0,0 +1,121 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import {
+  ERR_NOT_FOUND,
+  getCollectionSchemasForPath,
+  getLogger,
+  getServerConfig,
+  type QueryPredicate,
+} from '@byline/core'
+
+import { ensureCollection } from '../../integrations/api-utils.js'
+import { getAdminBylineClient } from '../../integrations/byline-client.js'
+import { serialise } from './utils'
+
+// ---------------------------------------------------------------------------
+// Shared param types
+// ---------------------------------------------------------------------------
+
+export interface CollectionSearchParams {
+  page?: number
+  page_size?: number
+  order?: string
+  desc?: boolean
+  query?: string
+  locale?: string
+  status?: string
+  fields?: string[]
+}
+
+// ---------------------------------------------------------------------------
+// List documents
+// ---------------------------------------------------------------------------
+
+export const getCollectionDocuments = createServerFn({ method: 'GET' })
+  .inputValidator((input: { collection: string; params: CollectionSearchParams }) => input)
+  .handler(async ({ data }) => {
+    const { collection: path, params } = data
+    const config = await ensureCollection(path)
+    if (!config) {
+      throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: { collectionPath: path },
+      }).log(getLogger())
+    }
+
+    const client = getAdminBylineClient()
+    const handle = client.collection(path)
+    const pageSize = params.page_size ?? 20
+
+    // Routes through CollectionHandle.find so the read pipeline (beforeRead
+    // → findDocuments → afterRead) is identical to any non-admin client.
+    // `status: 'any'` keeps admin behaviour: in-progress drafts are visible
+    // even when no published version exists. The `where.status` filter
+    // (when supplied) further narrows to a specific exact status, and
+    // `where.query` triggers the configured search-fields text search.
+    const where: QueryPredicate = {}
+    if (params.status) where.status = params.status
+    if (params.query) where.query = params.query
+
+    const result = await handle.find({
+      where: Object.keys(where).length > 0 ? where : undefined,
+      sort: params.order ? { [params.order]: params.desc === false ? 'asc' : 'desc' } : undefined,
+      locale: params.locale ?? 'en',
+      page: params.page,
+      pageSize,
+      select: params.fields,
+      status: 'any',
+    })
+
+    // Decorate each doc with `hasPublishedVersion` so the list UI can show a
+    // "live" indicator on documents that still have a published version
+    // even when the current row is a newer draft. This is admin-bespoke
+    // metadata, so it sits alongside the public ClientDocument shape rather
+    // than inside it.
+    const documentIds = result.docs.map((d) => d.id)
+    const publishedSet =
+      documentIds.length > 0
+        ? await getServerConfig().db.queries.documents.getPublishedDocumentIds({
+            collection_id: config.collection.id,
+            document_ids: documentIds,
+          })
+        : new Set<string>()
+
+    const docs = result.docs.map((d) => ({
+      ...d,
+      hasPublishedVersion: publishedSet.has(d.id),
+    }))
+
+    const response = {
+      docs,
+      meta: {
+        ...result.meta,
+        order: params.order,
+        desc: params.desc,
+      },
+      included: {
+        collection: {
+          id: config.collection.id,
+          path: config.collection.path,
+          labels: {
+            singular: config.definition.labels.singular || config.collection.path,
+            plural: config.definition.labels.plural || config.collection.path,
+          },
+        },
+      },
+    }
+
+    const serialised = serialise(response)
+
+    // Validate with schema for runtime type safety and field normalisation.
+    const { list } = getCollectionSchemasForPath(path)
+    return list.parse(serialised)
+  })

package/src/server-fns/collections/stats.ts

@@ -0,0 +1,52 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import { ensureCollection } from '../../integrations/api-utils.js'
+import { getAdminBylineClient } from '../../integrations/byline-client.js'
+
+// ---------------------------------------------------------------------------
+// Shared types
+// ---------------------------------------------------------------------------
+
+export interface CollectionStatusCount {
+  status: string
+  count: number
+}
+
+// ---------------------------------------------------------------------------
+// Collection stats (per-status document counts)
+// ---------------------------------------------------------------------------
+
+const getCollectionStatsFn = createServerFn({ method: 'GET' })
+  .inputValidator((input: { collection: string }) => input)
+  .handler(async ({ data }) => {
+    const config = await ensureCollection(data.collection)
+    if (!config) return { stats: [] as CollectionStatusCount[] }
+
+    // Routes through CollectionHandle.countByStatus so per-status counts
+    // reflect the actor's beforeRead predicate (multi-tenant scoping,
+    // owner-only drafts, etc).
+    const counts = await getAdminBylineClient().collection(data.collection).countByStatus()
+
+    return { stats: counts as CollectionStatusCount[] }
+  })
+
+/**
+ * Fetch per-status document counts for a collection.
+ * Returns an empty array on any error so the caller can degrade gracefully.
+ */
+export async function getCollectionStats(collection: string): Promise<CollectionStatusCount[]> {
+  try {
+    const result = await getCollectionStatsFn({ data: { collection } })
+    return result.stats
+  } catch {
+    return []
+  }
+}

package/src/server-fns/collections/status.ts

@@ -0,0 +1,102 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import { ERR_NOT_FOUND, getLogger, getServerConfig } from '@byline/core'
+import type { DocumentLifecycleContext } from '@byline/core/services'
+import {
+  changeDocumentStatus,
+  unpublishDocument as unpublishDocumentService,
+} from '@byline/core/services'
+
+import { getAdminRequestContext } from '../../auth/auth-context.js'
+import { ensureCollection } from '../../integrations/api-utils.js'
+
+// ---------------------------------------------------------------------------
+// Change document workflow status
+// ---------------------------------------------------------------------------
+
+export const updateDocumentStatus = createServerFn({ method: 'POST' })
+  .inputValidator((input: { collection: string; id: string; status: string }) => input)
+  .handler(async ({ data: input }) => {
+    const { collection: path, id, status: nextStatus } = input
+    const logger = getLogger()
+    const config = await ensureCollection(path)
+    if (!config) {
+      throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: { collectionPath: path },
+      }).log(logger)
+    }
+
+    const serverConfig = getServerConfig()
+    const ctx: DocumentLifecycleContext = {
+      db: serverConfig.db,
+      definition: config.definition,
+      collectionId: config.collection.id,
+      collectionVersion: config.collection.version,
+      collectionPath: path,
+      logger,
+      defaultLocale: serverConfig.i18n.content.defaultLocale,
+      slugifier: serverConfig.slugifier,
+      requestContext: await getAdminRequestContext(),
+    }
+
+    const result = await changeDocumentStatus(ctx, {
+      documentId: id,
+      nextStatus,
+    })
+    return {
+      status: 'ok' as const,
+      previousStatus: result.previousStatus,
+      newStatus: result.newStatus,
+    }
+  })
+
+// ---------------------------------------------------------------------------
+// Unpublish document (archive the live published version)
+// ---------------------------------------------------------------------------
+
+export const unpublishDocument = createServerFn({ method: 'POST' })
+  .inputValidator((input: { collection: string; id: string }) => input)
+  .handler(async ({ data: input }) => {
+    const { collection: path, id } = input
+    const logger = getLogger()
+    const config = await ensureCollection(path)
+    if (!config) {
+      throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: { collectionPath: path },
+      }).log(logger)
+    }
+
+    const serverConfig = getServerConfig()
+    const ctx: DocumentLifecycleContext = {
+      db: serverConfig.db,
+      definition: config.definition,
+      collectionId: config.collection.id,
+      collectionVersion: config.collection.version,
+      collectionPath: path,
+      logger,
+      defaultLocale: serverConfig.i18n.content.defaultLocale,
+      slugifier: serverConfig.slugifier,
+      requestContext: await getAdminRequestContext(),
+    }
+
+    const result = await unpublishDocumentService(ctx, { documentId: id })
+
+    if (result.archivedCount === 0) {
+      throw ERR_NOT_FOUND({
+        message: 'No published version found for this document',
+        details: { documentId: id, collectionPath: path },
+      }).log(logger)
+    }
+
+    return { status: 'ok' as const, archivedCount: result.archivedCount }
+  })

package/src/server-fns/collections/update.ts

@@ -0,0 +1,67 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import { ERR_NOT_FOUND, getLogger, getServerConfig } from '@byline/core'
+import type { DocumentPatch } from '@byline/core/patches'
+import type { DocumentLifecycleContext } from '@byline/core/services'
+import { updateDocumentWithPatches } from '@byline/core/services'
+
+import { getAdminRequestContext } from '../../auth/auth-context.js'
+import { ensureCollection } from '../../integrations/api-utils.js'
+
+// ---------------------------------------------------------------------------
+// Apply patches (patch-based update — creates a new immutable version)
+// ---------------------------------------------------------------------------
+
+export const updateCollectionDocumentWithPatches = createServerFn({ method: 'POST' })
+  .inputValidator(
+    (input: {
+      collection: string
+      id: string
+      patches: DocumentPatch[]
+      versionId?: string
+      locale?: string
+      path?: string
+    }) => input
+  )
+  .handler(async ({ data: input }) => {
+    const { collection: path, id, patches, versionId, locale, path: explicitPath } = input
+    const logger = getLogger()
+    const config = await ensureCollection(path)
+    if (!config) {
+      throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: { collectionPath: path },
+      }).log(logger)
+    }
+
+    const serverConfig = getServerConfig()
+    const ctx: DocumentLifecycleContext = {
+      db: serverConfig.db,
+      definition: config.definition,
+      collectionId: config.collection.id,
+      collectionVersion: config.collection.version,
+      collectionPath: path,
+      logger,
+      defaultLocale: serverConfig.i18n.content.defaultLocale,
+      slugifier: serverConfig.slugifier,
+      requestContext: await getAdminRequestContext(),
+    }
+
+    await updateDocumentWithPatches(ctx, {
+      documentId: id,
+      patches,
+      documentVersionId: versionId,
+      locale: locale ?? serverConfig.i18n.content.defaultLocale,
+      path: explicitPath,
+    })
+
+    return { status: 'ok' as const }
+  })