@volcanicminds/tools 0.0.7 → 0.0.8

package/dist/lib/tenant/index.d.ts

@@ -0,0 +1,4 @@
+export type { DataSourceLike, QueryRunnerLike, RepositoryLike } from './types.js';
+export { TenantEx, TenantStatus, ProvisionResult, validateSchemaName, createTenantSchema, syncTenantSchema, dropTenantSchema } from './provisioner.js';
+export { TenantResolverConfig, resolveTenant, extractTenantId, setSchemaContext } from './resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/tenant/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/tenant/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGjF,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA"}

package/dist/lib/tenant/index.js

@@ -0,0 +1,3 @@
+export { validateSchemaName, createTenantSchema, syncTenantSchema, dropTenantSchema } from './provisioner.js';
+export { resolveTenant, extractTenantId, setSchemaContext } from './resolver.js';
+//# sourceMappingURL=index.js.map

package/dist/lib/tenant/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/tenant/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAwB,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA"}

package/dist/lib/tenant/provisioner.d.ts

@@ -0,0 +1,22 @@
+import type { DataSourceLike } from './types.js';
+export type TenantStatus = 'active' | 'suspended' | 'archived';
+export interface TenantEx {
+    name: string;
+    slug: string;
+    schemaName: string;
+    status: TenantStatus;
+    config: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt?: Date;
+}
+export interface ProvisionResult {
+    success: boolean;
+    schemaName: string;
+    error?: string;
+}
+export declare function validateSchemaName(name: string): boolean;
+export declare function createTenantSchema(dataSource: DataSourceLike, schemaName: string): Promise<ProvisionResult>;
+export declare function syncTenantSchema(dataSource: DataSourceLike, schemaName: string): Promise<void>;
+export declare function dropTenantSchema(dataSource: DataSourceLike, schemaName: string): Promise<void>;
+//# sourceMappingURL=provisioner.d.ts.map

package/dist/lib/tenant/provisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioner.d.ts","sourceRoot":"","sources":["../../../lib/tenant/provisioner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAA;AAmB9D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,CAAC,EAAE,IAAI,CAAA;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAOD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAKD,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBjH;AAMD,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUpG;AAKD,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQpG"}

package/dist/lib/tenant/provisioner.js

@@ -0,0 +1,45 @@
+const SCHEMA_REGEX = /^[a-z][a-z0-9_]*$/;
+export function validateSchemaName(name) {
+    return SCHEMA_REGEX.test(name);
+}
+export async function createTenantSchema(dataSource, schemaName) {
+    if (!validateSchemaName(schemaName)) {
+        return { success: false, schemaName, error: 'Invalid schema name format' };
+    }
+    const qr = dataSource.createQueryRunner();
+    await qr.connect();
+    try {
+        await qr.query(`CREATE SCHEMA IF NOT EXISTS "${schemaName}"`);
+        return { success: true, schemaName };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, schemaName, error: message };
+    }
+    finally {
+        await qr.release();
+    }
+}
+export async function syncTenantSchema(dataSource, schemaName) {
+    const qr = dataSource.createQueryRunner();
+    await qr.connect();
+    try {
+        await qr.query(`SET search_path TO "${schemaName}"`);
+        await dataSource.synchronize();
+        await qr.query(`SET search_path TO "public"`);
+    }
+    finally {
+        await qr.release();
+    }
+}
+export async function dropTenantSchema(dataSource, schemaName) {
+    const qr = dataSource.createQueryRunner();
+    await qr.connect();
+    try {
+        await qr.query(`DROP SCHEMA IF EXISTS "${schemaName}" CASCADE`);
+    }
+    finally {
+        await qr.release();
+    }
+}
+//# sourceMappingURL=provisioner.js.map

package/dist/lib/tenant/provisioner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioner.js","sourceRoot":"","sources":["../../../lib/tenant/provisioner.ts"],"names":[],"mappings":"AAsCA,MAAM,YAAY,GAAG,mBAAmB,CAAA;AAKxC,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAChC,CAAC;AAKD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,UAA0B,EAAE,UAAkB;IACrF,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,4BAA4B,EAAE,CAAA;IAC5E,CAAC;IAED,MAAM,EAAE,GAAG,UAAU,CAAC,iBAAiB,EAAE,CAAA;IACzC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;IAClB,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,gCAAgC,UAAU,GAAG,CAAC,CAAA;QAC7D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA;IACtC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAChE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;IACvD,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;IACpB,CAAC;AACH,CAAC;AAMD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,UAA0B,EAAE,UAAkB;IACnF,MAAM,EAAE,GAAG,UAAU,CAAC,iBAAiB,EAAE,CAAA;IACzC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;IAClB,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,uBAAuB,UAAU,GAAG,CAAC,CAAA;QACpD,MAAM,UAAU,CAAC,WAAW,EAAE,CAAA;QAC9B,MAAM,EAAE,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAA;IAC/C,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;IACpB,CAAC;AACH,CAAC;AAKD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,UAA0B,EAAE,UAAkB;IACnF,MAAM,EAAE,GAAG,UAAU,CAAC,iBAAiB,EAAE,CAAA;IACzC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;IAClB,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,0BAA0B,UAAU,WAAW,CAAC,CAAA;IACjE,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;IACpB,CAAC;AACH,CAAC"}

package/dist/lib/tenant/resolver.d.ts

@@ -0,0 +1,17 @@
+import type { DataSourceLike, RepositoryLike } from './types.js';
+import type { TenantEx } from './provisioner.js';
+export interface TenantResolverConfig<T extends TenantEx> {
+    dataSource: DataSourceLike;
+    tenantRepository: RepositoryLike<T>;
+    headerName?: string;
+    subdomainEnabled?: boolean;
+    baseDomain?: string;
+}
+export declare function resolveTenant<T extends TenantEx>(repository: RepositoryLike<T>, tenantIdOrSlug: string): Promise<T | null>;
+export declare function extractTenantId(headers: Record<string, string | string[] | undefined>, host: string | undefined, config: {
+    headerName?: string;
+    subdomainEnabled?: boolean;
+    baseDomain?: string;
+}): string | null;
+export declare function setSchemaContext(dataSource: DataSourceLike, schemaName: string): Promise<() => Promise<void>>;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/lib/tenant/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../../lib/tenant/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAEhD,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,QAAQ;IACtD,UAAU,EAAE,cAAc,CAAA;IAC1B,gBAAgB,EAAE,cAAc,CAAC,CAAC,CAAC,CAAA;IACnC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAOD,wBAAsB,aAAa,CAAC,CAAC,SAAS,QAAQ,EACpD,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,EAC7B,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAGnB;AAKD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/E,MAAM,GAAG,IAAI,CAef;AAMD,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CASnH"}

package/dist/lib/tenant/resolver.js

@@ -0,0 +1,29 @@
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export async function resolveTenant(repository, tenantIdOrSlug) {
+    const where = UUID_RE.test(tenantIdOrSlug) ? { id: tenantIdOrSlug } : { slug: tenantIdOrSlug };
+    return repository.findOne({ where });
+}
+export function extractTenantId(headers, host, config) {
+    const headerName = config.headerName || 'x-tenant-id';
+    const fromHeader = headers[headerName];
+    if (fromHeader && typeof fromHeader === 'string')
+        return fromHeader;
+    if (config.subdomainEnabled && config.baseDomain && host) {
+        if (host.endsWith(config.baseDomain)) {
+            const subdomain = host.replace(`.${config.baseDomain}`, '').split('.')[0];
+            if (subdomain && subdomain !== 'www')
+                return subdomain;
+        }
+    }
+    return null;
+}
+export async function setSchemaContext(dataSource, schemaName) {
+    const qr = dataSource.createQueryRunner();
+    await qr.connect();
+    await qr.query(`SET search_path TO "${schemaName}", "public"`);
+    return async () => {
+        await qr.query(`SET search_path TO "public"`);
+        await qr.release();
+    };
+}
+//# sourceMappingURL=resolver.js.map

package/dist/lib/tenant/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../lib/tenant/resolver.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,GAAG,4EAA4E,CAAA;AAK5F,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAA6B,EAC7B,cAAsB;IAEtB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAA;IAC9F,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;AACtC,CAAC;AAKD,MAAM,UAAU,eAAe,CAC7B,OAAsD,EACtD,IAAwB,EACxB,MAAgF;IAGhF,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,aAAa,CAAA;IACrD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IACtC,IAAI,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAA;IAGnE,IAAI,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;QACzD,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YACrC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;YACzE,IAAI,SAAS,IAAI,SAAS,KAAK,KAAK;gBAAE,OAAO,SAAS,CAAA;QACxD,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAMD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,UAA0B,EAAE,UAAkB;IACnF,MAAM,EAAE,GAAG,UAAU,CAAC,iBAAiB,EAAE,CAAA;IACzC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;IAClB,MAAM,EAAE,CAAC,KAAK,CAAC,uBAAuB,UAAU,aAAa,CAAC,CAAA;IAE9D,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,EAAE,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAA;QAC7C,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;IACpB,CAAC,CAAA;AACH,CAAC"}

package/dist/lib/tenant/types.d.ts

@@ -0,0 +1,15 @@
+export interface QueryRunnerLike {
+    connect(): Promise<void>;
+    query(query: string, parameters?: unknown[]): Promise<unknown>;
+    release(): Promise<void>;
+}
+export interface DataSourceLike {
+    createQueryRunner(): QueryRunnerLike;
+    synchronize(): Promise<void>;
+}
+export interface RepositoryLike<T> {
+    findOne(options: {
+        where: Record<string, unknown>;
+    }): Promise<T | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/tenant/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../lib/tenant/types.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC9D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAKD,MAAM,WAAW,cAAc;IAC7B,iBAAiB,IAAI,eAAe,CAAA;IACpC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAKD,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,OAAO,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;CACxE"}

package/dist/lib/tenant/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/tenant/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../lib/tenant/types.ts"],"names":[],"mappings":""}

package/lib/tenant/index.ts

@@ -0,0 +1,19 @@
+// TenantEx Module - Multi-tenant utilities for Volcanic Backend
+// Zero external dependencies - uses duck-typed interfaces
+
+// Types
+export type { DataSourceLike, QueryRunnerLike, RepositoryLike } from './types.js'
+
+// Entity Interface & Provisioning
+export {
+  TenantEx,
+  TenantStatus,
+  ProvisionResult,
+  validateSchemaName,
+  createTenantSchema,
+  syncTenantSchema,
+  dropTenantSchema
+} from './provisioner.js'
+
+// Tenant Resolution
+export { TenantResolverConfig, resolveTenant, extractTenantId, setSchemaContext } from './resolver.js'

package/lib/tenant/provisioner.ts

@@ -0,0 +1,96 @@
+import type { DataSourceLike } from './types.js'
+
+export type TenantStatus = 'active' | 'suspended' | 'archived'
+
+/**
+ * Interface for multi-tenant entities.
+ * Consumer entities should extend BaseEntity and implement this interface.
+ *
+ * @example
+ * ```typescript
+ * import { TenantEx } from "@volcanicminds/tools/tenant"
+ * import { Entity, PrimaryGeneratedColumn, Column, ... } from "typeorm"
+ *
+ * @Entity({ name: "tenants", schema: "public" })
+ * export class Tenant extends BaseEntity implements TenantEx {
+ *   @PrimaryGeneratedColumn("uuid") id!: string
+ *   @Column() name!: string
+ *   // ...
+ * }
+ * ```
+ */
+export interface TenantEx {
+  name: string
+  slug: string
+  schemaName: string
+  status: TenantStatus
+  config: Record<string, unknown>
+  createdAt: Date
+  updatedAt: Date
+  deletedAt?: Date
+}
+
+export interface ProvisionResult {
+  success: boolean
+  schemaName: string
+  error?: string
+}
+
+const SCHEMA_REGEX = /^[a-z][a-z0-9_]*$/
+
+/**
+ * Validates a schema name for PostgreSQL compatibility.
+ */
+export function validateSchemaName(name: string): boolean {
+  return SCHEMA_REGEX.test(name)
+}
+
+/**
+ * Creates a new PostgreSQL schema for a tenant.
+ */
+export async function createTenantSchema(dataSource: DataSourceLike, schemaName: string): Promise<ProvisionResult> {
+  if (!validateSchemaName(schemaName)) {
+    return { success: false, schemaName, error: 'Invalid schema name format' }
+  }
+
+  const qr = dataSource.createQueryRunner()
+  await qr.connect()
+  try {
+    await qr.query(`CREATE SCHEMA IF NOT EXISTS "${schemaName}"`)
+    return { success: true, schemaName }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err)
+    return { success: false, schemaName, error: message }
+  } finally {
+    await qr.release()
+  }
+}
+
+/**
+ * Synchronizes TypeORM entities to a tenant schema.
+ * WARNING: Use with caution in production. Prefer migrations.
+ */
+export async function syncTenantSchema(dataSource: DataSourceLike, schemaName: string): Promise<void> {
+  const qr = dataSource.createQueryRunner()
+  await qr.connect()
+  try {
+    await qr.query(`SET search_path TO "${schemaName}"`)
+    await dataSource.synchronize()
+    await qr.query(`SET search_path TO "public"`)
+  } finally {
+    await qr.release()
+  }
+}
+
+/**
+ * Drops a tenant schema and all its contents. DESTRUCTIVE.
+ */
+export async function dropTenantSchema(dataSource: DataSourceLike, schemaName: string): Promise<void> {
+  const qr = dataSource.createQueryRunner()
+  await qr.connect()
+  try {
+    await qr.query(`DROP SCHEMA IF EXISTS "${schemaName}" CASCADE`)
+  } finally {
+    await qr.release()
+  }
+}

package/lib/tenant/resolver.ts

@@ -0,0 +1,62 @@
+import type { DataSourceLike, RepositoryLike } from './types.js'
+import type { TenantEx } from './provisioner.js'
+
+export interface TenantResolverConfig<T extends TenantEx> {
+  dataSource: DataSourceLike
+  tenantRepository: RepositoryLike<T>
+  headerName?: string
+  subdomainEnabled?: boolean
+  baseDomain?: string
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/**
+ * Resolves a tenant by ID or slug.
+ */
+export async function resolveTenant<T extends TenantEx>(
+  repository: RepositoryLike<T>,
+  tenantIdOrSlug: string
+): Promise<T | null> {
+  const where = UUID_RE.test(tenantIdOrSlug) ? { id: tenantIdOrSlug } : { slug: tenantIdOrSlug }
+  return repository.findOne({ where })
+}
+
+/**
+ * Extracts tenant identifier from request headers or subdomain.
+ */
+export function extractTenantId(
+  headers: Record<string, string | string[] | undefined>,
+  host: string | undefined,
+  config: { headerName?: string; subdomainEnabled?: boolean; baseDomain?: string }
+): string | null {
+  // 1. Try header
+  const headerName = config.headerName || 'x-tenant-id'
+  const fromHeader = headers[headerName]
+  if (fromHeader && typeof fromHeader === 'string') return fromHeader
+
+  // 2. Try subdomain
+  if (config.subdomainEnabled && config.baseDomain && host) {
+    if (host.endsWith(config.baseDomain)) {
+      const subdomain = host.replace(`.${config.baseDomain}`, '').split('.')[0]
+      if (subdomain && subdomain !== 'www') return subdomain
+    }
+  }
+
+  return null
+}
+
+/**
+ * Sets the PostgreSQL search_path for a tenant schema.
+ * Returns a cleanup function to reset to public.
+ */
+export async function setSchemaContext(dataSource: DataSourceLike, schemaName: string): Promise<() => Promise<void>> {
+  const qr = dataSource.createQueryRunner()
+  await qr.connect()
+  await qr.query(`SET search_path TO "${schemaName}", "public"`)
+
+  return async () => {
+    await qr.query(`SET search_path TO "public"`)
+    await qr.release()
+  }
+}

package/lib/tenant/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Minimal type definitions for ORM compatibility.
+ * These are duck-typed interfaces that match the methods we use.
+ * Works with TypeORM or any ORM with compatible signatures.
+ */
+
+/**
+ * Minimal QueryRunner interface.
+ */
+export interface QueryRunnerLike {
+  connect(): Promise<void>
+  query(query: string, parameters?: unknown[]): Promise<unknown>
+  release(): Promise<void>
+}
+
+/**
+ * Minimal DataSource interface.
+ */
+export interface DataSourceLike {
+  createQueryRunner(): QueryRunnerLike
+  synchronize(): Promise<void>
+}
+
+/**
+ * Minimal Repository interface.
+ */
+export interface RepositoryLike<T> {
+  findOne(options: { where: Record<string, unknown> }): Promise<T | null>
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volcanicminds/tools",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Tools for the volcanic (minds) backend",
   "keywords": [
     "volcanic",
@@ -68,6 +68,11 @@
       "types": "./dist/lib/transfer/index.d.ts",
       "import": "./dist/lib/transfer/index.js",
       "require": "./dist/lib/transfer/index.js"
+    },
+    "./tenant": {
+      "types": "./dist/lib/tenant/index.d.ts",
+      "import": "./dist/lib/tenant/index.js",
+      "require": "./dist/lib/tenant/index.js"
     }
   },
   "main": "dist/index.js",
@@ -137,6 +142,9 @@
       ],
       "transfer": [
         "dist/lib/transfer/index.d.ts"
+      ],
+      "tenant": [
+        "dist/lib/tenant/index.d.ts"
       ]
     }
   }