@dudousxd/nestjs-agent 1.9.0 → 1.10.0

package/dist/media/index.js

@@ -0,0 +1,608 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/media/media-attachment-staging.ts
+import { randomUUID } from "crypto";
+import { publishMedia } from "@dudousxd/nestjs-media";
+import { BadRequestException, ConflictException, Logger, NotImplementedException, PayloadTooLargeException, UnprocessableEntityException, UnsupportedMediaTypeException } from "@nestjs/common";
+
+// src/media/media-attachments.options.ts
+var DEFAULT_AGENT_MEDIA_COLLECTION = "agent-attachments";
+var DEFAULT_AGENT_MEDIA_OWNER_TYPE = "agent-actor";
+var DEFAULT_AGENT_MEDIA_URL_TTL_SECONDS = 7 * 24 * 60 * 60;
+var DEFAULT_AGENT_MEDIA_TUS_BASE_PATH = "/media/uploads";
+
+// src/media/media-attachment-staging.ts
+var DEFAULT_MAX_BYTES = 20 * 1024 * 1024;
+var DEFAULT_ALLOWED_CONTENT_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "application/pdf",
+  "text/plain",
+  "text/csv"
+];
+var MediaAttachmentStaging2 = class _MediaAttachmentStaging {
+  static {
+    __name(this, "MediaAttachmentStaging");
+  }
+  deps;
+  options;
+  logger = new Logger(_MediaAttachmentStaging.name);
+  collection;
+  ownerType;
+  maxBytes;
+  allowed;
+  now;
+  newId;
+  warnedInline = false;
+  constructor(deps, options) {
+    this.deps = deps;
+    this.options = options;
+    this.collection = options.collection ?? DEFAULT_AGENT_MEDIA_COLLECTION;
+    this.ownerType = options.ownerType ?? DEFAULT_AGENT_MEDIA_OWNER_TYPE;
+    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.allowed = options.allowedContentTypes ?? DEFAULT_ALLOWED_CONTENT_TYPES;
+    this.now = options.clock ?? (() => /* @__PURE__ */ new Date());
+    this.newId = options.idGenerator ?? (() => randomUUID());
+  }
+  get diskName() {
+    return this.options.disk ?? this.deps.storage.defaultDisk;
+  }
+  /** Open a tus session for one file, owned by `actor`. Validation happens here, before any byte moves. */
+  async beginUpload(input) {
+    const uploads = this.deps.uploads;
+    if (uploads === null) {
+      throw new NotImplementedException("Resumable attachment uploads need MediaModule configured with `uploadSessions` and `tus`.");
+    }
+    this.validate(input.filename, input.contentType, input.size);
+    const id = this.newId();
+    const fileName = safeFileName(input.filename);
+    const path = this.pathFor(input.actor, id, fileName);
+    const session = await uploads.createUpload({
+      disk: this.diskName,
+      key: path,
+      size: input.size,
+      contentType: input.contentType,
+      metadata: {
+        agentMediaId: id
+      }
+    });
+    await this.saveRecord({
+      id,
+      actor: input.actor,
+      fileName,
+      mimeType: input.contentType,
+      size: input.size,
+      path,
+      state: {
+        status: "pending",
+        uploadId: session.id
+      }
+    });
+    const base = (this.options.tusBasePath ?? DEFAULT_AGENT_MEDIA_TUS_BASE_PATH).replace(/\/+$/, "");
+    return {
+      mediaId: id,
+      uploadId: session.id,
+      location: `${base}/${session.id}`
+    };
+  }
+  /**
+  * Confirm the bytes of a `beginUpload` landed and whole. `null` for an unknown or foreign id;
+  * `409` while the bytes are still missing; `422` (and the record dropped) when what arrived is
+  * not the size that was declared. Idempotent on a ready record.
+  */
+  async completeUpload(input) {
+    const record = await this.ownRecord(input.mediaId, input.actor);
+    if (record === null) return null;
+    const ready = await this.ensureReady(record);
+    if (ready === "missing") {
+      throw new ConflictException(`upload ${input.mediaId} has not finished`);
+    }
+    if (ready === "mismatch") {
+      await this.remove(record.id);
+      throw new UnprocessableEntityException(`upload ${input.mediaId} does not match its declared size`);
+    }
+    return this.toAttachment(ready, {
+      forModel: false
+    });
+  }
+  /** The actor drops one of their own attachments — aborting its upload if still in flight. */
+  async discard(input) {
+    const record = await this.ownRecord(input.mediaId, input.actor);
+    if (record === null) return false;
+    await this.remove(record.id);
+    return true;
+  }
+  /**
+  * Delete an attachment's bytes, its in-flight tus session and its record. NO ownership check —
+  * the host's sweep calls this for what `AgentService.collectableAttachments` returned.
+  */
+  async remove(mediaId) {
+    const record = await this.deps.store.find(mediaId);
+    if (record === null || !this.isOurs(record)) return;
+    const state = stateOf(record);
+    if (state.status === "pending" && state.uploadId !== void 0) {
+      await this.deps.uploads?.abort(state.uploadId).catch(() => void 0);
+    }
+    await this.deps.storage.disk(record.disk).delete(record.path).catch(() => void 0);
+    await this.deps.store.delete(record.id);
+    if (this.options.indexForRag === true && state.status === "ready") {
+      publishMedia("delete", {
+        id: record.id,
+        ownerType: record.ownerType,
+        ownerId: record.ownerId
+      });
+    }
+  }
+  async stage(input) {
+    const id = this.newId();
+    const fileName = safeFileName(input.filename);
+    const path = this.pathFor(input.actor, id, fileName);
+    await this.deps.storage.disk(this.diskName).put(path, input.data, {
+      contentType: input.contentType
+    });
+    const record = await this.saveRecord({
+      id,
+      actor: input.actor,
+      fileName,
+      mimeType: input.contentType,
+      size: input.sizeBytes,
+      path,
+      state: {
+        status: "ready"
+      }
+    });
+    this.announce(record);
+    return this.toAttachment(record, {
+      forModel: false
+    });
+  }
+  /**
+  * The attachment for `mediaId`, or `null` when it is unknown, not this actor's, or its bytes have
+  * not (fully) arrived. The actor may use media they own, and media a message in one of THEIR
+  * threads already carries (a fork, a regenerate) — never anything else.
+  */
+  async resolve(input) {
+    const record = await this.deps.store.find(input.mediaId);
+    if (record === null || !this.isOurs(record)) return null;
+    if (!await this.canUse(record, input.actor)) return null;
+    const ready = await this.ensureReady(record);
+    if (typeof ready === "string") return null;
+    return this.toAttachment(ready, {
+      forModel: true
+    });
+  }
+  async list(input) {
+    const records = await this.deps.store.listByOwner(this.ownerType, input.actor.id, this.collection);
+    const entries = records.map((record) => ({
+      mediaId: record.id,
+      name: record.fileName,
+      contentType: record.mimeType,
+      sizeBytes: record.size,
+      createdAt: new Date(record.createdAt).toISOString()
+    })).filter((entry) => input.stagedBefore === void 0 || entry.createdAt < input.stagedBefore).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    return input.limit === void 0 ? entries : entries.slice(0, input.limit);
+  }
+  validate(filename, contentType, size) {
+    if (typeof filename !== "string" || filename.trim().length === 0) {
+      throw new BadRequestException("filename is required");
+    }
+    if (typeof contentType !== "string" || !this.allowed.includes(contentType)) {
+      throw new UnsupportedMediaTypeException(`content type "${String(contentType)}" is not allowed (allowed: ${this.allowed.join(", ")})`);
+    }
+    if (typeof size !== "number" || !Number.isInteger(size) || size <= 0) {
+      throw new BadRequestException("size must be a positive integer byte count");
+    }
+    if (size > this.maxBytes) {
+      throw new PayloadTooLargeException(`file exceeds the ${this.maxBytes}-byte limit`);
+    }
+  }
+  pathFor(actor, id, fileName) {
+    return `${this.ownerType}/${encodeURIComponent(actor.id)}/${this.collection}/${id}/${fileName}`;
+  }
+  async saveRecord(input) {
+    const timestamp = this.now();
+    return this.deps.store.save({
+      id: input.id,
+      ownerType: this.ownerType,
+      ownerId: input.actor.id,
+      collection: this.collection,
+      name: stripExtension(input.fileName),
+      fileName: input.fileName,
+      mimeType: input.mimeType,
+      size: input.size,
+      disk: this.diskName,
+      path: input.path,
+      order: await this.deps.store.nextOrder(this.ownerType, input.actor.id, this.collection),
+      customProperties: {
+        agentAttachment: input.state
+      },
+      conversions: {},
+      createdAt: timestamp,
+      updatedAt: timestamp
+    });
+  }
+  isOurs(record) {
+    return record.ownerType === this.ownerType && record.collection === this.collection;
+  }
+  async ownRecord(mediaId, actor) {
+    const record = await this.deps.store.find(mediaId);
+    if (record === null || !this.isOurs(record) || record.ownerId !== actor.id) return null;
+    return record;
+  }
+  async canUse(record, actor) {
+    const allowed = await this.defaultAccess(record, actor);
+    const custom = this.options.canAccess;
+    return custom === void 0 ? allowed : await custom({
+      record,
+      actor,
+      allowed
+    }) === true;
+  }
+  async defaultAccess(record, actor) {
+    if (record.ownerId === actor.id) return true;
+    const referenced = this.deps.agentStore?.referencedMediaIds?.bind(this.deps.agentStore);
+    if (referenced === void 0) return false;
+    return (await referenced(actor.id, [
+      record.id
+    ])).includes(record.id);
+  }
+  /**
+  * A ready record as-is; a pending one promoted to ready once its bytes are on the disk at exactly
+  * the declared size. `'missing'` while they are not; `'mismatch'` when they arrived at another size.
+  */
+  async ensureReady(record) {
+    if (stateOf(record).status === "ready") return record;
+    const disk = this.deps.storage.disk(record.disk);
+    if (!await disk.exists(record.path)) return "missing";
+    const size = await disk.size(record.path);
+    if (size !== record.size || size > this.maxBytes) return "mismatch";
+    const ready = await this.deps.store.save({
+      ...record,
+      customProperties: {
+        ...record.customProperties,
+        agentAttachment: {
+          status: "ready"
+        }
+      },
+      updatedAt: this.now()
+    });
+    this.announce(ready);
+    return ready;
+  }
+  announce(record) {
+    if (this.options.indexForRag !== true) return;
+    publishMedia("attach", {
+      id: record.id,
+      ownerType: record.ownerType,
+      ownerId: record.ownerId,
+      collection: record.collection,
+      disk: record.disk,
+      path: record.path,
+      size: record.size,
+      mimeType: record.mimeType
+    });
+  }
+  /**
+  * `forModel: false` is what goes back to the uploader: never inline bytes (they already have the
+  * file), so an inline-only disk answers with an empty url there.
+  */
+  async toAttachment(record, { forModel }) {
+    const base = {
+      mediaId: record.id,
+      contentType: record.mimeType,
+      name: record.fileName
+    };
+    const disk = this.deps.storage.disk(record.disk);
+    if (this.options.resolveUrl !== void 0) {
+      return {
+        ...base,
+        url: await this.options.resolveUrl(record, {
+          disk
+        })
+      };
+    }
+    if (this.options.visibility === "public") {
+      return {
+        ...base,
+        url: await disk.url(record.path)
+      };
+    }
+    if (disk.capabilities.presign) {
+      const ttl = this.options.urlExpiresInSeconds ?? DEFAULT_AGENT_MEDIA_URL_TTL_SECONDS;
+      return {
+        ...base,
+        url: await disk.temporaryUrl(record.path, ttl, {
+          responseContentType: record.mimeType
+        })
+      };
+    }
+    if (!forModel) return {
+      ...base,
+      url: ""
+    };
+    if (!this.warnedInline) {
+      this.warnedInline = true;
+      this.logger.warn(`disk "${record.disk}" cannot presign urls: attachments reach the model inline (data: urls, persisted with each message). Use a presign-capable disk or resolveUrl in production.`);
+    }
+    const bytes = await disk.get(record.path);
+    return {
+      ...base,
+      url: `data:${record.mimeType};base64,${bytes.toString("base64")}`
+    };
+  }
+};
+function stateOf(record) {
+  const state = record.customProperties.agentAttachment;
+  return state ?? {
+    status: "ready"
+  };
+}
+__name(stateOf, "stateOf");
+function safeFileName(filename) {
+  const last = filename.split(/[\\/]/).pop() ?? "";
+  const cleaned = last.replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  return cleaned === "" || cleaned === "." || cleaned === ".." ? "file" : cleaned;
+}
+__name(safeFileName, "safeFileName");
+function stripExtension(fileName) {
+  const dot = fileName.lastIndexOf(".");
+  return dot > 0 ? fileName.slice(0, dot) : fileName;
+}
+__name(stripExtension, "stripExtension");
+
+// src/media/media-attachments.module.ts
+import { AGENT_ATTACHMENT_STAGING, AGENT_STORE } from "@dudousxd/nestjs-agent-core";
+import { MEDIA_STORAGE_SHARED, MEDIA_STORE, MEDIA_UPLOADS } from "@dudousxd/nestjs-media";
+import { Global, Module } from "@nestjs/common";
+import { RouterModule } from "@nestjs/core";
+
+// src/media/media-uploads.controller.ts
+import { AGENT_ACTOR_RESOLVER } from "@dudousxd/nestjs-agent-core";
+import { BadRequestException as BadRequestException2, Body, Controller, Delete, HttpCode, Inject, NotFoundException, Param, Post, Req } from "@nestjs/common";
+
+// src/media/tokens.ts
+var AGENT_MEDIA_ATTACHMENTS = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:media-attachments");
+var AGENT_MEDIA_ATTACHMENTS_OPTIONS = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:media-attachments-options");
+
+// src/media/media-uploads.controller.ts
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata, "_ts_metadata");
+function _ts_param(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param, "_ts_param");
+var AgentMediaUploadsController = class {
+  static {
+    __name(this, "AgentMediaUploadsController");
+  }
+  actorResolver;
+  staging;
+  constructor(actorResolver, staging) {
+    this.actorResolver = actorResolver;
+    this.staging = staging;
+  }
+  /** `{ filename, contentType, size }` → `{ mediaId, uploadId, location }`. */
+  async begin(req, body) {
+    if (typeof body !== "object" || body === null) {
+      throw new BadRequestException2("body must be { filename, contentType, size }");
+    }
+    const { filename, contentType, size } = body;
+    const actor = await this.actorResolver.resolve(req);
+    return this.staging.beginUpload({
+      actor,
+      filename,
+      contentType,
+      size
+    });
+  }
+  async complete(req, mediaId) {
+    const actor = await this.actorResolver.resolve(req);
+    const attachment = await this.staging.completeUpload({
+      actor,
+      mediaId
+    });
+    if (attachment === null) throw new NotFoundException(`attachment ${mediaId} not found`);
+    return attachment;
+  }
+  async discard(req, mediaId) {
+    const actor = await this.actorResolver.resolve(req);
+    if (!await this.staging.discard({
+      actor,
+      mediaId
+    })) {
+      throw new NotFoundException(`attachment ${mediaId} not found`);
+    }
+  }
+};
+_ts_decorate([
+  Post(),
+  _ts_param(0, Req()),
+  _ts_param(1, Body()),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    Object
+  ]),
+  _ts_metadata("design:returntype", Promise)
+], AgentMediaUploadsController.prototype, "begin", null);
+_ts_decorate([
+  Post(":mediaId/complete"),
+  HttpCode(200),
+  _ts_param(0, Req()),
+  _ts_param(1, Param("mediaId")),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    String
+  ]),
+  _ts_metadata("design:returntype", Promise)
+], AgentMediaUploadsController.prototype, "complete", null);
+_ts_decorate([
+  Delete(":mediaId"),
+  HttpCode(204),
+  _ts_param(0, Req()),
+  _ts_param(1, Param("mediaId")),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    String
+  ]),
+  _ts_metadata("design:returntype", Promise)
+], AgentMediaUploadsController.prototype, "discard", null);
+AgentMediaUploadsController = _ts_decorate([
+  Controller("attachments/uploads"),
+  _ts_param(0, Inject(AGENT_ACTOR_RESOLVER)),
+  _ts_param(1, Inject(AGENT_MEDIA_ATTACHMENTS)),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof ActorResolver === "undefined" ? Object : ActorResolver,
+    typeof MediaAttachmentStaging === "undefined" ? Object : MediaAttachmentStaging
+  ])
+], AgentMediaUploadsController);
+
+// src/media/media-attachments.module.ts
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+var GUARDS_METADATA = "__guards__";
+function stagingProvider() {
+  return {
+    provide: AGENT_MEDIA_ATTACHMENTS,
+    inject: [
+      AGENT_MEDIA_ATTACHMENTS_OPTIONS,
+      MEDIA_STORAGE_SHARED,
+      MEDIA_STORE,
+      MEDIA_UPLOADS,
+      {
+        token: AGENT_STORE,
+        optional: true
+      }
+    ],
+    useFactory: /* @__PURE__ */ __name((options, storage, store, uploads, agentStore) => {
+      if (store === null) {
+        throw new Error("AgentMediaAttachmentsModule: MediaModule has no `store`. Chat attachments are media records, so configure MediaModule with a MediaStore (e.g. a database adapter).");
+      }
+      return new MediaAttachmentStaging2({
+        storage,
+        store,
+        uploads,
+        ...agentStore !== void 0 ? {
+          agentStore
+        } : {}
+      }, options);
+    }, "useFactory")
+  };
+}
+__name(stagingProvider, "stagingProvider");
+function build(mount, optionsProvider, imports = []) {
+  const routes = mount.routes !== false;
+  Reflect.defineMetadata(GUARDS_METADATA, mount.guards ?? [], AgentMediaUploadsController);
+  const guards = [
+    ...new Set(mount.guards ?? [])
+  ];
+  return {
+    module: AgentMediaAttachmentsModule,
+    global: true,
+    imports: [
+      ...imports,
+      ...routes ? [
+        RouterModule.register([
+          {
+            path: mount.path ?? "agent",
+            module: AgentMediaAttachmentsModule
+          }
+        ])
+      ] : []
+    ],
+    controllers: routes ? [
+      AgentMediaUploadsController
+    ] : [],
+    providers: [
+      optionsProvider,
+      stagingProvider(),
+      {
+        provide: AGENT_ATTACHMENT_STAGING,
+        useExisting: AGENT_MEDIA_ATTACHMENTS
+      },
+      {
+        provide: MediaAttachmentStaging2,
+        useExisting: AGENT_MEDIA_ATTACHMENTS
+      },
+      ...guards
+    ],
+    exports: [
+      AGENT_ATTACHMENT_STAGING,
+      AGENT_MEDIA_ATTACHMENTS,
+      MediaAttachmentStaging2
+    ]
+  };
+}
+__name(build, "build");
+var AgentMediaAttachmentsModule = class {
+  static {
+    __name(this, "AgentMediaAttachmentsModule");
+  }
+  static forRoot(options = {}) {
+    return build(options, {
+      provide: AGENT_MEDIA_ATTACHMENTS_OPTIONS,
+      useValue: options
+    });
+  }
+  static forRootAsync(options) {
+    return build(options, {
+      provide: AGENT_MEDIA_ATTACHMENTS_OPTIONS,
+      inject: options.inject ?? [],
+      useFactory: options.useFactory
+    }, options.imports);
+  }
+};
+AgentMediaAttachmentsModule = _ts_decorate2([
+  Global(),
+  Module({})
+], AgentMediaAttachmentsModule);
+export {
+  AGENT_MEDIA_ATTACHMENTS,
+  AGENT_MEDIA_ATTACHMENTS_OPTIONS,
+  AgentMediaAttachmentsModule,
+  AgentMediaUploadsController,
+  DEFAULT_AGENT_MEDIA_COLLECTION,
+  DEFAULT_AGENT_MEDIA_OWNER_TYPE,
+  DEFAULT_AGENT_MEDIA_TUS_BASE_PATH,
+  DEFAULT_AGENT_MEDIA_URL_TTL_SECONDS,
+  MediaAttachmentStaging2 as MediaAttachmentStaging
+};
+//# sourceMappingURL=index.js.map