@futdevpro/nts-dynamo 1.15.121 → 1.15.122

package/src/_modules/ftp/_services/ftp-service.api-service.ts

@@ -0,0 +1,120 @@
+import { DyFM_HttpCallType } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_ApiService } from '../../../_services/core/api.service';
+import { DyNTS_ApiCall_Params, DyNTS_HttpOptions } from '../../../_models/control-models/api-call-params.control-model';
+import { DyNTS_FtpUrlSigner_Util } from '../_collections/ftp-url-signer.util';
+
+/** A signed UPLOAD-aláírás érvényessége (10 perc) — a szerver-szerver app→ftp feltöltés szinkron, rövid ablak elég. */
+const FTP_SIGNED_UPLOAD_TTL_MS: number = 10 * 60 * 1000;
+/** A signed SERVE-URL alap-élettartama (30 nap) — a felhasználó később is letölti a fájlt. */
+const FTP_SIGNED_SERVE_TTL_MS: number = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * FTP-kliens KONFIG (a consumer adja át — PURE: nincs fdp-templates-függés).
+ * A `fdp-ftp-service` URL-jei + a megosztott aláíró-titok a hívó-oldalról jönnek.
+ */
+export interface DyNTS_FtpService_Config {
+  /** az `fdp-ftp-service` API base-URL a szerver-szerver feltöltéshez (pl. `FDP_ftpServiceApiEnv_settings.baseUrl.fromBE`). */
+  apiBaseUrl: string;
+  /** a publikus serve-host az aláírt letöltő-URL-ekhez (pl. `FDP_ftpServiceApiEnv_settings.baseUrl.siteAddress`). */
+  serveBaseUrl: string;
+  /** a megosztott HMAC-titok (env-var `FTP_URL_SIGNING_SECRET`, MÁR létező). Üres → a serve-gate inaktív. */
+  signingSecret: string;
+  /** az upload-endpoint (default `/files/upload`). */
+  uploadFileEndpoint?: string;
+}
+
+/** FTP-feltöltés bemenete. */
+export interface DyNTS_FtpService_UploadFile_Input {
+  accountId: string;
+  folderPath: string;
+  fileName: string;
+  fileBuffer: Buffer;
+}
+
+/** FTP-feltöltés válasza. */
+export interface DyNTS_FtpService_UploadFile_Response {
+  filePath: string;
+  ftpPath: string;
+}
+
+/**
+ * FTP Service API kliens (deep/generikus — `@futdevpro/nts-dynamo`).
+ * @description A szerver-oldali FTP-KLIENS: a meglévő `fdp-ftp-service` tároló-szervert HÍVJA — fájlt tölt
+ *   fel (signed upload), és aláírt serve-URL-t épít. **NEM tartalmaz FTP-szervert.** A korábban az
+ *   MP-be / token-service-be duplikált FTP-kliens EGYETLEN, flotta-közös kiváltása.
+ *
+ *   **PURE (ADR-004):** a config (URL-ek + titok) a `DyNTS_FtpService_Config`-ból, a hívó adja át —
+ *   nincs `fdp-templates`-import. Nem singleton: minden consumer a saját config-jával példányosít.
+ *
+ * @example
+ * ```ts
+ * const ftp: DyNTS_FtpService_ApiService = new DyNTS_FtpService_ApiService({
+ *   apiBaseUrl: FDP_ftpServiceApiEnv_settings.baseUrl.fromBE,
+ *   serveBaseUrl: FDP_ftpServiceApiEnv_settings.baseUrl.siteAddress,
+ *   signingSecret: process.env.FTP_URL_SIGNING_SECRET || '',
+ * });
+ * const { ftpPath } = await ftp.uploadFile({ accountId, folderPath: 'invoices/<userId>', fileName, fileBuffer });
+ * const url: string = ftp.buildSignedServeUrl(ftpPath);
+ * ```
+ */
+export class DyNTS_FtpService_ApiService {
+
+  private readonly config: DyNTS_FtpService_Config;
+
+  constructor(config: DyNTS_FtpService_Config) {
+    this.config = config;
+  }
+
+  private get uploadFileEndpoint(): string {
+    return this.config.uploadFileEndpoint ?? '/files/upload';
+  }
+
+  /**
+   * Fájl feltöltése az `fdp-ftp-service`-re (signed, szerver-szerver).
+   * @description A kanonikus upload-célt + lejáratot HMAC-aláírjuk a megosztott titokkal; az ftp ezt
+   *   validálja (a signature a KONKRÉT account+path-hoz köt — más account-ra nem replay-elhető).
+   */
+  async uploadFile(input: DyNTS_FtpService_UploadFile_Input): Promise<DyNTS_FtpService_UploadFile_Response> {
+    const expMs: number = Date.now() + FTP_SIGNED_UPLOAD_TTL_MS;
+    const uploadTarget: string = DyNTS_FtpUrlSigner_Util.uploadTarget(input.accountId, input.folderPath, input.fileName);
+    const sig: string = DyNTS_FtpUrlSigner_Util.sign(uploadTarget, expMs, this.config.signingSecret);
+
+    return await DyNTS_ApiService.startApiCall<DyNTS_FtpService_UploadFile_Response>(
+      new DyNTS_ApiCall_Params({
+        name: 'uploadFile (DyNTS_FtpService)',
+        type: DyFM_HttpCallType.post,
+        baseUrl: this.config.apiBaseUrl,
+        endpoint: this.uploadFileEndpoint,
+        httpOptions: new DyNTS_HttpOptions({
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        }),
+      }),
+      {
+        body: {
+          accountId: input.accountId,
+          folderPath: input.folderPath,
+          fileName: input.fileName,
+          fileBuffer: input.fileBuffer.toString('base64'),
+          exp: expMs,
+          sig: sig,
+        },
+      },
+    );
+  }
+
+  /**
+   * Aláírt serve-URL egy `ftpPath`-ból (böngésző-letöltéshez). Üres titok → üres string (gate inaktív).
+   * @param ttlMs opcionális egyedi élettartam; default 30 nap.
+   */
+  buildSignedServeUrl(ftpPath: string, ttlMs: number = FTP_SIGNED_SERVE_TTL_MS): string {
+    return DyNTS_FtpUrlSigner_Util.buildSignedServeUrl({
+      serveBaseUrl: this.config.serveBaseUrl,
+      ftpPath: ftpPath,
+      ttlMs: ttlMs,
+      secret: this.config.signingSecret,
+    });
+  }
+}

package/src/_modules/ftp/index.ts

@@ -0,0 +1,7 @@
+export { DyNTS_FtpUrlSigner_Util } from './_collections/ftp-url-signer.util';
+export {
+  DyNTS_FtpService_ApiService,
+  DyNTS_FtpService_Config,
+  DyNTS_FtpService_UploadFile_Input,
+  DyNTS_FtpService_UploadFile_Response,
+} from './_services/ftp-service.api-service';