@chronicle.app/arc-timeline 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+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

@@ -0,0 +1,105 @@
+# @chronicle.app/arc-timeline
+
+Chronicle plugin for the location timeline from [Arc Timeline](https://apps.apple.com/ca/app/arc-timeline-4/id6740688708) (the iOS app, built on LocoKit).
+
+## Installation
+
+```bash
+npm install @chronicle.app/arc-timeline
+```
+
+## Usage
+
+Point the extractor at the Arc Timeline **daily backup** — the per-day files the
+iOS app writes automatically (no manual export step). On macOS these sync to
+iCloud Drive under:
+
+```
+~/Library/Mobile Documents/iCloud~com~bigpaua~Arc-Timeline-Editor/Documents/Exports
+```
+
+`--input` accepts that `Exports` folder, its `Daily` subfolder, or the
+`Daily/JSON` directory that actually holds the `YYYY-MM-DD.json.gz` files — the
+extractor resolves the right subdirectory.
+
+### Basic extraction
+
+```bash
+chronicle extract arc-timeline --input /path/to/Exports
+```
+
+### With date filtering
+
+```bash
+chronicle extract arc-timeline \
+  --input /path/to/Exports \
+  --since 2024-01-01 \
+  --until 2024-12-31 \
+  --limit 1000
+```
+
+## Configuration
+
+- `--input`: Path to the daily backup (the `Exports`, `Daily`, or `Daily/JSON` directory); defaults to Arc's iCloud Drive `Exports` folder
+- `--identity`: Override the person whose timeline this is (e.g. an email); defaults to the macOS iCloud account
+- `--since`: Extract items whose start date is on or after this date
+- `--until`: Extract items whose start date is on or before this date
+- `--limit`: Maximum number of records to extract
+
+## File Format
+
+The daily backup (schema `2.2.0`, written by the Arc Timeline Editor app on
+LocoKit) is a flat directory of one gzipped file per day:
+
+```
+Daily/JSON/
+  YYYY-MM-DD.json.gz   a self-contained day: { items, places, samples, notes, metadata }
+```
+
+Each day's file inlines everything for that day, so there are no cross-file
+joins within a day. A timeline item is `{ base, trip | visit }`. `base` holds
+the fields common to every item (id, start/end dates, `isVisit`, step count,
+heart rate, the `previousItemId`/`nextItemId` linked list). Exactly one of:
+
+- `visit` — a stay: `placeId` (joined to that day's `places`), coordinates, street address.
+- `trip` — movement: distance, speed, and a `classifiedActivityType` enum code.
+
+The extractor reads the day files newest-first and joins each visit to that
+day's `places`. It emits one record per item:
+
+- `recordType: "visit"` for stays
+- `recordType: "travel"` for trips
+
+An item that spans midnight appears in both adjacent days' files; it is deduped
+on the stable item id, and a trip's GPS samples (which are split at the day
+boundary) are merged from each day its span covers.
+
+## Schema
+
+| Source         | Chronicle                                                                            |
+| -------------- | ------------------------------------------------------------------------------------ |
+| visit item     | `VisitAction` → `object: Venue`, `startTime`/`endTime`                               |
+| trip item      | `TravelAction` → `Journey` (`travelMode`, `distance`, `path`), `startTime`/`endTime` |
+| `places` entry | `Venue` (name, coordinates, `address`, `category`, `sameAs` to Foursquare/Google)    |
+
+A dictionary-backed place becomes a `Venue`; a visit Arc never matched to a
+place falls back to a coordinate-keyed `Place`. A venue's street address,
+locality, and country are folded into the freeform `address` (the geocoder
+resolves structured admin areas later); `category` comes from the place's
+Google primary type. A trip's GPS `samples` become the `Journey.path` track,
+and its `classifiedActivityType` enum is mapped to a `travelMode` name.
+
+### Not yet ingested
+
+The `notes` text is not read yet. The storage shape for free-text day notes is
+still being decided.
+
+## Development
+
+```bash
+npm install
+npm run build
+```
+
+Tests use synthetic daily backup files and an explicit `identity`, so they never
+read the host's Arc backup or iCloud account.

package/dist/activityTypes.d.ts

@@ -0,0 +1,3 @@
+export declare const ARC_ACTIVITY_TYPES: Record<number, string>;
+export declare function activityTypeName(code: number | undefined): string | undefined;
+//# sourceMappingURL=activityTypes.d.ts.map

package/dist/activityTypes.js

@@ -0,0 +1,50 @@
+// LocoKit2 `ActivityType` enum (Int rawValues) — the classifier codes Arc
+// stores in a trip's `classifiedActivityType` / `confirmedActivityType`.
+//
+// Source of truth (LocoKit2 is the engine behind Arc Timeline, sourceVersion 9):
+// https://github.com/sobri909/LocoKit2/blob/main/Sources/LocoKit2/ActivityTypes/ActivityType.swift
+//
+// `unknown` (-1) and `bogus` (0) carry no classification, so they are
+// intentionally omitted: an unrecognised or unclassified code yields no mode.
+// Multi-word values use the enum's own `displayName` spelling.
+export const ARC_ACTIVITY_TYPES = {
+    1: 'stationary',
+    2: 'walking',
+    3: 'running',
+    4: 'cycling',
+    5: 'car',
+    6: 'airplane',
+    20: 'train',
+    21: 'bus',
+    22: 'motorcycle',
+    23: 'boat',
+    24: 'tram',
+    25: 'tractor',
+    26: 'tuk-tuk',
+    27: 'songthaew',
+    28: 'scooter',
+    29: 'metro',
+    30: 'cable car',
+    31: 'funicular',
+    32: 'chairlift',
+    33: 'ski lift',
+    34: 'taxi',
+    35: 'hot air balloon',
+    50: 'skateboarding',
+    51: 'inline skating',
+    52: 'snowboarding',
+    53: 'skiing',
+    54: 'horseback',
+    55: 'swimming',
+    56: 'golf',
+    57: 'wheelchair',
+    58: 'rowing',
+    59: 'kayaking',
+    60: 'surfing',
+    61: 'hiking',
+};
+export function activityTypeName(code) {
+    if (code === undefined)
+        return undefined;
+    return ARC_ACTIVITY_TYPES[code];
+}

package/dist/connectors/ArcTimelineExtractor.d.ts

@@ -0,0 +1,41 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import ArcTimelineTransformer from './ArcTimelineTransformer.js';
+export declare class ArcTimelineExtractor extends Extractor<typeof ArcTimelineExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "local";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof ArcTimelineTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        input: z.ZodDefault<z.ZodString>;
+        identity: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        input: string;
+        identity?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }, {
+        input?: string | undefined;
+        identity?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }>;
+    extract(): AsyncGenerator<Record>;
+    private resolvePerson;
+    private loadSamples;
+    determineCount(): Promise<number | null>;
+    private indexPlaces;
+    private findDailyDir;
+    private listDayFiles;
+    private readDayFile;
+}
+//# sourceMappingURL=ArcTimelineExtractor.d.ts.map

package/dist/connectors/ArcTimelineExtractor.js

@@ -0,0 +1,264 @@
+import { Extractor } from '@chronicle.app/etl';
+import { buildICloudPersonSchema } from '@chronicle.app/icloud';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { z } from 'zod';
+import ArcTimelineTransformer from './ArcTimelineTransformer.js';
+// A daily backup file is named for the UTC day it covers ("YYYY-MM-DD.json.gz").
+const DAILY_FILE = /^(\d{4}-\d{2}-\d{2})\.json\.gz$/;
+// Arc Timeline's iCloud Drive container, where the app writes its daily backup.
+const DEFAULT_EXPORTS = `${process.env.HOME}/Library/Mobile Documents/iCloud~com~bigpaua~Arc-Timeline-Editor/Documents/Exports`;
+// The "YYYY-MM-DD" UTC key for a date; daily files are named by this key, so a
+// trip's samples can be loaded from just the day file(s) covering its span.
+function dayKey(date) {
+    return date.toISOString().slice(0, 10);
+}
+// The day keys (inclusive) that an item's [start, end] span touches — a trip
+// that crosses midnight has its samples split across each day's file.
+function coveringDayKeys(startDate, endDate) {
+    const start = new Date(startDate);
+    const endMs = new Date(endDate).getTime();
+    const keys = [];
+    for (let ms = Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate()); ms <= endMs; ms += 86_400_000) {
+        keys.push(dayKey(new Date(ms)));
+    }
+    return keys;
+}
+export class ArcTimelineExtractor extends Extractor {
+    // The CLI name matches the plugin's; records keep the `arc` namespace.
+    static source = 'arc-timeline';
+    static description = 'Location timeline: visits and trips';
+    static delivery = 'local';
+    // The strategy, in Arc's own vocabulary: the app's iCloud backup (the daily
+    // YYYY-MM-DD.json.gz folder) — "timeline" named the product, not the strategy.
+    static strategy = 'icloud-backup';
+    static recordTypes = ['visits', 'travels'];
+    static default = true;
+    static defaultTransformer = ArcTimelineTransformer;
+    static schema = Extractor.schema.extend({
+        input: z
+            .string()
+            .default(DEFAULT_EXPORTS)
+            .describe("Path to the Arc Timeline daily backup — the folder of YYYY-MM-DD.json.gz files, or a parent such as the iCloud Exports or Exports/Daily directory; defaults to Arc's iCloud Drive Exports folder"),
+        identity: z
+            .string()
+            .optional()
+            .describe('Override the person whose timeline this is (e.g. an email); defaults to the macOS iCloud account'),
+    });
+    async *extract() {
+        const config = this.config;
+        const person = await this.resolvePerson(config.identity);
+        // Pass 1: select the items to emit, reading day files newest-first. Each
+        // day's file is self-contained (its `places` resolve its visits), but an
+        // item that spans midnight appears in two adjacent files, so dedupe on the
+        // stable item id. `--limit N` yields the N most recent items, and the early
+        // break keeps a limited run from reading the whole archive.
+        const dir = await this.findDailyDir(config.input);
+        const dayFiles = await this.listDayFiles(dir);
+        const sinceKey = config.since ? dayKey(config.since) : undefined;
+        const untilKey = config.until ? dayKey(config.until) : undefined;
+        const seen = new Set();
+        const selected = [];
+        for (const { path, key } of dayFiles) {
+            // Day keys sort chronologically, so (newest-first) every remaining file
+            // is older than `since`; and any file newer than `until` holds nothing in
+            // range (an item's earliest day file is its start day).
+            if (sinceKey && key < sinceKey)
+                break;
+            if (untilKey && key > untilKey)
+                continue;
+            const day = await this.readDayFile(path);
+            const places = this.indexPlaces(day.places);
+            for (const item of day.items.reverse()) {
+                const { base } = item;
+                if (!base || base.deleted)
+                    continue;
+                if (seen.has(base.id))
+                    continue;
+                if (config.since || config.until) {
+                    const start = new Date(base.startDate);
+                    if (config.since && start < config.since)
+                        continue;
+                    if (config.until && start > config.until)
+                        continue;
+                }
+                if (item.visit || base.isVisit) {
+                    const place = item.visit?.placeId ? places.get(item.visit.placeId) : undefined;
+                    selected.push({ item, recordType: 'visits', place });
+                }
+                else if (item.trip) {
+                    selected.push({ item, recordType: 'travels' });
+                }
+                else {
+                    continue;
+                }
+                seen.add(base.id);
+                if (this.shouldStopExtracting(selected.length))
+                    break;
+            }
+            if (this.shouldStopExtracting(selected.length))
+                break;
+        }
+        // Load GPS samples for just the trips we'll emit, keyed by their item id.
+        const trips = selected.filter(s => s.recordType === 'travels').map(s => s.item);
+        const samplesByItem = await this.loadSamples(dir, trips);
+        this.logInitStep(`Emitting ${selected.length} items (${trips.length} trips, ${samplesByItem.size} with samples)`);
+        // Pass 2: emit. Trips carry their ordered samples; the transformer encodes
+        // them into the Journey's path.
+        for (const { item, recordType, place } of selected) {
+            if (recordType === 'visits') {
+                yield this.createRecord(item, { recordType, person, place });
+            }
+            else {
+                yield this.createRecord(item, {
+                    recordType,
+                    person,
+                    samples: samplesByItem.get(item.base.id),
+                });
+            }
+        }
+    }
+    // The person whose timeline this is: an explicit `--identity` override, else
+    // the macOS iCloud account (so Arc data merges onto the same person as other
+    // iCloud-sourced data). An override is keyed the same way, so it merges too.
+    async resolvePerson(identity) {
+        if (identity) {
+            return {
+                '@type': 'Person',
+                '@key': ['@type', 'source', 'sourceId'],
+                source: 'icloud',
+                sourceId: identity,
+                handle: identity,
+            };
+        }
+        return ((await buildICloudPersonSchema()) ?? {
+            '@type': 'Person',
+            '@key': ['@type', 'source'],
+            source: 'icloud',
+        });
+    }
+    // GPS samples for the given trips, grouped by `timelineItemId` and ordered by
+    // time. Only the day buckets covering the trips' spans are read, so a
+    // `--limit` run touches a handful of files; a midnight-spanning trip's samples
+    // are merged from each day its span touches.
+    async loadSamples(root, trips) {
+        const byItem = new Map();
+        if (trips.length === 0)
+            return byItem;
+        const wantIds = new Set(trips.map(t => t.base.id));
+        const dayKeys = new Set();
+        for (const t of trips) {
+            for (const key of coveringDayKeys(t.base.startDate, t.base.endDate)) {
+                dayKeys.add(key);
+            }
+        }
+        for (const key of dayKeys) {
+            let day;
+            try {
+                day = await this.readDayFile(join(root, `${key}.json.gz`));
+            }
+            catch {
+                continue; // Day file missing — trip predates the backup, or a gap.
+            }
+            for (const s of day.samples) {
+                if (!s.timelineItemId || !wantIds.has(s.timelineItemId))
+                    continue;
+                const arr = byItem.get(s.timelineItemId);
+                if (arr)
+                    arr.push(s);
+                else
+                    byItem.set(s.timelineItemId, [s]);
+            }
+        }
+        for (const samples of byItem.values()) {
+            samples.sort((a, b) => a.date.localeCompare(b.date));
+        }
+        return byItem;
+    }
+    async determineCount() {
+        const config = this.config;
+        try {
+            const dir = await this.findDailyDir(config.input);
+            const dayFiles = await this.listDayFiles(dir);
+            const sinceKey = config.since ? dayKey(config.since) : undefined;
+            const untilKey = config.until ? dayKey(config.until) : undefined;
+            // Count distinct items in range (midnight-spanning items appear in two
+            // files; the id set keeps the total honest).
+            const seen = new Set();
+            for (const { path, key } of dayFiles) {
+                if (sinceKey && key < sinceKey)
+                    break;
+                if (untilKey && key > untilKey)
+                    continue;
+                const day = await this.readDayFile(path);
+                for (const item of day.items) {
+                    const { base } = item;
+                    if (!base || base.deleted)
+                        continue;
+                    if (config.since && new Date(base.startDate) < config.since)
+                        continue;
+                    if (config.until && new Date(base.startDate) > config.until)
+                        continue;
+                    seen.add(base.id);
+                }
+            }
+            return config.limit ? Math.min(seen.size, config.limit) : seen.size;
+        }
+        catch {
+            return null;
+        }
+    }
+    // The day's place dictionary, keyed by place id, joined to visits via
+    // `visit.placeId`. Scoped to the day, but complete for that day's visits.
+    indexPlaces(places) {
+        const byId = new Map();
+        for (const place of places) {
+            if (place?.id)
+                byId.set(place.id, place);
+        }
+        return byId;
+    }
+    // Resolve the input to the directory that actually holds the day files. The
+    // input may be that directory, or a parent the user finds it easier to point
+    // at — the iCloud "Exports" folder or its "Daily" subfolder.
+    async findDailyDir(input) {
+        const candidates = [
+            input,
+            join(input, 'JSON'), // …/Daily
+            join(input, 'Daily', 'JSON'), // …/Exports
+        ];
+        for (const dir of candidates) {
+            let entries;
+            try {
+                entries = await readdir(dir);
+            }
+            catch {
+                continue; // Not a directory — try the next candidate.
+            }
+            if (entries.some(name => DAILY_FILE.test(name)))
+                return dir;
+        }
+        throw new Error(`No Arc Timeline daily backup files (YYYY-MM-DD.json.gz) found under ${input} ` +
+            `(looked in there, in JSON/, and in Daily/JSON/)`);
+    }
+    // The daily backup files in a resolved directory, sorted by their day key
+    // descending (newest first).
+    async listDayFiles(dir) {
+        const entries = await readdir(dir);
+        return entries
+            .map(name => DAILY_FILE.exec(name))
+            .filter((m) => m !== null)
+            .map(m => ({ path: join(dir, m[0]), key: m[1] }))
+            .sort((a, b) => b.key.localeCompare(a.key));
+    }
+    async readDayFile(path) {
+        const buf = await readFile(path);
+        const parsed = JSON.parse(gunzipSync(buf).toString('utf-8'));
+        return {
+            items: Array.isArray(parsed.items) ? parsed.items : [],
+            places: Array.isArray(parsed.places) ? parsed.places : [],
+            samples: Array.isArray(parsed.samples) ? parsed.samples : [],
+        };
+    }
+}

package/dist/connectors/ArcTimelineTransformer.d.ts

@@ -0,0 +1,13 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class ArcTimelineTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildVisit;
+    private buildTravel;
+    private buildPlace;
+    private buildVenue;
+    private buildLocation;
+    private buildPlaceSameAs;
+    private buildPlaceFromVisit;
+}
+//# sourceMappingURL=ArcTimelineTransformer.d.ts.map

package/dist/connectors/ArcTimelineTransformer.js

@@ -0,0 +1,140 @@
+import { ChronicleTransformer } from '@chronicle.app/etl';
+import { activityTypeName } from '../activityTypes.js';
+import { buildTrackFeature } from '../track.js';
+export default class ArcTimelineTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const context = record.context;
+        const item = record.data;
+        if (context.recordType === 'visits') {
+            return this.buildVisit(item, context.person, context.place);
+        }
+        if (context.recordType === 'travels') {
+            return this.buildTravel(item, context.person, context.samples);
+        }
+        return [];
+    }
+    buildVisit(item, person, place) {
+        const { visit } = item;
+        if (!visit)
+            return [];
+        const action = {
+            '@type': 'VisitAction',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'arc',
+            sourceId: item.base.id,
+            agent: person,
+            object: this.buildPlace(visit, place),
+            startTime: new Date(item.base.startDate),
+            endTime: new Date(item.base.endDate),
+        };
+        return [action];
+    }
+    buildTravel(item, person, samples) {
+        const { trip } = item;
+        // The action stays sparse; the detail lives on the Journey it produces.
+        // A user-confirmed activity type wins over the classifier's guess. The path
+        // is the trip's GPS trail as a GeoJSON track (when enough fixes exist).
+        const mode = activityTypeName(trip?.confirmedActivityType ?? trip?.classifiedActivityType);
+        const path = buildTrackFeature(samples);
+        const journey = {
+            '@type': 'Journey',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'arc',
+            sourceId: item.base.id,
+            ...(trip?.distance !== undefined && { distance: trip.distance }),
+            ...(mode && { travelMode: mode }),
+            ...(path && { path }),
+        };
+        const action = {
+            '@type': 'TravelAction',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'arc',
+            sourceId: item.base.id,
+            agent: person,
+            result: journey,
+            startTime: new Date(item.base.startDate),
+            endTime: new Date(item.base.endDate),
+        };
+        return [action];
+    }
+    buildPlace(visit, place) {
+        if (place)
+            return this.buildVenue(place);
+        return this.buildPlaceFromVisit(visit);
+    }
+    // A dictionary-backed Arc place is a named point of interest → a Venue. It
+    // carries the venue's category and sameAs edges to the foreign venue ids Arc
+    // resolved against. Raw locality/country stay as plain strings folded into the
+    // freeform address — they have no keyed City/Country entity here; the geocoder
+    // resolves those later, and raw strings live on `address`.
+    buildVenue(place) {
+        const sameAs = this.buildPlaceSameAs(place);
+        const address = [place.streetAddress, place.locality, place.countryCode?.toUpperCase()]
+            .filter(Boolean)
+            .join(', ');
+        return {
+            '@type': 'Venue',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'arc',
+            sourceId: place.id,
+            name: place.name,
+            // The venue's coordinates/address are its own Location value — a keyless
+            // (content-interned) geo node, not entity properties on the Venue.
+            location: this.buildLocation(place.latitude, place.longitude, address),
+            ...(place.googlePrimaryType && { category: [place.googlePrimaryType] }),
+            ...(sameAs.length > 0 && { sameAs }),
+        };
+    }
+    // The geo as a `Location` value — a keyless StructuredValue that shred
+    // content-interns into location_values (deduped by payload). Raw
+    // locality/country are folded into the freeform address by the caller; the
+    // geocoder resolves structured admin areas later.
+    buildLocation(latitude, longitude, address) {
+        return {
+            '@type': 'Location',
+            latitude,
+            longitude,
+            ...(address && { address }),
+        };
+    }
+    // Arc's place dictionary carries the external venue ids it resolved a place
+    // against. Emit a sameAs edge per id so the Arc venue collapses into the same
+    // entity as the foreign source's own Venue (which keys identically on
+    // [@type, source, sourceId]). The id is a real handle from the export — never
+    // synthesized — and each edge carries the title so a yet-unseen foreign venue
+    // still has a name when this edge is what mints it.
+    buildPlaceSameAs(place) {
+        const edges = [
+            { source: 'foursquare', sourceId: place.foursquarePlaceId },
+            { source: 'google-places', sourceId: place.googlePlaceId },
+        ];
+        return edges
+            .filter((edge) => Boolean(edge.sourceId))
+            .map(edge => ({
+            '@type': 'Venue',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: edge.source,
+            sourceId: edge.sourceId,
+            name: place.name,
+        }));
+    }
+    buildPlaceFromVisit(visit) {
+        // No dictionary entry — a coordinate-identified place. Key on the visit's
+        // coordinates via computed keyfields (a natural key, never synthesized) so
+        // repeat visits to the same spot merge; the geo itself is a nested Location
+        // value, like every other place's.
+        const name = visit.customTitle ?? visit.streetAddress;
+        return {
+            '@type': 'Place',
+            '@key': [
+                '@type',
+                'source',
+                { key: 'lat', value: String(visit.latitude) },
+                { key: 'lng', value: String(visit.longitude) },
+            ],
+            source: 'arc',
+            ...(name && { name }),
+            location: this.buildLocation(visit.latitude, visit.longitude, visit.streetAddress),
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ArcTimelineExtractor } from './connectors/ArcTimelineExtractor.js';
+export { default as ArcTimelineTransformer } from './connectors/ArcTimelineTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ArcTimelineExtractor } from './connectors/ArcTimelineExtractor.js';
+export { default as ArcTimelineTransformer } from './connectors/ArcTimelineTransformer.js';

package/dist/track.d.ts

@@ -0,0 +1,3 @@
+import { ArcSample } from './types.js';
+export declare function buildTrackFeature(samples: ArcSample[] | undefined): string | undefined;
+//# sourceMappingURL=track.d.ts.map

package/dist/track.js

@@ -0,0 +1,31 @@
+// A trip's GPS trail as a GeoJSON `Feature` (LineString) with per-point time,
+// speed, and course carried in `properties` via the Mapbox `coordTimes`
+// convention — so it round-trips to GPX (togpx) and renders directly. Stored
+// verbatim as the Journey's `path` (a JSON string in a Text property).
+//
+// Returns undefined when there aren't at least two located fixes to form a line.
+export function buildTrackFeature(samples) {
+    if (!samples || samples.length === 0)
+        return undefined;
+    const fixes = samples
+        .filter(s => typeof s.latitude === 'number' && typeof s.longitude === 'number')
+        .sort((a, b) => a.date.localeCompare(b.date));
+    if (fixes.length < 2)
+        return undefined;
+    const coordinates = [];
+    const coordTimes = [];
+    const speeds = [];
+    const courses = [];
+    for (const s of fixes) {
+        coordinates.push([s.longitude, s.latitude]);
+        coordTimes.push(s.date);
+        // Arc encodes unknown speed/course as -1; null keeps the arrays aligned.
+        speeds.push(typeof s.speed === 'number' && s.speed >= 0 ? s.speed : null);
+        courses.push(typeof s.course === 'number' && s.course >= 0 ? s.course : null);
+    }
+    return JSON.stringify({
+        type: 'Feature',
+        geometry: { type: 'LineString', coordinates },
+        properties: { coordTimes, speeds, courses },
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+import { AgentAndChildren } from '@chronicle.app/schema';
+export interface ArcItemBase {
+    id: string;
+    startDate: string;
+    endDate: string;
+    isVisit: boolean;
+    source: string;
+    sourceVersion?: string;
+    deleted?: boolean;
+    disabled?: boolean;
+    locked?: boolean;
+    samplesChanged?: boolean;
+    lastSaved?: string;
+    previousItemId?: string;
+    nextItemId?: string;
+    stepCount?: number;
+    averageHeartRate?: number;
+    maxHeartRate?: number;
+    activeEnergyBurned?: number;
+}
+export interface ArcTrip {
+    itemId: string;
+    distance?: number;
+    speed?: number;
+    classifiedActivityType?: number;
+    confirmedActivityType?: number;
+    uncertainActivityType?: boolean;
+    lastSaved?: string;
+}
+export interface ArcVisit {
+    itemId: string;
+    placeId?: string;
+    latitude: number;
+    longitude: number;
+    streetAddress?: string;
+    customTitle?: string;
+    radiusMean?: number;
+    radiusSD?: number;
+    confirmedPlace?: boolean;
+    uncertainPlace?: boolean;
+    lastSaved?: string;
+}
+export interface ArcItem {
+    base: ArcItemBase;
+    trip?: ArcTrip;
+    visit?: ArcVisit;
+}
+export interface ArcSample {
+    timelineItemId?: string;
+    date: string;
+    latitude?: number;
+    longitude?: number;
+    speed?: number;
+    course?: number;
+}
+export interface ArcPlace {
+    id: string;
+    name: string;
+    latitude: number;
+    longitude: number;
+    streetAddress?: string;
+    locality?: string;
+    countryCode?: string;
+    secondsFromGMT?: number;
+    visitCount?: number;
+    visitDays?: number;
+    lastVisitDate?: string;
+    isStale?: boolean;
+    source?: string;
+    lastSaved?: string;
+    foursquarePlaceId?: string;
+    foursquareCategoryId?: string;
+    googlePlaceId?: string;
+    googlePrimaryType?: string;
+    mapboxPlaceId?: string;
+    mapboxCategory?: string;
+    mapboxMakiIcon?: string;
+}
+export interface DailyExport {
+    items: ArcItem[];
+    places: ArcPlace[];
+    samples: ArcSample[];
+    periodStart?: string;
+    periodEnd?: string;
+    periodId?: string;
+}
+export interface ArcRecordContext {
+    recordType: 'visits' | 'travels';
+    person: AgentAndChildren;
+    place?: ArcPlace;
+    samples?: ArcSample[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@chronicle.app/arc-timeline",
+  "version": "0.3.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [
+    "chronicle",
+    "arc-timeline"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for location tracking data from Arc timeline database",
+  "devDependencies": {
+    "@chronicle.app/etl": "0.3.0",
+    "@chronicle.app/schema": "0.3.0",
+    "@chronicle.app/tsconfig": "0.3.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "plugins/arc-timeline"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@chronicle.app/icloud": "0.3.0",
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "@chronicle.app/etl": ">=0.1.0 <1.0.0",
+    "@chronicle.app/schema": ">=0.1.0 <1.0.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "chronicle": {
+    "plugin": true,
+    "sources": {
+      "arc-timeline": {
+        "strategies": {
+          "icloud-backup": {
+            "delivery": "local",
+            "recordTypes": [
+              "visits",
+              "travels"
+            ],
+            "default": true
+          }
+        },
+        "platforms": [
+          "darwin"
+        ]
+      }
+    }
+  }
+}