its bun-time

:D
(publish & merge initial version)

Author: xwxfox

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install root dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run root tests
+        run: bun run test
+
+      - name: Install docs dependencies
+        working-directory: docs
+        run: bun install --frozen-lockfile
+
+      - name: Build docs
+        working-directory: docs
+        run: bun run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -32,3 +32,10 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+
+# Documentation build artifacts
+docs/.docusaurus
+docs/.vitepress
+docs/build
+docs_dist
+research/

README.md

@@ -1,6 +1,108 @@
 # @syncfm/applemusic-api
-> A lot of work here is based off the work of https://github.com/oxmc
 
+Typed helpers around Apple Music catalog endpoints with shared configuration, logging, and token management. The client is still in active development, so expect method signatures to move as we close gaps.
 
+## Features
 
-More coming soon :D
+- Zero configuration authentication with automatic scraping and validation of session tokens
+- Strong typing across endpoints for albums, artists, songs, music videos, search, hints, suggestions, and relationships
+- Consistent logging hooks so you can forward diagnostics to your own observability stack
+- Built with Bun and Vitest for fast builds and test feedback
+
+## Requirements
+
+- Node.js 18 or newer, or Bun 1.1 or newer
+- Optional developer or user tokens if you want to override the default scraped authentication flow
+
+
+Guides, endpoint details, and configuration notes live at https://docs.syncfm.dev/applemusic-api .
+
+## Installation
+
+```bash
+npm install @syncfm/applemusic-api
+# or
+pnpm add @syncfm/applemusic-api
+# or
+yarn add @syncfm/applemusic-api
+# or
+bun add @syncfm/applemusic-api
+```
+
+## Quick start
+
+```ts
+import { AppleMusic, AuthType, Region } from "@syncfm/applemusic-api";
+
+const music = new AppleMusic({
+	region: Region.US,
+	authType: AuthType.Scraped,
+});
+
+await music.init();
+
+const results = await music.Search.search({
+	term: "bad omens",
+	types: ["songs", "albums"],
+	limit: 5,
+});
+
+console.log(results.songs?.data?.map((song) => song.attributes?.name));
+```
+
+### Endpoint usage examples
+
+Every top level namespace mirrors an Apple Music resource. Each method enforces the correct parameter and response types.
+
+```ts
+await music.Albums.get({
+	ids: ["1644355784"],
+});
+
+await music.Albums.getRelationship({
+	id: "1644355784",
+	relationship: "tracks",
+});
+
+await music.Suggestions.suggestions({
+	term: "blind cha",
+	limit: 10,
+});
+```
+
+## Configuration
+
+`AppleMusic` accepts either an `AppleMusicConfig` instance or plain `AppleMusicConfigParams`.
+
+- `region`: defaults to `Region.US` but can be set to any supported storefront
+- `authType`: choose between `Scraped`, `DeveloperToken`, `UserTokenViaDevToken`, or `UserTokenUnofficial`
+- `logger`: pass a custom logger implementing the client logger interface, or configure the built in logger through `loggerOptions`
+
+
+## Tooling
+
+- Build: `bun run build`
+- Type check: `bun run type-check`
+- Tests with coverage: `bun run test`
+- Lint and format: `bun run check`
+- Generate reference docs: `bun run docs:build`
+
+## Documentation
+
+Guides, endpoint details, and configuration notes live at https://docs.syncfm.dev/applemusic-api .
+
+## Contributing
+
+1. Fork the repository and create a feature branch
+2. Install dependencies and run the test suite
+3. Open a pull request with a clear description and examples
+
+Please include tests or docs when you add new features.
+
+## Legal
+
+Apple Music and the Apple logo are trademarks of Apple Inc., registered in the U.S. and other countries. This project is an independent community effort and is not affiliated with, endorsed by, or sponsored by Apple Inc. Any interaction with Apple services remains subject to Apple policies, terms, and applicable laws. Ensure you have the necessary authorization before using this client in your applications.
+
+## License
+
+MIT License. See `LICENSE.md` for details.

biome.json

@@ -0,0 +1,44 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.2.5/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"includes": [
+			"**/*.ts",
+			"!dist/*",
+			"!coverage/*",
+			"scripts/*",
+			"!docs/*",
+			"!docs-src/.vitepress/cache/*"
+		]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"style": { "useTemplate": "error", "useShorthandFunctionType": "off" },
+			"suspicious": { "noArrayIndexKey": "off", "noExplicitAny": "off" }
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
+}