ad2app-lib 1.17.0 → 1.20.0

package/src/types/scheduling/I_SchedulingInbox.ts

@@ -82,6 +82,12 @@ export class SchedulingInboxCommentDTO {
   /** Parent comment id on nested replies (AD2-1088). Absent on top-level comments. */
   parentId?: string;
   replies?: SchedulingInboxCommentDTO[];
+  /**
+   * True when this comment can be moderated (approve/reject/hold) — YouTube only
+   * per Zernio (OpenAPI v1.0.4:22489, `platform` enum = [youtube]). Absent for
+   * every other platform; never fabricated to false-as-if-known (082 US7).
+   */
+  canModerate?: boolean;
 
   constructor(data: SchedulingInboxCommentDTO) {
     this.id = data.id;
@@ -94,6 +100,7 @@ export class SchedulingInboxCommentDTO {
     this.isOwner = data.isOwner;
     this.parentId = data.parentId;
     this.replies = data.replies;
+    this.canModerate = data.canModerate;
   }
 }
 
@@ -128,3 +135,285 @@ export class SchedulingReplyToCommentDTO {
     this.commentId = data.commentId;
   }
 }
+
+// ── 082 Inbox Parity — new inbox surfaces (US1) ───────────────────────────────
+//
+// Shapes below mirror the Zernio OpenAPI v1.0.4 inbox surface (line anchors in
+// each comment); ad2app must NOT invent fields (AD2-1038). Availability is
+// honest-or-absent: an optional field is absent when Zernio does not report it,
+// never zero/false-backfilled.
+
+// ── SchedulingInboxMessageDTO / SchedulingInboxMessagePageDTO ──────────────────
+
+/**
+ * One message inside a DM thread.
+ * Returned (paginated) by GET /social/inbox/messages/:id/thread — backed by
+ * Zernio GET /v1/inbox/conversations/{id}/messages (OpenAPI v1.0.4:20845).
+ */
+export class SchedulingInboxMessageDTO {
+  id: string;
+  conversationId: string;
+  authorId: string;
+  authorName: string;
+  text: string;
+  createdAt: string;
+  /** True when OUR connected account authored this message. */
+  isOwn: boolean;
+  mediaUrl?: string;
+
+  constructor(data: SchedulingInboxMessageDTO) {
+    this.id = data.id;
+    this.conversationId = data.conversationId;
+    this.authorId = data.authorId;
+    this.authorName = data.authorName;
+    this.text = data.text;
+    this.createdAt = data.createdAt;
+    this.isOwn = data.isOwn;
+    this.mediaUrl = data.mediaUrl;
+  }
+}
+
+/**
+ * A cursor page of thread messages — kills the prior 100-message truncation.
+ * `nextCursor` absent = last page.
+ */
+export class SchedulingInboxMessagePageDTO {
+  items: SchedulingInboxMessageDTO[];
+  nextCursor?: string;
+
+  constructor(data: SchedulingInboxMessagePageDTO) {
+    this.items = data.items;
+    this.nextCursor = data.nextCursor;
+  }
+}
+
+// ── SchedulingConversationReadDTO ─────────────────────────────────────────────
+
+/**
+ * Mark-read acknowledgement — POST /social/inbox/messages/:id/read → Zernio
+ * POST /v1/inbox/conversations/{id}/read (OpenAPI v1.0.4:21692). `unreadCount`
+ * absent unless Zernio reports the post-read count.
+ */
+export class SchedulingConversationReadDTO {
+  conversationId: string;
+  unreadCount?: number;
+
+  constructor(data: SchedulingConversationReadDTO) {
+    this.conversationId = data.conversationId;
+    this.unreadCount = data.unreadCount;
+  }
+}
+
+// ── SchedulingInboxMentionDTO / SchedulingReplyToMentionDTO ────────────────────
+
+/**
+ * An inbound mention.
+ * Returned by GET /social/inbox/mentions → Zernio GET /v1/inbox/mentions
+ * (OpenAPI v1.0.4:23108). Source post fields absent when the platform omits them.
+ */
+export class SchedulingInboxMentionDTO {
+  id: string;
+  platform: string;
+  accountId: string;
+  authorName: string;
+  authorAvatarUrl?: string;
+  text: string;
+  createdAt: string;
+  sourcePostId?: string;
+  sourcePostUrl?: string;
+
+  constructor(data: SchedulingInboxMentionDTO) {
+    this.id = data.id;
+    this.platform = data.platform;
+    this.accountId = data.accountId;
+    this.authorName = data.authorName;
+    this.authorAvatarUrl = data.authorAvatarUrl;
+    this.text = data.text;
+    this.createdAt = data.createdAt;
+    this.sourcePostId = data.sourcePostId;
+    this.sourcePostUrl = data.sourcePostUrl;
+  }
+}
+
+/**
+ * Input for replying to a mention. Zernio requires [accountId, mediaId, message]
+ * (OpenAPI v1.0.4:23207) — `mediaId` (the mention's target media) is mandatory,
+ * unlike a DM reply.
+ */
+export class SchedulingReplyToMentionDTO {
+  accountId: string;
+  mediaId: string;
+  message: string;
+
+  constructor(data: SchedulingReplyToMentionDTO) {
+    this.accountId = data.accountId;
+    this.mediaId = data.mediaId;
+    this.message = data.message;
+  }
+}
+
+// ── SchedulingInboxReviewDTO / SchedulingReplyToReviewDTO ──────────────────────
+
+/**
+ * A platform review (e.g. Google Business).
+ * Returned by GET /social/inbox/reviews → Zernio GET /v1/inbox/reviews
+ * (OpenAPI v1.0.4:23269). `replied` absent unless Zernio reports reply state.
+ */
+export class SchedulingInboxReviewDTO {
+  id: string;
+  platform: string;
+  accountId: string;
+  authorName: string;
+  rating: number;
+  text: string;
+  createdAt: string;
+  replied?: boolean;
+
+  constructor(data: SchedulingInboxReviewDTO) {
+    this.id = data.id;
+    this.platform = data.platform;
+    this.accountId = data.accountId;
+    this.authorName = data.authorName;
+    this.rating = data.rating;
+    this.text = data.text;
+    this.createdAt = data.createdAt;
+    this.replied = data.replied;
+  }
+}
+
+/**
+ * Input for replying to a review — POST /social/inbox/reviews/:reviewId/reply →
+ * Zernio POST /v1/inbox/reviews/{reviewId}/reply (OpenAPI v1.0.4:23377).
+ */
+export class SchedulingReplyToReviewDTO {
+  reviewId: string;
+  accountId: string;
+  text: string;
+
+  constructor(data: SchedulingReplyToReviewDTO) {
+    this.reviewId = data.reviewId;
+    this.accountId = data.accountId;
+    this.text = data.text;
+  }
+}
+
+// ── SchedulingCommentModerationDTO ────────────────────────────────────────────
+
+/**
+ * The moderation decision on a comment. Closed set per Zernio
+ * (OpenAPI v1.0.4:22489): `published` approves, `rejected` removes,
+ * `heldForReview` returns it to the queue. YouTube only. `banAuthor` is valid
+ * ONLY with `rejected` (any other pairing is a 400 — enforced server-side).
+ */
+export type SchedulingCommentModerationStatus = 'published' | 'rejected' | 'heldForReview';
+
+export class SchedulingCommentModerationDTO {
+  moderationStatus: SchedulingCommentModerationStatus;
+  banAuthor?: boolean;
+
+  constructor(data: SchedulingCommentModerationDTO) {
+    this.moderationStatus = data.moderationStatus;
+    this.banAuthor = data.banAuthor;
+  }
+}
+
+// ── SchedulingCreateConversationDTO ───────────────────────────────────────────
+
+/**
+ * Input for starting a new DM — POST /social/inbox/conversations → Zernio
+ * POST /v1/inbox/conversations (OpenAPI v1.0.4:20355). WhatsApp is excluded
+ * (it requires an approved template to open a thread; 082 non-goal).
+ */
+export class SchedulingCreateConversationDTO {
+  accountId: string;
+  recipientId: string;
+  text: string;
+
+  constructor(data: SchedulingCreateConversationDTO) {
+    this.accountId = data.accountId;
+    this.recipientId = data.recipientId;
+    this.text = data.text;
+  }
+}
+
+// ── SchedulingInboxCapabilityDTO ──────────────────────────────────────────────
+
+/**
+ * Per-connected-account inbox capability truth — which surfaces a platform
+ * actually supports. Drives honest showing/hiding (082 FR-4): a false/absent
+ * surface is HIDDEN, never rendered as a fabricated empty. Reconciled from
+ * platform-capabilities + Zernio /accounts/health.
+ */
+export class SchedulingInboxCapabilityDTO {
+  platform: string;
+  dm: boolean;
+  comments: boolean;
+  mentions: boolean;
+  reviews: boolean;
+  /** Can INITIATE a DM (not just reply). */
+  dmInit: boolean;
+  /** Comment moderation queue (YouTube). */
+  moderation: boolean;
+
+  constructor(data: SchedulingInboxCapabilityDTO) {
+    this.platform = data.platform;
+    this.dm = data.dm;
+    this.comments = data.comments;
+    this.mentions = data.mentions;
+    this.reviews = data.reviews;
+    this.dmInit = data.dmInit;
+    this.moderation = data.moderation;
+  }
+}
+
+// ── SchedulingCrossPostCommentDTO ─────────────────────────────────────────────
+
+/**
+ * A comment re-sourced from Zernio's cross-post inbox (GET /v1/inbox/comments),
+ * carrying its OWN post attribution so it surfaces even when the post is absent
+ * from our local SocialPostCache. The cache is enrichment ONLY (post snippet /
+ * thumbnail), never the source of truth (082 US3 / AD2-1110): a comment on an
+ * uncached post must still reach the moderator. Comment/engagement fields mirror
+ * SchedulingInboxCommentDTO; enrichment fields are honest-or-absent — filled from
+ * the cache when present, never zero/empty-backfilled.
+ */
+export class SchedulingCrossPostCommentDTO {
+  // Comment identity + content (mirrors SchedulingInboxCommentDTO).
+  id: string;
+  authorName: string;
+  authorAvatarUrl?: string;
+  text: string;
+  createdAt: string;
+  likeCount?: number;
+  replyCount?: number;
+  isOwner?: boolean;
+  parentId?: string;
+  canModerate?: boolean;
+  replies?: SchedulingCrossPostCommentDTO[];
+  // Post attribution — from the cross-post payload, NOT the cache (the whole point of US3).
+  postId: string;
+  platform: string;
+  accountId: string;
+  // Enrichment — from SocialPostCache WHEN present, absent otherwise (never backfilled).
+  postContentSnippet?: string;
+  postThumbnailUrl?: string;
+
+  constructor(data: SchedulingCrossPostCommentDTO) {
+    this.id = data.id;
+    this.authorName = data.authorName;
+    this.authorAvatarUrl = data.authorAvatarUrl;
+    this.text = data.text;
+    this.createdAt = data.createdAt;
+    this.likeCount = data.likeCount;
+    this.replyCount = data.replyCount;
+    this.isOwner = data.isOwner;
+    this.parentId = data.parentId;
+    this.canModerate = data.canModerate;
+    this.replies = data.replies;
+    this.postId = data.postId;
+    this.platform = data.platform;
+    this.accountId = data.accountId;
+    this.postContentSnippet = data.postContentSnippet;
+    this.postThumbnailUrl = data.postThumbnailUrl;
+  }
+}

package/src/types/scheduling/I_SchedulingPost.test.ts

@@ -102,3 +102,27 @@ test('SchedulingPostStatus gains PUBLISHING (AD2-1153 publish resilience)', () =
   const post = basePost({ status: SchedulingPostStatus.PUBLISHING });
   assert.equal(post.status, 'publishing');
 });
+
+// AD2-1154 FR-2 — the backend's local PlatformStatusMap already has an
+// 'unknown' member (a platform Zernio attempted but couldn't yet confirm
+// either way — Paweł's Facebook incident); this pins the lib side so the
+// backend's `platformStatuses: (...) as unknown as SchedulingPostDTO['platformStatuses']`
+// cast in post-response.dto.ts can eventually be replaced by a direct import.
+test("SchedulingPlatformStatusMap gains 'unknown' (AD2-1154 FR-2 honest reconcile state)", () => {
+  const post = basePost({ platformStatuses: { instagram: 'published', facebook: 'unknown' } });
+  assert.equal(post.platformStatuses.facebook, 'unknown');
+});
+
+// AD2-1154 FR-3a — the backend's local platform_retry_counts column already
+// tracks per-platform attempts (a permanently-failing platform must never
+// loop forever); this pins the lib side so the field can be exposed on the
+// DTO without a cast once the backend swaps to it.
+test('SchedulingPostDTO gains platformRetryCounts (AD2-1154 FR-3a terminal-retry tracking)', () => {
+  const post = basePost({ platformRetryCounts: { tiktok: 3 } });
+  assert.equal(post.platformRetryCounts.tiktok, 3);
+});
+
+test('SchedulingPostDTO platformRetryCounts is absent by default (backward compatible)', () => {
+  const post = basePost();
+  assert.equal(post.platformRetryCounts, undefined);
+});

package/src/types/scheduling/I_SchedulingPost.ts

@@ -27,7 +27,12 @@ export enum SchedulingPostStatus {
 
 export type SchedulingPlatformStatusMap = Record<
   string,
-  'scheduled' | 'published' | 'failed'
+  // 'unknown': the publisher attempted this platform but its outcome isn't
+  // confirmable yet (e.g. Zernio 'pending'/'publishing') — distinct from
+  // 'scheduled' (not yet attempted at all). Must never render as a success
+  // or a failure (AD2-1154 FR-2, Paweł's incident: his Facebook post was
+  // neither confirmed nor failed).
+  'scheduled' | 'published' | 'failed' | 'unknown'
 >;
 
 // ── SchedulingPlatformTargetDTO ───────────────────────────────────────────────
@@ -163,6 +168,12 @@ export class SchedulingPostDTO {
   postUrls?: Record<string, string>;
   /** Per-platform error messages for platforms that failed to publish. */
   platformErrors?: Record<string, string>;
+  /**
+   * Per-platform retry-attempt counts (AD2-1154 FR-3a). A platform that has
+   * used its 3rd attempt and is still failed is terminal — the retry
+   * affordance withdraws and the last real error is shown as permanent.
+   */
+  platformRetryCounts?: Record<string, number>;
   scheduledAt?: string;
   publishedAt?: string;
   status: SchedulingPostStatus;
@@ -196,6 +207,7 @@ export class SchedulingPostDTO {
     this.platformStatuses = data.platformStatuses;
     this.postUrls = data.postUrls;
     this.platformErrors = data.platformErrors;
+    this.platformRetryCounts = data.platformRetryCounts;
     this.scheduledAt = data.scheduledAt;
     this.publishedAt = data.publishedAt;
     this.status = data.status;