stream-feeds-migration

/stream-feeds-migration produces the mapping object for an Activity Feeds v2 → v3 sync configuration by looking at what your v2 app's data actually contains, rather than at what your schema is believed to contain. The same mapping drives both migration paths (the live syncer and the bulk exporter), so getting it right once fixes both.

What it produces

The mapping object, ready to paste into your app's sync configuration, with every key justified by evidence in your data:

• Activity field mapping: id sources (id, foreign_id), field renames, reshare/reply parents, activity attachments, and where the extra_context bag should land.
• Reaction classification: each reaction kind sorted into a v3 comment, bookmark, comment bookmark, or plain reaction, plus comment text, reply, and attachment paths.
• The keys it deliberately left out: with the default that already covers your app's shape, so an absent key reads as a decision rather than an oversight. An empty mapping ({}) is a valid, correct answer for an app that already matches v3 conventions.

It also states plainly what a sample cannot prove (user fields are never sampled, older post formats can be missing when older periods are empty or crowded, rare shapes hide in the tail), so you know what still needs confirming. When you give it your v2 integration code as well, it closes most of those gaps from the code.

Example prompts

/stream-feeds-migration what mapping do we need for our app?
/stream-feeds-migration build the v2 to v3 sync mapping for my feeds app
/stream-feeds-migration a migrated activity landed in v3 with no text, review our mapping
/stream-feeds-migration our comments came through as plain reactions, what's wrong with the mapping?

How it works

1. Credentials into the environment. You export the v2 app's key and secret yourself (! export STREAM_API_KEY=… STREAM_API_SECRET=…) so the secret never enters the conversation. The skill never reads a .env file.
2. Sample the live v2 app. The skill ships a small sampling script (Python, standard library only) that calls the read-only migration sample endpoints to pull activities from several periods (newest, then up to 2 years back) and a spread of reactions, returning the raw stored payloads so the real field names and nesting are visible. It reads the per-period stats first, to see how representative the sample is. Because the sample does not say which feed group an activity came from, it asks which feed groups your app uses and can read named feeds directly (--feed group:id) for groups the sample missed. It writes one local JSON file and nothing else.
3. Read your integration code (when you have it). If the skill can see your app's repository, a second read-only script lists every place your code writes to Feeds v2: activities, reactions and child reactions, follows, users and collections, with the feed groups and reaction kinds each call uses. The skill builds an inventory of your write paths from it, checks git log for fields that changed over time, and cross-checks the code against the sample. The code shows what the sample can miss: user fields, rarely used feed groups, how foreign_id is built, and older formats still in storage. The sample stays the source of truth, since your code is rarely the only writer.
4. Analyze and emit. It works through activities, reactions, and users against the full key catalogue, then returns the mapping object with each key explained and the sample's limits called out.