@opfelmusig/lib 0.0.0-ci.0.sha-3e76884

package/dist/core/error.d.ts

@@ -0,0 +1,23 @@
+import type z from "zod";
+import { type AppleMusicErrorSchema } from "../schemas/error.js";
+export type AppleMusicErrorKind = "response" | "network";
+export type AppleMusicErrorDetail = z.infer<typeof AppleMusicErrorSchema>;
+export interface AppleMusicErrorOptions {
+    kind: AppleMusicErrorKind;
+    url: string;
+    status?: number;
+    statusText?: string;
+    retryAfter?: string;
+    errors?: readonly AppleMusicErrorDetail[];
+    message?: string;
+    cause?: unknown;
+}
+export declare class AppleMusicError extends Error {
+    readonly kind: AppleMusicErrorKind;
+    readonly url: string;
+    readonly status?: number;
+    readonly statusText?: string;
+    readonly retryAfter?: string;
+    readonly errors: readonly AppleMusicErrorDetail[];
+    constructor(options: AppleMusicErrorOptions);
+}

package/dist/core/error.js

@@ -0,0 +1,24 @@
+import {} from "../schemas/error.js";
+function getDefaultMessage(options) {
+    if (options.kind === "network")
+        return "Apple Music API network error";
+    return `Apple Music API error ${options.status ?? "unknown"}${options.statusText ? ` ${options.statusText}` : ""}`;
+}
+export class AppleMusicError extends Error {
+    kind;
+    url;
+    status;
+    statusText;
+    retryAfter;
+    errors;
+    constructor(options) {
+        super(options.message ?? getDefaultMessage(options), { cause: options.cause });
+        this.name = "AppleMusicError";
+        this.kind = options.kind;
+        this.url = options.url;
+        this.status = options.status;
+        this.statusText = options.statusText;
+        this.retryAfter = options.retryAfter;
+        this.errors = options.errors ?? [];
+    }
+}

package/dist/core/http.d.ts

@@ -0,0 +1,22 @@
+import type { OpfelMusigConfig } from "../types/config.js";
+import type { OpfelMusigHttpRequest } from "../types/request.js";
+export declare const appleMusicApiUrl = "https://amp-api.music.apple.com";
+type DeepPartialNullable<T> = T extends (...args: any[]) => any ? T | null : T extends object ? {
+    [K in keyof T]?: DeepPartialNullable<T[K]> | null;
+} : T | null;
+export declare class HttpClient {
+    private config;
+    constructor(config: OpfelMusigConfig);
+    edit: (config: DeepPartialNullable<OpfelMusigConfig>) => void;
+    get conf(): {
+        storefront: string | undefined;
+        language: import("../types/config.js").LanguageConfig | undefined;
+    };
+    private prepareTokens;
+    private get baseUrl();
+    private emit;
+    private send;
+    request<T>(path: string, request?: OpfelMusigHttpRequest): Promise<T>;
+    requestUrl<T>(url: string, request?: OpfelMusigHttpRequest): Promise<T>;
+}
+export {};

package/dist/core/http.js

@@ -0,0 +1,232 @@
+import { AppleMusicError } from "../core/error.js";
+import { getDefaultHeaders } from "../helpers/public.js";
+import { RequestQueryBuilder } from "../helpers/requestQuery.js";
+import { AppleMusicErrorResponseSchema } from "../schemas/error.js";
+export const appleMusicApiUrl = "https://amp-api.music.apple.com";
+function mergePatch(current, patch) {
+    const next = { ...current };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        if (value === null) {
+            delete next[key];
+            continue;
+        }
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            next[key] = mergePatch((next[key] ?? {}), value);
+            continue;
+        }
+        next[key] = value;
+    }
+    return next;
+}
+async function resolveToken(token) {
+    return typeof token === "function" ? token() : token;
+}
+function rethrowAbort(cause, signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? cause;
+    if (cause instanceof Error && cause.name === "AbortError")
+        throw cause;
+}
+function headerValue(headers, name) {
+    const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase());
+    return entry?.[1];
+}
+function bearerToken(value) {
+    return value?.match(/^Bearer\s+(.+)$/i)?.[1];
+}
+function httpEventError(kind, aborted = false) {
+    if (aborted) {
+        return {
+            name: "AbortError",
+            message: "Request aborted",
+        };
+    }
+    return kind === "network"
+        ? {
+            name: "NetworkError",
+            message: "Request failed",
+        }
+        : {
+            name: "ParseError",
+            message: "Response parsing failed",
+        };
+}
+export class HttpClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    edit = (config) => {
+        this.config = mergePatch(this.config, config);
+    };
+    get conf() {
+        return {
+            storefront: this.config.storefront,
+            language: this.config.language,
+        };
+    }
+    async prepareTokens() {
+        return {
+            developerToken: await resolveToken(this.config.developerToken),
+            userToken: await resolveToken(this.config.userToken),
+            excludeOrigin: this.config.excludeOrigin,
+        };
+    }
+    get baseUrl() {
+        const baseUrl = this.config.baseUrl ?? appleMusicApiUrl;
+        return baseUrl.replace(/\/$/, "");
+    }
+    emit(event) {
+        const observer = this.config.onHttpEvent;
+        if (!observer)
+            return;
+        try {
+            Promise.resolve(observer(event)).catch(() => { });
+        }
+        catch {
+            return;
+        }
+    }
+    async send(url, request) {
+        const configuredTokens = await this.prepareTokens();
+        const headers = {
+            ...getDefaultHeaders(configuredTokens),
+            ...this.config.extraHeaders,
+            ...request.config?.extraHeaders,
+            ...request.headers,
+        };
+        const method = request.method ?? "GET";
+        const requestTokens = {
+            developerToken: bearerToken(headerValue(headers, "Authorization")) ?? configuredTokens.developerToken,
+            userToken: headerValue(headers, "Media-User-Token") ??
+                headerValue(headers, "Music-User-Token") ??
+                configuredTokens.userToken,
+            excludeOrigin: configuredTokens.excludeOrigin,
+        };
+        const body = typeof request.body === "function" ? request.body(requestTokens) : request.body;
+        const fetch = this.config.fetch ?? globalThis.fetch;
+        const startedAt = performance.now();
+        let response;
+        try {
+            response = await fetch(url, {
+                body,
+                headers,
+                method,
+                signal: request.config?.signal,
+            });
+        }
+        catch (cause) {
+            const aborted = request.config?.signal?.aborted || (cause instanceof Error && cause.name === "AbortError");
+            this.emit({
+                method,
+                url,
+                durationMs: performance.now() - startedAt,
+                error: httpEventError("network", aborted),
+            });
+            rethrowAbort(cause, request.config?.signal);
+            throw new AppleMusicError({
+                kind: "network",
+                url,
+                cause,
+            });
+        }
+        if (this.config.debug) {
+            console.log(`RES ${response.status} [${response.statusText}]`);
+        }
+        const responseContext = {
+            url,
+            status: response.status,
+            statusText: response.statusText,
+            retryAfter: response.headers.get("Retry-After") ?? undefined,
+        };
+        let result;
+        try {
+            result =
+                response.status === 204 || response.status === 205 ? undefined : await response.json();
+        }
+        catch (cause) {
+            const aborted = request.config?.signal?.aborted || (cause instanceof Error && cause.name === "AbortError");
+            this.emit({
+                method,
+                url,
+                status: response.status,
+                statusText: response.statusText,
+                durationMs: performance.now() - startedAt,
+                error: httpEventError("parse", aborted),
+            });
+            throw cause;
+        }
+        if (!response.ok) {
+            let errorResponse;
+            try {
+                errorResponse = AppleMusicErrorResponseSchema.parse(result);
+            }
+            catch (cause) {
+                this.emit({
+                    method,
+                    url,
+                    status: response.status,
+                    statusText: response.statusText,
+                    durationMs: performance.now() - startedAt,
+                    response: result,
+                    error: httpEventError("parse"),
+                });
+                throw cause;
+            }
+            this.emit({
+                method,
+                url,
+                status: response.status,
+                statusText: response.statusText,
+                durationMs: performance.now() - startedAt,
+                response: result,
+            });
+            throw new AppleMusicError({
+                kind: "response",
+                ...responseContext,
+                errors: errorResponse.errors,
+            });
+        }
+        this.emit({
+            method,
+            url,
+            status: response.status,
+            statusText: response.statusText,
+            durationMs: performance.now() - startedAt,
+            response: result,
+        });
+        return result;
+    }
+    async request(path, request = {}) {
+        const questionIndex = path.indexOf("?");
+        const url = questionIndex === -1 ? path : path.slice(0, questionIndex);
+        const params = questionIndex === -1 ? "" : path.slice(questionIndex + 1);
+        const requestPath = url
+            .replace("{{storefront}}", request.config?.storefront ?? this.config.storefront ?? "us")
+            .replace(/^\/+/, "");
+        const requestQuery = RequestQueryBuilder.create(request.query)
+            .language(this.config.language)
+            .requestConfig(request.config)
+            .urlParams(params)
+            .set("art[url]", "f")
+            .set("omit[resource]", "autos")
+            .prepare();
+        const query = new URLSearchParams(requestQuery).toString();
+        const requestUrl = `${this.baseUrl}/${requestPath}${query ? `?${query}` : ""}`;
+        const method = request.method ?? "GET";
+        if (this.config.debug) {
+            const { ["art[url]"]: artworkUrlFormat, ["omit[resource]"]: omitResource, ...rest } = requestQuery;
+            console.log(`REQ ${method} [/${requestPath}] - ${JSON.stringify(rest)}`);
+        }
+        return this.send(requestUrl, request);
+    }
+    async requestUrl(url, request = {}) {
+        const parsedUrl = new URL(url);
+        if (this.config.debug) {
+            console.log(`REQ ${request.method ?? "GET"} [${parsedUrl.origin}${parsedUrl.pathname}]`);
+        }
+        return this.send(url, request);
+    }
+}

package/dist/helpers/language.d.ts

@@ -0,0 +1 @@
+export declare function lyricScriptFromLanguage(language?: string): string | undefined;

package/dist/helpers/language.js

@@ -0,0 +1,48 @@
+const lyricScripts = {
+    am: "Ethi",
+    ar: "Arab",
+    be: "Cyrl",
+    bg: "Cyrl",
+    bn: "Beng",
+    bo: "Tibt",
+    el: "Grek",
+    fa: "Arab",
+    gu: "Gujr",
+    he: "Hebr",
+    hi: "Deva",
+    hy: "Armn",
+    ja: "Kana",
+    ka: "Geor",
+    kk: "Cyrl",
+    km: "Khmr",
+    kn: "Knda",
+    ko: "Hang",
+    ky: "Cyrl",
+    lo: "Laoo",
+    mk: "Cyrl",
+    ml: "Mlym",
+    mn: "Cyrl",
+    mr: "Deva",
+    my: "Mymr",
+    ne: "Deva",
+    or: "Orya",
+    pa: "Guru",
+    ps: "Arab",
+    ru: "Cyrl",
+    sa: "Deva",
+    sd: "Arab",
+    si: "Sinh",
+    sr: "Cyrl",
+    ta: "Taml",
+    te: "Telu",
+    th: "Thai",
+    ti: "Ethi",
+    uk: "Cyrl",
+    ur: "Aran",
+    yi: "Hebr",
+    zh: "Hans",
+};
+export function lyricScriptFromLanguage(language) {
+    const languageCode = language?.split("-")[0]?.toLowerCase();
+    return languageCode ? `${languageCode}-${lyricScripts[languageCode] ?? "Latn"}` : undefined;
+}

package/dist/helpers/public.d.ts

@@ -0,0 +1,19 @@
+import type { ResourceScopes } from "../types/query/scopes.js";
+import type { HeaderConfig } from "../types/request.js";
+import type { Artwork } from "../types/shared.js";
+interface ImageOptions {
+    width?: number;
+    height?: number;
+    crop?: string;
+    format?: string;
+}
+export declare function defineScopes<const TScopes extends ResourceScopes>(scopes: TScopes): TScopes;
+export declare function parseImageUrl(image: string, options?: ImageOptions): string;
+export declare function getArtworkUrl(artwork?: Artwork | string | null, options?: ImageOptions): string | undefined;
+export declare function getDefaultHeaders(config?: HeaderConfig): {
+    Origin?: string | undefined;
+    Authorization?: string | undefined;
+    "Music-User-Token"?: string | undefined;
+    "Media-User-Token"?: string | undefined;
+};
+export { lyricScriptFromLanguage } from "../helpers/language.js";

package/dist/helpers/public.js

@@ -0,0 +1,35 @@
+export function defineScopes(scopes) {
+    return scopes;
+}
+export function parseImageUrl(image, options = {}) {
+    const width = options?.width ?? options?.height ?? 512;
+    const height = options?.height ?? width;
+    return image
+        .replace("{w}", String(width))
+        .replace("{h}", String(height))
+        .replace("{c}", options.crop ?? "")
+        .replace("{f}", options.format ?? "jpg");
+}
+export function getArtworkUrl(artwork, options = {}) {
+    const url = typeof artwork === "string" ? artwork : artwork?.url;
+    if (!url)
+        return;
+    return parseImageUrl(url, options);
+}
+export function getDefaultHeaders(config) {
+    return {
+        ...(config?.excludeOrigin ? {} : { Origin: "https://music.apple.com" }),
+        ...(config?.developerToken
+            ? {
+                Authorization: `Bearer ${config.developerToken}`,
+            }
+            : {}),
+        ...(config?.userToken
+            ? {
+                "Music-User-Token": config.userToken,
+                "Media-User-Token": config.userToken,
+            }
+            : {}),
+    };
+}
+export { lyricScriptFromLanguage } from "../helpers/language.js";

package/dist/helpers/requestQuery.d.ts

@@ -0,0 +1,17 @@
+import type { LanguageConfig, RequestConfig } from "../types/config.js";
+export declare class RequestQueryBuilder {
+    private query;
+    static create(base?: RequestQueryBuilder): RequestQueryBuilder;
+    params(params?: Record<string, any>): this;
+    private shape;
+    private scopes;
+    private scope;
+    language(language?: LanguageConfig): this;
+    requestConfig(config: RequestConfig | undefined): this;
+    urlParams(params: string): this;
+    set(key?: string, value?: string, scope?: string): this;
+    setNumber(key: string, value?: number, scope?: string): this;
+    setStringArray(key: string, values?: string | string[], scope?: string): this;
+    setString(key: string, value?: string, scope?: string): this;
+    prepare(): Record<string, string>;
+}

package/dist/helpers/requestQuery.js

@@ -0,0 +1,153 @@
+import { ScopeSchema, ScopesSchema, ShapeSchema } from "../schemas/request.js";
+export class RequestQueryBuilder {
+    query = {};
+    static create(base) {
+        const requestQuery = new RequestQueryBuilder();
+        requestQuery.query = base?.query ? structuredClone(base.query) : {};
+        return requestQuery;
+    }
+    params(params) {
+        if (!params)
+            return this;
+        for (const [key, value] of Object.entries(params)) {
+            if (["limit", "offset"].includes(key)) {
+                this.setNumber(key, value);
+            }
+            if (key === "scopes") {
+                this.scopes(value);
+            }
+            if (key === "shape") {
+                this.shape(value);
+            }
+        }
+        return this;
+    }
+    shape(value) {
+        const result = ShapeSchema.safeParse(value);
+        if (!result.success) {
+            console.warn(`[Opfelmusig/RequestQuery] 'shape' is not in the correct format, skipping.`, result.error.issues[0]?.message);
+            return;
+        }
+        this.setStringArray("types", result.data.types);
+        if (result.data.with)
+            this.setStringArray("with", result.data.with);
+    }
+    scopes(value) {
+        const result = ScopesSchema.safeParse(value);
+        if (!result.success) {
+            console.warn(`[Opfelmusig/RequestQuery] 'scopes' is not in the correct format, skipping.`, result.error.issues[0]?.message);
+            return;
+        }
+        for (const [key, value] of Object.entries(result.data)) {
+            const result = ScopeSchema.safeParse(value);
+            if (!result.success) {
+                console.warn(`[Opfelmusig/RequestQuery] 'scopes/${key}' is not in the correct format, skipping.`, result.error.issues[0]?.message);
+                continue;
+            }
+            this.scope(key, result.data);
+        }
+    }
+    scope(scope, value) {
+        const fields = value.fields ? [...(value.fields ?? []), ...(value.extend ?? [])] : [];
+        if (fields.length)
+            this.setStringArray("fields", fields, scope);
+        if (value.extend?.length)
+            this.setStringArray("extend", value.extend, scope);
+        if (value.relationships) {
+            const include = [];
+            const relate = [];
+            for (const [name, options] of Object.entries(value.relationships)) {
+                const mode = typeof options === "string" ? options : options.mode;
+                if (mode === "include")
+                    include.push(name);
+                if (mode === "relate")
+                    relate.push(name);
+                if (typeof options === "object") {
+                    this.setNumber("limit", options.limit, `${scope}:${name}`);
+                }
+            }
+            if (include.length)
+                this.setStringArray("include", include, scope);
+            if (relate.length)
+                this.setStringArray("relate", relate, scope);
+        }
+        if (value.views) {
+            const views = [];
+            for (const [name, options] of Object.entries(value.views)) {
+                if (!options)
+                    continue;
+                views.push(name);
+                if (typeof options === "object") {
+                    this.setNumber("limit", options.limit, `${scope}:${name}`);
+                }
+            }
+            if (views.length)
+                this.setStringArray("views", views, scope);
+        }
+    }
+    language(language) {
+        if (language) {
+            this.setString("l", language.default);
+            this.setString("l[lyrics]", language.lyrics);
+            this.setString("l[script]", language.script);
+        }
+        return this;
+    }
+    requestConfig(config) {
+        this.language(config?.language);
+        if (config?.extraParams) {
+            for (const [key, value] of Object.entries(config.extraParams)) {
+                if (key === undefined || value === undefined)
+                    continue;
+                this.set(key, value);
+            }
+        }
+        return this;
+    }
+    urlParams(params) {
+        for (const [key, value] of new URLSearchParams(params).entries()) {
+            this.set(key, value);
+        }
+        return this;
+    }
+    set(key, value, scope) {
+        if (!key || value === undefined || key.startsWith("~"))
+            return this;
+        key = scope ? `${key}[${scope}]` : key;
+        this.query[key] = value;
+        return this;
+    }
+    setNumber(key, value, scope) {
+        if (value === undefined)
+            return this;
+        if (typeof value !== "number") {
+            console.warn(`[Opfelmusig/RequestQuery] '${key}' is not a number. skipping.`);
+            return this;
+        }
+        this.set(key, String(value), scope);
+        return this;
+    }
+    setStringArray(key, values, scope) {
+        if (values === undefined)
+            return this;
+        values = !Array.isArray(values) ? [values] : values;
+        values = values.filter((x) => x !== undefined && !String(x).startsWith("~"));
+        if (values.length <= 0)
+            return this;
+        this.set(key, values.join(","), scope);
+        return this;
+    }
+    setString(key, value, scope) {
+        if (value === undefined)
+            return this;
+        if (typeof value !== "string") {
+            console.warn(`[Opfelmusig/RequestQuery] '${key}' is not a string. skipping.`);
+            return this;
+        }
+        this.set(key, value, scope);
+        return this;
+    }
+    prepare() {
+        return this.query;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { OpfelMusigClient } from "./core/client.js";
+export { AppleMusicError, type AppleMusicErrorDetail, type AppleMusicErrorKind, type AppleMusicErrorOptions, } from "./core/error.js";
+export { defineScopes } from "./helpers/public.js";
+export type { HttpEvent, LanguageConfig, OpfelMusigConfig, RequestConfig, TokenProvider, } from "./types/config.js";
+export type { ResourceOf, ResourceTemplate, ResourceTemplateOf, ValidateResourceName, } from "./types/query/helpers.js";
+export type { ScopedResourceOf } from "./types/query/scopes.js";
+export { appleMusicApiUrl } from "./core/http.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { OpfelMusigClient } from "./core/client.js";
+export { AppleMusicError, } from "./core/error.js";
+export { defineScopes } from "./helpers/public.js";
+export { appleMusicApiUrl } from "./core/http.js";

package/dist/schemas/error.d.ts

@@ -0,0 +1,29 @@
+import z from "zod";
+export declare const AppleMusicErrorSourceSchema: z.ZodObject<{
+    parameter: z.ZodOptional<z.ZodString>;
+    pointer: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const AppleMusicErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    source: z.ZodOptional<z.ZodObject<{
+        parameter: z.ZodOptional<z.ZodString>;
+        pointer: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    status: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>;
+export declare const AppleMusicErrorResponseSchema: z.ZodObject<{
+    errors: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        source: z.ZodOptional<z.ZodObject<{
+            parameter: z.ZodOptional<z.ZodString>;
+            pointer: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        status: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/schemas/error.js

@@ -0,0 +1,16 @@
+import z from "zod";
+export const AppleMusicErrorSourceSchema = z.object({
+    parameter: z.string().optional(),
+    pointer: z.string().optional(),
+});
+export const AppleMusicErrorSchema = z.object({
+    code: z.string(),
+    detail: z.string().optional(),
+    id: z.string(),
+    source: AppleMusicErrorSourceSchema.optional(),
+    status: z.string(),
+    title: z.string(),
+});
+export const AppleMusicErrorResponseSchema = z.object({
+    errors: z.array(AppleMusicErrorSchema),
+});