@tstdl/base 0.93.139 → 0.93.140

package/orm/README.md

@@ -0,0 +1,423 @@
+# ORM Module
+
+A robust, code-first Object-Relational Mapping (ORM) library for PostgreSQL, built on top of [Drizzle ORM](https://orm.drizzle.team/). It simplifies data access through a repository pattern, provides advanced type-safe querying (including full-text search and ParadeDB integration), and integrates seamlessly with the dependency injection system.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Entities](#entities)
+  - [Repositories](#repositories)
+  - [Decorators](#decorators)
+  - [Querying](#querying)
+  - [Transactions](#transactions)
+- [🚀 Basic Usage](#-basic-usage)
+  - [1. Configuration](#1-configuration)
+  - [2. Defining Entities](#2-defining-entities)
+  - [3. Using Repositories](#3-using-repositories)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Full-Text Search](#full-text-search)
+  - [ParadeDB Integration](#paradedb-integration)
+  - [Transparent Encryption](#transparent-encryption)
+  - [Automatic Expiration (TTL)](#automatic-expiration-ttl)
+  - [Embedded Properties](#embedded-properties)
+  - [Transactions](#transaction-management)
+  - [Soft Deletes](#soft-deletes)
+  - [SQL Helper Functions](#sql-helper-functions)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Code-First Schema**: Define database tables, columns, and relationships using TypeScript classes and decorators.
+- **Repository Pattern**: Standardized API for CRUD operations, bulk actions, and complex querying.
+- **Type-Safe Querying**: MongoDB-like query syntax (`$eq`, `$gt`, `$in`, `$or`) fully typed to your entities.
+- **Advanced Search**: Built-in support for PostgreSQL `tsvector`, `pg_trgm`, and ParadeDB (`bm25`) full-text search.
+- **Transparent Encryption**: Encrypt sensitive columns automatically at the application level using AES-GCM.
+- **Automatic Expiration**: Built-in Time-To-Live (TTL) support for auto-deleting old records.
+- **Transaction Management**: Robust transaction handling with automatic commit/rollback and context propagation.
+- **Soft Deletes**: Built-in support for soft deletion when using the standard `Entity` base class.
+- **Dependency Injection**: Seamless integration with `@tstdl/base/injector`.
+
+## Core Concepts
+
+### Entities
+
+Entities are classes that map directly to database tables. The module provides base classes to standardize common fields:
+
+- **`Entity`**: The standard base class. Includes an `id` (UUIDv7 primary key) and metadata fields: `revision`, `createTimestamp`, `deleteTimestamp` (for soft deletes), and `attributes` (JSONB).
+- **`BaseEntity`**: A minimal base class providing only the `id` primary key. Useful for join tables or simple configuration data.
+- **`TenantEntity`**: Extends `Entity` with a `tenantId` column for multi-tenant applications.
+
+### Repositories
+
+Repositories provide the interface to the database.
+
+- **`EntityRepository<T>`**: The generic class providing methods like `load`, `insert`, `update`, `search`, etc.
+- **`injectRepository(Entity)`**: Helper to inject the default repository for an entity.
+- **`getRepository(Entity)`**: Helper to create a custom repository class extending the base functionality.
+
+### Decorators
+
+Decorators configure the mapping between TypeScript properties and database columns/constraints.
+
+- **Class**: `@Table`, `@Index`, `@Unique`, `@Check`, `@ParadeIndex`, `@TimeToLive`.
+- **Property**: `@StringProperty`, `@Integer`, `@UuidProperty`, `@TimestampProperty`, `@EncryptedProperty`, `@References`, `@EmbeddedProperty`, `@GeneratedTsVector`, `@TrigramIndex`.
+
+### Querying
+
+The ORM uses a structured query object syntax instead of raw SQL builders for most operations.
+
+- **Comparison**: `$eq`, `$neq`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$regex`.
+- **Logical**: `$and`, `$or`, `$nor`, `$not`.
+- **Search**: `$tsvector`, `$trigram`, `$parade`.
+
+### Transactions
+
+The `Transactional` base class allows services to manage transactions easily.
+
+- **`this.transaction(async (tx) => { ... })`**: Starts a transaction scope.
+- **`repository.withTransaction(tx)`**: Binds a repository to an active transaction.
+
+## 🚀 Basic Usage
+
+### 1. Configuration
+
+Configure the ORM in your application bootstrap.
+
+```typescript
+import { configureOrm } from '@tstdl/base/orm/server';
+
+configureOrm({
+  connection: {
+    host: 'localhost',
+    port: 5432,
+    user: 'postgres',
+    password: 'password',
+    database: 'my_app',
+  },
+  // Optional: Secret for column encryption (32 bytes)
+  encryptionSecret: new Uint8Array([
+    /* ... 32 bytes ... */
+  ]),
+});
+```
+
+### 2. Defining Entities
+
+Define your data model using classes and decorators. Note that standard schema decorators (like `@StringProperty`) are combined with ORM-specific decorators.
+
+```typescript
+import { Entity, Table, Unique, References } from '@tstdl/base/orm';
+import { UuidProperty } from '@tstdl/base/orm/schemas';
+import { StringProperty } from '@tstdl/base/schema';
+
+@Table({ name: 'users' })
+export class User extends Entity {
+  @StringProperty()
+  name: string;
+
+  @StringProperty()
+  @Unique()
+  email: string;
+}
+
+@Table({ name: 'posts' })
+export class Post extends Entity {
+  @StringProperty()
+  title: string;
+
+  @UuidProperty()
+  @References(() => User)
+  authorId: string;
+}
+```
+
+### 3. Using Repositories
+
+Inject repositories into your services to interact with the database.
+
+```typescript
+import { Singleton } from '@tstdl/base/injector';
+import { injectRepository, Transactional } from '@tstdl/base/orm/server';
+import { User } from './user.model.js';
+
+@Singleton()
+export class UserService extends Transactional {
+  // Inject the default repository for User
+  readonly #userRepository = injectRepository(User);
+
+  async createUser(name: string, email: string): Promise<User> {
+    // Insert a new entity
+    return await this.#userRepository.insert({
+      name,
+      email,
+    });
+  }
+
+  async findByEmail(email: string): Promise<User | undefined> {
+    // Query using the object syntax
+    return await this.#userRepository.tryLoadByQuery({
+      email: { $eq: email },
+    });
+  }
+
+  async updateName(id: string, newName: string): Promise<void> {
+    // Update specific fields
+    await this.#userRepository.update(id, {
+      name: newName,
+    });
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Full-Text Search
+
+The ORM supports PostgreSQL's native full-text search (`tsvector`) and trigram similarity (`pg_trgm`).
+
+```typescript
+import { Entity, Table, GeneratedTsVector } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+@Table({ name: 'articles' })
+export class Article extends Entity {
+  @StringProperty()
+  title: string;
+
+  @StringProperty()
+  content: string;
+
+  // Automatically generated tsvector column combining title (weight A) and content (weight B)
+  @GeneratedTsVector({
+    sources: ['title', 'content'],
+    weights: { title: 'A', content: 'B' },
+    language: 'english',
+  })
+  searchVector: string;
+}
+
+// In your service:
+const results = await articleRepository.search({
+  query: {
+    $tsvector: {
+      fields: ['searchVector'],
+      query: 'typescript & orm',
+      language: 'english',
+    },
+  },
+  highlight: 'content', // Optional: highlight matches in content
+});
+```
+
+### ParadeDB Integration
+
+If you are using [ParadeDB](https://www.paradedb.com/), you can use the `@ParadeIndex` decorator for BM25 relevance scoring and advanced search capabilities.
+
+```typescript
+import { Entity, Table, ParadeIndex } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+@Table({ name: 'products' })
+@ParadeIndex({
+  // Define a BM25 index on these columns
+  columns: ['name', 'description'],
+})
+export class Product extends Entity {
+  @StringProperty()
+  name: string;
+
+  @StringProperty()
+  description: string;
+}
+
+// Searching with ParadeDB
+const results = await productRepository.search({
+  query: {
+    $parade: {
+      fields: ['name', 'description'],
+      query: 'shoes OR boots',
+      distance: 1, // Fuzzy matching
+    },
+  },
+});
+```
+
+### Transparent Encryption
+
+Encrypt sensitive data at rest using the `@EncryptedProperty` decorator. The data is automatically encrypted on insert/update and decrypted on load. The underlying database column type will be `bytea`.
+
+```typescript
+import { Entity, EncryptedProperty } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+export class UserSecret extends Entity {
+  @StringProperty()
+  @EncryptedProperty()
+  apiKey: string;
+}
+```
+
+### Automatic Expiration (TTL)
+
+Automatically delete records after a specified duration. This relies on the `createTimestamp` field of `Entity` or a specific property marked with `@Expires`.
+
+```typescript
+import { Entity, TimeToLive, Expires } from '@tstdl/base/orm';
+import { TimestampProperty } from '@tstdl/base/orm/schemas';
+
+// Soft delete records 24 hours after creation
+@TimeToLive(24 * 60 * 60 * 1000, 'soft')
+export class Session extends Entity {
+  // ...
+}
+
+// Or expire based on a specific column
+export class ApiKey extends Entity {
+  @TimestampProperty()
+  @Expires({ after: 0, mode: 'hard' }) // Hard delete immediately when validUntil is reached
+  validUntil: number;
+}
+```
+
+### Embedded Properties
+
+Group related columns into a reusable class and embed them into entities. This flattens the structure in the database table but keeps it structured in your code.
+
+```typescript
+import { Entity, EmbeddedProperty } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+class Address {
+  @StringProperty()
+  street: string;
+
+  @StringProperty()
+  city: string;
+}
+
+export class User extends Entity {
+  @EmbeddedProperty(Address, { prefix: 'billing_' })
+  billingAddress: Address; // DB Columns: billing_street, billing_city
+
+  @EmbeddedProperty(Address, { prefix: 'shipping_' })
+  shippingAddress: Address; // DB Columns: shipping_street, shipping_city
+}
+```
+
+### Transaction Management
+
+Services extending `Transactional` can manage transactions. The repository automatically participates in the active transaction context.
+
+```typescript
+@Singleton()
+export class OrderService extends Transactional {
+  readonly #orderRepository = injectRepository(Order);
+  readonly #itemRepository = injectRepository(OrderItem);
+
+  async createOrder(data: OrderData): Promise<void> {
+    // Start a transaction scope
+    await this.transaction(async (tx) => {
+      // Repositories automatically use the transaction 'tx'
+      // because they are accessed within the scope of 'this.transaction'
+      // and injected via injectRepository which handles context propagation.
+
+      // Alternatively, explicitly bind:
+      // const txRepo = this.#orderRepository.withTransaction(tx);
+
+      const order = await this.#orderRepository.insert({ ... });
+      await this.#itemRepository.insertMany(data.items.map(i => ({ ...i, orderId: order.id })));
+
+      // If an error is thrown here, everything is rolled back.
+    });
+  }
+}
+```
+
+### Soft Deletes
+
+When using the `Entity` base class, the `delete` and `deleteByQuery` methods perform a soft delete by setting the `deleteTimestamp`. The `load` and `loadByQuery` methods automatically filter out soft-deleted records.
+
+To permanently remove records, use `hardDelete` or `hardDeleteByQuery`.
+
+### SQL Helper Functions
+
+The module exports SQL helpers in `@tstdl/base/orm/sqls` for complex queries.
+
+```typescript
+import { sql } from 'drizzle-orm';
+import { interval, TRANSACTION_TIMESTAMP } from '@tstdl/base/orm/sqls';
+
+// Find records created in the last 7 days
+const recent = await repository.loadManyByQuery({
+  createTimestamp: { $gt: sql`${TRANSACTION_TIMESTAMP} - ${interval(7, 'days')}` },
+});
+```
+
+## 📚 API
+
+### Decorators
+
+| Decorator                            | Target     | Description                                             |
+| :----------------------------------- | :--------- | :------------------------------------------------------ |
+| `@Table({ name?, schema? })`         | Class      | Configures table name and schema.                       |
+| `@Unique(columns?, options?)`        | Class/Prop | Defines unique constraints.                             |
+| `@Index(columns?, options?)`         | Class/Prop | Defines database indexes.                               |
+| `@Check(name, builder)`              | Class      | Defines a SQL CHECK constraint.                         |
+| `@ForeignKey(...)`                   | Class      | Defines a foreign key constraint.                       |
+| `@ParadeIndex(options)`              | Class/Prop | Configures a ParadeDB BM25 index.                       |
+| `@TimeToLive(ttl, mode)`             | Class      | Sets TTL for automatic deletion based on creation time. |
+| `@PrimaryKeyProperty()`              | Prop       | Marks the primary key column.                           |
+| `@References(target)`                | Prop       | Defines a foreign key relationship.                     |
+| `@EncryptedProperty()`               | Prop       | Marks column for encryption (`bytea`).                  |
+| `@EmbeddedProperty(type)`            | Prop       | Embeds another class's properties.                      |
+| `@GeneratedTsVector(opts)`           | Prop       | Creates a generated `tsvector` column.                  |
+| `@TrigramIndex(opts)`                | Prop       | Creates a GIN/GIST trigram index.                       |
+| `@Expires(opts)`                     | Prop       | Sets expiration based on the property value.            |
+| `@UuidProperty()`                    | Prop       | Maps to `uuid` column.                                  |
+| `@TimestampProperty()`               | Prop       | Maps to `timestamp with time zone` (number).            |
+| `@NumericDateProperty()`             | Prop       | Maps to `date` (number YYYYMMDD).                       |
+| `@JsonProperty()`                    | Prop       | Maps to `jsonb` column.                                 |
+| `@NumericProperty(precision, scale)` | Prop       | Maps to `numeric` column.                               |
+| `@TsVectorProperty()`                | Prop       | Maps to `tsvector` column.                              |
+
+### Repository Methods
+
+| Method                              | Description                                              |
+| :---------------------------------- | :------------------------------------------------------- |
+| `load(id)`                          | Loads an entity by ID. Throws if not found.              |
+| `tryLoad(id)`                       | Loads an entity by ID. Returns `undefined` if not found. |
+| `loadByQuery(query)`                | Loads first match. Throws if not found.                  |
+| `tryLoadByQuery(query)`             | Loads first match. Returns `undefined` if not found.     |
+| `loadMany(ids)`                     | Loads multiple entities by ID.                           |
+| `loadManyByQuery(query)`            | Loads all matches.                                       |
+| `loadAll()`                         | Loads all entities in the table.                         |
+| `insert(entity)`                    | Inserts a new entity.                                    |
+| `insertMany(entities)`              | Inserts multiple entities.                               |
+| `insertIfNotExists(target, entity)` | Inserts if no conflict on target columns.                |
+| `update(id, update)`                | Updates an entity by ID.                                 |
+| `updateByQuery(query, update)`      | Updates entities matching query.                         |
+| `upsert(target, entity)`            | Inserts or updates on conflict.                          |
+| `delete(id)`                        | Soft deletes (if supported) or hard deletes by ID.       |
+| `deleteByQuery(query)`              | Soft deletes matching entity.                            |
+| `hardDelete(id)`                    | Permanently removes the record.                          |
+| `search(options)`                   | Performs full-text search (TsVector, Trigram, Parade).   |
+| `count()`                           | Returns total count of entities.                         |
+| `countByQuery(query)`               | Returns the count of matching records.                   |
+| `has(id)`                           | Checks if an ID exists.                                  |
+| `transaction(handler)`              | Executes handler in a transaction.                       |
+
+### Query Operators
+
+| Operator                | Description                          |
+| :---------------------- | :----------------------------------- |
+| `$eq` / `$neq`          | Equal / Not Equal                    |
+| `$gt` / `$gte`          | Greater Than / Greater Than or Equal |
+| `$lt` / `$lte`          | Less Than / Less Than or Equal       |
+| `$in` / `$nin`          | In Array / Not In Array              |
+| `$regex`                | Regular Expression match             |
+| `$and` / `$or` / `$nor` | Logical operators                    |
+| `$not`                  | Negation                             |
+| `$tsvector`             | PostgreSQL Text Search               |
+| `$trigram`              | Trigram Similarity Search            |
+| `$parade`               | ParadeDB Search                      |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.139",
+  "version": "0.93.140",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -10,7 +10,7 @@
     "build": "tsc && tsc-alias && npm run copy:orm",
     "build:watch": "concurrently --raw --kill-others npm:tsc:watch npm:tsc-alias:watch",
     "build:production": "rm -rf dist && npm run build && npm run build:production:copy-files",
-    "build:production:copy-files": "cp package.json eslint.config.js tsconfig.server.json dist/ && cp tsconfig.base.json dist/tsconfig.json && npm run copy:orm",
+    "build:production:copy-files": "cp package.json eslint.config.js tsconfig.server.json dist/ && cp tsconfig.base.json dist/tsconfig.json && npm run copy:orm && npm run copy:readmes",
     "build:dts": "rm -rf dist && tsc -p tsconfig.dts.json && tsc-alias",
     "build:docs": "typedoc",
     "build:docs:watch": "typedoc --watch",
@@ -20,6 +20,7 @@
     "tsc:watch": "tsc --watch",
     "tsc-alias:watch": "tsc-alias --watch",
     "cleanup:dist": "rm -vrf dist/tools/",
+    "copy:readmes": "cp README.md dist/ && cd source && find . -name \"README.md\" -exec cp --parents {} ../dist/ \\;",
     "generate:migration": "./scripts/manage-orm.sh generate && npm run copy:orm",
     "generate:readmes": "deno run --allow-run=code2prompt --allow-read --allow-write=source --allow-net=generativelanguage.googleapis.com --allow-env=GEMINI_API_KEY generate-readmes.ts",
     "generate:readmes:new-only": "npm run generate:readmes -- --skip-existing",
@@ -150,7 +151,9 @@
     "type-fest": "^5.4"
   },
   "peerDependencies": {
-    "@genkit-ai/google-genai": "^1.28",
+    "@aws-sdk/client-s3": "^3.994",
+    "@aws-sdk/s3-request-presigner": "^3.994",
+    "@genkit-ai/google-genai": "^1.29",
     "@google-cloud/storage": "^7.19",
     "@toon-format/toon": "^2.1.0",
     "@tstdl/angular": "^0.93",
@@ -160,10 +163,8 @@
     "@zxcvbn-ts/language-en": "^3.0",
     "drizzle-orm": "^0.45",
     "file-type": "^21.3",
-    "genkit": "^1.28",
+    "genkit": "^1.29",
     "handlebars": "^4.7",
-    "@aws-sdk/client-s3": "^3.993",
-    "@aws-sdk/s3-request-presigner": "^3.993",
     "mjml": "^4.18",
     "nodemailer": "^8.0",
     "pg": "^8.18",
@@ -181,6 +182,7 @@
     }
   },
   "devDependencies": {
+    "@biomejs/biome": "2.4",
     "@stylistic/eslint-plugin": "5.9",
     "@types/koa__router": "12.0",
     "@types/luxon": "3.7",

package/password/README.md

@@ -0,0 +1,164 @@
+# @tstdl/base/password
+
+A robust password strength estimation module that combines the advanced heuristic analysis of `zxcvbn-ts` with secure checks against the "Have I Been Pwned" breach database.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Strength Analysis](#strength-analysis-zxcvbn)
+  - [Breach Check](#breach-check-hibp)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Localization](#localization)
+  - [Offline Checks](#offline-checks)
+  - [Schema Integration](#schema-integration)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Advanced Heuristics:** Utilizes `zxcvbn-ts` to detect common patterns, dictionary words, names, keyboard sequences, and dates.
+- **Breach Detection:** Securely checks if a password has appeared in known data breaches via the "Have I Been Pwned" (HIBP) API.
+- **Secure by Design:** Uses k-Anonymity for HIBP checks; the full password hash is never sent over the network.
+- **Unified Scoring:** Provides a consolidated strength score from 0 (Very Weak) to 4 (Very Strong).
+- **Localized Feedback:** Returns localization keys for warnings and suggestions, supporting English and German out of the box.
+- **Schema & Validation Ready:** `PasswordCheckResult` is fully decorated with `@tstdl/base/schema`, making it ready for API contracts and data models.
+- **Performance Optimized:** Dynamically imports heavy analysis libraries only when needed to keep initial bundle sizes low.
+
+## Core Concepts
+
+### Strength Analysis (zxcvbn)
+
+The module uses `zxcvbn-ts` to calculate entropy and estimate crack time. It looks for:
+
+- **Dictionaries:** Common passwords, names, and words in multiple languages.
+- **Patterns:** L33t speak, keyboard walks (e.g., "qwerty"), and repetitions.
+- **Personal Info:** Dates and years.
+
+### Breach Check (HIBP)
+
+To protect against credential stuffing, the module checks the "Have I Been Pwned" database.
+
+1.  The password is hashed using SHA-1.
+2.  Only the first 5 characters of the hash are sent to the API (k-Anonymity).
+3.  The API returns all suffixes matching that prefix.
+4.  The module checks locally if the full hash exists in the response.
+
+If a password is found in the breach database, its strength score is automatically downgraded to **0 (Very Weak)**, regardless of its complexity.
+
+## 🚀 Basic Usage
+
+The primary entry point is the `checkPassword` function. It returns a `PasswordCheckResult` containing the score, breach count, and feedback keys.
+
+```typescript
+import { checkPassword, PasswordStrength } from '@tstdl/base/password';
+
+async function validateUserPassword(password: string) {
+  const result = await checkPassword(password);
+
+  console.log(`Score: ${result.strength} (${PasswordStrength[result.strength]})`);
+
+  if (result.pwned && result.pwned > 0) {
+    console.warn(`⚠️ This password has appeared in ${result.pwned} data breaches!`);
+  }
+
+  if (result.strength < PasswordStrength.Strong) {
+    console.log('Password is too weak.');
+  }
+}
+
+validateUserPassword('correct-horse-battery-staple');
+```
+
+## 🔧 Advanced Topics
+
+### Localization
+
+The `warnings` and `suggestions` arrays in the result contain **localization keys** (e.g., `tstdl.passwordCheck.warnings.simpleRepeat`) rather than raw text. This allows you to easily translate feedback using the `@tstdl/base/text` module.
+
+The module exports `englishPasswordCheckLocalization` and `germanPasswordCheckLocalization`.
+
+```typescript
+import { checkPassword, englishPasswordCheckLocalization } from '@tstdl/base/password';
+import { LocalizationService } from '@tstdl/base/text';
+
+// 1. Setup the localization service with the provided language pack
+const localization = new LocalizationService([englishPasswordCheckLocalization]);
+localization.setLanguage('en');
+
+async function showFeedback(password: string) {
+  const result = await checkPassword(password);
+
+  // 2. Translate the keys to human-readable text
+  const warnings = result.warnings.map((key) => localization.localize(key));
+  const suggestions = result.suggestions.map((key) => localization.localize(key));
+
+  console.log('Warnings:', warnings);
+  console.log('Suggestions:', suggestions);
+}
+```
+
+### Offline Checks
+
+If you are in an environment without internet access, or if you want to skip the HTTP request to "Have I Been Pwned" for performance reasons, you can disable it via options.
+
+```typescript
+import { checkPassword } from '@tstdl/base/password';
+
+async function checkOffline(password: string) {
+  // Disables the HIBP API call
+  const result = await checkPassword(password, { checkForPwned: false });
+
+  // result.pwned will be undefined
+  console.log(`Local Strength Score: ${result.strength}`);
+}
+```
+
+### Schema Integration
+
+The `PasswordCheckResult` is a class decorated with `@tstdl/base/schema`. This makes it easy to use as a return type in your API definitions or as a nested property in other models.
+
+```typescript
+import { PasswordCheckResult } from '@tstdl/base/password';
+import { defineApi } from '@tstdl/base/api';
+
+export const myApiDefinition = defineApi({
+  endpoints: {
+    checkStrength: {
+      method: 'GET',
+      parameters: { password: String },
+      result: PasswordCheckResult,
+    },
+  },
+});
+```
+
+### Authentication Integration
+
+This module is used by the `@tstdl/base/authentication` framework to enforce password requirements during registration or password changes. See `AuthenticationSecretRequirementsValidator` for more details on how to customize these checks in your application.
+
+## 📚 API
+
+### Functions
+
+| Function         | Signature                                                                            | Description                                                                     |
+| :--------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
+| `checkPassword`  | `(password: string, options?: CheckPasswordOptions) => Promise<PasswordCheckResult>` | Analyzes password strength and checks for breaches.                             |
+| `haveIBeenPwned` | `(password: string) => Promise<number>`                                              | Checks the password against the HIBP database and returns the occurrence count. |
+
+### Classes & Interfaces
+
+| Name                        | Type    | Description                                                                                |
+| :-------------------------- | :------ | :----------------------------------------------------------------------------------------- |
+| `PasswordCheckResult`       | `class` | The result object containing `strength`, `pwned` count, `warnings`, and `suggestions`.     |
+| `CheckPasswordOptions`      | `type`  | Options object. Property `checkForPwned` (boolean, default `true`) controls the API check. |
+| `PasswordCheckLocalization` | `type`  | Type definition for the localization structure used by this module.                        |
+
+### Enums & Constants
+
+| Name                               | Type    | Description                                                               |
+| :--------------------------------- | :------ | :------------------------------------------------------------------------ |
+| `PasswordStrength`                 | `enum`  | `VeryWeak` (0), `Weak` (1), `Medium` (2), `Strong` (3), `VeryStrong` (4). |
+| `englishPasswordCheckLocalization` | `const` | English localization definitions for warnings and suggestions.            |
+| `germanPasswordCheckLocalization`  | `const` | German localization definitions for warnings and suggestions.             |
+| `passwordCheckLocalizationKeys`    | `const` | Helper object containing the localization key paths.                      |