ad2app-lib 1.0.11 → 1.2.0

package/README.md

@@ -1,37 +1,89 @@
-# ad2app library
+# ad2app-lib
 
-General use package for ad2app related projects.
-In here, you will find types and utils. Updating was never that easy.
+Shared TypeScript package used across all ad2app projects. Provides types, utilities, and API driver configuration.
 
-## First steps
+---
 
-To begin, install all dependencies and build the project.
+## Table of Contents
+
+- [Overview](#overview)
+- [Tech Stack](#tech-stack)
+- [Project Structure](#project-structure)
+- [Getting Started](#getting-started)
+- [Usage](#usage)
+
+---
+
+## Overview
+
+`ad2app-lib` is a local npm package linked via `npm link`. It is not published to the npm registry. Changes propagate instantly to all linked projects after `npm run build`.
+
+| Export | Description |
+|---|---|
+| `ad2app-lib/types` | Shared TypeScript interfaces and enums (User, Campaign, Offer, etc.) |
+| `ad2app-lib/utils` | Shared utility functions |
+| `ad2app-lib/api` | `configureApiDriver` — sets up the shared HTTP client |
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Language | TypeScript 5.8 |
+| Build | `tsc` (CommonJS output + `.d.ts` declarations) |
+| Validation | class-validator 0.14 |
+| Date handling | date-fns 3.5 + date-fns-tz |
+
+---
+
+## Project Structure
 
 ```
-npm install
-npm run build
+src/
+├── types/     # Shared interfaces and enums (User, Campaign, Offer, I_Item, etc.)
+├── utils/     # Shared utility functions
+└── api/       # configureApiDriver — HTTP client setup
+dist/          # Compiled output (generated by npm run build)
 ```
 
-## Propagating library
+---
 
-To be able to use ad2app-link in other npm projects, you must first link this project to your local npm repository
+## Getting Started
 
-```
+### Build and link
+
+```bash
+npm install
+npm run build
 npm link
 ```
 
-Then, you should be good to go to link this project to any other project. e.g. for frontend:
+### Link to a consumer project
 
-```
+```bash
+# In any ad2app project (backend, frontend, mobile-v2, etc.)
 npm link ad2app-lib
 ```
 
-## Propagating changes
+> **Note:** The backend runs `npm link ad2app-lib` automatically via `postinstall`. Other projects must run it manually.
+
+---
 
-Whenever you have to update your package, simply run
+## Usage
 
+```typescript
+import { UserRoles, I_Item } from 'ad2app-lib/types';
+import { configureApiDriver } from 'ad2app-lib/api';
+import { someUtil } from 'ad2app-lib/utils';
 ```
+
+### Propagating changes
+
+After editing source files, rebuild:
+
+```bash
 npm run build
 ```
 
-Thanks to the npm linkage, this will cause automatic propagation to all the other packages.
+All linked projects pick up the changes immediately — no re-linking needed.

package/dist/types/I_PlatformStatistics.d.ts

@@ -0,0 +1,65 @@
+import { SocialProvider } from "./I_SocialAccount";
+export declare class I_TikTokUserStatisticsDTO {
+    follower_count: number;
+    following_count: number;
+    likes_count: number;
+    video_count: number;
+    is_verified: boolean;
+    constructor(data?: Partial<I_TikTokUserStatisticsDTO>);
+}
+export declare class I_TikTokVideoStatisticsDTO {
+    video_id: string;
+    title: string;
+    share_url: string;
+    view_count: number;
+    like_count: number;
+    comment_count: number;
+    share_count: number;
+    create_time: number;
+    constructor(data?: Partial<I_TikTokVideoStatisticsDTO>);
+}
+export declare class I_TikTokStatisticsResponseDTO {
+    user: I_TikTokUserStatisticsDTO;
+    videos: I_TikTokVideoStatisticsDTO[];
+    fetched_at: Date;
+    constructor(data?: Partial<I_TikTokStatisticsResponseDTO>);
+}
+export declare class I_YouTubeChannelStatisticsDTO {
+    subscriber_count: number;
+    total_view_count: number;
+    video_count: number;
+    channel_title: string;
+    channel_url: string;
+    constructor(data?: Partial<I_YouTubeChannelStatisticsDTO>);
+}
+export declare class I_YouTubeStatisticsResponseDTO {
+    channel: I_YouTubeChannelStatisticsDTO;
+    fetched_at: Date;
+    constructor(data?: Partial<I_YouTubeStatisticsResponseDTO>);
+}
+export declare class I_InstagramUserStatisticsDTO {
+    username: string;
+    media_count: number;
+    account_type: string;
+    constructor(data?: Partial<I_InstagramUserStatisticsDTO>);
+}
+export declare class I_InstagramMediaStatisticsDTO {
+    media_id: string;
+    caption: string;
+    media_type: string;
+    permalink: string;
+    like_count: number;
+    comments_count: number;
+    timestamp: string;
+    constructor(data?: Partial<I_InstagramMediaStatisticsDTO>);
+}
+export declare class I_InstagramStatisticsResponseDTO {
+    user: I_InstagramUserStatisticsDTO;
+    media: I_InstagramMediaStatisticsDTO[];
+    fetched_at: Date;
+    constructor(data?: Partial<I_InstagramStatisticsResponseDTO>);
+}
+export declare class I_ConnectedPlatformsDTO {
+    platforms: SocialProvider[];
+    constructor(data?: Partial<I_ConnectedPlatformsDTO>);
+}

package/dist/types/I_PlatformStatistics.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I_ConnectedPlatformsDTO = exports.I_InstagramStatisticsResponseDTO = exports.I_InstagramMediaStatisticsDTO = exports.I_InstagramUserStatisticsDTO = exports.I_YouTubeStatisticsResponseDTO = exports.I_YouTubeChannelStatisticsDTO = exports.I_TikTokStatisticsResponseDTO = exports.I_TikTokVideoStatisticsDTO = exports.I_TikTokUserStatisticsDTO = void 0;
+class I_TikTokUserStatisticsDTO {
+    constructor(data) {
+        this.follower_count = data?.follower_count ?? 0;
+        this.following_count = data?.following_count ?? 0;
+        this.likes_count = data?.likes_count ?? 0;
+        this.video_count = data?.video_count ?? 0;
+        this.is_verified = data?.is_verified ?? false;
+    }
+}
+exports.I_TikTokUserStatisticsDTO = I_TikTokUserStatisticsDTO;
+class I_TikTokVideoStatisticsDTO {
+    constructor(data) {
+        this.video_id = data?.video_id ?? "";
+        this.title = data?.title ?? "";
+        this.share_url = data?.share_url ?? "";
+        this.view_count = data?.view_count ?? 0;
+        this.like_count = data?.like_count ?? 0;
+        this.comment_count = data?.comment_count ?? 0;
+        this.share_count = data?.share_count ?? 0;
+        this.create_time = data?.create_time ?? 0;
+    }
+}
+exports.I_TikTokVideoStatisticsDTO = I_TikTokVideoStatisticsDTO;
+class I_TikTokStatisticsResponseDTO {
+    constructor(data) {
+        this.user = data?.user ?? new I_TikTokUserStatisticsDTO();
+        this.videos = data?.videos ?? [];
+        this.fetched_at = data?.fetched_at ?? new Date();
+    }
+}
+exports.I_TikTokStatisticsResponseDTO = I_TikTokStatisticsResponseDTO;
+class I_YouTubeChannelStatisticsDTO {
+    constructor(data) {
+        this.subscriber_count = data?.subscriber_count ?? 0;
+        this.total_view_count = data?.total_view_count ?? 0;
+        this.video_count = data?.video_count ?? 0;
+        this.channel_title = data?.channel_title ?? "";
+        this.channel_url = data?.channel_url ?? "";
+    }
+}
+exports.I_YouTubeChannelStatisticsDTO = I_YouTubeChannelStatisticsDTO;
+class I_YouTubeStatisticsResponseDTO {
+    constructor(data) {
+        this.channel = data?.channel ?? new I_YouTubeChannelStatisticsDTO();
+        this.fetched_at = data?.fetched_at ?? new Date();
+    }
+}
+exports.I_YouTubeStatisticsResponseDTO = I_YouTubeStatisticsResponseDTO;
+class I_InstagramUserStatisticsDTO {
+    constructor(data) {
+        this.username = data?.username ?? "";
+        this.media_count = data?.media_count ?? 0;
+        this.account_type = data?.account_type ?? "";
+    }
+}
+exports.I_InstagramUserStatisticsDTO = I_InstagramUserStatisticsDTO;
+class I_InstagramMediaStatisticsDTO {
+    constructor(data) {
+        this.media_id = data?.media_id ?? "";
+        this.caption = data?.caption ?? "";
+        this.media_type = data?.media_type ?? "";
+        this.permalink = data?.permalink ?? "";
+        this.like_count = data?.like_count ?? 0;
+        this.comments_count = data?.comments_count ?? 0;
+        this.timestamp = data?.timestamp ?? "";
+    }
+}
+exports.I_InstagramMediaStatisticsDTO = I_InstagramMediaStatisticsDTO;
+class I_InstagramStatisticsResponseDTO {
+    constructor(data) {
+        this.user = data?.user ?? new I_InstagramUserStatisticsDTO();
+        this.media = data?.media ?? [];
+        this.fetched_at = data?.fetched_at ?? new Date();
+    }
+}
+exports.I_InstagramStatisticsResponseDTO = I_InstagramStatisticsResponseDTO;
+class I_ConnectedPlatformsDTO {
+    constructor(data) {
+        this.platforms = data?.platforms ?? [];
+    }
+}
+exports.I_ConnectedPlatformsDTO = I_ConnectedPlatformsDTO;

package/dist/types/I_User.d.ts

@@ -3,7 +3,6 @@ export declare class I_User {
     id: string;
     email?: string;
     password?: string;
-    contact_email?: string;
     first_name?: string;
     last_name?: string;
     display_name?: string;
@@ -22,7 +21,6 @@ export declare enum UserRoles {
 export declare class I_UserCreateDTO {
     password: string;
     email: string;
-    contact_email: string;
     first_name: string;
     last_name: string;
     display_name: string;
@@ -34,7 +32,6 @@ export declare class I_UserSignInDTO {
 export declare class I_UserSignUpDTO {
     email: string;
     password: string;
-    contact_email: string;
     first_name: string;
     last_name: string;
     display_name: string;

package/dist/types/I_User.js

@@ -34,10 +34,6 @@ __decorate([
     (0, class_validator_1.IsNotEmpty)(),
     __metadata("design:type", String)
 ], I_UserCreateDTO.prototype, "email", void 0);
-__decorate([
-    (0, class_validator_1.IsNotEmpty)(),
-    __metadata("design:type", String)
-], I_UserCreateDTO.prototype, "contact_email", void 0);
 __decorate([
     (0, class_validator_1.IsNotEmpty)(),
     __metadata("design:type", String)
@@ -72,10 +68,6 @@ __decorate([
     (0, class_validator_1.IsNotEmpty)(),
     __metadata("design:type", String)
 ], I_UserSignUpDTO.prototype, "password", void 0);
-__decorate([
-    (0, class_validator_1.IsNotEmpty)(),
-    __metadata("design:type", String)
-], I_UserSignUpDTO.prototype, "contact_email", void 0);
 __decorate([
     (0, class_validator_1.IsNotEmpty)(),
     __metadata("design:type", String)

package/dist/types/index.d.ts

@@ -33,3 +33,5 @@ export * from "./I_Media";
 export * from "./I_SocialAccount";
 export * from "./I_Collaboration";
 export * from "./I_Publish";
+export * from "./I_SM_Platform";
+export * from "./scheduling";

package/dist/types/index.js

@@ -49,3 +49,6 @@ __exportStar(require("./I_Media"), exports);
 __exportStar(require("./I_SocialAccount"), exports);
 __exportStar(require("./I_Collaboration"), exports);
 __exportStar(require("./I_Publish"), exports);
+__exportStar(require("./I_SM_Platform"), exports);
+// ── Scheduling domain ─────────────────────────────────────────────────────────
+__exportStar(require("./scheduling"), exports);

package/dist/types/scheduling/I_SchedulingAnalytics.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Scheduling domain — Analytics DTOs
+ *
+ * Covers KPI summaries, daily engagement entries, best-time-to-post slots,
+ * per-post timeline snapshots, content decay windows, and follower stats.
+ */
+/**
+ * Aggregated KPI figures for the selected date range.
+ * Returned by GET /social/analytics.
+ */
+export declare class SchedulingAnalyticsKpiDTO {
+    impressions: number;
+    reach: number;
+    engagementRate: number;
+    followerGrowth: number;
+    constructor(data: SchedulingAnalyticsKpiDTO);
+}
+/**
+ * A single day/platform analytics row.
+ * Returned by GET /social/analytics/daily.
+ */
+export declare class SchedulingAnalyticsEntryDTO {
+    platform: string;
+    date: string;
+    impressions: number;
+    reach: number;
+    views: number;
+    likes: number;
+    comments: number;
+    shares: number;
+    saves: number;
+    clicks: number;
+    engagements: number;
+    constructor(data: SchedulingAnalyticsEntryDTO);
+}
+/** Query parameters shared by all analytics endpoints. */
+export declare class SchedulingAnalyticsParamsDTO {
+    fromDate?: string;
+    toDate?: string;
+    platform?: string;
+    constructor(data: SchedulingAnalyticsParamsDTO);
+}
+/**
+ * A single day+hour slot with average engagement data.
+ * Returned by GET /social/analytics/best-time.
+ */
+export declare class SchedulingBestTimeSlotDTO {
+    /** 0 = Sunday … 6 = Saturday */
+    day: number;
+    /** 0 – 23 */
+    hour: number;
+    avgEngagements: number;
+    avgImpressions: number;
+    constructor(data: SchedulingBestTimeSlotDTO);
+}
+/**
+ * One snapshot in a per-post timeline series.
+ * Returned by GET /social/analytics/post-timeline.
+ */
+export declare class SchedulingPostTimelineEntryDTO {
+    date: string;
+    platform: string;
+    impressions: number;
+    likes: number;
+    comments: number;
+    shares: number;
+    saves: number;
+    clicks: number;
+    constructor(data: SchedulingPostTimelineEntryDTO);
+}
+/**
+ * Engagement decay percentage at a specific time window after publishing.
+ * Returned by GET /social/analytics/content-decay.
+ */
+export declare class SchedulingContentDecayDTO {
+    window: '1h' | '6h' | '24h' | '7d';
+    platform: string;
+    /** Percentage of peak engagement remaining at this window */
+    pct: number;
+    constructor(data: SchedulingContentDecayDTO);
+}
+/**
+ * Follower count and growth for one platform on one date.
+ * Returned by GET /social/analytics/follower-stats.
+ */
+export declare class SchedulingFollowerStatDTO {
+    platform: string;
+    date: string;
+    followers: number;
+    followersGrowth: number;
+    constructor(data: SchedulingFollowerStatDTO);
+}

package/dist/types/scheduling/I_SchedulingAnalytics.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Scheduling domain — Analytics DTOs
+ *
+ * Covers KPI summaries, daily engagement entries, best-time-to-post slots,
+ * per-post timeline snapshots, content decay windows, and follower stats.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchedulingFollowerStatDTO = exports.SchedulingContentDecayDTO = exports.SchedulingPostTimelineEntryDTO = exports.SchedulingBestTimeSlotDTO = exports.SchedulingAnalyticsParamsDTO = exports.SchedulingAnalyticsEntryDTO = exports.SchedulingAnalyticsKpiDTO = void 0;
+// ── SchedulingAnalyticsKpiDTO ─────────────────────────────────────────────────
+/**
+ * Aggregated KPI figures for the selected date range.
+ * Returned by GET /social/analytics.
+ */
+class SchedulingAnalyticsKpiDTO {
+    constructor(data) {
+        this.impressions = data.impressions;
+        this.reach = data.reach;
+        this.engagementRate = data.engagementRate;
+        this.followerGrowth = data.followerGrowth;
+    }
+}
+exports.SchedulingAnalyticsKpiDTO = SchedulingAnalyticsKpiDTO;
+// ── SchedulingAnalyticsEntryDTO ───────────────────────────────────────────────
+/**
+ * A single day/platform analytics row.
+ * Returned by GET /social/analytics/daily.
+ */
+class SchedulingAnalyticsEntryDTO {
+    constructor(data) {
+        this.platform = data.platform;
+        this.date = data.date;
+        this.impressions = data.impressions;
+        this.reach = data.reach;
+        this.views = data.views;
+        this.likes = data.likes;
+        this.comments = data.comments;
+        this.shares = data.shares;
+        this.saves = data.saves;
+        this.clicks = data.clicks;
+        this.engagements = data.engagements;
+    }
+}
+exports.SchedulingAnalyticsEntryDTO = SchedulingAnalyticsEntryDTO;
+// ── SchedulingAnalyticsParamsDTO ──────────────────────────────────────────────
+/** Query parameters shared by all analytics endpoints. */
+class SchedulingAnalyticsParamsDTO {
+    constructor(data) {
+        this.fromDate = data.fromDate;
+        this.toDate = data.toDate;
+        this.platform = data.platform;
+    }
+}
+exports.SchedulingAnalyticsParamsDTO = SchedulingAnalyticsParamsDTO;
+// ── SchedulingBestTimeSlotDTO ─────────────────────────────────────────────────
+/**
+ * A single day+hour slot with average engagement data.
+ * Returned by GET /social/analytics/best-time.
+ */
+class SchedulingBestTimeSlotDTO {
+    constructor(data) {
+        this.day = data.day;
+        this.hour = data.hour;
+        this.avgEngagements = data.avgEngagements;
+        this.avgImpressions = data.avgImpressions;
+    }
+}
+exports.SchedulingBestTimeSlotDTO = SchedulingBestTimeSlotDTO;
+// ── SchedulingPostTimelineEntryDTO ────────────────────────────────────────────
+/**
+ * One snapshot in a per-post timeline series.
+ * Returned by GET /social/analytics/post-timeline.
+ */
+class SchedulingPostTimelineEntryDTO {
+    constructor(data) {
+        this.date = data.date;
+        this.platform = data.platform;
+        this.impressions = data.impressions;
+        this.likes = data.likes;
+        this.comments = data.comments;
+        this.shares = data.shares;
+        this.saves = data.saves;
+        this.clicks = data.clicks;
+    }
+}
+exports.SchedulingPostTimelineEntryDTO = SchedulingPostTimelineEntryDTO;
+// ── SchedulingContentDecayDTO ─────────────────────────────────────────────────
+/**
+ * Engagement decay percentage at a specific time window after publishing.
+ * Returned by GET /social/analytics/content-decay.
+ */
+class SchedulingContentDecayDTO {
+    constructor(data) {
+        this.window = data.window;
+        this.platform = data.platform;
+        this.pct = data.pct;
+    }
+}
+exports.SchedulingContentDecayDTO = SchedulingContentDecayDTO;
+// ── SchedulingFollowerStatDTO ─────────────────────────────────────────────────
+/**
+ * Follower count and growth for one platform on one date.
+ * Returned by GET /social/analytics/follower-stats.
+ */
+class SchedulingFollowerStatDTO {
+    constructor(data) {
+        this.platform = data.platform;
+        this.date = data.date;
+        this.followers = data.followers;
+        this.followersGrowth = data.followersGrowth;
+    }
+}
+exports.SchedulingFollowerStatDTO = SchedulingFollowerStatDTO;

package/dist/types/scheduling/I_SchedulingConnectedAccount.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Scheduling domain — Connected Account DTOs
+ *
+ * Represents a social-media account that a user has connected via OAuth
+ * through the Late API integration layer.
+ */
+/**
+ * Response DTO for a single connected social account.
+ * Returned in list form by GET /social/accounts.
+ */
+export declare class SchedulingConnectedAccountDTO {
+    /** Internal (Late) account identifier */
+    id: string;
+    platform: string;
+    username: string;
+    display_name?: string;
+    avatar_url?: string;
+    constructor(data: SchedulingConnectedAccountDTO);
+}
+/**
+ * Response DTO returned after initiating an OAuth account connection.
+ * The client should redirect the user to the returned URL.
+ */
+export declare class SchedulingConnectAccountResultDTO {
+    /** OAuth redirect URL the client must navigate to */
+    url: string;
+    platform: string;
+    constructor(data: SchedulingConnectAccountResultDTO);
+}
+/**
+ * A Pinterest board that the connected account has access to.
+ * Returned by GET /social/accounts/pinterest-boards.
+ */
+export declare class SchedulingPinterestBoardDTO {
+    id: string;
+    name: string;
+    constructor(data: SchedulingPinterestBoardDTO);
+}
+/**
+ * Latest follower count for a single platform.
+ * Returned by GET /social/accounts/follower-stats.
+ */
+export declare class SchedulingAccountFollowerStatDTO {
+    platform: string;
+    followers: number;
+    date: string;
+    constructor(data: SchedulingAccountFollowerStatDTO);
+}

package/dist/types/scheduling/I_SchedulingConnectedAccount.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Scheduling domain — Connected Account DTOs
+ *
+ * Represents a social-media account that a user has connected via OAuth
+ * through the Late API integration layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchedulingAccountFollowerStatDTO = exports.SchedulingPinterestBoardDTO = exports.SchedulingConnectAccountResultDTO = exports.SchedulingConnectedAccountDTO = void 0;
+// ── SchedulingConnectedAccountDTO ────────────────────────────────────────────
+/**
+ * Response DTO for a single connected social account.
+ * Returned in list form by GET /social/accounts.
+ */
+class SchedulingConnectedAccountDTO {
+    constructor(data) {
+        this.id = data.id;
+        this.platform = data.platform;
+        this.username = data.username;
+        this.display_name = data.display_name;
+        this.avatar_url = data.avatar_url;
+    }
+}
+exports.SchedulingConnectedAccountDTO = SchedulingConnectedAccountDTO;
+// ── SchedulingConnectAccountResultDTO ────────────────────────────────────────
+/**
+ * Response DTO returned after initiating an OAuth account connection.
+ * The client should redirect the user to the returned URL.
+ */
+class SchedulingConnectAccountResultDTO {
+    constructor(data) {
+        this.url = data.url;
+        this.platform = data.platform;
+    }
+}
+exports.SchedulingConnectAccountResultDTO = SchedulingConnectAccountResultDTO;
+// ── SchedulingPinterestBoardDTO ───────────────────────────────────────────────
+/**
+ * A Pinterest board that the connected account has access to.
+ * Returned by GET /social/accounts/pinterest-boards.
+ */
+class SchedulingPinterestBoardDTO {
+    constructor(data) {
+        this.id = data.id;
+        this.name = data.name;
+    }
+}
+exports.SchedulingPinterestBoardDTO = SchedulingPinterestBoardDTO;
+// ── SchedulingAccountFollowerStatDTO ─────────────────────────────────────────
+/**
+ * Latest follower count for a single platform.
+ * Returned by GET /social/accounts/follower-stats.
+ */
+class SchedulingAccountFollowerStatDTO {
+    constructor(data) {
+        this.platform = data.platform;
+        this.followers = data.followers;
+        this.date = data.date;
+    }
+}
+exports.SchedulingAccountFollowerStatDTO = SchedulingAccountFollowerStatDTO;