@chronicle.app/lastfm 0.3.0 → 0.5.0

package/README.md

@@ -105,10 +105,11 @@ The plugin generates the following Chronicle schema types:
 
 - `ListenAction`: a scrobble (recent track), timestamped at the play time
 - `LikeAction`: a loved/favorited track, timestamped when loved
-- `FollowAction`: the listener following a friend; no timestamp (Last.fm gives no
-  befriended date), sighted at read time by the snapshot `friends` extractor
-- `CreateAction`: a friend's Last.fm account registration, keyed on the account
-  handle and timestamped at their `registered` date (the account's
+- `FollowAction`: the listener following a friend, keyed by the friend's account;
+  no timestamp (Last.fm gives no befriended date), sighted at read time by the
+  snapshot `friends` extractor
+- `CreateAction`: a friend's Last.fm account registration, keyed by the account
+  it made and timestamped at their `registered` date (the account's
   coming-into-being on `result`)
 - `Agent`: the listener and their friends, keyed on the Last.fm `handle` (the
   canonical username), with real name, profile URL, and avatar `image` when

package/dist/auth/LastfmOAuthProvider.js

@@ -1,6 +1,7 @@
 import axios from 'axios';
 import { createHash } from 'node:crypto';
 import { OAuthProvider } from '@chronicle.app/auth';
+import { AuthRequired } from '@chronicle.app/etl';
 export class LastfmOAuthProvider extends OAuthProvider {
     static providerId = 'lastfm';
     static authorizationUrl = 'https://www.last.fm/api/auth';
@@ -43,10 +44,12 @@ export class LastfmOAuthProvider extends OAuthProvider {
             });
             const sessionData = sessionResponse.data;
             if (sessionData.error) {
-                throw new Error(`Last.fm API error: ${sessionData.message || sessionData.error}`);
+                throw new AuthRequired(`Last.fm refused the session: ${sessionData.message || sessionData.error}`, {
+                    source: 'lastfm',
+                });
             }
             if (!sessionData.session || !sessionData.session.key) {
-                throw new Error('No session key received from Last.fm');
+                throw new AuthRequired('Last.fm sent no session key', { source: 'lastfm' });
             }
             // Last.fm returns a session key instead of access/refresh tokens
             const tokens = {
@@ -62,7 +65,10 @@ export class LastfmOAuthProvider extends OAuthProvider {
         catch (error) {
             if (axios.isAxiosError(error)) {
                 const message = error.response?.data?.message || error.message;
-                throw new Error(`Failed to get Last.fm session: ${message}`);
+                throw new AuthRequired(`Couldn't get a Last.fm session: ${message}`, {
+                    source: 'lastfm',
+                    cause: error,
+                });
             }
             throw error;
         }

package/dist/connectors/LastfmFriendsExtractor.js

@@ -42,6 +42,7 @@ export class LastfmFriendsExtractor extends Extractor {
                 '1. Run: chronicle auth login lastfm --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n' +
                 '2. Or use: --api-key YOUR_API_KEY for traditional auth\n' +
                 '3. Or use: --access-token TOKEN for OAuth session key',
+            hint: 'Run `chronicle auth login lastfm` to sign in.',
         });
         // Get username from config or stored credentials
         const { username } = await resolveCredentials('lastfm', {
@@ -49,6 +50,7 @@ export class LastfmFriendsExtractor extends Extractor {
         }, {
             overrides: { username: config.username },
             errorMessage: 'Last.fm username is required. Either provide --username or authenticate with: chronicle auth login lastfm',
+            hint: 'Run `chronicle auth login lastfm` to sign in.',
         });
         this.proxy = new LastfmProxy(authToken, username);
         this.username = username;

package/dist/connectors/LastfmLovedTracksExtractor.js

@@ -37,6 +37,7 @@ export class LastfmLovedTracksExtractor extends Extractor {
                 '1. Run: chronicle auth login lastfm --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n' +
                 '2. Or use: --api-key YOUR_API_KEY for traditional auth\n' +
                 '3. Or use: --access-token TOKEN for OAuth session key',
+            hint: 'Run `chronicle auth login lastfm` to sign in.',
         });
         // Get username from config or stored credentials
         const { username } = await resolveCredentials('lastfm', {
@@ -44,6 +45,7 @@ export class LastfmLovedTracksExtractor extends Extractor {
         }, {
             overrides: { username: config.username },
             errorMessage: 'Last.fm username is required. Either provide --username or authenticate with: chronicle auth login lastfm',
+            hint: 'Run `chronicle auth login lastfm` to sign in.',
         });
         this.proxy = new LastfmProxy(authToken, username);
         this.username = username;

package/dist/connectors/LastfmRecentTracksExtractor.js

@@ -38,6 +38,7 @@ export class LastfmRecentTracksExtractor extends Extractor {
                 '1. Run: chronicle auth login lastfm --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n' +
                 '2. Or use: --api-key YOUR_API_KEY for traditional auth\n' +
                 '3. Or use: --access-token TOKEN for OAuth session key',
+            hint: 'Run `chronicle auth login lastfm` to sign in.',
         });
         // Get username from config or stored credentials
         const { username } = await resolveCredentials('lastfm', {
@@ -45,6 +46,7 @@ export class LastfmRecentTracksExtractor extends Extractor {
         }, {
             overrides: { username: config.username },
             errorMessage: 'Last.fm username is required. Either provide --username or authenticate with: chronicle auth login lastfm',
+            hint: 'Run `chronicle auth login lastfm` to sign in.',
         });
         this.proxy = new LastfmProxy(authToken, username);
         this.username = username;

package/dist/connectors/LastfmTransformer.js

@@ -32,8 +32,8 @@ export default class LastfmTransformer extends ChronicleTransformer {
     }
     // A Last.fm friend is a user the listener follows. Last.fm gives no
     // befriended date, so the FollowAction carries no timestamp — it's sighted at
-    // read time by the snapshot extractor — and keys on the followed user's handle
-    // so re-reads supersede rather than duplicate.
+    // read time by the snapshot extractor — and keys on the followed user, by
+    // handle, so re-reads supersede rather than duplicate.
     buildFriendAction(record) {
         const friend = record.data;
         const friendAgent = this.buildLastfmAgent(friend.name, {
@@ -44,9 +44,8 @@ export default class LastfmTransformer extends ChronicleTransformer {
         const actions = [
             {
                 '@type': 'FollowAction',
-                '@key': ['@type', 'source', 'sourceId'],
+                '@key': ['@type', 'source', 'object.handle'],
                 source: 'lastfm',
-                sourceId: friend.name,
                 agent: this.resolveUser(record),
                 object: friendAgent,
             },
@@ -59,7 +58,8 @@ export default class LastfmTransformer extends ChronicleTransformer {
     }
     // When a Last.fm account was created (its `registered` date). This is a real
     // source event with a real timestamp, so it's a keyed action — not synthetic —
-    // keyed on the account handle so it's referenceable and re-reads supersede. The
+    // keyed on the account it made, by handle, so it's referenceable and re-reads
+    // supersede. The
     // account's coming-into-being is origin-grade evidence carried on `result`; a
     // bare handle reference is used so the friend's *current* avatar/name aren't
     // back-dated to the registration instant — those stay on the FollowAction.
@@ -77,9 +77,8 @@ export default class LastfmTransformer extends ChronicleTransformer {
         };
         return {
             '@type': 'CreateAction',
-            '@key': ['@type', 'source', 'sourceId'],
+            '@key': ['@type', 'source', 'result.handle'],
             source: 'lastfm',
-            sourceId: handle,
             timestamp: at,
             agent: ref,
             result: ref,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/lastfm",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -22,9 +22,9 @@
   "type": "module",
   "description": "Chronicle plugin for Last.fm listening history and loved tracks",
   "devDependencies": {
-    "@chronicle.app/etl": "0.3.0",
-    "@chronicle.app/schema": "0.3.0",
-    "@chronicle.app/tsconfig": "0.3.0",
+    "@chronicle.app/etl": "0.5.0",
+    "@chronicle.app/schema": "0.5.0",
+    "@chronicle.app/tsconfig": "0.5.0",
     "@types/node": "^22.10.1",
     "typescript": "^5.7.2"
   },
@@ -39,7 +39,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@chronicle.app/auth": "0.3.0",
+    "@chronicle.app/auth": "0.5.0",
     "axios": "^1.7.9",
     "zod": "^3.24.1"
   },