コア API 連携

プラグインは独自テーブルで完結させるのが原則です（データモデル の niyase.data）。 コアの業務データ（社員・部署）の参照が必要な場合だけ niyase.core を使います。 直接 DB を参照したり、任意のサーバへ fetch したりすることはできません。データアクセスは常に useNiyase() ブリッジ経由です。

2 種類のデータ API

プラグインが使えるデータ API は用途で 2 つに分かれます。

API	用途	ブリッジ
/nplg/:pluginId/:table	自分の plg_* テーブルの汎用 CRUD	niyase.data（データモデル）
/nplg-core/v1/:pluginId/*	コアデータ（社員・部署）の読み取り専用	niyase.core（本ページ）

/nplg という接頭辞は、廃止済みの旧称「ネットワークプラグイン」に由来する実装上の名残りです。特定の連携パターン専用ではなく、単独型・PROVIDER-CLIENT 型を問わずすべてのプラグインが自分のテーブルを読み書きする、全プラグイン共通の汎用データ API です。「ネットワーク専用の API」ではありません。

niyase.core API

const niyase = useNiyase();

await niyase.core.employees({ limit: 200 }); // { items, total } — 氏名・メール・在籍状態のみ
await niyase.core.employee(id);
await niyase.core.departments(); // { items } — id・名称・親部署のみ

niyase.core.grantedScopes; // 有効化時に承認されたスコープ（UI 出し分けに使う）

内部的にはアプリ内プロキシ /nplg-core/v1/:pluginId/* を叩きます。 返るのは最小 projectionです（社員はマイナンバー等の機微情報を含まず、氏名・メール・在籍状態のみ）。

niyase.core.workspace() について: 型定義には存在しますが、クラウドに接続されたスペース（cloud / desktop / mobile 共通の実行系）ではこの経路から提供されていません（呼ぶと NOT_FOUND になります）。スペースの基本情報（workspaceId / workspaceType / spaceId）はスコープ不要で常に niyase.context から取得できるため、スペース情報が欲しいときはそちらを使ってください。

承認スコープ（grantedScopes）

コアデータは、スペースのオーナーが有効化時に承認したスコープの範囲でのみ読めます。

スコープ	内容
core:employee:read	社員一覧・個別
core:department:read	部署

未承認の機能はサーバ側が 403 SCOPE_DENIED を返します。 niyase.core.grantedScopes を見れば、403 を待たずに UI を出し分けできます。

if (niyase.core.grantedScopes.includes("core:employee:read")) {
  // 担当者選択 UI を出す
}

現状の制約（β）: スペース設定のプラグイン管理 UI には、有効化時にスコープを個別承認する画面がまだありません。既定では grantedScopes は空になるため、いま本番でプラグインを有効化すると niyase.core.* の呼び出しは SCOPE_DENIED になります（有効化 API 自体は grantedScopes を受け付けるため、承認 UI が実装され次第そのまま有効になります）。開発中の動作確認は niyase-plugin dev（既定で core:employee:read を付与した MOCK が起動）か、テストヘルパー createTestHost({ context: { grantedScopes: [...] } }) でスコープを明示してください（リファレンス）。

読める範囲は呼び出したユーザーを超えない

grantedScopes は「このプラグインが最大どこまで読んでよいか」という天井です。実際の実行は、それを呼び出したユーザー本人の実効権限との積（ユーザー権限 ∩ grantedScopes）に絞って行われます。オーナーが有効化したプラグインでも、閲覧している人が一般社員なら一般社員が見られる範囲までしか返りません。「静的なフィールド絞り込みだけを防御にしない」設計のため、経路を増やしても越権はできません。

エラーの扱い

ブリッジのエラーは安定したコード集合（NiyaseErrorCode、リファレンス 参照）に正規化されます。コア API の呼び出しで特に出会うのは次のとおりです。

コード	意味
SCOPE_DENIED	grantedScopes が不足（403）
NOT_FOUND	対象が存在しない、またはこの経路では提供されない（404）
VALIDATION	リクエストが不正（400）
MAINTENANCE	メンテナンス中で一時的に利用不可（503）

try {
  await niyase.core.employees();
} catch (e) {
  const err = e as { code: string; status: number };
  if (err.code === "SCOPE_DENIED") {
    // grantedScopes 不足。UI 側の分岐が漏れていないか確認する
  }
}