@ossy/resources 3.4.0 → 3.5.1

package/src/reference-field.helpers.spec.js

@@ -0,0 +1,100 @@
+import { describe, expect, it, jest } from '@jest/globals'
+import {
+  commitResourceValue,
+  resourceIdFromValue,
+  resourceIdsFromValue,
+  resourcePickerLabel,
+  sortResourcesForPicker,
+  toReferenceArray,
+} from './reference-field.helpers.js'
+
+describe('reference-field.helpers', () => {
+  describe('resourceIdFromValue', () => {
+    it('reads resourceId from a stored reference object', () => {
+      expect(resourceIdFromValue({ resourceId: 'abc' })).toBe('abc')
+    })
+
+    it('returns null for missing or invalid values', () => {
+      expect(resourceIdFromValue(null)).toBe(null)
+      expect(resourceIdFromValue('abc')).toBe(null)
+      expect(resourceIdFromValue({ resourceId: 1 })).toBe(null)
+      expect(resourceIdFromValue([{ resourceId: 'abc' }])).toBe(null)
+    })
+  })
+
+  describe('resourceIdsFromValue', () => {
+    it('reads resourceIds from a multi-reference array', () => {
+      expect(resourceIdsFromValue([{ resourceId: 'a' }, { resourceId: 'b' }])).toEqual(['a', 'b'])
+    })
+
+    it('skips invalid entries and non-arrays', () => {
+      expect(resourceIdsFromValue(null)).toEqual([])
+      expect(resourceIdsFromValue({ resourceId: 'a' })).toEqual([])
+      expect(resourceIdsFromValue([{ resourceId: 'a' }, null, { resourceId: 1 }, { resourceId: 'b' }])).toEqual([
+        'a',
+        'b',
+      ])
+    })
+  })
+
+  describe('toReferenceArray', () => {
+    it('maps ids to stored reference objects', () => {
+      expect(toReferenceArray(['a', 'b'])).toEqual([{ resourceId: 'a' }, { resourceId: 'b' }])
+    })
+  })
+
+  describe('resourcePickerLabel', () => {
+    it('prefers trimmed name over id', () => {
+      expect(resourcePickerLabel({ id: 'r1', name: '  Author  ' })).toBe('Author')
+    })
+
+    it('falls back to id when name is empty', () => {
+      expect(resourcePickerLabel({ id: 'r1', name: '   ' })).toBe('r1')
+      expect(resourcePickerLabel({ id: 'r1' })).toBe('r1')
+    })
+  })
+
+  describe('sortResourcesForPicker', () => {
+    it('sorts by label case-insensitively', () => {
+      const sorted = sortResourcesForPicker([
+        { id: '2', name: 'zeta' },
+        { id: '1', name: 'Alpha' },
+        { id: '3', name: 'beta' },
+      ])
+      expect(sorted.map(r => r.id)).toEqual(['1', '3', '2'])
+    })
+
+    it('returns empty array for non-arrays', () => {
+      expect(sortResourcesForPicker(null)).toEqual([])
+    })
+  })
+
+  describe('commitResourceValue', () => {
+    it('emits a file-replace shaped change event', () => {
+      const onChange = jest.fn()
+      commitResourceValue('author', { resourceId: 'r1' }, onChange)
+      expect(onChange).toHaveBeenCalledWith({
+        target: {
+          id: 'author',
+          name: 'author',
+          dataset: { ossyFileResourceReplace: 'true' },
+          value: JSON.stringify({ resourceId: 'r1' }),
+        },
+      })
+    })
+
+    it('emits arrays for multi-reference values', () => {
+      const onChange = jest.fn()
+      const value = toReferenceArray(['a', 'b'])
+      commitResourceValue('authors', value, onChange)
+      expect(onChange).toHaveBeenCalledWith({
+        target: {
+          id: 'authors',
+          name: 'authors',
+          dataset: { ossyFileResourceReplace: 'true' },
+          value: JSON.stringify([{ resourceId: 'a' }, { resourceId: 'b' }]),
+        },
+      })
+    })
+  })
+})

package/src/resource-download.js

@@ -0,0 +1,194 @@
+/**
+ * Download helpers for workspace resources (`/r/{id}?download=1`).
+ */
+
+const DIRECTORY_TYPES = new Set(['directory', '@ossy/platform/schema/directory'])
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isTruthyDownloadQuery (value) {
+  if (value === true || value === 1) return true
+  if (typeof value !== 'string') return false
+  const normalized = value.trim().toLowerCase()
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'download'
+}
+
+/**
+ * @param {{ query?: Record<string, unknown> } | null | undefined} req
+ * @returns {boolean}
+ */
+export function wantsAttachmentDownload (req) {
+  const query = req?.query ?? {}
+  return isTruthyDownloadQuery(query.download)
+}
+
+/**
+ * @param {object | null | undefined} resource
+ * @returns {boolean}
+ */
+export function isDirectoryResource (resource) {
+  return DIRECTORY_TYPES.has(resource?.type)
+}
+
+/**
+ * Non-directory resources can be downloaded (file bytes or JSON content).
+ *
+ * @param {object | null | undefined} resource
+ * @returns {boolean}
+ */
+export function isDownloadableResource (resource) {
+  if (!resource?.id) return false
+  if (isDirectoryResource(resource)) return false
+  return true
+}
+
+/**
+ * App-relative download URL for a resource.
+ *
+ * @param {string | { id?: string }} resourceOrId
+ * @returns {string | null}
+ */
+export function resourceDownloadHref (resourceOrId) {
+  const id = typeof resourceOrId === 'string' ? resourceOrId : resourceOrId?.id
+  if (!id) return null
+  return `/r/${encodeURIComponent(id)}?download=1`
+}
+
+/**
+ * Sanitize a filename for Content-Disposition (ASCII fallback).
+ *
+ * @param {string | null | undefined} name
+ * @param {{ fallback?: string, ensureExtension?: string }} [options]
+ * @returns {string}
+ */
+export function sanitizeDownloadFilename (name, { fallback = 'download', ensureExtension } = {}) {
+  let base = String(name || '')
+    .replace(/[\r\n\0\"\\]/g, '')
+    .replace(/[\/\\?%*:|"<>]/g, '-')
+    .trim()
+  if (!base) base = fallback
+  if (ensureExtension) {
+    const ext = ensureExtension.startsWith('.') ? ensureExtension : `.${ensureExtension}`
+    if (!base.toLowerCase().endsWith(ext.toLowerCase())) {
+      base = `${base}${ext}`
+    }
+  }
+  return base.slice(0, 180)
+}
+
+/**
+ * Build a Content-Disposition attachment header value.
+ *
+ * @param {string | null | undefined} filename
+ * @returns {string}
+ */
+export function contentDispositionAttachment (filename) {
+  const safe = sanitizeDownloadFilename(filename)
+  const encoded = encodeURIComponent(safe)
+  return `attachment; filename="${safe}"; filename*=UTF-8''${encoded}`
+}
+
+/**
+ * Filename used when streaming a download response.
+ *
+ * @param {object | null | undefined} resource
+ * @returns {string}
+ */
+export function downloadFilenameForResource (resource) {
+  const hasFileKey = Boolean(resource?.content?.Key)
+  if (hasFileKey) {
+    return sanitizeDownloadFilename(resource?.name, { fallback: 'download' })
+  }
+  return sanitizeDownloadFilename(resource?.name, { fallback: 'resource', ensureExtension: '.json' })
+}
+
+/**
+ * Trigger a browser download for a resource (client-side).
+ *
+ * @param {object | null | undefined} resource
+ * @returns {boolean} whether a download was started
+ */
+export function triggerResourceDownload (resource) {
+  if (typeof document === 'undefined') return false
+  if (!isDownloadableResource(resource)) return false
+  const href = resourceDownloadHref(resource)
+  if (!href) return false
+  const a = document.createElement('a')
+  a.href = href
+  a.download = downloadFilenameForResource(resource)
+  a.rel = 'noopener'
+  document.body.appendChild(a)
+  a.click()
+  a.remove()
+  return true
+}
+
+/**
+ * Fetch a resource as a blob and trigger a local file download.
+ * Used for batch downloads so later files are not blocked after the user-gesture window ends.
+ *
+ * @param {object | null | undefined} resource
+ * @returns {Promise<boolean>}
+ */
+export async function triggerResourceBlobDownload (resource) {
+  if (typeof document === 'undefined' || typeof fetch !== 'function') return false
+  if (!isDownloadableResource(resource)) return false
+  const href = resourceDownloadHref(resource)
+  if (!href) return false
+
+  const response = await fetch(href, { credentials: 'same-origin' })
+  if (!response.ok) {
+    throw Object.assign(new Error(`Download failed (${response.status})`), { status: response.status })
+  }
+
+  const blob = await response.blob()
+  const objectUrl = URL.createObjectURL(blob)
+  try {
+    const a = document.createElement('a')
+    a.href = objectUrl
+    a.download = downloadFilenameForResource(resource)
+    a.rel = 'noopener'
+    document.body.appendChild(a)
+    a.click()
+    a.remove()
+  } finally {
+    // Keep the object URL alive briefly so the browser can start the download.
+    setTimeout(() => URL.revokeObjectURL(objectUrl), 2_000)
+  }
+  return true
+}
+
+/**
+ * @param {Array<object | null | undefined> | null | undefined} resources
+ * @returns {object[]}
+ */
+export function filterDownloadableResources (resources) {
+  return (resources || []).filter(isDownloadableResource)
+}
+
+/**
+ * Trigger browser downloads for many resources via blob fetches.
+ * Anchor-click staggering fails after the first file because browsers revoke
+ * the user-gesture token once the click handler yields.
+ *
+ * @param {Array<object | null | undefined> | null | undefined} resources
+ * @param {{ delayMs?: number }} [options]
+ * @returns {Promise<number>} number of downloads started
+ */
+export async function triggerResourceDownloads (resources, { delayMs = 300 } = {}) {
+  const downloadable = filterDownloadableResources(resources)
+  let started = 0
+  for (let i = 0; i < downloadable.length; i += 1) {
+    try {
+      if (await triggerResourceBlobDownload(downloadable[i])) started += 1
+    } catch (error) {
+      console.error('[resources] batch download failed', downloadable[i]?.id, error)
+    }
+    if (delayMs > 0 && i < downloadable.length - 1) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs))
+    }
+  }
+  return started
+}

package/src/resource-download.spec.js

@@ -0,0 +1,93 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  contentDispositionAttachment,
+  downloadFilenameForResource,
+  filterDownloadableResources,
+  isDirectoryResource,
+  isDownloadableResource,
+  isTruthyDownloadQuery,
+  resourceDownloadHref,
+  sanitizeDownloadFilename,
+  wantsAttachmentDownload,
+} from './resource-download.js'
+
+describe('resource-download', () => {
+  describe('isTruthyDownloadQuery', () => {
+    it('accepts common truthy download flags', () => {
+      expect(isTruthyDownloadQuery('1')).toBe(true)
+      expect(isTruthyDownloadQuery('true')).toBe(true)
+      expect(isTruthyDownloadQuery('yes')).toBe(true)
+      expect(isTruthyDownloadQuery('download')).toBe(true)
+      expect(isTruthyDownloadQuery(true)).toBe(true)
+    })
+
+    it('rejects falsy values', () => {
+      expect(isTruthyDownloadQuery('0')).toBe(false)
+      expect(isTruthyDownloadQuery('false')).toBe(false)
+      expect(isTruthyDownloadQuery('')).toBe(false)
+      expect(isTruthyDownloadQuery(undefined)).toBe(false)
+    })
+  })
+
+  describe('wantsAttachmentDownload', () => {
+    it('reads download from req.query', () => {
+      expect(wantsAttachmentDownload({ query: { download: '1' } })).toBe(true)
+      expect(wantsAttachmentDownload({ query: {} })).toBe(false)
+      expect(wantsAttachmentDownload(null)).toBe(false)
+    })
+  })
+
+  describe('resource classification', () => {
+    it('detects directories', () => {
+      expect(isDirectoryResource({ type: 'directory' })).toBe(true)
+      expect(isDirectoryResource({ type: '@ossy/platform/schema/directory' })).toBe(true)
+      expect(isDirectoryResource({ type: '@ossy/platform/schema/file' })).toBe(false)
+    })
+
+    it('marks non-directory resources as downloadable', () => {
+      expect(isDownloadableResource({ id: 'abc', type: '@ossy/platform/schema/file' })).toBe(true)
+      expect(isDownloadableResource({ id: 'abc', type: 'directory' })).toBe(false)
+      expect(isDownloadableResource({ type: '@ossy/platform/schema/file' })).toBe(false)
+    })
+  })
+
+  describe('resourceDownloadHref', () => {
+    it('builds /r/{id}?download=1', () => {
+      expect(resourceDownloadHref('res_1')).toBe('/r/res_1?download=1')
+      expect(resourceDownloadHref({ id: 'res_2' })).toBe('/r/res_2?download=1')
+      expect(resourceDownloadHref({})).toBe(null)
+    })
+  })
+
+  describe('filenames', () => {
+    it('sanitizes unsafe characters', () => {
+      expect(sanitizeDownloadFilename('a/b:c*.png')).toBe('a-b-c-.png')
+      expect(sanitizeDownloadFilename('evil\\name')).toBe('evilname')
+      expect(sanitizeDownloadFilename('')).toBe('download')
+    })
+
+    it('adds .json for document resources without Key', () => {
+      expect(downloadFilenameForResource({ name: 'Author', content: { title: 'x' } }))
+        .toBe('Author.json')
+      expect(downloadFilenameForResource({ name: 'photo.png', content: { Key: 'abc' } }))
+        .toBe('photo.png')
+    })
+
+    it('builds Content-Disposition attachment header', () => {
+      const header = contentDispositionAttachment('resume.pdf')
+      expect(header).toContain('attachment;')
+      expect(header).toContain('filename="resume.pdf"')
+      expect(header).toContain("filename*=UTF-8''resume.pdf")
+    })
+  })
+
+  describe('batch helpers', () => {
+    it('filters downloadable resources', () => {
+      expect(filterDownloadableResources([
+        { id: '1', type: '@ossy/platform/schema/file' },
+        { id: '2', type: 'directory' },
+        { type: '@ossy/platform/schema/file' },
+      ]).map((r) => r.id)).toEqual(['1'])
+    })
+  })
+})

package/src/resource-read.helpers.js

@@ -3,6 +3,7 @@ import { StorageClient } from '@ossy/platform'
 import { derivativeObjectKey } from '@ossy/platform/storage-keys'
 import { Workspace } from '@ossy/workspaces/server'
 import { attachResourceMediaUrls } from './resources.attach-media-urls.js'
+import { attachResourceReferenceLinks } from './resources.attach-reference-links.js'
 import { viewResource } from './resource-stream.helpers.js'
 
 export function resolveResourceId({ payload, req } = {}) {
@@ -88,10 +89,13 @@ export async function loadResourceForRead(resourceId, req) {
 
   await assertResourceAccess(resource, req)
 
-  return attachResourceMediaUrls(resource, {
+  const withMedia = await attachResourceMediaUrls(resource, {
     userId: req?.userId,
     workspaceId: req?.workspaceId,
   })
+  return attachResourceReferenceLinks(withMedia, {
+    workspaceId: req?.workspaceId ?? resource.belongsTo,
+  })
 }
 
 /**

package/src/resource-selection.js

@@ -0,0 +1,91 @@
+/**
+ * Multi-select helpers for storage resource lists (Cmd/Ctrl toggle, Shift range).
+ */
+
+/**
+ * @param {MouseEvent | { metaKey?: boolean, ctrlKey?: boolean, shiftKey?: boolean } | null | undefined} event
+ * @returns {boolean}
+ */
+export function isToggleSelectModifier (event) {
+  return Boolean(event?.metaKey || event?.ctrlKey)
+}
+
+/**
+ * @param {MouseEvent | { shiftKey?: boolean } | null | undefined} event
+ * @returns {boolean}
+ */
+export function isRangeSelectModifier (event) {
+  return Boolean(event?.shiftKey)
+}
+
+/**
+ * @param {MouseEvent | { metaKey?: boolean, ctrlKey?: boolean, shiftKey?: boolean } | null | undefined} event
+ * @returns {boolean}
+ */
+export function isMultiSelectGesture (event) {
+  return isToggleSelectModifier(event) || isRangeSelectModifier(event)
+}
+
+/**
+ * Inclusive range of ids between two anchors in the visible ordered list.
+ *
+ * @param {string[]} orderedIds
+ * @param {string | null | undefined} fromId
+ * @param {string | null | undefined} toId
+ * @returns {string[]}
+ */
+export function idsInRange (orderedIds, fromId, toId) {
+  if (!orderedIds?.length || !toId) return toId ? [toId] : []
+  const end = orderedIds.indexOf(toId)
+  if (end < 0) return [toId]
+  const start = fromId ? orderedIds.indexOf(fromId) : end
+  if (start < 0) return [toId]
+  const from = Math.min(start, end)
+  const to = Math.max(start, end)
+  return orderedIds.slice(from, to + 1)
+}
+
+/**
+ * Apply a selection gesture to the current multi-select set.
+ *
+ * @param {{
+ *   selectedIds: Iterable<string>,
+ *   orderedIds: string[],
+ *   targetId: string,
+ *   event?: { metaKey?: boolean, ctrlKey?: boolean, shiftKey?: boolean } | null,
+ *   anchorId?: string | null,
+ * }} params
+ * @returns {{ nextSelectedIds: Set<string>, nextAnchorId: string | null }}
+ */
+export function applyResourceSelectionGesture ({
+  selectedIds,
+  orderedIds,
+  targetId,
+  event,
+  anchorId = null,
+}) {
+  const current = new Set(selectedIds || [])
+
+  if (isRangeSelectModifier(event)) {
+    const range = idsInRange(orderedIds, anchorId || targetId, targetId)
+    for (const id of range) current.add(id)
+    return {
+      nextSelectedIds: current,
+      nextAnchorId: anchorId || targetId,
+    }
+  }
+
+  if (isToggleSelectModifier(event)) {
+    if (current.has(targetId)) current.delete(targetId)
+    else current.add(targetId)
+    return {
+      nextSelectedIds: current,
+      nextAnchorId: targetId,
+    }
+  }
+
+  return {
+    nextSelectedIds: new Set([targetId]),
+    nextAnchorId: targetId,
+  }
+}

package/src/resource-selection.spec.js

@@ -0,0 +1,77 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  applyResourceSelectionGesture,
+  idsInRange,
+  isMultiSelectGesture,
+  isRangeSelectModifier,
+  isToggleSelectModifier,
+} from './resource-selection.js'
+
+describe('resource-selection', () => {
+  const orderedIds = ['a', 'b', 'c', 'd']
+
+  describe('modifiers', () => {
+    it('detects toggle and range gestures', () => {
+      expect(isToggleSelectModifier({ metaKey: true })).toBe(true)
+      expect(isToggleSelectModifier({ ctrlKey: true })).toBe(true)
+      expect(isRangeSelectModifier({ shiftKey: true })).toBe(true)
+      expect(isMultiSelectGesture({ metaKey: true })).toBe(true)
+      expect(isMultiSelectGesture({ shiftKey: true })).toBe(true)
+      expect(isMultiSelectGesture({})).toBe(false)
+    })
+  })
+
+  describe('idsInRange', () => {
+    it('returns inclusive slice between anchors', () => {
+      expect(idsInRange(orderedIds, 'b', 'd')).toEqual(['b', 'c', 'd'])
+      expect(idsInRange(orderedIds, 'd', 'b')).toEqual(['b', 'c', 'd'])
+      expect(idsInRange(orderedIds, null, 'c')).toEqual(['c'])
+    })
+  })
+
+  describe('applyResourceSelectionGesture', () => {
+    it('replaces selection on plain click', () => {
+      const result = applyResourceSelectionGesture({
+        selectedIds: ['a', 'b'],
+        orderedIds,
+        targetId: 'c',
+        event: {},
+        anchorId: 'a',
+      })
+      expect([...result.nextSelectedIds]).toEqual(['c'])
+      expect(result.nextAnchorId).toBe('c')
+    })
+
+    it('toggles with meta/ctrl', () => {
+      const add = applyResourceSelectionGesture({
+        selectedIds: ['a'],
+        orderedIds,
+        targetId: 'c',
+        event: { metaKey: true },
+        anchorId: 'a',
+      })
+      expect(new Set(add.nextSelectedIds)).toEqual(new Set(['a', 'c']))
+
+      const remove = applyResourceSelectionGesture({
+        selectedIds: ['a', 'c'],
+        orderedIds,
+        targetId: 'a',
+        event: { ctrlKey: true },
+        anchorId: 'c',
+      })
+      expect([...remove.nextSelectedIds]).toEqual(['c'])
+    })
+
+    it('extends with shift from the anchor', () => {
+      const result = applyResourceSelectionGesture({
+        selectedIds: ['a'],
+        orderedIds,
+        targetId: 'c',
+        event: { shiftKey: true },
+        anchorId: 'a',
+      })
+      expect([...result.nextSelectedIds]).toEqual(['a', 'b', 'c'])
+      expect(result.nextAnchorId).toBe('a')
+    })
+  })
+})

package/src/resource-upload-access.js

@@ -0,0 +1,63 @@
+import { Aggregate } from '@ossy/event-store'
+import { Workspace } from '@ossy/workspaces/server'
+import { viewResource } from './resource-stream.helpers.js'
+
+/**
+ * Storage keys are `{resourceId}` or `{resourceId}:{variant}`.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+export function resourceIdFromStorageKey(key) {
+  if (!key || typeof key !== 'string') {
+    throw Object.assign(new Error('Invalid storage key'), { status: 400 })
+  }
+  const colon = key.indexOf(':')
+  return colon === -1 ? key : key.slice(0, colon)
+}
+
+/**
+ * Assert the caller may PUT bytes for an existing resource (local-storage upload).
+ * Requires authenticated workspace membership — public access never grants upload.
+ *
+ * @param {object} resource
+ * @param {{ userId?: string, workspaceId?: string }} req
+ */
+export async function assertResourceUploadAccess(resource, req) {
+  const userId = req?.userId
+  const workspaceId = req?.workspaceId
+
+  if (!userId || userId === 'anonymous') {
+    throw Object.assign(new Error('Unauthorized'), { status: 401 })
+  }
+
+  if (!workspaceId) {
+    throw Object.assign(new Error('Forbidden'), { status: 403 })
+  }
+
+  if (!resource?.id || resource.belongsTo !== workspaceId) {
+    throw Object.assign(new Error('Forbidden'), { status: 403 })
+  }
+
+  const workspace = await Aggregate.Of(Workspace, workspaceId).then(Aggregate.View())
+  if (!workspace?.users?.includes(userId)) {
+    throw Object.assign(new Error('Forbidden'), { status: 403 })
+  }
+}
+
+/**
+ * Load resource for a storage key and assert upload permission.
+ *
+ * @param {string} storageKey
+ * @param {{ userId?: string, workspaceId?: string }} req
+ * @returns {Promise<object>}
+ */
+export async function assertUploadAccessForStorageKey(storageKey, req) {
+  const resourceId = resourceIdFromStorageKey(storageKey)
+  const resource = await viewResource(resourceId)
+  if (!resource?.id) {
+    throw Object.assign(new Error('Resource not found'), { status: 404 })
+  }
+  await assertResourceUploadAccess(resource, req)
+  return resource
+}