@abyss-project/link 1.0.0 → 1.1.0

package/src/constants/link.constants.ts

@@ -43,7 +43,24 @@ export const MAX_LINK_PASSWORD_LENGTH = 128;
 export const LINK_RESOURCE_CODE_LENGTH = 10;
 /** Base62 campaign token. */
 export const LINK_CAMPAIGN_TOKEN_LENGTH = 12;
+/** Campaign tokens a product resource (a Spotlight project) holds at most (O5). */
 export const LINK_CAMPAIGN_TOKENS_PER_PROJECT = 50;
+/** The query parameter carrying a campaign token on the product's page: `?lnk=<token>`. */
+export const CAMPAIGN_TOKEN_QUERY_PARAM = 'lnk';
 
 /** Raw visits are kept this long (O2); daily aggregates live as long as the link. */
 export const LINK_VISIT_RETENTION_DAYS = 90;
+
+/** Schemes a link may target. */
+export const LINK_ALLOWED_URL_SCHEMES = ['http', 'https'] as const;
+/** Length of the slug drawn when a SHORTENED link is created without one. */
+export const LINK_GENERATED_SLUG_LENGTH = 6;
+export const MAX_LINK_TARGET_URL_LENGTH = 2048;
+export const MAX_LINK_TITLE_LENGTH = 255;
+export const MAX_LINK_DESCRIPTION_LENGTH = 1000;
+export const MIN_LINK_MAX_CLICKS = 1;
+
+export const MIN_LINK_PAGE = 1;
+export const MIN_LINK_LIMIT = 1;
+export const MAX_LINK_LIMIT = 100;
+export const DEFAULT_LINK_LIMIT = 20;

package/src/index.ts

@@ -7,6 +7,9 @@ export * from './utils';
 export * from './constants';
 
 import * as abyssAdminApi from './api/abyss.admin.api';
+import * as linkApi from './api/link.api';
+import * as linkAdminApi from './api/link.admin.api';
+import * as linkPublicApi from './api/link.public.api';
 
 const DEFAULT_BASE_URL = 'https://link-api.abyss-project.fr/api/';
 
@@ -35,6 +38,40 @@ type AbyssLinkCoreSDK = {
       syncProject: typeof abyssAdminApi.syncProjectAbyssAdmin;
     };
   };
+  link: {
+    get: typeof linkApi.getLink;
+    paginate: typeof linkApi.paginateLink;
+    paginateProject: typeof linkApi.paginateProjectLink;
+    paginateOrganization: typeof linkApi.paginateOrganizationLink;
+    countOrganization: typeof linkApi.countOrganizationLink;
+    create: typeof linkApi.createLink;
+    createForOrganization: typeof linkApi.createForOrganizationLink;
+    update: typeof linkApi.updateLink;
+    delete: typeof linkApi.deleteLink;
+    transfer: typeof linkApi.transferLink;
+    getStats: typeof linkApi.getStatsLink;
+    getVisits: typeof linkApi.getVisitsLink;
+    getByOrigin: typeof linkApi.getByOriginLink;
+    getStatsByOrigin: typeof linkApi.getStatsByOriginLink;
+    public: {
+      unlock: typeof linkPublicApi.unlockLinkPublic;
+    };
+    admin: {
+      paginate: typeof linkAdminApi.paginateLinkAdmin;
+      get: typeof linkAdminApi.getLinkAdmin;
+      getVisits: typeof linkAdminApi.getVisitsLinkAdmin;
+      getCampaignStats: typeof linkAdminApi.getCampaignStatsLinkAdmin;
+      setProtection: typeof linkAdminApi.setProtectionLinkAdmin;
+      update: typeof linkAdminApi.updateLinkAdmin;
+      delete: typeof linkAdminApi.deleteLinkAdmin;
+      create: typeof linkAdminApi.createLinkAdmin;
+      getByOrigin: typeof linkAdminApi.getByOriginLinkAdmin;
+      getStatsByOrigin: typeof linkAdminApi.getStatsByOriginLinkAdmin;
+      recordCampaignView: typeof linkAdminApi.recordCampaignViewLinkAdmin;
+      listCampaignTokens: typeof linkAdminApi.listCampaignTokensLinkAdmin;
+      deleteCampaignToken: typeof linkAdminApi.deleteCampaignTokenLinkAdmin;
+    };
+  };
 };
 
 export class AbyssLinkCore {
@@ -67,6 +104,40 @@ export class AbyssLinkCore {
           syncProject: abyssAdminApi.syncProjectAbyssAdmin,
         },
       },
+      link: {
+        get: linkApi.getLink,
+        paginate: linkApi.paginateLink,
+        paginateProject: linkApi.paginateProjectLink,
+        paginateOrganization: linkApi.paginateOrganizationLink,
+        countOrganization: linkApi.countOrganizationLink,
+        create: linkApi.createLink,
+        createForOrganization: linkApi.createForOrganizationLink,
+        update: linkApi.updateLink,
+        delete: linkApi.deleteLink,
+        transfer: linkApi.transferLink,
+        getStats: linkApi.getStatsLink,
+        getVisits: linkApi.getVisitsLink,
+        getByOrigin: linkApi.getByOriginLink,
+        getStatsByOrigin: linkApi.getStatsByOriginLink,
+        public: {
+          unlock: linkPublicApi.unlockLinkPublic,
+        },
+        admin: {
+          paginate: linkAdminApi.paginateLinkAdmin,
+          get: linkAdminApi.getLinkAdmin,
+          getVisits: linkAdminApi.getVisitsLinkAdmin,
+          getCampaignStats: linkAdminApi.getCampaignStatsLinkAdmin,
+          setProtection: linkAdminApi.setProtectionLinkAdmin,
+          update: linkAdminApi.updateLinkAdmin,
+          delete: linkAdminApi.deleteLinkAdmin,
+          create: linkAdminApi.createLinkAdmin,
+          getByOrigin: linkAdminApi.getByOriginLinkAdmin,
+          getStatsByOrigin: linkAdminApi.getStatsByOriginLinkAdmin,
+          recordCampaignView: linkAdminApi.recordCampaignViewLinkAdmin,
+          listCampaignTokens: linkAdminApi.listCampaignTokensLinkAdmin,
+          deleteCampaignToken: linkAdminApi.deleteCampaignTokenLinkAdmin,
+        },
+      },
     };
   }
 

package/src/tests/link-public-api.spec.ts

@@ -0,0 +1,37 @@
+import { AbyssLinkCore } from '..';
+
+describe('AbyssLinkCore.sdk.link.public', () => {
+  let post: jest.SpyInstance;
+
+  beforeEach(() => {
+    post = jest
+      .spyOn(AbyssLinkCore.axios, 'post')
+      .mockResolvedValue({ data: { data: { url: 'https://example.com/landing' } } });
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('unlocks with POST link/public/<slug>/unlock, the password and the visit data in the body', async () => {
+    const answer = await AbyssLinkCore.sdk.link.public.unlock({
+      slug: 'Launch',
+      password: 'open sesame',
+      ref: 'https://news.example.org/a',
+      utmSource: 'mail',
+    });
+
+    expect(post).toHaveBeenCalledWith('link/public/Launch/unlock', {
+      password: 'open sesame',
+      ref: 'https://news.example.org/a',
+      utmSource: 'mail',
+    });
+    expect(answer).toEqual({ data: { url: 'https://example.com/landing' } });
+  });
+
+  it('encodes the slug in the path', async () => {
+    await AbyssLinkCore.sdk.link.public.unlock({ slug: 'a/b', password: 'x' });
+
+    expect(post).toHaveBeenCalledWith('link/public/a%2Fb/unlock', { password: 'x' });
+  });
+});

package/src/tests/link-sdk-surface.spec.ts

@@ -0,0 +1,191 @@
+import { AbyssLinkCore, LinkKind, LinkResourceProduct, LinkStatsGranularity } from '..';
+
+const LINK_ID = '11111111-1111-4111-8111-111111111111';
+const ORGANIZATION_ID = '22222222-2222-4222-8222-222222222222';
+const PROJECT_ID = '33333333-3333-4333-8333-333333333333';
+const ORIGIN = {
+  service: LinkResourceProduct.BEAM,
+  resourceType: 'beam_transfer',
+  resourceId: '44444444-4444-4444-8444-444444444444',
+};
+
+/**
+ * `sdk.link.*` (the user routes of the Links screen) and `sdk.link.admin.*` (the back-office and
+ * Monitor): each call hits the route `link.controller.ts` / `link.admin.controller.ts` serve.
+ */
+describe('AbyssLinkCore sdk.link surface', () => {
+  let get: jest.SpyInstance;
+  let post: jest.SpyInstance;
+  let put: jest.SpyInstance;
+  let del: jest.SpyInstance;
+
+  beforeEach(() => {
+    const ok = { data: { data: {} } };
+    get = jest.spyOn(AbyssLinkCore.axios, 'get').mockResolvedValue(ok);
+    post = jest.spyOn(AbyssLinkCore.axios, 'post').mockResolvedValue(ok);
+    put = jest.spyOn(AbyssLinkCore.axios, 'put').mockResolvedValue(ok);
+    del = jest.spyOn(AbyssLinkCore.axios, 'delete').mockResolvedValue(ok);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('exposes the user routes and the admin routes', () => {
+    expect(Object.keys(AbyssLinkCore.sdk.link)).toEqual(
+      expect.arrayContaining([
+        'get',
+        'paginate',
+        'paginateProject',
+        'paginateOrganization',
+        'countOrganization',
+        'create',
+        'createForOrganization',
+        'update',
+        'delete',
+        'transfer',
+        'getStats',
+        'getVisits',
+        'getByOrigin',
+        'getStatsByOrigin',
+        'admin',
+      ]),
+    );
+    expect(Object.keys(AbyssLinkCore.sdk.link.admin).sort()).toEqual([
+      'create',
+      'delete',
+      'deleteCampaignToken',
+      'get',
+      'getByOrigin',
+      'getCampaignStats',
+      'getStatsByOrigin',
+      'getVisits',
+      'listCampaignTokens',
+      'paginate',
+      'recordCampaignView',
+      'setProtection',
+      'update',
+    ]);
+  });
+
+  it('reads the user routes', async () => {
+    const { link } = AbyssLinkCore.sdk;
+    await link.get({ linkId: LINK_ID });
+    expect(get).toHaveBeenLastCalledWith(`link/${LINK_ID}`);
+    await link.paginate({ page: 2, search: 'promo' });
+    expect(get).toHaveBeenLastCalledWith('link/paginate', { params: { page: 2, search: 'promo' } });
+    await link.paginateProject({ projectId: PROJECT_ID }, { page: 1 });
+    expect(get).toHaveBeenLastCalledWith(`link/project/${PROJECT_ID}/paginate`, {
+      params: { page: 1 },
+    });
+    await link.paginateOrganization({ organizationId: ORGANIZATION_ID }, { adminView: true });
+    expect(get).toHaveBeenLastCalledWith(`link/organization/${ORGANIZATION_ID}/paginate`, {
+      params: { adminView: true },
+    });
+    await link.countOrganization({ organizationId: ORGANIZATION_ID });
+    expect(get).toHaveBeenLastCalledWith(`link/organization/${ORGANIZATION_ID}/count`, {
+      params: {},
+    });
+    await link.getStats({ linkId: LINK_ID }, { granularity: LinkStatsGranularity.WEEK });
+    expect(get).toHaveBeenLastCalledWith(`link/${LINK_ID}/stats`, {
+      params: { granularity: LinkStatsGranularity.WEEK },
+    });
+    await link.getVisits({ linkId: LINK_ID }, { page: 3 });
+    expect(get).toHaveBeenLastCalledWith(`link/${LINK_ID}/visits`, { params: { page: 3 } });
+    await link.getByOrigin(ORIGIN);
+    expect(get).toHaveBeenLastCalledWith('link/origin', { params: ORIGIN });
+    await link.getStatsByOrigin({ ...ORIGIN, from: '2026-11-01' });
+    expect(get).toHaveBeenLastCalledWith('link/origin/stats', {
+      params: { ...ORIGIN, from: '2026-11-01' },
+    });
+  });
+
+  it('writes through the user routes', async () => {
+    const { link } = AbyssLinkCore.sdk;
+    await link.create({ targetUrl: 'https://example.com' });
+    expect(post).toHaveBeenLastCalledWith('link', { targetUrl: 'https://example.com' });
+    await link.createForOrganization(
+      { organizationId: ORGANIZATION_ID },
+      { targetUrl: 'https://example.com', projectId: PROJECT_ID },
+    );
+    expect(post).toHaveBeenLastCalledWith(`link/organization/${ORGANIZATION_ID}`, {
+      targetUrl: 'https://example.com',
+      projectId: PROJECT_ID,
+    });
+    await link.update({ linkId: LINK_ID }, { isActive: false });
+    expect(put).toHaveBeenLastCalledWith(`link/${LINK_ID}`, { isActive: false });
+    await link.transfer({ linkId: LINK_ID }, { newOwnerId: PROJECT_ID });
+    expect(post).toHaveBeenLastCalledWith(`link/${LINK_ID}/transfer`, { newOwnerId: PROJECT_ID });
+    await link.delete({ linkId: LINK_ID });
+    expect(del).toHaveBeenLastCalledWith(`link/${LINK_ID}`);
+  });
+
+  it('calls the admin routes', async () => {
+    const { admin } = AbyssLinkCore.sdk.link;
+    await admin.paginate({ isProtected: true });
+    expect(get).toHaveBeenLastCalledWith('admin/link/paginate', {
+      params: { isProtected: true },
+    });
+    await admin.get({ linkId: LINK_ID });
+    expect(get).toHaveBeenLastCalledWith(`admin/link/${LINK_ID}`);
+    await admin.getVisits({ linkId: LINK_ID }, { limit: 10 });
+    expect(get).toHaveBeenLastCalledWith(`admin/link/${LINK_ID}/visits`, {
+      params: { limit: 10 },
+    });
+    await admin.getCampaignStats(
+      { linkId: LINK_ID },
+      { from: '2026-11-01T00:00:00.000Z', to: '2026-11-11T00:00:00.000Z' },
+    );
+    expect(get).toHaveBeenLastCalledWith(`admin/link/${LINK_ID}/campaign-stats`, {
+      params: { from: '2026-11-01T00:00:00.000Z', to: '2026-11-11T00:00:00.000Z' },
+    });
+    await admin.setProtection({ linkId: LINK_ID }, { isProtected: true, adminId: PROJECT_ID });
+    expect(put).toHaveBeenLastCalledWith(`admin/link/${LINK_ID}/protection`, {
+      isProtected: true,
+      adminId: PROJECT_ID,
+    });
+    await admin.update({ linkId: LINK_ID }, { isActive: false });
+    expect(put).toHaveBeenLastCalledWith(`admin/link/${LINK_ID}`, { isActive: false });
+    await admin.delete({ linkId: LINK_ID });
+    expect(del).toHaveBeenLastCalledWith(`admin/link/${LINK_ID}`);
+  });
+
+  it('calls the product routes (T3.1)', async () => {
+    const { admin } = AbyssLinkCore.sdk.link;
+    const scope = { userId: null, organizationId: ORGANIZATION_ID, projectId: PROJECT_ID };
+    await admin.create({
+      kind: LinkKind.RESOURCE,
+      origin: ORIGIN,
+      targetUrl: 'https://beam.example.com/b/x',
+      scope,
+    });
+    expect(post).toHaveBeenLastCalledWith('admin/link', {
+      kind: LinkKind.RESOURCE,
+      origin: ORIGIN,
+      targetUrl: 'https://beam.example.com/b/x',
+      scope,
+    });
+    await admin.getByOrigin(ORIGIN);
+    expect(get).toHaveBeenLastCalledWith('admin/link/origin', { params: ORIGIN });
+    await admin.getStatsByOrigin(ORIGIN, { granularity: LinkStatsGranularity.MONTH });
+    expect(get).toHaveBeenLastCalledWith('admin/link/origin/stats', {
+      params: { ...ORIGIN, granularity: LinkStatsGranularity.MONTH },
+    });
+    await admin.getStatsByOrigin(ORIGIN);
+    expect(get).toHaveBeenLastCalledWith('admin/link/origin/stats', { params: ORIGIN });
+    const view = { token: 'Ab3dE5gH9kLm', ip: '203.0.113.7', utm: { utmSource: 'mail' } };
+    await admin.recordCampaignView(view);
+    expect(post).toHaveBeenLastCalledWith('admin/link/campaign-view', view);
+    await admin.listCampaignTokens(ORIGIN);
+    expect(get).toHaveBeenLastCalledWith('admin/link/campaign-token', { params: ORIGIN });
+    await admin.deleteCampaignToken({ linkId: LINK_ID });
+    expect(del).toHaveBeenLastCalledWith(`admin/link/campaign-token/${LINK_ID}`);
+  });
+
+  it('returns the response body', async () => {
+    get.mockResolvedValueOnce({ data: { data: { link: { id: LINK_ID } } } });
+    await expect(AbyssLinkCore.sdk.link.get({ linkId: LINK_ID })).resolves.toEqual({
+      data: { link: { id: LINK_ID } },
+    });
+  });
+});

package/src/tests/sdk-surface.spec.ts

@@ -16,7 +16,7 @@ describe('AbyssLinkCore SDK surface', () => {
   });
 
   it('exposes exactly the three abyss.admin calls', () => {
-    expect(Object.keys(AbyssLinkCore.sdk)).toEqual(['abyss']);
+    expect(Object.keys(AbyssLinkCore.sdk)).toEqual(['abyss', 'link']);
     expect(Object.keys(AbyssLinkCore.sdk.abyss)).toEqual(['admin']);
     expect(Object.keys(AbyssLinkCore.sdk.abyss.admin).sort()).toEqual([
       'activateUserService',

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

@@ -15,4 +15,17 @@ export enum Code {
   internalServerError = 'internal_server_error',
   serviceUnavailable = 'service_unavailable',
   invalidData = 'invalid_data',
+
+  // Link management (422 / 409 / 403 with an explicit code the front can name)
+  linkSlugForbidden = 'link_slug_forbidden',
+  linkTargetForbidden = 'link_target_forbidden',
+  linkSlugTaken = 'link_slug_taken',
+  linkProtected = 'link_protected',
+  linkManagedByProduct = 'link_managed_by_product',
+  // 422: the product resource already holds LINK_CAMPAIGN_TOKENS_PER_PROJECT campaign tokens (O5)
+  linkCampaignTokenLimit = 'link_campaign_token_limit',
+
+  // Link unlock (401 wrong password, 410 a link that can no longer be followed)
+  linkWrongPassword = 'link_wrong_password',
+  linkExpired = 'link_expired',
 }

package/src/types/enum/index.ts

@@ -1,2 +1,4 @@
 export * from './api-error.enum';
 export * from './link.enum';
+export * from './link-stats.enum';
+export * from './link-share.enum';

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

@@ -0,0 +1,17 @@
+/**
+ * Permission of the caller on a link, from abyss-main's content sharing (spec §5). Same values as
+ * `SharePermission` of `@abyss-project/main`, which this SDK does not depend on.
+ */
+export enum LinkSharePermission {
+  VIEW = 'VIEW',
+  EDIT = 'EDIT',
+  MANAGE = 'MANAGE',
+}
+
+/** Scope of the organization list, same values as `ContentShareScope` of `@abyss-project/main`. */
+export enum LinkShareScope {
+  ORGANIZATION = 'ORGANIZATION',
+  ORG_USER = 'ORG_USER',
+  ORG_TEAM = 'ORG_TEAM',
+  ORG_PROJECT = 'ORG_PROJECT',
+}

package/src/types/enum/link-stats.enum.ts

@@ -0,0 +1,6 @@
+/** Bucket of the series of `getStats`. A bucket sums the daily values of its UTC days. */
+export enum LinkStatsGranularity {
+  DAY = 'DAY',
+  WEEK = 'WEEK',
+  MONTH = 'MONTH',
+}

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

@@ -1 +1,4 @@
 export * from './abyss.admin.request';
+export * from './link.request';
+export * from './link.admin.request';
+export * from './link.public.request';

package/src/types/interface/api/requests/link.admin.request.ts

@@ -0,0 +1,104 @@
+import { LinkKind } from '../../../enum/link.enum';
+import { ILinkOrigin } from '../../models/link.dto';
+import { QueryPaginate } from '../type-message/base-paginate';
+import { IGetLinkStatsQuery, ILinkIdParams } from './link.request';
+
+export interface IPaginateLinkAdminQuery extends QueryPaginate {
+  search?: string;
+  kind?: LinkKind;
+  userId?: string;
+  projectId?: string;
+  organizationId?: string;
+  isActive?: boolean;
+  isProtected?: boolean;
+}
+
+export type IGetLinkAdminParams = ILinkIdParams;
+export type IGetVisitsLinkAdminParams = ILinkIdParams;
+export type IGetVisitsLinkAdminQuery = QueryPaginate;
+export type IGetCampaignStatsLinkAdminParams = ILinkIdParams;
+export type ISetProtectionLinkAdminParams = ILinkIdParams;
+export type IUpdateLinkAdminParams = ILinkIdParams;
+export type IDeleteLinkAdminParams = ILinkIdParams;
+
+/** Human visits of `[from, to)`, read from the raw visits: days older than the retention count nothing. */
+export interface IGetCampaignStatsLinkAdminQuery {
+  from: Date | string;
+  to: Date | string;
+}
+
+export interface ISetProtectionLinkAdminBody {
+  isProtected: boolean;
+  /** The back-office administrator, recorded on the link and in abyss-main's audit. */
+  adminId: string;
+}
+
+/** What the back-office changes on a link: no password, which stays the owner's. */
+export interface IUpdateLinkAdminBody {
+  targetUrl?: string;
+  slug?: string;
+  title?: string | null;
+  description?: string | null;
+  isActive?: boolean;
+  expiresAt?: Date | string | null;
+  maxClicks?: number | null;
+}
+
+/** The kinds a product creates through `sdk.link.admin.create`; SHORTENED belongs to the user. */
+export type LinkProductKind = LinkKind.RESOURCE | LinkKind.CAMPAIGN_TOKEN;
+
+/**
+ * The container of a product's link (spec §4): kept for the deletion fan-out and the access, never
+ * a billing scope (a product's link is free on Link's lines).
+ */
+export interface ILinkContainerScope {
+  userId: string | null;
+  organizationId: string | null;
+  projectId: string | null;
+  /** The user acting in the product, when there is one. */
+  createdByUserId?: string | null;
+}
+
+/**
+ * A RESOURCE address (`<host>/<prefix>/<code>`) or a CAMPAIGN_TOKEN for a product resource. A
+ * RESOURCE is one per origin: a second call returns the existing link. A campaign token is a new
+ * token on each call, at most `LINK_CAMPAIGN_TOKENS_PER_PROJECT` per origin (422
+ * `link_campaign_token_limit` beyond).
+ */
+export interface ICreateLinkAdminBody {
+  kind: LinkProductKind;
+  origin: ILinkOrigin;
+  targetUrl: string;
+  scope: ILinkContainerScope;
+  /** A label the product shows, for example the channel of a campaign token. */
+  title?: string | null;
+}
+
+/** The product resource, flattened in the query string. */
+export type IGetByOriginLinkAdminQuery = ILinkOrigin;
+export type IGetStatsByOriginLinkAdminQuery = ILinkOrigin & IGetLinkStatsQuery;
+export type IListCampaignTokensLinkAdminQuery = ILinkOrigin;
+export type IDeleteCampaignTokenLinkAdminParams = ILinkIdParams;
+
+/** The campaign parameters of a page view, in the SDK's camelCase. */
+export interface ILinkVisitCampaign {
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+}
+
+/**
+ * A page view a product reports for a campaign token, after answering its visitor. Link hashes the
+ * visitor with the day's salt, looks the country and the city up locally and discards the IP: it is
+ * never stored, logged nor sent on.
+ */
+export interface IRecordCampaignViewLinkAdminBody {
+  token: string;
+  ip: string;
+  userAgent?: string;
+  /** The full referer: only its domain is kept. */
+  referer?: string;
+  utm?: ILinkVisitCampaign;
+}

package/src/types/interface/api/requests/link.public.request.ts

@@ -0,0 +1,18 @@
+export interface IUnlockLinkPublicParams {
+  slug: string;
+}
+
+/**
+ * The password of a shortened link, plus what the visit records about where the visitor came from:
+ * the unlock page reads them from the address the Link host sent it to (`?ref`, `?lang`, `utm_*`).
+ */
+export interface IUnlockLinkPublicBody {
+  password: string;
+  ref?: string;
+  lang?: string;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+}

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

@@ -0,0 +1,100 @@
+import { LinkShareScope } from '../../../enum/link-share.enum';
+import { LinkStatsGranularity } from '../../../enum/link-stats.enum';
+import { ILinkOrigin } from '../../models/link.dto';
+import { QueryPaginate } from '../type-message/base-paginate';
+
+export interface ILinkIdParams {
+  linkId: string;
+}
+
+export type IGetLinkParams = ILinkIdParams;
+export type IUpdateLinkParams = ILinkIdParams;
+export type IDeleteLinkParams = ILinkIdParams;
+export type ITransferLinkParams = ILinkIdParams;
+export type IGetLinkStatsParams = ILinkIdParams;
+export type IGetLinkVisitsParams = ILinkIdParams;
+
+/** Filters of the SHORTENED lists: `search` matches the title, the slug and the target URL. */
+export interface IPaginateLinkQuery extends QueryPaginate {
+  search?: string;
+  isActive?: boolean;
+}
+
+export interface IPaginateProjectLinkParams {
+  projectId: string;
+}
+
+export interface IPaginateOrganizationLinkParams {
+  organizationId: string;
+}
+
+export interface IPaginateOrganizationLinkQuery extends IPaginateLinkQuery {
+  scope?: LinkShareScope;
+  teamId?: string;
+  projectId?: string;
+  /** Honoured only for a member holding ORG_FULL_ACCESS. */
+  adminView?: boolean;
+}
+
+export interface ICountOrganizationLinkParams {
+  organizationId: string;
+}
+
+export interface ICountOrganizationLinkQuery {
+  adminView?: boolean;
+}
+
+/** A SHORTENED link. Without `slug`, a random one is drawn. */
+export interface ICreateLinkBody {
+  targetUrl: string;
+  slug?: string;
+  password?: string;
+  title?: string;
+  description?: string;
+  expiresAt?: Date | string;
+  maxClicks?: number;
+  forwardCampaignParams?: boolean;
+}
+
+export interface ICreateForOrganizationLinkParams {
+  organizationId: string;
+}
+
+/** `projectId` puts the link in a project; `scope: 'USER'` makes it the caller's within the organization. */
+export interface ICreateForOrganizationLinkBody extends ICreateLinkBody {
+  projectId?: string;
+  scope?: 'USER';
+}
+
+/** `password: null` removes the password; `expiresAt: null` and `maxClicks: null` lift the limit. */
+export interface IUpdateLinkBody {
+  targetUrl?: string;
+  slug?: string;
+  password?: string | null;
+  title?: string | null;
+  description?: string | null;
+  isActive?: boolean;
+  expiresAt?: Date | string | null;
+  maxClicks?: number | null;
+  forwardCampaignParams?: boolean;
+}
+
+export interface ITransferLinkBody {
+  newOwnerId: string;
+}
+
+/** Period `[from, to)`, 30 days up to now by default. */
+export interface IGetLinkStatsQuery {
+  from?: Date | string;
+  to?: Date | string;
+  granularity?: LinkStatsGranularity;
+}
+
+export type IGetLinkVisitsQuery = QueryPaginate;
+
+/**
+ * The product resource of a RESOURCE address, flattened in the query string: the product page
+ * finds its address and its statistics, from EDIT on the resource (spec §5).
+ */
+export type IGetByOriginLinkQuery = ILinkOrigin;
+export type IGetStatsByOriginLinkQuery = ILinkOrigin & IGetLinkStatsQuery;

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

@@ -1 +1,4 @@
 export * from './abyss.admin.response';
+export * from './link.response';
+export * from './link.admin.response';
+export * from './link.public.response';