MetaLinks

1. Overview

Property	Value
Status	Stable
Owner	platform
Depends on	MetaLink model from @nx/core, PostgresCoreDataSource
Controller	MetaLinkController (/meta-links)
Repository	MetaLinkRepository (thin DefaultCRUDRepository)

A MetaLink is the DB record describing a stored S3 object and (optionally) the business entity it belongs to. The model lives in @nx/core so commerce/ledger can reference it without circular deps (ADR-0002).

2. Entity Model

See Domain Model for the full field table and indexes.

Field	Type	Required	Description
bucketName / objectName	text	✓	Identifies the stored S3 object
link	text	✓	Relative access path /assets/objects/{name}
mimetype / size / etag	—	mixed	From S3 stat
variant	text		Caller-supplied role tag
storageType	text	✓	Always s3 today
isSynced	boolean	✓	true once mirroring the object
principalType / principalId	text		Polymorphic owner (no DB FK)

Principal types (MetaLinkPrincipalTypes): Product, ProductVariant, Organizer, Ledger, Category.

3. Lifecycle

From	Event	To	Guards
*	upload	Created	created in same handler as S3 put; failures captured into metaLinkError, not thrown
Created	updateById	Updated	MetaLinkUpdateSchema body
Created	object delete	Deleted	deleteAll({ bucketName, objectName }) (hard delete, no soft-delete column)

4. Operations

Handler	Purpose	Inputs	Output
MetaLinkRepository.create	Insert a MetaLink (used by upload)	MetaLinkInsertSchema data	{ data: MetaLink }
MetaLinkRepository.deleteAll	Remove rows by { bucketName, objectName }	filter	count
MetaLinkController (CRUD factory)	Standard find/findById/findOne/count/create/updateById/deleteById/deleteBy	per-route schema	per-route

MetaLinkRepository adds no custom methods — it is DefaultCRUDRepository<TMetaLinkSchema, TMetaLink>.

5. REST Endpoints

MetaLinkController is ControllerFactory.defineCrudController(). Full schemas render live from the host's /doc/openapi.json. Source: controllers/meta-link/meta-link.controller.ts.

Verb	Path	Auth	Authorize
GET	/meta-links	JWT / BASIC	skipped
GET	/meta-links/{id}	JWT / BASIC	skipped
GET	/meta-links/count	JWT / BASIC	skipped
GET	/meta-links/find-one	JWT / BASIC	skipped
POST	/meta-links	JWT / BASIC	skipped (MetaLinkInsertSchema)
PATCH	/meta-links/{id}	JWT / BASIC	skipped (MetaLinkUpdateSchema)
DELETE	/meta-links/{id}	JWT / BASIC	skipped
DELETE	/meta-links (by filter)	JWT / BASIC	skipped

AssetPermissions (= MetaLink CRUD perms from crudPermissions) are declared but not enforced — every route sets authorize: { skip: true } today.

6. Events

Inbound / Outbound: none (see API Events).

7. Related Pages

• Domain Model
• Storage
• API Events
• ADR-0002 — MetaLink polymorphic principal