@happyvertical/smrt-assets 0.60.10 → 0.60.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +5 -0
- package/README.md +38 -2
- package/dist/asset-store.d.ts +15 -3
- package/dist/asset-store.d.ts.map +1 -1
- package/dist/chunks/{files-runtime-KsFTbJR0.js → files-runtime-MnHRkfnd.js} +5 -2
- package/dist/chunks/{files-runtime-KsFTbJR0.js.map → files-runtime-MnHRkfnd.js.map} +1 -1
- package/dist/chunks/local-asset-locator-v4zTxVgM.js +59 -0
- package/dist/chunks/local-asset-locator-v4zTxVgM.js.map +1 -0
- package/dist/files-runtime.d.ts +2 -0
- package/dist/files-runtime.d.ts.map +1 -1
- package/dist/filesystem.js +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +54 -8
- package/dist/index.js.map +1 -1
- package/dist/local-asset-locator.d.ts +14 -0
- package/dist/local-asset-locator.d.ts.map +1 -0
- package/dist/locator.d.ts +2 -0
- package/dist/locator.d.ts.map +1 -0
- package/dist/locator.js +2 -0
- package/dist/manifest.json +1 -1
- package/dist/smrt-knowledge.json +12 -5
- package/dist/smrt-knowledge.okf.md +7 -2
- package/package.json +12 -8
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/** Identify the portable locator namespace without accepting the key yet. */
|
|
2
|
+
export declare function isLocalAssetLocator(value: string): boolean;
|
|
3
|
+
/** Encode a validated raw key as a persisted local asset locator. */
|
|
4
|
+
export declare function makeLocalAssetLocator(key: string): string;
|
|
5
|
+
/** Decode a portable locator to a validated key relative to the asset root. */
|
|
6
|
+
export declare function localAssetKey(locator: string): string;
|
|
7
|
+
export declare function requireLocalAssetRoot(root: string): string;
|
|
8
|
+
export declare function keyFromLegacyFileLocator(root: string, locator: string): string;
|
|
9
|
+
/**
|
|
10
|
+
* Refuse links and non-files beneath the trusted configured root. This
|
|
11
|
+
* inspection assumes the host prevents untrusted concurrent filesystem edits.
|
|
12
|
+
*/
|
|
13
|
+
export declare function checkLocalAssetPath(root: string, key: string): Promise<void>;
|
|
14
|
+
//# sourceMappingURL=local-asset-locator.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"local-asset-locator.d.ts","sourceRoot":"","sources":["../src/local-asset-locator.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOrD;AAkBD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW1D;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,MAAM,CA4BR;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAkBf"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"locator.d.ts","sourceRoot":"","sources":["../src/locator.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}
|
package/dist/locator.js
ADDED
package/dist/manifest.json
CHANGED
package/dist/smrt-knowledge.json
CHANGED
|
@@ -3,18 +3,20 @@
|
|
|
3
3
|
"sensitiveFieldsExcluded": true,
|
|
4
4
|
"generatedAt": "1970-01-01T00:00:00.000Z",
|
|
5
5
|
"packageName": "@happyvertical/smrt-assets",
|
|
6
|
-
"packageVersion": "0.60.
|
|
6
|
+
"packageVersion": "0.60.11",
|
|
7
7
|
"sourceManifestPath": "dist/manifest.json",
|
|
8
8
|
"agentDocPath": "AGENTS.md",
|
|
9
9
|
"sourceHashes": {
|
|
10
|
-
"manifest": "
|
|
11
|
-
"packageJson": "
|
|
12
|
-
"agents": "
|
|
10
|
+
"manifest": "8123cd92f9bfcd34b5db9850a1f501cfede0dccbe92b9930e352812fb9a75462",
|
|
11
|
+
"packageJson": "972f4d64de29038ee8ef35a088a232a621ccf958bc76d29707a1e70a8ab938a3",
|
|
12
|
+
"agents": "57d57d3eff49cb185e2a8cadf8b14b06d26a4a7750862a41a09e5000dc9570b6",
|
|
13
|
+
"moduleDoc:README.md": "565639275a9f6b74d64d9043dc1ec642339446cbeaf0ebc3f0239da7dc5e7222",
|
|
13
14
|
"moduleDoc:agents/private-assets.md": "e1a4ab4be7048f29d9e5b0d37d298f13e5a88ae9d988ef3a7cad728e03fb5797"
|
|
14
15
|
},
|
|
15
16
|
"exports": [
|
|
16
17
|
".",
|
|
17
18
|
"./filesystem",
|
|
19
|
+
"./locator",
|
|
18
20
|
"./manifest",
|
|
19
21
|
"./manifest.json",
|
|
20
22
|
"./playground",
|
|
@@ -3721,8 +3723,13 @@
|
|
|
3721
3723
|
"polymorphicAssociations": 1,
|
|
3722
3724
|
"uuidColumns": 40
|
|
3723
3725
|
},
|
|
3724
|
-
"agentDoc": "# @happyvertical/smrt-assets\n\nProvider-agnostic asset management with versioning, type classification, and generic/provenance associations.\n\n## Models\n\n- **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`).\n- **AssetType** / **AssetStatus**: lookup tables for classification and lifecycle.\n- **AssetMetafield**: custom metadata field definitions with JSON validation rules.\n- **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.\n- **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`.\n\n## Key Patterns\n\n- **Versioning**: `createNewVersion()` increments version, chains via `primaryVersionId`. `findVersions()` to retrieve history.\n- **Tag integration**: `addTag()`/`removeTag()` use raw `db.upsert()` on `asset_tags` join table (not a SMRT model).\n- **AssetStore**: abstraction for provider-agnostic file I/O (S3, local, etc.).\n `planFile(asset, opts)` resolves a recoverable URI before bytes are written;\n persist it before `preserveFile(asset, bytes, opts)`. Preservation adopts equal\n existing bytes and rejects changed bytes, changed resolver targets and read\n failures other than not-found. The caller owns receipt fencing/serialization.\n `removeFile(asset)` removes only bytes for recovery cleanup, including an\n already-pruned owner record; `remove(asset)` also deletes the owner record.\n- **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.\n\n## Runtime surface\n\nApps and agents should depend on the public **asset runtime** rather than hand-wiring a collection + store per-package (#1128).\n\n- `createAssetRuntime({ db, storage })` → `AssetRuntime` bundling `AssetCollection`, `AssetAssociationCollection`, and an initialized `AssetStore`.\n- `AssetRuntime.storeSourceAsset(name, data, opts)` — create a new source asset (record + bytes).\n- `AssetRuntime.storeDerivedAsset(source, name, data, opts)` — create a derivative with `sourceAssetId` set and (by default) a provenance `AssetAssociation` under a chosen role.\n- `AssetRuntime.linkDerivation(source, derivative, { role })` — record provenance without touching bytes.\n- `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.\n\n- `AssetRuntime.getPrivateAssetMetadata({ tenantId, actorUserId, assetId })` → `PrivateAssetMetadata | null` — authorized, tenant-scoped display metadata read of one PRIVATE asset so hosts never read `assets` rows. Trusted server capability (host authorizes first); requires an ambient tenant actor matching `tenantId`/`actorUserId` exactly (throws otherwise, including empty ids). Result is an allowlist (`id, tenantId, name, mimeType, version, typeSlug, statusSlug, createdAt, updatedAt`); never owner, `sourceUri`, description/metadata sidecars. There is no size field on `Asset`. Missing, public and other-tenant assets all return `null`. Internally resolves the owner from the tenant-scoped private row, then reads through the guarded collection inside a one-id `withPrivateAssetAccess` that closes on return; inside an existing scope it can only narrow (throws `cannot widen` otherwise).\n\nAgents that need asset I/O should accept an `AssetRuntimeLike` in their options rather than asking callers to pass a store + collection separately.\n\n## Serving contract\n\n- `serveAsset({ runtime, asset, tenantId?, disposition?, canAccess?, headers?, remoteMode? })` → standard Web `Response`.\n - `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.\n - 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.\n - `Content-Disposition` uses an ASCII-safe quoted `filename` fallback and retains the Unicode download name in UTF-8 `filename*` ([RFC 6266](https://www.rfc-editor.org/rfc/rfc6266#section-4.3), [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187#section-3.2.1)). Both names strip C0/DEL/C1 controls and replace `\"` / `\\` / `/` to prevent header injection; isolated UTF-16 surrogates become U+FFFD before encoding, while valid pairs are preserved.\n - 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.\n - Works in SvelteKit `+server.ts` endpoints, Hono, and any runtime with a global `Response` (Node 18+). Pass `responseCtor` for older runtimes.\n- `resolveAssetForServing(options)` → `{ asset, data, contentType, filename, size }` when callers want to render their own framework response. Throws `AssetServeError(status)` on the same failure modes.\n\n## Source/derived vocabulary\n\nThe 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:\n\n| Role | Use |\n|------|-----|\n| `source_document` | original upstream document (agenda PDF, minutes) |\n| `document_image` | page/extracted image derived from a source document |\n| `thumbnail` | preview rendition of another asset |\n| `proof` | non-canonical evidence asset backing a fact |\n| `derivation_source` | \"came from\" link on generated media |\n| `attachment` | generic owner-join link |\n| `hero` | primary/featured asset on an owner |\n\nCanonical 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`).\n\n## UI Registry\n\nThe `./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.\n\n```ts\nimport { ASSETS_MODULE_META, ASSETS_UI_SLOTS } from '@happyvertical/smrt-assets/ui';\nimport '@happyvertical/smrt-assets/svelte'; // side-effect: ModuleUIRegistry.register(...)\nimport { ModuleUIRegistry } from '@happyvertical/smrt-ui/registry';\n\nconst AssetManager = ModuleUIRegistry.get('@happyvertical/smrt-assets', 'asset-manager');\n```\n\nRegistered 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.\n\n## Gotchas\n\n- **Files SDK is a lazy boundary (#1979)**: `AssetStore` loads `@happyvertical/files` through `src/files-runtime.ts` (bundler-invisible), because smrt-assets is reachable from provider-neutral consumer graphs via profiles. Node/tsx/vite-dev runtimes resolve it on first file operation; fully-bundled deployments import `@happyvertical/smrt-assets/filesystem` at startup. Never import the files SDK statically from modules reachable from `src/index.ts`.\n- **Version history manual**: `findVersions()` chaining required — no ORM shortcut\n- **Tag management uses raw SQL**: `asset_tags` is a join table, not an SMRT model\n- **Folder tree traversal**: via `SmrtHierarchical` (`getParent`/`getChildren`/`getAncestors`/`getDescendants`/`getHierarchy`/`moveTo`); `FolderCollection.getTree(rootId?)` and `getPath(folderId)` wrap these for convenience\n- **AssetAssociation polymorphic FK**: requires manual `metaType` string matching\n- **Optional tenancy**: assets can be global (tenantId=null) or tenant-scoped\n\n## Private records\n\n`Asset.accessMode` and the mandatory owning interceptor protect private records\nacross generated and parent STI surfaces. Use the exact actor/owner/ID capability\nonly after host authorization; see [private assets](agents/private-assets.md).\nFor display metadata (name, mime type, version) use `AssetRuntime.getPrivateAssetMetadata`\ninstead of reading raw `assets` rows to discover the owner.\n",
|
|
3726
|
+
"agentDoc": "# @happyvertical/smrt-assets\n\nProvider-agnostic asset management with versioning, type classification, and generic/provenance associations.\n\n## Models\n\n- **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`).\n- **AssetType** / **AssetStatus**: lookup tables for classification and lifecycle.\n- **AssetMetafield**: custom metadata field definitions with JSON validation rules.\n- **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.\n- **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`.\n\n## Key Patterns\n\n- **Versioning**: `createNewVersion()` increments version, chains via `primaryVersionId`. `findVersions()` to retrieve history.\n- **Tag integration**: `addTag()`/`removeTag()` use raw `db.upsert()` on `asset_tags` join table (not a SMRT model).\n- **AssetStore**: abstraction for provider-agnostic file I/O (S3, local, etc.).\n `planFile(asset, opts)` resolves a recoverable URI before bytes are written;\n persist it before `preserveFile(asset, bytes, opts)`. Preservation adopts equal\n existing bytes and rejects changed bytes, changed resolver targets and read\n failures other than not-found. The caller owns receipt fencing/serialization.\n `removeFile(asset)` removes only bytes for recovery cleanup, including an\n already-pruned owner record; `remove(asset)` also deletes the owner record.\n Opt into `asset-local:<key>` writes with\n `{ type: 'local', basePath: absoluteRoot, locatorMode: 'relative' }`.\n Keep the root app-owned; portable paths must resolve beneath it without links.\n See [portable local storage](README.md#portable-local-storage) for adoption and\n the legacy locator boundary.\n- **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.\n\n## Runtime surface\n\nApps and agents should depend on the public **asset runtime** rather than hand-wiring a collection + store per-package (#1128).\n\n- `createAssetRuntime({ db, storage })` → `AssetRuntime` bundling `AssetCollection`, `AssetAssociationCollection`, and an initialized `AssetStore`.\n- `AssetRuntime.storeSourceAsset(name, data, opts)` — create a new source asset (record + bytes).\n- `AssetRuntime.storeDerivedAsset(source, name, data, opts)` — create a derivative with `sourceAssetId` set and (by default) a provenance `AssetAssociation` under a chosen role.\n- `AssetRuntime.linkDerivation(source, derivative, { role })` — record provenance without touching bytes.\n- `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.\n\n- `AssetRuntime.getPrivateAssetMetadata({ tenantId, actorUserId, assetId })` → `PrivateAssetMetadata | null` — authorized, tenant-scoped display metadata read of one PRIVATE asset so hosts never read `assets` rows. Trusted server capability (host authorizes first); requires an ambient tenant actor matching `tenantId`/`actorUserId` exactly (throws otherwise, including empty ids). Result is an allowlist (`id, tenantId, name, mimeType, version, typeSlug, statusSlug, createdAt, updatedAt`); never owner, `sourceUri`, description/metadata sidecars. There is no size field on `Asset`. Missing, public and other-tenant assets all return `null`. Internally resolves the owner from the tenant-scoped private row, then reads through the guarded collection inside a one-id `withPrivateAssetAccess` that closes on return; inside an existing scope it can only narrow (throws `cannot widen` otherwise).\n\nAgents that need asset I/O should accept an `AssetRuntimeLike` in their options rather than asking callers to pass a store + collection separately.\n\n## Serving contract\n\n- `serveAsset({ runtime, asset, tenantId?, disposition?, canAccess?, headers?, remoteMode? })` → standard Web `Response`.\n - `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.\n - 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.\n - `Content-Disposition` uses an ASCII-safe quoted `filename` fallback and retains the Unicode download name in UTF-8 `filename*` ([RFC 6266](https://www.rfc-editor.org/rfc/rfc6266#section-4.3), [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187#section-3.2.1)). Both names strip C0/DEL/C1 controls and replace `\"` / `\\` / `/` to prevent header injection; isolated UTF-16 surrogates become U+FFFD before encoding, while valid pairs are preserved.\n - 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.\n - Works in SvelteKit `+server.ts` endpoints, Hono, and any runtime with a global `Response` (Node 18+). Pass `responseCtor` for older runtimes.\n- `resolveAssetForServing(options)` → `{ asset, data, contentType, filename, size }` when callers want to render their own framework response. Throws `AssetServeError(status)` on the same failure modes.\n\n## Source/derived vocabulary\n\nThe 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:\n\n| Role | Use |\n|------|-----|\n| `source_document` | original upstream document (agenda PDF, minutes) |\n| `document_image` | page/extracted image derived from a source document |\n| `thumbnail` | preview rendition of another asset |\n| `proof` | non-canonical evidence asset backing a fact |\n| `derivation_source` | \"came from\" link on generated media |\n| `attachment` | generic owner-join link |\n| `hero` | primary/featured asset on an owner |\n\nCanonical 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`).\n\n## UI Registry\n\nThe `./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.\n\n```ts\nimport { ASSETS_MODULE_META, ASSETS_UI_SLOTS } from '@happyvertical/smrt-assets/ui';\nimport '@happyvertical/smrt-assets/svelte'; // side-effect: ModuleUIRegistry.register(...)\nimport { ModuleUIRegistry } from '@happyvertical/smrt-ui/registry';\n\nconst AssetManager = ModuleUIRegistry.get('@happyvertical/smrt-assets', 'asset-manager');\n```\n\nRegistered 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.\n\n## Gotchas\n\n- **Files SDK is a lazy boundary (#1979)**: `AssetStore` loads `@happyvertical/files` through `src/files-runtime.ts` (bundler-invisible), because smrt-assets is reachable from provider-neutral consumer graphs via profiles. Node/tsx/vite-dev runtimes resolve it on first file operation; fully-bundled deployments import `@happyvertical/smrt-assets/filesystem` at startup. Never import the files SDK statically from modules reachable from `src/index.ts`.\n- **Version history manual**: `findVersions()` chaining required — no ORM shortcut\n- **Tag management uses raw SQL**: `asset_tags` is a join table, not an SMRT model\n- **Folder tree traversal**: via `SmrtHierarchical` (`getParent`/`getChildren`/`getAncestors`/`getDescendants`/`getHierarchy`/`moveTo`); `FolderCollection.getTree(rootId?)` and `getPath(folderId)` wrap these for convenience\n- **AssetAssociation polymorphic FK**: requires manual `metaType` string matching\n- **Optional tenancy**: assets can be global (tenantId=null) or tenant-scoped\n\n## Private records\n\n`Asset.accessMode` and the mandatory owning interceptor protect private records\nacross generated and parent STI surfaces. Use the exact actor/owner/ID capability\nonly after host authorization; see [private assets](agents/private-assets.md).\nFor display metadata (name, mime type, version) use `AssetRuntime.getPrivateAssetMetadata`\ninstead of reading raw `assets` rows to discover the owner.\n",
|
|
3725
3727
|
"moduleDocs": [
|
|
3728
|
+
{
|
|
3729
|
+
"path": "README.md",
|
|
3730
|
+
"module": "README",
|
|
3731
|
+
"content": "# @happyvertical/smrt-assets\n\nProvider-agnostic asset management with versioning, type classification, metadata fields, and generic/provenance associations.\n\n`AssetAssociation` is the generic exception path for linking assets to arbitrary\nobjects when there is not a model-owned noun join table. Base/domain-owned\nrelationships should use dedicated joins such as `content_assets`,\n`profile_assets`, `event_assets`, `place_assets`, and `product_assets`.\n\n## Feature recipes\n\n`assets.library` provides the model-backed file and media library: assets,\nfolders, classifications, statuses, and metadata definitions.\n`assets.attachments` adds record attachment provenance and requires the library.\nThey share the **Files and media** catalog card and the **Assets** navigation\nsection, and both embed user-facing help in the generated manifest. The recipes\npublish browser-safe mock fixture exports from `@happyvertical/smrt-assets/playground`.\n`AssetManager` needs host persistence callbacks and `AttachmentPanel` needs\nrecord-scoped authorized attachments, so neither is declared as a standalone\nplacement. Storage providers remain application-owned, so the recipes declare\nno provider.\n\nThe package playground is a Mock preview. Its asset grid uses in-memory props\nand data-URI thumbnails, and its attachment panel demonstrates supplied native\nform data only. It never performs a real network upload or creates public\nstorage URLs.\n\n## Installation\n\n```bash\npnpm add @happyvertical/smrt-assets\n```\n\n## Usage\n\n```typescript\nimport {\n Asset, AssetCollection,\n AssetType, AssetStatus, AssetMetafield,\n AssetAssociation, AssetAssociationCollection,\n Folder, FolderCollection,\n AssetStore,\n} from '@happyvertical/smrt-assets';\n\n// Create lookup records\nconst imageType = new AssetType({ slug: 'image', name: 'Image' });\nawait imageType.save();\n\nconst published = new AssetStatus({ slug: 'published', name: 'Published' });\nawait published.save();\n\n// Create an asset\nconst photo = new Asset({\n name: 'Product Photo',\n slug: 'product-photo-001',\n sourceUri: 's3://bucket/products/photo-001.jpg',\n mimeType: 'image/jpeg',\n typeSlug: 'image',\n statusSlug: 'published',\n version: 1,\n});\nawait photo.save();\n\n// Versioning -- chain via primaryVersionId, increment version number\nconst v2 = new Asset({\n ...photo, slug: 'product-photo-002', version: 2, primaryVersionId: photo.id,\n sourceUri: 's3://bucket/products/photo-002.jpg',\n});\nawait v2.save();\n\n// Derivatives via sourceAssetId (renamed from `parentId` in R3-D)\nconst thumb = new Asset({\n name: 'Thumbnail', slug: 'product-photo-001-thumb', sourceAssetId: photo.id,\n sourceUri: 's3://bucket/products/photo-001-thumb.jpg',\n mimeType: 'image/jpeg', typeSlug: 'image', statusSlug: 'published',\n});\nawait thumb.save();\n\n// Generic/provenance association -- link asset to an arbitrary object\nconst assoc = new AssetAssociation({\n assetId: photo.id,\n metaType: 'Image',\n metaId: 'derived-image-123',\n role: 'derivation-source',\n sortOrder: 0,\n});\nawait assoc.save();\n\n// Base/domain-owned asset relationships should use dedicated noun joins instead:\n// content_assets, profile_assets, event_assets, place_assets, product_assets\n\n// Folder organization (its own SmrtHierarchical model, `folders` table)\nconst folder = new Folder({ name: 'Product Images', slug: 'product-images' });\nawait folder.save();\n// Move an asset into a folder\nphoto.folderId = folder.id;\nawait photo.save();\n\n// AssetStore -- provider-agnostic file I/O + record creation\nconst store = await new AssetStore(assetRoot, collection).initialize();\nawait store.store('screenshot', buffer, { mimeType: 'image/png' });\n```\n\n## Portable local storage\n\nFor a new desktop installation, pass the same portable storage configuration\nto each asset runtime, worker, and service that handles its managed files:\n\n```ts\nconst assets = await createAssetRuntime({\n db,\n storage: { type: 'local', basePath: assetRoot, locatorMode: 'relative' },\n});\n```\n\nUse an absolute, app-owned `assetRoot`. The store persists\n`asset-local:<key>`, for example `asset-local:document/17f6.txt`.\nThe key is a raw, slash-separated path under the configured root and\ncontains no URL escaping. Use ASCII letters, digits, underscores, and\nhyphens in type slugs and IDs. The store rejects traversal, absolute keys,\nWindows device names, links at or below the root, and non-regular files. Keep\nthe root and its contents under app control; the filesystem checks assume\nno concurrent changes by an untrusted local process.\n\nWhen copying an installation, copy the database and the asset directory\ntogether, keep each file's path within the directory, and set `basePath`\nto the copied directory. Read, preserve, and remove assets through the\nruntime. A storage resolver may choose a path for a portable write, but\nlater reads and deletes must use the stored key in the built-in local\nfilesystem for that runtime.\n\nThe option changes new writes only. Existing local options and S3\nlocators keep their formats. A built-in local store can read portable\nlocators whether or not it opts in to writing them. In portable mode,\nan existing `file://` locator can still be read or removed when it\nidentifies a valid key inside the configured root; changing the root\ndoes not relocate such records. Start with fresh desktop data or handle\nexisting absolute locators before moving an installation.\n\n## API\n\n### Models (SmrtObject)\n\n| Export | Description |\n|--------|------------|\n| `Asset` | Core asset with versioning (`primaryVersionId`, `version`), derivation chain (`sourceAssetId`), `sourceUri`, `mimeType`, `typeSlug`, `statusSlug`, `ownerProfileId` |\n| `AssetAssociation` | Generic/provenance polymorphic join: `assetId` + `metaType` + `metaId` + `role` + `sortOrder`; not for base/domain-owned joins that already have noun tables |\n| `AssetType` | Lookup table for asset type classification |\n| `AssetStatus` | Lookup table for lifecycle status |\n| `AssetMetafield` | Custom metadata field definitions with JSON validation rules |\n| `Folder` | Hierarchical container for assets; own `folders` table extending `SmrtHierarchical` |\n\n### Collections (SmrtCollection)\n\n| Export | Description |\n|--------|------------|\n| `AssetCollection` | Collection for Asset |\n| `AssetAssociationCollection` | Collection for AssetAssociation |\n| `AssetTypeCollection` | Collection for AssetType |\n| `AssetStatusCollection` | Collection for AssetStatus |\n| `AssetMetafieldCollection` | Collection for AssetMetafield |\n| `FolderCollection` | Collection for Folder |\n\n### Utilities\n\n| Export | Description |\n|--------|------------|\n| `AssetStore` | Provider-agnostic file I/O that writes buffers to storage and creates Asset records |\n\n### Types\n\n| Export | Description |\n|--------|------------|\n| `AssetOptions` | Options for `Asset` constructor |\n| `AssetAssociationOptions` | Options for `AssetAssociation` constructor |\n| `AssetTypeOptions` | Options for `AssetType` constructor |\n| `AssetStatusOptions` | Options for `AssetStatus` constructor |\n| `AssetMetafieldOptions` | Options for `AssetMetafield` constructor |\n| `FolderOptions` | Options for `Folder` constructor |\n| `StoreOptions` | Options for `AssetStore.store()` |\n| `ProviderOptions` | Provider configuration for `AssetStore` |\n\n## Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `@happyvertical/smrt-core` | ORM base (SmrtObject, SmrtCollection) |\n| `@happyvertical/smrt-tags` | Tag integration (`addTag`/`removeTag` on assets) |\n| `@happyvertical/smrt-tenancy` | Optional tenant scoping |\n| `@happyvertical/files` | Provider-agnostic filesystem for AssetStore |\n\n## Native private attachments\n\n`AttachmentPanel`, `AttachmentList` and `AttachmentUpload` compose authorized\nprivate links, caller-supplied version history, and native multipart uploads.\nThey preserve request identity and failed-action metadata without deriving\npublic storage URLs. See [the attachment contract](agents/attachments.md) for\npublic types, native payloads, recovery, and server responsibilities.\n\nPass `onremove(attachment)` and/or `removeAction` (native POST of the\nattachment id) to add a confirmed per-attachment Remove button; see\n\"Removing attachments\" in the contract.\n\n### Polymorphic junction collection types\n\n`AssetAssociationCollection` extends `SmrtJunctionBase`, sharing `byRight`,\nordering, positioning, and registration guards with ordinary junctions. Its\n`byLeft`, `attach`, `detach`, and `setLinks` methods still require both `metaType`\nand `metaId`; they do not implement the single-owner `SmrtJunction` contract.\nUse `instanceof SmrtJunctionBase` when recognizing either kind of junction.\nAsset associations no longer satisfy `instanceof SmrtJunction`.\n\nAfter building the workspace, `node scripts/verify-packed-junction-types.mjs`\nchecks actual core/assets tarballs in the standard Bundler mode with\n`skipLibCheck: false`, inherited result types, and negative owner-argument tests.\nFull NodeNext declaration portability is tracked separately in #3524.\n\nThe consumer fixture installs declared dependencies in a temporary directory\nwith no ancestor `node_modules`; it never links producer dependencies. It retains\nthe project’s public registry routing without copying credentials. Set\n`SMRT_PACKED_EVIDENCE_DIR` to retain tarballs and the consumer lockfile. For an\nexplicitly separate upstream-candidate proof, `SMRT_PACKED_OVERRIDES` may name\na JSON file of pnpm overrides; such a proof does not establish that the normal\npublished dependency graph passes.\n"
|
|
3732
|
+
},
|
|
3726
3733
|
{
|
|
3727
3734
|
"path": "agents/private-assets.md",
|
|
3728
3735
|
"module": "private-assets",
|
|
@@ -5,10 +5,10 @@ description: "Asset management system with versioning, metadata, and AI-powered
|
|
|
5
5
|
status: "stable"
|
|
6
6
|
generated:
|
|
7
7
|
by: "smrt/scripts/generate-knowledge-okf.ts"
|
|
8
|
-
at: "2026-11-
|
|
8
|
+
at: "2026-11-06T01:23:41Z"
|
|
9
9
|
audience: "internal"
|
|
10
10
|
evidence_level: "source-inspected"
|
|
11
|
-
source_revision: "sha256:
|
|
11
|
+
source_revision: "sha256:73bdc0cbe39f1720505c0abd7438920e0e7d167f84e8ca629c3cb40127d8027c"
|
|
12
12
|
sources:
|
|
13
13
|
- id: "manifest"
|
|
14
14
|
resource: "https://github.com/happyvertical/smrt/blob/main/packages/assets/package.json"
|
|
@@ -17,6 +17,9 @@ sources:
|
|
|
17
17
|
resource: "https://github.com/happyvertical/smrt/blob/main/packages/assets/AGENTS.md"
|
|
18
18
|
title: "@happyvertical/smrt-assets packages/assets/AGENTS.md"
|
|
19
19
|
- id: "agents-2"
|
|
20
|
+
resource: "https://github.com/happyvertical/smrt/blob/main/packages/assets/README.md"
|
|
21
|
+
title: "@happyvertical/smrt-assets packages/assets/README.md"
|
|
22
|
+
- id: "agents-3"
|
|
20
23
|
resource: "https://github.com/happyvertical/smrt/blob/main/packages/assets/agents/private-assets.md"
|
|
21
24
|
title: "@happyvertical/smrt-assets packages/assets/agents/private-assets.md"
|
|
22
25
|
---
|
|
@@ -33,6 +36,7 @@ sources:
|
|
|
33
36
|
## Documentation
|
|
34
37
|
|
|
35
38
|
- `packages/assets/AGENTS.md`
|
|
39
|
+
- `packages/assets/README.md`
|
|
36
40
|
- `packages/assets/agents/private-assets.md`
|
|
37
41
|
|
|
38
42
|
## Framework dependencies
|
|
@@ -57,6 +61,7 @@ sources:
|
|
|
57
61
|
|
|
58
62
|
- `.`
|
|
59
63
|
- `./filesystem`
|
|
64
|
+
- `./locator`
|
|
60
65
|
- `./manifest`
|
|
61
66
|
- `./manifest.json`
|
|
62
67
|
- `./playground`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@happyvertical/smrt-assets",
|
|
3
|
-
"version": "0.60.
|
|
3
|
+
"version": "0.60.11",
|
|
4
4
|
"smrtJsdoc": "strict",
|
|
5
5
|
"description": "Asset management system with versioning, metadata, and AI-powered operations for SMRT framework",
|
|
6
6
|
"type": "module",
|
|
@@ -22,6 +22,10 @@
|
|
|
22
22
|
"types": "./dist/filesystem.d.ts",
|
|
23
23
|
"import": "./dist/filesystem.js"
|
|
24
24
|
},
|
|
25
|
+
"./locator": {
|
|
26
|
+
"types": "./dist/locator.d.ts",
|
|
27
|
+
"import": "./dist/locator.js"
|
|
28
|
+
},
|
|
25
29
|
"./ui": {
|
|
26
30
|
"types": "./dist/ui.d.ts",
|
|
27
31
|
"import": "./dist/ui.js"
|
|
@@ -48,11 +52,11 @@
|
|
|
48
52
|
"@happyvertical/ai": "^0.111.5",
|
|
49
53
|
"@happyvertical/files": "^0.111.5",
|
|
50
54
|
"@happyvertical/logger": "^0.111.5",
|
|
51
|
-
"@happyvertical/smrt-core": "0.60.
|
|
52
|
-
"@happyvertical/smrt-tags": "0.60.
|
|
53
|
-
"@happyvertical/smrt-tenancy": "0.60.
|
|
54
|
-
"@happyvertical/smrt-types": "0.60.
|
|
55
|
-
"@happyvertical/smrt-ui": "0.60.
|
|
55
|
+
"@happyvertical/smrt-core": "0.60.11",
|
|
56
|
+
"@happyvertical/smrt-tags": "0.60.11",
|
|
57
|
+
"@happyvertical/smrt-tenancy": "0.60.11",
|
|
58
|
+
"@happyvertical/smrt-types": "0.60.11",
|
|
59
|
+
"@happyvertical/smrt-ui": "0.60.11",
|
|
56
60
|
"@happyvertical/sql": "^0.111.5",
|
|
57
61
|
"@happyvertical/utils": "^0.111.5"
|
|
58
62
|
},
|
|
@@ -65,8 +69,8 @@
|
|
|
65
69
|
}
|
|
66
70
|
},
|
|
67
71
|
"devDependencies": {
|
|
68
|
-
"@happyvertical/smrt-playground": "0.60.
|
|
69
|
-
"@happyvertical/smrt-vitest": "0.60.
|
|
72
|
+
"@happyvertical/smrt-playground": "0.60.11",
|
|
73
|
+
"@happyvertical/smrt-vitest": "0.60.11",
|
|
70
74
|
"@sveltejs/adapter-auto": "^7.0.1",
|
|
71
75
|
"@sveltejs/kit": "2.69.1",
|
|
72
76
|
"@sveltejs/package": "^2.5.8",
|