@venturekit-pro/tenancy

Warning: This package is in active development and not production-ready. APIs may change without notice.

Multi-tenant utilities for VentureKit — tenant resolution, context management, data isolation, and quota enforcement.

Installation

npm install @venturekit-pro/tenancy@dev

Overview

@venturekit-pro/tenancy provides:

• Tenant resolution — resolve tenants from subdomain, custom domain, path, header, or JWT
• Tenant context — createTenantContext(), getCurrentTenant(), resolveTenant()
• Tenant middleware — createTenantMiddleware() for automatic tenant resolution per request
• Quota enforcement — createQuotaMiddleware(), checkQuotas() for usage limits
• Error types — TenantNotFoundError, TenantSuspendedError, TenantInactiveError, QuotaExceededError

Tenant Resolution

VentureKit supports multiple strategies for identifying the current tenant:

| Strategy | Example | |----------|---------| | Subdomain | acme.app.example.com → tenant acme | | Custom domain | app.acme.com → lookup in domain table | | Path prefix | /t/acme/api/tasks → tenant acme | | Header | X-Tenant-ID: acme | | JWT claim | tenant_id claim in access token |

Middleware

Add tenant resolution to your handlers:

import { createTenantMiddleware, createQuotaMiddleware } from '@venturekit-pro/tenancy';
import { handler } from '@venturekit/runtime';

export const main = handler(async (_body, ctx, logger) => {
  logger.info('Current tenant', { tenantId: ctx.tenant?.id });
  return { tenantId: ctx.tenant?.id };
}, {
  scopes: ['api.read'],
  middleware: [
    createTenantMiddleware({ strategy: 'subdomain' }),
    createQuotaMiddleware(),
  ],
});

Quota Enforcement

Define per-tenant quotas and enforce them automatically:

import { checkQuotas } from '@venturekit-pro/tenancy';

// Throws QuotaExceededError if over limit
await checkQuotas(tenantId, {
  apiRequests: { limit: 10000, period: 'month' },
  storage: { limit: 5_000_000_000 }, // 5 GB
});

Context

Access the current tenant anywhere in your handler:

import { getCurrentTenant } from '@venturekit-pro/tenancy';

const tenant = getCurrentTenant(ctx);
// { id: 'acme', slug: 'acme', metadata: { ... } }

API Reference

See the API reference for full documentation.

License

Apache-2.0 — see LICENSE for details.