CedarCopilot/cedar-mail

/**
 * The message to surface for a failed scoped call, or `null` for a failure that
 * is not about permission.
 *
 * An administered surface passes its query error straight through, and most of
 * those errors have nothing to do with administration: `/agents/playbook`
 * defaults its `aop` param to the literal `'deals'`, so an org admin landing
 * there without `?aop=` gets "AOP with id deals not found". Rendering that in a
 * red permission box invents a problem that did not exist before this feature,
 * on a page that previously ignored the error entirely.
 *
 * Only the authority's refusals belong in that box, so only FORBIDDEN and
 * UNAUTHORIZED reach it.
 */
export function permissionErrorMessage(error: unknown): string | null {
  if (!error || typeof error !== 'object') return null;

  const code = (error as { data?: { code?: unknown }; shape?: { data?: { code?: unknown } } }).data
    ?.code;
  if (code !== 'FORBIDDEN' && code !== 'UNAUTHORIZED') return null;

  const message = (error as { message?: unknown }).message;
  return typeof message === 'string' && message.trim() ? message : null;
}