@usebetterdev/plugin 0.5.0 → 0.7.0

package/dist/config-loader.d.ts

@@ -0,0 +1,23 @@
+import type { BetterConfig } from "./config-types.js";
+/** Thrown when no `better.config.*` file is found in the working directory. */
+export declare class BetterConfigNotFoundError extends Error {
+    readonly name = "BetterConfigNotFoundError";
+    readonly cwd: string;
+    constructor(cwd: string);
+}
+export interface LoadBetterConfigOptions {
+    /** Working directory to search for the config file. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Explicit path to a config file, bypassing discovery. Maps to c12's `configFile` option. */
+    configPath?: string;
+}
+/**
+ * Loads a `better.config.{ts,js,mjs}` file using c12.
+ * Throws {@link BetterConfigNotFoundError} when no config file is found.
+ *
+ * The returned config is **unvalidated**. Pass it through
+ * {@link requireTenantConfig} or {@link requireAuditConfig} to validate
+ * product-specific sections.
+ */
+export declare function loadBetterConfig(options?: LoadBetterConfigOptions): Promise<BetterConfig>;
+//# sourceMappingURL=config-loader.d.ts.map

package/dist/config-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../src/config-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,+EAA+E;AAC/E,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,SAAkB,IAAI,+BAA+B;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,GAAG,EAAE,MAAM;CAgBxB;AAED,MAAM,WAAW,uBAAuB;IACtC,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,YAAY,CAAC,CAsBvB"}

package/dist/config-types.d.ts

@@ -0,0 +1,2 @@
+export type { TelemetryConfig, PathResolverConfig, SubdomainResolverConfig, StaticJwtResolverConfig, StaticTenantResolverConfig, BetterTenantStaticConfig, RetentionPolicy, BetterAuditStaticConfig, StaticMagicLinkConfig, StaticConsoleSessionConfig, BetterConsoleStaticConfig, BetterConfig, } from "@usebetterdev/contract/config-types";
+//# sourceMappingURL=config-types.d.ts.map

package/dist/config-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-types.d.ts","sourceRoot":"","sources":["../src/config-types.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,YAAY,GACb,MAAM,qCAAqC,CAAC"}

package/dist/config-validation.d.ts

@@ -0,0 +1,19 @@
+import type { BetterConfig, BetterTenantStaticConfig, BetterAuditStaticConfig } from "./config-types.js";
+/** Thrown when a config section fails validation. */
+export declare class ConfigValidationError extends Error {
+    readonly name = "ConfigValidationError";
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/**
+ * Validates that `config.tenant` exists and its `tenantTables` is a non-empty
+ * array of non-empty strings. Returns the narrowed tenant config.
+ */
+export declare function requireTenantConfig(config: BetterConfig): BetterTenantStaticConfig;
+/**
+ * Validates that `config.audit` exists and its `auditTables` is a non-empty
+ * array of non-empty strings. When `retention` is present, validates `days` is
+ * a positive integer and `tables` (if present) is a non-empty string array.
+ */
+export declare function requireAuditConfig(config: BetterConfig): BetterAuditStaticConfig;
+//# sourceMappingURL=config-validation.d.ts.map

package/dist/config-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-validation.d.ts","sourceRoot":"","sources":["../src/config-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,qDAAqD;AACrD,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAkB,IAAI,2BAA2B;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI3C;AA4BD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,GACnB,wBAAwB,CAM1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,GACnB,uBAAuB,CAoBzB"}

package/dist/config.cjs

@@ -0,0 +1,142 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/config.ts
+var config_exports = {};
+__export(config_exports, {
+  BetterConfigNotFoundError: () => BetterConfigNotFoundError,
+  ConfigValidationError: () => ConfigValidationError,
+  defineBetterConfig: () => defineBetterConfig,
+  loadBetterConfig: () => loadBetterConfig,
+  requireAuditConfig: () => requireAuditConfig,
+  requireTenantConfig: () => requireTenantConfig
+});
+module.exports = __toCommonJS(config_exports);
+
+// src/define-config.ts
+function defineBetterConfig(config) {
+  return config;
+}
+
+// src/config-loader.ts
+var import_c12 = require("c12");
+var BetterConfigNotFoundError = class extends Error {
+  name = "BetterConfigNotFoundError";
+  cwd;
+  constructor(cwd) {
+    super(
+      [
+        `No better.config.{ts,js,mjs} file found in ${cwd}.`,
+        "",
+        "Create one with:",
+        "",
+        '  import { defineBetterConfig } from "@usebetterdev/plugin/config";',
+        "",
+        "  export default defineBetterConfig({",
+        '    tenant: { tenantTables: ["organizations"] },',
+        "  });"
+      ].join("\n")
+    );
+    this.cwd = cwd;
+  }
+};
+async function loadBetterConfig(options) {
+  const cwd = options?.cwd ?? process.cwd();
+  const configFile = options?.configPath;
+  const result = await (0, import_c12.loadConfig)({
+    name: "better",
+    cwd,
+    ...configFile !== void 0 ? { configFile } : {},
+    rcFile: false,
+    globalRc: false,
+    packageJson: false,
+    dotenv: false
+  });
+  const layers = result.layers ?? [];
+  if (layers.length === 0) {
+    throw new BetterConfigNotFoundError(cwd);
+  }
+  return result.config ?? {};
+}
+
+// src/config-validation.ts
+var ConfigValidationError = class extends Error {
+  name = "ConfigValidationError";
+  field;
+  constructor(field, message) {
+    super(`Config error: "${field}" ${message}`);
+    this.field = field;
+  }
+};
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function validateStringArray(items, fieldName, sectionName) {
+  const qualifiedName = `${sectionName}.${fieldName}`;
+  if (!Array.isArray(items)) {
+    throw new ConfigValidationError(qualifiedName, "must be an array");
+  }
+  if (items.length === 0) {
+    throw new ConfigValidationError(qualifiedName, "must not be empty");
+  }
+  for (const item of items) {
+    if (!isNonEmptyString(item)) {
+      throw new ConfigValidationError(
+        qualifiedName,
+        "entries must be non-empty strings"
+      );
+    }
+  }
+}
+function requireTenantConfig(config) {
+  if (config.tenant === void 0) {
+    throw new ConfigValidationError("tenant", "section is required");
+  }
+  validateStringArray(config.tenant.tenantTables, "tenantTables", "tenant");
+  return config.tenant;
+}
+function requireAuditConfig(config) {
+  if (config.audit === void 0) {
+    throw new ConfigValidationError("audit", "section is required");
+  }
+  validateStringArray(config.audit.auditTables, "auditTables", "audit");
+  if (config.audit.retention !== void 0) {
+    const { days, tables } = config.audit.retention;
+    if (!Number.isInteger(days) || days <= 0) {
+      throw new ConfigValidationError(
+        "audit.retention.days",
+        "must be a positive integer"
+      );
+    }
+    if (tables !== void 0) {
+      validateStringArray(tables, "retention.tables", "audit");
+    }
+  }
+  return config.audit;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BetterConfigNotFoundError,
+  ConfigValidationError,
+  defineBetterConfig,
+  loadBetterConfig,
+  requireAuditConfig,
+  requireTenantConfig
+});
+//# sourceMappingURL=config.cjs.map

package/dist/config.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts","../src/define-config.ts","../src/config-loader.ts","../src/config-validation.ts"],"sourcesContent":["// ── Config helpers ───────────────────────────────────────────────────────────\n\nexport { defineBetterConfig } from \"./define-config.js\";\n\nexport {\n  loadBetterConfig,\n  BetterConfigNotFoundError,\n} from \"./config-loader.js\";\nexport type { LoadBetterConfigOptions } from \"./config-loader.js\";\n\nexport {\n  requireTenantConfig,\n  requireAuditConfig,\n  ConfigValidationError,\n} from \"./config-validation.js\";\n\n// ── Re-export config types ──────────────────────────────────────────────────\n\nexport type {\n  BetterConfig,\n  BetterTenantStaticConfig,\n  BetterAuditStaticConfig,\n  BetterConsoleStaticConfig,\n  TelemetryConfig,\n  PathResolverConfig,\n  SubdomainResolverConfig,\n  StaticJwtResolverConfig,\n  StaticTenantResolverConfig,\n  RetentionPolicy,\n  StaticMagicLinkConfig,\n  StaticConsoleSessionConfig,\n} from \"./config-types.js\";\n","import type { BetterConfig } from \"./config-types.js\";\n\n/**\n * Identity helper that provides TypeScript autocomplete for `better.config.ts`.\n *\n * ```ts\n * // better.config.ts\n * import { defineBetterConfig } from \"@usebetterdev/plugin/config\";\n *\n * export default defineBetterConfig({\n *   tenant: { tenantTables: [\"organizations\"] },\n * });\n * ```\n */\nexport function defineBetterConfig(config: BetterConfig): BetterConfig {\n  return config;\n}\n","import { loadConfig } from \"c12\";\nimport type { BetterConfig } from \"./config-types.js\";\n\n/** Thrown when no `better.config.*` file is found in the working directory. */\nexport class BetterConfigNotFoundError extends Error {\n  override readonly name = \"BetterConfigNotFoundError\";\n  readonly cwd: string;\n\n  constructor(cwd: string) {\n    super(\n      [\n        `No better.config.{ts,js,mjs} file found in ${cwd}.`,\n        \"\",\n        \"Create one with:\",\n        \"\",\n        '  import { defineBetterConfig } from \"@usebetterdev/plugin/config\";',\n        \"\",\n        \"  export default defineBetterConfig({\",\n        '    tenant: { tenantTables: [\"organizations\"] },',\n        \"  });\",\n      ].join(\"\\n\"),\n    );\n    this.cwd = cwd;\n  }\n}\n\nexport interface LoadBetterConfigOptions {\n  /** Working directory to search for the config file. Defaults to `process.cwd()`. */\n  cwd?: string;\n  /** Explicit path to a config file, bypassing discovery. Maps to c12's `configFile` option. */\n  configPath?: string;\n}\n\n/**\n * Loads a `better.config.{ts,js,mjs}` file using c12.\n * Throws {@link BetterConfigNotFoundError} when no config file is found.\n *\n * The returned config is **unvalidated**. Pass it through\n * {@link requireTenantConfig} or {@link requireAuditConfig} to validate\n * product-specific sections.\n */\nexport async function loadBetterConfig(\n  options?: LoadBetterConfigOptions,\n): Promise<BetterConfig> {\n  const cwd = options?.cwd ?? process.cwd();\n\n  // configPath maps to c12's configFile — spread conditionally to satisfy exactOptionalPropertyTypes\n  const configFile = options?.configPath;\n\n  const result = await loadConfig<BetterConfig>({\n    name: \"better\",\n    cwd,\n    ...(configFile !== undefined ? { configFile } : {}),\n    rcFile: false,\n    globalRc: false,\n    packageJson: false,\n    dotenv: false,\n  });\n\n  const layers = result.layers ?? [];\n  if (layers.length === 0) {\n    throw new BetterConfigNotFoundError(cwd);\n  }\n\n  return result.config ?? {};\n}\n","import type {\n  BetterConfig,\n  BetterTenantStaticConfig,\n  BetterAuditStaticConfig,\n} from \"./config-types.js\";\n\n/** Thrown when a config section fails validation. */\nexport class ConfigValidationError extends Error {\n  override readonly name = \"ConfigValidationError\";\n  readonly field: string;\n\n  constructor(field: string, message: string) {\n    super(`Config error: \"${field}\" ${message}`);\n    this.field = field;\n  }\n}\n\nfunction isNonEmptyString(value: unknown): value is string {\n  return typeof value === \"string\" && value.length > 0;\n}\n\nfunction validateStringArray(\n  items: unknown,\n  fieldName: string,\n  sectionName: string,\n): void {\n  const qualifiedName = `${sectionName}.${fieldName}`;\n  if (!Array.isArray(items)) {\n    throw new ConfigValidationError(qualifiedName, \"must be an array\");\n  }\n  if (items.length === 0) {\n    throw new ConfigValidationError(qualifiedName, \"must not be empty\");\n  }\n  for (const item of items) {\n    if (!isNonEmptyString(item)) {\n      throw new ConfigValidationError(\n        qualifiedName,\n        \"entries must be non-empty strings\",\n      );\n    }\n  }\n}\n\n/**\n * Validates that `config.tenant` exists and its `tenantTables` is a non-empty\n * array of non-empty strings. Returns the narrowed tenant config.\n */\nexport function requireTenantConfig(\n  config: BetterConfig,\n): BetterTenantStaticConfig {\n  if (config.tenant === undefined) {\n    throw new ConfigValidationError(\"tenant\", \"section is required\");\n  }\n  validateStringArray(config.tenant.tenantTables, \"tenantTables\", \"tenant\");\n  return config.tenant;\n}\n\n/**\n * Validates that `config.audit` exists and its `auditTables` is a non-empty\n * array of non-empty strings. When `retention` is present, validates `days` is\n * a positive integer and `tables` (if present) is a non-empty string array.\n */\nexport function requireAuditConfig(\n  config: BetterConfig,\n): BetterAuditStaticConfig {\n  if (config.audit === undefined) {\n    throw new ConfigValidationError(\"audit\", \"section is required\");\n  }\n  validateStringArray(config.audit.auditTables, \"auditTables\", \"audit\");\n\n  if (config.audit.retention !== undefined) {\n    const { days, tables } = config.audit.retention;\n    if (!Number.isInteger(days) || days <= 0) {\n      throw new ConfigValidationError(\n        \"audit.retention.days\",\n        \"must be a positive integer\",\n      );\n    }\n    if (tables !== undefined) {\n      validateStringArray(tables, \"retention.tables\", \"audit\");\n    }\n  }\n\n  return config.audit;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACcO,SAAS,mBAAmB,QAAoC;AACrE,SAAO;AACT;;;AChBA,iBAA2B;AAIpB,IAAM,4BAAN,cAAwC,MAAM;AAAA,EACjC,OAAO;AAAA,EAChB;AAAA,EAET,YAAY,KAAa;AACvB;AAAA,MACE;AAAA,QACE,8CAA8C,GAAG;AAAA,QACjD;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,EAAE,KAAK,IAAI;AAAA,IACb;AACA,SAAK,MAAM;AAAA,EACb;AACF;AAiBA,eAAsB,iBACpB,SACuB;AACvB,QAAM,MAAM,SAAS,OAAO,QAAQ,IAAI;AAGxC,QAAM,aAAa,SAAS;AAE5B,QAAM,SAAS,UAAM,uBAAyB;AAAA,IAC5C,MAAM;AAAA,IACN;AAAA,IACA,GAAI,eAAe,SAAY,EAAE,WAAW,IAAI,CAAC;AAAA,IACjD,QAAQ;AAAA,IACR,UAAU;AAAA,IACV,aAAa;AAAA,IACb,QAAQ;AAAA,EACV,CAAC;AAED,QAAM,SAAS,OAAO,UAAU,CAAC;AACjC,MAAI,OAAO,WAAW,GAAG;AACvB,UAAM,IAAI,0BAA0B,GAAG;AAAA,EACzC;AAEA,SAAO,OAAO,UAAU,CAAC;AAC3B;;;AC1DO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAC7B,OAAO;AAAA,EAChB;AAAA,EAET,YAAY,OAAe,SAAiB;AAC1C,UAAM,kBAAkB,KAAK,KAAK,OAAO,EAAE;AAC3C,SAAK,QAAQ;AAAA,EACf;AACF;AAEA,SAAS,iBAAiB,OAAiC;AACzD,SAAO,OAAO,UAAU,YAAY,MAAM,SAAS;AACrD;AAEA,SAAS,oBACP,OACA,WACA,aACM;AACN,QAAM,gBAAgB,GAAG,WAAW,IAAI,SAAS;AACjD,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI,sBAAsB,eAAe,kBAAkB;AAAA,EACnE;AACA,MAAI,MAAM,WAAW,GAAG;AACtB,UAAM,IAAI,sBAAsB,eAAe,mBAAmB;AAAA,EACpE;AACA,aAAW,QAAQ,OAAO;AACxB,QAAI,CAAC,iBAAiB,IAAI,GAAG;AAC3B,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAMO,SAAS,oBACd,QAC0B;AAC1B,MAAI,OAAO,WAAW,QAAW;AAC/B,UAAM,IAAI,sBAAsB,UAAU,qBAAqB;AAAA,EACjE;AACA,sBAAoB,OAAO,OAAO,cAAc,gBAAgB,QAAQ;AACxE,SAAO,OAAO;AAChB;AAOO,SAAS,mBACd,QACyB;AACzB,MAAI,OAAO,UAAU,QAAW;AAC9B,UAAM,IAAI,sBAAsB,SAAS,qBAAqB;AAAA,EAChE;AACA,sBAAoB,OAAO,MAAM,aAAa,eAAe,OAAO;AAEpE,MAAI,OAAO,MAAM,cAAc,QAAW;AACxC,UAAM,EAAE,MAAM,OAAO,IAAI,OAAO,MAAM;AACtC,QAAI,CAAC,OAAO,UAAU,IAAI,KAAK,QAAQ,GAAG;AACxC,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,MACF;AAAA,IACF;AACA,QAAI,WAAW,QAAW;AACxB,0BAAoB,QAAQ,oBAAoB,OAAO;AAAA,IACzD;AAAA,EACF;AAEA,SAAO,OAAO;AAChB;","names":[]}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export { defineBetterConfig } from "./define-config.js";
+export { loadBetterConfig, BetterConfigNotFoundError, } from "./config-loader.js";
+export type { LoadBetterConfigOptions } from "./config-loader.js";
+export { requireTenantConfig, requireAuditConfig, ConfigValidationError, } from "./config-validation.js";
+export type { BetterConfig, BetterTenantStaticConfig, BetterAuditStaticConfig, BetterConsoleStaticConfig, TelemetryConfig, PathResolverConfig, SubdomainResolverConfig, StaticJwtResolverConfig, StaticTenantResolverConfig, RetentionPolicy, StaticMagicLinkConfig, StaticConsoleSessionConfig, } from "./config-types.js";
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EACL,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAElE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAIhC,YAAY,EACV,YAAY,EACZ,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EACzB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,eAAe,EACf,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC"}

package/dist/config.js

@@ -0,0 +1,110 @@
+// src/define-config.ts
+function defineBetterConfig(config) {
+  return config;
+}
+
+// src/config-loader.ts
+import { loadConfig } from "c12";
+var BetterConfigNotFoundError = class extends Error {
+  name = "BetterConfigNotFoundError";
+  cwd;
+  constructor(cwd) {
+    super(
+      [
+        `No better.config.{ts,js,mjs} file found in ${cwd}.`,
+        "",
+        "Create one with:",
+        "",
+        '  import { defineBetterConfig } from "@usebetterdev/plugin/config";',
+        "",
+        "  export default defineBetterConfig({",
+        '    tenant: { tenantTables: ["organizations"] },',
+        "  });"
+      ].join("\n")
+    );
+    this.cwd = cwd;
+  }
+};
+async function loadBetterConfig(options) {
+  const cwd = options?.cwd ?? process.cwd();
+  const configFile = options?.configPath;
+  const result = await loadConfig({
+    name: "better",
+    cwd,
+    ...configFile !== void 0 ? { configFile } : {},
+    rcFile: false,
+    globalRc: false,
+    packageJson: false,
+    dotenv: false
+  });
+  const layers = result.layers ?? [];
+  if (layers.length === 0) {
+    throw new BetterConfigNotFoundError(cwd);
+  }
+  return result.config ?? {};
+}
+
+// src/config-validation.ts
+var ConfigValidationError = class extends Error {
+  name = "ConfigValidationError";
+  field;
+  constructor(field, message) {
+    super(`Config error: "${field}" ${message}`);
+    this.field = field;
+  }
+};
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function validateStringArray(items, fieldName, sectionName) {
+  const qualifiedName = `${sectionName}.${fieldName}`;
+  if (!Array.isArray(items)) {
+    throw new ConfigValidationError(qualifiedName, "must be an array");
+  }
+  if (items.length === 0) {
+    throw new ConfigValidationError(qualifiedName, "must not be empty");
+  }
+  for (const item of items) {
+    if (!isNonEmptyString(item)) {
+      throw new ConfigValidationError(
+        qualifiedName,
+        "entries must be non-empty strings"
+      );
+    }
+  }
+}
+function requireTenantConfig(config) {
+  if (config.tenant === void 0) {
+    throw new ConfigValidationError("tenant", "section is required");
+  }
+  validateStringArray(config.tenant.tenantTables, "tenantTables", "tenant");
+  return config.tenant;
+}
+function requireAuditConfig(config) {
+  if (config.audit === void 0) {
+    throw new ConfigValidationError("audit", "section is required");
+  }
+  validateStringArray(config.audit.auditTables, "auditTables", "audit");
+  if (config.audit.retention !== void 0) {
+    const { days, tables } = config.audit.retention;
+    if (!Number.isInteger(days) || days <= 0) {
+      throw new ConfigValidationError(
+        "audit.retention.days",
+        "must be a positive integer"
+      );
+    }
+    if (tables !== void 0) {
+      validateStringArray(tables, "retention.tables", "audit");
+    }
+  }
+  return config.audit;
+}
+export {
+  BetterConfigNotFoundError,
+  ConfigValidationError,
+  defineBetterConfig,
+  loadBetterConfig,
+  requireAuditConfig,
+  requireTenantConfig
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/define-config.ts","../src/config-loader.ts","../src/config-validation.ts"],"sourcesContent":["import type { BetterConfig } from \"./config-types.js\";\n\n/**\n * Identity helper that provides TypeScript autocomplete for `better.config.ts`.\n *\n * ```ts\n * // better.config.ts\n * import { defineBetterConfig } from \"@usebetterdev/plugin/config\";\n *\n * export default defineBetterConfig({\n *   tenant: { tenantTables: [\"organizations\"] },\n * });\n * ```\n */\nexport function defineBetterConfig(config: BetterConfig): BetterConfig {\n  return config;\n}\n","import { loadConfig } from \"c12\";\nimport type { BetterConfig } from \"./config-types.js\";\n\n/** Thrown when no `better.config.*` file is found in the working directory. */\nexport class BetterConfigNotFoundError extends Error {\n  override readonly name = \"BetterConfigNotFoundError\";\n  readonly cwd: string;\n\n  constructor(cwd: string) {\n    super(\n      [\n        `No better.config.{ts,js,mjs} file found in ${cwd}.`,\n        \"\",\n        \"Create one with:\",\n        \"\",\n        '  import { defineBetterConfig } from \"@usebetterdev/plugin/config\";',\n        \"\",\n        \"  export default defineBetterConfig({\",\n        '    tenant: { tenantTables: [\"organizations\"] },',\n        \"  });\",\n      ].join(\"\\n\"),\n    );\n    this.cwd = cwd;\n  }\n}\n\nexport interface LoadBetterConfigOptions {\n  /** Working directory to search for the config file. Defaults to `process.cwd()`. */\n  cwd?: string;\n  /** Explicit path to a config file, bypassing discovery. Maps to c12's `configFile` option. */\n  configPath?: string;\n}\n\n/**\n * Loads a `better.config.{ts,js,mjs}` file using c12.\n * Throws {@link BetterConfigNotFoundError} when no config file is found.\n *\n * The returned config is **unvalidated**. Pass it through\n * {@link requireTenantConfig} or {@link requireAuditConfig} to validate\n * product-specific sections.\n */\nexport async function loadBetterConfig(\n  options?: LoadBetterConfigOptions,\n): Promise<BetterConfig> {\n  const cwd = options?.cwd ?? process.cwd();\n\n  // configPath maps to c12's configFile — spread conditionally to satisfy exactOptionalPropertyTypes\n  const configFile = options?.configPath;\n\n  const result = await loadConfig<BetterConfig>({\n    name: \"better\",\n    cwd,\n    ...(configFile !== undefined ? { configFile } : {}),\n    rcFile: false,\n    globalRc: false,\n    packageJson: false,\n    dotenv: false,\n  });\n\n  const layers = result.layers ?? [];\n  if (layers.length === 0) {\n    throw new BetterConfigNotFoundError(cwd);\n  }\n\n  return result.config ?? {};\n}\n","import type {\n  BetterConfig,\n  BetterTenantStaticConfig,\n  BetterAuditStaticConfig,\n} from \"./config-types.js\";\n\n/** Thrown when a config section fails validation. */\nexport class ConfigValidationError extends Error {\n  override readonly name = \"ConfigValidationError\";\n  readonly field: string;\n\n  constructor(field: string, message: string) {\n    super(`Config error: \"${field}\" ${message}`);\n    this.field = field;\n  }\n}\n\nfunction isNonEmptyString(value: unknown): value is string {\n  return typeof value === \"string\" && value.length > 0;\n}\n\nfunction validateStringArray(\n  items: unknown,\n  fieldName: string,\n  sectionName: string,\n): void {\n  const qualifiedName = `${sectionName}.${fieldName}`;\n  if (!Array.isArray(items)) {\n    throw new ConfigValidationError(qualifiedName, \"must be an array\");\n  }\n  if (items.length === 0) {\n    throw new ConfigValidationError(qualifiedName, \"must not be empty\");\n  }\n  for (const item of items) {\n    if (!isNonEmptyString(item)) {\n      throw new ConfigValidationError(\n        qualifiedName,\n        \"entries must be non-empty strings\",\n      );\n    }\n  }\n}\n\n/**\n * Validates that `config.tenant` exists and its `tenantTables` is a non-empty\n * array of non-empty strings. Returns the narrowed tenant config.\n */\nexport function requireTenantConfig(\n  config: BetterConfig,\n): BetterTenantStaticConfig {\n  if (config.tenant === undefined) {\n    throw new ConfigValidationError(\"tenant\", \"section is required\");\n  }\n  validateStringArray(config.tenant.tenantTables, \"tenantTables\", \"tenant\");\n  return config.tenant;\n}\n\n/**\n * Validates that `config.audit` exists and its `auditTables` is a non-empty\n * array of non-empty strings. When `retention` is present, validates `days` is\n * a positive integer and `tables` (if present) is a non-empty string array.\n */\nexport function requireAuditConfig(\n  config: BetterConfig,\n): BetterAuditStaticConfig {\n  if (config.audit === undefined) {\n    throw new ConfigValidationError(\"audit\", \"section is required\");\n  }\n  validateStringArray(config.audit.auditTables, \"auditTables\", \"audit\");\n\n  if (config.audit.retention !== undefined) {\n    const { days, tables } = config.audit.retention;\n    if (!Number.isInteger(days) || days <= 0) {\n      throw new ConfigValidationError(\n        \"audit.retention.days\",\n        \"must be a positive integer\",\n      );\n    }\n    if (tables !== undefined) {\n      validateStringArray(tables, \"retention.tables\", \"audit\");\n    }\n  }\n\n  return config.audit;\n}\n"],"mappings":";AAcO,SAAS,mBAAmB,QAAoC;AACrE,SAAO;AACT;;;AChBA,SAAS,kBAAkB;AAIpB,IAAM,4BAAN,cAAwC,MAAM;AAAA,EACjC,OAAO;AAAA,EAChB;AAAA,EAET,YAAY,KAAa;AACvB;AAAA,MACE;AAAA,QACE,8CAA8C,GAAG;AAAA,QACjD;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,EAAE,KAAK,IAAI;AAAA,IACb;AACA,SAAK,MAAM;AAAA,EACb;AACF;AAiBA,eAAsB,iBACpB,SACuB;AACvB,QAAM,MAAM,SAAS,OAAO,QAAQ,IAAI;AAGxC,QAAM,aAAa,SAAS;AAE5B,QAAM,SAAS,MAAM,WAAyB;AAAA,IAC5C,MAAM;AAAA,IACN;AAAA,IACA,GAAI,eAAe,SAAY,EAAE,WAAW,IAAI,CAAC;AAAA,IACjD,QAAQ;AAAA,IACR,UAAU;AAAA,IACV,aAAa;AAAA,IACb,QAAQ;AAAA,EACV,CAAC;AAED,QAAM,SAAS,OAAO,UAAU,CAAC;AACjC,MAAI,OAAO,WAAW,GAAG;AACvB,UAAM,IAAI,0BAA0B,GAAG;AAAA,EACzC;AAEA,SAAO,OAAO,UAAU,CAAC;AAC3B;;;AC1DO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAC7B,OAAO;AAAA,EAChB;AAAA,EAET,YAAY,OAAe,SAAiB;AAC1C,UAAM,kBAAkB,KAAK,KAAK,OAAO,EAAE;AAC3C,SAAK,QAAQ;AAAA,EACf;AACF;AAEA,SAAS,iBAAiB,OAAiC;AACzD,SAAO,OAAO,UAAU,YAAY,MAAM,SAAS;AACrD;AAEA,SAAS,oBACP,OACA,WACA,aACM;AACN,QAAM,gBAAgB,GAAG,WAAW,IAAI,SAAS;AACjD,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI,sBAAsB,eAAe,kBAAkB;AAAA,EACnE;AACA,MAAI,MAAM,WAAW,GAAG;AACtB,UAAM,IAAI,sBAAsB,eAAe,mBAAmB;AAAA,EACpE;AACA,aAAW,QAAQ,OAAO;AACxB,QAAI,CAAC,iBAAiB,IAAI,GAAG;AAC3B,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAMO,SAAS,oBACd,QAC0B;AAC1B,MAAI,OAAO,WAAW,QAAW;AAC/B,UAAM,IAAI,sBAAsB,UAAU,qBAAqB;AAAA,EACjE;AACA,sBAAoB,OAAO,OAAO,cAAc,gBAAgB,QAAQ;AACxE,SAAO,OAAO;AAChB;AAOO,SAAS,mBACd,QACyB;AACzB,MAAI,OAAO,UAAU,QAAW;AAC9B,UAAM,IAAI,sBAAsB,SAAS,qBAAqB;AAAA,EAChE;AACA,sBAAoB,OAAO,MAAM,aAAa,eAAe,OAAO;AAEpE,MAAI,OAAO,MAAM,cAAc,QAAW;AACxC,UAAM,EAAE,MAAM,OAAO,IAAI,OAAO,MAAM;AACtC,QAAI,CAAC,OAAO,UAAU,IAAI,KAAK,QAAQ,GAAG;AACxC,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,MACF;AAAA,IACF;AACA,QAAI,WAAW,QAAW;AACxB,0BAAoB,QAAQ,oBAAoB,OAAO;AAAA,IACzD;AAAA,EACF;AAEA,SAAO,OAAO;AAChB;","names":[]}

package/dist/define-config.d.ts

@@ -0,0 +1,15 @@
+import type { BetterConfig } from "./config-types.js";
+/**
+ * Identity helper that provides TypeScript autocomplete for `better.config.ts`.
+ *
+ * ```ts
+ * // better.config.ts
+ * import { defineBetterConfig } from "@usebetterdev/plugin/config";
+ *
+ * export default defineBetterConfig({
+ *   tenant: { tenantTables: ["organizations"] },
+ * });
+ * ```
+ */
+export declare function defineBetterConfig(config: BetterConfig): BetterConfig;
+//# sourceMappingURL=define-config.d.ts.map

package/dist/define-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../src/define-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAErE"}

package/dist/demo/auth-events.d.ts

@@ -0,0 +1,34 @@
+export declare const authEvents: () => {
+    id: string;
+    schema: {
+        tables: {
+            auth_events: {
+                fields: {
+                    id: {
+                        type: "string";
+                        required: true;
+                        unique: true;
+                    };
+                    event_type: {
+                        type: "string";
+                        required: true;
+                    };
+                    user_id: {
+                        type: "string";
+                        required: true;
+                        index: true;
+                    };
+                    timestamp: {
+                        type: "date";
+                        required: true;
+                        defaultValue: () => Date;
+                    };
+                    metadata: {
+                        type: "json";
+                    };
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=auth-events.d.ts.map

package/dist/demo/auth-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-events.d.ts","sourceRoot":"","sources":["../../src/demo/auth-events.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsBtB,CAAC"}

package/dist/demo/webhook-dispatcher.d.ts

@@ -0,0 +1,74 @@
+export type AuditHookContract = {
+    afterLog: {
+        log: Readonly<{
+            id: string;
+            tableName: string;
+        }>;
+    };
+};
+export interface WebhookDispatcherConfig {
+    /** Target URL to POST event payloads to. */
+    url: string;
+    /** Optional list of event types to forward. When omitted, all events are forwarded. */
+    events?: string[];
+}
+export declare const webhookDispatcher: (config: WebhookDispatcherConfig) => {
+    id: string;
+    hooks: {
+        afterLog: (_payload: {
+            log: Readonly<{
+                id: string;
+                tableName: string;
+            }>;
+        }) => Promise<void>;
+    };
+    schema: {
+        tables: {
+            webhook_deliveries: {
+                fields: {
+                    id: {
+                        type: "string";
+                        required: true;
+                        unique: true;
+                    };
+                    endpoint_url: {
+                        type: "string";
+                        required: true;
+                        index: true;
+                    };
+                    event_type: {
+                        type: "string";
+                        required: true;
+                    };
+                    status: {
+                        type: "string";
+                        required: true;
+                    };
+                    http_status: {
+                        type: "number";
+                    };
+                    attempt_count: {
+                        type: "number";
+                        required: true;
+                        defaultValue: number;
+                    };
+                    last_attempt_at: {
+                        type: "date";
+                    };
+                    created_at: {
+                        type: "date";
+                        required: true;
+                    };
+                };
+            };
+        };
+        extend: {
+            audit_log: {
+                webhook_delivered_at: {
+                    type: "date";
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=webhook-dispatcher.d.ts.map

package/dist/demo/webhook-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-dispatcher.d.ts","sourceRoot":"","sources":["../../src/demo/webhook-dispatcher.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE;QAAE,GAAG,EAAE,QAAQ,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CAChE,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,eAAO,MAAM,iBAAiB,WAAY,uBAAuB;;;;iBAV9C,QAAQ,CAAC;gBAAE,EAAE,EAAE,MAAM,CAAC;gBAAC,SAAS,EAAE,MAAM,CAAA;aAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6C7D,CAAC"}

package/dist/hook-registry.d.ts

@@ -0,0 +1,68 @@
+import type { HookContract, HookHandlers } from "./types.js";
+/**
+ * Error captured when a plugin hook handler fails during `invokeAfter`.
+ */
+export interface PluginError {
+    pluginId: string;
+    hook: string;
+    error: unknown;
+}
+/**
+ * Error thrown by `invokeBefore` when a plugin hook handler fails.
+ * Wraps the original error with plugin and hook context so callers
+ * can identify which plugin caused the failure.
+ */
+export declare class PluginInvokeError extends Error {
+    readonly name = "PluginInvokeError";
+    readonly pluginId: string;
+    readonly hook: string;
+    constructor(pluginId: string, hook: string, cause: unknown);
+}
+/**
+ * Runtime registry that products use to register plugin hooks and invoke them
+ * at lifecycle points.
+ *
+ * Generic over THooks so products get type-safe hook names and payloads.
+ */
+export declare class HookRegistry<THooks extends HookContract> {
+    private hooks;
+    private registeredPlugins;
+    /**
+     * Register all hooks declared by a plugin. Skips entries whose value is not
+     * a function (defensive against partial/optional declarations).
+     *
+     * Throws if a plugin with the same ID has already been registered.
+     */
+    register(pluginId: string, hooks: Partial<HookHandlers<THooks>>): void;
+    /**
+     * Sequential, fail-fast invocation — for "before" hooks.
+     * Runs handlers in registration order. Aborts on first throw and wraps
+     * the error in a {@link PluginInvokeError} so the caller knows which
+     * plugin failed. Later handlers are **not** called.
+     *
+     * Uses a snapshot of the handler list so that registrations during
+     * async execution do not affect the current invocation.
+     */
+    invokeBefore<K extends keyof THooks & string>(hook: K, payload: THooks[K]): Promise<void>;
+    /**
+     * Sequential, collect-errors invocation — for "after" hooks.
+     * Runs **all** handlers even when some fail. Failures are wrapped in
+     * {@link PluginError} and returned as an array. Returns an empty array
+     * when all handlers succeed or when no handlers are registered.
+     *
+     * Uses a snapshot of the handler list so that registrations during
+     * async execution do not affect the current invocation.
+     */
+    invokeAfter<K extends keyof THooks & string>(hook: K, payload: THooks[K]): Promise<PluginError[]>;
+    /**
+     * Calls a stored handler with the given payload.
+     *
+     * Handlers are stored as `(payload: never) => …` for variance compatibility
+     * (see {@link RegisteredHook}). At runtime the payload always matches
+     * `THooks[K]` — guaranteed by the generic constraint on {@link register}.
+     * This single assertion is the only place where TypeScript's type system
+     * cannot statically verify the heterogeneous map access.
+     */
+    private callHandler;
+}
+//# sourceMappingURL=hook-registry.d.ts.map

package/dist/hook-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-registry.d.ts","sourceRoot":"","sources":["../src/hook-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAuB;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAQ3D;AAYD;;;;;GAKG;AACH,qBAAa,YAAY,CAAC,MAAM,SAAS,YAAY;IACnD,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,iBAAiB,CAAqB;IAE9C;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAoBtE;;;;;;;;OAQG;IACG,YAAY,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EAChD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,GACjB,OAAO,CAAC,IAAI,CAAC;IAehB;;;;;;;;OAQG;IACG,WAAW,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EAC/C,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,GACjB,OAAO,CAAC,WAAW,EAAE,CAAC;IAsBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;CAMpB"}