### Use @animegarden/client fetchResources

Source: https://github.com/yjl9903/animegarden/blob/main/README.md

Example usage of the @animegarden/client package. Requires a built-in Fetch function; polyfill with undici or ofetch if needed.

```ts
import { fetchResources } from '@animegarden/client'

// Fetch the first page of Anime Garden mirror site
const resources = await fetchResources()

// Fetch all the resources which match some filter conditions
const sakurato = await fetchResources({ count: -1, fansub: 'ANi' })
```

--------------------------------

### Install @animegarden/client

Source: https://github.com/yjl9903/animegarden/blob/main/README.md

Installs the @animegarden/client npm package for JavaScript/TypeScript development.

```bash
npm i @animegarden/client
```

--------------------------------

### PaginationResult interface

Source: https://github.com/yjl9903/animegarden/blob/main/docs/client/pagination.md

Defines the pagination metadata returned by the HTTP API and client SDK. `page` starts at 1, `pageSize` is the requested page size, and `complete: true` only indicates no more matching resources after the current page.

```ts
interface PaginationResult {
  page: number;
  pageSize: number;
  complete: boolean;
}
```

--------------------------------

### fetchResources with pagination

Source: https://github.com/yjl9903/animegarden/blob/main/docs/client/pagination.md

Fetches a page of resources using the SDK. On success, `result.resources` contains the resources and `result.pagination` describes the page. The `complete` flag may be `false` even when the requested `count` is reached.

```ts
import { fetchResources } from '@animegarden/client';

const result = await fetchResources({ subject: 1234, page: 1, pageSize: 100 });

if (result.ok) {
  console.log(result.resources);
  console.log(result.pagination.page, result.pagination.pageSize, result.pagination.complete);
}
```

--------------------------------

### Fetch resources with curl

Source: https://github.com/yjl9903/animegarden/blob/main/README.md

Fetches the first page of resources from the Anime Garden open API. Returns JSON data.

```bash
curl "https://api.animes.garden/resources?page=1&pageSize=10"
```

--------------------------------

### Using fetchAPI with try/catch

Source: https://github.com/yjl9903/animegarden/blob/main/docs/client/error-model.md

Demonstrates the throw semantics of the low-level `fetchAPI`. Catch `AnimeGardenError` to access `code`, `retryable`, and `status`.

```typescript
try {
  const body = await fetchAPI('resources');
} catch (error) {
  if (error instanceof AnimeGardenError) {
    console.error(error.code, error.retryable, error.status);
  }
}
```

--------------------------------

### Configure MCP client for Anime Garden

Source: https://github.com/yjl9903/animegarden/blob/main/README.md

Configuration for an MCP client to connect to the Anime Garden MCP server. Place this in your MCP client's configuration file.

```json
{
  "mcpServers": {
    "animegarden": {
      "url": "https://api.animes.garden/mcp"
    }
  }
}
```

--------------------------------

### Add Anime Garden skill with npx

Source: https://github.com/yjl9903/animegarden/blob/main/README.md

Adds the Anime Garden skill to your environment using the Vercel skills CLI. Requires Node.js and npx.

```bash
npx skills add https://github.com/yjl9903/AnimeGarden --skill animegarden
```

--------------------------------

### Handling ClientResult with ok check

Source: https://github.com/yjl9903/animegarden/blob/main/docs/client/error-model.md

Shows how to handle a `ClientResult` from `fetchResourceDetail`. Check `ok` first, then handle specific error codes and log the error before returning.

```typescript
const result = await fetchResourceDetail('dmhy', providerId);

if (!result.ok) {
  if (result.code === 'NOT_FOUND') {
    // 资源不存在
  }
  console.error(result.error);
  return;
}

console.log(result.resource);
```

--------------------------------

### manager CLI 命令：pnpm manager admin patch

Source: https://github.com/yjl9903/animegarden/blob/main/docs/server/resources-write-flow.md

manager CLI 提供对应命令，需传入 provider、provider-id，可选 --subject 和 --detail，至少传一个。--url 可选指定 API 地址，默认使用 client 的线上地址。

```bash
pnpm manager admin patch <provider> <provider-id> \
  [--subject <subject-id>] [--detail] --url <api-base-url>
```

--------------------------------

### Client SDK Pagination Functions

Source: https://github.com/yjl9903/animegarden/blob/main/docs/client/pagination.md

Client SDK functions for paginated resource and collection queries.

```APIDOC
## fetchResources

### Description
Fetches a paginated list of resources using the client SDK. The result includes a `pagination` object with `page`, `pageSize`, and `complete` fields.

### Method
SDK Function

### Parameters
- **subject** (number) - Required - The subject identifier to filter resources.
- **page** (number) - Required - The page number to retrieve, starting from 1.
- **pageSize** (number) - Required - The number of resources per page.

### Response
- **ok** (boolean) - Indicates whether the request succeeded.
- **resources** (array) - The list of resources for the requested page.
- **pagination** (object) - Pagination metadata.
  - **page** (number) - The current page number.
  - **pageSize** (number) - The requested page size.
  - **complete** (boolean) - Indicates whether there are no more matching resources after this page.

### Example
```ts
import { fetchResources } from '@animegarden/client';

const result = await fetchResources({ subject: 1234, page: 1, pageSize: 100 });

if (result.ok) {
  console.log(result.resources);
  console.log(result.pagination.page, result.pagination.pageSize, result.pagination.complete);
}
```
```

```APIDOC
## fetchCollection

### Description
Fetches a collection of resources using the client SDK. The result contains an array of results, each corresponding to a filter option.

### Method
SDK Function

### Parameters
- **hash** (string) - Required - The hash identifier of the collection.

### Response
- **ok** (boolean) - Indicates whether the request succeeded.
- **results** (array) - An array of collection resource pages.
  - **resources** (array) - The list of resources for the page.
  - **pagination** (object) - Pagination metadata.
    - **page** (number) - The current page number (default 1).
    - **pageSize** (number) - The page size (default 1000).
    - **complete** (boolean) - Indicates whether there are no more matching resources after this page.
  - **filter** (object) - The resolved filter options for this page.

### Example
```ts
import { fetchCollection } from '@animegarden/client';

const result = await fetchCollection({ hash: '...' });

if (result.ok) {
  console.log(result.results);
}
```
```

--------------------------------

### Inspect production apps with Fly CLI

Source: https://github.com/yjl9903/animegarden/blob/main/docs/server/deployment-topology.md

Use these read-only Fly CLI commands to inspect the status, health checks, and logs of the three production apps. The commands target the web, server, and feed apps respectively, and the logs commands use --no-tail to avoid streaming.

```bash
fly status --app animegarden-web-production
fly status --app animegarden-server-production
fly status --app animegarden-feed-production
fly checks list --app animegarden-web-production
fly logs --app animegarden-web-production --no-tail
fly logs --app animegarden-server-production --no-tail
fly logs --app animegarden-feed-production --no-tail
```

--------------------------------

### TypeScript：通过 extensions 添加 subjectId

Source: https://github.com/yjl9903/animegarden/blob/main/docs/server/rss.md

在 getRssString() 的 item 中使用结构化 extensions 添加 animegarden:subjectId 字段，无需拼接 XML。字段名使用 prefix:localName 格式，值支持字符串、有限数字和布尔值；null/undefined 自动省略，0、false 和空字符串保留。

```typescript
extensions: { 'animegarden:subjectId': r.subjectId }
```

--------------------------------

### HTTP API Pagination Endpoints

Source: https://github.com/yjl9903/animegarden/blob/main/docs/client/pagination.md

HTTP API endpoints for paginated resource and collection queries.

```APIDOC
## GET /resources

### Description
Retrieves a paginated list of resources. The response includes a `pagination` object with `page`, `pageSize`, and `complete` fields.

### Method
GET

### Endpoint
/resources

### Parameters
#### Query Parameters
- **subject** (number) - Required - The subject identifier to filter resources.
- **page** (number) - Required - The page number to retrieve, starting from 1.
- **pageSize** (number) - Required - The number of resources per page.

### Response
#### Success Response (200)
- **resources** (array) - The list of resources for the requested page.
- **pagination** (object) - Pagination metadata.
  - **page** (number) - The current page number.
  - **pageSize** (number) - The requested page size.
  - **complete** (boolean) - Indicates whether there are no more matching resources after this page.
- **filter** (object) - The filter options used for the query.

#### Response Example
```json
{
  "resources": [],
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "complete": false
  },
  "filter": {}
}
```
```

```APIDOC
## GET /collection/{hash}

### Description
Retrieves a collection of resources based on a collection hash. The response contains an array of results, each corresponding to a filter option.

### Method
GET

### Endpoint
/collection/{hash}

### Parameters
#### Path Parameters
- **hash** (string) - Required - The hash identifier of the collection.

### Response
#### Success Response (200)
- **results** (array) - An array of collection resource pages.
  - **resources** (array) - The list of resources for the page.
  - **pagination** (object) - Pagination metadata.
    - **page** (number) - The current page number (default 1).
    - **pageSize** (number) - The page size (default 1000).
    - **complete** (boolean) - Indicates whether there are no more matching resources after this page.
  - **filter** (object) - The resolved filter options for this page.

#### Response Example
```json
{
  "results": [
    {
      "resources": [],
      "pagination": {
        "page": 1,
        "pageSize": 1000,
        "complete": false
      },
      "filter": {}
    }
  ]
}
```
```

--------------------------------

### bgmx subject calendar synchronization flow

Source: https://github.com/yjl9903/animegarden/blob/main/docs/server/telegram-push-flow.md

The sequence of operations performed during cron initialization to update subject calendars and trigger historical resource binding.

```text
cli cron
  -> sys.import()
  -> SubjectsModule.import()
  -> SubjectsModule.updateCalendar()
  -> updateCalendar(mod)
```

--------------------------------

### PATCH /admin/resources/:provider/:providerId 请求示例

Source: https://github.com/yjl9903/animegarden/blob/main/docs/server/resources-write-flow.md

管理员通过受 Bearer secret 保护的接口修正单个资源的 Bangumi subject。请求体包含 subjectId 和 detail 字段，detail 为 true 时 cron 会绕过 Redis detail cache 立即重新抓取。

```http
PATCH /admin/resources/:provider/:providerId
Content-Type: application/json

{ "subjectId": 123, "detail": true }
```

--------------------------------

### PATCH /admin/resources/:provider/:providerId

Source: https://github.com/yjl9903/animegarden/blob/main/docs/server/resources-write-flow.md

管理员通过受 Bearer secret 保护的接口修正单个资源的 Bangumi subject ID。

```APIDOC
## PATCH /admin/resources/:provider/:providerId

### Description
修正单个资源的 Bangumi subject ID。该接口受 Bearer secret 保护，仅管理员可调用。

### Method
PATCH

### Endpoint
`/admin/resources/:provider/:providerId`

### Parameters
#### Path Parameters
- **provider** (string) - Required - 资源提供方标识。
- **providerId** (string) - Required - 资源在提供方中的 ID。

#### Request Body
- **subjectId** (number) - Required - 要设置的 Bangumi subject ID。
- **detail** (boolean) - Optional - 若为 true，则 cron 会绕过已有 Redis detail cache 和详情过期时间，立即从上游重新抓取并覆盖 detail。

### Request Example
```json
{ "subjectId": 123, "detail": true }
```

### Response
#### Success Response (200)
修改成功。

#### Error Response (503)
cron 不可用时返回 503，不会降级为 server 直接写库。

### Notes
- 该修改不是永久锁定，后续资源同步可能覆盖手工设置的值。
- 接口不支持把 subject ID 清空。
```

--------------------------------

### CollectionResourcePage type

Source: https://github.com/yjl9903/animegarden/blob/main/docs/client/pagination.md

Structure of each item in the collection query result. Each `results[i]` corresponds to `filters[i]`. The collection endpoint defaults to page 1 with a maximum of 1000 items per page and does not accept `page` or `pageSize` parameters.

```ts
type CollectionResourcePage = {
  resources: Resource[];
  pagination: PaginationResult;
  filter: ResolvedFilterOptions | undefined;
};
```

--------------------------------

### XML 示例：animegarden:subjectId 元素

Source: https://github.com/yjl9903/animegarden/blob/main/docs/server/rss.md

在 RSS item 中输出 Bangumi Subject ID 的 XML 示例。该元素仅当资源已绑定 Bangumi 条目时出现，未绑定时省略。

```xml
<animegarden:subjectId>123456</animegarden:subjectId>
```

--------------------------------

### Embed Anime Garden iframe

Source: https://github.com/yjl9903/animegarden/blob/main/README.md

Embeddable iframe code for displaying Anime Garden resources on your own webpage. Copy from the resource search page.

```html
<iframe src="//animes.garden/iframe?subject=477825" width="100%" height="600" frameborder="0"></iframe>
```

--------------------------------

### ClientResult type definition

Source: https://github.com/yjl9903/animegarden/blob/main/docs/client/error-model.md

Defines the unified return type for high-level client APIs. Callers must check the `ok` property before accessing result data.

```typescript
type ClientErrorCode =
  | 'NOT_FOUND'
  | 'BAD_REQUEST'
  | 'RATE_LIMITED'
  | 'SERVER_ERROR'
  | 'NETWORK_ERROR'
  | 'TIMEOUT'
  | 'ABORTED'
  | 'INVALID_RESPONSE';

type ClientFailure = {
  ok: false;
  code: ClientErrorCode;
  error: AnimeGardenError;
};

type ClientResult<T extends object> = ({ ok: true } & T) | ClientFailure;
```