@zintrust/core 0.1.0 → 0.1.2

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"}

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

@@ -0,0 +1,63 @@
+import { ErrorFactory } from '../../../exceptions/ZintrustError';
+import { fsPromises as fs } from '../../../node-singletons/fs';
+import * as path from '../../../node-singletons/path';
+export const LocalDriver = Object.freeze({
+    async put(config, key, content) {
+        const root = config.root;
+        if (!root || root.trim() === '') {
+            throw ErrorFactory.createConfigError('Local storage root is not configured');
+        }
+        const fullPath = path.join(root, key);
+        const dir = path.dirname(fullPath);
+        await fs.mkdir(dir, { recursive: true });
+        if (typeof content === 'string') {
+            await fs.writeFile(fullPath, content, 'utf8');
+        }
+        else {
+            await fs.writeFile(fullPath, content);
+        }
+        return fullPath;
+    },
+    async get(config, key) {
+        const fullPath = path.join(config.root, key);
+        try {
+            return await fs.readFile(fullPath);
+        }
+        catch (err) {
+            throw ErrorFactory.createNotFoundError('Local storage: file not found', { key, error: err });
+        }
+    },
+    async exists(config, key) {
+        const fullPath = path.join(config.root, key);
+        try {
+            await fs.access(fullPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async delete(config, key) {
+        const fullPath = path.join(config.root, key);
+        try {
+            await fs.unlink(fullPath);
+        }
+        catch (err) {
+            // ignore not found
+            void err; // NOSONAR
+        }
+    },
+    url(config, key) {
+        if (config?.url === undefined || config.url.trim() === '')
+            return undefined;
+        return `${config.url.replace(/\/$/, '')}/${key}`;
+    },
+    tempUrl(config, key, _options) {
+        const url = LocalDriver.url(config, key);
+        if (url === undefined) {
+            throw ErrorFactory.createConfigError('Local storage: url is not configured (set STORAGE_URL)');
+        }
+        return url;
+    },
+});
+export default LocalDriver;

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

@@ -0,0 +1,20 @@
+export type R2Config = {
+    bucket: string;
+    region?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    endpoint?: string;
+};
+export declare const R2Driver: Readonly<{
+    put(config: R2Config, key: string, content: string | Buffer): Promise<string>;
+    get(config: R2Config, key: string): Promise<Buffer>;
+    exists(config: R2Config, key: string): Promise<boolean>;
+    delete(config: R2Config, key: string): Promise<void>;
+    url(config: R2Config, key: string): string;
+    tempUrl(config: R2Config, key: string, options?: {
+        expiresIn?: number;
+        method?: "GET" | "PUT";
+    }): string;
+}>;
+export default R2Driver;
+//# sourceMappingURL=R2.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"R2.d.ts","sourceRoot":"","sources":["../../../../../src/tools/storage/drivers/R2.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,QAAQ;gBACD,QAAQ,OAAO,MAAM,WAAW,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBAkBjE,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;mBAapC,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;mBAaxC,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;gBAa9C,QAAQ,OAAO,MAAM,GAAG,MAAM;oBAQhC,QAAQ,OACX,MAAM,YACD;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE,GACvD,MAAM;EAgBT,CAAC;AAEH,eAAe,QAAQ,CAAC"}

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

@@ -0,0 +1,73 @@
+import { ErrorFactory } from '../../../exceptions/ZintrustError';
+import { S3Driver } from '../drivers/S3';
+export const R2Driver = Object.freeze({
+    async put(config, key, content) {
+        if (typeof config.endpoint !== 'string' || config.endpoint.trim() === '') {
+            throw ErrorFactory.createConfigError('R2: missing endpoint');
+        }
+        // Delegate to S3Driver using path-style endpoint
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.put(s3Config, key, content);
+    },
+    async get(config, key) {
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.get(s3Config, key);
+    },
+    async exists(config, key) {
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.exists(s3Config, key);
+    },
+    async delete(config, key) {
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.delete(s3Config, key);
+    },
+    url(config, key) {
+        if (config.endpoint !== undefined && config.endpoint.trim() !== '') {
+            return `${config.endpoint.replace(/\/$/, '')}/${config.bucket}/${key}`;
+        }
+        return `https://${config.bucket}.r2.cloudflarestorage.com/${key}`;
+    },
+    tempUrl(config, key, options) {
+        if (typeof config.endpoint !== 'string' || config.endpoint.trim() === '') {
+            throw ErrorFactory.createConfigError('R2: missing endpoint');
+        }
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.tempUrl(s3Config, key, options);
+    },
+});
+export default R2Driver;

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

@@ -0,0 +1,26 @@
+export type S3Config = {
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    endpoint?: string;
+    usePathStyle?: boolean;
+};
+export type GS3Cred = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string | undefined;
+};
+export declare const S3Driver: Readonly<{
+    put(config: S3Config, key: string, content: string | Buffer): Promise<string>;
+    get(config: S3Config, key: string): Promise<Buffer>;
+    exists(config: S3Config, key: string): Promise<boolean>;
+    delete(config: S3Config, key: string): Promise<void>;
+    url(config: S3Config, key: string): string;
+    tempUrl(config: S3Config, key: string, options?: {
+        expiresIn?: number;
+        method?: "GET" | "PUT";
+    }): string;
+}>;
+export default S3Driver;
+//# sourceMappingURL=S3.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"S3.d.ts","sourceRoot":"","sources":["../../../../../src/tools/storage/drivers/S3.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAwGF,eAAO,MAAM,QAAQ;gBACD,QAAQ,OAAO,MAAM,WAAW,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBA8CjE,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;mBA0CpC,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;mBAkCxC,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;gBAoC9C,QAAQ,OAAO,MAAM,GAAG,MAAM;oBAOhC,QAAQ,OACX,MAAM,YACD;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE,GACvD,MAAM;EAqDT,CAAC;AAEH,eAAe,QAAQ,CAAC"}