@warlock.js/notifications 5.27.0 → 5.29.0

package/esm/seal/src/validators/object-validator.mjs

@@ -300,7 +300,8 @@ var ObjectValidator = class ObjectValidator extends BaseValidator {
 		if (mutatedData === void 0 || mutatedData === null) return result;
 		const errors = [];
 		const validatedData = {};
-		const validationPromises = Object.entries(this.schema).filter(([, validator]) => !this.isComputedValidator(validator)).map(async ([key, validator]) => {
+		const fieldErrors = [];
+		const validationPromises = Object.entries(this.schema).filter(([, validator]) => !this.isComputedValidator(validator)).map(async ([key, validator], index) => {
 			const value = mutatedData?.[key] !== void 0 ? mutatedData[key] : validator.getDefaultValue();
 			const childContext = {
 				...context,
@@ -311,16 +312,18 @@ var ObjectValidator = class ObjectValidator extends BaseValidator {
 			};
 			const childResult = await validator.validate(value, childContext);
 			if (childResult.data !== void 0 && !validator.isOmitted()) validatedData[key] = childResult.data;
-			if (childResult.isValid === false) errors.push(...childResult.errors);
+			if (childResult.isValid === false) fieldErrors[index] = childResult.errors;
 		});
 		await Promise.all(validationPromises);
+		for (const childErrors of fieldErrors) if (childErrors) errors.push(...childErrors);
 		if (errors.length > 0) return {
 			isValid: false,
 			errors,
 			data: void 0
 		};
 		const computedFields = this.getComputedFields();
-		const computedPromises = Object.entries(computedFields).map(async ([key, validator]) => {
+		const computedErrors = [];
+		const computedPromises = Object.entries(computedFields).map(async ([key, validator], index) => {
 			const childContext = {
 				...context,
 				parent: validatedData,
@@ -328,15 +331,18 @@ var ObjectValidator = class ObjectValidator extends BaseValidator {
 			};
 			const childResult = await validator.validate(validatedData, childContext);
 			if (childResult.data !== void 0 && !validator.isOmitted()) validatedData[key] = childResult.data;
-			if (childResult.isValid === false) errors.push(...childResult.errors);
+			if (childResult.isValid === false) computedErrors[index] = childResult.errors;
 		});
 		await Promise.all(computedPromises);
+		for (const childErrors of computedErrors) if (childErrors) errors.push(...childErrors);
 		if (errors.length > 0) return {
 			isValid: false,
 			errors,
 			data: void 0
 		};
-		const cleanedData = removeUndefinedValues(validatedData);
+		const orderedData = {};
+		for (const key of Object.keys(this.schema)) if (key in validatedData) orderedData[key] = validatedData[key];
+		const cleanedData = removeUndefinedValues(orderedData);
 		const transformedData = await this.startTransformationPipeline(cleanedData, context);
 		return {
 			isValid: true,

package/esm/seal/src/validators/object-validator.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"object-validator.mjs","names":[],"sources":["../../../../../../../../../seal/src/validators/object-validator.ts"],"sourcesContent":["import { except } from \"@mongez/reinforcements\";\nimport { isPlainObject } from \"@mongez/supportive-is\";\nimport { setKeyPath } from \"../helpers/path-helpers\";\nimport { objectTrimMutator, stripUnknownMutator } from \"../mutators/object-mutators\";\nimport { objectRule } from \"../rules/common/type-rules\";\nimport { unknownKeyRule } from \"../rules/common/unknown-key\";\nimport type { JsonSchemaResult, JsonSchemaTarget } from \"../standard-schema/json-schema\";\nimport { applyNullable, wrapNullableStrict } from \"../standard-schema/json-schema\";\nimport type { Schema, SchemaContext, ValidationResult } from \"../types\";\nimport type { InferInputObjectShape, InferOutputObjectShape } from \"../types/inference-types\";\nimport { BaseValidator } from \"./base-validator\";\nimport { ComputedValidator } from \"./computed-validator\";\n\n/**\n * Object validator class with generic schema type for proper type inference.\n *\n * Threads two distinct inferred shapes into `BaseValidator`'s `TInput`/`TOutput`:\n *\n * - `TInput`  = `InferInputObjectShape<TSchema>`  — what `~standard.validate()`\n *               accepts (caller's pre-validation payload; defaults/catches make\n *               keys optional)\n * - `TOutput` = `InferOutputObjectShape<TSchema>` — what `~standard.validate()`\n *               returns on success (post-default, post-catch shape; guaranteed\n *               keys are required)\n *\n * Both helpers are used directly (not the full `Infer.*` walker) to avoid a\n * recursive class-base evaluation that would otherwise occur when the\n * brand-aware widening tries to inspect the class type.\n */\nexport class ObjectValidator<TSchema extends Schema = Schema> extends BaseValidator<\n  InferInputObjectShape<TSchema>,\n  InferOutputObjectShape<TSchema>\n> {\n  protected shouldAllowUnknown = false;\n  protected allowedKeys: string[] = [];\n  protected hasUnknownKeyRule = false;\n\n  public constructor(\n    public schema: TSchema,\n    errorMessage?: string,\n  ) {\n    super();\n    this.addMutableRule(objectRule, errorMessage);\n  }\n\n  /**\n   * Check if value is an object type (plain object, not array or date)\n   */\n  public matchesType(value: any): boolean {\n    return isPlainObject(value);\n  }\n\n  /** Strip unknown keys from the data */\n  public stripUnknown() {\n    const validator = this.instance;\n    return validator.addMutator(stripUnknownMutator, {\n      get allowedKeys() {\n        return validator.allowedKeys;\n      },\n    });\n  }\n\n  /** Add list of allowed keys that could be in the data but not necessarily validated */\n  public allow(...keys: string[]) {\n    const validator = this.instance;\n    validator.allowedKeys.push(...keys);\n    return validator;\n  }\n\n  /** Trim values of the object properties */\n  public trim(recursive = true) {\n    const validator = this.instance;\n    return validator.addMutator(objectTrimMutator, { recursive });\n  }\n\n  /** Whether to allow unknown properties\n   * Please note it will allow only unknown direct children keys, not nested children keys\n   */\n  public allowUnknown(allow = true) {\n    const validator = this.instance;\n    validator.shouldAllowUnknown = allow;\n    return validator;\n  }\n\n  /**\n   * Create a copy of this object validator with the same configuration\n   * Copies schema, rules, mutators, transformers, and object-specific settings\n   *\n   * @returns A new ObjectValidator instance with copied configuration\n   *\n   * @example\n   * ```ts\n   * const baseUser = v.object({ name: v.string() }).allowUnknown();\n   * const userCopy = baseUser.clone();\n   * // userCopy has the same schema and allowUnknown setting\n   * ```\n   */\n  public override clone(keys?: string[]): this {\n    // Get cloned instance with all BaseValidator properties\n    const cloned = super.clone();\n\n    // Clone schema with deep copy of validators\n    const newSchema = {} as TSchema;\n    for (const [key, validator] of Object.entries(this.schema)) {\n      if (keys && !keys.includes(key)) continue;\n      (newSchema as Schema)[key] = validator.clone();\n    }\n\n    cloned.schema = newSchema;\n\n    // Add ObjectValidator-specific properties\n    cloned.shouldAllowUnknown = this.shouldAllowUnknown;\n    cloned.allowedKeys = [...this.allowedKeys];\n    // NOTE: hasUnknownKeyRule is intentionally NOT copied.\n    // Each clone must add its own unknownKeyRule on first validate()\n    // so it holds references to its own schema/allowedKeys, not the original's.\n\n    return cloned;\n  }\n\n  /**\n   * Extend this schema with additional fields\n   * Clones the current validator and adds new fields to the schema\n   * **Keeps original configuration** (allowUnknown, stripUnknown, etc.)\n   *\n   * If an ObjectValidator is provided, only its schema is used - its configuration is ignored.\n   * This is useful for creating reusable field collections that can be added to different schemas.\n   *\n   * @param schemaOrValidator - Plain schema object or ObjectValidator to extend with\n   * @returns A new ObjectValidator with merged schema and original configuration\n   *\n   * @example\n   * ```ts\n   * // Extend with plain schema\n   * const baseUser = v.object({\n   *   name: v.string().required(),\n   *   email: v.string().email().required()\n   * }).allowUnknown();\n   *\n   * const adminUser = baseUser.extend({\n   *   role: v.string().in(['admin', 'superadmin']).required()\n   * });\n   * // adminUser has: name, email, role\n   * // adminUser keeps: allowUnknown() from base ✅\n   *\n   * // Extend with ObjectValidator (only schema is used)\n   * const auditFields = v.object({\n   *   createdAt: v.date().required(),\n   *   updatedAt: v.date().required()\n   * }).stripUnknown(); // This config is ignored!\n   *\n   * const fullUser = baseUser.extend(auditFields);\n   * // fullUser has: name, email, createdAt, updatedAt\n   * // fullUser keeps: allowUnknown() from base (NOT stripUnknown from auditFields) ✅\n   *\n   * // Chain multiple extends\n   * const complexSchema = baseUser\n   *   .extend(auditFields)\n   *   .extend({ metadata: v.object({}) });\n   * ```\n   */\n  public extend<TExtension extends Schema>(\n    schemaOrValidator: TExtension | ObjectValidator<TExtension>,\n  ): ObjectValidator<TSchema & TExtension> {\n    // Clone current validator to preserve original\n    const extended = this.clone() as any;\n\n    // Extract schema from parameter\n    const schemaToAdd =\n      schemaOrValidator instanceof ObjectValidator ? schemaOrValidator.schema : schemaOrValidator;\n\n    // Merge schemas with cloned validators (later fields override earlier ones)\n    for (const [key, validator] of Object.entries(schemaToAdd)) {\n      (extended.schema as Schema)[key] = validator.clone();\n    }\n\n    return extended as ObjectValidator<TSchema & TExtension>;\n  }\n\n  /**\n   * Merge with another ObjectValidator\n   * Clones current validator, merges schemas, and **overrides configuration** with other validator's config\n   *\n   * Unlike extend(), merge() combines both schemas AND configurations.\n   * The other validator's configuration (allowUnknown, stripUnknown, etc.) takes precedence.\n   *\n   * @param validator - Another ObjectValidator to merge with\n   * @returns A new ObjectValidator with merged schema and configuration\n   *\n   * @example\n   * ```ts\n   * const baseUser = v.object({\n   *   name: v.string().required()\n   * }).allowUnknown();\n   *\n   * const timestamps = v.object({\n   *   createdAt: v.date().required(),\n   *   updatedAt: v.date().required()\n   * }).stripUnknown();\n   *\n   * const merged = baseUser.merge(timestamps);\n   * // merged has: name, createdAt, updatedAt\n   * // merged config: stripUnknown() from timestamps (overrides allowUnknown) ✅\n   *\n   * // Chain multiple merges\n   * const full = baseUser.merge(timestamps).merge(softDeleteSchema);\n   * ```\n   */\n  public merge<TMerge extends Schema>(\n    validator: ObjectValidator<TMerge>,\n  ): ObjectValidator<TSchema & TMerge> {\n    // Clone current validator\n    const merged = this.clone() as any;\n\n    // Merge schemas with cloned validators (later fields override earlier ones)\n    for (const [key, schemaValidator] of Object.entries(validator.schema)) {\n      (merged.schema as Schema)[key] = schemaValidator.clone();\n    }\n\n    // Override configuration with other validator's config\n    merged.shouldAllowUnknown = validator.shouldAllowUnknown;\n    merged.allowedKeys = [...merged.allowedKeys, ...validator.allowedKeys];\n\n    // Append rules, mutators, transformers from other validator\n    merged.rules.push(...validator.rules);\n    merged.mutators.push(...validator.mutators);\n    merged.dataTransformers.push(...validator.dataTransformers);\n\n    // Merge attributes text (later wins)\n    merged.attributesText = {\n      ...merged.attributesText,\n      ...validator.attributesText,\n    };\n\n    merged.translatedAttributes = {\n      ...merged.translatedAttributes,\n      ...validator.translatedAttributes,\n    };\n\n    return merged as ObjectValidator<TSchema & TMerge>;\n  }\n\n  /**\n   * Create a new schema with only the specified fields\n   * Clones the current validator and keeps only the selected fields\n   * **Preserves all configuration** (allowUnknown, stripUnknown, etc.)\n   *\n   * @param keys - Field names to keep in the schema\n   * @returns A new ObjectValidator with only the picked fields\n   *\n   * @example\n   * ```ts\n   * const fullUser = v.object({\n   *   id: v.int().required(),\n   *   name: v.string().required(),\n   *   email: v.string().email().required(),\n   *   password: v.string().required(),\n   *   role: v.string()\n   * }).allowUnknown();\n   *\n   * // For login - only need email and password\n   * const loginSchema = fullUser.pick('email', 'password');\n   * // loginSchema has: { email, password }\n   * // loginSchema keeps: allowUnknown() ✅\n   *\n   * // For public profile\n   * const publicSchema = fullUser.pick('id', 'name', 'role');\n   * // publicSchema has: { id, name, role }\n   * ```\n   */\n  public pick<K extends keyof TSchema>(...keys: K[]): ObjectValidator<Pick<TSchema, K>> {\n    // Clone current validator\n    const picked = this.clone() as any;\n\n    // Create new schema with only picked keys\n    const newSchema = {} as Pick<TSchema, K>;\n    for (const key of keys) {\n      if (key in picked.schema) {\n        (newSchema as any)[key] = picked.schema[key];\n      }\n    }\n\n    picked.schema = newSchema;\n\n    return picked as ObjectValidator<Pick<TSchema, K>>;\n  }\n\n  /**\n   * Mark all or the given schema fields as optional\n   */\n  public partial<K extends keyof TSchema>(...keys: K[]) {\n    const validationSchema = this.clone();\n\n    if (keys.length === 0) {\n      keys = Object.keys(validationSchema.schema) as K[];\n    }\n\n    for (const [key, validator] of Object.entries(validationSchema.schema)) {\n      if (keys.length === 0 || keys.includes(key as K)) {\n        (validationSchema.schema as Schema)[key] = validator.optional();\n      }\n    }\n\n    return validationSchema;\n  }\n\n  /**\n   * Make the all or the given fields as required\n   */\n  public requiredFields<K extends keyof TSchema>(...keys: K[]) {\n    const validationSchema = this.clone();\n\n    if (keys.length === 0) {\n      keys = Object.keys(validationSchema.schema) as K[];\n    }\n\n    for (const [key, validator] of Object.entries(validationSchema.schema)) {\n      if (keys.length === 0 || keys.includes(key as K)) {\n        (validationSchema.schema as Schema)[key] = validator.required();\n      }\n    }\n\n    return validationSchema;\n  }\n\n  /**\n   * Create a new schema excluding the specified fields\n   * Clones the current validator and removes the specified fields\n   * **Preserves all configuration** (allowUnknown, stripUnknown, etc.)\n   *\n   * @param keys - Field names to exclude from the schema\n   * @returns A new ObjectValidator without the excluded fields\n   *\n   * @example\n   * ```ts\n   * const fullUser = v.object({\n   *   id: v.int().required(),\n   *   name: v.string().required(),\n   *   email: v.string().email().required(),\n   *   password: v.string().required(),\n   *   role: v.string()\n   * }).allowUnknown();\n   *\n   * // For updates - exclude id\n   * const updateSchema = fullUser.without('id');\n   * // updateSchema has: { name, email, password, role }\n   * // updateSchema keeps: allowUnknown() ✅\n   *\n   * // For public API - exclude sensitive fields\n   * const publicSchema = fullUser.without('password', 'role');\n   * // publicSchema has: { id, name, email }\n   *\n   * // Combine with other methods\n   * const patchSchema = fullUser.without('id', 'password');\n   * // patchSchema has: { name, email, role }\n   * ```\n   */\n  public without<K extends keyof TSchema>(...keys: K[]): ObjectValidator<Omit<TSchema, K>> {\n    // Clone current validator\n    const filtered = this.clone() as any;\n\n    // Create new schema excluding specified keys\n    const newSchema = {} as Omit<TSchema, K>;\n    for (const key in filtered.schema) {\n      if (!keys.includes(key as any)) {\n        (newSchema as any)[key] = filtered.schema[key];\n      }\n    }\n\n    filtered.schema = newSchema;\n\n    return filtered as ObjectValidator<Omit<TSchema, K>>;\n  }\n\n  /** Mutate the data */\n  public mutate(data: any, context: SchemaContext) {\n    if (!isPlainObject(data)) return data;\n    return super.mutate({ ...data }, context);\n  }\n\n  /** Validate the data */\n  public async validate(\n    data: any,\n    context: SchemaContext = { path: \"\" } as SchemaContext,\n  ): Promise<ValidationResult> {\n    context.schema = this.schema;\n    const mutatedData = await this.mutate(data, context);\n\n    // Check for unknown properties\n    if (this.shouldAllowUnknown === false && !this.hasUnknownKeyRule) {\n      this.hasUnknownKeyRule = true;\n      const rule = this.addMutableRule(unknownKeyRule, undefined, {\n        allowedKeys: this.allowedKeys,\n        schema: this.schema,\n      });\n\n      this.setRuleAttributesList(rule);\n    }\n\n    const result = await super.validate(mutatedData, context);\n\n    if (result.isValid === false) return result;\n\n    // Absent (no default) or null (nullable) inputs short-circuit here —\n    // BaseValidator.validate already resolved the outcome, so recursing into\n    // the shape below would wrongly re-run required checks against `undefined`.\n    if (mutatedData === undefined || mutatedData === null) return result;\n\n    // ═══════════════════════════════════════════════════════════\n    // PHASE 1: Validate user input fields (skip computed/managed)\n    // ═══════════════════════════════════════════════════════════\n    const errors: ValidationResult[\"errors\"] = [];\n    const validatedData: any = {};\n\n    const userInputEntries = Object.entries(this.schema).filter(\n      ([, validator]) => !this.isComputedValidator(validator),\n    );\n\n    const validationPromises = userInputEntries.map(async ([key, validator]) => {\n      const value =\n        mutatedData?.[key] !== undefined ? mutatedData[key] : validator.getDefaultValue();\n\n      const childContext: SchemaContext = {\n        ...context,\n        parent: mutatedData,\n        value,\n        key,\n        path: setKeyPath(context.path, key),\n      };\n\n      const childResult = await validator.validate(value, childContext);\n\n      // Only include in validated data if not omitted\n      if (childResult.data !== undefined && !validator.isOmitted()) {\n        validatedData[key] = childResult.data;\n      }\n\n      if (childResult.isValid === false) {\n        errors.push(...childResult.errors);\n      }\n    });\n\n    await Promise.all(validationPromises);\n\n    // If Phase 1 failed, return early\n    if (errors.length > 0) {\n      return {\n        isValid: false,\n        errors,\n        data: undefined,\n      };\n    }\n\n    // ═══════════════════════════════════════════════════════════\n    // PHASE 2: Execute computed/managed fields with validated data\n    // ═══════════════════════════════════════════════════════════\n    const computedFields = this.getComputedFields();\n\n    const computedPromises = Object.entries(computedFields).map(async ([key, validator]) => {\n      const childContext: SchemaContext = {\n        ...context,\n        parent: validatedData,\n        value: undefined, // Computed fields don't have input value\n      };\n\n      // Execute computed callback with validated data\n      const childResult = await validator.validate(validatedData, childContext);\n\n      // Only include in final data if not omitted\n      if (childResult.data !== undefined && !validator.isOmitted()) {\n        validatedData[key] = childResult.data;\n      }\n\n      if (childResult.isValid === false) {\n        errors.push(...childResult.errors);\n      }\n    });\n\n    await Promise.all(computedPromises);\n\n    // If Phase 2 failed, return early\n    if (errors.length > 0) {\n      return {\n        isValid: false,\n        errors,\n        data: undefined,\n      };\n    }\n\n    // Remove undefined values\n    const cleanedData = removeUndefinedValues(validatedData);\n\n    const transformedData = await this.startTransformationPipeline(cleanedData, context);\n\n    const output =\n      this.shouldAllowUnknown === false\n        ? transformedData\n        : {\n            ...transformedData,\n            ...except(mutatedData, Object.keys(this.schema)),\n          };\n\n    return {\n      isValid: true,\n      errors: [],\n      data: output,\n    };\n  }\n\n  /**\n   * Check if a validator is a computed or managed field\n   * ManagedValidator extends ComputedValidator, so instanceof catches both\n   */\n  private isComputedValidator(validator: BaseValidator): boolean {\n    return validator instanceof ComputedValidator;\n  }\n\n  /**\n   * Get all computed/managed fields from the schema\n   */\n  private getComputedFields(): Record<string, ComputedValidator> {\n    const computed: Record<string, ComputedValidator> = {};\n\n    for (const [key, validator] of Object.entries(this.schema)) {\n      if (validator instanceof ComputedValidator) {\n        computed[key] = validator;\n      }\n    }\n\n    return computed;\n  }\n\n  /**\n   * @inheritdoc\n   *\n   * Recursively generates JSON Schema for all input fields in the schema.\n   * Computed/managed fields are skipped — they have no input representation.\n   *\n   * **Standard targets** (`draft-2020-12`, `draft-07`, `openapi-3.0`):\n   * - Fields marked `.optional()` are excluded from `required`.\n   *\n   * **`openai-strict` target** (OpenAI Structured Outputs):\n   * - ALL fields appear in `required` — OpenAI rejects schemas with optional fields.\n   * - Optional fields are instead expressed as nullable types:\n   *   `{ type: [\"string\", \"null\"] }` so the model can output `null` for them.\n   * - Recursively applies `openai-strict` to all nested objects.\n   *\n   * @example\n   * ```ts\n   * v.object({\n   *   name: v.string().required(),\n   *   age: v.int().optional(),\n   * }).toJsonSchema(\"draft-2020-12\")\n   * // → { type: \"object\",\n   * //     properties: { name: { type: \"string\" }, age: { type: \"integer\" } },\n   * //     required: [\"name\"], additionalProperties: false }\n   *\n   * v.object({\n   *   name: v.string().required(),\n   *   age: v.int().optional(),\n   * }).toJsonSchema(\"openai-strict\")\n   * // → { type: \"object\",\n   * //     properties: { name: { type: \"string\" }, age: { type: [\"integer\", \"null\"] } },\n   * //     required: [\"name\", \"age\"],   ← all fields\n   * //     additionalProperties: false }\n   * ```\n   */\n  public override toJsonSchema(target: JsonSchemaTarget = \"draft-2020-12\"): JsonSchemaResult {\n    const properties: Record<string, JsonSchemaResult> = {};\n    const required: string[] = [];\n    const isOpenAIStrict = target === \"openai-strict\";\n\n    for (const [key, validator] of Object.entries(this.schema)) {\n      // Skip computed/managed — runtime-only, no input schema\n      if (validator instanceof ComputedValidator) continue;\n\n      let fieldSchema = validator.toJsonSchema(target);\n\n      if (isOpenAIStrict) {\n        // OpenAI strict: every field must be in required.\n        // Optional fields are expressed as nullable rather than absent.\n        if (validator.isOptional) {\n          fieldSchema = wrapNullableStrict(fieldSchema);\n        }\n        required.push(key);\n      } else {\n        // Standard JSON Schema: only non-optional fields go in required\n        if (!validator.isOptional) {\n          required.push(key);\n        }\n      }\n\n      properties[key] = fieldSchema;\n    }\n\n    const schema: JsonSchemaResult = { type: \"object\", properties };\n\n    if (required.length > 0) schema.required = required;\n    if (!this.shouldAllowUnknown) schema.additionalProperties = false;\n    if (this.isNullable) applyNullable(schema, target);\n\n    return schema;\n  }\n}\n\n/** Recursively remove undefined values from an object */\nfunction removeUndefinedValues(obj: any, visited = new WeakMap<object, any>()): any {\n  // Handle primitives and null\n  if (obj === null) {\n    return obj;\n  }\n\n  // Handle arrays\n  if (Array.isArray(obj)) {\n    return obj.map((item) => removeUndefinedValues(item, visited));\n  }\n\n  // Skip non-plain objects (class instances, Dates, Buffers, etc.)\n  if (!isPlainObject(obj)) {\n    return obj;\n  }\n\n  // Handle circular references - return already processed result\n  if (visited.has(obj)) {\n    return visited.get(obj);\n  }\n\n  // Process plain objects\n  const result: any = {};\n  visited.set(obj, result); // Mark as processing BEFORE recursion\n\n  for (const [key, value] of Object.entries(obj)) {\n    if (value !== undefined) {\n      result[key] = removeUndefinedValues(value, visited);\n    }\n  }\n\n  return result;\n}\n"],"mappings":"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"}
+{"version":3,"file":"object-validator.mjs","names":[],"sources":["../../../../../../../../../seal/src/validators/object-validator.ts"],"sourcesContent":["import { except } from \"@mongez/reinforcements\";\nimport { isPlainObject } from \"@mongez/supportive-is\";\nimport { setKeyPath } from \"../helpers/path-helpers\";\nimport { objectTrimMutator, stripUnknownMutator } from \"../mutators/object-mutators\";\nimport { objectRule } from \"../rules/common/type-rules\";\nimport { unknownKeyRule } from \"../rules/common/unknown-key\";\nimport type { JsonSchemaResult, JsonSchemaTarget } from \"../standard-schema/json-schema\";\nimport { applyNullable, wrapNullableStrict } from \"../standard-schema/json-schema\";\nimport type { Schema, SchemaContext, ValidationResult } from \"../types\";\nimport type { InferInputObjectShape, InferOutputObjectShape } from \"../types/inference-types\";\nimport { BaseValidator } from \"./base-validator\";\nimport { ComputedValidator } from \"./computed-validator\";\n\n/**\n * Object validator class with generic schema type for proper type inference.\n *\n * Threads two distinct inferred shapes into `BaseValidator`'s `TInput`/`TOutput`:\n *\n * - `TInput`  = `InferInputObjectShape<TSchema>`  — what `~standard.validate()`\n *               accepts (caller's pre-validation payload; defaults/catches make\n *               keys optional)\n * - `TOutput` = `InferOutputObjectShape<TSchema>` — what `~standard.validate()`\n *               returns on success (post-default, post-catch shape; guaranteed\n *               keys are required)\n *\n * Both helpers are used directly (not the full `Infer.*` walker) to avoid a\n * recursive class-base evaluation that would otherwise occur when the\n * brand-aware widening tries to inspect the class type.\n */\nexport class ObjectValidator<TSchema extends Schema = Schema> extends BaseValidator<\n  InferInputObjectShape<TSchema>,\n  InferOutputObjectShape<TSchema>\n> {\n  protected shouldAllowUnknown = false;\n  protected allowedKeys: string[] = [];\n  protected hasUnknownKeyRule = false;\n\n  public constructor(\n    public schema: TSchema,\n    errorMessage?: string,\n  ) {\n    super();\n    this.addMutableRule(objectRule, errorMessage);\n  }\n\n  /**\n   * Check if value is an object type (plain object, not array or date)\n   */\n  public matchesType(value: any): boolean {\n    return isPlainObject(value);\n  }\n\n  /** Strip unknown keys from the data */\n  public stripUnknown() {\n    const validator = this.instance;\n    return validator.addMutator(stripUnknownMutator, {\n      get allowedKeys() {\n        return validator.allowedKeys;\n      },\n    });\n  }\n\n  /** Add list of allowed keys that could be in the data but not necessarily validated */\n  public allow(...keys: string[]) {\n    const validator = this.instance;\n    validator.allowedKeys.push(...keys);\n    return validator;\n  }\n\n  /** Trim values of the object properties */\n  public trim(recursive = true) {\n    const validator = this.instance;\n    return validator.addMutator(objectTrimMutator, { recursive });\n  }\n\n  /** Whether to allow unknown properties\n   * Please note it will allow only unknown direct children keys, not nested children keys\n   */\n  public allowUnknown(allow = true) {\n    const validator = this.instance;\n    validator.shouldAllowUnknown = allow;\n    return validator;\n  }\n\n  /**\n   * Create a copy of this object validator with the same configuration\n   * Copies schema, rules, mutators, transformers, and object-specific settings\n   *\n   * @returns A new ObjectValidator instance with copied configuration\n   *\n   * @example\n   * ```ts\n   * const baseUser = v.object({ name: v.string() }).allowUnknown();\n   * const userCopy = baseUser.clone();\n   * // userCopy has the same schema and allowUnknown setting\n   * ```\n   */\n  public override clone(keys?: string[]): this {\n    // Get cloned instance with all BaseValidator properties\n    const cloned = super.clone();\n\n    // Clone schema with deep copy of validators\n    const newSchema = {} as TSchema;\n    for (const [key, validator] of Object.entries(this.schema)) {\n      if (keys && !keys.includes(key)) continue;\n      (newSchema as Schema)[key] = validator.clone();\n    }\n\n    cloned.schema = newSchema;\n\n    // Add ObjectValidator-specific properties\n    cloned.shouldAllowUnknown = this.shouldAllowUnknown;\n    cloned.allowedKeys = [...this.allowedKeys];\n    // NOTE: hasUnknownKeyRule is intentionally NOT copied.\n    // Each clone must add its own unknownKeyRule on first validate()\n    // so it holds references to its own schema/allowedKeys, not the original's.\n\n    return cloned;\n  }\n\n  /**\n   * Extend this schema with additional fields\n   * Clones the current validator and adds new fields to the schema\n   * **Keeps original configuration** (allowUnknown, stripUnknown, etc.)\n   *\n   * If an ObjectValidator is provided, only its schema is used - its configuration is ignored.\n   * This is useful for creating reusable field collections that can be added to different schemas.\n   *\n   * @param schemaOrValidator - Plain schema object or ObjectValidator to extend with\n   * @returns A new ObjectValidator with merged schema and original configuration\n   *\n   * @example\n   * ```ts\n   * // Extend with plain schema\n   * const baseUser = v.object({\n   *   name: v.string().required(),\n   *   email: v.string().email().required()\n   * }).allowUnknown();\n   *\n   * const adminUser = baseUser.extend({\n   *   role: v.string().in(['admin', 'superadmin']).required()\n   * });\n   * // adminUser has: name, email, role\n   * // adminUser keeps: allowUnknown() from base ✅\n   *\n   * // Extend with ObjectValidator (only schema is used)\n   * const auditFields = v.object({\n   *   createdAt: v.date().required(),\n   *   updatedAt: v.date().required()\n   * }).stripUnknown(); // This config is ignored!\n   *\n   * const fullUser = baseUser.extend(auditFields);\n   * // fullUser has: name, email, createdAt, updatedAt\n   * // fullUser keeps: allowUnknown() from base (NOT stripUnknown from auditFields) ✅\n   *\n   * // Chain multiple extends\n   * const complexSchema = baseUser\n   *   .extend(auditFields)\n   *   .extend({ metadata: v.object({}) });\n   * ```\n   */\n  public extend<TExtension extends Schema>(\n    schemaOrValidator: TExtension | ObjectValidator<TExtension>,\n  ): ObjectValidator<TSchema & TExtension> {\n    // Clone current validator to preserve original\n    const extended = this.clone() as any;\n\n    // Extract schema from parameter\n    const schemaToAdd =\n      schemaOrValidator instanceof ObjectValidator ? schemaOrValidator.schema : schemaOrValidator;\n\n    // Merge schemas with cloned validators (later fields override earlier ones)\n    for (const [key, validator] of Object.entries(schemaToAdd)) {\n      (extended.schema as Schema)[key] = validator.clone();\n    }\n\n    return extended as ObjectValidator<TSchema & TExtension>;\n  }\n\n  /**\n   * Merge with another ObjectValidator\n   * Clones current validator, merges schemas, and **overrides configuration** with other validator's config\n   *\n   * Unlike extend(), merge() combines both schemas AND configurations.\n   * The other validator's configuration (allowUnknown, stripUnknown, etc.) takes precedence.\n   *\n   * @param validator - Another ObjectValidator to merge with\n   * @returns A new ObjectValidator with merged schema and configuration\n   *\n   * @example\n   * ```ts\n   * const baseUser = v.object({\n   *   name: v.string().required()\n   * }).allowUnknown();\n   *\n   * const timestamps = v.object({\n   *   createdAt: v.date().required(),\n   *   updatedAt: v.date().required()\n   * }).stripUnknown();\n   *\n   * const merged = baseUser.merge(timestamps);\n   * // merged has: name, createdAt, updatedAt\n   * // merged config: stripUnknown() from timestamps (overrides allowUnknown) ✅\n   *\n   * // Chain multiple merges\n   * const full = baseUser.merge(timestamps).merge(softDeleteSchema);\n   * ```\n   */\n  public merge<TMerge extends Schema>(\n    validator: ObjectValidator<TMerge>,\n  ): ObjectValidator<TSchema & TMerge> {\n    // Clone current validator\n    const merged = this.clone() as any;\n\n    // Merge schemas with cloned validators (later fields override earlier ones)\n    for (const [key, schemaValidator] of Object.entries(validator.schema)) {\n      (merged.schema as Schema)[key] = schemaValidator.clone();\n    }\n\n    // Override configuration with other validator's config\n    merged.shouldAllowUnknown = validator.shouldAllowUnknown;\n    merged.allowedKeys = [...merged.allowedKeys, ...validator.allowedKeys];\n\n    // Append rules, mutators, transformers from other validator\n    merged.rules.push(...validator.rules);\n    merged.mutators.push(...validator.mutators);\n    merged.dataTransformers.push(...validator.dataTransformers);\n\n    // Merge attributes text (later wins)\n    merged.attributesText = {\n      ...merged.attributesText,\n      ...validator.attributesText,\n    };\n\n    merged.translatedAttributes = {\n      ...merged.translatedAttributes,\n      ...validator.translatedAttributes,\n    };\n\n    return merged as ObjectValidator<TSchema & TMerge>;\n  }\n\n  /**\n   * Create a new schema with only the specified fields\n   * Clones the current validator and keeps only the selected fields\n   * **Preserves all configuration** (allowUnknown, stripUnknown, etc.)\n   *\n   * @param keys - Field names to keep in the schema\n   * @returns A new ObjectValidator with only the picked fields\n   *\n   * @example\n   * ```ts\n   * const fullUser = v.object({\n   *   id: v.int().required(),\n   *   name: v.string().required(),\n   *   email: v.string().email().required(),\n   *   password: v.string().required(),\n   *   role: v.string()\n   * }).allowUnknown();\n   *\n   * // For login - only need email and password\n   * const loginSchema = fullUser.pick('email', 'password');\n   * // loginSchema has: { email, password }\n   * // loginSchema keeps: allowUnknown() ✅\n   *\n   * // For public profile\n   * const publicSchema = fullUser.pick('id', 'name', 'role');\n   * // publicSchema has: { id, name, role }\n   * ```\n   */\n  public pick<K extends keyof TSchema>(...keys: K[]): ObjectValidator<Pick<TSchema, K>> {\n    // Clone current validator\n    const picked = this.clone() as any;\n\n    // Create new schema with only picked keys\n    const newSchema = {} as Pick<TSchema, K>;\n    for (const key of keys) {\n      if (key in picked.schema) {\n        (newSchema as any)[key] = picked.schema[key];\n      }\n    }\n\n    picked.schema = newSchema;\n\n    return picked as ObjectValidator<Pick<TSchema, K>>;\n  }\n\n  /**\n   * Mark all or the given schema fields as optional\n   */\n  public partial<K extends keyof TSchema>(...keys: K[]) {\n    const validationSchema = this.clone();\n\n    if (keys.length === 0) {\n      keys = Object.keys(validationSchema.schema) as K[];\n    }\n\n    for (const [key, validator] of Object.entries(validationSchema.schema)) {\n      if (keys.length === 0 || keys.includes(key as K)) {\n        (validationSchema.schema as Schema)[key] = validator.optional();\n      }\n    }\n\n    return validationSchema;\n  }\n\n  /**\n   * Make the all or the given fields as required\n   */\n  public requiredFields<K extends keyof TSchema>(...keys: K[]) {\n    const validationSchema = this.clone();\n\n    if (keys.length === 0) {\n      keys = Object.keys(validationSchema.schema) as K[];\n    }\n\n    for (const [key, validator] of Object.entries(validationSchema.schema)) {\n      if (keys.length === 0 || keys.includes(key as K)) {\n        (validationSchema.schema as Schema)[key] = validator.required();\n      }\n    }\n\n    return validationSchema;\n  }\n\n  /**\n   * Create a new schema excluding the specified fields\n   * Clones the current validator and removes the specified fields\n   * **Preserves all configuration** (allowUnknown, stripUnknown, etc.)\n   *\n   * @param keys - Field names to exclude from the schema\n   * @returns A new ObjectValidator without the excluded fields\n   *\n   * @example\n   * ```ts\n   * const fullUser = v.object({\n   *   id: v.int().required(),\n   *   name: v.string().required(),\n   *   email: v.string().email().required(),\n   *   password: v.string().required(),\n   *   role: v.string()\n   * }).allowUnknown();\n   *\n   * // For updates - exclude id\n   * const updateSchema = fullUser.without('id');\n   * // updateSchema has: { name, email, password, role }\n   * // updateSchema keeps: allowUnknown() ✅\n   *\n   * // For public API - exclude sensitive fields\n   * const publicSchema = fullUser.without('password', 'role');\n   * // publicSchema has: { id, name, email }\n   *\n   * // Combine with other methods\n   * const patchSchema = fullUser.without('id', 'password');\n   * // patchSchema has: { name, email, role }\n   * ```\n   */\n  public without<K extends keyof TSchema>(...keys: K[]): ObjectValidator<Omit<TSchema, K>> {\n    // Clone current validator\n    const filtered = this.clone() as any;\n\n    // Create new schema excluding specified keys\n    const newSchema = {} as Omit<TSchema, K>;\n    for (const key in filtered.schema) {\n      if (!keys.includes(key as any)) {\n        (newSchema as any)[key] = filtered.schema[key];\n      }\n    }\n\n    filtered.schema = newSchema;\n\n    return filtered as ObjectValidator<Omit<TSchema, K>>;\n  }\n\n  /** Mutate the data */\n  public mutate(data: any, context: SchemaContext) {\n    if (!isPlainObject(data)) return data;\n    return super.mutate({ ...data }, context);\n  }\n\n  /** Validate the data */\n  public async validate(\n    data: any,\n    context: SchemaContext = { path: \"\" } as SchemaContext,\n  ): Promise<ValidationResult> {\n    context.schema = this.schema;\n    const mutatedData = await this.mutate(data, context);\n\n    // Check for unknown properties\n    if (this.shouldAllowUnknown === false && !this.hasUnknownKeyRule) {\n      this.hasUnknownKeyRule = true;\n      const rule = this.addMutableRule(unknownKeyRule, undefined, {\n        allowedKeys: this.allowedKeys,\n        schema: this.schema,\n      });\n\n      this.setRuleAttributesList(rule);\n    }\n\n    const result = await super.validate(mutatedData, context);\n\n    if (result.isValid === false) return result;\n\n    // Absent (no default) or null (nullable) inputs short-circuit here —\n    // BaseValidator.validate already resolved the outcome, so recursing into\n    // the shape below would wrongly re-run required checks against `undefined`.\n    if (mutatedData === undefined || mutatedData === null) return result;\n\n    // ═══════════════════════════════════════════════════════════\n    // PHASE 1: Validate user input fields (skip computed/managed)\n    // ═══════════════════════════════════════════════════════════\n    const errors: ValidationResult[\"errors\"] = [];\n    const validatedData: any = {};\n\n    // Child validators settle in completion order, so errors are collected per\n    // field and flattened in declared schema order for deterministic output.\n    const fieldErrors: Array<ValidationResult[\"errors\"]> = [];\n\n    const userInputEntries = Object.entries(this.schema).filter(\n      ([, validator]) => !this.isComputedValidator(validator),\n    );\n\n    const validationPromises = userInputEntries.map(async ([key, validator], index) => {\n      const value =\n        mutatedData?.[key] !== undefined ? mutatedData[key] : validator.getDefaultValue();\n\n      const childContext: SchemaContext = {\n        ...context,\n        parent: mutatedData,\n        value,\n        key,\n        path: setKeyPath(context.path, key),\n      };\n\n      const childResult = await validator.validate(value, childContext);\n\n      // Only include in validated data if not omitted\n      if (childResult.data !== undefined && !validator.isOmitted()) {\n        validatedData[key] = childResult.data;\n      }\n\n      if (childResult.isValid === false) {\n        fieldErrors[index] = childResult.errors;\n      }\n    });\n\n    await Promise.all(validationPromises);\n\n    for (const childErrors of fieldErrors) {\n      if (childErrors) {\n        errors.push(...childErrors);\n      }\n    }\n\n    // If Phase 1 failed, return early\n    if (errors.length > 0) {\n      return {\n        isValid: false,\n        errors,\n        data: undefined,\n      };\n    }\n\n    // ═══════════════════════════════════════════════════════════\n    // PHASE 2: Execute computed/managed fields with validated data\n    // ═══════════════════════════════════════════════════════════\n    const computedFields = this.getComputedFields();\n\n    const computedErrors: Array<ValidationResult[\"errors\"]> = [];\n\n    const computedPromises = Object.entries(computedFields).map(async ([key, validator], index) => {\n      const childContext: SchemaContext = {\n        ...context,\n        parent: validatedData,\n        value: undefined, // Computed fields don't have input value\n      };\n\n      // Execute computed callback with validated data\n      const childResult = await validator.validate(validatedData, childContext);\n\n      // Only include in final data if not omitted\n      if (childResult.data !== undefined && !validator.isOmitted()) {\n        validatedData[key] = childResult.data;\n      }\n\n      if (childResult.isValid === false) {\n        computedErrors[index] = childResult.errors;\n      }\n    });\n\n    await Promise.all(computedPromises);\n\n    for (const childErrors of computedErrors) {\n      if (childErrors) {\n        errors.push(...childErrors);\n      }\n    }\n\n    // If Phase 2 failed, return early\n    if (errors.length > 0) {\n      return {\n        isValid: false,\n        errors,\n        data: undefined,\n      };\n    }\n\n    // Fields were assigned in the order their validators finished; re-emit\n    // them in declared schema order so the output shape is deterministic.\n    const orderedData: any = {};\n\n    for (const key of Object.keys(this.schema)) {\n      if (key in validatedData) {\n        orderedData[key] = validatedData[key];\n      }\n    }\n\n    // Remove undefined values\n    const cleanedData = removeUndefinedValues(orderedData);\n\n    const transformedData = await this.startTransformationPipeline(cleanedData, context);\n\n    const output =\n      this.shouldAllowUnknown === false\n        ? transformedData\n        : {\n            ...transformedData,\n            ...except(mutatedData, Object.keys(this.schema)),\n          };\n\n    return {\n      isValid: true,\n      errors: [],\n      data: output,\n    };\n  }\n\n  /**\n   * Check if a validator is a computed or managed field\n   * ManagedValidator extends ComputedValidator, so instanceof catches both\n   */\n  private isComputedValidator(validator: BaseValidator): boolean {\n    return validator instanceof ComputedValidator;\n  }\n\n  /**\n   * Get all computed/managed fields from the schema\n   */\n  private getComputedFields(): Record<string, ComputedValidator> {\n    const computed: Record<string, ComputedValidator> = {};\n\n    for (const [key, validator] of Object.entries(this.schema)) {\n      if (validator instanceof ComputedValidator) {\n        computed[key] = validator;\n      }\n    }\n\n    return computed;\n  }\n\n  /**\n   * @inheritdoc\n   *\n   * Recursively generates JSON Schema for all input fields in the schema.\n   * Computed/managed fields are skipped — they have no input representation.\n   *\n   * **Standard targets** (`draft-2020-12`, `draft-07`, `openapi-3.0`):\n   * - Fields marked `.optional()` are excluded from `required`.\n   *\n   * **`openai-strict` target** (OpenAI Structured Outputs):\n   * - ALL fields appear in `required` — OpenAI rejects schemas with optional fields.\n   * - Optional fields are instead expressed as nullable types:\n   *   `{ type: [\"string\", \"null\"] }` so the model can output `null` for them.\n   * - Recursively applies `openai-strict` to all nested objects.\n   *\n   * @example\n   * ```ts\n   * v.object({\n   *   name: v.string().required(),\n   *   age: v.int().optional(),\n   * }).toJsonSchema(\"draft-2020-12\")\n   * // → { type: \"object\",\n   * //     properties: { name: { type: \"string\" }, age: { type: \"integer\" } },\n   * //     required: [\"name\"], additionalProperties: false }\n   *\n   * v.object({\n   *   name: v.string().required(),\n   *   age: v.int().optional(),\n   * }).toJsonSchema(\"openai-strict\")\n   * // → { type: \"object\",\n   * //     properties: { name: { type: \"string\" }, age: { type: [\"integer\", \"null\"] } },\n   * //     required: [\"name\", \"age\"],   ← all fields\n   * //     additionalProperties: false }\n   * ```\n   */\n  public override toJsonSchema(target: JsonSchemaTarget = \"draft-2020-12\"): JsonSchemaResult {\n    const properties: Record<string, JsonSchemaResult> = {};\n    const required: string[] = [];\n    const isOpenAIStrict = target === \"openai-strict\";\n\n    for (const [key, validator] of Object.entries(this.schema)) {\n      // Skip computed/managed — runtime-only, no input schema\n      if (validator instanceof ComputedValidator) continue;\n\n      let fieldSchema = validator.toJsonSchema(target);\n\n      if (isOpenAIStrict) {\n        // OpenAI strict: every field must be in required.\n        // Optional fields are expressed as nullable rather than absent.\n        if (validator.isOptional) {\n          fieldSchema = wrapNullableStrict(fieldSchema);\n        }\n        required.push(key);\n      } else {\n        // Standard JSON Schema: only non-optional fields go in required\n        if (!validator.isOptional) {\n          required.push(key);\n        }\n      }\n\n      properties[key] = fieldSchema;\n    }\n\n    const schema: JsonSchemaResult = { type: \"object\", properties };\n\n    if (required.length > 0) schema.required = required;\n    if (!this.shouldAllowUnknown) schema.additionalProperties = false;\n    if (this.isNullable) applyNullable(schema, target);\n\n    return schema;\n  }\n}\n\n/** Recursively remove undefined values from an object */\nfunction removeUndefinedValues(obj: any, visited = new WeakMap<object, any>()): any {\n  // Handle primitives and null\n  if (obj === null) {\n    return obj;\n  }\n\n  // Handle arrays\n  if (Array.isArray(obj)) {\n    return obj.map((item) => removeUndefinedValues(item, visited));\n  }\n\n  // Skip non-plain objects (class instances, Dates, Buffers, etc.)\n  if (!isPlainObject(obj)) {\n    return obj;\n  }\n\n  // Handle circular references - return already processed result\n  if (visited.has(obj)) {\n    return visited.get(obj);\n  }\n\n  // Process plain objects\n  const result: any = {};\n  visited.set(obj, result); // Mark as processing BEFORE recursion\n\n  for (const [key, value] of Object.entries(obj)) {\n    if (value !== undefined) {\n      result[key] = removeUndefinedValues(value, visited);\n    }\n  }\n\n  return result;\n}\n"],"mappings":"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"}

package/llms-full.txt

@@ -8,7 +8,7 @@
 
 ---
 name: configure-notifications
-description: 'Wire `@warlock.js/notifications` via a declarative `src/config/notifications.ts` that exports a `NotificationConfig` default — the notifications connector registers it at boot, so app code never calls `setNotificationConfig`. `channels`: registry mapping name → factory result (`mailChannel`, `inApp.configure`, custom `defineChannel`); `queue`: optional `QueueDispatcher` (`.queue()` throws without it); `preferences`: optional `PreferenceProvider` (drops channels the recipient muted); `rateLimit`: optional `RateLimiter` (drops channels exceeding per-recipient budgets). Triggers: `config/notifications.ts`, `NotificationConfig`, `setNotificationConfig`, `getNotificationConfig`, `mailChannel`, `inApp.configure`, "configure notifications", "wire notifications at boot", "set preferences provider", "set rate limit"; typical import `import { type NotificationConfig, mailChannel, inApp } from "@warlock.js/notifications"`. Skip: building a reusable notification — `@warlock.js/notifications/define-notification/SKILL.md`; the in-app read API — `@warlock.js/notifications/use-in-app/SKILL.md`; adding a custom channel — `@warlock.js/notifications/define-channel/SKILL.md`.'
+description: 'Wire `@warlock.js/notifications` via a declarative `src/config/notifications.ts` that exports a `NotificationConfig` default — the notifications connector registers it at boot, so app code never calls `setNotificationConfig`. `channels`: registry mapping name → factory result (`mailChannel`, `inApp.configure`, custom `defineChannel`); `queue`: optional `QueueDispatcher` (`.queue()` throws without it); `preferences`: optional `PreferenceProvider` (drops channels the recipient muted); `rateLimit`: optional `RateLimiter` (drops channels exceeding per-recipient budgets). Triggers: `config/notifications.ts`, `NotificationConfig`, `setNotificationConfig`, `getNotificationConfig`, `mailChannel`, `inApp.configure`, "configure notifications", "wire notifications at boot", "set preferences provider", "set rate limit"; typical import `import { type NotificationConfig, mailChannel, inApp } from "@warlock.js/notifications"`. Skip: building a reusable notification — the `define-notification` topic; the in-app read API — the `use-in-app` topic; adding a custom channel — the `define-channel` topic.'
 ---
 
 # Configure notifications
@@ -140,17 +140,17 @@ afterEach(() => resetNotificationConfig());
 
 ## See also
 
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — reusable multi-channel definitions.
-- [`use-in-app/SKILL.md`](../use-in-app/SKILL.md) — in-app read API.
-- [`define-channel/SKILL.md`](../define-channel/SKILL.md) — custom channels.
+- The `notifications-basics` topic — package front door.
+- The `define-notification` topic — reusable multi-channel definitions.
+- The `use-in-app` topic — in-app read API.
+- The `define-channel` topic — custom channels.
 
 
 ## define-channel  `@warlock.js/notifications/define-channel/SKILL.md`
 
 ---
 name: define-channel
-description: 'Add a custom notification channel — `defineChannel<P>({ name, route?, send })` returns a `Channel<P>` you register in the `channels` map of `setNotificationConfig`. `name` matches the key in `NotificationChannels` (extend via `declare module` for typing); `route(notifiable)` resolves the recipient''s address (defaults to `{ id }` when omitted); `send({ payload, route, notifiable, options })` does the actual transport. Use for Slack/Discord/internal-webhook/anything else — `fetch`-based with NO SDK is the simplest variant. Channels that load a heavy SDK should follow the lazy-import pattern from the develop-feature playbook. Triggers: `defineChannel`, `Channel<P>`, "custom notification channel", "add discord channel", "slack channel", "webhook channel", "new channel type", `declare module "@warlock.js/notifications"`; typical import `import { defineChannel } from "@warlock.js/notifications"`. Skip: lazy-loading an optional SDK behind the channel — `D:/xampp/htdocs/mongez/node/.claude/skills/develop-warlock.js-feature/SKILL.md`; using built-in channels — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
+description: 'Add a custom notification channel — `defineChannel<P>({ name, route?, send })` returns a `Channel<P>` you register in the `channels` map of `setNotificationConfig`. `name` matches the key in `NotificationChannels` (extend via `declare module` for typing); `route(notifiable)` resolves the recipient''s address (defaults to `{ id }` when omitted); `send({ payload, route, notifiable, options })` does the actual transport. Use for Slack/Discord/internal-webhook/anything else — `fetch`-based with NO SDK is the simplest variant. Channels that load a heavy SDK should follow the lazy-import pattern from the develop-feature playbook. Triggers: `defineChannel`, `Channel<P>`, "custom notification channel", "add discord channel", "slack channel", "webhook channel", "new channel type", `declare module "@warlock.js/notifications"`; typical import `import { defineChannel } from "@warlock.js/notifications"`. Skip: lazy-loading an optional SDK behind the channel — the `develop-warlock.js-feature` workspace skill; using built-in channels — the `configure-notifications` topic.'
 ---
 
 # `defineChannel` — custom channels
@@ -224,7 +224,7 @@ Throw to fail the send. The dispatcher catches per channel, fires a `failed` eve
 
 ## SDK-backed channels — lazy-import the SDK
 
-Channels that wrap a heavy SDK (Twilio, Slack SDK, FCM SDK) should follow the lazy-import pattern so apps that don't use them don't pay the install/load cost. The recipe + race-safe template lives in [`develop-warlock.js-feature`](../../../../.claude/skills/develop-warlock.js-feature/SKILL.md) — copy from there; do not invent a variant.
+Channels that wrap a heavy SDK (Twilio, Slack SDK, FCM SDK) should follow the lazy-import pattern so apps that don't use them don't pay the install/load cost. The recipe + race-safe template lives in the `develop-warlock.js-feature` workspace skill — copy from there; do not invent a variant.
 
 Sketch:
 
@@ -251,17 +251,17 @@ export const slackChannel = (config: { token: string }) =>
 
 ## See also
 
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — register channels in the config.
-- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — `notify.<custom-channel>` works after registration.
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — multi-channel renderers with the custom channel key.
-- `D:/xampp/htdocs/mongez/node/.claude/skills/develop-warlock.js-feature/SKILL.md` — lazy-import pattern for SDK-backed channels.
+- The `configure-notifications` topic — register channels in the config.
+- The `send-ad-hoc` topic — `notify.<custom-channel>` works after registration.
+- The `define-notification` topic — multi-channel renderers with the custom channel key.
+- The `develop-warlock.js-feature` workspace skill — lazy-import pattern for SDK-backed channels.
 
 
 ## define-notification  `@warlock.js/notifications/define-notification/SKILL.md`
 
 ---
 name: define-notification
-description: 'Build a reusable multi-channel notification with `defineNotification<Data>({ type, via, ...renderers })`. `type` is the stable identifier preference/rate-limit gates use AND defaults the database channel''s `type`. `via` is `ChannelName[]` OR `(data, to) => ChannelName[]` for per-recipient channel selection. Renderers are `(data, to, ctx) => NotificationChannels[C]`; `ctx` carries `locale` + `meta` from `SendOptions`. The returned object exposes `.send(to|to[], data, options?)`, `.queue(to|to[], data, options?)`, and `.only(...channels)`. Per-recipient + per-channel `Promise.allSettled` isolates failures; the database channel''s `type` is auto-defaulted from `def.type`; `SendOptions.idempotencyKey` is injected into the database payload. Triggers: `defineNotification`, `via`, "reusable notification", "multi-channel notification", "send through several channels at once", "render per channel", `RenderContext`, `def.type`; "force on a notification", "queue with delay"; typical import `import { defineNotification } from "@warlock.js/notifications"`. Skip: single-channel ad-hoc sends — `@warlock.js/notifications/send-ad-hoc/SKILL.md`; adding a brand-new channel — `@warlock.js/notifications/define-channel/SKILL.md`; observing dispatch outcomes — `@warlock.js/notifications/observe-notifications/SKILL.md`.'
+description: 'Build a reusable multi-channel notification with `defineNotification<Data>({ type, via, ...renderers })`. `type` is the stable identifier preference/rate-limit gates use AND defaults the database channel''s `type`. `via` is `ChannelName[]` OR `(data, to) => ChannelName[]` for per-recipient channel selection. Renderers are `(data, to, ctx) => NotificationChannels[C]`; `ctx` carries `locale` + `meta` from `SendOptions`. The returned object exposes `.send(to|to[], data, options?)`, `.queue(to|to[], data, options?)`, and `.only(...channels)`. Per-recipient + per-channel `Promise.allSettled` isolates failures; the database channel''s `type` is auto-defaulted from `def.type`; `SendOptions.idempotencyKey` is injected into the database payload. Triggers: `defineNotification`, `via`, "reusable notification", "multi-channel notification", "send through several channels at once", "render per channel", `RenderContext`, `def.type`; "force on a notification", "queue with delay"; typical import `import { defineNotification } from "@warlock.js/notifications"`. Skip: single-channel ad-hoc sends — the `send-ad-hoc` topic; adding a brand-new channel — the `define-channel` topic; observing dispatch outcomes — the `observe-notifications` topic.'
 ---
 
 # `defineNotification` — reusable multi-channel notification
@@ -388,10 +388,10 @@ Per-recipient: each recipient gets an independent `Promise.allSettled`. Per-chan
 
 ## See also
 
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
-- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — `notify.<channel>` per-channel shorthand.
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — wire channels + preferences + rate-limit + queue.
-- [`observe-notifications/SKILL.md`](../observe-notifications/SKILL.md) — `notifications.on("sending" | "sent" | "failed" | "skipped", …)`.
+- The `notifications-basics` topic — package front door.
+- The `send-ad-hoc` topic — `notify.<channel>` per-channel shorthand.
+- The `configure-notifications` topic — wire channels + preferences + rate-limit + queue.
+- The `observe-notifications` topic — `notifications.on("sending" | "sent" | "failed" | "skipped", …)`.
 
 
 ## notifications-basics  `@warlock.js/notifications/notifications-basics/SKILL.md`
@@ -487,20 +487,20 @@ await inApp.markAsRead(user, "ntf_123");
 
 ## See also
 
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — wire `config/notifications.ts`.
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — reusable multi-channel definitions.
-- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — `notify.<channel>` shorthand.
-- [`use-in-app/SKILL.md`](../use-in-app/SKILL.md) — `inApp` read API.
-- [`define-channel/SKILL.md`](../define-channel/SKILL.md) — custom channels.
-- [`write-notification-migration/SKILL.md`](../write-notification-migration/SKILL.md) — columnMap-driven columns.
-- [`observe-notifications/SKILL.md`](../observe-notifications/SKILL.md) — events + metrics.
+- The `configure-notifications` topic — wire `config/notifications.ts`.
+- The `define-notification` topic — reusable multi-channel definitions.
+- The `send-ad-hoc` topic — `notify.<channel>` shorthand.
+- The `use-in-app` topic — `inApp` read API.
+- The `define-channel` topic — custom channels.
+- The `write-notification-migration` topic — columnMap-driven columns.
+- The `observe-notifications` topic — events + metrics.
 
 
 ## observe-notifications  `@warlock.js/notifications/observe-notifications/SKILL.md`
 
 ---
 name: observe-notifications
-description: 'Wire metrics, logging, tracing, and audits via `notifications.on(event, handler)` — four events fire per (channel, recipient): `sending` (gates passed, about to hit the transport), `sent` (succeeded), `failed` (channel threw — carries the Error), `skipped` (a pre-send gate dropped it — carries `reason: "preference" | "rate-limit"`). Every event carries the recipient as `notifiable?` (undefined only for raw-target ad-hoc sends) and a `dispatchId` — `sending` and its terminal `sent`/`failed` share it, so observers can pair them (spans, latency, hung-send detection). `sent`/`failed` also carry `durationMs`. Handler exceptions are logged-and-swallowed so one bad listener can not break the dispatcher. `on(...)` returns an unsubscribe function; `off(event, handler)` exists for symmetry. Triggers: `notifications.on`, `notifications.off`, `"sending"` event, `"sent"` event, `"failed"` event, `"skipped"` event, `dispatchId`, `durationMs`, `NotificationEvents`, "notification metrics", "notification latency", "trace notifications", "notification audit log", "track notification drops"; typical import `import { notifications } from "@warlock.js/notifications"`. Skip: building notifications — `@warlock.js/notifications/define-notification/SKILL.md`; configuring the preference/rate-limit gates that produce `skipped` — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
+description: 'Wire metrics, logging, tracing, and audits via `notifications.on(event, handler)` — four events fire per (channel, recipient): `sending` (gates passed, about to hit the transport), `sent` (succeeded), `failed` (channel threw — carries the Error), `skipped` (a pre-send gate dropped it — carries `reason: "preference" | "rate-limit"`). Every event carries the recipient as `notifiable?` (undefined only for raw-target ad-hoc sends) and a `dispatchId` — `sending` and its terminal `sent`/`failed` share it, so observers can pair them (spans, latency, hung-send detection). `sent`/`failed` also carry `durationMs`. Handler exceptions are logged-and-swallowed so one bad listener can not break the dispatcher. `on(...)` returns an unsubscribe function; `off(event, handler)` exists for symmetry. Triggers: `notifications.on`, `notifications.off`, `"sending"` event, `"sent"` event, `"failed"` event, `"skipped"` event, `dispatchId`, `durationMs`, `NotificationEvents`, "notification metrics", "notification latency", "trace notifications", "notification audit log", "track notification drops"; typical import `import { notifications } from "@warlock.js/notifications"`. Skip: building notifications — the `define-notification` topic; configuring the preference/rate-limit gates that produce `skipped` — the `configure-notifications` topic.'
 ---
 
 # Observe notifications
@@ -561,16 +561,16 @@ A handler that throws is logged and swallowed — the other handlers for the sam
 
 ## See also
 
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — front door + mental model.
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — `preferences` / `rateLimit` slots that emit `skipped`.
-- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — when `notifiable` is undefined in events.
+- The `notifications-basics` topic — front door + mental model.
+- The `configure-notifications` topic — `preferences` / `rateLimit` slots that emit `skipped`.
+- The `send-ad-hoc` topic — when `notifiable` is undefined in events.
 
 
 ## queue-notifications  `@warlock.js/notifications/queue-notifications/SKILL.md`
 
 ---
 name: queue-notifications
-description: "Send notifications asynchronously through the herald backend or the BullMQ driver. Configure a QueueDispatcher in config/notifications.ts, then use notif.queue(to, data, options?) to enqueue rendered jobs. Herald uses heraldQueue() and startNotificationsWorker(); bullmqQueue({ attempts, backoff }) from @warlock.js/notifications uses BullMQ (lazy-loading the optional @warlock.js/queue peer), supports retries, and honours SendOptions.delay. Without a queue configured, .queue() rejects NoQueueDispatcherError. Triggers: heraldQueue, bullmqQueue, startNotificationsWorker, QueueDispatcher, .queue(, async notifications, queue notifications, notification worker, background notifications, notifications.dispatch. Skip: synchronous sends - @warlock.js/notifications/define-notification/SKILL.md; herald itself - @warlock.js/herald/*."
+description: "Send notifications asynchronously through the herald backend or the BullMQ driver. Configure a QueueDispatcher in config/notifications.ts, then use notif.queue(to, data, options?) to enqueue rendered jobs. Herald uses heraldQueue() and startNotificationsWorker(); bullmqQueue({ attempts, backoff }) from @warlock.js/notifications uses BullMQ (lazy-loading the optional @warlock.js/queue peer), supports retries, and honours SendOptions.delay. Without a queue configured, .queue() rejects NoQueueDispatcherError. Triggers: heraldQueue, bullmqQueue, startNotificationsWorker, QueueDispatcher, .queue(, async notifications, queue notifications, notification worker, background notifications, notifications.dispatch. Skip: synchronous sends - the `define-notification` topic; herald itself - @warlock.js/herald/*."
 ---
 
 # Queue notifications (async)
@@ -675,16 +675,16 @@ await orderShipped.queue(user, { order }, { idempotencyKey: `ship:${order.id}` }
 
 ## See also
 
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) - `.queue()` on a defined notification.
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) - the `queue` config slot.
-- [`@warlock.js/herald/herald-basics/SKILL.md`](../../../herald/skills/herald-basics/SKILL.md) - connecting the broker.
+- The `define-notification` topic - `.queue()` on a defined notification.
+- The `configure-notifications` topic - the `queue` config slot.
+- The `herald-basics` topic of the `warlock-js-herald` skill - connecting the broker.
 
 
 ## send-ad-hoc  `@warlock.js/notifications/send-ad-hoc/SKILL.md`
 
 ---
 name: send-ad-hoc
-description: 'Ad-hoc per-channel send via the `notify.<channel>(to, payload, options?)` Proxy facade. Works for any channel registered in `NotificationChannels` (built-in or custom). `to` accepts a `Notifiable` model OR a raw route string (`"x@y.com"`); `payload` is typed per channel via the registry; `options` is the standard `SendOptions`. `notify.channel(name).send(...)` is the runtime escape when the channel name is not a compile-time literal. Type-based preference gating applies when a type is known — explicit via `options.type` OR auto-detected from a database payload''s `type` field. For multi-channel sends use `defineNotification` instead — there is no inline `notify(to, { via, ... })` form on purpose. Triggers: `notify.<channel>`, `notify.channel(name)`, `notify.mail`, `notify.database`, "send a one-off notification", "ad-hoc notification", "send an email without defining a notification", "raw email target", "dynamic channel name"; typical import `import { notify } from "@warlock.js/notifications"`. Skip: reusable multi-channel notifications — `@warlock.js/notifications/define-notification/SKILL.md`; configuring channels — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
+description: 'Ad-hoc per-channel send via the `notify.<channel>(to, payload, options?)` Proxy facade. Works for any channel registered in `NotificationChannels` (built-in or custom). `to` accepts a `Notifiable` model OR a raw route string (`"x@y.com"`); `payload` is typed per channel via the registry; `options` is the standard `SendOptions`. `notify.channel(name).send(...)` is the runtime escape when the channel name is not a compile-time literal. Type-based preference gating applies when a type is known — explicit via `options.type` OR auto-detected from a database payload''s `type` field. For multi-channel sends use `defineNotification` instead — there is no inline `notify(to, { via, ... })` form on purpose. Triggers: `notify.<channel>`, `notify.channel(name)`, `notify.mail`, `notify.database`, "send a one-off notification", "ad-hoc notification", "send an email without defining a notification", "raw email target", "dynamic channel name"; typical import `import { notify } from "@warlock.js/notifications"`. Skip: reusable multi-channel notifications — the `define-notification` topic; configuring channels — the `configure-notifications` topic.'
 ---
 
 # `notify.<channel>` — ad-hoc, per-channel sends
@@ -698,7 +698,7 @@ await notify.mail(user, { subject: "Welcome", html: "<p>Hi!</p>" });
 await notify.database(user, { type: "welcome", title: "Welcome!" });
 ```
 
-For **multi-channel** sends, use [`defineNotification`](../define-notification/SKILL.md) — that's the reusable pattern and the only mental model for "send through several channels at once" (no inline multi-channel overload).
+For **multi-channel** sends, use `defineNotification` (the `define-notification` topic) — that's the reusable pattern and the only mental model for "send through several channels at once" (no inline multi-channel overload).
 
 ## Shape
 
@@ -730,7 +730,7 @@ const channelName = await chooseChannelForUser(user);
 await notify.channel(channelName).send(user, payload);
 ```
 
-This is the only path with `unknown`-typed payloads — prefer the literal `notify.<channel>` when you can. `to` is still what decides the recipient: even for the `database` channel, a `recipientId`-shaped key on `payload` (or the model's physical recipient column name) is stripped before the row is built, so an untyped payload assembled from request JSON can't redirect the write to another recipient — see [`use-in-app/SKILL.md`](../use-in-app/SKILL.md#createfor-write-side--no-idor-either-since-4150).
+This is the only path with `unknown`-typed payloads — prefer the literal `notify.<channel>` when you can. `to` is still what decides the recipient: even for the `database` channel, a `recipientId`-shaped key on `payload` (or the model's physical recipient column name) is stripped before the row is built, so an untyped payload assembled from request JSON can't redirect the write to another recipient — see the `createFor` write-side section of the `use-in-app` topic.
 
 ## Opt into preference/rate-limit gating
 
@@ -749,7 +749,7 @@ await notify.database(user, { type: "welcome", title: "Welcome!" });
 
 ## Custom channels
 
-After registering a custom channel (see [`define-channel`](../define-channel/SKILL.md)), it's first-class:
+After registering a custom channel (see the `define-channel` topic), it's first-class:
 
 ```ts
 await notify.discord(user, { content: "Build finished 🎉" });
@@ -773,17 +773,17 @@ await notify.slack(staff, { text: "Deploy starting" });
 
 ## See also
 
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — front door + mental model.
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — reusable multi-channel.
-- [`define-channel/SKILL.md`](../define-channel/SKILL.md) — register a custom channel.
-- [`observe-notifications/SKILL.md`](../observe-notifications/SKILL.md) — `sending` / `sent` / `failed` / `skipped` events.
+- The `notifications-basics` topic — front door + mental model.
+- The `define-notification` topic — reusable multi-channel.
+- The `define-channel` topic — register a custom channel.
+- The `observe-notifications` topic — `sending` / `sent` / `failed` / `skipped` events.
 
 
 ## use-in-app  `@warlock.js/notifications/use-in-app/SKILL.md`
 
 ---
 name: use-in-app
-description: 'Use the `inApp` facade for the in-app/database channel''s READ side: `inApp.configure({ model: Notification })` or `{ repository: myRepo }` binds the store AND returns the channel; `inApp.list / listUnread / countUnread / markAsRead / markAsUnread` are RECIPIENT-SCOPED by construction (no IDOR — `markAsRead(user, id)` cannot flip another user''s row even with a foreign id). `countUnread` uses `RepositoryManager.countCached` for the badge fast-path. Triggers: `inApp.configure`, `inApp.list`, `inApp.listUnread`, `inApp.countUnread`, `inApp.markAsRead`, `inApp.markAsUnread`, `BaseNotificationsRepository`, `DatabaseNotification`, `NotificationsFilter`, "in-app notifications", "mark notification as read", "unread count", "notification badge", "IDOR-safe markAsRead"; typical import `import { inApp } from "@warlock.js/notifications"`. Skip: writing notifications (use `defineNotification` or `notify.database`) — `@warlock.js/notifications/define-notification/SKILL.md`; the migration columns — `@warlock.js/notifications/write-notification-migration/SKILL.md`; wiring it into config — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
+description: 'Use the `inApp` facade for the in-app/database channel''s READ side: `inApp.configure({ model: Notification })` or `{ repository: myRepo }` binds the store AND returns the channel; `inApp.list / listUnread / countUnread / markAsRead / markAsUnread` are RECIPIENT-SCOPED by construction (no IDOR — `markAsRead(user, id)` cannot flip another user''s row even with a foreign id). `countUnread` uses `RepositoryManager.countCached` for the badge fast-path. Triggers: `inApp.configure`, `inApp.list`, `inApp.listUnread`, `inApp.countUnread`, `inApp.markAsRead`, `inApp.markAsUnread`, `BaseNotificationsRepository`, `DatabaseNotification`, `NotificationsFilter`, "in-app notifications", "mark notification as read", "unread count", "notification badge", "IDOR-safe markAsRead"; typical import `import { inApp } from "@warlock.js/notifications"`. Skip: writing notifications (use `defineNotification` or `notify.database`) — the `define-notification` topic; the migration columns — the `write-notification-migration` topic; wiring it into config — the `configure-notifications` topic.'
 ---
 
 # `inApp` — in-app notification read API
@@ -949,17 +949,17 @@ database: inApp.configure({ repository: notificationsRepository }),
 
 ## See also
 
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — wire `inApp.configure` into the config.
-- [`write-notification-migration/SKILL.md`](../write-notification-migration/SKILL.md) — `notificationColumns(Notification)`, named from `columnMap`.
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — create rows via the database channel.
+- The `notifications-basics` topic — package front door.
+- The `configure-notifications` topic — wire `inApp.configure` into the config.
+- The `write-notification-migration` topic — `notificationColumns(Notification)`, named from `columnMap`.
+- The `define-notification` topic — create rows via the database channel.
 
 
 ## write-notification-migration  `@warlock.js/notifications/write-notification-migration/SKILL.md`
 
 ---
 name: write-notification-migration
-description: 'Create the notifications table with the `notificationColumns(Notification)` factory + cascade `Migration.create`. Column NAMES come from the model''s `columnMap` (recipient / tenant / readAt / isRead); the fixed columns are `type` / `title` / `body` / `payload` / `idempotency_key`. Set `{ idType: "bigint" }` for integer-key apps; UUID remains the default. Read-state follows columnMap presence: `readAt` → nullable timestamp, `isRead` → indexed boolean, both → both. Defaults to `user_id` + `read_at` when no columnMap. Spread + extend for extras (FK references, composite indexes). Triggers: `notificationColumns`, `Migration.create` for notifications, "create the notifications table", "notification migration", "add organization_id to notifications", `is_read` column, `read_at` column, `idempotency_key` column; typical import `import { Migration } from "@warlock.js/cascade"; import { notificationColumns } from "@warlock.js/notifications"`. Skip: generic cascade migration writing — `@warlock.js/cascade/write-migration/SKILL.md`; the model itself — `@warlock.js/notifications/use-in-app/SKILL.md`.'
+description: 'Create the notifications table with the `notificationColumns(Notification)` factory + cascade `Migration.create`. Column NAMES come from the model''s `columnMap` (recipient / tenant / readAt / isRead); the fixed columns are `type` / `title` / `body` / `payload` / `idempotency_key`. Set `{ idType: "bigint" }` for integer-key apps; UUID remains the default. Read-state follows columnMap presence: `readAt` → nullable timestamp, `isRead` → indexed boolean, both → both. Defaults to `user_id` + `read_at` when no columnMap. Spread + extend for extras (FK references, composite indexes). Triggers: `notificationColumns`, `Migration.create` for notifications, "create the notifications table", "notification migration", "add organization_id to notifications", `is_read` column, `read_at` column, `idempotency_key` column; typical import `import { Migration } from "@warlock.js/cascade"; import { notificationColumns } from "@warlock.js/notifications"`. Skip: generic cascade migration writing — the `write-migration` topic of the `warlock-js-cascade` skill; the model itself — the `use-in-app` topic.'
 ---
 
 # Write the notifications migration
@@ -1017,7 +1017,7 @@ export default Migration.create(Notification, {
 });
 ```
 
-Mirror any extra column in the model `schema`. To make it filterable, add a method to a custom repository (see `use-in-app/SKILL.md`).
+Mirror any extra column in the model `schema`. To make it filterable, add a method to a custom repository (see the `use-in-app` topic).
 
 ## Column naming follows `columnMap`
 
@@ -1030,12 +1030,12 @@ class Notification extends DatabaseNotification {
 // → notificationColumns(Notification) emits `userId` + `readAt`
 ```
 
-Without a model passed, defaults to `user_id` + `read_at` (read_at-only). See [`use-in-app/SKILL.md`](../use-in-app/SKILL.md) for the full `columnMap` shape.
+Without a model passed, defaults to `user_id` + `read_at` (read_at-only). See the `use-in-app` topic for the full `columnMap` shape.
 
 ## See also
 
-- [`use-in-app/SKILL.md`](../use-in-app/SKILL.md) — the model + repository the migration backs.
-- [`@warlock.js/cascade/write-migration/SKILL.md`](../../../cascade/skills/write-migration/SKILL.md) — generic Cascade migration form, `Migration.alter`, etc.
-- [`@warlock.js/cascade/manage-data-sources/SKILL.md`](../../../cascade/skills/manage-data-sources/SKILL.md) — multi-data-source setup.
+- The `use-in-app` topic — the model + repository the migration backs.
+- The `write-migration` topic of the `warlock-js-cascade` skill — generic Cascade migration form, `Migration.alter`, etc.
+- The `manage-data-sources` topic of the `warlock-js-cascade` skill — multi-data-source setup.
 
 

package/llms.txt

@@ -6,12 +6,12 @@
 
 ## Skills
 
-- [configure-notifications](@warlock.js/notifications/configure-notifications/SKILL.md): (no description)
-- [define-channel](@warlock.js/notifications/define-channel/SKILL.md): (no description)
-- [define-notification](@warlock.js/notifications/define-notification/SKILL.md): (no description)
+- [configure-notifications](@warlock.js/notifications/configure-notifications/SKILL.md): Wire `@warlock.js/notifications` via a declarative `src/config/notifications.ts` that exports a `NotificationConfig` default — the notifications connector registers it at boot, so app code never calls `setNotificationConfig`. `channels`: registry mapping name → factory result (`mailChannel`, `inApp.configure`, custom `defineChannel`); `queue`: optional `QueueDispatcher` (`.queue()` throws without it); `preferences`: optional `PreferenceProvider` (drops channels the recipient muted); `rateLimit`: optional `RateLimiter` (drops channels exceeding per-recipient budgets). Triggers: `config/notifications.ts`, `NotificationConfig`, `setNotificationConfig`, `getNotificationConfig`, `mailChannel`, `inApp.configure`, "configure notifications", "wire notifications at boot", "set preferences provider", "set rate limit"; typical import `import { type NotificationConfig, mailChannel, inApp } from "@warlock.js/notifications"`. Skip: building a reusable notification — the `define-notification` topic; the in-app read API — the `use-in-app` topic; adding a custom channel — the `define-channel` topic.
+- [define-channel](@warlock.js/notifications/define-channel/SKILL.md): Add a custom notification channel — `defineChannel<P>({ name, route?, send })` returns a `Channel<P>` you register in the `channels` map of `setNotificationConfig`. `name` matches the key in `NotificationChannels` (extend via `declare module` for typing); `route(notifiable)` resolves the recipient's address (defaults to `{ id }` when omitted); `send({ payload, route, notifiable, options })` does the actual transport. Use for Slack/Discord/internal-webhook/anything else — `fetch`-based with NO SDK is the simplest variant. Channels that load a heavy SDK should follow the lazy-import pattern from the develop-feature playbook. Triggers: `defineChannel`, `Channel<P>`, "custom notification channel", "add discord channel", "slack channel", "webhook channel", "new channel type", `declare module "@warlock.js/notifications"`; typical import `import { defineChannel } from "@warlock.js/notifications"`. Skip: lazy-loading an optional SDK behind the channel — the `develop-warlock.js-feature` workspace skill; using built-in channels — the `configure-notifications` topic.
+- [define-notification](@warlock.js/notifications/define-notification/SKILL.md): Build a reusable multi-channel notification with `defineNotification<Data>({ type, via, ...renderers })`. `type` is the stable identifier preference/rate-limit gates use AND defaults the database channel's `type`. `via` is `ChannelName[]` OR `(data, to) => ChannelName[]` for per-recipient channel selection. Renderers are `(data, to, ctx) => NotificationChannels[C]`; `ctx` carries `locale` + `meta` from `SendOptions`. The returned object exposes `.send(to|to[], data, options?)`, `.queue(to|to[], data, options?)`, and `.only(...channels)`. Per-recipient + per-channel `Promise.allSettled` isolates failures; the database channel's `type` is auto-defaulted from `def.type`; `SendOptions.idempotencyKey` is injected into the database payload. Triggers: `defineNotification`, `via`, "reusable notification", "multi-channel notification", "send through several channels at once", "render per channel", `RenderContext`, `def.type`; "force on a notification", "queue with delay"; typical import `import { defineNotification } from "@warlock.js/notifications"`. Skip: single-channel ad-hoc sends — the `send-ad-hoc` topic; adding a brand-new channel — the `define-channel` topic; observing dispatch outcomes — the `observe-notifications` topic.
 - [notifications-basics](@warlock.js/notifications/notifications-basics/SKILL.md): Start here for @warlock.js/notifications channels, notification definitions, delivery, and application setup.
-- [observe-notifications](@warlock.js/notifications/observe-notifications/SKILL.md): (no description)
-- [queue-notifications](@warlock.js/notifications/queue-notifications/SKILL.md): (no description)
-- [send-ad-hoc](@warlock.js/notifications/send-ad-hoc/SKILL.md): (no description)
-- [use-in-app](@warlock.js/notifications/use-in-app/SKILL.md): (no description)
-- [write-notification-migration](@warlock.js/notifications/write-notification-migration/SKILL.md): (no description)
+- [observe-notifications](@warlock.js/notifications/observe-notifications/SKILL.md): Wire metrics, logging, tracing, and audits via `notifications.on(event, handler)` — four events fire per (channel, recipient): `sending` (gates passed, about to hit the transport), `sent` (succeeded), `failed` (channel threw — carries the Error), `skipped` (a pre-send gate dropped it — carries `reason: "preference" | "rate-limit"`). Every event carries the recipient as `notifiable?` (undefined only for raw-target ad-hoc sends) and a `dispatchId` — `sending` and its terminal `sent`/`failed` share it, so observers can pair them (spans, latency, hung-send detection). `sent`/`failed` also carry `durationMs`. Handler exceptions are logged-and-swallowed so one bad listener can not break the dispatcher. `on(...)` returns an unsubscribe function; `off(event, handler)` exists for symmetry. Triggers: `notifications.on`, `notifications.off`, `"sending"` event, `"sent"` event, `"failed"` event, `"skipped"` event, `dispatchId`, `durationMs`, `NotificationEvents`, "notification metrics", "notification latency", "trace notifications", "notification audit log", "track notification drops"; typical import `import { notifications } from "@warlock.js/notifications"`. Skip: building notifications — the `define-notification` topic; configuring the preference/rate-limit gates that produce `skipped` — the `configure-notifications` topic.
+- [queue-notifications](@warlock.js/notifications/queue-notifications/SKILL.md): Send notifications asynchronously through the herald backend or the BullMQ driver. Configure a QueueDispatcher in config/notifications.ts, then use notif.queue(to, data, options?) to enqueue rendered jobs. Herald uses heraldQueue() and startNotificationsWorker(); bullmqQueue({ attempts, backoff }) from @warlock.js/notifications uses BullMQ (lazy-loading the optional @warlock.js/queue peer), supports retries, and honours SendOptions.delay. Without a queue configured, .queue() rejects NoQueueDispatcherError. Triggers: heraldQueue, bullmqQueue, startNotificationsWorker, QueueDispatcher, .queue(, async notifications, queue notifications, notification worker, background notifications, notifications.dispatch. Skip: synchronous sends - the `define-notification` topic; herald itself - @warlock.js/herald/*.
+- [send-ad-hoc](@warlock.js/notifications/send-ad-hoc/SKILL.md): Ad-hoc per-channel send via the `notify.<channel>(to, payload, options?)` Proxy facade. Works for any channel registered in `NotificationChannels` (built-in or custom). `to` accepts a `Notifiable` model OR a raw route string (`"x@y.com"`); `payload` is typed per channel via the registry; `options` is the standard `SendOptions`. `notify.channel(name).send(...)` is the runtime escape when the channel name is not a compile-time literal. Type-based preference gating applies when a type is known — explicit via `options.type` OR auto-detected from a database payload's `type` field. For multi-channel sends use `defineNotification` instead — there is no inline `notify(to, { via, ... })` form on purpose. Triggers: `notify.<channel>`, `notify.channel(name)`, `notify.mail`, `notify.database`, "send a one-off notification", "ad-hoc notification", "send an email without defining a notification", "raw email target", "dynamic channel name"; typical import `import { notify } from "@warlock.js/notifications"`. Skip: reusable multi-channel notifications — the `define-notification` topic; configuring channels — the `configure-notifications` topic.
+- [use-in-app](@warlock.js/notifications/use-in-app/SKILL.md): Use the `inApp` facade for the in-app/database channel's READ side: `inApp.configure({ model: Notification })` or `{ repository: myRepo }` binds the store AND returns the channel; `inApp.list / listUnread / countUnread / markAsRead / markAsUnread` are RECIPIENT-SCOPED by construction (no IDOR — `markAsRead(user, id)` cannot flip another user's row even with a foreign id). `countUnread` uses `RepositoryManager.countCached` for the badge fast-path. Triggers: `inApp.configure`, `inApp.list`, `inApp.listUnread`, `inApp.countUnread`, `inApp.markAsRead`, `inApp.markAsUnread`, `BaseNotificationsRepository`, `DatabaseNotification`, `NotificationsFilter`, "in-app notifications", "mark notification as read", "unread count", "notification badge", "IDOR-safe markAsRead"; typical import `import { inApp } from "@warlock.js/notifications"`. Skip: writing notifications (use `defineNotification` or `notify.database`) — the `define-notification` topic; the migration columns — the `write-notification-migration` topic; wiring it into config — the `configure-notifications` topic.
+- [write-notification-migration](@warlock.js/notifications/write-notification-migration/SKILL.md): Create the notifications table with the `notificationColumns(Notification)` factory + cascade `Migration.create`. Column NAMES come from the model's `columnMap` (recipient / tenant / readAt / isRead); the fixed columns are `type` / `title` / `body` / `payload` / `idempotency_key`. Set `{ idType: "bigint" }` for integer-key apps; UUID remains the default. Read-state follows columnMap presence: `readAt` → nullable timestamp, `isRead` → indexed boolean, both → both. Defaults to `user_id` + `read_at` when no columnMap. Spread + extend for extras (FK references, composite indexes). Triggers: `notificationColumns`, `Migration.create` for notifications, "create the notifications table", "notification migration", "add organization_id to notifications", `is_read` column, `read_at` column, `idempotency_key` column; typical import `import { Migration } from "@warlock.js/cascade"; import { notificationColumns } from "@warlock.js/notifications"`. Skip: generic cascade migration writing — the `write-migration` topic of the `warlock-js-cascade` skill; the model itself — the `use-in-app` topic.

package/package.json

@@ -5,16 +5,16 @@
     "environment": "server"
   },
   "dependencies": {
-    "@warlock.js/cache": "5.27.0",
-    "@warlock.js/cascade": "5.27.0",
-    "@warlock.js/core": "5.27.0",
-    "@warlock.js/logger": "5.27.0"
+    "@warlock.js/cache": "5.29.0",
+    "@warlock.js/cascade": "5.29.0",
+    "@warlock.js/core": "5.29.0",
+    "@warlock.js/logger": "5.29.0"
   },
   "optionalDependencies": {
-    "@warlock.js/herald": "5.27.0"
+    "@warlock.js/herald": "5.29.0"
   },
   "peerDependencies": {
-    "@warlock.js/queue": "5.27.0"
+    "@warlock.js/queue": "5.29.0"
   },
   "peerDependenciesMeta": {
     "@warlock.js/queue": {
@@ -35,7 +35,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.27.0",
+  "version": "5.29.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/configure-notifications/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: configure-notifications
-description: 'Wire `@warlock.js/notifications` via a declarative `src/config/notifications.ts` that exports a `NotificationConfig` default — the notifications connector registers it at boot, so app code never calls `setNotificationConfig`. `channels`: registry mapping name → factory result (`mailChannel`, `inApp.configure`, custom `defineChannel`); `queue`: optional `QueueDispatcher` (`.queue()` throws without it); `preferences`: optional `PreferenceProvider` (drops channels the recipient muted); `rateLimit`: optional `RateLimiter` (drops channels exceeding per-recipient budgets). Triggers: `config/notifications.ts`, `NotificationConfig`, `setNotificationConfig`, `getNotificationConfig`, `mailChannel`, `inApp.configure`, "configure notifications", "wire notifications at boot", "set preferences provider", "set rate limit"; typical import `import { type NotificationConfig, mailChannel, inApp } from "@warlock.js/notifications"`. Skip: building a reusable notification — `@warlock.js/notifications/define-notification/SKILL.md`; the in-app read API — `@warlock.js/notifications/use-in-app/SKILL.md`; adding a custom channel — `@warlock.js/notifications/define-channel/SKILL.md`.'
+description: 'Wire `@warlock.js/notifications` via a declarative `src/config/notifications.ts` that exports a `NotificationConfig` default — the notifications connector registers it at boot, so app code never calls `setNotificationConfig`. `channels`: registry mapping name → factory result (`mailChannel`, `inApp.configure`, custom `defineChannel`); `queue`: optional `QueueDispatcher` (`.queue()` throws without it); `preferences`: optional `PreferenceProvider` (drops channels the recipient muted); `rateLimit`: optional `RateLimiter` (drops channels exceeding per-recipient budgets). Triggers: `config/notifications.ts`, `NotificationConfig`, `setNotificationConfig`, `getNotificationConfig`, `mailChannel`, `inApp.configure`, "configure notifications", "wire notifications at boot", "set preferences provider", "set rate limit"; typical import `import { type NotificationConfig, mailChannel, inApp } from "@warlock.js/notifications"`. Skip: building a reusable notification — the `define-notification` topic; the in-app read API — the `use-in-app` topic; adding a custom channel — the `define-channel` topic.'
 ---
 
 # Configure notifications
@@ -132,7 +132,7 @@ afterEach(() => resetNotificationConfig());
 
 ## See also
 
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — reusable multi-channel definitions.
-- [`use-in-app/SKILL.md`](../use-in-app/SKILL.md) — in-app read API.
-- [`define-channel/SKILL.md`](../define-channel/SKILL.md) — custom channels.
+- The `notifications-basics` topic — package front door.
+- The `define-notification` topic — reusable multi-channel definitions.
+- The `use-in-app` topic — in-app read API.
+- The `define-channel` topic — custom channels.