convex-tenants

Convex テナント

@djpanda/convex-authz による柔軟な認可を備えた、Convex 向けのマルチテナント組織・チーム管理です。

クイックスタート

1. convex/convex.config.ts でコンポーネントを登録します。

import { defineApp } from "convex/server";
import tenants from "@djpanda/convex-tenants/convex.config";
import authz from "@djpanda/convex-authz/convex.config";

const app = defineApp();
app.use(tenants);
app.use(authz);

export default app;

2. convex/authz.ts で認可を定義します。パッケージの TENANTS_PERMISSIONS と TENANTS_ROLES を使用してください。node_modules/@djpanda/convex-tenants/docs/quick-start.md を参照してください。

3. convex/tenants.ts でテナント API を作成します。

import { makeTenantsAPI } from "@djpanda/convex-tenants";
import { components } from "./_generated/api";
import { authz } from "./authz";

export const { listOrganizations, createOrganization, inviteMember, ... } =
  makeTenantsAPI(components.tenants, {
    authz,
    creatorRole: "owner",
    auth: async (ctx) => (await getAuthUserId(ctx)) ?? null,
    getUser: async (ctx, userId) => {
      const user = await ctx.db.get(userId);
      return user ? { name: user.name, email: user.email } : null;
    },
  });

4. React で使用します — useQuery(api.tenants.listOrganizations) を使うか、TenantsProvider と事前構築済みコンポーネントを使用してください。node_modules/@djpanda/convex-tenants/docs/react-components.md を参照してください。

主な概念

• authz は独立したコンポーネントです — authz は tenants の子としてではなく、tenants と並べて登録してください。アプリのほかの部分でも、テナント外で authz を使用できます。
• ロールは単なる文字列です — authz.ts で定義してください。デフォルトのロールは owner、admin、member です。node_modules/@djpanda/convex-tenants/docs/flexible-roles.md を参照してください。
• 構造上のオーナー — 各組織には ownerId があります。オーナーが退会する前に transferOwnership を使用してください。すべての権限チェックは authz を介して行われます。
• 組織のステータス — suspended または archived にするとミューテーションがブロックされます。再有効化できるのは、status: "active" を指定した updateOrganization のみです。

エクスポート

エクスポート	説明
TENANTS_PERMISSIONS	definePermissions() 用のデフォルト権限
TENANTS_ROLES	defineRoles() 用のデフォルトロール（owner、admin、member）
DEFAULT_TENANTS_PERMISSION_MAP	操作 → 権限のマッピング
TENANTS_REQUIRED_PERMISSIONS	権限文字列のフラットなリスト

ドキュメント（パッケージから読み込み）

ベースパス：node_modules/@djpanda/convex-tenants/docs/。ユーザーのキーワードまたはタスクに合ったドキュメントを選択し、必要なものだけを読み込みます。

ドキュメント	パス	ユーザーが次の内容について尋ねた場合に読み込みます
クイックスタート	docs/quick-start.md	セットアップ、インストール、初回統合、convex.config、authz.ts、tenants.ts、利用開始、初期設定
API リファレンス	docs/api-reference.md	関数名（listOrganizations、createOrganization、addMember、inviteMember など）、makeTenantsAPI のオプション、イベントフック、ミューテーション／クエリの引数、ページネーション（任意の paginationOpts を指定した listMembers/listTeams/listTeamMembers/listInvitations）、API シグネチャ
権限マップ	docs/permission-map.md	権限、permissionMap、操作の実行権限、操作ごとの権限、権限の上書き、ガード、操作ごとのアクセス制御
柔軟なロール	docs/flexible-roles.md	ロール、カスタムロール、owner/admin/member、creatorRole、defineRoles、構造上のオーナー、transferOwnership、ロールの追加／削除
招待システム	docs/invitation-system.md	招待、inviteMember、acceptInvitation、validateInvitationCreate、validateInvitationAccept、識別子の種類、メール／電話番号／ユーザー名、ドメイン許可リスト、招待のレート制限
React コンポーネント	docs/react-components.md	TenantsProvider、OrganizationSwitcher、MembersSection、TeamsSection、InviteMemberDialog、useOrganization、useMembers、useTeams、useOrganizationInvitations、MembersTable、TeamsGrid、AcceptInvitation、JoinByDomainSection、ページネーション対応フック
組織ストア	docs/organization-store.md	アクティブな組織、組織の切り替え、useOrganizationStore、setActiveOrganizationId、localStorage、storageKey、configureOrganizationStore

インストール

npm install @djpanda/convex-tenants @djpanda/convex-authz

React UI を使用する場合：npm install clsx tailwind-merge（任意のピア依存関係）。