@exellix/graphs-studio-catalog 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@exellix/graphs-studio-catalog",
+  "version": "0.1.0",
+  "description": "Graphs Studio library UI helpers (list, status, soft-delete, job types, branches). Not @exellix/catalox-graphs persistence.",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/exellix/graphs-studio.git",
+    "directory": "packages/graphs-studio-catalog"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "prepublishOnly": "node --test tests/graphs-studio-catalog.test.mjs"
+  },
+  "dependencies": {
+    "@x12i/graphenix-authoring-format": "^2.11.0",
+    "@x12i/graphenix-executable-contracts": "^2.11.0"
+  }
+}

package/src/catalogIds.js

@@ -0,0 +1,8 @@
+export const GRAPH_CATALOG_IDS = {
+  graphs: 'graphs',
+  graphVersions: 'graph-versions',
+  graphTemplates: 'graph-templates',
+  jobTypes: 'job-types',
+  graphJobTypeRelations: 'graph-job-type-relations',
+  graphBranches: 'graph-branches',
+};

package/src/cataloxGraphManagementApi.js

@@ -0,0 +1,121 @@
+/**
+ * Browser-side Catalox graph management API (calls dev BFF /api/catalox/*).
+ */
+
+const BASE = '/api/catalox';
+
+async function fetchJson(url, init) {
+  const res = await fetch(url, init);
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    return { ok: false, error: body.error ?? res.statusText };
+  }
+  return body;
+}
+
+/**
+ * @param {{ limit?: number, status?: string, jobTypeId?: string, includeDeleted?: boolean }} [options]
+ */
+export async function listGraphsForLibrary(options = {}) {
+  const params = new URLSearchParams();
+  if (options.limit) params.set('limit', String(options.limit));
+  if (options.status) params.set('status', options.status);
+  if (options.jobTypeId) params.set('jobTypeId', options.jobTypeId);
+  if (options.includeDeleted) params.set('includeDeleted', '1');
+  const qs = params.toString();
+  return fetchJson(`${BASE}/graphs${qs ? `?${qs}` : ''}`);
+}
+
+/** @param {string} graphId @param {string} title */
+export async function renameGraphInCatalox(graphId, title) {
+  const load = await fetchJson(`${BASE}/graphs/${encodeURIComponent(graphId)}`);
+  if (!load.ok || !load.item) return load;
+  const data = { ...load.item.data, title, updatedAt: new Date().toISOString() };
+  return fetchJson(`${BASE}/graphs/${encodeURIComponent(graphId)}`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ data }),
+  });
+}
+
+/** @param {string} graphId @param {string} status */
+export async function updateGraphStatusInCatalox(graphId, status) {
+  const load = await fetchJson(`${BASE}/graphs/${encodeURIComponent(graphId)}`);
+  if (!load.ok || !load.item) return load;
+  const data = { ...load.item.data, status, updatedAt: new Date().toISOString() };
+  return fetchJson(`${BASE}/graphs/${encodeURIComponent(graphId)}`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ data }),
+  });
+}
+
+/** @param {string} graphId */
+export async function softDeleteGraphInCatalox(graphId) {
+  const load = await fetchJson(`${BASE}/graphs/${encodeURIComponent(graphId)}`);
+  if (!load.ok || !load.item) return load;
+  const now = new Date().toISOString();
+  const data = {
+    ...load.item.data,
+    status: 'deleted',
+    deletedAt: now,
+    updatedAt: now,
+  };
+  return fetchJson(`${BASE}/graphs/${encodeURIComponent(graphId)}`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ data }),
+  });
+}
+
+/** @param {string} graphId */
+export async function restoreGraphInCatalox(graphId) {
+  const load = await fetchJson(`${BASE}/graphs/${encodeURIComponent(graphId)}`);
+  if (!load.ok || !load.item) return load;
+  const data = { ...load.item.data, status: 'draft', updatedAt: new Date().toISOString() };
+  delete data.deletedAt;
+  delete data.deletedBy;
+  return fetchJson(`${BASE}/graphs/${encodeURIComponent(graphId)}`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ data }),
+  });
+}
+
+export async function listJobTypesFromCatalox() {
+  return fetchJson(`${BASE}/catalogs/job-types/items?limit=500`);
+}
+
+/** @param {Record<string, unknown>} jobTypeData */
+export async function upsertJobTypeInCatalox(jobTypeData) {
+  const id = typeof jobTypeData.jobTypeId === 'string' ? jobTypeData.jobTypeId : '';
+  if (!id) return { ok: false, error: 'jobTypeId required' };
+  return fetchJson(`${BASE}/catalogs/job-types/items/${encodeURIComponent(id)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ itemId: id, data: jobTypeData }),
+  });
+}
+
+/** @param {string} jobTypeId */
+export async function deleteJobTypeFromCatalox(jobTypeId) {
+  return fetchJson(`${BASE}/catalogs/job-types/items/${encodeURIComponent(jobTypeId)}`, {
+    method: 'DELETE',
+  });
+}
+
+export async function listGraphBranchesFromCatalox(graphId) {
+  const params = graphId ? `?limit=500&q=${encodeURIComponent(graphId)}` : '?limit=500';
+  return fetchJson(`${BASE}/catalogs/graph-branches/items${params}`);
+}
+
+/** @param {Record<string, unknown>} branchData */
+export async function upsertGraphBranchInCatalox(branchData) {
+  const id = typeof branchData.branchId === 'string' ? branchData.branchId : '';
+  if (!id) return { ok: false, error: 'branchId required' };
+  return fetchJson(`${BASE}/catalogs/graph-branches/items/${encodeURIComponent(id)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ itemId: id, data: branchData }),
+  });
+}

package/src/graphBranches.js

@@ -0,0 +1,55 @@
+/**
+ * @typedef {Object} GraphBranchRecord
+ * @property {string} branchId
+ * @property {string} graphId
+ * @property {string} branchName
+ * @property {string} [parentBranchId]
+ * @property {string} [headVersionId]
+ * @property {'active' | 'merged' | 'archived'} status
+ * @property {string} [createdAt]
+ * @property {string} [createdBy]
+ */
+
+/**
+ * @param {Record<string, unknown>} raw
+ * @returns {GraphBranchRecord | null}
+ */
+export function normalizeBranchRecord(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const branchId = typeof raw.branchId === 'string' ? raw.branchId.trim() : '';
+  const graphId = typeof raw.graphId === 'string' ? raw.graphId.trim() : '';
+  const branchName = typeof raw.branchName === 'string' ? raw.branchName.trim() : '';
+  if (!branchId || !graphId || !branchName) return null;
+  const statusRaw = typeof raw.status === 'string' ? raw.status : 'active';
+  const status = statusRaw === 'merged' || statusRaw === 'archived' ? statusRaw : 'active';
+  return {
+    branchId,
+    graphId,
+    branchName,
+    parentBranchId:
+      typeof raw.parentBranchId === 'string' ? raw.parentBranchId : undefined,
+    headVersionId:
+      typeof raw.headVersionId === 'string' ? raw.headVersionId : undefined,
+    status,
+    createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : undefined,
+    createdBy: typeof raw.createdBy === 'string' ? raw.createdBy : undefined,
+  };
+}
+
+/**
+ * Fork a branch from a parent.
+ * @param {{ graphId: string, branchName: string, parentBranchId?: string, headVersionId?: string, actor?: string }} input
+ */
+export function createBranchRecord(input) {
+  const branchId = `${input.graphId}::${input.branchName.replace(/\s+/g, '-').toLowerCase()}`;
+  return normalizeBranchRecord({
+    branchId,
+    graphId: input.graphId,
+    branchName: input.branchName,
+    parentBranchId: input.parentBranchId,
+    headVersionId: input.headVersionId,
+    status: 'active',
+    createdAt: new Date().toISOString(),
+    createdBy: input.actor,
+  });
+}

package/src/graphList.js

@@ -0,0 +1,110 @@
+import { normalizeGraphPublishStatus } from './graphStatus.js';
+
+/**
+ * @typedef {Object} GraphListRow
+ * @property {string} id
+ * @property {string} graphId
+ * @property {string} title
+ * @property {string} status
+ * @property {string} [jobTypeId]
+ * @property {string} [branchId]
+ * @property {string} [branchName]
+ * @property {string} [createdAt]
+ * @property {string} [updatedAt]
+ * @property {string} [createdBy]
+ * @property {string} [modifiedBy]
+ * @property {string} [deletedAt]
+ */
+
+/**
+ * Normalize a Catalox graphs catalog list item into a library row.
+ * @param {Record<string, unknown>} item
+ * @returns {GraphListRow | null}
+ */
+export function normalizeGraphListItem(item) {
+  if (!item || typeof item !== 'object') return null;
+  const graphId =
+    (typeof item.itemId === 'string' && item.itemId.trim()) ||
+    (typeof item.graphId === 'string' && item.graphId.trim()) ||
+    '';
+  if (!graphId) return null;
+  const data = item.data && typeof item.data === 'object' ? item.data : item;
+  const title =
+    (typeof data.title === 'string' && data.title.trim()) ||
+    (typeof data.name === 'string' && data.name.trim()) ||
+    graphId;
+  const graph = data.graph && typeof data.graph === 'object' ? data.graph : null;
+  const md =
+    graph?.metadata && typeof graph.metadata === 'object' ? graph.metadata : {};
+  const pipeline =
+    md.jobPipeline && typeof md.jobPipeline === 'object' ? md.jobPipeline : {};
+  const jobTypeId =
+    (typeof data.jobTypeId === 'string' && data.jobTypeId) ||
+    (typeof pipeline.jobTypeId === 'string' && pipeline.jobTypeId) ||
+    undefined;
+
+  return {
+    id: graphId,
+    graphId,
+    title,
+    status: normalizeGraphPublishStatus(data.status ?? md.status),
+    jobTypeId,
+    branchId: typeof data.branchId === 'string' ? data.branchId : undefined,
+    branchName: typeof data.branchName === 'string' ? data.branchName : 'main',
+    createdAt: typeof data.createdAt === 'string' ? data.createdAt : undefined,
+    updatedAt:
+      typeof data.updatedAt === 'string'
+        ? data.updatedAt
+        : typeof item.updatedAt === 'string'
+          ? item.updatedAt
+          : undefined,
+    createdBy: typeof data.createdBy === 'string' ? data.createdBy : undefined,
+    modifiedBy: typeof data.modifiedBy === 'string' ? data.modifiedBy : undefined,
+    deletedAt: typeof data.deletedAt === 'string' ? data.deletedAt : undefined,
+  };
+}
+
+/**
+ * @param {GraphListRow[]} rows
+ * @param {{ search?: string, status?: string, jobTypeId?: string, deletedOnly?: boolean }} [filters]
+ */
+export function filterGraphListRows(rows, filters = {}) {
+  let list = [...rows];
+  if (filters.deletedOnly) {
+    list = list.filter((r) => r.status === 'deleted' || r.deletedAt);
+  } else {
+    list = list.filter((r) => r.status !== 'deleted' && !r.deletedAt);
+  }
+  if (filters.status && filters.status !== 'all') {
+    list = list.filter((r) => r.status === filters.status);
+  }
+  if (filters.jobTypeId && filters.jobTypeId !== 'all') {
+    list = list.filter((r) => r.jobTypeId === filters.jobTypeId);
+  }
+  const q = filters.search?.trim().toLowerCase();
+  if (q) {
+    list = list.filter(
+      (r) =>
+        r.title.toLowerCase().includes(q) ||
+        r.graphId.toLowerCase().includes(q) ||
+        (r.jobTypeId ?? '').toLowerCase().includes(q),
+    );
+  }
+  return list;
+}
+
+/**
+ * @param {GraphListRow[]} rows
+ * @param {string} sortKey
+ * @param {'asc' | 'desc'} sortDir
+ */
+export function sortGraphListRows(rows, sortKey = 'updatedAt', sortDir = 'desc') {
+  const copy = [...rows];
+  copy.sort((a, b) => {
+    const av = a[sortKey] ?? '';
+    const bv = b[sortKey] ?? '';
+    const cmp = String(av).localeCompare(String(bv));
+    return sortDir === 'asc' ? cmp : -cmp;
+  });
+  return copy;
+}

package/src/graphRecycleBin.js

@@ -0,0 +1,41 @@
+/**
+ * Soft-delete / recycle bin helpers (interim until Catalox native soft-delete).
+ */
+
+/**
+ * @param {Record<string, unknown>} projectData
+ * @param {string} [actor]
+ * @returns {Record<string, unknown>}
+ */
+export function markGraphSoftDeleted(projectData, actor) {
+  const now = new Date().toISOString();
+  return {
+    ...projectData,
+    status: 'deleted',
+    deletedAt: now,
+    deletedBy: actor ?? projectData.deletedBy,
+    updatedAt: now,
+    modifiedBy: actor ?? projectData.modifiedBy,
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} projectData
+ * @param {string} [actor]
+ * @returns {Record<string, unknown>}
+ */
+export function restoreSoftDeletedGraph(projectData, actor) {
+  const next = { ...projectData };
+  delete next.deletedAt;
+  delete next.deletedBy;
+  next.status = 'draft';
+  next.updatedAt = new Date().toISOString();
+  if (actor) next.modifiedBy = actor;
+  return next;
+}
+
+/** @param {Record<string, unknown>} projectData */
+export function isGraphSoftDeleted(projectData) {
+  if (!projectData || typeof projectData !== 'object') return false;
+  return projectData.status === 'deleted' || Boolean(projectData.deletedAt);
+}

package/src/graphStatus.js

@@ -0,0 +1,25 @@
+/** Catalox catalog ids owned or extended by graphs-studio graph management. */
+export const GRAPH_CATALOG_IDS = {
+  graphs: 'graphs',
+  graphVersions: 'graph-versions',
+  graphTemplates: 'graph-templates',
+  jobTypes: 'job-types',
+  graphJobTypeRelations: 'graph-job-type-relations',
+  graphBranches: 'graph-branches',
+};
+
+/** @typedef {'draft' | 'published' | 'deleted'} GraphPublishStatus */
+
+export const GRAPH_PUBLISH_STATUSES = /** @type {const} */ (['draft', 'published', 'deleted']);
+
+/** @param {unknown} value */
+export function normalizeGraphPublishStatus(value) {
+  const s = typeof value === 'string' ? value.trim() : '';
+  if (s === 'published' || s === 'deleted') return s;
+  return 'draft';
+}
+
+/** @param {unknown} value */
+export function isValidGraphPublishStatus(value) {
+  return GRAPH_PUBLISH_STATUSES.includes(normalizeGraphPublishStatus(value));
+}

package/src/index.js

@@ -0,0 +1,30 @@
+export { GRAPH_CATALOG_IDS } from './catalogIds.js';
+export {
+  GRAPH_PUBLISH_STATUSES,
+  normalizeGraphPublishStatus,
+  isValidGraphPublishStatus,
+} from './graphStatus.js';
+export {
+  normalizeGraphListItem,
+  filterGraphListRows,
+  sortGraphListRows,
+} from './graphList.js';
+export {
+  markGraphSoftDeleted,
+  restoreSoftDeletedGraph,
+  isGraphSoftDeleted,
+} from './graphRecycleBin.js';
+export { normalizeJobTypeRecord, jobTypeToCatalogPayload } from './jobTypesCatalog.js';
+export { normalizeBranchRecord, createBranchRecord } from './graphBranches.js';
+export {
+  listGraphsForLibrary,
+  renameGraphInCatalox,
+  updateGraphStatusInCatalox,
+  softDeleteGraphInCatalox,
+  restoreGraphInCatalox,
+  listJobTypesFromCatalox,
+  upsertJobTypeInCatalox,
+  deleteJobTypeFromCatalox,
+  listGraphBranchesFromCatalox,
+  upsertGraphBranchInCatalox,
+} from './cataloxGraphManagementApi.js';

package/src/jobTypesCatalog.js

@@ -0,0 +1,49 @@
+import { GRAPH_CATALOG_IDS } from './catalogIds.js';
+
+/**
+ * @typedef {{ jobTypeId: string, displayName: string, description?: string, createdAt?: string, updatedAt?: string, createdBy?: string, modifiedBy?: string }} JobTypeRecord
+ */
+
+/**
+ * @param {Record<string, unknown>} raw
+ * @returns {JobTypeRecord | null}
+ */
+export function normalizeJobTypeRecord(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const jobTypeId = typeof raw.jobTypeId === 'string' ? raw.jobTypeId.trim() : '';
+  if (!jobTypeId) return null;
+  const displayName =
+    typeof raw.displayName === 'string' && raw.displayName.trim()
+      ? raw.displayName.trim()
+      : jobTypeId;
+  return {
+    jobTypeId,
+    displayName,
+    description: typeof raw.description === 'string' ? raw.description : undefined,
+    createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : undefined,
+    updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : undefined,
+    createdBy: typeof raw.createdBy === 'string' ? raw.createdBy : undefined,
+    modifiedBy: typeof raw.modifiedBy === 'string' ? raw.modifiedBy : undefined,
+  };
+}
+
+/**
+ * @param {JobTypeRecord} jobType
+ * @param {string} [actor]
+ */
+export function jobTypeToCatalogPayload(jobType, actor) {
+  const now = new Date().toISOString();
+  return {
+    catalogId: GRAPH_CATALOG_IDS.jobTypes,
+    itemId: jobType.jobTypeId,
+    data: {
+      ...jobType,
+      updatedAt: now,
+      modifiedBy: actor ?? jobType.modifiedBy,
+      createdAt: jobType.createdAt ?? now,
+      createdBy: jobType.createdBy ?? actor,
+    },
+  };
+}
+
+export { GRAPH_CATALOG_IDS };