feat: render the server's effective API operation set (#3391 PR-4) (#2823)

The frontend consumes the per-object effective API operation set the server resolves (/me/permissions apiOperations, framework #3391) — never the raw apiMethods — so CRUD/Import/Export buttons match what the server admits, and a 405 import refusal shows a dedicated message instead of a silent fallback.

- core: resolveCrudAffordances(obj, effectiveApiOperations?) optional 2nd-arg intersection
- permissions: /me/permissions apiOperations + getObjectApiOperations + check(import→allowCreate, export→allowRead)
- app-shell ObjectView: Import affordance ∩ effective (identity-import bypass unaffected)
- plugin-list/plugin-grid: Export button+handler gate on effective export; plugin-grid gains @object-ui/permissions dep
- plugin-grid ImportWizard: isImportNotAllowed (405) at all catch sites → dedicated grid.import.notAllowed message, no fallback

Backward-compatible: missing effective set preserves current default-allow behavior.

Author: os-zhuang

.changeset/effective-api-operations-ui.md

@@ -0,0 +1,41 @@
+---
+"@object-ui/core": minor
+"@object-ui/permissions": minor
+"@object-ui/plugin-grid": minor
+"@object-ui/plugin-list": minor
+"@object-ui/app-shell": minor
+"@object-ui/i18n": minor
+---
+
+feat: render the server's effective API operation set (#3391 PR-4)
+
+The frontend now consumes the per-object **effective API operation set** the
+server resolves (from `/me/permissions` `apiOperations`, framework #3391) —
+never the raw `apiMethods` — so Import/Export/New/Edit/Delete buttons match what
+the server will actually admit, and a 405 import refusal shows a dedicated
+message instead of silently falling back.
+
+- **core** `resolveCrudAffordances(obj, effectiveApiOperations?)` — new optional
+  second argument intersects each affordance bit with its API operation
+  (create/import→create/import, edit→update, delete→delete, exportCsv→export).
+  Omitting it (old backend / no effective set) leaves affordances unchanged.
+- **permissions** — `/me/permissions` response carries per-object
+  `apiOperations`; `PermissionContextValue.getObjectApiOperations(object)`
+  exposes it (undefined when absent → callers keep current behavior); `check()`
+  maps `import→allowCreate`, `export→allowRead`.
+- **app-shell** `ObjectView` intersects its toolbar affordances with the object's
+  effective operations (Import); the platform-admin identity-import bypass is
+  unaffected.
+- **plugin-list** `ListView` / **plugin-grid** `ObjectGrid` gate the Export
+  button (and export handler) on effective `export`; `plugin-grid` gains the
+  `@object-ui/permissions` workspace dependency.
+- **plugin-grid** `ImportWizard` — a 405 / `OBJECT_API_METHOD_NOT_ALLOWED`
+  import refusal is detected by a new `isImportNotAllowed` predicate at every
+  catch site (async, sync, dry-run) and STOPS with a dedicated
+  `grid.import.notAllowed` message (10 locales + fallback dict) — it never falls
+  back to the sync/legacy path (which 405s too), distinct from the 404
+  route-absent fallback.
+
+Backward-compatible: a missing effective set (unrestricted object, older
+backend, or no permission provider) preserves the current default-allow
+behavior everywhere.

packages/app-shell/src/views/ObjectView.tsx

@@ -350,7 +350,7 @@ function ObjectViewInner({ dataSource, objects, onEdit, externalRefreshKey }: an
     // Admin users automatically get design tools (no toggle needed)
     const { user, activeOrganization } = useAuth();
     const isAdmin = useIsWorkspaceAdmin();
-    const { can } = usePermissions();
+    const { can, getObjectApiOperations } = usePermissions();
 
     // Get Object Definition. The outer ObjectView wrapper already guards the
     // missing-object case, so this always resolves while this component is
@@ -405,9 +405,14 @@ function ObjectViewInner({ dataSource, objects, onEdit, externalRefreshKey }: an
     // hide the lot — those flows go through purpose-built actions on the
     // source record (e.g. "Submit for Approval" on an Opportunity creates
     // an `sys_approval_request`).  Permissions still gate the buttons.
+    // [#3391] Intersect the bucket affordances with the server's effective API
+    // operation set for this object (from /me/permissions apiOperations), so the
+    // toolbar never offers Import/Export/New/Edit/Delete the server would 405.
+    // `undefined` (unrestricted object / old backend) leaves affordances as-is.
+    // The identity-import bypass below is independent of `affordances.import`.
     const affordances = useMemo(
-      () => resolveCrudAffordances(objectDef as any),
-      [objectDef],
+      () => resolveCrudAffordances(objectDef as any, getObjectApiOperations(objectDef.name)),
+      [objectDef, getObjectApiOperations],
     );
 
     // Propagate externally-triggered refreshes (e.g. global ModalForm submit)

packages/core/src/utils/managedBy.test.ts

@@ -143,3 +143,46 @@ describe('MANAGED_BY_BUCKETS', () => {
     expect(MANAGED_BY_BUCKETS).toEqual(['platform', 'config', 'system', 'engine-owned', 'append-only', 'better-auth']);
   });
 });
+
+describe('resolveCrudAffordances — effective API operations (#3391)', () => {
+  it('undefined effective set → affordances unchanged (backward-compatible)', () => {
+    const platform = { managedBy: 'platform' };
+    expect(resolveCrudAffordances(platform)).toEqual(resolveCrudAffordances(platform, undefined));
+    expect(resolveCrudAffordances(platform, undefined)).toEqual({
+      create: true, import: true, edit: true, delete: true, exportCsv: true,
+    });
+  });
+
+  it('ANDs each affordance bit with its API operation (create/import→create/import, edit→update, delete→delete, exportCsv→export)', () => {
+    // A full-CRUD platform object whose server effective set is read-only + list-derived.
+    const aff = resolveCrudAffordances({ managedBy: 'platform' }, ['get', 'list', 'export']);
+    expect(aff).toMatchObject({
+      create: false, import: false, edit: false, delete: false, exportCsv: true,
+    });
+  });
+
+  it('keeps a bit only when BOTH the affordance and the effective op allow it', () => {
+    // create+update present → create/import/edit survive; no delete/list → delete/export drop.
+    const aff = resolveCrudAffordances({ managedBy: 'platform' }, ['create', 'update', 'import']);
+    expect(aff.create).toBe(true);
+    expect(aff.edit).toBe(true);
+    expect(aff.import).toBe(true);
+    expect(aff.delete).toBe(false);
+    expect(aff.exportCsv).toBe(false);
+  });
+
+  it('empty effective set → all bits off (deny-all)', () => {
+    expect(resolveCrudAffordances({ managedBy: 'platform' }, [])).toMatchObject({
+      create: false, import: false, edit: false, delete: false, exportCsv: false,
+    });
+  });
+
+  it('never re-enables a bit the bucket/userActions already denied', () => {
+    // config bucket has no import; even if the server would allow import, the
+    // UI-intent axis keeps it off (intersection, never union).
+    const aff = resolveCrudAffordances({ managedBy: 'config' }, ['create', 'update', 'delete', 'import', 'export']);
+    expect(aff.import).toBe(false); // config never imports
+    expect(aff.create).toBe(true);
+    expect(aff.exportCsv).toBe(true);
+  });
+});

packages/core/src/utils/managedBy.ts

@@ -112,8 +112,36 @@ export function userActionPredicates(
   return normalizeUserAction(v, false).predicates;
 }
 
-/** Resolve the effective CRUD affordances for an object schema. */
-export function resolveCrudAffordances(obj: SchemaLike | null | undefined): CrudAffordances {
+/**
+ * The affordance-bit → server API-operation mapping used to intersect the
+ * UI-intent affordances with the server's effective API operation set (#3391).
+ * This is the objectui end of the framework's `API_METHOD_DERIVATION` contract:
+ * the button predicate is `affordance(op) ∧ effective.api(op)`.
+ */
+const AFFORDANCE_TO_API_OPERATION = {
+  create: 'create',
+  import: 'import',
+  edit: 'update',
+  delete: 'delete',
+  exportCsv: 'export',
+} as const;
+
+/**
+ * Resolve the effective CRUD affordances for an object schema.
+ *
+ * @param obj The object schema (managedBy bucket + userActions overrides).
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (from `/me/permissions` `apiOperations`, #3391). When
+ *   provided, each affordance bit is ANDed with the corresponding API operation
+ *   (create/import→create/import, edit→update, delete→delete, exportCsv→export),
+ *   so the UI never shows a button the server would 405. Passing `undefined`
+ *   (old backend / no effective set) leaves the affordances untouched —
+ *   backward-compatible. An empty array means "expose nothing" → all bits off.
+ */
+export function resolveCrudAffordances(
+  obj: SchemaLike | null | undefined,
+  effectiveApiOperations?: readonly string[] | null,
+): CrudAffordances {
   const bucket = (obj?.managedBy as ManagedByBucket | undefined) ?? 'platform';
   const base = DEFAULTS[bucket] ?? DEFAULTS.platform;
   const o = obj?.userActions ?? {};
@@ -128,6 +156,17 @@ export function resolveCrudAffordances(obj: SchemaLike | null | undefined): Crud
   };
   if (edit.predicates) out.editPredicates = edit.predicates;
   if (del.predicates) out.deletePredicates = del.predicates;
+  // [#3391] Intersect with the server's effective API operations when present.
+  // The frontend consumes the effective set the server hands down; it never
+  // reads the raw `apiMethods` nor re-derives.
+  if (Array.isArray(effectiveApiOperations)) {
+    const eff = new Set(effectiveApiOperations);
+    for (const [bit, op] of Object.entries(AFFORDANCE_TO_API_OPERATION) as Array<
+      [keyof typeof AFFORDANCE_TO_API_OPERATION, string]
+    >) {
+      if (out[bit] && !eff.has(op)) out[bit] = false;
+    }
+  }
   return out;
 }
 

packages/i18n/src/locales/ar.ts

@@ -198,6 +198,7 @@ const ar = {
     },
     import: {
       title: "استيراد {{object}}",
+      notAllowed: "هذا الكائن غير متاح للاستيراد.",
       stepUpload: "رفع",
       stepMapping: "تعيين",
       stepPreview: "معاينة",

packages/i18n/src/locales/de.ts

@@ -198,6 +198,7 @@ const de = {
     },
     import: {
       title: "{{object}} importieren",
+      notAllowed: "Dieses Objekt ist nicht für den Import freigegeben.",
       stepUpload: "Hochladen",
       stepMapping: "Zuordnung",
       stepPreview: "Vorschau",

packages/i18n/src/locales/en.ts

@@ -223,6 +223,7 @@ const en = {
     },
     import: {
       title: 'Import {{object}}',
+      notAllowed: 'This object is not open for import.',
       stepUpload: 'Upload',
       stepMapping: 'Mapping',
       stepPreview: 'Preview',

packages/i18n/src/locales/es.ts

@@ -198,6 +198,7 @@ const es = {
     },
     import: {
       title: "Importar {{object}}",
+      notAllowed: "Este objeto no está habilitado para la importación.",
       stepUpload: "Cargar",
       stepMapping: "Asignación",
       stepPreview: "Vista previa",

packages/i18n/src/locales/fr.ts

@@ -198,6 +198,7 @@ const fr = {
     },
     import: {
       title: "Importer {{object}}",
+      notAllowed: "Cet objet n'est pas ouvert à l'import.",
       stepUpload: "Télécharger",
       stepMapping: "Correspondance",
       stepPreview: "Aperçu",

packages/i18n/src/locales/ja.ts

@@ -198,6 +198,7 @@ const ja = {
     },
     import: {
       title: "{{object}}をインポート",
+      notAllowed: "このオブジェクトはインポートに対応していません。",
       stepUpload: "アップロード",
       stepMapping: "マッピング",
       stepPreview: "プレビュー",