@abyss-project/beam 0.0.0-stage → 1.0.0

package/src/types/enum/content-share.enum.ts

@@ -0,0 +1,37 @@
+export enum ShareableContentType {
+  DRAW = 'draw',
+  BOARD = 'board',
+  ATLAS = 'atlas',
+  RETROSPECTIVE = 'retrospective',
+  SHORT_LINK = 'short_link',
+  CLOUD_FILE = 'cloud_file',
+  CLOUD_FOLDER = 'cloud_folder',
+  CLOUD_GALLERY = 'cloud_gallery',
+  FORM = 'form',
+  SPOTLIGHT_PROJECT = 'spotlight_project',
+  EVENT = 'event',
+  REPORT = 'report',
+  PDF = 'pdf',
+  BEAM = 'beam',
+}
+
+export enum ShareTargetType {
+  USER = 'USER',
+  TEAM = 'TEAM',
+  ORGANIZATION = 'ORGANIZATION',
+  PROJECT = 'PROJECT',
+  LINK = 'LINK',
+}
+
+export enum SharePermission {
+  VIEW = 'VIEW',
+  EDIT = 'EDIT',
+  MANAGE = 'MANAGE',
+}
+
+export enum ContentShareScope {
+  ORGANIZATION = 'ORGANIZATION',
+  ORG_USER = 'ORG_USER',
+  ORG_TEAM = 'ORG_TEAM',
+  ORG_PROJECT = 'ORG_PROJECT',
+}

package/src/types/enum/index.ts

@@ -0,0 +1,3 @@
+export * from './api-error.enum';
+export * from './content-share.enum';
+export * from './beam.enum';

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './interface';
+export * from './enum';

package/src/types/interface/api/index.ts

@@ -0,0 +1,5 @@
+export * from './requests';
+export * from './responses';
+export * from './type-message/response';
+export * from './type-message/api-error';
+export * from './type-message/base-paginate';

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

@@ -0,0 +1,180 @@
+import { ContentShareScope } from '../../../enum';
+import { ShareTargetType, SharePermission } from '../../../enum/content-share.enum';
+import { BeamVisibility } from '../../../enum/beam.enum';
+import { QueryPaginate } from '../type-message/base-paginate';
+
+export type IGetBeamParams = {
+  beamId: string;
+};
+
+export type IGetBeamBySlugParams = {
+  slug: string;
+};
+
+export type IPaginateBeamQuery = {
+  title?: string;
+  isActive?: boolean;
+  scope?: ContentShareScope;
+  teamId?: string;
+  projectId?: string;
+  adminView?: boolean;
+  sharedWithMe?: boolean;
+} & QueryPaginate;
+
+export type IPaginateProjectBeamParams = {
+  projectId: string;
+};
+
+export type IPaginateOrganizationBeamParams = {
+  organizationId: string;
+};
+
+// Draft-creation metadata bundle (design §4 step 1). Files are attached
+// afterwards (B2) and the transfer is sealed at finalize (B5).
+export type ICreateBeamBody = {
+  title?: string;
+  message?: string;
+  visibility?: BeamVisibility;
+  expiresInDays?: number;
+  password?: string;
+  maxDownloads?: number;
+  recipients?: { email: string; locale?: string }[];
+};
+
+// Anonymous draft creation (POST /beam/public). Same metadata as the owned
+// create. `expiresInDays` is an optional 1..7 lifetime (integer) the anonymous
+// creator may pick; absent = the fixed 7-day anonymous TTL, and createDraft caps
+// it at 7 days.
+export type ICreateBeamPublicBody = {
+  title?: string;
+  message?: string;
+  visibility?: BeamVisibility;
+  password?: string;
+  expiresInDays?: number;
+  maxDownloads?: number;
+  recipients?: { email: string; locale?: string }[];
+};
+
+export interface IAddBeamFilesParams {
+  beamId: string;
+}
+
+export interface IAddBeamFilesBody {
+  files: { storageFileId: string }[];
+}
+
+export interface IImportCloudBeamFilesParams {
+  beamId: string;
+}
+
+export interface IImportCloudBeamFilesBody {
+  cloudFileIds: string[];
+}
+
+export interface IFinalizeBeamParams {
+  beamId: string;
+}
+
+export type IFinalizeBeamBody = Record<string, never>;
+
+export type ICreateForOrganizationBeamParams = {
+  organizationId: string;
+};
+
+export type IUpdateBeamParams = {
+  beamId: string;
+};
+
+export type IUpdateBeamBody = {
+  title?: string;
+  message?: string;
+  visibility?: BeamVisibility;
+  isActive?: boolean;
+  expiresAt?: Date | null;
+  maxDownloads?: number | null;
+};
+
+export type IDeleteBeamParams = {
+  beamId: string;
+};
+
+// Public serving (B3): unlock a password-protected transfer to obtain a
+// short-lived unlock token used by the byte-serving endpoints.
+export interface IUnlockBeamPublicParams {
+  slug: string;
+}
+
+export interface IUnlockBeamPublicBody {
+  password: string;
+}
+
+// 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 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
+// transfer. targetId is null for a LINK share, otherwise the user/team/org/project id.
+export interface ICreateBeamShareParams {
+  beamId: string;
+}
+
+export interface ICreateBeamShareBody {
+  targetType: ShareTargetType;
+  targetId?: string | null;
+  permission: SharePermission;
+}
+
+export interface IListBeamSharesParams {
+  beamId: string;
+}
+
+export interface IRevokeBeamShareParams {
+  beamId: string;
+  shareId: string;
+}
+
+// Recipients (B5): add extra recipients to a transfer (explicit add path,
+// distinct from the recipients recorded at draft time). Capped at
+// MAX_BEAM_RECIPIENTS on the API side.
+export interface IAddRecipientsBeamParams {
+  beamId: string;
+}
+
+export interface IAddRecipientsBeamBody {
+  recipients: { email: string; locale?: string | null }[];
+}
+
+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/index.ts

@@ -0,0 +1 @@
+export * from './beam.request';

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

@@ -0,0 +1,162 @@
+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,
+  BeamDownloadKind,
+  BeamFileScanStatus,
+} from '../../../enum/beam.enum';
+
+export interface IGetBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type IGetBeamResponse = IResponse<IGetBeamData>;
+
+export type IPaginateBeamResponse = IResponse<BasePaginate<IBeamTransfer>>;
+
+export interface ICreateBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type ICreateBeamResponse = IResponse<ICreateBeamData>;
+
+export interface IUpdateBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type IUpdateBeamResponse = IResponse<IUpdateBeamData>;
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface IDeleteBeamData {}
+export type IDeleteBeamResponse = IResponse<IDeleteBeamData>;
+
+export type IAddBeamFilesResponse = IResponse<{ files: IBeamFile[] }>;
+
+export interface IFinalizeBeamData {
+  slug: string;
+  viewUrl: string;
+  manageToken: string;
+  manageUrl: string;
+  expiresAt: string;
+}
+
+export type IFinalizeBeamResponse = IResponse<IFinalizeBeamData>;
+
+// Public serving (B3) — safe, purpose-built projection of a transfer for the
+// browser-facing view: no owner ids, no password/manage hashes; adds
+// hasPassword/isLocked/hasThumbnail so the front can render the locked state.
+// `scanStatus` is the per-file AV verdict (storage-neutral — an INFECTED file
+// is still listed and downloadable; the front renders the warning from this
+// field, see BeamFileScanStatus).
+export interface IBeamPublicFile {
+  id: string;
+  name: string;
+  sizeOctet: number;
+  mimeType: string | null;
+  isImage: boolean;
+  hasThumbnail: boolean;
+  width: number | null;
+  height: number | null;
+  scanStatus: BeamFileScanStatus;
+}
+
+export interface IBeamPublicView {
+  slug: string;
+  title: string | null;
+  message: string | null;
+  visibility: BeamVisibility;
+  hasPassword: boolean;
+  isLocked: boolean;
+  expiresAt: string | null;
+  fileCount: number;
+  totalSizeOctet: number;
+  downloadCount: number;
+  files: IBeamPublicFile[];
+}
+
+// `transfer` is null on the discovery-path denials the VIEW surfaces (404
+// not-found / hidden, 410 expired, 403 max-downloads): the metadata projection
+// is intentionally absent and `reason` carries the machine-readable denial code
+// so the front renders the correct state rather than inferring it from the bare
+// HTTP status (spec §17.1). On a 200 `transfer` is non-null (visible transfer,
+// possibly password-locked) and `reason` is omitted.
+export type IGetBeamPublicResponse = IResponse<{
+  transfer: IBeamPublicView | null;
+  reason?: BeamServeDenyReasonCode;
+}>;
+
+export interface IUnlockBeamPublicData {
+  unlockToken: string;
+  expiresIn: number;
+}
+
+export type IUnlockBeamPublicResponse = IResponse<IUnlockBeamPublicData>;
+
+// Management lifecycle (B4): renew/reactivate return the refreshed transfer.
+export interface IRenewBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type IRenewBeamResponse = IResponse<IRenewBeamData>;
+
+export interface IReactivateBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type IReactivateBeamResponse = IResponse<IReactivateBeamData>;
+
+// Sharing (B4): create returns the new grant, list returns every grant, revoke
+// returns an empty envelope (the delete cascade is server-side).
+export interface ICreateBeamShareData {
+  contentShare: IContentShare;
+}
+export type ICreateBeamShareResponse = IResponse<ICreateBeamShareData>;
+
+export interface IListBeamSharesData {
+  contentShares: IContentShare[];
+}
+export type IListBeamSharesResponse = IResponse<IListBeamSharesData>;
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface IRevokeBeamShareData {}
+export type IRevokeBeamShareResponse = IResponse<IRevokeBeamShareData>;
+
+// Recipients (B5): add returns how many were enqueued vs rate-limited by the
+// anti-abuse caps; list returns every recipient row of the transfer.
+export interface IAddRecipientsBeamData {
+  enqueued: number;
+  rateLimited: number;
+}
+export type IAddRecipientsBeamResponse = IResponse<IAddRecipientsBeamData>;
+
+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/index.ts

@@ -0,0 +1 @@
+export * from './beam.response';

package/src/types/interface/api/type-message/api-error.ts

@@ -0,0 +1,7 @@
+import { Code, ErrorType } from '../../../enum';
+
+export interface IApiError {
+  code: Code;
+  type: ErrorType;
+  message?: string;
+}

package/src/types/interface/api/type-message/base-paginate.ts

@@ -0,0 +1,11 @@
+export interface BasePaginate<T> {
+  maxPages: number;
+  currentPage: number;
+  data: T[];
+  totalItems: number;
+}
+
+export interface QueryPaginate {
+  page?: number;
+  limit?: number;
+}

package/src/types/interface/api/type-message/response.ts

@@ -0,0 +1,6 @@
+import { IApiError } from './api-error';
+
+export interface IResponse<T> {
+  data: T;
+  error?: IApiError | Error;
+}

package/src/types/interface/index.ts

@@ -0,0 +1,2 @@
+export * from './models';
+export * from './api';

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

@@ -0,0 +1,86 @@
+import { IOrganization } from './organization.dto';
+import { IUser } from './user.dto';
+import { IProject } from './project.dto';
+import { BeamVisibility, BeamDownloadKind } from '../../enum/beam.enum';
+
+export interface IBeamTransfer {
+  id: string;
+  slug: string;
+  // sha256 of the anonymous management token; the plaintext is returned once at
+  // finalize (B5) and never stored.
+  manageTokenHash: string | null;
+  userId: string | null;
+  organizationId: string | null;
+  projectId: string | null;
+  createdByUserId: string | null;
+  visibility: BeamVisibility;
+  passwordHash: string | null;
+  title: string | null;
+  message: string | null;
+  isActive: boolean;
+  expiresAt: Date | null;
+  finalizedAt: Date | null;
+  maxDownloads: number | null;
+  downloadCount: number;
+  lastDownloadedAt: Date | null;
+  totalSizeOctet: number;
+  fileCount: number;
+  createdAt?: Date;
+  updatedAt?: Date;
+
+  user?: IUser | null;
+  project?: IProject | null;
+  organization?: IOrganization | null;
+  files?: IBeamFile[];
+  recipients?: IBeamRecipient[];
+}
+
+export interface IBeamFile {
+  id: string;
+  transferId: string;
+  // abyss-storage applicationFileId (PRIVATE bucket); resolved at serve time (B4).
+  storageFileId: string;
+  thumbnailStorageFileId: string | null;
+  name: string;
+  mimeType: string | null;
+  sizeOctet: number;
+  isImage: boolean;
+  width: number | null;
+  height: number | null;
+  downloadCount: number;
+  position: number;
+  createdAt?: Date;
+
+  transfer?: IBeamTransfer;
+}
+
+export interface IBeamRecipient {
+  id: string;
+  transferId: string;
+  email: string;
+  locale: string | null;
+  sentAt: Date | null;
+  firstOpenedAt: Date | null;
+  createdAt?: Date;
+
+  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;
+}

package/src/types/interface/models/content-share.dto.ts

@@ -0,0 +1,20 @@
+import {
+  ShareableContentType,
+  SharePermission,
+  ShareTargetType,
+} from '../../enum/content-share.enum';
+
+export interface IContentShare {
+  id: string;
+  contentType: ShareableContentType;
+  contentId: string;
+  organizationId: string | null;
+  targetType: ShareTargetType;
+  targetId: string | null;
+  permission: SharePermission;
+  publicToken: string | null;
+  expiresAt: string | null;
+  createdByUserId: string;
+  createdAt: string;
+  updatedAt: string;
+}

package/src/types/interface/models/index.ts

@@ -0,0 +1,5 @@
+export * from './user.dto';
+export * from './organization.dto';
+export * from './project.dto';
+export * from './beam.dto';
+export * from './content-share.dto';

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

@@ -0,0 +1,21 @@
+import { IProject } from './project.dto';
+
+export interface IOrganization {
+  id?: string;
+  name: string;
+  slug: string;
+  // Mirror of abyss-main Organization.kind. Drives the family default-share
+  // permission (family → EDIT, else VIEW). Synced by organization.middleware.ts.
+  // Typed as a literal union that mirrors @abyss-project/main's OrganizationKind
+  // enum values 1:1 — this published SDK package intentionally does NOT depend on
+  // @abyss-project/main, so the enum is referenced by value (the api-side model
+  // and middleware narrow this to OrganizationKind, where main IS resolvable).
+  kind?: 'standard' | 'family';
+  // Last refresh of `kind` from abyss-main; drives the TTL (≤5min) sync gate.
+  kindSyncedAt?: string | null;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Associations
+  projects?: IProject[];
+}

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

@@ -0,0 +1,16 @@
+import { IOrganization } from './organization.dto';
+import { IUser } from './user.dto';
+
+export interface IProject {
+  id?: string;
+  name: string;
+  // Historical creator of the project, null once their account is deleted. NOT used for access control.
+  createdByUserId: string | null;
+  organizationId: string;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Associations
+  organization?: IOrganization;
+  user?: IUser;
+}

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

@@ -0,0 +1,19 @@
+import { IProject } from './project.dto';
+
+export interface IUser {
+  id?: string;
+  isAdmin: boolean;
+  // Personal API key mirror from abyss-main (ADR-0037). The lookup hash is the
+  // non-reversible sha256 fingerprint used for local validation; revokedAt marks
+  // a mirrored key that must no longer authenticate.
+  personalApiKeyLookupHash?: string | null;
+  personalApiKeyRevokedAt?: Date | null;
+  // Set when the account was deleted in abyss-main (USER_DELETED, #199): the row stays, marked,
+  // and a session token signed before the deletion no longer authenticates.
+  accountDeletedAt?: Date | null;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Associations
+  projects?: IProject[];
+}

package/src/types/tests/beam-management-types.spec.ts

@@ -0,0 +1,38 @@
+import type {
+  IRenewBeamParams,
+  IReactivateBeamParams,
+  ICreateBeamShareBody,
+  IRevokeBeamShareParams,
+} from '../interface/api/requests/beam.request';
+import type {
+  IRenewBeamResponse,
+  ICreateBeamShareResponse,
+  IListBeamSharesResponse,
+} from '../interface/api/responses/beam.response';
+import { ShareTargetType, SharePermission } from '../enum/content-share.enum';
+import { BEAM_MANAGE_TOKEN_HEADER } from '../../constants/beam.constants';
+
+describe('beam management SDK types', () => {
+  it('compiles renew/share request + response shapes', () => {
+    const renew: IRenewBeamParams = { beamId: 'b1' };
+    const reactivate: IReactivateBeamParams = { beamId: 'b1' };
+    const share: ICreateBeamShareBody = {
+      targetType: ShareTargetType.PROJECT,
+      targetId: 'p1',
+      permission: SharePermission.VIEW,
+    };
+    const revoke: IRevokeBeamShareParams = { beamId: 'b1', shareId: 's1' };
+    const renewResp: IRenewBeamResponse['data'] = { beamTransfer: {} as never };
+    const createResp: ICreateBeamShareResponse['data'] = { contentShare: {} as never };
+    const listResp: IListBeamSharesResponse['data'] = { contentShares: [] };
+
+    expect(renew.beamId).toBe('b1');
+    expect(reactivate.beamId).toBe('b1');
+    expect(share.targetType).toBe(ShareTargetType.PROJECT);
+    expect(revoke.shareId).toBe('s1');
+    expect(BEAM_MANAGE_TOKEN_HEADER).toBe('x-beam-manage-token');
+    expect(renewResp).toBeDefined();
+    expect(createResp).toBeDefined();
+    expect(listResp.contentShares).toHaveLength(0);
+  });
+});

package/src/types/tests/beam-share-enums.spec.ts

@@ -0,0 +1,11 @@
+import { ShareableContentType, ShareTargetType } from '../enum/content-share.enum';
+
+describe('tools content-share mirror — beam sharing members', () => {
+  it('exposes ShareableContentType.BEAM matching the abyss-main value', () => {
+    expect(ShareableContentType.BEAM).toBe('beam');
+  });
+
+  it('exposes ShareTargetType.PROJECT so beam RESTRICTED grants can target a project', () => {
+    expect(ShareTargetType.PROJECT).toBe('PROJECT');
+  });
+});