api.ts · Source

api.tsapps/web/src/lib/files/api.tsraw ← files15,061 B← Back to the app
1/**
2 * TASK-0103 — the file API client (web).
3 *
4 * The single source of truth for talking to the real TASK-0101/0103 file
5 * endpoints. It replaces the stale `fileApi`/`uploadFile` in `@/lib/api`
6 * (which targeted the pre-Phase-9 draft endpoints `POST /files/upload`,
7 * `POST /files/:id/complete`, `GET /files/:id/url` and a `mime`/`url` shape
8 * the live API never emitted — every one of those 404/405s against the
9 * current backend).
10 *
11 * Security contract (spec §Security): the ONLY content path is a signed URL
12 * minted by the API. This client never assembles a bucket URL from a raw key
13 * (the raw `key` is not even part of `FileRecord`), and the file KIND is
14 * always derived from the server-verified `mimeType` (post-scan), never the
15 * extension.
16 *
17 * Workspace scoping: `GET /files` and `POST /files/uploads` resolve the
18 * workspace from `req.auth.workspaceId` — the `x-factory-workspace` header
19 * when present, else `claims.workspaces[0]`. We pass the header explicitly
20 * whenever we know the active workspace (multi-workspace users), so a call is
21 * never silently routed to the user's first workspace.
22 */
23 
24import { apiFetch, mutatingApiFetch, buildQuery } from "@/lib/api";
25 
26/* ------------------------------------------------------------ types */
27 
28/** The server-side file status machine (TASK-0102). */
29export type FileStatus =
30  | "UPLOADING"
31  | "SCANNING"
32  | "READY"
33  | "VIRUS_DETECTED"
34  | "FAILED";
35 
36/** A render/display kind, derived from the verified `mimeType`. */
37export type FileKind = "image" | "video" | "audio" | "pdf" | "doc" | "other";
38 
39/** `FileRecord` — the wire shape (docs/api/files.md §File object). */
40export interface FileRecord {
41  id: string;
42  workspaceId: string;
43  blockId: string | null;
44  pageId: string | null;
45  name: string;
46  size: number;
47  mimeType: string;
48  status: FileStatus;
49  metadata: Record<string, unknown>;
50  thumbnailKey: string | null;
51  /** Worker-minted 15-min signed GET of the 480 artifact (may be expired). */
52  thumbnailUrl: string | null;
53  scanReport: Record<string, unknown> | null;
54  uploadedBy: string;
55  version: number;
56  createdAt: string;
57  updatedAt: string;
58}
59 
60/** A list row: `FileRecord` + batch-resolved display fields. */
61export interface FileListItem extends FileRecord {
62  uploadedByName: string | null;
63  pageName: string | null;
64  versionCount: number;
65}
66 
67/** `GET /files/:id` — metadata + FRESH signed URLs + version history. */
68export interface FileDetail extends FileRecord {
69  /**
70   * Fresh signed GET, `attachment` disposition (900 s). OMITTED (absent) for
71   * a `VIRUS_DETECTED` file: the detail endpoint still returns the record
72   * (status/scanReport, so the block renders the "Blocked by virus scan"
73   * card) but a quarantined file is never signed (docs/api/files.md §8.5;
74   * the byte-serving endpoints 403, §8.6).
75   */
76  downloadUrl?: string;
77  /** Fresh signed GET, `inline` disposition (900 s) — absent when quarantined. */
78  previewUrl?: string;
79  /** ISO timestamp the signed URLs above expire at — absent when quarantined. */
80  expiresAt?: string;
81  versions: { id: string; version: number; size: number; createdAt: string }[];
82}
83 
84/** `POST /files/uploads` — a presigned upload session. */
85export interface UploadSession {
86  file: FileRecord;
87  /** Query-string signed PUT URL (bound to the key + declared content-type). */
88  uploadUrl: string;
89  method: "PUT";
90  /** The EXACT signed headers to send on the PUT (content-type is signed). */
91  headers: Record<string, string>;
92  expiresAt: string;
93}
94 
95export interface ListFilesParams {
96  scope?: "page" | "workspace";
97  pageId?: string;
98  kind?: FileKind;
99  status?: FileStatus;
100  search?: string;
101  sort?: "name" | "size" | "date" | "updated";
102  cursor?: string;
103  limit?: number;
104}
105 
106export interface ListFilesResult {
107  data: FileListItem[];
108  nextCursor: string | null;
109}
110 
111/* ----------------------------------------------------- TASK-0104 types */
112 
113/** A file-level explicit grant (`Permission` row, resourceType "file"). */
114export interface FileGrant {
115  id: string;
116  granteeType: "user" | "team" | "role";
117  /** userId | teamId | role name ("OWNER" | "ADMIN" | "MEMBER" | "GUEST"). */
118  granteeId: string;
119  /** NONE is an EXPLICIT DENY (overrides inheritance) — not "remove". */
120  level: "NONE" | "VIEW" | "COMMENT" | "EDIT" | "FULL_ACCESS";
121  /** Set by the server for display; a role grant resolves to the role name. */
122  granteeName: string | null;
123  granteeEmail?: string | null;
124}
125 
126/** One grant to (re)send with `setPermissions` (REPLACE — full desired set). */
127export interface FilePermissionGrantInput {
128  granteeType: "user" | "team" | "role";
129  granteeId: string;
130  level: "NONE" | "VIEW" | "COMMENT" | "EDIT" | "FULL_ACCESS";
131}
132 
133/** `GET /files/:id/versions` — one version row (ascending, `current` flags
134 *  the active version). The raw storage `key` is never exposed. */
135export interface FileVersion {
136  id: string;
137  version: number;
138  size: number;
139  current: boolean;
140  createdBy: string | null;
141  createdByName: string | null;
142  createdAt: string;
143}
144 
145/** `GET /files/trash` — a trashed file record (+ deletedAt for display). */
146export interface TrashedFile extends FileRecord {
147  deletedAt: string | null;
148  uploadedByName: string | null;
149}
150 
151/** `GET /workspaces/:id/usage`. NOTE: `storageBytes` arrives as a decimal
152 *  STRING (BigInt serialization) — `Number()` it before arithmetic. */
153export interface WorkspaceUsage {
154  workspaceId: string;
155  usage: {
156    pages: number;
157    databases: number;
158    records: number;
159    storageBytes: string;
160    storageBytesComputed: number;
161    apiKeys: number;
162    webhooks: number;
163  };
164  limits: {
165    maxFileSize: number;
166    maxPages: number | null;
167    maxDatabases: number | null;
168    maxRecords: number | null;
169    /** The effective plan quota (number) — always set since TASK-0104. */
170    maxStorageBytes: number;
171    maxApiKeys: number | null;
172    maxWebhooks: number | null;
173  };
174}
175 
176/* ------------------------------------------------------------ client */
177 
178/** Every method takes the active workspace id (sent as a header). */
179export interface WsOpt {
180  workspaceId?: string;
181}
182 
183function wsHeaders(workspaceId?: string): Record<string, string> {
184  return workspaceId ? { "x-factory-workspace": workspaceId } : {};
185}
186 
187export const filesApi = {
188  /** `GET /files` — server-side permission-filtered, cursor-paginated list. */
189  list(params: ListFilesParams & WsOpt = {}): Promise<ListFilesResult> {
190    const { workspaceId, scope, pageId, kind, status, search, sort, cursor, limit } = params;
191    return apiFetch<ListFilesResult>(
192      `/files${buildQuery({ scope, pageId, kind, status, search, sort, cursor, limit })}`,
193      { headers: wsHeaders(workspaceId) },
194    );
195  },
196 
197  /** `GET /files/:id` — metadata + fresh signed URLs + versions. */
198  get(fileId: string, opts: WsOpt = {}): Promise<FileDetail> {
199    return apiFetch<FileDetail>(`/files/${fileId}`, { headers: wsHeaders(opts.workspaceId) });
200  },
201 
202  /** `POST /files/uploads` — open a presigned session (plan limit enforced). */
203  openSession(input: {
204    name: string;
205    mimeType: string;
206    size: number;
207    pageId?: string | null;
208    blockId?: string | null;
209    /** TASK-0104: re-upload that replaces an existing file (same block). */
210    replaceFileId?: string | null;
211  } & WsOpt): Promise<UploadSession> {
212    const { workspaceId, ...body } = input;
213    return mutatingApiFetch<{ upload: UploadSession }>("/files/uploads", {
214      method: "POST",
215      body,
216      headers: wsHeaders(workspaceId),
217    }).then((r) => r.upload);
218  },
219 
220  /** `PUT /files/uploads/:id/complete` — verify bytes + SCANNING + enqueue. */
221  complete(fileId: string, opts: WsOpt = {}): Promise<{ id: string; status: FileStatus; verifiedBy: string }> {
222    return mutatingApiFetch(`/files/uploads/${fileId}/complete`, {
223      method: "PUT",
224      body: {},
225      headers: wsHeaders(opts.workspaceId),
226    });
227  },
228 
229  /** `POST /files/uploads/:id/cancel` — delete the partial object + row. */
230  cancel(fileId: string, opts: WsOpt = {}): Promise<{ deleted: boolean }> {
231    return mutatingApiFetch(`/files/uploads/${fileId}/cancel`, {
232      method: "POST",
233      body: {},
234      headers: wsHeaders(opts.workspaceId),
235    });
236  },
237 
238  /* ------------------------------------------------- TASK-0104 endpoints */
239  /*
240   * Wire-shape note (verified against the live API): the list-ish endpoints
241   * below return a BARE JSON array at the top level — there is no `{data}` /
242   * `{versions}` / `{grants}` envelope and no global wrapper. Only the
243   * object-returning endpoints (get/rename/rollback/restore) return a file
244   * record. `GET /files` (list) keeps its `{data, nextCursor}` envelope.
245   */
246 
247  /** `GET /files/trash` — trashed files (deletedAt set), bare array. */
248  listTrash(opts: WsOpt = {}): Promise<TrashedFile[]> {
249    return apiFetch<TrashedFile[]>("/files/trash", { headers: wsHeaders(opts.workspaceId) });
250  },
251 
252  /** `GET /files/:id/versions` — version history, bare array (ascending). */
253  listVersions(fileId: string, opts: WsOpt = {}): Promise<FileVersion[]> {
254    return apiFetch<FileVersion[]>(`/files/${fileId}/versions`, { headers: wsHeaders(opts.workspaceId) });
255  },
256 
257  /** `POST /files/:id/rollback` — make version n current (key swap). */
258  rollback(fileId: string, version: number, opts: WsOpt = {}): Promise<FileRecord> {
259    return mutatingApiFetch<FileRecord>(`/files/${fileId}/rollback`, {
260      method: "POST",
261      body: { version },
262      headers: wsHeaders(opts.workspaceId),
263    });
264  },
265 
266  /** `POST /files/:id/versions/prune` — delete non-current versions. */
267  pruneVersions(fileId: string, opts: WsOpt = {}): Promise<{ pruned: number }> {
268    return mutatingApiFetch<{ pruned: number }>(`/files/${fileId}/versions/prune`, {
269      method: "POST",
270      body: {},
271      headers: wsHeaders(opts.workspaceId),
272    });
273  },
274 
275  /** `DELETE /files/:id` — soft delete to the workspace trash. */
276  trash(fileId: string, opts: WsOpt = {}): Promise<{ trashed: true; deletedAt: string }> {
277    return mutatingApiFetch(`/files/${fileId}`, {
278      method: "DELETE",
279      headers: wsHeaders(opts.workspaceId),
280    });
281  },
282 
283  /** `DELETE /files/:id?purge=true` — delete objects + thumbs + rows. */
284  purge(fileId: string, opts: WsOpt = {}): Promise<{ purged: true }> {
285    return mutatingApiFetch(`/files/${fileId}${buildQuery({ purge: "true" })}`, {
286      method: "DELETE",
287      headers: wsHeaders(opts.workspaceId),
288    });
289  },
290 
291  /** `POST /files/:id/restore` — restore a trashed file. */
292  restore(fileId: string, opts: WsOpt = {}): Promise<FileRecord> {
293    return mutatingApiFetch<FileRecord>(`/files/${fileId}/restore`, {
294      method: "POST",
295      body: {},
296      headers: wsHeaders(opts.workspaceId),
297    });
298  },
299 
300  /** `GET /files/:id/permissions` — explicit file grants, bare array. */
301  listPermissions(fileId: string, opts: WsOpt = {}): Promise<FileGrant[]> {
302    return apiFetch<FileGrant[]>(`/files/${fileId}/permissions`, { headers: wsHeaders(opts.workspaceId) });
303  },
304 
305  /** `PUT /files/:id/permissions` — REPLACE the grant set; returns the new
306   *  grants (bare array). The API is the sole authority on effective levels. */
307  setPermissions(fileId: string, grants: FilePermissionGrantInput[], opts: WsOpt = {}): Promise<FileGrant[]> {
308    return mutatingApiFetch<FileGrant[]>(`/files/${fileId}/permissions`, {
309      method: "PUT",
310      body: { grants },
311      headers: wsHeaders(opts.workspaceId),
312    });
313  },
314 
315  /** `PATCH /files/:id` — rename only (the API rejects any other field). */
316  rename(fileId: string, name: string, opts: WsOpt = {}): Promise<FileRecord> {
317    return mutatingApiFetch<FileRecord>(`/files/${fileId}`, {
318      method: "PATCH",
319      body: { name },
320      headers: wsHeaders(opts.workspaceId),
321    });
322  },
323};
324 
325/** `GET /workspaces/:id/usage` — usage counters + effective limits.
326 *  Lives next to the file client (storage usage is the files concern) but
327 *  targets the workspace surface (no `x-factory-workspace` header needed). */
328export function getWorkspaceUsage(workspaceId: string): Promise<WorkspaceUsage> {
329  return apiFetch<WorkspaceUsage>(`/workspaces/${workspaceId}/usage`);
330}
331 
332/* ------------------------------------------------- kind + size helpers */
333 
334/**
335 * mime → render kind. Mirrors the server's `KIND_MIMES` (files.service.ts) so
336 * the block renderer and the list filter agree. Derived from the
337 * server-verified `mimeType` — never the file extension.
338 */
339const KIND_MIMES: Record<FileKind, string[]> = {
340  image: ["image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml"],
341  video: ["video/mp4", "video/webm", "video/quicktime"],
342  audio: ["audio/mpeg", "audio/wav", "audio/mp4", "audio/x-wav"],
343  pdf: ["application/pdf"],
344  doc: [
345    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
346    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
347    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
348    "text/markdown",
349    "text/plain",
350    "text/csv",
351  ],
352  other: [], // the fallback bucket
353};
354 
355export function kindForMime(mimeType: string | null | undefined): FileKind {
356  if (!mimeType) return "other";
357  const m = (mimeType.toLowerCase().split(";")[0] ?? "").trim();
358  if (!m) return "other";
359  for (const kind of ["image", "video", "audio", "pdf", "doc"] as FileKind[]) {
360    if (KIND_MIMES[kind].includes(m)) return kind;
361  }
362  return "other";
363}
364 
365/** Bytes → human string ("50 MB", "1.2 GB"). The download card + list use it. */
366export function humanSize(bytes: number): string {
367  if (!Number.isFinite(bytes) || bytes < 0) return "0 B";
368  if (bytes < 1024) return `${bytes} B`;
369  const units = ["KB", "MB", "GB", "TB"];
370  let value = bytes;
371  let i = -1;
372  do {
373    value /= 1024;
374    i += 1;
375  } while (value >= 1024 && i < units.length - 1);
376  return `${value >= 100 ? Math.round(value) : value.toFixed(1)} ${units[i]}`;
377}
378 
379/* ------------------------------------------- plan size-limit (pre-check) */
380 
381/** Per-plan defaults — mirrors the server's `PLAN_USAGE_LIMITS`. */
382const PLAN_MAX_FILE: Record<string, number> = {
383  free: 50 * 1024 * 1024,
384  paid: 500 * 1024 * 1024,
385};
386 
387/** The hard ceiling (server `LIMITS.MAX_FILE_SIZE` / @factory/shared). */
388export const MAX_FILE_SIZE_HARD = 500 * 1024 * 1024;
389 
390/**
391 * Effective per-file limit = min(plan default, admin override, hard ceiling).
392 * Mirrors the server's `effectiveMaxFileSize` (uploads.service.ts) so the
393 * client pre-check ("50 MB per file on your plan") rejects the exact set the
394 * server would 413 — no wasted session, and the error names the real limit.
395 */
396export function effectiveMaxFileSize(
397  billingPlan: string,
398  usageLimits: { maxFileSize?: number } | null | undefined,
399): number {
400  const plan = PLAN_MAX_FILE[billingPlan] ?? PLAN_MAX_FILE.free!;
401  const override = usageLimits?.maxFileSize;
402  return Math.min(
403    plan,
404    typeof override === "number" && override > 0 ? override : Infinity,
405    MAX_FILE_SIZE_HARD,
406  );
407}
408