@manta-eu/client 0.1.9 → 0.1.10

package/src/shared/questionnaire.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+
+export const requestUserInputToolName = "requestUserInput";
+export const requestUserInputToolPartType = `tool-${requestUserInputToolName}` as const;
+
+const questionnaireOptionSchema = z.object({
+  label: z.string().trim().min(1).max(40).describe("Short user-facing option label"),
+  description: z.string().trim().min(1).max(120).describe("One sentence explaining the option"),
+  recommended: z.boolean().optional().describe("Whether this is the recommended option"),
+});
+
+const questionnaireQuestionSchema = z
+  .object({
+    id: z
+      .string()
+      .trim()
+      .regex(/^[a-z][a-z0-9_]*$/)
+      .describe("Stable snake_case identifier for mapping the answer"),
+    header: z.string().trim().min(1).max(24).describe("Short heading of one to four words"),
+    question: z.string().trim().min(1).max(200).describe("Single-sentence question shown to the user"),
+    options: z
+      .array(questionnaireOptionSchema)
+      .min(1)
+      .max(4)
+      .describe("One to four mutually exclusive predefined answers"),
+  })
+  .superRefine(({ options }, context) => {
+    if (options.filter(({ recommended }) => recommended).length <= 1) return;
+    context.addIssue({
+      code: "custom",
+      message: "At most one option can be recommended",
+      path: ["options"],
+    });
+  });
+
+export const questionnaireInputSchema = z
+  .object({
+    questions: z.array(questionnaireQuestionSchema).min(1).max(3),
+  })
+  .superRefine(({ questions }, context) => {
+    const questionIds = new Set<string>();
+    questions.forEach(({ id }, index) => {
+      if (questionIds.has(id)) {
+        context.addIssue({
+          code: "custom",
+          message: "Question IDs must be unique",
+          path: ["questions", index, "id"],
+        });
+      }
+      questionIds.add(id);
+    });
+  });
+
+const questionnaireAnswerSchema = z.discriminatedUnion("source", [
+  z.object({
+    questionId: z.string().trim().min(1),
+    source: z.literal("option"),
+    value: z.string().trim().min(1),
+  }),
+  z.object({
+    questionId: z.string().trim().min(1),
+    source: z.literal("other"),
+    value: z.string().trim().min(1),
+  }),
+  z.object({
+    questionId: z.string().trim().min(1),
+    source: z.literal("skipped"),
+  }),
+]);
+
+export const questionnaireOutputSchema = z.object({
+  answers: z.array(questionnaireAnswerSchema).min(1).max(3),
+});
+
+export type QuestionnaireInput = z.infer<typeof questionnaireInputSchema>;
+export type QuestionnaireOutput = z.infer<typeof questionnaireOutputSchema>;

package/src/shared/rdf-namespaces.ts

@@ -0,0 +1,62 @@
+import {
+  encodeIriLocalName as encodeIriLocalNameValue,
+  expandPrefix as expandPrefixIri,
+  iriLocalName as iriLocalNameValue,
+  iriNamespace as iriNamespaceValue,
+  rdfoxDefaultBaseIri as rdfoxDefaultBaseIriValue,
+  shaclGraphIri as shaclGraphIriValue,
+} from "@manta-eu/rdf-lib/namespaces";
+
+export const rulesGraphIri = `${rdfoxDefaultBaseIriValue}rules`;
+
+// KGC uploads the realm ontology here (kgc/kgc/realms/lib/ontology.py: realm_base + "ontology").
+export const ontologyGraphIri = expandPrefixIri(":ontology");
+
+// Field mutability Inferal publishes on its property shapes (DAT-577).
+export const writeLifecycle = {
+  predicate: expandPrefixIri("relay:writeLifecycle"),
+  readOnly: expandPrefixIri("relay:ReadOnly"),
+  createOnly: expandPrefixIri("relay:CreateOnly"),
+};
+
+export const nonDataGraphIris = [ontologyGraphIri, shaclGraphIriValue, rulesGraphIri];
+
+export function mintInstanceIri(classIri: string, localId: string): string {
+  return `${iriNamespaceValue(classIri)}${encodeIriLocalNameValue(`${iriLocalNameValue(classIri)}_${localId}`)}`;
+}
+
+export {
+  baseIri,
+  compactUri,
+  decodeIriLocalName,
+  encodeIriLocalName,
+  encodeIriUnsafeChars,
+  expandPrefix,
+  formatEntityName,
+  formatIriForRdfox,
+  getNamespaceValues,
+  isFullIri,
+  isValidFullIri,
+  isIri,
+  isIsoDatetime,
+  infrastructureNamespaces,
+  iriLocalName,
+  iriNamespace,
+  isOwlNothing,
+  owlNothingIri,
+  isPrefixedIri,
+  labeledNamespaces,
+  type LabeledNamespacePrefix,
+  namespaces,
+  type NamespaceMeta,
+  nfo,
+  parseEntityUri,
+  prependMissingSparqlPrefixes,
+  rdfoxDefaultBaseIri,
+  shaclGraphIri,
+  sh,
+  toTurtlePrefixes,
+  validateFullIri,
+  wellKnownPredicates,
+  type IRI,
+} from "@manta-eu/rdf-lib/namespaces";

package/src/shared/rule-iri.ts

@@ -0,0 +1,15 @@
+export const ruleNameMaxLength = 255;
+
+export function sanitizeRuleName(value: string): string {
+  return value
+    .trim()
+    .replace(/[^a-zA-Z0-9_-]+/g, "_")
+    .replace(/^[-_]+|[-_]+$/g, "");
+}
+
+export function normalizeRuleLocalName(value: string): string | null {
+  const sanitizedName = sanitizeRuleName(value);
+  if (!sanitizedName) return null;
+
+  return sanitizedName.startsWith("Rule_") ? sanitizedName : `Rule_${sanitizedName}`;
+}

package/src/shared/rule-search.ts

@@ -0,0 +1 @@
+export const ruleSearchMaxLength = 200;

package/src/shared/session-types.ts

@@ -0,0 +1,14 @@
+export type User = {
+  id: string;
+  email: string;
+  name?: string | null | undefined;
+};
+
+/** Structurally the same as `@manta-eu/ldo-ui`'s picker row, so either satisfies the other. */
+export type Datastore = {
+  id: string;
+  name: string;
+  depth?: number;
+  selectable?: boolean;
+  badge?: string;
+};

package/src/shared/stakeholder-iri.ts

@@ -0,0 +1,23 @@
+import { decodeIriLocalName, encodeIriLocalName, expandPrefix } from "./rdf-namespaces";
+
+export const userIriPrefix = expandPrefix(":User_");
+export const teamIriPrefix = expandPrefix(":Team_");
+
+export function getUserIri(userId: string): string {
+  return `${userIriPrefix}${encodeIriLocalName(userId)}`;
+}
+
+export function parseUserIdFromIri(iri: string): string | null {
+  if (!iri.startsWith(userIriPrefix)) return null;
+  return decodeIriLocalName(iri.slice(userIriPrefix.length));
+}
+
+// Team paths are stored encodeURIComponent'd, so re-encoding them here would orphan existing nodes
+export function getTeamIri(path: string): string {
+  return `${teamIriPrefix}${encodeURIComponent(path)}`;
+}
+
+export function parseTeamPathFromIri(iri: string): string | null {
+  if (!iri.startsWith(teamIriPrefix)) return null;
+  return decodeIriLocalName(iri.slice(teamIriPrefix.length));
+}

package/src/shared/team-activation.ts

@@ -0,0 +1,9 @@
+export type ActivationAccessArgs = {
+  realmAllows: boolean;
+  flagEnabled: boolean | undefined;
+  wholeOrg: boolean;
+};
+
+export function canManageActivation({ realmAllows, flagEnabled, wholeOrg }: ActivationAccessArgs): boolean {
+  return realmAllows && flagEnabled === true && wholeOrg;
+}

package/src/shared/team-filters.ts

@@ -0,0 +1,33 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { plainMemberRole, type OrgRoleDefinition } from "./org-roles";
+
+export const allRoles = "all";
+
+export type RoleFilter = string;
+
+export type ActivationFilter = "all" | "enabled" | "disabled";
+
+export const activationFilters: readonly ActivationFilter[] = ["all", "enabled", "disabled"];
+
+export function matchesActivationFilter(entry: { enabled: boolean }, filter: ActivationFilter): boolean {
+  if (filter === "all") return true;
+  return entry.enabled === (filter === "enabled");
+}
+
+export function matchesRoleFilter(
+  member: { roles: readonly string[] },
+  filter: RoleFilter,
+  roles: readonly OrgRoleDefinition[],
+): boolean {
+  if (filter === allRoles) return true;
+
+  const held = roles.some((role) => member.roles.includes(role.id));
+  return filter === plainMemberRole ? !held : member.roles.includes(filter);
+}
+
+export function matchesSearch(haystack: (string | undefined)[], query: string | undefined): boolean {
+  if (!isPresent(query)) return true;
+
+  const needle = query.trim().toLowerCase();
+  return haystack.some((value) => (value ?? "").toLowerCase().includes(needle));
+}

package/src/shared/team.ts

@@ -0,0 +1,243 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { splitEvery } from "ramda";
+
+export type TeamRole = string;
+
+export type TeamMember = {
+  id: string;
+  email?: string;
+  name?: string;
+  roles: string[];
+  pending: boolean;
+  expired?: boolean;
+  inviteUrl?: string;
+  teams: string[];
+  federated?: boolean;
+  // Keycloak deletes a managed member's account when they leave the organization.
+  managed?: true;
+  enabled: boolean;
+};
+
+export type TeamOrganization = {
+  alias?: string;
+  name?: string;
+  managed: boolean;
+  mirrored: boolean;
+  inviteCarriesGrants?: true;
+};
+
+export type TeamRoster = {
+  members: TeamMember[];
+  truncated: boolean;
+  organization?: TeamOrganization;
+  total?: number;
+  unfilteredTotal?: number;
+  hasMore?: boolean;
+  snapshot?: string;
+};
+
+export const rosterPageSize = 20;
+
+export const maxRosterPageSize = 100;
+
+export type TeamGroup = { name: string; path: string; depth: number; selectable?: boolean };
+
+export type UserLabelSource = { id: string; name?: string; email?: string; username?: string };
+
+export function userLabel(user: UserLabelSource): string {
+  return user.name ?? user.email ?? user.username ?? user.id;
+}
+
+export type DirectoryMembership = { org: string; name?: string; groups: string[]; managed?: true };
+
+export type DirectoryUser = {
+  id: string;
+  username?: string;
+  email?: string;
+  name?: string;
+  firstName?: string;
+  lastName?: string;
+  memberships: DirectoryMembership[];
+  pending?: boolean;
+  inviteUrl?: string;
+  invitedTo?: DirectoryMembership[];
+  federated?: boolean;
+  nameReadOnly?: boolean;
+  enabled: boolean;
+};
+
+export type TeamDirectory = {
+  users: DirectoryUser[];
+  truncated: boolean;
+  /** Rows matching the query across the realm, or undefined when Keycloak could not count them. */
+  total?: number;
+  hasMore: boolean;
+};
+
+export const directoryPageSize = 20;
+
+export const auth0NameLimits = { part: 150, whole: 300 } as const;
+
+export const maxDirectoryPageSize = 100;
+
+export type AssignableGroup = { path: string; name: string; depth: number; selectable?: boolean };
+
+// `groups` is absent until the org's tree is fetched on demand: loading every org's up front is O(orgs x groups).
+export type AssignableOrganization = {
+  alias: string;
+  name?: string;
+  wholeOrg?: boolean;
+  groups?: AssignableGroup[];
+};
+
+export type AssignTarget = { org: string; group?: string };
+
+export type BulkMutationFailure = { id: string; message: string };
+
+export type AssignmentOutcome = "assigned" | "already" | "failed";
+
+export type AssignmentResult = AssignTarget & {
+  userId: string;
+  outcome: AssignmentOutcome;
+  message?: string;
+};
+
+export type AssignmentSummary = {
+  results: AssignmentResult[];
+  assigned: number;
+  skipped: number;
+  failed: number;
+  roleFailures: BulkMutationFailure[];
+};
+
+export type AssignmentRole = { userId: string; role: string };
+
+export type BulkMutationResult = {
+  attempted: number;
+  changed: number;
+  failures: BulkMutationFailure[];
+};
+
+export type BulkUserOrgPair = { userId: string; org?: string };
+
+export function bulkPairId(pair: BulkUserOrgPair): string {
+  return `${pair.userId}:${pair.org}`;
+}
+
+export function pathSegments(path: string): string[] {
+  return path.split("/").filter(isPresent);
+}
+
+/** Mirrors manta-clj's normalization, so client-side comparisons match its replies. */
+export function normalizeGroupPath(path: string): string {
+  return `/${pathSegments(path).join("/")}`;
+}
+
+export function namesAGroup(path: string | undefined): boolean {
+  return path !== undefined && isPresent(pathSegments(path));
+}
+
+export function ancestorPaths(path: string): string[] {
+  const segments = pathSegments(path);
+  return segments.slice(0, -1).map((_, index) => normalizeGroupPath(segments.slice(0, index + 1).join("/")));
+}
+
+// Keycloak forbids "/" in group names, so the last segment is unambiguously the group's own name.
+export function groupNameFromPath(path: string): string {
+  return pathSegments(path).at(-1) ?? path;
+}
+
+export function groupDepthFromPath(path: string): number {
+  return pathSegments(path).length;
+}
+
+export function chunk<T>(items: T[], size: number): T[][] {
+  return splitEvery(size, items);
+}
+
+export const waveSize = 8;
+
+export async function mapInWaves<T, R>(items: T[], fn: (item: T) => Promise<R>, size: number = waveSize): Promise<R[]> {
+  const results: R[] = [];
+  for (const wave of chunk(items, size)) {
+    results.push(...(await Promise.all(wave.map(fn))));
+  }
+  return results;
+}
+
+export const maxAssignmentPairs = 200;
+
+export const maxBulkMembers = 300;
+
+export function assignTargetKey(target: AssignTarget): string {
+  return namesAGroup(target.group) ? `${target.org}${normalizeGroupPath(target.group ?? "")}` : target.org;
+}
+
+export type InviteOutcome = "invited" | "already" | "failed";
+
+export type InviteGrantOutcome = "applied" | "recorded" | "dropped";
+
+export type InviteResult = {
+  email: string;
+  id?: string;
+  pending?: boolean;
+  outcome: InviteOutcome;
+  message?: string;
+  grant?: InviteGrantOutcome;
+};
+
+export type InviteSummary = {
+  results: InviteResult[];
+  invited: number;
+  skipped: number;
+  failed: number;
+};
+
+// Same shape as metric.spec.core/email-regex, so client and server reject the same addresses.
+const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,63}$/;
+
+export function isEmailAddress(value: string): boolean {
+  return emailPattern.test(value);
+}
+
+const pastedContact = /([^,;<]*)<([^>]*)>/g;
+
+function extractContacts(raw: string): { entries: string[]; rest: string } {
+  const entries: string[] = [];
+  const rest = raw.replace(pastedContact, (match, _label: string, address: string) => {
+    const trimmed = address.trim();
+    entries.push(isEmailAddress(trimmed) ? trimmed : match.trim());
+    return " ";
+  });
+  return { entries, rest };
+}
+
+export type EmailListParse = {
+  emails: string[];
+  invalid: string[];
+};
+
+/** Folds like manta-clj's distinct-emails: case-insensitively, first spelling wins. */
+export function parseEmailList(raw: string): EmailListParse {
+  const seen = new Set<string>();
+  const emails: string[] = [];
+  const invalid: string[] = [];
+
+  function take(entry: string): void {
+    if (!isPresent(entry)) return;
+    if (!isEmailAddress(entry)) {
+      if (!invalid.includes(entry)) invalid.push(entry);
+      return;
+    }
+    const key = entry.toLowerCase();
+    if (seen.has(key)) return;
+    seen.add(key);
+    emails.push(entry);
+  }
+
+  const { entries, rest } = extractContacts(raw);
+  for (const entry of entries) take(entry);
+  for (const entry of rest.split(/[,;\s]+/)) take(entry.trim());
+
+  return { emails, invalid };
+}

package/src/shared/tools/coercers.ts

@@ -0,0 +1,82 @@
+import type {
+  RDFoxFactsOutput,
+  ShowEntitiesOutput,
+  SparqlJsonResults,
+  ToolErrorResult,
+  ToolName,
+  ToolOutputCoercer,
+  ToolOutputType,
+} from "./types";
+import { isJsonLdGraphDocument } from "#types/jsonld";
+
+export function isErrorToolResult(data: unknown): data is ToolErrorResult {
+  return typeof data === "object" && data !== null && "is_error" in data && (data as ToolErrorResult).is_error === true;
+}
+
+export function isSparqlJsonResults(data: unknown): data is SparqlJsonResults {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    "head" in data &&
+    "results" in data &&
+    typeof (data as SparqlJsonResults).head === "object" &&
+    typeof (data as SparqlJsonResults).results === "object"
+  );
+}
+
+function coerceWith<T>(
+  toolName: ToolName,
+  raw: unknown,
+  guards: Array<(value: unknown) => value is T>,
+): T | ToolErrorResult {
+  if (typeof raw === "string") {
+    try {
+      raw = JSON.parse(raw);
+    } catch {
+      return { is_error: true, content: `Failed to parse tool output: ${raw}` };
+    }
+  }
+  if (isErrorToolResult(raw)) return raw;
+  for (const guard of guards) {
+    if (guard(raw)) return raw;
+  }
+  return { is_error: true, content: `Unexpected ${toolName} output format` };
+}
+
+function coerceRDFoxFactsOutput(raw: unknown): RDFoxFactsOutput {
+  return coerceWith<RDFoxFactsOutput>("getRDFoxFacts", raw, [isSparqlJsonResults, isJsonLdGraphDocument]);
+}
+
+export function isShowEntitiesResult(data: unknown): data is Exclude<ShowEntitiesOutput, ToolErrorResult> {
+  if (typeof data !== "object" || data === null) return false;
+  if (!("entityIris" in data) || !("graph" in data)) return false;
+  return (
+    Array.isArray(data.entityIris) &&
+    data.entityIris.every((iri) => typeof iri === "string") &&
+    isJsonLdGraphDocument(data.graph)
+  );
+}
+
+function coerceShowEntitiesOutput(raw: unknown): ShowEntitiesOutput {
+  return coerceWith<ShowEntitiesOutput>("showEntities", raw, [isShowEntitiesResult]);
+}
+
+const coercers: Partial<Record<ToolName, ToolOutputCoercer<ToolName>>> = {
+  getRDFoxFacts: coerceRDFoxFactsOutput as ToolOutputCoercer<"getRDFoxFacts">,
+  showEntities: coerceShowEntitiesOutput as ToolOutputCoercer<"showEntities">,
+};
+
+export function coerceToolOutput<T extends ToolName>(toolName: T, raw: unknown): ToolOutputType<T> {
+  const coercer = coercers[toolName] as ToolOutputCoercer<T> | undefined;
+  if (coercer) {
+    return coercer(raw);
+  }
+  if (typeof raw === "string") {
+    try {
+      return JSON.parse(raw) as ToolOutputType<T>;
+    } catch {
+      return raw as ToolOutputType<T>;
+    }
+  }
+  return raw as ToolOutputType<T>;
+}

package/src/shared/tools/index.ts

@@ -0,0 +1,49 @@
+export { coerceToolOutput, isErrorToolResult, isShowEntitiesResult, isSparqlJsonResults } from "./coercers";
+export {
+  allToolNames,
+  assertValidToolName,
+  getHumanToolName,
+  getSkillToolLabel,
+  getToolMetadata,
+  getToolUIPartLabel,
+  isValidToolName,
+  toolMetadata,
+} from "./metadata";
+export type {
+  ActionPlanShowcaseInput,
+  ActionPlanShowcaseOutput,
+  ActionPlanStatus,
+  AddRDFoxFactsInput,
+  AddRDFoxFactsOutput,
+  CancelScheduleInput,
+  CancelScheduleOutput,
+  ExecuteActionPlanInput,
+  ExecuteActionPlanOutput,
+  ExplainRDFoxRulesInput,
+  ExplainRDFoxRulesOutput,
+  GenerateChartInput,
+  GenerateChartOutput,
+  GetRDFoxRulesInput,
+  GetRDFoxRulesOutput,
+  ListScheduledTasksInput,
+  ListScheduledTasksOutput,
+  RDFoxFactsInput,
+  RDFoxFactsOutput,
+  ScheduleTaskInput,
+  ScheduleTaskOutput,
+  ShowEntitiesInput,
+  ShowEntitiesOutput,
+  SparqlJsonBinding,
+  SparqlJsonResults,
+  SparqlValue,
+  ToolCategory,
+  ToolDefinition,
+  ToolDefinitions,
+  ToolErrorResult,
+  ToolInputSchema,
+  ToolMetadata,
+  ToolName,
+  ToolOutput,
+  ToolOutputCoercer,
+  ToolOutputType,
+} from "./types";