@quicktalog/common 1.52.0 → 1.54.0

package/README.md

@@ -0,0 +1,113 @@
+# @quicktalog/common
+
+Shared TypeScript building blocks for the Quicktalog applications — published to npm and installed
+by every service that needs to agree on the same types, constants, helpers, and database schema.
+
+The goal is a single source of truth. When a catalogue gains a field or a pricing tier changes, it
+changes here once, gets published, and every consumer picks it up by bumping a version rather than
+re-declaring the shape locally and drifting out of sync.
+
+## Installation
+
+```bash
+npm install @quicktalog/common
+```
+
+```ts
+import { tiers, defaultCatalogueData, generateUniqueSlug, schema } from "@quicktalog/common";
+```
+
+Everything is re-exported from the package root, so there are no deep import paths to remember.
+
+## What's inside
+
+The package is ESM-only (`"type": "module"`) and ships compiled JavaScript plus `.d.ts`
+declarations from `dist/`. Source lives in `src/` and is organised into four groups:
+
+| Group | Path | Contents |
+| --- | --- | --- |
+| **Types** | `src/types/` | Domain models and unions — `Catalogue`, `ContentBlockType`, `Status`, `ThemeType`, `LimitType`, and friends |
+| **Constants** | `src/constants/` | Shared values — `themes`, `layouts`, `tiers`, `BUSINESS_TYPES`, `defaultCatalogueData` |
+| **Helpers** | `src/helpers/` | Small utilities such as `generateUniqueSlug` and `fetchImageFromUnsplash` |
+| **Drizzle** | `src/drizzle/` | The Postgres schema, exported as a `schema` namespace, plus generated relations |
+
+The Drizzle schema is **generated, not hand-written**. `src/drizzle/migrations/schema.ts` is
+produced by `drizzle-kit pull`, which introspects the live Postgres database described by
+`drizzle.config.ts`. Treat the database as authoritative and regenerate rather than editing those
+files directly.
+
+## Local development
+
+```bash
+npm install     # also installs the git hooks via the prepare script
+npm run build   # tsc -> dist/
+```
+
+### Git hooks
+
+A single Husky hook runs on commit:
+
+```
+.husky/pre-commit
+  ├── npx drizzle-kit pull   (only when a real DATABASE_URL is available)
+  └── npm run build
+```
+
+The drizzle step is guarded. It looks for `DATABASE_URL` in the environment, falls back to `.env`,
+and runs only if the value actually looks like a connection string. Without one it prints a skip
+notice and moves on, so fresh clones and CI can commit without a database. The build always runs,
+so a commit that does not typecheck cannot be created.
+
+There is deliberately **no pre-push hook**. Versioning is explicit — see below.
+
+> **Note:** when the drizzle step does run, it rewrites files under `src/drizzle/migrations/`
+> *after* staging has already happened. Those regenerated files land in your working tree unstaged;
+> review and commit them yourself.
+
+## Release workflow
+
+Publishing is driven entirely by the version in `package.json`. Pushing to `main` is what triggers
+CI, but only a **new** version actually publishes.
+
+```
+npm run release
+  ├── npm version minor         -> bumps package.json, commits it, tags it
+  │                                (the commit message is just the version, e.g. "1.53.0")
+  └── git push --follow-tags    -> pushes the commit and its tag
+```
+
+Use `npm run release:patch` or `npm run release:major` for the other bump types. `--follow-tags`
+matters: a plain `git push` leaves the tag stranded locally.
+
+Because the bump lives *inside* the commit being pushed, the version CI sees is always the version
+you intended to ship. The commit message being the bare version string is also why the GitHub
+Actions run shows up named after the release.
+
+### What CI does
+
+`.github/workflows/publish.yaml` runs on every push to `main`:
+
+1. Checkout, set up Node 22, upgrade npm for OIDC support
+2. `npm ci`
+3. `npm run build`
+4. **Check the registry** for the current `name@version`
+5. `npm publish --access public` — only if that version does not already exist
+
+Step 4 is what keeps ordinary commits green. A docs or config push builds and verifies as usual,
+then skips publishing instead of failing on a version that is already taken. The job summary states
+which path it took, so a green run never leaves you guessing whether it shipped.
+
+### Authentication
+
+There is no npm token. Publishing uses **OIDC trusted publishing** — GitHub Actions proves its
+identity to npm directly, and npm attaches a signed [provenance](https://docs.npmjs.com/generating-provenance-statements)
+statement to each release.
+
+This is why `package.json` must carry a `repository` field pointing at this repo: npm validates the
+provenance bundle against it and rejects the publish with `E422` if the two disagree.
+
+## Conventions
+
+- **Never edit `package.json` version by hand** — use the release scripts so the tag and commit stay consistent
+- **Never hand-edit the generated Drizzle schema** — change the database and re-pull
+- `dist/` is gitignored and built by CI; only `src/` is tracked

package/dist/constants/pricing.js

@@ -28,6 +28,7 @@ export const tiers = [
             apperance: {
                 standardThemes: true,
                 styles: false,
+                customThemes: false,
             },
         },
     },
@@ -60,6 +61,7 @@ export const tiers = [
             apperance: {
                 standardThemes: true,
                 styles: false,
+                customThemes: false,
             },
         },
     },
@@ -92,6 +94,7 @@ export const tiers = [
             apperance: {
                 standardThemes: true,
                 styles: true,
+                customThemes: true,
             },
         },
     },
@@ -124,6 +127,7 @@ export const tiers = [
             apperance: {
                 standardThemes: true,
                 styles: true,
+                customThemes: true,
             },
         },
     },
@@ -156,6 +160,7 @@ export const tiers = [
             apperance: {
                 standardThemes: true,
                 styles: true,
+                customThemes: true,
             },
         },
     },
@@ -188,6 +193,7 @@ export const tiers = [
             apperance: {
                 standardThemes: true,
                 styles: true,
+                customThemes: true,
             },
         },
     },

package/dist/drizzle/migrations/relations.d.ts

@@ -14,6 +14,7 @@ export declare const usersRelations: import("drizzle-orm/relations").Relations<"
     ocrs: import("drizzle-orm/relations").Many<"ocr">;
     analytics: import("drizzle-orm/relations").Many<"analytics">;
     catalogues: import("drizzle-orm/relations").Many<"catalogues">;
+    userThemes: import("drizzle-orm/relations").Many<"user_themes">;
 }>;
 export declare const newsletterRelations: import("drizzle-orm/relations").Relations<"newsletter", {
     user: import("drizzle-orm/relations").One<"users", true>;
@@ -28,3 +29,6 @@ export declare const analyticsRelations: import("drizzle-orm/relations").Relatio
 export declare const qrConfigsRelations: import("drizzle-orm/relations").Relations<"qr_configs", {
     catalogue: import("drizzle-orm/relations").One<"catalogues", true>;
 }>;
+export declare const userThemesRelations: import("drizzle-orm/relations").Relations<"user_themes", {
+    user: import("drizzle-orm/relations").One<"users", true>;
+}>;

package/dist/drizzle/migrations/relations.js

@@ -1,5 +1,5 @@
 import { relations } from "drizzle-orm/relations";
-import { catalogues, prompts, users, newsletter, ocr, analytics, qrConfigs } from "./schema";
+import { catalogues, prompts, users, newsletter, ocr, analytics, qrConfigs, userThemes } from "./schema";
 export const promptsRelations = relations(prompts, ({ one }) => ({
     catalogue: one(catalogues, {
         fields: [prompts.catalogue],
@@ -25,6 +25,7 @@ export const usersRelations = relations(users, ({ many }) => ({
     ocrs: many(ocr),
     analytics: many(analytics),
     catalogues: many(catalogues),
+    userThemes: many(userThemes),
 }));
 export const newsletterRelations = relations(newsletter, ({ one }) => ({
     user: one(users, {
@@ -54,3 +55,9 @@ export const qrConfigsRelations = relations(qrConfigs, ({ one }) => ({
         references: [catalogues.name]
     }),
 }));
+export const userThemesRelations = relations(userThemes, ({ one }) => ({
+    user: one(users, {
+        fields: [userThemes.userId],
+        references: [users.id]
+    }),
+}));

package/dist/drizzle/migrations/schema.d.ts

@@ -911,6 +911,115 @@ export declare const qrConfigs: import("drizzle-orm/pg-core").PgTableWithColumns
     };
     dialect: "pg";
 }>;
+export declare const userThemes: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "user_themes";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "user_themes";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "user_id";
+            tableName: "user_themes";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "user_themes";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        colors: import("drizzle-orm/pg-core").PgColumn<{
+            name: "colors";
+            tableName: "user_themes";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "user_themes";
+            dataType: "string";
+            columnType: "PgTimestampString";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "updated_at";
+            tableName: "user_themes";
+            dataType: "string";
+            columnType: "PgTimestampString";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 export declare const catalogues: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "catalogues";
     schema: undefined;

package/dist/drizzle/migrations/schema.js

@@ -112,6 +112,21 @@ export const qrConfigs = pgTable("qr_configs", {
     }).onUpdate("cascade").onDelete("cascade"),
     unique("qr_configs_catalogue_key").on(table.catalogue),
 ]);
+export const userThemes = pgTable("user_themes", {
+    id: uuid().defaultRandom().primaryKey().notNull(),
+    userId: text("user_id").notNull(),
+    name: text().notNull(),
+    colors: jsonb().default({}).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true, mode: 'string' }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true, mode: 'string' }).defaultNow().notNull(),
+}, (table) => [
+    foreignKey({
+        columns: [table.userId],
+        foreignColumns: [users.id],
+        name: "user_themes_user_id_fkey"
+    }).onUpdate("cascade").onDelete("cascade"),
+    unique("user_themes_user_id_name_key").on(table.userId, table.name),
+]);
 export const catalogues = pgTable("catalogues", {
     id: uuid().defaultRandom().primaryKey().notNull(),
     name: text().notNull(),

package/dist/types/catalogue.d.ts

@@ -15,6 +15,10 @@ export type Catalogue = Update<RawCatalogue, {
     partners: Partner[];
     metadata: Metadata;
 }>;
+type RawSavedTheme = InferSelectModel<typeof schema.userThemes>;
+export type SavedTheme = Update<RawSavedTheme, {
+    colors: CustomThemeColors;
+}>;
 export type Metadata = {
     title: string;
     description: string;
@@ -87,10 +91,12 @@ export type Legal = {
     privacyPolicy: string;
     address: string;
 };
+export type CustomThemeColors = Partial<Record<"background" | "heading" | "text" | "primary" | "secondary" | "cardBackground", string>>;
 export type Appearance = {
     theme: {
         type: ThemeType;
         name: string;
+        colors?: CustomThemeColors;
     };
     style: {
         contentFontSize: FontSize;

package/dist/types/general.d.ts

@@ -44,6 +44,7 @@ export type PricingPlan = {
         apperance: {
             standardThemes: boolean;
             styles: boolean;
+            customThemes: boolean;
         };
     };
     billing_period?: "month" | "year";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicktalog/common",
-  "version": "1.52.0",
+  "version": "1.54.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nikolamirilo/quicktalog-packages.git"
@@ -17,6 +17,9 @@
   ],
   "scripts": {
     "build": "tsc",
+    "release": "npm version minor && git push --follow-tags",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags",
     "prepare": "husky"
   },
   "devDependencies": {