@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.

Feature recipes

assets.library provides the model-backed file and media library: assets, folders, classifications, statuses, and metadata definitions. assets.attachments adds record attachment provenance and requires the library. They share the Files and media catalog card and the Assets navigation section, and both embed user-facing help in the generated manifest. The recipes publish browser-safe mock fixture exports from @happyvertical/smrt-assets/playground. AssetManager needs host persistence callbacks and AttachmentPanel needs record-scoped authorized attachments, so neither is declared as a standalone placement. Storage providers remain application-owned, so the recipes declare no provider.

The package playground is a Mock preview. Its asset grid uses in-memory props and data-URI thumbnails, and its attachment panel demonstrates supplied native form data only. It never performs a real network upload or creates public storage URLs.

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 = await new AssetStore(assetRoot, collection).initialize();
await store.store('screenshot', buffer, { mimeType: 'image/png' });

Portable local storage

For a new desktop installation, pass the same portable storage configuration to each asset runtime, worker, and service that handles its managed files:

const assets = await createAssetRuntime({
  db,
  storage: { type: 'local', basePath: assetRoot, locatorMode: 'relative' },
});

Use an absolute, app-owned assetRoot. The store persists asset-local:<key>, for example asset-local:document/17f6.txt. The key is a raw, slash-separated path under the configured root and contains no URL escaping. Use ASCII letters, digits, underscores, and hyphens in type slugs and IDs. The store rejects traversal, absolute keys, Windows device names, links at or below the root, and non-regular files. Keep the root and its contents under app control; the filesystem checks assume no concurrent changes by an untrusted local process.

When copying an installation, copy the database and the asset directory together, keep each file's path within the directory, and set basePath to the copied directory. Read, preserve, and remove assets through the runtime. A storage resolver may choose a path for a portable write, but later reads and deletes must use the stored key in the built-in local filesystem for that runtime.

The option changes new writes only. Existing local options and S3 locators keep their formats. A built-in local store can read portable locators whether or not it opts in to writing them. In portable mode, an existing file:// locator can still be read or removed when it identifies a valid key inside the configured root; changing the root does not relocate such records. Start with fresh desktop data or handle existing absolute locators before moving an installation.

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 |

Native private attachments

AttachmentPanel, AttachmentList and AttachmentUpload compose authorized private links, caller-supplied version history, and native multipart uploads. They preserve request identity and failed-action metadata without deriving public storage URLs. See the attachment contract for public types, native payloads, recovery, and server responsibilities.

Pass onremove(attachment) and/or removeAction (native POST of the attachment id) to add a confirmed per-attachment Remove button; see "Removing attachments" in the contract.

Polymorphic junction collection types

AssetAssociationCollection extends SmrtJunctionBase, sharing byRight, ordering, positioning, and registration guards with ordinary junctions. Its byLeft, attach, detach, and setLinks methods still require both metaType and metaId; they do not implement the single-owner SmrtJunction contract. Use instanceof SmrtJunctionBase when recognizing either kind of junction. Asset associations no longer satisfy instanceof SmrtJunction.

After building the workspace, node scripts/verify-packed-junction-types.mjs checks actual core/assets tarballs in the standard Bundler mode with skipLibCheck: false, inherited result types, and negative owner-argument tests. Full NodeNext declaration portability is tracked separately in #3524.

The consumer fixture installs declared dependencies in a temporary directory with no ancestor node_modules; it never links producer dependencies. It retains the project’s public registry routing without copying credentials. Set SMRT_PACKED_EVIDENCE_DIR to retain tarballs and the consumer lockfile. For an explicitly separate upstream-candidate proof, SMRT_PACKED_OVERRIDES may name a JSON file of pnpm overrides; such a proof does not establish that the normal published dependency graph passes.