@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

pnpm add @happyvertical/smrt-assets

Usage

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