# コミュニティライブラリ

> TypeScript から Nodaro のコミュニティライブラリを閲覧し、共有されたキャラクター、ロケーション、オブジェクトを自分のアカウントに複製し、お気に入りに登録し、掲載を通報します。

Source: https://nodaro.ai/ja/docs/developers/sdk/community

**`client.community`** は、コミュニティライブラリを読み取ります。これは、Nodaro チームがキュレーションする、キャラクター、ロケーション、オブジェクトの共有コレクションです。閲覧と検索、1 件の掲載の読み取り、掲載を自分のアカウントへ複製すること、お気に入りへの登録、モデレーション用の通報ができます。これらのメソッドは、[コミュニティ REST API](https://nodaro.ai/docs/developers/api/community) を呼び出します。この機能と、肖像・同意に関するルールについては、[コミュニティライブラリ](https://nodaro.ai/docs/guides/community-library)を参照してください。

コミュニティライブラリは、複数ユーザー向けのインストール環境、つまり Nodaro Cloud と Business エディションにあります。1 人用の Community エディションのインストール環境では、どの呼び出しも `NotFoundError` を返します。

## メソッド
| メソッド | 内容 |
| --- | --- |
| [`browse(params?)`](#browseparams) | 掲載を閲覧、検索します |
| [`get(slug)`](#getslug) | 1 件の掲載を読み取ります |
| [`getFull(slug)`](#getfullslug) | 1 件の掲載を、完全な公開スナップショットとともに読み取ります |
| [`favorites()`](#favorites) | お気に入りに登録した掲載を一覧表示します |
| [`clone(id, entityType)`](#cloneid-entitytype) | 掲載を自分のアカウントに複製します |
| [`favorite(id)`](#favoriteid) | お気に入りを追加または解除します |
| [`report(id, reason)`](#reportid-reason) | モデレーション用に掲載を通報します |

公開機能は SDK に含まれていません。SDK で使う個人用 API トークンと OAuth トークンでは、公開できません。

## client.community
掲載は `CommunityCard` です。そのフィールドは、API が送るとおりの snake_case です。`CommunityEntityType` は、`"character"`、`"location"`、`"object"` のいずれかです。

### browse(params?)
公開されている掲載のページと、`nextCursor` を返します（`GET /v1/community/browse`）。次のページを取得するには、`nextCursor` を `cursor` に渡してください。最後のページでは `null` になります。

```ts
browse(params?: BrowseCommunityParams): Promise<{ data: CommunityCard[]; nextCursor: string | null }>
```

<TypeTable
type={{
entityType: { type: '"character" | "location" | "object"', description: "指定した種類のアセットだけに絞ります。" },
q: { type: 'string', description: "タイトル、説明、タグを検索します。" },
category: { type: 'string', description: "指定したカテゴリーだけに絞ります。" },
sort: { type: '"newest" | "popular"', default: '"newest"', description: "並び順です。" },
cursor: { type: 'string', description: "前のページの nextCursor です。" },
limit: { type: 'number', default: '20', description: "ページのサイズで、最大 50 です。" },
}}
/>

```ts
const { data: listings, nextCursor } = await client.community.browse({
entityType: "character",
sort: "popular",
limit: 20,
})
```

### get(slug)
スラッグを指定して、1 件の掲載を読み取ります（`GET /v1/community/detail/:slug`）。

```ts
get(slug: string): Promise<{ data: CommunityCard }>
```

<TypeTable
type={{
slug: { type: 'string', required: true, description: "掲載のスラッグです。" },
}}
/>

```ts
const { data: listing } = await client.community.get("detective-mara")
```

掲載が存在しない場合や、すでに有効でない場合は、`NotFoundError` をスローします。

### getFull(slug)
1 件の掲載を、完全な公開スナップショット（詳細ページに表示されるとおりの画像、ボイス、テキスト）とともに読み取ります（`GET /v1/community/detail/:slug/full`）。

```ts
getFull(slug: string): Promise<{ data: CommunityFullDetail }>
```

<TypeTable
type={{
slug: { type: 'string', required: true, description: "掲載のスラッグです。" },
}}
/>

```ts
const { data: detail } = await client.community.getFull("detective-mara")
```

### favorites()
お気に入りに登録した掲載を一覧表示します（`GET /v1/community/favorites`）。

```ts
favorites(): Promise<{ data: CommunityCard[] }>
```

```ts
const { data: favorites } = await client.community.favorites()
```

### clone(id, entityType)
掲載を、**独立したコピー**としてあなたのライブラリに複製します（`POST /v1/community/listings/:id/clone`）。ファイルはあなた自身のストレージにコピーされるため、元の掲載が変更されたり削除されたりしても、コピーは残ります。新しいアセットの種類と ID を返します。

```ts
clone(id: string, entityType: "character" | "location" | "object"): Promise<{ entityType: string; id: string }>
```

<TypeTable
type={{
id: { type: 'string', required: true, description: "掲載の ID です。" },
entityType: { type: '"character" | "location" | "object"', required: true, description: "掲載が保持するアセットの種類です。" },
}}
/>

```ts
const { id: characterId } = await client.community.clone(listingId, "character")
const character = await client.characters.get(characterId)
```

OAuth トークンには `assets:write` スコープが必要です。ストレージが満杯の場合は、`StorageExceededError` をスローします。

### favorite(id)
掲載をお気に入りに追加します。すでに追加されている場合は削除します（`POST /v1/community/listings/:id/favorite`）。新しい状態を返します。

```ts
favorite(id: string): Promise<{ favorited: boolean }>
```

<TypeTable
type={{
id: { type: 'string', required: true, description: "掲載の ID です。" },
}}
/>

```ts
const { favorited } = await client.community.favorite(listingId)
```

### report(id, reason)
モデレーション用に掲載を通報します（`POST /v1/community/listings/:id/report`）。

```ts
report(id: string, reason: CommunityReportReason): Promise<{ ok: true }>
```

<TypeTable
type={{
id: { type: 'string', required: true, description: "掲載の ID です。" },
reason: { type: '"real_person_no_consent" | "inappropriate" | "ip_violation" | "other"', required: true, description: "real_person_no_consent：実在の人物を同意なく描写しています。inappropriate：不適切なコンテンツです。ip_violation：他者の知的財産を使用しています。other：それ以外の理由です。" },
}}
/>

```ts
await client.community.report(listingId, "real_person_no_consent")
```

## Frequently asked questions

### コミュニティのキャラクターを自分のアカウントにコピーするにはどうすればよいですか？

掲載の ID と、character のようなエンティティタイプを指定して、client.community.clone を呼び出します。コピーはあなたのものになり、元の掲載が変わっても変化しません。あなたのストレージ容量に加算されます。

### SDK でコミュニティライブラリに公開できますか？

できません。公開機能は SDK に含まれていません。SDK でできるのは、掲載の閲覧、読み取り、複製、お気に入り登録、通報です。

### 自分のインストール環境で client.community が 404 を返すのはなぜですか？

コミュニティライブラリは、Nodaro Cloud と Business エディションのインストール環境にあります。1 人用の Community エディションのインストール環境には、コミュニティ用のルートがなく、404 を返します。

### 実在の人物を同意なく描写している掲載を通報するには、どうすればよいですか？

掲載の ID と、理由 real_person_no_consent を指定して、client.community.report を呼び出します。掲載はモデレーションに送られます。