getstream/agent-skills/stream-feeds-migration

Stream Feeds - v2 to v3 sync mapping

For CLI commands or routing to another Stream skill, read `../stream/SKILL.md`.

Produce the mapping object for an app's v2 -> v3 sync configuration by looking at what the app's v2 data actually contains, rather than at what anyone believes it contains.

One mapping serves both migration paths - the live syncer and the bulk exporter read the same configuration. Getting it right once fixes both; getting it wrong breaks both in the same way.

Workflow

1. Get credentials into the environment

Use getstream env to write the v2 app's credentials to an env file. Read getstream env -h for app selection and output options. Use --target web so the file contains both STREAM_API_KEY and STREAM_API_SECRET, which the sampler expects.

Load that file when running the sampler below. Do not print its contents or put credential values in chat or tool commands.

2. Pick the target

Default to production - https://api.stream-io-api.com. Use it unless the user names a different environment (EU, dedicated, staging), in which case pass --base-url <that URL>.

Do not raise alternative environments on your own; production is the assumed target and the user will say so if they mean otherwise.

3. Fetch the sample

set -a
. "<env-file>"
set +a
python3 <skill-dir>/fetch_sample.py --out v3sync-sample.json

<env-file> is the absolute path to the file written by getstream env. Run the block in one shell invocation so Python inherits the credentials.

<skill-dir> is the directory holding this SKILL.md. Resolve it to an absolute path before running - the skill runs from whatever directory the user happens to be in, so a relative path only works by accident. getstream skills links the pack into one of two places, so it is one of:

• .agents/skills/stream-feeds-migration (Cursor, Codex)
• .claude/skills/stream-feeds-migration (Claude Code)

Glob {.agents,.claude}/skills/stream-feeds-migration/SKILL.md to settle which.

The key and secret are read from STREAM_API_KEY and STREAM_API_SECRET. The script takes no `--secret` flag by design - a secret passed as an argument would land in the process list and the shell history, which is exactly what the environment variable avoids. (--api-key exists, since the key is not sensitive.) The sample is written to the working directory, which is where you want it.

Standard library only - no pip install. It calls two server-side-only endpoints:

• GET /api/v1.0/migration/sample/activities - up to 100 activities, drawn

from several periods (the newest, then at or before 7d, 30d, 180d, 1y and 2y ago)

• GET /api/v1.0/migration/sample/reactions - 5 reactions per distinct kind

Both return raw stored payloads: unflattened extra_context, unmodified reaction data. That is the point - you are looking for the real field names and nesting.

A 401 or 403 means the secret is wrong, or the token was built as a user token rather than a server-side one. A 404 means these endpoints are not available on the app's deployment yet; Stream support can confirm.

An empty activities array alongside a 200 is worth calling out rather than working around: the app is either genuinely empty or its activity store cannot serve this scan. Reactions carry an activity_id, so reactions in the sample prove activities exist and point to the second explanation.

Read what the activity sample left out

Recent deployments also return reaction_reference_count, reaction_references and slices, and the script keeps them in the sample file. Read them before the activities, because they say how representative the activities are:

• `reaction_reference_count` - how many target-feed copies of reactions

the sample left out. v2 writes one of these when a reaction has target_feeds. You can recognise them by a foreign_id of reaction:<id> and an extra_context.reaction holding an SR: ref. They carry no post fields, so they say nothing about the mapping; up to 3 are in reaction_references for reference.

• `slices` - one entry per period, with scanned, posts and

reaction_references. before is the period's cutoff; the newest slice has none. extended means the period was re-read with a larger scan because reaction references crowded it.

• A slice whose posts is small next to scanned was crowded: posts from

that period are under-represented. Say so.

• A slice with scanned: 0 held no activities inserted in that window.

Periods are by insert time, not by the activity's time, so data imported into v2 recently all lands in the newest slice.

When the older slices are empty on an app that has existed for a while, the sample cannot show what older posts look like. Ask whether the post format ever changed (different field names for text, media or ids), and say the mapping only covers the shape the sample shows.

If these keys are missing, the deployment predates them: the activities are the newest 100 and can include reaction references. Leave those out yourself by the shape above before analysing.

Cover every feed group

The sample is app-wide: it takes the newest activities wherever they were written, and does not say which feed group each came from. A feed group with little or old traffic can be missing entirely. One mapping serves the whole app, so a group whose activities are written differently (a backend job, a notification feed, an older client) gets a mapping fitted to the others.

Recent deployments list the app's feed groups in feed_groups (name and type); on older ones, ask the user which groups the app uses. Either way the sample does not say which group each activity came from, so ask whether any group is written by a different code path. For each group the sample may have missed, read a feed or two of it directly with --feed (read-only, repeatable):

python3 <skill-dir>/fetch_sample.py --out v3sync-sample.json \
  --feed notification:<user-id> --feed timeline:<user-id>

The activities land under feed_samples in the same file, normalised to the sample's shape (custom fields under extra_context, plus a feed field), so analyse them the same way. Aggregated and notification feeds are unwrapped into their activities. They also hold the target-feed copies of reactions; leave those out as above. A feed that fails (for example an unknown group) is recorded with its error and does not stop the run.

4. Read the integration code (when you have it)

The sample shows what is stored; the app's v2 integration code shows every way it gets written - including the paths the sample is weakest on: low-traffic feed groups, rarely used reaction kinds, child reactions, how users are created, and whether foreign_id is unique. If the user's repository is in the working directory (or they point you at it), read it. If not, ask once whether it is available; the skill works without it.

Follow `code-inventory.md`:

1. Run <skill-dir>/scan_v2_calls.py --root <repo> --out v2-code-scan.json to list every v2 write call

site (read-only; secrets in snippets are redacted - never quote one from the code yourself).

1. Read the call sites and build the inventory: one row per write path,

with its feed group(s), to-targets, fields, foreign_id construction, reaction kinds and data shape, child reactions, and user fields.

1. Check history for fields that changed (git log -S'<field>'): older

activities still carry the old format.

1. Cross-check the inventory against the sample. Agreement confirms a key;

code-only evidence is a rare or new path (map it, say so, and read a feed of it with --feed); sample-only evidence is another writer or an older version (ask). The sample stays the source of truth - the code is rarely the only writer.

5. Analyze

Read v3sync-sample.json and work through the checklist below. Read `mapping-keys.md` for the full key catalogue, defaults, exact resolution rules, and worked examples of the common shapes - do not guess key names or defaults from memory.

The single most common mistake is over-configuring. Every key has a default that is right for a conventional v2 app. Only emit a key when the sample shows the app deviates from that default. An empty mapping is a valid answer.

6. Emit the mapping

Produce only the mapping object, ready to paste into the app's existing sync configuration. Do not emit the surrounding configuration (enabled, base_url, api_key, secret, sample_rates, feed_groups_synced); those are deployment concerns, they are not derived from the sample, and restating them with placeholder credentials invites someone deploying a config with a <v3 app key> still in it.

Explain each key you set by pointing at the evidence: rows in the sample, and, when you read the code, the call sites (file:line). Say which keys rest on code alone.

Flag explicitly anything you could not determine from the sample - see Limits of the sample below. Silence there reads as "verified", which it is not.

7. Plan the code port (when you read the code)

If you read the integration code in step 4, also write a porting plan, following `porting-plan.md`: one row per write and read path with its v2 call, its v3 call, the switch-over step it belongs to (reads move first, every write moves together last), and the behaviour that changes. Take the v3 calls from the V2 to V3 Code Migration guide (through getstream docs), not from memory.

The plan is a document: do not edit the app's code. Offer to port it; if the user asks, follow Porting the code in that reference (v3 read paths behind a read flag, every write path behind one write flag, never writing to both versions).

Analysis checklist

Activities

Look at activities[].extra_context across the whole sample.

• Custom field names - any field whose name collides with a v3 reserved key,

or that should be surfaced at the top level of custom, needs a rename entry. Fields that are already conventionally named need nothing.

• Activity id - does a field hold a stable external id (external_id,

post_id, uuid)? If so, id should point at it. If instead foreign_id is populated and meaningful across the sample, foreign_id: "id" is the simpler answer. If neither, omit both and let the v2 UUID carry over. Before recommending foreign_id: "id", check that no two sampled activities share a foreign_id. v2 allows several activities with the same foreign_id (they differ by time), but as v3 ids they collide and only one survives. If any repeat, or the sample is too small to tell, ask whether foreign_ids are unique in the app, and keep the v2 UUID when they are not.

• Reshares / replies - a field holding an SA:<uuid> ref (commonly

shared_origin_post) is the parent_id field. Note that SA: refs are also autodetected, so only configure this when the sample shows the ref buried somewhere the autodetection would not reach first.

• Text - is the post body under text (default, no config) or something

else like body / message / content? Set text only if it differs.

• Attachments - a list of media objects under a custom path means

activity_attachments_field.

• Actor format - check actor across the sample. SU:<id> is handled

natively. A different prefix (User:<id>) needs a replaces entry. An actor that is a whole JSON blob is a known legacy shape and needs no mapping.

• extra_context nesting - decide whether the bag should stay nested under

custom.extra_context (default), be renamed, or be flattened (""). This one is a preference, not something the sample can settle: ask.

Reactions