@abyss-project/tools 1.2.0 → 1.3.0

package/dist/types/interface/api/responses/beam.response.d.ts

@@ -2,7 +2,7 @@ import { BasePaginate } from '../type-message/base-paginate';
 import { IResponse } from '../type-message/response';
 import { IBeamTransfer, IBeamFile, IBeamRecipient } from '../../models/beam.dto';
 import { IContentShare } from '../../models/content-share.dto';
-import { BeamVisibility, BeamServeDenyReasonCode } from '../../../enum/beam.enum';
+import { BeamVisibility, BeamServeDenyReasonCode, BeamDownloadKind } from '../../../enum/beam.enum';
 export interface IGetBeamData {
     beamTransfer: IBeamTransfer;
 }
@@ -90,3 +90,25 @@ export interface IListRecipientsBeamData {
     recipients: IBeamRecipient[];
 }
 export type IListRecipientsBeamResponse = IResponse<IListRecipientsBeamData>;
+export interface IBeamStatsDayBucket {
+    day: string;
+    count: number;
+    zipCount: number;
+}
+export interface IBeamStatsRecentEvent {
+    downloadedAt: string;
+    kind: BeamDownloadKind;
+    fileId: string | null;
+    fileName: string | null;
+    userId: string | null;
+    ipHash: string;
+}
+export interface IGetBeamStatsData {
+    byDay: IBeamStatsDayBucket[];
+    recent: IBeamStatsRecentEvent[];
+    totals: {
+        downloadCount: number;
+        lastDownloadedAt: string | null;
+    };
+}
+export type IGetBeamStatsResponse = IResponse<IGetBeamStatsData>;

package/dist/types/interface/api/responses/extraction.response.d.ts

@@ -169,6 +169,12 @@ export interface IGetTemplateData {
 }
 export type IGetTemplateResponse = IResponse<IGetTemplateData>;
 export type IListTemplateVersionsResponse = IResponse<IExtractionTemplateVersion[]>;
+export interface IGetTemplateWitnessUrlData {
+    url: string;
+    filename: string | null;
+    size_bytes: number | null;
+}
+export type IGetTemplateWitnessUrlResponse = IResponse<IGetTemplateWitnessUrlData>;
 export interface IExtractionTemplateCollection {
     $schema: 'abyss-rcb-template-collection/v1';
     exported_at: string;

package/dist/types/interface/models/beam.dto.d.ts

@@ -1,7 +1,7 @@
 import { IOrganization } from './organization.dto';
 import { IUser } from './user.dto';
 import { IProject } from './project.dto';
-import { BeamVisibility } from '../../enum/beam.enum';
+import { BeamVisibility, BeamDownloadKind } from '../../enum/beam.enum';
 export interface IBeamTransfer {
     id: string;
     slug: string;
@@ -56,3 +56,15 @@ export interface IBeamRecipient {
     createdAt?: Date;
     transfer?: IBeamTransfer;
 }
+export interface IBeamDownloadEvent {
+    id: string;
+    transferId: string;
+    fileId: string | null;
+    kind: BeamDownloadKind;
+    ipHash: string;
+    userId: string | null;
+    downloadedAt: Date;
+    createdAt?: Date;
+    transfer?: IBeamTransfer;
+    file?: IBeamFile | null;
+}

package/dist/types/interface/models/extraction.dto.d.ts

@@ -101,10 +101,14 @@ export interface IExtraction {
 }
 export interface IExtractionTemplate {
     id: string;
-    userId: string;
+    userId: string | null;
+    organizationId: string | null;
+    projectId: string | null;
+    createdByUserId: string | null;
     name: string;
     description: string | null;
     isActive: boolean;
+    lastUsedAt: string | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -141,6 +145,9 @@ export interface IExtractionTemplateVersion {
     version: number;
     templateJson: Record<string, unknown>;
     comment: string | null;
+    witnessFileId: string | null;
+    witnessSizeBytes: number | null;
+    witnessFilename: string | null;
     createdAt: string;
 }
 export interface IExtractionFeedback {

package/dist/types/interface/models/extraction.dto.js.map

@@ -1 +1 @@
-{"version":3,"file":"extraction.dto.js","sourceRoot":"","sources":["../../../../src/types/interface/models/extraction.dto.ts"],"names":[],"mappings":";;;AAKA,yFAAoF;AA+E3E,sGA/EA,+CAAqB,OA+EA;AA9E9B,iHAAsG;AAQ7F,4GARA,iEAA2B,OAQA;AAwOpC,IAAY,sBAYX;AAZD,WAAY,sBAAsB;IAChC,qEAA2C,CAAA;IAC3C,+DAAqC,CAAA;IACrC,+EAAqD,CAAA;IACrD,uEAA6C,CAAA;IAC7C,6DAAmC,CAAA;IACnC,2DAAiC,CAAA;IACjC,6DAAmC,CAAA;IACnC,uEAA6C,CAAA;IAC7C,uDAA6B,CAAA;IAC7B,mEAAyC,CAAA;IACzC,6DAAmC,CAAA;AACrC,CAAC,EAZW,sBAAsB,sCAAtB,sBAAsB,QAYjC;AAEY,QAAA,yBAAyB,GACpC,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAuCxC,IAAY,2BAGX;AAHD,WAAY,2BAA2B;IACrC,4CAAa,CAAA;IACb,0CAAW,CAAA;AACb,CAAC,EAHW,2BAA2B,2CAA3B,2BAA2B,QAGtC"}
+{"version":3,"file":"extraction.dto.js","sourceRoot":"","sources":["../../../../src/types/interface/models/extraction.dto.ts"],"names":[],"mappings":";;;AAKA,yFAAoF;AA2E3E,sGA3EA,+CAAqB,OA2EA;AA1E9B,iHAAsG;AAI7F,4GAJA,iEAA2B,OAIA;AA8PpC,IAAY,sBAYX;AAZD,WAAY,sBAAsB;IAChC,qEAA2C,CAAA;IAC3C,+DAAqC,CAAA;IACrC,+EAAqD,CAAA;IACrD,uEAA6C,CAAA;IAC7C,6DAAmC,CAAA;IACnC,2DAAiC,CAAA;IACjC,6DAAmC,CAAA;IACnC,uEAA6C,CAAA;IAC7C,uDAA6B,CAAA;IAC7B,mEAAyC,CAAA;IACzC,6DAAmC,CAAA;AACrC,CAAC,EAZW,sBAAsB,sCAAtB,sBAAsB,QAYjC;AAEY,QAAA,yBAAyB,GACpC,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAuCxC,IAAY,2BAGX;AAHD,WAAY,2BAA2B;IACrC,4CAAa,CAAA;IACb,0CAAW,CAAA;AACb,CAAC,EAHW,2BAA2B,2CAA3B,2BAA2B,QAGtC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abyss-project/tools",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Core package to interact with Abyss-Project Tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/api/beam.api.ts

@@ -42,6 +42,9 @@ import type {
   IAddRecipientsBeamBody,
   IAddRecipientsBeamResponse,
   IListRecipientsBeamResponse,
+  IGetBeamStatsParams,
+  IGetBeamStatsQuery,
+  IGetBeamStatsResponse,
 } from '../types';
 import { BEAM_MANAGE_TOKEN_HEADER } from '../constants/beam.constants';
 
@@ -51,6 +54,10 @@ import { BEAM_MANAGE_TOKEN_HEADER } from '../constants/beam.constants';
 const manageTokenHeader = (manageToken?: string): { headers?: Record<string, string> } =>
   manageToken ? { headers: { [BEAM_MANAGE_TOKEN_HEADER]: manageToken } } : {};
 
+// renew/reactivate POST body: only carry `days` when the caller requested a
+// specific extension window (the API clamps it to the tier cap; default 7).
+const renewalBody = (days?: number): { days?: number } => (days !== undefined ? { days } : {});
+
 export const beamApi = {
   get: async (params: IGetBeamParams): Promise<IGetBeamResponse> => {
     const response = await AbyssToolsCore.axios.get<IGetBeamResponse>(`/beam/${params.beamId}`);
@@ -138,13 +145,31 @@ export const beamApi = {
 
   renew: async (params: IRenewBeamParams): Promise<IRenewBeamResponse> => {
     return (
-      await AbyssToolsCore.axios.post<IRenewBeamResponse>(`/beam/${params.beamId}/renew`)
+      await AbyssToolsCore.axios.post<IRenewBeamResponse>(
+        `/beam/${params.beamId}/renew`,
+        renewalBody(params.days),
+      )
     ).data;
   },
 
   reactivate: async (params: IReactivateBeamParams): Promise<IReactivateBeamResponse> => {
     return (
-      await AbyssToolsCore.axios.post<IReactivateBeamResponse>(`/beam/${params.beamId}/reactivate`)
+      await AbyssToolsCore.axios.post<IReactivateBeamResponse>(
+        `/beam/${params.beamId}/reactivate`,
+        renewalBody(params.days),
+      )
+    ).data;
+  },
+
+  // Owner download stats (MANAGE-gated): per-day series + recent events + totals.
+  stats: async (
+    params: IGetBeamStatsParams,
+    query?: IGetBeamStatsQuery,
+  ): Promise<IGetBeamStatsResponse> => {
+    return (
+      await AbyssToolsCore.axios.get<IGetBeamStatsResponse>(`/beam/${params.beamId}/stats`, {
+        params: query,
+      })
     ).data;
   },
 
@@ -258,7 +283,7 @@ export const beamApi = {
       return (
         await AbyssToolsCore.axios.post<IRenewBeamResponse>(
           `/beam/${params.beamId}/renew`,
-          undefined,
+          renewalBody(params.days),
           manageTokenHeader(params.manageToken),
         )
       ).data;
@@ -269,7 +294,7 @@ export const beamApi = {
       return (
         await AbyssToolsCore.axios.post<IReactivateBeamResponse>(
           `/beam/${params.beamId}/reactivate`,
-          undefined,
+          renewalBody(params.days),
           manageTokenHeader(params.manageToken),
         )
       ).data;

package/src/api/extraction.api.ts

@@ -42,6 +42,7 @@ import {
   IListTemplatesResponse,
   IGetTemplateResponse,
   IListTemplateVersionsResponse,
+  IGetTemplateWitnessUrlResponse,
   IExtractionTemplateCollection,
   IImportTemplateCollectionResponse,
   IGetJobResponse,
@@ -62,6 +63,7 @@ import {
   ICreateTemplateBody,
   IUpdateTemplateBody,
   IPatchTemplateMetaBody,
+  IListTemplatesQuery,
   ISubmitFeedbackExtractionBody,
   IPatchFeedbackBody,
   IListFeedbackQuery,
@@ -478,7 +480,7 @@ export const toggleExtractionTraining = async (
 // ─── TEMPLATES ───────────────────────────────
 
 export const listTemplates = async (
-  query: { kind?: 'spatial' | 'dsl' } & IExtractionTemplateScopeQuery = {},
+  query: IListTemplatesQuery & IExtractionTemplateScopeQuery = {},
   apiKey?: string,
 ): Promise<IListTemplatesResponse> => {
   return (
@@ -566,19 +568,58 @@ export const listTemplateVersions = async (
   ).data;
 };
 
+/**
+ * Presigned download URL for a template version's witness PDF.
+ * 404 when the version has no witness.
+ * GET /extract/templates/:id/versions/:version/witness-url
+ */
+export const getTemplateWitnessUrl = async (
+  templateId: string,
+  version: number,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IGetTemplateWitnessUrlResponse> => {
+  return (
+    await AbyssToolsCore.axios.get<IGetTemplateWitnessUrlResponse>(
+      `extract/templates/${templateId}/versions/${version}/witness-url`,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+/**
+ * Delete a template version's witness PDF (frees the billed storage).
+ * 404 when the version has no witness. Allowed on archived templates.
+ * DELETE /extract/templates/:id/versions/:version/witness
+ */
+export const deleteTemplateWitness = async (
+  templateId: string,
+  version: number,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<void> => {
+  await AbyssToolsCore.axios.delete(`extract/templates/${templateId}/versions/${version}/witness`, {
+    params: serializeParams(scope),
+    headers: authHeader(apiKey),
+  });
+};
+
 export const exportTemplateCollection = async (
   ids: string[] | null,
   scope: IExtractionTemplateScopeQuery = {},
   apiKey?: string,
 ): Promise<IExtractionTemplateCollection> => {
-  const res = await AbyssToolsCore.axios.get<IExtractionTemplateCollection>(`extract/templates/export`, {
-    params: {
-      ...(ids && ids.length ? { ids: ids.join(',') } : {}),
-      ...serializeParams(scope),
+  const res = await AbyssToolsCore.axios.get<IExtractionTemplateCollection>(
+    `extract/templates/export`,
+    {
+      params: {
+        ...(ids && ids.length ? { ids: ids.join(',') } : {}),
+        ...serializeParams(scope),
+      },
+      headers: authHeader(apiKey),
+      responseType: 'json',
     },
-    headers: authHeader(apiKey),
-    responseType: 'json',
-  });
+  );
   return res.data;
 };
 
@@ -792,10 +833,10 @@ export const getExtractionWebhook = async (
   apiKey?: string,
 ): Promise<IGetExtractionWebhookResponse> =>
   (
-    await AbyssToolsCore.axios.get<IGetExtractionWebhookResponse>(
-      `extract/webhook/${webhookId}`,
-      { params: serializeParams(scope), headers: authHeader(apiKey) },
-    )
+    await AbyssToolsCore.axios.get<IGetExtractionWebhookResponse>(`extract/webhook/${webhookId}`, {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    })
   ).data;
 
 export const createExtractionWebhook = async (
@@ -804,11 +845,10 @@ export const createExtractionWebhook = async (
   apiKey?: string,
 ): Promise<ICreateExtractionWebhookResponse> =>
   (
-    await AbyssToolsCore.axios.post<ICreateExtractionWebhookResponse>(
-      `extract/webhook`,
-      body,
-      { params: serializeParams(scope), headers: authHeader(apiKey) },
-    )
+    await AbyssToolsCore.axios.post<ICreateExtractionWebhookResponse>(`extract/webhook`, body, {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    })
   ).data;
 
 export const updateExtractionWebhook = async (

package/src/api/tests/beam.api.spec.ts

@@ -39,4 +39,68 @@ describe('beamApi', () => {
     expect(get).toHaveBeenCalledWith('/b/abcdefghij');
     get.mockRestore();
   });
+
+  it('renew posts an empty body by default and { days } when a window is requested', async () => {
+    const post = jest
+      .spyOn(AbyssToolsCore.axios, 'post')
+      .mockResolvedValue({ data: { data: { beamTransfer: { id: 't1' } } } });
+
+    await AbyssToolsCore.sdk.beam.renew({ beamId: 't1' });
+    expect(post).toHaveBeenCalledWith('/beam/t1/renew', {});
+
+    await AbyssToolsCore.sdk.beam.renew({ beamId: 't1', days: 30 });
+    expect(post).toHaveBeenCalledWith('/beam/t1/renew', { days: 30 });
+    post.mockRestore();
+  });
+
+  it('reactivate posts an empty body by default and { days } when a window is requested', async () => {
+    const post = jest
+      .spyOn(AbyssToolsCore.axios, 'post')
+      .mockResolvedValue({ data: { data: { beamTransfer: { id: 't1' } } } });
+
+    await AbyssToolsCore.sdk.beam.reactivate({ beamId: 't1' });
+    expect(post).toHaveBeenCalledWith('/beam/t1/reactivate', {});
+
+    await AbyssToolsCore.sdk.beam.reactivate({ beamId: 't1', days: 14 });
+    expect(post).toHaveBeenCalledWith('/beam/t1/reactivate', { days: 14 });
+    post.mockRestore();
+  });
+
+  it('public.renew carries the manage token header AND the optional days body', async () => {
+    const post = jest
+      .spyOn(AbyssToolsCore.axios, 'post')
+      .mockResolvedValue({ data: { data: { beamTransfer: { id: 't1' } } } });
+
+    await AbyssToolsCore.sdk.beam.public.renew({ beamId: 't1', manageToken: 'tok', days: 7 });
+
+    expect(post).toHaveBeenCalledWith(
+      '/beam/t1/renew',
+      { days: 7 },
+      { headers: { 'x-beam-manage-token': 'tok' } },
+    );
+    post.mockRestore();
+  });
+
+  it('stats reads /beam/:beamId/stats with the window/pagination query', async () => {
+    const get = jest.spyOn(AbyssToolsCore.axios, 'get').mockResolvedValue({
+      data: {
+        data: {
+          byDay: [{ day: '2026-07-09', count: 2, zipCount: 1 }],
+          recent: [],
+          totals: { downloadCount: 2, lastDownloadedAt: null },
+        },
+      },
+    });
+
+    const res = await AbyssToolsCore.sdk.beam.stats(
+      { beamId: 't1' },
+      { days: 7, limit: 10, offset: 0 },
+    );
+
+    expect(get).toHaveBeenCalledWith('/beam/t1/stats', {
+      params: { days: 7, limit: 10, offset: 0 },
+    });
+    expect(res.data.byDay[0].zipCount).toBe(1);
+    get.mockRestore();
+  });
 });

package/src/index.ts

@@ -286,6 +286,7 @@ type AbyssToolsCoreSDK = {
     delete: typeof beamApiModule.beamApi.delete;
     renew: typeof beamApiModule.beamApi.renew;
     reactivate: typeof beamApiModule.beamApi.reactivate;
+    stats: typeof beamApiModule.beamApi.stats;
     share: {
       create: typeof beamApiModule.beamApi.share.create;
       list: typeof beamApiModule.beamApi.share.list;
@@ -362,8 +363,13 @@ type AbyssToolsCoreSDK = {
       create: typeof extractionApi.createTemplate;
       update: typeof extractionApi.updateTemplate;
       patchMeta: typeof extractionApi.patchTemplateMeta;
+      /** DESTRUCTIVE: template + versions + witness PDFs. Archive via patchMeta instead. */
       delete: typeof extractionApi.deleteTemplate;
       listVersions: typeof extractionApi.listTemplateVersions;
+      /** Presigned download URL for a version's witness PDF (404 when none). */
+      getWitnessUrl: typeof extractionApi.getTemplateWitnessUrl;
+      /** Delete a version's witness PDF and free the billed storage. */
+      deleteWitness: typeof extractionApi.deleteTemplateWitness;
       exportCollection: typeof extractionApi.exportTemplateCollection;
       importCollection: typeof extractionApi.importTemplateCollection;
     };
@@ -671,6 +677,7 @@ export class AbyssToolsCore {
         delete: beamApiModule.beamApi.delete,
         renew: beamApiModule.beamApi.renew,
         reactivate: beamApiModule.beamApi.reactivate,
+        stats: beamApiModule.beamApi.stats,
         share: {
           create: beamApiModule.beamApi.share.create,
           list: beamApiModule.beamApi.share.list,
@@ -748,6 +755,8 @@ export class AbyssToolsCore {
           patchMeta: extractionApi.patchTemplateMeta,
           delete: extractionApi.deleteTemplate,
           listVersions: extractionApi.listTemplateVersions,
+          getWitnessUrl: extractionApi.getTemplateWitnessUrl,
+          deleteWitness: extractionApi.deleteTemplateWitness,
           exportCollection: extractionApi.exportTemplateCollection,
           importCollection: extractionApi.importTemplateCollection,
         },

package/src/types/enum/beam.enum.ts

@@ -22,3 +22,11 @@ export enum BeamServeDenyReasonCode {
   SCAN_PENDING = 'scan_pending',
   SCAN_INFECTED = 'scan_infected',
 }
+
+// What a beam_download_events row counted: a single-file download (/b/:slug/
+// file/:fileId) or the whole-transfer zip (/b/:slug/zip). Inline embeds (/raw)
+// and thumbnails (/thumb) are deliberately NOT download events (spec §17.6).
+export enum BeamDownloadKind {
+  FILE = 'file',
+  ZIP = 'zip',
+}

package/src/types/interface/api/requests/beam.request.ts

@@ -105,14 +105,26 @@ export interface IUnlockBeamPublicBody {
   password: string;
 }
 
-// Management lifecycle (B4): renew/reactivate take only the transfer id. Both
-// push expiresAt forward and reactivate the transfer server-side.
+// Management lifecycle (B4): renew/reactivate push expiresAt forward and
+// reactivate the transfer server-side. `days` optionally requests the extension
+// window; the API clamps it to the tier cap (7 days for anonymous transfers,
+// the plan's TOOLS_BEAM_EXPIRY_MAX_DAYS for owned ones; default 7).
 export interface IRenewBeamParams {
   beamId: string;
+  days?: number;
+}
+
+export interface IRenewBeamBody {
+  days?: number;
 }
 
 export interface IReactivateBeamParams {
   beamId: string;
+  days?: number;
+}
+
+export interface IReactivateBeamBody {
+  days?: number;
 }
 
 // Sharing (B4): a MANAGE holder grants a content_share (BEAM content type) on the
@@ -150,3 +162,16 @@ export interface IAddRecipientsBeamBody {
 export interface IListRecipientsBeamParams {
   beamId: string;
 }
+
+// Download stats (owner view): per-day series over the last `days` days plus the
+// paginated recent-event feed (limit/offset, newest first). Defaults are applied
+// server-side (days=30, limit=50, offset=0).
+export interface IGetBeamStatsParams {
+  beamId: string;
+}
+
+export interface IGetBeamStatsQuery {
+  days?: number;
+  limit?: number;
+  offset?: number;
+}

package/src/types/interface/api/requests/extraction.request.ts

@@ -150,16 +150,38 @@ export interface IAsyncExportExtractionBody {
 
 // ─── TEMPLATES ───────────────────────────────
 
+/**
+ * Query for GET /extract/templates.
+ * `archived`: 'false' (default) = active templates, 'true' = the archive,
+ * 'all' = everything.
+ */
+export interface IListTemplatesQuery {
+  kind?: 'spatial' | 'dsl';
+  archived?: 'true' | 'false' | 'all';
+}
+
 export interface ICreateTemplateBody {
   name: string;
   description?: string;
   template_json: Record<string, unknown>;
   comment?: string;
+  /**
+   * Optional witness (sample) PDF, base64-encoded (max 25 MB decoded).
+   * Stored per version, billed to the owner's storage pool.
+   */
+  witness_pdf_base64?: string;
+  witness_filename?: string;
 }
 
 export interface IUpdateTemplateBody {
   template_json: Record<string, unknown>;
   comment?: string;
+  /**
+   * Optional witness (sample) PDF, base64-encoded (max 25 MB decoded).
+   * Stored per version, billed to the owner's storage pool.
+   */
+  witness_pdf_base64?: string;
+  witness_filename?: string;
 }
 
 export interface IPatchTemplateMetaBody {

package/src/types/interface/api/responses/beam.response.ts

@@ -2,7 +2,7 @@ import { BasePaginate } from '../type-message/base-paginate';
 import { IResponse } from '../type-message/response';
 import { IBeamTransfer, IBeamFile, IBeamRecipient } from '../../models/beam.dto';
 import { IContentShare } from '../../models/content-share.dto';
-import { BeamVisibility, BeamServeDenyReasonCode } from '../../../enum/beam.enum';
+import { BeamVisibility, BeamServeDenyReasonCode, BeamDownloadKind } from '../../../enum/beam.enum';
 
 export interface IGetBeamData {
   beamTransfer: IBeamTransfer;
@@ -120,3 +120,32 @@ export interface IListRecipientsBeamData {
   recipients: IBeamRecipient[];
 }
 export type IListRecipientsBeamResponse = IResponse<IListRecipientsBeamData>;
+
+// Download stats (owner view, MANAGE-gated): a per-day series (SQL date_trunc,
+// UTC buckets; days with zero downloads are omitted), the paginated recent-event
+// feed (newest first) and the denormalized transfer totals. `fileName` is null
+// for a zip event and after the downloaded file was deleted (FK SET NULL).
+export interface IBeamStatsDayBucket {
+  day: string; // 'YYYY-MM-DD'
+  count: number;
+  zipCount: number;
+}
+
+export interface IBeamStatsRecentEvent {
+  downloadedAt: string;
+  kind: BeamDownloadKind;
+  fileId: string | null;
+  fileName: string | null;
+  userId: string | null;
+  ipHash: string;
+}
+
+export interface IGetBeamStatsData {
+  byDay: IBeamStatsDayBucket[];
+  recent: IBeamStatsRecentEvent[];
+  totals: {
+    downloadCount: number;
+    lastDownloadedAt: string | null;
+  };
+}
+export type IGetBeamStatsResponse = IResponse<IGetBeamStatsData>;

package/src/types/interface/api/responses/extraction.response.ts

@@ -3,7 +3,11 @@
 // ──────────────────────────────────────────────
 
 import { IResponse } from '../type-message/response';
-import type { IExtractionPlanPreset, IExtractModesData, IFieldValue } from '../../models/extraction-plan.dto';
+import type {
+  IExtractionPlanPreset,
+  IExtractModesData,
+  IFieldValue,
+} from '../../models/extraction-plan.dto';
 import {
   IExtractionBankVersion,
   IExtraction,
@@ -134,7 +138,11 @@ export interface IDiffExtractionsData {
   same: number;
   added: IExtractionTransaction[];
   removed: IExtractionTransaction[];
-  changed: Array<{ before: IExtractionTransaction; after: IExtractionTransaction; fields: string[] }>;
+  changed: Array<{
+    before: IExtractionTransaction;
+    after: IExtractionTransaction;
+    fields: string[];
+  }>;
   summary: { leftCount: number; rightCount: number; sumDeltaCents: number };
 }
 export type IDiffExtractionsResponse = IResponse<IDiffExtractionsData>;
@@ -180,6 +188,15 @@ export type IGetTemplateResponse = IResponse<IGetTemplateData>;
 
 export type IListTemplateVersionsResponse = IResponse<IExtractionTemplateVersion[]>;
 
+/** Presigned download reference for a version's witness PDF. */
+export interface IGetTemplateWitnessUrlData {
+  /** Presigned DOWNLOAD URL (time-limited). */
+  url: string;
+  filename: string | null;
+  size_bytes: number | null;
+}
+export type IGetTemplateWitnessUrlResponse = IResponse<IGetTemplateWitnessUrlData>;
+
 // Deferred wire-schema rename — must match server SCHEMA constant in
 // extraction-template-portability.service.ts; rename together in the server/main batch.
 export interface IExtractionTemplateCollection {

package/src/types/interface/models/beam.dto.ts

@@ -1,7 +1,7 @@
 import { IOrganization } from './organization.dto';
 import { IUser } from './user.dto';
 import { IProject } from './project.dto';
-import { BeamVisibility } from '../../enum/beam.enum';
+import { BeamVisibility, BeamDownloadKind } from '../../enum/beam.enum';
 
 export interface IBeamTransfer {
   id: string;
@@ -65,3 +65,22 @@ export interface IBeamRecipient {
 
   transfer?: IBeamTransfer;
 }
+
+// One download-history event (B-phase download history). Written on the counted
+// download paths only (/file + /zip); fileId is null for a zip and after the
+// downloaded file was deleted (FK SET NULL). ipHash is the sha256 of the client
+// IP — the raw IP is never stored. userId is the optionally-resolved bearer of
+// the public serve request (null for anonymous downloads).
+export interface IBeamDownloadEvent {
+  id: string;
+  transferId: string;
+  fileId: string | null;
+  kind: BeamDownloadKind;
+  ipHash: string;
+  userId: string | null;
+  downloadedAt: Date;
+  createdAt?: Date;
+
+  transfer?: IBeamTransfer;
+  file?: IBeamFile | null;
+}