@activitymerge/core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Vogl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @activitymerge/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MIT. Local FIT merge for Garmin, Wahoo, COROS, Zwift, and Strava files. Callers pass bytes. The library does not read the filesystem and does not open a network connection.
+
+```sh
+npm i @activitymerge/core
+```
+
+`engineVersion` is `0.1.0`.
+
+```ts
+import { merge } from '@activitymerge/core'
+
+const result = await merge(
+  [{ name: 'a.fit', bytes: a }, { name: 'b.fit', bytes: b }],
+  { gap: 'keep', order: 'start-time', deviceFrom: 0 },
+)
+```
+
+`result.bytes` is the FIT file. `result.report` matches `schema/report.v1.json`. Coordinates are omitted unless `includeCoordinates` is true.
+
+A checkout of the repository is the other way to build it: `npm ci` and `npm run build:packages`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,33 @@
+# Third-party notices
+
+`@activitymerge/core` bundles the following third-party software in `dist/index.js`.
+
+## fit-file-parser 6.2.3
+
+https://github.com/jimmykane/fit-parser
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2015 Pierre Jacquier
+http://pierrejacquier.com | @pierremtb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+```

package/dist/index.d.ts

@@ -0,0 +1,515 @@
+/** Stable error codes. Exit class is decided by the CLI and MCP, not by the byte merge. */
+export declare const ERROR_CODES: readonly [
+	"UNSUPPORTED_FORMAT",
+	"CORRUPT_FILE",
+	"OVERLAPPING_TIMERANGES",
+	"SPORT_MISMATCH",
+	"TOO_FEW_INPUTS",
+	"FILE_TOO_LARGE",
+	"DUPLICATE_INPUT",
+	"OUTPUT_EXISTS"
+];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+export declare class ActivityError extends Error {
+	readonly code: ErrorCode;
+	readonly hint: string;
+	readonly input?: number;
+	constructor(code: ErrorCode, message: string, hint: string, input?: number);
+	toJSON(): {
+		code: ErrorCode;
+		message: string;
+		hint: string;
+		input?: number;
+	};
+}
+/** 2 usage/input, 3 merge/data, 4 IO. */
+export declare function exitFor(code: ErrorCode): 2 | 3 | 4;
+declare const WARNING_CODES: readonly [
+	"overlap_trimmed",
+	"file_fully_overlapped",
+	"sport_mismatch",
+	"multiple_sessions",
+	"developer_fields_omitted",
+	"training_metrics_omitted",
+	"partial_calories",
+	"partial_ascent",
+	"partial_descent",
+	"missing_distance",
+	"laps_keep_original",
+	"time_not_monotonic"
+];
+export type WarningCode = (typeof WARNING_CODES)[number];
+export interface MergeWarning {
+	code: WarningCode;
+	message: string;
+	fileName?: string;
+	count?: number;
+}
+/** One sample. Optional channels stay absent when that file did not record them. */
+export interface TrackPoint {
+	timestamp: Date;
+	latitude?: number;
+	longitude?: number;
+	altitudeMeters?: number;
+	/** Cumulative meters from the start of the merged activity after continuity is applied. */
+	distanceMeters?: number;
+	speedMps?: number;
+	heartRate?: number;
+	power?: number;
+	/**
+	 * FIT cadence as stored. Running and walking use half-cadence (strides/min),
+	 * not steps/min. `fractionalCadence` is the fractional revolution, 0–1.
+	 */
+	cadence?: number;
+	fractionalCadence?: number;
+	temperatureCelsius?: number;
+	/** Raw FIT uint8, including the right-side bit. */
+	leftRightBalance?: number;
+	/** Raw FIT uint8. The profile scale is 2, so the stored byte is percent × 2. */
+	leftTorqueEffectiveness?: number;
+	rightTorqueEffectiveness?: number;
+	leftPedalSmoothness?: number;
+	rightPedalSmoothness?: number;
+	/** Raw FIT uint16. The profile scale is 100. */
+	stanceTimeBalance?: number;
+	/** Record fields we do not reinterpret. Multi-byte values are stored little-endian. */
+	extraFields?: RecordRawField[];
+	/** Developer-field bytes, stored little-endian when a field description gives the base type. */
+	developerFields?: DeveloperFieldSample[];
+}
+export interface RecordRawField {
+	fieldNumber: number;
+	baseType: number;
+	raw: number[];
+}
+export interface DeveloperDataId {
+	index: number;
+	manufacturerId?: number;
+	applicationVersion?: number;
+	applicationId?: number[];
+}
+export interface DeveloperFieldDescription {
+	developerDataIndex: number;
+	fieldNumber: number;
+	baseType: number;
+	name?: string;
+	units?: string;
+	scale?: number;
+	offset?: number;
+}
+export interface DeveloperFieldSample {
+	developerDataIndex: number;
+	fieldNumber: number;
+	raw: number[];
+}
+export interface TimerEvent {
+	timestamp: Date;
+	type: "start" | "stop" | "stop_all";
+}
+export interface TimeRange {
+	start: Date;
+	end: Date;
+}
+export interface ActivityLap {
+	startTime: Date;
+	endTime: Date;
+	elapsedSeconds: number;
+	timerSeconds: number;
+	distanceMeters: number;
+	calories?: number;
+	ascentMeters?: number;
+	descentMeters?: number;
+	avgHeartRate?: number;
+	maxHeartRate?: number;
+	avgPower?: number;
+	maxPower?: number;
+	avgCadence?: number;
+	maxCadence?: number;
+	avgSpeedMps?: number;
+	maxSpeedMps?: number;
+	startLatitude?: number;
+	startLongitude?: number;
+	endLatitude?: number;
+	endLongitude?: number;
+	sport?: string;
+	subSport?: string;
+	trigger?: string;
+}
+export interface DeviceIdentity {
+	manufacturerId?: number;
+	manufacturerName?: string;
+	product?: number;
+	productName?: string;
+	serialNumber?: number;
+	softwareVersion?: number;
+	hardwareVersion?: number;
+}
+export interface ActivityFile {
+	sourceName?: string;
+	sport: string;
+	subSport: string;
+	records: TrackPoint[];
+	laps: ActivityLap[];
+	timerEvents: TimerEvent[];
+	device: DeviceIdentity;
+	sessionCount: number;
+	totalCalories?: number;
+	totalAscentMeters?: number;
+	totalDescentMeters?: number;
+	/** Sum of `session.total_distance`, meters. Absent when the file recorded none. */
+	sessionDistanceMeters?: number;
+	/** Sum of `session.total_timer_time`, seconds. */
+	sessionTimerSeconds?: number;
+	/** Highest `session.max_heart_rate`. */
+	sessionMaxHeartRate?: number;
+	hasDeveloperData: boolean;
+	hasTrainingMetrics: boolean;
+	/**
+	 * `local_timestamp - timestamp` from the FIT activity message, in milliseconds.
+	 * Missing when the file has no local timestamp. Calendar days use this offset, not the browser zone.
+	 */
+	localOffsetMs?: number;
+	developerDataIds: DeveloperDataId[];
+	fieldDescriptions: DeveloperFieldDescription[];
+}
+export interface SessionTotals {
+	startTime: Date;
+	endTime: Date;
+	elapsedSeconds: number;
+	timerSeconds: number;
+	pauseSeconds: number;
+	distanceMeters: number;
+	distanceKnown: boolean;
+	calories?: number;
+	ascentMeters?: number;
+	descentMeters?: number;
+	avgHeartRate?: number;
+	maxHeartRate?: number;
+	avgPower?: number;
+	maxPower?: number;
+	/** Combined FIT cadence, including the fractional part. */
+	avgCadence?: number;
+	maxCadence?: number;
+	avgSpeedMps?: number;
+	maxSpeedMps?: number;
+	avgTemperatureCelsius?: number;
+	maxTemperatureCelsius?: number;
+	sport: string;
+	subSport: string;
+}
+export interface MergedActivity {
+	device: DeviceIdentity;
+	sport: string;
+	subSport: string;
+	records: TrackPoint[];
+	laps: ActivityLap[];
+	intervals: TimeRange[];
+	timerEvents: TimerEvent[];
+	session: SessionTotals;
+	warnings: MergeWarning[];
+	developerDataIds: DeveloperDataId[];
+	fieldDescriptions: DeveloperFieldDescription[];
+}
+export interface MergeOptions {
+	/**
+	 * `start-time` sorts by the first record (default).
+	 * `given` keeps the caller's order, which is what the web UI sends after a manual reorder.
+	 */
+	order?: "start-time" | "given";
+	/** Shift later files earlier so the clock gap disappears. Off by default: it changes timestamps. */
+	removeGap?: boolean;
+	/** Add the straight-line distance across the gap. Off by default. */
+	includeGapDistance?: boolean;
+	/**
+	 * `trim-next` drops the later file’s overlapping points (default).
+	 * `trim-previous` drops the earlier file’s tail instead.
+	 */
+	overlap?: "trim-next" | "trim-previous";
+	/** Index into the ordered inputs whose device and file id are written. Defaults to the first file that contributes records. */
+	deviceFrom?: number;
+}
+export interface MergeSummary {
+	startTime: string;
+	endTime: string;
+	elapsedSeconds: number;
+	timerSeconds: number;
+	pauseSeconds: number;
+	distanceMeters: number;
+	distanceKnown: boolean;
+	sport: string;
+	subSport: string;
+	recordCount: number;
+	lapCount: number;
+	deviceName?: string;
+	avgHeartRate?: number;
+	maxHeartRate?: number;
+	avgPower?: number;
+	maxPower?: number;
+	avgCadence?: number;
+	maxCadence?: number;
+	cadenceUnit?: "spm" | "rpm";
+	avgSpeedMps?: number;
+	maxSpeedMps?: number;
+	ascentMeters?: number;
+	avgTemperatureCelsius?: number;
+	maxTemperatureCelsius?: number;
+	warnings: MergeWarning[];
+	preview: TrackPreview;
+	/** Route, stats, and chart for the result card. Built from the source files, before overlap trimming. */
+	resultPreview: ResultPreview;
+}
+export interface ResultPreviewPart {
+	start: number;
+	end: number;
+	/** Device offset, milliseconds, for local clocks and calendar days. */
+	offsetMs: number;
+	distM?: number;
+	color: "trail" | "accent";
+}
+export interface ResultPreviewJoin {
+	/** Positive when the next part starts after this one ends. */
+	gapMs: number;
+	/** Positive when the next part starts before this one ends. */
+	overlapMs: number;
+}
+export interface ResultPreviewStats {
+	distM?: number;
+	elapsedS: number;
+	movingS?: number;
+	pauseS: number;
+	upM?: number;
+	downM?: number;
+	hrAvg?: number;
+	hrMax?: number;
+	powerAvg?: number;
+}
+export interface ResultPreviewSeries {
+	t: number[];
+	v: number[];
+}
+export interface ResultRoutePart {
+	d: string;
+	color: "trail" | "accent";
+	/** Coral outline for the section of this part that overlaps the previous one. */
+	overlapD?: string;
+}
+export interface ResultRouteGap {
+	/** Dashed segment. Absent when the join is shorter than 30 m. */
+	d?: string;
+	dot: [
+		number,
+		number
+	];
+}
+export interface ResultRoute {
+	viewBox: [
+		number,
+		number
+	];
+	parts: ResultRoutePart[];
+	gaps: ResultRouteGap[];
+	start: [
+		number,
+		number
+	];
+	finish: [
+		number,
+		number
+	];
+}
+export interface ResultPreviewWarning {
+	kind: "overlap";
+	separationMs: number;
+	/** 1-based index of the earlier part. */
+	prev: number;
+	/** 1-based index of the later part. */
+	next: number;
+}
+/** Sensor channels that actually had a sample. Power counts only above 0 W. */
+export type KeptChannel = "hr" | "cadence" | "power" | "elevation" | "temperature";
+export interface ResultPreview {
+	files: number;
+	parts: ResultPreviewPart[];
+	joins: ResultPreviewJoin[];
+	/** Moving-time seconds (join pauses removed) where the chart draws a gap marker. */
+	joinAt: number[];
+	route: ResultRoute | null;
+	stats: ResultPreviewStats;
+	series: {
+		ele?: ResultPreviewSeries;
+		hr?: ResultPreviewSeries;
+		pw?: ResultPreviewSeries;
+	};
+	/** Present channels, in display order. */
+	kept: KeptChannel[];
+	warning: ResultPreviewWarning | null;
+}
+export interface FileSummary {
+	sourceName?: string;
+	sport: string;
+	subSport: string;
+	startTime: string;
+	endTime: string;
+	/** FIT activity local-time offset. Absent when the file did not carry `local_timestamp`. */
+	localOffsetMs?: number;
+	elapsedSeconds: number;
+	recordCount: number;
+	lapCount: number;
+	distanceMeters?: number;
+	deviceName?: string;
+	avgHeartRate?: number;
+	maxHeartRate?: number;
+	avgPower?: number;
+	avgSpeedMps?: number;
+	timerSeconds: number;
+	ascentMeters?: number;
+	hasHeartRate: boolean;
+	hasPower: boolean;
+	hasCadence: boolean;
+	hasSpeed: boolean;
+	preview: TrackPreview;
+}
+/** Downsampled series for an offline map and chart. Coordinates are degrees. */
+export interface TrackPreview {
+	hasGps: boolean;
+	path: Array<[
+		number,
+		number
+	]>;
+	heartRate: Array<[
+		number,
+		number
+	]>;
+	altitude: Array<[
+		number,
+		number
+	]>;
+	power: Array<[
+		number,
+		number
+	]>;
+	speed: Array<[
+		number,
+		number
+	]>;
+}
+export interface FitInput {
+	name?: string;
+	bytes: Uint8Array;
+}
+export interface MergeFitResult {
+	bytes: Uint8Array;
+	activity: MergedActivity;
+	summary: MergeSummary;
+}
+declare const ERROR_CODES$1: readonly [
+	"need_two_files",
+	"invalid_fit",
+	"no_records",
+	"empty_merge"
+];
+export type FitMergeErrorCode = (typeof ERROR_CODES$1)[number];
+export declare class FitMergeError extends Error {
+	readonly code: FitMergeErrorCode;
+	readonly warnings: MergeWarning[];
+	constructor(code: FitMergeErrorCode, message: string, warnings?: MergeWarning[]);
+}
+export declare function readActivity(bytes: Uint8Array, sourceName?: string): Promise<ActivityFile>;
+export declare function summarizeActivity(file: ActivityFile): FileSummary;
+export declare function mergeFitFiles(inputs: readonly FitInput[], options?: MergeOptions): Promise<MergeFitResult>;
+export interface SampleFitFile {
+	name: string;
+	bytes: Uint8Array;
+}
+/**
+ * Two short synthetic rides with a one-minute pause.
+ * Six fixes each (twelve in total) so the result preview treats them as a GPS track.
+ * Built in memory so the page never fetches a file.
+ */
+export declare function buildSampleFits(start?: Date): SampleFitFile[];
+export type GapHandling = "keep" | "close" | "distance";
+export interface ReportInput {
+	index: number;
+	name?: string;
+	sport: string;
+	start: string;
+	end: string;
+	durationS: number;
+	distanceM: number;
+	records: number;
+	laps: number;
+	sensors: string[];
+	coordinates?: Array<{
+		latitude: number;
+		longitude: number;
+	}>;
+}
+export interface ActivityReport {
+	engineVersion: string;
+	inputs: ReportInput[];
+	output: {
+		format: "fit";
+		records: number;
+		laps: number;
+		durationS: number;
+		distanceM: number;
+		bytes: number;
+	};
+	gaps: Array<{
+		afterInput: number;
+		seconds: number;
+		handling: GapHandling;
+	}>;
+	warnings: Array<{
+		code: string;
+		message: string;
+	}>;
+}
+export interface InspectResult {
+	engineVersion: string;
+	input: ReportInput;
+}
+export declare function inspect(bytes: Uint8Array, name?: string, includeCoordinates?: boolean): Promise<InspectResult>;
+export declare function validate(bytes: Uint8Array, name?: string): Promise<{
+	ok: true;
+	engineVersion: string;
+	records: number;
+}>;
+/** Spec limits. The browser tool keeps its own 50 MiB check and is not routed through this. */
+export declare const MAX_FILE_BYTES = 50000000;
+export declare const MAX_TOTAL_BYTES = 200000000;
+export declare const MAX_FILES = 20;
+export declare function assertMergeInputs(inputs: readonly {
+	bytes: Uint8Array;
+}[]): void;
+export interface FitPart {
+	name?: string;
+	bytes: Uint8Array;
+}
+export interface CoreMergeOptions {
+	/**
+	 * `keep` leaves the pause (the browser default).
+	 * `close` shifts later timestamps. `distance` adds straight-line distance.
+	 */
+	gap?: GapHandling;
+	/** `given` is what the web worker sends after the page has ordered the files. */
+	order?: "start-time" | "given";
+	overlap?: "trim-next" | "trim-previous";
+	/** The worker always sends 0. Omit only when calling the library default. */
+	deviceFrom?: number;
+	includeCoordinates?: boolean;
+}
+export interface CoreMergeResult {
+	bytes: Uint8Array;
+	summary: Awaited<ReturnType<typeof mergeFitFiles>>["summary"];
+	report: ActivityReport;
+}
+/**
+ * Same FIT bytes as `mergeFitFiles` for the same options.
+ * `gap=close` forces distance-across-gap off, matching the web worker.
+ */
+export declare function merge(inputs: readonly FitPart[], options?: CoreMergeOptions): Promise<CoreMergeResult>;
+/** Matches packages/core/package.json. The report field engineVersion uses this string. */
+export declare const engineVersion = "0.1.0";
+
+export {};