# smart-tags

A Convex component for smart tagging and categorization with hierarchy and analytics

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-smart-tags
- Source: https://github.com/itsminhz/convex-smart-tags
- npm: https://www.npmjs.com/package/convex-smart-tags
- Directory: https://bijection.com/components/convex-smart-tags

Read the upstream README for setup, license, and compatibility before using it.

## Upstream package documentation

Recorded 2026-10-23. This describes convex-smart-tags; check the Bijection adaptation separately.

convex-smart-tags is a Convex component that adds tagging infrastructure across any table in your Convex project. It provides tag CRUD, parent-child tag hierarchies with ancestor traversal, daily usage tracking, and trending calculations through a type-safe TypeScript client wrapper. The component registers its own tables (tags, entityTags, tagHierarchy, tagAnalytics) and exposes a clean API callable from mutations and queries without any schema modifications to your existing tables.

### Use cases

- Adding user-defined labels to heterogeneous entity types (posts, comments, products) from a single shared tag store without duplicating tagging logic per table
- Building a content taxonomy where tags have parent-child relationships and you need ancestor chain lookups or subtree queries (e.g., 'technology' -> 'ai' -> 'llms')
- Surfacing trending or popular tags over a configurable time window for a discovery or search feature
- Auditing cross-table tag usage to understand which entity types use which tags and at what volume
- Bootstrapping a tagging system quickly in a Convex project without writing custom schema, indexes, and query logic from scratch

### How it works

Register the component in `convex/convex.config.ts` using `app.use(smartTags)`. This mounts the component's internal tables (tags, entityTags, tagHierarchy, tagAnalytics) into your Convex deployment under its own namespace, leaving your existing schema untouched.

Instantiate the `SmartTags` client with `new SmartTags(components.smartTags)` inside your server-side files. The client exposes methods like `addTag`, `removeTag`, `getTagsForEntity`, and `getEntitiesByTag`, each taking a `tableName` and `entityId` string so tags are scoped per entity type without requiring foreign key constraints or schema changes.

Hierarchy is managed via `createTagHierarchy`, `getChildTags`, and `getTagAncestors`. These operate on the tagHierarchy table, which is indexed by parent and child tag name, enabling traversal in both directions.

Analytics are tracked automatically at the daily granularity in the tagAnalytics table. `getTrendingTags` accepts a `timeRange` in milliseconds and returns tags ranked by usage velocity, while `getTagStats` returns per-tag aggregate counts including recent trend data.

### Upstream README

# Convex Smart Tags Component

A reusable Convex component that provides intelligent tagging and categorization capabilities with hierarchical organization and analytics. Designed for easy integration into Convex projects and to work across multiple tables and entity types.

## Why use this component

- Core tag management (add, remove, query tags) across table boundaries
- Tag hierarchy support (parent-child relationships, ancestor/descendant lookups)
- Tag analytics and trending (daily counts, trending calculation)
- Type-safe TypeScript client wrapper for convenient usage in Convex functions
- Example app and test helpers included for fast onboarding

## Features

- Add and remove tags from any entity
- Query tags for an entity and entities by tag
- Create and query parent-child tag relationships
- Track daily tag usage and compute trending tags
- Cross-table tag usage statistics
- Full TypeScript types for client and server integration

## Installation

Install from npm:

```bash
npm install convex-smart-tags
# or
yarn add convex-smart-tags
```

## Quick start

1. Add the component to your Convex app configuration:

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import smartTags from "convex-smart-tags/convex.config";

const app = defineApp();
app.use(smartTags);

export default app;
```

2. Use the client wrapper inside Convex functions:

```ts
// functions.ts (Convex server-side code)
import { SmartTags } from "convex-smart-tags";
import { components } from "./_generated/api";
import { mutation, query } from "./_generated/server";

const smartTags = new SmartTags(components.smartTags);

export const tagPost = mutation({
  handler: async (ctx) => {
    const postId = "post123";
    await smartTags.addTag(ctx, {
      tagName: "urgent",
      tableName: "posts",
      entityId: postId,
    });
  },
});

export const getPostTags = query({
  args: { postId: v.id("posts") },
  handler: async (ctx, args) => {
    return smartTags.getTagsForEntity(ctx, {
      tableName: "posts",
      entityId: args.postId,
    });
  },
});
```

See the `example/` directory for a complete working example application.

## API overview

The component exposes a client wrapper `SmartTags` with a type-safe surface. Primary methods include:

- addTag(ctx, args: { tagName, tableName, entityId }): Promise<void>
- removeTag(ctx, args: { tagName, tableName, entityId }): Promise<void>
- getTagsForEntity(ctx, args: { tableName, entityId }): Promise<Array<string>>
- getEntitiesByTag(ctx, args: { tagName, tableName?, limit? }): Promise<Array<{ tableName, entityId }>>
- createTagHierarchy(ctx, args: { parentTag, childTag }): Promise<void>
- getChildTags(ctx, args: { parentTag, limit? }): Promise<Array<{ tagName, level }>>
- getTagAncestors(ctx, args: { tagName }): Promise<Array<{ tagName, level }>>
- getTrendingTags(ctx, args: { timeRange, limit? }): Promise<Array<{ tagName, usageCount, trend }>>
- getTagStats(ctx, args: { tagName }): Promise<{ totalUsage, entityCount, createdAt, recentTrend }>
- getTagsAcrossTables(ctx, args?: { limit? }): Promise<Array<{ tableName, tagName, entityCount }>>

Each method is implemented in a type-safe manner; consult the generated types under `src/_generated` in your project for full signatures.

## Schema

The component registers the following tables in your Convex schema:

- tags
  - name: string
  - createdAt: number
  - usageCount: number
  - indexed by: by_name

- entityTags
  - tagName: string
  - tableName: string
  - entityId: string
  - createdAt: number
  - indexes: by_tag, by_entity, by_tag_and_entity

- tagHierarchy
  - parentTag: string
  - childTag: string
  - createdAt: number
  - indexes: by_parent, by_child, by_parent_and_child

- tagAnalytics
  - tagName: string
  - usageDate: number
  - dailyCount: number

The full schema definition is in `src/component/schema.ts`.

## Examples

Basic tag management:

```ts
// Add a tag to an entity
await smartTags.addTag(ctx, {
  tagName: "important",
  tableName: "posts",
  entityId: "post123",
});

// Get tags for an entity
const tags = await smartTags.getTagsForEntity(ctx, {
  tableName: "posts",
  entityId: "post123",
});
```

Tag hierarchy:

```ts
// Create a parent-child relationship
await smartTags.createTagHierarchy(ctx, {
  parentTag: "technology",
  childTag: "ai",
});

// Get child tags
const children = await smartTags.getChildTags(ctx, { parentTag: "technology" });

// Get ancestor chain
const ancestors = await smartTags.getTagAncestors(ctx, { tagName: "ai" });
```

Analytics and trending:

```ts
// Get trending tags for the last 7 days
const sevenDays = 7 * 24 * 60 * 60 * 1000;
const trending = await smartTags.getTrendingTags(ctx, {
  timeRange: sevenDays,
  limit: 10,
});

// Get comprehensive statistics for a single tag
const stats = await smartTags.getTagStats(ctx, { tagName: "ai" });
```

Example Convex component registration (from `example/convex/convex.config.ts`):

```ts
import { defineApp } from "convex/server";
import smartTags from "convex-smart-tags/convex.config";

const app = defineApp();
app.use(smartTags);

export default app;
```

## Testing

The package includes test helper registration for the Convex test environment.

```ts
// src/test.ts — usage inside tests
import { convextTest } from "convex-test";
import smartTagsTest from "convex-smart-tags/src/test";

const t = convextTest();
smartTagsTest.register(t, "smartTags");
```

Run the project's test and typecheck commands as configured (see `vitest.config.js` and `package.json` scripts).

## Development

To develop locally:

1. Install dependencies
```bash
npm install
```

2. Build and run example
```bash
npm run build
cd example
npm install
npx convex dev
npm run dev
```

3. Typecheck and run tests
```bash
npm run typecheck
npm run test
```

## License

Apache-2.0 — see the `LICENSE` file for details.