@abyss-project/beam 0.0.0-stage → 1.0.0

package/src/api/beam.api.ts

@@ -0,0 +1,325 @@
+import { AbyssBeamCore } from '..';
+import type {
+  IGetBeamParams,
+  IGetBeamResponse,
+  IGetBeamBySlugParams,
+  IGetBeamPublicResponse,
+  IUnlockBeamPublicParams,
+  IUnlockBeamPublicBody,
+  IUnlockBeamPublicResponse,
+  IPaginateBeamQuery,
+  IPaginateBeamResponse,
+  IPaginateProjectBeamParams,
+  IPaginateOrganizationBeamParams,
+  ICreateBeamBody,
+  ICreateBeamResponse,
+  ICreateForOrganizationBeamParams,
+  IUpdateBeamParams,
+  IUpdateBeamBody,
+  IUpdateBeamResponse,
+  IDeleteBeamParams,
+  IDeleteBeamResponse,
+  ICreateBeamPublicBody,
+  IAddBeamFilesParams,
+  IAddBeamFilesBody,
+  IAddBeamFilesResponse,
+  IImportCloudBeamFilesParams,
+  IImportCloudBeamFilesBody,
+  IFinalizeBeamParams,
+  IFinalizeBeamBody,
+  IFinalizeBeamResponse,
+  IRenewBeamParams,
+  IRenewBeamResponse,
+  IReactivateBeamParams,
+  IReactivateBeamResponse,
+  ICreateBeamShareParams,
+  ICreateBeamShareBody,
+  ICreateBeamShareResponse,
+  IListBeamSharesParams,
+  IListBeamSharesResponse,
+  IRevokeBeamShareParams,
+  IRevokeBeamShareResponse,
+  IAddRecipientsBeamBody,
+  IAddRecipientsBeamResponse,
+  IListRecipientsBeamResponse,
+  IGetBeamStatsParams,
+  IGetBeamStatsQuery,
+  IGetBeamStatsResponse,
+} from '../types';
+import { BEAM_MANAGE_TOKEN_HEADER } from '../constants/beam.constants';
+
+// Anonymous management requests carry the plaintext manage token as a header the
+// API (BeamMiddleware) compares to beam_transfers.manageTokenHash. Owner requests
+// omit it and authorize via the session JWT instead.
+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 AbyssBeamCore.axios.get<IGetBeamResponse>(`/beam/${params.beamId}`);
+    return response.data;
+  },
+
+  getBySlug: async (params: IGetBeamBySlugParams): Promise<IGetBeamPublicResponse> => {
+    const response = await AbyssBeamCore.axios.get<IGetBeamPublicResponse>(`/b/${params.slug}`);
+    return response.data;
+  },
+
+  unlock: async (
+    params: IUnlockBeamPublicParams,
+    body: IUnlockBeamPublicBody,
+  ): Promise<IUnlockBeamPublicResponse> => {
+    const response = await AbyssBeamCore.axios.post<IUnlockBeamPublicResponse>(
+      `/b/${params.slug}/unlock`,
+      body,
+    );
+    return response.data;
+  },
+
+  paginate: async (query: IPaginateBeamQuery): Promise<IPaginateBeamResponse> => {
+    const response = await AbyssBeamCore.axios.get<IPaginateBeamResponse>('/beam/paginate', {
+      params: query,
+    });
+    return response.data;
+  },
+
+  paginateProject: async (
+    params: IPaginateProjectBeamParams,
+    query: IPaginateBeamQuery,
+  ): Promise<IPaginateBeamResponse> => {
+    const response = await AbyssBeamCore.axios.get<IPaginateBeamResponse>(
+      `/beam/project/${params.projectId}/paginate`,
+      { params: query },
+    );
+    return response.data;
+  },
+
+  paginateOrganization: async (
+    params: IPaginateOrganizationBeamParams,
+    query: IPaginateBeamQuery,
+  ): Promise<IPaginateBeamResponse> => {
+    const response = await AbyssBeamCore.axios.get<IPaginateBeamResponse>(
+      `/beam/organization/${params.organizationId}/paginate`,
+      { params: query },
+    );
+    return response.data;
+  },
+
+  create: async (body: ICreateBeamBody): Promise<ICreateBeamResponse> => {
+    const response = await AbyssBeamCore.axios.post<ICreateBeamResponse>('/beam', body);
+    return response.data;
+  },
+
+  createForOrganization: async (
+    params: ICreateForOrganizationBeamParams,
+    body: ICreateBeamBody,
+  ): Promise<ICreateBeamResponse> => {
+    const response = await AbyssBeamCore.axios.post<ICreateBeamResponse>(
+      `/beam/organization/${params.organizationId}`,
+      body,
+    );
+    return response.data;
+  },
+
+  update: async (
+    params: IUpdateBeamParams,
+    body: IUpdateBeamBody,
+  ): Promise<IUpdateBeamResponse> => {
+    const response = await AbyssBeamCore.axios.put<IUpdateBeamResponse>(
+      `/beam/${params.beamId}`,
+      body,
+    );
+    return response.data;
+  },
+
+  delete: async (params: IDeleteBeamParams): Promise<IDeleteBeamResponse> => {
+    const response = await AbyssBeamCore.axios.delete<IDeleteBeamResponse>(
+      `/beam/${params.beamId}`,
+    );
+    return response.data;
+  },
+
+  renew: async (params: IRenewBeamParams): Promise<IRenewBeamResponse> => {
+    return (
+      await AbyssBeamCore.axios.post<IRenewBeamResponse>(
+        `/beam/${params.beamId}/renew`,
+        renewalBody(params.days),
+      )
+    ).data;
+  },
+
+  reactivate: async (params: IReactivateBeamParams): Promise<IReactivateBeamResponse> => {
+    return (
+      await AbyssBeamCore.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 AbyssBeamCore.axios.get<IGetBeamStatsResponse>(`/beam/${params.beamId}/stats`, {
+        params: query,
+      })
+    ).data;
+  },
+
+  share: {
+    create: async (
+      params: ICreateBeamShareParams,
+      body: ICreateBeamShareBody,
+    ): Promise<ICreateBeamShareResponse> => {
+      return (
+        await AbyssBeamCore.axios.post<ICreateBeamShareResponse>(
+          `/beam/${params.beamId}/share`,
+          body,
+        )
+      ).data;
+    },
+    list: async (params: IListBeamSharesParams): Promise<IListBeamSharesResponse> => {
+      return (
+        await AbyssBeamCore.axios.get<IListBeamSharesResponse>(`/beam/${params.beamId}/share`)
+      ).data;
+    },
+    revoke: async (params: IRevokeBeamShareParams): Promise<IRevokeBeamShareResponse> => {
+      return (
+        await AbyssBeamCore.axios.delete<IRevokeBeamShareResponse>(
+          `/beam/${params.beamId}/share/${params.shareId}`,
+        )
+      ).data;
+    },
+  },
+
+  recipients: {
+    add: async (
+      params: { beamId: string },
+      body: IAddRecipientsBeamBody,
+    ): Promise<IAddRecipientsBeamResponse> =>
+      (
+        await AbyssBeamCore.axios.post<IAddRecipientsBeamResponse>(
+          `beam/${params.beamId}/recipients`,
+          body,
+        )
+      ).data,
+    list: async (params: { beamId: string }): Promise<IListRecipientsBeamResponse> =>
+      (
+        await AbyssBeamCore.axios.get<IListRecipientsBeamResponse>(
+          `beam/${params.beamId}/recipients`,
+        )
+      ).data,
+  },
+
+  addFiles: async (
+    params: IAddBeamFilesParams,
+    body: IAddBeamFilesBody,
+  ): Promise<IAddBeamFilesResponse> => {
+    return (
+      await AbyssBeamCore.axios.post<IAddBeamFilesResponse>(`/beam/${params.beamId}/files`, body)
+    ).data;
+  },
+
+  importCloudFiles: async (
+    params: IImportCloudBeamFilesParams,
+    body: IImportCloudBeamFilesBody,
+  ): Promise<IAddBeamFilesResponse> => {
+    return (
+      await AbyssBeamCore.axios.post<IAddBeamFilesResponse>(
+        `/beam/${params.beamId}/files/import-cloud`,
+        body,
+      )
+    ).data;
+  },
+
+  finalize: async (
+    params: IFinalizeBeamParams,
+    body?: IFinalizeBeamBody,
+  ): Promise<IFinalizeBeamResponse> => {
+    return (
+      await AbyssBeamCore.axios.post<IFinalizeBeamResponse>(
+        `/beam/${params.beamId}/finalize`,
+        body ?? {},
+      )
+    ).data;
+  },
+
+  public: {
+    create: async (body: ICreateBeamPublicBody): Promise<ICreateBeamResponse> => {
+      return (await AbyssBeamCore.axios.post<ICreateBeamResponse>(`/beam/public`, body)).data;
+    },
+    addFiles: async (
+      params: IAddBeamFilesParams,
+      body: IAddBeamFilesBody,
+    ): Promise<IAddBeamFilesResponse> => {
+      return (
+        await AbyssBeamCore.axios.post<IAddBeamFilesResponse>(
+          `/beam/public/${params.beamId}/files`,
+          body,
+        )
+      ).data;
+    },
+    finalize: async (
+      params: IFinalizeBeamParams,
+      body?: IFinalizeBeamBody,
+    ): Promise<IFinalizeBeamResponse> => {
+      return (
+        await AbyssBeamCore.axios.post<IFinalizeBeamResponse>(
+          `/beam/public/${params.beamId}/finalize`,
+          body ?? {},
+        )
+      ).data;
+    },
+    renew: async (
+      params: IRenewBeamParams & { manageToken?: string },
+    ): Promise<IRenewBeamResponse> => {
+      return (
+        await AbyssBeamCore.axios.post<IRenewBeamResponse>(
+          `/beam/${params.beamId}/renew`,
+          renewalBody(params.days),
+          manageTokenHeader(params.manageToken),
+        )
+      ).data;
+    },
+    reactivate: async (
+      params: IReactivateBeamParams & { manageToken?: string },
+    ): Promise<IReactivateBeamResponse> => {
+      return (
+        await AbyssBeamCore.axios.post<IReactivateBeamResponse>(
+          `/beam/${params.beamId}/reactivate`,
+          renewalBody(params.days),
+          manageTokenHeader(params.manageToken),
+        )
+      ).data;
+    },
+    update: async (
+      params: IUpdateBeamParams & { manageToken?: string },
+      body: IUpdateBeamBody,
+    ): Promise<IUpdateBeamResponse> => {
+      return (
+        await AbyssBeamCore.axios.put<IUpdateBeamResponse>(
+          `/beam/${params.beamId}`,
+          body,
+          manageTokenHeader(params.manageToken),
+        )
+      ).data;
+    },
+    delete: async (
+      params: IDeleteBeamParams & { manageToken?: string },
+    ): Promise<IDeleteBeamResponse> => {
+      return (
+        await AbyssBeamCore.axios.delete<IDeleteBeamResponse>(
+          `/beam/${params.beamId}`,
+          manageTokenHeader(params.manageToken),
+        )
+      ).data;
+    },
+  },
+};

package/src/api/index.ts

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

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

@@ -0,0 +1,106 @@
+import { AbyssBeamCore } from '../../index';
+import { BeamVisibility } from '../../types';
+
+describe('beamApi', () => {
+  it('exposes the beam CRUD namespace on the SDK facade', () => {
+    const beam = AbyssBeamCore.sdk.beam;
+    expect(typeof beam.get).toBe('function');
+    expect(typeof beam.getBySlug).toBe('function');
+    expect(typeof beam.paginate).toBe('function');
+    expect(typeof beam.paginateProject).toBe('function');
+    expect(typeof beam.paginateOrganization).toBe('function');
+    expect(typeof beam.create).toBe('function');
+    expect(typeof beam.update).toBe('function');
+    expect(typeof beam.delete).toBe('function');
+  });
+
+  it('create posts to /beam and returns the wrapped transfer', async () => {
+    const post = jest
+      .spyOn(AbyssBeamCore.axios, 'post')
+      .mockResolvedValue({ data: { data: { beamTransfer: { id: 't1' } } } });
+
+    const res = await AbyssBeamCore.sdk.beam.create({
+      title: 'T',
+      visibility: BeamVisibility.PUBLIC,
+    });
+
+    expect(post).toHaveBeenCalledWith('/beam', { title: 'T', visibility: BeamVisibility.PUBLIC });
+    expect(res.data.beamTransfer.id).toBe('t1');
+    post.mockRestore();
+  });
+
+  it('getBySlug reads the public /b/:slug path', async () => {
+    const get = jest
+      .spyOn(AbyssBeamCore.axios, 'get')
+      .mockResolvedValue({ data: { data: { beamTransfer: { id: 't1', slug: 'abcdefghij' } } } });
+
+    await AbyssBeamCore.sdk.beam.getBySlug({ slug: 'abcdefghij' });
+
+    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(AbyssBeamCore.axios, 'post')
+      .mockResolvedValue({ data: { data: { beamTransfer: { id: 't1' } } } });
+
+    await AbyssBeamCore.sdk.beam.renew({ beamId: 't1' });
+    expect(post).toHaveBeenCalledWith('/beam/t1/renew', {});
+
+    await AbyssBeamCore.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(AbyssBeamCore.axios, 'post')
+      .mockResolvedValue({ data: { data: { beamTransfer: { id: 't1' } } } });
+
+    await AbyssBeamCore.sdk.beam.reactivate({ beamId: 't1' });
+    expect(post).toHaveBeenCalledWith('/beam/t1/reactivate', {});
+
+    await AbyssBeamCore.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(AbyssBeamCore.axios, 'post')
+      .mockResolvedValue({ data: { data: { beamTransfer: { id: 't1' } } } });
+
+    await AbyssBeamCore.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(AbyssBeamCore.axios, 'get').mockResolvedValue({
+      data: {
+        data: {
+          byDay: [{ day: '2026-07-09', count: 2, zipCount: 1 }],
+          recent: [],
+          totals: { downloadCount: 2, lastDownloadedAt: null },
+        },
+      },
+    });
+
+    const res = await AbyssBeamCore.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/constants/beam.constants.ts

@@ -0,0 +1,4 @@
+// Header carrying the anonymous transfer management secret (spec §7). The front
+// keeps the plaintext manageToken in the URL fragment and sends it here; the API
+// (BeamMiddleware) compares sha256(header) to beam_transfers.manageTokenHash.
+export const BEAM_MANAGE_TOKEN_HEADER = 'x-beam-manage-token';

package/src/constants/index.ts

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

package/src/index.ts

@@ -0,0 +1,167 @@
+import axios from 'axios';
+import axiosRetry, { IAxiosRetryConfig, isNetworkOrIdempotentRequestError } from 'axios-retry';
+
+export * from './api';
+export * from './types';
+export * from './utils';
+export * from './constants';
+
+import * as beamApiModule from './api/beam.api';
+
+const DEFAULT_BASE_URL = 'https://beam-api.abyss-project.fr/api/';
+
+export const API_KEY_HEADER = 'abyss-api-key';
+export const ADMIN_TOKEN_HEADER = 'abyss-admin-token';
+
+const NUMBER_RETRY_API = 10;
+const BASE_DELAY_BETWEEN_RETRY = 5000;
+const RETRY_CODES = [
+  502, // Bad Gateway
+  503, // Service Unavailable
+];
+
+type CoreConfig = {
+  token?: string;
+  apiKey?: string;
+  adminToken?: string;
+  baseURL?: string;
+};
+
+type AbyssBeamCoreSDK = {
+  beam: {
+    get: typeof beamApiModule.beamApi.get;
+    getBySlug: typeof beamApiModule.beamApi.getBySlug;
+    unlock: typeof beamApiModule.beamApi.unlock;
+    paginate: typeof beamApiModule.beamApi.paginate;
+    paginateProject: typeof beamApiModule.beamApi.paginateProject;
+    paginateOrganization: typeof beamApiModule.beamApi.paginateOrganization;
+    create: typeof beamApiModule.beamApi.create;
+    createForOrganization: typeof beamApiModule.beamApi.createForOrganization;
+    update: typeof beamApiModule.beamApi.update;
+    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;
+      revoke: typeof beamApiModule.beamApi.share.revoke;
+    };
+    recipients: {
+      add: typeof beamApiModule.beamApi.recipients.add;
+      list: typeof beamApiModule.beamApi.recipients.list;
+    };
+    addFiles: typeof beamApiModule.beamApi.addFiles;
+    importCloudFiles: typeof beamApiModule.beamApi.importCloudFiles;
+    finalize: typeof beamApiModule.beamApi.finalize;
+    public: {
+      create: typeof beamApiModule.beamApi.public.create;
+      addFiles: typeof beamApiModule.beamApi.public.addFiles;
+      finalize: typeof beamApiModule.beamApi.public.finalize;
+      renew: typeof beamApiModule.beamApi.public.renew;
+      reactivate: typeof beamApiModule.beamApi.public.reactivate;
+      update: typeof beamApiModule.beamApi.public.update;
+      delete: typeof beamApiModule.beamApi.public.delete;
+    };
+  };
+};
+
+export class AbyssBeamCore {
+  private static config = {
+    token: '',
+    apiKey: '',
+    adminToken: '',
+    baseURL: DEFAULT_BASE_URL,
+  };
+  static axios = axios.create({
+    baseURL: this.config.baseURL,
+    withCredentials: true,
+  });
+
+  private static _sdk: AbyssBeamCoreSDK | null = null;
+
+  public static get sdk(): AbyssBeamCoreSDK {
+    if (!AbyssBeamCore._sdk) {
+      AbyssBeamCore._sdk = AbyssBeamCore.buildSDK();
+    }
+    return AbyssBeamCore._sdk;
+  }
+
+  private static buildSDK(): AbyssBeamCoreSDK {
+    return {
+      beam: {
+        get: beamApiModule.beamApi.get,
+        getBySlug: beamApiModule.beamApi.getBySlug,
+        unlock: beamApiModule.beamApi.unlock,
+        paginate: beamApiModule.beamApi.paginate,
+        paginateProject: beamApiModule.beamApi.paginateProject,
+        paginateOrganization: beamApiModule.beamApi.paginateOrganization,
+        create: beamApiModule.beamApi.create,
+        createForOrganization: beamApiModule.beamApi.createForOrganization,
+        update: beamApiModule.beamApi.update,
+        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,
+          revoke: beamApiModule.beamApi.share.revoke,
+        },
+        recipients: {
+          add: beamApiModule.beamApi.recipients.add,
+          list: beamApiModule.beamApi.recipients.list,
+        },
+        addFiles: beamApiModule.beamApi.addFiles,
+        importCloudFiles: beamApiModule.beamApi.importCloudFiles,
+        finalize: beamApiModule.beamApi.finalize,
+        public: {
+          create: beamApiModule.beamApi.public.create,
+          addFiles: beamApiModule.beamApi.public.addFiles,
+          finalize: beamApiModule.beamApi.public.finalize,
+          renew: beamApiModule.beamApi.public.renew,
+          reactivate: beamApiModule.beamApi.public.reactivate,
+          update: beamApiModule.beamApi.public.update,
+          delete: beamApiModule.beamApi.public.delete,
+        },
+      },
+    };
+  }
+
+  public static enableAxiosRetry(axiosRetryConfig?: IAxiosRetryConfig): void {
+    axiosRetry(AbyssBeamCore.axios, {
+      retries: NUMBER_RETRY_API,
+      retryDelay: (retryCount) => retryCount * BASE_DELAY_BETWEEN_RETRY,
+      retryCondition: (error) =>
+        isNetworkOrIdempotentRequestError(error) ||
+        RETRY_CODES.includes(error.response?.status || 502),
+      ...axiosRetryConfig,
+    });
+  }
+
+  public static setConfig(config: CoreConfig): void {
+    AbyssBeamCore._sdk = null;
+
+    AbyssBeamCore.config = { ...AbyssBeamCore.config, ...config };
+
+    if (config.baseURL) {
+      AbyssBeamCore.axios.defaults.baseURL = config.baseURL;
+    }
+
+    if (config.token) {
+      AbyssBeamCore.axios.defaults.headers.common.Authorization = `Bearer ${config.token}`;
+    }
+
+    if (config.apiKey) {
+      AbyssBeamCore.axios.defaults.headers.common[API_KEY_HEADER] = `${config.apiKey}`;
+    }
+
+    if (config.adminToken) {
+      AbyssBeamCore.axios.defaults.headers.common[ADMIN_TOKEN_HEADER] = `${config.adminToken}`;
+    }
+  }
+
+  public static getConfig(): CoreConfig {
+    return AbyssBeamCore.config;
+  }
+}

package/src/types/enum/api-error.enum.ts

@@ -0,0 +1,33 @@
+export enum ErrorType {
+  apiError = 'api_error',
+  authError = 'authentication_error',
+  resourceError = 'resource_error',
+}
+
+export enum Code {
+  // HTTP Error
+  tokenFailure = 'token_authentication_failure',
+  authenticationFailure = 'authentication_credentials_failure',
+  accessNotAllowed = 'access_not_allowed',
+  notFound = 'not_found',
+  validationError = 'resource_validation_error',
+  constraintError = 'resource_constraint_error',
+  internalServerError = 'internal_server_error',
+  serviceUnavailable = 'service_unavailable',
+  invalidData = 'invalid_data',
+  notImplemented = 'not_implemented',
+  retrospectiveCannotBeModifiedWhenCompleted = 'retrospective_cannot_be_modified_when_completed',
+  retrospectiveActionNotAllowedInPhase = 'retrospective_action_not_allowed_in_phase',
+  retrospectiveVoteBudgetExhausted = 'retrospective_vote_budget_exhausted',
+  retrospectiveActionLimitReached = 'retrospective_action_limit_reached',
+  atlasDocumentLimitReached = 'atlas_document_limit_reached',
+  boardCardDocumentLimitReached = 'board_card_document_limit_reached',
+  boardCardMoveInvalidDestination = 'board_card_move_invalid_destination',
+  boardCardLinkLimitReached = 'board_card_link_limit_reached',
+  boardCardLinkAlreadyExists = 'board_card_link_already_exists',
+  boardCardLinkToSelf = 'board_card_link_to_self',
+  shortLinkProtected = 'short_link_protected',
+  drawImageLimitReached = 'draw_image_limit_reached',
+  drawImageOwnerRequired = 'draw_image_owner_required',
+  drawImageNotInDraw = 'draw_image_not_in_draw',
+}

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

@@ -0,0 +1,48 @@
+// AbyssBeam transfer visibility (design D7). PUBLIC = a contentShare LINK so the
+// /b/:slug link works for anyone until expiry; RESTRICTED = USER/ORG/TEAM/PROJECT
+// grants resolved via contentShare.resolveAccess (>= VIEW). Password is an
+// independent second factor, NOT a visibility level.
+export enum BeamVisibility {
+  PUBLIC = 'PUBLIC',
+  RESTRICTED = 'RESTRICTED',
+}
+
+// Machine-readable denial reason returned on the public serving discovery path
+// (GET /b/:slug) so the front renders the correct state from the reason code
+// rather than inferring it from the bare HTTP status (spec §17.1). Mirrors the
+// backend `BeamServeDenyReason`; only the non-password discovery denials are
+// surfaced here (PASSWORD_REQUIRED is not a VIEW denial — the metadata is still
+// returned with isLocked=true). Byte endpoints (/file, /raw, /thumb, /zip) stay
+// bare-status by design (CDN-visible), so this reason is a VIEW-only signal.
+export enum BeamServeDenyReasonCode {
+  NOT_FOUND = 'not_found',
+  EXPIRED = 'expired',
+  FORBIDDEN_VISIBILITY = 'forbidden_visibility',
+  MAX_DOWNLOADS = 'max_downloads',
+  SCAN_PENDING = 'scan_pending',
+}
+
+// Per-file AV verdict surfaced on the public listing (GET /b/:slug) so the
+// front can render a per-file badge — clean / "en analyse" (pending) /
+// "infecté" — independently of the whole-transfer denial reason above.
+// Storage-neutral: AbyssBeam serves an INFECTED file's bytes (spec decision —
+// infected files stay downloadable, not blocked; the front is expected to
+// warn before/at download). Mirrors the storage extension's `FileScanStatus`
+// (`@abyss-project/storage`) byte-for-byte; duplicated locally because this
+// package does not depend on `@abyss-project/storage` (same rationale as
+// BeamServeDenyReasonCode above).
+export enum BeamFileScanStatus {
+  PENDING_SCAN = 'pending_scan',
+  CLEAN = 'clean',
+  INFECTED = 'infected',
+  SKIPPED = 'skipped',
+  ERROR = 'error',
+}
+
+// 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',
+}