@chronicle.app/foursquare 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,86 @@
+# @chronicle.app/foursquare
+
+Chronicle plugin that imports your Foursquare/Swarm check-in history.
+
+## Installation
+
+```bash
+npm install @chronicle.app/foursquare
+```
+
+## Authentication
+
+Check-ins come from the authenticated user (`users/self/checkins`), so the
+plugin needs a user OAuth access token. Register a Foursquare developer app to
+get a client ID/secret, set its redirect URI to `http://127.0.0.1:7463/callback`,
+then run:
+
+```bash
+chronicle auth login foursquare --client-id YOUR_ID --client-secret YOUR_SECRET
+```
+
+This stores the access token; the extractor picks it up automatically. You can
+also pass a token directly with `--access-token`.
+
+## Usage
+
+```bash
+# Uses the stored token from `auth login`
+chronicle extract foursquare
+
+# With a token and date/size filters
+chronicle extract foursquare --strategy api \
+  --access-token YOUR_TOKEN \
+  --since 2024-01-01 \
+  --limit 1000
+```
+
+## Configuration
+
+The extractor supports the following options:
+
+- `--access-token`: Foursquare user OAuth token (auto-retrieved from stored
+  credentials if omitted)
+- `--since`: Only check-ins on or after this date
+- `--limit`: Maximum number of check-ins to extract
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the plugin
+npm run build -w @chronicle.app/foursquare
+
+# Run the tests
+npm test -w @chronicle.app/foursquare
+```
+
+## API Endpoints
+
+- `users/self`: the authenticated user (actor), for the check-in agent
+- `users/self/checkins`: check-in history, paged (50/page) with `afterTimestamp`
+  for `--since`
+
+## Chronicle schema output
+
+Each check-in becomes a `CheckInAction` (keyed on the check-in id, timestamped at
+`createdAt`) whose:
+
+- `agent` is an `Agent` keyed on your Foursquare user id, with name, profile
+  `url`, and avatar `image`
+- `object` is a `Venue` keyed on the Foursquare venue id, with `category` (the
+  venue's Foursquare categories) and a nested keyless `Location` (lat/long +
+  formatted address)
+
+Because the `Venue` is keyed on `[@type, source: foursquare, sourceId]`, it
+collapses onto the same entity as an Arc Timeline place that carries a `sameAs`
+edge to the same Foursquare venue id.
+
+## Tests
+
+The tests serve synthetic `users/self` and check-in responses from a local HTTP
+server on 127.0.0.1, pass a fake access token in config, and point Chronicle's
+credential store at an empty temporary directory, so they never call Foursquare
+or read the host's stored credentials or accounts.

package/dist/auth/FoursquareOAuthProvider.d.ts

@@ -0,0 +1,9 @@
+import { OAuthProvider } from '@chronicle.app/auth';
+export declare class FoursquareOAuthProvider extends OAuthProvider {
+    static providerId: string;
+    static authorizationUrl: string;
+    static tokenUrl: string;
+    static scopes: string[];
+    static requiresClientSecret: boolean;
+}
+//# sourceMappingURL=FoursquareOAuthProvider.d.ts.map

package/dist/auth/FoursquareOAuthProvider.js

@@ -0,0 +1,8 @@
+import { OAuthProvider } from '@chronicle.app/auth';
+export class FoursquareOAuthProvider extends OAuthProvider {
+    static providerId = 'foursquare';
+    static authorizationUrl = 'https://foursquare.com/oauth2/authenticate';
+    static tokenUrl = 'https://foursquare.com/oauth2/access_token';
+    static scopes = [];
+    static requiresClientSecret = true;
+}

package/dist/connectors/FoursquareExtractor.d.ts

@@ -0,0 +1,35 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import FoursquareTransformer from './FoursquareTransformer.js';
+export declare class FoursquareExtractor extends Extractor<typeof FoursquareExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "api";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof FoursquareTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        'access-token': z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        'access-token'?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }, {
+        limit?: number | undefined;
+        'access-token'?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }>;
+    private proxy;
+    private actor;
+    setup(): Promise<void>;
+    extract(): AsyncGenerator<Record>;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=FoursquareExtractor.d.ts.map

package/dist/connectors/FoursquareExtractor.js

@@ -0,0 +1,54 @@
+import { Extractor } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { resolveCredentials } from '@chronicle.app/auth';
+import FoursquareProxy from '../utils/FoursquareProxy.js';
+import FoursquareTransformer from './FoursquareTransformer.js';
+export class FoursquareExtractor extends Extractor {
+    static source = 'foursquare';
+    static description = 'Check-ins';
+    static delivery = 'api';
+    static strategy = 'api';
+    static recordTypes = ['checkins'];
+    static default = true;
+    static defaultTransformer = FoursquareTransformer;
+    static schema = Extractor.schema.extend({
+        'access-token': z
+            .string()
+            .optional()
+            .describe('Foursquare access token (auto-retrieved from stored credentials if not provided)'),
+    });
+    proxy;
+    actor;
+    async setup() {
+        const config = this.config;
+        // Use the token from the flag, else the one stored by `auth login foursquare`.
+        const { accessToken } = await resolveCredentials('foursquare', {
+            accessToken: { from: ['accessToken'] },
+        }, {
+            overrides: { accessToken: config['access-token'] },
+            errorMessage: 'Foursquare access token is required. Either pass --access-token or authenticate with: chronicle auth login foursquare --client-id YOUR_ID --client-secret YOUR_SECRET',
+        });
+        this.proxy = new FoursquareProxy(accessToken);
+        this.actor = await this.proxy.loadSelf();
+    }
+    async *extract() {
+        const config = this.config;
+        try {
+            const checkins = await this.proxy.loadCheckins({
+                since: config.since,
+                limit: config.limit,
+            });
+            this.logger.info(`Retrieved ${checkins.length} checkins from Foursquare`);
+            for (const checkin of checkins) {
+                yield this.createRecord(checkin, { actor: this.actor });
+            }
+        }
+        catch (error) {
+            this.logger.error('Error fetching Foursquare checkins');
+            throw error;
+        }
+    }
+    async determineCount() {
+        return null;
+    }
+}

package/dist/connectors/FoursquareTransformer.d.ts

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

package/dist/connectors/FoursquareTransformer.js

@@ -0,0 +1,78 @@
+import { ChronicleTransformer, createImageObject } from '@chronicle.app/etl';
+export default class FoursquareTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        if (record.extraction.recordType === 'checkins') {
+            actions.push(...this.buildCheckinActions(record));
+        }
+        return actions;
+    }
+    buildCheckinActions(record) {
+        const actions = [];
+        const checkin = record.data;
+        const actor = record.context?.actor;
+        const user = this.buildUser(actor);
+        const venue = this.buildVenue(checkin);
+        const action = {
+            '@type': 'CheckInAction',
+            '@key': ['@type', 'source', 'sourceId'],
+            timestamp: new Date(checkin.createdAt * 1000),
+            source: 'foursquare',
+            sourceId: checkin.id,
+            agent: user,
+            object: venue,
+        };
+        actions.push(action);
+        return actions;
+    }
+    // A Foursquare venue is a named point of interest → a Venue. Its
+    // coordinates/address are its own keyless Location value (content-interned),
+    // not entity properties on the Venue. Keyed [@type, source, sourceId] with
+    // source "foursquare", so an Arc place's sameAs edge to this id collapses onto
+    // the same entity.
+    buildVenue(checkin) {
+        const { venue } = checkin;
+        const { location } = venue;
+        const address = location.formattedAddress ? location.formattedAddress.join(', ') : undefined;
+        // Foursquare's category names (the primary one first), e.g. ["Park"].
+        const category = [...(venue.categories ?? [])]
+            .sort((a, b) => (b.primary ? 1 : 0) - (a.primary ? 1 : 0))
+            .map(c => c.name)
+            .filter(Boolean);
+        return {
+            '@type': 'Venue',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'foursquare',
+            sourceId: venue.id,
+            name: venue.name,
+            location: this.buildLocation(location.lat, location.lng, address),
+            ...(category.length > 0 && { category }),
+        };
+    }
+    // The geo as a `Location` value — a keyless StructuredValue that shred
+    // content-interns into location_values (deduped by payload).
+    buildLocation(latitude, longitude, address) {
+        return {
+            '@type': 'Location',
+            latitude,
+            longitude,
+            ...(address && { address }),
+        };
+    }
+    buildUser(actor) {
+        // Foursquare photo URLs are assembled as `${prefix}${size}${suffix}`.
+        const avatar = actor.photo?.prefix
+            ? `${actor.photo.prefix}300x300${actor.photo.suffix}`
+            : undefined;
+        return {
+            '@type': 'Agent',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'foursquare',
+            sourceId: actor.id,
+            name: `${actor.firstName} ${actor.lastName}`,
+            url: actor.canonicalUrl,
+            sameAs: ['@me'],
+            ...(avatar && { emblem: createImageObject({ url: avatar }) }),
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { FoursquareExtractor } from './connectors/FoursquareExtractor.js';
+export { default as FoursquareTransformer } from './connectors/FoursquareTransformer.js';
+export { FoursquareOAuthProvider } from './auth/FoursquareOAuthProvider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,7 @@
+export { FoursquareExtractor } from './connectors/FoursquareExtractor.js';
+export { default as FoursquareTransformer } from './connectors/FoursquareTransformer.js';
+export { FoursquareOAuthProvider } from './auth/FoursquareOAuthProvider.js';
+// Register OAuth provider
+import { OAuthProviderRegistry } from '@chronicle.app/auth';
+import { FoursquareOAuthProvider } from './auth/FoursquareOAuthProvider.js';
+OAuthProviderRegistry.register(FoursquareOAuthProvider);

package/dist/utils/FoursquareProxy.d.ts

@@ -0,0 +1,48 @@
+import { ApiProxy } from '@chronicle.app/etl';
+export interface FoursquareCategory {
+    id: string;
+    name: string;
+    primary?: boolean;
+}
+export interface FoursquareCheckin {
+    id: string;
+    createdAt: number;
+    venue: {
+        id: string;
+        name: string;
+        categories?: FoursquareCategory[];
+        location: {
+            lat: number;
+            lng: number;
+            formattedAddress?: string[];
+            country?: string;
+            city?: string;
+            state?: string;
+            postalCode?: string;
+            address?: string;
+        };
+    };
+}
+export interface FoursquareUser {
+    id: string;
+    firstName: string;
+    lastName: string;
+    canonicalUrl: string;
+    photo: {
+        prefix: string;
+        suffix: string;
+    };
+}
+export default class FoursquareProxy extends ApiProxy {
+    private oauthToken;
+    constructor(accessToken: string);
+    initialize(): Promise<void>;
+    loadCheckins(options?: {
+        since?: Date;
+        limit?: number;
+    }): Promise<FoursquareCheckin[]>;
+    loadSelf(): Promise<FoursquareUser>;
+    private loadCheckinPage;
+    private loadEndpoint;
+}
+//# sourceMappingURL=FoursquareProxy.d.ts.map

package/dist/utils/FoursquareProxy.js

@@ -0,0 +1,54 @@
+import { ApiProxy } from '@chronicle.app/etl';
+const API_VERSION = 20_170_310;
+export default class FoursquareProxy extends ApiProxy {
+    // Foursquare authenticates with an `oauth_token` query parameter, not a
+    // bearer header, so the token lives here and the base's accessToken stays unset.
+    oauthToken;
+    constructor(accessToken) {
+        super({
+            baseURL: 'https://api.foursquare.com/v2/',
+            headers: {
+                'User-Agent': 'Chronicle/1.0',
+                'Content-Type': 'application/json',
+            },
+        });
+        this.oauthToken = accessToken;
+    }
+    async initialize() {
+        // The access token is resolved by the extractor's own CredentialManager
+        // lookup and handed to the constructor; nothing to load lazily here.
+    }
+    async loadCheckins(options = {}) {
+        return this.paginateOffset({
+            pageSize: 50,
+            limit: options.limit,
+            fetchPage: offset => this.loadCheckinPage({ limit: 50, offset, since: options.since }),
+        });
+    }
+    async loadSelf() {
+        const response = await this.loadEndpoint('users/self');
+        return response.response.user;
+    }
+    async loadCheckinPage(options) {
+        const params = {
+            limit: options.limit,
+            offset: options.offset,
+        };
+        if (options.since) {
+            params.afterTimestamp = Math.floor(options.since.getTime() / 1000);
+        }
+        const response = await this.loadEndpoint('users/self/checkins', params);
+        return response.response.checkins.items;
+    }
+    async loadEndpoint(endpoint, params = {}) {
+        return this.request({
+            url: endpoint,
+            method: 'GET',
+            params: {
+                ...params,
+                oauth_token: this.oauthToken,
+                v: API_VERSION,
+            },
+        });
+    }
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@chronicle.app/foursquare",
+  "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",
+    "foursquare"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for Foursquare check-ins",
+  "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/foursquare"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@chronicle.app/auth": "0.3.0",
+    "axios": "^1.7.9",
+    "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": {
+      "foursquare": {
+        "strategies": {
+          "api": {
+            "delivery": "api",
+            "recordTypes": [
+              "checkins"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}