@owlmeans/image-resource 0.1.18-rc.42 → 0.1.18-rc.43

package/README.md

@@ -1,47 +1,103 @@
 # @owlmeans/image-resource
 
-Image-specific type extensions for OwlMeans object storage — AJV schemas for image metadata.
-
-## Overview
-
-- `ImageMeta` / `StoredImage` / `ImageData` — typed image record interfaces
-- `ImageMetaSchema` / `StoredImageSchema` / `ImageDataSchema` — AJV JSON schemas for validation
-- Extends `@owlmeans/storage-common` types with image semantics
+Image-shaped names and AJV schemas over the stored-file types of `@owlmeans/storage-common`:
+`ImageMeta`, `StoredImage`, `ImageData` and their schemas. An app uses it to type the record that
+describes an image and to validate an image upload or response against a schema of its own, so a
+signature says it carries an image rather than an arbitrary file. It registers no resource and
+stores nothing: the bytes go to a bucket through `@owlmeans/storage-resource`, the describing record
+goes to a database resource (`@owlmeans/mongo-resource`, `@owlmeans/postgres-resource`), and a
+non-image file uses the `StoredFile*` types of `@owlmeans/storage-common` directly.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/image-resource@^0.1.18-rc.42
+bun add @owlmeans/image-resource@^0.1.18-rc.43
 ```
 
+`ajv` is a peer dependency. Install `@owlmeans/storage-common` explicitly as well — the schemas are
+built from its runtime values, and it is not a declared dependency of this package.
+
+## Concepts
+
+- **Image meta** — `ImageMeta`, the descriptive fields of an image: `entityId?`, `sourceName?`,
+  `name?`, `title?`, `scopes`, `mimeType`, `alias`, `status` (`StoredFileStatus`).
+- **Stored image** — `StoredImage`, the meta plus `instances`: a map of renditions (original,
+  thumbnail, converted format), each `{ size, alias, url }`.
+- **Image data** — `ImageData`, the upload payload: the meta plus `format?` and `instances` whose
+  entries may carry `bytes` or `base64` (`StoredFileFormat`).
+- **Bucket vs. record** — a bucket (`StorageResource`) only accepts an upload and returns a URL; the
+  record that answers criteria, sorting and paging lives in a database resource.
+
 ## Usage
 
+### Validate an upload or a response
+
+```typescript
+import Ajv from 'ajv'
+import { ImageDataSchema, StoredImageSchema } from '@owlmeans/image-resource'
+import type { ImageData, StoredImage } from '@owlmeans/image-resource'
+
+const ajv = new Ajv()
+const validateUpload = ajv.compile<ImageData>(ImageDataSchema)
+const validateImage = ajv.compile<StoredImage>(StoredImageSchema)
+
+if (!validateUpload(payload)) {
+  throw new SyntaxError(ajv.errorsText(validateUpload.errors))
+}
+```
+
+The schemas set `additionalProperties: false`, so an extra field fails validation.
+
+### Keep image records in a database resource
+
 ```typescript
-import { StoredImageSchema, ImageDataSchema } from '@owlmeans/image-resource'
-import type { StoredImage, ImageData } from '@owlmeans/image-resource'
+import type { Resource } from '@owlmeans/resource'
+import type { StoredImage } from '@owlmeans/image-resource'
+
+const images = ctx.resource<Resource<StoredImage>>('images')
+const page = await images.list({ entityId, mimeType: { $startsWith: 'image/' } }, { sort: ['name'], size: 20 })
 
-// Use AJV schema for validation
-const validate = ajv.compile<StoredImage>(StoredImageSchema)
+// Pick a rendition from the map; never derive one url from another
+const thumbnailUrl = page.items[0]?.instances.thumbnail?.url
 ```
 
 ## API
 
 ### Types
 
-- `ImageMeta` — extends `StoredFileMeta` with image-specific fields
-- `StoredImage` — extends `StoredFile` for stored image records
-- `ImageData` — extends `StoredFileWithData` for image upload payloads
+| Symbol | Extends | Purpose |
+|---|---|---|
+| `ImageMeta` | `StoredFileMeta` | descriptive fields of an image |
+| `StoredImage` | `StoredFile` | a stored image with its `instances` renditions |
+| `ImageData` | `StoredFileWithData` | an upload payload carrying bytes or base64 per instance |
 
 ### Schemas
 
-- `ImageMetaSchema: JSONSchemaType<ImageMeta>`
-- `StoredImageSchema: JSONSchemaType<StoredImage>`
-- `ImageDataSchema: JSONSchemaType<ImageData>`
+| Symbol | Type | Built from |
+|---|---|---|
+| `ImageMetaSchema` | `JSONSchemaType<ImageMeta>` | `StoredFileMetaSchema` |
+| `StoredImageSchema` | `JSONSchemaType<StoredImage>` | `StoredFileSchema` |
+| `ImageDataSchema` | `JSONSchemaType<ImageData>` | `StoredFileWithDataSchema` |
+
+Each copies the base schema's `properties` and `required` and closes the object.
+
+## Common pitfalls
+
+- This package registers no resource — `ctx.resource('images')` needs a resource the app registered
+  with a database backend.
+- A bucket accepts only `create`; listing or reading images goes through the record resource.
+- `instances` keys are renditions; read the `url` of the one a screen needs instead of rebuilding a
+  url by string surgery.
+- A missing `@owlmeans/storage-common` install fails at import, since the schemas spread its runtime
+  values.
+
+## Related packages
 
-## Related Packages
+- [`@owlmeans/storage-common`](../storage-common) — `StoredFileMeta`, `StoredFile`, `StoredFileWithData`, their schemas and enums
+- [`@owlmeans/storage-resource`](../storage-resource) — the upload-only bucket resource that stores the bytes
+- [`@owlmeans/resource`](../resource) — the `Resource<T>` contract the image record store implements
 
-- [`@owlmeans/storage-common`](../storage-common) — `StoredFileMeta`, `StoredFile`, `StoredFileWithData` base types
-- [`@owlmeans/storage-resource`](../storage-resource) — S3 resource used to persist images
+The `image-resource` skill covers the same contract for agents.
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -51,7 +107,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.49
+npx @owlmeans/agent-skills@^0.1.18-rc.52
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/image-resource",
-  "version": "0.1.18-rc.42",
-  "generatedAt": "2026-10-05T21:03:06.393Z",
+  "version": "0.1.18-rc.43",
+  "generatedAt": "2026-10-08T21:27:54.300Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/image-resource/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/image-resource
 
 **Layer:** Infra
-**Install:** `"@owlmeans/image-resource": "^0.1.18-rc.42"` in `dependencies` (peer `ajv`)
+**Install:** `"@owlmeans/image-resource": "^0.1.18-rc.43"` in `dependencies` (peer `ajv`)
 
 Types and schemas only — no resource is registered here. An image *is* a stored file
 ([[storage-common]]); this package gives that file image-shaped names so a signature says what it

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@owlmeans/image-resource",
   "type": "module",
-  "version": "0.1.18-rc.42",
+  "version": "0.1.18-rc.43",
   "license": "MIT",
   "scripts": {
     "build": "tsc -b",
@@ -24,7 +24,7 @@
     "ajv": "*"
   },
   "dependencies": {
-    "@owlmeans/storage-resource": "^0.1.18-rc.43"
+    "@owlmeans/storage-resource": "^0.1.18-rc.44"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",