@happyvertical/smrt-tags 0.30.0

package/AGENTS.md

@@ -0,0 +1,22 @@
+# @happyvertical/smrt-tags
+
+Hierarchical tagging with context-scoped slugs and multi-language aliases.
+
+## Models
+
+- **Tag** (STI, extends `SmrtHierarchical`): public identifier is `slug` (not UUID) + `context` (default: 'global'), but the hierarchy FK is `parentId` (UUID) since R3-B. `TagCollection.moveTag` / `mergeTag` / `getChildren` keep slug-string signatures and resolve to UUIDs internally. `level` is a denormalised depth recalculated on `moveTag`. Metadata JSON.
+- **TagAlias**: language-specific translations/aliases (ISO 639-1 `language` code, nullable). Optional context scoping.
+
+## Key Collection Methods
+
+- `getOrCreate(slug, options)`: auto-generates name from slug
+- `moveTag(slug, newParentSlug)`: circular reference detection, level recalculation
+- `mergeTag(sourceSlug, targetSlug)`: moves children + aliases from source to target, then deletes source
+- `cleanupUnused()`: only deletes tags with no children AND no aliases
+- `findWithGlobals(tenantId)`: tenant + global tags
+
+## Gotchas
+
+- **Slug stored in protected `_slug`**: has override getter/setter (not standard SmrtObject slug behavior)
+- **Context defaults to 'global'**: if not specified
+- **Optional tenancy** with nullable tenantId

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @happyvertical/smrt-tags
+
+Hierarchical tagging with context-scoped slugs, multi-language aliases, and slug utilities.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-tags
+```
+
+## Usage
+
+```typescript
+import { Tag, TagCollection, TagAlias, TagAliasCollection } from '@happyvertical/smrt-tags';
+import { sanitizeSlug, validateSlug, generateUniqueSlug } from '@happyvertical/smrt-tags';
+
+// Create a tag hierarchy
+const collection = await TagCollection.create();
+
+// `collection.create(...)` returns the saved row, so use it directly
+// instead of `new Tag()` + a separate `.create(...)` step. The returned
+// instance has its persisted `id` set for use as a parent reference.
+const tech = await collection.create({
+  slug: 'technology',
+  name: 'Technology',
+  context: 'blog', // defaults to 'global' if omitted
+});
+
+// Children reference their parent by UUID (`parentId`). With `tech`
+// already saved, pass `tech.id` directly. `level` is recalculated by
+// `TagCollection.moveTag` / `mergeTag` for later moves; you can pass it
+// explicitly on create or let it stay at 0 and call moveTag later.
+const ai = await collection.create({
+  slug: 'artificial-intelligence',
+  name: 'Artificial Intelligence',
+  context: 'blog',
+  parentId: tech.id,
+  level: 1,
+});
+
+// Traverse hierarchy
+const children = await tech.getChildren();
+const ancestors = await ai.getAncestors();
+
+// Context scoping -- same slug, different contexts
+const blogNews = new Tag({ slug: 'news', name: 'News', context: 'blog' });
+const forumNews = new Tag({ slug: 'news', name: 'Forum News', context: 'forum' });
+
+// Multi-language aliases
+const aliasCollection = await TagAliasCollection.create();
+const alias = new TagAlias({
+  tagSlug: 'technology',
+  alias: 'Tecnologia',
+  language: 'es',
+  context: 'blog',
+});
+await aliasCollection.create(alias);
+
+// Collection operations. Slug args resolve through (slug, context) —
+// pass an explicit context when the same slug exists in multiple
+// contexts, otherwise the resolver throws on ambiguity.
+await collection.moveTag('artificial-intelligence', 'technology', 'blog'); // cycle-checked
+await collection.mergeTag('source', 'target', 'blog');                     // moves children + aliases, deletes source
+await collection.cleanupUnused();                                          // deletes tags with no children and no aliases
+
+// Slug utilities
+sanitizeSlug('My Cool Tag!');   // 'my-cool-tag'
+validateSlug('my-tag-123');     // true
+```
+
+## API
+
+### Models (SmrtObject)
+
+| Export | Description |
+|--------|------------|
+| `Tag` | Identified by `slug` + `context`. Hierarchical via `parentId` (UUID, inherited from `SmrtHierarchical`). Denormalised `level` recalculated by `TagCollection.moveTag` / `mergeTag`. JSON `metadata`. Hierarchy methods inherited: `getParent()`, `getChildren()`, `getAncestors()`, `getDescendants()`, `getHierarchy()`, `moveTo()`. Own helpers: `getMetadata()`, `setMetadata()`, `updateMetadata()` |
+| `TagAlias` | Language-specific translations: `tagSlug`, `alias`, `language` (ISO 639-1), optional `context` |
+
+### Collections (SmrtCollection)
+
+| Export | Description |
+|--------|------------|
+| `TagCollection` | CRUD + `getOrCreate()`, `moveTag()`, `mergeTag()`, `cleanupUnused()`, `findWithGlobals()` |
+| `TagAliasCollection` | CRUD for tag aliases |
+
+### Utilities
+
+| Export | Description |
+|--------|------------|
+| `sanitizeSlug(input)` | Clean and format slug strings |
+| `validateSlug(slug)` | Validate slug format (lowercase, alphanumeric + hyphens) |
+| `generateUniqueSlug(name, context, collection)` | Auto-numbered unique slug generation |
+| `calculateLevel(parentSlug, collection)` | Determine hierarchy depth from parent |
+| `hasCircularReference(slug, parentSlug, collection)` | Detect circular parent references |
+
+### Types
+
+| Export | Description |
+|--------|------------|
+| `TagOptions` | Options for `Tag` constructor |
+| `TagAliasOptions` | Options for `TagAlias` constructor |
+| `TagMetadata` | Flexible metadata structure (colors, icons, statistics) |
+| `TagHierarchy` | Complete hierarchy result (ancestors, current, descendants) |
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@happyvertical/smrt-core` | ORM base (SmrtObject, SmrtCollection) |
+| `@happyvertical/smrt-tenancy` | Optional tenant scoping |

package/dist/index.d.ts

@@ -0,0 +1,450 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtHierarchical } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+
+/**
+ * Calculate hierarchy level
+ *
+ * Determines the level (depth) of a tag based on its parent.
+ * Root tags have level 0, their children have level 1, etc.
+ *
+ * @param parentSlug - The parent tag slug (null for root)
+ * @param tagCollection - TagCollection instance for queries
+ * @returns The calculated level
+ */
+export declare function calculateLevel(parentSlug: string | null, tagCollection: TagCollection): Promise<number>;
+
+/**
+ * Generate a unique slug from a name
+ *
+ * Creates a slug and ensures uniqueness by appending a number if needed.
+ *
+ * @param name - The name to convert to slug
+ * @param context - The context for uniqueness checking
+ * @param tagCollection - TagCollection instance for queries
+ * @returns Unique slug
+ */
+export declare function generateUniqueSlug(name: string, context: string, tagCollection: TagCollection): Promise<string>;
+
+/**
+ * Validate hierarchy for circular references
+ *
+ * Checks if setting a parent would create a circular reference
+ * (e.g., making a tag its own ancestor). The actual move call in
+ * `TagCollection.moveTag` also runs `SmrtHierarchical.moveTo`'s
+ * descendant-cycle check; this helper remains exported for callers that
+ * want to pre-validate a candidate parent without attempting the move.
+ *
+ * Tags are identified by `(slug, context)`. If `context` is omitted,
+ * slug-only lookups are used — fine when slugs are unique across all
+ * contexts, but the walk can traverse the wrong chain when the same
+ * slug exists in multiple contexts. Pass the candidate parent's
+ * `context` for accurate cross-context-safe validation.
+ *
+ * @param slug - The tag being moved
+ * @param parentSlug - The proposed new parent
+ * @param tagCollection - TagCollection instance for queries
+ * @param context - Optional context to scope every slug lookup to
+ * @returns True if circular reference detected
+ */
+export declare function hasCircularReference(slug: string, parentSlug: string, tagCollection: TagCollection, context?: string): Promise<boolean>;
+
+/**
+ * Sanitize slug input
+ *
+ * Converts to lowercase, replaces spaces with hyphens,
+ * removes invalid characters, and ensures proper format.
+ *
+ * @param input - The input string to sanitize
+ * @returns Sanitized slug
+ */
+export declare function sanitizeSlug(input: string): string;
+
+export declare class Tag extends SmrtHierarchical {
+    protected _slug: string;
+    protected _context: string;
+    get slug(): string;
+    set slug(value: string);
+    get context(): string;
+    set context(value: string);
+    name: string;
+    level: number;
+    description: string;
+    metadata: string;
+    tenantId: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    constructor(options?: TagOptions);
+    /**
+     * Get metadata as parsed object
+     *
+     * @returns Parsed metadata object or empty object if no metadata
+     */
+    getMetadata(): TagMetadata;
+    /**
+     * Set metadata from object
+     *
+     * @param data - Metadata object to store
+     */
+    setMetadata(data: TagMetadata): void;
+    /**
+     * Update metadata by merging with existing values
+     *
+     * @param updates - Partial metadata to merge
+     */
+    updateMetadata(updates: Partial<TagMetadata>): void;
+    /**
+     * Convenience method for slug-based lookup
+     *
+     * @param slug - The slug to search for
+     * @param context - Optional context filter
+     * @returns Tag instance or null if not found
+     */
+    static getBySlug(_slug: string, _context?: string): Promise<Tag | null>;
+    /**
+     * Get root tags (no parent) for a context
+     *
+     * @param context - The context to filter by
+     * @returns Array of root tags
+     */
+    static getRootTags(_context?: string): Promise<Tag[]>;
+}
+
+export declare class TagAlias extends SmrtObject {
+    tagSlug: string;
+    alias: string;
+    language: string;
+    protected _context: string;
+    get context(): string;
+    set context(value: string);
+    tenantId: string | null;
+    createdAt: Date;
+    constructor(options?: TagAliasOptions);
+    /**
+     * Get the tag this alias belongs to
+     *
+     * @returns Tag instance or null if not found
+     */
+    getTag(): Promise<Tag | null>;
+    /**
+     * Search tags by alias
+     *
+     * @param alias - The alias to search for
+     * @param language - Optional language filter
+     * @returns Array of matching tags
+     */
+    static searchByAlias(_alias: string, _language?: string): Promise<Tag[]>;
+    /**
+     * Get all aliases for a tag
+     *
+     * @param tagSlug - The tag slug to get aliases for
+     * @returns Array of TagAlias instances
+     */
+    static getAliasesForTag(_tagSlug: string): Promise<TagAlias[]>;
+}
+
+export declare class TagAliasCollection extends SmrtCollection<TagAlias> {
+    static readonly _itemClass: typeof TagAlias;
+    /**
+     * Add an alias to a tag (get or create)
+     *
+     * @param tagSlug - The tag slug
+     * @param alias - The alias text
+     * @param language - Optional language code
+     * @param context - Optional context
+     * @returns TagAlias instance
+     */
+    addAlias(tagSlug: string, alias: string, language?: string, context?: string): Promise<TagAlias>;
+    /**
+     * Search tags by alias
+     *
+     * @param alias - The alias to search for
+     * @param language - Optional language filter
+     * @returns Array of matching tags
+     */
+    searchByAlias(alias: string, language?: string): Promise<Tag[]>;
+    /**
+     * Get all aliases for a tag
+     *
+     * @param tagSlug - The tag slug
+     * @param language - Optional language filter
+     * @returns Array of TagAlias instances
+     */
+    getAliasesForTag(tagSlug: string, language?: string): Promise<TagAlias[]>;
+    /**
+     * Remove an alias by ID
+     *
+     * @param aliasId - The alias UUID
+     */
+    removeAlias(aliasId: string): Promise<void>;
+    /**
+     * Bulk add aliases to a tag
+     *
+     * @param tagSlug - The tag slug
+     * @param aliases - Array of alias configurations
+     * @returns Array of created TagAlias instances
+     */
+    bulkAddAliases(tagSlug: string, aliases: Array<{
+        alias: string;
+        language?: string;
+        context?: string;
+    }>): Promise<TagAlias[]>;
+    /**
+     * Get aliases grouped by language
+     *
+     * @param tagSlug - The tag slug
+     * @returns Map of language code to array of aliases
+     */
+    getAliasesByLanguage(tagSlug: string): Promise<Map<string, string[]>>;
+    /**
+     * Find matching aliases (case-insensitive partial match)
+     *
+     * Note: This is a simple implementation. For production use,
+     * consider using full-text search or fuzzy matching.
+     *
+     * @param query - The search query
+     * @param language - Optional language filter
+     * @returns Array of matching TagAlias instances
+     */
+    findMatchingAliases(query: string, language?: string): Promise<TagAlias[]>;
+    /**
+     * Find all tag aliases belonging to a specific tenant
+     *
+     * @param tenantId - The tenant ID to filter by
+     * @returns Array of tag aliases for the specified tenant
+     */
+    findByTenant(tenantId: string): Promise<TagAlias[]>;
+    /**
+     * Find all global (tenant-less) tag aliases
+     *
+     * @returns Array of global tag aliases with null tenantId
+     */
+    findGlobal(): Promise<TagAlias[]>;
+    /**
+     * Find tag aliases for a tenant including global aliases
+     *
+     * @param tenantId - The tenant ID to filter by
+     * @returns Array of tag aliases for the tenant plus all global aliases
+     */
+    findWithGlobals(tenantId: string): Promise<TagAlias[]>;
+}
+
+/**
+ * Options for creating a TagAlias instance
+ */
+export declare interface TagAliasOptions extends SmrtObjectOptions {
+    tagSlug?: string;
+    alias?: string;
+    language?: string;
+    context?: string;
+    tenantId?: string | null;
+}
+
+export declare class TagCollection extends SmrtCollection<Tag> {
+    static readonly _itemClass: typeof Tag;
+    /**
+     * Get or create a tag with context
+     *
+     * @param slug - Tag slug
+     * @param context - Tag context (default: 'global')
+     * @returns Tag instance
+     */
+    getOrCreate(slug: string, context?: string): Promise<Tag>;
+    /**
+     * Resolve a tag by slug, optionally scoped to a context.
+     *
+     * Tags are identified by `(slug, context)`. When `context` is omitted
+     * and the slug exists in more than one context, this throws a clear
+     * ambiguity error rather than silently picking the first matching row.
+     * Callers that know their context should pass it; callers that work in
+     * a single-context world can leave it off.
+     *
+     * @returns The matching Tag, or `null` if nothing matches.
+     * @throws Error if `context` is omitted and the slug is ambiguous.
+     */
+    private resolveBySlug;
+    /**
+     * List tags by context with optional parent filtering by slug.
+     *
+     * @param context - The context to filter by
+     * @param parentSlug - Optional parent slug to filter children. Pass an
+     *   empty string or `null` to find root tags; pass a slug to find that
+     *   tag's immediate children. Typed as `string | null` so TypeScript
+     *   callers can pass `null` without a cast — the `null` and `''` paths
+     *   are both treated as "roots only".
+     * @returns Array of matching tags
+     */
+    listByContext(context: string, parentSlug?: string | null): Promise<Tag[]>;
+    /**
+     * Get root tags (no parent) for a context
+     *
+     * @param context - The context to filter by (default: 'global')
+     * @returns Array of root tags
+     */
+    getRootTags(context?: string): Promise<Tag[]>;
+    /**
+     * Get immediate children of a parent tag, looked up by slug.
+     *
+     * @param parentSlug - The parent tag slug
+     * @param context - Optional context for the parent lookup. When omitted,
+     *   the parent slug must be unambiguous across contexts (throws if not).
+     * @returns Array of child tags, or `[]` if the parent slug doesn't
+     *   resolve. Children are filtered to the resolved parent's context so
+     *   cross-context children don't leak in.
+     */
+    getChildren(parentSlug: string, context?: string): Promise<Tag[]>;
+    /**
+     * Get tag hierarchy (all ancestors and descendants)
+     *
+     * @param slug - The tag slug
+     * @param context - Optional context for the slug lookup. When omitted,
+     *   the slug must be unambiguous across contexts.
+     * @returns Object with ancestors, current tag, and descendants
+     */
+    getHierarchy(slug: string, context?: string): Promise<TagHierarchy>;
+    /**
+     * Move a tag to a new parent. Slug-based API; UUIDs resolved internally.
+     *
+     * Cycle detection is inlined here (mirroring `SmrtHierarchical.moveTo`'s
+     * self-loop + descendant checks) so that both `parentId` and the
+     * denormalised `level` field can be persisted in a single `save()`.
+     * Delegating to `moveTo` would write `parentId` first and `level` in a
+     * second save — if the second save failed, the tag would be left with
+     * the new parent but a stale level, breaking the depth cache.
+     *
+     * After the moved tag persists, descendant levels are recalculated
+     * recursively via `updateDescendantLevels`.
+     *
+     * @param slug - The tag to move
+     * @param newParentSlug - The new parent slug (null for root)
+     * @param context - Optional context. When provided, both source and new
+     *   parent are resolved within it. When omitted, both slugs must be
+     *   unambiguous across contexts; the resolver throws otherwise.
+     * @throws Error if either slug fails to resolve, if either slug is
+     *   ambiguous across contexts (no context provided), if source and new
+     *   parent live in different contexts, or if the move would create a
+     *   cycle.
+     */
+    moveTag(slug: string, newParentSlug: string | null, context?: string): Promise<void>;
+    /**
+     * Merge one tag into another (updates all references)
+     *
+     * Reparents `fromTag`'s direct children onto `toTag` and recalculates
+     * their `level` field plus the level of every descendant — without
+     * this, children moved from a different depth would carry stale
+     * levels relative to their new parent. `TagAlias.tagSlug` references
+     * are also rewritten, then `fromTag` is deleted.
+     *
+     * Note: Consuming packages are responsible for updating their own
+     * join tables (e.g. `asset_tags`).
+     *
+     * @param fromSlug - The tag to merge from
+     * @param toSlug - The tag to merge into
+     * @param context - Optional context. When provided, both tags are
+     *   resolved within it. When omitted, both slugs must be unambiguous
+     *   across contexts.
+     * @throws Error if either slug fails to resolve, if either slug is
+     *   ambiguous, or if the two tags live in different contexts.
+     */
+    mergeTag(fromSlug: string, toSlug: string, context?: string): Promise<void>;
+    /**
+     * Remove tags with no references (cleanup unused tags)
+     *
+     * Note: This requires consuming packages to provide usage information.
+     * By default, only removes tags with no children and no aliases.
+     *
+     * @param context - Optional context to filter cleanup
+     */
+    cleanupUnused(context?: string): Promise<number>;
+    /**
+     * Calculate hierarchy level for a tag, looking the parent up by slug.
+     *
+     * @param parentSlug - The parent tag slug (null/empty for root)
+     * @param context - Optional context for the parent lookup. When
+     *   omitted, the parent slug must be unambiguous across contexts.
+     * @returns The calculated level (root parent → 1, missing parent → 0)
+     */
+    calculateLevel(parentSlug: string | null, context?: string): Promise<number>;
+    /**
+     * Update levels for all descendants after moving a tag
+     *
+     * @param tag - The tag that was moved
+     */
+    private updateDescendantLevels;
+    /**
+     * Find all tags belonging to a specific tenant
+     *
+     * @param tenantId - The tenant ID to filter by
+     * @returns Array of tags for the specified tenant
+     */
+    findByTenant(tenantId: string): Promise<Tag[]>;
+    /**
+     * Find all global (tenant-less) tags
+     *
+     * @returns Array of global tags with null tenantId
+     */
+    findGlobal(): Promise<Tag[]>;
+    /**
+     * Find tags for a tenant including global tags
+     *
+     * @param tenantId - The tenant ID to filter by
+     * @returns Array of tags for the tenant plus all global tags
+     */
+    findWithGlobals(tenantId: string): Promise<Tag[]>;
+}
+
+/**
+ * Tag hierarchy result structure
+ */
+export declare interface TagHierarchy {
+    ancestors: Tag[];
+    current: Tag;
+    descendants: Tag[];
+}
+
+/**
+ * Tag metadata structure (flexible, application-specific)
+ */
+export declare interface TagMetadata {
+    color?: string;
+    backgroundColor?: string;
+    icon?: string;
+    emoji?: string;
+    usageCount?: number;
+    lastUsed?: string;
+    trending?: boolean;
+    featured?: boolean;
+    sortOrder?: number;
+    showInNav?: boolean;
+    displayFormat?: string;
+    aiGenerated?: boolean;
+    confidence?: number;
+    source?: string;
+    reviewStatus?: string;
+    [key: string]: any;
+}
+
+/**
+ * Options for creating a Tag instance
+ */
+export declare interface TagOptions extends SmrtObjectOptions {
+    slug?: string;
+    name?: string;
+    context?: string;
+    parentId?: string | null;
+    level?: number;
+    description?: string;
+    metadata?: string | Record<string, any>;
+    tenantId?: string | null;
+}
+
+/**
+ * Validate slug format (lowercase, alphanumeric + hyphens)
+ *
+ * @param slug - The slug to validate
+ * @returns True if slug is valid
+ */
+export declare function validateSlug(slug: string): boolean;
+
+export { }