@zintrust/core 0.1.1 → 0.1.2

package/src/tools/notification/templates/markdown/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/tools/notification/templates/markdown/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,YAAY,GACvB,MAAM,MAAM,KACX;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAuC3D,CAAC;AAEF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;;yBA1ClF,MAAM,KACX;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE;;AA2C9D,wBAAgC"}

package/src/tools/notification/templates/markdown/index.js

@@ -0,0 +1,38 @@
+import { readFileSync } from '../../../../node-singletons/fs';
+import { join } from '../../../../node-singletons/path';
+export const loadTemplate = (name) => {
+    const parts = name.split('/');
+    const dir = join(process.cwd(), 'src', 'tools', 'notification', 'templates', 'markdown', ...parts.slice(0, -1));
+    const leaf = parts.at(-1) ?? '';
+    const filePath = join(dir, `${leaf}.md`);
+    const raw = readFileSync(filePath, 'utf-8');
+    const meta = {};
+    const lines = raw.split(/\r?\n/);
+    let i = 0;
+    for (; i < lines.length; i++) {
+        const line = lines[i].trim();
+        // Fast path: must look like an HTML comment and contain a colon separator.
+        if (!line.startsWith('<!--') || !line.endsWith('-->'))
+            break;
+        const inner = line.slice(4, -3).trim();
+        const colonIndex = inner.indexOf(':');
+        if (colonIndex === -1)
+            break;
+        const key = inner.slice(0, colonIndex).trim().toLowerCase();
+        const val = inner.slice(colonIndex + 1).trim();
+        if (!key)
+            break;
+        if (key === 'subject')
+            meta.subject = val;
+        if (key === 'variables') {
+            meta.variables = val
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+        }
+    }
+    const content = lines.slice(i).join('\n').trim();
+    return { content, ...meta };
+};
+export { listTemplates, renderTemplate } from '../../templates/markdown/registry';
+export default { loadTemplate };

package/src/tools/notification/templates/markdown/registry.d.ts

@@ -0,0 +1,15 @@
+import { loadTemplate } from '../../templates/markdown';
+export declare const listTemplates: () => string[];
+export declare const renderTemplate: (name: string, vars?: Record<string, unknown>) => {
+    html: string;
+    meta: ReturnType<typeof loadTemplate>;
+};
+declare const _default: {
+    listTemplates: () => string[];
+    renderTemplate: (name: string, vars?: Record<string, unknown>) => {
+        html: string;
+        meta: ReturnType<typeof loadTemplate>;
+    };
+};
+export default _default;
+//# sourceMappingURL=registry.d.ts.map

package/src/tools/notification/templates/markdown/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../../../src/tools/notification/templates/markdown/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAwBhE,eAAO,MAAM,aAAa,QAAO,MAAM,EAEtC,CAAC;AAIF,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,OAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,KACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAA;CAOvD,CAAC;;yBAhB+B,MAAM,EAAE;2BAOjC,MAAM,SACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAA;KAAE;;AAS1D,wBAAiD"}

package/src/tools/notification/templates/markdown/registry.js

@@ -0,0 +1,36 @@
+import { readdirSync, statSync } from '../../../../node-singletons/fs';
+import { join, relative } from '../../../../node-singletons/path';
+import { loadTemplate } from '../../templates/markdown';
+import { MarkdownRenderer } from '../../../templates';
+const BASE = join(process.cwd(), 'src', 'tools', 'notification', 'templates', 'markdown');
+const walkDir = (dir, base = dir) => {
+    const entries = readdirSync(dir);
+    let files = [];
+    for (const e of entries) {
+        const p = join(dir, e);
+        const s = statSync(p);
+        if (s.isDirectory()) {
+            files = files.concat(walkDir(p, base));
+            continue;
+        }
+        if (e.endsWith('.md')) {
+            const rel = relative(base, p).replaceAll('\\', '/');
+            const withoutExt = rel.toLowerCase().endsWith('.md') ? rel.slice(0, -3) : rel;
+            files.push(withoutExt);
+        }
+    }
+    return files;
+};
+export const listTemplates = () => {
+    return walkDir(BASE);
+};
+import { ErrorFactory } from '../../../../exceptions/ZintrustError';
+export const renderTemplate = (name, vars = {}) => {
+    const tpl = loadTemplate(name);
+    // Basic validation: subject required
+    if (tpl.subject === null || tpl.subject === undefined || tpl.subject.trim() === '')
+        throw ErrorFactory.createValidationError('Notification template missing subject', { name });
+    const html = MarkdownRenderer.render(tpl.content, vars);
+    return { html, meta: tpl };
+};
+export default { listTemplates, renderTemplate };

package/src/tools/notification/testing.d.ts

@@ -0,0 +1,19 @@
+type SentRecord = {
+    provider: string;
+    payload: unknown;
+    config: unknown;
+};
+export declare const NotificationFake: Readonly<{
+    _sent: Array<SentRecord>;
+    send(provider: string, config: unknown, payload: unknown): Promise<{
+        ok: boolean;
+    }>;
+    assertSent(predicate: (r: SentRecord) => boolean): void;
+    assertNotSent(predicate: (r: SentRecord) => boolean): void;
+    assertSentCount(expected: number): void;
+    getSent(): Array<SentRecord>;
+    lastSent(): SentRecord | undefined;
+    reset(): void;
+}>;
+export default NotificationFake;
+//# sourceMappingURL=testing.d.ts.map

package/src/tools/notification/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../../src/tools/notification/testing.ts"],"names":[],"mappings":"AAEA,KAAK,UAAU,GAAG;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,gBAAgB;WACd,KAAK,CAAC,UAAU,CAAC;mBAET,MAAM,UAAU,OAAO,WAAW,OAAO,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;0BAMnE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO;6BAKvB,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO;8BAKzB,MAAM;eASrB,KAAK,CAAC,UAAU,CAAC;gBAIhB,UAAU,GAAG,SAAS;;EAOlC,CAAC;AAEH,eAAe,gBAAgB,CAAC"}

package/src/tools/notification/testing.js

@@ -0,0 +1,35 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+export const NotificationFake = Object.freeze({
+    _sent: [],
+    async send(provider, config, payload) {
+        this._sent.push({ provider, config, payload });
+        await Promise.resolve();
+        return { ok: true };
+    },
+    assertSent(predicate) {
+        if (!this._sent.some(predicate))
+            throw ErrorFactory.createValidationError('Expected notification to be sent');
+    },
+    assertNotSent(predicate) {
+        if (this._sent.some(predicate))
+            throw ErrorFactory.createValidationError('Expected notification to NOT be sent');
+    },
+    assertSentCount(expected) {
+        if (this._sent.length !== expected) {
+            throw ErrorFactory.createValidationError('Unexpected notification send count', {
+                expected,
+                actual: this._sent.length,
+            });
+        }
+    },
+    getSent() {
+        return [...this._sent];
+    },
+    lastSent() {
+        return this._sent.length > 0 ? this._sent.at(-1) : undefined;
+    },
+    reset() {
+        this._sent.length = 0;
+    },
+});
+export default NotificationFake;

package/src/tools/notification/testingHelpers.d.ts

@@ -0,0 +1,12 @@
+export declare const useFakeDriver: (name?: string, fake?: unknown) => {
+    driverName: string;
+    restore: () => void;
+};
+declare const _default: {
+    useFakeDriver: (name?: string, fake?: unknown) => {
+        driverName: string;
+        restore: () => void;
+    };
+};
+export default _default;
+//# sourceMappingURL=testingHelpers.d.ts.map

package/src/tools/notification/testingHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingHelpers.d.ts","sourceRoot":"","sources":["../../../../src/tools/notification/testingHelpers.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,aAAa,GACxB,aAA0B,EAC1B,OAAM,OAA0B,KAC/B;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CA2B3C,CAAC;;0CA5BM,OAAO,KACZ;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE;;AA6B9C,wBAAiC"}

package/src/tools/notification/testingHelpers.js

@@ -0,0 +1,32 @@
+import { NotificationRegistry } from './Registry';
+import NotificationFake from './testing';
+export const useFakeDriver = (name = 'notification-fake', fake = NotificationFake) => {
+    let previous;
+    try {
+        previous = NotificationRegistry.get(name);
+    }
+    catch {
+        previous = undefined;
+    }
+    const fakeDriver = fake;
+    NotificationRegistry.register(name, fakeDriver);
+    const prevEnv = process.env['NOTIFICATION_DRIVER'];
+    process.env['NOTIFICATION_DRIVER'] = name;
+    return {
+        driverName: name,
+        restore() {
+            // Restore previous driver if present, otherwise keep fake registered
+            if (previous === undefined) {
+                NotificationRegistry.register(name, NotificationFake);
+            }
+            else {
+                NotificationRegistry.register(name, previous);
+            }
+            if (prevEnv === undefined)
+                delete process.env['NOTIFICATION_DRIVER'];
+            else
+                process.env['NOTIFICATION_DRIVER'] = prevEnv;
+        },
+    };
+};
+export default { useFakeDriver };

package/src/tools/queue/Queue.d.ts

@@ -0,0 +1,23 @@
+export type QueueMessage<T = unknown> = {
+    id: string;
+    payload: T;
+    attempts: number;
+};
+interface IQueueDriver {
+    enqueue<T = unknown>(queue: string, payload: T): Promise<string>;
+    dequeue<T = unknown>(queue: string): Promise<QueueMessage<T> | undefined>;
+    ack(queue: string, id: string): Promise<void>;
+    length(queue: string): Promise<number>;
+    drain(queue: string): Promise<void>;
+}
+export declare const Queue: Readonly<{
+    register(name: string, driver: IQueueDriver): void;
+    get(name?: string): IQueueDriver;
+    enqueue<T = unknown>(queue: string, payload: T, driverName?: string): Promise<string>;
+    dequeue<T = unknown>(queue: string, driverName?: string): Promise<QueueMessage<T> | undefined>;
+    ack(queue: string, id: string, driverName?: string): Promise<void>;
+    length(queue: string, driverName?: string): Promise<number>;
+    drain(queue: string, driverName?: string): Promise<void>;
+}>;
+export default Queue;
+//# sourceMappingURL=Queue.d.ts.map

package/src/tools/queue/Queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Queue.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/Queue.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAErF,UAAU,YAAY;IACpB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjE,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC1E,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAID,eAAO,MAAM,KAAK;mBACD,MAAM,UAAU,YAAY;eAIhC,MAAM,GAAG,YAAY;YAUlB,CAAC,mBAAmB,MAAM,WAAW,CAAC,eAAe,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAK7E,CAAC,mBACN,MAAM,eACA,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;eAKtB,MAAM,MAAM,MAAM,eAAe,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;kBAKpD,MAAM,eAAe,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;iBAK9C,MAAM,eAAe,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;EAI9D,CAAC;AAEH,eAAe,KAAK,CAAC"}

package/src/tools/queue/Queue.js

@@ -0,0 +1,38 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+const drivers = new Map();
+export const Queue = Object.freeze({
+    register(name, driver) {
+        drivers.set(name.toLowerCase(), driver);
+    },
+    get(name) {
+        const driverName = (name ?? process.env['QUEUE_DRIVER'] ?? 'inmemory')
+            .toString()
+            .trim()
+            .toLowerCase();
+        const driver = drivers.get(driverName);
+        if (!driver)
+            throw ErrorFactory.createConfigError(`Queue driver not registered: ${driverName}`);
+        return driver;
+    },
+    async enqueue(queue, payload, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.enqueue(queue, payload);
+    },
+    async dequeue(queue, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.dequeue(queue);
+    },
+    async ack(queue, id, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.ack(queue, id);
+    },
+    async length(queue, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.length(queue);
+    },
+    async drain(queue, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.drain(queue);
+    },
+});
+export default Queue;

package/src/tools/queue/drivers/InMemory.d.ts

@@ -0,0 +1,10 @@
+import { QueueMessage } from '../../queue/Queue';
+export declare const InMemoryQueue: {
+    readonly enqueue: <T = unknown>(queue: string, payload: T) => Promise<string>;
+    readonly dequeue: <T = unknown>(queue: string) => Promise<QueueMessage<T> | undefined>;
+    readonly ack: (_queue: string, _id: string) => Promise<void>;
+    readonly length: (queue: string) => Promise<number>;
+    readonly drain: (queue: string) => Promise<void>;
+};
+export default InMemoryQueue;
+//# sourceMappingURL=InMemory.d.ts.map

package/src/tools/queue/drivers/InMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemory.d.ts","sourceRoot":"","sources":["../../../../../src/tools/queue/drivers/InMemory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIlD,eAAO,MAAM,aAAa;uBAQR,CAAC,mBAAmB,MAAM,WAAW,CAAC,KAAG,OAAO,CAAC,MAAM,CAAC;uBAmBxD,CAAC,mBAAmB,MAAM,KAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;2BAW7D,MAAM,OAAO,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;6BAKjC,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;4BAOzB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;CAMzC,CAAC;AAEL,eAAe,aAAa,CAAC"}

package/src/tools/queue/drivers/InMemory.js

@@ -0,0 +1,55 @@
+import { generateUuid } from '../../../common/uuid';
+export const InMemoryQueue = (() => {
+    const store = new Map();
+    const ensure = (queue) => {
+        if (!store.has(queue))
+            store.set(queue, []);
+    };
+    return {
+        async enqueue(queue, payload) {
+            await Promise.resolve();
+            ensure(queue);
+            const id = generateUuid();
+            const msg = {
+                id,
+                payload: payload,
+                attempts: 0,
+                enqueuedAt: Date.now(),
+            };
+            const arr = store.get(queue);
+            if (arr && arr.length > 0) {
+                arr.push(msg);
+            }
+            else {
+                store.set(queue, [msg]);
+            }
+            return id;
+        },
+        async dequeue(queue) {
+            await Promise.resolve();
+            ensure(queue);
+            const arr = store.get(queue);
+            if (arr && arr.length > 0) {
+                const msg = arr.shift();
+                return msg;
+            }
+            return undefined;
+        },
+        async ack(_queue, _id) {
+            // in-memory dequeue already removed the message; ack is a no-op
+            await Promise.resolve();
+        },
+        async length(queue) {
+            await Promise.resolve();
+            ensure(queue);
+            const arr = store.get(queue);
+            return Array.isArray(arr) ? arr.length : 0;
+        },
+        async drain(queue) {
+            await Promise.resolve();
+            ensure(queue);
+            store.set(queue, []);
+        },
+    };
+})();
+export default InMemoryQueue;

package/src/tools/queue/drivers/Redis.d.ts

@@ -0,0 +1,10 @@
+import { QueueMessage } from '../../queue/Queue';
+export declare const RedisQueue: {
+    readonly enqueue: <T = unknown>(queue: string, payload: T) => Promise<string>;
+    readonly dequeue: <T = unknown>(queue: string) => Promise<QueueMessage<T> | undefined>;
+    readonly ack: (_queue: string, _id: string) => Promise<void>;
+    readonly length: (queue: string) => Promise<number>;
+    readonly drain: (queue: string) => Promise<void>;
+};
+export default RedisQueue;
+//# sourceMappingURL=Redis.d.ts.map

package/src/tools/queue/drivers/Redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Redis.d.ts","sourceRoot":"","sources":["../../../../../src/tools/queue/drivers/Redis.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAelD,eAAO,MAAM,UAAU;uBAuDL,CAAC,mBAAmB,MAAM,WAAW,CAAC,KAAG,OAAO,CAAC,MAAM,CAAC;uBAQxD,CAAC,mBAAmB,MAAM,KAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;2BAY7D,MAAM,OAAO,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;6BAMjC,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;4BAKzB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;CAKzC,CAAC;AAEL,eAAe,UAAU,CAAC"}

package/src/tools/queue/drivers/Redis.js

@@ -0,0 +1,91 @@
+import { generateUuid } from '../../../common/uuid';
+import { ErrorFactory } from '../../../exceptions/ZintrustError';
+const getRedisUrl = () => {
+    const url = (process.env['REDIS_URL'] ?? '').trim();
+    return url.length > 0 ? url : null;
+};
+export const RedisQueue = (() => {
+    let client = null;
+    let connected = false;
+    const ensureClient = async () => {
+        if (connected && client !== null)
+            return client;
+        const url = getRedisUrl();
+        if (url === null)
+            throw ErrorFactory.createConfigError('Redis queue driver requires REDIS_URL');
+        // Import lazily so package is optional for environments that don't use Redis
+        // Prefer real 'redis' package when available, otherwise allow tests to inject a fake client
+        try {
+            // Dynamically import the redis package if available (optional dependency)
+            // Tests can inject a fake client on `globalThis.__fakeRedisClient` if the package is absent.
+            // Dynamically import the redis package if available (optional dependency)
+            const mod = (await import('redis'));
+            const createClient = mod.createClient;
+            client = createClient({ url });
+            if (typeof client.connect === 'function') {
+                try {
+                    // Await connect to ensure readiness; network errors will be surfaced
+                    await client.connect();
+                    connected = true;
+                }
+                catch (connectionError) {
+                    connected = false;
+                    // log non-fatally — operations will surface errors as needed
+                    // eslint-disable-next-line no-console
+                    console.warn('Redis client connect failed:', String(connectionError));
+                }
+            }
+            else {
+                connected = true;
+            }
+        }
+        catch {
+            const globalFake = globalThis
+                .__fakeRedisClient;
+            if (globalFake === undefined) {
+                throw ErrorFactory.createConfigError("Redis queue driver requires the 'redis' package or a test fake client set in globalThis.__fakeRedisClient");
+            }
+            client = globalFake;
+            connected = true;
+        }
+        if (client === null)
+            throw ErrorFactory.createConfigError('Redis client could not be initialized');
+        return client;
+    };
+    return {
+        async enqueue(queue, payload) {
+            const cli = await ensureClient();
+            const id = generateUuid();
+            const msg = JSON.stringify({ id, payload, attempts: 0 });
+            await cli.rPush(queue, msg);
+            return id;
+        },
+        async dequeue(queue) {
+            const cli = await ensureClient();
+            const raw = await cli.lPop(queue);
+            if (raw === null)
+                return undefined;
+            try {
+                const parsed = JSON.parse(raw);
+                return parsed;
+            }
+            catch (err) {
+                throw ErrorFactory.createTryCatchError('Failed to parse queue message', err);
+            }
+        },
+        async ack(_queue, _id) {
+            // Simple list-based queue removes on dequeue, so ack is a no-op here.
+            // For visibility timeout or retry semantics, implement BRPOPLPUSH and a processing list.
+            return Promise.resolve(); // NOSONAR
+        },
+        async length(queue) {
+            const cli = await ensureClient();
+            return cli.lLen(queue);
+        },
+        async drain(queue) {
+            const cli = await ensureClient();
+            await cli.del(queue);
+        },
+    };
+})();
+export default RedisQueue;

package/src/tools/storage/drivers/Gcs.d.ts

@@ -0,0 +1,20 @@
+export type GcsConfig = {
+    bucket: string;
+    projectId?: string;
+    keyFile?: string;
+    url?: string;
+};
+type TempUrlOptions = {
+    expiresIn?: number;
+    method?: 'GET' | 'PUT';
+};
+export declare const GcsDriver: Readonly<{
+    url(config: GcsConfig, key: string): string | undefined;
+    put(config: GcsConfig, key: string, content: string | Buffer): Promise<string>;
+    get(config: GcsConfig, key: string): Promise<Buffer>;
+    exists(config: GcsConfig, key: string): Promise<boolean>;
+    delete(config: GcsConfig, key: string): Promise<void>;
+    tempUrl(config: GcsConfig, key: string, options?: TempUrlOptions): Promise<string>;
+}>;
+export default GcsDriver;
+//# sourceMappingURL=Gcs.d.ts.map

package/src/tools/storage/drivers/Gcs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Gcs.d.ts","sourceRoot":"","sources":["../../../../../src/tools/storage/drivers/Gcs.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,cAAc,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;CAAE,CAAC;AA+ErE,eAAO,MAAM,SAAS;gBACR,SAAS,OAAO,MAAM,GAAG,MAAM,GAAG,SAAS;gBAWrC,SAAS,OAAO,MAAM,WAAW,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBAkBlE,SAAS,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;mBAiBrC,SAAS,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;mBAgBzC,SAAS,OAAO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;oBAiBrC,SAAS,OAAO,MAAM,YAAY,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;EA8BxF,CAAC;AAEH,eAAe,SAAS,CAAC"}

package/src/tools/storage/drivers/Gcs.js

@@ -0,0 +1,152 @@
+import { ErrorFactory } from '../../../exceptions/ZintrustError';
+let cachedRealClient;
+const getInjectedStorageModule = () => {
+    return globalThis
+        .__fakeGoogleCloudStorageModule;
+};
+const getInjectedFakeClient = () => {
+    const v = globalThis.__fakeGcsClient;
+    return v;
+};
+const loadRealClient = async (config) => {
+    if (cachedRealClient !== undefined)
+        return cachedRealClient;
+    // Avoid a string-literal import so TypeScript doesn't require the module at build time.
+    const specifier = '@google-cloud/storage';
+    const injected = getInjectedStorageModule();
+    let mod;
+    try {
+        mod = (injected ?? (await import(specifier)));
+    }
+    catch (err) {
+        throw ErrorFactory.createConfigError('GCS: missing optional dependency @google-cloud/storage (install it or inject globalThis.__fakeGcsClient for tests)', { error: err });
+    }
+    if (typeof mod.Storage !== 'function') {
+        throw ErrorFactory.createConfigError('GCS: @google-cloud/storage did not export Storage');
+    }
+    const opts = {};
+    if (typeof config.projectId === 'string' && config.projectId.trim() !== '') {
+        opts['projectId'] = config.projectId;
+    }
+    if (typeof config.keyFile === 'string' && config.keyFile.trim() !== '') {
+        opts['keyFilename'] = config.keyFile;
+    }
+    try {
+        cachedRealClient = new mod.Storage(opts);
+        return cachedRealClient;
+    }
+    catch (err) {
+        throw ErrorFactory.createConfigError('GCS: failed to initialize Storage client', {
+            error: err,
+        });
+    }
+};
+const getClient = async (config) => {
+    const injected = getInjectedFakeClient();
+    if (injected !== undefined)
+        return injected;
+    return loadRealClient(config);
+};
+const encodePathSegments = (key) => key
+    .split('/')
+    .map((seg) => encodeURIComponent(seg))
+    .join('/');
+export const GcsDriver = Object.freeze({
+    url(config, key) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            return undefined;
+        const base = typeof config.url === 'string' ? config.url.trim() : '';
+        if (base !== '')
+            return `${base.replace(/\/$/, '')}/${key}`;
+        const encodedKey = encodePathSegments(key);
+        return `https://storage.googleapis.com/${encodeURIComponent(bucket)}/${encodedKey}`;
+    },
+    async put(config, key, content) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.save !== 'function') {
+            throw ErrorFactory.createConfigError('GCS: client is missing file.save()');
+        }
+        await file.save(content);
+        const url = GcsDriver.url(config, key);
+        if (url === undefined)
+            return '';
+        return url;
+    },
+    async get(config, key) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.download !== 'function') {
+            throw ErrorFactory.createConfigError('GCS: client is missing file.download()');
+        }
+        const [data] = await file.download();
+        if (Buffer.isBuffer(data))
+            return data;
+        if (typeof data === 'string')
+            return Buffer.from(data);
+        return Buffer.from(data);
+    },
+    async exists(config, key) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.exists !== 'function') {
+            // if client doesn't support exists, assume true (matches Storage.exists default behavior)
+            return true;
+        }
+        const [exists] = await file.exists();
+        return Boolean(exists);
+    },
+    async delete(config, key) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.delete !== 'function')
+            return;
+        try {
+            // google-cloud-storage supports ignoreNotFound, but keep it flexible for fakes
+            await file.delete({ ignoreNotFound: true });
+        }
+        catch (err) {
+            void err; // NOSONAR
+        }
+    },
+    async tempUrl(config, key, options) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const expiresIn = options?.expiresIn ?? 900;
+        if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+            throw ErrorFactory.createValidationError('GCS: expiresIn must be a positive number', {
+                expiresIn,
+            });
+        }
+        if (expiresIn > 604800) {
+            throw ErrorFactory.createValidationError('GCS: expiresIn exceeds 7 days', {
+                expiresIn,
+            });
+        }
+        const method = options?.method ?? 'GET';
+        const action = method === 'PUT' ? 'write' : 'read';
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.getSignedUrl !== 'function') {
+            throw ErrorFactory.createConfigError('GCS: client is missing file.getSignedUrl()');
+        }
+        const expires = Date.now() + expiresIn * 1000;
+        const [url] = await file.getSignedUrl({ version: 'v4', action, expires });
+        return url;
+    },
+});
+export default GcsDriver;

package/src/tools/storage/drivers/Local.d.ts

@@ -0,0 +1,17 @@
+export type LocalConfig = {
+    root: string;
+    url?: string;
+};
+export declare const LocalDriver: Readonly<{
+    put(config: LocalConfig, key: string, content: string | Buffer): Promise<string>;
+    get(config: LocalConfig, key: string): Promise<Buffer>;
+    exists(config: LocalConfig, key: string): Promise<boolean>;
+    delete(config: LocalConfig, key: string): Promise<void>;
+    url(config: LocalConfig, key: string): string | undefined;
+    tempUrl(config: LocalConfig, key: string, _options?: {
+        expiresIn?: number;
+        method?: "GET" | "PUT";
+    }): string;
+}>;
+export default LocalDriver;
+//# sourceMappingURL=Local.d.ts.map

package/src/tools/storage/drivers/Local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Local.d.ts","sourceRoot":"","sources":["../../../../../src/tools/storage/drivers/Local.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,WAAW;gBACJ,WAAW,OAAO,MAAM,WAAW,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBAkBpE,WAAW,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;mBASvC,WAAW,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;mBAU3C,WAAW,OAAO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;gBAUjD,WAAW,OAAO,MAAM,GAAG,MAAM,GAAG,SAAS;oBAM/C,WAAW,OACd,MAAM,aACA;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE,GACxD,MAAM;EAST,CAAC;AAEH,eAAe,WAAW,CAAC"}