{"id":19069927,"url":"https://github.com/ansango/lastfm-client-ts","last_synced_at":"2026-07-10T04:31:01.268Z","repository":{"id":128618614,"uuid":"610035434","full_name":"ansango/lastfm-client-ts","owner":"ansango","description":"A node ts lastfm client api","archived":false,"fork":false,"pushed_at":"2025-11-07T22:09:51.000Z","size":338,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-16T09:49:36.804Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ansango.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-06T00:07:20.000Z","updated_at":"2025-11-07T22:09:54.000Z","dependencies_parsed_at":"2023-05-30T03:30:37.205Z","dependency_job_id":null,"html_url":"https://github.com/ansango/lastfm-client-ts","commit_stats":{"total_commits":49,"total_committers":2,"mean_commits":24.5,"dds":"0.020408163265306145","last_synced_commit":"6e26de1bd3b848cb816e0a6442256b3bff6bb2c7"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/ansango/lastfm-client-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansango%2Flastfm-client-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansango%2Flastfm-client-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansango%2Flastfm-client-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansango%2Flastfm-client-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ansango","download_url":"https://codeload.github.com/ansango/lastfm-client-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansango%2Flastfm-client-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35321224,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T01:16:13.292Z","updated_at":"2026-07-10T04:31:01.262Z","avatar_url":"https://github.com/ansango.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lastfm-client-ts\n\n[![NPM Version](https://img.shields.io/npm/v/lastfm-client-ts.svg?branch=main)](https://www.npmjs.com/package/lastfm-client-ts)\n[![Downloads Per Week](https://img.shields.io/npm/dw/lastfm-client-ts.svg?color=blue)](https://www.npmjs.com/package/lastfm-client-ts)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nA universal Last.fm API client for Node.js and Browser, written in TypeScript.\n\n## Features\n\n- ✅ **Universal**: Works in Node.js (≥20.0.0) and Browser\n- ✅ **TypeScript**: Full type safety with comprehensive type definitions\n- ✅ **Zod Schemas**: Runtime validation schemas for all types\n- ✅ **ESM**: Modern ES modules with tree-shaking support\n- ✅ **Flexible**: Global configuration or per-instance configuration\n- ✅ **Modular**: Import only what you need\n- ✅ **Minimal Dependencies**: Only `js-md5` for API signatures and `zod` for runtime validation\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n  - [Using the Client Class](#using-the-client-class)\n  - [Using Global Configuration](#using-global-configuration)\n  - [Using Individual Services](#using-individual-services)\n- [Environment Variables](#environment-variables)\n- [API Reference](#api-reference)\n- [TypeScript Support](#typescript-support)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\n```bash\nnpm install lastfm-client-ts\n```\n\n**Requirements:**\n- Node.js ≥ 20.0.0 (for native fetch support)\n- Modern browsers with fetch API support\n\n## Quick Start\n\n```typescript\nimport { LastFmClient } from 'lastfm-client-ts';\n\n// Create a client instance\nconst client = new LastFmClient({\n  apiKey: 'YOUR_API_KEY'\n});\n\n// Fetch user information\nconst userInfo = await client.user.getInfo({ user: 'ansango' });\nconsole.log(userInfo);\n\n// Search for albums\nconst albums = await client.album.search({ album: 'Believe' });\nconsole.log(albums);\n```\n\n## Usage\n\n### Using the Client Class (Recommended)\n\nThe client class provides access to all API services in one place:\n\n```typescript\nimport { LastFmClient } from 'lastfm-client-ts';\n\nconst client = new LastFmClient({\n  apiKey: 'YOUR_API_KEY',\n  sharedSecret: 'YOUR_SHARED_SECRET', // Optional, required for authenticated methods\n  sessionKey: 'USER_SESSION_KEY'      // Optional, required for user-specific methods\n});\n\n// User service\nconst userInfo = await client.user.getInfo({ user: 'ansango' });\nconst topArtists = await client.user.getTopArtists({ user: 'ansango', period: '7day' });\n\n// Album service\nconst albumInfo = await client.album.getInfo({ artist: 'Cher', album: 'Believe' });\nconst albumSearch = await client.album.search({ album: 'Believe', limit: 10 });\n\n// Artist service\nconst artistInfo = await client.artist.getInfo({ artist: 'Radiohead' });\nconst similarArtists = await client.artist.getSimilar({ artist: 'Radiohead' });\n\n// Track service\nconst trackInfo = await client.track.getInfo({ artist: 'The Beatles', track: 'Yesterday' });\nconst trackSearch = await client.track.search({ track: 'Yesterday', limit: 10 });\n\n// Chart service\nconst topChartArtists = await client.chart.getTopArtists();\nconst topChartTracks = await client.chart.getTopTracks();\n\n// Tag service\nconst tagInfo = await client.tag.getInfo({ tag: 'rock' });\nconst topTagArtists = await client.tag.getTopArtists({ tag: 'rock' });\n\n// Geo service\nconst topArtistsByCountry = await client.geo.getTopArtists({ country: 'spain' });\n\n// Library service\nconst libraryArtists = await client.library.getArtists({ user: 'ansango' });\n\n// Auth service (for scrobbling and authenticated methods)\nconst session = await client.auth.getSession({ token: 'AUTH_TOKEN' });\n```\n\n### Using Global Configuration\n\nSet configuration globally and reuse it across multiple client instances:\n\n```typescript\nimport { setGlobalConfig, createClient } from 'lastfm-client-ts';\n\n// Set global configuration once\nsetGlobalConfig({\n  apiKey: process.env.LASTFM_API_KEY!,\n  sharedSecret: process.env.LASTFM_SHARED_SECRET\n});\n\n// Create clients without passing config\nconst client1 = createClient();\nconst client2 = createClient();\n\n// Both clients use the same global configuration\nconst user1 = await client1.user.getInfo({ user: 'user1' });\nconst user2 = await client2.user.getInfo({ user: 'user2' });\n```\n\n### Using Individual Services\n\nImport only the services you need for better tree-shaking:\n\n```typescript\n// Import only the user service\nimport { createUserService } from 'lastfm-client-ts/user';\nimport type { UserGetInfoRequest } from 'lastfm-client-ts/user';\n\nconst userService = createUserService({\n  apiKey: 'YOUR_API_KEY'\n});\n\nconst params: UserGetInfoRequest = { user: 'ansango' };\nconst userInfo = await userService.getInfo(params);\n```\n\n```typescript\n// Import multiple services\nimport { createAlbumService } from 'lastfm-client-ts/album';\nimport { createTrackService } from 'lastfm-client-ts/track';\n\nconst config = { apiKey: 'YOUR_API_KEY' };\n\nconst albumService = createAlbumService(config);\nconst trackService = createTrackService(config);\n\nconst albums = await albumService.search({ album: 'Abbey Road' });\nconst tracks = await trackService.search({ track: 'Come Together' });\n```\n\n**Available service imports:**\n- `lastfm-client-ts/user`\n- `lastfm-client-ts/album`\n- `lastfm-client-ts/artist`\n- `lastfm-client-ts/track`\n- `lastfm-client-ts/tag`\n- `lastfm-client-ts/chart`\n- `lastfm-client-ts/geo`\n- `lastfm-client-ts/library`\n- `lastfm-client-ts/auth`\n\n## Zod Schema Validation\n\nThe library includes automatically generated Zod schemas for runtime validation. These schemas mirror all TypeScript types and can be used to validate API responses or user input at runtime.\n\n### Importing Schemas\n\nSchemas are available through modular imports, following the same pattern as the services:\n\n```typescript\nimport { userGetInfoRequestSchema, userGetInfoResponseSchema } from 'lastfm-client-ts/user/schemas';\nimport { albumSearchRequestSchema } from 'lastfm-client-ts/album/schemas';\nimport { trackGetInfoResponseSchema } from 'lastfm-client-ts/track/schemas';\n```\n\n### Usage Example\n\n```typescript\nimport { userGetInfoRequestSchema, userGetInfoResponseSchema } from 'lastfm-client-ts/user/schemas';\n\n// Validate request parameters\nconst params = { user: 'ansango' };\nconst validatedParams = userGetInfoRequestSchema.parse(params);\n\n// Validate API response\nconst response = await fetch(`https://ws.audioscrobbler.com/2.0/...`);\nconst data = await response.json();\nconst validatedData = userGetInfoResponseSchema.parse(data);\n\n// Safe parsing (doesn't throw)\nconst result = userGetInfoResponseSchema.safeParse(data);\nif (result.success) {\n  console.log(result.data);\n} else {\n  console.error(result.error);\n}\n```\n\n**Available schema imports:**\n- `lastfm-client-ts/user/schemas`\n- `lastfm-client-ts/album/schemas`\n- `lastfm-client-ts/artist/schemas`\n- `lastfm-client-ts/track/schemas`\n- `lastfm-client-ts/tag/schemas`\n- `lastfm-client-ts/chart/schemas`\n- `lastfm-client-ts/geo/schemas`\n- `lastfm-client-ts/library/schemas`\n- `lastfm-client-ts/auth/schemas`\n- `lastfm-client-ts/schemas` (base types like `imageSchema`, `datePropSchema`, etc.)\n\n## Environment Variables\n\nIn Node.js environments, the client automatically loads configuration from environment variables:\n\n```bash\n# .env file\nLASTFM_API_KEY=your_api_key_here\nLASTFM_SHARED_SECRET=your_shared_secret_here\nLASTFM_SESSION_KEY=user_session_key_here\n\n# Optional: Custom base URL\nLASTFM_BASE_URL=https://ws.audioscrobbler.com/2.0/\n```\n\n```typescript\n// Configuration is loaded automatically from process.env\nimport { createClient } from 'lastfm-client-ts';\n\nconst client = createClient(); // Uses environment variables\n```\n\n**Browser Usage:**\n\nIn browser environments, pass configuration explicitly or use your bundler's environment variable system:\n\n```typescript\n// Vite\nconst client = new LastFmClient({\n  apiKey: import.meta.env.VITE_LASTFM_API_KEY\n});\n\n// Webpack\nconst client = new LastFmClient({\n  apiKey: process.env.REACT_APP_LASTFM_API_KEY\n});\n```\n\n## API Reference\n\n### Client\n\nThe main client class with all services:\n\n```typescript\nclass LastFmClient {\n  user: UserService;\n  album: AlbumService;\n  artist: ArtistService;\n  track: TrackService;\n  tag: TagService;\n  chart: ChartService;\n  geo: GeoService;\n  library: LibraryService;\n  auth: AuthService;\n  \n  constructor(config?: Partial\u003cLastFmConfig\u003e);\n  getConfig(): Readonly\u003cLastFmConfig\u003e;\n}\n```\n\n### Configuration\n\n```typescript\ninterface LastFmConfig {\n  apiKey: string;           // Required: Your Last.fm API key\n  sharedSecret?: string;    // Optional: Required for authenticated methods\n  sessionKey?: string;      // Optional: User session key for scrobbling\n  baseUrl?: string;         // Optional: API base URL (default: https://ws.audioscrobbler.com/2.0/)\n}\n\n// Configuration functions\nfunction createConfig(options?: Partial\u003cLastFmConfig\u003e): LastFmConfig;\nfunction setGlobalConfig(config: Partial\u003cLastFmConfig\u003e): void;\nfunction getGlobalConfig(): LastFmConfig;\nfunction resetGlobalConfig(): void;\n```\n\n### Services\n\nEach service provides methods for interacting with specific Last.fm API endpoints:\n\n- **UserService**: User-related methods (getInfo, getTopArtists, getRecentTracks, etc.)\n- **AlbumService**: Album methods (getInfo, search, getTags, etc.)\n- **ArtistService**: Artist methods (getInfo, getSimilar, getTopAlbums, etc.)\n- **TrackService**: Track methods (getInfo, search, scrobble, etc.)\n- **TagService**: Tag methods (getInfo, getTopArtists, getTopTracks, etc.)\n- **ChartService**: Chart methods (getTopArtists, getTopTracks, etc.)\n- **GeoService**: Geographic methods (getTopArtists, getTopTracks by country)\n- **LibraryService**: Library methods (getArtists, etc.)\n- **AuthService**: Authentication methods (getSession, etc.)\n\n## TypeScript Support\n\nThe library is fully typed with comprehensive TypeScript definitions:\n\n```typescript\nimport { LastFmClient } from 'lastfm-client-ts';\nimport type {\n  UserGetInfoRequest,\n  UserGetInfoResponse,\n  AlbumSearchRequest,\n  AlbumSearchResponse\n} from 'lastfm-client-ts';\n\nconst client = new LastFmClient({ apiKey: 'YOUR_API_KEY' });\n\n// Type-safe requests and responses\nconst userParams: UserGetInfoRequest = { user: 'ansango' };\nconst userInfo: UserGetInfoResponse = await client.user.getInfo(userParams);\n\nconst albumParams: AlbumSearchRequest = { album: 'Believe', limit: 10 };\nconst albums: AlbumSearchResponse = await client.album.search(albumParams);\n```\n\nAll request parameters and response types are exported for your convenience.\n\n## Contributing\n\nContributions are always welcome!\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes using [Conventional Commits](https://www.conventionalcommits.org/)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Scripts\n\n```bash\n# Install dependencies\nbun install\n\n# Run in development mode (watch mode)\nbun run dev\n\n# Build the project\nbun run build\n\n# Run tests\nbun test\n\n# Clean build artifacts\nbun run clean\n```\n\n### Release Process\n\nThis project uses automated release scripts:\n\n```bash\n# Create a patch release (1.0.0 -\u003e 1.0.1)\nbun run release:patch\n\n# Create a minor release (1.0.0 -\u003e 1.1.0)\nbun run release:minor\n\n# Create a major release (1.0.0 -\u003e 2.0.0)\nbun run release:major\n\n# Create an alpha release (1.0.0 -\u003e 1.0.1-alpha.0)\nbun run release:alpha\n\n# Create a beta release (1.0.0 -\u003e 1.0.1-beta.0)\nbun run release:beta\n```\n\nThe release script will:\n- Run tests\n- Build the project\n- Generate changelog from commits\n- Bump version in package.json\n- Create git tag\n- Create GitHub release\n- Publish to npm\n\nFor more details, see [scripts/README.md](scripts/README.md).\n\n## License\n\n[MIT](LICENSE) © [Anibal Santos](https://github.com/ansango)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansango%2Flastfm-client-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fansango%2Flastfm-client-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansango%2Flastfm-client-ts/lists"}