vintasend-managed-templates 1.0.0-alpha2

package/dist/tags.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Turning free text into a tag slug, and keeping that slug unique.
+ *
+ * Tags are typed by humans ("Black Friday", "black friday ", "Black-Friday") and searched by
+ * machines, so every tag carries a normalized `slug` alongside the text it was written as. The
+ * slug is the identity: it is what a filter matches on, what a URL carries, and what a store
+ * enforces uniqueness over.
+ *
+ * Slugging lives here rather than in a backend so every implementation of the storage seam
+ * produces the same slug for the same text — and so the TypeScript and Python packages agree,
+ * which matters the moment two services read the same store.
+ *
+ * The rules, in order:
+ *
+ * 1. Unicode-normalize (NFKD) and drop everything outside ASCII, so `Promoção` and `Promocao`
+ *    are the same tag.
+ * 2. Lowercase, then replace every run of non-alphanumeric characters with a single `-`.
+ * 3. Trim leading and trailing `-`.
+ *
+ * Text that is entirely non-Latin (`日本語`) folds to nothing under step 1, so it falls back to a
+ * Unicode-preserving pass that keeps alphanumeric characters as they are. Losing a whole tag to
+ * transliteration would be worse than a slug that is not URL-clean.
+ */
+/**
+ * Longest slug this module will produce. Chosen to fit the 255-char columns backends use for
+ * it, leaving room for the `-2` / `-3` suffix uniqueness may need to append.
+ */
+export declare const MAX_SLUG_LENGTH = 240;
+/**
+ * Collapse a tag's whitespace and trim it, leaving the caller's casing intact.
+ *
+ * The text is what a UI displays, so this is deliberately gentle — it fixes the artifacts of
+ * typing (a trailing space, a double space) and nothing else. {@link slugifyTag} handles the rest.
+ */
+export declare function normalizeTagText(text: string): string;
+/**
+ * Normalize free text into a tag slug. Returns `''` for text with nothing sluggable.
+ *
+ * An empty result is returned rather than thrown on so callers can decide what it means: the
+ * service rejects it, while a filter treats it as a tag that matches nothing.
+ */
+export declare function slugifyTag(text: string): string;
+/**
+ * Return `slug`, or the first `slug-N` that `isTaken` says is free.
+ *
+ * Backends call this while holding whatever lock they use for tag writes: `isTaken` is a read,
+ * so two concurrent creates can both be told the same slug is free. The unique constraint on
+ * the store is what actually decides, and this only keeps the common case from hitting it.
+ *
+ * @param slug an already-slugified base.
+ * @param isTaken resolves to true when a tag with that slug already exists.
+ */
+export declare function nextAvailableSlug(slug: string, isTaken: (candidate: string) => boolean | Promise<boolean>): Promise<string>;
+//# sourceMappingURL=tags.d.ts.map

package/dist/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AA4BnC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS/C;AAeD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACzD,OAAO,CAAC,MAAM,CAAC,CAcjB"}

package/dist/tags.js

@@ -0,0 +1,108 @@
+/**
+ * Turning free text into a tag slug, and keeping that slug unique.
+ *
+ * Tags are typed by humans ("Black Friday", "black friday ", "Black-Friday") and searched by
+ * machines, so every tag carries a normalized `slug` alongside the text it was written as. The
+ * slug is the identity: it is what a filter matches on, what a URL carries, and what a store
+ * enforces uniqueness over.
+ *
+ * Slugging lives here rather than in a backend so every implementation of the storage seam
+ * produces the same slug for the same text — and so the TypeScript and Python packages agree,
+ * which matters the moment two services read the same store.
+ *
+ * The rules, in order:
+ *
+ * 1. Unicode-normalize (NFKD) and drop everything outside ASCII, so `Promoção` and `Promocao`
+ *    are the same tag.
+ * 2. Lowercase, then replace every run of non-alphanumeric characters with a single `-`.
+ * 3. Trim leading and trailing `-`.
+ *
+ * Text that is entirely non-Latin (`日本語`) folds to nothing under step 1, so it falls back to a
+ * Unicode-preserving pass that keeps alphanumeric characters as they are. Losing a whole tag to
+ * transliteration would be worse than a slug that is not URL-clean.
+ */
+/**
+ * Longest slug this module will produce. Chosen to fit the 255-char columns backends use for
+ * it, leaving room for the `-2` / `-3` suffix uniqueness may need to append.
+ */
+export const MAX_SLUG_LENGTH = 240;
+const NON_ALPHANUMERIC = /[^a-z0-9]+/g;
+const ALPHANUMERIC = /[\p{L}\p{N}]/u;
+const DASH_RUN = /-+/g;
+const ASCII_CEILING = 0x80;
+function trimDashes(value) {
+    return value.replace(/^-+/, '').replace(/-+$/, '');
+}
+/**
+ * Drop everything outside ASCII, the way Python's `str.encode('ascii', 'ignore')` does.
+ *
+ * Dropping rather than substituting is what makes step 1 work: after NFKD, `ç` is `c` plus a
+ * combining cedilla, and the cedilla has to *vanish* for `Promoção` to slug as `promocao`.
+ * Turning it into a separator instead would give `promoc-ao`, a different tag.
+ */
+function asciiOnly(value) {
+    let result = '';
+    for (const character of value) {
+        if ((character.codePointAt(0) ?? 0) < ASCII_CEILING) {
+            result += character;
+        }
+    }
+    return result;
+}
+/**
+ * Collapse a tag's whitespace and trim it, leaving the caller's casing intact.
+ *
+ * The text is what a UI displays, so this is deliberately gentle — it fixes the artifacts of
+ * typing (a trailing space, a double space) and nothing else. {@link slugifyTag} handles the rest.
+ */
+export function normalizeTagText(text) {
+    return text.split(/\s+/).filter(Boolean).join(' ');
+}
+/**
+ * Normalize free text into a tag slug. Returns `''` for text with nothing sluggable.
+ *
+ * An empty result is returned rather than thrown on so callers can decide what it means: the
+ * service rejects it, while a filter treats it as a tag that matches nothing.
+ */
+export function slugifyTag(text) {
+    const folded = asciiOnly(text.normalize('NFKD'));
+    let slug = trimDashes(folded.toLowerCase().replace(NON_ALPHANUMERIC, '-'));
+    if (!slug) {
+        slug = slugifyUnicode(text);
+    }
+    return trimDashes(slug.slice(0, MAX_SLUG_LENGTH));
+}
+/**
+ * Slug for text ASCII folding empties out — `日本語`, `Привет` and the like.
+ *
+ * Alphanumeric characters survive as they are; everything else becomes a separator. Not
+ * URL-clean without percent-encoding, but a tag that exists beats a tag that vanished.
+ */
+function slugifyUnicode(text) {
+    const characters = Array.from(text.toLowerCase(), (character) => ALPHANUMERIC.test(character) ? character : '-');
+    return trimDashes(characters.join('').replace(DASH_RUN, '-'));
+}
+/**
+ * Return `slug`, or the first `slug-N` that `isTaken` says is free.
+ *
+ * Backends call this while holding whatever lock they use for tag writes: `isTaken` is a read,
+ * so two concurrent creates can both be told the same slug is free. The unique constraint on
+ * the store is what actually decides, and this only keeps the common case from hitting it.
+ *
+ * @param slug an already-slugified base.
+ * @param isTaken resolves to true when a tag with that slug already exists.
+ */
+export async function nextAvailableSlug(slug, isTaken) {
+    if (!(await isTaken(slug))) {
+        return slug;
+    }
+    // Truncate the base first so appending the suffix cannot push the result over the limit.
+    for (let suffixIndex = 2;; suffixIndex += 1) {
+        const suffix = `-${suffixIndex}`;
+        const base = trimDashes(slug.slice(0, MAX_SLUG_LENGTH - suffix.length));
+        const candidate = `${base}${suffix}`;
+        if (!(await isTaken(candidate))) {
+            return candidate;
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+import type { ManagedTemplateStatus, ManagedTemplateTagStatus } from './constants.js';
+/**
+ * Whatever a store uses to key a row. Mirrors `vintasend`'s own `Identifier`: a backend on
+ * Postgres hands back a number, one on FHIR a string, and neither is this package's business.
+ */
+export type ManagedTemplateId = string | number;
+/**
+ * A label attached to any number of template versions, and versions carry any number of them.
+ *
+ * `slug` is the identity: it is normalized from `text` by {@link slugifyTag}, unique across the
+ * store, and what the tag filters match on. Editing `text` regenerates it.
+ */
+export type ManagedTemplateTag = {
+    id: ManagedTemplateId;
+    text: string;
+    slug: string;
+    status: ManagedTemplateTagStatus;
+    createdAt: Date;
+    updatedAt: Date;
+    tenant: string | null;
+};
+/**
+ * One version of a managed template.
+ *
+ * Templates are versioned rather than edited in place, so a `ManagedTemplate` is always a
+ * specific version of `key` — never "the template" in the abstract.
+ */
+export type ManagedTemplate = {
+    id: ManagedTemplateId;
+    key: string;
+    version: number;
+    name: string;
+    description: string;
+    templateManagedBackend: string;
+    bodyTemplate: string;
+    subjectTemplate: string | null;
+    preheaderTemplate: string | null;
+    status: ManagedTemplateStatus;
+    tenant: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    /** Every tag on this version, in the order the backend returns them. */
+    tags: ManagedTemplateTag[];
+    /**
+     * Whether this is a base to build on rather than a template to send: it declares a
+     * `{% managed_children %}` hole, or declares blocks without extending anything.
+     *
+     * Denormalized, not authored. Nobody sets it on a write — there is no field for it on either
+     * write input — because it is a fact about the source, and a stored copy that disagreed with
+     * the source would be a lie a filter repeats. A backend derives it on every write with
+     * {@link isAbstract} and stores the answer so a query can use it; `isAbstract` recomputed is
+     * always the authority.
+     */
+    isAbstract: boolean;
+};
+/** One entry in a template version's status audit trail. */
+export type ManagedTemplateStatusHistory = {
+    templateKey: string;
+    version: number;
+    status: ManagedTemplateStatus;
+    createdAt: Date;
+    changedBy: string | null;
+    tenant: string | null;
+};
+/** What creating a template's first version needs. */
+export type ManagedTemplateCreateInput = {
+    key: string;
+    name: string;
+    description: string;
+    templateManagedBackend: string;
+    bodyTemplate: string;
+    subjectTemplate: string | null;
+    preheaderTemplate: string | null;
+    tenant: string | null;
+    /**
+     * Tag *texts*, not slugs: a caller tags a template with what a person typed, and any text
+     * with no tag behind it yet becomes one. `null`, `undefined` and `[]` all mean "no tags".
+     */
+    tags?: string[] | null;
+};
+/**
+ * What creating the *next* version of an existing key needs.
+ *
+ * Every field is optional and an absent one means "carry this one forward": the backend copies
+ * the latest version and applies only the fields that are set. There is deliberately no
+ * `templateManagedBackend` or `tenant` here — neither can change across versions of one key.
+ */
+export type ManagedTemplateUpdateInput = {
+    name?: string | null;
+    description?: string | null;
+    bodyTemplate?: string | null;
+    subjectTemplate?: string | null;
+    preheaderTemplate?: string | null;
+    /**
+     * Unlike the other fields, tags distinguish absent from empty: absent carries the previous
+     * version's tags forward, `[]` creates the version with none.
+     */
+    tags?: string[] | null;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAEtF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,iBAAiB,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,wBAAwB,CAAC;IACjC,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,iBAAiB,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,wEAAwE;IACxE,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC3B;;;;;;;;;OASG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,4BAA4B,GAAG;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACxB,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "vintasend-managed-templates",
+  "version": "1.0.0-alpha2",
+  "description": "Database-backed notification templates for VintaSend: versioning, a draft/active/inactive/archived lifecycle with an audit trail, tags, composition and filtering — on top of a storage seam you implement.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "Vinta Software",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vintasoftware/vintasend-ts-managed-templates.git"
+  },
+  "dependencies": {
+    "vintasend": "^1.0.0-alpha2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.10",
+    "@types/node": "^25.0.8",
+    "@vitest/coverage-v8": "4.0.18",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}