@yaghmori/storage-service 0.1.1

package/README.md

@@ -0,0 +1,20 @@
+# @yaghmori/storage-service
+
+Configurable client for **storage-service** (HTTP · TCP · Kafka · auth).
+
+## Docs
+
+- **[docs/PROTOCOL_GUIDE.md](./docs/PROTOCOL_GUIDE.md)** — full HTTP / TCP / Kafka for Node and .NET
+- **[docs/USAGE.md](./docs/USAGE.md)** — practical usage
+- **[docs/NUGET_TRUSTED_PUBLISHING.md](./docs/NUGET_TRUSTED_PUBLISHING.md)** — publish `Yaghmori.StorageService` without API keys
+
+SDKs: npm · `sdk/dotnet`
+
+```ts
+import { createStorageHttpClient } from '@yaghmori/storage-service';
+
+const storage = createStorageHttpClient({
+  baseUrl: process.env.STORAGE_SERVICE_URL,
+  auth: { apiKey: process.env.STORAGE_SERVICE_API_KEY! },
+});
+```

package/contracts.json

@@ -0,0 +1,46 @@
+{
+  "name": "storage-service",
+  "npmPackage": "@yaghmori/storage-service",
+  "nugetPackage": "Yaghmori.StorageService",
+  "dockerImage": "ghcr.io/yaghmori/storage-service",
+  "description": "Client SDK for the standalone storage-service (TCP, Kafka, HTTP)",
+  "ports": {
+    "tcp": 4002,
+    "http": 4000
+  },
+  "injectionToken": "STORAGE_SERVICE",
+  "env": {
+    "httpBaseUrl": "STORAGE_SERVICE_URL",
+    "host": "STORAGE_SERVICE_HOST",
+    "tcpPort": "STORAGE_SERVICE_TCP_PORT",
+    "httpPort": "STORAGE_SERVICE_HTTP_PORT"
+  },
+  "patterns": {
+    "GET_FILE_INFO": "storage.get_file_info",
+    "DELETE_FILE": "storage.delete_file",
+    "BATCH_OPERATIONS": "storage.batch_operations",
+    "GET_SIGNED_URL": "storage.get_signed_url",
+    "UPLOAD_FILE": "uploadFile",
+    "GET_ASSET_URL": "getAssetUrl",
+    "DELETE_ASSET": "deleteAsset",
+    "HEALTH_CHECK": "health.check"
+  },
+  "httpPaths": {
+    "UPLOAD": "/upload",
+    "GET_FILE": "/files/{id}",
+    "DELETE_FILE": "/files/{id}",
+    "DOWNLOAD": "/files/{id}/download",
+    "SIGNED_URL": "/files/{id}/signed-url",
+    "HEALTH": "/health"
+  },
+  "topics": {
+    "FILE_UPLOADED": "file.uploaded",
+    "FILE_DELETED": "file.deleted",
+    "FILE_PROCESSED": "file.processed"
+  },
+  "eventTypes": {
+    "UPLOADED": "evt.storage.file.uploaded.v1",
+    "DELETED": "evt.storage.file.deleted.v1",
+    "PROCESSED": "evt.storage.file.processed.v1"
+  }
+}

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+export type ClientAuth = {
+    type: 'apiKey';
+    apiKey: string;
+} | {
+    type: 'bearer';
+    token: string;
+} | {
+    apiKey: string;
+    bearerToken?: never;
+} | {
+    bearerToken: string;
+    apiKey?: never;
+} | {
+    apiKey?: string;
+    bearerToken?: string;
+};
+export declare const AUTH_HEADERS: {
+    readonly apiKey: "x-api-key";
+    readonly authorization: "authorization";
+};
+export declare function buildAuthHeaders(auth?: ClientAuth | string, envApiKeyVar?: string): Record<string, string>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,GACvC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GACvC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,wBAAgB,gBAAgB,CAC9B,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,EAC1B,YAAY,SAA4B,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyBxB"}

package/dist/auth.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_HEADERS = void 0;
+exports.buildAuthHeaders = buildAuthHeaders;
+exports.AUTH_HEADERS = {
+    apiKey: 'x-api-key',
+    authorization: 'authorization',
+};
+function buildAuthHeaders(auth, envApiKeyVar = 'STORAGE_SERVICE_API_KEY') {
+    if (!auth) {
+        const fromEnv = process.env[envApiKeyVar] ||
+            process.env.SERVICE_API_KEY ||
+            process.env.API_KEY;
+        if (fromEnv)
+            return { [exports.AUTH_HEADERS.apiKey]: fromEnv };
+        const bearer = process.env.STORAGE_SERVICE_BEARER || process.env.SERVICE_BEARER_TOKEN;
+        if (bearer)
+            return { [exports.AUTH_HEADERS.authorization]: `Bearer ${bearer}` };
+        return {};
+    }
+    if (typeof auth === 'string') {
+        return { [exports.AUTH_HEADERS.apiKey]: auth };
+    }
+    if ('type' in auth) {
+        if (auth.type === 'apiKey')
+            return { [exports.AUTH_HEADERS.apiKey]: auth.apiKey };
+        return { [exports.AUTH_HEADERS.authorization]: `Bearer ${auth.token}` };
+    }
+    const headers = {};
+    if (auth.apiKey)
+        headers[exports.AUTH_HEADERS.apiKey] = auth.apiKey;
+    if (auth.bearerToken)
+        headers[exports.AUTH_HEADERS.authorization] = `Bearer ${auth.bearerToken}`;
+    return headers;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":";;;AAYA,4CA4BC;AAjCY,QAAA,YAAY,GAAG;IAC1B,MAAM,EAAE,WAAW;IACnB,aAAa,EAAE,eAAe;CACtB,CAAC;AAEX,SAAgB,gBAAgB,CAC9B,IAA0B,EAC1B,YAAY,GAAG,yBAAyB;IAExC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,OAAO,GACX,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;YACzB,OAAO,CAAC,GAAG,CAAC,eAAe;YAC3B,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QACtB,IAAI,OAAO;YAAE,OAAO,EAAE,CAAC,oBAAY,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;QACvD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACtF,IAAI,MAAM;YAAE,OAAO,EAAE,CAAC,oBAAY,CAAC,aAAa,CAAC,EAAE,UAAU,MAAM,EAAE,EAAE,CAAC;QACxE,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC,oBAAY,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;QACnB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC,oBAAY,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QAC1E,OAAO,EAAE,CAAC,oBAAY,CAAC,aAAa,CAAC,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;IAClE,CAAC;IAED,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,oBAAY,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5D,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,CAAC,oBAAY,CAAC,aAAa,CAAC,GAAG,UAAU,IAAI,CAAC,WAAW,EAAE,CAAC;IACzF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export type ServiceEndpoint = {
+    baseUrl?: string;
+    host?: string;
+    port?: number;
+    protocol?: 'http' | 'https';
+};
+export declare function resolveHttpBaseUrl(options?: ServiceEndpoint): string;
+export declare function resolveTcpEndpoint(options?: ServiceEndpoint): {
+    host: string;
+    port: number;
+};
+export declare function joinUrl(base: string, path: string): string;
+export declare function fillPath(template: string, params: Record<string, string | number>): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7B,CAAC;AAOF,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,eAAoB,GAAG,MAAM,CAaxE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,eAAoB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMhG;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAK1F"}

package/dist/config.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveHttpBaseUrl = resolveHttpBaseUrl;
+exports.resolveTcpEndpoint = resolveTcpEndpoint;
+exports.joinUrl = joinUrl;
+exports.fillPath = fillPath;
+const generated_1 = require("./generated");
+function env(name) {
+    const v = process.env[name];
+    return v && v.length > 0 ? v : undefined;
+}
+function resolveHttpBaseUrl(options = {}) {
+    if (options.baseUrl)
+        return options.baseUrl.replace(/\/$/, '');
+    const fromEnv = env(generated_1.ENV_KEYS.httpBaseUrl) ?? env('STORAGE_SERVICE_URL');
+    if (fromEnv)
+        return fromEnv.replace(/\/$/, '');
+    const host = options.host ?? env(generated_1.ENV_KEYS.host) ?? env('STORAGE_HOST') ?? '127.0.0.1';
+    const port = Number(options.port ?? env(generated_1.ENV_KEYS.httpPort) ?? env('STORAGE_HTTP_PORT') ?? generated_1.PORTS.http);
+    const protocol = options.protocol ?? (port === 443 ? 'https' : 'http');
+    const defaultPort = protocol === 'https' ? 443 : 80;
+    const authority = port === defaultPort ? host : `${host}:${port}`;
+    return `${protocol}://${authority}`;
+}
+function resolveTcpEndpoint(options = {}) {
+    const host = options.host ?? env(generated_1.ENV_KEYS.host) ?? env('STORAGE_HOST') ?? '127.0.0.1';
+    const port = Number(options.port ?? env(generated_1.ENV_KEYS.tcpPort) ?? env('STORAGE_TCP_PORT') ?? generated_1.PORTS.tcp);
+    return { host, port };
+}
+function joinUrl(base, path) {
+    const b = base.replace(/\/$/, '');
+    const p = path.startsWith('/') ? path : `/${path}`;
+    return `${b}${p}`;
+}
+function fillPath(template, params) {
+    return template.replace(/\{(\w+)\}/g, (_, key) => {
+        if (params[key] === undefined)
+            throw new Error(`Missing path param: ${key}`);
+        return encodeURIComponent(String(params[key]));
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/generated.d.ts

@@ -0,0 +1,89 @@
+export declare const PORTS: {
+    readonly tcp: 4002;
+    readonly http: 4000;
+};
+export declare const INJECTION_TOKEN: "STORAGE_SERVICE";
+export declare const DOCKER_IMAGE: "ghcr.io/yaghmori/storage-service";
+export declare const SERVICE_NAME: "storage-service";
+export declare const ENV_KEYS: {
+    readonly httpBaseUrl: "STORAGE_SERVICE_URL";
+    readonly host: "STORAGE_SERVICE_HOST";
+    readonly tcpPort: "STORAGE_SERVICE_TCP_PORT";
+    readonly httpPort: "STORAGE_SERVICE_HTTP_PORT";
+};
+export declare const PATTERNS: {
+    readonly GET_FILE_INFO: "storage.get_file_info";
+    readonly DELETE_FILE: "storage.delete_file";
+    readonly BATCH_OPERATIONS: "storage.batch_operations";
+    readonly GET_SIGNED_URL: "storage.get_signed_url";
+    readonly UPLOAD_FILE: "uploadFile";
+    readonly GET_ASSET_URL: "getAssetUrl";
+    readonly DELETE_ASSET: "deleteAsset";
+    readonly HEALTH_CHECK: "health.check";
+};
+export declare const HTTP_PATHS: {
+    readonly UPLOAD: "/upload";
+    readonly GET_FILE: "/files/{id}";
+    readonly DELETE_FILE: "/files/{id}";
+    readonly DOWNLOAD: "/files/{id}/download";
+    readonly SIGNED_URL: "/files/{id}/signed-url";
+    readonly HEALTH: "/health";
+};
+export declare const TOPICS: {
+    readonly FILE_UPLOADED: "file.uploaded";
+    readonly FILE_DELETED: "file.deleted";
+    readonly FILE_PROCESSED: "file.processed";
+};
+export declare const EVENT_TYPES: {
+    readonly UPLOADED: "evt.storage.file.uploaded.v1";
+    readonly DELETED: "evt.storage.file.deleted.v1";
+    readonly PROCESSED: "evt.storage.file.processed.v1";
+};
+export type StoragePattern = (typeof PATTERNS)[keyof typeof PATTERNS];
+export type StorageTopic = (typeof TOPICS)[keyof typeof TOPICS];
+export type StorageEventType = (typeof EVENT_TYPES)[keyof typeof EVENT_TYPES];
+export type StorageHttpPath = (typeof HTTP_PATHS)[keyof typeof HTTP_PATHS];
+export declare const StorageService: {
+    readonly name: "storage-service";
+    readonly token: "STORAGE_SERVICE";
+    readonly image: "ghcr.io/yaghmori/storage-service";
+    readonly ports: {
+        readonly tcp: 4002;
+        readonly http: 4000;
+    };
+    readonly env: {
+        readonly httpBaseUrl: "STORAGE_SERVICE_URL";
+        readonly host: "STORAGE_SERVICE_HOST";
+        readonly tcpPort: "STORAGE_SERVICE_TCP_PORT";
+        readonly httpPort: "STORAGE_SERVICE_HTTP_PORT";
+    };
+    readonly patterns: {
+        readonly GET_FILE_INFO: "storage.get_file_info";
+        readonly DELETE_FILE: "storage.delete_file";
+        readonly BATCH_OPERATIONS: "storage.batch_operations";
+        readonly GET_SIGNED_URL: "storage.get_signed_url";
+        readonly UPLOAD_FILE: "uploadFile";
+        readonly GET_ASSET_URL: "getAssetUrl";
+        readonly DELETE_ASSET: "deleteAsset";
+        readonly HEALTH_CHECK: "health.check";
+    };
+    readonly httpPaths: {
+        readonly UPLOAD: "/upload";
+        readonly GET_FILE: "/files/{id}";
+        readonly DELETE_FILE: "/files/{id}";
+        readonly DOWNLOAD: "/files/{id}/download";
+        readonly SIGNED_URL: "/files/{id}/signed-url";
+        readonly HEALTH: "/health";
+    };
+    readonly topics: {
+        readonly FILE_UPLOADED: "file.uploaded";
+        readonly FILE_DELETED: "file.deleted";
+        readonly FILE_PROCESSED: "file.processed";
+    };
+    readonly eventTypes: {
+        readonly UPLOADED: "evt.storage.file.uploaded.v1";
+        readonly DELETED: "evt.storage.file.deleted.v1";
+        readonly PROCESSED: "evt.storage.file.processed.v1";
+    };
+};
+//# sourceMappingURL=generated.d.ts.map

package/dist/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../src/generated.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,KAAK;;;CAGR,CAAC;AAEX,eAAO,MAAM,eAAe,EAAG,iBAA0B,CAAC;AAC1D,eAAO,MAAM,YAAY,EAAG,kCAA2C,CAAC;AACxE,eAAO,MAAM,YAAY,EAAG,iBAA0B,CAAC;AAEvD,eAAO,MAAM,QAAQ;;;;;CAKX,CAAC;AACX,eAAO,MAAM,QAAQ;;;;;;;;;CASX,CAAC;AACX,eAAO,MAAM,UAAU;;;;;;;CAOb,CAAC;AACX,eAAO,MAAM,MAAM;;;;CAIT,CAAC;AACX,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AACtE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAC9E,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAE3E,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAUjB,CAAC"}

package/dist/generated.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageService = exports.EVENT_TYPES = exports.TOPICS = exports.HTTP_PATHS = exports.PATTERNS = exports.ENV_KEYS = exports.SERVICE_NAME = exports.DOCKER_IMAGE = exports.INJECTION_TOKEN = exports.PORTS = void 0;
+/* AUTO-GENERATED from contracts.json - do not edit by hand. Run: pnpm run codegen */
+exports.PORTS = {
+    tcp: 4002,
+    http: 4000,
+};
+exports.INJECTION_TOKEN = "STORAGE_SERVICE";
+exports.DOCKER_IMAGE = "ghcr.io/yaghmori/storage-service";
+exports.SERVICE_NAME = "storage-service";
+exports.ENV_KEYS = {
+    httpBaseUrl: "STORAGE_SERVICE_URL",
+    host: "STORAGE_SERVICE_HOST",
+    tcpPort: "STORAGE_SERVICE_TCP_PORT",
+    httpPort: "STORAGE_SERVICE_HTTP_PORT",
+};
+exports.PATTERNS = {
+    GET_FILE_INFO: "storage.get_file_info",
+    DELETE_FILE: "storage.delete_file",
+    BATCH_OPERATIONS: "storage.batch_operations",
+    GET_SIGNED_URL: "storage.get_signed_url",
+    UPLOAD_FILE: "uploadFile",
+    GET_ASSET_URL: "getAssetUrl",
+    DELETE_ASSET: "deleteAsset",
+    HEALTH_CHECK: "health.check",
+};
+exports.HTTP_PATHS = {
+    UPLOAD: "/upload",
+    GET_FILE: "/files/{id}",
+    DELETE_FILE: "/files/{id}",
+    DOWNLOAD: "/files/{id}/download",
+    SIGNED_URL: "/files/{id}/signed-url",
+    HEALTH: "/health",
+};
+exports.TOPICS = {
+    FILE_UPLOADED: "file.uploaded",
+    FILE_DELETED: "file.deleted",
+    FILE_PROCESSED: "file.processed",
+};
+exports.EVENT_TYPES = {
+    UPLOADED: "evt.storage.file.uploaded.v1",
+    DELETED: "evt.storage.file.deleted.v1",
+    PROCESSED: "evt.storage.file.processed.v1",
+};
+exports.StorageService = {
+    name: exports.SERVICE_NAME,
+    token: exports.INJECTION_TOKEN,
+    image: exports.DOCKER_IMAGE,
+    ports: exports.PORTS,
+    env: exports.ENV_KEYS,
+    patterns: exports.PATTERNS,
+    httpPaths: exports.HTTP_PATHS,
+    topics: exports.TOPICS,
+    eventTypes: exports.EVENT_TYPES,
+};
+//# sourceMappingURL=generated.js.map

package/dist/generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.js","sourceRoot":"","sources":["../src/generated.ts"],"names":[],"mappings":";;;AAAA,qFAAqF;AACxE,QAAA,KAAK,GAAG;IACnB,GAAG,EAAE,IAAI;IACT,IAAI,EAAE,IAAI;CACF,CAAC;AAEE,QAAA,eAAe,GAAG,iBAA0B,CAAC;AAC7C,QAAA,YAAY,GAAG,kCAA2C,CAAC;AAC3D,QAAA,YAAY,GAAG,iBAA0B,CAAC;AAE1C,QAAA,QAAQ,GAAG;IACtB,WAAW,EAAE,qBAAqB;IAClC,IAAI,EAAE,sBAAsB;IAC5B,OAAO,EAAE,0BAA0B;IACnC,QAAQ,EAAE,2BAA2B;CAC7B,CAAC;AACE,QAAA,QAAQ,GAAG;IACtB,aAAa,EAAE,uBAAuB;IACtC,WAAW,EAAE,qBAAqB;IAClC,gBAAgB,EAAE,0BAA0B;IAC5C,cAAc,EAAE,wBAAwB;IACxC,WAAW,EAAE,YAAY;IACzB,aAAa,EAAE,aAAa;IAC5B,YAAY,EAAE,aAAa;IAC3B,YAAY,EAAE,cAAc;CACpB,CAAC;AACE,QAAA,UAAU,GAAG;IACxB,MAAM,EAAE,SAAS;IACjB,QAAQ,EAAE,aAAa;IACvB,WAAW,EAAE,aAAa;IAC1B,QAAQ,EAAE,sBAAsB;IAChC,UAAU,EAAE,wBAAwB;IACpC,MAAM,EAAE,SAAS;CACT,CAAC;AACE,QAAA,MAAM,GAAG;IACpB,aAAa,EAAE,eAAe;IAC9B,YAAY,EAAE,cAAc;IAC5B,cAAc,EAAE,gBAAgB;CACxB,CAAC;AACE,QAAA,WAAW,GAAG;IACzB,QAAQ,EAAE,8BAA8B;IACxC,OAAO,EAAE,6BAA6B;IACtC,SAAS,EAAE,+BAA+B;CAClC,CAAC;AAOE,QAAA,cAAc,GAAG;IAC5B,IAAI,EAAE,oBAAY;IAClB,KAAK,EAAE,uBAAe;IACtB,KAAK,EAAE,oBAAY;IACnB,KAAK,EAAE,aAAK;IACZ,GAAG,EAAE,gBAAQ;IACb,QAAQ,EAAE,gBAAQ;IAClB,SAAS,EAAE,kBAAU;IACrB,MAAM,EAAE,cAAM;IACd,UAAU,EAAE,mBAAW;CACf,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,22 @@
+import { type ServiceEndpoint } from './config';
+import { type ClientAuth } from './auth';
+export type StorageHttpClientOptions = ServiceEndpoint & {
+    auth?: ClientAuth | string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+};
+export declare class StorageHttpClient {
+    readonly baseUrl: string;
+    private readonly headers;
+    private readonly fetchImpl;
+    constructor(options?: StorageHttpClientOptions);
+    getFile(id: string): Promise<unknown>;
+    deleteFile(id: string): Promise<unknown>;
+    getSignedUrl(id: string): Promise<unknown>;
+    health(): Promise<unknown>;
+    upload(formData: FormData): Promise<unknown>;
+    private request;
+}
+export declare function createStorageHttpClient(options?: StorageHttpClientOptions): StorageHttpClient;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAG3D,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG;IACvD,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB,CAAC;AAEF,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,GAAE,wBAA6B;IAW5C,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1C,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAI1B,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;YAepC,OAAO;CAYtB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,iBAAiB,CAE7F"}

package/dist/http.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageHttpClient = void 0;
+exports.createStorageHttpClient = createStorageHttpClient;
+const config_1 = require("./config");
+const auth_1 = require("./auth");
+const generated_1 = require("./generated");
+class StorageHttpClient {
+    constructor(options = {}) {
+        this.baseUrl = (0, config_1.resolveHttpBaseUrl)(options);
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        const auth = options.auth ?? (options.apiKey ? { apiKey: options.apiKey } : undefined);
+        this.headers = {
+            accept: 'application/json',
+            ...(0, auth_1.buildAuthHeaders)(auth, 'STORAGE_SERVICE_API_KEY'),
+            ...options.headers,
+        };
+    }
+    async getFile(id) {
+        return this.request('GET', (0, config_1.fillPath)(generated_1.HTTP_PATHS.GET_FILE, { id }));
+    }
+    async deleteFile(id) {
+        return this.request('DELETE', (0, config_1.fillPath)(generated_1.HTTP_PATHS.DELETE_FILE, { id }));
+    }
+    async getSignedUrl(id) {
+        return this.request('GET', (0, config_1.fillPath)(generated_1.HTTP_PATHS.SIGNED_URL, { id }));
+    }
+    async health() {
+        return this.request('GET', generated_1.HTTP_PATHS.HEALTH);
+    }
+    async upload(formData) {
+        const headers = { ...this.headers };
+        delete headers['content-type'];
+        const res = await this.fetchImpl((0, config_1.joinUrl)(this.baseUrl, generated_1.HTTP_PATHS.UPLOAD), {
+            method: 'POST',
+            headers,
+            body: formData,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`storage-service HTTP ${res.status} POST ${generated_1.HTTP_PATHS.UPLOAD}: ${text}`);
+        }
+        return res.json();
+    }
+    async request(method, path) {
+        const res = await this.fetchImpl((0, config_1.joinUrl)(this.baseUrl, path), {
+            method,
+            headers: this.headers,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`storage-service HTTP ${res.status} ${method} ${path}: ${text}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+}
+exports.StorageHttpClient = StorageHttpClient;
+function createStorageHttpClient(options) {
+    return new StorageHttpClient(options);
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { StorageService, PORTS, PATTERNS, HTTP_PATHS, TOPICS, EVENT_TYPES, ENV_KEYS, INJECTION_TOKEN, DOCKER_IMAGE, SERVICE_NAME, } from './generated';
+export type { StoragePattern, StorageTopic, StorageEventType, StorageHttpPath, } from './generated';
+export * from './schemas';
+export { resolveHttpBaseUrl, resolveTcpEndpoint, joinUrl, fillPath, } from './config';
+export type { ServiceEndpoint } from './config';
+export { buildAuthHeaders, AUTH_HEADERS } from './auth';
+export type { ClientAuth } from './auth';
+export { StorageHttpClient, createStorageHttpClient } from './http';
+export type { StorageHttpClientOptions } from './http';
+export { StorageKafka, resolveKafkaConnection } from './kafka';
+export type { KafkaConnectionEnv } from './kafka';
+export { storageTcpClient } from './nest';
+export type { StorageTcpClientOptions } from './nest';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,EACL,QAAQ,EACR,UAAU,EACV,MAAM,EACN,WAAW,EACX,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,cAAc,WAAW,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,OAAO,EACP,QAAQ,GACT,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AACpE,YAAY,EAAE,wBAAwB,EAAE,MAAM,QAAQ,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC1C,YAAY,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,46 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageTcpClient = exports.resolveKafkaConnection = exports.StorageKafka = exports.createStorageHttpClient = exports.StorageHttpClient = exports.AUTH_HEADERS = exports.buildAuthHeaders = exports.fillPath = exports.joinUrl = exports.resolveTcpEndpoint = exports.resolveHttpBaseUrl = exports.SERVICE_NAME = exports.DOCKER_IMAGE = exports.INJECTION_TOKEN = exports.ENV_KEYS = exports.EVENT_TYPES = exports.TOPICS = exports.HTTP_PATHS = exports.PATTERNS = exports.PORTS = exports.StorageService = void 0;
+var generated_1 = require("./generated");
+Object.defineProperty(exports, "StorageService", { enumerable: true, get: function () { return generated_1.StorageService; } });
+Object.defineProperty(exports, "PORTS", { enumerable: true, get: function () { return generated_1.PORTS; } });
+Object.defineProperty(exports, "PATTERNS", { enumerable: true, get: function () { return generated_1.PATTERNS; } });
+Object.defineProperty(exports, "HTTP_PATHS", { enumerable: true, get: function () { return generated_1.HTTP_PATHS; } });
+Object.defineProperty(exports, "TOPICS", { enumerable: true, get: function () { return generated_1.TOPICS; } });
+Object.defineProperty(exports, "EVENT_TYPES", { enumerable: true, get: function () { return generated_1.EVENT_TYPES; } });
+Object.defineProperty(exports, "ENV_KEYS", { enumerable: true, get: function () { return generated_1.ENV_KEYS; } });
+Object.defineProperty(exports, "INJECTION_TOKEN", { enumerable: true, get: function () { return generated_1.INJECTION_TOKEN; } });
+Object.defineProperty(exports, "DOCKER_IMAGE", { enumerable: true, get: function () { return generated_1.DOCKER_IMAGE; } });
+Object.defineProperty(exports, "SERVICE_NAME", { enumerable: true, get: function () { return generated_1.SERVICE_NAME; } });
+__exportStar(require("./schemas"), exports);
+var config_1 = require("./config");
+Object.defineProperty(exports, "resolveHttpBaseUrl", { enumerable: true, get: function () { return config_1.resolveHttpBaseUrl; } });
+Object.defineProperty(exports, "resolveTcpEndpoint", { enumerable: true, get: function () { return config_1.resolveTcpEndpoint; } });
+Object.defineProperty(exports, "joinUrl", { enumerable: true, get: function () { return config_1.joinUrl; } });
+Object.defineProperty(exports, "fillPath", { enumerable: true, get: function () { return config_1.fillPath; } });
+var auth_1 = require("./auth");
+Object.defineProperty(exports, "buildAuthHeaders", { enumerable: true, get: function () { return auth_1.buildAuthHeaders; } });
+Object.defineProperty(exports, "AUTH_HEADERS", { enumerable: true, get: function () { return auth_1.AUTH_HEADERS; } });
+var http_1 = require("./http");
+Object.defineProperty(exports, "StorageHttpClient", { enumerable: true, get: function () { return http_1.StorageHttpClient; } });
+Object.defineProperty(exports, "createStorageHttpClient", { enumerable: true, get: function () { return http_1.createStorageHttpClient; } });
+var kafka_1 = require("./kafka");
+Object.defineProperty(exports, "StorageKafka", { enumerable: true, get: function () { return kafka_1.StorageKafka; } });
+Object.defineProperty(exports, "resolveKafkaConnection", { enumerable: true, get: function () { return kafka_1.resolveKafkaConnection; } });
+var nest_1 = require("./nest");
+Object.defineProperty(exports, "storageTcpClient", { enumerable: true, get: function () { return nest_1.storageTcpClient; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yCAWqB;AAVnB,2GAAA,cAAc,OAAA;AACd,kGAAA,KAAK,OAAA;AACL,qGAAA,QAAQ,OAAA;AACR,uGAAA,UAAU,OAAA;AACV,mGAAA,MAAM,OAAA;AACN,wGAAA,WAAW,OAAA;AACX,qGAAA,QAAQ,OAAA;AACR,4GAAA,eAAe,OAAA;AACf,yGAAA,YAAY,OAAA;AACZ,yGAAA,YAAY,OAAA;AASd,4CAA0B;AAC1B,mCAKkB;AAJhB,4GAAA,kBAAkB,OAAA;AAClB,4GAAA,kBAAkB,OAAA;AAClB,iGAAA,OAAO,OAAA;AACP,kGAAA,QAAQ,OAAA;AAIV,+BAAwD;AAA/C,wGAAA,gBAAgB,OAAA;AAAE,oGAAA,YAAY,OAAA;AAGvC,+BAAoE;AAA3D,yGAAA,iBAAiB,OAAA;AAAE,+GAAA,uBAAuB,OAAA;AAGnD,iCAA+D;AAAtD,qGAAA,YAAY,OAAA;AAAE,+GAAA,sBAAsB,OAAA;AAG7C,+BAA0C;AAAjC,wGAAA,gBAAgB,OAAA"}

package/dist/kafka.d.ts

@@ -0,0 +1,25 @@
+export type KafkaConnectionEnv = {
+    brokers: string[];
+    clientId: string;
+    ssl?: boolean;
+    sasl?: {
+        mechanism: 'plain' | 'scram-sha-256' | 'scram-sha-512';
+        username: string;
+        password: string;
+    };
+};
+export declare function resolveKafkaConnection(env?: NodeJS.ProcessEnv): KafkaConnectionEnv;
+export declare const StorageKafka: {
+    readonly topics: {
+        readonly FILE_UPLOADED: "file.uploaded";
+        readonly FILE_DELETED: "file.deleted";
+        readonly FILE_PROCESSED: "file.processed";
+    };
+    readonly eventTypes: {
+        readonly UPLOADED: "evt.storage.file.uploaded.v1";
+        readonly DELETED: "evt.storage.file.deleted.v1";
+        readonly PROCESSED: "evt.storage.file.processed.v1";
+    };
+    readonly connection: typeof resolveKafkaConnection;
+};
+//# sourceMappingURL=kafka.d.ts.map

package/dist/kafka.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kafka.d.ts","sourceRoot":"","sources":["../src/kafka.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE;QACL,SAAS,EAAE,OAAO,GAAG,eAAe,GAAG,eAAe,CAAC;QACvD,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,kBAAkB,CAqBpB;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;CAIf,CAAC"}

package/dist/kafka.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageKafka = void 0;
+exports.resolveKafkaConnection = resolveKafkaConnection;
+const generated_1 = require("./generated");
+function resolveKafkaConnection(env = process.env) {
+    const brokers = (env.KAFKA_BROKERS || env.KAFKA_BOOTSTRAP_SERVERS || 'localhost:9092')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const clientId = env.KAFKA_CLIENT_ID || 'storage-service-client';
+    const ssl = env.KAFKA_SSL === 'true' || env.KAFKA_SSL === '1';
+    const username = env.KAFKA_SASL_USERNAME || env.KAFKA_USERNAME;
+    const password = env.KAFKA_SASL_PASSWORD || env.KAFKA_PASSWORD;
+    const mechanism = (env.KAFKA_SASL_MECHANISM || 'plain').toLowerCase();
+    return {
+        brokers,
+        clientId,
+        ...(ssl ? { ssl: true } : {}),
+        ...(username && password ? { sasl: { mechanism, username, password } } : {}),
+    };
+}
+exports.StorageKafka = {
+    topics: generated_1.TOPICS,
+    eventTypes: generated_1.EVENT_TYPES,
+    connection: resolveKafkaConnection,
+};
+//# sourceMappingURL=kafka.js.map

package/dist/kafka.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kafka.js","sourceRoot":"","sources":["../src/kafka.ts"],"names":[],"mappings":";;;AAaA,wDAuBC;AApCD,2CAAkD;AAalD,SAAgB,sBAAsB,CACpC,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,aAAa,IAAI,GAAG,CAAC,uBAAuB,IAAI,gBAAgB,CAAC;SACnF,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnB,MAAM,QAAQ,GAAG,GAAG,CAAC,eAAe,IAAI,wBAAwB,CAAC;IACjE,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,KAAK,MAAM,IAAI,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC;IAC9D,MAAM,QAAQ,GAAG,GAAG,CAAC,mBAAmB,IAAI,GAAG,CAAC,cAAc,CAAC;IAC/D,MAAM,QAAQ,GAAG,GAAG,CAAC,mBAAmB,IAAI,GAAG,CAAC,cAAc,CAAC;IAC/D,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,oBAAoB,IAAI,OAAO,CAAC,CAAC,WAAW,EAGhD,CAAC;IAEpB,OAAO;QACL,OAAO;QACP,QAAQ;QACR,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,QAAQ,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7E,CAAC;AACJ,CAAC;AAEY,QAAA,YAAY,GAAG;IAC1B,MAAM,EAAE,kBAAM;IACd,UAAU,EAAE,uBAAW;IACvB,UAAU,EAAE,sBAAsB;CAC1B,CAAC"}

package/dist/nest.d.ts

@@ -0,0 +1,7 @@
+import type { ClientProviderOptions } from '@nestjs/microservices';
+import { type ServiceEndpoint } from './config';
+export type StorageTcpClientOptions = ServiceEndpoint & {
+    name?: string | symbol;
+};
+export declare function storageTcpClient(options?: StorageTcpClientOptions): ClientProviderOptions;
+//# sourceMappingURL=nest.d.ts.map

package/dist/nest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest.d.ts","sourceRoot":"","sources":["../src/nest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAGpE,MAAM,MAAM,uBAAuB,GAAG,eAAe,GAAG;IACtD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,qBAAqB,CAO7F"}

package/dist/nest.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageTcpClient = storageTcpClient;
+const microservices_1 = require("@nestjs/microservices");
+const config_1 = require("./config");
+const generated_1 = require("./generated");
+function storageTcpClient(options = {}) {
+    const { host, port } = (0, config_1.resolveTcpEndpoint)(options);
+    return {
+        name: options.name ?? generated_1.INJECTION_TOKEN,
+        transport: microservices_1.Transport.TCP,
+        options: { host, port },
+    };
+}
+//# sourceMappingURL=nest.js.map

package/dist/nest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest.js","sourceRoot":"","sources":["../src/nest.ts"],"names":[],"mappings":";;AASA,4CAOC;AAfD,yDAAkD;AAClD,qCAAoE;AACpE,2CAA8C;AAM9C,SAAgB,gBAAgB,CAAC,UAAmC,EAAE;IACpE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAA,2BAAkB,EAAC,OAAO,CAAC,CAAC;IACnD,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,2BAAe;QACrC,SAAS,EAAE,yBAAS,CAAC,GAAG;QACxB,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;KACxB,CAAC;AACJ,CAAC"}

package/dist/schemas.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export declare const getFileInfoRequestSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    key?: string | undefined;
+}, {
+    id?: string | undefined;
+    key?: string | undefined;
+}>;
+export type GetFileInfoRequest = z.infer<typeof getFileInfoRequestSchema>;
+export declare const getSignedUrlRequestSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+    expiresInSeconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    key?: string | undefined;
+    expiresInSeconds?: number | undefined;
+}, {
+    id?: string | undefined;
+    key?: string | undefined;
+    expiresInSeconds?: number | undefined;
+}>;
+export type GetSignedUrlRequest = z.infer<typeof getSignedUrlRequestSchema>;
+export declare const deleteFileRequestSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    key?: string | undefined;
+}, {
+    id?: string | undefined;
+    key?: string | undefined;
+}>;
+export type DeleteFileRequest = z.infer<typeof deleteFileRequestSchema>;
+export declare const BATCH_OPERATION_TYPES: {
+    readonly GET: "get";
+    readonly DELETE: "delete";
+};
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,wBAAwB;;;;;;;;;EAGnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;EAIpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,uBAAuB;;;;;;;;;EAGlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,qBAAqB;;;CAGxB,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BATCH_OPERATION_TYPES = exports.deleteFileRequestSchema = exports.getSignedUrlRequestSchema = exports.getFileInfoRequestSchema = void 0;
+const zod_1 = require("zod");
+const uuidSchema = zod_1.z.string().uuid();
+const nonEmptyStringSchema = zod_1.z.string().min(1);
+exports.getFileInfoRequestSchema = zod_1.z.object({
+    id: uuidSchema.optional(),
+    key: nonEmptyStringSchema.optional(),
+});
+exports.getSignedUrlRequestSchema = zod_1.z.object({
+    id: uuidSchema.optional(),
+    key: nonEmptyStringSchema.optional(),
+    expiresInSeconds: zod_1.z.number().int().positive().optional(),
+});
+exports.deleteFileRequestSchema = zod_1.z.object({
+    id: uuidSchema.optional(),
+    key: nonEmptyStringSchema.optional(),
+});
+exports.BATCH_OPERATION_TYPES = {
+    GET: 'get',
+    DELETE: 'delete',
+};
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,MAAM,UAAU,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;AACrC,MAAM,oBAAoB,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAElC,QAAA,wBAAwB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE;IACzB,GAAG,EAAE,oBAAoB,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAGU,QAAA,yBAAyB,GAAG,OAAC,CAAC,MAAM,CAAC;IAChD,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE;IACzB,GAAG,EAAE,oBAAoB,CAAC,QAAQ,EAAE;IACpC,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACzD,CAAC,CAAC;AAGU,QAAA,uBAAuB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9C,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE;IACzB,GAAG,EAAE,oBAAoB,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAGU,QAAA,qBAAqB,GAAG;IACnC,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,QAAQ;CACR,CAAC"}

package/docs/BEST_PRACTICES.md

@@ -0,0 +1,9 @@
+# Best practices — storage-service client
+
+See also email-service `docs/BEST_PRACTICES.md` (same transport / auth model).
+
+- **HTTP** for signed URL / upload from apps with `x-api-key`.
+- **TCP** for internal Nest↔Nest or .NET↔Nest (`StorageServiceTcpClient`).
+- **Kafka** for async file events (`StorageService.Topics.*`).
+- Configure with `STORAGE_SERVICE_*` env or `StorageServiceOptions` — any host/port.
+- Keep TCP private; do not expose `TCP_PORT` publicly.

package/docs/NUGET_TRUSTED_PUBLISHING.md

@@ -0,0 +1,18 @@
+# Publish .NET SDK to nuget.org (Trusted Publishing)
+
+No long-lived API key required. Full steps mirror email-service:
+
+→ [Trusted Publishing on nuget.org](https://learn.microsoft.com/en-us/nuget/nuget-org/trusted-publishing)
+
+## Quick setup
+
+1. nuget.org → **Trusted Publishing** → policy:
+   - Repository owner: `yaghmori`
+   - Repository: `storage-service`
+   - Workflow: `cd-main.yml` (filename only)
+2. GitHub → Settings → Secrets and variables → Actions → **Variables** → `NUGET_USER` = nuget.org **username** (not email, not API key).
+3. CD uses `permissions.id-token: write` + `NuGet/login@v1` → temp key → `dotnet nuget push`.
+
+Private repos: one successful login within 7 days permanently activates the policy.
+
+After it works, revoke any old nuget.org API keys / `NUGET_TOKEN`.

package/docs/PROTOCOL_GUIDE.md

@@ -0,0 +1,200 @@
+# Multi-protocol client guide (storage-service)
+
+Full integration guide for **storage-service** over **HTTP**, **NestJS TCP**, and **Kafka** from **Node.js**, **.NET**. Companion to the email-service protocol guide — same auth, framing, and env conventions, different contracts.
+
+| Artifact | Location |
+|----------|----------|
+| Truth file | `packages/client/contracts.json` |
+| Node SDK | `@yaghmori/storage-service` |
+| .NET SDK | `Yaghmori.StorageService` |
+| Docker | `ghcr.io/yaghmori/storage-service` |
+
+```bash
+cd packages/client && pnpm run codegen
+```
+
+Default suggestions: TCP **4002**, HTTP **4000** (override freely).
+
+---
+
+## 1. Protocol selection
+
+| Protocol | Use for | Auth |
+|----------|---------|------|
+| **HTTP** | Uploads/downloads/signed URLs from apps and gateways | `x-api-key` / Bearer JWT |
+| **TCP** | Metadata RPCs (file info, delete, signed URL) inside the mesh | Network trust |
+| **Kafka** | Async lifecycle (`file.uploaded` / `deleted` / `processed`) | Cluster SASL/SSL |
+
+Binary uploads are **HTTP multipart** (or your existing upload path). Prefer signing downloads rather than streaming huge files over TCP.
+
+---
+
+## 2. Address resolution
+
+| Client env | Purpose |
+|------------|---------|
+| `STORAGE_SERVICE_URL` | Full HTTP base |
+| `STORAGE_SERVICE_HOST` | Host for TCP/HTTP fallback |
+| `STORAGE_SERVICE_TCP_PORT` | TCP dial port |
+| `STORAGE_SERVICE_HTTP_PORT` | HTTP dial port if URL omitted |
+| `STORAGE_SERVICE_API_KEY` / `STORAGE_SERVICE_BEARER` | HTTP auth |
+
+Service listen: `PORT` (HTTP), `TCP_PORT` (Nest TCP). Kafka: same `KAFKA_*` variables as email-service.
+
+Priority: constructor options → env → contract defaults.
+
+---
+
+## 3. Authentication (HTTP)
+
+Identical header contract to email-service:
+
+- `x-api-key: <key>` (preferred for API keys)
+- `Authorization: Bearer <jwt>`
+- `Authorization: ApiKey <key>`
+
+Service: `AUTH_API_KEYS`, `JWT_SECRET`, or `AUTH_DISABLED=true` on trusted meshes only. `GET /health` may be `@Public()`.
+
+Never expose TCP publicly. Never put API keys in `Authorization: Bearer`.
+
+---
+
+## 4. HTTP paths (contracts)
+
+| Constant | Path | Notes |
+|----------|------|-------|
+| `UPLOAD` | `POST /upload` | Multipart / binary upload |
+| `GET_FILE` | `GET /files/{id}` | Metadata |
+| `DELETE_FILE` | `DELETE /files/{id}` | Soft/hard delete per service |
+| `DOWNLOAD` | `GET /files/{id}/download` | Stream or redirect |
+| `SIGNED_URL` | `GET /files/{id}/signed-url` | Time-limited URL |
+| `HEALTH` | `GET /health` | Liveness |
+
+SDK HTTP helpers currently emphasize signed URL + health; extend with multipart upload using the same auth headers and `HttpPaths.Upload`.
+
+Best practices:
+
+- Short-lived signed URLs for browsers/CDN.
+- Timeouts longer for upload/download (60–120s) than for metadata.
+- Retry 408/429/5xx with backoff; never retry non-idempotent uploads without an idempotency key.
+- Do not log storage keys or full signed URLs in cleartext logs.
+
+---
+
+## 5. NestJS TCP
+
+Framing: `<utf8-byte-length>#<json>` (same as email).
+
+| Constant | Pattern |
+|----------|---------|
+| `GET_FILE_INFO` | `storage.get_file_info` |
+| `DELETE_FILE` | `storage.delete_file` |
+| `BATCH_OPERATIONS` | `storage.batch_operations` |
+| `GET_SIGNED_URL` | `storage.get_signed_url` |
+| `UPLOAD_FILE` | `uploadFile` |
+| `GET_ASSET_URL` | `getAssetUrl` |
+| `DELETE_ASSET` | `deleteAsset` |
+| `HEALTH_CHECK` | `health.check` |
+
+Request/response includes `id`; events omit `id`. SDKs throw when response `err` is set.
+
+---
+
+## 6. Kafka
+
+| Topic constant | Topic | Event type |
+|----------------|-------|------------|
+| `FILE_UPLOADED` | `file.uploaded` | `evt.storage.file.uploaded.v1` |
+| `FILE_DELETED` | `file.deleted` | `evt.storage.file.deleted.v1` |
+| `FILE_PROCESSED` | `file.processed` | `evt.storage.file.processed.v1` |
+
+Producer defaults: `acks=all`, idempotent, retries, JSON values. Consumers: manual commit, dedicated group IDs, subscribe to the topics above.
+
+Typical pattern: service publishes lifecycle events after successful storage mutations; other services react (thumbnails, antivirus, analytics) without calling TCP on the hot path.
+
+---
+
+## 7. Node.js
+
+```ts
+import {
+  createStorageHttpClient,
+  storageTcpClient,
+  StorageService,
+  resolveKafkaConnection,
+} from '@yaghmori/storage-service';
+
+const http = createStorageHttpClient({
+  baseUrl: process.env.STORAGE_SERVICE_URL,
+  auth: { apiKey: process.env.STORAGE_SERVICE_API_KEY! },
+});
+
+const tcp = storageTcpClient({
+  host: process.env.STORAGE_SERVICE_HOST,
+  port: Number(process.env.STORAGE_SERVICE_TCP_PORT),
+});
+
+const kafkaConn = resolveKafkaConnection();
+// pass kafkaConn to kafkajs; use StorageService.topics.*
+```
+
+---
+
+## 8. .NET
+
+```csharp
+services.AddStorageServiceClient();
+
+await using var tcp = new StorageServiceTcpClient(new StorageServiceOptions
+{
+    Host = "storage-service",
+    TcpPort = 4002,
+});
+var info = await tcp.GetFileInfoAsync<JsonElement>(new { id = fileId });
+
+using var http = new StorageServiceHttpClient(new StorageServiceOptions
+{
+    BaseUrl = "https://storage.prod.example.com",
+    ApiKey = Environment.GetEnvironmentVariable("STORAGE_SERVICE_API_KEY"),
+});
+using var signed = await http.GetSignedUrlAsync(fileId);
+
+using var producer = new StorageKafkaProducer(new StorageKafkaOptions());
+await producer.PublishAsync(StorageService.Topics.FileUploaded, new { id = fileId });
+
+using var consumer = new StorageKafkaConsumer(new StorageKafkaOptions(), "media-pipeline");
+```
+
+`NestJsTcpClient` implements framing. Constants are PascalCase (`StorageService.Patterns.GetSignedUrl`).
+
+---
+
+
+## 10. Security checklist
+
+- [ ] Authenticated HTTP on every non-health route
+- [ ] Private TCP
+- [ ] Signed URLs expire and use HTTPS
+- [ ] Kafka SASL/SSL in shared clusters
+- [ ] Separate API keys per environment
+- [ ] No PII in object keys if avoidable; scrub logs
+
+---
+
+## 11. Debugging
+
+| Symptom | Check |
+|---------|-------|
+| 401 | `x-api-key` vs `AUTH_API_KEYS` |
+| Wrong file host | `STORAGE_SERVICE_URL` vs service `PORT` |
+| TCP pattern miss | Compare to `contracts.json` (legacy `uploadFile` vs `storage.*`) |
+| Signed URL 404 | File id / soft-delete |
+| Missed Kafka events | Group id, topic name, consumer lag |
+
+---
+
+## 12. Codegen
+
+Edit `contracts.json` only; regenerate TS/C#. Align breaking path/pattern/topic changes with a SemVer bump of the client packages.
+
+See also [`USAGE.md`](./USAGE.md) and email-service `PROTOCOL_GUIDE.md` for framing/auth deep dives shared across services.

package/docs/USAGE.md

@@ -0,0 +1,162 @@
+# Full SDK usage — @yaghmori/storage-service
+
+HTTP + TCP + Kafka names + auth. Deploy on **any host/port**; configure the SDK.
+
+## Install / run
+
+```bash
+pnpm add @yaghmori/storage-service zod
+docker pull ghcr.io/yaghmori/storage-service:latest
+```
+
+```bash
+docker run --rm -p 9000:9000 -p 5002:5002 \
+  -e PORT=9000 -e TCP_PORT=5002 \
+  -e AUTH_API_KEYS=dev-key \
+  -e DATABASE_URL=... \
+  ghcr.io/yaghmori/storage-service:latest
+```
+
+## Configure address / ports
+
+| | Client options | Client env | Service env |
+|--|----------------|------------|-------------|
+| HTTP | `baseUrl` / `host`+`port` | `STORAGE_SERVICE_URL` or `HOST`+`HTTP_PORT` | `PORT` |
+| TCP | `storageTcpClient({ host, port })` | `STORAGE_SERVICE_HOST`, `STORAGE_SERVICE_TCP_PORT` | `TCP_PORT` |
+| Kafka | `StorageKafka.connection()` | `KAFKA_BROKERS`, SASL_*, SSL | same |
+
+## Auth (HTTP)
+
+Same contract as email-service:
+
+| Mode | Service config | Client |
+|------|----------------|--------|
+| API key | `AUTH_API_KEYS=k1,k2` | `auth: { apiKey }` → `x-api-key` |
+| JWT | `JWT_SECRET` + Bearer with `serviceName` | `auth: { bearerToken }` |
+| Open | `AUTH_DISABLED=true` | omit auth |
+| Health | always public | `GET /health` |
+
+TCP: private network. Kafka: broker SASL/SSL via env (not HTTP API keys).
+
+```ts
+import { createStorageHttpClient } from '@yaghmori/storage-service';
+
+const storage = createStorageHttpClient({
+  baseUrl: process.env.STORAGE_SERVICE_URL,
+  auth: { apiKey: process.env.STORAGE_SERVICE_API_KEY! },
+});
+```
+
+## HTTP
+
+```ts
+await storage.upload(formData);
+await storage.getFile(id);
+await storage.getSignedUrl(id);
+await storage.deleteFile(id);
+await storage.health();
+```
+
+## Nest TCP
+
+```ts
+import { ClientsModule } from '@nestjs/microservices';
+import { storageTcpClient, StorageService } from '@yaghmori/storage-service';
+
+ClientsModule.register([
+  storageTcpClient({
+    host: process.env.STORAGE_SERVICE_HOST ?? 'storage-service',
+    port: Number(process.env.STORAGE_SERVICE_TCP_PORT ?? 4002),
+  }),
+]);
+
+// client.send(StorageService.patterns.GET_SIGNED_URL, { id })
+```
+
+## Kafka
+
+```ts
+import { Kafka } from 'kafkajs';
+import { StorageKafka, StorageService } from '@yaghmori/storage-service';
+
+const conn = StorageKafka.connection();
+const kafka = new Kafka({
+  clientId: conn.clientId,
+  brokers: conn.brokers,
+  ssl: conn.ssl,
+  sasl: conn.sasl as any,
+});
+
+// Consume / produce using package topic names:
+StorageService.topics.FILE_UPLOADED;
+StorageService.eventTypes.UPLOADED;
+```
+
+## .NET
+
+```xml
+<PackageReference Include="Yaghmori.StorageService" Version="0.1.*" />
+```
+
+### TCP (easiest)
+
+```csharp
+using Yaghmori.StorageService;
+
+await using var storage = new StorageServiceTcpClient("storage-service", 5002);
+
+var signed = await storage.GetSignedUrlAsync<JsonElement>(new { id = fileId });
+var info = await storage.GetFileInfoAsync<JsonElement>(new { id = fileId });
+
+// Or any pattern
+await storage.SendAsync<JsonElement>(StorageService.Patterns.DeleteFile, new { id = fileId });
+```
+
+### DI
+
+```csharp
+builder.Services.AddStorageServiceClient(o =>
+{
+    o.Host = "storage-service";
+    o.TcpPort = 4002;
+    o.BaseUrl = "http://storage-service:4000";
+    o.ApiKey = builder.Configuration["Storage:ApiKey"];
+});
+```
+
+### HTTP
+
+```csharp
+using var http = new StorageServiceHttpClient(new StorageServiceOptions
+{
+    BaseUrl = Environment.GetEnvironmentVariable("STORAGE_SERVICE_URL"),
+    ApiKey = Environment.GetEnvironmentVariable("STORAGE_SERVICE_API_KEY"),
+});
+await http.GetSignedUrlAsync(fileId);
+await http.HealthAsync();
+```
+
+### Kafka producer + consumer (.NET)
+
+```csharp
+using var producer = new StorageKafkaProducer(new StorageKafkaOptions());
+await producer.PublishAsync(StorageService.Topics.FileUploaded, new { id = fileId });
+
+using var consumer = new StorageKafkaConsumer(new StorageKafkaOptions(), "media-pipeline");
+```
+
+
+## Full multi-protocol guide
+
+→ **[PROTOCOL_GUIDE.md](./PROTOCOL_GUIDE.md)** — HTTP / TCP / Kafka for Node and .NET.
+
+## Service env
+
+```bash
+PORT=9000
+TCP_PORT=5002
+AUTH_API_KEYS=prod-key
+# AUTH_DISABLED=true
+JWT_SECRET=...          # optional for Bearer
+KAFKA_BROKERS=...
+```

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@yaghmori/storage-service",
+  "version": "0.1.1",
+  "description": "Client SDK for storage-service — ports, TCP patterns, Kafka topics, Zod DTOs",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./nest": {
+      "types": "./dist/nest.d.ts",
+      "default": "./dist/nest.js"
+    }
+  },
+  "files": [
+    "dist",
+    "contracts.json",
+    "README.md",
+    "docs"
+  ],
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/microservices": "^11.0.0",
+    "rxjs": "^7.8.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/microservices": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/microservices": "^11.0.0",
+    "@types/node": "^22.15.3",
+    "rxjs": "^7.8.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yaghmori/storage-service.git",
+    "directory": "packages/client"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "codegen": "node scripts/codegen.cjs",
+    "build": "pnpm run codegen && tsc -p tsconfig.json",
+    "check-types": "tsc -p tsconfig.json --noEmit"
+  }
+}