@taodigital/app-brain 0.0.0-stage → 1.2.0

package/dist/cloud-storage.js

@@ -0,0 +1,539 @@
+"use strict";
+/**
+ * Cloud Storage integration for ZeTa-AI artifacts.
+ *
+ * Folder convention:
+ *   {prefix}/{tenantId}/{projectId}/screenshots/{filename}
+ *   {prefix}/{tenantId}/{projectId}/test-plans/{filename}
+ *   {prefix}/{tenantId}/{projectId}/test-data/{filename}
+ *   {prefix}/{tenantId}/{projectId}/reports/{runId}/{filename}
+ *
+ * Industry reference: Playwright Cloud, BrowserStack, Cypress Cloud all use
+ * tenant→project→type→artifact path hierarchies for multi-tenant isolation.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTenantStorageConfig = getTenantStorageConfig;
+exports.uploadScreenshotToTenantStorage = uploadScreenshotToTenantStorage;
+exports.uploadFileToTenantStorage = uploadFileToTenantStorage;
+exports.resolveCloudUrl = resolveCloudUrl;
+exports.getProjectStorageConfig = getProjectStorageConfig;
+exports.buildArtifactKey = buildArtifactKey;
+exports.uploadArtifact = uploadArtifact;
+exports.uploadArtifactBuffer = uploadArtifactBuffer;
+exports.generatePresignedGetUrl = generatePresignedGetUrl;
+exports.downloadBufferFromTenantStorage = downloadBufferFromTenantStorage;
+exports.uploadBufferToTenantStorage = uploadBufferToTenantStorage;
+exports.buildKnowledgeKey = buildKnowledgeKey;
+exports.listProjectStorageObjects = listProjectStorageObjects;
+exports.deleteProjectStorageObjects = deleteProjectStorageObjects;
+exports.deleteTenantStorageObjects = deleteTenantStorageObjects;
+exports.buildContentKey = buildContentKey;
+exports.persistContent = persistContent;
+exports.resolveContent = resolveContent;
+const database_1 = require("@taodigital/database");
+const core_1 = require("@taodigital/core");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+function decryptConfig(raw) {
+    const out = {};
+    for (const [key, value] of Object.entries(raw ?? {})) {
+        if (key.endsWith('_enc') && typeof value === 'string') {
+            try {
+                out[key.replace('_enc', '')] = (0, core_1.decrypt)(value);
+            }
+            catch {
+                out[key.replace('_enc', '')] = '';
+            }
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** Resolve the platform-managed default bucket from Platform Admin config first,
+ *  then env vars (AWS_S3_BUCKET / PLATFORM_S3_BUCKET). Used as a fallback for
+ *  tenants who haven't set up their own storage connector. accessKeyId/
+ *  secretAccessKey are optional: when unset, buildS3Client() falls back to the
+ *  AWS SDK's default credential provider chain (e.g. an ECS task IAM role). */
+async function getPlatformStorageConfig() {
+    const adminCfg = await (0, core_1.getSystemConfig)('storage').catch(() => ({}));
+    const p = core_1.config.platformStorage;
+    const bucket = adminCfg.bucket || p.bucket;
+    const accountId = adminCfg.accountId || p.accountId;
+    const providerRaw = (adminCfg.provider || p.provider || (accountId ? 'R2' : bucket ? 'S3' : '')).toUpperCase();
+    const provider = providerRaw === 'R2' ? 'R2' : providerRaw === 'S3' ? 'S3' : null;
+    if (!provider || !bucket)
+        return null;
+    return {
+        provider,
+        bucket,
+        region: adminCfg.region || p.region,
+        accountId,
+        endpointUrl: adminCfg.endpointUrl || p.endpointUrl,
+        accessKeyId: adminCfg.accessKeyId || p.accessKeyId || '',
+        secretAccessKey: adminCfg.secretAccessKey || p.secretAccessKey || '',
+        publicUrl: adminCfg.publicUrl || p.publicUrl,
+        prefix: adminCfg.prefix || p.prefix,
+    };
+}
+/**
+ * Resolves the storage config to use for a tenant's screenshots/artifacts:
+ * the tenant's own connector if they've configured one, otherwise the
+ * platform-managed default bucket (if configured via env vars), otherwise
+ * null — meaning the caller should leave the artifact on local disk.
+ */
+async function getTenantStorageConfig(tenantId) {
+    const { withTenant: wt } = await import('@taodigital/database');
+    const setting = await wt(tenantId, (tx) => tx.tenantSetting.findUnique({ where: { tenantId_category: { tenantId, category: 'STORAGE' } } }));
+    const raw = setting?.config;
+    if (raw?.bucket && raw?.accessKeyId && raw?.secretAccessKey_enc) {
+        try {
+            return {
+                provider: raw.provider ?? 'S3',
+                bucket: raw.bucket,
+                region: raw.region ?? undefined,
+                accountId: raw.accountId ?? undefined,
+                endpointUrl: raw.endpointUrl ?? undefined,
+                accessKeyId: raw.accessKeyId,
+                secretAccessKey: (0, core_1.decrypt)(raw.secretAccessKey_enc),
+                publicUrl: raw.publicUrl ?? undefined,
+                prefix: raw.prefix ?? undefined,
+            };
+        }
+        catch { /* fall through to platform default below */ }
+    }
+    return getPlatformStorageConfig();
+}
+/**
+ * Upload a screenshot to tenant-level S3/R2 storage.
+ * Returns public URL if publicUrl configured, otherwise returns the storage key
+ * (callers should use resolveCloudUrl() to generate presigned URLs on demand).
+ */
+async function uploadScreenshotToTenantStorage(cfg, localPath, screenshotKey) {
+    const isR2 = cfg.provider === 'R2';
+    const creds = {
+        bucket: cfg.bucket,
+        region: cfg.region ?? 'auto',
+        accountId: cfg.accountId ?? '',
+        endpointUrl: cfg.endpointUrl ?? '',
+        accessKeyId: cfg.accessKeyId,
+        secretAccessKey: cfg.secretAccessKey,
+    };
+    await s3Upload(creds, localPath, screenshotKey, 'image/png', isR2);
+    if (cfg.publicUrl) {
+        const base = cfg.publicUrl.replace(/\/$/, '');
+        return `${base}/${screenshotKey}`;
+    }
+    return screenshotKey;
+}
+/**
+ * Upload any file to tenant-level S3/R2 storage.
+ * Returns public URL if publicUrl configured, otherwise returns the storage key.
+ */
+async function uploadFileToTenantStorage(cfg, localPath, storageKey, contentType) {
+    const isR2 = cfg.provider === 'R2';
+    const creds = {
+        bucket: cfg.bucket,
+        region: cfg.region ?? 'auto',
+        accountId: cfg.accountId ?? '',
+        endpointUrl: cfg.endpointUrl ?? '',
+        accessKeyId: cfg.accessKeyId,
+        secretAccessKey: cfg.secretAccessKey,
+    };
+    await s3Upload(creds, localPath, storageKey, contentType, isR2);
+    if (cfg.publicUrl) {
+        const base = cfg.publicUrl.replace(/\/$/, '');
+        return `${base}/${storageKey}`;
+    }
+    return storageKey;
+}
+/**
+ * Resolve a stored cloudUrl to a usable URL for the browser.
+ * - If it starts with https:// → return as-is (public URL, no expiry).
+ * - Otherwise → treat as storage key and generate a presigned GET URL.
+ */
+async function resolveCloudUrl(cfg, cloudUrl, expiresIn = 3600) {
+    if (cloudUrl.startsWith('https://') || cloudUrl.startsWith('http://')) {
+        return cloudUrl;
+    }
+    return generatePresignedGetUrl(cfg, cloudUrl, expiresIn);
+}
+async function getProjectStorageConfig(tenantId, projectId) {
+    const connector = await (0, database_1.withTenant)(tenantId, (tx) => tx.connector.findFirst({
+        where: { tenantId, projectId, kind: { in: ['S3', 'R2', 'GDRIVE', 'DROPBOX'] } },
+    }));
+    if (connector) {
+        const creds = decryptConfig(connector.config);
+        return { kind: connector.kind, creds, prefix: creds.prefix ?? '' };
+    }
+    const tenantCfg = await getTenantStorageConfig(tenantId);
+    if (!tenantCfg)
+        return null;
+    return {
+        kind: tenantCfg.provider,
+        prefix: tenantCfg.prefix ?? '',
+        creds: {
+            bucket: tenantCfg.bucket,
+            region: tenantCfg.region ?? '',
+            accountId: tenantCfg.accountId ?? '',
+            endpointUrl: tenantCfg.endpointUrl ?? '',
+            accessKeyId: tenantCfg.accessKeyId,
+            secretAccessKey: tenantCfg.secretAccessKey,
+            publicUrl: tenantCfg.publicUrl ?? '',
+            prefix: tenantCfg.prefix ?? '',
+        },
+    };
+}
+/** Build the cloud storage key for an artifact. */
+function buildArtifactKey(tenantId, projectId, type, filename, prefix = '') {
+    return [prefix, tenantId, projectId, type, filename].filter(Boolean).join('/');
+}
+/** Upload a single file to the configured cloud storage provider. Returns storage key/path. */
+async function uploadArtifact(cfg, localPath, storageKey, contentType = 'application/octet-stream') {
+    switch (cfg.kind) {
+        case 'S3': return s3Upload(cfg.creds, localPath, storageKey, contentType, false);
+        case 'R2': return s3Upload(cfg.creds, localPath, storageKey, contentType, true);
+        case 'GDRIVE': return gdriveUpload(cfg.creds, localPath, storageKey, contentType);
+        case 'DROPBOX': return dropboxUpload(cfg.creds, localPath, storageKey);
+        default: throw new Error(`Unknown storage provider: ${cfg.kind}`);
+    }
+}
+/** Upload a Buffer (for generated content like test plans, scripts). */
+async function uploadArtifactBuffer(cfg, buffer, storageKey, contentType = 'text/plain; charset=utf-8') {
+    switch (cfg.kind) {
+        case 'S3': return s3UploadBuffer(cfg.creds, buffer, storageKey, contentType, false);
+        case 'R2': return s3UploadBuffer(cfg.creds, buffer, storageKey, contentType, true);
+        case 'GDRIVE': return gdriveUploadBuffer(cfg.creds, buffer, storageKey, contentType);
+        case 'DROPBOX': return dropboxUploadBuffer(cfg.creds, buffer, storageKey);
+        default: throw new Error(`Unknown storage provider: ${cfg.kind}`);
+    }
+}
+// ── S3 / R2 ─────────────────────────────────────────────────────────────────
+function buildS3Client(creds, isR2) {
+    const { S3Client } = require('@aws-sdk/client-s3');
+    const endpoint = isR2 ? `https://${creds.accountId}.r2.cloudflarestorage.com` : creds.endpointUrl;
+    return new S3Client({
+        region: isR2 ? 'auto' : (creds.region || 'us-east-1'),
+        // No explicit key pair (e.g. platform-default bucket on ECS with a task IAM
+        // role) — omit `credentials` entirely so the SDK's default provider chain
+        // (env vars, IMDS, task role) resolves them instead of an empty key pair.
+        ...(creds.accessKeyId && creds.secretAccessKey
+            ? { credentials: { accessKeyId: creds.accessKeyId, secretAccessKey: creds.secretAccessKey } }
+            : {}),
+        ...(endpoint ? { endpoint, forcePathStyle: true } : {}),
+    });
+}
+async function s3Upload(creds, localPath, key, ct, isR2) {
+    const { PutObjectCommand } = require('@aws-sdk/client-s3');
+    const { createReadStream } = require('node:fs');
+    const client = buildS3Client(creds, isR2);
+    await client.send(new PutObjectCommand({ Bucket: creds.bucket, Key: key, Body: createReadStream(localPath), ContentType: ct }));
+    return key;
+}
+async function s3UploadBuffer(creds, buffer, key, ct, isR2) {
+    const { PutObjectCommand } = require('@aws-sdk/client-s3');
+    const client = buildS3Client(creds, isR2);
+    await client.send(new PutObjectCommand({ Bucket: creds.bucket, Key: key, Body: buffer, ContentType: ct }));
+    return key;
+}
+async function s3PresignedGetUrl(creds, key, isR2, expiresIn) {
+    const { GetObjectCommand } = require('@aws-sdk/client-s3');
+    const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');
+    const client = buildS3Client(creds, isR2);
+    return getSignedUrl(client, new GetObjectCommand({ Bucket: creds.bucket, Key: key }), { expiresIn });
+}
+async function s3DownloadBuffer(creds, key, isR2) {
+    const { GetObjectCommand } = require('@aws-sdk/client-s3');
+    const client = buildS3Client(creds, isR2);
+    const res = await client.send(new GetObjectCommand({ Bucket: creds.bucket, Key: key }));
+    const chunks = [];
+    for await (const chunk of res.Body)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+// ── Google Drive ─────────────────────────────────────────────────────────────
+async function getGDriveToken(sa) {
+    const { createSign } = require('node:crypto');
+    const now = Math.floor(Date.now() / 1000);
+    const header = Buffer.from(JSON.stringify({ alg: 'RS256', typ: 'JWT' })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify({
+        iss: sa.client_email,
+        scope: 'https://www.googleapis.com/auth/drive',
+        aud: 'https://oauth2.googleapis.com/token',
+        iat: now, exp: now + 3600,
+    })).toString('base64url');
+    const sigInput = `${header}.${payload}`;
+    const sign = createSign('RSA-SHA256');
+    sign.update(sigInput);
+    const jwt = `${sigInput}.${sign.sign(sa.private_key, 'base64url')}`;
+    const res = await fetch('https://oauth2.googleapis.com/token', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion: jwt }),
+    });
+    if (!res.ok)
+        throw new Error(`GDrive token error: ${await res.text()}`);
+    return (await res.json()).access_token;
+}
+async function gdriveUpload(creds, localPath, key, ct) {
+    return gdriveUploadBuffer(creds, (0, node_fs_1.readFileSync)(localPath), key, ct);
+}
+async function gdriveUploadBuffer(creds, buffer, key, ct) {
+    const sa = JSON.parse(creds.serviceAccountJson);
+    const token = await getGDriveToken(sa);
+    const name = node_path_1.default.basename(key);
+    const boundary = 'ZeTa_b';
+    const body = `--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n${JSON.stringify({ name, parents: creds.folderId ? [creds.folderId] : [] })}\r\n--${boundary}\r\nContent-Type: ${ct}\r\n\r\n`;
+    const tail = `\r\n--${boundary}--`;
+    const full = Buffer.concat([Buffer.from(body), buffer, Buffer.from(tail)]);
+    const res = await fetch('https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': `multipart/related; boundary=${boundary}` },
+        body: full,
+    });
+    if (!res.ok)
+        throw new Error(`GDrive upload failed: ${await res.text()}`);
+    return (await res.json()).id;
+}
+// ── Dropbox ──────────────────────────────────────────────────────────────────
+async function dropboxUpload(creds, localPath, key) {
+    return dropboxUploadBuffer(creds, (0, node_fs_1.readFileSync)(localPath), key);
+}
+async function dropboxUploadBuffer(creds, buffer, key) {
+    const folder = creds.folderPath ?? '/ZeTa-AI';
+    const dropboxPath = `${folder}/${key}`.replace(/\/+/g, '/');
+    const res = await fetch('https://content.dropboxapi.com/2/files/upload', {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${creds.accessToken}`,
+            'Dropbox-API-Arg': JSON.stringify({ path: dropboxPath, mode: 'overwrite' }),
+            'Content-Type': 'application/octet-stream',
+        },
+        body: buffer,
+    });
+    if (!res.ok)
+        throw new Error(`Dropbox upload failed: ${await res.text()}`);
+    return dropboxPath;
+}
+async function gdriveDownloadBuffer(creds, fileId) {
+    const sa = JSON.parse(creds.serviceAccountJson);
+    const token = await getGDriveToken(sa);
+    const res = await fetch(`https://www.googleapis.com/drive/v3/files/${fileId}?alt=media`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok)
+        throw new Error(`GDrive download failed: ${await res.text()}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+async function dropboxDownloadBuffer(creds, dropboxPath) {
+    const res = await fetch('https://content.dropboxapi.com/2/files/download', {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${creds.accessToken}`,
+            'Dropbox-API-Arg': JSON.stringify({ path: dropboxPath }),
+        },
+    });
+    if (!res.ok)
+        throw new Error(`Dropbox download failed: ${await res.text()}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Generate a presigned GET URL for S3/R2 (time-limited, auth-gated).
+ * GDrive/Dropbox: returns null (caller must use downloadBufferFromTenantStorage + proxy).
+ */
+async function generatePresignedGetUrl(cfg, storageKey, expiresIn = 3600) {
+    if (cfg.provider === 'S3' || cfg.provider === 'R2') {
+        const isR2 = cfg.provider === 'R2';
+        const creds = {
+            bucket: cfg.bucket,
+            region: cfg.region ?? 'auto',
+            accountId: cfg.accountId ?? '',
+            endpointUrl: cfg.endpointUrl ?? '',
+            accessKeyId: cfg.accessKeyId,
+            secretAccessKey: cfg.secretAccessKey,
+        };
+        return s3PresignedGetUrl(creds, storageKey, isR2, expiresIn);
+    }
+    return null;
+}
+/**
+ * Download raw bytes from tenant storage (for GDrive/Dropbox proxy, or fallback).
+ */
+async function downloadBufferFromTenantStorage(cfg, storageKey) {
+    const isR2 = cfg.provider === 'R2';
+    const creds = {
+        bucket: cfg.bucket,
+        region: cfg.region ?? 'auto',
+        accountId: cfg.accountId ?? '',
+        endpointUrl: cfg.endpointUrl ?? '',
+        accessKeyId: cfg.accessKeyId,
+        secretAccessKey: cfg.secretAccessKey,
+    };
+    return s3DownloadBuffer(creds, storageKey, isR2);
+}
+/** Upload a buffer to tenant storage. Returns the storage key. */
+async function uploadBufferToTenantStorage(cfg, buffer, storageKey, contentType = 'application/octet-stream') {
+    const isR2 = cfg.provider === 'R2';
+    const creds = {
+        bucket: cfg.bucket,
+        region: cfg.region ?? 'auto',
+        accountId: cfg.accountId ?? '',
+        endpointUrl: cfg.endpointUrl ?? '',
+        accessKeyId: cfg.accessKeyId,
+        secretAccessKey: cfg.secretAccessKey,
+    };
+    return s3UploadBuffer(creds, buffer, storageKey, contentType, isR2);
+}
+/** Build the canonical storage key for a knowledge artifact. */
+function buildKnowledgeKey(tenantId, projectId, artifactId, filename, prefix) {
+    return [prefix, tenantId, projectId, 'knowledge', artifactId, filename].filter(Boolean).join('/');
+}
+/** List all S3/R2 objects under a project prefix. Paginates automatically. */
+async function listProjectStorageObjects(cfg, tenantId, projectId) {
+    const { ListObjectsV2Command } = require('@aws-sdk/client-s3');
+    const isR2 = cfg.provider === 'R2';
+    const creds = {
+        bucket: cfg.bucket,
+        region: cfg.region ?? 'auto',
+        accountId: cfg.accountId ?? '',
+        endpointUrl: cfg.endpointUrl ?? '',
+        accessKeyId: cfg.accessKeyId,
+        secretAccessKey: cfg.secretAccessKey,
+    };
+    const client = buildS3Client(creds, isR2);
+    const prefix = [cfg.prefix, tenantId, projectId].filter(Boolean).join('/') + '/';
+    const objects = [];
+    let continuationToken;
+    do {
+        const res = await client.send(new ListObjectsV2Command({
+            Bucket: cfg.bucket,
+            Prefix: prefix,
+            ContinuationToken: continuationToken,
+            MaxKeys: 1000,
+        }));
+        for (const obj of (res.Contents ?? [])) {
+            objects.push({ key: obj.Key, size: obj.Size ?? 0, lastModified: obj.LastModified ? obj.LastModified.toISOString() : null });
+        }
+        continuationToken = res.IsTruncated ? res.NextContinuationToken : undefined;
+    } while (continuationToken);
+    return objects;
+}
+/**
+ * Delete all S3/R2 objects under a project prefix (GDPR cleanup on project delete).
+ * Batch-deletes in groups of 1 000 (S3 DeleteObjects limit).
+ * No-ops silently when cfg is null.
+ */
+async function deleteProjectStorageObjects(tenantId, projectId) {
+    const cfg = await getTenantStorageConfig(tenantId);
+    if (!cfg)
+        return;
+    const objects = await listProjectStorageObjects(cfg, tenantId, projectId);
+    if (objects.length === 0)
+        return;
+    const { DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+    const isR2 = cfg.provider === 'R2';
+    const creds = {
+        bucket: cfg.bucket,
+        region: cfg.region ?? 'auto',
+        accountId: cfg.accountId ?? '',
+        endpointUrl: cfg.endpointUrl ?? '',
+        accessKeyId: cfg.accessKeyId,
+        secretAccessKey: cfg.secretAccessKey,
+    };
+    const client = buildS3Client(creds, isR2);
+    for (let i = 0; i < objects.length; i += 1000) {
+        const batch = objects.slice(i, i + 1000).map((o) => ({ Key: o.key }));
+        await client.send(new DeleteObjectsCommand({ Bucket: cfg.bucket, Delete: { Objects: batch, Quiet: true } }));
+    }
+}
+/**
+ * Delete all S3/R2 objects for an entire tenant (GDPR cleanup on tenant delete).
+ * Lists by tenant prefix and batch-deletes everything found.
+ * No-ops silently when cfg is null.
+ */
+async function deleteTenantStorageObjects(tenantId) {
+    const cfg = await getTenantStorageConfig(tenantId);
+    if (!cfg)
+        return;
+    const { ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+    const isR2 = cfg.provider === 'R2';
+    const creds = {
+        bucket: cfg.bucket,
+        region: cfg.region ?? 'auto',
+        accountId: cfg.accountId ?? '',
+        endpointUrl: cfg.endpointUrl ?? '',
+        accessKeyId: cfg.accessKeyId,
+        secretAccessKey: cfg.secretAccessKey,
+    };
+    const client = buildS3Client(creds, isR2);
+    const prefix = [cfg.prefix, tenantId].filter(Boolean).join('/') + '/';
+    let continuationToken;
+    do {
+        const res = await client.send(new ListObjectsV2Command({
+            Bucket: cfg.bucket,
+            Prefix: prefix,
+            ContinuationToken: continuationToken,
+            MaxKeys: 1000,
+        }));
+        const keys = (res.Contents ?? []).map((o) => ({ Key: o.Key }));
+        if (keys.length > 0) {
+            await client.send(new DeleteObjectsCommand({ Bucket: cfg.bucket, Delete: { Objects: keys, Quiet: true } }));
+        }
+        continuationToken = res.IsTruncated ? res.NextContinuationToken : undefined;
+    } while (continuationToken);
+}
+// ── DB→S3 Content Pointer Helpers (doc 18) ────────────────────────────────────
+//
+// These implement the DB→S3 pointer pattern: large content fields (script code,
+// artifact markdown, test case steps/gherkin) are stored in tenant S3 when
+// configured, with only an object key kept in the DB column. When tenant S3
+// is not configured, content stays in the DB and the key field remains NULL.
+//
+// Key convention: {prefix}/{tenantId}/{projectId}/{type}/{entityId}.{ext}
+//   type: "scripts" | "artifacts" | "testcases"
+//   ext:  "ts" | "md" | "json" | "feature"
+/** Build a content object key for a specific entity type. */
+function buildContentKey(tenantId, projectId, type, entityId, ext, prefix) {
+    return [prefix, tenantId, projectId, type, `${entityId}.${ext}`].filter(Boolean).join('/');
+}
+/**
+ * Persist string content to tenant S3 if configured.
+ * Returns the storage key on success, or null if no S3 is configured
+ * (caller should keep content in the DB column in that case).
+ */
+async function persistContent(tenantId, projectId, type, entityId, ext, content, mimeType = 'text/plain; charset=utf-8') {
+    try {
+        const cfg = await getTenantStorageConfig(tenantId);
+        if (!cfg)
+            return null;
+        const key = buildContentKey(tenantId, projectId, type, entityId, ext, cfg.prefix);
+        await uploadBufferToTenantStorage(cfg, Buffer.from(content, 'utf-8'), key, mimeType);
+        return key;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve content: if a storage key is provided, download from S3.
+ * Otherwise (or on error) return the fallback DB content.
+ */
+async function resolveContent(tenantId, storageKey, fallback) {
+    if (!storageKey)
+        return fallback;
+    try {
+        const cfg = await getTenantStorageConfig(tenantId);
+        if (!cfg)
+            return fallback;
+        const buf = await downloadBufferFromTenantStorage(cfg, storageKey);
+        return buf.toString('utf-8');
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/email.d.ts

@@ -0,0 +1,21 @@
+export interface EmailPayload {
+    to: string;
+    name?: string;
+    type: string;
+    title: string;
+    body: string;
+    metadata?: Record<string, unknown>;
+    tenantId?: string;
+}
+export interface SendEmailResult {
+    sent: boolean;
+    reason?: string;
+}
+export interface EmailDiagnostics {
+    configured: boolean;
+    provider: 'platform-smtp' | 'tenant-smtp' | 'tenant-resend' | 'env-resend' | 'none';
+    missing: string[];
+    message: string;
+}
+export declare function getEmailDiagnostics(tenantId?: string): Promise<EmailDiagnostics>;
+export declare function sendEmail(payload: EmailPayload): Promise<SendEmailResult>;