instagram-private-api 响应模型解析：NewsRepositoryInboxResponseCounts 通知未读计数接口详解

• 后端

本篇技术指南围绕 instagram-private-api（NodeJS Instagram 私有 API SDK，TypeScript 编写）中的NewsRepositoryInboxResponseCounts接口展开。该接口承载 Instagram 通知中心（News Inbox）中各类未读事件的计数统计，是解析client.news.inbox()返回值时必须理解的核心数据结构。读完本文，你将掌握这 8 个可选计数字段各自的业务含义、它们在响应体中的嵌套位置、对应的底层请求调用链，以及如何在实际代码中安全地消费这些可能缺失的字段。

接口在响应模型中的定位

NewsRepositoryInboxResponseCounts并非孤立存在，它被复用于三处，均由 src/responses/news.repository.inbox.response.ts 导出：

• 根对象级未读汇总：作为NewsRepositoryInboxResponseRootObject.counts字段的类型（源码第 3 行），表示整个通知中心当前的未读事件总览；
• 每条新通知的计数：作为NewsRepositoryInboxResponseNewStoriesItem.counts字段的类型（源码第 58 行），描述单条"新通知"条目携带的计数信息；
• 每条旧通知的计数：作为NewsRepositoryInboxResponseOldStoriesItem.counts字段的类型（源码第 102 行），描述已读/历史通知条目中的计数信息。

接口定义位于 src/responses/news.repository.inbox.response.ts#L44-L53，完整声明如下：

export interface NewsRepositoryInboxResponseCounts { relationships?: number; usertags?: number; likes?: number; comments?: number; campaign_notification?: number; comment_likes?: number; photos_of_you?: number; requests?: number; }

8 个可选字段的完整语义

原文档列出该接口共 8 个属性，全部为Optional（可选）的number类型，即 Instagram 服务端可能省略其中任意一个或多个字段。各字段含义如下：

从字段组合可以推断，Instagram 将通知中心的活动按业务类型分桶统计：关系维护（relationships、requests）、内容互动（likes、comments、comment_likes）、用户提及（usertags、photos_of_you）以及平台推广（campaign_notification）。开发者可以利用这些字段快速构建"未读通知数"的角标展示，无需逐条遍历通知列表。

底层调用链：inbox() 如何返回这些计数

该接口经由 NewsRepository.inbox() 方法获取，其实现对应当前仓库源码：

import { Repository } from '../core/repository'; import { NewsRepositoryInboxResponseRootObject } from '../responses'; export class NewsRepository extends Repository { public async inbox(): Promise<NewsRepositoryInboxResponseRootObject> { const { body } = await this.client.request.send<NewsRepositoryInboxResponseRootObject>({ url: '/api/v1/news/inbox', method: 'GET', }); return body; } }

调用链说明：

1. NewsRepository继承自 src/core/repository.ts 中的Repository基类，构造函数接收IgApiClient实例；
2. inbox()通过client.request.send()向 Instagram 私有端点的/api/v1/news/inbox发送GET请求；
3. 响应体被泛型断言为NewsRepositoryInboxResponseRootObject，其中的counts字段即NewsRepositoryInboxResponseCounts；
4. NewsRepository已注册在客户端入口 src/core/client.ts#L33 与 src/core/client.ts#L72，因此实际使用时通过ig.news.inbox()直接调用。

import { IgApiClient } from 'instagram-private-api'; const ig = new IgApiClient(); ig.state.generateDevice('your_username'); await ig.account.login('your_username', 'your_password'); const inbox = await ig.news.inbox(); // 读取根对象级的未读计数 if (inbox.counts) { console.log('未读点赞:', inbox.counts.likes); console.log('未读评论:', inbox.counts.comments); console.log('未读关注请求:', inbox.counts.requests); }

实战要点：安全消费可选字段

由于NewsRepositoryInboxResponseCounts的全部字段均为可选，在编写业务代码时应注意：

• 判空保护：inbox.counts本身也可能缺失（见NewsRepositoryInboxResponseRootObject源码，counts为必填字段但内容可空），读取单个字段前建议先确认对象存在；
• 数值默认值：对likes、comments等字段，建议在展示层用?? 0兜底，避免渲染undefined；
• 聚合未读总数：可将存在且大于 0 的字段求和，作为"通知中心总未读数"角标，但需注意campaign_notification是否应计入，取决于产品需求；
• 结合通知列表交叉验证：根对象同时返回new_stories与old_stories数组，数组中的每条条目也带有各自独立的counts字段（类型同为NewsRepositoryInboxResponseCounts），可用于逐条展示"该通知相关事件的互动次数"。

对比观察：NewsFeed 响应中的空计数接口

值得注意的源码细节是：新闻动态流（News Feed）的响应模型NewsFeedResponseCounts被定义为空接口：

// src/responses/news.feed.response.ts:41 export interface NewsFeedResponseCounts {}

该接口是 NewsFeedResponseStoriesItem 的counts字段类型，经由 NewsFeed 分页请求/api/v1/news获得。对比可见：

• 旧版/api/v1/news（对应NewsFeed，走max_id分页）未解析出具体计数结构，故为空接口；
• 新版/api/v1/news/inbox（对应NewsRepository.inbox()，返回continuation_token续传标记）解析出了完整的 8 字段计数结构。

这种差异属于仓库对真实接口响应的忠实建模：NewsRepositoryInboxResponseCounts明确声明了字段与可空性，而NewsFeedResponseCounts保持空结构，反映了 Instagram 两套通知接口数据形态的演进。从源码结构看，inbox()更适合需要精确未读计数的场景，而NewsFeed更偏向流式浏览通知列表（通过isMoreAvailable()与items()迭代，见 docs/classes/feeds/NewsFeed.md）。

小结

NewsRepositoryInboxResponseCounts是理解 instagram-private-api 通知模块数据模型的关键一环。它把 Instagram 通知中心的未读事件归纳为 8 类计数，全部可选、全部为数值，配合 NewsRepository.inbox() 使用即可快速获取未读角标数据。若需深入查看接口在整体响应中的位置，可进一步阅读 NewsRepositoryInboxResponseRootObject 与其兄弟接口（如 NewsRepositoryInboxResponseNewStoriesItem、NewsRepositoryInboxResponseOldStoriesItem），响应模型的完整入口见 docs/modules/responses.md。

• 后端