@usebetterdev/tenant-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 usebetter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @better-tenant/core
+
+Core library for request-scoped multi-tenancy with Postgres RLS. Provides tenant context (AsyncLocalStorage), resolver strategies, adapter contract, and tenant API. No database driver dependency — use with [@usebetterdev/tenant-drizzle](https://github.com/usebetter-dev/usebetter) or a custom adapter.
+
+## Install
+
+```bash
+pnpm add @better-tenant/core
+```
+
+## Quick start
+
+```ts
+import { betterTenant, getContext, getDatabase } from "@better-tenant/core";
+import { drizzleAdapter } from "better-tenant/drizzle"; // or your adapter
+
+const adapter = drizzleAdapter(db);
+const tenant = betterTenant({
+  adapter,
+  tenantResolver: { header: "x-tenant-id" },
+  tenantTables: ["projects", "tasks"],
+  getTenantRepository: (database) => ({ create, update, list, delete }), // adapter provides this
+});
+
+// In middleware: resolve tenantId (e.g. tenant.resolveTenant(request)), then:
+await tenant.runWithTenantAndDatabase(tenantId, adapter, async () => {
+  await next();
+});
+
+// In handlers:
+const context = tenant.getContext();       // { tenantId, tenant?, database? }
+const database = tenant.getDatabase();     // tenant-scoped DB handle (use only this for tenant tables)
+```
+
+## API
+
+| API                                                     | Description                                                                                                  |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `betterTenant(config)`                                  | Create instance with adapter, resolver, optional `getTenantRepository`.                                      |
+| `getContext()`                                          | Current `TenantContext \| undefined` (tenantId, tenant?, database?).                                         |
+| `getDatabase()`                                         | Tenant-scoped database handle, or `undefined` outside request scope. Use only this for tenant-scoped tables. |
+| `runWithTenant(tenantId, fn)`                           | Run `fn` with context only (no DB). For tests or when adapter not used.                                      |
+| `runWithTenantAndDatabase(tenantId, adapter, fn)`       | Set context and run `fn` with adapter’s tenant-scoped DB. Call from middleware.                              |
+| `resolveTenant(request, config)` / `resolveTenantAsync` | Resolve tenant id from request (header, path, subdomain, jwt, custom).                                       |
+| `runAs(tenantId, adapter, fn)`                          | Same as request flow; use for cron or per-tenant jobs.                                                       |
+| `runAsSystem(fn)`                                       | Run with RLS bypass (adapter must implement `runAsSystem`).                                                  |
+| `tenant.api`                                            | `createTenant`, `updateTenant`, `listTenants`, `deleteTenant` (when `getTenantRepository` is set).           |
+
+## Adapter contract
+
+Adapters implement `TenantAdapter`:
+
+- **runWithTenant(tenantId, fn)** — Begin transaction → `SET LOCAL app.current_tenant = '<uuid>'` → call `fn(database)` → commit. Core does not run SQL.
+- **runAsSystem?(fn)** — Optional; run `fn` with a DB handle that has RLS bypass (e.g. `SET LOCAL app.bypass_rls = true`).
+
+Types: `TenantScopedDatabase` (opaque handle), `SystemDatabase` (opaque handle for system operations).
+
+## Resolver
+
+Resolution order: **header → path → subdomain → jwt → custom**. Configure `tenantResolver` with e.g. `header: "x-tenant-id"`, `path: "/t/:tenantId"`, `subdomain: true`, `jwt: { claim: "tenant_id" }`, or `custom: (req) => ...`.
+
+## Telemetry
+
+Anonymous telemetry is **on by default** to help improve the library. Data is sent to `https://telemetry.usebetter.dev` and includes runtime, framework, and redacted config (no PII or secrets). Telemetry is disabled in `NODE_ENV=test`.
+
+**Opt out:** Set `telemetry: { enabled: false }` in your config or `BETTER_TENANT_TELEMETRY=0`.
+
+**Debug mode:** Set `telemetry: { debug: true }` or `BETTER_TENANT_TELEMETRY_DEBUG=1` to log payloads to the console without sending.
+
+## Documentation
+
+- [Under the Hood](../docs/UNDER-THE-HOOD.md) — RLS, SET LOCAL, runAsSystem
+- [Product plan](../docs/PLAN.md) — Roadmap, architecture

package/dist/adapter.d.ts

@@ -0,0 +1,24 @@
+import type { TenantAdapter, TenantScopedDatabase, RunWithTenantAndDatabaseOptions } from "./types.js";
+/**
+ * Returns the tenant-scoped database handle when inside a runWithTenantAndDatabase (or runAs) scope.
+ *
+ * Use only the handle from getDatabase() for tenant-scoped tables. Outside scope, returns undefined.
+ * Config requires an adapter when tenant-scoped DB is used; getDatabase() is then available inside
+ * request handlers that ran via runWithTenantAndDatabase(tenantId, adapter, next).
+ */
+export declare function getDatabase(): TenantScopedDatabase | undefined;
+/**
+ * Sets AsyncLocalStorage context and runs fn with the adapter's tenant-scoped DB.
+ *
+ * (1) Sets AsyncLocalStorage context with tenantId and database.
+ * (2) Calls adapter.runWithTenant(tenantId, (database) => fn(database)).
+ * (3) Stores the database handle in context so getDatabase() returns it.
+ *
+ * Middleware should resolve tenantId from the request, then call
+ * runWithTenantAndDatabase(tenantId, adapter, next) so both context and DB handle are available.
+ *
+ * When options.loadTenant is true and options.getTenantRepository and adapter.runAsSystem are set,
+ * loads the full Tenant row into context so getContext().tenant is available (or undefined if not found).
+ */
+export declare function runWithTenantAndDatabase<T>(tenantId: string, adapter: TenantAdapter, fn: (database: TenantScopedDatabase) => Promise<T>, options?: RunWithTenantAndDatabaseOptions): Promise<T>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAEb,oBAAoB,EACpB,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAGpB;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,oBAAoB,GAAG,SAAS,CAG9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAAC,CAAC,CAAC,EAClD,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,CAAC,CAAC,CAgBZ"}

package/dist/api.d.ts

@@ -0,0 +1,33 @@
+import type { TenantAdapter, Tenant, SystemDatabase, TenantScopedDatabase, TenantRepository } from "./types.js";
+export interface CreateTenantData {
+    name: string;
+    slug: string;
+}
+export interface UpdateTenantData {
+    name?: string;
+    slug?: string;
+}
+export interface ListTenantsOptions {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Tenant CRUD API. All methods run via adapter.runAsSystem and getTenantRepository.
+ */
+export declare function createTenantApi(adapter: TenantAdapter, getTenantRepository: (database: SystemDatabase) => TenantRepository): {
+    createTenant(data: CreateTenantData): Promise<Tenant>;
+    updateTenant(tenantId: string, data: UpdateTenantData): Promise<Tenant>;
+    listTenants(options?: ListTenantsOptions): Promise<Tenant[]>;
+    deleteTenant(tenantId: string): Promise<void>;
+};
+/**
+ * runAs(tenantId, fn): same as request flow — set context + run inside adapter.runWithTenant
+ * so code can use getDatabase() and run tenant-scoped queries. Use for cron, per-tenant migrations.
+ */
+export declare function runAs<T>(tenantId: string, adapter: TenantAdapter, fn: (database: TenantScopedDatabase) => Promise<T>): Promise<T>;
+/**
+ * runAsSystem(fn): run fn with a DB handle that has RLS bypass.
+ * Optionally set context so getContext() reflects system mode.
+ */
+export declare function runAsSystem<T>(adapter: TenantAdapter, fn: (database: SystemDatabase) => Promise<T>): Promise<T>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EACN,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAOpB,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAwBD;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,aAAa,EACtB,mBAAmB,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,gBAAgB;uBAMxC,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;2BAgB/C,MAAM,QACV,gBAAgB,GACrB,OAAO,CAAC,MAAM,CAAC;0BAYS,kBAAkB,GAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;2BAWzC,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;EAStD;AAED;;;GAGG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAAC,CAAC,CAAC,GACjD,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3C,OAAO,CAAC,CAAC,CAAC,CAKZ"}

package/dist/better-tenant.d.ts

@@ -0,0 +1,40 @@
+import type { BetterTenantConfig, Tenant, ResolvableRequest, SystemDatabase } from "./types.js";
+import { getContext, runWithTenant } from "./context.js";
+import { getDatabase, runWithTenantAndDatabase } from "./adapter.js";
+import { type HandleRequestOptions } from "./handle-request.js";
+import { runAs } from "./api.js";
+export interface TenantApi {
+    createTenant(data: {
+        name: string;
+        slug: string;
+    }): Promise<Tenant>;
+    updateTenant(tenantId: string, data: {
+        name?: string;
+        slug?: string;
+    }): Promise<Tenant>;
+    listTenants(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Tenant[]>;
+    deleteTenant(tenantId: string): Promise<void>;
+}
+export interface BetterTenantInstance {
+    getContext: typeof getContext;
+    getDatabase: typeof getDatabase;
+    runWithTenant: typeof runWithTenant;
+    runWithTenantAndDatabase: typeof runWithTenantAndDatabase;
+    runAs: typeof runAs;
+    runAsSystem: <T>(fn: (database: SystemDatabase) => Promise<T>) => Promise<T>;
+    resolveTenant: (request: ResolvableRequest) => string | undefined;
+    resolveTenantAsync: (request: ResolvableRequest) => Promise<string | undefined>;
+    handleRequest: <Req extends ResolvableRequest, Result>(request: Req, next: () => Promise<Result>, options?: Omit<HandleRequestOptions<Req, Result>, "resolveTenant" | "adapter">) => Promise<Result>;
+    tenant: {
+        api: TenantApi;
+    };
+}
+/**
+ * Creates the Better Tenant instance. Config must include adapter and tenantResolver.
+ * When getTenantRepository is provided, tenant.api is available for CRUD on the tenants table.
+ */
+export declare function betterTenant(config: BetterTenantConfig): BetterTenantInstance;
+//# sourceMappingURL=better-tenant.d.ts.map

package/dist/better-tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-tenant.d.ts","sourceRoot":"","sources":["../src/better-tenant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,MAAM,EACN,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,EAEN,MAAM,UAAU,CAAC;AAGlB,MAAM,WAAW,SAAS;IACxB,YAAY,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACrC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,WAAW,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9E,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,WAAW,EAAE,OAAO,WAAW,CAAC;IAChC,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;IAC1D,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,aAAa,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,MAAM,GAAG,SAAS,CAAC;IAClE,kBAAkB,EAAE,CAClB,OAAO,EAAE,iBAAiB,KACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjC,aAAa,EAAE,CAAC,GAAG,SAAS,iBAAiB,EAAE,MAAM,EACnD,OAAO,EAAE,GAAG,EACZ,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,KAC3E,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,MAAM,EAAE;QAAE,GAAG,EAAE,SAAS,CAAA;KAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,oBAAoB,CAmC7E"}

package/dist/context.d.ts

@@ -0,0 +1,16 @@
+import type { TenantContext } from "./types.js";
+/**
+ * Returns the current tenant context, or undefined when not inside runWithTenant / runWithTenantAndDatabase.
+ */
+export declare function getContext(): TenantContext | undefined;
+/**
+ * Runs fn inside a scope where getContext() returns { tenantId }.
+ * No adapter/DB involved; use for tests or when adapter is not configured.
+ * If tenantId is empty string, it is treated as undefined (no tenant).
+ */
+export declare function runWithTenant<T>(tenantId: string, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Internal: set context with optional database handle. Used by runWithTenantAndDatabase.
+ */
+export declare function runWithContext<T>(context: TenantContext, fn: () => T | Promise<T>): Promise<T>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD;;GAEG;AACH,wBAAgB,UAAU,IAAI,aAAa,GAAG,SAAS,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAEZ"}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class TenantNotResolvedError extends Error {
+    constructor(message?: string);
+}
+export declare class TenantMiddlewareError extends Error {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,SAA6D;CAIjF;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAE5C,OAAO,SAAmD,EAC1D,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhC"}

package/dist/handle-request.d.ts

@@ -0,0 +1,17 @@
+import type { TenantAdapter } from "./types.js";
+type MaybePromise<T> = T | Promise<T>;
+export interface HandleRequestOptions<Req, Result> {
+    resolveTenant: (request: Req) => MaybePromise<string | undefined>;
+    adapter: TenantAdapter;
+    onMissingTenant?: (request: Req) => MaybePromise<Result>;
+    onError?: (error: unknown, request: Req) => MaybePromise<Result>;
+}
+/**
+ * Generic request helper for framework adapters.
+ *
+ * It resolves a tenant id from the framework request, then runs the request handler
+ * inside runWithTenantAndDatabase so both getContext() and getDatabase() are available.
+ */
+export declare function handleRequest<Req, Result>(request: Req, next: () => Promise<Result>, options: HandleRequestOptions<Req, Result>): Promise<Result>;
+export {};
+//# sourceMappingURL=handle-request.d.ts.map

package/dist/handle-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-request.d.ts","sourceRoot":"","sources":["../src/handle-request.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,oBAAoB,CAAC,GAAG,EAAE,MAAM;IAC/C,aAAa,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,YAAY,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAClE,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,YAAY,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK,YAAY,CAAC,MAAM,CAAC,CAAC;CAClE;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAC7C,OAAO,EAAE,GAAG,EACZ,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3B,OAAO,EAAE,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,GACzC,OAAO,CAAC,MAAM,CAAC,CAmCjB"}