// helpers.ts ~L131 — operates on collection/root document links
export function scanCsapiLinks(
  links: Array<{ rel?: string; href?: string }>
): Map {
  // Looks for rel="ogc-cs:systems", rel="items", etc.
  // Does NOT handle systemKind@link, platform@link, etc.
}

getSystemProcedures(systemId: string): string    // → /systems/{id}/procedures
getSystemDeployments(systemId: string): string   // → /systems/{id}/deployments
getDeploymentSystems(deploymentId: string): string // → /deployments/{id}/systems
getProcedureSystems(procedureId: string): string   // → /procedures/{id}/systems
// ... etc.

// ResourceDetail.vue — ~105 lines of boilerplate that should be in the library
async function tryLinkFallback(resource: any, resourceType: string) {
  const props = resource.properties ?? resource;
  
  if (props['systemKind@link']?.href) {
    const resp = await fetch(props['systemKind@link'].href, { headers });
    if (resp.ok) {
      const procedure = await resp.json();
      // Display procedure info
    }
  }
  
  if (props['platform@link']?.href) {
    const resp = await fetch(props['platform@link'].href, { headers });
    if (resp.ok) {
      const platform = await resp.json();
      // Display platform info
    }
  }
  
  // ... repeat for every @link field type
}

export interface CSAPIResourceRef {
  href: string;
  uid?: string;
  title?: string;
  rt?: string;
}

/**
 * Fetches the resource referenced by a `@link` property.
 *
 * Handles both absolute and relative hrefs by resolving against the
 * provided API root URL.
 *
 * @param ref - The `@link` reference object (e.g., from `systemKindLink`)
 * @param apiRootUrl - The CS API root URL for resolving relative hrefs
 * @param fetchOptions - Optional fetch configuration (headers, auth, etc.)
 * @returns The fetched resource as parsed JSON
 */
export async function resolveResourceRef(
  ref: CSAPIResourceRef,
  apiRootUrl: string,
  fetchOptions?: RequestInit,
): Promise {
  const url = new URL(ref.href, apiRootUrl).toString();
  const response = await fetch(url, fetchOptions);
  if (!response.ok) {
    throw new Error(`Failed to resolve @link: ${response.status} ${url}`);
  }
  return response.json();
}

/**
 * Extracts the resource type and ID from a `@link` href.
 *
 * Handles hrefs like:
 *   - "http://server/api/procedures/abc123" → { type: 'procedures', id: 'abc123' }
 *   - "/api/systems/xyz" → { type: 'systems', id: 'xyz' }
 *
 * @param href - The href string from a `@link` object
 * @returns Parsed resource type and ID, or null if the href doesn't match a known pattern
 */
export function parseResourceRefHref(
  href: string,
): { resourceType: string; resourceId: string } | null {
  const segments = new URL(href, 'http://placeholder').pathname
    .replace(/\/+$/, '')
    .split('/');
  const id = segments.pop();
  const type = segments.pop();
  if (!id || !type) return null;
  return { resourceType: type, resourceId: id };
}

/**
 * Extracts all `@link` and `@id` cross-reference fields from a raw
 * resource object.
 *
 * Useful for discovering what associations a server provided, regardless
 * of whether the typed model includes them.
 *
 * @param raw - Raw JSON object from the server
 * @returns Map of field name → value (CSAPIResourceRef for @link, string for @id)
 */
export function extractCrossReferences(
  raw: Record,
): Map {
  const refs = new Map();
  const props = (raw.properties as Record) ?? raw;

  for (const [key, value] of Object.entries(props)) {
    if (key.endsWith('@link') && typeof value === 'object' && value !== null) {
      const obj = value as Record;
      if (typeof obj.href === 'string') {
        refs.set(key, {
          href: obj.href,
          ...(typeof obj.uid === 'string' ? { uid: obj.uid } : {}),
          ...(typeof obj.title === 'string' ? { title: obj.title } : {}),
          ...(typeof obj.rt === 'string' ? { rt: obj.rt } : {}),
        });
      }
    }
    if (key.endsWith('@id') && typeof value === 'string') {
      refs.set(key, value);
    }
  }

  return refs;
}

/**
 * Attempts server-side navigation first, then falls back to `@link` data
 * if the server returns an error.
 *
 * This is the recommended pattern for consumers that need to discover
 * associations on servers with varying endpoint support.
 *
 * @param navigationUrl - The server-side navigation endpoint URL
 * @param linkRef - The `@link` reference to use as fallback (may be undefined)
 * @param apiRootUrl - The CS API root URL for resolving relative hrefs
 * @param fetchOptions - Optional fetch configuration
 * @returns The fetched resource(s), or null if both approaches fail
 */
export async function resolveWithLinkFallback(
  navigationUrl: string,
  linkRef: CSAPIResourceRef | undefined,
  apiRootUrl: string,
  fetchOptions?: RequestInit,
): Promise {
  // Step 1: Try server-side navigation
  try {
    const response = await fetch(navigationUrl, fetchOptions);
    if (response.ok) return response.json();
  } catch { /* fall through */ }

  // Step 2: Fall back to @link
  if (linkRef) {
    try {
      return await resolveResourceRef(linkRef, apiRootUrl, fetchOptions);
    } catch { /* fall through */ }
  }

  return null;
}