upnext-adapter-spotify 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,224 @@
+# upnext-adapter-spotify
+
+[![npm](https://img.shields.io/npm/v/upnext-adapter-spotify)](https://www.npmjs.com/package/upnext-adapter-spotify)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/tothienbao6a0/upnext/blob/main/LICENSE)
+
+Plays Spotify for [**upnext-core**](https://www.npmjs.com/package/upnext-core) —
+**two backends, with honestly different capabilities.**
+
+```bash
+npm i upnext-core upnext-adapter-spotify
+```
+
+## Which one you want
+
+| | `SpotifyDesktopAdapter` | `SpotifyWebAdapter` |
+|---|---|---|
+| **Needs** | the Spotify app, on macOS | an OAuth token + Premium + a live device |
+| **Credentials** | none at all | your own, via `getAccessToken` |
+| **Search** | ❌ | ✅ |
+| **Runs on** | macOS | anywhere Node does |
+| **Setup** | none | register an app with Spotify |
+
+The desktop one works right now, on your machine, with nothing to sign up for:
+
+```ts
+import { Runtime } from 'upnext-core';
+import { SpotifyDesktopAdapter } from 'upnext-adapter-spotify';
+
+const runtime = new Runtime({ adapters: [new SpotifyDesktopAdapter()] });
+
+runtime.enqueue('https://open.spotify.com/track/6f3Slt0GbA2bPZlz0aIFXN');
+runtime.enqueue('spotify:track:1OWBh1eVxUdA1Z6UA8r4nh');
+
+await runtime.play();
+```
+
+The web one costs setup and buys reach:
+
+```ts
+import { SpotifyWebAdapter } from 'upnext-adapter-spotify';
+
+new SpotifyWebAdapter({
+  // Your OAuth, your storage, your refresh. This library never runs a flow,
+  // holds a client id, or opens a browser.
+  getAccessToken: () => myTokenStore.current(),
+  deviceId: 'optional-specific-speaker',
+});
+```
+
+Registering **both** is reasonable. They score the same on a Spotify URI, so the
+runtime uses one and falls through to the other when it cannot deliver — the
+desktop app while it is open, the Web API when it is not.
+
+## Two adapters, one service, different truths
+
+This is the clearest example in the project of why capabilities belong to an
+*adapter* rather than to a *service*:
+
+```ts
+{                          // desktop                web
+  endOfTrack:      'event',    // 'event'            'event'
+  position:        'authoritative',
+  externalControl: true,       // ← both: a human shares this backend with you
+  seek: true, pause: true, volume: true,
+  search:          false,      // ← desktop          true  ← web
+}
+```
+
+`search: false` is the load-bearing one. Spotify's AppleScript dictionary cannot
+search a catalogue. That could be faked — scrape something, guess — and then
+every `resolve` of a title would be a coin flip dressed up as a lookup. **An
+adapter that says it cannot do a thing is correct and slightly limited; one that
+says it can and then does it badly is broken.**
+
+So the desktop adapter scores `0` on anything that is not already a Spotify link,
+and the entry goes to a backend that can actually find it.
+
+```ts
+runtime.can('search');   // false on desktop, true on web — whichever is loaded
+```
+
+## When a human takes over
+
+Spotify is the first backend in this project that somebody else can also touch.
+It has its own transport bar, its own queue, and a listener holding a phone who
+is entirely entitled to press next.
+
+The hard part is that **"the track I loaded is not the track that is playing"
+has two opposite causes**:
+
+```
+   our track ended, Spotify rolled on          a person hit next
+              │                                       │
+              ▼                                       ▼
+        advance OUR queue                     the human wins
+         (event: ended)                    (event: external → adopted)
+```
+
+Get it backwards and the library breaks in the most visible way there is: either
+an agent's carefully built queue silently defers to Spotify's autoplay after
+every single song, or a listener who picks a song has it yanked away.
+
+What separates them is **where the playhead was on the previous reading**. A
+rollover can only happen at the end of a track. The core cannot make that call —
+by the time it sees the mismatch, the evidence is gone — so the adapter keeps it.
+That decision lives in [`sampler.ts`](./src/sampler.ts) as a pure function, and
+every branch of it is a test.
+
+Which way it goes is still the runtime's call, via `desyncPolicy`:
+
+```ts
+new Runtime({ desyncPolicy: 'adopt' });   // default — the human wins
+new Runtime({ desyncPolicy: 'correct' }); // put our track back
+new Runtime({ desyncPolicy: 'ignore' });  // report it, change nothing
+```
+
+## What the desktop adapter will never do
+
+**Launch Spotify behind your back.** Reading state is guarded by
+`if application "Spotify" is running`, because a bare `tell application` *starts*
+the app — and a status poll running every second would boot a music player onto
+the machine of someone who never opened one. Only an explicit `play()` may open
+it, and it does not steal focus when it does.
+
+**Quit your music player.** Spotify's dictionary has no stop that does not quit,
+so `stop()` pauses. The queue moving on to a podcast is not a reason to close
+somebody's app.
+
+## Playlists and albums
+
+A container is not a queue entry — this runtime holds one item at a time and owns
+the ordering itself. So expanding is explicit, and on purpose: you get to see and
+filter the list before it becomes thirty queue entries.
+
+```ts
+const tracks = await spotify.expandContext('spotify:playlist:37i9dQZF1DXcBWIGoYBM5M');
+runtime.enqueueMany(tracks.slice(0, 10));
+```
+
+## Failures worth telling apart
+
+Every error is a `SpotifyError` with a `reason`, because "your token expired" and
+"your phone went to sleep" are both a failed play and an agent that cannot tell
+them apart will nag for a login when all it needed to do was wait.
+
+| `reason` | what it means | what to do |
+|---|---|---|
+| `unauthorized` | no usable session, or macOS Automation was declined | get a token / grant permission |
+| `premium-required` | the account cannot control playback | nothing — it's a free account |
+| `no-device` | nothing to play *on* | open Spotify somewhere |
+| `rate-limited` | too many calls; `retryAfterMs` when Spotify says | wait |
+| `not-found` | not in the catalogue, or not in this market | try another source |
+| `unavailable` | this backend cannot run here at all | use the other adapter |
+
+A backend that cannot start is reported rather than thrown — it is excluded from
+selection and shows up in `getState().adapters` as `available: false` with the
+reason. A host on Linux gets one clear message at startup instead of discovering
+it one failed track at a time.
+
+## What the Web API needs from you
+
+- **Scopes:** `user-read-playback-state` and `user-modify-playback-state`.
+- **Premium.** Every playback-control endpoint is Premium-only. There is nothing
+  an adapter can do about that, so a free account gets `premium-required` rather
+  than a mystery.
+- **Somewhere to play.** The Web API *commands* a device, it is not one. Spotify
+  has to be open somewhere, or `deviceId` has to name something real.
+
+## Options
+
+```ts
+new SpotifyDesktopAdapter({
+  id: 'spotify-desktop',
+  sampleIntervalMs: 1000,   // how often to read the app while something plays
+  lookup: null,             // turn off the credential-free metadata fill-in
+  osascript: myRunner,      // injected for tests
+  scheduler: myScheduler,
+});
+
+new SpotifyWebAdapter({
+  getAccessToken,           // required
+  id: 'spotify-web',
+  deviceId: '…',
+  market: 'US',             // so results are things this listener can play
+  sampleIntervalMs: 2000,   // each sample is a real call against a shared limit
+  fetch: myFetch,           // injected for tests
+});
+```
+
+### About `lookup`
+
+The desktop adapter has no catalogue access, so a queue of share links would show
+a column of raw URIs until each one started playing. To fill in titles it reads
+Spotify's public embed page, which needs no credentials — but **is not a
+documented API**, and Spotify can change it whenever it likes.
+
+So it is a nicety, never a dependency: failures are silent, results are cached,
+lookups are skipped when the ref already has what it needs, and `lookup: null`
+turns it off. Nothing about whether a track *plays* runs through it.
+
+## Testing
+
+Everything is injectable, so all 77 tests run with **no macOS, no Spotify, no
+account and no network** — including a captured reading from a real running copy
+of the app, kept verbatim so a change to the wire format breaks a test rather
+than a user.
+
+## A third door
+
+If you want queue-reading and search with no app registration at all, there is
+[spogo](https://github.com/openclaw/spogo), a CLI that presents itself as the
+Spotify web player using your browser's cookies. It is deliberately **not** a
+dependency here: it works through a rotating secret that Spotify actively
+changes, and pinning a published package to that means the treadmill lands on
+this issue tracker.
+
+The right home for it is
+[`upnext-adapter-process`](https://www.npmjs.com/package/upnext-adapter-process),
+which runs an adapter as a subprocess speaking JSON — so the moving target stays
+on the far side of a process boundary.
+
+---
+
+Apache-2.0 · [source](https://github.com/tothienbao6a0/upnext/tree/main/packages/adapter-spotify)

package/dist/src/applescript.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Talking to the Spotify desktop app through its AppleScript dictionary.
+ *
+ * The script text and the parsing are separated on purpose, and both are
+ * exported. AppleScript is a string until the moment it runs, so the part most
+ * likely to break — a field order that drifts, a property spelled wrong — is
+ * exactly the part a type checker cannot see. Keeping the parser pure means the
+ * wire format has real tests on a machine with no Spotify, no macOS and no
+ * network, which is where this package's CI runs.
+ */
+/** ASCII unit separator. Written as an escape because the character is
+ * invisible in an editor, and chosen over a tab or a pipe because a track title
+ * is free text — anything a person might plausibly type would split a title in
+ * half. */
+export declare const FIELD = "\u001F";
+/** How long any one script may take. A beachballing player, or a first run
+ * waiting on the macOS Automation consent prompt, must not hold a sample
+ * forever and let the next one stack behind it. */
+export declare const SCRIPT_TIMEOUT_MS = 5000;
+/** The one dependency on the outside world, injectable so every decision this
+ * package makes is testable without a Mac, a Spotify account, or an app. */
+export type Osascript = (script: string) => Promise<string>;
+export declare function runOsascript(script: string): Promise<string>;
+/**
+ * One reading of the desktop app.
+ *
+ * `running: false` is a first-class answer, not an error. Spotify not being
+ * open is the ordinary state of most machines most of the time, and a backend
+ * that treats it as a failure would fill a host's logs with news it cannot act
+ * on.
+ */
+export interface Sample {
+    running: boolean;
+    status: 'playing' | 'paused' | 'idle';
+    positionMs: number;
+    durationMs: number | null;
+    /** What Spotify says it is playing, as a `spotify:` URI. */
+    nativeUri: string | null;
+    /** 0..1, or null when the app would not say. */
+    volume: number | null;
+}
+/**
+ * Read the app's state without ever launching it.
+ *
+ * `if application "Spotify" is running` is the load-bearing line. A bare
+ * `tell application "Spotify"` *launches* Spotify, so a sampler running every
+ * second would boot a music player onto the machine of someone who never opened
+ * one — and would do it on a poll the user never asked for. The guard is what
+ * makes this safe to run on a timer.
+ *
+ * Every property sits behind its own `try` so that one that errors — and
+ * `current track` errors whenever nothing is loaded — costs its own field
+ * rather than the whole reading.
+ */
+export declare function stateScript(): string;
+/**
+ * Turn a reading into a `Sample`, or `null` if the text is not one.
+ *
+ * Anything malformed answers null rather than a half-filled sample: a sample
+ * with a NaN playhead would be read as a real position and could end a track
+ * that is still playing, where a missing sample simply means this tick learned
+ * nothing and the next one will.
+ */
+export declare function parseSample(raw: string): Sample | null;
+/**
+ * Start a specific track.
+ *
+ * This is the one script allowed to launch Spotify, because it only ever runs
+ * as the direct result of something asking for playback. `activate` is
+ * deliberately absent: starting a song should not take the foreground away from
+ * whatever the person is actually looking at.
+ *
+ * A start offset needs the pause. `play track` returns as soon as the command
+ * is accepted, not when the track is loaded, and moving the playhead of a track
+ * that has not loaded yet either errors or is silently discarded — so the seek
+ * is retried until it takes, which costs nothing in the common case where
+ * `startAtMs` is zero and none of this runs.
+ */
+export declare function playTrackScript(nativeUri: string, startAtMs?: number): string;
+/**
+ * Any other verb, wrapped so it cannot launch the app.
+ *
+ * There is nothing to pause, seek or re-level in an app that is not open, and
+ * launching one to tell it to be quiet would be absurd — so unlike
+ * `playTrackScript`, everything here is behind the running guard.
+ */
+export declare function commandScript(body: string): string;
+export declare const commands: {
+    readonly play: "play";
+    /**
+     * Spotify's dictionary has no stop that does not quit the app, and quitting
+     * someone's music player because a queue moved to a different source would be
+     * far ruder than leaving it paused. `stop` therefore means pause here, and
+     * that is the honest description of what happens.
+     */
+    readonly pause: "pause";
+    readonly seek: (positionMs: number) => string;
+    readonly volume: (volume: number) => string;
+};
+//# sourceMappingURL=applescript.d.ts.map

package/dist/src/applescript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applescript.d.ts","sourceRoot":"","sources":["../../src/applescript.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH;;;WAGW;AACX,eAAO,MAAM,KAAK,WAAW,CAAC;AAE9B;;mDAEmD;AACnD,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AAEvC;4EAC4E;AAC5E,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE5D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB5D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4DAA4D;IAC5D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gDAAgD;IAChD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,IAAI,MAAM,CA8BpC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBtD;AAqBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,SAAI,GAAG,MAAM,CAkBxE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED,eAAO,MAAM,QAAQ;;IAEnB;;;;;OAKG;;gCAEgB,MAAM;8BACR,MAAM;CAEf,CAAC"}