@galaxyproject/galaxy-api-client 25.0.0-dev.0

package/README.md

@@ -0,0 +1,194 @@
+# Galaxy API Client
+
+A standalone client library for the Galaxy API, built using the type definitions from the main Galaxy client.
+
+## Installation
+
+```bash
+npm install @galaxyproject/galaxy-api-client
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createGalaxyApi } from "@galaxyproject/galaxy-api-client";
+
+// Create an instance of the Galaxy API client with a specific base URL
+const api = createGalaxyApi("https://usegalaxy.org");
+
+// Alternatively, use the default (current origin)
+// const api = createGalaxyApi();
+
+// Example: Get a list of histories
+const { data, error } = await api.GET("/api/histories");
+
+if (error) {
+    console.error("Error fetching histories:", error);
+} else {
+    console.log("Histories:", data);
+}
+
+// For backward compatibility
+import { GalaxyApi } from "@galaxyproject/galaxy-api-client";
+const legacyApi = GalaxyApi(); // Uses current origin
+```
+
+### Usage with API Keys and Custom Headers
+
+```typescript
+import { createGalaxyApi } from "@galaxyproject/galaxy-api-client";
+
+// Create a client with API key authentication and custom headers
+const api = createGalaxyApi({
+    baseUrl: "https://usegalaxy.org",
+    apiKey: "your-api-key-here",
+    headers: {
+        Accept: "application/json",
+    },
+    fetchOptions: {
+        credentials: "include", // Include cookies for CORS requests
+        cache: "no-cache", // Don't cache responses
+    },
+});
+
+// Now all requests will include the API key header and custom options
+const { data, error } = await api.GET("/api/histories");
+```
+
+## Type Safety
+
+This package provides TypeScript types for Galaxy API endpoints and models:
+
+```typescript
+import { createGalaxyApi, type HistorySummary, type DatasetEntry } from "@galaxyproject/galaxy-api-client";
+
+const api = createGalaxyApi();
+
+// Type-safe API calls
+const { data: histories } = await api.GET("/api/histories");
+// histories is typed as HistorySummary[] | undefined
+
+// You can use the types for your variables
+const myHistory: HistorySummary = {
+    id: "123",
+    name: "My History",
+    // ...other required properties
+};
+```
+
+## Examples
+
+See more in `src/example.ts` that demonstrate how to use the client:
+
+### Basic Example
+
+```typescript
+import { createGalaxyApi } from "@galaxyproject/galaxy-api-client";
+
+// Create a client with a specific Galaxy instance
+const api = createGalaxyApi("https://usegalaxy.org");
+
+// Example: Get a list of tools
+async function getTools() {
+    const { data, error } = await api.GET("/api/tools");
+
+    if (error) {
+        console.error("Error fetching tools:", error);
+        return [];
+    }
+
+    // Log tool count
+    console.log(`Found ${data.length} tools`);
+
+    return data;
+}
+```
+
+## Notes
+
+This package uses a symlink to reference API type definitions from the main Galaxy client while providing a standalone client implementation. This approach was chosen to:
+
+1. Minimize duplication of type definitions
+2. Ensure type definitions stay in sync with the main codebase
+3. Allow the client to work independently of Galaxy's internal utilities
+
+## Development
+
+To work on this package:
+
+1. Make changes to the API type definitions in the main Galaxy client
+2. The type changes will automatically be available in this package via symlinks
+3. Synchronize the version with Galaxy:
+
+    ```bash
+    # Update the version in package.json from Galaxy's version.py
+    npm run sync-version
+    ```
+
+4. Build the library for distribution:
+
+    ```bash
+    # Install dependencies
+    npm install
+
+    # Build the library
+    npm run build
+
+    # Watch mode for development
+    npm run dev
+    ```
+
+### Version Synchronization
+
+This package maintains version parity with Galaxy to indicate API compatibility. The version number in `package.json` is derived from Galaxy's `lib/galaxy/version.py` file but formatted to comply with npm's semver requirements.
+
+**Important:** npm does not allow republishing the same version, even for development versions. When making changes to the client API during development:
+
+1. Manually increment the version before publishing:
+
+    ```bash
+    # Example: Update from 25.0.0-dev.0 to 25.0.0-dev.1
+    npm version prerelease --preid=dev
+    ```
+
+2. Or edit the npm version directly in package.json:
+    ```json
+    {
+        "version": "25.0.0-dev.1"
+    }
+    ```
+
+There's also a script to automate this process of syncing with galaxy version that we may want to use in other contexts, too?:
+
+```bash
+# Using npm script
+npm run sync-version
+```
+
+The script will:
+
+1. Read the version from Galaxy's `version.py` file
+2. Convert it to npm-compatible semver format
+3. Update the version in `package.json` if different
+
+Version synchronization should be performed before each release to ensure the client API version accurately reflects the Galaxy API version it supports.
+
+### Testing
+
+The package includes a few vitest tests as a sanity check, but we could do a lot more here:
+
+```bash
+# Run tests
+npm test
+
+# Run tests with watch mode (during development)
+npm run test:watch
+```
+
+The tests verify:
+
+- Client creation with default and custom base URLs
+- Basic API interaction with proper typing
+- Error handling

package/dist/index.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+var createClient = require('openapi-fetch');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var createClient__default = /*#__PURE__*/_interopDefault(createClient);
+
+// src/client.ts
+
+// src/api-types.ts
+function isHDA(entry) {
+  return entry !== void 0 && "history_content_type" in entry && entry.history_content_type === "dataset";
+}
+function isHDCA(entry) {
+  return entry !== void 0 && "history_content_type" in entry && entry.history_content_type === "dataset_collection";
+}
+function isDCE(item) {
+  return item && "element_type" in item;
+}
+function isCollectionElement(element) {
+  return element.element_type === "dataset_collection";
+}
+function isDatasetElement(element) {
+  return element.element_type === "hda";
+}
+function hasDetails(entry) {
+  return "peek" in entry;
+}
+function isInaccessible(entry) {
+  return "accessible" in entry && !entry.accessible;
+}
+
+// src/client.ts
+function createGalaxyApi(options = {}) {
+  const opts = typeof options === "string" ? { baseUrl: options } : options;
+  const baseUrl = opts.baseUrl || window.location.origin;
+  const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const headers = {
+    ...opts.headers || {}
+  };
+  if (opts.apiKey) {
+    headers["x-api-key"] = opts.apiKey;
+  }
+  return createClient__default.default({
+    baseUrl: normalizedBaseUrl,
+    headers,
+    // Pass any custom fetchOptions directly to createClient
+    ...opts.fetchOptions ? { fetchOptions: opts.fetchOptions } : {}
+  });
+}
+
+// src/utils/error.ts
+function errorMessageAsString(error) {
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (error && typeof error === "object") {
+    if (error.status && error.error) {
+      return `API Error (${error.status}): ${error.error}`;
+    }
+    if (error.message) {
+      return error.message;
+    }
+    try {
+      return JSON.stringify(error);
+    } catch (e) {
+      return String(error);
+    }
+  }
+  return "Unknown error";
+}
+
+// src/index.ts
+var SimpleError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GalaxyApiError";
+  }
+};
+function GalaxyApi() {
+  return createGalaxyApi();
+}
+function formatErrorMessage(error) {
+  return errorMessageAsString(error);
+}
+
+exports.GalaxyApi = GalaxyApi;
+exports.SimpleError = SimpleError;
+exports.createGalaxyApi = createGalaxyApi;
+exports.formatErrorMessage = formatErrorMessage;
+exports.hasDetails = hasDetails;
+exports.isCollectionElement = isCollectionElement;
+exports.isDCE = isDCE;
+exports.isDatasetElement = isDatasetElement;
+exports.isHDA = isHDA;
+exports.isHDCA = isHDCA;
+exports.isInaccessible = isInaccessible;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api-types.ts","../src/client.ts","../src/utils/error.ts","../src/index.ts"],"names":["createClient"],"mappings":";;;;;;;;;;;AA6EO,SAAS,MAAM,KAAiD,EAAA;AACnE,EAAA,OAAO,KAAU,KAAA,MAAA,IAAa,sBAA0B,IAAA,KAAA,IAAS,MAAM,oBAAyB,KAAA,SAAA;AACpG;AAEO,SAAS,OAAO,KAAoE,EAAA;AACvF,EAAA,OACI,KAAU,KAAA,MAAA,IAAa,sBAA0B,IAAA,KAAA,IAAS,MAAM,oBAAyB,KAAA,oBAAA;AAEjG;AAEO,SAAS,MAAM,IAAkC,EAAA;AACpD,EAAA,OAAO,QAAQ,cAAkB,IAAA,IAAA;AACrC;AAEO,SAAS,oBAAoB,OAA+C,EAAA;AAC/E,EAAA,OAAO,QAAQ,YAAiB,KAAA,oBAAA;AACpC;AAEO,SAAS,iBAAiB,OAA4C,EAAA;AACzE,EAAA,OAAO,QAAQ,YAAiB,KAAA,KAAA;AACpC;AAEO,SAAS,WAAW,KAA2C,EAAA;AAClE,EAAA,OAAO,MAAU,IAAA,KAAA;AACrB;AAEO,SAAS,eAAe,KAA+C,EAAA;AAC1E,EAAO,OAAA,YAAA,IAAgB,KAAS,IAAA,CAAC,KAAM,CAAA,UAAA;AAC3C;;;ACvEO,SAAS,eAAA,CAAgB,OAAqC,GAAA,EAAI,EAAA;AAErE,EAAA,MAAM,OAAO,OAAO,OAAA,KAAY,WAAW,EAAE,OAAA,EAAS,SAAY,GAAA,OAAA;AAGlE,EAAA,MAAM,OAAU,GAAA,IAAA,CAAK,OAAW,IAAA,MAAA,CAAO,QAAS,CAAA,MAAA;AAChD,EAAM,MAAA,iBAAA,GAAoB,QAAQ,QAAS,CAAA,GAAG,IAAI,OAAQ,CAAA,KAAA,CAAM,CAAG,EAAA,EAAE,CAAI,GAAA,OAAA;AAGzE,EAAA,MAAM,OAAkC,GAAA;AAAA,IACpC,GAAI,IAAK,CAAA,OAAA,IAAW;AAAC,GACzB;AAGA,EAAA,IAAI,KAAK,MAAQ,EAAA;AACb,IAAQ,OAAA,CAAA,WAAW,IAAI,IAAK,CAAA,MAAA;AAAA;AAIhC,EAAA,OAAOA,6BAA6B,CAAA;AAAA,IAChC,OAAS,EAAA,iBAAA;AAAA,IACT,OAAA;AAAA;AAAA,IAEA,GAAI,KAAK,YAAe,GAAA,EAAE,cAAc,IAAK,CAAA,YAAA,KAAiB;AAAC,GAClE,CAAA;AACL;;;ACpDO,SAAS,qBAAqB,KAAoB,EAAA;AACrD,EAAI,IAAA,OAAO,UAAU,QAAU,EAAA;AAC3B,IAAO,OAAA,KAAA;AAAA;AAGX,EAAA,IAAI,iBAAiB,KAAO,EAAA;AACxB,IAAA,OAAO,KAAM,CAAA,OAAA;AAAA;AAGjB,EAAI,IAAA,KAAA,IAAS,OAAO,KAAA,KAAU,QAAU,EAAA;AAEpC,IAAI,IAAA,KAAA,CAAM,MAAU,IAAA,KAAA,CAAM,KAAO,EAAA;AAC7B,MAAA,OAAO,CAAc,WAAA,EAAA,KAAA,CAAM,MAAM,CAAA,GAAA,EAAM,MAAM,KAAK,CAAA,CAAA;AAAA;AAItD,IAAA,IAAI,MAAM,OAAS,EAAA;AACf,MAAA,OAAO,KAAM,CAAA,OAAA;AAAA;AAIjB,IAAI,IAAA;AACA,MAAO,OAAA,IAAA,CAAK,UAAU,KAAK,CAAA;AAAA,aACtB,CAAG,EAAA;AAER,MAAA,OAAO,OAAO,KAAK,CAAA;AAAA;AACvB;AAGJ,EAAO,OAAA,eAAA;AACX;;;ACzBa,IAAA,WAAA,GAAN,cAA0B,KAAM,CAAA;AAAA,EACnC,YAAY,OAAiB,EAAA;AACzB,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAO,GAAA,gBAAA;AAAA;AAEpB;AAMO,SAAS,SAAY,GAAA;AACxB,EAAA,OAAO,eAAgB,EAAA;AAC3B;AAGO,SAAS,mBAAmB,KAAoB,EAAA;AACnD,EAAA,OAAO,qBAAqB,KAAK,CAAA;AACrC","file":"index.cjs","sourcesContent":["/**\n * This file re-exports the types we want to use from the Galaxy API.\n * It serves as a compatibility layer to avoid importing directly from the\n * symlinked files, which would require all of Galaxy's dependencies.\n */\n\n// Import types from the symlinked files\nimport { type components, type GalaxyApiPaths } from \"./api/schema\";\n\n// We only need the types, not the code that depends on Galaxy's implementation\nexport type { components, GalaxyApiPaths };\n\n// Re-export specific types\nexport type HistorySummary = components[\"schemas\"][\"HistorySummary\"];\nexport type HistoryDetailed = components[\"schemas\"][\"HistoryDetailed\"];\nexport type HDASummary = components[\"schemas\"][\"HDASummary\"];\nexport type HDADetailed = components[\"schemas\"][\"HDADetailed\"];\nexport type DCESummary = components[\"schemas\"][\"DCESummary\"];\nexport type HDCASummary = components[\"schemas\"][\"HDCASummary\"];\nexport type HDCADetailed = components[\"schemas\"][\"HDCADetailed\"];\nexport type DCObject = components[\"schemas\"][\"DCObject\"];\nexport type HDAObject = components[\"schemas\"][\"HDAObject\"];\nexport type HDAInaccessible = components[\"schemas\"][\"HDAInaccessible\"];\nexport type DatasetTextContentDetails = components[\"schemas\"][\"DatasetTextContentDetails\"];\nexport type DatasetStorageDetails = components[\"schemas\"][\"DatasetStorageDetails\"];\nexport type DatasetCollectionAttributes = components[\"schemas\"][\"DatasetCollectionAttributesResult\"];\nexport type ConcreteObjectStoreModel = components[\"schemas\"][\"ConcreteObjectStoreModel\"];\nexport type MessageException = components[\"schemas\"][\"MessageExceptionModel\"];\nexport type DatasetHash = components[\"schemas\"][\"DatasetHash\"];\nexport type DatasetSource = components[\"schemas\"][\"DatasetSource\"];\nexport type DatasetTransform = components[\"schemas\"][\"DatasetSourceTransform\"];\nexport type StoreExportPayload = components[\"schemas\"][\"StoreExportPayload\"];\nexport type ModelStoreFormat = components[\"schemas\"][\"ModelStoreFormat\"];\nexport type ObjectExportTaskResponse = components[\"schemas\"][\"ObjectExportTaskResponse\"];\nexport type ExportObjectRequestMetadata = components[\"schemas\"][\"ExportObjectRequestMetadata\"];\nexport type ExportObjectResultMetadata = components[\"schemas\"][\"ExportObjectResultMetadata\"];\nexport type AsyncTaskResultSummary = components[\"schemas\"][\"AsyncTaskResultSummary\"];\n\n// Define utility types that may be used in the client\nexport type HistorySortByLiteral = \"create_time\" | \"name\" | \"update_time\" | \"username\" | undefined;\n\nexport interface HistoryContentsStats {\n    id: string;\n    update_time: string;\n    size: number;\n    contents_active: components[\"schemas\"][\"HistoryActiveContentCounts\"];\n}\n\nexport interface HistorySummaryExtended extends HistorySummary, HistoryContentsStats {\n    user_id: string | null;\n}\n\nexport interface SelectableObjectStore extends ConcreteObjectStoreModel {\n    object_store_id: string;\n}\n\nexport type DatasetEntry = HDASummary | HDADetailed | HDAInaccessible;\n\nexport interface DCECollection extends DCESummary {\n    element_type: \"dataset_collection\";\n    object: DCObject;\n}\n\nexport interface DCEDataset extends DCESummary {\n    element_type: \"hda\";\n    object: HDAObject;\n}\n\nexport interface SubCollection extends DCObject {\n    name: string;\n    hdca_id: string;\n}\n\nexport type CollectionEntry = HDCASummary | SubCollection;\nexport type HistoryItemSummary = HDASummary | HDCASummary;\n\n// Utility functions\nexport function isHDA(entry?: HistoryItemSummary): entry is HDASummary {\n    return entry !== undefined && \"history_content_type\" in entry && entry.history_content_type === \"dataset\";\n}\n\nexport function isHDCA(entry?: HistoryItemSummary | CollectionEntry): entry is HDCASummary {\n    return (\n        entry !== undefined && \"history_content_type\" in entry && entry.history_content_type === \"dataset_collection\"\n    );\n}\n\nexport function isDCE(item: object): item is DCESummary {\n    return item && \"element_type\" in item;\n}\n\nexport function isCollectionElement(element: DCESummary): element is DCECollection {\n    return element.element_type === \"dataset_collection\";\n}\n\nexport function isDatasetElement(element: DCESummary): element is DCEDataset {\n    return element.element_type === \"hda\";\n}\n\nexport function hasDetails(entry: DatasetEntry): entry is HDADetailed {\n    return \"peek\" in entry;\n}\n\nexport function isInaccessible(entry: DatasetEntry): entry is HDAInaccessible {\n    return \"accessible\" in entry && !entry.accessible;\n}\n","import createClient from \"openapi-fetch\";\nimport { type GalaxyApiPaths } from \"./api-types\";\n\n/**\n * Options for creating a Galaxy API client\n */\nexport interface GalaxyApiOptions {\n    /**\n     * The base URL of the Galaxy server (e.g., \"https://usegalaxy.org\")\n     * @default window.location.origin\n     */\n    baseUrl?: string;\n\n    /**\n     * API key for authentication\n     */\n    apiKey?: string;\n\n    /**\n     * Custom headers to include with each request\n     */\n    headers?: Record<string, string>;\n\n    /**\n     * Custom fetch options that will be passed to all requests\n     */\n    fetchOptions?: RequestInit;\n}\n\n/**\n * Creates a Galaxy API client with the specified options\n * @param options Configuration options for the Galaxy API client\n * @returns The Galaxy API client\n */\nexport function createGalaxyApi(options: GalaxyApiOptions | string = {}) {\n    // Handle the case where baseUrl is passed as a string for backward compatibility\n    const opts = typeof options === \"string\" ? { baseUrl: options } : options;\n\n    // Default to window.location.origin if no baseUrl is provided\n    const baseUrl = opts.baseUrl || window.location.origin;\n    const normalizedBaseUrl = baseUrl.endsWith(\"/\") ? baseUrl.slice(0, -1) : baseUrl;\n\n    // Build headers object\n    const headers: Record<string, string> = {\n        ...(opts.headers || {}),\n    };\n\n    // Add API key header if provided\n    if (opts.apiKey) {\n        headers[\"x-api-key\"] = opts.apiKey;\n    }\n\n    // Create the client with all options\n    return createClient<GalaxyApiPaths>({\n        baseUrl: normalizedBaseUrl,\n        headers,\n        // Pass any custom fetchOptions directly to createClient\n        ...(opts.fetchOptions ? { fetchOptions: opts.fetchOptions } : {}),\n    });\n}\n\nexport type GalaxyApiClient = ReturnType<typeof createGalaxyApi>;\n","/**\n * Simple error handling utilities for Galaxy Client API\n */\n\n/**\n * Convert various error formats to a readable string message\n */\nexport function errorMessageAsString(error: any): string {\n    if (typeof error === \"string\") {\n        return error;\n    }\n\n    if (error instanceof Error) {\n        return error.message;\n    }\n\n    if (error && typeof error === \"object\") {\n        // Handle API response errors\n        if (error.status && error.error) {\n            return `API Error (${error.status}): ${error.error}`;\n        }\n\n        // Handle response objects with error message\n        if (error.message) {\n            return error.message;\n        }\n\n        // Try to stringify the error object\n        try {\n            return JSON.stringify(error);\n        } catch (e) {\n            // Fall back to object inspection\n            return String(error);\n        }\n    }\n\n    return \"Unknown error\";\n}\n","/**\n * Galaxy Client API\n * A client library for the Galaxy API\n */\n\nimport { createGalaxyApi, type GalaxyApiClient } from \"./client\";\nimport { errorMessageAsString } from \"./utils/error\";\n\n// Re-export all the types from our type compatibility layer\nexport * from \"./api-types\";\n\n// SimpleError class for error handling\nexport class SimpleError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = \"GalaxyApiError\";\n    }\n}\n\n// Re-export the client functions\nexport { createGalaxyApi, type GalaxyApiClient };\n\n// For backward compatibility - creates a client with default settings\nexport function GalaxyApi() {\n    return createGalaxyApi();\n}\n\n// Utility function to format error messages\nexport function formatErrorMessage(error: any): string {\n    return errorMessageAsString(error);\n}\n"]}