Migration 0.3.x → 1.0

v1.0.0 is a deliberate semver gate — not automatic when Phase 10 or Phase 11 close. This guide documents breaking changes planned for (or shipped in) the 1.0 release so you can upgrade on your schedule.

# Recommended: align all packages to 1.0.0 when released
pnpm add @media-sdk/core@^1.0.0 @media-sdk/react@^1.0.0 @media-sdk/ui-react@^1.0.0
pnpm add @media-sdk/native@^1.0.0 @media-sdk/ui-native@^1.0.0   # React Native apps

If you are still on 0.3.x with no wire-type imports, you can stay put until you are ready — search, pagination, capabilities, and filters are unchanged.

Summary of changes

Area	0.3.x	1.0
Pexels wire types	@deprecated public exports	Removed from @media-sdk/core
Domain types	Photo, Video, PaginatedResponse<T>	Unchanged — use these
Capabilities / filters	getCapabilities, photoFilters, videoFilters	Unchanged
Abort helpers	createAbortError, isAbortError	Unchanged (shipped in 0.3.1)
Native packages	0.1.0	Recommended: 1.0.0 aligned with core/react
ProviderFactory	Not shipped	Still not shipped — use createMediaClient

Removed: Pexels wire types

The following types are no longer exported from @media-sdk/core:

Removed type	Use instead
PexelsPhotoSearchResponse	PaginatedResponse<Photo>
PexelsVideo	Video
PexelsVideoFile	VideoFile (on Video.videoFiles)
PexelsVideoUser	Video.user fields
PexelsVideoSearchResponse	PaginatedResponse<Video>

Before (0.3.x — deprecated)

import type { PexelsPhotoSearchResponse } from "@media-sdk/core";

async function handleRaw(response: PexelsPhotoSearchResponse) {
  const photos = response.photos;
  const page = response.page;
}

After (1.0)

import type { PaginatedResponse, Photo } from "@media-sdk/core";

async function handleNormalized(result: PaginatedResponse<Photo>) {
  const photos = result.items;
  const page = result.pagination.page;
}

PexelsMediaClient and PixabayMediaClient already return normalized shapes from searchPhotos, searchVideos, getCuratedPhotos, and related methods. You only need to change code that imported wire types directly.

If you mock Pexels HTTP responses in tests (snake_case JSON), define local wire interfaces in your test harness — they are not part of the SDK public API.

Package version relationships

Package	0.3.x / 0.1.x	1.0 recommendation
@media-sdk/core	0.3.1	1.0.0
@media-sdk/react	0.3.0	1.0.0
@media-sdk/ui-react	0.3.0	1.0.0
@media-sdk/native	0.1.0	1.0.0
@media-sdk/ui-native	0.1.0	1.0.0

Recommendation: Release all five packages at 1.0.0 together. Native packages shipped at 0.1.0 during Phase 9; promoting them to 1.0.0 alongside core/react signals a stable, cross-platform API without a separate native semver track.

Peer dependencies remain:

• react ^18.0.0 || ^19.0.0 on hook and UI packages
• react-native >= 0.71.0 on @media-sdk/ui-native only

Abort helpers (already in 0.3.1)

createAbortError() and isAbortError() shipped in @media-sdk/core@0.3.1 (no 1.0 breaking change):

import { createAbortError, isAbortError } from "@media-sdk/core";

const controller = new AbortController();
controller.abort();
throw createAbortError();

try {
  await client.searchPhotos({ query: "nature", signal: controller.signal });
} catch (error) {
  if (isAbortError(error)) {
    return; // user cancelled — not a failure
  }
  throw error;
}

@media-sdk/react and @media-sdk/native hooks use these helpers internally. You do not need to change hook code when upgrading to 1.0.

Capabilities and filters (unchanged)

The capability and filter model from 0.3.0 is stable for 1.0:

• client.capabilities / getCapabilities(client) / useMediaCapabilities()
• photoFilters and videoFilters on SearchParams and hooks
• UNSUPPORTED_CAPABILITY, UNSUPPORTED_FILTER, INVALID_FILTER_VALUE error codes

See Migration 0.2 → 0.3 for capability and filter adoption if you are upgrading from an older baseline.

What is not changing

Item	Status
MediaClient interface	Stable
PexelsMediaClient / PixabayMediaClient	Stable
Hook return shapes (loading, data, error, pagination helpers)	Stable
UI component props	Stable
ProviderFactory / plugin registry	Not planned — keep app-local createMediaClient
Cache getStats()	Declined for 1.x (see reliability)
Analytics metadata v2	Design only — not shipped in 1.0

Upgrade checklist

1. Search your codebase for imports of PexelsPhotoSearchResponse, PexelsVideo, PexelsVideoFile, PexelsVideoUser, or PexelsVideoSearchResponse from @media-sdk/core.
2. Replace with Photo, Video, VideoFile, or PaginatedResponse<T>.
3. Bump all @media-sdk/* packages to ^1.0.0 (when published).
4. Run pnpm typecheck and your test suite.
5. Review compatibility matrix if you use both Pexels and Pixabay.

Related guides

• Migration 0.2 → 0.3 — capabilities, filters, earlier deprecations
• Installation — current version pins
• Doc journeys — adoption paths