@geoly-ai/social-hub-core 0.0.4 → 0.0.6

package/dist/activity.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 互动时序去同质化(需求 v5)的 Hub 侧纯函数层:
+ * canonical event payload 校验、civil-time 归日、recentActivitySummary 聚合、
+ * effectiveTimezone 计算。全部无 IO,便于 §11.4 fixture 逐条验收。
+ *
+ * 口径来源:openclaw-template docs/reddit-interaction-timing-hub-requirements-2026-07.md
+ * §4.3 + 实现方裁决(飞书评论 7662423677899656150):
+ * - occurredAt(带 offset 绝对时刻)为权威,eventTimezone 仅用于归日;
+ * - 三元组去重=整条 event 去重;
+ * - 历史无 eventTimezone 且当前时区 unknown → 不做逐日归属。
+ */
+export declare const CANONICAL_EVENT_SCHEMA_VERSION = 1;
+/** 需求A:canonical v2 —— 允许 eventTimezone null + timezoneKnown。v1 语义不变。 */
+export declare const CANONICAL_EVENT_SCHEMA_VERSION_V2 = 2;
+export declare const SUPPORTED_CANONICAL_VERSIONS: readonly [1, 2];
+/** 需求A:执行/环境行为健康事件类型(interaction_events.type,非普通互动事件)。 */
+export declare const INTERACTION_ACTION_OUTCOME_TYPE = "interaction_action_outcome";
+export declare const CANONICAL_ACTION_KINDS: readonly ["browse", "like", "comment", "reply", "session_start", "planned", "skipped"];
+export type CanonicalActionKind = (typeof CANONICAL_ACTION_KINDS)[number];
+/** 补录延迟上限:occurredAt 不得早于写入时刻 48h(否则 createdAt 索引查询会漏聚合)。 */
+export declare const CANONICAL_MAX_BACKFILL_MS: number;
+/** 允许的时钟漂移:occurredAt 不得晚于写入时刻 15min。 */
+export declare const CANONICAL_MAX_FUTURE_SKEW_MS: number;
+export declare function isValidIanaTimezone(tz: string): boolean;
+export type CanonicalValidationResult = {
+    ok: true;
+    canonical: boolean;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * canonical 全组校验(v5 终审②:禁止半 canonical 事件):
+ * - 7 个 canonical 键全缺 → legacy 事件,放行(向后兼容);
+ * - 任一出现 → occurredAt/eventTimezone/actionKind/eventSchemaVersion/jobId
+ *   必须完整合法;runId/sessionId 可选。
+ * API contract 层与 DB service 层(worker/import 直写路径)共用本函数。
+ */
+export declare function validateCanonicalEventPayload(payload: Record<string, unknown> | null | undefined, opts?: {
+    now?: Date;
+    eventType?: string;
+}): CanonicalValidationResult;
+export declare const OUTCOME_VALUES: readonly ["succeeded", "failed", "stopped", "uncertain"];
+/** 终止类 code(A 组,stop=true/retryable=false;STOP_WRITE_UNCERTAIN 例外→uncertain)。 */
+export declare const OUTCOME_STOP_CODES: readonly ["STOP_CHALLENGE", "STOP_RATE_LIMIT", "STOP_AUTH_REQUIRED", "STOP_HIDDEN", "STOP_PAGE_UNFOCUSED", "STOP_WRITE_UNCERTAIN", "STOP_POST_CLICK_NO_CHANGE", "STOP_FOCUS_NOT_ACQUIRED", "STOP_UPLOAD_FAILED", "STOP_UNEXPECTED_NAVIGATION"];
+/** 可重试类 code(B 组,stop=false/retryable=true/outcome=failed)。 */
+export declare const OUTCOME_RETRYABLE_CODES: readonly ["TARGET_STALE", "TARGET_NOT_FOUND", "TARGET_OBSCURED", "KEYBOARD_INPUT_FAILED", "PAGE_NAVIGATING"];
+export declare const OUTCOME_CODES: readonly ["NONE", "STOP_CHALLENGE", "STOP_RATE_LIMIT", "STOP_AUTH_REQUIRED", "STOP_HIDDEN", "STOP_PAGE_UNFOCUSED", "STOP_WRITE_UNCERTAIN", "STOP_POST_CLICK_NO_CHANGE", "STOP_FOCUS_NOT_ACQUIRED", "STOP_UPLOAD_FAILED", "STOP_UNEXPECTED_NAVIGATION", "TARGET_STALE", "TARGET_NOT_FOUND", "TARGET_OBSCURED", "KEYBOARD_INPUT_FAILED", "PAGE_NAVIGATING"];
+export declare const OUTCOME_PHASES: readonly ["precondition", "target", "focus", "input", "submit", "verify", "upload"];
+export declare const OUTCOME_METHODS: readonly ["coordinate-input", "dom-fallback", "applescript-upload"];
+/**
+ * interaction_action_outcome payload 交叉校验(需求A §5.1)。严格枚举 + 交叉关系
+ * 完整闭合(非法组合一律拒绝);未知 code 拒绝不静默降级;method=null(JSON null)
+ * 仅 precondition/target 未执行输入时允许。纯函数,fixture 可测。
+ */
+export declare function validateInteractionActionOutcomePayload(payload: Record<string, unknown>): {
+    ok: boolean;
+    errors: string[];
+};
+/** payload 已含 canonical 字段(occurredAt 在即视为 canonical 行,append-only 依据)。 */
+export declare function hasCanonicalEventFields(payload: Record<string, unknown> | null | undefined): boolean;
+export type CivilParts = {
+    date: string;
+    hour: number;
+    minute: number;
+};
+/** 绝对时刻 → 目标时区 civil 日期/时分(tz-db 规则,DST 由 Intl 处理)。 */
+export declare function getCivilInZone(instant: Date, timeZone: string): CivilParts;
+/** 日历日字符串 ±N 天(纯日期运算,与时区无关)。 */
+export declare function shiftCalendarDate(date: string, days: number): string;
+/**
+ * activityDate(§4.3③ 固定业务日 cutoff):本地 civil 时刻 00:00–02:00 归前一日。
+ * 注意:−2h 是 local civil cutoff,不是 UTC elapsed——按 civil hour 判断后做
+ * 日历日减一,不做时间戳减法(DST 日 UTC 减法会错)。
+ */
+export declare function activityDateOf(instant: Date, timeZone: string): string;
+export type TimezoneSource = {
+    timezone: string | null;
+    timezoneConfigured: boolean;
+};
+export type BrowserEnvTimezoneSource = TimezoneSource & {
+    lastHealthAt: Date | null;
+    createdAt: Date | null;
+};
+export type EffectiveTimezoneResult = {
+    effectiveTimezone: string;
+    timezoneKnown: boolean;
+};
+/**
+ * 唯一时区来源:真配置的 risk.timezone → 真配置的 browser env(多 env 取
+ * lastHealthAt 最新,无健康记录则 createdAt 最新)→ "unknown"。
+ * 默认填充的 UTC(timezoneConfigured=false)不算已知(UTC 毒化修复,§2.5.2②)。
+ */
+export declare function computeEffectiveTimezone(input: {
+    risk: TimezoneSource | null;
+    browserEnvs: BrowserEnvTimezoneSource[];
+}): EffectiveTimezoneResult;
+export type ActivityEventInput = {
+    id: string;
+    /** interaction_events.type —— 用于按类型排除非活动事件(需求A)。 */
+    type?: string | null;
+    externalRef: string | null;
+    result: string | null;
+    payload: Record<string, unknown> | null;
+    createdAt: Date;
+};
+export type ActivityLocalDay = {
+    date: string;
+    sessions: number;
+    comments: number;
+    likes: number;
+    replies: number;
+};
+export type RecentActivitySummary = {
+    windowDays: number;
+    localDays: ActivityLocalDay[];
+    lastSessionAt: string | null;
+    consecutiveSilentDays: number | null;
+    activeDaysLast7: number | null;
+    activeDaysLast28: number | null;
+    timezoneKnown: boolean;
+    /** 有事件因缺 eventTimezone 而按当前时区近似归日(§4.3⑤)。 */
+    historicalTzApprox: boolean;
+    /** 因时区完全未知而无法归日的事件数(裁决④:不猜,只计数)。 */
+    unattributedEvents: number;
+};
+/**
+ * 聚合最近 windowDays 个 activityDate 的 session/action(§4.3④ 全口径)。
+ * 仅统计 canonical 事件(payload 带合法 actionKind∈browse/like/comment/reply
+ * 且 result 非 failed/skipped);legacy 无 actionKind 事件不参与(P1 起新数据)。
+ */
+export declare function computeRecentActivitySummary(events: ActivityEventInput[], opts: {
+    now: Date;
+    effectiveTimezone: string;
+    timezoneKnown: boolean;
+    windowDays?: number;
+}): RecentActivitySummary;
+//# sourceMappingURL=activity.d.ts.map

package/dist/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAChD,yEAAyE;AACzE,eAAO,MAAM,iCAAiC,IAAI,CAAC;AACnD,eAAO,MAAM,4BAA4B,iBAG/B,CAAC;AAEX,0DAA0D;AAC1D,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAE5E,eAAO,MAAM,sBAAsB,wFAQzB,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAoB1E,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB,QAAsB,CAAC;AAC7D,yCAAyC;AACzC,eAAO,MAAM,4BAA4B,QAAiB,CAAC;AAE3D,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAQvD;AASD,MAAM,MAAM,yBAAyB,GACjC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACnD,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,yBAAyB,CA4G3B;AAID,eAAO,MAAM,cAAc,0DAKjB,CAAC;AAEX,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,gPAWrB,CAAC;AAEX,+DAA+D;AAC/D,eAAO,MAAM,uBAAuB,8GAM1B,CAAC;AAEX,eAAO,MAAM,aAAa,2VAIhB,CAAC;AAEX,eAAO,MAAM,cAAc,qFAQjB,CAAC;AAEX,eAAO,MAAM,eAAe,qEAIlB,CAAC;AAQX;;;;GAIG;AACH,wBAAgB,uCAAuC,CACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA8GnC;AAED,2EAA2E;AAC3E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAClD,OAAO,CAET;AAuBD,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,uDAAuD;AACvD,wBAAgB,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAQ1E;AAED,gCAAgC;AAChC,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGtE;AAID,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG,cAAc,GAAG;IACtD,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,wBAAwB,EAAE,CAAC;CACzC,GAAG,uBAAuB,CAwB1B;AAID,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC;AAWF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,oCAAoC;IACpC,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAAC;AAeF;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,kBAAkB,EAAE,EAC5B,IAAI,EAAE;IACJ,GAAG,EAAE,IAAI,CAAC;IACV,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,qBAAqB,CAqMvB"}