@letpeoplework/lighthouse-client 0.1.0

package/dist/index.mjs

@@ -0,0 +1,578 @@
+// src/index.ts
+var getClientPackageContract = () => ({
+  name: "@letpeoplework/lighthouse-client",
+  capabilities: [
+    "versioned-api-contracts",
+    "shared-domain-operations",
+    "connectivity-and-discovery-contracts",
+    "automation-auth-contracts"
+  ]
+});
+var SUPPORTED_DISCOVERY_CONTRACT_VERSION = 1;
+var isObjectRecord = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var getNormalizedLighthouseUrl = (value) => {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return null;
+    }
+    const pathname = parsed.pathname.replace(/\/+$/u, "");
+    if (pathname.length === 0 || pathname === "/") {
+      return parsed.origin;
+    }
+    return `${parsed.origin}${pathname}`;
+  } catch {
+    return null;
+  }
+};
+var getApiBaseUrl = (lighthouseUrl) => {
+  if (lighthouseUrl.endsWith("/api")) {
+    return lighthouseUrl;
+  }
+  return `${lighthouseUrl}/api`;
+};
+var validateDiscoveryTimestamp = (detectedAtUtc) => {
+  return !Number.isNaN(Date.parse(detectedAtUtc));
+};
+var getInvalidContractResult = (reason) => ({
+  isValid: false,
+  reason
+});
+var validateStandaloneDiscoveryContract = (contract) => {
+  if (contract.contractVersion !== SUPPORTED_DISCOVERY_CONTRACT_VERSION) {
+    return getInvalidContractResult(
+      "Discovery contractVersion is not supported."
+    );
+  }
+  const normalizedUrl = getNormalizedLighthouseUrl(contract.lighthouseUrl);
+  if (normalizedUrl === null) {
+    return getInvalidContractResult("Discovery lighthouseUrl is invalid.");
+  }
+  if (!validateDiscoveryTimestamp(contract.detectedAtUtc)) {
+    return getInvalidContractResult("Discovery detectedAtUtc is invalid.");
+  }
+  return {
+    isValid: true,
+    contract: {
+      contractVersion: SUPPORTED_DISCOVERY_CONTRACT_VERSION,
+      lighthouseUrl: normalizedUrl,
+      detectedAtUtc: contract.detectedAtUtc
+    }
+  };
+};
+var parseStandaloneDiscoveryContract = (serializedContract) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(serializedContract);
+  } catch {
+    return getInvalidContractResult(
+      "Discovery contract payload is not valid JSON."
+    );
+  }
+  if (!isObjectRecord(parsed)) {
+    return getInvalidContractResult(
+      "Discovery contract payload must be an object."
+    );
+  }
+  const contractVersion = parsed.contractVersion;
+  if (typeof contractVersion !== "number") {
+    return getInvalidContractResult(
+      "Discovery contractVersion must be a number."
+    );
+  }
+  const lighthouseUrl = parsed.lighthouseUrl;
+  if (typeof lighthouseUrl !== "string") {
+    return getInvalidContractResult(
+      "Discovery lighthouseUrl must be a string."
+    );
+  }
+  const detectedAtUtc = parsed.detectedAtUtc;
+  if (typeof detectedAtUtc !== "string") {
+    return getInvalidContractResult(
+      "Discovery detectedAtUtc must be a string."
+    );
+  }
+  return validateStandaloneDiscoveryContract({
+    contractVersion,
+    lighthouseUrl,
+    detectedAtUtc
+  });
+};
+var getResolvedEndpoint = (mode, lighthouseUrl) => {
+  const apiBaseUrl = getApiBaseUrl(lighthouseUrl);
+  return {
+    mode,
+    lighthouseUrl,
+    apiBaseUrl,
+    healthCheckUrl: `${apiBaseUrl}/v1/version`
+  };
+};
+var getMisconfiguredResult = (reason) => ({
+  category: "misconfigured",
+  reason
+});
+var resolveConnectionEndpoint = async (configuration) => {
+  if (configuration.kind === "explicit") {
+    const normalizedUrl = getNormalizedLighthouseUrl(
+      configuration.lighthouseUrl
+    );
+    if (normalizedUrl === null) {
+      return {
+        isValid: false,
+        result: getMisconfiguredResult("Explicit Lighthouse URL is invalid.")
+      };
+    }
+    return {
+      isValid: true,
+      endpoint: getResolvedEndpoint("explicit", normalizedUrl)
+    };
+  }
+  const discoveryContract = await configuration.getDiscoveryContract();
+  if (discoveryContract === null) {
+    return {
+      isValid: false,
+      result: getMisconfiguredResult(
+        "Standalone discovery contract is not available."
+      )
+    };
+  }
+  const parsedContract = validateStandaloneDiscoveryContract(discoveryContract);
+  if (!parsedContract.isValid) {
+    return {
+      isValid: false,
+      result: getMisconfiguredResult(parsedContract.reason)
+    };
+  }
+  return {
+    isValid: true,
+    endpoint: getResolvedEndpoint(
+      "standalone",
+      parsedContract.contract.lighthouseUrl
+    )
+  };
+};
+var getFailureCategoryForStatus = (statusCode) => {
+  if (statusCode === 401 || statusCode === 403) {
+    return "unauthorized";
+  }
+  if (statusCode === 404) {
+    return "misconfigured";
+  }
+  if (statusCode >= 500 && statusCode <= 599) {
+    return "dependency-failure";
+  }
+  return "unexpected";
+};
+var validateLighthouseConnectivity = async (configuration, dependencies, requestInit) => {
+  const resolvedEndpoint = await resolveConnectionEndpoint(configuration);
+  if (!resolvedEndpoint.isValid) {
+    return resolvedEndpoint.result;
+  }
+  const endpoint = resolvedEndpoint.endpoint;
+  try {
+    const response = await dependencies.fetch(
+      endpoint.healthCheckUrl,
+      requestInit
+    );
+    if (response.ok) {
+      const serverVersion = (await response.text()).trim();
+      return {
+        category: "success",
+        endpoint,
+        serverVersion
+      };
+    }
+    return {
+      category: getFailureCategoryForStatus(response.status),
+      reason: `Connectivity check failed with status ${response.status}.`,
+      statusCode: response.status,
+      endpoint
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Connectivity request failed.";
+    return {
+      category: "unreachable",
+      reason: message,
+      endpoint
+    };
+  }
+};
+var getTrimmedValue = (value) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return void 0;
+  }
+  return trimmed;
+};
+var getAuthFromOverrides = (overrides) => {
+  const apiKey = getTrimmedValue(overrides?.apiKey);
+  const bearerToken = getTrimmedValue(overrides?.bearerToken);
+  if (apiKey !== void 0 && bearerToken !== void 0) {
+    throw new Error("Specify either --api-key or --bearer-token, not both.");
+  }
+  if (apiKey !== void 0) {
+    return {
+      kind: "api-key",
+      value: apiKey,
+      headerName: getTrimmedValue(overrides?.apiKeyHeaderName)
+    };
+  }
+  if (bearerToken !== void 0) {
+    return {
+      kind: "bearer-token",
+      token: bearerToken
+    };
+  }
+  return null;
+};
+var getStatusFromAuth = (auth, source) => {
+  if (auth.kind === "none") {
+    return {
+      isAuthenticated: false,
+      kind: "none",
+      source: "none"
+    };
+  }
+  return {
+    isAuthenticated: true,
+    kind: auth.kind,
+    source
+  };
+};
+var createLighthouseAuthContext = (store) => ({
+  resolveAuth: async (overrides) => {
+    const overrideAuth = getAuthFromOverrides(overrides);
+    if (overrideAuth !== null) {
+      return overrideAuth;
+    }
+    const storedAuth = await store.load();
+    if (storedAuth !== null) {
+      return storedAuth;
+    }
+    return {
+      kind: "none"
+    };
+  },
+  login: async (overrides) => {
+    const auth = getAuthFromOverrides(overrides);
+    if (auth === null) {
+      throw new Error("Provide --api-key or --bearer-token for auth login.");
+    }
+    await store.save(auth);
+  },
+  logout: async () => {
+    await store.clear();
+  },
+  getStatus: async (overrides) => {
+    const overrideAuth = getAuthFromOverrides(overrides);
+    if (overrideAuth !== null) {
+      return getStatusFromAuth(overrideAuth, "override");
+    }
+    const storedAuth = await store.load();
+    if (storedAuth !== null) {
+      return getStatusFromAuth(storedAuth, "stored");
+    }
+    return getStatusFromAuth({ kind: "none" }, "none");
+  }
+});
+var getAuthHeaders = (auth) => {
+  if (auth === void 0 || auth.kind === "none") {
+    return {};
+  }
+  if (auth.kind === "api-key") {
+    return {
+      [auth.headerName ?? "X-Api-Key"]: auth.value
+    };
+  }
+  return {
+    Authorization: `Bearer ${auth.token}`
+  };
+};
+var getRequestInit = (auth, requestOptions) => {
+  const authHeaders = getAuthHeaders(auth);
+  const hasBody = requestOptions?.body !== void 0;
+  const headers = hasBody ? {
+    ...authHeaders,
+    "content-type": "application/json"
+  } : authHeaders;
+  return {
+    method: requestOptions?.method,
+    headers,
+    body: hasBody ? JSON.stringify(requestOptions.body) : void 0
+  };
+};
+var getFetchDependency = (dependencies) => {
+  if (dependencies.fetch !== void 0) {
+    return dependencies.fetch;
+  }
+  return async (url, init) => {
+    const response = await fetch(url, init);
+    return response;
+  };
+};
+var getErrorResult = (error) => ({
+  ok: false,
+  error
+});
+var getErrorFromConnectivityResult = (result) => ({
+  category: result.category,
+  reason: result.reason,
+  statusCode: result.statusCode
+});
+var toApiError = (statusCode, reason) => ({
+  category: getFailureCategoryForStatus(statusCode),
+  reason,
+  statusCode
+});
+var requestText = async (configuration, dependencies, route) => {
+  const fetchDependency = getFetchDependency(dependencies);
+  const connectivityResult = await validateLighthouseConnectivity(
+    configuration.connection,
+    {
+      fetch: fetchDependency
+    },
+    getRequestInit(configuration.auth)
+  );
+  if (connectivityResult.category !== "success") {
+    return getErrorResult(getErrorFromConnectivityResult(connectivityResult));
+  }
+  try {
+    const response = await fetchDependency(
+      `${connectivityResult.endpoint.apiBaseUrl}${route}`,
+      getRequestInit(configuration.auth)
+    );
+    if (!response.ok) {
+      return getErrorResult(
+        toApiError(
+          response.status,
+          `Request failed with status ${response.status}.`
+        )
+      );
+    }
+    return {
+      ok: true,
+      value: (await response.text()).trim()
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : "Request execution failed.";
+    return getErrorResult({
+      category: "unreachable",
+      reason
+    });
+  }
+};
+var requestJson = async (configuration, dependencies, route, requestOptions) => {
+  const fetchDependency = getFetchDependency(dependencies);
+  const connectivityResult = await validateLighthouseConnectivity(
+    configuration.connection,
+    {
+      fetch: fetchDependency
+    },
+    getRequestInit(configuration.auth, {
+      method: "GET"
+    })
+  );
+  if (connectivityResult.category !== "success") {
+    return getErrorResult(getErrorFromConnectivityResult(connectivityResult));
+  }
+  try {
+    const response = await fetchDependency(
+      `${connectivityResult.endpoint.apiBaseUrl}${route}`,
+      getRequestInit(configuration.auth, requestOptions)
+    );
+    if (!response.ok) {
+      return getErrorResult(
+        toApiError(
+          response.status,
+          `Request failed with status ${response.status}.`
+        )
+      );
+    }
+    const value = response.json !== void 0 ? await response.json() : JSON.parse(await response.text());
+    return {
+      ok: true,
+      value
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : "Request execution failed.";
+    return getErrorResult({
+      category: "unreachable",
+      reason
+    });
+  }
+};
+var requestNoContent = async (configuration, dependencies, route, requestOptions) => {
+  const fetchDependency = getFetchDependency(dependencies);
+  const connectivityResult = await validateLighthouseConnectivity(
+    configuration.connection,
+    {
+      fetch: fetchDependency
+    },
+    getRequestInit(configuration.auth, {
+      method: "GET"
+    })
+  );
+  if (connectivityResult.category !== "success") {
+    return getErrorResult(getErrorFromConnectivityResult(connectivityResult));
+  }
+  try {
+    const response = await fetchDependency(
+      `${connectivityResult.endpoint.apiBaseUrl}${route}`,
+      getRequestInit(configuration.auth, requestOptions)
+    );
+    if (!response.ok) {
+      return getErrorResult(
+        toApiError(
+          response.status,
+          `Request failed with status ${response.status}.`
+        )
+      );
+    }
+    return {
+      ok: true,
+      value: void 0
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : "Request execution failed.";
+    return getErrorResult({
+      category: "unreachable",
+      reason
+    });
+  }
+};
+var createLighthouseClient = (configuration, dependencies = {}) => ({
+  checkConnectivity: async () => {
+    const fetchDependency = getFetchDependency(dependencies);
+    return validateLighthouseConnectivity(
+      configuration.connection,
+      {
+        fetch: fetchDependency
+      },
+      getRequestInit(configuration.auth)
+    );
+  },
+  getVersion: async () => requestText(configuration, dependencies, "/v1/version"),
+  listWorkTrackingConnections: async () => requestJson(
+    configuration,
+    dependencies,
+    "/v1/worktrackingsystemconnections",
+    {
+      method: "GET"
+    }
+  ),
+  getWorkTrackingConnection: async (connectionId) => requestJson(
+    configuration,
+    dependencies,
+    `/v1/worktrackingsystemconnections/${connectionId}`,
+    {
+      method: "GET"
+    }
+  ),
+  createWorkTrackingConnection: async (payload) => requestJson(
+    configuration,
+    dependencies,
+    "/v1/worktrackingsystemconnections",
+    {
+      method: "POST",
+      body: payload
+    }
+  ),
+  updateWorkTrackingConnection: async (connectionId, payload) => requestJson(
+    configuration,
+    dependencies,
+    `/v1/worktrackingsystemconnections/${connectionId}`,
+    {
+      method: "PUT",
+      body: payload
+    }
+  ),
+  deleteWorkTrackingConnection: async (connectionId) => requestNoContent(
+    configuration,
+    dependencies,
+    `/v1/worktrackingsystemconnections/${connectionId}`,
+    {
+      method: "DELETE"
+    }
+  ),
+  listTeams: async () => requestJson(configuration, dependencies, "/v1/teams", {
+    method: "GET"
+  }),
+  getTeam: async (teamId) => requestJson(configuration, dependencies, `/v1/teams/${teamId}`, {
+    method: "GET"
+  }),
+  createTeam: async (payload) => requestJson(configuration, dependencies, "/v1/teams", {
+    method: "POST",
+    body: payload
+  }),
+  updateTeam: async (teamId, payload) => requestJson(configuration, dependencies, `/v1/teams/${teamId}`, {
+    method: "PUT",
+    body: payload
+  }),
+  deleteTeam: async (teamId) => requestNoContent(configuration, dependencies, `/v1/teams/${teamId}`, {
+    method: "DELETE"
+  }),
+  refreshTeam: async (teamId) => requestNoContent(configuration, dependencies, `/v1/teams/${teamId}`, {
+    method: "POST"
+  }),
+  listPortfolios: async () => requestJson(
+    configuration,
+    dependencies,
+    "/v1/portfolios",
+    {
+      method: "GET"
+    }
+  ),
+  getPortfolio: async (portfolioId) => requestJson(
+    configuration,
+    dependencies,
+    `/v1/portfolios/${portfolioId}`,
+    {
+      method: "GET"
+    }
+  ),
+  createPortfolio: async (payload) => requestJson(configuration, dependencies, "/v1/portfolios", {
+    method: "POST",
+    body: payload
+  }),
+  updatePortfolio: async (portfolioId, payload) => requestJson(
+    configuration,
+    dependencies,
+    `/v1/portfolios/${portfolioId}`,
+    {
+      method: "PUT",
+      body: payload
+    }
+  ),
+  deletePortfolio: async (portfolioId) => requestNoContent(
+    configuration,
+    dependencies,
+    `/v1/portfolios/${portfolioId}`,
+    {
+      method: "DELETE"
+    }
+  ),
+  refreshPortfolio: async (portfolioId) => requestNoContent(
+    configuration,
+    dependencies,
+    `/v1/portfolios/${portfolioId}/refresh`,
+    {
+      method: "POST"
+    }
+  )
+});
+export {
+  createLighthouseAuthContext,
+  createLighthouseClient,
+  getClientPackageContract,
+  parseStandaloneDiscoveryContract,
+  validateLighthouseConnectivity
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@letpeoplework/lighthouse-client",
+  "version": "0.1.0",
+  "description": "Shared Lighthouse API client contracts",
+  "repository": "https://github.com/LetPeopleWork/lighthouse-clients",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "clean": "rimraf dist"
+  }
+}