playlist-data-engine 1.7.2 → 1.8.0

package/dist/utils/engineDocs.d.ts

@@ -0,0 +1,33 @@
+export interface EngineDocTopic {
+    /** Slug accepted by engineHelp(topic) and `npx playlist-data-engine docs <topic>` */
+    slug: string;
+    /** File path relative to the package root */
+    file: string;
+    summary: string;
+}
+export declare const ENGINE_DOC_TOPICS: readonly EngineDocTopic[];
+/**
+ * Timestamped Arweave snapshots of docs/, newest last. Arweave TXs are
+ * immutable, so every entry stays addressable forever — re-uploading after a
+ * docs change adds a new entry and never retires the old ones. Append the
+ * paste-ready output of `node scripts/upload-docs.cjs <wallet.json> --yes`.
+ */
+export interface EngineDocArchiveEntry {
+    /** Engine version the docs describe */
+    version: string;
+    /** ISO timestamp of the upload */
+    uploadedAt: string;
+    /** docs/-relative path → Turbo transaction id */
+    files: Record<string, string>;
+}
+export declare const ENGINE_DOC_ARCHIVE: readonly EngineDocArchiveEntry[];
+/**
+ * Self-describing docs entry point: the doc index, one topic's location, or
+ * the Claude Code skill file. Inlined content only — safe in browsers and
+ * always version-matched to the installed package.
+ *
+ * @param topic - Omit for the doc index; a topic slug (or alias) for one doc's
+ *   location; `'skill'` for the SKILL.md contents.
+ */
+export declare function engineHelp(topic?: string): string;
+//# sourceMappingURL=engineDocs.d.ts.map

package/dist/utils/engineDocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineDocs.d.ts","sourceRoot":"","sources":["../../src/utils/engineDocs.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,cAAc;IAC3B,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAiBtD,CAAC;AAYF;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IAClC,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,qBAAqB,EAuB9D,CAAC;AAqEF;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjD"}

package/dist/utils/playlistUtils.d.ts

@@ -3,6 +3,7 @@
  * "No nonsense" functions that return arrays of basic data from playlists
  */
 import type { ServerlessPlaylist, RawArweavePlaylist } from '../core/types/Playlist.js';
+import { type MixInfo } from '../core/parser/TrackExtras.js';
 /** Input type that accepts both parsed and raw playlists */
 export type PlaylistInput = ServerlessPlaylist | RawArweavePlaylist;
 /** Simplified track object for getTracks() */
@@ -20,6 +21,22 @@ export interface SimpleTrack {
     mint_price?: string;
     mint_snapshot_time?: number;
     mint_token?: string;
+    /** Name of the entry's pinned mix (absent when the entry plays primary audio) */
+    selected_mix?: string;
+}
+/** Track object with mix data for getMixTracks() */
+export interface MixTrackInfo {
+    title: string;
+    artist: string;
+    description?: string;
+    /** The entry's audio URL, already repointed when the entry pins a mix */
+    audio_url: string;
+    audio_url_lossless?: string;
+    image_url: string;
+    /** Name of the entry's pinned mix (absent when the entry plays primary audio) */
+    selected_mix?: string;
+    /** All mixes the track ships */
+    mixes: MixInfo[];
 }
 /** Track object with VRM data for getVRMTracks() */
 export interface VRMTrack {
@@ -154,4 +171,24 @@ export declare function getVRMs(playlist: PlaylistInput): string[];
  * // [{ title: 'Song', artist: 'Artist', audio_url: '...', image_url: '...', image_thumb_url: '...', vrm: '...' }, ...]
  */
 export declare function getVRMTracks(playlist: PlaylistInput): VRMTrack[];
+/**
+ * Get all alternate mixes across a playlist's tracks
+ * @param playlist - Parsed or raw playlist
+ * @returns Array of mixes (flattened across tracks, in track order)
+ *
+ * @example
+ * const mixes = getMixes(playlist);
+ * // [{ name: 'Instrumental', uri: '...', mime_type: 'audio/mpeg', conditions: [] }, ...]
+ */
+export declare function getMixes(playlist: PlaylistInput): MixInfo[];
+/**
+ * Get tracks that ship alternate mixes, with each entry's pin resolved
+ * @param playlist - Parsed or raw playlist
+ * @returns Array of track objects with their mixes and pinned mix name
+ *
+ * @example
+ * const mixTracks = getMixTracks(playlist);
+ * // [{ title: 'Song', artist: 'Artist', audio_url: '...', selected_mix: 'Instrumental', mixes: [...] }, ...]
+ */
+export declare function getMixTracks(playlist: PlaylistInput): MixTrackInfo[];
 //# sourceMappingURL=playlistUtils.d.ts.map

package/dist/utils/playlistUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playlistUtils.d.ts","sourceRoot":"","sources":["../../src/utils/playlistUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAiB,MAAM,2BAA2B,CAAC;AAOvG,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAEpE,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,oDAAoD;AACpD,MAAM,WAAW,QAAQ;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;CACf;AAqHD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CAW9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CAW9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CAuBhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CAuB5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CAoB3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CA4BzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAoBhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAE7D;AAMD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW,EAAE,CAgFhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqDrF;AAMD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CAWzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,QAAQ,EAAE,CAqDhE"}
+{"version":3,"file":"playlistUtils.d.ts","sourceRoot":"","sources":["../../src/utils/playlistUtils.ts"],"names":[],"mappings":"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"}

package/dist/utils/validators.d.ts

@@ -186,4 +186,31 @@ export declare const CharacterSheetSchema: z.ZodObject<{
     seed: z.ZodString;
     generated_at: z.ZodString;
 }, z.core.$strip>;
+/**
+ * Mix condition schema (alternate mixes)
+ */
+export declare const MixConditionSchema: z.ZodObject<{
+    type: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Alternate mix schema
+ */
+export declare const MixInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    uri: z.ZodOptional<z.ZodString>;
+    mime_type: z.ZodOptional<z.ZodString>;
+    conditions: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Stem schema
+ */
+export declare const StemInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    uri: z.ZodOptional<z.ZodString>;
+    mime_type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 //# sourceMappingURL=validators.d.ts.map

package/dist/utils/validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/utils/validators.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;iBAoC/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQnC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;iBAuB7B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;iBAO9B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkD/B,CAAC"}
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/utils/validators.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;iBAoC/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQnC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;iBAuB7B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;iBAO9B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkD/B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;iBAKxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc;;;;iBAIzB,CAAC"}