@constructive-io/express-context 0.4.0 → 0.6.0

package/README.md

@@ -136,6 +136,21 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
 * [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
 * [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
 
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
 ## Credits
 
 **🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**

package/billing-client.d.ts

@@ -0,0 +1,56 @@
+/**
+ * billing-client — Shared billing operations for any Express-based service
+ *
+ * Provides a unified `BillingClient` that encapsulates:
+ *   - `checkQuota(meterSlug, amount)` — pre-check billing quota
+ *   - `recordUsage(meterSlug, amount, metadata)` — post-record usage
+ *   - `logInference(entry)` — write to usage_log_inference table
+ *
+ * Both `agentic-server` and `graphile-llm` should delegate to this client
+ * instead of implementing their own SQL calls.
+ *
+ * Graceful: all operations are no-ops if the billing/inference_log modules
+ * are not provisioned. Errors are logged and swallowed (non-fatal).
+ */
+import type { BillingConfig, InferenceLogConfig, WithPgClient } from './types';
+export interface InferenceLogEntry {
+    entityId: string;
+    actorId: string | null;
+    model: string;
+    provider: string | null;
+    service: string;
+    operation: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    latencyMs: number;
+    status: string;
+    cacheReadTokens?: number | null;
+    cacheWriteTokens?: number | null;
+    ragEnabled?: boolean;
+    chunksRetrieved?: number | null;
+    embeddingModel?: string | null;
+    embeddingLatencyMs?: number | null;
+    errorType?: string | null;
+    rawUsage?: Record<string, unknown> | null;
+}
+export interface BillingClient {
+    /**
+     * Check if the entity has sufficient quota for the requested amount.
+     * Returns true if allowed, false if quota is exceeded.
+     *
+     * Gracefully returns true if billing is not provisioned or errors.
+     */
+    checkQuota(meterSlug: string, amount?: number): Promise<boolean>;
+    /**
+     * Record usage after a successful operation.
+     * Gracefully skips if billing is not provisioned or errors.
+     */
+    recordUsage(meterSlug: string, amount: number, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Write a row to the usage_log_inference table.
+     * Gracefully skips if inference_log_module is not provisioned or errors.
+     */
+    logInference(entry: InferenceLogEntry): Promise<void>;
+}
+export declare function createBillingClient(withPgClient: WithPgClient, entityId: string, billing: BillingConfig | null, inferenceLog: InferenceLogConfig | null): BillingClient;

package/billing-client.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * billing-client — Shared billing operations for any Express-based service
+ *
+ * Provides a unified `BillingClient` that encapsulates:
+ *   - `checkQuota(meterSlug, amount)` — pre-check billing quota
+ *   - `recordUsage(meterSlug, amount, metadata)` — post-record usage
+ *   - `logInference(entry)` — write to usage_log_inference table
+ *
+ * Both `agentic-server` and `graphile-llm` should delegate to this client
+ * instead of implementing their own SQL calls.
+ *
+ * Graceful: all operations are no-ops if the billing/inference_log modules
+ * are not provisioned. Errors are logged and swallowed (non-fatal).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBillingClient = createBillingClient;
+const logger_1 = require("@pgpmjs/logger");
+const log = new logger_1.Logger('billing-client');
+// ─── Implementation ─────────────────────────────────────────────────────────
+function createBillingClient(withPgClient, entityId, billing, inferenceLog) {
+    return {
+        async checkQuota(meterSlug, amount = 1) {
+            if (!billing)
+                return true;
+            try {
+                return await withPgClient(async (client) => {
+                    const sql = `SELECT "${billing.privateSchema}"."${billing.checkBillingQuotaFunction}"($1, $2::uuid, $3) AS allowed`;
+                    const result = await client.query(sql, [meterSlug, entityId, amount]);
+                    return result.rows[0]?.allowed !== false;
+                });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                log.warn(`check_billing_quota failed (allowing): ${message}`);
+                return true;
+            }
+        },
+        async recordUsage(meterSlug, amount, metadata) {
+            if (!billing)
+                return;
+            try {
+                await withPgClient(async (client) => {
+                    const sql = `SELECT "${billing.privateSchema}"."${billing.recordUsageFunction}"($1, $2::uuid, $3, $4::jsonb)`;
+                    await client.query(sql, [meterSlug, entityId, amount, JSON.stringify(metadata ?? {})]);
+                });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                log.warn(`record_usage failed (non-fatal): ${message}`);
+            }
+        },
+        async logInference(entry) {
+            if (!inferenceLog)
+                return;
+            try {
+                await withPgClient(async (client) => {
+                    await client.query(`INSERT INTO "${inferenceLog.schema}"."${inferenceLog.tableName}"
+             (entity_id, actor_id, model, provider, service, operation,
+              input_tokens, output_tokens, total_tokens, latency_ms, status,
+              cache_read_tokens, cache_write_tokens,
+              rag_enabled, chunks_retrieved,
+              embedding_model, embedding_latency_ms,
+              error_type, raw_usage)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19)`, [
+                        entry.entityId, entry.actorId, entry.model,
+                        entry.provider, entry.service, entry.operation,
+                        entry.inputTokens, entry.outputTokens, entry.totalTokens,
+                        entry.latencyMs, entry.status,
+                        entry.cacheReadTokens ?? null, entry.cacheWriteTokens ?? null,
+                        entry.ragEnabled ?? false, entry.chunksRetrieved ?? null,
+                        entry.embeddingModel ?? null, entry.embeddingLatencyMs ?? null,
+                        entry.errorType ?? null,
+                        entry.rawUsage ? JSON.stringify(entry.rawUsage) : null
+                    ]);
+                });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                log.warn(`inference log INSERT failed (non-fatal): ${message}`);
+            }
+        }
+    };
+}

package/context.d.ts

@@ -13,8 +13,8 @@
  * The result is a single `req.constructive` object that any downstream
  * route handler can use for tenant-scoped database operations.
  */
-import type { Request, RequestHandler } from 'express';
 import type { PgpmOptions } from '@pgpmjs/types';
+import type { Request, RequestHandler } from 'express';
 import type { LoaderRegistry } from './loaders/registry';
 import type { ConstructiveContext } from './types';
 export interface ContextMiddlewareOptions {

package/context.js

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildContext = buildContext;
 exports.createContextMiddleware = createContextMiddleware;
 const pg_cache_1 = require("pg-cache");
+const billing_client_1 = require("./billing-client");
 const pg_client_1 = require("./pg-client");
 const pg_settings_1 = require("./pg-settings");
 /**
@@ -54,11 +55,11 @@ function buildContext(req, opts = {}) {
         api,
         token,
         requestId,
-        clientIp: req.clientIp,
+        clientIp: req.clientIp
     });
     const tenantPool = (0, pg_cache_1.getPgPool)({
         ...opts.pg,
-        database: api.dbname,
+        database: api.dbname
     });
     // Build loader context (if registry provided and databaseId known)
     let loaderCtx = null;
@@ -69,9 +70,15 @@ function buildContext(req, opts = {}) {
             tenantPool,
             databaseId: api.databaseId,
             apiId: api.apiId,
-            dbname: api.dbname,
+            dbname: api.dbname
         };
     }
+    const withPgClient = (fn) => (0, pg_client_1.withPgClient)(tenantPool, pgSettings, fn);
+    const useModule = createUseModule(opts.loaders, loaderCtx);
+    // Lazy-initialized billing client (cached per request)
+    let billingClient;
+    // Lazy-initialized LLM config (cached per request)
+    let llmConfig;
     return {
         api,
         token,
@@ -80,8 +87,34 @@ function buildContext(req, opts = {}) {
         userId: token?.user_id ?? null,
         requestId,
         pool: tenantPool,
-        withPgClient: (fn) => (0, pg_client_1.withPgClient)(tenantPool, pgSettings, fn),
-        useModule: createUseModule(opts.loaders, loaderCtx),
+        withPgClient,
+        useModule,
+        async useBilling() {
+            if (billingClient !== undefined)
+                return billingClient;
+            const entityId = token?.entity_id;
+            if (!entityId) {
+                billingClient = null;
+                return null;
+            }
+            const [billing, inferenceLog] = await Promise.all([
+                useModule('billing'),
+                useModule('inferenceLog')
+            ]);
+            if (!billing) {
+                billingClient = null;
+                return null;
+            }
+            billingClient = (0, billing_client_1.createBillingClient)(withPgClient, entityId, billing, inferenceLog ?? null);
+            return billingClient;
+        },
+        async useLlm() {
+            if (llmConfig !== undefined)
+                return llmConfig;
+            const resolved = await useModule('llm');
+            llmConfig = resolved ?? null;
+            return llmConfig;
+        }
     };
 }
 /**

package/esm/billing-client.js

@@ -0,0 +1,81 @@
+/**
+ * billing-client — Shared billing operations for any Express-based service
+ *
+ * Provides a unified `BillingClient` that encapsulates:
+ *   - `checkQuota(meterSlug, amount)` — pre-check billing quota
+ *   - `recordUsage(meterSlug, amount, metadata)` — post-record usage
+ *   - `logInference(entry)` — write to usage_log_inference table
+ *
+ * Both `agentic-server` and `graphile-llm` should delegate to this client
+ * instead of implementing their own SQL calls.
+ *
+ * Graceful: all operations are no-ops if the billing/inference_log modules
+ * are not provisioned. Errors are logged and swallowed (non-fatal).
+ */
+import { Logger } from '@pgpmjs/logger';
+const log = new Logger('billing-client');
+// ─── Implementation ─────────────────────────────────────────────────────────
+export function createBillingClient(withPgClient, entityId, billing, inferenceLog) {
+    return {
+        async checkQuota(meterSlug, amount = 1) {
+            if (!billing)
+                return true;
+            try {
+                return await withPgClient(async (client) => {
+                    const sql = `SELECT "${billing.privateSchema}"."${billing.checkBillingQuotaFunction}"($1, $2::uuid, $3) AS allowed`;
+                    const result = await client.query(sql, [meterSlug, entityId, amount]);
+                    return result.rows[0]?.allowed !== false;
+                });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                log.warn(`check_billing_quota failed (allowing): ${message}`);
+                return true;
+            }
+        },
+        async recordUsage(meterSlug, amount, metadata) {
+            if (!billing)
+                return;
+            try {
+                await withPgClient(async (client) => {
+                    const sql = `SELECT "${billing.privateSchema}"."${billing.recordUsageFunction}"($1, $2::uuid, $3, $4::jsonb)`;
+                    await client.query(sql, [meterSlug, entityId, amount, JSON.stringify(metadata ?? {})]);
+                });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                log.warn(`record_usage failed (non-fatal): ${message}`);
+            }
+        },
+        async logInference(entry) {
+            if (!inferenceLog)
+                return;
+            try {
+                await withPgClient(async (client) => {
+                    await client.query(`INSERT INTO "${inferenceLog.schema}"."${inferenceLog.tableName}"
+             (entity_id, actor_id, model, provider, service, operation,
+              input_tokens, output_tokens, total_tokens, latency_ms, status,
+              cache_read_tokens, cache_write_tokens,
+              rag_enabled, chunks_retrieved,
+              embedding_model, embedding_latency_ms,
+              error_type, raw_usage)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19)`, [
+                        entry.entityId, entry.actorId, entry.model,
+                        entry.provider, entry.service, entry.operation,
+                        entry.inputTokens, entry.outputTokens, entry.totalTokens,
+                        entry.latencyMs, entry.status,
+                        entry.cacheReadTokens ?? null, entry.cacheWriteTokens ?? null,
+                        entry.ragEnabled ?? false, entry.chunksRetrieved ?? null,
+                        entry.embeddingModel ?? null, entry.embeddingLatencyMs ?? null,
+                        entry.errorType ?? null,
+                        entry.rawUsage ? JSON.stringify(entry.rawUsage) : null
+                    ]);
+                });
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                log.warn(`inference log INSERT failed (non-fatal): ${message}`);
+            }
+        }
+    };
+}

package/esm/context.js

@@ -14,6 +14,7 @@
  * route handler can use for tenant-scoped database operations.
  */
 import { getPgPool } from 'pg-cache';
+import { createBillingClient } from './billing-client';
 import { withPgClient as withPgClientFn } from './pg-client';
 import { buildPgSettings } from './pg-settings';
 /**
@@ -50,11 +51,11 @@ export function buildContext(req, opts = {}) {
         api,
         token,
         requestId,
-        clientIp: req.clientIp,
+        clientIp: req.clientIp
     });
     const tenantPool = getPgPool({
         ...opts.pg,
-        database: api.dbname,
+        database: api.dbname
     });
     // Build loader context (if registry provided and databaseId known)
     let loaderCtx = null;
@@ -65,9 +66,15 @@ export function buildContext(req, opts = {}) {
             tenantPool,
             databaseId: api.databaseId,
             apiId: api.apiId,
-            dbname: api.dbname,
+            dbname: api.dbname
         };
     }
+    const withPgClient = (fn) => withPgClientFn(tenantPool, pgSettings, fn);
+    const useModule = createUseModule(opts.loaders, loaderCtx);
+    // Lazy-initialized billing client (cached per request)
+    let billingClient;
+    // Lazy-initialized LLM config (cached per request)
+    let llmConfig;
     return {
         api,
         token,
@@ -76,8 +83,34 @@ export function buildContext(req, opts = {}) {
         userId: token?.user_id ?? null,
         requestId,
         pool: tenantPool,
-        withPgClient: (fn) => withPgClientFn(tenantPool, pgSettings, fn),
-        useModule: createUseModule(opts.loaders, loaderCtx),
+        withPgClient,
+        useModule,
+        async useBilling() {
+            if (billingClient !== undefined)
+                return billingClient;
+            const entityId = token?.entity_id;
+            if (!entityId) {
+                billingClient = null;
+                return null;
+            }
+            const [billing, inferenceLog] = await Promise.all([
+                useModule('billing'),
+                useModule('inferenceLog')
+            ]);
+            if (!billing) {
+                billingClient = null;
+                return null;
+            }
+            billingClient = createBillingClient(withPgClient, entityId, billing, inferenceLog ?? null);
+            return billingClient;
+        },
+        async useLlm() {
+            if (llmConfig !== undefined)
+                return llmConfig;
+            const resolved = await useModule('llm');
+            llmConfig = resolved ?? null;
+            return llmConfig;
+        }
     };
 }
 /**

package/esm/index.js

@@ -34,12 +34,13 @@
  * });
  * ```
  */
+export { createBillingClient } from './billing-client';
 export { buildPgSettings } from './pg-settings';
 // withPgClient helper
 export { withPgClient } from './pg-client';
 // Request ID middleware
 export { requestIdMiddleware } from './request-id';
 export { buildContext, createContextMiddleware } from './context';
-export { agentChatLoader, authSettingsLoader, billingLoader, corsLoader, createDefaultRegistry, createLoaderRegistry, createModuleLoader, databaseSettingsLoader, inferenceLogLoader, pubkeyLoader, rlsLoader, webauthnLoader, } from './loaders';
+export { agentChatLoader, authSettingsLoader, billingLoader, corsLoader, createDefaultRegistry, createLoaderRegistry, createModuleLoader, databaseSettingsLoader, inferenceLogLoader, pubkeyLoader, rlsLoader, llmLoader, webauthnLoader, } from './loaders';
 // Side-effect: Express type augmentation
 import './types';

package/esm/loaders/database-settings.js

@@ -19,7 +19,8 @@ const DATABASE_SETTINGS_SQL = `
     COALESCE(aps.enable_ltree, ds.enable_ltree) AS resolved_enable_ltree,
     COALESCE(aps.enable_llm, ds.enable_llm) AS resolved_enable_llm,
     COALESCE(aps.enable_realtime, ds.enable_realtime) AS resolved_enable_realtime,
-    COALESCE(aps.enable_bulk, ds.enable_bulk) AS resolved_enable_bulk
+    COALESCE(aps.enable_bulk, ds.enable_bulk) AS resolved_enable_bulk,
+    COALESCE(aps.enable_i18n, ds.enable_i18n) AS resolved_enable_i18n
   FROM services_public.database_settings ds
   LEFT JOIN services_public.api_settings aps ON ds.database_id = aps.database_id AND aps.api_id = $2
   WHERE ds.database_id = $1
@@ -47,6 +48,7 @@ export const databaseSettingsLoader = createModuleLoader({
             enableLlm: row.resolved_enable_llm,
             enableRealtime: row.resolved_enable_realtime,
             enableBulk: row.resolved_enable_bulk,
+            enableI18n: row.resolved_enable_i18n,
         };
     },
 });

package/esm/loaders/index.js

@@ -37,6 +37,7 @@ export { authSettingsLoader } from './auth-settings';
 export { billingLoader } from './billing';
 export { inferenceLogLoader } from './inference-log';
 export { agentChatLoader } from './agent-chat';
+export { llmLoader } from './llm';
 /**
  * Convenience: create a registry pre-loaded with all built-in loaders.
  */
@@ -50,6 +51,7 @@ import { authSettingsLoader } from './auth-settings';
 import { billingLoader } from './billing';
 import { inferenceLogLoader } from './inference-log';
 import { agentChatLoader } from './agent-chat';
+import { llmLoader } from './llm';
 export function createDefaultRegistry() {
     const registry = createLoaderRegistry();
     registry.register(rlsLoader);
@@ -61,5 +63,6 @@ export function createDefaultRegistry() {
     registry.register(billingLoader);
     registry.register(inferenceLogLoader);
     registry.register(agentChatLoader);
+    registry.register(llmLoader);
     return registry;
 }

package/esm/loaders/llm.js

@@ -0,0 +1,51 @@
+/**
+ * LLM Module Loader
+ *
+ * Resolves per-database LLM provider config from metaschema_modules_public.llm_module.
+ * Returns embedding and chat provider settings (model, base URL, dimensions, limits).
+ *
+ * When the llm_module table doesn't exist yet (pre-migration), the loader
+ * gracefully returns undefined — callers fall back to env vars.
+ */
+import { createModuleLoader } from './create-loader';
+// ─── SQL ────────────────────────────────────────────────────────────────────
+const LLM_MODULE_SQL = `
+  SELECT
+    lm.embedding_provider,
+    lm.embedding_model,
+    lm.embedding_base_url,
+    lm.embedding_dimensions,
+    lm.chat_provider,
+    lm.chat_model,
+    lm.chat_base_url,
+    lm.rate_limit_rpm,
+    lm.max_tokens_per_request,
+    lm.rag_context_limit
+  FROM metaschema_modules_public.llm_module lm
+  WHERE lm.database_id = $1
+  LIMIT 1
+`;
+// ─── Loader ─────────────────────────────────────────────────────────────────
+export const llmLoader = createModuleLoader({
+    name: 'llm',
+    ttlMs: 5 * 60_000,
+    async resolve(ctx) {
+        const { tenantPool, databaseId } = ctx;
+        const result = await tenantPool.query(LLM_MODULE_SQL, [databaseId]);
+        const row = result.rows[0];
+        if (!row)
+            return undefined;
+        return {
+            embeddingProvider: row.embedding_provider,
+            embeddingModel: row.embedding_model,
+            embeddingBaseUrl: row.embedding_base_url,
+            embeddingDimensions: row.embedding_dimensions,
+            chatProvider: row.chat_provider,
+            chatModel: row.chat_model,
+            chatBaseUrl: row.chat_base_url,
+            rateLimitRpm: row.rate_limit_rpm,
+            maxTokensPerRequest: row.max_tokens_per_request,
+            ragContextLimit: row.rag_context_limit,
+        };
+    },
+});

package/index.d.ts

@@ -34,7 +34,9 @@
  * });
  * ```
  */
-export type { AgentChatConfig, ApiConfigResult, ApiError, ApiModule, ApiStructure, AuthSettings, BillingConfig, BuiltinModuleMap, ConstructiveAPIToken, ConstructiveContext, CorsModuleData, DatabaseSettings, GenericModuleData, InferenceLogConfig, PublicKeyChallengeData, PubkeyChallengeSettings, RlsModule, WebauthnSettings, WithPgClient, } from './types';
+export type { AgentChatConfig, ApiConfigResult, ApiError, ApiModule, ApiStructure, AuthSettings, BillingConfig, BuiltinModuleMap, ConstructiveAPIToken, ConstructiveContext, CorsModuleData, DatabaseSettings, GenericModuleData, InferenceLogConfig, LlmConfig, PublicKeyChallengeData, PubkeyChallengeSettings, RlsModule, WebauthnSettings, WithPgClient, } from './types';
+export type { BillingClient, InferenceLogEntry } from './billing-client';
+export { createBillingClient } from './billing-client';
 export type { PgSettingsInput } from './pg-settings';
 export { buildPgSettings } from './pg-settings';
 export { withPgClient } from './pg-client';
@@ -42,5 +44,5 @@ export { requestIdMiddleware } from './request-id';
 export type { ContextMiddlewareOptions } from './context';
 export { buildContext, createContextMiddleware } from './context';
 export type { CreateLoaderOptions, LoaderContext, LoaderRegistry, ModuleLoader, } from './loaders';
-export { agentChatLoader, authSettingsLoader, billingLoader, corsLoader, createDefaultRegistry, createLoaderRegistry, createModuleLoader, databaseSettingsLoader, inferenceLogLoader, pubkeyLoader, rlsLoader, webauthnLoader, } from './loaders';
+export { agentChatLoader, authSettingsLoader, billingLoader, corsLoader, createDefaultRegistry, createLoaderRegistry, createModuleLoader, databaseSettingsLoader, inferenceLogLoader, pubkeyLoader, rlsLoader, llmLoader, webauthnLoader, } from './loaders';
 import './types';

package/index.js

@@ -36,7 +36,9 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.webauthnLoader = exports.rlsLoader = exports.pubkeyLoader = exports.inferenceLogLoader = exports.databaseSettingsLoader = exports.createModuleLoader = exports.createLoaderRegistry = exports.createDefaultRegistry = exports.corsLoader = exports.billingLoader = exports.authSettingsLoader = exports.agentChatLoader = exports.createContextMiddleware = exports.buildContext = exports.requestIdMiddleware = exports.withPgClient = exports.buildPgSettings = void 0;
+exports.webauthnLoader = exports.llmLoader = exports.rlsLoader = exports.pubkeyLoader = exports.inferenceLogLoader = exports.databaseSettingsLoader = exports.createModuleLoader = exports.createLoaderRegistry = exports.createDefaultRegistry = exports.corsLoader = exports.billingLoader = exports.authSettingsLoader = exports.agentChatLoader = exports.createContextMiddleware = exports.buildContext = exports.requestIdMiddleware = exports.withPgClient = exports.buildPgSettings = exports.createBillingClient = void 0;
+var billing_client_1 = require("./billing-client");
+Object.defineProperty(exports, "createBillingClient", { enumerable: true, get: function () { return billing_client_1.createBillingClient; } });
 var pg_settings_1 = require("./pg-settings");
 Object.defineProperty(exports, "buildPgSettings", { enumerable: true, get: function () { return pg_settings_1.buildPgSettings; } });
 // withPgClient helper
@@ -60,6 +62,7 @@ Object.defineProperty(exports, "databaseSettingsLoader", { enumerable: true, get
 Object.defineProperty(exports, "inferenceLogLoader", { enumerable: true, get: function () { return loaders_1.inferenceLogLoader; } });
 Object.defineProperty(exports, "pubkeyLoader", { enumerable: true, get: function () { return loaders_1.pubkeyLoader; } });
 Object.defineProperty(exports, "rlsLoader", { enumerable: true, get: function () { return loaders_1.rlsLoader; } });
+Object.defineProperty(exports, "llmLoader", { enumerable: true, get: function () { return loaders_1.llmLoader; } });
 Object.defineProperty(exports, "webauthnLoader", { enumerable: true, get: function () { return loaders_1.webauthnLoader; } });
 // Side-effect: Express type augmentation
 require("./types");

package/loaders/database-settings.js

@@ -22,7 +22,8 @@ const DATABASE_SETTINGS_SQL = `
     COALESCE(aps.enable_ltree, ds.enable_ltree) AS resolved_enable_ltree,
     COALESCE(aps.enable_llm, ds.enable_llm) AS resolved_enable_llm,
     COALESCE(aps.enable_realtime, ds.enable_realtime) AS resolved_enable_realtime,
-    COALESCE(aps.enable_bulk, ds.enable_bulk) AS resolved_enable_bulk
+    COALESCE(aps.enable_bulk, ds.enable_bulk) AS resolved_enable_bulk,
+    COALESCE(aps.enable_i18n, ds.enable_i18n) AS resolved_enable_i18n
   FROM services_public.database_settings ds
   LEFT JOIN services_public.api_settings aps ON ds.database_id = aps.database_id AND aps.api_id = $2
   WHERE ds.database_id = $1
@@ -50,6 +51,7 @@ exports.databaseSettingsLoader = (0, create_loader_1.createModuleLoader)({
             enableLlm: row.resolved_enable_llm,
             enableRealtime: row.resolved_enable_realtime,
             enableBulk: row.resolved_enable_bulk,
+            enableI18n: row.resolved_enable_i18n,
         };
     },
 });

package/loaders/index.d.ts

@@ -39,4 +39,5 @@ export { authSettingsLoader } from './auth-settings';
 export { billingLoader } from './billing';
 export { inferenceLogLoader } from './inference-log';
 export { agentChatLoader } from './agent-chat';
+export { llmLoader } from './llm';
 export declare function createDefaultRegistry(): import("./registry").LoaderRegistry;

package/loaders/index.js

@@ -27,7 +27,7 @@
  *   registry.register(myLoader);
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agentChatLoader = exports.inferenceLogLoader = exports.billingLoader = exports.authSettingsLoader = exports.webauthnLoader = exports.pubkeyLoader = exports.databaseSettingsLoader = exports.corsLoader = exports.rlsLoader = exports.createLoaderRegistry = exports.createModuleLoader = void 0;
+exports.llmLoader = exports.agentChatLoader = exports.inferenceLogLoader = exports.billingLoader = exports.authSettingsLoader = exports.webauthnLoader = exports.pubkeyLoader = exports.databaseSettingsLoader = exports.corsLoader = exports.rlsLoader = exports.createLoaderRegistry = exports.createModuleLoader = void 0;
 exports.createDefaultRegistry = createDefaultRegistry;
 var create_loader_1 = require("./create-loader");
 Object.defineProperty(exports, "createModuleLoader", { enumerable: true, get: function () { return create_loader_1.createModuleLoader; } });
@@ -52,6 +52,8 @@ var inference_log_1 = require("./inference-log");
 Object.defineProperty(exports, "inferenceLogLoader", { enumerable: true, get: function () { return inference_log_1.inferenceLogLoader; } });
 var agent_chat_1 = require("./agent-chat");
 Object.defineProperty(exports, "agentChatLoader", { enumerable: true, get: function () { return agent_chat_1.agentChatLoader; } });
+var llm_1 = require("./llm");
+Object.defineProperty(exports, "llmLoader", { enumerable: true, get: function () { return llm_1.llmLoader; } });
 /**
  * Convenience: create a registry pre-loaded with all built-in loaders.
  */
@@ -65,6 +67,7 @@ const auth_settings_2 = require("./auth-settings");
 const billing_2 = require("./billing");
 const inference_log_2 = require("./inference-log");
 const agent_chat_2 = require("./agent-chat");
+const llm_2 = require("./llm");
 function createDefaultRegistry() {
     const registry = (0, registry_2.createLoaderRegistry)();
     registry.register(rls_2.rlsLoader);
@@ -76,5 +79,6 @@ function createDefaultRegistry() {
     registry.register(billing_2.billingLoader);
     registry.register(inference_log_2.inferenceLogLoader);
     registry.register(agent_chat_2.agentChatLoader);
+    registry.register(llm_2.llmLoader);
     return registry;
 }

package/loaders/llm.d.ts

@@ -0,0 +1,12 @@
+/**
+ * LLM Module Loader
+ *
+ * Resolves per-database LLM provider config from metaschema_modules_public.llm_module.
+ * Returns embedding and chat provider settings (model, base URL, dimensions, limits).
+ *
+ * When the llm_module table doesn't exist yet (pre-migration), the loader
+ * gracefully returns undefined — callers fall back to env vars.
+ */
+import type { LlmConfig } from '../types';
+import type { ModuleLoader } from './types';
+export declare const llmLoader: ModuleLoader<LlmConfig>;

package/loaders/llm.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * LLM Module Loader
+ *
+ * Resolves per-database LLM provider config from metaschema_modules_public.llm_module.
+ * Returns embedding and chat provider settings (model, base URL, dimensions, limits).
+ *
+ * When the llm_module table doesn't exist yet (pre-migration), the loader
+ * gracefully returns undefined — callers fall back to env vars.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.llmLoader = void 0;
+const create_loader_1 = require("./create-loader");
+// ─── SQL ────────────────────────────────────────────────────────────────────
+const LLM_MODULE_SQL = `
+  SELECT
+    lm.embedding_provider,
+    lm.embedding_model,
+    lm.embedding_base_url,
+    lm.embedding_dimensions,
+    lm.chat_provider,
+    lm.chat_model,
+    lm.chat_base_url,
+    lm.rate_limit_rpm,
+    lm.max_tokens_per_request,
+    lm.rag_context_limit
+  FROM metaschema_modules_public.llm_module lm
+  WHERE lm.database_id = $1
+  LIMIT 1
+`;
+// ─── Loader ─────────────────────────────────────────────────────────────────
+exports.llmLoader = (0, create_loader_1.createModuleLoader)({
+    name: 'llm',
+    ttlMs: 5 * 60_000,
+    async resolve(ctx) {
+        const { tenantPool, databaseId } = ctx;
+        const result = await tenantPool.query(LLM_MODULE_SQL, [databaseId]);
+        const row = result.rows[0];
+        if (!row)
+            return undefined;
+        return {
+            embeddingProvider: row.embedding_provider,
+            embeddingModel: row.embedding_model,
+            embeddingBaseUrl: row.embedding_base_url,
+            embeddingDimensions: row.embedding_dimensions,
+            chatProvider: row.chat_provider,
+            chatModel: row.chat_model,
+            chatBaseUrl: row.chat_base_url,
+            rateLimitRpm: row.rate_limit_rpm,
+            maxTokensPerRequest: row.max_tokens_per_request,
+            ragContextLimit: row.rag_context_limit,
+        };
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/express-context",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Extractable Express middleware for Constructive tenant context — domain resolution, JWT auth, pgSettings, and withPgClient",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -59,5 +59,5 @@
     "jwt",
     "pgSettings"
   ],
-  "gitHead": "0503916f414a3b8a6f6cbe46e03a59988b2f3cb5"
+  "gitHead": "16c2ae1c30850db1d71c021346c9d34361361d8e"
 }

package/types.d.ts

@@ -7,6 +7,7 @@
  * (PostGraphile, LLM sidecar, etc.) can share the same context.
  */
 import type { Pool, PoolClient } from 'pg';
+import type { BillingClient } from './billing-client';
 export interface CorsModuleData {
     urls: string[];
 }
@@ -33,6 +34,7 @@ export interface DatabaseSettings {
     enableLlm: boolean;
     enableRealtime: boolean;
     enableBulk: boolean;
+    enableI18n: boolean;
 }
 export interface PubkeyChallengeSettings {
     schema: string;
@@ -135,6 +137,18 @@ export interface AgentChatConfig {
     messageTableName: string | null;
     taskTableName: string | null;
 }
+export interface LlmConfig {
+    embeddingProvider: string;
+    embeddingModel: string;
+    embeddingBaseUrl: string;
+    embeddingDimensions: number | null;
+    chatProvider: string | null;
+    chatModel: string | null;
+    chatBaseUrl: string | null;
+    rateLimitRpm: number | null;
+    maxTokensPerRequest: number | null;
+    ragContextLimit: number | null;
+}
 /**
  * Maps built-in loader names to their resolved types.
  *
@@ -153,6 +167,7 @@ export interface BuiltinModuleMap {
     billing: BillingConfig;
     inferenceLog: InferenceLogConfig;
     agentChat: AgentChatConfig;
+    llm: LlmConfig;
 }
 /**
  * Callback for executing queries within a tenant-scoped transaction
@@ -202,6 +217,28 @@ export interface ConstructiveContext {
         <K extends keyof BuiltinModuleMap>(name: K): Promise<BuiltinModuleMap[K] | undefined>;
         (name: string): Promise<unknown>;
     };
+    /**
+     * Resolve a shared BillingClient bound to this request's entity.
+     *
+     * Returns a BillingClient with `checkQuota`, `recordUsage`, and
+     * `logInference` methods. Returns null if billing_module is not
+     * provisioned for this database or if no entity ID is available.
+     *
+     * Lazy: only resolves billing/inferenceLog loaders on first call.
+     * Cached: subsequent calls return the same client instance.
+     */
+    useBilling(): Promise<BillingClient | null>;
+    /**
+     * Resolve per-database LLM provider config.
+     *
+     * Returns the resolved LlmConfig from the llm_module table, or null
+     * if the module is not provisioned for this database. Callers should
+     * fall back to environment variables when null.
+     *
+     * Lazy: only resolves the llm loader on first call.
+     * Cached: subsequent calls return the same config instance.
+     */
+    useLlm(): Promise<LlmConfig | null>;
 }
 declare global {
     namespace Express {