Three coexisting JS API clients (api-client 0.2 vs 0.7, wp-native-client, raw fetch) — finish migration

[chubes4]

Summary

Three coexisting JS API-client dependencies across the network, including two divergent major-ish versions of the same client. MEMORY notes an in-flight migration from @extrachill/api-client → wp-native-client; the half-migrated state is visible.

Evidence (verified)

• @extrachill/api-client: extrachill-studio/package.json:16 (^0.7.0), extrachill-analytics/package.json:18 (^0.2.0) — TWO divergent versions of the same client
• wp-native-client: extrachill-seo/package.json:14, extrachill-admin-tools/package.json:23
• raw @wordpress/api-fetch: studio, admin-tools, analytics, content-blocks, data-machine, data-machine-editor, data-machine-socials
• extrachill-admin-tools ships BOTH @wordpress/api-fetch AND wp-native-client
  (Note: the standalone "extrachill-api-client" PLUGIN does not exist — only the npm package + the extrachill-api REST wrapper.)

Why it's debt

Three ways to call the same API, duplicated request/auth/error handling, and the migration target (wp-native-client) is adopted by only 2 of 4+ consumers. The 0.2 vs 0.7 split means studio and analytics ship divergent client behavior.

Fix

Complete the migration to the single chosen client (wp-native-client per MEMORY). Migrate studio + analytics off @extrachill/api-client; standardize on one client across consumers. Track per-plugin in existing migration issues if they exist (extrachill-artist-platform#26, extrachill-community#23 are the analogous ones).

Acceptance criteria

• One canonical JS API client across consumers
• No divergent versions of the same client pinned
• @extrachill/api-client retired where wp-native-client is the target

[chubes4]

Network-wide version map (fresh-eyes audit, current main)

#84 frames this as a single-plugin problem, but a network-wide sweep of current origin/main shows the fork is three incompatible major versions of the same client plus the wp-native-client migration target — the literal seam between "federated plugins" and "one network."

Who's on what (source-confirmed, not build artifacts)

Plugin	Client	Version	Pattern
extrachill-studio	@extrachill/api-client	^0.7.0 (current)	new ExtraChillClient(new WpApiFetchTransport(apiFetch))
extrachill-community	@extrachill/api-client	^0.3.0	same
extrachill-artist-platform	@extrachill/api-client	^0.2.1 (oldest)	same
extrachill-analytics	wp-native-client	^0.0.1	new WPNativeClient(transport, { validateAbilityNames: false })
extrachill-seo	wp-native-client	—	migrated
extrachill-admin-tools	wp-native-client	—	migrated

Canonical published extrachill-api-client repo is at 0.7.0 — so community (0.3) and artist-platform (0.2.1) are 4–5 minors behind the same library studio ships.

Why this is the keystone for the interconnected-network mission

• All three @extrachill/api-client consumers hit the SAME REST hub (extrachill-api) but at three different client behaviors/auth/fetch semantics. For a network that wants to read as one surface, that's the seam where it reads as three.
• wp-native-client is the convergence target (ability-by-name, validateAbilityNames) — seo/admin-tools/analytics already cut over. The @extrachill/api-client trio is the unfinished half.
• Both clients wrap the identical WpApiFetchTransport(apiFetch), so the cutover is mechanical, not architectural — the blocker is just doing it consistently.

Recommended end-state

One client (wp-native-client, ability-by-name) at one version across every plugin. Intermediate acceptable step: bump the three @extrachill/api-client consumers to 0.7.0 to kill the version skew first, then cut to wp-native-client.

A migration punch-list (exact client calls per plugin) is being inventoried separately and will be linked here. Related migration issues: community#23, artist-platform#26/#11, analytics#8.

[chubes4]

JS API-client unification — migration punch-list

Investigation only (no code changed). Inventory built from fresh origin/main of extrachill-studio, extrachill-community, extrachill-artist-platform, mapped through @extrachill/api-client v0.7.0 source and extrachill-api route handlers.

TL;DR

• All three plugins instantiate the client identically (new ExtraChillClient(new WpApiFetchTransport(apiFetch))), so the transport doesn't change — only the client class + method-call style.
• The migration target (wp-native-client, ability-by-name) is the pattern already shipped in analytics and seo. Their src/api/client.js is the copy-from reference: build a thin facade module that keeps the same exported function names, internally swapping client.<resource>.<method>() for client.execute('extrachill/<ability>', {...}) and falling back to raw apiFetch for the routes that have no backing ability.
• Most REST paths are already ability-backed in extrachill-api (the route handler is a thin wp_get_ability()->execute() wrapper), so those cut over mechanically.
• The blockers are all the same shape: media/upload routes that implement logic inline (no ability) or abilities that require a WP_REST_Request for multipart files. These cannot move to ability-by-name without backend work first.

---

Per-plugin call-site inventory

1. extrachill-artist-platform — single facade, cleanest case

Everything funnels through src/blocks/shared/api/client.js (one file; 12 consumer modules import named exports from it). Migration = rewrite that one file; consumers need zero changes (same export names — exactly how analytics/seo did it).

Facade export (file: shared/api/client.js)	old method	target REST path	backing ability
getArtist	client.artists.getArtist	GET extrachill/v1/artists/{id}	extrachill/get-artist-data
createArtist	client.artists.create	POST extrachill/v1/artists	extrachill/create-artist
updateArtist	client.artists.update	PUT extrachill/v1/artists/{id}	extrachill/update-artist
getLinks	client.artists.getLinks	GET extrachill/v1/artists/{id}/links	extrachill/get-link-page-data
updateLinks	client.artists.updateLinks	PUT extrachill/v1/artists/{id}/links	extrachill/save-link-page-links / -styles / -settings / save-social-links (handler fans out by payload key)
getSocials	client.artists.getSocials	GET extrachill/v1/artists/{id}/socials	NO ABILITY — handler builds response inline (extrachill_api_build_socials_response)
updateSocials	client.artists.updateSocials	PUT extrachill/v1/artists/{id}/socials	extrachill/save-social-links
getAnalytics	client.artists.getAnalytics	GET extrachill/v1/artists/{id}/analytics	extrachill/artist-get-analytics
uploadMedia	client.media.buildUploadForm + client.media.upload	POST extrachill/v1/media (multipart)	NO ABILITY — handler is fully inline (blocker)
deleteMedia	client.media.delete	DELETE extrachill/v1/media	NO ABILITY — inline (blocker)
getRoster	client.artists.getRoster	GET extrachill/v1/artists/{id}/roster	extrachill/artist-get-roster
inviteRosterMember	client.artists.inviteRosterMember	POST extrachill/v1/artists/{id}/roster	NO ABILITY — apply_filters('extrachill_artist_invite_member') inline (blocker)
removeRosterMember	client.artists.removeRosterMember	DELETE extrachill/v1/artists/{id}/roster/{userId}	NO ABILITY — inline ec_remove_artist_membership (blocker)
cancelRosterInvite	client.artists.cancelRosterInvite	DELETE extrachill/v1/artists/{id}/roster/invites/{inviteId}	NO ABILITY — inline ec_remove_pending_invitation (blocker)
searchArtistCapableUsers	client.users.search	GET extrachill/v1/users/search	extrachill/users-search
getSubscribers	client.artists.getSubscribers	GET extrachill/v1/artists/{id}/subscribers	extrachill/artist-list-subscribers
exportSubscribers	client.artists.exportSubscribers	GET extrachill/v1/artists/{id}/subscribers/export	extrachill/artist-export-subscribers
listShopProducts	client.shop.listProducts	GET extrachill/v1/shop/products	extrachill/shop-list-products
createShopProduct	client.shop.createProduct	POST extrachill/v1/shop/products	extrachill/shop-create-product
updateShopProduct	client.shop.updateProduct	PUT extrachill/v1/shop/products/{id}	extrachill/shop-update-product
deleteShopProduct	client.shop.deleteProduct	DELETE extrachill/v1/shop/products/{id}	extrachill/shop-delete-product
uploadShopProductImages	client.shop.uploadProductImages	POST extrachill/v1/shop/products/{id}/images (multipart)	extrachill/shop-upload-product-image — ability takes the raw WP_REST_Request (multipart blocker, see below)
deleteShopProductImage	client.shop.deleteProductImage	DELETE extrachill/v1/shop/products/{id}/images/{attId}	extrachill/shop-delete-product-image
getArtistShippingAddress	client.shop.getShippingAddress	GET extrachill/v1/shop/shipping-address	extrachill/shop-get-shipping-address
updateArtistShippingAddress	client.shop.updateShippingAddress	PUT extrachill/v1/shop/shipping-address	extrachill/shop-update-shipping-address
purchaseShippingLabel	client.shop.purchaseShippingLabel	POST extrachill/v1/shop/shipping-labels	extrachill/shop-create-shipping-label
getShippingLabel	client.shop.getShippingLabel	GET extrachill/v1/shop/shipping-labels/{orderId}	extrachill/shop-get-shipping-label
getArtistPermissions	client.artists.getPermissions	GET extrachill/v1/artists/{id}/permissions	extrachill/artist-get-permissions
generateQRCode	client.admin.generateQrCode	POST extrachill/v1/tools/qr-code	extrachill/generate-qr-code
getStripeConnectStatus / createStripeConnect*Link / listShopOrders / updateShopOrderStatus / refundShopOrder	raw shopFetch() (cross-origin to shop.extrachill.com)	—	already bypasses api-client; stays raw fetch, not in scope

Note: the orders + stripe-connect REST routes in extrachill-api are ability-backed (extrachill/shop-list-orders, -update-order-status, -refund-order, -stripe-status, -stripe-onboarding-link, -stripe-dashboard-link), but artist-platform deliberately calls them via cross-origin shopFetch instead of the client. Out of scope for this cutover — leave as-is.

2. extrachill-community — three view.tsx files, nested namespaces

No facade; each block instantiates its own const client = new ExtraChillClient(...). Uses client.users.* and client.media.* nested resources.

Call site	old method	target REST path	backing ability
src/blocks/edit-profile/view.tsx:88	client.media.buildUploadForm('user_avatar',...)	(form builder, client-side)	n/a (helper)
src/blocks/edit-profile/view.tsx:89	client.media.upload(formData)	POST extrachill/v1/media (multipart, user_avatar)	NO ABILITY — inline (blocker)
src/blocks/edit-profile/view.tsx:217	client.users.getProfile()	GET extrachill/v1/users/me/profile	extrachill/get-user-profile
src/blocks/edit-profile/view.tsx:248	client.users.updateProfile(...)	POST extrachill/v1/users/me/profile	extrachill/update-user-profile
src/blocks/edit-profile/view.tsx:253	client.users.updateLinks({links})	POST extrachill/v1/users/me/links	extrachill/update-user-links
src/blocks/leaderboard/view.tsx:105	client.users.leaderboard(...)	GET extrachill/v1/users/leaderboard	extrachill/users-leaderboard
src/blocks/user-settings/view.tsx:54	client.users.updateSettings(...)	POST extrachill/v1/users/me/settings	extrachill/update-user-settings
src/blocks/user-settings/view.tsx:97	client.users.changeEmail(...)	POST extrachill/v1/users/me/email	extrachill/change-user-email
src/blocks/user-settings/view.tsx:111	client.users.changePassword(...)	POST extrachill/v1/users/me/password	extrachill/change-user-password
src/blocks/user-settings/view.tsx:156	client.users.getSubscriptions()	GET extrachill/v1/users/me/subscriptions	extrachill/get-subscriptions
src/blocks/user-settings/view.tsx:177	client.users.updateSubscriptions(...)	POST extrachill/v1/users/me/subscriptions	extrachill/update-subscriptions
src/blocks/user-settings/view.tsx:212	client.users.requestArtistAccess(...)	POST extrachill/v1/users/me/artist-access	extrachill/request-artist-access
src/blocks/user-settings/view.tsx:241	client.users.getSettings() + client.users.getProfile()	GET .../me/settings + .../me/profile	extrachill/get-user-settings + extrachill/get-user-profile

Community blockers: only the avatar upload (client.media.upload). Every client.users.* call has a registered ability — community is fully migratable except avatar upload.

3. extrachill-studio — mostly RAW apiFetch already; client used for a thin slice

studioClient is defined in src/blocks/studio/app/client.ts. Most studio socials traffic is raw apiFetch to datamachine/v1/socials/... inside studioSocialsApi (not through the client at all — out of scope for the api-client cutover but worth noting it does NOT use either client). The actual studioClient.* call sites:

Call site	old method	target REST path	backing ability
app/client.ts:147 (uploadStudioFile)	studioClient.socials.uploadCroppedMedia(formData)	POST datamachine/v1/socials/media/crop (multipart)	DM-namespaced route, no extrachill/* ability (blocker for ability-by-name)
tabs/qr-codes/index.ts:42	studioClient.admin.generateQrCode(url, size)	POST extrachill/v1/tools/qr-code	extrachill/generate-qr-code
tabs/socials/index.ts:48	studioClient.socials.getPlatforms()	GET datamachine/v1/socials/platforms	DM route (not ability-backed in that handler)
tabs/socials/media-picker/index.tsx:59	studioClient.networkMedia.list(...)	GET extrachill/v1/network-media	extrachill/network-media-list
tabs/socials/media-picker/index.tsx:134	studioClient.networkMedia.buildUploadForm(file)	(form builder, client-side)	n/a (helper)
tabs/socials/media-picker/index.tsx:135	studioClient.networkMedia.upload(formData)	POST extrachill/v1/network-media (multipart)	extrachill/network-media-upload — multipart; needs verification it accepts a non-request payload
tabs/socials/publish/index.ts:210	studioClient.socials.crossPost(...)	POST datamachine/v1/socials/post	DM route
tabs/socials/publish/index.ts:237	studioClient.socials.waitForCrossPostJob(...)	polls GET datamachine/v1/socials/jobs/{id}	DM route (datamachine/get-jobs ability exists but the client-side poll loop is bespoke orchestration)

Studio also imports several types from @extrachill/api-client (SocialPlatformConfig, NetworkMediaItem, SocialMediaUploadResponse, SocialJobPlatformResult) in tabs/socials/* and types/externals.d.ts. wp-native-client is type-light — the migration must re-home or inline these type definitions, since wp-native-client won't export the EC domain types. This is a non-trivial part of studio's cutover.

---

Consolidated distinct @extrachill/api-client method surface in use

This is what wp-native-client (or the facade around it) must cover for full cutover:

client.artists.* — getArtist, create, update, getLinks, updateLinks, getSocials, updateSocials, getAnalytics, getPermissions, getRoster, inviteRosterMember, removeRosterMember, cancelRosterInvite, getSubscribers, exportSubscribers
client.users.* — getProfile, updateProfile, updateLinks, getSettings, updateSettings, changeEmail, changePassword, getSubscriptions, updateSubscriptions, requestArtistAccess, leaderboard, search
client.shop.* — listProducts, createProduct, updateProduct, deleteProduct, uploadProductImages, deleteProductImage, getShippingAddress, updateShippingAddress, purchaseShippingLabel, getShippingLabel
client.media.* — buildUploadForm, upload, delete
client.networkMedia.* — list, upload, buildUploadForm
client.socials.* — getPlatforms, crossPost, waitForCrossPostJob (+ internal getJobStatus), uploadCroppedMedia
client.admin.* — generateQrCode

Since wp-native-client calls abilities by name (client.execute('extrachill/<ability>', payload)), there is no resource-namespace surface to replicate — the facade module maps each old method name to either an execute() call or a raw apiFetch fallback (the analytics client mixes both; copy that).

---

Blockers (cannot move to ability-by-name without backend work)

#	Blocker	Affected plugins	Why	Fix needed first
B1	POST/DELETE extrachill/v1/media has no ability	community (avatar), artist-platform (artist/link-page images)	inc/routes/media/upload.php implements all upload/assign/delete logic inline (file validation, wp_handle_upload, per-context assignment, cross-site product images). There is no wp_get_ability() call.	Register an extrachill/upload-media + extrachill/delete-media ability that owns this logic; and it must accept multipart files (see B5). Until then, keep these as raw apiFetch in the facade.
B2	Roster write ops have no ability	artist-platform	inviteRosterMember uses apply_filters('extrachill_artist_invite_member'); removeRosterMember/cancelRosterInvite call ec_* functions inline. Only artist-get-roster (read) exists.	Register extrachill/artist-invite-roster-member, -remove-roster-member, -cancel-roster-invite abilities. Until then, keep these three as raw apiFetch.
B3	GET extrachill/v1/artists/{id}/socials has no read ability	artist-platform	Handler builds the response inline (extrachill_api_build_socials_response); the comment in the route even says "there's no dedicated read ability for socials."	Either add extrachill/get-artist-socials or fetch socials via get-link-page-data (socials are embedded there). Until then, keep getSocials raw.
B4	Studio socials hit the datamachine/v1/* namespace, not extrachill/*	studio	crossPost, getPlatforms, waitForCrossPostJob, uploadCroppedMedia target Data Machine Socials routes. Some have datamachine/* abilities, but they're a different namespace + the job-wait is bespoke client-side polling. wp-native-client (ability-by-name) doesn't model the poll loop.	Out of scope for the extrachill/* unification. Studio's socials layer should keep its current path (raw apiFetch / the existing socials client orchestration). Migrate only generateQrCode + networkMedia.* to wp-native-client.
B5	Multipart/upload calls can't carry files through ability-by-name as written	community, artist-platform, studio	shop-upload-product-image ability executes with 'request' => $request — it reads $_FILES off the WP_REST_Request. An ability-by-name JSON execute() from JS won't carry the multipart body. Same concern for network-media-upload.	Verify each upload ability can accept a transport-provided FormData (the wp-native-client transport must support postFormData-style multipart to an ability route), or keep uploads on the REST apiFetch path. Needs a transport capability check before any upload call is migrated.
B6	Studio depends on EC domain types exported by api-client	studio	SocialPlatformConfig, NetworkMediaItem, SocialMediaUploadResponse, SocialJobPlatformResult are imported from @extrachill/api-client. wp-native-client is type-light and won't export them.	Re-home these types (inline in studio, or a small shared @extrachill/types import) before dropping the api-client dependency.

The image-voting anonymous-vote perm mismatch pattern from api#81 does not appear in any of these three plugins' client call sites (it lives in content-blocks/image-voting-vote.php, unrelated to studio/community/artist-platform). No occurrence here — noted for completeness.

---

Suggested migration order

1. extrachill-community (do first — highest ability coverage, single nested-namespace pattern, smallest surface).
12 of 13 call sites have registered abilities; the only blocker is the avatar client.media.upload (B1). Migrate all client.users.* calls to client.execute('extrachill/<ability>', ...), keep avatar upload on raw apiFetch until B1's media ability lands. Three view.tsx files, mechanical.

2. extrachill-artist-platform (second — single client.js facade makes the swap surgical, but more blockers).
One file to rewrite; consumers untouched (proven by analytics/seo). Migrate the ~20 ability-backed exports; keep uploadMedia/deleteMedia (B1), getSocials (B3), and the 3 roster writes (B2) on raw apiFetch. The cross-origin shopFetch block stays as-is.

3. extrachill-studio (last — least api-client usage but most awkward).
Only generateQrCode + networkMedia.list/upload are clean extrachill/* ability moves. The bulk of studio's socials lives in the datamachine/v1/* namespace with bespoke job-polling (B4) and pulls EC types from api-client (B6). Migrate the QR + network-media slice to wp-native-client; leave the socials layer on its current path. Lowest ROI, highest special-casing — do it once the pattern is proven on the other two.

Backend prerequisite track (can run in parallel): file abilities for B1 (media upload/delete), B2 (roster writes), B3 (artist socials read), and confirm the wp-native-client transport's multipart story for B5. These unblock the "keep as raw apiFetch" exceptions so the final state is genuinely 100% ability-by-name.