@mediacubeco/expo-template-fsd 2.3.0 → 2.4.0

package/.claude/skills/api/references/client/overview.md

@@ -0,0 +1,106 @@
+# API infrastructure (shared, not per-domain)
+
+These pieces exist **once** in the API lib. A new domain plugs into them — it
+does not regenerate them. Read this so the per-domain code you generate fits the
+machine around it, and so you know which shared files to touch.
+
+## The transport: `ApiInstance`
+
+Every repository extends `ApiInstance`, which owns `fetch`. Two things matter for
+generated repositories:
+
+- **Transport options.** Every request accepts `options?: { signal?, timeout? }`.
+  The domain `Config` types carry this through `ApiConfig<Config>`
+  (`Config & { options?: ApiInstanceOptions }`). Repository methods split it out,
+  mapping the camelCase fields into snake_case `params`/`body` by hand:
+  `async getX({ isActive, options })` → `this.get('/', { params: { is_active: isActive }, options })`.
+  This is why the `options`/`params` separation in the repository is mandatory —
+  forget it and an `AbortSignal` leaks into the query string.
+- **Empty/error handling is centralized.** A 204 or empty body returns
+  `undefined`; non-2xx throws an `Error` whose `cause` is the `Response` (so the
+  status survives). The repository does not try/catch — errors propagate to React
+  Query. Repositories return the raw success payload unchanged; shaping into
+  `{ list }`/`{ item }` and the camelCase conversion both happen in the hook's `select`.
+
+## Errors are handled in one place: `QueryCache.onError`
+
+The `QueryClient` is built with a `QueryCache` whose `onError` is the single
+funnel for every failed query (a future toast/Sentry hook lives here). It reads
+`query.meta.silent` to skip noise. Consequence for generated code: **hooks and
+repositories never log or swallow errors** — they let them throw. Per-query
+suppression is `meta: { silent: true }`, nothing more.
+
+`retry` skips 4xx (client errors don't heal on repeat) and retries the rest up to
+twice, reading the status from the error's `cause`.
+
+```ts
+const queryClient = new QueryClient({
+  queryCache: new QueryCache({
+    onError: (error, query) => {
+      if (query.meta?.silent) {
+        return
+      }
+
+      ErrorHandler.capture(error, { signal: 'query', message: JSON.stringify(query.queryKey) })
+    },
+  }),
+  defaultOptions: {
+    queries: {
+      retry: (failureCount, error) => {
+        const status = getErrorStatus(error)
+
+        if (status !== undefined && status >= 400 && status < 500) {
+          return false
+        }
+
+        return failureCount < MAX_RETRY_COUNT
+      },
+    },
+  },
+})
+```
+
+## Typed `meta`
+
+`meta` is typed globally (module augmentation of `Register` in a root
+`react-query.d.ts`), so `meta: { persist: true }` and `meta: { silent: true }`
+are checked, not free-form:
+
+```ts
+type ApiQueryMeta = {
+  persist?: boolean
+  silent?: boolean
+}
+
+declare module '@tanstack/react-query' {
+  interface Register {
+    queryMeta: ApiQueryMeta
+    mutationMeta: ApiQueryMeta
+  }
+}
+```
+
+- `persist: true` — the query is whitelisted for AsyncStorage/MMKV persistence
+  (survives restarts). Only set it on non-sensitive, slow-changing data.
+- `silent: true` — `onError` ignores this query.
+
+## Persistence and freshness
+
+- Persistence is opt-in per query via `meta: { persist: true }`. Never persist
+  user-private data — the store is not encrypted.
+- `staleTime` is opt-in. Slow-changing reference data (countries, languages,
+  labels) uses `staleTime: STALE_TIME` so it is not refetched on every mount.
+  Always-fresh data (status, feature flags, anything user-specific) omits it.
+
+## Online + focus
+
+`focusManager` (app foreground/background) and `onlineManager` (network via
+`expo-network`) are wired once at module scope so `refetchOnReconnect` and
+pause-while-offline work in React Native. Nothing per-domain here.
+
+## What a NEW domain must touch in shared files
+
+1. `api.ts` — register the repository singleton: `static postRepository = new PostRepository('/posts')` (URN is the plural route).
+2. `constants/index.ts` — add the base query key: `POSTS: 'posts'` in `QUERY_KEYS`.
+3. Barrels — `resources/index.ts`, `entities/index.ts`, `repositories/index.ts`, `queries/index.ts`, `hooks/index.ts` each get one re-export line (alphabetical).
+4. Prefetch (optional) — if the domain is reference data shown on first screens, add `queryClient.prefetchQuery(postQueries.list())` to the startup prefetch.

package/.claude/skills/api/references/hooks/index.ts

@@ -0,0 +1,3 @@
+export * from './use-api-health'
+export * from './use-api-post'
+export * from './use-api-posts'

package/.claude/skills/api/references/hooks/use-api-health.ts

@@ -0,0 +1,25 @@
+import { useQuery } from '@tanstack/react-query'
+import { healthQueries } from '../queries'
+import { type GetHealthResponse } from '../repositories'
+
+// map-case: every field is optional, so the default answer is the empty wire object
+const PLACEHOLDER_DATA: GetHealthResponse = {}
+
+const selectHealth = (data: GetHealthResponse) => {
+  return {
+    item: {
+      maintenance: data.maintenance,
+      startAt: data.start_at,
+    },
+  }
+}
+
+const useApiHealth = () => {
+  return useQuery({
+    ...healthQueries.detail(),
+    placeholderData: PLACEHOLDER_DATA,
+    select: selectHealth,
+  })
+}
+
+export { useApiHealth }

package/.claude/skills/api/references/hooks/use-api-post.ts

@@ -0,0 +1,46 @@
+import { useMutation, useQuery } from '@tanstack/react-query'
+import { Api } from '../api'
+import { queryClient } from '../api.client'
+import { PostEntity } from '../entities'
+import { postQueries } from '../queries'
+import {
+  type CreatePostConfig,
+  type CreatePostResponse,
+  type GetPostResponse,
+} from '../repositories'
+
+const PLACEHOLDER_DATA: GetPostResponse = {
+  data: { is_skeleton: true },
+}
+
+const selectPost = (data: GetPostResponse) => {
+  return {
+    item: new PostEntity(data.data),
+  }
+}
+
+const selectPostCreate = (data: CreatePostResponse) => {
+  return {
+    item: new PostEntity(data.data),
+  }
+}
+
+const useApiPost = (id: PostEntity['id']) => {
+  return useQuery({
+    ...postQueries.detail(id),
+    placeholderData: PLACEHOLDER_DATA,
+    select: selectPost,
+  })
+}
+
+const useApiPostCreate = () => {
+  return useMutation({
+    mutationFn: async (config: CreatePostConfig) =>
+      selectPostCreate(await Api.postRepository.createPost(config)),
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: postQueries.key })
+    },
+  })
+}
+
+export { useApiPost, useApiPostCreate }

package/.claude/skills/api/references/hooks/use-api-posts.ts

@@ -0,0 +1,24 @@
+import { useQuery } from '@tanstack/react-query'
+import { PostEntity } from '../entities'
+import { postQueries } from '../queries'
+import { type GetPostListResponse } from '../repositories'
+
+const INITIAL_DATA: GetPostListResponse = {
+  data: [{ is_skeleton: true }, { is_skeleton: true }, { is_skeleton: true }],
+}
+
+const selectPostList = (data: GetPostListResponse) => {
+  return {
+    list: data.data?.map((post) => new PostEntity(post)) ?? [],
+  }
+}
+
+const useApiPosts = () => {
+  return useQuery({
+    ...postQueries.list(),
+    initialData: INITIAL_DATA,
+    select: selectPostList,
+  })
+}
+
+export { useApiPosts }

package/.claude/skills/api/references/mock/post.mock.ts

@@ -0,0 +1,29 @@
+import { PostEntity } from '../entities'
+import { type PostResource } from '../resources'
+
+const POST_RESOURCE_LIST: PostResource[] = [
+  {
+    id: '1',
+    title: 'Getting started with the API layer',
+    description: 'A short walkthrough of resources, entities and queries.',
+    number_of_likes: 12,
+    number_of_comments: 3,
+  },
+  {
+    id: '2',
+    title: 'Caching reference data',
+    description: 'When to set staleTime and persist on a query.',
+    number_of_likes: 47,
+    number_of_comments: 8,
+  },
+]
+
+const getPostMockResourceList = () => {
+  return JSON.parse(JSON.stringify(POST_RESOURCE_LIST)) as PostResource[]
+}
+
+const getPostMockEntityList = () => {
+  return getPostMockResourceList().map((post) => new PostEntity(post))
+}
+
+export { getPostMockResourceList, getPostMockEntityList }

package/.claude/skills/{generate-api-model/references → api/references/model}/entities/common.ts

@@ -20,8 +20,11 @@ class BaseEntity<Resource extends BaseResource> {
     this.updatedAt = resource?.updated_at ?? new Date()
   }
 
-  get isPending() {
-    return this.resource?.is_pending ?? this.context?.is_pending ?? false
+  /**
+   * Флаг определяющий, что данные еще не подгружены
+   */
+  get isSkeleton() {
+    return this.resource?.is_skeleton ?? this.context?.is_skeleton ?? false
   }
 }
 

package/.claude/skills/api/references/model/resources/common.ts

@@ -0,0 +1,9 @@
+type BaseResource = {
+  id?: string
+  created_at?: Date
+  updated_at?: Date
+  /** Флаг определяющий, что данные еще не подгружены **/
+  is_skeleton?: boolean
+}
+
+export type { BaseResource }

package/.claude/skills/api/references/queries/health.ts

@@ -0,0 +1,14 @@
+import { queryOptions } from '@tanstack/react-query'
+import { Api } from '../api'
+import { QUERY_KEYS } from '../constants'
+
+const healthQueries = {
+  key: [QUERY_KEYS.HEALTH] as const,
+  detail: () =>
+    queryOptions({
+      queryKey: healthQueries.key,
+      queryFn: (options) => Api.healthRepository.getHealth({ options }),
+    }),
+}
+
+export { healthQueries }

package/.claude/skills/api/references/queries/index.ts

@@ -0,0 +1,2 @@
+export * from './health'
+export * from './post'

package/.claude/skills/api/references/queries/post.ts

@@ -0,0 +1,23 @@
+import { queryOptions } from '@tanstack/react-query'
+import { Api } from '../api'
+import { QUERY_KEYS, STALE_TIME } from '../constants'
+import { type PostEntity } from '../entities'
+import { type GetPostListConfig } from '../repositories'
+
+const postQueries = {
+  key: [QUERY_KEYS.POSTS] as const,
+  list: (config: GetPostListConfig = {}) =>
+    queryOptions({
+      queryKey: [...postQueries.key, config] as const,
+      queryFn: (options) => Api.postRepository.getPostList({ ...config, options }),
+      staleTime: STALE_TIME,
+      meta: { persist: true },
+    }),
+  detail: (id: PostEntity['id']) =>
+    queryOptions({
+      queryKey: [...postQueries.key, id] as const,
+      queryFn: (options) => Api.postRepository.getPost({ id, options }),
+    }),
+}
+
+export { postQueries }

package/.claude/skills/api/references/repository/health/health.ts

@@ -0,0 +1,11 @@
+import { ApiInstance } from '../../models'
+import { type GetHealthApiConfig, type GetHealthApiResponse } from './health.types'
+
+class HealthRepository extends ApiInstance {
+  // no auth
+  async getHealth({ options }: GetHealthApiConfig) {
+    return await this.get<GetHealthApiResponse>('/', { options })
+  }
+}
+
+export default HealthRepository

package/.claude/skills/api/references/repository/health/health.types.ts

@@ -0,0 +1,25 @@
+import { type ApiConfig, type ApiResponse } from '../../api.types'
+
+type GetHealthConfig = {}
+
+type GetHealthResponse = {
+  maintenance?: boolean
+  start_at?: Date
+}
+
+// config
+
+type GetHealthApiConfig = ApiConfig<GetHealthConfig>
+
+// response
+
+type GetHealthApiResponse = ApiResponse<GetHealthResponse>
+
+export type {
+  GetHealthConfig,
+  GetHealthResponse,
+  // config
+  GetHealthApiConfig,
+  // response
+  GetHealthApiResponse,
+}

package/.claude/skills/api/references/repository/health/index.ts

@@ -0,0 +1,2 @@
+export { default as HealthRepository } from './health'
+export { type GetHealthConfig, type GetHealthResponse } from './health.types'

package/.claude/skills/api/references/repository/post/index.ts

@@ -0,0 +1,9 @@
+export { default as PostRepository } from './post'
+export {
+  type CreatePostConfig,
+  type CreatePostResponse,
+  type GetPostConfig,
+  type GetPostListConfig,
+  type GetPostListResponse,
+  type GetPostResponse,
+} from './post.types'

package/.claude/skills/api/references/repository/post/post.ts

@@ -0,0 +1,34 @@
+import { ApiInstance } from '../../models'
+import {
+  type CreatePostApiConfig,
+  type CreatePostApiResponse,
+  type GetPostApiConfig,
+  type GetPostApiResponse,
+  type GetPostListApiConfig,
+  type GetPostListApiResponse,
+} from './post.types'
+
+class PostRepository extends ApiInstance {
+  // no auth
+  async getPostList({ isPublished, options }: GetPostListApiConfig) {
+    return await this.get<GetPostListApiResponse>('/', {
+      params: { is_published: isPublished },
+      options,
+    })
+  }
+
+  // auth
+  async getPost({ id, options }: GetPostApiConfig) {
+    return await this.get<GetPostApiResponse>(`/${id}`, { options })
+  }
+
+  // auth
+  async createPost({ title, description, options }: CreatePostApiConfig) {
+    return await this.post<CreatePostApiResponse>('/', {
+      body: { title, description },
+      options,
+    })
+  }
+}
+
+export default PostRepository

package/.claude/skills/api/references/repository/post/post.types.ts

@@ -0,0 +1,61 @@
+import { type ApiConfig, type ApiResponse } from '../../api.types'
+import { type PostEntity } from '../../entities'
+import { type PostResource } from '../../resources'
+
+type GetPostListConfig = {
+  isPublished?: boolean
+}
+
+type GetPostConfig = {
+  id: PostEntity['id']
+}
+
+type CreatePostConfig = {
+  title: string
+  description?: string
+}
+
+type GetPostListResponse = {
+  data?: PostResource[]
+}
+
+type GetPostResponse = {
+  data?: PostResource
+}
+
+type CreatePostResponse = {
+  data?: PostResource
+}
+
+// config
+
+type GetPostListApiConfig = ApiConfig<GetPostListConfig>
+
+type GetPostApiConfig = ApiConfig<GetPostConfig>
+
+type CreatePostApiConfig = ApiConfig<CreatePostConfig>
+
+// response
+
+type GetPostListApiResponse = ApiResponse<GetPostListResponse>
+
+type GetPostApiResponse = ApiResponse<GetPostResponse>
+
+type CreatePostApiResponse = ApiResponse<CreatePostResponse>
+
+export type {
+  GetPostListConfig,
+  GetPostConfig,
+  CreatePostConfig,
+  GetPostListResponse,
+  GetPostResponse,
+  CreatePostResponse,
+  // config
+  GetPostListApiConfig,
+  GetPostApiConfig,
+  CreatePostApiConfig,
+  // response
+  GetPostListApiResponse,
+  GetPostApiResponse,
+  CreatePostApiResponse,
+}