@thomasfosterau/pulpit 0.0.0-stage → 0.1.0

package/dist/working-copy.js

@@ -0,0 +1,95 @@
+/**
+ * **The working copy** — an editor's autosave buffer, kept outside the
+ * version chain and overwritten freely, which an explicit save appends as
+ * one ordinary `update` version.
+ *
+ * ## The model (owner decisions on pulpit#46)
+ *
+ * - **Nothing in a working copy is a version**: saving it writes only the
+ *   {@link WorkingCopyStore}, so `VERSION-CHAIN-001` is untouched and a
+ *   hundred autosaves leave no trace in history.
+ * - **One copy per (node, editor)**, so two editors never overwrite each
+ *   other's unsaved work.
+ * - **`commit` appends the copy** through the leaf's own `update`, expecting
+ *   the head the copy was first based on: an edit landing in between fails
+ *   `StaleVersion` (and keeps the copy), so a commit never silently
+ *   overwrites work its editor didn't see. A committed copy is cleared.
+ * - **Every operation is gated like a write** (the leaf's `authorize`):
+ *   reading a copy shows unpublished state, so it is gated like the head.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/working-copy
+ * @since 0.1.0
+ */
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Record from "effect/Record";
+import * as Schema from "effect/Schema";
+import { NodeNotFound, } from "./version-chain.js";
+/**
+ * No working copy to commit: the wire's 404.
+ *
+ * @since 0.1.0
+ */
+export class WorkingCopyNotFound extends Schema.TaggedError()("WorkingCopyNotFound", { type: Schema.String, id: Schema.String }) {
+}
+const nowDate = Effect.map(Clock.currentTimeMillis, (millis) => DateTime.toDate(DateTime.makeUnsafe(millis)));
+/**
+ * Bind a leaf's working copies: `leaf` gates and commits, `chain` reads
+ * the head a new copy is based on, `store` keeps the copies.
+ *
+ * @since 0.1.0
+ */
+export const defineWorkingCopy = (definition) => {
+    const { leaf, chain, store } = definition;
+    const type = leaf.type;
+    const keyFor = (id) => Effect.map(leaf.authorize(id), (account) => ({ id, userId: account.id }));
+    const save = Effect.fn(`${type}.workingCopy.save`)(function* (id, patch) {
+        const key = yield* keyFor(id);
+        const head = yield* chain.head(id);
+        if (Option.isNone(head) || head.value.action === "delete") {
+            return yield* new NodeNotFound({ type, id });
+        }
+        const earlier = yield* store.get(key);
+        const copy = {
+            patch: Option.match(earlier, {
+                onNone: () => patch,
+                // An absent (or `undefined`) key in the new patch keeps the copy's own.
+                onSome: (existing) => ({
+                    ...existing.patch,
+                    ...Record.filter(patch, (value) => value !== undefined),
+                }),
+            }),
+            baseVersion: Option.match(earlier, {
+                onNone: () => head.value.version,
+                onSome: (existing) => existing.baseVersion,
+            }),
+            savedAt: yield* nowDate,
+        };
+        yield* store.put(key, copy);
+        return copy;
+    });
+    const get = Effect.fn(`${type}.workingCopy.get`)(function* (id) {
+        return yield* store.get(yield* keyFor(id));
+    });
+    const discard = Effect.fn(`${type}.workingCopy.discard`)(function* (id) {
+        yield* store.discard(yield* keyFor(id));
+    });
+    const commit = Effect.fn(`${type}.workingCopy.commit`)(function* (id) {
+        const key = yield* keyFor(id);
+        const copy = yield* store.get(key);
+        if (Option.isNone(copy))
+            return yield* new WorkingCopyNotFound({ type, id });
+        const written = yield* leaf.update({
+            id,
+            patch: copy.value.patch,
+            expectedVersion: copy.value.baseVersion,
+        });
+        yield* store.discard(key);
+        return written;
+    });
+    return { save, get, discard, commit };
+};
+//# sourceMappingURL=working-copy.js.map

package/dist/working-copy.js.map

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

package/package.json

@@ -1,6 +1,148 @@
 {
   "name": "@thomasfosterau/pulpit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The versioned-content kernel for an Effect headless CMS: Content model fields and registry flags on effect-jsonapi, the append-only node/version chain operations, the subtype operation factory with owned/reference access, and the publication / moderation / cache-serveability predicates.",
+  "keywords": [
+    "cms",
+    "effect",
+    "effect-schema",
+    "headless-cms",
+    "json-api",
+    "jsonapi",
+    "typescript",
+    "versioning"
+  ],
+  "homepage": "https://github.com/thomasfosterau/pulpit#readme",
+  "bugs": {
+    "url": "https://github.com/thomasfosterau/pulpit/issues"
+  },
+  "license": "MIT",
+  "author": "Thomas Foster <me@thomasfoster.au>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thomasfosterau/pulpit.git",
+    "directory": "packages/pulpit"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./content": {
+      "types": "./dist/content.d.ts",
+      "default": "./dist/content.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "default": "./dist/registry.js"
+    },
+    "./version-chain": {
+      "types": "./dist/version-chain.d.ts",
+      "default": "./dist/version-chain.js"
+    },
+    "./filter": {
+      "types": "./dist/filter.d.ts",
+      "default": "./dist/filter.js"
+    },
+    "./subtype": {
+      "types": "./dist/subtype.d.ts",
+      "default": "./dist/subtype.js"
+    },
+    "./publication": {
+      "types": "./dist/publication.d.ts",
+      "default": "./dist/publication.js"
+    },
+    "./cache": {
+      "types": "./dist/cache.d.ts",
+      "default": "./dist/cache.js"
+    },
+    "./documents": {
+      "types": "./dist/documents.d.ts",
+      "default": "./dist/documents.js"
+    },
+    "./edges": {
+      "types": "./dist/edges.d.ts",
+      "default": "./dist/edges.js"
+    },
+    "./proposals": {
+      "types": "./dist/proposals.d.ts",
+      "default": "./dist/proposals.js"
+    },
+    "./blobs": {
+      "types": "./dist/blobs.d.ts",
+      "default": "./dist/blobs.js"
+    },
+    "./paths": {
+      "types": "./dist/paths.d.ts",
+      "default": "./dist/paths.js"
+    },
+    "./collections": {
+      "types": "./dist/collections.d.ts",
+      "default": "./dist/collections.js"
+    },
+    "./moderation": {
+      "types": "./dist/moderation.d.ts",
+      "default": "./dist/moderation.js"
+    },
+    "./working-copy": {
+      "types": "./dist/working-copy.d.ts",
+      "default": "./dist/working-copy.js"
+    },
+    "./comments": {
+      "types": "./dist/comments.d.ts",
+      "default": "./dist/comments.js"
+    },
+    "./purge": {
+      "types": "./dist/purge.d.ts",
+      "default": "./dist/purge.js"
+    },
+    "./search": {
+      "types": "./dist/search.d.ts",
+      "default": "./dist/search.js"
+    },
+    "./budgets": {
+      "types": "./dist/budgets.d.ts",
+      "default": "./dist/budgets.js"
+    },
+    "./reactions": {
+      "types": "./dist/reactions.d.ts",
+      "default": "./dist/reactions.js"
+    },
+    "./social": {
+      "types": "./dist/social.d.ts",
+      "default": "./dist/social.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@effect/docgen": "^4.1.2",
+    "@effect/language-service": "^0.87.5",
+    "@thomasfosterau/effect-jsonapi": "^0.20.0",
+    "@types/node": "^26.6.6",
+    "@vitest/coverage-istanbul": "5.0.5",
+    "effect": "4.1.2",
+    "tsx": "^4.23.13"
+  },
+  "peerDependencies": {
+    "@thomasfosterau/effect-jsonapi": ">=0.17.0",
+    "effect": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
 }

package/src/blobs.ts

@@ -0,0 +1,384 @@
+/**
+ * **File and media leaves** — the blob-store seam a file leaf's bytes live
+ * behind, the field spread a file version carries, the commit-ordered byte
+ * write, and the usage index as an edge family.
+ *
+ * The behavioural spec is gardeneria's `apps/api/src/operations/media.ts`
+ * (bytes written only after the transaction commits) and `apps/api/src/files.ts`
+ * (the content hash), and website's `apps/api/src/operations/file-chain.ts`.
+ *
+ * ## The model (owner decisions on pulpit#55)
+ *
+ * - **Bytes are keyed by their content hash** ({@link blobKey}), so a
+ *   version's bytes are immutable: new bytes are a new hash and a new
+ *   version, and `restoreVersion` restores the reference to the old bytes,
+ *   which are still there. Equal bytes are stored once.
+ * - **Bytes are written after the chain commits.** {@link defineFileWrites}
+ *   appends the version first, marked `bytesPending: true` unless the store
+ *   already holds the bytes, puts the bytes once the transaction has
+ *   returned, and then appends `bytesPending: false`. A byte write that
+ *   fails leaves the node visibly incomplete: `bytesPending` stays `true`
+ *   and {@link fileUrl} gives no URL, so no reader is ever pointed at
+ *   missing bytes. `confirmBytes` finishes it later, once the bytes are
+ *   there.
+ * - **Nothing garbage-collects bytes.** They stay for as long as any
+ *   version references them; purge (pulpit#58) is the only removal path,
+ *   which is what {@link BlobStore.delete} is for.
+ * - **"Where is this file used" is an edge family** ({@link fileUsageEnds}),
+ *   so the endpoint-visibility gate (`EDGE-001`) applies: a "used by" list
+ *   never reveals content the viewer can't see. Maintaining those edges is
+ *   the referencing leaf's job (or an after hook's).
+ *
+ * The adapters (R2, S3), image transforms, EXIF extraction and video
+ * streaming are the application's.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/blobs
+ * @since 0.1.0
+ */
+
+import { Resource } from "@thomasfosterau/effect-jsonapi";
+import * as Arr from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import type { EdgeEnd, EdgeEnds } from "./edges.ts";
+import type { Forbidden, SubtypeOps, Unauthorized, WriteRejected } from "./subtype.ts";
+import type {
+  ChainState,
+  ChainWrite,
+  NodeAlreadyExists,
+  NodeNotFound,
+  Precondition,
+  StaleVersion,
+  VersionConflict,
+} from "./version-chain.ts";
+
+// ── Vocabulary ────────────────────────────────────────────────────────
+
+/**
+ * A file's content hash: the SHA-256 digest of its bytes as 64 lowercase
+ * hexadecimal characters ({@link sha256Hex}).
+ *
+ * @since 0.1.0
+ */
+export const ContentHash = Schema.String.check(
+  Schema.isPattern(/^[0-9a-f]{64}$/, {
+    description: "a SHA-256 content hash as 64 lowercase hexadecimal characters",
+  }),
+);
+/**
+ * The {@link ContentHash} string.
+ *
+ * @since 0.1.0
+ */
+export type ContentHash = typeof ContentHash.Type;
+
+/**
+ * The SHA-256 content hash of `bytes`, through the platform's Web Crypto
+ * (`globalThis.crypto.subtle`, in browsers, Node 22+ and Workers alike).
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { sha256Hex } from "@thomasfosterau/pulpit/blobs";
+ *
+ * strictEqual(
+ *   await Effect.runPromise(sha256Hex(new TextEncoder().encode("abc"))),
+ *   "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const sha256Hex = (bytes: Uint8Array): Effect.Effect<ContentHash> =>
+  Effect.tryPromise(() => globalThis.crypto.subtle.digest("SHA-256", Uint8Array.from(bytes))).pipe(
+    // Web Crypto's SHA-256 over bytes has no failure a caller could act on.
+    Effect.orDie,
+    Effect.map((digest) =>
+      Arr.map(Arr.fromIterable(new Uint8Array(digest)), (byte) =>
+        byte.toString(16).padStart(2, "0"),
+      ).join(""),
+    ),
+  );
+
+/**
+ * The blob-store key for a content hash: `sha256/<hash>`. The key is
+ * derived from the bytes alone, never from a node id, so a node's history
+ * can point at every set of bytes it has ever had.
+ *
+ * @since 0.1.0
+ */
+export const blobKey = (hash: ContentHash): string => `sha256/${hash}`;
+
+/**
+ * What the blob store knows of one stored object.
+ *
+ * @since 0.1.0
+ */
+export interface BlobHead {
+  readonly byteSize: number;
+  readonly mediaType: string;
+}
+
+// ── The seam ──────────────────────────────────────────────────────────
+
+/**
+ * The byte store an application supplies (R2, S3, a local directory). It
+ * applies no policy and fails only with its `E`. Keys come from
+ * {@link blobKey}; see the package README → Seams for the contract.
+ *
+ * @since 0.1.0
+ */
+export interface BlobStore<E, R> {
+  /** Store `bytes` at `key`. Idempotent: the same key always holds the same bytes. */
+  readonly put: (key: string, bytes: Uint8Array, head: BlobHead) => Effect.Effect<void, E, R>;
+  /** The bytes at `key`, or none. */
+  readonly get: (key: string) => Effect.Effect<Option.Option<Uint8Array>, E, R>;
+  /** The object's size and media type, or none when nothing is stored at `key`. */
+  readonly head: (key: string) => Effect.Effect<Option.Option<BlobHead>, E, R>;
+  /** Remove the object at `key`. Purge's alone (pulpit#58): nothing else deletes bytes. */
+  readonly delete: (key: string) => Effect.Effect<void, E, R>;
+  /** The URL a reader fetches `key` from, when the store serves one. */
+  readonly publicUrl: (key: string) => Option.Option<string>;
+  /** A signed URL a client may upload `key`'s bytes to directly, when the store offers one. */
+  readonly signedUploadUrl: Option.Option<
+    (key: string, head: BlobHead) => Effect.Effect<string, E, R>
+  >;
+}
+
+// ── The field spread ──────────────────────────────────────────────────
+
+/**
+ * The attributes every file version carries, all server-computed from the
+ * upload and present on the resource only (`readOnlyAttribute`): the
+ * `contentHash` its bytes are stored under, their `byteSize` and
+ * `mediaType`, the original `filename`, and `bytesPending`, `true` while the
+ * bytes are not yet confirmed in the blob store. Spread into a file leaf's
+ * `Resource.make({ attributes })`.
+ *
+ * @since 0.1.0
+ */
+export const fileResourceFields = {
+  contentHash: Resource.readOnlyAttribute(ContentHash),
+  byteSize: Resource.readOnlyAttribute(Schema.Finite),
+  mediaType: Resource.readOnlyAttribute(Schema.String),
+  filename: Resource.readOnlyAttribute(Schema.String),
+  bytesPending: Resource.readOnlyAttribute(Schema.Boolean),
+} as const;
+
+/**
+ * A file version's columns, as {@link defineFileWrites} writes them.
+ *
+ * @since 0.1.0
+ */
+export interface FileColumns {
+  readonly contentHash: ContentHash;
+  readonly byteSize: number;
+  readonly mediaType: string;
+  readonly filename: string;
+  readonly bytesPending: boolean;
+}
+
+/**
+ * The URL a file version's bytes are read from: none while `bytesPending`
+ * (anything but an explicit `false`), and none when the store serves no
+ * URL, so no reader is pointed at bytes that may not be there.
+ *
+ * @since 0.1.0
+ */
+export const fileUrl = <E, R>(
+  file: { readonly contentHash: ContentHash; readonly bytesPending: boolean },
+  blobs: Pick<BlobStore<E, R>, "publicUrl">,
+): Option.Option<string> =>
+  !file.bytesPending ? blobs.publicUrl(blobKey(file.contentHash)) : Option.none();
+
+// ── The commit-ordered write ──────────────────────────────────────────
+
+/**
+ * An upload: the bytes and what the client said they are.
+ *
+ * @since 0.1.0
+ */
+export interface Upload {
+  readonly bytes: Uint8Array;
+  readonly mediaType: string;
+  readonly filename: string;
+}
+
+/**
+ * What a file write reports: the version it landed at, its content hash,
+ * and whether its bytes are still pending (the post-commit byte write
+ * failed, or its confirmation did).
+ *
+ * @since 0.1.0
+ */
+export interface FileWrite extends ChainWrite {
+  readonly contentHash: ContentHash;
+  readonly bytesPending: boolean;
+}
+
+type WriteFailure = Unauthorized | Forbidden | WriteRejected | VersionConflict;
+
+/**
+ * The operations {@link defineFileWrites} produces.
+ *
+ * @since 0.1.0
+ */
+export interface FileWriteOps<E, R> {
+  /**
+   * Create a file node from an upload, with the leaf's other columns in
+   * `state`. Fails as the leaf's `create` does; a failure to store the
+   * bytes after the commit does not fail it (the node is left
+   * `bytesPending`).
+   */
+  readonly create: (input: {
+    readonly id: Option.Option<string>;
+    readonly state: ChainState;
+    readonly upload: Upload;
+  }) => Effect.Effect<FileWrite, WriteFailure | NodeAlreadyExists | E, R>;
+  /**
+   * Replace a file node's bytes with a new version. Fails as the leaf's
+   * `update` does (`StaleVersion` against `expectedVersion`, `NodeNotFound`
+   * for a missing or tombstoned node).
+   */
+  readonly replace: (
+    input: { readonly id: string; readonly upload: Upload } & Precondition,
+  ) => Effect.Effect<FileWrite, WriteFailure | NodeNotFound | StaleVersion | E, R>;
+  /**
+   * Finish a pending version (`version`, whose bytes `contentHash` names,
+   * as a {@link FileWrite} reports them): when the store now holds those
+   * bytes, append `bytesPending: false` over exactly that version and
+   * report `false`; otherwise write nothing and report `true`. Gated as the
+   * leaf's `update` is; `StaleVersion` when the node has moved past
+   * `version` (its head names other bytes).
+   */
+  readonly confirmBytes: (input: {
+    readonly id: string;
+    readonly version: bigint;
+    readonly contentHash: ContentHash;
+  }) => Effect.Effect<boolean, WriteFailure | NodeNotFound | StaleVersion | E, R>;
+}
+
+/**
+ * Bind a file leaf's commit-ordered writes: the version is appended (in
+ * `transact`, the caller's write boundary) before any byte is written, and
+ * the bytes go to the blob store only once it has returned. Each version
+ * write goes through the leaf's own operations, so their gates,
+ * preconditions and before hooks apply; the cache write-through and after
+ * hooks are `subtypeHandlers`', which an application that caches the leaf
+ * runs itself.
+ *
+ * @since 0.1.0
+ */
+export const defineFileWrites = <Resource, E, R>(definition: {
+  readonly leaf: SubtypeOps<Resource, E, R>;
+  readonly blobs: BlobStore<E, R>;
+  readonly transact: <A, E2>(effect: Effect.Effect<A, E2, R>) => Effect.Effect<A, E2, R>;
+}): FileWriteOps<E, R> => {
+  const { leaf, blobs, transact } = definition;
+
+  /** The upload's columns, pending unless the store already holds its bytes. */
+  const columnsOf = (upload: Upload) =>
+    Effect.gen(function* () {
+      const contentHash = yield* sha256Hex(upload.bytes);
+      const stored = yield* blobs.head(blobKey(contentHash));
+      const columns: FileColumns = {
+        contentHash,
+        byteSize: upload.bytes.byteLength,
+        mediaType: upload.mediaType,
+        filename: upload.filename,
+        bytesPending: Option.isNone(stored),
+      };
+      return columns;
+    });
+
+  /**
+   * `bytesPending: false`, appended in its own transaction over exactly the
+   * pending version: if another write has landed since, it names other
+   * bytes, so the confirmation fails `StaleVersion` and confirms nothing.
+   */
+  const confirm = (id: string, pending: bigint) =>
+    transact(leaf.update({ id, patch: { bytesPending: false }, expectedVersion: pending }));
+
+  /**
+   * After the commit: put the bytes and confirm them. A failure of either
+   * leaves the node pending, never failing the write that committed.
+   */
+  const afterCommit = (written: ChainWrite, columns: FileColumns, upload: Upload) =>
+    Effect.gen(function* () {
+      if (!columns.bytesPending) {
+        return { ...written, contentHash: columns.contentHash, bytesPending: false };
+      }
+      const confirmed = yield* Effect.exit(
+        Effect.andThen(
+          blobs.put(blobKey(columns.contentHash), upload.bytes, {
+            byteSize: columns.byteSize,
+            mediaType: columns.mediaType,
+          }),
+          confirm(written.id, written.version),
+        ),
+      );
+      if (Exit.isFailure(confirmed)) {
+        yield* Effect.logWarning(`${leaf.type} ${written.id}: bytes left pending`, confirmed.cause);
+        return { ...written, contentHash: columns.contentHash, bytesPending: true };
+      }
+      return { ...confirmed.value, contentHash: columns.contentHash, bytesPending: false };
+    });
+
+  const create = Effect.fn(`${leaf.type}.files.create`)(function* (input: {
+    readonly id: Option.Option<string>;
+    readonly state: ChainState;
+    readonly upload: Upload;
+  }) {
+    const columns = yield* columnsOf(input.upload);
+    const written = yield* transact(
+      leaf.create({ id: input.id, state: { ...input.state, ...columns } }),
+    );
+    return yield* afterCommit(written, columns, input.upload);
+  });
+
+  const replace = Effect.fn(`${leaf.type}.files.replace`)(function* (
+    input: { readonly id: string; readonly upload: Upload } & Precondition,
+  ) {
+    const columns = yield* columnsOf(input.upload);
+    const written = yield* transact(
+      leaf.update({ id: input.id, patch: { ...columns }, expectedVersion: input.expectedVersion }),
+    );
+    return yield* afterCommit(written, columns, input.upload);
+  });
+
+  const confirmBytes = Effect.fn(`${leaf.type}.files.confirmBytes`)(function* (input: {
+    readonly id: string;
+    readonly version: bigint;
+    readonly contentHash: ContentHash;
+  }) {
+    if (Option.isNone(yield* blobs.head(blobKey(input.contentHash)))) return true;
+    yield* confirm(input.id, input.version);
+    return false;
+  });
+
+  return { create, replace, confirmBytes };
+};
+
+// ── The usage index ───────────────────────────────────────────────────
+
+/**
+ * The ends of a file-usage edge family: `user` (the content node that uses
+ * the file) and `file` (the file node), each declared with its own leaf's
+ * access and view, for `./edges`' `defineEdgeOps`. The family's edge table
+ * keys `(user_id, file_id)` uniquely, so a re-asserted use is a no-op under
+ * `onConflict: "ignore"`. A "used by" list is then an edge list at the file
+ * end, and `EDGE-001` hides every use whose content the viewer can't read.
+ *
+ * @since 0.1.0
+ */
+export const fileUsageEnds = <E, R>(ends: {
+  readonly user: Omit<EdgeEnd<E, R>, "column">;
+  readonly file: Omit<EdgeEnd<E, R>, "column">;
+}): EdgeEnds<E, R> => ({
+  user: { ...ends.user, column: "userId" },
+  file: { ...ends.file, column: "fileId" },
+});