recoupable
diff --git a/‎CLAUDE.md‎
Lines changed: 19 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎app/api/connectors/authorize/route.ts‎
Lines changed: 0 additions & 67 deletions b/‎app/api/connectors/authorize/route.ts‎
Lines changed: 0 additions & 67 deletions
diff --git a/‎app/api/connectors/route.ts‎
Lines changed: 35 additions & 75 deletions b/‎app/api/connectors/route.ts‎
Lines changed: 35 additions & 75 deletions
diff --git a/‎lib/artists/__tests__/checkAccountArtistAccess.test.ts‎
Lines changed: 81 additions & 0 deletions b/‎lib/artists/__tests__/checkAccountArtistAccess.test.ts‎
Lines changed: 81 additions & 0 deletions
diff --git a/‎lib/artists/checkAccountArtistAccess.ts‎
Lines changed: 44 additions & 0 deletions b/‎lib/artists/checkAccountArtistAccess.ts‎
Lines changed: 44 additions & 0 deletions
@@ -144,6 +144,25 @@ export async function selectTableName({
 - All API routes should have JSDoc comments
 - Run `pnpm lint` before committing
 
+### Terminology
+
+Use **"account"** terminology, never "entity" or "user". All entities in the system (individuals, artists, workspaces, organizations) are "accounts". When referring to specific types, use the specific name:
+
+- ✅ `account_id`, "artist", "workspace", "organization"
+- ❌ `entity_id`, "entity", "user"
+
+### API Response Shapes
+
+Keep response bodies **flat** — put fields at the root level, not nested inside a `data` wrapper:
+
+```typescript
+// ✅ Correct — flat response
+{ success: true, connectors: [...] }
+
+// ❌ Wrong — unnecessary nesting
+{ success: true, data: { connectors: [...] } }
+```
+
 ## Test-Driven Development (TDD)
 
 **CRITICAL: Always write tests BEFORE implementing new features or fixing bugs.**
 
@@ -1,11 +1,9 @@
 import type { NextRequest } from "next/server";
 import { NextResponse } from "next/server";
 import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
-import { getConnectors } from "@/lib/composio/connectors";
-import { disconnectConnector } from "@/lib/composio/connectors/disconnectConnector";
-import { validateDisconnectConnectorBody } from "@/lib/composio/connectors/validateDisconnectConnectorBody";
-import { verifyConnectorOwnership } from "@/lib/composio/connectors/verifyConnectorOwnership";
-import { validateAccountIdHeaders } from "@/lib/accounts/validateAccountIdHeaders";
+import { getConnectorsHandler } from "@/lib/composio/connectors/getConnectorsHandler";
+import { authorizeConnectorHandler } from "@/lib/composio/connectors/authorizeConnectorHandler";
+import { disconnectConnectorHandler } from "@/lib/composio/connectors/disconnectConnectorHandler";
 
 /**
  * OPTIONS handler for CORS preflight requests.
@@ -20,90 +18,52 @@ export async function OPTIONS() {
 /**
  * GET /api/connectors
  *
- * List all available connectors and their connection status for a user.
+ * List all available connectors and their connection status.
+ *
+ * Query params:
+ *   - account_id (optional): Entity ID for entity-specific connections (e.g., artist ID)
  *
  * Authentication: x-api-key OR Authorization Bearer token required.
  *
+ * @param request
  * @returns List of connectors with connection status
  */
-export async function GET(request: NextRequest): Promise<NextResponse> {
-  const headers = getCorsHeaders();
-
-  try {
-    const authResult = await validateAccountIdHeaders(request);
-    if (authResult instanceof NextResponse) {
-      return authResult;
-    }
-
-    const { accountId } = authResult;
-
-    const connectors = await getConnectors(accountId);
+export async function GET(request: NextRequest) {
+  return getConnectorsHandler(request);
+}
 
-    return NextResponse.json(
-      {
-        success: true,
-        data: {
-          connectors,
-        },
-      },
-      { status: 200, headers },
-    );
-  } catch (error) {
-    const message =
-      error instanceof Error ? error.message : "Failed to fetch connectors";
-    return NextResponse.json({ error: message }, { status: 500, headers });
-  }
+/**
+ * POST /api/connectors
+ *
+ * Generate an OAuth authorization URL for a specific connector.
+ *
+ * Authentication: x-api-key OR Authorization Bearer token required.
+ *
+ * Request body:
+ * - connector: The connector slug, e.g., "googlesheets" or "tiktok" (required)
+ * - callback_url: Optional custom callback URL after OAuth
+ * - account_id: Optional account ID for account-specific connections
+ *
+ * @param request
+ * @returns The redirect URL for OAuth authorization
+ */
+export async function POST(request: NextRequest) {
+  return authorizeConnectorHandler(request);
 }
 
 /**
  * DELETE /api/connectors
  *
  * Disconnect a connected account from Composio.
  *
+ * Body:
+ * - connected_account_id (required): The connected account ID to disconnect
+ * - account_id (optional): Entity ID for ownership verification (e.g., artist ID)
+ *
  * Authentication: x-api-key OR Authorization Bearer token required.
  *
- * Body: { connected_account_id: string }
+ * @param request
  */
-export async function DELETE(request: NextRequest): Promise<NextResponse> {
-  const headers = getCorsHeaders();
-
-  try {
-    const authResult = await validateAccountIdHeaders(request);
-    if (authResult instanceof NextResponse) {
-      return authResult;
-    }
-
-    const { accountId } = authResult;
-    const body = await request.json();
-
-    const validated = validateDisconnectConnectorBody(body);
-    if (validated instanceof NextResponse) {
-      return validated;
-    }
-
-    const { connected_account_id } = validated;
-
-    // Verify the connected account belongs to the authenticated user
-    const isOwner = await verifyConnectorOwnership(accountId, connected_account_id);
-    if (!isOwner) {
-      return NextResponse.json(
-        { error: "Connected account not found or does not belong to this user" },
-        { status: 403, headers }
-      );
-    }
-
-    const result = await disconnectConnector(connected_account_id);
-
-    return NextResponse.json(
-      {
-        success: true,
-        data: result,
-      },
-      { status: 200, headers },
-    );
-  } catch (error) {
-    const message =
-      error instanceof Error ? error.message : "Failed to disconnect connector";
-    return NextResponse.json({ error: message }, { status: 500, headers });
-  }
+export async function DELETE(request: NextRequest) {
+  return disconnectConnectorHandler(request);
 }
@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { checkAccountArtistAccess } from "../checkAccountArtistAccess";
+
+vi.mock("@/lib/supabase/account_artist_ids/selectAccountArtistId", () => ({
+  selectAccountArtistId: vi.fn(),
+}));
+
+vi.mock("@/lib/supabase/artist_organization_ids/selectArtistOrganizationIds", () => ({
+  selectArtistOrganizationIds: vi.fn(),
+}));
+
+vi.mock("@/lib/supabase/account_organization_ids/selectAccountOrganizationIds", () => ({
+  selectAccountOrganizationIds: vi.fn(),
+}));
+
+import { selectAccountArtistId } from "@/lib/supabase/account_artist_ids/selectAccountArtistId";
+import { selectArtistOrganizationIds } from "@/lib/supabase/artist_organization_ids/selectArtistOrganizationIds";
+import { selectAccountOrganizationIds } from "@/lib/supabase/account_organization_ids/selectAccountOrganizationIds";
+
+describe("checkAccountArtistAccess", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return true when account has direct access to artist", async () => {
+    vi.mocked(selectAccountArtistId).mockResolvedValue({ artist_id: "artist-123" });
+
+    const result = await checkAccountArtistAccess("account-123", "artist-123");
+
+    expect(selectAccountArtistId).toHaveBeenCalledWith("account-123", "artist-123");
+    expect(result).toBe(true);
+    expect(selectArtistOrganizationIds).not.toHaveBeenCalled();
+  });
+
+  it("should return true when account and artist share an organization", async () => {
+    vi.mocked(selectAccountArtistId).mockResolvedValue(null);
+    vi.mocked(selectArtistOrganizationIds).mockResolvedValue([
+      { organization_id: "org-1" },
+    ]);
+    vi.mocked(selectAccountOrganizationIds).mockResolvedValue([
+      { organization_id: "org-1" },
+    ]);
+
+    const result = await checkAccountArtistAccess("account-123", "artist-456");
+
+    expect(selectArtistOrganizationIds).toHaveBeenCalledWith("artist-456");
+    expect(selectAccountOrganizationIds).toHaveBeenCalledWith("account-123", ["org-1"]);
+    expect(result).toBe(true);
+  });
+
+  it("should return false when artist org lookup errors (fail closed)", async () => {
+    vi.mocked(selectAccountArtistId).mockResolvedValue(null);
+    vi.mocked(selectArtistOrganizationIds).mockResolvedValue(null);
+
+    const result = await checkAccountArtistAccess("account-123", "artist-123");
+
+    expect(result).toBe(false);
+  });
+
+  it("should return false when account has no access", async () => {
+    vi.mocked(selectAccountArtistId).mockResolvedValue(null);
+    vi.mocked(selectArtistOrganizationIds).mockResolvedValue([]);
+
+    const result = await checkAccountArtistAccess("account-123", "artist-456");
+
+    expect(result).toBe(false);
+    expect(selectAccountOrganizationIds).not.toHaveBeenCalled();
+  });
+
+  it("should return false when account org lookup errors (fail closed)", async () => {
+    vi.mocked(selectAccountArtistId).mockResolvedValue(null);
+    vi.mocked(selectArtistOrganizationIds).mockResolvedValue([
+      { organization_id: "org-1" },
+    ]);
+    vi.mocked(selectAccountOrganizationIds).mockResolvedValue(null);
+
+    const result = await checkAccountArtistAccess("account-123", "artist-456");
+
+    expect(result).toBe(false);
+  });
+});
@@ -0,0 +1,44 @@
+import { selectAccountArtistId } from "@/lib/supabase/account_artist_ids/selectAccountArtistId";
+import { selectArtistOrganizationIds } from "@/lib/supabase/artist_organization_ids/selectArtistOrganizationIds";
+import { selectAccountOrganizationIds } from "@/lib/supabase/account_organization_ids/selectAccountOrganizationIds";
+
+/**
+ * Check if an account has access to a specific artist.
+ *
+ * Access is granted if:
+ * 1. Account has direct access via account_artist_ids, OR
+ * 2. Account and artist share an organization
+ *
+ * Fails closed: returns false on any database error to deny access safely.
+ *
+ * @param accountId - The account ID to check
+ * @param artistId - The artist ID to check access for
+ * @returns true if the account has access to the artist, false otherwise
+ */
+export async function checkAccountArtistAccess(
+  accountId: string,
+  artistId: string,
+): Promise<boolean> {
+  // 1. Check direct access via account_artist_ids
+  const directAccess = await selectAccountArtistId(accountId, artistId);
+
+  if (directAccess) return true;
+
+  // 2. Check organization access: account and artist share an org
+  const artistOrgs = await selectArtistOrganizationIds(artistId);
+
+  if (!artistOrgs) return false; // Fail closed on error
+
+  if (!artistOrgs.length) return false;
+
+  const orgIds = artistOrgs
+    .map((o) => o.organization_id)
+    .filter((id): id is string => Boolean(id));
+  if (!orgIds.length) return false;
+
+  const userOrgAccess = await selectAccountOrganizationIds(accountId, orgIds);
+
+  if (!userOrgAccess) return false; // Fail closed on error
+
+  return !!userOrgAccess.length;
+}