@stackoverflow/backstage-stack-overflow-teams-collator 1.4.0

package/README.md

@@ -0,0 +1,77 @@
+
+# Stack Overflow for Teams Search Backend Module
+
+This module for the search plugin is an enhanced version of the original [Stack Overflow collator](https://github.com/backstage/backstage/tree/master/plugins/search-backend-module-stack-overflow-collator). It provides additional information while coded to work specifically with Stack Overflow for Teams API Version 3.
+
+## Getting started
+
+Before we begin, make sure:
+
+- You have created your own standalone Backstage app using @backstage/create-app and not using a fork of the backstage repository. If you haven't setup Backstage already, start [here](https://backstage.io/docs/getting-started/).
+
+To use any of the functionality this plugin provides, you need to start by configuring your App with the following config:
+
+```yaml
+stackoverflow:
+  baseUrl: https://api.stackoverflowteams.com # alternative: your Stack Overflow Enterprise site
+  teamName: $STACK_OVERFLOW_TEAM_NAME # optional if you are on Enterprise
+  apiAccessToken: $STACK_OVERFLOW_API_ACCESS_TOKEN
+```
+
+### Stack Overflow for Teams
+
+If you have a private Stack Overflow instance and/or a private Stack Overflow Team you will need to supply a Personal Access Token. You can read more about how to set this up by going to [Stack Overflow's Help Page](https://stackoverflowteams.help/en/articles/7913768-stack-overflow-for-teams-api-v3).
+
+## Areas of Responsibility
+
+This stack overflow backend plugin is primarily responsible for the following:
+
+- Provides a `StackOverflowQuestionsCollatorFactory`, which can be used in the search backend to index stack overflow questions to your Backstage Search.
+
+### Index Stack Overflow Questions to search
+
+Before you are able to start index stack overflow questions to search, you need to go through the [search getting started guide](https://backstage.io/docs/features/search/getting-started).
+
+When you have your `packages/backend/src/plugins/search.ts` file ready to make modifications, add the following code snippet to add the `StackOverflowQuestionsCollatorFactory`. Note that you can optionally modify the `requestParams`, otherwise it will defaults to `{ order: 'desc', sort: 'activity' }`.
+
+```ts
+indexBuilder.addCollator({
+  schedule,
+  factory: StackOverflowQuestionsCollatorFactory.fromConfig(env.config, {
+    logger: env.logger,
+    requestParams: {
+      tagged: ['backstage'],
+      pagesize: 100,
+    },
+  }),
+});
+```
+
+## New Backend System
+
+This package exports a module that extends the search backend to also indexing the questions exposed by the [`Stack Overflow for Teams API version 3`](https://stackoverflowteams.help/en/articles/7913768-stack-overflow-for-teams-api-v3).
+
+### Installation
+
+Add the module package as a dependency:
+
+```bash
+# From your Backstage root directory
+yarn --cwd packages/backend add backstage-stack-overflow-teams-collator
+```
+
+Add the collator to your backend instance, along with the search plugin itself:
+
+```tsx
+// packages/backend/src/index.ts
+import { createBackend } from '@backstage/backend-defaults';
+
+const backend = createBackend();
+backend.add(import('@backstage/plugin-search-backend'));
+backend.add(
+  import('backstage-stack-overflow-teams-collator'),
+);
+backend.start();
+```
+
+You may also want to add configuration parameters to your app-config, for example for controlling the scheduled indexing interval. These parameters should be placed under the `stackoverflow` key. See [the config definition file](https://github.com/estoesmoises/backstage-stackoverflow/blob/main/plugins/search-backend-module-stack-overflow-teams-collator/config.d.ts) for more details.

package/config.d.ts

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * 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.
+ */
+
+export interface Config {
+    /**
+     * Configuration options for the stack overflow plugin
+     */
+    stackoverflow?: {
+      /**
+       * The base url of the Stack Overflow API used for the plugin, if no BaseUrl is provided it will default to https://api.stackoverflowteams.com
+       */
+      baseUrl?: string;
+  
+      /**
+       * The API Access Token to authenticate to Stack Overflow API Version 3
+       * @visibility secret
+       */
+      apiAccessToken: string;
+  
+      /**
+       * The name of the team for a Stack Overflow for Teams account. When teamName is provided baseUrl will always be https://api.stackoverflowteams.com
+       */
+      teamName?: string;
+  
+      /**
+       * Type representing the request parameters.
+       */
+      requestParams?: {
+        [key: string]: string | string[] | number;
+      };
+      /**
+       * Type representing the schedule options.
+       */
+      schedule?: {
+        frequency?: TimeUnit;
+        timeout?: TimeUnit;
+        initialDelay?: TimeUnit;
+      };
+
+      
+    };
+  }
+
+type TimeUnit = { minutes?: number; hours?: number; seconds?: number }

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@stackoverflow/backstage-stack-overflow-teams-collator",
+  "version": "1.4.0",
+  "description": "A module for the search backend that exports stack overflow for teams modules",
+  "backstage": {
+    "role": "backend-plugin-module",
+    "pluginId": "search",
+    "pluginPackage": "@backstage/plugin-search-backend"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/StackExchange/backstage-stackoverflow"
+  },
+  "bugs": {
+    "url": "https://github.com/StackExchange/backstage-stackoverflow/issues"
+  },
+  "license": "Apache-2.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "dist",
+    "config.d.ts"
+  ],
+  "scripts": {
+    "build": "backstage-cli package build",
+    "clean": "backstage-cli package clean",
+    "lint": "backstage-cli package lint",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "start": "backstage-cli package start",
+    "test": "backstage-cli package test"
+  },
+  "dependencies": {
+    "@backstage/backend-plugin-api": "latest",
+    "@backstage/config": "latest",
+    "@backstage/plugin-search-backend-node": "latest",
+    "@backstage/plugin-search-common": "latest",
+    "qs": "^6.9.4"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "latest",
+    "@backstage/cli": "latest",
+    "msw": "^1.2.1",
+    "typescript": "^5.8.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * 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.
+ */
+
+/**
+ * @packageDocumentation
+ * A module for the search backend that exports Stack Overflow modules.
+ */
+
+export * from './collators';
+export { searchStackOverflowCollatorModule as default } from './module';