@happyvertical/smrt-assets 0.30.0

package/dist/asset-runtime.d.ts

@@ -0,0 +1,218 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { Asset } from './asset';
+import { AssetAssociation } from './asset-association';
+import { AssetAssociationCollection } from './asset-associations';
+import { AssetCapabilityProvider, AssetExternalSourceRef, AssetExternalSyncResult, AssetNearbySearchInput, AssetProcessResult, AssetSearchResult, AssetVariantRequest, AssetVariantResult, AssetWorkflowInput, AssetWorkflowResult } from './asset-capabilities';
+import { AssetExtractionStatus, AssetRole } from './asset-conventions';
+import { AssetStore, AssetStoreOptions, ProviderOptions, StoreOptions } from './asset-store';
+import { AssetCollection } from './assets';
+/**
+ * DB configuration accepted by the runtime — mirrors the shape
+ * `SmrtCollection.create({ db })` already accepts.
+ */
+export type AssetRuntimeDb = NonNullable<SmrtClassOptions['db']>;
+/**
+ * Options for constructing an `AssetRuntime` via `createAssetRuntime()`.
+ */
+export interface AssetRuntimeOptions {
+    /**
+     * Database used for `AssetCollection` and `AssetAssociationCollection`.
+     *
+     * Accepts anything `SmrtCollection.create({ db })` accepts — a string
+     * URL, a config object, or a live `DatabaseInterface`.
+     */
+    db: AssetRuntimeDb;
+    /**
+     * Storage provider for `AssetStore`.
+     *
+     * A string is treated as a local filesystem `basePath`; otherwise
+     * forwarded to `@happyvertical/files`.
+     */
+    storage: ProviderOptions;
+    /**
+     * Optional behavior for the underlying `AssetStore`.
+     *
+     * Use this to provide a storage resolver while keeping the convenience
+     * runtime factory.
+     */
+    storeOptions?: AssetStoreOptions;
+    /**
+     * Optional collection instance. If omitted, one is created from `db`.
+     * Useful in tests or when the caller already has a configured
+     * collection (e.g. from `ObjectRegistry`).
+     */
+    collection?: AssetCollection;
+    /**
+     * Optional associations collection. If omitted, one is created from `db`.
+     */
+    associations?: AssetAssociationCollection;
+    /**
+     * Optional asset capability providers.
+     *
+     * Providers let callers keep one app-facing asset runtime while
+     * delegating processing, variant generation, search, external sync, or
+     * workflow submission to local processors or external systems.
+     */
+    capabilityProviders?: AssetCapabilityProvider[];
+}
+/**
+ * Structural shape of the runtime. Agents and serving helpers should
+ * depend on `AssetRuntimeLike` rather than the concrete class so tests
+ * can pass in a minimal object.
+ */
+export interface AssetRuntimeLike {
+    readonly collection: AssetCollection;
+    readonly associations: AssetAssociationCollection;
+    readonly store: AssetStore;
+    readonly capabilityProviders?: readonly AssetCapabilityProvider[];
+}
+/**
+ * Options for `AssetRuntime.storeDerivedAsset()`.
+ */
+export interface StoreDerivedAssetOptions extends Omit<StoreOptions, 'sourceAssetId'> {
+    /**
+     * Relationship role for the derivation link.
+     *
+     * Defaults to `ASSET_ROLES.DERIVATION_SOURCE` when `linkAssociation`
+     * is true (the default). Set explicitly for roles like
+     * `document_image` or `thumbnail` when a derivative has a more
+     * specific semantic than "came from".
+     */
+    role?: AssetRole | string;
+    /**
+     * If true (default), also create an `AssetAssociation` record with
+     * `assetId=source.id`, `metaType=<derivativeMetaType>`,
+     * `metaId=<newAssetId>`, `role=<role>` so the provenance link is
+     * queryable independent of `sourceAssetId`.
+     *
+     * Set to `false` if you only want the column-level `sourceAssetId`
+     * derivation link.
+     */
+    linkAssociation?: boolean;
+    /**
+     * `metaType` string stored on the `AssetAssociation`. This describes
+     * the *derivative* object (the target of `metaId`), not the source.
+     *
+     * Defaults to `'Asset'`. Callers whose derivatives are STI subclasses
+     * — e.g. an `Image` produced from a PDF — should pass the subclass
+     * name here so consumers can distinguish subtype derivatives from
+     * plain assets. This matches the convention used by
+     * `smrt-images`' `ImageDeriver.deriveWithAssociations()`.
+     */
+    derivativeMetaType?: string;
+}
+/**
+ * Options for `AssetRuntime.linkDerivation()`.
+ */
+export interface LinkDerivationOptions {
+    role?: AssetRole | string;
+    /**
+     * `metaType` describing the derivative object (target of `metaId`).
+     * See `StoreDerivedAssetOptions.derivativeMetaType`.
+     */
+    derivativeMetaType?: string;
+}
+/**
+ * Convenience runtime for `smrt-assets` callers. See the package
+ * `CLAUDE.md` for the full "source vs derived" vocabulary.
+ */
+export declare class AssetRuntime implements AssetRuntimeLike {
+    readonly collection: AssetCollection;
+    readonly associations: AssetAssociationCollection;
+    readonly store: AssetStore;
+    readonly capabilityProviders: AssetCapabilityProvider[];
+    constructor(collection: AssetCollection, associations: AssetAssociationCollection, store: AssetStore, capabilityProviders?: AssetCapabilityProvider[]);
+    registerCapabilityProvider(provider: AssetCapabilityProvider): this;
+    private providersFor;
+    processAsset(asset: Asset, input?: {
+        variants?: AssetVariantRequest[];
+        metadata?: Record<string, unknown>;
+    }): Promise<AssetProcessResult>;
+    ensureVariant(asset: Asset, request: AssetVariantRequest): Promise<AssetVariantResult>;
+    searchNearbyAssets(input: Omit<AssetNearbySearchInput, 'runtime'>): Promise<AssetSearchResult>;
+    syncExternalAsset(asset: Asset, input?: {
+        externalId?: string | null;
+        sourceRef?: AssetExternalSourceRef | null;
+        metadata?: Record<string, unknown>;
+    }): Promise<AssetExternalSyncResult>;
+    submitAssetWorkflow(asset: Asset, input: Omit<AssetWorkflowInput, 'runtime' | 'asset'>): Promise<AssetWorkflowResult>;
+    /**
+     * Create a new source asset with both a record and bytes on disk.
+     *
+     * This is the same as `AssetStore.store()`, but exposed on the runtime
+     * so callers only need one handle.
+     */
+    storeSourceAsset(name: string, data: Buffer, opts: StoreOptions): Promise<Asset>;
+    /**
+     * Create a derivative of `source`, persist its bytes, and optionally
+     * record a provenance association.
+     *
+     * The new asset's `sourceAssetId` always points at `source.id`. When
+     * `linkAssociation` is true (the default), the runtime also writes
+     * an `AssetAssociation` so queries by role (e.g. "all `document_image`
+     * derivatives for this `source_document`") work without scanning
+     * `source_asset_id` chains.
+     */
+    storeDerivedAsset(source: Asset, name: string, data: Buffer, opts: StoreDerivedAssetOptions): Promise<Asset>;
+    /**
+     * Record a provenance association between an existing source asset
+     * and an existing derivative asset without touching bytes.
+     */
+    linkDerivation(source: Asset, derivative: Asset, opts?: LinkDerivationOptions): Promise<AssetAssociation>;
+    /**
+     * Update the standard extraction-status metadata on an asset's
+     * `description` JSON sidecar. This is a thin convenience over the
+     * convention in `asset-conventions.ts` — callers that store
+     * metadata elsewhere can ignore it.
+     *
+     * **How existing descriptions are handled**:
+     * - Empty / unset → fresh JSON object.
+     * - Valid JSON object → merged into; existing keys preserved.
+     * - Free-form prose or non-object JSON → preserved under the
+     *   reserved `text` key of the resulting object (e.g.
+     *   `{ text: "original prose", extractionStatus: "..." }`). No prose
+     *   is discarded.
+     *
+     * Callers that already use `text` for something else, or that need
+     * an entirely separate metadata surface, should either round-trip
+     * the JSON themselves or skip this helper — its only job is the
+     * `extractionStatus` / `extractionError` / `extractedAt` triple.
+     *
+     * Error handling: when `status` transitions away from `failed`
+     * without a new `extra.error`, the stale `extractionError` is
+     * cleared so downstream consumers don't misread the current state.
+     * When `status === 'succeeded'`, `extractedAt` is stamped to now
+     * unless the caller provides one.
+     */
+    setExtractionStatus(asset: Asset, status: AssetExtractionStatus, extra?: {
+        error?: string;
+        extractedAt?: Date;
+    }): Promise<void>;
+}
+/**
+ * Factory — lazily creates a shared asset runtime from DB + storage
+ * config. Initializes the store's filesystem adapter before returning.
+ *
+ * @example
+ * ```ts
+ * import { createAssetRuntime, ASSET_ROLES } from '@happyvertical/smrt-assets';
+ *
+ * const runtime = await createAssetRuntime({
+ *   db: { type: 'sqlite', url: 'app.db' },
+ *   storage: { type: 's3', bucket: 'my-app' },
+ * });
+ *
+ * const pdf = await runtime.storeSourceAsset('agenda.pdf', bytes, {
+ *   mimeType: 'application/pdf',
+ *   typeSlug: 'document',
+ * });
+ *
+ * await runtime.storeDerivedAsset(pdf, 'agenda-p1.png', pageBytes, {
+ *   mimeType: 'image/png',
+ *   typeSlug: 'image',
+ *   role: ASSET_ROLES.DOCUMENT_IMAGE,
+ * });
+ * ```
+ */
+export declare function createAssetRuntime(options: AssetRuntimeOptions): Promise<AssetRuntime>;
+//# sourceMappingURL=asset-runtime.d.ts.map

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

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

package/dist/asset-serving.d.ts

@@ -0,0 +1,146 @@
+import { Asset } from './asset';
+import { AssetRuntimeLike } from './asset-runtime';
+/**
+ * Result of `resolveAssetForServing()` — lets advanced callers
+ * stream bytes themselves while still reusing the access check.
+ */
+export interface ResolvedAssetBytes {
+    asset: Asset;
+    data: Buffer;
+    contentType: string;
+    filename: string;
+    size: number;
+}
+/**
+ * Options for `serveAsset()` and `resolveAssetForServing()`.
+ */
+export interface ServeAssetOptions {
+    /** Shared asset runtime (collection + store). */
+    runtime: AssetRuntimeLike;
+    /**
+     * Either an asset id to look up or a fully-loaded `Asset`
+     * instance. Passing the instance skips the `collection.get()` call.
+     */
+    asset: string | Asset;
+    /**
+     * Tenant of the caller. When provided, the asset must either
+     * belong to this tenant or be a global asset (`tenantId = null`)
+     * or a 403 is returned.
+     */
+    tenantId?: string | null;
+    /**
+     * Optional `Content-Disposition` — `'inline'` (default) or
+     * `'attachment'`. Use `'attachment'` for download links.
+     */
+    disposition?: 'inline' | 'attachment';
+    /**
+     * Extra headers merged into the 200 response. Does not affect
+     * 403/404/500 responses.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional override for the filename used in `Content-Disposition`.
+     * Defaults to the basename of the asset's `sourceUri` or `name`.
+     */
+    filename?: string;
+    /**
+     * Optional access-check hook. Return `false` to short-circuit with a
+     * 403 before bytes are loaded. Runs after the built-in tenant check.
+     */
+    canAccess?: (asset: Asset) => boolean | Promise<boolean>;
+    /**
+     * How to handle assets whose `sourceUri` is an `http(s)` URL rather
+     * than a store-backed path.
+     *
+     * - `'error'` (default): treat a remote URI as an error (`500`). This
+     *   is the safe default — `sourceUri` is attacker-settable on many
+     *   asset-creation paths, so proxying it blindly is an SSRF vector
+     *   (fetching `169.254.169.254` cloud metadata, internal services,
+     *   etc.). Opt into `'proxy'` only for trusted sources.
+     * - `'proxy'`: fetch the bytes via `globalThis.fetch` and return them
+     *   inline. Keeps the origin URL hidden from the client and preserves
+     *   the same tenant/access checks the local path gets. Guarded against
+     *   SSRF: the host must resolve to a public IP (private, loopback,
+     *   link-local, and cloud-metadata ranges are rejected), only
+     *   `http(s)` is allowed, and redirects are re-validated.
+     * - `'redirect'`: return a `302` to `sourceUri` instead of fetching.
+     *   Skips the byte round-trip but exposes the origin URL.
+     *
+     * Anything that does not look like `http://` or `https://` is read
+     * through the store as usual.
+     */
+    remoteMode?: 'proxy' | 'redirect' | 'error';
+    /**
+     * Custom `fetch` implementation for the `remoteMode: 'proxy'` path.
+     * Defaults to `globalThis.fetch` (Node 18+).
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Maximum number of bytes to buffer when `remoteMode: 'proxy'` fetches
+     * a remote asset. Protects against memory-exhaustion DoS from a hostile
+     * (or compromised) origin streaming an unbounded body. Defaults to
+     * {@link DEFAULT_REMOTE_MAX_BYTES} (50 MiB).
+     */
+    remoteMaxBytes?: number;
+    /**
+     * Timeout in milliseconds for the `remoteMode: 'proxy'` fetch. Defaults
+     * to {@link DEFAULT_REMOTE_TIMEOUT_MS} (10s). Prevents a slow/hung
+     * origin from pinning the request indefinitely.
+     */
+    remoteTimeoutMs?: number;
+    /**
+     * Custom `Response`-like constructor, for runtimes that don't have
+     * a global `Response` (pre-Node-18, workers with a custom shim).
+     * Defaults to `globalThis.Response`.
+     */
+    responseCtor?: ResponseConstructor;
+}
+type ResponseConstructor = typeof Response;
+/** Default cap (50 MiB) on bytes buffered from a proxied remote asset. */
+export declare const DEFAULT_REMOTE_MAX_BYTES: number;
+/** Default timeout (10s) for a proxied remote-asset fetch. */
+export declare const DEFAULT_REMOTE_TIMEOUT_MS = 10000;
+/**
+ * Resolve an asset + bytes for serving, enforcing the same tenant
+ * and access checks as `serveAsset()` but returning the parts so
+ * callers can render their own framework response.
+ *
+ * Throws `AssetServeError` with a status on any error so callers can
+ * map to their HTTP layer.
+ */
+export declare function resolveAssetForServing(options: ServeAssetOptions): Promise<ResolvedAssetBytes>;
+/**
+ * Serve an asset as a standard Web `Response`.
+ *
+ * Returns:
+ *  - `404` when the asset id doesn't resolve
+ *  - `403` when the tenant mismatches or `canAccess` denies
+ *  - `302` when `remoteMode: 'redirect'` and the asset's `sourceUri`
+ *    is an `http(s)` URL
+ *  - `502` when `remoteMode: 'proxy'` and the origin fetch fails
+ *  - `500` when bytes fail to read (file missing, provider error)
+ *  - `200` with the raw bytes, `Content-Type`, `Content-Length`, and
+ *    `Content-Disposition` set otherwise.
+ *
+ * The resulting `Response` is framework-agnostic: SvelteKit `+server.ts`
+ * endpoints, Hono, and plain Node HTTP all accept it via their Web
+ * interop layer.
+ */
+export declare function serveAsset(options: ServeAssetOptions): Promise<Response>;
+/**
+ * Error raised by `resolveAssetForServing()` with the HTTP status
+ * callers should use when rendering their own response.
+ *
+ * `message` is the specific, server-side reason — safe to log, never sent to
+ * the client. `clientMessage` is the opaque body {@link serveAsset} returns to
+ * the HTTP client; it defaults to a generic, status-keyed string so the
+ * specific reason can't leak (SSRF rejection cause, upstream status, etc.).
+ */
+export declare class AssetServeError extends Error {
+    readonly status: number;
+    /** Opaque body safe to return to the HTTP client. */
+    readonly clientMessage: string;
+    constructor(message: string, status: number, clientMessage?: string);
+}
+export {};
+//# sourceMappingURL=asset-serving.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asset-serving.d.ts","sourceRoot":"","sources":["../src/asset-serving.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,OAAO,EAAE,gBAAgB,CAAC;IAE1B;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC;IAEtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;IAE5C;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAEzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED,KAAK,mBAAmB,GAAG,OAAO,QAAQ,CAAC;AAE3C,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,QAAmB,CAAC;AAEzD,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAkWhD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAmG7B;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,QAAQ,CAAC,CA2FnB;AAuBD;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAMtB,MAAM,EAAE,MAAM;IALhC,qDAAqD;IACrD,SAAgB,aAAa,EAAE,MAAM,CAAC;gBAGpC,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EAC9B,aAAa,CAAC,EAAE,MAAM;CAMzB"}

package/dist/asset-status.d.ts

@@ -0,0 +1,15 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { AssetStatusOptions } from './types';
+export declare class AssetStatus extends SmrtObject {
+    name: string;
+    description: string;
+    constructor(options?: AssetStatusOptions);
+    /**
+     * Get asset status by slug
+     *
+     * @param slug - The slug to search for
+     * @returns AssetStatus instance or null
+     */
+    static getBySlug(_slug: string): Promise<AssetStatus | null>;
+}
+//# sourceMappingURL=asset-status.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asset-status.d.ts","sourceRoot":"","sources":["../src/asset-status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,qBAMa,WAAY,SAAQ,UAAU;IAEzC,IAAI,SAAM;IACV,WAAW,SAAM;gBAEL,OAAO,GAAE,kBAAuB;IAO5C;;;;;OAKG;WACU,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CAInE"}

package/dist/asset-statuses.d.ts

@@ -0,0 +1,25 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { AssetStatus } from './asset-status';
+export declare class AssetStatusCollection extends SmrtCollection<AssetStatus> {
+    static readonly _itemClass: typeof AssetStatus;
+    /**
+     * Get or create an asset status by slug
+     *
+     * @param slug - The asset status slug
+     * @param name - The display name (defaults to slug)
+     * @param description - Optional description
+     * @returns The existing or newly created AssetStatus
+     */
+    getOrCreate(slug: string, name?: string, description?: string): Promise<AssetStatus>;
+    /**
+     * Initialize common asset statuses
+     *
+     * Creates standard asset statuses if they don't exist:
+     * - draft
+     * - published
+     * - archived
+     * - deleted
+     */
+    initializeCommonStatuses(): Promise<void>;
+}
+//# sourceMappingURL=asset-statuses.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asset-statuses.d.ts","sourceRoot":"","sources":["../src/asset-statuses.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,qBAAa,qBAAsB,SAAQ,cAAc,CAAC,WAAW,CAAC;IACpE,MAAM,CAAC,QAAQ,CAAC,UAAU,qBAAe;IAEzC;;;;;;;OAOG;IACG,WAAW,CACf,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,WAAW,CAAC;IAavB;;;;;;;;OAQG;IACG,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC;CAUhD"}

package/dist/asset-store.d.ts

@@ -0,0 +1,200 @@
+import { FilesystemInterface, GetFilesystemOptions } from '@happyvertical/files';
+import { Asset } from './asset';
+import { AssetCollection } from './assets';
+/**
+ * Options for storing an asset
+ */
+export interface StoreOptions {
+    /** MIME type of the data */
+    mimeType: string;
+    /** Asset type slug (e.g., 'video', 'audio', 'image', 'reference-image') */
+    typeSlug?: string;
+    /**
+     * Source asset ID (for derivatives like thumbnails, variants, AI edits).
+     *
+     * Renamed from `parentId` in R3-D — see Asset.sourceAssetId.
+     */
+    sourceAssetId?: string;
+    /** Asset status slug */
+    statusSlug?: string;
+    /** Description */
+    description?: string;
+    /** Original source system for imported/derived assets */
+    sourceType?: string;
+    /** External id in the source system */
+    externalId?: string;
+    /** JSON metadata stored on the asset record */
+    metadata?: string | Record<string, unknown> | null;
+}
+/**
+ * Provider options for configuring the filesystem backend.
+ * Accepts any @happyvertical/files options or a simple basePath string for local storage.
+ */
+export type ProviderOptions = GetFilesystemOptions | string;
+/**
+ * Asset storage operation currently being resolved.
+ */
+export type AssetStorageOperation = 'read' | 'write' | 'delete';
+/**
+ * Context passed to an AssetStore resolver.
+ *
+ * Downstream apps can use this hook to route a logical Asset to whichever
+ * storage backend is appropriate for the current operation.
+ */
+export interface AssetStorageResolveRequest {
+    operation: AssetStorageOperation;
+    asset: Asset;
+    path: string;
+    sourceUri: string;
+    mimeType?: string;
+    typeSlug?: string;
+    defaultProviderOptions: GetFilesystemOptions;
+    defaultFilesystem: FilesystemInterface;
+}
+/**
+ * Resolved storage target for an AssetStore operation.
+ */
+export interface AssetStorageResolution {
+    filesystem?: FilesystemInterface;
+    providerOptions?: ProviderOptions;
+    path?: string;
+    sourceUri?: string;
+}
+export type AssetStorageResolver = (request: AssetStorageResolveRequest) => AssetStorageResolution | null | undefined | Promise<AssetStorageResolution | null | undefined>;
+export interface AssetStoreOptions {
+    resolver?: AssetStorageResolver;
+}
+/**
+ * AssetStore manages file storage and Asset record creation.
+ *
+ * Files are stored using @happyvertical/files with the convention:
+ * `{typeSlug}/{assetId}.{ext}`
+ *
+ * @example
+ * ```typescript
+ * import { AssetStore } from '@happyvertical/smrt-assets';
+ *
+ * // Local storage (backward-compatible)
+ * const store = new AssetStore('dev/data/assets', assetCollection);
+ * await store.initialize();
+ *
+ * // Provider-agnostic storage
+ * const s3Store = new AssetStore({ type: 's3', bucket: 'my-bucket' }, assetCollection);
+ * await s3Store.initialize();
+ *
+ * // Store a video buffer
+ * const asset = await store.store('my-video', videoBuffer, {
+ *   mimeType: 'video/mp4',
+ *   typeSlug: 'video',
+ * });
+ *
+ * // Read it back
+ * const data = await store.read(asset);
+ *
+ * // Delete it
+ * await store.remove(asset);
+ * ```
+ */
+export declare class AssetStore {
+    private readonly collection;
+    private fs;
+    private readonly fsOptions;
+    private readonly fsCache;
+    private readonly resolver?;
+    constructor(providerOrBasePath: ProviderOptions, collection: AssetCollection, options?: AssetStoreOptions);
+    /** The base path for local storage, or empty string for non-local providers */
+    get basePath(): string;
+    /**
+     * Initialize the filesystem adapter.
+     * Must be called before any file operations.
+     */
+    initialize(): Promise<this>;
+    /**
+     * Get the initialized filesystem (throws if not initialized)
+     */
+    private getFs;
+    private providerCacheKey;
+    private getFilesystemForOptions;
+    /**
+     * Build a sourceUri for the given file path based on the provider type.
+     */
+    private buildSourceUri;
+    private static buildSourceUriForProvider;
+    private static providerRelativePath;
+    private static requireAssetId;
+    private resolveStorage;
+    private writeAssetData;
+    /**
+     * Write file data for an existing Asset record (no DB record created).
+     *
+     * Use this when you've already created the record (e.g., via a
+     * collection.create()) and only need to persist the file data.
+     *
+     * @param asset - The existing asset to write data for
+     * @param data - File data as a Buffer
+     * @param opts - Storage options (mimeType required)
+     * @returns The sourceUri for the written file
+     */
+    storeFile(asset: Asset, data: Buffer, opts: {
+        mimeType: string;
+        typeSlug?: string;
+    }): Promise<string>;
+    /**
+     * Write buffer to disk and create an Asset record.
+     *
+     * @param name - Human-readable name for the asset
+     * @param data - File data as a Buffer
+     * @param opts - Storage options (mimeType required)
+     * @returns Created Asset instance
+     */
+    store(name: string, data: Buffer, opts: StoreOptions): Promise<Asset>;
+    /**
+     * Store a new version of an existing asset.
+     *
+     * @param asset - The existing asset to version
+     * @param data - File data for the new version
+     * @param opts - Optional overrides for store options
+     * @returns The newly created version Asset
+     */
+    storeVersion(asset: Asset, data: Buffer, opts?: Partial<StoreOptions>): Promise<Asset>;
+    /**
+     * Read file data for a specific version of an asset.
+     *
+     * @param asset - The asset (any version in the chain)
+     * @param version - The version number to read
+     * @returns File data as a Buffer
+     */
+    readVersion(asset: Asset, version: number): Promise<Buffer>;
+    /**
+     * Read file data from an Asset's sourceUri.
+     *
+     * @param asset - Asset to read data for
+     * @returns File data as a Buffer
+     */
+    read(asset: Asset): Promise<Buffer>;
+    /**
+     * Read file by asset ID.
+     *
+     * @param id - Asset ID to look up
+     * @returns Object with data Buffer and Asset, or null if not found
+     */
+    readById(id: string): Promise<{
+        data: Buffer;
+        asset: Asset;
+    } | null>;
+    /**
+     * Delete file from disk and remove the Asset record.
+     *
+     * @param asset - Asset to remove
+     */
+    remove(asset: Asset): Promise<void>;
+    /**
+     * Extract filesystem path from a sourceUri.
+     * Handles file://, s3://, and plain paths.
+     *
+     * @param sourceUri - Asset sourceUri (e.g., 'file:///path/to/file.mp4', 's3://bucket/key')
+     * @returns Filesystem path
+     */
+    static pathFromUri(sourceUri: string): string;
+}
+//# sourceMappingURL=asset-store.d.ts.map

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

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

package/dist/asset-type.d.ts

@@ -0,0 +1,15 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { AssetTypeOptions } from './types';
+export declare class AssetType extends SmrtObject {
+    name: string;
+    description: string;
+    constructor(options?: AssetTypeOptions);
+    /**
+     * Get asset type by slug
+     *
+     * @param slug - The slug to search for
+     * @returns AssetType instance or null
+     */
+    static getBySlug(_slug: string): Promise<AssetType | null>;
+}
+//# sourceMappingURL=asset-type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asset-type.d.ts","sourceRoot":"","sources":["../src/asset-type.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,qBAMa,SAAU,SAAQ,UAAU;IAEvC,IAAI,SAAM;IACV,WAAW,SAAM;gBAEL,OAAO,GAAE,gBAAqB;IAO1C;;;;;OAKG;WACU,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAIjE"}