@objectstack/types 10.2.0 → 11.0.0

package/dist/index.d.mts

@@ -25,6 +25,39 @@
 declare function readEnvWithDeprecation(preferred: string, legacy: string | readonly string[], options?: {
     silent?: boolean;
 }): string | undefined;
+/**
+ * Resolve whether the deployment runs in multi-org (a.k.a. multi-tenant) mode.
+ *
+ * Single source of truth for the `OS_MULTI_ORG_ENABLED` flag. Resolution: the
+ * canonical `OS_MULTI_ORG_ENABLED` wins; else the deprecated `OS_MULTI_TENANT`
+ * (which fires the one-shot rename warning via {@link readEnvWithDeprecation});
+ * else `false`. Any value other than a case-insensitive `'false'` enables it.
+ *
+ * Every site that needs to know "is this multi-org?" — the SQL driver's
+ * tenant-audit gate, the auth manager's `/auth/config` feature flag and
+ * org-create guard, the CLI / dev / runtime org-scoping plugin wiring — MUST
+ * call this instead of re-reading the env, so the driver, the security layer,
+ * and the UI can never disagree about the mode. Previously each site inlined
+ * its own `String(... ?? 'false').toLowerCase() !== 'false'` (and the SQL
+ * driver read `process.env` directly, skipping the deprecation warning).
+ *
+ * Reads `process.env` live on each call; memoise at the call site if the
+ * result must be stable for the process lifetime.
+ */
+declare function resolveMultiOrgEnabled(): boolean;
+/**
+ * Maximum number of organizations a single user may CREATE, from `OS_ORG_LIMIT`.
+ * The auth plugin forwards this as better-auth's `organizationLimit` in function
+ * form, counting only the caller's `role=owner` memberships — so it caps
+ * self-created orgs (each of which can auto-provision a free environment on the
+ * cloud control plane) without penalising a user invited into many orgs.
+ *
+ * Only meaningful when multi-org is enabled ({@link resolveMultiOrgEnabled}).
+ * Returns `undefined` when unset or non-positive → no limit (better-auth treats
+ * an absent `organizationLimit` as unlimited), preserving self-host behaviour.
+ * Deployments that let users self-create orgs SHOULD set a generous cap.
+ */
+declare function resolveOrgLimit(): number | undefined;
 /**
  * Internal: clear the dedupe set. Test-only; exposed so suite-wide
  * deprecation warnings don't bleed between tests.
@@ -47,4 +80,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, readEnvWithDeprecation };
+export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, readEnvWithDeprecation, resolveMultiOrgEnabled, resolveOrgLimit };

package/dist/index.d.ts

@@ -25,6 +25,39 @@
 declare function readEnvWithDeprecation(preferred: string, legacy: string | readonly string[], options?: {
     silent?: boolean;
 }): string | undefined;
+/**
+ * Resolve whether the deployment runs in multi-org (a.k.a. multi-tenant) mode.
+ *
+ * Single source of truth for the `OS_MULTI_ORG_ENABLED` flag. Resolution: the
+ * canonical `OS_MULTI_ORG_ENABLED` wins; else the deprecated `OS_MULTI_TENANT`
+ * (which fires the one-shot rename warning via {@link readEnvWithDeprecation});
+ * else `false`. Any value other than a case-insensitive `'false'` enables it.
+ *
+ * Every site that needs to know "is this multi-org?" — the SQL driver's
+ * tenant-audit gate, the auth manager's `/auth/config` feature flag and
+ * org-create guard, the CLI / dev / runtime org-scoping plugin wiring — MUST
+ * call this instead of re-reading the env, so the driver, the security layer,
+ * and the UI can never disagree about the mode. Previously each site inlined
+ * its own `String(... ?? 'false').toLowerCase() !== 'false'` (and the SQL
+ * driver read `process.env` directly, skipping the deprecation warning).
+ *
+ * Reads `process.env` live on each call; memoise at the call site if the
+ * result must be stable for the process lifetime.
+ */
+declare function resolveMultiOrgEnabled(): boolean;
+/**
+ * Maximum number of organizations a single user may CREATE, from `OS_ORG_LIMIT`.
+ * The auth plugin forwards this as better-auth's `organizationLimit` in function
+ * form, counting only the caller's `role=owner` memberships — so it caps
+ * self-created orgs (each of which can auto-provision a free environment on the
+ * cloud control plane) without penalising a user invited into many orgs.
+ *
+ * Only meaningful when multi-org is enabled ({@link resolveMultiOrgEnabled}).
+ * Returns `undefined` when unset or non-positive → no limit (better-auth treats
+ * an absent `organizationLimit` as unlimited), preserving self-host behaviour.
+ * Deployments that let users self-create orgs SHOULD set a generous cap.
+ */
+declare function resolveOrgLimit(): number | undefined;
 /**
  * Internal: clear the dedupe set. Test-only; exposed so suite-wide
  * deprecation warnings don't bleed between tests.
@@ -47,4 +80,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, readEnvWithDeprecation };
+export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, readEnvWithDeprecation, resolveMultiOrgEnabled, resolveOrgLimit };

package/dist/index.js

@@ -21,7 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   _resetEnvDeprecationWarnings: () => _resetEnvDeprecationWarnings,
-  readEnvWithDeprecation: () => readEnvWithDeprecation
+  readEnvWithDeprecation: () => readEnvWithDeprecation,
+  resolveMultiOrgEnabled: () => resolveMultiOrgEnabled,
+  resolveOrgLimit: () => resolveOrgLimit
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -52,12 +54,24 @@ function readEnvWithDeprecation(preferred, legacy, options) {
   }
   return void 0;
 }
+function resolveMultiOrgEnabled() {
+  const raw = readEnvWithDeprecation("OS_MULTI_ORG_ENABLED", "OS_MULTI_TENANT");
+  return String(raw ?? "false").toLowerCase() !== "false";
+}
+function resolveOrgLimit() {
+  const raw = readEnvWithDeprecation("OS_ORG_LIMIT", [], { silent: true });
+  if (raw == null || String(raw).trim() === "") return void 0;
+  const n = Number.parseInt(String(raw), 10);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
 function _resetEnvDeprecationWarnings() {
   _warnedKeys.clear();
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   _resetEnvDeprecationWarnings,
-  readEnvWithDeprecation
+  readEnvWithDeprecation,
+  resolveMultiOrgEnabled,
+  resolveOrgLimit
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/env.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport * from './env.js';\n\n// Placeholder for Kernel interface to avoid circular dependency\n// The actual Kernel implementation will satisfy this interface.\nexport interface IKernel {\n    // We can add specific methods here that plugins are allowed to call\n    // forcing a stricter contract than exposing the whole class.\n    ql?: any; // ObjectQL instance (optional to support initialization phase)\n    start(): Promise<void>;\n    // ... expose other needed public methods\n    [key: string]: any; \n}\n\nexport interface RuntimeContext {\n    engine: IKernel;\n}\n\nexport interface RuntimePlugin {\n    name: string;\n    install?: (ctx: RuntimeContext) => void | Promise<void>;\n    onStart?: (ctx: RuntimeContext) => void | Promise<void>;\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @param options    Optional behaviour flags. Set `silent: true` for aliases\n *                   that remain accepted conventions rather than true legacy\n *                   names — e.g. `PORT`, which PaaS platforms (Render, Railway,\n *                   Heroku, Fly, …) inject automatically. Warning on those\n *                   would nag operators about env they never set.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n  options?: { silent?: boolean },\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!options?.silent && !_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBA,IAAM,cAAc,oBAAI,IAAY;AA0B7B,SAAS,uBACd,WACA,QACA,SACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,SAAS,UAAU,CAAC,YAAY,IAAI,SAAS,GAAG;AACnD,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/env.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport * from './env.js';\n\n// Placeholder for Kernel interface to avoid circular dependency\n// The actual Kernel implementation will satisfy this interface.\nexport interface IKernel {\n    // We can add specific methods here that plugins are allowed to call\n    // forcing a stricter contract than exposing the whole class.\n    ql?: any; // ObjectQL instance (optional to support initialization phase)\n    start(): Promise<void>;\n    // ... expose other needed public methods\n    [key: string]: any; \n}\n\nexport interface RuntimeContext {\n    engine: IKernel;\n}\n\nexport interface RuntimePlugin {\n    name: string;\n    install?: (ctx: RuntimeContext) => void | Promise<void>;\n    onStart?: (ctx: RuntimeContext) => void | Promise<void>;\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @param options    Optional behaviour flags. Set `silent: true` for aliases\n *                   that remain accepted conventions rather than true legacy\n *                   names — e.g. `PORT`, which PaaS platforms (Render, Railway,\n *                   Heroku, Fly, …) inject automatically. Warning on those\n *                   would nag operators about env they never set.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n  options?: { silent?: boolean },\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!options?.silent && !_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve whether the deployment runs in multi-org (a.k.a. multi-tenant) mode.\n *\n * Single source of truth for the `OS_MULTI_ORG_ENABLED` flag. Resolution: the\n * canonical `OS_MULTI_ORG_ENABLED` wins; else the deprecated `OS_MULTI_TENANT`\n * (which fires the one-shot rename warning via {@link readEnvWithDeprecation});\n * else `false`. Any value other than a case-insensitive `'false'` enables it.\n *\n * Every site that needs to know \"is this multi-org?\" — the SQL driver's\n * tenant-audit gate, the auth manager's `/auth/config` feature flag and\n * org-create guard, the CLI / dev / runtime org-scoping plugin wiring — MUST\n * call this instead of re-reading the env, so the driver, the security layer,\n * and the UI can never disagree about the mode. Previously each site inlined\n * its own `String(... ?? 'false').toLowerCase() !== 'false'` (and the SQL\n * driver read `process.env` directly, skipping the deprecation warning).\n *\n * Reads `process.env` live on each call; memoise at the call site if the\n * result must be stable for the process lifetime.\n */\nexport function resolveMultiOrgEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MULTI_ORG_ENABLED', 'OS_MULTI_TENANT');\n  return String(raw ?? 'false').toLowerCase() !== 'false';\n}\n\n/**\n * Maximum number of organizations a single user may CREATE, from `OS_ORG_LIMIT`.\n * The auth plugin forwards this as better-auth's `organizationLimit` in function\n * form, counting only the caller's `role=owner` memberships — so it caps\n * self-created orgs (each of which can auto-provision a free environment on the\n * cloud control plane) without penalising a user invited into many orgs.\n *\n * Only meaningful when multi-org is enabled ({@link resolveMultiOrgEnabled}).\n * Returns `undefined` when unset or non-positive → no limit (better-auth treats\n * an absent `organizationLimit` as unlimited), preserving self-host behaviour.\n * Deployments that let users self-create orgs SHOULD set a generous cap.\n */\nexport function resolveOrgLimit(): number | undefined {\n  const raw = readEnvWithDeprecation('OS_ORG_LIMIT', [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return undefined;\n  const n = Number.parseInt(String(raw), 10);\n  return Number.isFinite(n) && n > 0 ? n : undefined;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBA,IAAM,cAAc,oBAAI,IAAY;AA0B7B,SAAS,uBACd,WACA,QACA,SACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,SAAS,UAAU,CAAC,YAAY,IAAI,SAAS,GAAG;AACnD,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAqBO,SAAS,yBAAkC;AAChD,QAAM,MAAM,uBAAuB,wBAAwB,iBAAiB;AAC5E,SAAO,OAAO,OAAO,OAAO,EAAE,YAAY,MAAM;AAClD;AAcO,SAAS,kBAAsC;AACpD,QAAM,MAAM,uBAAuB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACvE,MAAI,OAAO,QAAQ,OAAO,GAAG,EAAE,KAAK,MAAM,GAAI,QAAO;AACrD,QAAM,IAAI,OAAO,SAAS,OAAO,GAAG,GAAG,EAAE;AACzC,SAAO,OAAO,SAAS,CAAC,KAAK,IAAI,IAAI,IAAI;AAC3C;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}

package/dist/index.mjs

@@ -25,11 +25,23 @@ function readEnvWithDeprecation(preferred, legacy, options) {
   }
   return void 0;
 }
+function resolveMultiOrgEnabled() {
+  const raw = readEnvWithDeprecation("OS_MULTI_ORG_ENABLED", "OS_MULTI_TENANT");
+  return String(raw ?? "false").toLowerCase() !== "false";
+}
+function resolveOrgLimit() {
+  const raw = readEnvWithDeprecation("OS_ORG_LIMIT", [], { silent: true });
+  if (raw == null || String(raw).trim() === "") return void 0;
+  const n = Number.parseInt(String(raw), 10);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
 function _resetEnvDeprecationWarnings() {
   _warnedKeys.clear();
 }
 export {
   _resetEnvDeprecationWarnings,
-  readEnvWithDeprecation
+  readEnvWithDeprecation,
+  resolveMultiOrgEnabled,
+  resolveOrgLimit
 };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/env.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @param options    Optional behaviour flags. Set `silent: true` for aliases\n *                   that remain accepted conventions rather than true legacy\n *                   names — e.g. `PORT`, which PaaS platforms (Render, Railway,\n *                   Heroku, Fly, …) inject automatically. Warning on those\n *                   would nag operators about env they never set.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n  options?: { silent?: boolean },\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!options?.silent && !_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n"],"mappings":";AAmBA,IAAM,cAAc,oBAAI,IAAY;AA0B7B,SAAS,uBACd,WACA,QACA,SACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,SAAS,UAAU,CAAC,YAAY,IAAI,SAAS,GAAG;AACnD,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}
+{"version":3,"sources":["../src/env.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @param options    Optional behaviour flags. Set `silent: true` for aliases\n *                   that remain accepted conventions rather than true legacy\n *                   names — e.g. `PORT`, which PaaS platforms (Render, Railway,\n *                   Heroku, Fly, …) inject automatically. Warning on those\n *                   would nag operators about env they never set.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n  options?: { silent?: boolean },\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!options?.silent && !_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve whether the deployment runs in multi-org (a.k.a. multi-tenant) mode.\n *\n * Single source of truth for the `OS_MULTI_ORG_ENABLED` flag. Resolution: the\n * canonical `OS_MULTI_ORG_ENABLED` wins; else the deprecated `OS_MULTI_TENANT`\n * (which fires the one-shot rename warning via {@link readEnvWithDeprecation});\n * else `false`. Any value other than a case-insensitive `'false'` enables it.\n *\n * Every site that needs to know \"is this multi-org?\" — the SQL driver's\n * tenant-audit gate, the auth manager's `/auth/config` feature flag and\n * org-create guard, the CLI / dev / runtime org-scoping plugin wiring — MUST\n * call this instead of re-reading the env, so the driver, the security layer,\n * and the UI can never disagree about the mode. Previously each site inlined\n * its own `String(... ?? 'false').toLowerCase() !== 'false'` (and the SQL\n * driver read `process.env` directly, skipping the deprecation warning).\n *\n * Reads `process.env` live on each call; memoise at the call site if the\n * result must be stable for the process lifetime.\n */\nexport function resolveMultiOrgEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MULTI_ORG_ENABLED', 'OS_MULTI_TENANT');\n  return String(raw ?? 'false').toLowerCase() !== 'false';\n}\n\n/**\n * Maximum number of organizations a single user may CREATE, from `OS_ORG_LIMIT`.\n * The auth plugin forwards this as better-auth's `organizationLimit` in function\n * form, counting only the caller's `role=owner` memberships — so it caps\n * self-created orgs (each of which can auto-provision a free environment on the\n * cloud control plane) without penalising a user invited into many orgs.\n *\n * Only meaningful when multi-org is enabled ({@link resolveMultiOrgEnabled}).\n * Returns `undefined` when unset or non-positive → no limit (better-auth treats\n * an absent `organizationLimit` as unlimited), preserving self-host behaviour.\n * Deployments that let users self-create orgs SHOULD set a generous cap.\n */\nexport function resolveOrgLimit(): number | undefined {\n  const raw = readEnvWithDeprecation('OS_ORG_LIMIT', [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return undefined;\n  const n = Number.parseInt(String(raw), 10);\n  return Number.isFinite(n) && n > 0 ? n : undefined;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n"],"mappings":";AAmBA,IAAM,cAAc,oBAAI,IAAY;AA0B7B,SAAS,uBACd,WACA,QACA,SACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,SAAS,UAAU,CAAC,YAAY,IAAI,SAAS,GAAG;AACnD,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAqBO,SAAS,yBAAkC;AAChD,QAAM,MAAM,uBAAuB,wBAAwB,iBAAiB;AAC5E,SAAO,OAAO,OAAO,OAAO,EAAE,YAAY,MAAM;AAClD;AAcO,SAAS,kBAAsC;AACpD,QAAM,MAAM,uBAAuB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACvE,MAAI,OAAO,QAAQ,OAAO,GAAG,EAAE,KAAK,MAAM,GAAI,QAAO;AACrD,QAAM,IAAI,OAAO,SAAS,OAAO,GAAG,GAAG,EAAE;AACzC,SAAO,OAAO,SAAS,CAAC,KAAK,IAAI,IAAI,IAAI;AAC3C;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/types",
-  "version": "10.2.0",
+  "version": "11.0.0",
   "license": "Apache-2.0",
   "description": "Shared interfaces describing the ObjectStack Runtime environment",
   "main": "dist/index.js",
@@ -13,7 +13,7 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "10.2.0"
+    "@objectstack/spec": "11.0.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",