@happyvertical/smrt-content 0.30.0

package/dist/asset-associable.d.ts

@@ -0,0 +1,115 @@
+import { Asset } from '@happyvertical/smrt-assets';
+/**
+ * Contract for objects that participate in the content/asset association
+ * pattern.
+ *
+ * Any class that exposes asset-relationship methods (e.g. `Content` and its
+ * STI subclasses) implements this interface explicitly so consumers can rely
+ * on the methods existing instead of falling back to `typeof === 'function'`
+ * duck-typing checks.
+ *
+ * @example
+ * ```ts
+ * import type { AssetAssociable } from '@happyvertical/smrt-content';
+ *
+ * async function attachThumbnail(
+ *   target: AssetAssociable,
+ *   image: Asset,
+ * ): Promise<void> {
+ *   // No defensive runtime checks needed — the contract guarantees the method.
+ *   await target.addAsset(image, 'thumbnail', 0);
+ * }
+ * ```
+ */
+export interface AssetAssociable {
+    /**
+     * Get all assets associated with this object.
+     *
+     * @param relationship - Optional filter by relationship type
+     *   (e.g. `'thumbnail'`, `'attachment'`).
+     * @returns Array of associated assets. Returns an empty array if the object
+     *   has not been persisted yet.
+     */
+    getAssets(relationship?: string): Promise<Asset[]>;
+    /**
+     * Associate an asset with this object via a typed relationship.
+     *
+     * @param asset - The asset to associate. Must be persisted (have an `id`).
+     * @param relationship - Relationship type. Must match
+     *   `/^[a-zA-Z_][a-zA-Z0-9_]*$/`. Defaults to `'attachment'`.
+     * @param sortOrder - Non-negative integer for display order.
+     * @throws if either side is unsaved or the relationship/sort order is invalid.
+     */
+    addAsset(asset: Asset, relationship?: string, sortOrder?: number): Promise<void>;
+    /**
+     * Remove an associated asset.
+     *
+     * @param assetId - The asset ID to detach.
+     * @param relationship - Optional specific relationship to remove. If omitted,
+     *   all relationships between this object and the asset are removed.
+     */
+    removeAsset(assetId: string, relationship?: string): Promise<void>;
+}
+/**
+ * Contract for objects exposing typed access to a `metadata` JSON field.
+ *
+ * Use alongside an explicit interface (such as {@link AssetAssociable}) to
+ * give consumers a stable contract for reading/writing the loose JSON bag,
+ * without leaking the `metadata: Record<string, any>` type into call sites.
+ */
+export interface MetadataAccessor<TMetadata extends Record<string, any> = Record<string, any>> {
+    /**
+     * Get the full metadata record. Always returns an object (never `null`).
+     * The returned reference is the live object — callers should treat it as
+     * read-only and use {@link MetadataAccessor.setMetadata} or
+     * {@link MetadataAccessor.updateMetadata} to mutate it safely.
+     */
+    getMetadata(): TMetadata;
+    /**
+     * Replace the entire metadata record.
+     *
+     * @param metadata - The new metadata object. `null`/`undefined` clears it.
+     */
+    setMetadata(metadata: TMetadata | null | undefined): void;
+    /**
+     * Shallow-merge the supplied patch over the existing metadata.
+     *
+     * @param patch - Partial metadata. Keys present in the patch overwrite the
+     *   existing record; keys absent from the patch are preserved.
+     * @returns The merged metadata record.
+     */
+    updateMetadata(patch: Partial<TMetadata>): TMetadata;
+}
+/**
+ * Runtime type guard for {@link AssetAssociable}.
+ *
+ * The interface exists primarily so that statically-typed consumers can drop
+ * defensive `typeof === 'function'` checks. This guard is for the rare cases
+ * where a value enters the system as `unknown` (deserialised payload, plugin
+ * input, etc.) and the caller needs to confirm shape before delegating.
+ *
+ * @example
+ * ```ts
+ * if (isAssetAssociable(input)) {
+ *   await input.addAsset(asset, 'attachment');
+ * }
+ * ```
+ */
+export declare function isAssetAssociable(value: unknown): value is AssetAssociable;
+/**
+ * Runtime type guard for {@link MetadataAccessor}.
+ *
+ * Mirrors {@link isAssetAssociable} for the metadata-accessor contract.
+ */
+export declare function isMetadataAccessor(value: unknown): value is MetadataAccessor;
+/**
+ * Returns `true` if `value` is a plain object (not an array, not `null`,
+ * not a class instance with a custom prototype). Used by `Content`'s metadata
+ * accessors to enforce the "record-shaped" contract — arrays and other
+ * non-record objects are normalised to `{}` rather than silently leaked
+ * through.
+ *
+ * @internal
+ */
+export declare function isPlainMetadataRecord(value: unknown): value is Record<string, any>;
+//# sourceMappingURL=asset-associable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asset-associable.d.ts","sourceRoot":"","sources":["../src/asset-associable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAEnD;;;;;;;;OAQG;IACH,QAAQ,CACN,KAAK,EAAE,KAAK,EACZ,YAAY,CAAC,EAAE,MAAM,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAC/B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAE3D;;;;;OAKG;IACH,WAAW,IAAI,SAAS,CAAC;IAEzB;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;IAE1D;;;;;;OAMG;IACH,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAQ1E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAQ5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAK9B"}

package/dist/body-format.d.ts

@@ -0,0 +1,29 @@
+export type ContentBodyFormat = 'markdown' | 'html';
+export type ContentBodyImagePlacement = 'block' | 'left' | 'right' | 'center' | 'full';
+export interface ContentBodyImage {
+    src: string;
+    alt: string;
+    title?: string;
+    assetId?: string;
+    placement?: ContentBodyImagePlacement;
+    width?: number;
+    index: number;
+}
+export declare const DEFAULT_CONTENT_BODY_FORMAT: ContentBodyFormat;
+export declare function isContentBodyFormat(value: unknown): value is ContentBodyFormat;
+export declare function looksLikeHtml(value: unknown): boolean;
+export declare function resolveBodyFormat(format: unknown, body?: unknown): ContentBodyFormat;
+export declare function escapeHtml(value: string): string;
+export declare function escapeAttribute(value: string): string;
+export declare function sanitizeHtml(value: string): string;
+export declare function renderMarkdownToHtml(markdown: string): string;
+export declare function stripHtml(value: string): string;
+export declare function htmlToMarkdown(html: string): string;
+export declare function normalizeEditorHtml(html: string): string;
+export declare function bodyToEditorHtml(body: string, format: ContentBodyFormat): string;
+export declare function editorHtmlToBody(html: string, format: ContentBodyFormat): string;
+export declare function extractBodyImages(body: string, format?: ContentBodyFormat): ContentBodyImage[];
+export declare function getImageSource(asset: any): string;
+export declare function getImageAlt(asset: any): string;
+export declare function imageAssetToHtml(asset: any): string;
+//# sourceMappingURL=body-format.d.ts.map

package/dist/body-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-format.d.ts","sourceRoot":"","sources":["../src/body-format.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,MAAM,CAAC;AACpD,MAAM,MAAM,yBAAyB,GACjC,OAAO,GACP,MAAM,GACN,OAAO,GACP,QAAQ,GACR,MAAM,CAAC;AAEX,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,2BAA2B,EAAE,iBAA0B,CAAC;AAqErE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAErD;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,OAAO,EACf,IAAI,GAAE,OAAY,GACjB,iBAAiB,CAcnB;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBhD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAsGD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAyFlD;AAgCD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAqE7D;AAuGD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AA6ED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBnD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWxD;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAIR;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAIR;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,iBAAsD,GAC7D,gBAAgB,EAAE,CAyFpB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAEjD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAE9C;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAenD"}