@happyvertical/smrt-assets 0.30.0

package/AGENTS.md

@@ -0,0 +1,78 @@
+# @happyvertical/smrt-assets
+
+Provider-agnostic asset management with versioning, type classification, and generic/provenance associations.
+
+## Models
+
+- **Asset** (STI base): versioning via `primaryVersionId` chain + `version` number. `ownerProfileId`, `typeSlug`, `statusSlug`, `mimeType`, `sourceUri`. Derivation chain via `sourceAssetId` (R3-D — was `parentId` before the rename; column `source_asset_id`).
+- **AssetType** / **AssetStatus**: lookup tables for classification and lifecycle.
+- **AssetMetafield**: custom metadata field definitions with JSON validation rules.
+- **Folder**: hierarchical container for assets. Own `SmrtHierarchical` model with its own `folders` table (R3-D — was an STI subclass of Asset before). `Asset.folderId` points to the folder.
+- **AssetAssociation**: generic/provenance polymorphic join — `assetId` + `metaType` + `metaId` + `role` + `sortOrder`. Use it when a relationship is not owned by a base/domain model join table like `content_assets`, `profile_assets`, `event_assets`, `place_assets`, or `product_assets`.
+
+## Key Patterns
+
+- **Versioning**: `createNewVersion()` increments version, chains via `primaryVersionId`. `findVersions()` to retrieve history.
+- **Tag integration**: `addTag()`/`removeTag()` use raw `db.upsert()` on `asset_tags` join table (not a SMRT model).
+- **AssetStore**: abstraction for provider-agnostic file I/O (S3, local, etc.).
+- **Ownership rule**: base/domain-owned asset relationships should live on noun join tables such as `content_assets`, `profile_assets`, `event_assets`, `place_assets`, and `product_assets`; keep `AssetAssociation` for generic/provenance links like image derivation.
+
+## Runtime surface
+
+Apps and agents should depend on the public **asset runtime** rather than hand-wiring a collection + store per-package (#1128).
+
+- `createAssetRuntime({ db, storage })` → `AssetRuntime` bundling `AssetCollection`, `AssetAssociationCollection`, and an initialized `AssetStore`.
+- `AssetRuntime.storeSourceAsset(name, data, opts)` — create a new source asset (record + bytes).
+- `AssetRuntime.storeDerivedAsset(source, name, data, opts)` — create a derivative with `sourceAssetId` set and (by default) a provenance `AssetAssociation` under a chosen role.
+- `AssetRuntime.linkDerivation(source, derivative, { role })` — record provenance without touching bytes.
+- `AssetRuntime.setExtractionStatus(asset, status, { error?, extractedAt? })` — write canonical extraction metadata into the asset's description JSON sidecar. Non-destructive: if `description` is free-form prose or non-object JSON, the original value is preserved under the reserved `text` key instead of being overwritten. Existing JSON objects are merged into.
+
+Agents that need asset I/O should accept an `AssetRuntimeLike` in their options rather than asking callers to pass a store + collection separately.
+
+## Serving contract
+
+- `serveAsset({ runtime, asset, tenantId?, disposition?, canAccess?, headers?, remoteMode? })` → standard Web `Response`.
+  - `404` when the id doesn't resolve; `403` when the tenant mismatches or `canAccess` denies; `302` when `remoteMode: 'redirect'` and the asset's `sourceUri` is `http(s)`; `502` when `remoteMode: 'proxy'` and the origin fetch fails; `500` on store read errors or unexpected failures; `200` otherwise with `Content-Type`, `Content-Length`, and `Content-Disposition` set.
+  - Assets whose `sourceUri` is `http(s)` are supported via `remoteMode`: `'proxy'` (default, fetch and return bytes), `'redirect'` (302 to the origin), or `'error'` (treat as misconfiguration). Pass `fetchImpl` to swap the fetch client.
+  - `Content-Disposition` filenames are sanitised (control characters stripped, `"` / `\` / `/` replaced) to prevent header injection on untrusted asset names.
+  - The 500 body is a generic `'Internal error serving asset'`; the underlying error is logged via `console.error` so operators can debug without leaking paths/bucket names to clients.
+  - Works in SvelteKit `+server.ts` endpoints, Hono, and any runtime with a global `Response` (Node 18+). Pass `responseCtor` for older runtimes.
+- `resolveAssetForServing(options)` → `{ asset, data, contentType, filename, size }` when callers want to render their own framework response. Throws `AssetServeError(status)` on the same failure modes.
+
+## Source/derived vocabulary
+
+The following roles are exported as `ASSET_ROLES` and should be preferred over ad-hoc strings when apps want cross-package tooling (serving, UI pickers) to agree on meaning:
+
+| Role | Use |
+|------|-----|
+| `source_document` | original upstream document (agenda PDF, minutes) |
+| `document_image` | page/extracted image derived from a source document |
+| `thumbnail` | preview rendition of another asset |
+| `proof` | non-canonical evidence asset backing a fact |
+| `derivation_source` | "came from" link on generated media |
+| `attachment` | generic owner-join link |
+| `hero` | primary/featured asset on an owner |
+
+Canonical metadata keys are exported as `ASSET_METADATA_KEYS`: `extractionStatus`, `extractionError`, `extractedAt`, `sourceUrl`, `sourceHash`, `pageNumber`. Extraction status values live in `ASSET_EXTRACTION_STATUS` (`pending | running | succeeded | failed`).
+
+## UI Registry
+
+The `./ui` subpath exports `ASSETS_MODULE_META` and `ASSETS_UI_SLOTS` so registry-driven hosts (smrt-chat, dynamic admin shells) can discover the package's Svelte components without a hard import.
+
+```ts
+import { ASSETS_MODULE_META, ASSETS_UI_SLOTS } from '@happyvertical/smrt-assets/ui';
+import '@happyvertical/smrt-assets/svelte'; // side-effect: ModuleUIRegistry.register(...)
+import { ModuleUIRegistry } from '@happyvertical/smrt-svelte/registry';
+
+const AssetManager = ModuleUIRegistry.get('@happyvertical/smrt-assets', 'asset-manager');
+```
+
+Registered slots: `asset-manager` (admin), `asset-grid` / `asset-list` (list), `asset-detail` (detail), `asset-toolbar` / `asset-action-bar` (action), `asset-create-modal` (form). Slot IDs are stable contracts — host apps reference them by string.
+
+## Gotchas
+
+- **Version history manual**: `findVersions()` chaining required — no ORM shortcut
+- **Tag management uses raw SQL**: `asset_tags` is a join table, not an SMRT model
+- **Folder tree traversal**: via `SmrtHierarchical` (`getParent`/`getChildren`/`getAncestors`/`getDescendants`/`getHierarchy`/`moveTo`); `FolderCollection.getTree(rootId?)` and `getPath(folderId)` wrap these for convenience
+- **AssetAssociation polymorphic FK**: requires manual `metaType` string matching
+- **Optional tenancy**: assets can be global (tenantId=null) or tenant-scoped

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# @happyvertical/smrt-assets
+
+Provider-agnostic asset management with versioning, type classification, metadata fields, and generic/provenance associations.
+
+`AssetAssociation` is the generic exception path for linking assets to arbitrary
+objects when there is not a model-owned noun join table. Base/domain-owned
+relationships should use dedicated joins such as `content_assets`,
+`profile_assets`, `event_assets`, `place_assets`, and `product_assets`.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-assets
+```
+
+## Usage
+
+```typescript
+import {
+  Asset, AssetCollection,
+  AssetType, AssetStatus, AssetMetafield,
+  AssetAssociation, AssetAssociationCollection,
+  Folder, FolderCollection,
+  AssetStore,
+} from '@happyvertical/smrt-assets';
+
+// Create lookup records
+const imageType = new AssetType({ slug: 'image', name: 'Image' });
+await imageType.save();
+
+const published = new AssetStatus({ slug: 'published', name: 'Published' });
+await published.save();
+
+// Create an asset
+const photo = new Asset({
+  name: 'Product Photo',
+  slug: 'product-photo-001',
+  sourceUri: 's3://bucket/products/photo-001.jpg',
+  mimeType: 'image/jpeg',
+  typeSlug: 'image',
+  statusSlug: 'published',
+  version: 1,
+});
+await photo.save();
+
+// Versioning -- chain via primaryVersionId, increment version number
+const v2 = new Asset({
+  ...photo, slug: 'product-photo-002', version: 2, primaryVersionId: photo.id,
+  sourceUri: 's3://bucket/products/photo-002.jpg',
+});
+await v2.save();
+
+// Derivatives via sourceAssetId (renamed from `parentId` in R3-D)
+const thumb = new Asset({
+  name: 'Thumbnail', slug: 'product-photo-001-thumb', sourceAssetId: photo.id,
+  sourceUri: 's3://bucket/products/photo-001-thumb.jpg',
+  mimeType: 'image/jpeg', typeSlug: 'image', statusSlug: 'published',
+});
+await thumb.save();
+
+// Generic/provenance association -- link asset to an arbitrary object
+const assoc = new AssetAssociation({
+  assetId: photo.id,
+  metaType: 'Image',
+  metaId: 'derived-image-123',
+  role: 'derivation-source',
+  sortOrder: 0,
+});
+await assoc.save();
+
+// Base/domain-owned asset relationships should use dedicated noun joins instead:
+// content_assets, profile_assets, event_assets, place_assets, product_assets
+
+// Folder organization (its own SmrtHierarchical model, `folders` table)
+const folder = new Folder({ name: 'Product Images', slug: 'product-images' });
+await folder.save();
+// Move an asset into a folder
+photo.folderId = folder.id;
+await photo.save();
+
+// AssetStore -- provider-agnostic file I/O + record creation
+const store = new AssetStore({ collection, filesystem });
+await store.store({ buffer, mimeType: 'image/png', name: 'screenshot' });
+```
+
+## API
+
+### Models (SmrtObject)
+
+| Export | Description |
+|--------|------------|
+| `Asset` | Core asset with versioning (`primaryVersionId`, `version`), derivation chain (`sourceAssetId`), `sourceUri`, `mimeType`, `typeSlug`, `statusSlug`, `ownerProfileId` |
+| `AssetAssociation` | Generic/provenance polymorphic join: `assetId` + `metaType` + `metaId` + `role` + `sortOrder`; not for base/domain-owned joins that already have noun tables |
+| `AssetType` | Lookup table for asset type classification |
+| `AssetStatus` | Lookup table for lifecycle status |
+| `AssetMetafield` | Custom metadata field definitions with JSON validation rules |
+| `Folder` | Hierarchical container for assets; own `folders` table extending `SmrtHierarchical` |
+
+### Collections (SmrtCollection)
+
+| Export | Description |
+|--------|------------|
+| `AssetCollection` | Collection for Asset |
+| `AssetAssociationCollection` | Collection for AssetAssociation |
+| `AssetTypeCollection` | Collection for AssetType |
+| `AssetStatusCollection` | Collection for AssetStatus |
+| `AssetMetafieldCollection` | Collection for AssetMetafield |
+| `FolderCollection` | Collection for Folder |
+
+### Utilities
+
+| Export | Description |
+|--------|------------|
+| `AssetStore` | Provider-agnostic file I/O that writes buffers to storage and creates Asset records |
+
+### Types
+
+| Export | Description |
+|--------|------------|
+| `AssetOptions` | Options for `Asset` constructor |
+| `AssetAssociationOptions` | Options for `AssetAssociation` constructor |
+| `AssetTypeOptions` | Options for `AssetType` constructor |
+| `AssetStatusOptions` | Options for `AssetStatus` constructor |
+| `AssetMetafieldOptions` | Options for `AssetMetafield` constructor |
+| `FolderOptions` | Options for `Folder` constructor |
+| `StoreOptions` | Options for `AssetStore.store()` |
+| `ProviderOptions` | Provider configuration for `AssetStore` |
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@happyvertical/smrt-core` | ORM base (SmrtObject, SmrtCollection) |
+| `@happyvertical/smrt-tags` | Tag integration (`addTag`/`removeTag` on assets) |
+| `@happyvertical/smrt-tenancy` | Optional tenant scoping |
+| `@happyvertical/files` | Provider-agnostic filesystem for AssetStore |

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/asset-association.d.ts

@@ -0,0 +1,16 @@
+import { SmrtPolymorphicAssociation } from '@happyvertical/smrt-core';
+import { AssetAssociationOptions } from './types';
+export declare class AssetAssociation extends SmrtPolymorphicAssociation {
+    /**
+     * Optional tenant scope. Without this, the generated `api`/`mcp` `create`
+     * routes let any caller forge a polymorphic link between an asset and an
+     * arbitrary object across tenant boundaries — the #1540 generated-route
+     * tenant-context fix only filters models that ARE `@TenantScoped`, so this
+     * model must opt in to be covered (S5 #1396).
+     */
+    tenantId: string | null;
+    /** FK to Asset.id */
+    assetId: string;
+    constructor(options?: AssetAssociationOptions);
+}
+//# sourceMappingURL=asset-association.d.ts.map

package/dist/asset-association.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-association.d.ts","sourceRoot":"","sources":["../src/asset-association.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,0BAA0B,EAE3B,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEvD,qBAOa,gBAAiB,SAAQ,0BAA0B;IAC9D;;;;;;OAMG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,qBAAqB;IAErB,OAAO,SAAM;gBAED,OAAO,GAAE,uBAA4B;CAKlD"}

package/dist/asset-associations.d.ts

@@ -0,0 +1,27 @@
+import { JunctionAttachOptions, JunctionFilterOptions, SmrtJunction } from '@happyvertical/smrt-core';
+import { AssetAssociation } from './asset-association';
+export declare class AssetAssociationCollection extends SmrtJunction<AssetAssociation> {
+    static readonly _itemClass: typeof AssetAssociation;
+    protected leftField: string;
+    protected rightField: string;
+    /**
+     * List associations for a polymorphic owner.
+     *
+     * Composite left key — pass both halves.
+     */
+    byLeft(metaType: string, metaId: string, opts?: JunctionFilterOptions): Promise<AssetAssociation[]>;
+    /**
+     * Create an association. Composite left (metaType, metaId) precedes right (assetId).
+     */
+    attach(metaType: string, metaId: string, assetId: string, opts?: JunctionAttachOptions): Promise<AssetAssociation>;
+    /**
+     * Delete matching associations. Composite left (metaType, metaId) precedes right (assetId).
+     */
+    detach(metaType: string, metaId: string, assetId: string, opts?: JunctionFilterOptions): Promise<void>;
+    /**
+     * Replace all associations for a polymorphic owner with the given asset IDs.
+     * Not transactional — see `SmrtJunction.setLinks` for caveats.
+     */
+    setLinks(metaType: string, metaId: string, assetIds: string[], opts?: JunctionAttachOptions): Promise<void>;
+}
+//# sourceMappingURL=asset-associations.d.ts.map

package/dist/asset-associations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-associations.d.ts","sourceRoot":"","sources":["../src/asset-associations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,YAAY,EAEb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAMvD,qBACa,0BAA2B,SAAQ,YAAY,CAAC,gBAAgB,CAAC;IAC5E,MAAM,CAAC,QAAQ,CAAC,UAAU,0BAAoB;IAK9C,SAAS,CAAC,SAAS,SAAY;IAC/B,SAAS,CAAC,UAAU,SAAa;IAEjC;;;;OAIG;IAEG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAQ9B;;OAEG;IAEG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,gBAAgB,CAAC;IAU5B;;OAEG;IAEG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,IAAI,CAAC;IAShB;;;OAGG;IAEG,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,IAAI,CAAC;CAuBjB"}

package/dist/asset-capabilities.d.ts

@@ -0,0 +1,137 @@
+import { Asset } from './asset';
+import { AssetAssociationCollection } from './asset-associations';
+import { AssetStore, StoreOptions } from './asset-store';
+import { AssetCollection } from './assets';
+export type AssetVariantFit = 'cover' | 'contain' | 'inside';
+export type AssetCapabilitySource = 'cached' | 'generated' | 'external';
+export interface AssetCapabilityRuntime {
+    readonly collection: AssetCollection;
+    readonly associations: AssetAssociationCollection;
+    readonly store: AssetStore;
+    storeDerivedAsset(source: Asset, name: string, data: Buffer, opts: Omit<StoreOptions, 'sourceAssetId'> & {
+        role?: string;
+        derivativeMetaType?: string;
+        linkAssociation?: boolean;
+    }): Promise<Asset>;
+}
+export interface AssetVariantRequest {
+    variant: string;
+    width?: number;
+    height?: number;
+    fit?: AssetVariantFit;
+    mimeType?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AssetVariantResult {
+    asset: Asset;
+    variant: string;
+    source: AssetCapabilitySource;
+    url?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface AssetProcessInput {
+    runtime: AssetCapabilityRuntime;
+    asset: Asset;
+    variants?: AssetVariantRequest[];
+    metadata?: Record<string, unknown>;
+}
+export interface AssetProcessResult {
+    asset: Asset;
+    metadata?: Record<string, unknown> | null;
+    variants?: AssetVariantResult[];
+    warnings?: string[];
+}
+export interface AssetEnsureVariantInput {
+    runtime: AssetCapabilityRuntime;
+    asset: Asset;
+    request: AssetVariantRequest;
+}
+export interface AssetNearbySearchInput {
+    runtime: AssetCapabilityRuntime;
+    tenantId?: string | null;
+    latitude: number;
+    longitude: number;
+    radiusMeters?: number;
+    limit?: number;
+    source?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AssetSearchItem {
+    asset?: Asset | null;
+    assetId: string;
+    origin: string;
+    title?: string | null;
+    previewUrl?: string | null;
+    deliveryUrl?: string | null;
+    mimeType?: string | null;
+    width?: number | null;
+    height?: number | null;
+    distanceMeters?: number | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface AssetSearchResult {
+    items: AssetSearchItem[];
+    nextCursor?: string | null;
+}
+export interface AssetExternalSyncInput {
+    runtime: AssetCapabilityRuntime;
+    asset: Asset;
+    externalId?: string | null;
+    sourceRef?: AssetExternalSourceRef | null;
+    metadata?: Record<string, unknown>;
+}
+export interface AssetExternalSourceRef {
+    system: string;
+    id: string;
+    kind?: string | null;
+}
+export interface AssetExternalSyncResult {
+    asset: Asset;
+    provider: string;
+    status: 'ready' | 'pending' | 'skipped';
+    externalAssetId?: string | null;
+    externalId?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface AssetWorkflowInputSelection {
+    slotKey: string;
+    assetIds: string[];
+}
+export interface AssetWorkflowInput {
+    runtime: AssetCapabilityRuntime;
+    asset: Asset;
+    workflowSlug: string;
+    clientRequestId?: string | null;
+    name?: string;
+    inputSelections?: AssetWorkflowInputSelection[];
+    sourceAssetIds?: string[];
+    parameters?: Record<string, unknown>;
+    requestContext?: Record<string, unknown>;
+    requestedPlacement?: string | null;
+    priority?: number | null;
+}
+export interface AssetWorkflowResult {
+    provider: string;
+    jobId: string;
+    status: string;
+    idempotent?: boolean;
+    metadata?: Record<string, unknown> | null;
+}
+export interface AssetCapabilityProvider {
+    readonly name: string;
+    processAsset?(input: AssetProcessInput): Promise<AssetProcessResult>;
+    ensureVariant?(input: AssetEnsureVariantInput): Promise<AssetVariantResult>;
+    searchNearbyAssets?(input: AssetNearbySearchInput): Promise<AssetSearchResult>;
+    syncExternalAsset?(input: AssetExternalSyncInput): Promise<AssetExternalSyncResult>;
+    submitAssetWorkflow?(input: AssetWorkflowInput): Promise<AssetWorkflowResult>;
+}
+export type AssetCapabilityName = 'processAsset' | 'ensureVariant' | 'searchNearbyAssets' | 'syncExternalAsset' | 'submitAssetWorkflow';
+export declare class AssetCapabilityUnavailableError extends Error {
+    readonly capability: AssetCapabilityName;
+    constructor(capability: AssetCapabilityName, message?: string);
+}
+export declare class AssetCapabilitySkippedError extends Error {
+    readonly capability: AssetCapabilityName;
+    constructor(capability: AssetCapabilityName, message: string);
+}
+//# sourceMappingURL=asset-capabilities.d.ts.map

package/dist/asset-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-capabilities.d.ts","sourceRoot":"","sources":["../src/asset-capabilities.ts"],"names":[],"mappings":"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"}

package/dist/asset-conventions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Asset conventions
+ *
+ * Shared constants and metadata-key conventions for how apps and agents
+ * describe asset relationships and derivation state on top of `smrt-assets`.
+ *
+ * These are advisory: `AssetAssociation.role` and `Asset` metadata fields
+ * accept any string, but standardising on these values makes cross-agent
+ * serving, filtering, and UI work possible without everybody inventing
+ * their own vocabulary.
+ */
+/**
+ * Canonical association roles used with `AssetAssociation` and noun join
+ * tables like `content_assets`.
+ *
+ * - `source_document`: original upstream document (e.g. agenda PDF) that
+ *   later derivatives are extracted from.
+ * - `document_image`: page image or other visual derived from a source
+ *   document.
+ * - `thumbnail`: small preview rendition of another asset.
+ * - `asset_variant`: deterministic sized rendition of another asset.
+ * - `proof`: non-canonical evidence asset (e.g. a screenshot used to
+ *   back a fact).
+ * - `derivation_source`: source side of a derivation link (used when a
+ *   derivative points back to the asset it was produced from).
+ * - `attachment`: generic "this asset belongs to that object" link —
+ *   the default for noun join tables.
+ * - `hero`: primary/featured asset for an owner.
+ */
+export declare const ASSET_ROLES: {
+    readonly SOURCE_DOCUMENT: "source_document";
+    readonly DOCUMENT_IMAGE: "document_image";
+    readonly THUMBNAIL: "thumbnail";
+    readonly ASSET_VARIANT: "asset_variant";
+    readonly PROOF: "proof";
+    readonly DERIVATION_SOURCE: "derivation_source";
+    readonly ATTACHMENT: "attachment";
+    readonly HERO: "hero";
+};
+export type AssetRole = (typeof ASSET_ROLES)[keyof typeof ASSET_ROLES];
+/**
+ * Canonical metadata keys used on `Asset.description`-adjacent metadata
+ * surfaces or stored via `AssetAssociation` sidecars. These keys are the
+ * recommended names for cross-package extraction, provenance, and
+ * content-addressing state.
+ *
+ * Apps are free to add their own keys; using these for the common cases
+ * keeps derived-asset tooling portable.
+ *
+ * - `extractionStatus`: `'pending' | 'running' | 'succeeded' | 'failed'`
+ * - `extractionError`: error string from the last extraction attempt
+ * - `extractedAt`: ISO timestamp of the last successful extraction
+ * - `sourceUrl`: upstream URL the asset was fetched from
+ * - `sourceHash`: content-address hash of the source bytes (e.g. sha256)
+ * - `pageNumber`: 1-based page number within a multi-page source document
+ */
+export declare const ASSET_METADATA_KEYS: {
+    readonly EXTRACTION_STATUS: "extractionStatus";
+    readonly EXTRACTION_ERROR: "extractionError";
+    readonly EXTRACTED_AT: "extractedAt";
+    readonly SOURCE_URL: "sourceUrl";
+    readonly SOURCE_HASH: "sourceHash";
+    readonly PAGE_NUMBER: "pageNumber";
+};
+export type AssetMetadataKey = (typeof ASSET_METADATA_KEYS)[keyof typeof ASSET_METADATA_KEYS];
+/**
+ * Known extraction status values for `ASSET_METADATA_KEYS.EXTRACTION_STATUS`.
+ */
+export declare const ASSET_EXTRACTION_STATUS: {
+    readonly PENDING: "pending";
+    readonly RUNNING: "running";
+    readonly SUCCEEDED: "succeeded";
+    readonly FAILED: "failed";
+};
+export type AssetExtractionStatus = (typeof ASSET_EXTRACTION_STATUS)[keyof typeof ASSET_EXTRACTION_STATUS];
+//# sourceMappingURL=asset-conventions.d.ts.map

package/dist/asset-conventions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-conventions.d.ts","sourceRoot":"","sources":["../src/asset-conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB;;;;;;;CAOtB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAC1B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;CAK1B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/asset-metafield.d.ts

@@ -0,0 +1,27 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { AssetMetafieldOptions } from './types';
+export declare class AssetMetafield extends SmrtObject {
+    name: string;
+    validation: string;
+    constructor(options?: AssetMetafieldOptions);
+    /**
+     * Get validation rules as parsed object
+     *
+     * @returns Parsed validation object or empty object if no validation
+     */
+    getValidation(): Record<string, unknown>;
+    /**
+     * Set validation rules from object
+     *
+     * @param rules - Validation rules object
+     */
+    setValidation(rules: Record<string, unknown>): void;
+    /**
+     * Get asset metafield by slug
+     *
+     * @param slug - The slug to search for
+     * @returns AssetMetafield instance or null
+     */
+    static getBySlug(_slug: string): Promise<AssetMetafield | null>;
+}
+//# sourceMappingURL=asset-metafield.d.ts.map

package/dist/asset-metafield.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-metafield.d.ts","sourceRoot":"","sources":["../src/asset-metafield.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD,qBAMa,cAAe,SAAQ,UAAU;IAE5C,IAAI,SAAM;IACV,UAAU,SAAM;gBAEJ,OAAO,GAAE,qBAA0B;IAO/C;;;;OAIG;IACH,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IASxC;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAInD;;;;;OAKG;WACU,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;CAItE"}

package/dist/asset-metafields.d.ts

@@ -0,0 +1,27 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { AssetMetafield } from './asset-metafield';
+export declare class AssetMetafieldCollection extends SmrtCollection<AssetMetafield> {
+    static readonly _itemClass: typeof AssetMetafield;
+    /**
+     * Get or create an asset metafield by slug
+     *
+     * @param slug - The metafield slug
+     * @param name - The display name (defaults to slug)
+     * @param validation - Optional validation rules (JSON string or object)
+     * @returns The existing or newly created AssetMetafield
+     */
+    getOrCreate(slug: string, name?: string, validation?: string | Record<string, unknown>): Promise<AssetMetafield>;
+    /**
+     * Initialize common asset metafields
+     *
+     * Creates standard metafields with validation rules:
+     * - width (integer, min: 0)
+     * - height (integer, min: 0)
+     * - duration (number, min: 0)
+     * - size (integer, min: 0)
+     * - author (string)
+     * - copyright (string)
+     */
+    initializeCommonMetafields(): Promise<void>;
+}
+//# sourceMappingURL=asset-metafields.d.ts.map

package/dist/asset-metafields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-metafields.d.ts","sourceRoot":"","sources":["../src/asset-metafields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,qBAAa,wBAAyB,SAAQ,cAAc,CAAC,cAAc,CAAC;IAC1E,MAAM,CAAC,QAAQ,CAAC,UAAU,wBAAkB;IAE5C;;;;;;;OAOG;IACG,WAAW,CACf,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5C,OAAO,CAAC,cAAc,CAAC;IAoB1B;;;;;;;;;;OAUG;IACG,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;CA8BlD"}