@swirl-search/backstage-plugin-search-backend-module-swirl 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2026 SWIRL AI Connect
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,160 @@
+# search-backend-module-swirl
+
+A Backstage search backend module that puts [SWIRL](https://github.com/swirlai/swirl-search) behind the search plugin.
+
+## What it does
+
+The module registers two things with the search backend:
+
+1. **A search engine.** Every document Backstage collates (catalog entities, TechDocs pages, anything else with a collator) is written to a SWIRL index instead of Lunr, Postgres or Elasticsearch, and every query is answered by SWIRL. Backstage keeps its own result rendering and its own permission filtering; only storage and relevance move.
+2. **A `swirl-federated` document type.** SWIRL can fan a query out to systems that are not in Backstage at all - GitHub, Confluence, an internal wiki, a ticket tracker. Those results come back in the same response, under the `swirl-federated` type, and land in the normal search page next to catalog results. The type is declared by a collator that yields zero documents; nothing federated is ever indexed by Backstage.
+
+Identity travels with the query. The search router mints a plugin token for each request whose `obo` claim carries the calling user, and the module forwards that token to SWIRL unchanged, so SWIRL applies the same user's access to the sources it federates to.
+
+## Install
+
+```sh
+# from your Backstage root
+yarn --cwd packages/backend add @swirl-search/backstage-plugin-search-backend-module-swirl
+```
+
+Add it to the backend, after the search plugin:
+
+```ts
+// packages/backend/src/index.ts
+backend.add(import('@backstage/plugin-search-backend'));
+backend.add(
+  import('@swirl-search/backstage-plugin-search-backend-module-swirl'),
+);
+```
+
+If your backend loads search modules conditionally, guard on the config key so the app still boots without SWIRL:
+
+```ts
+if (config.has('search.swirl')) {
+  yield import('@swirl-search/backstage-plugin-search-backend-module-swirl');
+}
+```
+
+The module also skips registration on its own, with a logged warning, when `search.swirl` is absent. Your existing engine stays in place.
+
+## Configuration
+
+```yaml
+search:
+  swirl:
+    # The only required key.
+    baseUrl: http://swirl:8000
+
+    # Backstage plugin id whose JWKS SWIRL trusts. Default "search".
+    audience: search
+
+    # Documents per ingest request. Default 500.
+    indexerBatchSize: 500
+
+    # Query timeout in ms. Default 8000.
+    queryTimeoutMs: 8000
+
+    federated:
+      # Register the swirl-federated document type. Default true.
+      enabled: true
+      # SWIRL provider tags to fan out to. Default ["backstage"].
+      providerTags: [backstage]
+      # Per-query federation timeout in ms, passed to SWIRL. Default 5000.
+      timeoutMs: 5000
+
+    # Relevance tuning, mirrored to SWIRL on startup.
+    tuning:
+      fieldBoosts:
+        titleExact: 3
+        titleNgram: 2
+        text: 1
+      ngram:
+        min: 4
+        max: 5
+      stemmer: en
+      stopwords: []
+      fuzzy:
+        enabled: true
+        distance: 1
+      bm25:
+        k1: 1.2
+        b: 0.75
+
+    highlight:
+      # Default true.
+      enabled: true
+      # Longest snippet returned per field, counted in visible characters
+      # rather than markup. Default 200.
+      maxChars: 200
+      # The marker pair SWIRL wraps hits in, from its
+      # SWIRL_HIGHLIGHT_START_CHAR and SWIRL_HIGHLIGHT_END_CHAR settings.
+      # Override both together if your SWIRL differs from the defaults.
+      startMarker: <em>
+      endMarker: </em>
+```
+
+The whole block is `@visibility backend`; none of it reaches the browser.
+
+## How it talks to SWIRL
+
+### Indexing
+
+One generation per collator run, per document type:
+
+| Call                                       | When                                                                                          |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `POST /swirl/index/<type>/begin/`          | the indexer opens                                                                             |
+| `POST /swirl/index/<type>/<gen>/docs/`     | once per batch, retried three times with backoff on 5xx and transport errors                  |
+| `POST /swirl/index/<type>/<gen>/finalize/` | at the end of a run that produced at least one document; swaps the live generation atomically |
+| `POST /swirl/index/<type>/<gen>/abort/`    | a run that produced zero documents, or one that failed anywhere in the pipeline               |
+
+The zero-document abort is the guard every Backstage engine needs: a collator that comes back empty must not wipe the index that is currently being served. Because a failed run aborts its own generation rather than half-writing the live one, a crashed collator leaves search working on the last good index.
+
+### Querying
+
+Page 0 federates:
+
+```
+GET /swirl/search/?qs=<term>&providers=<tags>&backstage_types=<types>&backstage_filters=<json>&rag=false
+```
+
+Page N is a database read in SWIRL, not a second federation, which keeps the paging loop in Backstage's `AuthorizedSearchEngine` cheap:
+
+```
+GET /swirl/results/?search_id=<id>&page=<n>
+```
+
+Both carry `Authorization: Bearer <plugin token>`. The page cursor Backstage passes around is base64 JSON, `{ "s": <swirl search id>, "p": <page> }`.
+
+The federated lane joins a query when the caller asked for no types at all, or named `swirl-federated`. Under `permission.enabled` the router always passes the full list of registered types, which is exactly why the type has to be registered.
+
+### Startup
+
+On startup the module posts the `tuning` block to `POST /swirl/index/config/`, so relevance is configured in app-config and mirrored into SWIRL rather than maintained twice. A SWIRL that is down, or one that does not know the endpoint, is logged and stepped over; it never stops the backend from booting.
+
+### Errors
+
+When SWIRL reports that a requested type has no live index, the engine throws an error named `MissingIndexError` rather than returning an empty page, so the cause is visible instead of looking like a query that simply matched nothing. SWIRL reports this either as a `404` whose body is `{"error": "missing_index", "types": [...]}`, or as a structured `{"type": "__MISSING_INDEX__", "types": [...]}` entry in the response `messages` array.
+
+## Highlighting
+
+SWIRL marks hits in `title_hit_highlights` and `body_hit_highlights` with `<em>` and `</em>`, from its `SWIRL_HIGHLIGHT_START_CHAR` and `SWIRL_HIGHLIGHT_END_CHAR` settings. The engine rewrites those markers to a random per-instance tag pair before handing results to Backstage, the same way the Postgres engine does, so a document body containing a literal `<em>` cannot forge a highlight. A SWIRL configured with a different pair is handled by `highlight.startMarker` and `highlight.endMarker`.
+
+`maxChars` budgets visible characters, not markup, and a snippet cut short inside a hit still closes it, so the engine never hands Backstage an unbalanced tag.
+
+## Scores
+
+SWIRL's `MappingResultProcessor` sweeps top level keys it does not recognise into `payload`, so the provider score arrives as `payload.searchprovider_score` rather than beside `swirl_score`. The engine reads it from there and falls back to `swirl_score`.
+
+Ranks stay sequential in the order SWIRL returned, because the relevancy mixer has already ordered results across providers; the engine does not re-sort by score. The score is attached to `swirl-federated` documents as `score`, where it is the only ranking signal a renderer has. Indexed documents are handed back exactly as Backstage collated them.
+
+## Development
+
+```sh
+yarn test
+yarn lint
+yarn tsc
+```
+
+`e2e/stub-swirl/` in the repository root serves the six endpoints this module calls, backed by an in-memory index, for manual checks without a SWIRL container.

package/config.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "search": {
+      "type": "object",
+      "properties": {
+        "swirl": {
+          "type": "object",
+          "properties": {
+            "baseUrl": {
+              "type": "string",
+              "description": "Base URL of the SWIRL for Backstage service, e.g. http://swirl:8000"
+            },
+            "audience": {
+              "type": "string",
+              "description": "Backstage plugin id whose JWKS SWIRL trusts. Default \"search\"."
+            },
+            "indexerBatchSize": {
+              "type": "number",
+              "description": "Batch size for indexing. Default 500."
+            },
+            "queryTimeoutMs": {
+              "type": "number",
+              "description": "Request timeout in ms for query calls. Default 8000."
+            },
+            "federated": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Register the swirl-federated document type. Default true."
+                },
+                "providerTags": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "SWIRL provider tags to fan out to. Default [\"backstage\"]."
+                },
+                "timeoutMs": {
+                  "type": "number",
+                  "description": "Per-query federation timeout in ms passed to SWIRL. Default 5000."
+                }
+              },
+              "description": "Federated lane"
+            },
+            "tuning": {
+              "type": "object",
+              "properties": {
+                "fieldBoosts": {
+                  "type": "object",
+                  "properties": {
+                    "titleExact": {
+                      "type": "number"
+                    },
+                    "titleNgram": {
+                      "type": "number"
+                    },
+                    "text": {
+                      "type": "number"
+                    }
+                  }
+                },
+                "ngram": {
+                  "type": "object",
+                  "properties": {
+                    "min": {
+                      "type": "number"
+                    },
+                    "max": {
+                      "type": "number"
+                    }
+                  }
+                },
+                "stemmer": {
+                  "type": "string"
+                },
+                "stopwords": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "fuzzy": {
+                  "type": "object",
+                  "properties": {
+                    "enabled": {
+                      "type": "boolean"
+                    },
+                    "distance": {
+                      "type": "number"
+                    }
+                  }
+                },
+                "bm25": {
+                  "type": "object",
+                  "properties": {
+                    "k1": {
+                      "type": "number"
+                    },
+                    "b": {
+                      "type": "number"
+                    }
+                  }
+                }
+              },
+              "description": "Relevance tuning, mirrored to SWIRL on startup"
+            },
+            "highlight": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "maxChars": {
+                  "type": "number"
+                },
+                "startMarker": {
+                  "type": "string",
+                  "description": "The marker pair SWIRL wraps hits in, from its SWIRL_HIGHLIGHT_START_CHAR and SWIRL_HIGHLIGHT_END_CHAR settings. Defaults \"<em>\" and \"</em>\". Override both together if your SWIRL is configured with a different pair."
+                },
+                "endMarker": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "required": [
+            "baseUrl"
+          ],
+          "description": "Configuration for the SWIRL search engine.",
+          "visibility": "backend"
+        }
+      }
+    }
+  }
+}

package/dist/alpha.cjs.js

@@ -0,0 +1,10 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var module$1 = require('./module.cjs.js');
+
+const _feature = module$1.searchModuleSwirlEngine;
+
+exports.default = _feature;
+//# sourceMappingURL=alpha.cjs.js.map

package/dist/alpha.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alpha.cjs.js","sources":["../src/alpha.ts"],"sourcesContent":["/*\n * Copyright 2026 SWIRL AI Connect\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { searchModuleSwirlEngine as feature } from './module';\n\n/** @alpha */\nconst _feature = feature;\nexport default _feature;\n"],"names":["feature"],"mappings":";;;;;;AAmBA,MAAM,QAAA,GAAWA;;"}

package/dist/alpha.d.ts

@@ -0,0 +1,6 @@
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+
+/** @alpha */
+declare const _feature: _backstage_backend_plugin_api.BackendFeature;
+
+export { _feature as default };

package/dist/collators/SwirlFederatedCollatorFactory.cjs.js

@@ -0,0 +1,26 @@
+'use strict';
+
+var node_stream = require('node:stream');
+var types = require('../engines/types.cjs.js');
+
+class SwirlFederatedCollatorFactory {
+  type = types.SWIRL_FEDERATED_TYPE;
+  logger;
+  constructor(options) {
+    this.logger = options.logger;
+  }
+  static fromConfig(_config, options) {
+    return new SwirlFederatedCollatorFactory(options);
+  }
+  async getCollator() {
+    return node_stream.Readable.from(this.execute());
+  }
+  async *execute() {
+    this.logger.debug(
+      `The ${types.SWIRL_FEDERATED_TYPE} type is served at query time by SWIRL; nothing to index`
+    );
+  }
+}
+
+exports.SwirlFederatedCollatorFactory = SwirlFederatedCollatorFactory;
+//# sourceMappingURL=SwirlFederatedCollatorFactory.cjs.js.map

package/dist/collators/SwirlFederatedCollatorFactory.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwirlFederatedCollatorFactory.cjs.js","sources":["../../src/collators/SwirlFederatedCollatorFactory.ts"],"sourcesContent":["/*\n * Copyright 2026 SWIRL AI Connect\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Readable } from 'node:stream';\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { Config } from '@backstage/config';\nimport {\n  DocumentCollatorFactory,\n  IndexableDocument,\n} from '@backstage/plugin-search-common';\nimport { SWIRL_FEDERATED_TYPE } from '../engines/types';\n\n/**\n * Options for {@link SwirlFederatedCollatorFactory}.\n *\n * @public\n */\nexport type SwirlFederatedCollatorFactoryOptions = {\n  logger: LoggerService;\n};\n\n/**\n * A collator that yields no documents.\n *\n * Federated results are produced by SWIRL at query time and are never indexed\n * by Backstage, but they still need a registered document type: the type is\n * what makes them appear in `getDocumentTypes()`, survive\n * `AuthorizedSearchEngine` when permissions are on, and show up as a filter in\n * the search UI. Registering an empty collator is the cheapest way to declare\n * the type.\n *\n * @public\n */\nexport class SwirlFederatedCollatorFactory implements DocumentCollatorFactory {\n  readonly type = SWIRL_FEDERATED_TYPE;\n\n  private readonly logger: LoggerService;\n\n  private constructor(options: SwirlFederatedCollatorFactoryOptions) {\n    this.logger = options.logger;\n  }\n\n  static fromConfig(\n    _config: Config,\n    options: SwirlFederatedCollatorFactoryOptions,\n  ): SwirlFederatedCollatorFactory {\n    return new SwirlFederatedCollatorFactory(options);\n  }\n\n  async getCollator(): Promise<Readable> {\n    return Readable.from(this.execute());\n  }\n\n  private async *execute(): AsyncGenerator<IndexableDocument> {\n    this.logger.debug(\n      `The ${SWIRL_FEDERATED_TYPE} type is served at query time by SWIRL; nothing to index`,\n    );\n  }\n}\n"],"names":["SWIRL_FEDERATED_TYPE","Readable"],"mappings":";;;;;AA8CO,MAAM,6BAAA,CAAiE;AAAA,EACnE,IAAA,GAAOA,0BAAA;AAAA,EAEC,MAAA;AAAA,EAET,YAAY,OAAA,EAA+C;AACjE,IAAA,IAAA,CAAK,SAAS,OAAA,CAAQ,MAAA;AAAA,EACxB;AAAA,EAEA,OAAO,UAAA,CACL,OAAA,EACA,OAAA,EAC+B;AAC/B,IAAA,OAAO,IAAI,8BAA8B,OAAO,CAAA;AAAA,EAClD;AAAA,EAEA,MAAM,WAAA,GAAiC;AACrC,IAAA,OAAOC,oBAAA,CAAS,IAAA,CAAK,IAAA,CAAK,OAAA,EAAS,CAAA;AAAA,EACrC;AAAA,EAEA,OAAe,OAAA,GAA6C;AAC1D,IAAA,IAAA,CAAK,MAAA,CAAO,KAAA;AAAA,MACV,OAAOD,0BAAoB,CAAA,wDAAA;AAAA,KAC7B;AAAA,EACF;AACF;;"}

package/dist/engines/SwirlClient.cjs.js

@@ -0,0 +1,69 @@
+'use strict';
+
+class SwirlClient {
+  baseUrl;
+  auth;
+  audience;
+  timeoutMs;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.auth = options.auth;
+    this.audience = options.audience;
+    this.timeoutMs = options.timeoutMs;
+    this.fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));
+  }
+  /**
+   * Mints a plugin token for SWIRL. Used by the indexer, by the startup
+   * tuning call, and by queries that arrive without a router supplied token.
+   */
+  async mintToken(credentials) {
+    const onBehalfOf = credentials ?? await this.auth.getOwnServiceCredentials();
+    const { token } = await this.auth.getPluginRequestToken({
+      onBehalfOf,
+      targetPluginId: this.audience
+    });
+    return token;
+  }
+  /**
+   * Builds an absolute URL against the configured base URL. Undefined and
+   * null query values are dropped.
+   */
+  url(path, query) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value === void 0 || value === null || value === "") {
+        continue;
+      }
+      url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+  async request(options) {
+    const response = await this.fetchImpl(options.url, {
+      method: options.method,
+      headers: {
+        Authorization: `Bearer ${options.token}`,
+        Accept: "application/json",
+        ...options.body === void 0 ? {} : { "Content-Type": "application/json" }
+      },
+      body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+      signal: AbortSignal.timeout(options.timeoutMs ?? this.timeoutMs)
+    });
+    let body;
+    if (response.status !== 204) {
+      const text = await response.text();
+      if (text) {
+        try {
+          body = JSON.parse(text);
+        } catch {
+          body = text;
+        }
+      }
+    }
+    return { status: response.status, ok: response.ok, body };
+  }
+}
+
+exports.SwirlClient = SwirlClient;
+//# sourceMappingURL=SwirlClient.cjs.js.map

package/dist/engines/SwirlClient.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwirlClient.cjs.js","sources":["../../src/engines/SwirlClient.ts"],"sourcesContent":["/*\n * Copyright 2026 SWIRL AI Connect\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  AuthService,\n  BackstageCredentials,\n} from '@backstage/backend-plugin-api';\n\n/**\n * Outcome of a single call to SWIRL. Non 2xx responses are returned rather\n * than thrown so that callers can decide what a status means; transport\n * failures still throw.\n *\n * @public\n */\nexport type SwirlRequestResult = {\n  status: number;\n  ok: boolean;\n  body: any;\n};\n\n/**\n * Options for {@link SwirlClient}.\n *\n * @public\n */\nexport type SwirlClientOptions = {\n  baseUrl: string;\n  auth: AuthService;\n  /** Plugin id whose JWKS SWIRL trusts. Tokens are minted for this target. */\n  audience: string;\n  /** Default request timeout in ms. */\n  timeoutMs: number;\n  /** Injectable for tests. Defaults to the global fetch. */\n  fetchImpl?: typeof fetch;\n};\n\n/**\n * Thin HTTP client for the SWIRL for Backstage service. Owns URL building,\n * bearer handling and timeouts; knows nothing about search semantics.\n *\n * @public\n */\nexport class SwirlClient {\n  private readonly baseUrl: string;\n  private readonly auth: AuthService;\n  private readonly audience: string;\n  private readonly timeoutMs: number;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(options: SwirlClientOptions) {\n    this.baseUrl = options.baseUrl.replace(/\\/+$/, '');\n    this.auth = options.auth;\n    this.audience = options.audience;\n    this.timeoutMs = options.timeoutMs;\n    this.fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));\n  }\n\n  /**\n   * Mints a plugin token for SWIRL. Used by the indexer, by the startup\n   * tuning call, and by queries that arrive without a router supplied token.\n   */\n  async mintToken(credentials?: BackstageCredentials): Promise<string> {\n    const onBehalfOf =\n      credentials ?? (await this.auth.getOwnServiceCredentials());\n    const { token } = await this.auth.getPluginRequestToken({\n      onBehalfOf,\n      targetPluginId: this.audience,\n    });\n    return token;\n  }\n\n  /**\n   * Builds an absolute URL against the configured base URL. Undefined and\n   * null query values are dropped.\n   */\n  url(\n    path: string,\n    query?: Record<string, string | number | undefined>,\n  ): string {\n    const url = new URL(`${this.baseUrl}${path}`);\n    for (const [key, value] of Object.entries(query ?? {})) {\n      if (value === undefined || value === null || value === '') {\n        continue;\n      }\n      url.searchParams.set(key, String(value));\n    }\n    return url.toString();\n  }\n\n  async request(options: {\n    url: string;\n    method: 'GET' | 'POST' | 'DELETE';\n    token: string;\n    body?: unknown;\n    timeoutMs?: number;\n  }): Promise<SwirlRequestResult> {\n    const response = await this.fetchImpl(options.url, {\n      method: options.method,\n      headers: {\n        Authorization: `Bearer ${options.token}`,\n        Accept: 'application/json',\n        ...(options.body === undefined\n          ? {}\n          : { 'Content-Type': 'application/json' }),\n      },\n      body:\n        options.body === undefined ? undefined : JSON.stringify(options.body),\n      signal: AbortSignal.timeout(options.timeoutMs ?? this.timeoutMs),\n    });\n\n    let body: any;\n    if (response.status !== 204) {\n      const text = await response.text();\n      if (text) {\n        try {\n          body = JSON.parse(text);\n        } catch {\n          body = text;\n        }\n      }\n    }\n\n    return { status: response.status, ok: response.ok, body };\n  }\n}\n"],"names":[],"mappings":"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"}