trackswap 0.2.3 → 0.2.5

package/README.md

@@ -59,6 +59,22 @@ const converted = await trackSwap.transcode(input, {
 const course = await trackSwap.encodeCourse(input);
 ~~~
 
+FIT 力量训练会将 `set` message 按原始顺序投影到
+`activity.strengthSets`，保留动作、休息、次数、重量、时长和设备动作标签：
+
+~~~ts
+const file = await trackSwap.decodeActivity(fitBuffer, { format: "fit" });
+const [activity] = file.activities ?? [];
+
+for (const phase of activity?.strengthSets ?? []) {
+  console.log(phase.setType, phase.repetitions, phase.weight, phase.exercises);
+}
+~~~
+
+部分 FIT 活动包含 `record`、但没有实际 `lap` message。TrackSwap 会把这些
+Record 放入一个合成 Lap，确保统一活动模型不丢样本；不会根据 Session 的
+`numLaps` 编造 Lap 明细。
+
 ## FIT 健康数据
 
 FIT 文件只解码一次，活动与健康数据作为同一 `TrackDocument` 的 facet 返回。健康结构不直接绑定 Garmin Connect JSON，使用稳定的中间表示：
@@ -69,6 +85,10 @@ FIT 文件只解码一次，活动与健康数据作为同一 `TrackDocument`
 - `summaries`：日汇总、睡眠汇总及设备汇总；
 - `diagnostics`：FIT SDK profile、无效值、未知消息和解析警告。
 
+标准化边界由 TrackSwap 负责：FIT epoch、`timestamp_16`、Garmin sentinel、
+字段 scale/unit、时区偏移和 HSA 数组展开均不会泄漏给业务调用方。所有时区偏移
+统一使用秒；sentinel 只保留在 `status`/`attributes.rawValue`，不会伪装成有效测量值。
+
 ~~~ts
 const document = await trackSwap.decode(fitBuffer, {
   fit: {

package/dist/FIT/base.d.ts

@@ -1,23 +1,47 @@
 import { IPlugin } from "../core/base.js";
 import { FITContext, FITDecoderMesgs, FITFileType } from "./types.js";
+/**
+ * FIT message converter plugin interface
+ */
 export interface IFITMessageConverter extends IPlugin<FITContext> {
+    /** Supported message types */
     supportedMessageTypes: string[];
+    /** Convert messages */
     convertMessages(messages: any[], context: FITContext): any;
+    /** Whether it supports the message type */
     supports(messageType: string): boolean;
+    /** Priority */
     priority?: number;
 }
+/**
+ * FIT data structuring plugin interface
+ */
 export interface IFITStructurePlugin extends IPlugin<FITContext> {
+    /** Structure data */
     structureData(messages: FITDecoderMesgs, context: FITContext): Partial<FITFileType>;
+    /** Priority */
     priority?: number;
 }
+/**
+ * FIT middleware plugin interface
+ */
 export interface IFITMiddlewarePlugin extends IPlugin<FITContext> {
+    /** Priority */
     priority?: number;
+    /** Execute during parse stage */
     onParse?(buffer: Buffer, context: FITContext): Promise<Buffer> | Buffer;
+    /** Execute during message extraction stage */
     onExtractMessages?(messages: FITDecoderMesgs, context: FITContext): Promise<FITDecoderMesgs> | FITDecoderMesgs;
+    /** Execute during data structuring stage */
     onStructure?(result: Partial<FITFileType>, context: FITContext): Promise<Partial<FITFileType>> | Partial<FITFileType>;
+    /** Execute during completion stage */
     onComplete?(result: FITFileType, context: FITContext): Promise<FITFileType> | FITFileType;
+    /** Error handling */
     onError?(error: Error, context: FITContext): Promise<void> | void;
 }
+/**
+ * FIT message converter base class
+ */
 export declare abstract class BaseFITMessageConverter implements IFITMessageConverter {
     abstract name: string;
     abstract supportedMessageTypes: string[];
@@ -36,6 +60,9 @@ export declare abstract class BaseFITMessageConverter implements IFITMessageConv
         records: any[];
     }>;
 }
+/**
+ * FIT data structuring plugin base class
+ */
 export declare abstract class BaseFITStructurePlugin implements IFITStructurePlugin {
     abstract name: string;
     version: string;
@@ -45,6 +72,9 @@ export declare abstract class BaseFITStructurePlugin implements IFITStructurePlu
     destroy(context: FITContext): Promise<void>;
     validate(context: FITContext): Promise<boolean>;
 }
+/**
+ * FIT middleware base class
+ */
 export declare abstract class BaseFITMiddleware implements IFITMiddlewarePlugin {
     abstract name: string;
     version: string;

package/dist/FIT/decoder.d.ts

@@ -1,5 +1,8 @@
 import { IFITMessageConverter, IFITStructurePlugin, IFITMiddlewarePlugin } from "./base.js";
 import { FITFileType } from "./types.js";
+/**
+ * FIT decoder - follows GPX style plugin architecture
+ */
 export declare class FITDecoder {
     private converterPlugins;
     private registeredPlugins;
@@ -9,20 +12,65 @@ export declare class FITDecoder {
     private initialized;
     private defaultPluginsRegistered;
     constructor();
+    /**
+     * Initialize pipeline - register fixed core processors
+     */
     private initializePipeline;
+    /**
+     * Auto-register default plugins
+     */
     private registerDefaultPlugins;
+    /**
+     * Add converter for specific message type, sorted by priority
+     */
     private addConverterForMessageType;
+    /**
+     * Add structure plugin
+     */
     private addStructurePlugin;
+    /**
+     * Register message converter plugin
+     */
     registerMessageConverter(plugin: IFITMessageConverter): Promise<void>;
+    /**
+     * Register structure plugin
+     */
     registerStructurePlugin(plugin: IFITStructurePlugin): Promise<void>;
+    /**
+     * Register middleware plugin
+     */
     registerMiddleware(plugin: IFITMiddlewarePlugin): Promise<void>;
+    /**
+     * Get message type converter (returns highest priority one)
+     */
     getConverter(messageType: string): IFITMessageConverter | undefined;
+    /**
+     * Get all converters for specified message type (sorted by priority)
+     */
     getConverters(messageType: string): IFITMessageConverter[];
+    /**
+     * Remove plugin
+     */
     unregisterPlugin(pluginName: string): boolean;
+    /**
+     * Initialize decoder
+     */
     initialize(): Promise<void>;
+    /**
+     * Destroy decoder
+     */
     destroy(): Promise<void>;
+    /**
+     * Create decode context
+     */
     private createContext;
+    /**
+     * Execute middleware hook
+     */
     private executeMiddlewareHook;
+    /**
+     * Main parse method - fixed pipeline + flexible middleware
+     */
     parseByBuffer(buffer: Buffer, options?: {
         userData?: Record<string, any>;
     }): Promise<FITFileType | undefined>;

package/dist/FIT/encoder.d.ts

@@ -1,41 +1,137 @@
 import { FITFileType } from "./types.js";
+/**
+ * FIT encoder options
+ */
 export interface FITEncoderOptions {
+    /** Whether to enable compact mode */
     compact?: boolean;
+    /** Default sport type */
     defaultActivity?: string;
+    /** Default sub sport type */
     defaultSubActivity?: string;
 }
+/**
+ * FIT encoder - encodes FITFileType data to FIT binary format
+ */
 export declare class FITEncoder {
     private localNum;
     private mesgDefn;
     private messages;
     private options;
+    /**
+     * Constructor
+     * @param options Encoder options
+     */
     constructor(options?: FITEncoderOptions);
+    /**
+     * Encode FIT data to Buffer - Activity file type
+     */
     encode(fitData: FITFileType): Promise<Buffer>;
+    /**
+     * Encode FIT data to Buffer - Course file type
+     */
     encodeCourse(fitData: FITFileType): Promise<Buffer>;
+    /**
+     * Encode FIT data to Blob
+     */
     encodeToBlob(fitData: FITFileType, fileType?: "activity" | "course"): Promise<Blob>;
+    /**
+     * Reset encoder state
+     */
     private reset;
+    /**
+     * Build FIT file content
+     */
     private buildFITContent;
+    /**
+     * Build Activity file content
+     */
     private buildActivityContent;
+    /**
+     * Build Course file content
+     */
     private buildCourseContent;
+    /**
+     * Build file ID
+     */
     private buildFileId;
+    /**
+     * Build Session
+     * 构造 Session 信息
+     */
     private buildSession;
+    /**
+     * Build Laps
+     */
     private buildLaps;
+    /**
+     * Build single Lap
+     * 构造 Lap 信息
+     */
     private buildLap;
+    /**
+     * Build Records
+     */
     private buildRecords;
+    /**
+     * Build single Record
+     */
     private buildRecord;
+    /**
+     * Build Event
+     */
     private buildEvent;
+    /**
+     * Build Activity
+     */
     private buildActivity;
+    /**
+     * Build Course
+     */
     private buildCourse;
+    /**
+     * Build Events from Laps
+     */
     private buildEventsFromLaps;
+    /**
+     * Build Activity from Session
+     */
     private buildActivityFromSession;
+    /**
+     * Parse timestamp
+     */
     private parseTimestamp;
+    /**
+     * Validate required fields
+     */
     private validateRequiredFields;
+    /**
+     * Write message
+     */
     private writeMesg;
+    /**
+     * Get Blob object
+     */
     get blob(): Blob;
+    /**
+     * Get data length
+     */
     get dataLen(): number;
+    /**
+     * Get data CRC
+     */
     get dataCrc(): number;
+    /**
+     * Get file header
+     */
     get header(): ArrayBuffer;
+    /**
+     * Get file trailer
+     */
     get trailer(): ArrayBuffer;
+    /**
+     * @deprecated Use encode() instead
+     */
     encoder(fitData: FITFileType): Promise<Buffer>;
 }
 declare const _default: {

package/dist/FIT/encoderCourse.d.ts

@@ -1,37 +1,82 @@
 import { CoursePoint as CoursePointType } from "./types/course_point.js";
 import { MesgNum } from "./types/mesg_num.js";
 import { Sport, SubSport } from "./types/message_index_type.js";
+/**
+ * 路线轨迹点（用于生成 record 消息）。
+ * 默认输入经纬度为「度」，内部会转换为 FIT semicircles。
+ */
 export interface CourseRecordPoint {
+    /** 轨迹点时间（Date 或 FIT 时间戳/Unix 时间戳）。 */
     timestamp: Date | number;
+    /** 纬度（默认按度处理，范围通常 -90~90）。 */
     latitude: number;
+    /** 经度（默认按度处理，范围通常 -180~180）。 */
     longitude: number;
+    /** 距离（单位 m，可选）。 */
     distance?: number;
+    /** 海拔（单位 m，可选）。 */
     altitude?: number;
+    /** 速度（单位 m/s，可选）。 */
     speed?: number;
 }
+/**
+ * 路线拐点（用于生成 course_point 消息）。
+ */
 export interface CourseCuePoint {
+    /** 拐点时间。 */
     timestamp: Date | number;
+    /** 拐点纬度（默认按度处理）。 */
     latitude: number;
+    /** 拐点经度（默认按度处理）。 */
     longitude: number;
+    /** 拐点类型（左转/右转/补给点等），默认 GENERIC。 */
     type?: CoursePointType;
+    /** 拐点名称。 */
     name?: string;
+    /** 拐点对应路线距离（单位 m，可选）。 */
     distance?: number;
+    /** 是否收藏点。 */
     favorite?: boolean;
 }
+/**
+ * 课程计划（业务模型）。
+ */
 export interface CoursePlan {
+    /** 路线名称。 */
     name: string;
+    /** 运动类型，默认 CYCLING。 */
     sport?: Sport;
+    /** 子运动类型，默认 GENERIC。 */
     subSport?: SubSport;
+    /** 路线轨迹点（至少 1 个）。 */
     records: CourseRecordPoint[];
+    /** 路线拐点列表（可选）。 */
     coursePoints?: CourseCuePoint[];
+    /** file_id.manufacturer，可选，默认 development。 */
     manufacturer?: string | number;
+    /** file_id.product，可选，默认 1。 */
     product?: number;
+    /** file_id.serialNumber，可选，默认 1。 */
     serialNumber?: number;
+    /** file_id.timeCreated，可选，默认首个 record.timestamp。 */
     timeCreated?: Date | number;
 }
+/**
+ * 中间消息结构，统一喂给 Garmin Encoder.onMesg()。
+ */
 export interface FitMesg {
+    /** FIT 消息号。 */
     mesgNum: MesgNum;
+    /** 消息体。 */
     data: Record<string, unknown>;
 }
+/**
+ * 课程映射：
+ * FILE_ID(course) + COURSE + LAP + EVENT(start/stop_all) + RECORD[] + COURSE_POINT[]。
+ */
 export declare function buildCourseMesgs(plan: CoursePlan): FitMesg[];
+/**
+ * 编码入口：
+ * 先映射消息，再写入 Garmin Encoder，最后 close() 输出 FIT 字节。
+ */
 export declare function encodeCourse(plan: CoursePlan): Uint8Array;

package/dist/FIT/encoderWorkout.d.ts

@@ -1,5 +1,9 @@
 import { MesgNum } from "./types/mesg_num.js";
 import { Intensity, Sport, SubSport } from "./types/message_index_type.js";
+/**
+ * 业务层的「步骤时长」抽象。
+ * 注意：这里只表达业务含义，具体如何编码到 FIT 在 mapDuration() 里处理。
+ */
 export type WorkoutDuration = {
     kind: "time";
     seconds: number;
@@ -12,30 +16,71 @@ export type WorkoutDuration = {
 } | {
     kind: "open";
 };
+/**
+ * 业务层的「步骤目标」抽象。
+ * V1 仅支持 open（不设目标区间）。
+ */
 export type WorkoutTarget = {
     kind: "open";
 };
+/**
+ * 单个训练步骤（业务模型）。
+ */
 export interface WorkoutStep {
+    /** 步骤名称（如 Warmup / Interval）。 */
     name?: string;
+    /** 步骤强度，默认 ACTIVE。 */
     intensity?: Intensity;
+    /** 步骤时长/结束条件（必填）。 */
     duration: WorkoutDuration;
+    /** 步骤目标，V1 默认 open。 */
     target?: WorkoutTarget;
 }
+/**
+ * 一个完整的训练计划（业务模型）。
+ * - 前 5 个字段是核心业务字段
+ * - 后面的 manufacturer/product... 是 FIT file_id 附加字段，可选
+ */
 export interface WorkoutPlan {
+    /** 训练名称，映射到 FIT 的 wktName。 */
     name: string;
+    /** 训练描述，映射到 FIT 的 wktDescription。 */
     description?: string;
+    /** 运动类型（跑步/骑行/游泳等）。 */
     sport: Sport;
+    /** 子运动类型，默认 GENERIC。 */
     subSport?: SubSport;
+    /** 训练步骤列表，至少 1 条。 */
     steps: WorkoutStep[];
+    /** file_id.manufacturer，可选，不传则用 development。 */
     manufacturer?: string | number;
+    /** file_id.product，可选，默认 1。 */
     product?: number;
+    /** file_id.serialNumber，可选，默认 1。 */
     serialNumber?: number;
+    /** workout.messageIndex，可选，默认 0。 */
     messageIndex?: number;
+    /** file_id.timeCreated，可选，默认 new Date()。 */
     timeCreated?: Date | number;
 }
+/**
+ * 中间层消息结构：后续统一喂给 Garmin Encoder.onMesg()。
+ */
 export interface FitMesg {
+    /** FIT 消息号，例如 FILE_ID/WORKOUT/WORKOUT_STEP。 */
     mesgNum: MesgNum;
+    /** Garmin Encoder 需要的消息体数据。 */
     data: Record<string, unknown>;
 }
+/**
+ * 核心映射函数：
+ * WorkoutPlan -> FILE_ID + WORKOUT + WORKOUT_STEP[]。
+ */
 export declare function buildWorkoutMesgs(plan: WorkoutPlan): FitMesg[];
+/**
+ * 编码入口：
+ * 1) 先构造中间消息数组
+ * 2) 逐条写入 Garmin Encoder
+ * 3) close() 得到 FIT 二进制（Uint8Array）
+ */
 export declare function encodeWorkout(plan: WorkoutPlan): Uint8Array;