Merge pull request #166 from gjsjohnmurray/package-types

Create @intersystems-community/intersystems-servermanager NPM package

Author: gjsjohnmurray

README.md

@@ -220,25 +220,32 @@ Embedded entries (built-in default ones) are demoted to the end of the list, or
 
 ## Information for VS Code Extension Developers - How To Leverage Server Manager
 
-An extension XYZ needing to connect to InterSystems servers can define Server Manager as a dependency in its `package.json` like this:
+The NPM package [`@intersystems-community/intersystems-servermanager`](https://www.npmjs.com/package/@intersystems-community/intersystems-servermanager) defines the types used by the API which this extension exports. It also declares some constants.
+
+An extension XYZ needing to connect to InterSystems servers should include `"@intersystems-community/intersystems-servermanager": "latest"` in the `"devDependencies"` object in its `package.json`.
+
+It might also define Server Manager as a dependency in its `package.json` like this:
 
 ```json
   "extensionDependencies": [
     "intersystems-community.servermanager"
   ],
 ```
 
-Alternatively the `activate` method of XYZ can detect whether the extension is already available, then offer to install it if necessary:
+Alternatively the `activate` method of XYZ can detect whether the extension is already available, then offer to install it if not:
 
 ```ts
-  const extId = 'intersystems-community.servermanager';
-  let extension = vscode.extensions.getExtension(extId);
+  import * as serverManager from '@intersystems-community/intersystems-servermanager';
+```
+...
+```ts
+  let extension = vscode.extensions.getExtension(serverManager.EXTENSION_ID);
   if (!extension) {
 	// Optionally ask user for permission
 	// ...
 
-	await vscode.commands.executeCommand('workbench.extensions.installExtension', extId);
-	extension = vscode.extensions.getExtension(extId);
+	await vscode.commands.executeCommand('workbench.extensions.installExtension', serverManager.EXTENSION_ID);
+	extension = vscode.extensions.getExtension(serverManager.EXTENSION_ID);
   }
   if (!extension.isActive) {
     await extension.activate();
@@ -250,7 +257,7 @@ XYZ can then use the extension's API to obtain the properties of a named server
 ```ts
   const serverManagerApi = extension.exports;
   if (serverManagerApi && serverManagerApi.getServerSpec) { // defensive coding
-	const serverSpec = await serverManagerApi.getServerSpec(serverName);
+	const serverSpec: serverManager.IServerSpec | undefined = await serverManagerApi.getServerSpec(serverName);
   }
 ```
 
@@ -259,12 +266,11 @@ The `username` and `password` properties will only be present if defined in the
 To obtain the password with which to connect, use code like this which will also prompt for a username if absent:
 
 ```ts
-  const AUTHENTICATION_PROVIDER = 'intersystems-server-credentials';
   if (typeof serverSpec.password === 'undefined') {
     const scopes = [serverSpec.name, serverSpec.username || ''];
-    let session = await vscode.authentication.getSession(AUTHENTICATION_PROVIDER, scopes, { silent: true });
+    let session = await vscode.authentication.getSession(serverManager.AUTHENTICATION_PROVIDER, scopes, { silent: true });
     if (!session) {
-      session = await vscode.authentication.getSession(AUTHENTICATION_PROVIDER, scopes, { createIfNone: true });
+      session = await vscode.authentication.getSession(serverManager.AUTHENTICATION_PROVIDER, scopes, { createIfNone: true });
     }
     if (session) {
       serverSpec.username = session.scopes[1];
@@ -276,13 +282,13 @@ To obtain the password with which to connect, use code like this which will also
 To offer the user a quickpick of servers:
 
 ```ts
-  const serverName = await serverManagerApi.pickServer();
+  const serverName: string = await serverManagerApi.pickServer();
 ```
 
 To obtain an array of server names:
 
 ```ts
-  const allServerNames = await serverManagerApi.getServerNames();
+  const allServerNames: serverManager.IServerName[] = await serverManagerApi.getServerNames();
 ```
 For up-to-date details of the API, including result types and available parameters, review the source code of the extension's `activate` method [here](https://github.com/intersystems-community/intersystems-servermanager/blob/master/src/extension.ts).
 

package-lock.json

@@ -50,6 +50,7 @@
     "tough-cookie": "^4.0.0"
   },
   "devDependencies": {
+    "@intersystems-community/intersystems-servermanager": "latest",
     "@types/vscode": "^1.63.0",
     "@types/glob": "^7.1.1",
     "@types/keytar": "^4.4.2",

package.json

@@ -1,5 +1,5 @@
 import * as vscode from "vscode";
-import { IJSONServerSpec } from "../extension";
+import { IJSONServerSpec } from "@intersystems-community/intersystems-servermanager";
 import { getServerNames } from "./getServerNames";
 
 export async function addServer(

src/api/addServer.ts

@@ -1,6 +1,7 @@
 import * as vscode from "vscode";
 import { Uri } from "vscode";
-import { extensionId, IServerSpec } from "../extension";
+import { IServerSpec } from "@intersystems-community/intersystems-servermanager";
+import { extensionId } from "../extension";
 import { makeRESTRequest } from "../makeRESTRequest";
 
 export enum BrowserTarget {

src/api/getPortalUriWithToken.ts

@@ -1,5 +1,5 @@
 import * as vscode from "vscode";
-import { IServerName } from "../extension";
+import { IServerName } from "@intersystems-community/intersystems-servermanager";
 import { serverDetail } from "./getServerSummary";
 
 export function getServerNames(scope?: vscode.ConfigurationScope, sorted?: boolean): IServerName[] {

src/api/getServerNames.ts

@@ -1,7 +1,7 @@
 import * as vscode from "vscode";
 import { AUTHENTICATION_PROVIDER } from "../authenticationProvider";
 import { filePassword } from "../commands/managePasswords";
-import { IServerSpec } from "../extension";
+import { IServerSpec } from "@intersystems-community/intersystems-servermanager";
 import { Keychain } from "../keychain";
 
 interface ICredentialSet {

src/api/getServerSpec.ts

@@ -1,5 +1,5 @@
 import * as vscode from "vscode";
-import { IServerName, IServerSpec } from "../extension";
+import { IServerName, IServerSpec } from "@intersystems-community/intersystems-servermanager";
 
 export function getServerSummary(name: string, scope?: vscode.ConfigurationScope): IServerName | undefined {
 	const server: IServerSpec | undefined = vscode.workspace.getConfiguration("intersystems.servers", scope).get(name);

src/api/getServerSummary.ts

@@ -1,6 +1,7 @@
 "use strict";
 
 import * as vscode from "vscode";
+import { IServerName, IServerSpec } from "@intersystems-community/intersystems-servermanager";
 import { addServer } from "./api/addServer";
 import { BrowserTarget, getPortalUriWithToken } from "./api/getPortalUriWithToken";
 import { getServerNames } from "./api/getServerNames";
@@ -16,34 +17,6 @@ import { NamespaceTreeItem, ProjectTreeItem, ServerManagerView, ServerTreeItem,
 export const extensionId = "intersystems-community.servermanager";
 export let globalState: vscode.Memento;
 
-export interface IServerName {
-	name: string;
-	description: string;
-	detail: string;
-}
-
-export interface IWebServerSpec {
-	scheme?: string;
-	host: string;
-	port: number;
-	pathPrefix?: string;
-}
-
-export interface IServerSpec {
-	name: string;
-	webServer: IWebServerSpec;
-	username?: string;
-	password?: string;
-	description?: string;
-}
-
-export interface IJSONServerSpec {
-	webServer: IWebServerSpec;
-	username?: string;
-	password?: string;
-	description?: string;
-}
-
 export function activate(context: vscode.ExtensionContext) {
 
 	const _onDidChangePassword = new vscode.EventEmitter<string>();

src/extension.ts

@@ -7,7 +7,7 @@ import * as https from "https";
 import tough = require("tough-cookie");
 import * as vscode from "vscode";
 import { AUTHENTICATION_PROVIDER } from "./authenticationProvider";
-import { IServerSpec } from "./extension";
+import { IServerSpec } from "@intersystems-community/intersystems-servermanager";
 import { getServerSpec } from "./api/getServerSpec";
 
 axiosCookieJarSupport(axios);