@keystrokehq/spotify 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Keystroke
+
+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,113 @@
+# @keystrokehq/spotify
+
+Spotify integration for Keystroke workflows and agents.
+
+## Overview
+
+This package provides official Spotify authoring surfaces for:
+
+- catalog reads across albums, artists, tracks, shows, episodes, audiobooks, and chapters
+- playlist management, follow/library helpers, and playback controls
+- polling triggers for devices, playlists, recently played tracks, and saved items
+- an official Spotify platform-app credential seed for Keystroke-managed OAuth
+
+## Installation
+
+```bash
+pnpm add @keystrokehq/spotify
+```
+
+## Credentials
+
+Public connection shape:
+
+- `SPOTIFY_ACCESS_TOKEN`
+
+Internal provider-app credential shape:
+
+- `clientId`
+- `clientSecret`
+
+Spotify access tokens are short-lived and the public connection is modeled as OAuth. Provider-owned app credentials stay on the internal platform-app seed rather than the public user connection.
+
+## Safety Model
+
+Mutating operations are marked with `needsApproval: true`.
+
+Spotify playback writes also inherit Spotify's own Premium and device-availability constraints.
+
+## Example
+
+```ts
+import { spotify } from '@keystrokehq/spotify/connection';
+import { getAlbum } from '@keystrokehq/spotify/albums';
+import { createPlaylist } from '@keystrokehq/spotify/playlists';
+
+void spotify;
+void getAlbum;
+void createPlaylist;
+```
+
+```ts
+import { spotifyOperations } from '@keystrokehq/spotify/operations';
+
+void spotifyOperations.get_spotify_album;
+void spotifyOperations.SPOTIFY_GET_AN_ARTIST;
+void spotifyOperations.SPOTIFY_GET_RECENTLY_PLAYED_TRACKS;
+```
+
+```ts
+import { polling } from '@keystrokehq/spotify/triggers';
+
+void polling.newDeviceAdded({ schedule: '5m' });
+void polling.playlistItemsChanged({ playlistId: 'playlist-123', schedule: '10m' });
+void polling.savedItemAdded({ itemType: 'track', schedule: '15m' });
+```
+
+## Domain Modules
+
+- `@keystrokehq/spotify/albums`
+- `@keystrokehq/spotify/artists`
+- `@keystrokehq/spotify/tracks`
+- `@keystrokehq/spotify/shows`
+- `@keystrokehq/spotify/episodes`
+- `@keystrokehq/spotify/audiobooks`
+- `@keystrokehq/spotify/chapters`
+- `@keystrokehq/spotify/search`
+- `@keystrokehq/spotify/browse`
+- `@keystrokehq/spotify/markets`
+- `@keystrokehq/spotify/genres`
+- `@keystrokehq/spotify/categories`
+- `@keystrokehq/spotify/recommendations`
+- `@keystrokehq/spotify/playlists`
+- `@keystrokehq/spotify/users`
+- `@keystrokehq/spotify/me`
+- `@keystrokehq/spotify/follow`
+- `@keystrokehq/spotify/player`
+- `@keystrokehq/spotify/library`
+- `@keystrokehq/spotify/audio-features`
+- `@keystrokehq/spotify/audio-analysis`
+- `@keystrokehq/spotify/operations`
+- `@keystrokehq/spotify/triggers`
+
+## Polling Triggers
+
+Spotify does not expose a server-side webhook/event surface for this package, so all first-class triggers are polling-based:
+
+- `polling.newDeviceAdded()`
+- `polling.playlistItemsChanged({ playlistId })`
+- `polling.userPlaylistsChanged()`
+- `polling.recentlyPlayedTrackAdded()`
+- `polling.savedItemAdded({ itemType })`
+
+## Deprecated Or Restricted Endpoints
+
+Spotify's current platform docs still expose some endpoints that may be restricted or return app-eligibility errors for newer apps. This package keeps those operations available, but documents them as deprecated where applicable:
+
+- artist related artists
+- available genre seeds
+- recommendations
+- audio features
+- audio analysis
+- featured playlists
+- category playlists

package/dist/_official/index.d.mts

@@ -0,0 +1,32 @@
+import { i as spotifyOfficialIntegration, r as spotifyBundle } from "../integration-DQ5Egd4f.mjs";
+import { z } from "zod";
+import { CredentialSet } from "@keystrokehq/core";
+import * as _keystrokehq_core_credential_set0 from "@keystrokehq/core/credential-set";
+
+//#region src/_official/provider-app.d.ts
+declare const spotifyAppCredentialSet: CredentialSet<"spotify-app", z.ZodObject<{
+  clientId: z.ZodString;
+  clientSecret: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  clientId: z.ZodString;
+  clientSecret: z.ZodString;
+}, z.core.$strip>>[] | undefined>;
+declare const spotifyPlatformProviderSeed: {
+  readonly provider: "spotify";
+  readonly appRef: "spotify-platform";
+  readonly displayName: "Spotify Platform";
+  readonly credentialSetName: "Keystroke Spotify Platform App";
+  readonly envShape: {
+    readonly KEYSTROKE_PLATFORM_SPOTIFY_CLIENT_ID: z.ZodOptional<z.ZodString>;
+    readonly KEYSTROKE_PLATFORM_SPOTIFY_CLIENT_SECRET: z.ZodOptional<z.ZodString>;
+  };
+  readonly requiredEnvKeys: readonly ["KEYSTROKE_PLATFORM_SPOTIFY_CLIENT_ID", "KEYSTROKE_PLATFORM_SPOTIFY_CLIENT_SECRET"];
+  readonly externalAppIdEnvKey: "KEYSTROKE_PLATFORM_SPOTIFY_CLIENT_ID";
+  readonly buildCredentials: (env: Record<string, string | undefined>) => {
+    clientId: string | undefined;
+    clientSecret: string | undefined;
+  };
+};
+type SpotifyAppCredentials = z.infer<typeof spotifyAppCredentialSet.auth>;
+//#endregion
+export { SpotifyAppCredentials, spotifyAppCredentialSet, spotifyBundle, spotifyOfficialIntegration, spotifyPlatformProviderSeed };

package/dist/_official/index.mjs

@@ -0,0 +1,3 @@
+import { a as spotifyPlatformProviderSeed, i as spotifyAppCredentialSet, n as spotifyBundle, r as spotifyOfficialIntegration } from "../integration-ykoImsCq.mjs";
+
+export { spotifyAppCredentialSet, spotifyBundle, spotifyOfficialIntegration, spotifyPlatformProviderSeed };

package/dist/_runtime/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/_runtime/index.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/albums.d.mts

@@ -0,0 +1,265 @@
+import { z } from "zod";
+import * as _keystrokehq_core0 from "@keystrokehq/core";
+import * as _keystrokehq_core_credential_set0 from "@keystrokehq/core/credential-set";
+
+//#region src/albums.d.ts
+declare const getAlbum: _keystrokehq_core0.Operation<z.ZodObject<{
+  id: z.ZodString;
+  market: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  albumType: z.ZodOptional<z.ZodEnum<{
+    album: "album";
+    single: "single";
+    compilation: "compilation";
+  }>>;
+  artists: z.ZodArray<z.ZodObject<{
+    externalUrls: z.ZodOptional<z.ZodObject<{
+      spotify: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+    href: z.ZodOptional<z.ZodURL>;
+    id: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodLiteral<"artist">;
+    uri: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  availableMarkets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  externalUrls: z.ZodOptional<z.ZodObject<{
+    spotify: z.ZodOptional<z.ZodURL>;
+  }, z.core.$strip>>;
+  href: z.ZodOptional<z.ZodURL>;
+  id: z.ZodString;
+  images: z.ZodArray<z.ZodObject<{
+    url: z.ZodURL;
+    height: z.ZodNullable<z.ZodNumber>;
+    width: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  name: z.ZodString;
+  releaseDate: z.ZodOptional<z.ZodString>;
+  releaseDatePrecision: z.ZodOptional<z.ZodEnum<{
+    year: "year";
+    month: "month";
+    day: "day";
+  }>>;
+  totalTracks: z.ZodOptional<z.ZodNumber>;
+  type: z.ZodLiteral<"album">;
+  uri: z.ZodOptional<z.ZodString>;
+  copyrights: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    text: z.ZodString;
+    type: z.ZodString;
+  }, z.core.$strip>>>;
+  genres: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  label: z.ZodOptional<z.ZodString>;
+  popularity: z.ZodOptional<z.ZodNumber>;
+  restrictions: z.ZodOptional<z.ZodObject<{
+    reason: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"spotify", z.ZodObject<{
+  SPOTIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  SPOTIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>>[] | undefined>], undefined>;
+declare const getAlbumTracks: _keystrokehq_core0.Operation<z.ZodObject<{
+  limit: z.ZodOptional<z.ZodNumber>;
+  offset: z.ZodOptional<z.ZodNumber>;
+  id: z.ZodString;
+  market: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  href: z.ZodOptional<z.ZodURL>;
+  items: z.ZodArray<z.ZodObject<{
+    album: z.ZodOptional<z.ZodObject<{
+      albumType: z.ZodOptional<z.ZodEnum<{
+        album: "album";
+        single: "single";
+        compilation: "compilation";
+      }>>;
+      artists: z.ZodArray<z.ZodObject<{
+        externalUrls: z.ZodOptional<z.ZodObject<{
+          spotify: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strip>>;
+        href: z.ZodOptional<z.ZodURL>;
+        id: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodLiteral<"artist">;
+        uri: z.ZodOptional<z.ZodString>;
+      }, z.core.$strip>>;
+      availableMarkets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      externalUrls: z.ZodOptional<z.ZodObject<{
+        spotify: z.ZodOptional<z.ZodURL>;
+      }, z.core.$strip>>;
+      href: z.ZodOptional<z.ZodURL>;
+      id: z.ZodString;
+      images: z.ZodArray<z.ZodObject<{
+        url: z.ZodURL;
+        height: z.ZodNullable<z.ZodNumber>;
+        width: z.ZodNullable<z.ZodNumber>;
+      }, z.core.$strip>>;
+      name: z.ZodString;
+      releaseDate: z.ZodOptional<z.ZodString>;
+      releaseDatePrecision: z.ZodOptional<z.ZodEnum<{
+        year: "year";
+        month: "month";
+        day: "day";
+      }>>;
+      totalTracks: z.ZodOptional<z.ZodNumber>;
+      type: z.ZodLiteral<"album">;
+      uri: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    artists: z.ZodArray<z.ZodObject<{
+      externalUrls: z.ZodOptional<z.ZodObject<{
+        spotify: z.ZodOptional<z.ZodURL>;
+      }, z.core.$strip>>;
+      href: z.ZodOptional<z.ZodURL>;
+      id: z.ZodString;
+      name: z.ZodString;
+      type: z.ZodLiteral<"artist">;
+      uri: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    availableMarkets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    discNumber: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodNumber;
+    explicit: z.ZodBoolean;
+    externalIds: z.ZodOptional<z.ZodObject<{
+      isrc: z.ZodOptional<z.ZodString>;
+      ean: z.ZodOptional<z.ZodString>;
+      upc: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    externalUrls: z.ZodOptional<z.ZodObject<{
+      spotify: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+    href: z.ZodOptional<z.ZodURL>;
+    id: z.ZodString;
+    isLocal: z.ZodOptional<z.ZodBoolean>;
+    isPlayable: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodString;
+    popularity: z.ZodOptional<z.ZodNumber>;
+    previewUrl: z.ZodOptional<z.ZodUnion<readonly [z.ZodURL, z.ZodNull]>>;
+    restrictions: z.ZodOptional<z.ZodObject<{
+      reason: z.ZodString;
+    }, z.core.$strip>>;
+    trackNumber: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"track">;
+    uri: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  limit: z.ZodNumber;
+  nextPageToken: z.ZodOptional<z.ZodString>;
+  offset: z.ZodNumber;
+  previousPageToken: z.ZodOptional<z.ZodString>;
+  total: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"spotify", z.ZodObject<{
+  SPOTIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  SPOTIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>>[] | undefined>], undefined>;
+declare const getSeveralAlbums: _keystrokehq_core0.Operation<z.ZodObject<{
+  ids: z.ZodArray<z.ZodString>;
+  market: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  albums: z.ZodArray<z.ZodObject<{
+    albumType: z.ZodOptional<z.ZodEnum<{
+      album: "album";
+      single: "single";
+      compilation: "compilation";
+    }>>;
+    artists: z.ZodArray<z.ZodObject<{
+      externalUrls: z.ZodOptional<z.ZodObject<{
+        spotify: z.ZodOptional<z.ZodURL>;
+      }, z.core.$strip>>;
+      href: z.ZodOptional<z.ZodURL>;
+      id: z.ZodString;
+      name: z.ZodString;
+      type: z.ZodLiteral<"artist">;
+      uri: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    availableMarkets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    externalUrls: z.ZodOptional<z.ZodObject<{
+      spotify: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+    href: z.ZodOptional<z.ZodURL>;
+    id: z.ZodString;
+    images: z.ZodArray<z.ZodObject<{
+      url: z.ZodURL;
+      height: z.ZodNullable<z.ZodNumber>;
+      width: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    name: z.ZodString;
+    releaseDate: z.ZodOptional<z.ZodString>;
+    releaseDatePrecision: z.ZodOptional<z.ZodEnum<{
+      year: "year";
+      month: "month";
+      day: "day";
+    }>>;
+    totalTracks: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"album">;
+    uri: z.ZodOptional<z.ZodString>;
+    copyrights: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      text: z.ZodString;
+      type: z.ZodString;
+    }, z.core.$strip>>>;
+    genres: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    label: z.ZodOptional<z.ZodString>;
+    popularity: z.ZodOptional<z.ZodNumber>;
+    restrictions: z.ZodOptional<z.ZodObject<{
+      reason: z.ZodString;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"spotify", z.ZodObject<{
+  SPOTIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  SPOTIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>>[] | undefined>], undefined>;
+declare const getNewReleases: _keystrokehq_core0.Operation<z.ZodObject<{
+  limit: z.ZodOptional<z.ZodNumber>;
+  offset: z.ZodOptional<z.ZodNumber>;
+  country: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  href: z.ZodOptional<z.ZodURL>;
+  items: z.ZodArray<z.ZodObject<{
+    albumType: z.ZodOptional<z.ZodEnum<{
+      album: "album";
+      single: "single";
+      compilation: "compilation";
+    }>>;
+    artists: z.ZodArray<z.ZodObject<{
+      externalUrls: z.ZodOptional<z.ZodObject<{
+        spotify: z.ZodOptional<z.ZodURL>;
+      }, z.core.$strip>>;
+      href: z.ZodOptional<z.ZodURL>;
+      id: z.ZodString;
+      name: z.ZodString;
+      type: z.ZodLiteral<"artist">;
+      uri: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    availableMarkets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    externalUrls: z.ZodOptional<z.ZodObject<{
+      spotify: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+    href: z.ZodOptional<z.ZodURL>;
+    id: z.ZodString;
+    images: z.ZodArray<z.ZodObject<{
+      url: z.ZodURL;
+      height: z.ZodNullable<z.ZodNumber>;
+      width: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    name: z.ZodString;
+    releaseDate: z.ZodOptional<z.ZodString>;
+    releaseDatePrecision: z.ZodOptional<z.ZodEnum<{
+      year: "year";
+      month: "month";
+      day: "day";
+    }>>;
+    totalTracks: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"album">;
+    uri: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  limit: z.ZodNumber;
+  nextPageToken: z.ZodOptional<z.ZodString>;
+  offset: z.ZodNumber;
+  previousPageToken: z.ZodOptional<z.ZodString>;
+  total: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"spotify", z.ZodObject<{
+  SPOTIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  SPOTIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>>[] | undefined>], undefined>;
+//#endregion
+export { getAlbum, getAlbumTracks, getNewReleases, getSeveralAlbums };

package/dist/albums.mjs

@@ -0,0 +1,72 @@
+import { spotifyAlbumPageSchema, spotifyAlbumSchema, spotifyIdSchema, spotifyMarketSchema, spotifyTrackPageSchema } from "./schemas.mjs";
+import { createSpotifyClient } from "./client.mjs";
+import { t as spotifyOperation } from "./factory-tZba6Hij.mjs";
+import { z } from "zod";
+
+//#region src/albums.ts
+const albumIdListSchema = z.array(spotifyIdSchema).min(1).max(20);
+const pagingSchema = z.object({
+	limit: z.number().int().positive().max(50).optional(),
+	offset: z.number().int().nonnegative().optional()
+});
+const severalAlbumsResponseSchema = z.object({ albums: z.array(spotifyAlbumSchema) });
+const getAlbum = spotifyOperation({
+	id: "get_spotify_album",
+	name: "Get Spotify Album",
+	description: "Fetch a Spotify album by its ID.",
+	input: z.object({
+		id: spotifyIdSchema,
+		market: spotifyMarketSchema.optional()
+	}),
+	output: spotifyAlbumSchema,
+	run: async (input, credentials) => {
+		return createSpotifyClient(credentials).albums.getAlbum(input.id, input.market);
+	}
+});
+const getAlbumTracks = spotifyOperation({
+	id: "get_spotify_album_tracks",
+	name: "Get Spotify Album Tracks",
+	description: "List tracks for a Spotify album.",
+	input: pagingSchema.extend({
+		id: spotifyIdSchema,
+		market: spotifyMarketSchema.optional()
+	}),
+	output: spotifyTrackPageSchema,
+	run: async (input, credentials) => {
+		return createSpotifyClient(credentials).albums.getAlbumTracks(input.id, {
+			market: input.market,
+			limit: input.limit,
+			offset: input.offset
+		});
+	}
+});
+const getSeveralAlbums = spotifyOperation({
+	id: "get_spotify_several_albums",
+	name: "Get Several Spotify Albums",
+	description: "Fetch multiple Spotify albums in one request.",
+	input: z.object({
+		ids: albumIdListSchema,
+		market: spotifyMarketSchema.optional()
+	}),
+	output: severalAlbumsResponseSchema,
+	run: async (input, credentials) => {
+		return createSpotifyClient(credentials).albums.getSeveralAlbums(input.ids, input.market);
+	}
+});
+const getNewReleases = spotifyOperation({
+	id: "get_spotify_new_releases",
+	name: "Get Spotify New Releases",
+	description: "List Spotify new-release albums for a market.",
+	input: pagingSchema.extend({ country: spotifyMarketSchema.optional() }),
+	output: spotifyAlbumPageSchema,
+	run: async (input, credentials) => {
+		return createSpotifyClient(credentials).albums.getNewReleases({
+			country: input.country,
+			limit: input.limit,
+			offset: input.offset
+		});
+	}
+});
+
+//#endregion
+export { getAlbum, getAlbumTracks, getNewReleases, getSeveralAlbums };