DEV Community: Juro Oravec

One AI config to rule all repos

Juro Oravec — Sun, 22 Feb 2026 19:55:41 +0000

How I stopped duplicating agents, skills, and rules across every repo - and why you might want to do the same.

If you use an AI coding assistant — Cursor, Claude Code, Codeium, Windsurf, or similar - and maintain more than one project, you've probably felt the pain:

You craft a solid set of rules, prompts, and agent definitions in one repo, and then you copy them into the next. And the next. Before long, you're maintaining five versions of the same config, and improvements in one place never make it to the others.

There's a better way.

The idea: one root, many projects

Instead of scattering your AI config across each repo, put it in a single root repository and import your projects as git submodules. Open that root in your editor, and every project inside it shares the same rules and definitions. Update once, apply everywhere.

The setup I use is for Cursor (.cursor/ with agents, skills, rules). The same pattern works for other tools — just swap in their config layout.

agents/                    ← you open this
├── .cursor/               ← ONE definition of agents, skills, rules
│   ├── agents/
│   ├── rules/
│   └── skills/
├── my-api/                ← your projects (git submodules)
├── my-dashboard/
├── my-scraper/
└── ...

All submodules are indexed together. The AI has full context. No duplication, no drift.

Why submodules (and not symlinks)?

You might think: "Can't I just symlink my projects into a mega folder?" You can, but many AI tools don't index symlinks — Cursor, for example, skips them, so the AI can't see the files. Git submodules are real directories; they get indexed and everything works.

Each project keeps its own git history. The root repo just holds pointers to specific commits. Clean, standard, and it plays nicely with git clone --recurse-submodules.

Getting started

1. Clone the repo

git clone --recurse-submodules https://github.com/JuroOravec/agents.git
cd agents

2. Add your projects

git submodule add https://github.com/you/your-project.git your-project
git add .gitmodules your-project
git commit -m "Add your-project as submodule"

Open the repo in Cursor. Your projects are now inside, sharing the same .cursor/ config. Edit a skill once, and it applies to every project.

3. Switching focus when you have too many projects

Indexing and tooling can slow down with dozens of submodules. You have two ways to change which projects are "active":

Soft switch — Toggle .gitignore so tooling skips projects you're not using. Add a path to deactivate, remove it to activate, reload the window. Your WIP stays local; no push, no commit. Use this when you just want to focus on 1–2 projects for a while.

# Soft-switch: project-a disabled, project-b active
project-a/
# project-b/

Hard switch — Remove one submodule and add another. Commit & push to save progress before removing, so you don't lose work. Use this when you want to permanently drop a project from the root and bring in a different one.

4. Or let the AI do it

I added a root-gitmodule-setup skill that makes this trivial: ask your AI to "add a project", "remove a project", or "switch projects", and it walks you through the right steps — including asking whether you want soft or hard switch when it's unclear.

See the full project setup guide for more.

What's in the box

The agents repo contains AI agents, skills, and rules I use across projects — development, scraping, packaging, releases, and more. They live in .cursor/skills/. You can keep them, replace them, or fork the whole thing and make it yours.

The root package.json (with @types/node) is there so Node built-in imports like node:path resolve correctly in TypeScript when editing files across submodules. No root tsconfig needed.

Try it

Clone, add your first project, and open it in Cursor. One config. Many projects. No more copy-paste.

Repo: https://github.com/JuroOravec/agents

django-components v0.94 - Templating is now on par with Vue or React

Juro Oravec — Wed, 25 Sep 2024 14:29:36 +0000

Hey, I'm Juro, I'm one of the maintainers of django-components. In releases v0.90-0.94 we've added features that make using components in templates much more flexible, similar to JSX / Vue.

(This info is already a bit dated (released a month ago; latest is v0.101), as I'm busy adding support for JS / CSS variables, TypeScript & Sass, and HTML fragment. Exciting stuff! But I realized haven't shared this update yet!)

Anyway, The following is a component blog_post, that accepts a title, id, and additional kwargs applied from blog_post_props:

    {% blog_post
      title="{{ person.first_name }} {{ person.last_name }}"
      id="{% random_int 10 20 %}"
      ...blog_post_props
    / %}

The above is a combination of multiple features:

1. Self-closing tags:

Instead of

    {% component "my_component" %}
    {% endcomponent %}

You can now simply write

    {% component "my_component" / %}

2. Multi-line tags:

django_components now automatically configures Django to allow multi-line tags. So instead of cramming everything on a single line:

    {% component "blog_post" title="abcdef..." author="John Wick" date_published="2024-08-28" %}
    {% endcomponent %}

You can spread it across multiple lines:

    {% component "blog_post"
      title="abcdef..."
      author="John Wick"
      date_published="2024-08-28"
    / %}

3. Spread operator:

Similarly to ...props operator in JSX or v-bind in Vue, this inserts props / kwargs into a given position.

So instead of

    {% component "blog_post"
      title="abcdef..."
      author="John Wick"
      date_published="2024-08-28"
    / %}

You can have the kwargs in a dictionary, and then apply that:

    # Python
    props = {
        "title": "abcdef...",
        "author": "John Wick",
        "date_published": "2024-08-28"
    }

    {# Django #}
    {% component "blog_post" ...props %}

4. Template tags inside string literals in component inputs:

You can now use template tags and flters inside component inputs:

    {% component 'blog_post'
      "As positional arg {# yay #}"
      title="{{ person.first_name }} {{ person.last_name }}"
      id="{% random_int 10 20 %}"
      readonly="{{ editable|not }}"
    / %}

This way you don't have to define extra variables every time you need to format a value.

Note that when there is only a single tag and no extra text around it, then the result is passed as a value. So "{% random_int 10 20 %}" passes in a number, and "{{ editable|not }}" passes a boolean.

You can even go a step further and have a similar experience to Vue or React, where you can evaluate arbitrary code expressions, AKA similar to this:

    <MyForm
      value={ isEnabled ? inputValue : null }
    />

This can be possible with django-expr, which adds an expr tag and filter that you can use to evaluate Python expressions from within the template:

    {% component "my_form"
      value="{% expr 'input_value if is_enabled else None' %}"
    / %}

5. Support for {% comp_name %} {% endcomp_name %} and TagFormatter

By default, the components are written using the component tag, followed by the name of the component:

    {% component "button" href="..." disabled %}
        Click me!
    {% endcomponent %}

You can now change this (and even make your own!).

For example, setting COMPONENTS.tag_formatter to "django_components.shorthand_component_formatter" allows you to write components like so:

    {% button href="..." disabled %}
        Click me!
    {% endbutton %}

Lots more is to come, so be sure to give django-components a try!

Portadom: A Unified Interface for DOM Manipulation

Juro Oravec — Wed, 30 Aug 2023 16:29:52 +0000

Introduction

Web scraping, while immensely useful, often requires developers to navigate a sea of tools and libraries, each with its own quirks and intricacies. Whether it's JSDOM, Cheerio, Playwright, or even just plain old vanilla JS in the DevTools console, moving between these platforms can be a challenge.

Enter Portadom, your new best friend in the world of web scraping.

What is Portadom?
Portadom provides a consistent DOM manipulation interface across:

Browser API
JSDOM
Cheerio
Playwright

This means you no longer have to rewrite or refactor large chunks of your code when switching between these tools. Instead, you can focus on the logic of your web scraping tasks and let Portadom handle the DOM manipulation intricacies.

The Portadom Workflow

Imagine you're working on a project to scrape data from several websites. You initially start by prototyping in the DevTools console using vanilla JS. Once you've figured out the transformations and data extractions, you realize that some sites can be scraped with static HTML, while others need a JS runtime.

1. Prototyping with Vanilla JS

You start with a simple site and define your transformations directly in the DevTools:

let title = document.querySelector('h1').innerText;

2. Static HTML with JSDOM or Cheerio

For sites where static HTML is sufficient, you can easily migrate your vanilla JS logic:

import { load as loadCheerio } from 'cheerio';
import { cheerioPortadom } from 'portadom';

const html = `<h1>Welcome to Portadom</h1>`;
const $ = loadCheerio(html);
const dom = cheerioPortadom($.root(), null);

const title = await dom.findOne('h1').text();

With Portadom, the transition feels almost seamless. The core logic remains consistent, and only the setup changes.

3. Dynamic Sites with Playwright

For websites that rely heavily on JavaScript, you'd need a tool like Playwright. But with Portadom, even this transition is smooth:

import { playwrightLocatorPortadom } from 'portadom';

const page = await browser.newPage();
await page.goto('https://example.com');

const bodyLoc = page.locator('body');
const dom = playwrightLocatorPortadom(bodyLoc, page);

const title = await dom.findOne('h1').text();

Notice how, once again, only the setup changed. The actual DOM querying logic remains consistent, thanks to Portadom.

Embracing Flexibility

Portadom is all about flexibility. No matter where you start — be it with Cheerio for static HTML parsing or Playwright for dynamic sites — you're never locked in. If your needs change, Portadom makes it easy to switch your underlying platform without overhauling your entire scraping logic.

Take the Leap with Portadom

Web scraping is finicky - everything breaks all the time. With Portadom, you're equipped with a tool that lets you focus on crafting the perfect data extraction strategy without getting bogged down by the intricacies of various DOM manipulation libraries. Dive in and let Portadom streamline your web scraping journey!

Portadom was already successfully used in scraping:

Portadom currently supports following manipulations:

Element attributes, properties, text
findOne - equivalent to document.querySelector
findMany - equivalent to document.querySelectorAll
closest - equivalent to Element.closest
parent - equivalent to Element.parent
children - equivalent to Element.children
root - Get document root
remove - Remove current Element
getCommonAncestor - Get common ancestor between this and other Element
getCommonAncestorFromSelector - Get common ancestor between this and other Element (found by selector)

Chaining

For cross-compatibility, each method on a Portadom instance returns
a Promise.

But this then leads to then / await hell when you need to call multiple methods in a row:

const employerName = (await (await el.findOne('.employer'))?.text()) ?? null;

To get around that, the results are wrapped in chainable instance. This applies to each method that returns a Portadom instance, or an array of Portadom instances.

So instead, we can call:

const employerName = await el.findOne('.employer').text();

You don't have to chain the commands. Instead, you can access the associated promise under promise property. For example this:

const mapPromises = await dom.findOne('ul')
  .parent()
  .findMany('li[data-id]')
  .map((li) => li.attr('data-id'));
const attrs = await Promise.all(mapResult);

Is the same as:

const ul = await dom.findOne('ul').promise;
const parent = await ul?.parent().promise;
const idEls = await parent?.findMany('li[data-id]').promise;
const mapPromises = idEls?.map((li) => li.attr('data-id')) ?? [];
const attrs = await Promise.all(mapPromises);

Examples

Example - Profesia.sk

See source code here.

// Following lines added for completeness 
const $ = loadCheerio(html);
const dom = cheerioPortadom($.root(), url);
// ...
const rootEl = dom.root();
const url = await dom.url();

// Find and extract data
const entries = await rootEl.findMany('.list-row:not(.native-agent):not(.reach-list)')
  .mapAsyncSerial(async (el) => {
  const employerName = await el.findOne('.employer').text();
  const employerUrl = await el.findOne('.offer-company-logo-link').href();
  const employerLogoUrl = await el.findOne('.offer-company-logo-link img').src();

  const offerUrlEl = el.findOne('h2 a');
  const offerUrl = await offerUrlEl.href();
  const offerName = await offerUrlEl.text();
  const offerId = offerUrl?.match(/O\d{2,}/)?.[0] ?? null;

  const location = await el.findOne('.job-location').text();

  const salaryText = await el.findOne('.label-group > a[data-dimension7="Salary label"]').text();

  const labels = await el.findMany('.label-group > a:not([data-dimension7="Salary label"])')
    .mapAsyncSerial((el) => el.text())
    .then((arr) => arr.filter(Boolean) as string[]);

  const footerInfoEl = el.findOne('.list-footer .info');
  const lastChangeRelativeTimeEl = footerInfoEl.findOne('strong');
  const lastChangeRelativeTime = await lastChangeRelativeTimeEl.text();
  // Remove the element so it's easier to get the text content
  await lastChangeRelativeTimeEl.remove();
  const lastChangeTypeText = await footerInfoEl.textAsLower();
  const lastChangeType = lastChangeTypeText === 'pridané' ? 'added' : 'modified';

  return {
    listingUrl: url,
    employerName,
    employerUrl,
    employerLogoUrl,
    offerName,
    offerUrl,
    offerId,
    location,
    labels,
    lastChangeRelativeTime,
    lastChangeType,
  };
});

Example - SKCRIS

See source code here.

// Following lines added for completeness. Edited for brevity.
const $ = loadCheerio(html);
const dom = cheerioPortadom($.root(), url);
// ...
const url = await dom.url();
const rootEl = dom.root();
const tableDataEls = await rootEl
  .findMany('.detail > tr')
  .filterAsyncSerial((el) => el.text()) // Remove empty tags
  .slice(1, -1).promise; // Remove first row (heading) and last row (related resources)

const tableData = tableDataEls.reduce(async (promiseAgg, rowEl) => {
  const agg = await promiseAgg;
  const [title, val] = await rowEl.children()
    .mapAsyncSerial(async (el) => {
      const text = await el.text();
      return text?.replace(/\s+/g, ' ') ?? null;
    });
  if (!title) return agg;

  agg[title] = val ?? null;
  return agg;
}, Promise.resolve({} as Record<string, string | null>));

return tableData;

Example - Facebook post timestamp

Facebook prompted the need to add the getCommonAncestor method, as Facebook's HTML doesn't provide many reliable patterns to work with.

Note how we used getCommonAncestor to get an element that wasn't easily targettable by class/attribute selectors.

// Following lines added for completeness. Edited for brevity.
const body = await page.evaluateHandle(() => document.body)
const dom = playwrightHandlePortadom(body, page);
// ...
// Find container with post stats
const likesEl = await dom.findOne('[aria-label*="Like:"]').promise;
const commentsEl = await dom
  .findMany('[role="button"] [dir="auto"]')
  .findAsyncSerial(async (el) => {
    const text = await el.text();
    return text?.match(URL_REGEX.COMMENT_COUNT);
  }).promise;

const statsContainerEl =
  likesEl?.node && commentsEl?.node
    ? await likesEl.getCommonAncestor(commentsEl.node).promise
    : null;
// "6.9K views"
const viewsText = await statsContainerEl
  ?.children()
  .findAsyncSerial(async (domEl) => {
    const text = await domEl.text();
    return text?.match(/views/i);
  })
  .textAsLower();

Learn more

Filter groups: The best practice of filtering just about anything

Juro Oravec — Mon, 07 Mar 2022 10:19:44 +0000

(Originally published on jurora.vc)

Jean was searching for a new place. He's a frequent mover, this was the 2nd time in last half a year. He's moved places 5 times in the last 3 years.

Jean already had a good sense of what it entails — he looks up several property marketplace websites, he compares which ones are more popular, and which ones favour ads from landlords vs letting agents. He choses one or two, to avoid overburderning himself.

He knows that the photos and description rarely paint the full picture. The descriptions are overflowing with only the best superfluous adjectives. The photos have impossible angles like it's early 2000's. But you can barely anyway, because they're overexposed so much you can't tell where a wall starts and where the furniture ends. "It's kind of like advertising. Over time, you become desensitised. You stop noticing those things and focus just on the factual points", said Jean.

What are these points? Location for one, and price for sure.
Are there glazed windows? Yes / No.
Does it have a washing machines? Yes / No.
Is it on a busy street? Yes / No.

And just like that, Jean can turn the ad — laden with emotional traps — into something that's easier for him to digest: a dataset.

Jean has interesting likings. He's a frugal chap, but he likes to have plenty of space in his rented kingdom. And so when he considers the data, right next to columns "monthly cost" and "travel time", you would find the average price per square meter, the cost of travel, and more. Not all property listings include details like that, and Jean is already used to the fact. It's even more rare so to enable to sort or filter the ads based on these conditions.

Jean was living by himself, but he's "not an old snarly hermit... just yet!", he said laughing, as he explained that he was considering two options. He could either look for something smaller, like a 50-60 m2 single bedroom flat for 400-600 EUR. Or he could move in with 1-2 other people, together living in a 100+ m2 two or three bedroom flat for 1000-1500 EUR. "I'm not hard-pressed either way", he added.

The websites Jean used for search are like any other.
And so Jean had to search for the 50-60 m2 single bedroom flats for 400-600 EUR.
And then he had to search for the 90-100 m2 two bedroom flats for 800-1200.
And then he had to search for the 140-150 m2 three bedroom flats for 1200-1500.
And then... kidding, he stopped there he claimed.

"You would've thought this is something so common that they [the property websites] would make it easier to search for these kind of things in one go", he starts. "When you have to search one-by-one, there's no easy way to compare the flats between the searches. Which flat is more cost effective, the larger one in the city centre, or a smaller one bit further out? In the end, I scraped the data from the website, just so I could put it into a spreadsheet. I've put it into a spreadsheet, did the math there, and finally I could decide which properties to prioritise."

"That's... quite a lot just to find a new place, isn't it?" I asked. "Yes, it's ridiculous" replied Jean.

Jean's a... what?

Except... there's no Jean. I'm the Jean and Jean is I. Jean is a figment to drive home the message of how tools with limited capabilities that don't sufficiently reflect our needs force us to take lengthy workarounds.

In reality, I'm actually looking for a place in Bratislava. Although, unlike Jean, I do feel like an old snarly hermit, sometimes. And I do have scraped a website just to put the data in a spreadsheet just to find the best options out there.

Sidenote: That's what I like about smaller cities. I'd need a group of 5 for a week to do the same thorough analysis for flats in London. But for Bratislava (with population of 0.5 M), I could do it in one afternoon.

The points stands though. The search would have been so much easier if I didn't have to do this extra legwork on my end, in spreadsheets, and instead just leverage the system that already exists to do what's basically just a more advanced search query.

Here comes the boy filter groups

This is where the concept of filter groups come in. And by filter groups, I mean the ability in the user interface (UI) to group filter conditions, and in turn apply all these groups together. So I can apply conditions like price ranges across distinct ranges (400-600 OR 800-1200 EUR), and the results I get back have considered them all.

Just see how Notion did it. You wrap the conditions in a group, then you add a new group, and then set their boolean operator.

Sweet. Simple. Sexy.

It's a piece of cake

Close your eyes and imagine how your data would look like on a 2D or 2D graph. Whatever data you work with — whether it's property listings or something else — practically it's just datapoints scatttered in a multidimensional space. Price is one dimension, size is another, and so are booleans like "has double glazing", etc. Actually, don't close your eyes, here's an example:

And search filters? Well, filtering is like cutting out slices out of this multi-dimensional cake. You can cut the cake up in different ways to get different slices, like so:

Without the filter groups, you can only create the slices one by one. You either look at one bedroom flats for 400-600, OR you look at two bedroom flats for 1200-1500 EUR, but not both.

But with filter groups, you can effectively pool the data from multiple slices. I can look at the flats for 400-600 AND the flats for 1200-1500! It's like cutting up the cake and taking two (or three or four) slices that are not touching their sides! So I hope you've washed your hands...

Note: When you think about it, NOT supporting multiple filter groups is effectively just the case of supporting only 1 filter group at all times. 🤔

Slaps cake This cake can be cut up in so man- ...oh

Clearly, it's good to support filter groups. It'll make your users happy. It'll give them capabilities that probably even you didn't think of. So, how would you go about implementing something like that?

Note: This is not a new concept, and so I'm sure there are more great resources on implementing the filter groups.

Let's start with the user's perspective.

User interface

For UI, it's fairly obvious. You'd want to give user a way to compartmentalise (wrap up and isolate) the filter conditions.

Example 1:

You could wrap the filters in tabs. User could add or remove a tab, which would represent adding or removing a filter group. The old filter settings would live in the tab's content, and the filter settings between each tab would be independent from others.

Example 2:

Or you can define the filter groups as a building blocks, akin to how Notion does it (see above).

Either way, everything that's inside the group is applied together (logical AND). And the groups themselves are chained among each other either with logical OR (pool results together), or AND (select overlap).

Behind the scenes

The change in the UI does make it a difference for the system the handles the user input.

Example 1

If you consider simplest implementation, you're probably thinking of filter conditions being held in an object of filter:value pairs.

Well, if we're going to support multiple groups, we naturally have to extend this to an array of objects.



// Before - single filter group
const filters = {
  rangeMin: 400,
  rangeMax: 600,
};

// After - many filter groups
const filters = [
  {
    rangeMin: 400,
    rangeMax: 600,
  },
  {
    rangeMin: 1200,
    rangeMax: 1500,
  },
];

Example 2

Alternatively, your system may represent filters as an array of { key: String, value: Any } entries.

Here we could simply add a third field to the entries, group, to distinguish between groups:



// Before - single filter group
const filters = [
  { key: 'rangeMin', value: 400 },
  { key: 'rangeMax', value: 600 },
];

// After - many filter groups
const filters = [
  { key: 'rangeMin', value: 400, group: 0 },
  { key: 'rangeMax', value: 600, group: 0 },
  { key: 'rangeMin', value: 800, group: 1 },
  { key: 'rangeMax', value: 1200, group: 1 },
];

Sending the filter groups to the server

You're most likely to come across filters on e-commerce or ads sites, just like I did. In these cases, there's several ways how the filter state is sent to the server.

Example 1: Filter as query parameters - each filter field is separate query param

Query parameters, are, quite literally, made for this, so it makes sense to use them.

The website may encode the filter as top top-level query params. This works for a single filter, but it's problematic for multiple filters.



?rangeMin=400&rangeMax=500

If your server supports array indices in query params, you could modify the above to the following:



?filters[0].rangeMin=400&filters[0].rangeMax=600

And multiple filters would thus be



?filters[0].rangeMin=400&filters[0].rangeMax=600&filters[1].rangeMin=800&filters[1].rangeMax=1200

Example 2: Filter as query parameters - filters encoded as JSON

I've also seen the following format used, where the filter state is effectively set as a JSON:



?filters={rangeMin:400,rangeMax:600}

This one would be a tad easier to modify, as we just wrap the object in an array:



?filters=[{rangeMin:400,rangeMax:600},{rangeMin:800,rangeMax:1200}]

Example 3: Filter state as post body, GraphQL query, or other

In most other situations, you'll probably do the same thing as we did above with encoding the filters as a JSON.

Querying the database

At the other end of the server, the request will be likely directed at some database.

When we are querying the database for a single filter group, we're sending a single request. But for the filter groups, we have two ways to approach it:

Example 1 - Query database for each of the filter group

Just as it says, we would query the database for each filter group and join the results at the end. Be mindful of deduplication in this case!

This makes it easier for you if you're working with any kind of ORM or other frameworks that talk to the database for you.

Example 2 - Construct single query from multiple groups

It might be a lot more complex to do this, but it's not impossible. If you can construct a single query, you'll get your results in a single request, and deduplication will be (most likely) handled for you!

Conclusion

And there you have it buddy, congratulations! You now know why filter groups are a good idea, and you know how to implement them. Filter groups are a feature that can really simplify tasks of your more demanding users. So go get 'em! ...and make my life easier please!

Reverse engineering Apple's MusicKitJS to create Apple Music Strategy for PassportJS

Juro Oravec — Sun, 21 Mar 2021 17:43:40 +0000

If you're wondering what's the gif in the title, that's a demo of authentication flow for Apple Music that I've tested in of the apps I've made, MoovinGroovin.

This post describes my journey of isolating the authentication from MusicKitJS, and packaging it into a passportJS strategy.

And in case the cover is cropped, this is it:

TL;DR

The package is available as passport-apple-music NPM package.

Background

Over the past few months, I've made MoovinGroovin, a web service that creates playlists from the songs you listened when working out with Strava turned on.

MoovinGroovin is integrated with Spotify, and I got a request from a user to add support for Apple Music.

Apple Music has a rest API (Apple Music API). The API has an endpoint to get recently-played resources which is what the app needed. But to access those on a per-user basis, you need a music user token. And these user tokens are made available only when the user logins in to Apple using MusicKitJS, and authenticates the app for Apple Music.

The MoovinGroovin app handled all other 3rd party integrations on the backend using passportJS.

But, there was no passport strategy for Apple Music. And handling Apple Music on the frontend as an exception felt like a bad design choice.

And so my goal was to extract the MusicKitJS auth flow and package it into a passport strategy.

Analysing MusicKitJS to understand auth flow

Note: To keep this article on the topic, I've written the tips for reverse-engineering minified JS code in a separate post:

7 Tips for reverse engineering minified TypeScript/JavaScript

Juro Oravec ・ Mar 20 '21

#typescript #devjournal #javascript #tutorial

When you trigger authentication using MusicKitJS, it opens a separate window with login page. This seems like a standard OAuth flow. Based on OAuth, I was expecting that I could ditch MusicKitJS by:

Generating the auth URL ourselves.
Passing in the callback URL (redirect URI) query param to the auth URL, which would point back to our server.
After user authenticates (or fails to do so) on the Apple login page, a request would be sent to the callback URL with either a code or error query param. code in this case, would've been the music user token we need.

Or so I thought..

Generating auth URL

And so I searched and found how MusicKitJS generates the auth URL. And I found that the query params of the auth URL contain the encoded info of your developer token, name and icon, as well as some analytics data.

You can see the query params in the comments in the screenshots below:

As you can see, there's no magic to the auth URL. And, if you have the developer token, you can construct it yourself too.

Great! 🦜 So now I could just use that URL and call it a day...

Controlling the auth flow

Except...

Except when I tried to open the URL, I got an error message and an error in the console. 😭

Quick debug revealed that the "invalid URL" was because the login page tries to do:

new URL(document.referrer);

As can be seen in the last line here:

And if I open the page directly, well, there's no referrer! 🤦 🤦

Cool, no problem, I thought. But in fact it was a problem.

First I tried to solve this by using an iframe and opening the auth URL inside the iframe. However, I was still getting empty referrer.

So I had to stick with opening the auth URL in a separate window.

OK. Fine. But then it should work, right?

...I guess you already know the answer. 😏

This time, the auth URL loaded, I could enter my credentials, verify with 2FA, and confirm. But, then the page froze in a loading state.

So I did it again, and it froze again. I've checked if I got any response, and I did not.

So I tried again. Still nothing. 😞

Once again diving deep into debugging the JS of the login page, it turned out that the login page sends messages using postMessage. And when it posts a message, it's waiting for a response with addEventListener. And if there's no response coming, it is stuck in the loading state.

Since I launched the window with the auth URL without handling any messages, it got stuck.

And the referrer is expected to respond to the sent messages. If this is not upheld, the JS on the auth URL hangs in a waiting state, and the user token is never received.

With an event-based communication like this, there could have been a lot going on that I could miss if I tried to handle it instead of MusicKitJS.

That meant that I really did not want to - I could not - bypass MusicKitJS. I had to use it to handle the communication with the login page, so that I could then get the user token from MusicKitJS.

This meant that since we cannot bypass MusicKitJS, we have to work with the auth URL it generates. So we cannot pass the callback URL, or other additional query params to the auth URL. 😟

To stick with the standard and to support passportJS features, I decided that, in the end, when we trigger the authentication for Apple Music, we need 2 windows:

The first is the one we control, which triggers the authorize method on MusicKitJS, waits for login, and processes the response (user token) once authenticated. We can pass the callback URL to this window, and we know it will call it with either the user token or error.

The second is the window opened by MusicKitJS that hosts the auth URL and that is out of our reach.

Passing options to auth flow

So at this point we've established how to trigger the Apple Music login page and get the user token back. Now, to make this into a useful packaged passportJS strategy, we still need to enable to pass options through.

As seen earlier, we know that you can pass app name and icon to the auth window. For these, the process was fairly simple, since these can be passed to MusicKitJS during initialization.

However, the question remained how to pass the parameters to the URL that we control.

One option was to require the user to add a server router endpoint. Upside of this is that we could pass all options as query params. BUT, then it would be user's responsibility to ensure that the right route is triggered. This is not the standard for passportJS strategies, where this should be abstracted away.

Other option was to respond directly with the HTML that will contain our logic to initialize MusicKitJS, call authorize, capture user token, and then redirect to the callback URL with the user token.

Since passportJS can be used with multiple frameworks, I didn't want to bake any templating engine into the package. Instead, the HTML string is constructed on the fly with vanilla string.replace to inject the user's options into the HTML. Not the cleanest solution, but hey, it works! 🤷

...But as always, there's a catch 🤔

Spotify strategy has a showDialog option that enable to force to show the login dialog. In my app, I was using that option show the dialog when users want to change the associated account.

But once I was logged in into Apple Music, I was never prompted for login again.

Crawling through the MusicKitJS code again, I saw that authorize checks if user token already exists, so it has to be stored somewhere.

And indeed, when I looked through the localStorage, there was an entry that started with music. and ended with .u. When the entry was there, the authorization was not trigger. when it was removed, I got asked to re-authorize on calling authorize.

Since we decided not to mess with/replace MusicKitJS, if we want to force the auth window to open, we need to make sure localStorage is free of Apple Music user tokens before we call authorize.

So in the HTML that controls MusicKitJS, we also clean the relevant localStorage keys in prompted to:

Conclusion

Not gonna lie, this was quite a journey. And not gonna lie, the Apple Music auth flow could've been design better, without the tight coupling to a parent window, and without the tight coupling to MusicKitJS.

Better design would lower the barrier for developers, and hence increase uptake - the number of developers trying out and authenticating with Apple Music. That would increase the number of apps or services that use the Apple Music API, which would improve Apple's positioning.

But luckily, now, the barrier has been lowered, and you can simply authenticate users against Apple Music. All you have to do is use passport-apple-music! 🎉

7 Tips for reverse engineering minified TypeScript/JavaScript

Juro Oravec — Sat, 20 Mar 2021 16:36:14 +0000

Recently I found myself deep inside the Apple's MusicKitJS production code to isolate user authentication flow for Apple Music.

Background

Over the past few months, I've made MoovinGroovin, a web service that creates playlists from the songs you listened when working out with Strava turned on.

MoovinGroovin is integrated with Spotify, and I got a request from a user to add support for Apple Music.

As I looked into the integration with Apple Music, I found that to access user's listening history, I needed a "Music User Token". This is an authentication token generated from an OAuth flow. Unfortunately, the only public way to generate these is through authenticate() method of Apple's MusicKitJS SDK.

This meant I would have to handle authentication with Apple Music on frontend, while all other integrations were handled by backend using passportJS.

And so, I decided to extract the auth flow out of MusicKitJS, and wrap it into a separate passportJS strategy (apple-music-passport).

This is where the journey begins...

TL;DR:

Use beautifiers to clean up minified code.
Understand how minifiers compress the execution (control) flow into &&, ||, ,, ;, and (x = y)
Recognize async constructs
Recognize class constructs
Use VSCode's rename symbol to rename variables without affecting other variables with the same name.
Use property names or class methods to understand the context.
Use VSCode's type inference to understand the context.

1. Use beautifiers to clean up minified code.

There's plenty of these tools, just google for a beautifier / prettifier / deminifier / unminifier and you will find them. Beautify and Prettier VSCode extensions work just as well.

Most of these are not very powerful. They will add whitespace, but that's it. You will still need to deal with statements chained with ,, compressed control flow by && or ||, ugly classes and asyncs, and cryptic variable names. But you will quickly learn that - unless you're dealing with event-driven flow - you can just stick with where the debugger takes you and ignore most of the cryptic code.

There was one tool (can't find it) which attempted assigning human-readable names to the minified variables. At first this seemed cool, the truth is this will easily mislead you if the random names make somewhat sense. Instead, rolling with the minified variable names and renaming what YOU understand is the way to go.

2. Understand how minifiers compress the execution (control) flow into `&&`, `||`, `,`, `;`, and `(x = y)`

As said above, you will still need to deal with cryptic statements like this:



void 0 === r && (r = ""), void 0 === i && (i = 14), void 0 === n && (n = window);

Let's break it down:

`void 0` as `undefined`



void 0 === r

void 0 is undefined. So this checks if undefined === r. Simple as that.

Inlined assignment `(x = y)`



(r = "")

This assigns the value ("") to the variable (r) and returns the assigned value. Be conscious of this especially when you find it inside a boolean evaluation (&& or ||).

Consider example below, only the second line will be printed:



(r = "") && console.log('will not print');
(r = "abc") && console.log('will print');

Logically, this will be evaluated as:



"" && console.log('will not print');
"abc" && console.log('will print');

Which is:



false && console.log('will not print');
true && console.log('will print');

So while the second line will print, the first one will not.

Conditional execution with `&&` and `||`

The code above used && to execute the console.log.

Remember that JS supports short-circuit_evaluation. This means that right hand side of



abc && console.log('will print');

will ever be executed if and only if abc is truthy.

In other words, if we have



false && console.log('will not print');
true && console.log('will print');

Then console.log('will not print'); will never be reached.

And same, but opposite, applies to ||:



false || console.log('will print');
true || console.log('will not print');

What does this mean for us when reverse-engineering minified JS code? Often, you can substitute



abc && console.log('hello');

with more-readable



if (abc) {
  console.log('hello');
}

One more thing here - be aware of the operator precedence.

Comma operator

So far, we understand that



void 0 === r && (r = "")

Really means



if (undefined === r) {
  r = "";
}

We see, though, that in the original code, it's actually followed by a comma:



void 0 === r && (r = ""), void 0 === i && (i = 14), void 0 === n && (n = window);

This is the comma operator.

For our reverse-engineering purposes, it just means that each statement (separated by comma) will be evaluated and the value of last statement will be returned.

In other words, think of a chain of comma statements as a mini-function. And so, we can think the code above as:



(function() {
  void 0 === r && (r = "");
  void 0 === i && (i = 14);
  return void 0 === n && (n = window);
})();

Overall, we can now read



void 0 === r && (r = ""), void 0 === i && (i = 14), void 0 === n && (n = window);



(function() {
  if (r === undefined) {
    r = "";
  }
  if (i === undefined) {
    i = 14;
  }
  if (n === undefined) {
    n = window;
    return n;
  } else {
    return false;
  }
})();

3. Recognize async constructs

Depending on the kind of code that you reverse-engineer, you may come into contact with async-heavy codebase. MusicKitJS was an example of this, as it handled requests to Apple Music API, so all methods that made requests were async.

You may find the async functions transpiled into an awaiter and generator functions. Example:



API.prototype.recommendations = function (e, t) {
  return __awaiter(this, void 0, void 0, function () {
    var r;
    return __generator(this, function (i) {
      switch (i.label) {
        case 0:
          return [4, this.collection(et.Personalized, "recommendations", e, t)];
        case 1:
          r = i.sent(), this._reindexRelationships(r, "recommendations");
          try {
            return [2, this._store.parse(r)]
          } catch (e) {
            return [2, Promise.reject(MKError.parseError(e))]
          }
      }
    })
  })
}

Sometimes the __awaiter and __generator names might not be there, and you will just see this pattern:



return a(this, void 0, void 0, function () {
  return __generator(this, function (i) {
    switch (i.label) {
      case 0:
        return ...
      case 1:
        return ...
      ...
    }
  })
})

Either way, these are async/await constructs from TypeScript. You can read more about them in this helpful post by Josh Goldberg.

The important part here is that if we have some like this:



return a(this, void 0, void 0, function () {
  return __generator(this, function (i) {
    switch (i.label) {
      case 0:
        /* ABC */
        return [2, /* DEF */]
      case 1:
        /* GHI */ 
        return [3, /* JKL */]
      ...
    }
  })
})

We can read most of the body inside case N as a regular code, and the second value of returned arrays (e.g. /* DEF */) as the awaited code.

In other words, the above would translated to



(async function(){
  /* ABC */;
  await /* DEF */;
  /* GHI */;
  await /* JKL */;
})()

4. Recognize class constructs

Similarly to the previous point, depending on the underlying codebase, you may come across a lot of class definitions.

Consider this example



API = function (e) {
  function API(t, r, i, n, o, a) {
    var s = e.call(this, t, r, n, a) || this;
    return s.storefrontId = je.ID, s.enablePlayEquivalencies = !!globalConfig.features.equivalencies, s.resourceRelatives = {
      artists: {
        albums: {
          include: "tracks"
        },
        playlists: {
          include: "tracks"
        },
        songs: null
      }
    }, s._store = new LocalDataStore, i && (s.storefrontId = i), n && o && (s.userStorefrontId = o), s.library = new Library(t, r, n), s
  }
  return __extends(API, e), Object.defineProperty(API.prototype, "needsEquivalents", {
    get: function () {
      return this.userStorefrontId && this.userStorefrontId !== this.storefrontId
    },
    enumerable: !0,
    configurable: !0
  }), API.prototype.activity = function (e, t) {
    return __awaiter(this, void 0, void 0, function () {
      return __generator(this, function (r) {
        return [2, this.resource(et.Catalog, "activities", e, t)]
      })
    })
  }

Quite packed, isn't it? If you're familiar with the older syntax for class definition, it might not be anything new. Either way, let's break it down:

Constructor as `function(...) {...}`

Constructor is the function that is called to construct the instance object.

You will find these defined as plain functions (but always with function keyword).

In the above, this is the



function API(t, r, i, n, o, a) {
  var s = e.call(this, t, r, n, a) || this;
  return s.storefrontId = je.ID, s.enablePlayEquivalencies = !!globalConfig.features.equivalencies, s.resourceRelatives = {
    artists: {
      albums: {
        include: "tracks"
      },
      playlists: {
        include: "tracks"
      },
      songs: null
    }
  }, s._store = new LocalDataStore, i && (s.storefrontId = i), n && o && (s.userStorefrontId = o), s.library = new Library(t, r, n), s
}

which we can read as



class API {
  constructor(t, r, i, n, o, a) {
    ...
  }
}

Inheritance with `__extends` and `x.call(this, ...) || this;`

Similarly to __awaiter and __generator, also __extends is a TypeScript helper function. And similarly, the variable name __extends might not be retained.

However, when you see that:

1) The constructor definition is nested inside another function with some arg



API = function (e // This is the parent class) {
  function API(t, r, i, n, o, a) {
    ...
  }
  ...
}

2) That that unknown arg is called inside the constructor



API = function (e // This is the parent class) {
  function API(t, r, i, n, o, a) {
    var s = e.call(this, t, r, n, a) || this; // This is same as `super(t, r, n, a)`
    ...
  }
  ...
}

3) That that same unknown arg is also passed to some function along with out class



return __extends(API, e) // This passes the prototype of `e` to `API`

Then you can read that as



class API extends e {
  constructor(t, r, i, n, o, a) {
    super(t, r, n, a);
    ...
  }
}

Class methods and props with `x.prototype.xyz = {...}` or `Object.defineProperty(x.prototype, 'xyz', {...}`

These are self-explanatory, but let's go over them too.

Object.defineProperty can be used to defined a getter or setter methods:



Object.defineProperty(API.prototype, "needsEquivalents", {
    get: function () {
      return this.userStorefrontId && this.userStorefrontId !== this.storefrontId
    },
    enumerable: !0,
    configurable: !0
  })

is a getter method that can be read as



class API {
  get needsEquivalents() {
    return this.userStorefrontId && this.userStorefrontId !== this.storefrontId
  }
}

Similarly, assignments to the prototype can be plain properties or methods. And so



API.prototype.activity = function (e, t) {
    return __awaiter(this, void 0, void 0, function () {
      return __generator(this, function (r) {
        return [2, this.resource(et.Catalog, "activities", e, t)]
      })
    })
  }

is the same as



class API {
  async activity(e, t) {
    return this.resource(et.Catalog, "activities", e, t);
  }
}

Use VSCode's rename symbol to rename variables without affecting other variables with the same name.

When reverse-engineering minified JS code, it crucial you write comments and rename variables to "save" the knowledge you've learnt parsing through the code.

When you read



void 0 === r && (r = "")

and you realize "Aha, r is the username!"

It is very tempting to rename all instances of r to username. However, the variable r may be used also in different functions to mean different things.

Consider this code, where r is used twice to mean two different things



DOMSupport.prototype._mutationDidOccur = function (e) {
  var t = this;
  e.forEach(function (e) {
    if ("attributes" === e.type) {
      // Here, r is a value of some attribute
      var r = t.elements[e.attributeName];
      r && t.attach(e.target, r)
    }
    // Here, r is current index
    for (var i = function (r) {
      var i = e.addedNodes[r];
      if (!i.id && !i.dataset) return "continue";
        i.id && t.elements[i.id] && t.attach(i, t.elements[i.id]), t.identifiers.forEach(function (e) {
          i.getAttribute(e) && t.attach(i, t.elements[e])
        })
     }, n = 0; n < e.addedNodes.length; ++n) i(n);
...

Identifying all rs that mean one thing would be mind-numbing. Luckily, VSCode has a rename symbol feature, which can identify which variables reference the one we care about, and rename only then:

Right click on the variable
Set new name:
After:

6. Use property names or class methods to understand the context.

Let's go back to the previous point where we had



var r = t.elements[e.attributeName];

When you are trying to figure out the code, you can see we have a quick win here. We don't know what r was originally, but we see that it is probably an attribute or an element, based on the properties that were accessed.

If you rename these cryptic variables to human-readable formats as you go along, you will quickly build up an approximate understanding of what's going on.

7. Use VSCode's type inference to understand the context.

Similarly to point 6. we can use VSCode's type inference to help us deciphering the variable names.

This is most applicable in case of classes, which have type of typeof ClassName. This tells us that that variable is the class constructor. It looks something like this:

From the type hint above we know we can rename xyz to DomSupport



DomSupport = function () {
  function DOMSupport(e, t) {
    void 0 === e && (e = void 0), void 0 === t && (t = Si.classes);
    var r = this;
    ...

Conclusion

That's all I had. These should take you long way. Do you know of other tips? Ping me or add them in the comments!

(Failed) trying to get recently played songs from Apple Music API

Juro Oravec — Sun, 14 Mar 2021 17:11:51 +0000

Recently I was on a quest to get recently played songs from Apple Music.

Background

Over the past few months, I've made MoovinGroovin, a web service that creates playlists from the songs you listened when working out with Strava turned on.

MoovinGroovin is integrated with Spotify, and I got a request from a user to add support for Apple Music.

Apple Music has a rest API (Apple Music API). Getting the tokens to access Apple Music API is a whole story on its own deserving a separate post, which you can find here:

Reverse engineering Apple's MusicKitJS to create Apple Music Strategy for PassportJS

Juro Oravec ・ Mar 21 '21 ・ 7 min read

#devjournal #passport #typescript #apple

In this one instead, I focus on what I've learnt about the Apple Music API's endpoint that fetches recently played resources:

https://api.music.apple.com/v1/me/recent/played

TL;DR:

The endpoint returns only playlists, albums, and stations. If you need songs like I did, you're out of luck.
The endpoint remembers only the last 50 recently played resources (same as Spotify). If you need older info, you better start caching darling.
You can get at most 10 items per request. You can specify the limit with limit=n query param.
To get resources beyond the first 10 items, you can use offset=n query param. If there are more data available beyond what you requested, the response also has a "next" key with URL to the next offset (e.g. "/v1/me/recent/played?offset=40").
The endpoint returns the resources in the order that they've been played. However, you don't get the time at which the resource was started. Which is what I needed. And it made me sad.

What I did

Observation 1: If you set `limit` above `10`, you get an error in the payload.

This confirms we have to operate in the range of 1-10 resources per request.

Response for "https://api.music.apple.com/v1/me/recent/played?limit=11"

{
    "errors": [
        {
            "id": "X6VOUROLIVE5XJSVKIA5FFHQEI",
            "title": "Invalid Parameter Value",
            "detail": "Value must be an integer less than or equal to 10",
            "status": "400",
            "code": "40005",
            "source": {
                "parameter": "limit"
            }
        }
    ]
}

Just out of curiosity, limit that's less than 1 (so 0 and including negatives) also throws.

Observation 2: `offset` DOES work for this endpoint

Other endpoints accept offset query param, so I tried I here too. Good news, offset works!

At the time of testing, I had just 4 entries in recently played. That was expected, today was the first time I've used Apple Music.

Response for "https://api.music.apple.com/v1/me/recent/played"

{
    "data": [
        {
            "id": "ra.562939683",
            "type": "stations",
            "href": "/v1/catalog/sk/stations/ra.562939683",
            "attributes": {
                "isLive": false,
                "artwork": {
                    "width": 2400,
                    "height": 2400,
                    "url": "https://is5-ssl.mzstatic.com/image/thumb/Features114/v4/40/0d/22/400d2226-ab71-66f4-92a1-baaa07276664/mzl.wimxogea.png/{w}x{h}AM.RSAB01.jpeg",
                    "bgColor": "f3f3f3",
                    "textColor1": "040404",
                    "textColor2": "282828",
                    "textColor3": "333333",
                    "textColor4": "505050"
                },
                "url": "https://music.apple.com/sk/station/rone-similar-artists/ra.562939683",
                "playParams": {
                    "id": "ra.562939683",
                    "kind": "radioStation",
                    "format": "tracks",
                    "stationHash": "CgkIARoFo463jAIQAQ"
                },
                "name": "Rone & Similar Artists"
            }
        },
        {
            "id": "pl.41fced032b8c4a909de7c696566ed485",
            "type": "playlists",
            "href": "/v1/catalog/sk/playlists/pl.41fced032b8c4a909de7c696566ed485",
            "attributes": {
                "artwork": {
                    "width": 1080,
                    "height": 1080,
                    "url": "https://is1-ssl.mzstatic.com/image/thumb/Features114/v4/87/09/5e/87095e3e-df15-05d8-6baa-4bf32ea6c0e0/source/{w}x{h}SC.DN01.jpeg?l=en-GB",
                    "bgColor": "aadf95",
                    "textColor1": "000000",
                    "textColor2": "0e2149",
                    "textColor3": "1c3656",
                    "textColor4": "264157"
                },
                "isChart": false,
                "url": "https://music.apple.com/sk/playlist/indie-electronic/pl.41fced032b8c4a909de7c696566ed485",
                "lastModifiedDate": "2021-03-12T05:00:46Z",
                "name": "Indie Electronic",
                "playlistType": "editorial",
                "curatorName": "Apple Music Indie",
                "playParams": {
                    "id": "pl.41fced032b8c4a909de7c696566ed485",
                    "kind": "playlist"
                },
                "description": {
                    "standard": "The longer we live and listen in this digital world, the weirder it feels to talk about electronic music. Still, it’s the artists that have embraced the possibilities of electronics on their own terms that have turned out the most reliably interesting music, hybrids that combine classic songwriting and expressivity—be it rock, soul, indie or pop—with sounds and forms that didn’t exist until the programming did. From the downtempo, club-inflected indie pop of artists like The xx to the straight-up cybernetic visions of FKA twigs, here’s a playlist gathering the most exciting indie electronic music of the still-young millennium. Our editors update tracks here regularly, so if you hear something you like, add it to your library.",
                    "short": "All hail the hybrids."
                }
            }
        },
        {
            "id": "1551178998",
            "type": "albums",
            "href": "/v1/catalog/sk/albums/1551178998",
            "attributes": {
                "artwork": {
                    "width": 4000,
                    "height": 4000,
                    "url": "https://is1-ssl.mzstatic.com/image/thumb/Music114/v4/fc/7f/0a/fc7f0a77-66a6-1a3a-018a-315d6f5d3eca/190295042998.jpg/{w}x{h}bb.jpeg",
                    "bgColor": "040404",
                    "textColor1": "fafafa",
                    "textColor2": "e0e2e1",
                    "textColor3": "c9c9c9",
                    "textColor4": "b4b6b5"
                },
                "artistName": "Dua Lipa",
                "isSingle": false,
                "url": "https://music.apple.com/sk/album/future-nostalgia-the-moonlight-edition/1551178998",
                "isComplete": true,
                "genreNames": [
                    "Pop",
                    "Music"
                ],
                "trackCount": 19,
                "isMasteredForItunes": false,
                "releaseDate": "2021-02-11",
                "name": "Future Nostalgia (The Moonlight Edition)",
                "recordLabel": "Warner Records",
                "upc": "190295042998",
                "copyright": "A Warner Records UK Release, ℗ 2021 Dua Lipa Limited under exclusive licence to Warner Music UK Limited. Except tracks 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 18 ℗ 2020, tracks 1 & 2 ℗ 2019 Dua Lipa Limited under exclusive licence to Warner Music UK Limited, track 14  ℗ 2020 RCA Records, a division of Sony Music Entertainment, track 19 ℗ 2020 Sueños Globales, LLC, Exclusively Licensed to UMG Recordings Inc, ℗ Universal Music Latino/NEON16.",
                "playParams": {
                    "id": "1551178998",
                    "kind": "album"
                },
                "editorialNotes": {
                    "standard": "When Dua Lipa released <i>Future Nostalgia</i> in March 2020, she knew she was taking a risk (in a tearful social media video at the time, the British singer wondered whether releasing an album so laced with joy was “the right thing to do” just as a global pandemic hit). Her gamble, of course, paid off. <i>Future Nostalgia</i>—a celebratory odyssey into pop’s future, influenced by the late-night sounds of its past—proved to be just the tonic a world in crisis needed. “When I was creating this record, I wanted it to feel like a form of escapism,” Lipa tells Apple Music. “And it felt like, during this time, it did serve as a form of escapism for me. And I was so happy with the response that the record got, and people [who] were like, ‘This got me through lockdown.’” Almost exactly a year later—and following an exhilarating, star-studded remix album, a Mercury Prize nomination and six Grammy Award nods—comes <i>The Moonlight Edition</i>. Here, you’ll find the original record's 11 uplifting tracks and the stream of hits Lipa served up in its wake (“Fever” with Angèle, a DaBaby-featuring remix of “Levitating” and “Prisoner”, Lipa’s inescapable Miley Cyrus collab) plus previously unreleased tracks, including “We’re Good”, on which Lipa departs from <i>Future Nostalgia</i>’s iridescent, disco-indebted sounds. <i>The Moonlight Edition</i> celebrates an album that met the moment—and allowed its creator to conquer the world.",
                    "short": "Pop’s unstoppable force delivers another round of Future Nostalgia."
                },
                "isCompilation": false,
                "contentRating": "explicit"
            }
        },
        {
            "id": "pl.886b4cfed21c4a1c9d817491feaeb8aa",
            "type": "playlists",
            "href": "/v1/catalog/sk/playlists/pl.886b4cfed21c4a1c9d817491feaeb8aa",
            "attributes": {
                "artwork": {
                    "width": 1080,
                    "height": 1080,
                    "url": "https://is1-ssl.mzstatic.com/image/thumb/Features124/v4/d9/fe/ca/d9feca92-73e1-c44e-386f-cfae36749aaf/source/{w}x{h}SC.CAESS02.jpeg?l=en-GB",
                    "bgColor": "21162a",
                    "textColor1": "ffffff",
                    "textColor2": "e8dcdc",
                    "textColor3": "cabdba",
                    "textColor4": "baadb3"
                },
                "isChart": false,
                "url": "https://music.apple.com/sk/playlist/inspirational-songs-essentials/pl.886b4cfed21c4a1c9d817491feaeb8aa",
                "lastModifiedDate": "2021-01-29T23:03:43Z",
                "name": "Inspirational Songs Essentials",
                "playlistType": "editorial",
                "curatorName": "Apple Music Pop",
                "playParams": {
                    "id": "pl.886b4cfed21c4a1c9d817491feaeb8aa",
                    "kind": "playlist"
                },
                "description": {
                    "standard": "Inspirational songs come in all shapes, sizes, and genres. You’ll encounter celebratory hard rock mingling with defiant hip-hop, peak-hour EDM rubbing shoulders with bubbly pop. There are even plenty of ballads as fragile as fine china. What’s more, the songs we find inspiring have many different purposes. More than a few are like rocket fuel powering us through sweaty workouts or late nights on the town; others have more personal aims, like pulling folks out of heartache or self-doubt. Some possess political dimensions, serving as soundtracks for social movements or pleas for peace and love in a world racked with strife. Yet all of them share a few vital traits. In addition to lyrics focused on perseverance and overcoming obstacles, each one boasts a riff, rhythm, or lead vocal that sounds as though it’s capable of physically elevating listeners to higher planes of existence.",
                    "short": "Beloved anthems of perseverance and overcoming obstacles."
                }
            }
        }
    ]
}

When I set the limit=2, I got just 2 entries. As expected.

Response for "https://api.music.apple.com/v1/me/recent/played?limit=2"

{
    "next": "/v1/me/recent/played?offset=2",
    "data": [
        {
            "id": "ra.562939683",
            "type": "stations",
            "href": "/v1/catalog/sk/stations/ra.562939683",
            "attributes": {
                "playParams": {
                    "id": "ra.562939683",
                    "kind": "radioStation",
                    "format": "tracks",
                    "stationHash": "CgkIARoFo463jAIQAQ"
                },
                "isLive": false,
                "artwork": {
                    "width": 2400,
                    "height": 2400,
                    "url": "https://is5-ssl.mzstatic.com/image/thumb/Features114/v4/40/0d/22/400d2226-ab71-66f4-92a1-baaa07276664/mzl.wimxogea.png/{w}x{h}AM.RSAB01.jpeg",
                    "bgColor": "f3f3f3",
                    "textColor1": "040404",
                    "textColor2": "282828",
                    "textColor3": "333333",
                    "textColor4": "505050"
                },
                "url": "https://music.apple.com/sk/station/rone-similar-artists/ra.562939683",
                "name": "Rone & Similar Artists"
            }
        },
        {
            "id": "pl.41fced032b8c4a909de7c696566ed485",
            "type": "playlists",
            "href": "/v1/catalog/sk/playlists/pl.41fced032b8c4a909de7c696566ed485",
            "attributes": {
                "artwork": {
                    "width": 1080,
                    "height": 1080,
                    "url": "https://is1-ssl.mzstatic.com/image/thumb/Features114/v4/87/09/5e/87095e3e-df15-05d8-6baa-4bf32ea6c0e0/source/{w}x{h}SC.DN01.jpeg?l=en-GB",
                    "bgColor": "aadf95",
                    "textColor1": "000000",
                    "textColor2": "0e2149",
                    "textColor3": "1c3656",
                    "textColor4": "264157"
                },
                "isChart": false,
                "url": "https://music.apple.com/sk/playlist/indie-electronic/pl.41fced032b8c4a909de7c696566ed485",
                "lastModifiedDate": "2021-03-12T05:00:46Z",
                "name": "Indie Electronic",
                "playlistType": "editorial",
                "curatorName": "Apple Music Indie",
                "playParams": {
                    "id": "pl.41fced032b8c4a909de7c696566ed485",
                    "kind": "playlist"
                },
                "description": {
                    "standard": "The longer we live and listen in this digital world, the weirder it feels to talk about electronic music. Still, it’s the artists that have embraced the possibilities of electronics on their own terms that have turned out the most reliably interesting music, hybrids that combine classic songwriting and expressivity—be it rock, soul, indie or pop—with sounds and forms that didn’t exist until the programming did. From the downtempo, club-inflected indie pop of artists like The xx to the straight-up cybernetic visions of FKA twigs, here’s a playlist gathering the most exciting indie electronic music of the still-young millennium. Our editors update tracks here regularly, so if you hear something you like, add it to your library.",
                    "short": "All hail the hybrids."
                }
            }
        }
    ]
}

Then I tried to get "next page", so limit=2&offset=2. And lo and behold, I got the next page!

Response for "https://api.music.apple.com/v1/me/recent/played?limit=2&offset=2"

{
    "data": [
        {
            "id": "1551178998",
            "type": "albums",
            "href": "/v1/catalog/sk/albums/1551178998",
            "attributes": {
                "artwork": {
                    "width": 4000,
                    "height": 4000,
                    "url": "https://is1-ssl.mzstatic.com/image/thumb/Music114/v4/fc/7f/0a/fc7f0a77-66a6-1a3a-018a-315d6f5d3eca/190295042998.jpg/{w}x{h}bb.jpeg",
                    "bgColor": "040404",
                    "textColor1": "fafafa",
                    "textColor2": "e0e2e1",
                    "textColor3": "c9c9c9",
                    "textColor4": "b4b6b5"
                },
                "artistName": "Dua Lipa",
                "isSingle": false,
                "url": "https://music.apple.com/sk/album/future-nostalgia-the-moonlight-edition/1551178998",
                "isComplete": true,
                "genreNames": [
                    "Pop",
                    "Music"
                ],
                "trackCount": 19,
                "isMasteredForItunes": false,
                "releaseDate": "2021-02-11",
                "name": "Future Nostalgia (The Moonlight Edition)",
                "recordLabel": "Warner Records",
                "upc": "190295042998",
                "copyright": "A Warner Records UK Release, ℗ 2021 Dua Lipa Limited under exclusive licence to Warner Music UK Limited. Except tracks 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 18 ℗ 2020, tracks 1 & 2 ℗ 2019 Dua Lipa Limited under exclusive licence to Warner Music UK Limited, track 14  ℗ 2020 RCA Records, a division of Sony Music Entertainment, track 19 ℗ 2020 Sueños Globales, LLC, Exclusively Licensed to UMG Recordings Inc, ℗ Universal Music Latino/NEON16.",
                "playParams": {
                    "id": "1551178998",
                    "kind": "album"
                },
                "editorialNotes": {
                    "standard": "When Dua Lipa released <i>Future Nostalgia</i> in March 2020, she knew she was taking a risk (in a tearful social media video at the time, the British singer wondered whether releasing an album so laced with joy was “the right thing to do” just as a global pandemic hit). Her gamble, of course, paid off. <i>Future Nostalgia</i>—a celebratory odyssey into pop’s future, influenced by the late-night sounds of its past—proved to be just the tonic a world in crisis needed. “When I was creating this record, I wanted it to feel like a form of escapism,” Lipa tells Apple Music. “And it felt like, during this time, it did serve as a form of escapism for me. And I was so happy with the response that the record got, and people [who] were like, ‘This got me through lockdown.’” Almost exactly a year later—and following an exhilarating, star-studded remix album, a Mercury Prize nomination and six Grammy Award nods—comes <i>The Moonlight Edition</i>. Here, you’ll find the original record's 11 uplifting tracks and the stream of hits Lipa served up in its wake (“Fever” with Angèle, a DaBaby-featuring remix of “Levitating” and “Prisoner”, Lipa’s inescapable Miley Cyrus collab) plus previously unreleased tracks, including “We’re Good”, on which Lipa departs from <i>Future Nostalgia</i>’s iridescent, disco-indebted sounds. <i>The Moonlight Edition</i> celebrates an album that met the moment—and allowed its creator to conquer the world.",
                    "short": "Pop’s unstoppable force delivers another round of Future Nostalgia."
                },
                "isCompilation": false,
                "contentRating": "explicit"
            }
        },
        {
            "id": "pl.886b4cfed21c4a1c9d817491feaeb8aa",
            "type": "playlists",
            "href": "/v1/catalog/sk/playlists/pl.886b4cfed21c4a1c9d817491feaeb8aa",
            "attributes": {
                "artwork": {
                    "width": 1080,
                    "height": 1080,
                    "url": "https://is1-ssl.mzstatic.com/image/thumb/Features124/v4/d9/fe/ca/d9feca92-73e1-c44e-386f-cfae36749aaf/source/{w}x{h}SC.CAESS02.jpeg?l=en-GB",
                    "bgColor": "21162a",
                    "textColor1": "ffffff",
                    "textColor2": "e8dcdc",
                    "textColor3": "cabdba",
                    "textColor4": "baadb3"
                },
                "isChart": false,
                "url": "https://music.apple.com/sk/playlist/inspirational-songs-essentials/pl.886b4cfed21c4a1c9d817491feaeb8aa",
                "lastModifiedDate": "2021-01-29T23:03:43Z",
                "name": "Inspirational Songs Essentials",
                "playlistType": "editorial",
                "curatorName": "Apple Music Pop",
                "playParams": {
                    "id": "pl.886b4cfed21c4a1c9d817491feaeb8aa",
                    "kind": "playlist"
                },
                "description": {
                    "standard": "Inspirational songs come in all shapes, sizes, and genres. You’ll encounter celebratory hard rock mingling with defiant hip-hop, peak-hour EDM rubbing shoulders with bubbly pop. There are even plenty of ballads as fragile as fine china. What’s more, the songs we find inspiring have many different purposes. More than a few are like rocket fuel powering us through sweaty workouts or late nights on the town; others have more personal aims, like pulling folks out of heartache or self-doubt. Some possess political dimensions, serving as soundtracks for social movements or pleas for peace and love in a world racked with strife. Yet all of them share a few vital traits. In addition to lyrics focused on perseverance and overcoming obstacles, each one boasts a riff, rhythm, or lead vocal that sounds as though it’s capable of physically elevating listeners to higher planes of existence.",
                    "short": "Beloved anthems of perseverance and overcoming obstacles."
                }
            }
        }
    ]
}

Then I also looked at what happens if you set offset beyond what's in the recently-played list. As expected, I got empty array.

Response for "https://api.music.apple.com/v1/me/recent/played?offset=10"

{
    "data": []
}

The offset can be set to as high as 1000000000s (10^9). At 10000000000 (one more zero), the query param is ignored.

Negative offset is ignored.

Conclusion

Frankly, I had higher hopes for the Apple Music API. While getting 50 latest recently played resources is fine, these are the cons:

No playedAt info per resource. One album might play just few seconds and one for hours, and you won't know.
No songs in the response. You don't know what exact songs were played.
Obtaining music user token is difficult, if you want to make requests to personalized endpoints on the server-side. I made a passportJS strategy for just that, reverse engineering MusicKitJS, but it wasn't easy. ~~Still need to publish it on NPM.~~ Now published as passport-apple-music.
If you're unfamiliar with Apple's developer env, it's hard to know which service ID and with what permissions you need to access Apple Music API. It took me 3 days to realize I was integrating "Sign in with Apple" instead of Apple Music access.

References

Apple Music API Docs: https://developer.apple.com/documentation/applemusicapi/get_recently_played_resources
Spotify API Docs: https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-the-users-currently-playing-track
Photo by Kind and Curious on Unsplash

DEV Community: Juro Oravec

One AI config to rule all repos

The idea: one root, many projects

Why submodules (and not symlinks)?

Getting started

1. Clone the repo

2. Add your projects

3. Switching focus when you have too many projects

4. Or let the AI do it

What's in the box

Try it

django-components v0.94 - Templating is now on par with Vue or React

Portadom: A Unified Interface for DOM Manipulation

Introduction

The Portadom Workflow

1. Prototyping with Vanilla JS

2. Static HTML with JSDOM or Cheerio

3. Dynamic Sites with Playwright

Embracing Flexibility

Take the Leap with Portadom

Chaining

Examples

Example - Profesia.sk

Example - SKCRIS

Example - Facebook post timestamp

Learn more

Filter groups: The best practice of filtering just about anything

Jean's a... what?

Here comes the boy filter groups

It's a piece of cake

*Slaps cake* This cake can be cut up in so man- ...oh

User interface

Example 1:

Example 2:

Behind the scenes

Example 1

Example 2

Sending the filter groups to the server

Example 1: Filter as query parameters - each filter field is separate query param

Example 2: Filter as query parameters - filters encoded as JSON

Example 3: Filter state as post body, GraphQL query, or other

Querying the database

Example 1 - Query database for each of the filter group

Example 2 - Construct single query from multiple groups

Conclusion

Reverse engineering Apple's MusicKitJS to create Apple Music Strategy for PassportJS

TL;DR

Background

Analysing MusicKitJS to understand auth flow

7 Tips for reverse engineering minified TypeScript/JavaScript

Juro Oravec ・ Mar 20 '21

Generating auth URL

Controlling the auth flow

Passing options to auth flow

Conclusion

7 Tips for reverse engineering minified TypeScript/JavaScript

Background

TL;DR:

1. Use beautifiers to clean up minified code.

2. Understand how minifiers compress the execution (control) flow into &&, ||, ,, ;, and (x = y)

void 0 as undefined

Inlined assignment (x = y)

Conditional execution with && and ||

Comma operator

3. Recognize async constructs

4. Recognize class constructs

Constructor as function(...) {...}

Inheritance with __extends and x.call(this, ...) || this;

Class methods and props with x.prototype.xyz = {...} or Object.defineProperty(x.prototype, 'xyz', {...}

6. Use property names or class methods to understand the context.

7. Use VSCode's type inference to understand the context.

Conclusion

(Failed) trying to get recently played songs from Apple Music API

Background

Reverse engineering Apple's MusicKitJS to create Apple Music Strategy for PassportJS

Juro Oravec ・ Mar 21 '21 ・ 7 min read

TL;DR:

What I did

Observation 1: If you set limit above 10, you get an error in the payload.

Observation 2: offset DOES work for this endpoint

Slaps cake This cake can be cut up in so man- ...oh

2. Understand how minifiers compress the execution (control) flow into `&&`, `||`, `,`, `;`, and `(x = y)`

`void 0` as `undefined`

Inlined assignment `(x = y)`

Conditional execution with `&&` and `||`

Constructor as `function(...) {...}`

Inheritance with `__extends` and `x.call(this, ...) || this;`

Class methods and props with `x.prototype.xyz = {...}` or `Object.defineProperty(x.prototype, 'xyz', {...}`

Observation 1: If you set `limit` above `10`, you get an error in the payload.

Observation 2: `offset` DOES work for this endpoint