@tribe-nest/forge 3.37.0 → 3.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.37.0",
+  "version": "3.38.0",
   "publishConfig": {
     "access": "public"
   },

package/src/ui/headless/work/index.ts

@@ -8,6 +8,9 @@ export {
   useWorkInvite,
   useAcceptWorkInvite,
   useWorkProjectInvoices,
+  useWorkSharedDocuments,
+  useWorkOpenSharedDocument,
+  useUploadWorkDocument,
   formatWorkMoney,
   formatWorkDate,
   type WorkProjectSummary,
@@ -21,5 +24,6 @@ export {
   type WorkInviteContext,
   type WorkInviteAcceptResult,
   type WorkProjectInvoice,
+  type WorkSharedDocument,
   type UseWorkTaskCommentsResult,
 } from "./useWorkPortal";

package/src/ui/headless/work/useWorkPortal.ts

@@ -1,4 +1,5 @@
 import { useMutation, useQuery, useQueryClient, type UseQueryResult } from "@tanstack/react-query";
+import axios from "axios";
 import { useForge } from "../../../provider/ForgeProvider";
 
 /**
@@ -89,6 +90,25 @@ export interface WorkTaskAttachment {
   size: number | null;
 }
 
+/**
+ * A case-file document the firm has shared with the client, or one the client
+ * put there themselves. A file document describes itself but never carries an
+ * address: the bytes come only through `useWorkOpenSharedDocument`.
+ */
+export interface WorkSharedDocument {
+  id: string;
+  title: string;
+  docType: "page" | "file";
+  updatedAt: string;
+  sharedAt: string;
+  file: {
+    mediaId: string;
+    filename: string | null;
+    size: number;
+    type: string;
+  } | null;
+}
+
 export interface WorkProjectInvoice {
   id: string;
   invoiceNumber: string;
@@ -110,7 +130,7 @@ export interface WorkInviteContext {
   firstName: string | null;
   /**
    * The invited address already has an account, so the invite grants portal
-   * access but cannot set a credential — render "sign in", not a password
+   * access but cannot set a credential: render "sign in", not a password
    * form (C10).
    */
   requiresExistingLogin?: boolean;
@@ -124,7 +144,7 @@ export interface WorkInviteAcceptResult {
    */
   requiresLogin?: boolean;
   token?: string;
-  /** Rotating refresh token for the portal session (backend §7) — persist it. */
+  /** Rotating refresh token for the portal session (backend §7). Persist it. */
   refreshToken?: string;
   projectId: string;
   account: { id: string; email: string; firstName: string | null; lastName: string | null };
@@ -142,12 +162,14 @@ const keys = {
     ["work-portal-task-attachments", profileId, projectId, taskId] as const,
   projectInvoices: (profileId: string | undefined, projectId: string) =>
     ["work-portal-project-invoices", profileId, projectId] as const,
+  sharedDocuments: (profileId: string | undefined, projectId: string) =>
+    ["work-portal-shared-documents", profileId, projectId] as const,
 };
 
 // ── Authed client's projects ─────────────────────────────────────────────────
 
 /** The authenticated client's (non-archived) client projects with a task/done
- * summary — GET /public/work/projects. The token is the identity. */
+ * summary: GET /public/work/projects. The token is the identity. */
 export function useWorkPortalProjects(): UseQueryResult<WorkProjectSummary[]> {
   const { client, profileId } = useForge();
   return useQuery<WorkProjectSummary[]>({
@@ -163,7 +185,7 @@ export function useWorkPortalProjects(): UseQueryResult<WorkProjectSummary[]> {
 // ── Authed client's single-project report ────────────────────────────────────
 
 /** The authenticated client's overview + billable-only time report for one of
- * their projects — GET /public/work/projects/:id/report. */
+ * their projects: GET /public/work/projects/:id/report. */
 export function useWorkProjectReport(projectId: string): UseQueryResult<WorkProjectReportData> {
   const { client, profileId } = useForge();
   return useQuery<WorkProjectReportData>({
@@ -180,7 +202,7 @@ export function useWorkProjectReport(projectId: string): UseQueryResult<WorkProj
 
 // ── Public tokenized report (no login) ───────────────────────────────────────
 
-/** Login-free tokenized share of a project's time report — GET
+/** Login-free tokenized share of a project's time report: GET
  * /public/work/time-report/:token. The signed token IS the authorization. */
 export function useWorkTokenReport(token: string): UseQueryResult<WorkProjectReportData> {
   const { client } = useForge();
@@ -208,7 +230,7 @@ export interface UseWorkTaskCommentsResult {
 
 /**
  * The authenticated client's comment thread for a single task on one of their
- * projects — GET/POST /public/work/projects/:projectId/tasks/:taskId/comments.
+ * projects: GET/POST /public/work/projects/:projectId/tasks/:taskId/comments.
  * Newest first. The bearer token IS the client identity (server-enforced).
  * Posting invalidates the thread so the new comment appears. Tier-1 primitive:
  * returns clean data + a bound mutation, renders nothing.
@@ -259,7 +281,7 @@ export function useWorkTaskComments(projectId: string, taskId: string): UseWorkT
 
 /**
  * Read-only attachments the team has added to a task on one of the client's
- * projects — GET /public/work/projects/:projectId/tasks/:taskId/attachments.
+ * projects: GET /public/work/projects/:projectId/tasks/:taskId/attachments.
  * Tier-1 primitive: returns clean data, renders nothing.
  */
 export function useWorkTaskAttachments(projectId: string, taskId: string): UseQueryResult<WorkTaskAttachment[]> {
@@ -279,7 +301,7 @@ export function useWorkTaskAttachments(projectId: string, taskId: string): UseQu
 // ── Authed client's invoices for a project ───────────────────────────────────
 
 /**
- * The client's (non-draft) invoices for one of their projects —
+ * The client's (non-draft) invoices for one of their projects:
  * GET /public/work/projects/:id/invoices. Each carries a `payable` flag the
  * portal turns into a Pay button (links to /i/invoice/:id). Tier-1 primitive.
  */
@@ -295,11 +317,104 @@ export function useWorkProjectInvoices(projectId: string): UseQueryResult<WorkPr
   });
 }
 
+// ── Authed client's case-file documents ──────────────────────────────────────
+
+/**
+ * The documents on one of the client's projects that they may see: what the
+ * firm shared with them, and what they uploaded themselves:
+ * GET /public/work/projects/:id/documents. Tier-1 primitive.
+ */
+export function useWorkSharedDocuments(projectId: string): UseQueryResult<WorkSharedDocument[]> {
+  const { client, profileId } = useForge();
+  return useQuery<WorkSharedDocument[]>({
+    queryKey: keys.sharedDocuments(profileId, projectId),
+    queryFn: async () => {
+      const res = await client.get(`/public/work/projects/${projectId}/documents`, { params: { profileId } });
+      return res.data as WorkSharedDocument[];
+    },
+    enabled: !!profileId && !!client && !!projectId,
+  });
+}
+
+/**
+ * A sixty-second, single-use GET at one shared file's bytes:
+ * GET /public/work/projects/:id/documents/:documentId/content. Meant to be
+ * followed once, by the click that asked for it; never cache or render the URL.
+ */
+export function useWorkOpenSharedDocument(projectId: string) {
+  const { client, profileId } = useForge();
+  return useMutation<{ url: string }, unknown, string>({
+    mutationFn: async (documentId: string) => {
+      const res = await client.get(`/public/work/projects/${projectId}/documents/${documentId}/content`, {
+        params: { profileId },
+      });
+      return res.data as { url: string };
+    },
+  });
+}
+
+const mediaTypeFor = (file: File): "image" | "video" | "audio" | "document" | "other" => {
+  const mime = file.type || "";
+  if (mime.startsWith("image/")) return "image";
+  if (mime.startsWith("video/")) return "video";
+  if (mime.startsWith("audio/")) return "audio";
+  if (mime.startsWith("text/") || mime.includes("pdf") || mime.includes("word") || mime.includes("document")) {
+    return "document";
+  }
+  return "other";
+};
+
+/**
+ * Put a file into the client's matter, in three steps that must stay in this
+ * order:
+ *
+ *   1. sign a PUT into the firm's PRIVATE bucket
+ *      (POST /public/work/projects/:id/documents/upload-url);
+ *   2. send the bytes straight to object storage, with the Content-Type the
+ *      server SIGNED (derived from the extension allowlist, not the browser);
+ *   3. register the document (POST /public/work/projects/:id/documents), which
+ *      writes the row, shares it back to the client and queues extraction.
+ *
+ * A failure at any step is a failure of the whole upload. On success the
+ * shared-documents list is refetched so the new file appears at once.
+ */
+export function useUploadWorkDocument(projectId: string) {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation<WorkSharedDocument, unknown, { file: File; title?: string }>({
+    mutationFn: async ({ file, title }) => {
+      const { data: signed } = await client.post<{
+        presignedUrl: string;
+        key: string;
+        requiredHeaders?: Record<string, string>;
+      }>(`/public/work/projects/${projectId}/documents/upload-url`, { fileName: file.name }, { params: { profileId } });
+      await axios.put(signed.presignedUrl, file, {
+        headers: signed.requiredHeaders ?? { "Content-Type": file.type || "application/octet-stream" },
+      });
+      const { data } = await client.post(
+        `/public/work/projects/${projectId}/documents`,
+        {
+          storageKey: signed.key,
+          fileName: file.name,
+          fileSize: file.size,
+          mediaType: mediaTypeFor(file),
+          ...(title ? { title } : {}),
+        },
+        { params: { profileId } },
+      );
+      return data as WorkSharedDocument;
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: keys.sharedDocuments(profileId, projectId) });
+    },
+  });
+}
+
 // ── Client invite accept (public, no auth) ───────────────────────────────────
 
 /**
  * Fetch the branded context for an invite link (GET /public/work/invite).
- * Public — no bearer token needed; the link's token IS the credential.
+ * Public: no bearer token needed; the link's token IS the credential.
  * `null`/errored when the token or project is missing/invalid/expired.
  */
 export function useWorkInvite(
@@ -321,7 +436,7 @@ export function useWorkInvite(
 /**
  * Accept an invite (POST /public/work/invite/accept): set a password and
  * receive a fresh portal session token. The caller persists the token +
- * navigates. Public — no bearer token needed.
+ * navigates. Public: no bearer token needed.
  */
 export function useAcceptWorkInvite() {
   const { client } = useForge();

package/src/ui/styled/work/WorkProjectDocuments.tsx

@@ -0,0 +1,224 @@
+import { useRef, useState } from "react";
+import { FileText, Paperclip, Upload } from "lucide-react";
+import { useThemeTokens } from "../../theme/ForgeThemeProvider";
+import {
+  formatWorkDate,
+  useUploadWorkDocument,
+  useWorkOpenSharedDocument,
+  useWorkSharedDocuments,
+  type WorkSharedDocument,
+} from "../../headless/work/useWorkPortal";
+
+export interface WorkProjectDocumentsProps {
+  /** The client project id. */
+  projectId: string;
+  /** Hide the upload control. The list still renders. Defaults to `true`. */
+  allowUpload?: boolean;
+}
+
+const humanSize = (size: number | null | undefined): string => {
+  if (!size || size <= 0) return "";
+  const units = ["B", "KB", "MB", "GB"];
+  let n = size;
+  let i = 0;
+  while (n >= 1024 && i < units.length - 1) {
+    n /= 1024;
+    i += 1;
+  }
+  return `${n.toFixed(n >= 10 || i === 0 ? 0 : 1)} ${units[i]}`;
+};
+
+const errorMessage = (error: unknown): string =>
+  (error as { response?: { data?: { message?: string } } })?.response?.data?.message ||
+  "The upload didn't go through. Please try again.";
+
+/**
+ * The documents on a client's project: what the firm shared with them, and
+ * what they sent in themselves, with an upload control for the latter.
+ *
+ * A file opens through a short-lived signed read fetched on the click, never
+ * from an address held in the page. Built on `useWorkSharedDocuments`,
+ * `useWorkOpenSharedDocument` and `useUploadWorkDocument`; theme tokens only.
+ *
+ * Unlike the invoices block this renders even when the list is empty, because
+ * the empty state is where the upload control lives.
+ */
+export function WorkProjectDocuments({ projectId, allowUpload = true }: WorkProjectDocumentsProps) {
+  const t = useThemeTokens();
+  const { data: documents, isLoading } = useWorkSharedDocuments(projectId);
+  const open = useWorkOpenSharedDocument(projectId);
+  const upload = useUploadWorkDocument(projectId);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [opening, setOpening] = useState<string | null>(null);
+
+  if (isLoading) return null;
+
+  const onFiles = async (files: FileList | null) => {
+    if (!files || files.length === 0) return;
+    setError(null);
+    // One at a time, in order: each is its own signed PUT and its own row, and
+    // a failure names the file that failed rather than the whole batch.
+    for (const file of Array.from(files)) {
+      try {
+        await upload.mutateAsync({ file });
+      } catch (err) {
+        setError(`${file.name}: ${errorMessage(err)}`);
+        return;
+      }
+    }
+  };
+
+  const openDocument = async (doc: WorkSharedDocument) => {
+    if (!doc.file) return;
+    setOpening(doc.id);
+    try {
+      const { url } = await open.mutateAsync(doc.id);
+      window.open(url, "_blank", "noopener");
+    } catch (err) {
+      setError(errorMessage(err));
+    } finally {
+      setOpening(null);
+    }
+  };
+
+  const list = documents ?? [];
+
+  return (
+    <div
+      data-testid="work-project-documents"
+      style={{
+        border: `1px solid ${t.border}`,
+        borderRadius: t.cornerRadius,
+        background: t.surface,
+        padding: 20,
+        color: t.text,
+        fontFamily: t.fontFamily,
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: 12,
+          flexWrap: "wrap",
+          marginBottom: 14,
+        }}
+      >
+        <h2 style={{ fontSize: 16, fontWeight: 800, margin: 0 }}>Documents</h2>
+        {allowUpload && (
+          <>
+            <input
+              ref={fileInputRef}
+              type="file"
+              multiple
+              hidden
+              data-testid="work-document-file-input"
+              onChange={(e) => {
+                void onFiles(e.target.files);
+                e.target.value = "";
+              }}
+            />
+            <button
+              type="button"
+              data-testid="work-document-upload"
+              onClick={() => fileInputRef.current?.click()}
+              disabled={upload.isPending}
+              style={{
+                display: "inline-flex",
+                alignItems: "center",
+                gap: 8,
+                padding: "8px 16px",
+                borderRadius: t.cornerRadius,
+                border: "none",
+                background: t.primary,
+                color: t.textPrimary,
+                fontWeight: 700,
+                fontSize: 13,
+                cursor: upload.isPending ? "wait" : "pointer",
+                opacity: upload.isPending ? 0.7 : 1,
+              }}
+            >
+              <Upload size={14} />
+              {upload.isPending ? "Uploading…" : "Upload a document"}
+            </button>
+          </>
+        )}
+      </div>
+
+      {error && (
+        <p
+          data-testid="work-document-error"
+          role="alert"
+          style={{ margin: "0 0 12px", fontSize: 13, color: "#ef4444" }}
+        >
+          {error}
+        </p>
+      )}
+
+      {list.length === 0 ? (
+        <p data-testid="work-project-documents-empty" style={{ margin: 0, fontSize: 13, color: t.muted }}>
+          {allowUpload
+            ? "Nothing here yet. Upload a document to add it to this project."
+            : "Nothing has been shared with you yet."}
+        </p>
+      ) : (
+        <ul style={{ listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 8 }}>
+          {list.map((doc) => (
+            <li
+              key={doc.id}
+              data-testid={`work-document-${doc.id}`}
+              style={{
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "space-between",
+                gap: 12,
+                flexWrap: "wrap",
+                padding: "10px 14px",
+                border: `1px solid ${t.border}`,
+                borderRadius: t.cornerRadius,
+              }}
+            >
+              <div style={{ display: "flex", alignItems: "center", gap: 10, minWidth: 0 }}>
+                {doc.file ? (
+                  <Paperclip size={14} style={{ color: t.muted, flexShrink: 0 }} />
+                ) : (
+                  <FileText size={14} style={{ color: t.muted, flexShrink: 0 }} />
+                )}
+                <div style={{ display: "flex", flexDirection: "column", gap: 2, minWidth: 0 }}>
+                  <span style={{ fontWeight: 700, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+                    {doc.title}
+                  </span>
+                  <span style={{ fontSize: 12, color: t.muted }}>
+                    {formatWorkDate(doc.sharedAt)}
+                    {doc.file?.size ? ` · ${humanSize(doc.file.size)}` : ""}
+                  </span>
+                </div>
+              </div>
+              {doc.file && (
+                <button
+                  type="button"
+                  data-testid={`work-document-open-${doc.id}`}
+                  onClick={() => void openDocument(doc)}
+                  disabled={opening === doc.id}
+                  style={{
+                    background: "transparent",
+                    border: "none",
+                    padding: 0,
+                    color: t.primary,
+                    fontSize: 13,
+                    textDecoration: "underline",
+                    cursor: opening === doc.id ? "wait" : "pointer",
+                  }}
+                >
+                  {opening === doc.id ? "Opening…" : "Open"}
+                </button>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/ui/styled/work/WorkProjectReport.tsx

@@ -3,6 +3,7 @@ import { Loading } from "../Loading";
 import { useWorkProjectReport } from "../../headless/work/useWorkPortal";
 import { WorkReportBody } from "./WorkReportBody";
 import { WorkProjectInvoices } from "./WorkProjectInvoices";
+import { WorkProjectDocuments } from "./WorkProjectDocuments";
 
 export interface WorkProjectReportProps {
   /** The client project id (from the route). */
@@ -17,7 +18,7 @@ export interface WorkProjectReportProps {
 }
 
 /**
- * The authenticated client's read-only project report — milestones, task list
+ * The authenticated client's read-only project report: milestones, task list
  * and the billable-only time report. Each task links to its detail/comments
  * page. Built on `useWorkProjectReport`; theme tokens only.
  */
@@ -55,11 +56,12 @@ export function WorkProjectReport({ projectId, taskHref, onOpenTask }: WorkProje
         ? undefined
         : (taskHref ?? ((taskId: string) => `/i/work/projects/${projectId}/tasks/${taskId}`));
 
-  // The invoices section is authed-only (not part of the login-free token
-  // share, which renders WorkReportBody directly).
+  // The documents and invoices sections are authed-only (not part of the
+  // login-free token share, which renders WorkReportBody directly).
   return (
     <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
       <WorkReportBody report={report} taskHref={resolvedTaskHref} onOpenTask={onOpenTask} />
+      <WorkProjectDocuments projectId={projectId} />
       <WorkProjectInvoices projectId={projectId} />
     </div>
   );

package/src/ui/styled/work/index.ts

@@ -8,3 +8,4 @@ export { WorkTaskAttachments, type WorkTaskAttachmentsProps } from "./WorkTaskAt
 export { WorkTaskDetail, type WorkTaskDetailProps } from "./WorkTaskDetail";
 export { WorkInviteAccept, type WorkInviteAcceptProps } from "./WorkInviteAccept";
 export { WorkProjectInvoices, type WorkProjectInvoicesProps } from "./WorkProjectInvoices";
+export { WorkProjectDocuments, type WorkProjectDocumentsProps } from "./WorkProjectDocuments";