@chronicle.app/spotify 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,107 @@
+# Chronicle Spotify Plugin
+
+Extract listening history, saved tracks, and playlists from Spotify using OAuth authentication.
+
+## Features
+
+- **Recently Played**: Extract your recent listening history
+- **Saved Tracks**: Extract your liked/saved tracks
+- **Saved Albums**: Extract your saved/liked albums
+- **Playlists**: Extract your playlists and their metadata
+- **OAuth Authentication**: Secure authentication via Spotify OAuth 2.0
+
+## Setup
+
+### 1. Create Spotify App
+
+1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
+2. Create a new app
+3. Note your **Client ID** and **Client Secret**
+4. Add `http://127.0.0.1:7463/callback` to your app's redirect URIs (use 127.0.0.1 for Spotify's OAuth validation, port 7463 is Chronicle's default)
+
+### 2. Authenticate
+
+Run the OAuth flow to get an access token:
+
+```bash
+chronicle auth login spotify --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
+```
+
+This will open your browser to authenticate with Spotify and store your access token.
+
+### 3. Extract Data
+
+Chronicle automatically uses your stored credentials and reads every record type unless you pass `--type`:
+
+```bash
+chronicle extract spotify
+```
+
+You can also manually provide a token:
+
+```bash
+chronicle extract spotify --access-token YOUR_ACCESS_TOKEN
+```
+
+## Credential Management
+
+Chronicle stores your OAuth credentials in `~/.config/chronicle/credentials.json` for easy access. You can manage them with:
+
+```bash
+# Check stored credentials
+chronicle auth list
+
+# Check status of Spotify credentials
+chronicle auth status spotify
+
+# Remove stored credentials (requires re-authentication)
+chronicle auth remove spotify
+```
+
+## Configuration Options
+
+- `--access-token` (optional): OAuth access token (auto-retrieved from secure storage if not provided)
+- `--limit` (default: 100): Limit the number of records extracted (use 0 for no limit)
+- `--since` (optional): Extract records since this date
+- `--until` (optional): Extract records until this date
+
+## Example Usage
+
+```bash
+# Extract every record type
+chronicle extract spotify
+
+# Extract one record type
+chronicle extract spotify --type listens
+
+# Extract with limits and date ranges
+chronicle extract spotify --limit 50
+chronicle extract spotify --since 2024-01-01
+chronicle extract spotify --until 2024-12-31
+
+# Use a specific access token (overrides stored credentials)
+chronicle extract spotify --access-token YOUR_TOKEN
+```
+
+## Data Types
+
+The plugin extracts the following record types and transforms them into Chronicle actions:
+
+- `listen` → `ListenAction`: Tracks you've recently listened to
+- `like` → `LikeAction`: Tracks and albums you've saved/liked
+- `playlist-track` → `AddAction`: Tracks added to your playlists
+
+## Spotify API Scopes
+
+The plugin requests these OAuth scopes:
+
+- `user-read-recently-played`: Access recently played tracks
+- `user-library-read`: Access saved tracks and albums
+- `playlist-read-private`: Access private playlists
+- `playlist-read-collaborative`: Access collaborative playlists
+
+## Tests
+
+The tests run each extractor and the transformer against synthetic Spotify API
+responses served from a local HTTP server on 127.0.0.1, with a fake access token
+passed in the config. They never call Spotify or read stored credentials.

package/dist/auth/SpotifyOAuthProvider.d.ts

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

package/dist/auth/SpotifyOAuthProvider.js

@@ -0,0 +1,17 @@
+import { OAuthProvider } from '@chronicle.app/auth';
+export class SpotifyOAuthProvider extends OAuthProvider {
+    static providerId = 'spotify';
+    static authorizationUrl = 'https://accounts.spotify.com/authorize';
+    static tokenUrl = 'https://accounts.spotify.com/api/token';
+    static scopes = [
+        'user-read-recently-played',
+        'user-read-playback-state',
+        'user-read-currently-playing',
+        'user-top-read',
+        'user-library-read',
+        'playlist-read-private',
+        'playlist-read-collaborative',
+    ];
+    static requiresClientSecret = true;
+    static tokenAuthStyle = 'basic-header';
+}

package/dist/connectors/SpotifyBaseExtractor.d.ts

@@ -0,0 +1,43 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import SpotifyTransformer from './SpotifyTransformer.js';
+import SpotifyProxy, { SpotifyUser } from '../utils/SpotifyProxy.js';
+export declare abstract class SpotifyBaseExtractor<T extends typeof SpotifyBaseExtractor> extends Extractor<T> {
+    static source: string;
+    static description: string;
+    static delivery: "api";
+    static strategy: string;
+    static defaultTransformer: typeof SpotifyTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        accessToken: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }>;
+    protected proxy: SpotifyProxy;
+    protected user?: SpotifyUser;
+    /**
+     * Check if valid Spotify credentials are available
+     */
+    static hasValidCredentials(): Promise<boolean>;
+    setup(): Promise<void>;
+    /**
+     * Create a record with user context
+     */
+    protected createRecordWithUser(data: any, options: {
+        recordType: string;
+    }): Record;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=SpotifyBaseExtractor.d.ts.map

package/dist/connectors/SpotifyBaseExtractor.js

@@ -0,0 +1,57 @@
+import { Extractor } from '@chronicle.app/etl';
+import { TokenHelper } from '@chronicle.app/auth';
+import { z } from 'zod';
+import SpotifyTransformer from './SpotifyTransformer.js';
+import SpotifyProxy from '../utils/SpotifyProxy.js';
+export class SpotifyBaseExtractor extends Extractor {
+    static source = 'spotify';
+    static description = 'Base extractor for Spotify data';
+    static delivery = 'api';
+    static strategy = 'api';
+    static defaultTransformer = SpotifyTransformer;
+    static schema = Extractor.schema.extend({
+        accessToken: z
+            .string()
+            .optional()
+            .describe('OAuth access token for Spotify API authentication (auto-retrieved if not provided)'),
+    });
+    proxy;
+    user;
+    /**
+     * Check if valid Spotify credentials are available
+     */
+    static async hasValidCredentials() {
+        try {
+            await TokenHelper.getValidToken('spotify');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async setup() {
+        const config = this.config;
+        // SpotifyProxy will automatically handle token retrieval from storage
+        // Only pass accessToken if explicitly provided by user
+        this.proxy = new SpotifyProxy(config.accessToken);
+        // Get user info for use in transformations
+        this.user = await this.proxy.getUser();
+    }
+    /**
+     * Create a record with user context
+     */
+    createRecordWithUser(data, options) {
+        return this.createRecord(data, {
+            recordType: options.recordType,
+            user: this.user,
+        });
+    }
+    async determineCount() {
+        try {
+            return await this.proxy.getTotalItemCount();
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/connectors/SpotifyPlaylistsExtractor.d.ts

@@ -0,0 +1,26 @@
+import { Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { SpotifyBaseExtractor } from './SpotifyBaseExtractor.js';
+export declare class SpotifyPlaylistsExtractor extends SpotifyBaseExtractor<typeof SpotifyPlaylistsExtractor> {
+    static description: string;
+    static recordTypes: string[];
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        accessToken: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }>;
+    extract(): AsyncGenerator<Record>;
+}
+//# sourceMappingURL=SpotifyPlaylistsExtractor.d.ts.map

package/dist/connectors/SpotifyPlaylistsExtractor.js

@@ -0,0 +1,43 @@
+import { SpotifyBaseExtractor } from './SpotifyBaseExtractor.js';
+export class SpotifyPlaylistsExtractor extends SpotifyBaseExtractor {
+    static description = 'Tracks added to playlists';
+    static recordTypes = ['playlist-tracks'];
+    static schema = SpotifyBaseExtractor.schema.extend({
+    // No additional schema - inherits limit from base Extractor
+    });
+    async *extract() {
+        const config = this.config;
+        try {
+            let recordCount = 0;
+            const maxRecords = config.limit || Number.POSITIVE_INFINITY;
+            const playlists = await this.proxy.getPlaylists();
+            for (const playlist of playlists) {
+                if (this.shouldStopExtracting(recordCount))
+                    break;
+                const tracks = await this.proxy.getPlaylistTracks(playlist.id, maxRecords - recordCount);
+                for (const trackItem of tracks) {
+                    if (this.shouldStopExtracting(recordCount))
+                        break;
+                    if (!trackItem.added_at) {
+                        continue;
+                    }
+                    yield this.createRecordWithUser({
+                        ...trackItem,
+                        playlist: {
+                            id: playlist.id,
+                            name: playlist.name,
+                            external_urls: playlist.external_urls,
+                        },
+                    }, {
+                        recordType: 'playlist-tracks',
+                    });
+                    recordCount++;
+                }
+            }
+        }
+        catch (error) {
+            this.logger.error('Error extracting Spotify playlists data');
+            throw error;
+        }
+    }
+}

package/dist/connectors/SpotifyRecentlyPlayedExtractor.d.ts

@@ -0,0 +1,27 @@
+import { Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { SpotifyBaseExtractor } from './SpotifyBaseExtractor.js';
+export declare class SpotifyRecentlyPlayedExtractor extends SpotifyBaseExtractor<typeof SpotifyRecentlyPlayedExtractor> {
+    static description: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        accessToken: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }>;
+    extract(): AsyncGenerator<Record>;
+}
+//# sourceMappingURL=SpotifyRecentlyPlayedExtractor.d.ts.map

package/dist/connectors/SpotifyRecentlyPlayedExtractor.js

@@ -0,0 +1,32 @@
+import { SpotifyBaseExtractor } from './SpotifyBaseExtractor.js';
+export class SpotifyRecentlyPlayedExtractor extends SpotifyBaseExtractor {
+    static description = 'Recently played tracks';
+    static recordTypes = ['listens'];
+    static default = true;
+    static schema = SpotifyBaseExtractor.schema.extend({
+    // No additional schema - inherits since/until/limit from base Extractor
+    });
+    async *extract() {
+        const config = this.config;
+        try {
+            let recordCount = 0;
+            const items = await this.proxy.getRecentlyPlayed({
+                since: config.since,
+                until: config.until,
+                limit: config.limit,
+            });
+            for (const item of items) {
+                if (this.shouldStopExtracting(recordCount))
+                    break;
+                yield this.createRecordWithUser(item, {
+                    recordType: 'listens',
+                });
+                recordCount++;
+            }
+        }
+        catch (error) {
+            this.logger.error('Error extracting Spotify recently played data');
+            throw error;
+        }
+    }
+}

package/dist/connectors/SpotifySavedAlbumsExtractor.d.ts

@@ -0,0 +1,26 @@
+import { Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { SpotifyBaseExtractor } from './SpotifyBaseExtractor.js';
+export declare class SpotifySavedAlbumsExtractor extends SpotifyBaseExtractor<typeof SpotifySavedAlbumsExtractor> {
+    static description: string;
+    static recordTypes: string[];
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        accessToken: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }>;
+    extract(): AsyncGenerator<Record>;
+}
+//# sourceMappingURL=SpotifySavedAlbumsExtractor.d.ts.map

package/dist/connectors/SpotifySavedAlbumsExtractor.js

@@ -0,0 +1,27 @@
+import { SpotifyBaseExtractor } from './SpotifyBaseExtractor.js';
+export class SpotifySavedAlbumsExtractor extends SpotifyBaseExtractor {
+    static description = 'Saved albums';
+    static recordTypes = ['saved-albums'];
+    static schema = SpotifyBaseExtractor.schema.extend({
+    // No additional schema - inherits limit from base Extractor
+    });
+    async *extract() {
+        const config = this.config;
+        try {
+            let recordCount = 0;
+            const items = await this.proxy.getSavedAlbums(config.limit);
+            for (const item of items) {
+                if (this.shouldStopExtracting(recordCount))
+                    break;
+                yield this.createRecordWithUser(item, {
+                    recordType: 'saved-albums',
+                });
+                recordCount++;
+            }
+        }
+        catch (error) {
+            this.logger.error('Error extracting Spotify saved albums data');
+            throw error;
+        }
+    }
+}

package/dist/connectors/SpotifySavedTracksExtractor.d.ts

@@ -0,0 +1,26 @@
+import { Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { SpotifyBaseExtractor } from './SpotifyBaseExtractor.js';
+export declare class SpotifySavedTracksExtractor extends SpotifyBaseExtractor<typeof SpotifySavedTracksExtractor> {
+    static description: string;
+    static recordTypes: string[];
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        accessToken: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }, {
+        limit?: number | undefined;
+        accessToken?: string | undefined;
+        since?: Date | undefined;
+        until?: Date | undefined;
+    }>;
+    extract(): AsyncGenerator<Record>;
+}
+//# sourceMappingURL=SpotifySavedTracksExtractor.d.ts.map

package/dist/connectors/SpotifySavedTracksExtractor.js

@@ -0,0 +1,27 @@
+import { SpotifyBaseExtractor } from './SpotifyBaseExtractor.js';
+export class SpotifySavedTracksExtractor extends SpotifyBaseExtractor {
+    static description = 'Saved tracks';
+    static recordTypes = ['saved-tracks'];
+    static schema = SpotifyBaseExtractor.schema.extend({
+    // No additional schema - inherits limit from base Extractor
+    });
+    async *extract() {
+        const config = this.config;
+        try {
+            let recordCount = 0;
+            const items = await this.proxy.getSavedTracks(config.limit);
+            for (const item of items) {
+                if (this.shouldStopExtracting(recordCount))
+                    break;
+                yield this.createRecordWithUser(item, {
+                    recordType: 'saved-tracks',
+                });
+                recordCount++;
+            }
+        }
+        catch (error) {
+            this.logger.error('Error extracting Spotify saved tracks data');
+            throw error;
+        }
+    }
+}

package/dist/connectors/SpotifyTransformer.d.ts

@@ -0,0 +1,14 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class SpotifyTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildListenActions;
+    private buildSaveActions;
+    private buildPlaylistTrackActions;
+    private buildMusicRecording;
+    private buildMusicGroup;
+    private buildPlaylistEntity;
+    private buildMusicAlbum;
+    private buildUser;
+}
+//# sourceMappingURL=SpotifyTransformer.d.ts.map

package/dist/connectors/SpotifyTransformer.js

@@ -0,0 +1,187 @@
+import { ChronicleTransformer, createImageObject } from '@chronicle.app/etl';
+export default class SpotifyTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        switch (record.extraction.recordType) {
+            case 'listens':
+                actions.push(...this.buildListenActions(record));
+                break;
+            case 'saved-tracks':
+            case 'saved-albums':
+                actions.push(...this.buildSaveActions(record));
+                break;
+            case 'playlist-tracks':
+                actions.push(...this.buildPlaylistTrackActions(record));
+                break;
+        }
+        return actions;
+    }
+    buildListenActions(record) {
+        const { data } = record;
+        const user = this.buildUser(record);
+        const track = this.buildMusicRecording(data.track);
+        const action = {
+            '@type': 'ListenAction',
+            '@key': ['@type', 'source', 'agent.handle', 'object.sourceId', 'timestamp'],
+            timestamp: new Date(data.played_at),
+            source: 'spotify',
+            agent: user,
+            object: track,
+        };
+        return [action];
+    }
+    buildSaveActions(record) {
+        const { data } = record;
+        const user = this.buildUser(record);
+        let object;
+        if (data.track) {
+            // Saved track
+            object = this.buildMusicRecording(data.track);
+        }
+        else if (data.album) {
+            // Saved album
+            object = this.buildMusicAlbum(data.album);
+        }
+        else {
+            throw new Error('Save action must have either track or album data');
+        }
+        const action = {
+            '@type': 'LikeAction',
+            '@key': ['@type', 'source', 'agent.handle', 'object.sourceId', 'timestamp'],
+            timestamp: new Date(data.added_at),
+            source: 'spotify',
+            agent: user,
+            object,
+        };
+        return [action];
+    }
+    buildPlaylistTrackActions(record) {
+        const { data } = record;
+        const user = this.buildUser(record);
+        const track = this.buildMusicRecording(data.track);
+        const playlist = this.buildPlaylistEntity(data.playlist);
+        // AddAction represents adding a track to a playlist collection
+        const action = {
+            '@type': 'AddAction',
+            '@key': ['@type', 'source', 'object.sourceId', 'target.sourceId', 'timestamp'],
+            timestamp: new Date(data.added_at),
+            source: 'spotify',
+            agent: user,
+            object: track, // The track being added
+            target: playlist, // The playlist collection
+        };
+        return [action];
+    }
+    buildMusicRecording(trackData) {
+        const recording = {
+            '@type': 'MusicRecording',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'spotify',
+            sourceId: trackData.id,
+            url: trackData.external_urls.spotify,
+            name: trackData.name,
+            duration: `PT${Math.floor(trackData.duration_ms / 1000)}S`,
+            ...(trackData.preview_url && { contentUrl: trackData.preview_url }),
+        };
+        // Add artists
+        if (trackData.artists && trackData.artists.length > 0) {
+            recording.artist = trackData.artists.map((artist) => this.buildMusicGroup(artist));
+        }
+        // Add album
+        if (trackData.album) {
+            recording.inAlbum = this.buildMusicAlbum(trackData.album);
+        }
+        // Add track image (usually from album artwork)
+        if (trackData.album?.images?.[0]) {
+            const largestImage = trackData.album.images[0];
+            recording.emblem = createImageObject({
+                url: largestImage.url,
+                width: largestImage.width,
+                height: largestImage.height,
+            });
+        }
+        return recording;
+    }
+    buildMusicGroup(artistData) {
+        const group = {
+            '@type': 'MusicGroup',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'spotify',
+            sourceId: artistData.id,
+            url: artistData.external_urls?.spotify || `https://open.spotify.com/artist/${artistData.id}`,
+            name: artistData.name,
+            ...(artistData.genres && { genre: artistData.genres }),
+        };
+        // Add artist image as attachment if available
+        if (artistData.images?.[0]) {
+            const largestImage = artistData.images[0];
+            group.emblem = createImageObject({
+                url: largestImage.url,
+                width: largestImage.width,
+                height: largestImage.height,
+            });
+        }
+        return group;
+    }
+    buildPlaylistEntity(playlistData) {
+        const entity = {
+            '@type': 'Entity',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'spotify',
+            sourceId: playlistData.id,
+            url: playlistData.external_urls.spotify,
+            name: playlistData.name,
+            description: playlistData.description,
+        };
+        // Add playlist image as attachment if available
+        if (playlistData.images?.[0]) {
+            const largestImage = playlistData.images[0];
+            entity.emblem = createImageObject({
+                url: largestImage.url,
+                width: largestImage.width,
+                height: largestImage.height,
+            });
+        }
+        return entity;
+    }
+    buildMusicAlbum(albumData) {
+        const album = {
+            '@type': 'MusicAlbum',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'spotify',
+            sourceId: albumData.id,
+            url: albumData.external_urls?.spotify || `https://open.spotify.com/album/${albumData.id}`,
+            name: albumData.name,
+            ...(albumData.release_date && { datePublished: albumData.release_date }),
+        };
+        // Add album art as attachment if available
+        if (albumData.images?.[0]) {
+            const largestImage = albumData.images[0];
+            album.emblem = createImageObject({
+                url: largestImage.url,
+                width: largestImage.width,
+                height: largestImage.height,
+            });
+        }
+        // Add album artists
+        if (albumData.artists && albumData.artists.length > 0) {
+            album.artist = albumData.artists.map((artist) => this.buildMusicGroup(artist));
+        }
+        return album;
+    }
+    buildUser(record) {
+        const userData = record.context?.user;
+        if (!userData) {
+            throw new Error('User data not available in record context');
+        }
+        return {
+            '@type': 'Agent',
+            '@key': ['@type', 'source', 'handle'],
+            source: 'spotify',
+            handle: userData.id,
+            name: userData.display_name || userData.id,
+            url: userData.external_urls?.spotify || `https://open.spotify.com/user/${userData.id}`,
+            sameAs: ['@me'],
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { SpotifyBaseExtractor } from './connectors/SpotifyBaseExtractor.js';
+export { SpotifyRecentlyPlayedExtractor } from './connectors/SpotifyRecentlyPlayedExtractor.js';
+export { SpotifySavedTracksExtractor } from './connectors/SpotifySavedTracksExtractor.js';
+export { SpotifySavedAlbumsExtractor } from './connectors/SpotifySavedAlbumsExtractor.js';
+export { SpotifyPlaylistsExtractor } from './connectors/SpotifyPlaylistsExtractor.js';
+export { default as SpotifyTransformer } from './connectors/SpotifyTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,11 @@
+// Export extractors
+export { SpotifyBaseExtractor } from './connectors/SpotifyBaseExtractor.js';
+export { SpotifyRecentlyPlayedExtractor } from './connectors/SpotifyRecentlyPlayedExtractor.js';
+export { SpotifySavedTracksExtractor } from './connectors/SpotifySavedTracksExtractor.js';
+export { SpotifySavedAlbumsExtractor } from './connectors/SpotifySavedAlbumsExtractor.js';
+export { SpotifyPlaylistsExtractor } from './connectors/SpotifyPlaylistsExtractor.js';
+export { default as SpotifyTransformer } from './connectors/SpotifyTransformer.js';
+// Register OAuth provider
+import { OAuthProviderRegistry } from '@chronicle.app/auth';
+import { SpotifyOAuthProvider } from './auth/SpotifyOAuthProvider.js';
+OAuthProviderRegistry.register(SpotifyOAuthProvider);

package/dist/utils/SpotifyProxy.d.ts

@@ -0,0 +1,144 @@
+import { ApiProxy } from '@chronicle.app/etl';
+export interface SpotifyTrack {
+    id: string;
+    name: string;
+    artists: Array<{
+        id: string;
+        name: string;
+    }>;
+    album: {
+        id: string;
+        name: string;
+        release_date: string;
+        images: Array<{
+            url: string;
+            height: number;
+            width: number;
+        }>;
+    };
+    duration_ms: number;
+    explicit: boolean;
+    external_urls: {
+        spotify: string;
+    };
+    popularity: number;
+    preview_url?: string;
+}
+export interface SpotifyRecentlyPlayed {
+    track: SpotifyTrack;
+    played_at: string;
+    context?: {
+        type: string;
+        href: string;
+        external_urls: {
+            spotify: string;
+        };
+    };
+}
+export interface SpotifySavedTrack {
+    added_at: string;
+    track: SpotifyTrack;
+}
+export interface SpotifyPlaylist {
+    id: string;
+    name: string;
+    description?: string;
+    public: boolean;
+    collaborative: boolean;
+    tracks: {
+        total: number;
+    };
+    external_urls: {
+        spotify: string;
+    };
+    images: Array<{
+        url: string;
+        height?: number;
+        width?: number;
+    }>;
+    owner: {
+        id: string;
+        display_name?: string;
+    };
+}
+export interface SpotifyArtist {
+    id: string;
+    name: string;
+    genres: string[];
+    popularity: number;
+    external_urls: {
+        spotify: string;
+    };
+    images: Array<{
+        url: string;
+        height: number;
+        width: number;
+    }>;
+    followers: {
+        total: number;
+    };
+}
+export interface SpotifyAlbum {
+    id: string;
+    name: string;
+    artists: Array<{
+        id: string;
+        name: string;
+    }>;
+    album_type: string;
+    release_date: string;
+    release_date_precision: string;
+    total_tracks: number;
+    images: Array<{
+        url: string;
+        height?: number;
+        width?: number;
+    }>;
+    external_urls: {
+        spotify: string;
+    };
+    genres: string[];
+    popularity: number;
+}
+export interface SpotifySavedAlbum {
+    added_at: string;
+    album: SpotifyAlbum;
+}
+export interface SpotifyUser {
+    id: string;
+    display_name?: string;
+    email?: string;
+    external_urls: {
+        spotify: string;
+    };
+    followers: {
+        total: number;
+    };
+    images: Array<{
+        url: string;
+        height?: number;
+        width?: number;
+    }>;
+    country?: string;
+}
+export default class SpotifyProxy extends ApiProxy {
+    constructor(accessToken?: string);
+    /**
+     * Ensure we have a valid access token, using stored credentials if available
+     */
+    initialize(): Promise<void>;
+    getRecentlyPlayed(options?: {
+        since?: Date;
+        until?: Date;
+        limit?: number;
+    }): Promise<SpotifyRecentlyPlayed[]>;
+    getSavedTracks(limit?: number): Promise<SpotifySavedTrack[]>;
+    getSavedAlbums(limit?: number): Promise<SpotifySavedAlbum[]>;
+    getPlaylists(): Promise<SpotifyPlaylist[]>;
+    getPlaylistTracks(playlistId: string, limit?: number): Promise<any[]>;
+    getTopTracks(timeRange?: 'short_term' | 'medium_term' | 'long_term'): Promise<SpotifyTrack[]>;
+    getTopArtists(timeRange?: 'short_term' | 'medium_term' | 'long_term'): Promise<SpotifyArtist[]>;
+    getUser(): Promise<SpotifyUser>;
+    getTotalItemCount(): Promise<number>;
+}
+//# sourceMappingURL=SpotifyProxy.d.ts.map

package/dist/utils/SpotifyProxy.js

@@ -0,0 +1,180 @@
+import { ApiAuthError, ApiProxy } from '@chronicle.app/etl';
+import { TokenHelper } from '@chronicle.app/auth';
+export default class SpotifyProxy extends ApiProxy {
+    constructor(accessToken) {
+        super({
+            baseURL: 'https://api.spotify.com/v1',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            pageDelayMs: 100,
+        });
+        // If token provided, use it directly
+        if (accessToken) {
+            this.setAccessToken(accessToken);
+        }
+    }
+    /**
+     * Ensure we have a valid access token, using stored credentials if available
+     */
+    async initialize() {
+        // If we already have an access token, we're good
+        if (this.accessToken) {
+            return;
+        }
+        // Try to get token from stored credentials
+        const token = await TokenHelper.getValidToken('spotify');
+        this.setAccessToken(token);
+    }
+    async getRecentlyPlayed(options = {}) {
+        await this.initialize();
+        const params = {
+            limit: Math.min(options.limit || 50, 50), // Spotify max is 50
+        };
+        if (options.since) {
+            params.after = options.since.getTime();
+        }
+        if (options.until) {
+            params.before = options.until.getTime();
+        }
+        try {
+            const data = await this.request({
+                url: '/me/player/recently-played',
+                method: 'GET',
+                params,
+            });
+            return data.items || [];
+        }
+        catch (error) {
+            if (error instanceof ApiAuthError) {
+                // eslint-disable-next-line unicorn/prefer-type-error -- rethrowing a friendlier message for a caught ApiAuthError, not validating an argument type
+                throw new Error('Spotify authentication failed. Please re-authenticate:\n' +
+                    '  chronicle auth login spotify --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n\n' +
+                    'Or get your credentials at: https://developer.spotify.com/dashboard');
+            }
+            throw error;
+        }
+    }
+    async getSavedTracks(limit) {
+        await this.initialize();
+        const batchSize = 50; // Spotify max per request
+        return this.paginateOffset({
+            pageSize: batchSize,
+            limit,
+            fetchPage: async (offset) => {
+                const data = await this.request({
+                    url: '/me/tracks',
+                    method: 'GET',
+                    params: { limit: batchSize, offset },
+                });
+                return data.items || [];
+            },
+        });
+    }
+    async getSavedAlbums(limit) {
+        await this.initialize();
+        const batchSize = 50; // Spotify max per request
+        return this.paginateOffset({
+            pageSize: batchSize,
+            limit,
+            fetchPage: async (offset) => {
+                const data = await this.request({
+                    url: '/me/albums',
+                    method: 'GET',
+                    params: { limit: batchSize, offset },
+                });
+                return data.items || [];
+            },
+        });
+    }
+    async getPlaylists() {
+        const pageSize = 50; // Spotify max per request
+        return this.paginateOffset({
+            pageSize,
+            fetchPage: async (offset) => {
+                const data = await this.request({
+                    url: '/me/playlists',
+                    method: 'GET',
+                    params: { limit: pageSize, offset },
+                });
+                return data.items || [];
+            },
+        });
+    }
+    async getPlaylistTracks(playlistId, limit) {
+        await this.initialize();
+        const batchSize = 50; // Spotify max per request
+        return this.paginateOffset({
+            pageSize: batchSize,
+            limit,
+            fetchPage: async (offset) => {
+                const data = await this.request({
+                    url: `/playlists/${playlistId}/tracks`,
+                    method: 'GET',
+                    params: {
+                        limit: batchSize,
+                        offset,
+                        fields: 'items(added_at,track(id,name,artists,album,duration_ms,external_urls,popularity)),total',
+                    },
+                });
+                return data.items || [];
+            },
+        });
+    }
+    async getTopTracks(timeRange = 'medium_term') {
+        const data = await this.request({
+            url: '/me/top/tracks',
+            method: 'GET',
+            params: {
+                time_range: timeRange,
+                limit: 50,
+            },
+        });
+        return data.items || [];
+    }
+    async getTopArtists(timeRange = 'medium_term') {
+        const data = await this.request({
+            url: '/me/top/artists',
+            method: 'GET',
+            params: {
+                time_range: timeRange,
+                limit: 50,
+            },
+        });
+        return data.items || [];
+    }
+    async getUser() {
+        await this.initialize();
+        return this.request({
+            url: '/me',
+            method: 'GET',
+        });
+    }
+    async getTotalItemCount() {
+        try {
+            // Get user profile to check if API is working
+            await this.request({ url: '/me', method: 'GET' });
+            // Get counts from different endpoints
+            const [savedTracksResponse, playlistsResponse] = await Promise.all([
+                this.request({
+                    url: '/me/tracks',
+                    method: 'GET',
+                    params: { limit: 1 },
+                }),
+                this.request({
+                    url: '/me/playlists',
+                    method: 'GET',
+                    params: { limit: 1 },
+                }),
+            ]);
+            const savedTracksCount = savedTracksResponse.total || 0;
+            const playlistsCount = playlistsResponse.total || 0;
+            // Recently played doesn't have a total count, so we estimate based on recent activity
+            const recentlyPlayedCount = 50; // Approximate recent activity
+            return savedTracksCount + playlistsCount + recentlyPlayedCount;
+        }
+        catch (error) {
+            throw new Error(`Failed to get item count: ${error}`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@chronicle.app/spotify",
+  "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",
+    "spotify"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for extracting data from Spotify",
+  "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/spotify"
+  },
+  "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": {
+      "spotify": {
+        "strategies": {
+          "api": {
+            "delivery": "api",
+            "recordTypes": [
+              "playlist-tracks",
+              "listens",
+              "saved-albums",
+              "saved-tracks"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}