nekocap-data-fetching

name	nekocap-data-fetching
description	Use when adding or modifying an API call, RTK Query endpoint, BackendProvider method, or any code that talks to the nekocap backend. Triggers on tasks like "add an endpoint", "fetch X from the server", "wire a mutation", or "expose a new BackendProvider method".

This skill covers how nekocap talks to its backend. All API access goes through the BackendProvider abstraction so the same code works in the Next.js web app and in the extension (where the actual request is proxied through the background script).

The three layers

1. BackendProvider — src/common/providers/backend-provider.ts. Defines every backend method. The class is implemented for Parse + Firebase. Add new methods here first.
2. RTK Query endpoints — src/common/store/api.ts plus per-feature src/common/feature/<name>/api.ts. Exposes provider methods as hooks (useGetFooQuery, useUpdateFooMutation).
3. Components — consume the generated hooks. Never call fetch or axios directly.

Adding a new endpoint (preferred path: RTK Query)

1. Add the method to BackendProvider in src/common/providers/backend-provider.ts and its Parse/Firebase implementations.

2. Expose it via RTK Query using the helpers in src/common/store/api.ts:

   // src/common/feature/<name>/api.ts
   import { nekocapApi } from "@/common/store/api";
   import { nekocapQueryMaker, nekocapMutationMaker } from "@/common/store/api";
   
   export const fooApi = nekocapApi.injectEndpoints({
     endpoints: (builder) => ({
       getFoo: nekocapQueryMaker(builder, "getFoo"),
       updateFoo: nekocapMutationMaker(builder, "updateFoo"),
     }),
   });
   
   export const { useGetFooQuery, useUpdateFooMutation } = fooApi;
   

   The "getFoo" string must match the BackendProvider method name exactly — the helpers are typed against BackendProvider<RootState>, so a typo will fail to compile.

3. Use the generated hooks in components.

Why BackendProvider?

The extension's content script can't make arbitrary network requests directly under MV3 — they're proxied through the background service worker via ChromeMessageType.ProviderRequest (see src/common/types.ts and the nekocap-extension-messaging skill). Going through BackendProvider keeps that proxy transparent. Bypassing it with fetch / axios breaks the extension silently.

Legacy direct async API calls

Files like searchCaptionsApi (in src/common/feature/search/api.ts) exist as plain async functions and predate RTK Query. They still work — don't rewrite them unprompted. New code uses RTK Query.

TanStack React Query coexistence

@tanstack/react-query is also installed (used by ServerReactQueryProvider for some web-only flows). Don't add new React Query usage in shared code — prefer RTK Query so the call works inside the extension too.

When you change X, also check Y

If you change…	Also verify…
BackendProvider method signature	All RTK Query endpoints referencing it (generics may mislead — check at the call site)
A method's return type	Components consuming the hook still typecheck
Add a method	Both Parse and Firebase implementations added (or one is intentionally a stub)

Anti-patterns

• Don't call fetch / axios / raw Parse.Cloud.run directly from a component. Do route through BackendProvider + RTK Query.
• Don't add a method to a provider implementation without adding it to the abstract BackendProvider first.
• Don't use TanStack React Query for new shared code — use RTK Query.
• Don't rename the BackendProvider method without renaming the matching nekocapQueryMaker(builder, "name") string.